@nielspeter/eess-md 0.8.0 → 0.10.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 —
@@ -168,6 +170,16 @@ adrEnforcement(c, {
 })
 ```
 
+## Code blocks that parse: `parseCodeBlocks()` + `codeBlocks()`
+
+Check every fenced block of one language with a parser you name. eess-md owns the loop and the
+evidence, and never loads a parser itself. `parseCodeBlocks(corpus, { language, parser })` is the
+one async call; `codeBlocks(parsed).should().parse().check()` is an ordinary synchronous rule over
+what it parsed. A parser names itself and declares canaries it must reject, and every way it can
+fail (a throw, a hang past its budget, a malformed or missing verdict, a canary it accepts) is one
+unsuppressable finding, never a pass. The port and the failure table are in
+[the Markdown dialect's docs](../../docs/markdown.md#code-blocks-that-parse).
+
 ## `@nielspeter/eess-md/internal` is not API
 
 | Specifier                      | What it is                                                                                                                          |

package/dist/builders/code-blocks.d.ts

@@ -0,0 +1,37 @@
+import { RuleBuilder, type CollectResult } from '@nielspeter/eess';
+import { type ParsedCodeBlock, type ParsedCodeBlocks } from '../model/code-block-parse.js';
+/** The instrument's identity: one constant, so several rules over one failed parse dedupe to one. */
+export declare const CODE_BLOCK_PARSER_INSTRUMENT = "eess-md: code-block parser";
+/**
+ * Rule builder over the blocks `parseCodeBlocks` parsed. Its elements are the parsed set, so a
+ * predicate can only narrow what a parser saw, never select a block no parser saw.
+ *
+ * No rule surface here is async: the parse happens once in `parseCodeBlocks`, and this builder reads
+ * its facts synchronously (plan 0412; an async `check()` would need an ADR).
+ */
+export declare class CodeBlockRuleBuilder extends RuleBuilder<ParsedCodeBlock, ParsedCodeBlocks> {
+    constructor(parsed: ParsedCodeBlocks);
+    protected getElements(): ParsedCodeBlock[];
+    /** No Markdown file loaded at all outranks everything, `.expectEmpty()` included (ADR-010). */
+    protected sourceEmpty(): boolean;
+    /** When near-miss tags are why nothing was examined, send the author to the spelling. */
+    protected deadGlobDiagnosis(): string | undefined;
+    /** The kernel's verdict, plus the instrument finding once per rule when the parser failed. */
+    protected collectViolations(): CollectResult;
+    /** Filter to blocks in documents whose repo-relative path matches the file glob. */
+    resideInFile(glob: string): this;
+    /** Filter to blocks in documents whose repo-relative path matches the folder glob. */
+    resideInFolder(glob: string): this;
+    /** Assert every selected block parses: an `invalid` or `unrecognised` verdict is a finding. */
+    parse(): this;
+}
+/**
+ * Entry point: rules over the code blocks one `parseCodeBlocks` call parsed.
+ *
+ * ```ts
+ * const parsed = await parseCodeBlocks(corpus, { language: 'mermaid', parser })
+ * codeBlocks(parsed).should().parse().check()
+ * ```
+ */
+export declare function codeBlocks(parsed: ParsedCodeBlocks): CodeBlockRuleBuilder;
+//# sourceMappingURL=code-blocks.d.ts.map

package/dist/builders/code-blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-blocks.d.ts","sourceRoot":"","sources":["../../src/builders/code-blocks.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,WAAW,EAGX,KAAK,aAAa,EAGnB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,8BAA8B,CAAA;AAIrC,qGAAqG;AACrG,eAAO,MAAM,4BAA4B,+BAA+B,CAAA;AAiExE;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,WAAW,CAAC,eAAe,EAAE,gBAAgB,CAAC;gBAC1E,MAAM,EAAE,gBAAgB;IAYpC,SAAS,CAAC,WAAW,IAAI,eAAe,EAAE;IAI1C,+FAA+F;cAC5E,WAAW,IAAI,OAAO;IAIzC,yFAAyF;cACtE,iBAAiB,IAAI,MAAM,GAAG,SAAS;IAS1D,8FAA8F;cAC3E,iBAAiB,IAAI,aAAa;IAqBrD,oFAAoF;IACpF,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIhC,sFAAsF;IACtF,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIlC,+FAA+F;IAC/F,KAAK,IAAI,IAAI;CAGd;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,oBAAoB,CAEzE"}

package/dist/builders/code-blocks.js

@@ -0,0 +1,143 @@
+import { ArchConfigError, RuleBuilder, collectResult, } from '@nielspeter/eess';
+import { describeNearMisses, isParsedCodeBlocks, } from '../model/code-block-parse.js';
+import { resideInFile, resideInFolder } from '../predicates/document.js';
+import { mdViolation } from '../model/violation.js';
+/** The instrument's identity: one constant, so several rules over one failed parse dedupe to one. */
+export const CODE_BLOCK_PARSER_INSTRUMENT = 'eess-md: code-block parser';
+const onDocument = (p) => ({
+    description: p.description,
+    test: (b) => p.test(b.doc),
+});
+function bodyLineCount(value) {
+    return value === '' ? 0 : value.split('\n').length;
+}
+/** Condition: every selected block's verdict is `valid`. */
+function parse(parsed) {
+    const by = `${parsed.parser.name} ${parsed.parser.version}`;
+    return {
+        description: `parse with ${by}`,
+        evaluate: (elements, ctx) => elements.flatMap((e) => {
+            const v = e.verdict;
+            // No verdict is never a pass: it exists only beside a failure, which the builder reports.
+            // `parseCodeBlocks` guarantees that pairing by construction (every path yields one verdict
+            // per text or a failure), so no second check here: one that can never fire proves nothing.
+            if (v === null || v.outcome === 'valid')
+                return [];
+            const where = `${e.doc.relPath}:${String(e.block.line)}`;
+            if (v.outcome === 'unrecognised') {
+                return [
+                    {
+                        ...mdViolation({
+                            element: where,
+                            file: e.doc.file,
+                            line: e.block.line,
+                            message: `${by} does not recognise this \`${parsed.language}\` block: ${v.message}`,
+                            sourceText: e.doc.text,
+                            context: ctx,
+                        }),
+                        suggestion: v.remedy,
+                    },
+                ];
+            }
+            const lines = bodyLineCount(e.block.value);
+            const inner = v.line;
+            const inside = inner !== null && inner >= 1 && inner <= lines;
+            const line = inside ? e.block.line + inner : e.block.line;
+            const note = inside
+                ? ''
+                : inner === null
+                    ? ' (the line inside the block is unknown)'
+                    : ` (the parser gave line ${String(inner)} for a ${String(lines)}-line block)`;
+            return [
+                {
+                    ...mdViolation({
+                        element: where,
+                        file: e.doc.file,
+                        line,
+                        message: `this \`${parsed.language}\` block does not parse with ${by}: ${v.message}${note}`,
+                        sourceText: e.doc.text,
+                        context: ctx,
+                    }),
+                    suggestion: v.remedy,
+                },
+            ];
+        }),
+    };
+}
+/**
+ * Rule builder over the blocks `parseCodeBlocks` parsed. Its elements are the parsed set, so a
+ * predicate can only narrow what a parser saw, never select a block no parser saw.
+ *
+ * No rule surface here is async: the parse happens once in `parseCodeBlocks`, and this builder reads
+ * its facts synchronously (plan 0412; an async `check()` would need an ADR).
+ */
+export class CodeBlockRuleBuilder extends RuleBuilder {
+    constructor(parsed) {
+        super(parsed);
+        if (!isParsedCodeBlocks(parsed)) {
+            throw new ArchConfigError('codeBlocks', "codeBlocks() takes the object this copy of eess-md's parseCodeBlocks() returned. A " +
+                'hand-built object would let any verdict through unchecked. If you built it with ' +
+                'parseCodeBlocks, two copies of @nielspeter/eess-md are installed; dedupe them.');
+        }
+    }
+    getElements() {
+        return [...this.project.blocks];
+    }
+    /** No Markdown file loaded at all outranks everything, `.expectEmpty()` included (ADR-010). */
+    sourceEmpty() {
+        return this.project.documentsLoaded === 0;
+    }
+    /** When near-miss tags are why nothing was examined, send the author to the spelling. */
+    deadGlobDiagnosis() {
+        const { blocks, nearMisses, language } = this.project;
+        if (blocks.length > 0 || nearMisses.length === 0)
+            return undefined;
+        return (`no block is tagged \`${language}\`, and the tag is matched exactly. These are not read: ` +
+            `${describeNearMisses(nearMisses)}. Retag them \`${language}\`.`);
+    }
+    /** The kernel's verdict, plus the instrument finding once per rule when the parser failed. */
+    collectViolations() {
+        const base = super.collectViolations();
+        const failure = this.project.failure;
+        if (failure === null)
+            return base;
+        const { name, version } = this.project.parser;
+        const instrument = {
+            rule: CODE_BLOCK_PARSER_INSTRUMENT,
+            ruleId: CODE_BLOCK_PARSER_INSTRUMENT,
+            element: `${name}@${version}`,
+            file: '',
+            line: 0,
+            message: `the ${this.project.language} blocks were not checked: ${failure.cause.replace(/\.$/, '')}. No block of the ` +
+                `language has a verdict, so this rule cannot pass.`,
+            suggestion: failure.remedy,
+            bypassFilters: true,
+        };
+        // The kernel's evidence, passed through whole, so no field it adds later can be dropped here.
+        return collectResult([...base, instrument], base);
+    }
+    /** Filter to blocks in documents whose repo-relative path matches the file glob. */
+    resideInFile(glob) {
+        return this.addPredicate(onDocument(resideInFile(glob)));
+    }
+    /** Filter to blocks in documents whose repo-relative path matches the folder glob. */
+    resideInFolder(glob) {
+        return this.addPredicate(onDocument(resideInFolder(glob)));
+    }
+    /** Assert every selected block parses: an `invalid` or `unrecognised` verdict is a finding. */
+    parse() {
+        return this.addCondition(parse(this.project));
+    }
+}
+/**
+ * Entry point: rules over the code blocks one `parseCodeBlocks` call parsed.
+ *
+ * ```ts
+ * const parsed = await parseCodeBlocks(corpus, { language: 'mermaid', parser })
+ * codeBlocks(parsed).should().parse().check()
+ * ```
+ */
+export function codeBlocks(parsed) {
+    return new CodeBlockRuleBuilder(parsed);
+}
+//# sourceMappingURL=code-blocks.js.map

package/dist/builders/code-blocks.js.map

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

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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"}