50ac8af2b8
✅ 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>
88 lines
4.4 KiB
Markdown
88 lines
4.4 KiB
Markdown
# 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`](tests/HC017_non_ascii_quotes/ng.hako) - Contains intentional smart quotes for detection testing
|
||
- [`tests/HC017_non_ascii_quotes/ok.hako`](tests/HC017_non_ascii_quotes/ok.hako) - Clean code without smart quotes (baseline)
|
||
- [`tests/HC017_non_ascii_quotes/expected.json`](tests/HC017_non_ascii_quotes/expected.json) - Empty diagnostics (reflects disabled state)
|
||
|
||
**Implementation File**: [`rules/rule_non_ascii_quotes.hako`](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.
|