[blang-ast][U1] Source locations end to end

[benpayne]

Unit U1 — Phase 1 (create spec) — DRAFT, no implementation yet

Epic: blang-ast (docs/epics/blang-ast/). Covers REQ-001: every AST node carries a source location (file, line, column).

Speckit artifacts (specs/001-source-locations/)

• spec.md — 3 user stories (nodes carry locations / backtracking accuracy / CompileError location), FR-001..FR-010, measurable success criteria, recorded assumptions (column convention, node-location=first-token, pre-order dump, NodeKind naming), out-of-scope list (error formatting → U2).
• research.md — decisions R1–R8 grounded in verified code facts (per-token positions in the SymbolInfo replay list so backtracking can't desynchronize; counting in LexerReader::popChar fixing multi-line-token line drift; location on Statement/Symbol/Type bases; CompileError snapshot-at-throw; LocationDumper walker with typeid NodeKinds; minimal stdout suppression only in --dump-locations mode).
• plan.md — technical context, constitution check (v1.1.0, all principles PASS, no complexity exceptions), file-level structure.
• data-model.md, contracts/dump-locations-cli.md, quickstart.md — entity shapes, CLI + dump-line grammar contract, validation runbook.
• tasks.md — T001–T020, ending with Gate A/B and the U1 golden-diff checks from evaluation.md.

Unit done-when (workplan.md U1)

--dump-locations flag; two committed goldens (test_files/golden/{func_simple,match_basic}.locations); both diffs exit 0; no node at line/col 0; all suites green in both build modes.

For the spec audit (Phase 2)

Please apply the Spec audit rubric in docs/epics/blang-ast/evaluation.md. Implementation (Phase 3) will not begin until this spec is approved.

[benpayne]

Phase 3 (Implement) complete — ready for code audit

All per-unit gates from evaluation.md were run locally and are green:

Gate A — LLVM build, full suites

• cmake -S . -B build -DLLVM_DIR=/usr/lib/llvm-18/lib/cmake/llvm && cmake --build build → clean
• ./run_tests.sh → 162/162 passed, 0 failed
• ./test_codegen.sh → 63/63 passed

Gate B — parse-only build

• cmake -S . -B build-parse -DBLANG_ENABLE_LLVM=OFF && cmake --build build-parse → clean
• BUILD_DIR=build-parse ./run_tests.sh → 154/154 passed (8 cgfail auto-skipped)

U1-specific checks (evaluation.md §Unit-specific)

• ./build/qcc --dump-locations test_files/pass/func_simple.b | diff - test_files/golden/func_simple.locations → exit 0
• ./build/qcc --dump-locations test_files/pass/match_basic.b | diff - test_files/golden/match_basic.locations → exit 0
• No node at line 0 / col 0 in either dump.
• Corpus-wide FR-004 smoke check (auditor note Add data persistence, serialization, services, contracts, and testing to language design #2): --dump-locations over all 113 pass/*.b → 0 files with any :0: location.
• Determinism: two runs byte-identical. Build-mode parity: LLVM vs parse-only dumps identical.

Gate C — leak-check (sanity; U1 touches no runtime/ARC)

• ./test_codegen.sh --leak-check codegen_spawn*/sync*/shared* → 6/6, 0 leaks.

Note on Gate D (quiet-compile): NOT expected to pass at U1 — quiet-by-default is U2's scope. Default-mode stdout is intentionally unchanged; --dump-locations output is byte-clean on its own (parser trace goes to stderr, and dump mode diverts informational stdout).

Auditor notes folded in: (1) COMPILE_ERROR count corrected to ~215 in spec docs; (2) corpus smoke check added to quickstart.md and run; (3) T008 covered QProtocolDefinition.cpp (QParser.cpp is an empty placeholder — no stamping needed).

Diffstat: 26 files changed (+387/−68); 3 new files (SourceLocation.h, LocationDumper.h/.cpp) + 2 goldens.