@timiagama/ecr 0.0.1 → 0.1.0

package/dist/per-document-visitor.js

@@ -0,0 +1,1032 @@
+/**
+ * Per-Document Visitor
+ *
+ * Orchestrates all four ECR rules (ECR101--ECR104) over a single Markdown
+ * document, producing a composite {@link LintResult}.
+ *
+ * This is the integration layer that:
+ *   1. Parses Markdown text into an AST using `unified` + `remark-parse`
+ *   2. Walks the AST and dispatches nodes to the appropriate rules
+ *   3. Manages the rule initialisation dependency chain:
+ *      - ECR101 must complete before ECR102/ECR103 can start
+ *      - ECR103 must complete before ECR104 can start (to provide declared DocIDs)
+ *      - If ECR101 fails, downstream rules are skipped entirely
+ *   4. Filters text nodes: excludes those inside `code`, `inlineCode`, `html`,
+ *      or link URL contexts before feeding to ECR104
+ *   5. Tracks the current section context (heading identifier) for ECR104
+ *   6. Feeds list items within the References section to ECR103
+ *   7. Finalises all rules and assembles the composite {@link LintResult}
+ *
+ * Spec references:
+ *   - 1#8   -- Visitor and State Model
+ *   - 1#11.1 -- Pass 1: Per-Document Parse, Validate, Extract
+ *   - 1#9.3 -- Document Identity Rule [ECR101]
+ *   - 1#9.4 -- Section Structure Rules [ECR102]
+ *   - 1#9.5 -- Inline Reference Rules [ECR104]
+ *   - 1#9.6 -- References Section Rules [ECR103]
+ *   - 1#10.2 -- LintResult
+ *   - 1#10.4 -- ExtractedDocument
+ */
+// ---------------------------------------------------------------------------
+// Runtime imports (value imports for classes and functions)
+// ---------------------------------------------------------------------------
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+// ---------------------------------------------------------------------------
+// Value imports for rule classes and grammar
+// ---------------------------------------------------------------------------
+import { DocumentIdentityRule } from './document-identity-rule.js';
+import { SectionHierarchyRule } from './section-hierarchy-rule.js';
+import { ReferencesSectionRule } from './references-section-rule.js';
+import { InlineReferenceRule } from './inline-reference-rule.js';
+import { IdentifierGrammar } from './identifier-grammar.js';
+// ---------------------------------------------------------------------------
+// A document the parser could not read
+// ---------------------------------------------------------------------------
+/** Rule identifier reported when a document cannot be parsed at all. */
+export const UNPARSABLE_DOCUMENT_RULE_ID = 'document/unparsable';
+/** The `data.cause` of that diagnostic. */
+export const UNPARSABLE_DOCUMENT_CAUSE = 'unparsable-document';
+/** How much of the parser's own account of the failure to repeat. */
+const UNPARSABLE_REASON_LIMIT = 200;
+// ---------------------------------------------------------------------------
+// Excluded ancestor node types for ECR104 filtering
+// ---------------------------------------------------------------------------
+/**
+ * MDAST node types whose descendant text nodes must be excluded from
+ * ECR104 inline reference detection.
+ *
+ * Per 1#9.5, text nodes inside code blocks, inline code, and HTML
+ * elements are not valid candidates for inline reference detection.
+ */
+export const EXCLUDED_ANCESTOR_NODE_TYPES = new Set([
+    'code',
+    'inlineCode',
+    'html',
+]);
+/**
+ * MDAST node types whose children form one inline run: the text a reader
+ * sees, recognised as a whole (1#9.5 rule 1). Headings are excluded, since
+ * heading text is not subject to inline reference detection.
+ */
+const INLINE_RUN_NODE_TYPES = new Set([
+    'paragraph',
+    'tableCell',
+]);
+/**
+ * Inline HTML a reader sees as a line break: an opening `br` tag in any case,
+ * whatever follows its name -- `<br>`, `<BR/>`, `<br class="x">`. It separates
+ * the words either side of it. Other inline HTML does not, so it is
+ * transparent to recognition (1#9.5 rule 1).
+ *
+ * Only the tag's name is read. The parser has already delimited the whole
+ * tag as one node, so its attributes need no second parse here; matching
+ * them again assumed every `>` closed the tag, and `<br title="x > y">` was
+ * taken for transparent HTML.
+ */
+const LINE_BREAK_HTML = /^<br(?=[\s/>])/i;
+// ---------------------------------------------------------------------------
+// Per-Document Visitor class
+// ---------------------------------------------------------------------------
+/**
+ * Orchestrates all four ECR rules (ECR101--ECR104) over a single Markdown
+ * document and produces a composite {@link LintResult}.
+ *
+ * The visitor is stateless between calls to {@link lint}. Each invocation
+ * produces a fresh result with no side effects on the visitor instance.
+ *
+ * The visitor creates its own {@link IdentifierGrammar} instance internally
+ * and manages the rule initialisation dependency chain:
+ * - ECR101 (Document Identity) runs first on all headings
+ * - If ECR101 produces a valid DocID, ECR102 (Section Hierarchy) and
+ *   ECR103 (References Section) are initialised and fed their respective nodes
+ * - After ECR103 finalises, the set of declared DocIDs is extracted and
+ *   used to initialise ECR104 (Inline Reference)
+ * - If ECR101 fails (no valid DocID), the result is returned early with
+ *   `ok=false` and no `extracted` field
+ *
+ * Usage:
+ * ```ts
+ * const visitor = new PerDocumentVisitor({
+ *   uri: 'file:///docs/3.1.md',
+ *   version: 1,
+ * });
+ *
+ * const result: LintResult = visitor.lint('# 3.1 - My Document\n\n## References\n- 8.1 - ...');
+ * ```
+ *
+ * @example
+ * ```ts
+ * const visitor = new PerDocumentVisitor({ uri: 'file:///docs/5.1.md' });
+ * const result: LintResult = visitor.lint(markdownText);
+ *
+ * if (result.ok) {
+ *   console.log('Document is valid:', result.extracted?.docId);
+ * } else {
+ *   console.log('Diagnostics:', result.diagnostics);
+ * }
+ * ```
+ */
+export class PerDocumentVisitor {
+    /**
+     * The opaque, host-provided URI identifying the document being validated.
+     */
+    uri;
+    /**
+     * Optional version tag for the document instance.
+     */
+    version;
+    /**
+     * The {@link IdentifierGrammar} instance shared across all rules
+     * within a single visitor. Created once during construction.
+     */
+    grammar;
+    /**
+     * Constructs a new Per-Document Visitor.
+     *
+     * Creates an internal {@link IdentifierGrammar} instance for use
+     * across all rule evaluations performed by this visitor.
+     *
+     * @param options - Configuration including the document URI and optional version
+     */
+    constructor(options) {
+        this.uri = options.uri;
+        this.version = options.version;
+        this.grammar = new IdentifierGrammar();
+    }
+    /**
+     * Lints a single Markdown document and produces a composite {@link LintResult}.
+     *
+     * Each call is stateless: the visitor creates fresh rule instances,
+     * parses the Markdown text into an AST, walks the AST to feed nodes
+     * to the appropriate rules, finalises all rules, and assembles the result.
+     *
+     * The orchestration proceeds in phases:
+     * 1. Parse the Markdown text into an MDAST {@link MdastRoot} node
+     * 2. First pass: walk headings and list items for ECR101, ECR102, ECR103
+     * 3. If ECR101 fails (no valid DocID), return early with `ok=false`
+     * 4. Second pass: walk text nodes for ECR104 (with ancestor filtering
+     *    and section context tracking)
+     * 5. Assemble the composite {@link LintResult} from all rule results
+     *
+     * @param markdownText - The raw Markdown text of the document to lint
+     * @returns The composite lint result including diagnostics and, when a valid
+     *          DocID is recovered, extracted structural artefacts
+     */
+    lint(markdownText) {
+        let root;
+        try {
+            root = this.parseMarkdown(markdownText);
+        }
+        catch (error) {
+            return this.reportUnparsable(error);
+        }
+        const passOneResult = this.executeHeadingsAndReferencesPass(root, markdownText);
+        // If ECR101 failed (no valid identity), return early
+        if (passOneResult.identityResult.identity === undefined) {
+            return this.assembleLintResult(passOneResult.identityResult, undefined, undefined, undefined);
+        }
+        // ECR101 succeeded -- extract declaredDocIds from ECR103
+        const referencesResult = passOneResult.referencesResult;
+        const referencesForExtraction = referencesResult !== undefined ? referencesResult.references : [];
+        const declaredDocIds = this.extractDeclaredDocIds(referencesForExtraction);
+        // Run ECR104
+        const inlineResult = this.executeInlineReferencesPass(root, passOneResult.identityResult.identity.docId, declaredDocIds, markdownText);
+        return this.assembleLintResult(passOneResult.identityResult, passOneResult.sectionsResult, passOneResult.referencesResult, inlineResult.inlineResult);
+    }
+    // -------------------------------------------------------------------------
+    // Private: Markdown parsing
+    // -------------------------------------------------------------------------
+    /**
+     * Parses raw Markdown text into an MDAST {@link MdastRoot} node.
+     *
+     * Uses `unified` with `remark-parse` to produce a standards-compliant
+     * MDAST tree with positional metadata attached to all nodes.
+     *
+     * The `unified().use(remarkParse).parse()` call returns a type that
+     * cannot be directly assigned to our local {@link MdastRoot} interface
+     * because `mdast` types are not importable as a module specifier in this
+     * project. The cast via `unknown` is safe because `remark-parse` always
+     * produces an MDAST Root node at runtime.
+     *
+     * @param markdownText - The raw Markdown text to parse
+     * @returns The parsed MDAST root node
+     */
+    parseMarkdown(markdownText) {
+        const root = unified()
+            .use(remarkParse)
+            .parse(markdownText);
+        return root;
+    }
+    /**
+     * Reports a document the parser could not read.
+     *
+     * The parser walks a document's structure by recursion, inside a package
+     * this project does not control, so a deeply nested link label or image
+     * description can end the parse with a stack overflow. That must be one
+     * document's error, reported like any other, and never a crash that stops
+     * a corpus part way and leaves the rest unvalidated.
+     *
+     * @param error - What the parser threw
+     * @returns A failing result carrying one error diagnostic
+     */
+    reportUnparsable(error) {
+        const reason = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+        return {
+            input: this.buildLintInput(),
+            ok: false,
+            diagnostics: [
+                {
+                    severity: 'error',
+                    ruleId: UNPARSABLE_DOCUMENT_RULE_ID,
+                    message: `Document could not be parsed, so none of it was validated ` +
+                        `(${reason.slice(0, UNPARSABLE_REASON_LIMIT)}). Deeply nested Markdown is the ` +
+                        `usual cause, because parsing it recurses.`,
+                    uri: this.uri,
+                    data: { cause: UNPARSABLE_DOCUMENT_CAUSE },
+                },
+            ],
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Private: First pass -- headings, sections, and references
+    // -------------------------------------------------------------------------
+    /**
+     * Executes the first AST traversal pass: headings, sections, and references.
+     *
+     * This pass walks the AST in document order and:
+     * - Feeds every heading node to ECR101 (`DocumentIdentityRule.evaluateHeading`)
+     * - Finalises ECR101 to determine whether a valid DocID was recovered
+     * - If a valid DocID is recovered:
+     *   - Registers the root H1 heading with ECR102
+     *     (`SectionHierarchyRule.registerRootHeading`)
+     *   - Feeds headings with depth \>= 2 to ECR102
+     *     (`SectionHierarchyRule.evaluateHeading`)
+     *   - Feeds all headings to ECR103
+     *     (`ReferencesSectionRule.evaluateHeading`)
+     *   - Feeds list items within the References section to ECR103
+     *     (`ReferencesSectionRule.evaluateListItem`)
+     *   - Finalises ECR102 and ECR103
+     * - If no valid DocID is recovered, ECR102 and ECR103 are skipped
+     *
+     * The pass is structured so that all heading nodes are collected first
+     * for ECR101, then the collected headings are replayed for ECR102 and ECR103.
+     *
+     * @param root - The parsed MDAST root node
+     * @param sourceText - The document's raw Markdown, for the heading source-form check of 1#9.11
+     * @returns The intermediate result from the headings and references pass
+     */
+    executeHeadingsAndReferencesPass(root, sourceText) {
+        // Phase 1: Collect all headings and feed to ECR101
+        const collectedHeadings = [];
+        this.collectHeadings(root, collectedHeadings);
+        const identityRule = new DocumentIdentityRule({
+            uri: this.uri,
+            grammar: this.grammar,
+            sourceText,
+        });
+        for (const headingData of collectedHeadings) {
+            identityRule.evaluateHeading(headingData);
+        }
+        const identityResult = identityRule.finalise();
+        // If ECR101 failed, return early -- no ECR102 or ECR103
+        if (identityResult.identity === undefined) {
+            return { identityResult };
+        }
+        // Phase 2: ECR101 succeeded -- initialise ECR102 and ECR103
+        const docId = identityResult.identity.docId;
+        const sectionHierarchyRule = new SectionHierarchyRule({
+            uri: this.uri,
+            docId,
+            grammar: this.grammar,
+            sourceText,
+        });
+        const referencesSectionRule = new ReferencesSectionRule({
+            uri: this.uri,
+            docId,
+            grammar: this.grammar,
+            sourceText,
+        });
+        // Feed collected headings to ECR102 and ECR103
+        for (const headingData of collectedHeadings) {
+            // ECR102: register root H1 or evaluate sub-headings.
+            // The `## References` heading is a structural heading owned by ECR103,
+            // not a numbered section heading — it must be excluded from ECR102
+            // to avoid a spurious "not a valid SectionID" diagnostic.
+            if (headingData.depth === 1) {
+                sectionHierarchyRule.registerRootHeading(headingData);
+            }
+            else if (!this.tellReferencesHeading(headingData)) {
+                sectionHierarchyRule.evaluateHeading(headingData);
+            }
+            // ECR103: evaluate all headings for References heading detection
+            referencesSectionRule.evaluateHeading(headingData);
+        }
+        // Phase 3: Walk the AST again to feed list items to ECR103
+        // after the References heading has been detected
+        this.feedListItemsToReferencesRule(root, referencesSectionRule);
+        // Finalise ECR102 and ECR103
+        const sectionsResult = sectionHierarchyRule.finalise();
+        const referencesResult = referencesSectionRule.finalise();
+        return {
+            identityResult,
+            sectionsResult,
+            referencesResult,
+        };
+    }
+    /**
+     * Collects all heading nodes from the AST into the provided array.
+     *
+     * Walks the AST depth-first in document order, extracting
+     * {@link HeadingNodeData} from every node with `type === 'heading'`.
+     *
+     * @param node - The root of the walk
+     * @param headings - The accumulator array for collected heading data
+     */
+    collectHeadings(node, headings) {
+        const pending = [node];
+        while (pending.length > 0) {
+            const current = pending.pop();
+            if (current === undefined) {
+                break;
+            }
+            if (current.type === 'heading' && current.depth !== undefined) {
+                headings.push(this.extractHeadingNodeData(current));
+            }
+            PerDocumentVisitor.pushChildren(current, pending);
+        }
+    }
+    /**
+     * Reads a node's plain text: what a reader sees, with the formatting gone.
+     *
+     * @param node - The node to read
+     * @returns Its text, and its descendants' text, in order
+     */
+    static showNodeText(node) {
+        // What `mdast-util-to-string` returns, gathered over a stack instead of
+        // by recursion: a node's own value, else an image's alternative text,
+        // else its children's text in order. That package recurses, so a heading
+        // of a few thousand nested emphasis spans -- which costs an author two
+        // characters a level -- ended the process inside it.
+        const parts = [];
+        const pending = [node];
+        while (pending.length > 0) {
+            const current = pending.pop();
+            if (current === undefined) {
+                break;
+            }
+            if (current.value !== undefined) {
+                parts.push(current.value);
+                continue;
+            }
+            if (typeof current.alt === 'string' && current.alt.length > 0) {
+                parts.push(current.alt);
+                continue;
+            }
+            PerDocumentVisitor.pushChildren(current, pending);
+        }
+        return parts.join('');
+    }
+    /**
+     * Puts a node's children on a walk's stack so that they come off it in
+     * document order.
+     *
+     * Every walk over a document's nodes keeps its own stack rather than
+     * calling itself, because nesting in Markdown costs the author almost
+     * nothing: a few thousand nested blockquotes, or nested bold spans, fit in
+     * a few kilobytes, and recursion over them exhausts the call stack and
+     * takes the process with it. A stack on the heap has no such limit.
+     *
+     * @param node - The node whose children are to be walked
+     * @param pending - The stack to push onto, from which nodes are taken with `pop`
+     */
+    static pushChildren(node, pending) {
+        const children = node.children;
+        if (children === undefined) {
+            return;
+        }
+        for (let index = children.length - 1; index >= 0; index -= 1) {
+            const child = children[index];
+            if (child !== undefined) {
+                pending.push(child);
+            }
+        }
+    }
+    /**
+     * Finds the References section and feeds its placement and entries to ECR103.
+     *
+     * The `## References` heading is looked for anywhere in the tree, not only
+     * among the root's children. A section nested in a blockquote or a list
+     * item used to be passed over, so its entries were silently discarded and
+     * the document reported as having an empty References section. It is now
+     * found, reported as misplaced (1#9.11 rule 3), and its entries still read.
+     *
+     * The entries are the items of the list that immediately follows the
+     * heading, or of a list that opens the container immediately following it
+     * -- which is also a placement violation.
+     *
+     * @param root - The parsed MDAST root node
+     * @param referencesSectionRule - The ECR103 rule instance to feed
+     */
+    feedListItemsToReferencesRule(root, referencesSectionRule) {
+        if (!referencesSectionRule.tellReferencesHeadingDetected()) {
+            return;
+        }
+        const section = this.findReferencesSection(root);
+        if (section === undefined) {
+            return;
+        }
+        const next = section.siblings[section.index + 1];
+        const list = this.findReferencesList(next);
+        const nested = section.siblings !== root.children || (list !== undefined && list !== next);
+        referencesSectionRule.evaluateSectionPlacement(this.mapPosition(section.heading.position), nested);
+        for (const listItemNode of list?.children ?? []) {
+            if (listItemNode.type === 'listItem') {
+                referencesSectionRule.evaluateListItem(this.extractListItemNodeData(listItemNode));
+            }
+        }
+    }
+    /**
+     * Finds the list holding the References entries, given the node after the
+     * heading: that node itself, or a list opening the container it is, at any
+     * depth of nesting.
+     *
+     * Looking one container deep lost `> > - 8.1 - …`: the list was never
+     * found, so its entries were discarded and the section reported as empty.
+     *
+     * @param next - The node immediately following the `## References` heading
+     * @returns The entries' list, or `undefined` when there is none
+     */
+    findReferencesList(next) {
+        let candidate = next;
+        while (candidate !== undefined && candidate.type !== 'heading') {
+            if (candidate.type === 'list') {
+                return candidate;
+            }
+            candidate = candidate.children?.[0];
+        }
+        return undefined;
+    }
+    /**
+     * Finds the first `## References` heading in document order, at any depth.
+     *
+     * @param node - The node to search from
+     * @returns The heading and its position among its siblings, or `undefined`
+     */
+    findReferencesSection(node) {
+        // Each frame is a list of siblings and how far through it the walk is, so
+        // that a match can report the position among its siblings that the caller
+        // needs. Depth-first and pre-order, as the recursive form was.
+        const frames = [{ children: node.children ?? [], index: 0 }];
+        while (frames.length > 0) {
+            const frame = frames.pop();
+            if (frame === undefined) {
+                break;
+            }
+            const child = frame.children[frame.index];
+            if (child === undefined) {
+                // These siblings are exhausted, so the frame is not put back.
+                continue;
+            }
+            // The rest of these siblings come after everything beneath this child,
+            // so they go back on the stack before it.
+            frames.push({ children: frame.children, index: frame.index + 1 });
+            if (child.type === 'heading' && this.tellReferencesHeading(this.extractHeadingNodeData(child))) {
+                return { heading: child, siblings: frame.children, index: frame.index };
+            }
+            frames.push({ children: child.children ?? [], index: 0 });
+        }
+        return undefined;
+    }
+    // -------------------------------------------------------------------------
+    // Private: Second pass -- inline references (ECR104)
+    // -------------------------------------------------------------------------
+    /**
+     * Executes the second AST traversal pass: inline reference detection.
+     *
+     * This pass walks the AST in document order using a custom recursive
+     * traversal that tracks ancestor node types and:
+     * - Tracks the current section context (the most recently encountered
+     *   heading identifier), starting with the DocID before any H2 heading
+     * - For each text node encountered, checks whether the node's ancestor
+     *   chain includes any excluded node types (`code`, `inlineCode`, `html`)
+     * - Text nodes whose ancestors include excluded types are skipped
+     * - Valid text nodes are fed to ECR104
+     *   (`InlineReferenceRule.evaluateTextNode`) with the current
+     *   section context
+     * - After traversal, ECR104 is finalised
+     *
+     * @param root - The parsed MDAST root node
+     * @param docId - The document's established DocID
+     * @param declaredDocIds - The set of DocIDs declared in the References section
+     * @param sourceText - The document's raw Markdown, for the source-form checks of 1#9.11
+     * @returns The intermediate result from the inline references pass
+     */
+    executeInlineReferencesPass(root, docId, declaredDocIds, sourceText) {
+        const inlineReferenceRule = new InlineReferenceRule({
+            uri: this.uri,
+            docId,
+            grammar: this.grammar,
+            declaredDocIds,
+            sourceText,
+        });
+        // Track the current section context -- starts with the DocID.
+        // The mutable wrapper allows the recursive walk callback to update
+        // the section context as headings are encountered.
+        const sectionContext = { current: docId };
+        // Walk the AST recursively, tracking ancestor types for exclusion filtering.
+        // When a heading is encountered, update the section context.
+        // When a text node is encountered (not excluded by ancestors), feed to ECR104.
+        this.walkNodesForInlineReferences(root, sectionContext, inlineReferenceRule);
+        const inlineResult = inlineReferenceRule.finalise();
+        return { inlineResult };
+    }
+    /**
+     * Walks the AST to find inline runs for ECR104, tracking whether an
+     * excluded ancestor encloses the node and updating section context when
+     * headings are encountered.
+     *
+     * A paragraph is handed to ECR104 whole, as one inline run, because a
+     * citation is recognised in the text a reader sees and not one parsed text
+     * node at a time (1#9.5 rule 1). Its children are not walked separately.
+     *
+     * A hand-written depth-first, pre-order walk over an explicit stack: document
+     * order decides which section each run belongs to, and see
+     * {@link PerDocumentVisitor.pushChildren} for why the stack is not the call
+     * stack. Exclusion is carried down as one flag, because a node is excluded
+     * exactly when some ancestor's type is, so nothing is gained by keeping the
+     * ancestors themselves.
+     *
+     * @param root - The root of the walk
+     * @param sectionContext - Mutable wrapper holding the current section context
+     * @param inlineReferenceRule - The ECR104 rule instance to feed runs to
+     */
+    walkNodesForInlineReferences(root, sectionContext, inlineReferenceRule) {
+        const pending = [{ node: root, excluded: false }];
+        while (pending.length > 0) {
+            const entry = pending.pop();
+            if (entry === undefined) {
+                break;
+            }
+            const { node, excluded } = entry;
+            if (node.type === 'heading' && node.depth !== undefined) {
+                sectionContext.current = this.determineSectionContext(PerDocumentVisitor.showNodeText(node), node.depth, sectionContext.current);
+                // Do not walk into heading children for text node extraction;
+                // heading text is not subject to inline reference detection.
+                continue;
+            }
+            if (INLINE_RUN_NODE_TYPES.has(node.type) && node.children !== undefined) {
+                if (!excluded) {
+                    const segments = [];
+                    for (const child of node.children) {
+                        this.collectInlineSegments(child, [], segments);
+                    }
+                    inlineReferenceRule.evaluateInlineRun(segments, sectionContext.current);
+                }
+                continue;
+            }
+            // A text node outside any run is not expected from the parser, but if one
+            // appears it is still evaluated, as a run of its own.
+            if (node.type === 'text' && node.value !== undefined) {
+                if (!excluded) {
+                    const textNodeData = this.extractTextNodeData(node);
+                    inlineReferenceRule.evaluateTextNode(textNodeData, sectionContext.current);
+                }
+                continue;
+            }
+            PerDocumentVisitor.pushInlineWalkChildren(node, excluded, pending);
+        }
+    }
+    /**
+     * Puts a node's children on the inline walk's stack, in document order,
+     * noting whether an excluded ancestor now encloses them.
+     *
+     * @param node - The node whose children are to be walked
+     * @param excluded - Whether an excluded ancestor already encloses the node
+     * @param pending - The stack to push onto
+     */
+    static pushInlineWalkChildren(node, excluded, pending) {
+        const children = node.children;
+        if (children === undefined) {
+            return;
+        }
+        const childrenExcluded = excluded || EXCLUDED_ANCESTOR_NODE_TYPES.has(node.type);
+        for (let index = children.length - 1; index >= 0; index -= 1) {
+            const child = children[index];
+            if (child !== undefined) {
+                pending.push({ node: child, excluded: childrenExcluded });
+            }
+        }
+    }
+    /**
+     * Flattens one inline node into the segments a reader sees, in order.
+     *
+     * Text becomes a `text` segment carrying its position, and inline code a
+     * `code` segment. Formatting contributes its contents, each segment noting
+     * the spans around it. A hard break, an image, and a `<br>` tag become a
+     * `break` of one space, because a reader sees the words either side of them
+     * as separate. Any other inline HTML -- a comment, or a tag such as
+     * `<span>` -- contributes nothing, because it separates nothing:
+     * `60<span>s</span>` reads as `60s`.
+     *
+     * @param node - An inline node
+     * @param wrappers - Types of the formatting spans enclosing it, outermost first
+     * @param segments - Accumulator the segments are appended to
+     */
+    collectInlineSegments(node, wrappers, segments) {
+        const pending = [{ node, wrappers }];
+        while (pending.length > 0) {
+            const entry = pending.pop();
+            if (entry === undefined) {
+                break;
+            }
+            this.collectInlineSegment(entry, segments, pending);
+        }
+    }
+    /**
+     * Turns one inline node into segments, or puts its children on the stack
+     * to be turned into segments in their turn.
+     *
+     * @param entry - The node and the formatting spans enclosing it
+     * @param segments - Accumulator the segments are appended to
+     * @param pending - The walk's stack, which children are pushed onto in document order
+     */
+    collectInlineSegment(entry, segments, pending) {
+        const { node, wrappers } = entry;
+        if (node.type === 'text') {
+            const range = this.mapPosition(node.position);
+            segments.push({
+                kind: 'text',
+                text: node.value ?? '',
+                wrappers,
+                ...(range !== undefined ? { range } : {}),
+            });
+            return;
+        }
+        if (node.type === 'inlineCode') {
+            segments.push({ kind: 'code', text: node.value ?? '', wrappers });
+            return;
+        }
+        if (node.type === 'html' && !LINE_BREAK_HTML.test((node.value ?? '').trim())) {
+            return;
+        }
+        if (node.type !== 'html' && node.children !== undefined) {
+            const inner = [...wrappers, node.type];
+            for (let index = node.children.length - 1; index >= 0; index -= 1) {
+                const child = node.children[index];
+                if (child !== undefined) {
+                    pending.push({ node: child, wrappers: inner });
+                }
+            }
+            return;
+        }
+        segments.push({ kind: 'break', text: ' ', wrappers });
+    }
+    // -------------------------------------------------------------------------
+    // Private: Section context tracking
+    // -------------------------------------------------------------------------
+    /**
+     * Determines the current section context identifier for a given heading.
+     *
+     * The section context is the identifier (DocID or SectionID) of the most
+     * recently encountered numbered heading. Before any H2 heading, the context
+     * is the DocID. After an H2 or deeper heading, the context is the
+     * SectionID of that heading.
+     *
+     * This method extracts the identifier from the heading text using the
+     * grammar's separator convention. If the heading text does not contain
+     * a valid identifier, the previous context is retained.
+     *
+     * @param headingText - The plain text content of the heading node
+     * @param headingDepth - The Markdown heading depth (1--6)
+     * @param currentContext - The current section context before this heading
+     * @returns The updated section context identifier
+     */
+    determineSectionContext(headingText, headingDepth, 
+    // eslint-disable-next-line @typescript-eslint/no-duplicate-type-constituents -- Semantically distinct: context may be DocID or SectionID
+    currentContext) {
+        // Only headings with depth >= 2 can change the section context
+        // (H1 establishes the DocID, which is the initial context)
+        if (headingDepth < 2) {
+            return currentContext;
+        }
+        // A sub-heading carries a SectionID, so it is parsed with the SectionID
+        // heading grammar rather than the DocID one an H1 uses.
+        const parseResult = this.grammar.parseSectionHeading(headingText);
+        if (parseResult.valid) {
+            return parseResult.sectionId;
+        }
+        return currentContext;
+    }
+    // -------------------------------------------------------------------------
+    // Private: References heading detection
+    // -------------------------------------------------------------------------
+    /**
+     * Determines whether a heading is the `## References` structural heading.
+     *
+     * The `## References` heading is owned by ECR103 and should not be
+     * evaluated by ECR102 (Section Hierarchy), because it is not a numbered
+     * section heading and would fail SectionID parsing.
+     *
+     * Per 1#9.6, the References heading is identified by depth === 2
+     * and text content exactly equal to `"References"`.
+     *
+     * @param headingData - The heading node data to check
+     * @returns `true` if the heading is the `## References` heading, `false` otherwise
+     */
+    tellReferencesHeading(headingData) {
+        return headingData.depth === 2 && headingData.text === 'References';
+    }
+    // -------------------------------------------------------------------------
+    // Private: Text extraction from list items
+    // -------------------------------------------------------------------------
+    /**
+     * Extracts the plain text content from a list item AST node.
+     *
+     * Gathers the text of the list item's child nodes into a single plain text
+     * string suitable for feeding to ECR103.
+     *
+     * @param listItemNode - The MDAST list item node to extract text from
+     * @returns The extracted {@link ListItemNodeData} with text and optional range
+     */
+    extractListItemNodeData(listItemNode) {
+        const segments = [];
+        this.collectListItemSegments(listItemNode, segments);
+        const text = segments.map((segment) => segment.text).join('');
+        const range = this.mapPosition(listItemNode.position);
+        const listItemData = {
+            text,
+            segments,
+            ...(range !== undefined ? { range } : {}),
+        };
+        return listItemData;
+    }
+    /**
+     * Classifies a literal node for tracing its text back to the source.
+     *
+     * @param type - The node's MDAST type
+     * @returns `text` for a text node, `code` for inline code, `other` otherwise
+     */
+    static showSegmentKind(type) {
+        if (type === 'text') {
+            return 'text';
+        }
+        return type === 'inlineCode' ? 'code' : 'other';
+    }
+    /**
+     * Splits a list item's text into the parsed nodes it comes from.
+     *
+     * Follows `mdast-util-to-string` exactly -- a node's `value`, else an
+     * image's `alt`, else its children in order -- so that joining the
+     * segments reproduces the entry text the rule parses, and an offset in that
+     * text identifies the node, and so the source, it came from.
+     *
+     * @param node - A node within the list item
+     * @param segments - Accumulator the segments are appended to
+     */
+    collectListItemSegments(node, segments) {
+        const pending = [node];
+        while (pending.length > 0) {
+            const current = pending.pop();
+            if (current === undefined) {
+                break;
+            }
+            const range = this.mapPosition(current.position);
+            const withRange = range !== undefined ? { range } : {};
+            if (current.value !== undefined) {
+                segments.push({
+                    kind: PerDocumentVisitor.showSegmentKind(current.type),
+                    text: current.value,
+                    ...withRange,
+                });
+                continue;
+            }
+            if (typeof current.alt === 'string' && current.alt.length > 0) {
+                segments.push({ kind: 'other', text: current.alt, ...withRange });
+                continue;
+            }
+            PerDocumentVisitor.pushChildren(current, pending);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Private: Heading data extraction
+    // -------------------------------------------------------------------------
+    /**
+     * Extracts heading node data from an MDAST heading node.
+     *
+     * Reads the plain text content with {@link PerDocumentVisitor.showNodeText}
+     * and maps the MDAST position to a {@link HeadingNodeData} structure
+     * suitable for consumption by ECR101, ECR102, and ECR103.
+     *
+     * @param headingNode - The MDAST heading node to extract data from
+     * @returns The extracted {@link HeadingNodeData} with depth, text, and optional range
+     */
+    extractHeadingNodeData(headingNode) {
+        const text = PerDocumentVisitor.showNodeText(headingNode);
+        const range = this.mapPosition(headingNode.position);
+        const headingData = {
+            depth: headingNode.depth ?? 1,
+            text,
+            ...(range !== undefined ? { range } : {}),
+        };
+        return headingData;
+    }
+    // -------------------------------------------------------------------------
+    // Private: Text node data extraction
+    // -------------------------------------------------------------------------
+    /**
+     * Extracts text node data from an MDAST text node.
+     *
+     * Maps the MDAST text node's value and position to a {@link TextNodeData}
+     * structure suitable for consumption by ECR104.
+     *
+     * @param textNode - The MDAST text node to extract data from
+     * @returns The extracted {@link TextNodeData} with text and optional range
+     */
+    extractTextNodeData(textNode) {
+        const range = this.mapPosition(textNode.position);
+        const textNodeData = {
+            text: textNode.value ?? '',
+            ...(range !== undefined ? { range } : {}),
+        };
+        return textNodeData;
+    }
+    // -------------------------------------------------------------------------
+    // Private: Declared DocID extraction
+    // -------------------------------------------------------------------------
+    /**
+     * Extracts the set of declared DocIDs from a completed ECR103 result.
+     *
+     * Iterates over the extracted {@link ReferenceEdge} artefacts and
+     * collects the `toDocId` field from each edge into a `ReadonlySet<DocID>`.
+     * This set is used to initialise ECR104 for undeclared reference detection.
+     *
+     * @param references - The extracted reference edges from ECR103
+     * @returns The set of declared DocIDs
+     */
+    extractDeclaredDocIds(references) {
+        const declaredDocIds = new Set();
+        for (const referenceEdge of references) {
+            declaredDocIds.add(referenceEdge.toDocId);
+        }
+        return declaredDocIds;
+    }
+    // -------------------------------------------------------------------------
+    // Private: Position mapping
+    // -------------------------------------------------------------------------
+    /**
+     * Maps an MDAST position to a {@link PositionRange}, if available.
+     *
+     * MDAST positions use 1-based lines and 1-based columns, while
+     * {@link PositionRange} uses 0-based lines and 0-based characters.
+     * This method performs the conversion.
+     *
+     * @param mdastPosition - The MDAST position object, or `undefined` if
+     *                         positional metadata is not available
+     * @returns The mapped position range, or `undefined` if no position is available
+     */
+    mapPosition(mdastPosition) {
+        if (mdastPosition === undefined) {
+            return undefined;
+        }
+        const mappedRange = {
+            start: {
+                line: mdastPosition.start.line - 1,
+                character: mdastPosition.start.column - 1,
+            },
+            end: {
+                line: mdastPosition.end.line - 1,
+                character: mdastPosition.end.column - 1,
+            },
+        };
+        return mappedRange;
+    }
+    // -------------------------------------------------------------------------
+    // Private: Result assembly
+    // -------------------------------------------------------------------------
+    /**
+     * Assembles the composite {@link LintResult} from individual rule results.
+     *
+     * Aggregates diagnostics from all rules, determines the `ok` status
+     * (true when no error-severity diagnostics are present), and constructs
+     * the {@link ExtractedDocument} when a valid DocID was recovered.
+     *
+     * @param identityResult - The result from ECR101
+     * @param sectionsResult - The result from ECR102 (undefined if ECR101 failed)
+     * @param referencesResult - The result from ECR103 (undefined if ECR101 failed)
+     * @param inlineResult - The result from ECR104 (undefined if ECR101 failed)
+     * @returns The composite lint result
+     */
+    assembleLintResult(identityResult, sectionsResult, referencesResult, inlineResult) {
+        // Aggregate all diagnostics
+        const allDiagnostics = this.aggregateDiagnostics(identityResult, sectionsResult, referencesResult, inlineResult);
+        const input = this.buildLintInput();
+        const isPassable = this.tellAllDiagnosticsPassable(allDiagnostics);
+        // Construct extracted document if identity is valid
+        if (identityResult.identity !== undefined) {
+            const identity = identityResult.identity;
+            const sections = sectionsResult !== undefined ? sectionsResult.sections : [];
+            const references = referencesResult !== undefined ? referencesResult.references : [];
+            const inlineReferences = inlineResult !== undefined ? inlineResult.inlineReferences : [];
+            const extracted = this.buildExtractedDocument(identity, sections, references, inlineReferences);
+            return {
+                input,
+                ok: isPassable,
+                diagnostics: allDiagnostics,
+                extracted,
+            };
+        }
+        return {
+            input,
+            ok: isPassable,
+            diagnostics: allDiagnostics,
+        };
+    }
+    /**
+     * Aggregates diagnostics from all rule results into a single array.
+     *
+     * Collects diagnostics from ECR101, ECR102, ECR103, and ECR104 in that
+     * order. Rules that did not run (undefined results) contribute no
+     * diagnostics.
+     *
+     * @param identityResult - The result from ECR101
+     * @param sectionsResult - The result from ECR102 (undefined if ECR101 failed)
+     * @param referencesResult - The result from ECR103 (undefined if ECR101 failed)
+     * @param inlineResult - The result from ECR104 (undefined if ECR101 failed)
+     * @returns The aggregated array of all diagnostics
+     */
+    aggregateDiagnostics(identityResult, sectionsResult, referencesResult, inlineResult) {
+        const allDiagnostics = [];
+        for (const diagnostic of identityResult.diagnostics) {
+            allDiagnostics.push(diagnostic);
+        }
+        if (sectionsResult !== undefined) {
+            for (const diagnostic of sectionsResult.diagnostics) {
+                allDiagnostics.push(diagnostic);
+            }
+        }
+        if (referencesResult !== undefined) {
+            for (const diagnostic of referencesResult.diagnostics) {
+                allDiagnostics.push(diagnostic);
+            }
+        }
+        if (inlineResult !== undefined) {
+            for (const diagnostic of inlineResult.diagnostics) {
+                allDiagnostics.push(diagnostic);
+            }
+        }
+        return allDiagnostics;
+    }
+    /**
+     * Constructs the {@link LintInput} descriptor for the result.
+     *
+     * Echoes the visitor's URI and optional version into the standard
+     * input descriptor shape.
+     *
+     * @returns The lint input descriptor
+     */
+    buildLintInput() {
+        const input = {
+            uri: this.uri,
+            ...(this.version !== undefined ? { version: this.version } : {}),
+        };
+        return input;
+    }
+    /**
+     * Determines the composite `ok` status from an aggregated diagnostics array.
+     *
+     * The result is `ok` (true) when no diagnostics have severity `"error"`.
+     * Any error-severity diagnostic causes the result to be not-ok (false).
+     *
+     * @param diagnostics - The full array of aggregated diagnostics from all rules
+     * @returns `true` if no error diagnostics are present, `false` otherwise
+     */
+    tellAllDiagnosticsPassable(diagnostics) {
+        return !diagnostics.some((diagnostic) => diagnostic.severity === 'error');
+    }
+    /**
+     * Constructs the {@link ExtractedDocument} from individual rule extraction
+     * results.
+     *
+     * Assembles the document identity (DocID and title), section nodes,
+     * reference edges, and inline reference edges into the canonical
+     * extracted document shape.
+     *
+     * @param identity - The document identity from ECR101
+     * @param sections - The section nodes from ECR102
+     * @param references - The reference edges from ECR103
+     * @param inlineReferences - The inline reference edges from ECR104
+     * @returns The assembled extracted document
+     */
+    buildExtractedDocument(identity, sections, references, inlineReferences) {
+        const extracted = {
+            docId: identity.docId,
+            title: identity.title,
+            sections,
+            references,
+            inlineReferences,
+        };
+        return extracted;
+    }
+}
+//# sourceMappingURL=per-document-visitor.js.map