From c27dbfaa52e97edb3411a5c8ce2e5be805eb6014 Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Sun, 10 May 2026 22:50:26 -0400 Subject: [PATCH 1/3] docs(plans): add Phase 3 implementation plan (3b + 3c) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Convert §6.2 of language-cli-survey.md into an actionable punch list for the remaining Phase 3 work — m fix, m profile, m bench, and m debug — with explicit dependencies, priority ordering, exit criteria, and per-subcommand risks. Phase 3a is shipped, so the plan picks up at 3b. Add a pointer from language-cli-survey.md so the plan is discoverable from the source survey. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/plans/language-cli-survey.md | 4 + docs/plans/phase-3-plan.md | 267 ++++++++++++++++++++++++++++++ 2 files changed, 271 insertions(+) create mode 100644 docs/plans/phase-3-plan.md diff --git a/docs/plans/language-cli-survey.md b/docs/plans/language-cli-survey.md index e77a4f4..afadc27 100644 --- a/docs/plans/language-cli-survey.md +++ b/docs/plans/language-cli-survey.md @@ -6,6 +6,10 @@ > software development life cycle (SDLC). Closes with a rank-ordered gap analysis > for `m-cli` — the canonical CLI for the M (MUMPS) language. > +> **Implementation:** the actionable punch list for Phase 3b/3c (with +> dependencies, priorities, and exit criteria) lives in +> [`phase-3-plan.md`](phase-3-plan.md). Phase 3a is shipped. +> > **Scope.** Five languages: **Rust, Go, Python, JavaScript/TypeScript, Java.** > Chosen for top consistent rankings (TIOBE / Stack Overflow / GitHub Octoverse > 2024–2026) and for spanning the design space — single-binary unified CLIs diff --git a/docs/plans/phase-3-plan.md b/docs/plans/phase-3-plan.md new file mode 100644 index 0000000..7d4b0ca --- /dev/null +++ b/docs/plans/phase-3-plan.md @@ -0,0 +1,267 @@ +# Phase 3 Implementation Plan — `m fix`, `m profile`, `m bench`, `m debug` + +**Status:** working plan. Phase 3a is shipped; this document scopes Phase 3b and Phase 3c with explicit dependencies and priorities. + +**Derived from:** [`language-cli-survey.md`](language-cli-survey.md) §6.2 (phased roadmap) and §4.1 (capability ranks). The phase labels and shape come from there — this doc converts the prose into an actionable punch list. + +**Audience:** m-cli contributors picking up the next subcommand; reviewers tracking what's queued. + +**Scope:** + +- Phase 3b: `m fix`, `m profile`, `m bench`. +- Phase 3c: `m debug` (DAP server + VS Code wiring). +- Cross-cutting: VistA gate, library API surface, performance budgets. + +**Not in scope:** Phase 4 (`m pkg` / `m audit` / `m publish` — ecosystem work, year-2+) and Phase 5 polish (`m typecheck`, `m toolchain`, `$PATH`-discovered subcommands). The IRIS portability track in [`iris-ydb-portability.md`](iris-ydb-portability.md) runs in parallel; this plan only notes touchpoints, not deliverables. + +--- + +## 0. Current state — Phase 3a shipped + +| Subcommand | Source | Status | +|---|---|---| +| `m doctor` | [`src/m_cli/doctor/cli.py`](../../src/m_cli/doctor/cli.py) | Shipped | +| `m new` | [`src/m_cli/new/cli.py`](../../src/m_cli/new/cli.py) | Shipped | +| `m ci init` | [`src/m_cli/ci/cli.py`](../../src/m_cli/ci/cli.py) | Shipped | +| `m run` | [`src/m_cli/run/cli.py`](../../src/m_cli/run/cli.py) | Shipped | +| `m build` | [`src/m_cli/build/cli.py`](../../src/m_cli/build/cli.py) | Shipped | +| `m doc` | [`src/m_cli/doc/cli.py`](../../src/m_cli/doc/cli.py) | Shipped | + +Phase 3a exit criterion is met: `m new` produces a project that passes `m fmt --check && m lint && m test && m coverage` on a clean clone. Everything below builds on the Phase 3a / Tier 1+2 foundation; nothing in this plan revisits it. + +--- + +## 1. Dependency graph + +``` + Tier 1+2 foundation (parser · fmt rule engine · lint runner · + WorkspaceIndex · YDB trace · test discovery) + │ + ┌─────────────────────────┼─────────────────────────┐ + │ │ │ + ▼ ▼ ▼ + ┌──────────┐ ┌──────────┐ ┌──────────┐ + │ m fix │ │ m profile│ │ m bench │ + │ (3b-1) │ │ (3b-2) │ │ (3b-3) │ + └────┬─────┘ └────┬─────┘ └──────────┘ + │ │ + │ shares fixer_id │ shares TRACE view + │ contract with LSP │ with `m coverage` + ▼ ▼ + (Quick Fix code-actions (flamegraph output · + expand to ≥10 rules) folded-stack format) + + ┌────────────────────────┐ + │ engine ZBREAK / ZSTEP │ + │ ZSHOW (existing) │ + └──────────┬─────────────┘ + ▼ + ┌──────────┐ ┌──────────────────┐ + │ m debug │ ────▶ │ VS Code DAP wiring│ + │ (3c-1) │ │ (3c-2) │ + └──────────┘ └──────────────────┘ +``` + +**Critical-path observations:** + +1. `m fix` is the highest-leverage 3b item — every `fixer_id`-tagged lint rule becomes an LSP Quick Fix the day it ships, and future lint rules can register a fixer alongside the rule. +2. `m profile` and `m bench` are independent of `m fix` and of each other. They can ship in parallel. +3. `m debug` depends on no other Phase 3 work. It's gated by DAP-server scope (large, ~4–6 weeks) and can run in parallel with all of 3b. +4. Nothing in 3b/3c blocks Phase 4. The ecosystem work is independent and deliberately a year-2+ commitment. + +--- + +## 2. Priorities — what to ship first + +Ranked by leverage (developer time saved per engineering week invested) and by how much existing infrastructure each item reuses. + +| Rank | Item | Why first | Effort | +|:---:|---|---|:---:| +| 1 | `m fix` | Promotes every existing `fixer_id`-tagged lint rule into an auto-fix; LSP Quick Fix coverage jumps from 2 → 10+ on day one. Reuses `m fmt` rule engine wholesale. | M (1–2 wk) | +| 2 | `m profile` | Closes the biggest "I can't tell where my routine is slow" gap. Reuses `view "TRACE"` machinery from `m coverage`; folded-stack output is one new formatter. | M (1–2 wk) | +| 3 | `m bench` | Smallest of the three; immediately useful for m-cli's own perf-budget discipline. Reuses test discovery 1:1 (just a different label prefix and a `.m` file-name suffix). | S (3–5 d) | +| 4 | `m debug` (DAP server) | Largest single developer-felt missing feature, but largest scope. Parallelizable, not blocking. | L (4–6 wk) | +| 5 | VS Code DAP wiring | Trivial once `m debug` exists; lands in `tree-sitter-m-vscode`. | S (3–5 d) | + +**Recommended sequencing.** Start `m fix` first — it has the steepest payoff curve and the smallest blast radius. Begin `m debug` in parallel if a second contributor is available; otherwise queue 3c after 3b. `m profile` and `m bench` can interleave with `m fix` reviews without contention. + +--- + +## 3. Phase 3b — Generalize existing infrastructure + +### 3b-1 · `m fix` — auto-fix recipes + structural search/replace + +**Builds on:** `m fmt` rule engine ([`src/m_cli/fmt/`](../../src/m_cli/fmt/)), lint `fixer_id` linkage ([`src/m_cli/lint/__init__.py`](../../src/m_cli/lint/__init__.py) `fixer_for`). + +**Deliverables:** + +- New subcommand package `src/m_cli/fix/` with `cli.py` + `recipes.py` + `engine.py`. +- Named recipes that wrap a single fmt rule (`m fix trim-trailing-whitespace`). +- Structural search/replace driven by tree-sitter-m queries (`m fix --query 'SET $x=$x+1' --replace 'SET $x=$x+1 ; iterate'`). +- Every lint rule with a `fixer_id` becomes auto-fixable via `m fix --rule M-XINDX-013`. +- LSP `code_actions_for_uri` updated to expose all `fixer_id`-tagged rules (currently exposes 2, target ≥10). +- Idempotency tests: running `m fix` twice on the same source produces no second diff. + +**Exit criterion:** + +- All currently-registered `fixer_id` mappings are reachable via `m fix --rule `. +- `make check-fixer-linkage` (new gate) asserts every lint rule with a `fixer_id` resolves to a real fmt rule. +- LSP Quick Fix code-action count ≥10 on a fixture file that triggers all auto-fixable rules. +- `make lint-vista` over the configured corpus shows zero regressions in finding counts (auto-fixes change source, not finding semantics). + +**Risks:** + +- Tree-sitter structural-replace UX is unproven in M; start with named recipes only, defer the `--query` mode if it complicates the first ship. +- Recipe-on-recipe ordering matters once we ship more than one rule that touches the same node type. Document the conflict resolution rule upfront — likely "left-to-right in CLI invocation, deterministic-order if discovered from `fixer_id` set." + +--- + +### 3b-2 · `m profile` — flat profile + folded-stack output + +**Builds on:** YDB `view "TRACE"` driver from [`src/m_cli/coverage/runner.py`](../../src/m_cli/coverage/runner.py). + +**Deliverables:** + +- New subcommand package `src/m_cli/profile/` with `cli.py` + `runner.py` + `output.py`. +- Flat profile: line/label execution counts × time per call, sorted by self-time. +- Folded-stack format compatible with [`flamegraph.pl`](https://github.com/brendangregg/FlameGraph). +- Optional `--svg` flag that shells to `flamegraph.pl` if available; otherwise prints folded stacks for the user to pipe. +- `--baseline FILE` for comparison runs (delta self-time per label). +- Test fixture: profile a real `*TST.m` suite from m-stdlib; assert the slowest label surfaces in the top-N. + +**Exit criterion:** + +- `m profile FILE.m::tLabel` produces a flat profile with non-zero self-times. +- `m profile --format=folded` output renders correctly in `flamegraph.pl` (manually verified once; CI checks format only, not rendering). +- `make check` includes a smoke test that profiles a known-slow fixture and asserts the hot label is at the top of the flat profile. + +**Risks:** + +- `view "TRACE"` resolution granularity is per-line, not per-call. Document the limitation; don't promise call-graph reconstruction we can't deliver. +- Time measurement uses `$ZH` (or `$ZHOROLOG`); confirm sub-millisecond resolution on the target YDB version. Fall back to "count-only profiling" if the timer is too coarse for short tests. + +--- + +### 3b-3 · `m bench` — micro-benchmark runner + +**Builds on:** `m test` discovery ([`src/m_cli/test/discovery.py`](../../src/m_cli/test/discovery.py)) and runner ([`src/m_cli/test/runner.py`](../../src/m_cli/test/runner.py)). + +**Deliverables:** + +- New subcommand package `src/m_cli/bench/` with `cli.py` + `discovery.py` + `runner.py` + `output.py`. +- Discovery: `b` labels in `*BCH.m` files (parser-aware, same pattern as test discovery). +- Timing via `$ZH`; report ops/sec and ns/op. +- `--baseline FILE` for comparison mode (delta ops/sec per label, with significance threshold). +- Output formats: text (default), JSON. +- Document the benchmark-writing convention in [`docs/guide.md`](../guide.md) (analogous to the test section). + +**Exit criterion:** + +- `m bench` discovers and runs at least one bench file in a real M project (m-stdlib `STDFMT` or `STDREGEX` are obvious candidates). +- Comparison mode flags a deliberate 2× regression in a fixture and surfaces it in the output. +- Zero new dependencies beyond what `m test` already pulls in. + +**Risks:** + +- Warmup / JIT-like effects are absent in M, but YDB block-cache state isn't. Document that benches should be self-contained or include explicit setup; don't try to auto-warm. + +--- + +## 4. Phase 3c — `m debug` (DAP server + editor wiring) + +### 3c-1 · `m debug` — DAP server + +**Builds on:** YDB engine primitives (`ZBREAK`, `ZSTEP`, `ZSHOW`) — already used elsewhere in the codebase via [`src/m_cli/engine.py`](../../src/m_cli/engine.py); no new engine work required. + +**Deliverables:** + +- New subcommand package `src/m_cli/debug/` exposing a [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) server over stdio. +- Capabilities: breakpoints (line, conditional), step in/over/out, locals/watch (via `ZSHOW`), call stack, exception breakpoints. +- Driver wraps a `ydb -direct` subprocess; multiplexes DAP messages on stdin/stdout while controlling the YDB process via `ZBREAK` / `ZSTEP`. +- Engine targeting: YDB-first. The `--target-engine` flag accepts `iris` but exit-1's with "not supported yet" — the hook stays in for the IRIS portability track. +- Tests use a fake engine (same pattern as `m test`'s injectable `RunnerFn`) so unit tests don't need a live ydb. + +**Exit criterion:** + +- A DAP client (manually invoked, no editor) can set a breakpoint, run, hit it, inspect locals, and step through a routine. +- `m debug` survives a 10-minute soak with breakpoints set on a real m-stdlib test suite (no leaks, no orphaned ydb processes). + +**Risks:** + +- `ZBREAK` semantics across YDB versions: confirm the documented behavior on the pinned minimum YDB version, pin the test suite to that version in CI. +- Variable scoping: M's local variables don't have explicit scopes the way most DAP clients expect. The DAP `Scope` for "locals" maps to "all currently-defined locals via `ZSHOW \"V\"`"; document the mapping upfront. +- Multi-process: YDB can fork worker processes (`JOB`); we will not attempt multi-process debugging in v1. Document and exit-1 if encountered. + +--- + +### 3c-2 · VS Code DAP wiring + +**Builds on:** `m debug` server + existing [`tree-sitter-m-vscode`](https://github.com/m-dev-tools/tree-sitter-m-vscode) extension. + +**Deliverables:** + +- Register a debug adapter contribution in `tree-sitter-m-vscode/package.json`. +- Launch configuration template: `m debug ` or `m debug --test FILE.m::tLabel`. +- F5 launches a debug session; breakpoints set in the gutter round-trip to the DAP server. +- Documentation update in `tree-sitter-m-vscode/README.md`. + +**Exit criterion:** + +- Setting a gutter breakpoint, pressing F5 on a `*TST.m` file, hitting the breakpoint, inspecting locals, and stepping through a routine all work without manual `ydb` terminal interaction. + +--- + +## 5. Cross-cutting investments + +These thread through every phase and should be budgeted explicitly, not as line items. + +| Investment | When | Why | +|---|---|---| +| **VistA gate maintenance.** Re-run `make vista`, `make lint-vista`, smoke tests on every new subcommand that touches the parser or rule engines. | Every PR | The 39,330-routine corpus is the only honest stress test we have. Regressions caught here cost 1 hour; in prod they cost weeks. | +| **Library API stability.** Anything new that out-of-tree tools should consume goes into `m_cli.__all__` and is pinned by [`tests/test_library_api.py`](../../tests/test_library_api.py). | Phase 3b onward | LSP, pre-commit, future IDE integrations all consume the library API. Breaking it is a tax on every consumer. | +| **Performance budget.** Every new subcommand that walks the corpus declares a budget and verifies it. | Phase 3b onward | Lint already costs ~22 s on 16 cores. A `fix` / `profile` / `bench` run that scales linearly to corpus size needs the same `--jobs` discipline up front. | +| **`make check-manifest` drift gate.** Every new subcommand must register a `cli.py` so `make manifest` picks it up into `dist/commands.json`. | Phase 3b onward | The manifest is the tier-1 contract for downstream tooling discovery. | + +--- + +## 6. Decision points to revisit per phase + +| Decision | When | Default | Watch for | +|---|---|---|---| +| Continue extending Python codebase vs port hot paths to Rust | End of 3b | Stay in Python | Lint perf regressing past 60 s on VistA; test runner startup overhead becoming visible. | +| `m debug` on YDB only or design for engine-portable DAP | Start of 3c | YDB-first; abstraction comes later if Caché / IRIS users appear | Demand signal from non-YDB users; sponsor for Caché support. | +| Tree-sitter structural-replace UX | During 3b-1 | Ship named recipes only in v1; defer `--query` mode | Recipe coverage stays flat; users hand-rolling `sed` for cross-rule fixes. | +| Profile call-graph reconstruction | During 3b-2 | Flat profile + folded stacks only; no synthetic call graph | Repeated user requests for true call-graph view. | + +--- + +## 7. Suggested Gantt + +``` + W1 W2 W3 W4 W5 W6 W7 W8 W9 W10 W11 W12 … +m fix (3b-1) █████████████ +m profile (3b-2) █████████████ +m bench (3b-3) ████████ +m debug (3c-1) ░░░░░░░░░░░░░░░░░░░░░░░░░████████████████████ +VS Code DAP (3c-2) ████████ +VistA gate ◄────────── continuous ──────────────────────────► +``` + +- 3b lands inside ~8 weeks if sequential, ~5 if `m profile` and `m bench` overlap. +- 3c can start at W1 with a second contributor; otherwise picks up at W8. Either way, lands inside one quarter. +- The "two productivity-defining phases (3b + 3c) ship inside one quarter" target from the survey is achievable; the constraint is contributor-count, not technical scope. + +--- + +## 8. Exit criterion for the phase as a whole + +Phase 3 is complete when: + +1. `m fix`, `m profile`, `m bench`, `m debug` are all documented in [`guide.md`](../guide.md), shipped with tests, and reachable via `m --help`. +2. `make check-manifest` passes — every subcommand is in `dist/commands.json`. +3. LSP Quick Fix coverage is ≥10 rules. +4. A flamegraph generated by `m profile` is checked in as a worked example under [`examples/`](../../examples/). +5. A debug session in VS Code (gutter breakpoint → hit → step → inspect) is documented with screenshots in `tree-sitter-m-vscode/README.md`. +6. The `m-cli` capability surface in `dist/commands.json` matches §6 of [`language-cli-survey.md`](language-cli-survey.md) rows 1–12 (the Tier-1 essentials + Phase 3 deliverables). + +When all six are true, the next planning doc is Phase 4 (`m pkg` / `m audit` / `m publish`) — explicitly a year-2+ commitment per the survey, contingent on ecosystem demand signal. From 51775f521b9bfc1e458b8e50a5582f9be6bdf0b3 Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Sun, 10 May 2026 22:53:40 -0400 Subject: [PATCH 2/3] Revert "docs(plans): add Phase 3 implementation plan (3b + 3c)" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This reverts c27dbfa. The doc was scoped to m-cli's internal Phase 3 from language-cli-survey.md §6.2 (m fix / m profile / m bench / m debug), but "Phase 3" in this org refers to the org-level AI-discoverability Phase 3 (recipes + handshake test) tracked in .github/docs/. The plan now lands there instead. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/plans/phase-3-plan.md | 267 ------------------------------------- 1 file changed, 267 deletions(-) delete mode 100644 docs/plans/phase-3-plan.md diff --git a/docs/plans/phase-3-plan.md b/docs/plans/phase-3-plan.md deleted file mode 100644 index 7d4b0ca..0000000 --- a/docs/plans/phase-3-plan.md +++ /dev/null @@ -1,267 +0,0 @@ -# Phase 3 Implementation Plan — `m fix`, `m profile`, `m bench`, `m debug` - -**Status:** working plan. Phase 3a is shipped; this document scopes Phase 3b and Phase 3c with explicit dependencies and priorities. - -**Derived from:** [`language-cli-survey.md`](language-cli-survey.md) §6.2 (phased roadmap) and §4.1 (capability ranks). The phase labels and shape come from there — this doc converts the prose into an actionable punch list. - -**Audience:** m-cli contributors picking up the next subcommand; reviewers tracking what's queued. - -**Scope:** - -- Phase 3b: `m fix`, `m profile`, `m bench`. -- Phase 3c: `m debug` (DAP server + VS Code wiring). -- Cross-cutting: VistA gate, library API surface, performance budgets. - -**Not in scope:** Phase 4 (`m pkg` / `m audit` / `m publish` — ecosystem work, year-2+) and Phase 5 polish (`m typecheck`, `m toolchain`, `$PATH`-discovered subcommands). The IRIS portability track in [`iris-ydb-portability.md`](iris-ydb-portability.md) runs in parallel; this plan only notes touchpoints, not deliverables. - ---- - -## 0. Current state — Phase 3a shipped - -| Subcommand | Source | Status | -|---|---|---| -| `m doctor` | [`src/m_cli/doctor/cli.py`](../../src/m_cli/doctor/cli.py) | Shipped | -| `m new` | [`src/m_cli/new/cli.py`](../../src/m_cli/new/cli.py) | Shipped | -| `m ci init` | [`src/m_cli/ci/cli.py`](../../src/m_cli/ci/cli.py) | Shipped | -| `m run` | [`src/m_cli/run/cli.py`](../../src/m_cli/run/cli.py) | Shipped | -| `m build` | [`src/m_cli/build/cli.py`](../../src/m_cli/build/cli.py) | Shipped | -| `m doc` | [`src/m_cli/doc/cli.py`](../../src/m_cli/doc/cli.py) | Shipped | - -Phase 3a exit criterion is met: `m new` produces a project that passes `m fmt --check && m lint && m test && m coverage` on a clean clone. Everything below builds on the Phase 3a / Tier 1+2 foundation; nothing in this plan revisits it. - ---- - -## 1. Dependency graph - -``` - Tier 1+2 foundation (parser · fmt rule engine · lint runner · - WorkspaceIndex · YDB trace · test discovery) - │ - ┌─────────────────────────┼─────────────────────────┐ - │ │ │ - ▼ ▼ ▼ - ┌──────────┐ ┌──────────┐ ┌──────────┐ - │ m fix │ │ m profile│ │ m bench │ - │ (3b-1) │ │ (3b-2) │ │ (3b-3) │ - └────┬─────┘ └────┬─────┘ └──────────┘ - │ │ - │ shares fixer_id │ shares TRACE view - │ contract with LSP │ with `m coverage` - ▼ ▼ - (Quick Fix code-actions (flamegraph output · - expand to ≥10 rules) folded-stack format) - - ┌────────────────────────┐ - │ engine ZBREAK / ZSTEP │ - │ ZSHOW (existing) │ - └──────────┬─────────────┘ - ▼ - ┌──────────┐ ┌──────────────────┐ - │ m debug │ ────▶ │ VS Code DAP wiring│ - │ (3c-1) │ │ (3c-2) │ - └──────────┘ └──────────────────┘ -``` - -**Critical-path observations:** - -1. `m fix` is the highest-leverage 3b item — every `fixer_id`-tagged lint rule becomes an LSP Quick Fix the day it ships, and future lint rules can register a fixer alongside the rule. -2. `m profile` and `m bench` are independent of `m fix` and of each other. They can ship in parallel. -3. `m debug` depends on no other Phase 3 work. It's gated by DAP-server scope (large, ~4–6 weeks) and can run in parallel with all of 3b. -4. Nothing in 3b/3c blocks Phase 4. The ecosystem work is independent and deliberately a year-2+ commitment. - ---- - -## 2. Priorities — what to ship first - -Ranked by leverage (developer time saved per engineering week invested) and by how much existing infrastructure each item reuses. - -| Rank | Item | Why first | Effort | -|:---:|---|---|:---:| -| 1 | `m fix` | Promotes every existing `fixer_id`-tagged lint rule into an auto-fix; LSP Quick Fix coverage jumps from 2 → 10+ on day one. Reuses `m fmt` rule engine wholesale. | M (1–2 wk) | -| 2 | `m profile` | Closes the biggest "I can't tell where my routine is slow" gap. Reuses `view "TRACE"` machinery from `m coverage`; folded-stack output is one new formatter. | M (1–2 wk) | -| 3 | `m bench` | Smallest of the three; immediately useful for m-cli's own perf-budget discipline. Reuses test discovery 1:1 (just a different label prefix and a `.m` file-name suffix). | S (3–5 d) | -| 4 | `m debug` (DAP server) | Largest single developer-felt missing feature, but largest scope. Parallelizable, not blocking. | L (4–6 wk) | -| 5 | VS Code DAP wiring | Trivial once `m debug` exists; lands in `tree-sitter-m-vscode`. | S (3–5 d) | - -**Recommended sequencing.** Start `m fix` first — it has the steepest payoff curve and the smallest blast radius. Begin `m debug` in parallel if a second contributor is available; otherwise queue 3c after 3b. `m profile` and `m bench` can interleave with `m fix` reviews without contention. - ---- - -## 3. Phase 3b — Generalize existing infrastructure - -### 3b-1 · `m fix` — auto-fix recipes + structural search/replace - -**Builds on:** `m fmt` rule engine ([`src/m_cli/fmt/`](../../src/m_cli/fmt/)), lint `fixer_id` linkage ([`src/m_cli/lint/__init__.py`](../../src/m_cli/lint/__init__.py) `fixer_for`). - -**Deliverables:** - -- New subcommand package `src/m_cli/fix/` with `cli.py` + `recipes.py` + `engine.py`. -- Named recipes that wrap a single fmt rule (`m fix trim-trailing-whitespace`). -- Structural search/replace driven by tree-sitter-m queries (`m fix --query 'SET $x=$x+1' --replace 'SET $x=$x+1 ; iterate'`). -- Every lint rule with a `fixer_id` becomes auto-fixable via `m fix --rule M-XINDX-013`. -- LSP `code_actions_for_uri` updated to expose all `fixer_id`-tagged rules (currently exposes 2, target ≥10). -- Idempotency tests: running `m fix` twice on the same source produces no second diff. - -**Exit criterion:** - -- All currently-registered `fixer_id` mappings are reachable via `m fix --rule `. -- `make check-fixer-linkage` (new gate) asserts every lint rule with a `fixer_id` resolves to a real fmt rule. -- LSP Quick Fix code-action count ≥10 on a fixture file that triggers all auto-fixable rules. -- `make lint-vista` over the configured corpus shows zero regressions in finding counts (auto-fixes change source, not finding semantics). - -**Risks:** - -- Tree-sitter structural-replace UX is unproven in M; start with named recipes only, defer the `--query` mode if it complicates the first ship. -- Recipe-on-recipe ordering matters once we ship more than one rule that touches the same node type. Document the conflict resolution rule upfront — likely "left-to-right in CLI invocation, deterministic-order if discovered from `fixer_id` set." - ---- - -### 3b-2 · `m profile` — flat profile + folded-stack output - -**Builds on:** YDB `view "TRACE"` driver from [`src/m_cli/coverage/runner.py`](../../src/m_cli/coverage/runner.py). - -**Deliverables:** - -- New subcommand package `src/m_cli/profile/` with `cli.py` + `runner.py` + `output.py`. -- Flat profile: line/label execution counts × time per call, sorted by self-time. -- Folded-stack format compatible with [`flamegraph.pl`](https://github.com/brendangregg/FlameGraph). -- Optional `--svg` flag that shells to `flamegraph.pl` if available; otherwise prints folded stacks for the user to pipe. -- `--baseline FILE` for comparison runs (delta self-time per label). -- Test fixture: profile a real `*TST.m` suite from m-stdlib; assert the slowest label surfaces in the top-N. - -**Exit criterion:** - -- `m profile FILE.m::tLabel` produces a flat profile with non-zero self-times. -- `m profile --format=folded` output renders correctly in `flamegraph.pl` (manually verified once; CI checks format only, not rendering). -- `make check` includes a smoke test that profiles a known-slow fixture and asserts the hot label is at the top of the flat profile. - -**Risks:** - -- `view "TRACE"` resolution granularity is per-line, not per-call. Document the limitation; don't promise call-graph reconstruction we can't deliver. -- Time measurement uses `$ZH` (or `$ZHOROLOG`); confirm sub-millisecond resolution on the target YDB version. Fall back to "count-only profiling" if the timer is too coarse for short tests. - ---- - -### 3b-3 · `m bench` — micro-benchmark runner - -**Builds on:** `m test` discovery ([`src/m_cli/test/discovery.py`](../../src/m_cli/test/discovery.py)) and runner ([`src/m_cli/test/runner.py`](../../src/m_cli/test/runner.py)). - -**Deliverables:** - -- New subcommand package `src/m_cli/bench/` with `cli.py` + `discovery.py` + `runner.py` + `output.py`. -- Discovery: `b` labels in `*BCH.m` files (parser-aware, same pattern as test discovery). -- Timing via `$ZH`; report ops/sec and ns/op. -- `--baseline FILE` for comparison mode (delta ops/sec per label, with significance threshold). -- Output formats: text (default), JSON. -- Document the benchmark-writing convention in [`docs/guide.md`](../guide.md) (analogous to the test section). - -**Exit criterion:** - -- `m bench` discovers and runs at least one bench file in a real M project (m-stdlib `STDFMT` or `STDREGEX` are obvious candidates). -- Comparison mode flags a deliberate 2× regression in a fixture and surfaces it in the output. -- Zero new dependencies beyond what `m test` already pulls in. - -**Risks:** - -- Warmup / JIT-like effects are absent in M, but YDB block-cache state isn't. Document that benches should be self-contained or include explicit setup; don't try to auto-warm. - ---- - -## 4. Phase 3c — `m debug` (DAP server + editor wiring) - -### 3c-1 · `m debug` — DAP server - -**Builds on:** YDB engine primitives (`ZBREAK`, `ZSTEP`, `ZSHOW`) — already used elsewhere in the codebase via [`src/m_cli/engine.py`](../../src/m_cli/engine.py); no new engine work required. - -**Deliverables:** - -- New subcommand package `src/m_cli/debug/` exposing a [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) server over stdio. -- Capabilities: breakpoints (line, conditional), step in/over/out, locals/watch (via `ZSHOW`), call stack, exception breakpoints. -- Driver wraps a `ydb -direct` subprocess; multiplexes DAP messages on stdin/stdout while controlling the YDB process via `ZBREAK` / `ZSTEP`. -- Engine targeting: YDB-first. The `--target-engine` flag accepts `iris` but exit-1's with "not supported yet" — the hook stays in for the IRIS portability track. -- Tests use a fake engine (same pattern as `m test`'s injectable `RunnerFn`) so unit tests don't need a live ydb. - -**Exit criterion:** - -- A DAP client (manually invoked, no editor) can set a breakpoint, run, hit it, inspect locals, and step through a routine. -- `m debug` survives a 10-minute soak with breakpoints set on a real m-stdlib test suite (no leaks, no orphaned ydb processes). - -**Risks:** - -- `ZBREAK` semantics across YDB versions: confirm the documented behavior on the pinned minimum YDB version, pin the test suite to that version in CI. -- Variable scoping: M's local variables don't have explicit scopes the way most DAP clients expect. The DAP `Scope` for "locals" maps to "all currently-defined locals via `ZSHOW \"V\"`"; document the mapping upfront. -- Multi-process: YDB can fork worker processes (`JOB`); we will not attempt multi-process debugging in v1. Document and exit-1 if encountered. - ---- - -### 3c-2 · VS Code DAP wiring - -**Builds on:** `m debug` server + existing [`tree-sitter-m-vscode`](https://github.com/m-dev-tools/tree-sitter-m-vscode) extension. - -**Deliverables:** - -- Register a debug adapter contribution in `tree-sitter-m-vscode/package.json`. -- Launch configuration template: `m debug ` or `m debug --test FILE.m::tLabel`. -- F5 launches a debug session; breakpoints set in the gutter round-trip to the DAP server. -- Documentation update in `tree-sitter-m-vscode/README.md`. - -**Exit criterion:** - -- Setting a gutter breakpoint, pressing F5 on a `*TST.m` file, hitting the breakpoint, inspecting locals, and stepping through a routine all work without manual `ydb` terminal interaction. - ---- - -## 5. Cross-cutting investments - -These thread through every phase and should be budgeted explicitly, not as line items. - -| Investment | When | Why | -|---|---|---| -| **VistA gate maintenance.** Re-run `make vista`, `make lint-vista`, smoke tests on every new subcommand that touches the parser or rule engines. | Every PR | The 39,330-routine corpus is the only honest stress test we have. Regressions caught here cost 1 hour; in prod they cost weeks. | -| **Library API stability.** Anything new that out-of-tree tools should consume goes into `m_cli.__all__` and is pinned by [`tests/test_library_api.py`](../../tests/test_library_api.py). | Phase 3b onward | LSP, pre-commit, future IDE integrations all consume the library API. Breaking it is a tax on every consumer. | -| **Performance budget.** Every new subcommand that walks the corpus declares a budget and verifies it. | Phase 3b onward | Lint already costs ~22 s on 16 cores. A `fix` / `profile` / `bench` run that scales linearly to corpus size needs the same `--jobs` discipline up front. | -| **`make check-manifest` drift gate.** Every new subcommand must register a `cli.py` so `make manifest` picks it up into `dist/commands.json`. | Phase 3b onward | The manifest is the tier-1 contract for downstream tooling discovery. | - ---- - -## 6. Decision points to revisit per phase - -| Decision | When | Default | Watch for | -|---|---|---|---| -| Continue extending Python codebase vs port hot paths to Rust | End of 3b | Stay in Python | Lint perf regressing past 60 s on VistA; test runner startup overhead becoming visible. | -| `m debug` on YDB only or design for engine-portable DAP | Start of 3c | YDB-first; abstraction comes later if Caché / IRIS users appear | Demand signal from non-YDB users; sponsor for Caché support. | -| Tree-sitter structural-replace UX | During 3b-1 | Ship named recipes only in v1; defer `--query` mode | Recipe coverage stays flat; users hand-rolling `sed` for cross-rule fixes. | -| Profile call-graph reconstruction | During 3b-2 | Flat profile + folded stacks only; no synthetic call graph | Repeated user requests for true call-graph view. | - ---- - -## 7. Suggested Gantt - -``` - W1 W2 W3 W4 W5 W6 W7 W8 W9 W10 W11 W12 … -m fix (3b-1) █████████████ -m profile (3b-2) █████████████ -m bench (3b-3) ████████ -m debug (3c-1) ░░░░░░░░░░░░░░░░░░░░░░░░░████████████████████ -VS Code DAP (3c-2) ████████ -VistA gate ◄────────── continuous ──────────────────────────► -``` - -- 3b lands inside ~8 weeks if sequential, ~5 if `m profile` and `m bench` overlap. -- 3c can start at W1 with a second contributor; otherwise picks up at W8. Either way, lands inside one quarter. -- The "two productivity-defining phases (3b + 3c) ship inside one quarter" target from the survey is achievable; the constraint is contributor-count, not technical scope. - ---- - -## 8. Exit criterion for the phase as a whole - -Phase 3 is complete when: - -1. `m fix`, `m profile`, `m bench`, `m debug` are all documented in [`guide.md`](../guide.md), shipped with tests, and reachable via `m --help`. -2. `make check-manifest` passes — every subcommand is in `dist/commands.json`. -3. LSP Quick Fix coverage is ≥10 rules. -4. A flamegraph generated by `m profile` is checked in as a worked example under [`examples/`](../../examples/). -5. A debug session in VS Code (gutter breakpoint → hit → step → inspect) is documented with screenshots in `tree-sitter-m-vscode/README.md`. -6. The `m-cli` capability surface in `dist/commands.json` matches §6 of [`language-cli-survey.md`](language-cli-survey.md) rows 1–12 (the Tier-1 essentials + Phase 3 deliverables). - -When all six are true, the next planning doc is Phase 4 (`m pkg` / `m audit` / `m publish`) — explicitly a year-2+ commitment per the survey, contingent on ecosystem demand signal. From f21d77e074f109f6d3c3756b693dbb82dbe8be90 Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Mon, 11 May 2026 10:14:57 -0400 Subject: [PATCH 3/3] 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 | 41 +++++++++++++++++++++ docs/evolution.md | 7 ++++ docs/guide.md | 7 ++++ docs/m-linting-user-guide.md | 7 ++++ docs/plans/iris-ydb-portability.md | 7 ++++ docs/plans/language-cli-survey.md | 7 ++++ docs/plans/linter-profiles-guide.md | 7 ++++ docs/plans/m-cli-history-and-evolution.md | 4 ++ docs/plans/m-corpus-catalog.md | 4 ++ docs/plans/m-env-implementation-plan.md | 7 ++++ docs/plans/m-environment-tool.md | 7 ++++ docs/plans/m-linter-status-2026-04-30.md | 7 ++++ docs/plans/m-linting-implementation-plan.md | 7 ++++ docs/plans/m-linting-survey.md | 7 ++++ docs/plugin-development.md | 7 ++++ docs/pre-commit.md | 7 ++++ docs/vista-meta-bootstrap.md | 7 ++++ docs/worked-example-accsum.md | 7 ++++ 18 files changed, 154 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..e601dd3 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,41 @@ +--- +created: 2026-05-11 +last_modified: 2026-05-11 +revisions: 0 +doc_type: [REFERENCE] +--- + +# m-cli — 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 + +- **`evolution.md`** — `[HISTORY · BUILD-LOG · history · implementation]` Chronological narrative of how m-cli was built tier by tier, milestone by milestone, with performance journey and deferred items. +- **`guide.md`** — `[GUIDE · REFERENCE · function · architecture]` Comprehensive user-facing reference covering every subcommand, configuration, profiles, and the four-tier framework m-cli implements. +- **`m-linting-user-guide.md`** — `[GUIDE · function]` How-to guide for `m lint`: profiles, severity, thresholds, output formats, inline disables, and CLI flags. +- **`plugin-development.md`** — `[GUIDE · SPEC · function · architecture]` Contract and walkthrough for registering out-of-tree subcommands via the `m_cli.plugins` entry-point group. +- **`pre-commit.md`** — `[GUIDE · INTEGRATION · function]` Downstream pre-commit integration recipe for `m-fmt-check`, `m-fmt`, and `m-lint` hooks via `language: system`. +- **`vista-meta-bootstrap.md`** — `[HISTORY · EXPLAINER · history · design]` Records how the vista-meta YottaDB container bootstrapped m-cli development and why m-cli is now engine-independent. +- **`worked-example-accsum.md`** — `[WORKED-EXAMPLE · TUTORIAL · function]` End-to-end TDD walkthrough building an `accsum` access-log summariser to demonstrate every `m` subcommand in context. + +## `plans/` — design proposals, surveys, status reports, and implementation plans tracking m-cli's roadmap + +- **`plans/iris-ydb-portability.md`** — `[PLAN · RESEARCH · planning · architecture]` Function-by-function IRIS vs YottaDB CLI comparison with an engine-adapter refactor plan for cross-engine dispatch. +- **`plans/language-cli-survey.md`** — `[SURVEY · GAP-ANALYSIS · planning · design]` Survey of Rust/Go/Python/JS/Java CLI toolchains scored on productivity and quality, closing with a rank-ordered m-cli gap analysis. +- **`plans/linter-profiles-guide.md`** — `[DESIGN · PROPOSAL · design · planning]` Proposes splitting the `sac` profile into four mechanism-grounded profiles (KIDS-build / vista / safety / sac-style) by gatekeeper. +- **`plans/m-cli-history-and-evolution.md`** — `[HISTORY · EXPLAINER · history · architecture]` Chronicles the six-week sprint birthing m-tools, vista-meta, m-standard, tree-sitter-m, m-cli, and m-stdlib as cooperating siblings. +- **`plans/m-corpus-catalog.md`** — `[REFERENCE · RESEARCH · planning]` Catalog of non-VistA open-source M corpora vetted as candidates for the M-MOD-NN regression gate. +- **`plans/m-env-implementation-plan.md`** — `[PLAN · planning · implementation]` Self-contained implementation guide for an `m-env` POC proving containerized YottaDB/IRIS environments before folding into m-cli. +- **`plans/m-environment-tool.md`** — `[PROPOSAL · DESIGN · design · planning]` Design proposal for `m init` / `m env` / `m doctor` commands managing Dev Container-based M execution environments. +- **`plans/m-linter-status-2026-04-30.md`** — `[STATUS · POSTMORTEM · implementation]` Comprehensive audit of every shipped lint rule against a 4,215-routine non-VA corpus with prioritized fixes and landed deltas. +- **`plans/m-linting-implementation-plan.md`** — `[PLAN · BUILD-LOG · planning · implementation]` Phase-by-phase tracker for the M-MOD-NN modernization track, vista split, thresholds, engine-aware rules, and data-flow research. +- **`plans/m-linting-survey.md`** — `[SURVEY · GAP-ANALYSIS · design · planning]` Audits the 42 XINDEX/SAC rules for modern relevance and proposes a rank-ordered greenfield rule set drawn from first principles. diff --git a/docs/evolution.md b/docs/evolution.md index c9fbe86..d40480d 100644 --- a/docs/evolution.md +++ b/docs/evolution.md @@ -1,3 +1,10 @@ +--- +created: 2026-05-10 +last_modified: 2026-05-10 +revisions: 1 +doc_type: [HISTORY, BUILD-LOG] +--- + # m-cli — evolution How m-cli was built, in chronological order. This is **archaeology** — read the diff --git a/docs/guide.md b/docs/guide.md index 5bdc707..2cba499 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -1,3 +1,10 @@ +--- +created: 2026-04-27 +last_modified: 2026-05-10 +revisions: 12 +doc_type: [GUIDE, REFERENCE] +--- + # m-cli — Comprehensive Guide **Document type:** Reference + roadmap diff --git a/docs/m-linting-user-guide.md b/docs/m-linting-user-guide.md index c18fe3c..2ba990f 100644 --- a/docs/m-linting-user-guide.md +++ b/docs/m-linting-user-guide.md @@ -1,3 +1,10 @@ +--- +created: 2026-04-30 +last_modified: 2026-05-10 +revisions: 2 +doc_type: [GUIDE] +--- + # m lint — User Guide The `m lint` command checks `.m` source for engine-neutral logic, style, diff --git a/docs/plans/iris-ydb-portability.md b/docs/plans/iris-ydb-portability.md index e852814..28b96fa 100644 --- a/docs/plans/iris-ydb-portability.md +++ b/docs/plans/iris-ydb-portability.md @@ -1,3 +1,10 @@ +--- +created: 2026-04-30 +last_modified: 2026-05-10 +revisions: 2 +doc_type: [PLAN, RESEARCH] +--- + # IRIS ↔ YottaDB CLI Comparison — Portability Plan for `m-cli` > **Purpose.** A function-by-function comparison of the command-line surface diff --git a/docs/plans/language-cli-survey.md b/docs/plans/language-cli-survey.md index afadc27..061ff00 100644 --- a/docs/plans/language-cli-survey.md +++ b/docs/plans/language-cli-survey.md @@ -1,3 +1,10 @@ +--- +created: 2026-04-30 +last_modified: 2026-05-10 +revisions: 4 +doc_type: [SURVEY, GAP-ANALYSIS] +--- + # Language CLI Survey — Tooling Landscape and `m-cli` Gap Analysis > **Purpose.** A comprehensive survey of the CLI toolchains shipped by five of the diff --git a/docs/plans/linter-profiles-guide.md b/docs/plans/linter-profiles-guide.md index 7fe7bd5..5e719e9 100644 --- a/docs/plans/linter-profiles-guide.md +++ b/docs/plans/linter-profiles-guide.md @@ -1,3 +1,10 @@ +--- +created: 2026-05-06 +last_modified: 2026-05-10 +revisions: 2 +doc_type: [DESIGN, PROPOSAL] +--- + # Linter Profiles Guide **Status:** design / review artifact. **Drafted 2026-05-06**, rewritten same day after the realization that the right organizing axis for SAC rules is *which gatekeeper enforces them*, not *which era they came from*. This doc proposes splitting today's `sac` profile into four mechanism-grounded profiles and reorganizing tags accordingly. diff --git a/docs/plans/m-cli-history-and-evolution.md b/docs/plans/m-cli-history-and-evolution.md index b5093e9..a9ae5e8 100644 --- a/docs/plans/m-cli-history-and-evolution.md +++ b/docs/plans/m-cli-history-and-evolution.md @@ -3,6 +3,10 @@ title: m-cli — history and evolution status: live (2026-05-06) audience: anyone trying to understand how m-cli came to exist, what its precursors were, and where it sits among the M-language tooling sibling projects companion: ../README.md (current capability surface) +created: 2026-05-06 +last_modified: 2026-05-10 +revisions: 3 +doc_type: [HISTORY, EXPLAINER] --- # m-cli — history and evolution diff --git a/docs/plans/m-corpus-catalog.md b/docs/plans/m-corpus-catalog.md index 34a65c0..b536507 100644 --- a/docs/plans/m-corpus-catalog.md +++ b/docs/plans/m-corpus-catalog.md @@ -4,6 +4,10 @@ purpose: Candidate corpora for m-cli's modern-rule-set regression gate inventory_date: 2026-04-29 inventoried_by: research pass for m-cli M-MOD-NN rule design scope: Public, post-2010-active, NOT VistA-derived, substantial enough to surface real lint findings +created: 2026-04-30 +last_modified: 2026-05-10 +revisions: 2 +doc_type: [REFERENCE, RESEARCH] --- # Catalog: open-source M / MUMPS / ObjectScript corpora (non-VistA) diff --git a/docs/plans/m-env-implementation-plan.md b/docs/plans/m-env-implementation-plan.md index d4b9a59..f2ccd10 100644 --- a/docs/plans/m-env-implementation-plan.md +++ b/docs/plans/m-env-implementation-plan.md @@ -1,3 +1,10 @@ +--- +created: 2026-05-07 +last_modified: 2026-05-10 +revisions: 4 +doc_type: [PLAN] +--- + # `m-env` Implementation Plan **Document type:** self-contained implementation guide diff --git a/docs/plans/m-environment-tool.md b/docs/plans/m-environment-tool.md index b1bce61..5a9032f 100644 --- a/docs/plans/m-environment-tool.md +++ b/docs/plans/m-environment-tool.md @@ -1,3 +1,10 @@ +--- +created: 2026-05-07 +last_modified: 2026-05-10 +revisions: 4 +doc_type: [PROPOSAL, DESIGN] +--- + # `m environment` / `m doctor` / `m init` — Engine Environment Strategy **Document type:** design proposal diff --git a/docs/plans/m-linter-status-2026-04-30.md b/docs/plans/m-linter-status-2026-04-30.md index 4ab78b8..0d3dc27 100644 --- a/docs/plans/m-linter-status-2026-04-30.md +++ b/docs/plans/m-linter-status-2026-04-30.md @@ -1,3 +1,10 @@ +--- +created: 2026-04-30 +last_modified: 2026-05-10 +revisions: 4 +doc_type: [STATUS, POSTMORTEM] +--- + # `m lint` — Status & Audit Report **Date:** 2026-04-30 *(filename was requested as `m-linter-status-2024-04-40.md`; date corrected — 2024 was a typo and `04-40` is not a valid date)* diff --git a/docs/plans/m-linting-implementation-plan.md b/docs/plans/m-linting-implementation-plan.md index 15e7849..1b5aed8 100644 --- a/docs/plans/m-linting-implementation-plan.md +++ b/docs/plans/m-linting-implementation-plan.md @@ -1,3 +1,10 @@ +--- +created: 2026-04-30 +last_modified: 2026-05-10 +revisions: 4 +doc_type: [PLAN, BUILD-LOG] +--- + # M Linting Implementation Plan **Status:** working plan, derived from [`docs/m-linting-survey.md`](m-linting-survey.md) §7 (greenfield rule list) and §8 (roadmap), informed by [`docs/m-corpus-catalog.md`](m-corpus-catalog.md) for the regression gate. diff --git a/docs/plans/m-linting-survey.md b/docs/plans/m-linting-survey.md index 55fe3ac..c1b8be0 100644 --- a/docs/plans/m-linting-survey.md +++ b/docs/plans/m-linting-survey.md @@ -1,3 +1,10 @@ +--- +created: 2026-04-30 +last_modified: 2026-05-10 +revisions: 2 +doc_type: [SURVEY, GAP-ANALYSIS] +--- + # M Linting Survey & Greenfield Recommendations **Status:** the four open questions in the original draft (§9) are now diff --git a/docs/plugin-development.md b/docs/plugin-development.md index f53666b..c64b5a8 100644 --- a/docs/plugin-development.md +++ b/docs/plugin-development.md @@ -1,3 +1,10 @@ +--- +created: 2026-05-09 +last_modified: 2026-05-09 +revisions: 1 +doc_type: [GUIDE, SPEC] +--- + # Plugin development m-cli's built-in subcommands (`m fmt`, `m lint`, `m test`, `m doc`, …) diff --git a/docs/pre-commit.md b/docs/pre-commit.md index 28e6e3d..e0e2651 100644 --- a/docs/pre-commit.md +++ b/docs/pre-commit.md @@ -1,3 +1,10 @@ +--- +created: 2026-04-27 +last_modified: 2026-05-07 +revisions: 2 +doc_type: [GUIDE, INTEGRATION] +--- + # Pre-commit integration `m-cli` ships a [pre-commit](https://pre-commit.com) hook scaffold so diff --git a/docs/vista-meta-bootstrap.md b/docs/vista-meta-bootstrap.md index fff3256..5bd8169 100644 --- a/docs/vista-meta-bootstrap.md +++ b/docs/vista-meta-bootstrap.md @@ -1,3 +1,10 @@ +--- +created: 2026-05-10 +last_modified: 2026-05-10 +revisions: 1 +doc_type: [HISTORY, EXPLAINER] +--- + # vista-meta bootstrap — and why m-cli is independent of it now This document records how the `vista-meta` YottaDB container was used during diff --git a/docs/worked-example-accsum.md b/docs/worked-example-accsum.md index d29b2ff..e564673 100644 --- a/docs/worked-example-accsum.md +++ b/docs/worked-example-accsum.md @@ -1,3 +1,10 @@ +--- +created: 2026-05-09 +last_modified: 2026-05-09 +revisions: 2 +doc_type: [WORKED-EXAMPLE, TUTORIAL] +--- + # Worked example — building `accsum` with `m`, TDD, and m-stdlib **Document type:** end-to-end walkthrough