Harden M2 compiler and language contract (#294–#299)

[cssbruno]

Implements the remaining M2 — Compiler + Language Contract issues. Each is a non-breaking slice landed behind the stable gwdkast AST seam, with tests.

What's in here

#299 — Parser direction (ADR)

ADR 0010 commits to a shared tokenizer + recursive-descent parser with error recovery, migrated behind the stable gwdkast AST seam. The decision is grounded in two facts: the target pipeline already names a lex/parse full AST front-end, and internal/lang.Lex is already a real tokenizer (only tooling uses it). Wired into the decisions index and docs/compiler/pipeline.md.

#294 — Byte offsets in source positions

source.SourcePosition gains a 0-based byte Offset, plus source.PositionAt / source.OffsetOf rune-accurate conversion helpers (round-trip tested). This is the exact-span substrate for AST-backed formatting and precise LSP edits. Parser-internal population is sequenced behind #299 (the field is best-effort; unset offsets stay zero, as the issue allows). The JSON-facing lang.Position is intentionally untouched so check --json goldens are stable.

#296 — Formatter brace safety

The formatter now tracks brace depth with the parser's string/comment-aware scanner (parser.NewBraceDepth) instead of naive strings.Count. Braces inside string literals, comments, and template literals (e.g. title "a { b", // note about }) no longer skew indentation. Idempotence preserved.

#297 — Related spans in conflict diagnostics

duplicate_route and route_method_conflict (including contract-route conflicts, which flow through the same registration path) now carry a related "first declared here" location. check --json gains an additive related array; the LSP emits relatedInformation. New source.RelatedSpan + ValidationError.Related thread it through compiler → lang → LSP.

#295 — Machine-checked conformance corpus

internal/lang/testdata/conformance/{accept,reject} pins the language contract: accept cases must check clean, reject cases must produce the stable diagnostic code named in a leading // expect: directive. Runner in conformance_test.go; referenced as the contract source of truth from the spec, grammar, and syntax-contributor checklist. See docs/language/conformance.md.

#298 — Per-construct stability table

docs/language/stability.md publishes stable/partial/planned/deprecated tiers for blocks, metadata keywords, and g: directives. Metadata keywords are DRYed into lang.MetadataKeywords (removing duplication between the lexer and formatter) and view.SupportedDirectiveNames is exported; a guard test cross-checks the doc against both registries.

Verification

• go test ./internal/... ./cmd/... . — all pass
• gofmt -l and go vet ./internal/... ./cmd/... — clean
• node --test editors/vscode/*.test.js — 39 pass, 0 fail
• git diff --check — clean

Notes

• One conscious call: [Compiler] Decide tokenizer + recursive-descent parser direction (ADR) #299 is filed as an ADR/decision (status Accepted, following repo convention) rather than the parser rewrite itself; the rewrite is the committed follow-up.
• M2 was a completed milestone (0 open / 53 closed); these issues reopen it with the new scope, as discussed.

🤖 Generated with Claude Code