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 e77a4f4..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 @@ -6,6 +13,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/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