hakorune/tools/hako_check

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:

• tests/HC017_non_ascii_quotes/ng.hako - Contains intentional smart quotes for detection testing
• tests/HC017_non_ascii_quotes/ok.hako - Clean code without smart quotes (baseline)
• tests/HC017_non_ascii_quotes/expected.json - Empty diagnostics (reflects disabled state)

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.