From 94eb80d4236c9b435ff4cd9e93b365cd994f6633 Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Mon, 11 May 2026 10:14:57 -0400 Subject: [PATCH] docs: add index README and YAML frontmatter to every doc Add docs/README.md indexing every document in docs/ with a shared TYPE/CONNECTION vocabulary used consistently across all m-dev-tools repos. Add YAML frontmatter (created, last_modified, revisions, doc_type) to every existing doc. Existing frontmatter is merged, not replaced. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/README.md | 36 +++++++++++++++++++ docs/adr/AD-01-source-grammar-surface.md | 7 ++++ .../adr/AD-02-hand-code-language-structure.md | 7 ++++ docs/adr/AD-03-standard-status-on-nodes.md | 7 ++++ docs/adr/AD-04-pin-mstandard-schema.md | 7 ++++ docs/adr/AD-05-real-source-corpus.md | 7 ++++ docs/adr/AD-06-tree-sitter-bindings.md | 7 ++++ docs/adr/README.md | 7 ++++ docs/build-log.md | 7 ++++ docs/discoveries.md | 7 ++++ docs/spec.md | 7 ++++ docs/tree-sitter-notes.md | 7 ++++ docs/vista-parse-error-categories.md | 7 ++++ 13 files changed, 120 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..57d7d01 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,36 @@ +--- +created: 2026-05-11 +last_modified: 2026-05-11 +revisions: 0 +doc_type: [REFERENCE] +--- + +# tree-sitter-m — Documentation Index + +> First-pass index generated 2026-05-11. Labels follow the shared vocabulary below; the same vocabulary is used across all m-dev-tools repos. + +## Vocabulary + +Each doc is labeled `[TYPE · type? · connection · connection?]`. + +**Types** — `HISTORY` · `ARCHITECTURE` · `DESIGN` · `ADR` · `SPEC` · `REFERENCE` · `GUIDE` · `TUTORIAL` · `ROADMAP` · `PLAN` · `RESEARCH` · `SURVEY` · `GAP-ANALYSIS` · `STATUS` · `EXPLAINER` · `NOTES` · `WORKED-EXAMPLE` · `SETUP` · `INTEGRATION` · `PROPOSAL` · `BUILD-LOG` · `CHANGELOG` · `POSTMORTEM` + +**Repo connections** — `history` · `function` · `design` · `architecture` · `planning` · `implementation` + +## Top-level + +- **`spec.md`** — `[SPEC · DESIGN · design · architecture]` Full v0.1 specification covering scope, architectural decisions, language structure, build pipeline, and v1.0 success criteria. +- **`build-log.md`** — `[BUILD-LOG · HISTORY · history · implementation]` Chronological per-milestone progression log capturing deliveries, decisions made mid-build, and drift from spec. +- **`discoveries.md`** — `[GAP-ANALYSIS · NOTES · implementation · function]` DISC-NNN findings from real-world parser use, covering upstream m-standard gaps and intentional parser-side limitations. +- **`tree-sitter-notes.md`** — `[REFERENCE · NOTES · implementation · design]` Tree-sitter lexer and parser gotchas with workaround patterns; mandatory reading before adding grammar rules. +- **`vista-parse-error-categories.md`** — `[GAP-ANALYSIS · PLAN · planning · implementation]` Living triage of remaining VistA-corpus parse errors bucketed into actionable categories. + +## `adr/` — Architecture Decision Records for the grammar + +- **`adr/README.md`** — `[REFERENCE · architecture]` Existing ADR index — see for full per-ADR detail. +- **`adr/AD-01-source-grammar-surface.md`** — `[ADR · design · architecture]` Source keyword tables from m-standard's union grammar-surface rather than any single M standard. +- **`adr/AD-02-hand-code-language-structure.md`** — `[ADR · design · architecture]` Hand-code invariant structural rules in `grammar.js`; data-drive the keyword tables from m-standard. +- **`adr/AD-03-standard-status-on-nodes.md`** — `[ADR · design · function]` Stamp every recognised keyword node with a `standard_status` tier attribute via sidecar metadata lookup. +- **`adr/AD-04-pin-mstandard-schema.md`** — `[ADR · architecture · planning]` Pin the consumed `m-standard` schema_version so breaking upstream changes require a deliberate major bump. +- **`adr/AD-05-real-source-corpus.md`** — `[ADR · design · implementation]` Validate against three test layers including the full 39,330-routine VistA corpus as the reality gate. +- **`adr/AD-06-tree-sitter-bindings.md`** — `[ADR · architecture · implementation]` Ship Node, Rust, Python, and Go bindings via tree-sitter's standard scaffold with no bespoke binding code. diff --git a/docs/adr/AD-01-source-grammar-surface.md b/docs/adr/AD-01-source-grammar-surface.md index 809085d..f01ae63 100644 --- a/docs/adr/AD-01-source-grammar-surface.md +++ b/docs/adr/AD-01-source-grammar-surface.md @@ -1,3 +1,10 @@ +--- +created: 2026-04-26 +last_modified: 2026-04-26 +revisions: 1 +doc_type: [ADR] +--- + # AD-01: Source the keyword tables from `m-standard`'s grammar-surface, not from any single standard **Status:** accepted (B0, 2026-04) diff --git a/docs/adr/AD-02-hand-code-language-structure.md b/docs/adr/AD-02-hand-code-language-structure.md index 1d1eb31..4e097b5 100644 --- a/docs/adr/AD-02-hand-code-language-structure.md +++ b/docs/adr/AD-02-hand-code-language-structure.md @@ -1,3 +1,10 @@ +--- +created: 2026-04-26 +last_modified: 2026-04-26 +revisions: 1 +doc_type: [ADR] +--- + # AD-02: Hand-code the language structure; data-drive the keyword tables **Status:** accepted (B0, 2026-04) diff --git a/docs/adr/AD-03-standard-status-on-nodes.md b/docs/adr/AD-03-standard-status-on-nodes.md index 0483e02..9094d26 100644 --- a/docs/adr/AD-03-standard-status-on-nodes.md +++ b/docs/adr/AD-03-standard-status-on-nodes.md @@ -1,3 +1,10 @@ +--- +created: 2026-04-26 +last_modified: 2026-04-26 +revisions: 1 +doc_type: [ADR] +--- + # AD-03: Stamp `standard_status` as an AST node attribute **Status:** accepted (B0, 2026-04); partial implementation (B3) diff --git a/docs/adr/AD-04-pin-mstandard-schema.md b/docs/adr/AD-04-pin-mstandard-schema.md index 9b8464d..b784442 100644 --- a/docs/adr/AD-04-pin-mstandard-schema.md +++ b/docs/adr/AD-04-pin-mstandard-schema.md @@ -1,3 +1,10 @@ +--- +created: 2026-04-26 +last_modified: 2026-04-26 +revisions: 1 +doc_type: [ADR] +--- + # AD-04: Pin to a specific `m-standard` schema version **Status:** accepted (B0, 2026-04) diff --git a/docs/adr/AD-05-real-source-corpus.md b/docs/adr/AD-05-real-source-corpus.md index dba5f54..9b4f940 100644 --- a/docs/adr/AD-05-real-source-corpus.md +++ b/docs/adr/AD-05-real-source-corpus.md @@ -1,3 +1,10 @@ +--- +created: 2026-04-26 +last_modified: 2026-04-26 +revisions: 1 +doc_type: [ADR] +--- + # AD-05: Test against a corpus of real M code from multiple sources **Status:** accepted (B0, 2026-04); validated end of B5 (99.06% on full diff --git a/docs/adr/AD-06-tree-sitter-bindings.md b/docs/adr/AD-06-tree-sitter-bindings.md index 9850b5e..9edb03f 100644 --- a/docs/adr/AD-06-tree-sitter-bindings.md +++ b/docs/adr/AD-06-tree-sitter-bindings.md @@ -1,3 +1,10 @@ +--- +created: 2026-04-26 +last_modified: 2026-05-09 +revisions: 2 +doc_type: [ADR] +--- + # AD-06: Provide language bindings via tree-sitter's standard scaffold **Status:** accepted (B0, 2026-04); scaffolded + locally verified (B6, diff --git a/docs/adr/README.md b/docs/adr/README.md index e631b3a..7c8b713 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -1,3 +1,10 @@ +--- +created: 2026-04-26 +last_modified: 2026-04-26 +revisions: 1 +doc_type: [REFERENCE] +--- + # Architectural decisions — tree-sitter-m The six decisions that drive the rest of [`docs/spec.md`](../spec.md). diff --git a/docs/build-log.md b/docs/build-log.md index e51078d..84c72a2 100644 --- a/docs/build-log.md +++ b/docs/build-log.md @@ -1,3 +1,10 @@ +--- +created: 2026-04-25 +last_modified: 2026-05-09 +revisions: 23 +doc_type: [BUILD-LOG, HISTORY] +--- + # Build log — tree-sitter-m Chronological notes on milestone deliveries, decisions made during diff --git a/docs/discoveries.md b/docs/discoveries.md index 53bebe6..c960267 100644 --- a/docs/discoveries.md +++ b/docs/discoveries.md @@ -1,3 +1,10 @@ +--- +created: 2026-04-26 +last_modified: 2026-05-09 +revisions: 3 +doc_type: [GAP-ANALYSIS, NOTES] +--- + # tree-sitter-m discoveries log Findings surfaced by real-world use of the parser — gaps in the diff --git a/docs/spec.md b/docs/spec.md index acfb873..42a6a8b 100644 --- a/docs/spec.md +++ b/docs/spec.md @@ -1,3 +1,10 @@ +--- +created: 2026-04-25 +last_modified: 2026-05-09 +revisions: 7 +doc_type: [SPEC, DESIGN] +--- + # tree-sitter-m — Specification v0.1 **Status:** draft for review diff --git a/docs/tree-sitter-notes.md b/docs/tree-sitter-notes.md index f1664b2..6f1bc1a 100644 --- a/docs/tree-sitter-notes.md +++ b/docs/tree-sitter-notes.md @@ -1,3 +1,10 @@ +--- +created: 2026-04-26 +last_modified: 2026-04-26 +revisions: 2 +doc_type: [REFERENCE, NOTES] +--- + # Tree-sitter implementation notes Things about tree-sitter's lexer/parser that aren't obvious from the diff --git a/docs/vista-parse-error-categories.md b/docs/vista-parse-error-categories.md index ff90f4a..ba9d183 100644 --- a/docs/vista-parse-error-categories.md +++ b/docs/vista-parse-error-categories.md @@ -1,3 +1,10 @@ +--- +created: 2026-05-06 +last_modified: 2026-05-06 +revisions: 1 +doc_type: [GAP-ANALYSIS, PLAN] +--- + # VistA parse-error triage — patterns to close Living document. Triage of the 376 parse-error files in the