m-tools — historical root of the m-dev-tools ecosystem

Status: archived. This repository is the seed from which the m-dev-tools organization grew. Its working code has graduated into the seven sibling repos listed below; what remains here is the historical record — the original gap analysis, Tier 1–4 strategy, and command-map specifications that shaped the rest of the ecosystem.

If you're looking for working tools, jump straight to m-cli (the CLI) and m-stdlib (the runtime standard library).

---

What m-dev-tools is today

A suite of engine-neutral developer tools for the M (MUMPS) programming language, built around a CI/CD-friendly, test-driven-development workflow. The ecosystem is anchored on two complementary projects — m-stdlib (the runtime standard library) and m-cli (the m <subcommand> toolchain) — supported by a real parser, a citable language reference, a containerised test engine, and editor integrations. Together they form an end-to-end TDD stack that works identically for InterSystems IRIS and YottaDB developers maintaining modern (non-VistA) M code.

Repository	Role
m-cli	The canonical m <subcommand> toolchain — m fmt, m lint, m test, m coverage, m watch, m lsp, m doc, m doctor, m new, m run, m build, m ci init. The successor to this repository's bin/y* scripts.
m-cli-extras	Out-of-tree subcommands for m-cli (e.g. m corpus-stats), registered via the m_cli.plugins entry-point group.
m-stdlib	Pure-M (and selectively $ZF-bound) runtime standard library — assertions, fixtures, mocks, JSON, regex, datetime, CSV, argparse, logging, UUID, base64, HTTP, crypto, compression, and more. YottaDB-first; IRIS-portable where reasonable.
m-standard	Citable, machine-readable M-language reference reconciling the ANSI standard, YottaDB docs, IRIS docs, and the VA SAC / XINDEX rule set. The vocabulary every Tier 1 tool consumes.
tree-sitter-m	Tree-sitter grammar for M. 99.06% clean on the 39,330-routine VistA corpus. The AST every source-level tool needs.
m-test-engine	Minimal YottaDB Docker container for m-cli and m-stdlib testing. Replaces the vista-meta SSH-staging path that lived in this repo's Makefile.
tree-sitter-m-vscode	VS Code extension — syntax highlighting via tree-sitter-m, plus live diagnostics / formatting / Quick Fix code actions when m-cli is installed (it spawns m lsp).
m-stdlib-vscode	VS Code extension — manifest-driven hover docs, goto-definition, and completion for the m-stdlib public surface.
m-modern-corpus	Snapshot collection of modern non-VistA M source (EWD, mgsql, M-Web-Server, YDBOcto auxiliary, YDBTest). The validation corpus for the parser and the M-MOD-NN lint rules.

---

How the ecosystem evolved out of this repo

m-tools began as a single hub project: a bin/ of 25 y* shell scripts (ycheck, ytest, ycover, ydiff, …) that wrapped YottaDB's command-line surface, plus a routines/ tree of tutorial M code, plus the strategic planning documents that drove everything else. As the strategy materialised, each capability moved into a dedicated repository:

1. Strategy was codified first. The four planning documents under docs/ framed the problem: M had a real ISO standard and two production engines (IRIS, YottaDB), but no formatter, no linter, no test runner, no LSP, no package ecosystem — none of the "developer inner-loop" infrastructure mainstream languages take for granted. The gap analysis ranked the missing capabilities; m-tool-gap-analysis.md §8 fixed the Tier 1 set; m-tooling-tier1.md produced the focused execution plan; and implementation.md defined the canonical m <subcommand> command map.

2. The language reference came next. Building tooling against an under-specified language doesn't work; every linter and formatter would re-invent its own keyword list and re-litigate which features were portable. The strategy called for a single citable reference, and that became m-standard — the ANSI standard, YottaDB docs, IRIS docs, and VA SAC reconciled into one machine-readable artefact.

3. The parser was generated mechanically from the reference. With m-standard providing the grammar surface as JSON, tree-sitter-m could be built without re-deriving the language by hand. It shipped clean enough on VistA (99.06%) to back every downstream tool.

4. The CLI replaced the y* scripts. m-cli implemented the canonical m <subcommand> surface from docs/implementation.md: m fmt and m lint (engine-neutral, source-level), m test and m coverage (YottaDB-targeted, runtime-bound), m watch (the TDD inner loop), and the m lsp server that editors plug into. The Tier 1 set from docs/m-tooling-tier1.md is fully shipped; Tier 2 quality gates and project-scaffolding subcommands layered on top.

5. The runtime standard library landed once the toolchain supported it. With m fmt, m lint, and m test in place, it became feasible to ship a versioned, conformance-tested, discoverable library — m-stdlib — covering the gaps every M shop has historically filled with private ^XB* / ^DI* / ^%Z* routines: assertions, JSON, regex, datetime, HTTP, crypto, and the rest. m-stdlib has architectural priority over m-cli: when both projects need a utility, it lands in m-stdlib first and m-cli imports.

6. The test engine was extracted. Originally m-tools' Makefile staged routines into the heavyweight vista-meta container over SSH. For non-VistA M development that was overkill, so the minimal YottaDB container moved into m-test-engine — docker exec replaces SSH staging, and consumer projects bind-mount their source at /work.

7. Editor integration shipped last, on top of everything else. tree-sitter-m-vscode provides syntax highlighting via the WASM-compiled grammar and spawns m lsp for live tooling. Its companion m-stdlib-vscode reads the m-stdlib manifest for hover, goto-def, and completion on STD* symbols.

8. A modern validation corpus was assembled. m-modern-corpus collects modern (post-2010, non-VistA) M source from active open-source projects, calibrating the M-MOD-NN rule track against contemporary idioms rather than legacy VA conventions.

---

What's preserved here

The bin/y* scripts, the routines/ tutorial code, the vista-meta-bound Makefile, and the host-YDB CI workflow have all been superseded and removed. What remains is the planning record:

• docs/gap-analysis-and-remediation-strategy.md — the original cross-engine gap analysis, the four-tier prioritisation, the technology-optimal remediation addenda, and the language-toolchain reference appendices.
• docs/m-tool-gap-analysis.md — the §8 rank-ordered developer-impact analysis that fixed the Tier 1 set.
• docs/m-tooling-tier1.md — the focused Tier 1 execution plan; still cited from the m-cli README.
• docs/implementation.md — the original m help command map and as-built specs that m-cli realises.

These are kept verbatim so the ecosystem's design rationale stays auditable: every choice the sibling repos make ultimately traces back to a paragraph in one of these four documents.

---

License

The historical documents under docs/ are released under the same terms as the rest of the m-dev-tools family — AGPL-3.0 — to match m-cli, m-stdlib, m-standard, tree-sitter-m, and m-test-engine. The two VS Code extensions are independently MIT to align with the broader extension ecosystem.