v3.1.0 — Documentation, diagrams, and maintainability

SQL Cartographer v3.1.0 — Documentation, diagrams, and maintainability

A quality pass over the code and the documentation. The product now explains
itself: the docs carry real Mermaid diagrams and screenshots of both pages, the
architecture is described against the code that actually exists, and the
contributor path has one home. Two correctness defects found during the pass
are fixed.

No user-data format changed. Nothing saved by v3.0.0 is affected.

Highlights

• Diagrams in the documentation. The project has exported Mermaid since
  v1.0 and not one doc rendered a diagram. There are now Mermaid figures for
  the analysis pipeline, the module dependency graph, the ERD layout pipeline,
  bridge tables, self joins, the two-paths tie-break, the report → dataset →
  object → column chain, and the node/edge vocabulary. All eight parse under
  securityLevel: 'strict' with the vendored renderer.
• Screenshots of both pages. index.html and erd.html — including the
  query builder mid-plan — are pictured in the README and the user guide. For a
  visualisation tool, this was the largest "can I judge this before running it"
  gap.
• A worked example. The user guide now walks one procedure from source SQL
  through the rendered diagram to the exported Mermaid and its provenance
  comment, using the product's real output rather than an invented one.
• A wordmark defect fixed. v3.0.0 renamed the project and claimed one
  consistent wordmark, but both pages still shipped proc>flow because the
  markup splits it across a <span class="caret">. A CI guard now catches that
  exact form.

Fixed

• ROLLBACK TO <savepoint> misread its target. tsqlTransactionAction
  never skipped the TO keyword, so ROLLBACK TO my_sp reported the savepoint
  as TO. The informative "roll back to savepoint X" label could not fire, and
  the name would have been registered wrongly had the save path seen it. Found
  by writing direct unit fixtures for the transaction model; those fixtures are
  the regression test.
• A failed column-flow analysis vanished silently. Two guards in
  analyse caught a failure and returned no column flow with no diagnostic,
  contradicting the contract that unknown constructs stay explicit. Both now
  push a document-scoped column_flow_analysis_error, matching what the report
  pipeline already did. The column-flow model survives a graph-layout failure;
  only the rendered graph is dropped, and that is now said out loud.

Documentation

• docs/README.md — a documentation map with a learning path for users,
  contributors, and reviewers.
• CONTRIBUTING.md — the non-negotiables, fixtures-before-fixes, and the
  pre-PR checklist, consolidated from three places that had drifted. ADR
  template and index in docs/decisions/.
• docs/GLOSSARY.md — the vocabulary the docs and the UI share (opaque region,
  bridge table, taught join, token attribution, declared evidence, and friends),
  which until now was used before definition.
• .github/SECURITY.md — points GitHub's security tab at the canonical policy
  in docs/SECURITY.md.
• docs/ARCHITECTURE.md refreshed against src/: seven modules were missing,
  one attribution was stale, and the documented one-way dependency chain was
  not reflected. Now includes the module load-order contract and the graph
  vocabulary table.
• TOCs added to the user guide and the query builder. 21 broken relative links
  in docs/archive/ repaired (they broke when those notes moved into
  archive/). README's roadmap link no longer contradicts the roadmap's own
  "historical" banner.

Maintainability

• The T-SQL transaction model is now testable on its own. 15 pure functions
  moved from src/ir.ts into src/dialects-state.ts, alongside the
  TSQL_XACT_* bitmask constants they operate on. ir.ts no longer contains
  the bitmask algebra at all.
• emitOne is a dispatch, not a 400-line switch. Its 16 node-kind cases
  are now named emitters (emitTry, emitIteration, emitHandler, …), each
  typed to its own AST node. ir.ts is 1532 → 1057 lines and the emitted graph
  is unchanged, verified by 222 golden assertions.
• 54 diagnostic codes are compiler-enforced. Diagnostic.code is now a
  closed DiagnosticCode union instead of string, so a typo is a compile
  error rather than a message that never matches a test.
• Deduplicated: twelve localStorage wrappers in src/workspace.ts
  collapsed to four primitives; three copies of the same span predicate in the
  golden tests collapsed to one; the duplicated outer-parenthesis stripper in
  src/dialects-state.ts is one helper.
• Renamed the confusables: queryBuildGraph → queryBuildJoinGraph
  (distinct from lineage.ts's buildQueryGraph), the O/o parameter pair
  in src/columnflow.ts, a variable named any, and the version-suffixed test
  helpers.
• Bundled ERD sample DDL moved from src/erd.ts to src/samples.ts, whose
  stated purpose is exactly that. Removed the production-dead layoutDrawio
  wrapper.

Testing

• New suite tests/xact-state.ts: 58 direct fixtures for the transaction
  algebra, which previously had zero direct coverage — depth-range
  intersection, the depth ↔ state bit-set conversions, the state labels,
  transaction action parsing (including BEGIN DISTRIBUTED TRAN [WORK] and
  variable savepoint targets), action validity per state, and FlowContext
  parent-chain inheritance. It gates the golden page.
• Two new fixtures in tests/column-flow.ts require that a column-flow or
  column-graph failure is reported rather than swallowed.
• golden 221 → 222 cases. The fixture-corpus snapshot is
  metrics-v3.1.0.json, with columnFlow 15 → 17 and
  every tracked rate still 1 — attribution, semantic edge coverage,
  provenance, export parity, export traceability, layout budgets, and the
  adversarial semantic assertion rate.

Verification

npm run lint, npm run typecheck, npm run build, npm test
(728 cases: golden 222, fuzz 400, ui 32, erd-ui 68, security 6),
npm run test:file, npm run metrics, npm run benchmark, and
npm run package:smoke all pass. Committed dist/ is current. The runtime
remains local-only: no network call, and localStorage is still touched only
by src/workspace.ts.

Known gaps

Deliberately out of scope for this release, and recorded so they are not lost:

• src/ui/erd-page.ts is still 1422 lines (cards, layout, zoom, routing, and
  event wiring in one closure). The clean split already used by
  src/ui/erd-query-view.ts is the template, but extracting it is a
  behaviour-sensitive change to the ERD interaction layer and wants its own
  release with its own fixtures.
• The type-strictness pilot still covers only the extracted modules. Extending
  tsconfig.strict.json is incremental work that is worth doing file by file.
• Test-side duplication of the export-manifest assertion block across
  tests/parity.ts, tests/report-graph.ts, and tests/column-flow.ts remains.

See the changelog for the condensed history.