@nielspeter/eess-md 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niels Peter
+
+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,124 @@
+# @nielspeter/eess-md
+
+Architecture testing for a **Markdown corpus** — the Markdown dialect of the [eess](../../README.md) family. _Specifications you can run._
+
+A repo's markdown (docs, ADRs, plans) should stay honest: cross-links resolve, code pointers point at real lines, and — if you use them — ADRs declare how they're enforced. `eess-md` validates all of that on the shared [`@nielspeter/eess`](../core) kernel, so you write a declarative rules file, not a custom validator script.
+
+## Install
+
+```bash
+npm install -D @nielspeter/eess-md
+```
+
+## Example
+
+Neutral, universal conventions — a `docs/**` corpus, English headers, a minimal frozen set:
+
+```typescript
+import { corpus, docs, links, pointers } from '@nielspeter/eess-md'
+
+const c = corpus({
+  roots: ['docs/**'],
+  frozen: ['**/completed/**', '**/archived/**'], // historical records: reported, never failed
+})
+
+// markdown-to-markdown links resolve
+links(c).that().areInternal().should().resolve().check()
+
+// `path:line` code pointers ground against real files
+// (resolves by unique path-suffix: `admin/index.vue` matches the one file
+//  ending with it; pass `{ paths: 'exact' }` to require full repo paths)
+pointers(c).that().areLive().should().resolve().check()
+
+// documents have the sections/tables they should
+docs(c).that().resideInFolder('docs/adr/**').should().haveSection('Context').check()
+```
+
+`docs()`, `links()`, and `pointers()` are entry points on the same fluent
+`.that().should().check()` chain as every other eess dialect — with `.because()`,
+`.warn()`, `.excluding()`, and baseline mode all working unchanged.
+
+## Binding a spec table to code: `rows()` + `correspondence()`
+
+A markdown table is a **spec** — a package list, an ADR index, a field
+reference. `rows()` turns its body rows into first-class elements, and
+`.select()` (inherited from the kernel, on every eess builder) turns any
+selection into one side of a `correspondence()`. Bind a table to what it
+describes and drift in either direction fails the build:
+
+```typescript
+import { corpus, rows } from '@nielspeter/eess-md'
+import { correspondence } from '@nielspeter/eess'
+
+const c = corpus({ roots: ['README.md'] })
+
+// each body row of the "Packages" table becomes a selectable element
+const packageRows = rows(c, {
+  section: /^Packages$/,
+  columns: { pkg: /^Package$/, status: /^Status$/ }, // role → header pattern
+}).select({
+  label: 'README package row',
+  identify: (r) => ({ name: r.get('pkg'), file: r.doc.relPath, line: r.line }),
+})
+
+// `workspacePackages` is a plain Selection you build from the filesystem
+correspondence({ left: packageRows, right: workspacePackages, keyBy: (e) => e.name })
+  .should()
+  .beComplete({ direction: 'both' }) // every row has a package AND vice versa
+  .because('the README package table must not drift from the workspace')
+  .check()
+```
+
+A row carries `get(role)` (the located cell text), its real source `line`, and
+back references to its `doc` and `table`. Rows are drawn from **every** table
+that matches the section and columns — a correspondence source never silently
+ignores a second matching table. Cell text is flattened (bold/links become
+plain text); a link's URL is not recoverable from a row, so verify link targets
+with a `links()` rule alongside.
+
+`direction: 'both'` is doing two jobs: left-to-right catches a table row with no
+package (a _lying_ spec), and right-to-left catches a package with no row
+(_unclaimed_ code — coverage). Drop to a single direction when you only want
+one. Coverage is the same "gate on declaredness" move the ADR `## Enforcement`
+table makes, pointed at code.
+
+## The ADR gate is an opt-in, opinionated preset
+
+`@nielspeter/eess-md/rules/adr` ships `adrEnforcement()`, which implements **one
+specific methodology** — the EESS enforcement-tier model (a `## Enforcement`
+table with tier + mechanism + status). Most teams' ADRs (MADR, Nygard) have none
+of that, and **you don't need it to get value from `eess-md`** — links, pointers,
+sections, and tables all validate through the generic primitives above. Reach for
+`adrEnforcement()` only if your ADRs follow the tier model; otherwise compose your
+own gate from `haveSection` / `haveTable` / `haveTableRowsSatisfying` / `resolve`.
+
+```typescript
+import { adrEnforcement } from '@nielspeter/eess-md/rules/adr'
+
+adrEnforcement(c, { dir: 'docs/adr/**' }) // section+table present, valid tiers, citations resolve
+```
+
+An index/schema doc in the ADR directory (`README.md` or `index.md`) is exempt —
+it isn't an ADR, so it isn't required to carry an `## Enforcement` table.
+
+## Custom conventions (localization, project-specific lifecycle)
+
+Everything project-specific is configuration, not a fork — column headers match
+by pattern (non-English works), and frozen folders are globs:
+
+```typescript
+const c = corpus({
+  roots: ['work/**', 'docs/**'], // plans live under work/
+  frozen: ['**/completed/**', '**/delivered/**', '**/wont-do/**', '**/archived/**'],
+  ignore: ['node_modules/**', '.git/**', '.nuxt/**'],
+})
+
+adrEnforcement(c, {
+  section: /håndhævelse/i,
+  columns: { tier: /tier/i, mechanism: /mekanisme/i, status: /status/i }, // Danish headers
+})
+```
+
+## License
+
+MIT

package/dist/builders/docs.d.ts

@@ -0,0 +1,28 @@
+import { RuleBuilder } from '@nielspeter/eess';
+import type { Corpus } from '../corpus.js';
+import type { MdDocument } from '../model/document.js';
+import { type HaveTableOptions } from '../conditions/structure.js';
+/**
+ * Rule builder over the corpus's markdown documents.
+ *
+ * `.that()` methods filter documents (predicates); `.should()` methods assert
+ * over them (conditions). `haveSection` is a single phase-dispatched method —
+ * a predicate after `.that()`, a condition after `.should()` — mirroring the
+ * dual-use methods in the TS dialect (plan 0041).
+ */
+export declare class DocsRuleBuilder extends RuleBuilder<MdDocument, Corpus> {
+    protected getElements(): MdDocument[];
+    /** Filter to documents whose repo-relative path matches the folder glob. */
+    resideInFolder(glob: string): this;
+    /** Filter to documents whose repo-relative path matches the file glob. */
+    resideInFile(glob: string): this;
+    /** Filter to documents whose file name matches the pattern. */
+    haveNameMatching(re: RegExp): this;
+    /** Dual-use: predicate after `.that()`, condition after `.should()`. */
+    haveSection(name: string | RegExp): this;
+    /** Assert each matched document contains a GFM table with the required columns. */
+    haveTable(opts: HaveTableOptions): this;
+}
+/** Entry point: build rules over the corpus's markdown documents. */
+export declare function docs(corpus: Corpus): DocsRuleBuilder;
+//# sourceMappingURL=docs.d.ts.map

package/dist/builders/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/builders/docs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAOtD,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,4BAA4B,CAAA;AAEnC;;;;;;;GAOG;AACH,qBAAa,eAAgB,SAAQ,WAAW,CAAC,UAAU,EAAE,MAAM,CAAC;IAClE,SAAS,CAAC,WAAW,IAAI,UAAU,EAAE;IAIrC,4EAA4E;IAC5E,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIlC,0EAA0E;IAC1E,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIhC,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIlC,wEAAwE;IACxE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAOxC,mFAAmF;IACnF,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI;CAGxC;AAED,qEAAqE;AACrE,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAEpD"}

package/dist/builders/docs.js

@@ -0,0 +1,44 @@
+import { RuleBuilder } from '@nielspeter/eess';
+import { resideInFolder, resideInFile, haveNameMatching, haveSectionPredicate, } from '../predicates/document.js';
+import { haveSection as haveSectionCondition, haveTable as haveTableCondition, } from '../conditions/structure.js';
+/**
+ * Rule builder over the corpus's markdown documents.
+ *
+ * `.that()` methods filter documents (predicates); `.should()` methods assert
+ * over them (conditions). `haveSection` is a single phase-dispatched method —
+ * a predicate after `.that()`, a condition after `.should()` — mirroring the
+ * dual-use methods in the TS dialect (plan 0041).
+ */
+export class DocsRuleBuilder extends RuleBuilder {
+    getElements() {
+        return this.project.documents();
+    }
+    /** Filter to documents whose repo-relative path matches the folder glob. */
+    resideInFolder(glob) {
+        return this.addPredicate(resideInFolder(glob));
+    }
+    /** Filter to documents whose repo-relative path matches the file glob. */
+    resideInFile(glob) {
+        return this.addPredicate(resideInFile(glob));
+    }
+    /** Filter to documents whose file name matches the pattern. */
+    haveNameMatching(re) {
+        return this.addPredicate(haveNameMatching(re));
+    }
+    /** Dual-use: predicate after `.that()`, condition after `.should()`. */
+    haveSection(name) {
+        if (this._phase === 'condition') {
+            return this.addCondition(haveSectionCondition(name));
+        }
+        return this.addPredicate(haveSectionPredicate(name));
+    }
+    /** Assert each matched document contains a GFM table with the required columns. */
+    haveTable(opts) {
+        return this.addCondition(haveTableCondition(opts));
+    }
+}
+/** Entry point: build rules over the corpus's markdown documents. */
+export function docs(corpus) {
+    return new DocsRuleBuilder(corpus);
+}
+//# sourceMappingURL=docs.js.map

package/dist/builders/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../src/builders/docs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAG9C,OAAO,EACL,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,2BAA2B,CAAA;AAClC,OAAO,EACL,WAAW,IAAI,oBAAoB,EACnC,SAAS,IAAI,kBAAkB,GAEhC,MAAM,4BAA4B,CAAA;AAEnC;;;;;;;GAOG;AACH,MAAM,OAAO,eAAgB,SAAQ,WAA+B;IACxD,WAAW;QACnB,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAA;IACjC,CAAC;IAED,4EAA4E;IAC5E,cAAc,CAAC,IAAY;QACzB,OAAO,IAAI,CAAC,YAAY,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAA;IAChD,CAAC;IAED,0EAA0E;IAC1E,YAAY,CAAC,IAAY;QACvB,OAAO,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAA;IAC9C,CAAC;IAED,+DAA+D;IAC/D,gBAAgB,CAAC,EAAU;QACzB,OAAO,IAAI,CAAC,YAAY,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAA;IAChD,CAAC;IAED,wEAAwE;IACxE,WAAW,CAAC,IAAqB;QAC/B,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;YAChC,OAAO,IAAI,CAAC,YAAY,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAA;QACtD,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAA;IACtD,CAAC;IAED,mFAAmF;IACnF,SAAS,CAAC,IAAsB;QAC9B,OAAO,IAAI,CAAC,YAAY,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAA;IACpD,CAAC;CACF;AAED,qEAAqE;AACrE,MAAM,UAAU,IAAI,CAAC,MAAc;IACjC,OAAO,IAAI,eAAe,CAAC,MAAM,CAAC,CAAA;AACpC,CAAC"}

package/dist/builders/links.d.ts

@@ -0,0 +1,26 @@
+import { RuleBuilder } from '@nielspeter/eess';
+import type { Corpus } from '../corpus.js';
+import { type MdLink } from '../model/links.js';
+import { type LinkResolveOptions } from '../conditions/resolve.js';
+export type { LinkResolveOptions } from '../conditions/resolve.js';
+/** A link element: a link occurrence plus its containing document. */
+export type { MdLink } from '../model/links.js';
+/**
+ * Rule builder over the corpus's markdown links.
+ */
+export declare class LinkRuleBuilder extends RuleBuilder<MdLink, Corpus> {
+    protected getElements(): MdLink[];
+    /** Filter to links that point within the repo (no scheme). */
+    areInternal(): this;
+    /** Filter to links with an external scheme (http, mailto, protocol-relative). */
+    areExternal(): this;
+    /**
+     * Condition: internal links resolve to an existing repo file. Static-site
+     * corpora with extensionless links pass `tryExtensions`/`tryIndex`, e.g.
+     * `resolve({ tryExtensions: ['.md'], tryIndex: 'index.md' })`.
+     */
+    resolve(options?: LinkResolveOptions): this;
+}
+/** Entry point: build rules over the corpus's markdown links. */
+export declare function links(corpus: Corpus): LinkRuleBuilder;
+//# sourceMappingURL=links.d.ts.map

package/dist/builders/links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../../src/builders/links.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAkB,MAAM,kBAAkB,CAAA;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,EAAgB,KAAK,MAAM,EAAkB,MAAM,mBAAmB,CAAA;AAC7E,OAAO,EAAgB,KAAK,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAEhF,YAAY,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAElE,sEAAsE;AACtE,YAAY,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAW/C;;GAEG;AACH,qBAAa,eAAgB,SAAQ,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC;IAC9D,SAAS,CAAC,WAAW,IAAI,MAAM,EAAE;IAQjC,8DAA8D;IAC9D,WAAW,IAAI,IAAI;IAInB,iFAAiF;IACjF,WAAW,IAAI,IAAI;IAInB;;;;OAIG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,IAAI;CAG5C;AAED,iEAAiE;AACjE,wBAAgB,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAErD"}

package/dist/builders/links.js

@@ -0,0 +1,42 @@
+import { RuleBuilder } from '@nielspeter/eess';
+import { collectLinks } from '../model/links.js';
+import { linkResolves } from '../conditions/resolve.js';
+const areInternal = () => ({
+    description: 'are internal',
+    test: (l) => !l.external,
+});
+const areExternal = () => ({
+    description: 'are external',
+    test: (l) => l.external,
+});
+/**
+ * Rule builder over the corpus's markdown links.
+ */
+export class LinkRuleBuilder extends RuleBuilder {
+    getElements() {
+        return this.project
+            .documents()
+            .flatMap((doc) => collectLinks(doc.root, doc.text).map((link) => ({ ...link, doc })));
+    }
+    /** Filter to links that point within the repo (no scheme). */
+    areInternal() {
+        return this.addPredicate(areInternal());
+    }
+    /** Filter to links with an external scheme (http, mailto, protocol-relative). */
+    areExternal() {
+        return this.addPredicate(areExternal());
+    }
+    /**
+     * Condition: internal links resolve to an existing repo file. Static-site
+     * corpora with extensionless links pass `tryExtensions`/`tryIndex`, e.g.
+     * `resolve({ tryExtensions: ['.md'], tryIndex: 'index.md' })`.
+     */
+    resolve(options) {
+        return this.addCondition(linkResolves(this.project, options));
+    }
+}
+/** Entry point: build rules over the corpus's markdown links. */
+export function links(corpus) {
+    return new LinkRuleBuilder(corpus);
+}
+//# sourceMappingURL=links.js.map

package/dist/builders/links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../../src/builders/links.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAkB,MAAM,kBAAkB,CAAA;AAE9D,OAAO,EAAE,YAAY,EAA+B,MAAM,mBAAmB,CAAA;AAC7E,OAAO,EAAE,YAAY,EAA2B,MAAM,0BAA0B,CAAA;AAOhF,MAAM,WAAW,GAAG,GAAsB,EAAE,CAAC,CAAC;IAC5C,WAAW,EAAE,cAAc;IAC3B,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ;CACzB,CAAC,CAAA;AACF,MAAM,WAAW,GAAG,GAAsB,EAAE,CAAC,CAAC;IAC5C,WAAW,EAAE,cAAc;IAC3B,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ;CACxB,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,WAA2B;IACpD,WAAW;QACnB,OAAO,IAAI,CAAC,OAAO;aAChB,SAAS,EAAE;aACX,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CACf,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAe,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,CAC9E,CAAA;IACL,CAAC;IAED,8DAA8D;IAC9D,WAAW;QACT,OAAO,IAAI,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC,CAAA;IACzC,CAAC;IAED,iFAAiF;IACjF,WAAW;QACT,OAAO,IAAI,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC,CAAA;IACzC,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,OAA4B;QAClC,OAAO,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAA;IAC/D,CAAC;CACF;AAED,iEAAiE;AACjE,MAAM,UAAU,KAAK,CAAC,MAAc;IAClC,OAAO,IAAI,eAAe,CAAC,MAAM,CAAC,CAAA;AACpC,CAAC"}

package/dist/builders/pointers.d.ts

@@ -0,0 +1,26 @@
+import { RuleBuilder } from '@nielspeter/eess';
+import type { Corpus } from '../corpus.js';
+import { type MdPointer } from '../model/pointers.js';
+import { type PointerResolveOptions } from '../conditions/pointer-resolve.js';
+/** A code-pointer element: a pointer occurrence plus its containing document. */
+export type { MdPointer } from '../model/pointers.js';
+/**
+ * Rule builder over the corpus's `path:line` code pointers.
+ */
+export declare class PointerRuleBuilder extends RuleBuilder<MdPointer, Corpus> {
+    protected getElements(): MdPointer[];
+    /** Filter to pointers in live documents (not in a frozen folder). */
+    areLive(): this;
+    /** Filter to pointers in frozen documents (historical records). */
+    areFrozen(): this;
+    /**
+     * Condition: pointers resolve to a real file with the line in range. By
+     * default a pointer resolves by unique path-suffix (`admin/index.vue` matches
+     * the one file ending in it); pass `{ paths: 'exact' }` to require full
+     * repo-relative paths.
+     */
+    resolve(options?: PointerResolveOptions): this;
+}
+/** Entry point: build rules over the corpus's code pointers. */
+export declare function pointers(corpus: Corpus): PointerRuleBuilder;
+//# sourceMappingURL=pointers.d.ts.map

package/dist/builders/pointers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pointers.d.ts","sourceRoot":"","sources":["../../src/builders/pointers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAkB,MAAM,kBAAkB,CAAA;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,EAAmB,KAAK,SAAS,EAAqB,MAAM,sBAAsB,CAAA;AACzF,OAAO,EAAmB,KAAK,qBAAqB,EAAE,MAAM,kCAAkC,CAAA;AAE9F,iFAAiF;AACjF,YAAY,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAWrD;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,WAAW,CAAC,SAAS,EAAE,MAAM,CAAC;IACpE,SAAS,CAAC,WAAW,IAAI,SAAS,EAAE;IAQpC,qEAAqE;IACrE,OAAO,IAAI,IAAI;IAIf,mEAAmE;IACnE,SAAS,IAAI,IAAI;IAIjB;;;;;OAKG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,IAAI;CAG/C;AAED,gEAAgE;AAChE,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,CAE3D"}

package/dist/builders/pointers.js

@@ -0,0 +1,43 @@
+import { RuleBuilder } from '@nielspeter/eess';
+import { extractPointers } from '../model/pointers.js';
+import { pointerResolves } from '../conditions/pointer-resolve.js';
+const areLive = () => ({
+    description: 'are live (not in a frozen folder)',
+    test: (p) => !p.doc.frozen,
+});
+const areFrozen = () => ({
+    description: 'are frozen (historical record)',
+    test: (p) => p.doc.frozen,
+});
+/**
+ * Rule builder over the corpus's `path:line` code pointers.
+ */
+export class PointerRuleBuilder extends RuleBuilder {
+    getElements() {
+        return this.project
+            .documents()
+            .flatMap((doc) => extractPointers(doc.text, doc.root).map((p) => ({ ...p, doc })));
+    }
+    /** Filter to pointers in live documents (not in a frozen folder). */
+    areLive() {
+        return this.addPredicate(areLive());
+    }
+    /** Filter to pointers in frozen documents (historical records). */
+    areFrozen() {
+        return this.addPredicate(areFrozen());
+    }
+    /**
+     * Condition: pointers resolve to a real file with the line in range. By
+     * default a pointer resolves by unique path-suffix (`admin/index.vue` matches
+     * the one file ending in it); pass `{ paths: 'exact' }` to require full
+     * repo-relative paths.
+     */
+    resolve(options) {
+        return this.addCondition(pointerResolves(this.project, options));
+    }
+}
+/** Entry point: build rules over the corpus's code pointers. */
+export function pointers(corpus) {
+    return new PointerRuleBuilder(corpus);
+}
+//# sourceMappingURL=pointers.js.map

package/dist/builders/pointers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pointers.js","sourceRoot":"","sources":["../../src/builders/pointers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAkB,MAAM,kBAAkB,CAAA;AAE9D,OAAO,EAAE,eAAe,EAAqC,MAAM,sBAAsB,CAAA;AACzF,OAAO,EAAE,eAAe,EAA8B,MAAM,kCAAkC,CAAA;AAK9F,MAAM,OAAO,GAAG,GAAyB,EAAE,CAAC,CAAC;IAC3C,WAAW,EAAE,mCAAmC;IAChD,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM;CAC3B,CAAC,CAAA;AACF,MAAM,SAAS,GAAG,GAAyB,EAAE,CAAC,CAAC;IAC7C,WAAW,EAAE,gCAAgC;IAC7C,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM;CAC1B,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,WAA8B;IAC1D,WAAW;QACnB,OAAO,IAAI,CAAC,OAAO;aAChB,SAAS,EAAE;aACX,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CACf,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAe,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAC9E,CAAA;IACL,CAAC;IAED,qEAAqE;IACrE,OAAO;QACL,OAAO,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC,CAAA;IACrC,CAAC;IAED,mEAAmE;IACnE,SAAS;QACP,OAAO,IAAI,CAAC,YAAY,CAAC,SAAS,EAAE,CAAC,CAAA;IACvC,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,OAA+B;QACrC,OAAO,IAAI,CAAC,YAAY,CAAC,eAAe,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAA;IAClE,CAAC;CACF;AAED,gEAAgE;AAChE,MAAM,UAAU,QAAQ,CAAC,MAAc;IACrC,OAAO,IAAI,kBAAkB,CAAC,MAAM,CAAC,CAAA;AACvC,CAAC"}

package/dist/builders/rows.d.ts

@@ -0,0 +1,36 @@
+import { RuleBuilder } from '@nielspeter/eess';
+import type { Corpus } from '../corpus.js';
+import { type MdRow, type RowMatchOptions } from '../model/rows.js';
+/**
+ * Rule builder over table rows drawn from the corpus.
+ *
+ * A row is a first-class element (`MdRow`): its located-column accessor
+ * (`get(role)`), its real source line, and back references to its document and
+ * table. Rows are drawn from **every** table (across all documents) that sits
+ * under the requested section and has all the requested columns.
+ *
+ * The primary use is `.select()` — turning spec-table rows into one side of a
+ * kernel `correspondence()` so a table can be bound to code and fail on drift.
+ * The standard `.that().satisfy(…)` / `.should().satisfy(…)` surface is
+ * inherited, so rows are also directly rule-able.
+ */
+export declare class RowsRuleBuilder extends RuleBuilder<MdRow, Corpus> {
+    private readonly opts;
+    constructor(corpus: Corpus, opts: RowMatchOptions);
+    protected getElements(): MdRow[];
+}
+/**
+ * Entry point: build rules over table rows in the corpus.
+ *
+ * ```ts
+ * const packageRows = rows(c, {
+ *   section: /^Packages$/,
+ *   columns: { pkg: /^Package$/, status: /^Status$/ },
+ * }).select({
+ *   label: 'README package row',
+ *   identify: (r) => ({ name: r.get('pkg'), file: r.doc.relPath, line: r.line }),
+ * })
+ * ```
+ */
+export declare function rows(corpus: Corpus, opts: RowMatchOptions): RowsRuleBuilder;
+//# sourceMappingURL=rows.d.ts.map

package/dist/builders/rows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rows.d.ts","sourceRoot":"","sources":["../../src/builders/rows.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,EAAkB,KAAK,KAAK,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAEnF;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,SAAQ,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC;IAG3D,OAAO,CAAC,QAAQ,CAAC,IAAI;gBADrB,MAAM,EAAE,MAAM,EACG,IAAI,EAAE,eAAe;IAKxC,SAAS,CAAC,WAAW,IAAI,KAAK,EAAE;CAMjC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,eAAe,CAE3E"}

package/dist/builders/rows.js

@@ -0,0 +1,42 @@
+import { RuleBuilder } from '@nielspeter/eess';
+import { matchTableRows } from '../model/rows.js';
+/**
+ * Rule builder over table rows drawn from the corpus.
+ *
+ * A row is a first-class element (`MdRow`): its located-column accessor
+ * (`get(role)`), its real source line, and back references to its document and
+ * table. Rows are drawn from **every** table (across all documents) that sits
+ * under the requested section and has all the requested columns.
+ *
+ * The primary use is `.select()` — turning spec-table rows into one side of a
+ * kernel `correspondence()` so a table can be bound to code and fail on drift.
+ * The standard `.that().satisfy(…)` / `.should().satisfy(…)` surface is
+ * inherited, so rows are also directly rule-able.
+ */
+export class RowsRuleBuilder extends RuleBuilder {
+    opts;
+    constructor(corpus, opts) {
+        super(corpus);
+        this.opts = opts;
+    }
+    getElements() {
+        return this.project.documents().flatMap((doc) => matchTableRows(doc, this.opts));
+    }
+}
+/**
+ * Entry point: build rules over table rows in the corpus.
+ *
+ * ```ts
+ * const packageRows = rows(c, {
+ *   section: /^Packages$/,
+ *   columns: { pkg: /^Package$/, status: /^Status$/ },
+ * }).select({
+ *   label: 'README package row',
+ *   identify: (r) => ({ name: r.get('pkg'), file: r.doc.relPath, line: r.line }),
+ * })
+ * ```
+ */
+export function rows(corpus, opts) {
+    return new RowsRuleBuilder(corpus, opts);
+}
+//# sourceMappingURL=rows.js.map

package/dist/builders/rows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rows.js","sourceRoot":"","sources":["../../src/builders/rows.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C,OAAO,EAAE,cAAc,EAAoC,MAAM,kBAAkB,CAAA;AAEnF;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,eAAgB,SAAQ,WAA0B;IAG1C;IAFnB,YACE,MAAc,EACG,IAAqB;QAEtC,KAAK,CAAC,MAAM,CAAC,CAAA;QAFI,SAAI,GAAJ,IAAI,CAAiB;IAGxC,CAAC;IAES,WAAW;QACnB,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,cAAc,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;IAClF,CAAC;CAIF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,IAAI,CAAC,MAAc,EAAE,IAAqB;IACxD,OAAO,IAAI,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;AAC1C,CAAC"}

package/dist/builders/task-items.d.ts

@@ -0,0 +1,21 @@
+import { RuleBuilder } from '@nielspeter/eess';
+import type { Corpus } from '../corpus.js';
+import type { MdDocument } from '../model/document.js';
+import { type MdTaskItemRef } from '../model/task-items.js';
+/** A task-item element: a task-list item plus its containing document. */
+export interface MdTaskItem extends MdTaskItemRef {
+    readonly doc: MdDocument;
+}
+/**
+ * Rule builder over the corpus's GFM task-list items (`- [ ]` / `- [x]`).
+ */
+export declare class TaskItemRuleBuilder extends RuleBuilder<MdTaskItem, Corpus> {
+    protected getElements(): MdTaskItem[];
+    /** Filter to open boxes (`- [ ]`). */
+    areOpen(): this;
+    /** Filter to checked boxes (`- [x]`). */
+    areChecked(): this;
+}
+/** Entry point: build rules over the corpus's task-list items. */
+export declare function taskItems(corpus: Corpus): TaskItemRuleBuilder;
+//# sourceMappingURL=task-items.d.ts.map

package/dist/builders/task-items.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-items.d.ts","sourceRoot":"","sources":["../../src/builders/task-items.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAkB,MAAM,kBAAkB,CAAA;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAE7E,0EAA0E;AAC1E,MAAM,WAAW,UAAW,SAAQ,aAAa;IAC/C,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAA;CACzB;AAWD;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,WAAW,CAAC,UAAU,EAAE,MAAM,CAAC;IACtE,SAAS,CAAC,WAAW,IAAI,UAAU,EAAE;IAMrC,sCAAsC;IACtC,OAAO,IAAI,IAAI;IAIf,yCAAyC;IACzC,UAAU,IAAI,IAAI;CAGnB;AAED,kEAAkE;AAClE,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,CAE7D"}

package/dist/builders/task-items.js

@@ -0,0 +1,33 @@
+import { RuleBuilder } from '@nielspeter/eess';
+import { collectTaskItems } from '../model/task-items.js';
+const areOpen = () => ({
+    description: 'are open',
+    test: (t) => !t.checked,
+});
+const areChecked = () => ({
+    description: 'are checked',
+    test: (t) => t.checked,
+});
+/**
+ * Rule builder over the corpus's GFM task-list items (`- [ ]` / `- [x]`).
+ */
+export class TaskItemRuleBuilder extends RuleBuilder {
+    getElements() {
+        return this.project
+            .documents()
+            .flatMap((doc) => collectTaskItems(doc.root).map((t) => ({ ...t, doc })));
+    }
+    /** Filter to open boxes (`- [ ]`). */
+    areOpen() {
+        return this.addPredicate(areOpen());
+    }
+    /** Filter to checked boxes (`- [x]`). */
+    areChecked() {
+        return this.addPredicate(areChecked());
+    }
+}
+/** Entry point: build rules over the corpus's task-list items. */
+export function taskItems(corpus) {
+    return new TaskItemRuleBuilder(corpus);
+}
+//# sourceMappingURL=task-items.js.map

package/dist/builders/task-items.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-items.js","sourceRoot":"","sources":["../../src/builders/task-items.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAkB,MAAM,kBAAkB,CAAA;AAG9D,OAAO,EAAE,gBAAgB,EAAsB,MAAM,wBAAwB,CAAA;AAO7E,MAAM,OAAO,GAAG,GAA0B,EAAE,CAAC,CAAC;IAC5C,WAAW,EAAE,UAAU;IACvB,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO;CACxB,CAAC,CAAA;AACF,MAAM,UAAU,GAAG,GAA0B,EAAE,CAAC,CAAC;IAC/C,WAAW,EAAE,aAAa;IAC1B,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO;CACvB,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,WAA+B;IAC5D,WAAW;QACnB,OAAO,IAAI,CAAC,OAAO;aAChB,SAAS,EAAE;aACX,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAA;IAC7E,CAAC;IAED,sCAAsC;IACtC,OAAO;QACL,OAAO,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC,CAAA;IACrC,CAAC;IAED,yCAAyC;IACzC,UAAU;QACR,OAAO,IAAI,CAAC,YAAY,CAAC,UAAU,EAAE,CAAC,CAAA;IACxC,CAAC;CACF;AAED,kEAAkE;AAClE,MAAM,UAAU,SAAS,CAAC,MAAc;IACtC,OAAO,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAAA;AACxC,CAAC"}

package/dist/builders/vocabulary.d.ts

@@ -0,0 +1,66 @@
+import { RuleBuilder } from '@nielspeter/eess';
+import type { Corpus } from '../corpus.js';
+import type { MdDocument } from '../model/document.js';
+/**
+ * Controlled-vocabulary primitive (plan 0069 Phase 4): derive a term set from
+ * the corpus, then assert that named references in prose resolve against it.
+ *
+ * Both halves are consumer parameters — where the terms come from
+ * (`fromFolders` / `fromHeadings` / explicit `terms`) and what a reference
+ * looks like (the `label` pattern). Nothing domain-shaped lives here.
+ */
+export interface VocabularyOptions {
+    /**
+     * Glob over directory paths (repo-relative, POSIX); each matched
+     * directory's basename becomes a term — e.g. folders-as-canonical-names.
+     */
+    readonly fromFolders?: string;
+    /** Glob over documents; every heading whose depth matches becomes a term. */
+    readonly fromHeadings?: {
+        readonly files: string;
+        readonly depth?: number;
+    };
+    /** Explicit terms, unioned with the derived ones. */
+    readonly terms?: readonly string[];
+    /** Normalization applied to terms AND references before comparing. Default: trim. */
+    readonly normalize?: (value: string) => string;
+}
+export interface Vocabulary {
+    /** The normalized term set. */
+    readonly terms: ReadonlySet<string>;
+    /** The normalization in force (shared with `resolveAgainst`). */
+    readonly normalize: (value: string) => string;
+}
+/** Derive a controlled vocabulary from the corpus. */
+export declare function vocabulary(corpus: Corpus, options: VocabularyOptions): Vocabulary;
+/** A labeled named reference found in prose — e.g. `Bounded Context: Billing`. */
+export interface MdTerm {
+    /** The referenced value (markdown emphasis stripped, trimmed). */
+    readonly value: string;
+    /** The line's text after the label match, before cleanup. */
+    readonly raw: string;
+    readonly doc: MdDocument;
+    readonly line: number;
+}
+export interface TermsOptions {
+    /** Pattern locating a labeled reference on a line — e.g. `/Bounded Context:/`. */
+    readonly label: RegExp;
+    /**
+     * Extract the referenced value from the text following the label match.
+     * Default: strip markdown emphasis characters and trim.
+     */
+    readonly value?: (rest: string) => string;
+}
+/** Rule builder over labeled named references in the corpus's prose. */
+export declare class TermRuleBuilder extends RuleBuilder<MdTerm, Corpus> {
+    private readonly opts;
+    constructor(corpus: Corpus, opts: TermsOptions);
+    protected getElements(): MdTerm[];
+    /** Filter to references in documents whose path matches the glob. */
+    resideInFile(glob: string): this;
+    /** Assert every reference's value is a term of the vocabulary. */
+    resolveAgainst(vocab: Vocabulary): this;
+}
+/** Entry point: build rules over labeled named references (`Label: Value` lines). */
+export declare function terms(corpus: Corpus, options: TermsOptions): TermRuleBuilder;
+//# sourceMappingURL=vocabulary.d.ts.map

package/dist/builders/vocabulary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabulary.d.ts","sourceRoot":"","sources":["../../src/builders/vocabulary.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAsD,MAAM,kBAAkB,CAAA;AAClG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC3E,qDAAqD;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC,qFAAqF;IACrF,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;CAC/C;AAED,MAAM,WAAW,UAAU;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACnC,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;CAC9C;AAID,sDAAsD;AACtD,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAoCjF;AAED,kFAAkF;AAClF,MAAM,WAAW,MAAM;IACrB,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;CAC1C;AA8DD,wEAAwE;AACxE,qBAAa,eAAgB,SAAQ,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC;IAG5D,OAAO,CAAC,QAAQ,CAAC,IAAI;gBADrB,MAAM,EAAE,MAAM,EACG,IAAI,EAAE,YAAY;IAKrC,SAAS,CAAC,WAAW,IAAI,MAAM,EAAE;IAIjC,qEAAqE;IACrE,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIhC,kEAAkE;IAClE,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;CAGxC;AAED,qFAAqF;AACrF,wBAAgB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,eAAe,CAE5E"}