tree-sitter-al: Instructions file for Claude Code

CLAUDE.md

GOAL: A parser which parses AL code CORRECT, not just without errors. That is the first and foremost goal.

Guidance for Claude Code when working on this tree-sitter parser for AL (Microsoft Dynamics 365 Business Central). The .claude/rules/*.md files are loaded with this one; they own scanner, keyword, attribute, debugging and test-failure detail and are not repeated here. One home per fact: a rule lives here or in a rules file with its one-line why; its history and measurements live in docs/ or in the comment at the rule in grammar.js / src/scanner.c.

Current numbers (tests, states, parser.c size, success rate) are NOT in this file. They drift every branch. Measure them: ./tools/metrics.sh and ./parse-al-parallel.sh ./BC.History/ .. Three different test counts circulated during 4.0.0 and two were arithmetic from a stale copy.

Git Commit Guidelines

Always include the error count in commit messages so a regression is visible in the log:

Fix XYZ pattern

[BC.History: 7 errors, 99.95% success]

Run the full parse before committing: ./parse-al-parallel.sh ./BC.History/ .

Commit all generated files together: tree-sitter generate writes src/parser.c, src/grammar.json and src/node-types.json, all tracked. Stage them as a set or grammar.json silently drifts.

Subagent briefs link docs/agent-brief-rules.md (blocked commands, process, environment, editing rules).

Quick Reference

# Validation (run before completing any task)
./validate-grammar.sh        # generation, tests, orphan/duplicate detection, field invariants, oracle quick tier, censuses
./validate-grammar.sh --full # plus production AL parsing and the has_error sweep over it

# Zero-behavior-change gate for refactors (byte-identical parse trees). Take a FRESH baseline,
# named for the change: a stale snapshot reports a huge delta that has nothing to do with your edit.
./tools/tree-harness.sh snapshot ./BC.History .snapshots/baseline-<change>  # ~16s
./tools/tree-harness.sh verify   ./BC.History .snapshots/baseline-<change>  # ~11s

# Query-coverage harness: the CST is lossless and values are queryable
python -m tools.query_coverage.qc run          # regression gate, exits 1 on a new cluster
python -m tools.query_coverage.qc run --all    # full picture
python -m tools.query_coverage.qc accept       # freeze the current state as the baseline

# has_error gate: the ONLY thing that sees a MISSING node for a HIDDEN token (see below)
python tools/has_error_sweep.py --root ./BC.History/   # exit 0 clean, 1 errors, 2 cannot run
python tools/has_error_sweep.py --corpus-fixtures      # every corpus case

# Config oracle (validate-grammar.sh Step 5e, CI job `config-oracle`): exit 0 clean, 1 finding, 2 cannot run
python -m tools.config_oracle run --tier quick  # ~2-3 s
./tools/ts-lock.sh python -m tools.config_oracle run --tier full|resolve --root ./BC.History --root ./DC ...  # full ~22 min
python -m tools.config_oracle replay            # historical-defect replays
# Exit-code gates, root labelling, the two classification tsvs, lowering modules: tools/config_oracle/README.md

# Traversal helper (roadmap F0, docs/traversal.md); Step 5f is the census
python tools/traversal_census.py
./tools/ts-lock.sh python -m pytest tests/traversal -q
python tests/traversal/regen_expected.py      # a -u: review every hunk of the diff

# Separator/continuation audit (B7a, docs/b7-separator-continuation-matrix.md); Step 5g is the census
python -m tools.b7_audit census --check
./tools/ts-lock.sh python -m tools.b7_audit run [--only X] [--check]   # full ~3 h cold; NOT in validate
python -m tools.b7_audit report                 # must be byte-identical to the committed matrix
./tools/ts-lock.sh python -m tools.b7_audit assert --refresh
./tools/ts-lock.sh python -m pytest tools/b7_audit/tests -q   # Step 5h
# After ANY change to src/parser.c, src/scanner.c or tools/config_oracle: `assert --refresh` per fix; a full `run`,
# then `report`, once per batch before merging (docs/agent-brief-rules.md, "Gate tiers").

# Perf (docs/performance-baselines.md). Speed DECISIONS come from `ab`, same session, ABBA; baselines are context.
python -m tools.perf ab --lib-a OLD --lib-b NEW --corpus dc
python -m tools.perf delta                      # structural production delta (B7b-3), tools/perf/delta-reviewed.tsv

# Workflow tools: use these, not ad-hoc versions
python tools/snip.py 'x := a + 1;'                 # cursor tree with fields, has_error, ERROR/MISSING/hidden; --sexp
python tools/snip.py --census --root ./BC.History   # two-shape detector for node types; exit 1 if any flagged
./tools/metrics.sh [--vs REV] [--tests]            # STATE/LARGE_STATE/SYMBOL_COUNT, parser.c size, grammar.js lines, tests
python tools/nodetypes.py show|who-has TYPE        # node-types.json questions; `diff REV`
./tools/corpus-grep.sh [-E|-P] [-i] [-l|-c] PAT    # sites over the four corpora (*.al only)
./tools/session-cleanup.sh --procs [--yes]         # leftover processes older than 30 min

# Development cycle. Always through the lock: `./tools/ts-lock.sh tree-sitter ...`
tree-sitter generate
tree-sitter generate --report-states-for-rule -  # rank rules by parser-state cost
tree-sitter test [-i PAT] [-e PAT] [--file-name F] [-d]
tree-sitter test -u                              # see the traps below
tree-sitter parse file.al -d > debug.log 2>&1    # .claude/rules/debugging.md