hakorune/tools/hako_check/README.md

# 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.

Rules
- Core implemented (green): HC011 Dead Methods, HC012 Dead Static Box, HC015 Arity Mismatch, HC016 Unused Alias, HC017 Non‑ASCII Quotes, HC018 Top‑level local, HC021 Analyzer IO Safety, HC022 Stage‑3 Gate, HC031 Brace Heuristics
- 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.
-												Phase 21.4: HC012 Dead Static Box + HC013 Duplicate Method実装完了

## 実装内容

### HC012: Dead Static Box
- 未参照static boxを検出
- IR boxes配列活用、calls情報から参照チェック
- テスト: HC012_dead_static_box/{ok,ng}.hako + expected.json

### HC013: Duplicate Method
- 同名・同arityメソッド重複検出
- Box内でメソッド署名の一意性チェック
- テスト: HC013_duplicate_method/{ok,ng}.hako + expected.json

### 🔥 Critical Bug Fix: parser_core.hako arity計算修正
- **問題**: arityが「カンマの数」を返していた（add(a,b) → 1）
- **修正**: `if any == 1 { arity = arity + 1 }` に変更
- **影響**: 全メソッドのarity計算が正しくなった（HC015等に波及）

### Infrastructure改善
- analysis_consumer.hako: _ensure_array()ヘルパー導入
  - MapBox.get().push()問題の根本解決
  - uses/methods/calls/boxes全てで安全なpush実現
- run_tests.sh: NYASH_JSON_ONLY=1で出力純度確保
- cli.hako: HC012/HC013統合、デバッグ出力追加

## テスト結果
✅ HC011_dead_methods: OK
✅ HC012_dead_static_box: OK
✅ HC013_duplicate_method: OK
✅ HC016_unused_alias: OK
[TEST/SUMMARY] all green

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

Co-Authored-By: Claude <noreply@anthropic.com>

											
										
										
											2025-11-08 02:59:54 +09:00
+								# 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安定化完了: NYASH_DISABLE_PLUGINS=1復元 + plugin無効化根治

## 修正内容
1. **hako_check.sh/run_tests.sh**: NYASH_DISABLE_PLUGINS=1 + NYASH_BOX_FACTORY_POLICY=builtin_first追加
2. **src/box_factory/plugin.rs**: NYASH_DISABLE_PLUGINS=1チェック追加
3. **src/box_factory/mod.rs**: plugin shortcut pathでNYASH_DISABLE_PLUGINS尊重
4. **tools/hako_check/render/graphviz.hako**: smart quotes修正（parse error解消）

## 根本原因
- NYASH_USE_PLUGIN_BUILTINS=1が自動設定され、ArrayBox/MapBoxがplugin経由で生成を試行
- bid/registry.rsで"Plugin loading temporarily disabled"の状態でも試行されエラー
- mod.rs:272のshortcut pathがNYASH_DISABLE_PLUGINSを無視していた

## テスト結果
- 10/11 PASS（HC011,13-18,21-22,31）
- HC012: 既存issue（JSON安定化未完）

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

Co-Authored-By: Claude <noreply@anthropic.com>

											
										
										
											2025-11-08 15:49:25 +09:00
 								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.
 								Rules
 								- Core implemented (green): HC011 Dead Methods, HC012 Dead Static Box, HC015 Arity Mismatch, HC016 Unused Alias, HC017 Non‑ASCII Quotes, HC018 Top‑level local, HC021 Analyzer IO Safety, HC022 Stage‑3 Gate, HC031 Brace Heuristics
 								- 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.