@nielspeter/eess-md 0.8.0 → 0.9.0

package/README.md

@@ -144,7 +144,9 @@ a `correspondence()` against the set you hold, both directions. The docs page's
 ```typescript
 import { adrEnforcement } from '@nielspeter/eess-md/rules/adr'
 
-adrEnforcement(c, { dir: 'docs/adr/**' }) // section+table present, valid tiers, citations resolve
+// section+table present, valid tiers, cited paths exist. A cited it('…') title is not
+// checked here — run eess-crossvalidate's adrCitationsResolve for that.
+adrEnforcement(c, { dir: 'docs/adr/**' })
 ```
 
 An index/schema doc in the ADR directory (`README.md` or `index.md`) is exempt —

package/dist/builders/declaration-findings.d.ts

@@ -0,0 +1,37 @@
+import type { ConditionContext } from '@nielspeter/eess';
+import type { Corpus } from '../corpus.js';
+import { type ArchViolation } from '../model/violation.js';
+/** What an `areLabelled()`/`areInSection()` call declared, kept for the declaration scan. */
+export type LinkDeclaration = {
+    readonly kind: 'label';
+    readonly label: string;
+} | {
+    readonly kind: 'section';
+    readonly name: string | RegExp;
+};
+/** One key per distinct declaration, so a label declared twice is scanned once. */
+export declare function declarationKey(d: LinkDeclaration): string;
+/**
+ * Plan 0405 — findings about the declarations themselves, scanned over the whole
+ * corpus (not the rule's selection: a misspelt declaration is, by definition, not
+ * selected). Each names something the selector could not read (ADR-016 rule 7):
+ *
+ * - **a near-miss label:** a wrapped label (`**Label:**`, `**Label**:`,
+ *   `__Label__:`) opening a block that matches the declared one except for case
+ *   or inner spacing. The plain `Label:` form is never a near-miss: prose
+ *   beginning "related to:" is common;
+ * - **a label inside the declaration:** a different wrapped label nested inside
+ *   a declaration takes the links under it out of the declaration;
+ * - **a label where no block starts:** the label, exact or near, later in a
+ *   paragraph, in a table cell or in a heading, where it declares nothing — or
+ *   at a block's start in a form the grammar does not read (`**_Label:_**`, a
+ *   whole line in bold);
+ * - **reference-style links:** a declaration holding `[text][ref]` links, which
+ *   eess-md does not read;
+ * - **an empty declaration:** a wrapped label selecting no link — it names no
+ *   record, or it stands alone with no list directly under it;
+ * - **a near-miss section:** a heading that misses a string declaration by case
+ *   or spacing (a `RegExp` states its own tolerance).
+ */
+export declare function declarationFindings(corpus: Corpus, declarations: readonly LinkDeclaration[], context: ConditionContext): ArchViolation[];
+//# sourceMappingURL=declaration-findings.d.ts.map

package/dist/builders/declaration-findings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declaration-findings.d.ts","sourceRoot":"","sources":["../../src/builders/declaration-findings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAG1C,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAGvE,6FAA6F;AAC7F,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAA;AAEhE,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAGzD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,SAAS,eAAe,EAAE,EACxC,OAAO,EAAE,gBAAgB,GACxB,aAAa,EAAE,CAyHjB"}

package/dist/builders/declaration-findings.js

@@ -0,0 +1,128 @@
+import { collectLinkBlocks } from '../model/links.js';
+import { isLabelAlone, isNearMiss, labelPattern, wrappedLabelOf } from '../model/label.js';
+import { mdViolation } from '../model/violation.js';
+import { decidingBlock } from '../predicates/declared-block.js';
+/** One key per distinct declaration, so a label declared twice is scanned once. */
+export function declarationKey(d) {
+    if (d.kind === 'label')
+        return `label:${d.label}`;
+    return typeof d.name === 'string' ? `section:${d.name}` : `section-re:${String(d.name)}`;
+}
+/**
+ * Plan 0405 — findings about the declarations themselves, scanned over the whole
+ * corpus (not the rule's selection: a misspelt declaration is, by definition, not
+ * selected). Each names something the selector could not read (ADR-016 rule 7):
+ *
+ * - **a near-miss label:** a wrapped label (`**Label:**`, `**Label**:`,
+ *   `__Label__:`) opening a block that matches the declared one except for case
+ *   or inner spacing. The plain `Label:` form is never a near-miss: prose
+ *   beginning "related to:" is common;
+ * - **a label inside the declaration:** a different wrapped label nested inside
+ *   a declaration takes the links under it out of the declaration;
+ * - **a label where no block starts:** the label, exact or near, later in a
+ *   paragraph, in a table cell or in a heading, where it declares nothing — or
+ *   at a block's start in a form the grammar does not read (`**_Label:_**`, a
+ *   whole line in bold);
+ * - **reference-style links:** a declaration holding `[text][ref]` links, which
+ *   eess-md does not read;
+ * - **an empty declaration:** a wrapped label selecting no link — it names no
+ *   record, or it stands alone with no list directly under it;
+ * - **a near-miss section:** a heading that misses a string declaration by case
+ *   or spacing (a `RegExp` states its own tolerance).
+ */
+export function declarationFindings(corpus, declarations, context) {
+    const out = [];
+    for (const doc of corpus.documents()) {
+        const { links, references, blocks, unreadLabels } = collectLinkBlocks(doc.root, doc.text);
+        // Each finding names its kind in its element, so one `.excluding()` sanctions one kind
+        // (`→ label "Supersedes" (empty)`), and carries its own remedy as the suggestion.
+        const report = (line, element, message, suggestion) => {
+            out.push(mdViolation({
+                file: doc.file,
+                line,
+                sourceText: doc.text,
+                context: { ...context, suggestion },
+                element,
+                message,
+            }));
+        };
+        for (const d of declarations) {
+            if (d.kind === 'section') {
+                if (typeof d.name !== 'string')
+                    continue;
+                const declared = d.name;
+                for (const section of doc.sections) {
+                    if (!isNearMiss(section.name, declared))
+                        continue;
+                    report(section.line, `${doc.relPath} → section "${section.name}" (near miss)`, `the heading "${section.name}" is not the declared section "${declared}", so the links under it are not checked`, `write it "${declared}"`);
+                }
+                continue;
+            }
+            const L = d.label;
+            const declared = new RegExp(labelPattern(L));
+            const element = (found, kind) => `${doc.relPath} → label "${found}" (${kind})`;
+            for (const block of blocks) {
+                const found = wrappedLabelOf(block.text);
+                if (found === undefined || !isNearMiss(found, L))
+                    continue;
+                report(block.line, element(found, 'near miss'), `the label "${found}" is not the declared "${L}", so the links under it are not checked`, `write it "${L}"`);
+            }
+            // Which declaration blocks select a link, which hold a reference, which enclose anything.
+            const selects = new Set();
+            const holdsReference = new Set();
+            const encloses = new Set();
+            const taken = new Map();
+            const classify = (path, isReference) => {
+                for (const b of path)
+                    encloses.add(b.line);
+                const decision = decidingBlock(path, declared);
+                if (decision === undefined)
+                    return;
+                if (decision.matches) {
+                    ;
+                    (isReference ? holdsReference : selects).add(decision.block.line);
+                    return;
+                }
+                const found = wrappedLabelOf(decision.block.text);
+                const outer = path.slice(0, decision.at).some((b) => declared.test(b.text));
+                if (found !== undefined && outer && !isNearMiss(found, L)) {
+                    taken.set(decision.block.line, found);
+                }
+            };
+            for (const l of links)
+                classify(l.blockPath ?? [], false);
+            for (const path of references)
+                classify(path, true);
+            for (const [line, found] of taken) {
+                report(line, element(found, `inside "${L}"`), `the label "${found}" sits inside the "${L}" declaration and takes the links under it out of it`, `drop the label, or move it out of the "${L}" list`);
+            }
+            for (const block of blocks) {
+                if (!declared.test(block.text))
+                    continue;
+                if (holdsReference.has(block.line)) {
+                    report(block.line, element(L, 'reference links'), `the "${L}" declaration holds reference-style links, which eess-md does not read`, 'write them as inline links ([text](path))');
+                }
+                else if (wrappedLabelOf(block.text) === L &&
+                    !selects.has(block.line) &&
+                    // A link under it that is not selected is already a finding of its own.
+                    !encloses.has(block.line)) {
+                    const alone = isLabelAlone(block.text);
+                    report(block.line, element(L, 'empty'), alone
+                        ? `the "${L}" label stands alone with no list directly under it, so it declares nothing`
+                        : `the "${L}" declaration names no record`, alone
+                        ? 'put its list right after it, or its links on its line'
+                        : 'add the links it declares, or remove the label');
+                }
+            }
+            for (const u of unreadLabels) {
+                if (u.label !== L && !isNearMiss(u.label, L))
+                    continue;
+                report(u.line, element(u.label, u.reason === 'format' ? 'formatting' : 'not at a block start'), u.reason === 'format'
+                    ? `the label "${u.label}" is written with formatting eess-md does not read, so the links after it are not read as a declaration`
+                    : `the label "${u.label}" is not at the start of a paragraph or list item, so the links after it are not read as a declaration`, u.reason === 'format' ? `write it **${L}:**` : 'start a paragraph or list item with it');
+            }
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=declaration-findings.js.map

package/dist/builders/declaration-findings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declaration-findings.js","sourceRoot":"","sources":["../../src/builders/declaration-findings.ts"],"names":[],"mappings":"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"}

package/dist/builders/links.d.ts

@@ -1,4 +1,4 @@
-import { RuleBuilder } from '@nielspeter/eess';
+import { RuleBuilder, type CollectResult } from '@nielspeter/eess';
 import type { Corpus } from '../corpus.js';
 import { type MdLink } from '../model/links.js';
 import { type LinkResolveOptions } from '../conditions/resolve.js';
@@ -9,17 +9,76 @@ export type { MdLink } from '../model/links.js';
  * Rule builder over the corpus's markdown links.
  */
 export declare class LinkRuleBuilder extends RuleBuilder<MdLink, Corpus> {
+    /** What `areLabelled()`/`areInSection()` declared, for the near-miss scan (plan 0405). */
+    private _declarations;
     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;
+    /**
+     * Filter to links declared under `label` (plan 0405), in any of the ledger's
+     * forms (`**Label:**`, `**Label**:`, `__Label__:`, `Label:`), matched exactly
+     * and case-sensitively. A link is under the label when it sits in the block the
+     * label opens, in that block's nested lists, or — for a label alone on its line
+     * — in the lists directly after it. The nearest label decides: walking out from
+     * the link, the first block that is the label, or opens with a wrapped label of
+     * its own, settles it; a plain line that is not the label settles nothing.
+     *
+     * The rule also reports, over the whole corpus, what it cannot read: a wrapped
+     * label that misses the declared one only by case or spacing, a different
+     * wrapped label inside the declaration, the label where no block starts, a
+     * declaration holding reference-style links, and a wrapped declaration with
+     * nothing under it. That check
+     * runs through this method only: a selection taken with `.select()` carries no
+     * findings, so it carries no such check either.
+     */
+    areLabelled(label: string): this;
+    /**
+     * Filter to links under a heading matching `name` — a string exactly, or a
+     * `RegExp` — at any depth beneath it, matched the way `haveSection()` matches
+     * (plan 0405). A heading that misses a string `name` only by case or spacing
+     * is reported, as for `areLabelled()`.
+     */
+    areInSection(name: string | RegExp): this;
+    /**
+     * Record a declaration once; declaring the same label twice scans it once.
+     * Called on the copy `addPredicate()` returns, and it replaces the array rather
+     * than pushing into it, so a fork never shares its parent's declarations — the
+     * kernel's shallow `copy()` is enough.
+     */
+    private recordDeclaration;
     /**
      * 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;
+    /**
+     * Filter to links whose target is not a frozen document (plan 0406) — a frozen
+     * record is history and cannot be edited to answer. Pass the options you pass
+     * `beLinkedBack()`, so the two resolve a link the same way. Every other target
+     * is kept, and examined.
+     */
+    haveLiveTargets(options?: LinkResolveOptions): this;
+    /**
+     * Condition: each link's target links back to the link's document (plan 0406).
+     * Any link back answers; several are one answer, and an incidental mention
+     * counts. A target that cannot answer — frozen, outside the corpus, missing, a
+     * directory, the record itself, an external URL — is one finding naming its
+     * cause, with its remedy as the suggestion. Takes the options `resolve()`
+     * takes, so a corpus with extensionless links resolves both ends the same way.
+     */
+    beLinkedBack(options?: LinkResolveOptions): this;
+    /**
+     * The base result, plus findings about the declarations themselves (plan
+     * 0405). The base evidence passes through unchanged: the declarations' scan
+     * examines nothing the rule asserts over, so it must not raise `examined`
+     * (which would hide the zero-examined finding when every declaration is
+     * misspelt) and must not go through `mergeCollectResults`, whose dead-member
+     * rule would read an empty findings part as a dead rule on every clean run.
+     */
+    protected collectViolations(): CollectResult;
 }
 /** Entry point: build rules over the corpus's markdown links. */
 export declare function links(corpus: Corpus): LinkRuleBuilder;

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

@@ -1 +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;AAE7E,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;IAIjC,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"}
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../../src/builders/links.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAiB,KAAK,aAAa,EAAkB,MAAM,kBAAkB,CAAA;AACjG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,EAAgB,KAAK,MAAM,EAAkB,MAAM,mBAAmB,CAAA;AAE7E,OAAO,EAAgB,KAAK,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAUhF,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,0FAA0F;IAC1F,OAAO,CAAC,aAAa,CAAiC;IAEtD,SAAS,CAAC,WAAW,IAAI,MAAM,EAAE;IAIjC,8DAA8D;IAC9D,WAAW,IAAI,IAAI;IAInB,iFAAiF;IACjF,WAAW,IAAI,IAAI;IAInB;;;;;;;;;;;;;;;;OAgBG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAOhC;;;;;OAKG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAOzC;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;;;OAIG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,IAAI;IAI3C;;;;;OAKG;IACH,eAAe,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,IAAI;IAInD;;;;;;;OAOG;IACH,YAAY,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,IAAI;IAIhD;;;;;;;OAOG;cACgB,iBAAiB,IAAI,aAAa;CAWtD;AAED,iEAAiE;AACjE,wBAAgB,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAErD"}

package/dist/builders/links.js

@@ -1,7 +1,11 @@
-import { RuleBuilder } from '@nielspeter/eess';
+import { RuleBuilder, collectResult } from '@nielspeter/eess';
 import { collectLinks } from '../model/links.js';
 import { stampedByDocument } from '../model/by-document.js';
 import { linkResolves } from '../conditions/resolve.js';
+import { linkedBack } from '../conditions/linked-back.js';
+import { haveLiveTargetsPredicate } from '../predicates/live-target.js';
+import { areInSectionPredicate, areLabelledPredicate } from '../predicates/declared-block.js';
+import { declarationFindings, declarationKey, } from './declaration-findings.js';
 const areInternal = () => ({
     description: 'are internal',
     test: (l) => !l.external,
@@ -14,6 +18,8 @@ const areExternal = () => ({
  * Rule builder over the corpus's markdown links.
  */
 export class LinkRuleBuilder extends RuleBuilder {
+    /** What `areLabelled()`/`areInSection()` declared, for the near-miss scan (plan 0405). */
+    _declarations = [];
     getElements() {
         return stampedByDocument(this.project, (doc) => collectLinks(doc.root, doc.text));
     }
@@ -25,6 +31,54 @@ export class LinkRuleBuilder extends RuleBuilder {
     areExternal() {
         return this.addPredicate(areExternal());
     }
+    /**
+     * Filter to links declared under `label` (plan 0405), in any of the ledger's
+     * forms (`**Label:**`, `**Label**:`, `__Label__:`, `Label:`), matched exactly
+     * and case-sensitively. A link is under the label when it sits in the block the
+     * label opens, in that block's nested lists, or — for a label alone on its line
+     * — in the lists directly after it. The nearest label decides: walking out from
+     * the link, the first block that is the label, or opens with a wrapped label of
+     * its own, settles it; a plain line that is not the label settles nothing.
+     *
+     * The rule also reports, over the whole corpus, what it cannot read: a wrapped
+     * label that misses the declared one only by case or spacing, a different
+     * wrapped label inside the declaration, the label where no block starts, a
+     * declaration holding reference-style links, and a wrapped declaration with
+     * nothing under it. That check
+     * runs through this method only: a selection taken with `.select()` carries no
+     * findings, so it carries no such check either.
+     */
+    areLabelled(label) {
+        return this.addPredicate(areLabelledPredicate(label)).recordDeclaration({
+            kind: 'label',
+            label,
+        });
+    }
+    /**
+     * Filter to links under a heading matching `name` — a string exactly, or a
+     * `RegExp` — at any depth beneath it, matched the way `haveSection()` matches
+     * (plan 0405). A heading that misses a string `name` only by case or spacing
+     * is reported, as for `areLabelled()`.
+     */
+    areInSection(name) {
+        return this.addPredicate(areInSectionPredicate(name)).recordDeclaration({
+            kind: 'section',
+            name,
+        });
+    }
+    /**
+     * Record a declaration once; declaring the same label twice scans it once.
+     * Called on the copy `addPredicate()` returns, and it replaces the array rather
+     * than pushing into it, so a fork never shares its parent's declarations — the
+     * kernel's shallow `copy()` is enough.
+     */
+    recordDeclaration(d) {
+        const key = declarationKey(d);
+        if (!this._declarations.some((x) => declarationKey(x) === key)) {
+            this._declarations = [...this._declarations, d];
+        }
+        return this;
+    }
     /**
      * Condition: internal links resolve to an existing repo file. Static-site
      * corpora with extensionless links pass `tryExtensions`/`tryIndex`, e.g.
@@ -33,6 +87,43 @@ export class LinkRuleBuilder extends RuleBuilder {
     resolve(options) {
         return this.addCondition(linkResolves(this.project, options));
     }
+    /**
+     * Filter to links whose target is not a frozen document (plan 0406) — a frozen
+     * record is history and cannot be edited to answer. Pass the options you pass
+     * `beLinkedBack()`, so the two resolve a link the same way. Every other target
+     * is kept, and examined.
+     */
+    haveLiveTargets(options) {
+        return this.addPredicate(haveLiveTargetsPredicate(this.project, options));
+    }
+    /**
+     * Condition: each link's target links back to the link's document (plan 0406).
+     * Any link back answers; several are one answer, and an incidental mention
+     * counts. A target that cannot answer — frozen, outside the corpus, missing, a
+     * directory, the record itself, an external URL — is one finding naming its
+     * cause, with its remedy as the suggestion. Takes the options `resolve()`
+     * takes, so a corpus with extensionless links resolves both ends the same way.
+     */
+    beLinkedBack(options) {
+        return this.addCondition(linkedBack(this.project, options));
+    }
+    /**
+     * The base result, plus findings about the declarations themselves (plan
+     * 0405). The base evidence passes through unchanged: the declarations' scan
+     * examines nothing the rule asserts over, so it must not raise `examined`
+     * (which would hide the zero-examined finding when every declaration is
+     * misspelt) and must not go through `mergeCollectResults`, whose dead-member
+     * rule would read an empty findings part as a dead rule on every clean run.
+     */
+    collectViolations() {
+        const base = super.collectViolations();
+        if (this._declarations.length === 0)
+            return base;
+        const findings = declarationFindings(this.project, this._declarations, this.buildConditionContext());
+        if (findings.length === 0)
+            return base;
+        return collectResult([...base, ...findings], base);
+    }
 }
 /** Entry point: build rules over the corpus's markdown links. */
 export function links(corpus) {

package/dist/builders/links.js.map

@@ -1 +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,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC3D,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,iBAAiB,CAAY,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAA;IAC9F,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"}
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../../src/builders/links.ts"],"names":[],"mappings":"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"}

package/dist/conditions/linked-back.d.ts

@@ -0,0 +1,17 @@
+import type { Condition } from '@nielspeter/eess';
+import type { Corpus } from '../corpus.js';
+import { type MdLink } from '../model/links.js';
+import { type LinkResolveOptions } from '../model/resolve-link.js';
+/**
+ * Condition (plan 0406): each link's target links back to the link's document.
+ * Any link back answers — several are one answer, and an incidental mention
+ * counts. The back-links are every internal link in the corpus, resolved with
+ * `resolveLink` and the same `options`, indexed on first evaluation.
+ *
+ * `examined` is the selected links: an empty selection fails with the
+ * zero-examined finding. A link that cannot answer — a frozen record, a file
+ * outside the corpus, a missing target — is one finding naming its cause, on
+ * the declaring link's line, with its remedy as the suggestion.
+ */
+export declare function linkedBack(corpus: Corpus, options?: LinkResolveOptions): Condition<MdLink>;
+//# sourceMappingURL=linked-back.d.ts.map

package/dist/conditions/linked-back.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linked-back.d.ts","sourceRoot":"","sources":["../../src/conditions/linked-back.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE7D,OAAO,EAIL,KAAK,kBAAkB,EAExB,MAAM,0BAA0B,CAAA;AAwFjC;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,SAAS,CAAC,MAAM,CAAC,CA8B9F"}

package/dist/conditions/linked-back.js

@@ -0,0 +1,122 @@
+import { collectLinks } from '../model/links.js';
+import { mdViolation } from '../model/violation.js';
+import { basenameIndex, movedLinkFix, resolveLink, } from '../model/resolve-link.js';
+/** Each document's repo path → the documents it links to, resolved as `options` resolves. */
+function linksFrom(corpus, options) {
+    const out = new Map();
+    for (const doc of corpus.documents()) {
+        const targets = new Set();
+        for (const link of collectLinks(doc.root, doc.text)) {
+            const target = resolveLink({ url: link.url, external: link.external, doc }, corpus, options);
+            if (target.kind === 'document')
+                targets.add(target.path);
+        }
+        out.set(doc.relPath, targets);
+    }
+    return out;
+}
+function unanswered(link, target) {
+    const source = link.doc.relPath;
+    switch (target.kind) {
+        case 'document':
+            return target.doc.frozen
+                ? {
+                    target: target.path,
+                    message: `${target.path} is frozen and cannot answer`,
+                    suggestion: `add .haveLiveTargets() to the rule, passing it the options you pass beLinkedBack(), or remove ${target.path} from the declaration`,
+                }
+                : {
+                    target: target.path,
+                    message: `${source} declares ${target.path}, and ${target.path} does not link back`,
+                    suggestion: `add a link to ${source} in ${target.path}, or remove ${target.path} from the declaration`,
+                };
+        case 'not-in-corpus': {
+            // One finding, for the reason whose remedy comes first: a file that is not a
+            // record is not fixed by widening the corpus.
+            if (target.reasons.includes('not-markdown')) {
+                return {
+                    target: target.path,
+                    message: `${target.path} is not a Markdown record`,
+                    suggestion: 'declare a record, not a file',
+                };
+            }
+            if (target.reasons.includes('ignored')) {
+                return {
+                    target: target.path,
+                    message: `${target.path} matches the corpus ignore option, so its links are not read`,
+                    suggestion: 'correct the link, or stop ignoring the path',
+                };
+            }
+            return {
+                target: target.path,
+                message: `${target.path} is outside the corpus, so its links are not read`,
+                suggestion: 'add its folder to the corpus roots, or correct the link',
+            };
+        }
+        case 'missing':
+            return {
+                target: link.url,
+                message: `${link.url} does not exist`,
+                suggestion: 'correct the link to the record it means — the same fix clears resolve()',
+            };
+        case 'directory':
+            return {
+                target: target.path,
+                message: `the link names a directory, ${target.path}, not a record`,
+                suggestion: "link the record's file",
+            };
+        case 'self':
+            return {
+                target: source,
+                message: 'the link points at this record',
+                suggestion: 'remove it; a record does not relate to itself',
+            };
+        case 'external':
+            return {
+                target: link.url,
+                message: `the declaration links outside the repository, to ${link.url}`,
+                suggestion: 'declare a record in the corpus',
+            };
+    }
+}
+/**
+ * Condition (plan 0406): each link's target links back to the link's document.
+ * Any link back answers — several are one answer, and an incidental mention
+ * counts. The back-links are every internal link in the corpus, resolved with
+ * `resolveLink` and the same `options`, indexed on first evaluation.
+ *
+ * `examined` is the selected links: an empty selection fails with the
+ * zero-examined finding. A link that cannot answer — a frozen record, a file
+ * outside the corpus, a missing target — is one finding naming its cause, on
+ * the declaring link's line, with its remedy as the suggestion.
+ */
+export function linkedBack(corpus, options = {}) {
+    let index;
+    let byBasename;
+    return {
+        description: 'be linked back by their targets',
+        evaluate: (links, ctx) => {
+            index ??= linksFrom(corpus, options);
+            const out = [];
+            for (const link of links) {
+                const target = resolveLink(link, corpus, options);
+                if (target.kind === 'document' && index.get(target.path)?.has(link.doc.relPath) === true) {
+                    continue;
+                }
+                const cause = unanswered(link, target);
+                byBasename ??= basenameIndex(corpus);
+                out.push(mdViolation({
+                    element: `${link.doc.relPath} → ${cause.target}`,
+                    file: link.doc.file,
+                    line: link.line,
+                    message: cause.message,
+                    sourceText: link.doc.text,
+                    fix: target.kind === 'missing' ? movedLinkFix(link, byBasename) : undefined,
+                    context: { ...ctx, suggestion: cause.suggestion },
+                }));
+            }
+            return out;
+        },
+    };
+}
+//# sourceMappingURL=linked-back.js.map

package/dist/conditions/linked-back.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"linked-back.js","sourceRoot":"","sources":["../../src/conditions/linked-back.ts"],"names":[],"mappings":"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"}

package/dist/conditions/resolve.d.ts

@@ -1,55 +1,23 @@
 import type { Condition } from '@nielspeter/eess';
 import type { Corpus } from '../corpus.js';
 import type { MdLink } from '../model/links.js';
+import { type LinkResolveOptions } from '../model/resolve-link.js';
 /**
  * Options for `linkResolves` — how a link URL is matched against the repo tree.
- * Covers static-site conventions (VitePress, Docusaurus, MkDocs, GitBook…)
- * generically instead of naming any tool: extensionless links resolve by
- * trying extensions and/or a directory index file.
+ * Defined beside `resolveLink` (`model/resolve-link.ts`), the one resolver both
+ * share (plan 0404); re-exported here so existing imports keep working.
  */
-export interface LinkResolveOptions {
-    /**
-     * Extensions to try when the URL as written doesn't resolve, e.g. `['.md']`
-     * for sites that link `./guide` meaning `./guide.md`. Tried in order.
-     */
-    readonly tryExtensions?: readonly string[];
-    /**
-     * Directory index filename to try, e.g. `'index.md'` for sites where
-     * `./guide/` (or `./guide`) means `./guide/index.md`.
-     */
-    readonly tryIndex?: string;
-    /**
-     * Content root for site-absolute links (leading `/`). Static-site generators
-     * resolve `/page` against the site's content root, not the repo root — e.g.
-     * `rootDir: 'docs'` makes `/guide` mean `docs/guide(.md)`. Repo-root
-     * resolution is still tried first, so plain repo-absolute links keep working.
-     */
-    readonly rootDir?: string;
-    /**
-     * Resolve a link naming a real directory (`./fixed/` or `./fixed`, with or
-     * without the trailing slash — both forms occur in this repo's own corpus)
-     * even when it has no index file. Correct for a repo-hosted corpus (GitHub,
-     * GitLab render a directory link as its listing); wrong for a static-site
-     * corpus where a bare directory is not itself a page — there, reach for
-     * {@link tryIndex} instead. Off by default: this widens what "resolves"
-     * means, and a link resolving that shouldn't is a false green, not a
-     * convenience. Default `false`.
-     *
-     * A link naming a real directory always wins over an unrelated typo — if
-     * `./foo` was meant as a deleted `foo.md` but a directory `foo/` happens to
-     * exist at that path, it resolves as the directory. Not a new failure mode:
-     * GitHub renders that link as the directory listing too, so this only
-     * closes the gap between the gate and what the link actually does when
-     * followed, it doesn't introduce a new way to be surprised by it.
-     */
-    readonly resolveDirectories?: boolean;
-}
+export type { LinkResolveOptions } from '../model/resolve-link.js';
 /**
  * Condition: every (internal) link resolves to a file in the corpus's repo tree.
  * Closes over the `Corpus` for the file index. External links and pure anchors
  * are skipped. `options` adds extensionless-link resolution (`tryExtensions`,
  * `tryIndex`) for static-site corpora, and directory resolution
  * (`resolveDirectories`) for repo-hosted ones.
+ *
+ * Resolution is `resolveLink`'s (plan 0404): this condition only decides which
+ * of its cases count as resolved — a loaded document, an existing file outside
+ * the corpus, and (with `resolveDirectories`) a directory.
  */
 export declare function linkResolves(corpus: Corpus, options?: LinkResolveOptions): Condition<MdLink>;
 //# sourceMappingURL=resolve.d.ts.map

package/dist/conditions/resolve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/conditions/resolve.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAW,MAAM,kBAAkB,CAAA;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAG/C;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;CACtC;AA8DD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,SAAS,CAAC,MAAM,CAAC,CAyEhG"}
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/conditions/resolve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE/C,OAAO,EAKL,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAA;AAEjC;;;;GAIG;AACH,YAAY,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAElE;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,SAAS,CAAC,MAAM,CAAC,CA+ChG"}