tomoaki/hakorune
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
50ac8af2b8a1523683c237300260d8ddded688b4
hakorune/tools/hako_check/README.md
nyash-codex 50ac8af2b8 Phase 21.4 Complete: FileBox SSOT + Analyzer Stabilization (7 Tasks) 
✅ Task 1: Fallback Guarantee (create_box failure → ring1/core-ro auto fallback)
- Three-tier fallback system: plugin → builtin → core-ro
- Mode control: auto/plugin-only/core-ro
- New: src/box_factory/builtin_impls/file_box.rs
- New: tools/test_filebox_fallback_smoke.sh

✅ Task 2: Provider Registration SSOT (static/dynamic/core-ro unified)
- ProviderFactory trait with priority-based selection
- Global registry PROVIDER_FACTORIES implementation
- Priority: dynamic(100) > builtin(10) > core-ro(0)
- New: src/boxes/file/builtin_factory.rs
- New: tools/smoke_provider_modes.sh

✅ Task 3: FileBox Publication Unification
- Verified: basic/file_box.rs already minimized (11 lines)
- Perfect re-export pattern maintained

✅ Task 4: ENV Unification (FILEBOX_MODE/DISABLE_PLUGINS priority)
- Removed auto-setting of NYASH_USE_PLUGIN_BUILTINS
- Removed auto-setting of NYASH_PLUGIN_OVERRIDE_TYPES
- Added deprecation warnings with migration guide
- ENV hierarchy: DISABLE_PLUGINS > BOX_FACTORY_POLICY > FILEBOX_MODE

✅ Task 5: Error Log Visibility (Analyzer rule execution errors to stderr)
- Added [rule/exec] logging before IR-based rule execution
- Format: [rule/exec] HC012 (dead_static_box) <filepath>
- VM errors now traceable via stderr output

✅ Task 6: Unnecessary Using Removal (14 rules Str alias cleanup)
- Removed unused `using ... as Str` from 14 rule files
- All rules use local _itoa() helper instead
- 14 lines of dead code eliminated

✅ Task 7: HC017 Skip & TODO Documentation (UTF-8 support required)
- Enhanced run_tests.sh with clear skip message
- Added "Known Limitations" section to README.md
- Technical requirements documented (3 implementation options)
- Re-enable timeline: Phase 22 (Unicode Support Phase)

📊 Test Results:
- Analyzer: 10 tests PASS, 1 skipped (HC017)
- FileBox fallback: All 3 modes PASS
- Provider modes: All 4 modes PASS
- Build: Success (0 errors, 0 warnings)

🎯 Key Achievements:
- 28 files modified/created
- Three-Tier Fallback System (stability)
- SSOT Provider Registry (extensibility)
- ENV unification (operational clarity)
- Error visibility (debugging efficiency)
- Code cleanup (maintainability)
- Comprehensive documentation (Phase 22 ready)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-08 17:04:21 +09:00

4.4 KiB
Raw Blame History

Hako Check — Diagnostics Contract (MVP)

This tool lints .hako sources and emits diagnostics.

Diagnostics schema (typed)

  • Map fields:
    • rule: string like "HC011"
    • message: string (human-readable, one line)
    • file: string (path)
    • line: int (1-based)
    • severity: string ("error"|"warning"|"info"), optional (default: warning)
    • quickFix: string, optional

Backwards compatibility

  • Rules may still out.push("[HCxxx] ...") with a single-line string.
  • The CLI accepts both forms. String diagnostics are converted to typed internally.

Suppression policy

  • HC012 (dead static box) takes precedence over HC011 (unreachable method).
  • If a box is reported by HC012, HC011 diagnostics for methods in that box are suppressed at aggregation.

Quiet / JSON output

  • When --format json-lsp is used, output is pure JSON (pretty). Combine with NYASH_JSON_ONLY=1 in the runner to avoid extra lines.
  • Non-JSON formats print human-readable lines per finding.

Planned AST metadata (parser_core.hako)

  • boxes[].span_line: starting line of the static box declaration.
  • methods[].arity: parameter count as an integer.
  • boxes[].is_static: boolean.

Notes

  • Prefer AST intake; text scans are a minimal fallback.
  • For tests, use tools/hako_check/run_tests.sh.

Analyzer policy (plugins)

  • Tests/CI/Analyzer run without plugins by default: NYASH_DISABLE_PLUGINS=1 and NYASH_JSON_ONLY=1.
  • File I/O is avoided by passing source text via --source-file <path> <text>.
  • When plugins are needed (dev/prod), set NYASH_FILEBOX_MODE=auto and provide [libraries] in nyash.toml.

Default test env (recommended)

  • NYASH_DISABLE_PLUGINS=1 – avoid dynamic plugin path and noise
  • NYASH_BOX_FACTORY_POLICY=builtin_first – prefer builtin/ring‑1 for stability
  • NYASH_DISABLE_NY_COMPILER=1 and HAKO_DISABLE_NY_COMPILER=1 – disable inline compiler in tests
  • NYASH_JSON_ONLY=1 – stdout is pure JSON (logs go to stderr)

Known Limitations

HC017: Non-ASCII Quotes Detection (Temporarily Skipped)

Status: ⏸️ Skipped until UTF-8 support is available

Reason: This rule requires UTF-8 byte-level manipulation to detect smart quotes (" " ' ') in source code. Nyash currently lacks:

  • Byte array access for UTF-8 encoded strings
  • UTF-8 sequence detection capabilities (e.g., detecting 0xE2 0x80 0x9C for ")
  • Unicode character property inspection methods

Technical Requirements: One of the following implementations is needed:

  • Implement ByteArrayBox with UTF-8 encoding/decoding methods (to_bytes(), from_bytes())
  • Add built-in Unicode character property methods to StringBox (e.g., is_ascii(), char_code_at())
  • Provide low-level byte access methods like string.get_byte(index) or string.byte_length()

Re-enable Timeline: Planned for Phase 22 (Unicode Support Phase) or when ByteArrayBox lands

Test Files:

Implementation File: rules/rule_non_ascii_quotes.hako - Currently returns 0 (disabled) in _has_fancy_quote()

Current Workaround: The test is automatically skipped in run_tests.sh to prevent CI failures until UTF-8 support is implemented.

Rules

  • Core implemented (green): HC011 Dead Methods, HC012 Dead Static Box, HC015 Arity Mismatch, HC016 Unused Alias, HC018 Top‑level local, HC021 Analyzer IO Safety, HC022 Stage‑3 Gate, HC031 Brace Heuristics
  • Temporarily skipped: HC017 Non‑ASCII Quotes (UTF-8 support required)
  • Pending fixtures update: HC013 Duplicate Method, HC014 Missing Entrypoint

CLI options

  • --rules a,b,c limit execution to selected rules.
  • --skip-rules a,b skip selected.
  • --no-ast (default) avoids AST parser; --force-ast enables AST path (use sparingly while PHI is under polish).

Tips

  • JSON-only output: set NYASH_JSON_ONLY=1 to avoid log noise in stdout; diagnostics go to stdout, logs to stderr.
  • For multiline --source-file payloads, CLI also provides HEX-escaped JSON in NYASH_SCRIPT_ARGS_HEX_JSON for robust transport; the VM prefers HEX→JSON→ARGV.