md-verified 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kristian Dupont
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,493 @@
+# md-verified
+
+Executable specifications from Markdown that nobody has to learn to read.
+
+There is no Given/When/Then, no feature-file dialect, no custom renderer. A
+specification is an ordinary `.md` file with ordinary tables, lists and Mermaid
+diagrams. It looks native on GitHub, in VS Code, and in any Markdown viewer you
+already use. A blockquote above each asset registers it with the test runner:
+
+```markdown
+> 🛠️ **Verified Data:** `orderTotals`
+> **Schema:** `[itemsTotal: Currency, shipping: Currency, tax: Percentage, total: Currency]`
+
+| Items Total | Shipping | Tax Rate | Total Owed |
+| ----------- | -------- | -------- | ---------- |
+| $10.00      | $5.00    | 10%      | $16.00     |
+```
+
+The blockquote renders as a callout. The table renders as a table. Nothing in
+the document is inert markup that only a tool understands.
+
+### Install
+
+```
+bun add -d md-verified          # or: npm install -D md-verified
+bunx md-verified 'docs/**/*.md' # or: npx md-verified 'docs/**/*.md'
+```
+
+Runs on **Bun** and **Node 24+**. The package itself uses only `node:`
+builtins, so there is one code path rather than a compatibility layer.
+
+Or from a clone:
+
+```
+bun install
+bun run check.ts examples/spec.md
+bun test
+```
+
+The point is documents that stay *true*, which is not the same as documents
+that are fully verified — see [writing documents that stay
+true](./docs/writing.md) for what earns an anchor and what should stay prose.
+There is an agent skill at
+[`.claude/skills/verified-docs`](./.claude/skills/verified-docs/SKILL.md).
+
+## How binding works
+
+An anchor is a blockquote whose first line matches:
+
+```
+> [glyph] **Verified <Label>:** `<id>`
+```
+
+The runner then takes the **immediately following block node** and binds it.
+The label says what you expect; the node says what is actually there, and a
+disagreement is reported rather than guessed at:
+
+`Data` and `Table` bind to a GFM table, `Flow` and `Diagram` to a
+` ```mermaid ` block, `Rules` and `Checklist` to a list. The full set of labels
+is listed — and verified against the source — in
+[docs/anchor-reference.md](./docs/anchor-reference.md).
+
+Lookahead skips only the HTML comments this tool writes itself, so a document
+that has already been annotated with failures still binds correctly next run.
+Anything else between the anchor and the asset — a stray paragraph — is an
+error, not something to search past.
+
+Blockquotes that are not anchors are left alone, so your existing callouts keep
+working.
+
+### Schemas
+
+The optional `**Schema:**` line names and types the columns positionally.
+Handlers then receive real values instead of strings:
+
+```markdown
+> 🛠️ **Verified Data:** `orderTotals`
+> **Schema:** `[itemsTotal: Currency, shipping: Currency, tax: Percentage, total: Currency]`
+```
+
+`$10.00` arrives as `10`, `8.5%` as `0.085`. Each value is reachable by column
+header *and* by schema field name, with the author's original text preserved on
+`row.$raw`:
+
+```ts
+row['Items Total']  // 10
+row.itemsTotal      // 10
+row.$raw['Items Total'] // '$10.00'
+```
+
+Built-in types cover currency, percentages, numbers, booleans, dates, JSON and
+comma-separated lists; the complete table, with a worked example per type, is in
+[docs/anchor-reference.md](./docs/anchor-reference.md). A trailing `?`
+(`discount?: Currency`) lets a blank cell through as `null`. Register your own
+with `verify.type()`.
+
+Without a `Schema:` line, cells arrive as the raw text — which is what you want
+when the document's exact formatting is part of the contract.
+
+## Runtimes
+
+The tool imports your `.verify.ts` glue at runtime, so what matters is how each
+runtime handles TypeScript.
+
+| | Glue TypeScript |
+| --- | --- |
+| Bun | Fully transformed. Everything works. |
+| Node 24+ | Type **stripping** only — see below. |
+
+Node strips types rather than transforming them, so a few TypeScript features
+do not survive **in glue, or in anything glue imports as `.ts`**:
+
+```
+enum, namespace, parameter properties (constructor(readonly x: string)), decorators
+```
+
+Types, interfaces, generics, `as const`, `satisfies` and type-only exports are
+all fine. In practice glue is plain functions, so this rarely bites — the case
+that does is glue importing an `enum` from your application code.
+
+The fix is one line:
+
+```bash
+NODE_OPTIONS=--experimental-transform-types npx md-verified docs/thing.md
+```
+
+The published bin uses a `node` shebang so `npx` works out of the box. To run it
+under Bun instead — which has none of the above limits — use `bunx --bun
+md-verified` or `bun node_modules/md-verified/dist/check.js`.
+
+Deno is untested. It should work in principle, via `node:` compatibility and an
+`npm:` specifier, but nothing here verifies that.
+
+## Project layout
+
+Put documents wherever you like — beside the code they describe, or in a `docs/`
+tree. The tool does not care. Your `tsconfig.json` does, and it fails in a
+different way for each.
+
+**The rule: treat `.verify.ts` exactly like `.test.ts`.** It is TypeScript that
+should be *checked* but not *shipped*, which is a problem your project has
+already solved once.
+
+Concretely, two configs — a wide one for checking and the editor, a narrow one
+for building:
+
+```jsonc
+// tsconfig.json — what gets typechecked
+{ "compilerOptions": { "noEmit": true }, "include": ["src", "docs"] }
+
+// tsconfig.build.json — what gets compiled
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "noEmit": false, "outDir": "dist", "rootDir": "src" },
+  "include": ["src"],
+  "exclude": ["**/*.verify.ts", "**/*.test.ts"]
+}
+```
+
+Without that split you hit one of these:
+
+| Layout | What goes wrong |
+| --- | --- |
+| `docs/` beside `src/`, `"include": ["src"]` | Glue is **never typechecked**. A real type error in a handler is invisible — Bun strips types, so the document still passes. |
+| `docs/` added to `include`, with `"rootDir": "src"` | `TS6059: File 'docs/x.verify.ts' is not under 'rootDir'`. |
+| Co-located `src/**/*.verify.ts` | Typechecked correctly, but the glue **compiles into your production build** (`dist/billing/billing.verify.js`). |
+
+The first is the dangerous one, because nothing tells you.
+
+Glue can import application code however the rest of your project does —
+`tsconfig` path aliases work, since Bun reads them.
+
+## Glue code
+
+```ts
+import { verify, assert } from './src/index.ts';
+
+// Once per data row.
+verify.table('orderTotals', (row) => {
+  const actual = calculateTotal(row.itemsTotal, row.shipping, row.tax);
+  assert(actual === row.total, `expected ${row.total}, got ${actual}`);
+});
+
+// Once per edge: { from, to, label, style, directed }.
+verify.mermaid.edges('checkoutFlow', async (edge) => {
+  assert(await checkNavigation(edge.from, edge.to),
+    `illegal transition: ${edge.from} -> ${edge.to}`);
+});
+
+// Once per list item, nested items included.
+verify.list('settlementRules', (item) => {
+  assert(item.checked === settlesImmediately(item.text), 'drifted');
+});
+```
+
+Return normally to pass, throw to fail. Any assertion library works, including
+none.
+
+### Assertions
+
+A failure message here is not a test log — it is **written into the Markdown
+file** and read as documentation. Terminal-shaped output reads badly there:
+
+```
+<!-- ERROR: row 1: expect(received).toBe(expected)
+     Expected: 15
+     Received: 16 -->
+
+<!-- ERROR: row 1: total: expected 15, got 16 -->
+```
+
+So the built-ins stay few, and each produces one self-contained line phrased in
+terms of the claim:
+
+| | |
+| --- | --- |
+| `assert(cond, message)` | the escape hatch — use it whenever you can say it better |
+| `equals(actual, expected, what?)` | `total: expected 16, got 15` |
+| `oneOf(value, allowed, what?)` | `status: "archived" is not one of active, paused` |
+| `covers(documented, actual, opts?)` | see [Completeness](#completeness) |
+
+Third-party libraries keep working — a handler fails by throwing and that is
+not going away. Multi-line messages keep their structure in the document rather
+than being flattened onto one line.
+
+| Registration | Handler receives |
+| --- | --- |
+| `verify.table(id, fn)` | one `TableRow` per data row |
+| `verify.table.all(id, fn)` | the whole `ParsedTable` |
+| `verify.mermaid(id, fn)` | the whole `MermaidGraph` |
+| `verify.mermaid.edges(id, fn)` | one `MermaidEdge` per edge |
+| `verify.list(id, fn)` | one `ListItem` per item |
+| `verify.list.all(id, fn)` | the whole `ParsedList` |
+| `verify.type(name, fn)` | — registers a `Schema:` value type |
+
+`MermaidGraph` carries `nodes`, `edges` and `subgraphs`, plus `node(id)`,
+`from(id)`, `to(id)`, `hasEdge(a, b)`, `hasPath(a, b)`, `roots()` and
+`leaves()`.
+
+One anchor may carry both an `each` and an `all` handler — they answer
+different questions about the same asset. Registering the same mode twice is
+still an error, so typos are still caught.
+
+Glue is located by, in order: `--glue`, a `<!-- verify: ./x.verify.ts -->` hint
+in the document, then `<name>.verify.ts` beside the Markdown file.
+
+## Completeness
+
+Per-element handlers only ever check elements that exist. If the code grows a
+fifth payment method and nobody adds a row, every row still passes and the
+document is quietly wrong. `covers()` is the assertion that catches it:
+
+```ts
+verify.mermaid('checkoutFlow', (graph) => {
+  covers(graph.edges.map((e) => `${e.from} -> ${e.to}`), allowedTransitions(), {
+    noun: 'transition',
+    missing: (t) => `${t} is allowed by checkNavigation but is not drawn`,
+    extra: false, // the per-edge handler already owns this direction
+  });
+});
+```
+
+It throws once, listing every gap, so a single run tells you the whole story.
+Options: `missing` / `extra` take a message function or `false` to allow that
+direction, `duplicates` (default on) flags a key the document lists twice, and
+`noun` names the thing in default messages.
+
+This is the check worth reaching for first. A *missing* element is
+machine-identifiable in a way a wrong one is not — the runner knows exactly
+which row should exist, which is what makes the annotation actionable.
+
+## Reference checking
+
+Anchors verify the assets. A second pass verifies the prose around them: links
+to files that have moved, in-document anchors that no longer resolve, and —
+where you ask for it with a fragment — symbols that no longer exist.
+
+```markdown
+Computed by [`calculateTotal`](./checkout.ts#calculateTotal).
+```
+
+That renders as an ordinary link, and it carries everything needed to check it:
+
+```
+examples/broken.md
+  ✖ 12:24 broken symbol: ./checkout.ts#calculateTotals (no export named
+          `calculateTotals`) (did you mean `calculateTotal`?)
+  ✖ 13:19 broken link: ./appendix.md (no such file)
+```
+
+Checked automatically: every link and image path, `#heading` anchors within the
+document and into other Markdown files, and link definitions. Nothing implicit
+is ever checked — bare inline code is not treated as a symbol, because
+`$10.00`, `--write` and `[itemsTotal: Currency]` are all inline code in a
+perfectly healthy spec. A document opts in by linking.
+
+Only files you fragment-link are imported, and only to read their export names.
+`--no-symbols` keeps the link checks but imports nothing; `--no-links` skips the
+pass entirely.
+
+## Reviews: the parts that cannot be executed
+
+Most of a good document is prose — rationale, context, the reason a rule exists
+at all. That is usually the part worth reading, and it is the part that rots
+silently.
+
+A review does not try to verify prose. It records which code a section
+describes, and a digest of that code at the moment someone last read the two
+together:
+
+```markdown
+> 👁️ **Reviewed:** `settlement`
+> **Covers:** `../src/checkout.ts#paymentMethod`
+> **Digest:** `1:3aaced165261`
+```
+
+When `paymentMethod` changes, the digest stops matching and the section is
+flagged for a human to re-read. That is an attestation, not a proof — the
+weaker claim, deliberately, because the alternative is either checking nothing
+or pretending prose can be executed.
+
+`--stamp` records the digest. It is **separate from `--write` on purpose**: a
+stamp applied as a side effect of a normal run would attest to nothing.
+
+The `1:` prefix is the digest format version. It exists so that a future change
+to the algorithm can be reported as "re-stamp needed" rather than as "the code
+changed", which would be a lie and would train people to stamp blindly.
+
+Digests ignore line endings, so a mixed Windows/Unix team does not see
+everything go stale.
+
+Point `Covers:` at a **symbol** rather than a whole file. A file-level target is
+invalidated by every unrelated edit in that file, and a review that cries wolf
+gets stamped without being read. Symbol targets ignore edits elsewhere in the
+file, and ignore changes to leading comments.
+
+### Which documents describe this code?
+
+The mapping from prose to code already lives in the documents, so there is no
+need for a marker in the source:
+
+```
+$ bun run check.ts docs/*.md --covering src/parser.ts
+Reviews covering src/parser.ts:
+  docs/anchor-reference.md:14  binding  ../src/parser.ts#parseMarkdown
+```
+
+Run it on the files a change touched. Anything listed describes code that just
+moved.
+
+## Bi-directional state
+
+`--write` folds the result of a run back into the document. The glyph changes,
+and each failure is recorded as an HTML comment directly above the asset that
+failed:
+
+```markdown
+> ❌ **Verified Flow:** `checkoutFlow` (Failed: 1 of 4)
+
+<!-- ERROR: Cart -> Payment: illegal transition: Cart -> Payment -->
+
+```mermaid
+graph TD
+    Cart[Cart Page] --> Shipping[Shipping Info]
+    Cart --> Payment[Payment Info]
+```
+```
+
+Comments are invisible in every renderer, so the page still reads as prose. For
+an agent, the failure text sits at exactly the place that has to change — no
+separate log to correlate against the document.
+
+Three properties this relies on, all covered by the test suite:
+
+- **Surgical.** Rewriting splices the original source; it never re-serialises
+  the AST. Prose, table alignment and diagram indentation survive byte for byte.
+- **Idempotent.** Annotating an annotated document is a no-op. (This is why the
+  comments carry case names rather than line numbers — writing the comments
+  shifts the lines they would otherwise cite. Exact lines are in `--json`.)
+- **Reversible.** A later green run clears the marks; `--reset` returns the file
+  to its unrun state exactly.
+
+## CLI
+
+```
+md-verified <file.md|glob> [...] [options]
+
+  --glue <path>   Glue module to load
+  --write, -w     Fold results back into the file
+  --report        Print the annotated Markdown to stdout instead
+  --reset         Return anchors to their unrun state
+  --json          Machine-readable results, for agents and CI
+  --stamp         Record reviews as read (never implied by --write)
+  --covering <p>  List the reviews that cover a source file
+  --no-links      Skip link, anchor and symbol checking
+  --no-symbols    Skip symbol checking
+  --no-reviews    Skip review staleness checking
+  --only <id>     Run one anchor (repeatable)
+  --bail          Stop at the first failure
+  --timeout <ms>  Per-case timeout (default 5000, 0 disables)
+  --verbose, -v   Show passing cases and stack frames
+```
+
+Exit code is 0 only when every anchor passed, every anchor bound cleanly, every
+reference resolved, and every review is current.
+
+### How things fail
+
+| | Reported as | Annotated into the document |
+| --- | --- | --- |
+| Handler throws | a failed case | yes |
+| A cell will not coerce | a failed case, that row only | yes |
+| Schema or diagram malformed | a failed anchor | yes |
+| No handler registered | a skipped anchor | yes |
+| Broken link or symbol | a problem, with `line:col` | no — it is prose, not an anchor |
+| Covered code changed | a stale review | yes |
+
+A row whose cell will not coerce never reaches your handler, and a whole-asset
+handler is never run against a table that is silently missing rows.
+
+## Under `bun test`
+
+`loadDocument()` expands a document into cases without running them, so Bun's
+test runner can own scheduling and reporting — one native test per table row:
+
+```ts
+import { describe, test, expect } from 'bun:test';
+import { loadDocument } from 'md-verified';
+
+for (const file of ['docs/pricing.md', 'docs/limits.md']) {
+  const doc = await loadDocument(file);
+
+  describe(doc.file, () => {
+    test('references resolve', () => expect(doc.problems).toEqual([]));
+    test('reviews current', () =>
+      expect(doc.reviews.filter((r) => r.status === 'failed')).toEqual([]));
+
+    for (const suite of doc.suites) {
+      describe(suite.id, () => {
+        for (const c of suite.cases) test(c.name, () => c.run());
+      });
+    }
+  });
+}
+```
+
+Use `loadDocument` rather than importing glue files directly. Anchor ids are
+unique per *document*, and Bun shares module state across test files, so two
+documents that both use `prices` would otherwise collide. `loadDocument`
+isolates the registry per document; cases keep their own handler afterwards.
+
+`planCases()` is the lower-level primitive if you need it. See
+[`spec.test.ts`](./spec.test.ts).
+
+## Layout
+
+| File | |
+| --- | --- |
+| [`src/parser.ts`](./src/parser.ts) | Markdown → anchors: the AST walk, lookahead binding, schemas |
+| [`src/mermaid.ts`](./src/mermaid.ts) | Mermaid flowcharts → nodes and edges |
+| [`src/framework.ts`](./src/framework.ts) | The `verify` registry |
+| [`src/runner.ts`](./src/runner.ts) | Execution, case planning, glue resolution |
+| [`src/report.ts`](./src/report.ts) | Terminal output and the Markdown rewrite |
+| [`src/references.ts`](./src/references.ts) | Link, anchor and symbol checking |
+| [`src/covers.ts`](./src/covers.ts) | Set assertions for completeness |
+| [`src/assertions.ts`](./src/assertions.ts) | `assert`, `equals`, `oneOf` |
+| [`src/reviews.ts`](./src/reviews.ts) | Review staleness and digests |
+| [`src/symbols.ts`](./src/symbols.ts) | Static symbol lookup, via the TS compiler API |
+| [`src/coerce.ts`](./src/coerce.ts) | `Schema:` value types |
+| [`check.ts`](./check.ts) | CLI |
+| [`examples/spec.md`](./examples/spec.md) | A specification that passes |
+| [`examples/broken.md`](./examples/broken.md) | The same spec, drifted, for the failure path |
+| [`docs/writing.md`](./docs/writing.md) | What earns an anchor, and what does not |
+| [`docs/anchor-reference.md`](./docs/anchor-reference.md) | The vocabulary, verified against the source |
+
+## Prototype limits
+
+- Mermaid support covers the flowchart/graph family. Sequence and class
+  diagrams parse only as far as their `A --> B` statements go.
+- Glue modules are loaded with a cache-busting query string, so a long-lived
+  process re-registering the same file will accumulate module instances.
+- Anchor ids must be unique per document. The CLI clears the registry between
+  files; in-process, use `loadDocument()`.
+- Node's type stripping cannot handle `enum`, `namespace`, parameter properties
+  or decorators in glue. See [Runtimes](#runtimes); `NODE_OPTIONS=--experimental-transform-types`
+  lifts the restriction.
+- Deno is untested.
+- Symbol lookup reads files rather than importing them, so nothing in the
+  checked project is executed and type-only exports are visible. The trade-off
+  is that `export * from './x'` is not followed.
+- A reference with no definition (`[text][missing]`) cannot be flagged:
+  CommonMark leaves it as literal text, so there is no node in the tree. The
+  reader does see the broken brackets.

package/dist/check.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};