@timiagama/ecr 0.0.1 → 0.1.0

package/dist/section-hierarchy-rule.js

@@ -0,0 +1,482 @@
+/**
+ * Section Hierarchy Rule (ECR102)
+ *
+ * Validates the section structure constraint defined in the ECR specification:
+ *   - 1#9.4 -- Section Structure Rules
+ *   - 1#9.8 -- Per-Document Structural Invariants ("SectionIDs unique within document")
+ *
+ * This rule consumes heading node data from an AST traversal and validates
+ * the section hierarchy for headings with depth \>= 2. It delegates identifier
+ * parsing and segment-count logic to {@link IdentifierGrammar} and emits
+ * {@link Diagnostic} objects for any violations.
+ *
+ * Validations performed:
+ *   1. A separator (any dash variant) must follow the identifier
+ *   2. Heading text prefix must parse as a valid SectionID
+ *   3. The SectionID's DocID must equal the document's DocID
+ *   4. The section path must have d - 1 segments, where d = heading depth
+ *   5. SectionIDs must be unique within the document (no duplicates)
+ *   6. Heading levels must not be skipped (e.g., H3 directly after H1 is invalid)
+ *
+ * Extracted artefacts:
+ *   - {@link SectionNode} for each valid heading, with parentId derived from the heading stack
+ */
+import { IdentifierGrammar } from './identifier-grammar.js';
+import { HEADING_SOURCE_FORM_CAUSE, HeadingSourceForm } from './heading-source-form.js';
+// ---------------------------------------------------------------------------
+// Rule identifier constant
+// ---------------------------------------------------------------------------
+/**
+ * Canonical rule identifier for the Section Hierarchy Rule.
+ *
+ * Referenced as [ECR102] in the ECR specification (1#9.4).
+ */
+export const SECTION_HIERARCHY_RULE_ID = 'ECR102';
+// ---------------------------------------------------------------------------
+// Diagnostic severity constant
+// ---------------------------------------------------------------------------
+/**
+ * The severity used for all Section Hierarchy Rule diagnostics.
+ *
+ * Per 1#9.8, violation of any per-document structural invariant is an ERROR.
+ */
+const SECTION_HIERARCHY_DIAGNOSTIC_SEVERITY = 'error';
+// ---------------------------------------------------------------------------
+// Separator pattern
+// ---------------------------------------------------------------------------
+/**
+ * Matches the separator between a SectionID and its title: a dash with any
+ * surrounding whitespace.
+ *
+ * The dash may be a hyphen-minus (U+002D), an en dash (U+2013) or an em dash
+ * (U+2014); the variant carries no structural meaning.
+ */
+const SECTION_SEPARATOR_PATTERN = /\s*[-–—]\s*/;
+/**
+ * Matches heading text that begins with a number, i.e. one that at least
+ * attempts an identifier.
+ */
+const STARTS_WITH_DIGIT_PATTERN = /^\s*\d/;
+// ---------------------------------------------------------------------------
+// Rule class
+// ---------------------------------------------------------------------------
+/**
+ * Validates the Section Hierarchy Rule as defined in the ECR specification (1#9.4, 1#9.8).
+ *
+ * The rule enforces that every heading with depth \>= 2 has a valid SectionID
+ * whose DocID is the document's own, carries a separator, has a section path of
+ * one segment per heading level below the H1, and is unique within the document.
+ *
+ * For each valid heading, the rule extracts a {@link SectionNode} with its
+ * parentId derived from the heading stack (the nearest preceding heading at
+ * depth - 1).
+ *
+ * The root H1 heading is registered via {@link registerRootHeading} to establish
+ * the heading stack base and produce the root {@link SectionNode}.
+ *
+ * Usage:
+ * 1. Construct a rule instance with the document URI, established DocID,
+ *    and an {@link IdentifierGrammar}.
+ * 2. Call {@link registerRootHeading} once with the H1 heading data to
+ *    establish the root of the heading stack.
+ * 3. Call {@link evaluateHeading} for every heading node with depth \>= 2
+ *    encountered during AST traversal.
+ * 4. Call {@link finalise} after all headings have been evaluated to obtain
+ *    the complete result.
+ *
+ * @example
+ * ```ts
+ * const grammar = new IdentifierGrammar();
+ * const rule = new SectionHierarchyRule({
+ *   uri: 'file:///doc.md',
+ *   docId: '3.1',
+ *   grammar,
+ * });
+ *
+ * rule.registerRootHeading({ depth: 1, text: '3.1 - My Document' });
+ * rule.evaluateHeading({ depth: 2, text: '3.1#1 - Section One' });
+ * rule.evaluateHeading({ depth: 3, text: '3.1#1.1 - Sub-Section' });
+ * rule.evaluateHeading({ depth: 2, text: '3.1#2 - Section Two' });
+ *
+ * const result: SectionHierarchyRuleResult = rule.finalise();
+ * ```
+ */
+export class SectionHierarchyRule {
+    /** The opaque, host-provided URI identifying the document being validated. */
+    uri;
+    /** The established DocID for this document. */
+    docId;
+    /** The grammar instance used for SectionID parsing and validation. */
+    grammar;
+    /** Diagnostics accumulated during heading evaluation. */
+    collectedDiagnostics;
+    /** Section nodes extracted from valid headings, in traversal order. */
+    collectedSections;
+    /**
+     * Depth-aware heading stack for parent-child derivation.
+     *
+     * Maintained so that each entry's depth is strictly increasing from
+     * bottom to top. When a heading at depth d is encountered, all entries
+     * with depth \>= d are popped before the new entry is pushed.
+     */
+    headingStack;
+    /**
+     * Set of SectionIDs already encountered, for duplicate detection.
+     */
+    encounteredSectionIds;
+    /** Checks each heading's source line against the section recipe. */
+    headingSourceForm;
+    /**
+     * Constructs a new Section Hierarchy Rule evaluator.
+     *
+     * @param options - Configuration including the document URI, established DocID,
+     *                  and grammar instance
+     */
+    constructor(options) {
+        this.uri = options.uri;
+        this.docId = options.docId;
+        this.grammar = options.grammar;
+        this.headingSourceForm = new HeadingSourceForm(options.sourceText);
+        this.collectedDiagnostics = [];
+        this.collectedSections = [];
+        this.headingStack = [];
+        this.encounteredSectionIds = new Set();
+    }
+    /**
+     * Registers the root H1 heading to establish the heading stack base.
+     *
+     * This produces the root {@link SectionNode} (id = DocID, headingDepth = 1,
+     * no parentId) and pushes the H1 onto the heading stack so that subsequent
+     * depth-2 headings can derive their parentId.
+     *
+     * Must be called exactly once, before any calls to {@link evaluateHeading}.
+     *
+     * @param headingNodeData - Data extracted from the H1 heading AST node.
+     *                          The depth must be 1. The title text is extracted
+     *                          from the heading content after the separator.
+     */
+    registerRootHeading(headingNodeData) {
+        const title = this.extractHeadingTitle(headingNodeData.text);
+        const rootSection = {
+            id: this.docId,
+            title,
+            headingDepth: 1,
+        };
+        this.collectedSections.push(rootSection);
+        this.updateHeadingStack(this.docId, 1);
+    }
+    /**
+     * Evaluates a single heading node with depth \>= 2 against the section
+     * hierarchy constraints.
+     *
+     * For each heading, the method validates:
+     * 1. A separator (any dash variant) follows the identifier
+     * 2. The textual prefix parses as a valid SectionID
+     * 3. The SectionID's DocID equals the document's DocID
+     * 4. The section path has d - 1 segments, where d is the heading depth
+     * 5. The SectionID has not been seen before in this document
+     * 6. No heading levels are skipped (depth must not exceed parent depth + 1)
+     *
+     * When all validations pass, a {@link SectionNode} is extracted with its
+     * parentId derived from the heading stack (the nearest preceding heading
+     * at depth - 1), and the heading stack is updated.
+     *
+     * When any validation fails, an error diagnostic is emitted and the heading
+     * stack is still updated to maintain correct parent derivation for
+     * subsequent headings.
+     *
+     * Headings with depth === 1 are ignored (H1 is handled by
+     * {@link registerRootHeading}).
+     *
+     * @param headingNodeData - Data extracted from a heading AST node with depth \>= 2
+     */
+    evaluateHeading(headingNodeData) {
+        if (headingNodeData.depth === 1) {
+            return;
+        }
+        const headingText = headingNodeData.text;
+        const depth = headingNodeData.depth;
+        const range = headingNodeData.range;
+        // 1. Validate separator
+        const separatorDiagnostic = this.validateHeadingSeparator(headingText, range);
+        if (separatorDiagnostic !== undefined) {
+            this.collectedDiagnostics.push(separatorDiagnostic);
+            return;
+        }
+        // 2. Extract SectionID candidate from prefix
+        const candidate = this.extractSectionIdCandidate(headingText);
+        // 3. Parse candidate as SectionID
+        const parseResult = this.grammar.parseSectionId(candidate);
+        if (!parseResult.valid) {
+            const diagnostic = this.createDiagnostic(`Heading prefix "${candidate}" does not parse as a valid SectionID.`, range);
+            this.collectedDiagnostics.push(diagnostic);
+            return;
+        }
+        const sectionId = parseResult.sectionId;
+        // 3a. Verify the heading is where the section recipe looks (1#9.11 rule
+        // 1). Reported, but the checks below still run and the section is still
+        // extracted: withholding it would turn every citation of it into an
+        // unresolved target, reporting one mistake many times over.
+        const obstruction = this.headingSourceForm.findObstruction(range, depth, sectionId);
+        if (obstruction !== undefined) {
+            this.collectedDiagnostics.push({
+                ...this.createDiagnostic(HeadingSourceForm.explain(obstruction, depth, sectionId), range, sectionId),
+                data: { cause: HEADING_SOURCE_FORM_CAUSE, obstruction, sectionId },
+            });
+        }
+        // 4. Verify SectionID extends DocID
+        const extendsDocId = this.grammar.tellSectionIdExtendsDocId(sectionId, this.docId);
+        if (!extendsDocId) {
+            const diagnostic = this.createDiagnostic(`SectionID "${sectionId}" belongs to a different document. ` +
+                `Headings in this document must be written as "${this.docId}#<section path>".`, range, sectionId);
+            this.collectedDiagnostics.push(diagnostic);
+            this.updateHeadingStack(sectionId, depth);
+            return;
+        }
+        // 5. Verify the section path has one segment per heading level below the H1
+        const actualPathLength = this.grammar.showSectionPathLength(sectionId);
+        const expectedPathLength = this.grammar.showExpectedSectionPathLength(depth);
+        if (actualPathLength !== expectedPathLength) {
+            const diagnostic = this.createDiagnostic(`SectionID "${sectionId}" has a section path of ${String(actualPathLength)} ` +
+                `segment(s), but heading depth ${String(depth)} requires ` +
+                `${String(expectedPathLength)}.`, range, sectionId);
+            this.collectedDiagnostics.push(diagnostic);
+            this.updateHeadingStack(sectionId, depth);
+            return;
+        }
+        // 6. Check for duplicate SectionIDs
+        if (this.encounteredSectionIds.has(sectionId)) {
+            const diagnostic = this.createDiagnostic(`Duplicate SectionID "${sectionId}". SectionIDs must be unique within a document.`, range, sectionId);
+            this.collectedDiagnostics.push(diagnostic);
+            this.updateHeadingStack(sectionId, depth);
+            return;
+        }
+        // 7. Check for skipped heading levels
+        const currentTopDepth = this.peekHeadingStackDepth();
+        if (depth > currentTopDepth + 1) {
+            const skippedFrom = currentTopDepth;
+            const diagnostic = this.createDiagnostic(`Heading depth ${String(depth)} skips level(s) after depth ${String(skippedFrom)}. ` +
+                `Each heading level must be introduced before its children.`, range, sectionId);
+            this.collectedDiagnostics.push(diagnostic);
+            this.updateHeadingStack(sectionId, depth);
+            return;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-duplicate-type-constituents -- Semantically distinct: parent may be DocID or SectionID
+        const parentId = this.lookUpParentId(depth);
+        // 8. Check that the section path continues its parent's path
+        const misplacedDiagnostic = this.validatePathAgainstParent(parseResult.sectionPath, parentId, sectionId, range);
+        if (misplacedDiagnostic !== undefined) {
+            this.collectedDiagnostics.push(misplacedDiagnostic);
+            this.updateHeadingStack(sectionId, depth);
+            return;
+        }
+        // All validations passed — extract SectionNode
+        this.encounteredSectionIds.add(sectionId);
+        const title = this.extractHeadingTitle(headingText);
+        const sectionNode = {
+            id: sectionId,
+            title,
+            headingDepth: depth,
+            ...(parentId !== undefined ? { parentId } : {}),
+        };
+        this.collectedSections.push(sectionNode);
+        this.updateHeadingStack(sectionId, depth);
+    }
+    /**
+     * Finalises the rule evaluation and produces the complete result.
+     *
+     * This method must be called after all heading nodes have been supplied
+     * via {@link registerRootHeading} and {@link evaluateHeading}. It returns
+     * all accumulated diagnostics and extracted section nodes.
+     *
+     * @returns The complete rule result including all diagnostics and extracted sections
+     */
+    finalise() {
+        return {
+            diagnostics: this.collectedDiagnostics,
+            sections: this.collectedSections,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Validates that a heading string carries a separator, and returns an
+     * error diagnostic when none is found.
+     *
+     * Delegates to {@link IdentifierGrammar.validateSeparator}.
+     *
+     * @param headingText - The plain text content of the heading node
+     * @param range - Optional positional range for the diagnostic
+     * @returns A diagnostic if the separator is invalid, or `undefined` if valid
+     */
+    validateHeadingSeparator(headingText, range) {
+        const separatorResult = this.grammar.validateSeparator(headingText);
+        if (separatorResult.valid) {
+            return undefined;
+        }
+        // A heading with no number at all is far more common than a numbered
+        // heading missing its dash, and deserves a message that says so.
+        if (!STARTS_WITH_DIGIT_PATTERN.test(headingText)) {
+            return this.createDiagnostic(`Heading "${headingText.trim()}" is not numbered. Every sub-heading carries a SectionID: ` +
+                `the DocID, "#", and a section path, for example "${this.docId}#1 - ${headingText.trim()}".`, range);
+        }
+        const diagnostic = this.createDiagnostic(`Heading has no recognisable separator. ` +
+            `Expected: a number, a dash (-, – or —), then the title.`, range);
+        return diagnostic;
+    }
+    /**
+     * Checks that a sub-section's path continues the path of the heading it
+     * sits under, so that a SectionID locates itself: `3.1#2.1` must sit under
+     * `3.1#2`, not under `3.1#1`.
+     *
+     * Only a parent that was itself extracted is checked against. A parent
+     * that failed validation has already been reported, and measuring its
+     * children against it would repeat that error rather than add one.
+     *
+     * @param sectionPath - The section path of the heading being evaluated
+     * @param parentId - The identifier of the heading it sits under, if any
+     * @param sectionId - The SectionID of the heading being evaluated
+     * @param range - Optional positional range for the diagnostic
+     * @returns A diagnostic if the path does not continue its parent's, or `undefined`
+     */
+    validatePathAgainstParent(sectionPath, 
+    // eslint-disable-next-line @typescript-eslint/no-duplicate-type-constituents -- Semantically distinct: parent may be DocID or SectionID
+    parentId, sectionId, range) {
+        if (parentId === undefined || !this.encounteredSectionIds.has(parentId)) {
+            return undefined;
+        }
+        const parentParse = this.grammar.parseSectionId(parentId);
+        if (!parentParse.valid) {
+            return undefined;
+        }
+        const segments = sectionPath.split('.');
+        const ownPrefix = segments.slice(0, -1).join('.');
+        if (ownPrefix === parentParse.sectionPath) {
+            return undefined;
+        }
+        const expectedId = `${this.docId}#${parentParse.sectionPath}.${segments[segments.length - 1] ?? ''}`;
+        return this.createDiagnostic(`SectionID "${sectionId}" sits under "${parentId}", so its section path must begin ` +
+            `"${parentParse.sectionPath}." (for example "${expectedId}").`, range, sectionId);
+    }
+    /**
+     * Extracts the SectionID candidate string from a heading's text.
+     *
+     * The candidate is the portion of the heading text before the first
+     * occurrence of a separator (any dash variant). If no separator
+     * is found, the entire trimmed text is returned as the candidate.
+     *
+     * @param headingText - The plain text content of the heading node
+     * @returns The SectionID candidate string
+     */
+    extractSectionIdCandidate(headingText) {
+        const match = SECTION_SEPARATOR_PATTERN.exec(headingText);
+        if (match === null) {
+            return headingText.trim();
+        }
+        return headingText.substring(0, match.index).trim();
+    }
+    /**
+     * Extracts the title text from a heading's text.
+     *
+     * The title is the portion of the heading text after the first
+     * occurrence of a separator (any dash variant). If no separator
+     * is found, an empty string is returned.
+     *
+     * @param headingText - The plain text content of the heading node
+     * @returns The extracted title string
+     */
+    extractHeadingTitle(headingText) {
+        const match = SECTION_SEPARATOR_PATTERN.exec(headingText);
+        if (match === null) {
+            return '';
+        }
+        return headingText.substring(match.index + match[0].length);
+    }
+    /**
+     * Looks up the parent identifier from the heading stack for a heading
+     * at the given depth.
+     *
+     * The parent is the nearest preceding heading whose depth is exactly
+     * `headingDepth - 1`. Returns `undefined` if no such heading exists
+     * in the stack (which should not happen for well-formed documents
+     * after the root H1 is registered).
+     *
+     * @param headingDepth - The depth of the heading whose parent is sought
+     * @returns The parent's identifier, or `undefined` if not found
+     */
+    // eslint-disable-next-line @typescript-eslint/no-duplicate-type-constituents -- Semantically distinct: parent may be DocID or SectionID
+    lookUpParentId(headingDepth) {
+        const targetDepth = headingDepth - 1;
+        for (let index = this.headingStack.length - 1; index >= 0; index--) {
+            const entry = this.headingStack[index];
+            if (entry?.depth === targetDepth) {
+                return entry.id;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Returns the depth of the topmost entry on the heading stack.
+     *
+     * Used to detect skipped heading levels: if the incoming heading depth
+     * exceeds the top-of-stack depth by more than 1, an intermediate heading
+     * level has been skipped.
+     *
+     * Returns 0 if the heading stack is empty (should not occur after
+     * {@link registerRootHeading} has been called).
+     *
+     * @returns The depth of the topmost heading stack entry, or 0 if empty
+     */
+    peekHeadingStackDepth() {
+        if (this.headingStack.length === 0) {
+            return 0;
+        }
+        const topEntry = this.headingStack[this.headingStack.length - 1];
+        return topEntry?.depth ?? 0;
+    }
+    /**
+     * Updates the heading stack when a new heading is encountered.
+     *
+     * All entries with depth \>= the new heading's depth are removed,
+     * then the new heading is pushed. This ensures the stack always
+     * reflects the current structural nesting.
+     *
+     * @param id - The DocID or SectionID of the heading
+     * @param depth - The Markdown heading depth
+     */
+    // eslint-disable-next-line @typescript-eslint/no-duplicate-type-constituents -- Semantically distinct: id may be DocID or SectionID
+    updateHeadingStack(id, depth) {
+        while (this.headingStack.length > 0) {
+            const topEntry = this.headingStack[this.headingStack.length - 1];
+            if (topEntry === undefined || topEntry.depth < depth) {
+                break;
+            }
+            this.headingStack.pop();
+        }
+        this.headingStack.push({ id, depth });
+    }
+    /**
+     * Creates a diagnostic object for the Section Hierarchy Rule.
+     *
+     * All diagnostics share the same rule ID ({@link SECTION_HIERARCHY_RULE_ID}),
+     * severity (error), and document URI.
+     *
+     * @param message - Human-readable description of the issue
+     * @param range - Optional positional range of the heading within the source document
+     * @param sectionId - Optional SectionID providing structural context
+     * @returns A fully populated diagnostic object
+     */
+    createDiagnostic(message, range, sectionId) {
+        const diagnostic = {
+            ruleId: SECTION_HIERARCHY_RULE_ID,
+            severity: SECTION_HIERARCHY_DIAGNOSTIC_SEVERITY,
+            message,
+            uri: this.uri,
+            ...(range !== undefined ? { range } : {}),
+            ...(sectionId !== undefined ? { sectionId } : {}),
+        };
+        return diagnostic;
+    }
+}
+//# sourceMappingURL=section-hierarchy-rule.js.map

package/dist/section-hierarchy-rule.js.map

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

package/dist/source-alignment.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Source Alignment
+ *
+ * Maps a parsed text node back to the raw Markdown it came from, character by
+ * character. The source-form checks of the navigation guarantee (1#9.11) need
+ * to know where a parsed character sits in the source, because a search reads
+ * the source: an identifier that parses correctly may be escaped, encoded or
+ * split across a line there, and no recipe would find it.
+ *
+ * Used by ECR104 for citations and by ECR103 for the relationship label of a
+ * References entry. Moved here unchanged from ECR104, where it was developed.
+ */
+/**
+ * Maps each offset of a node's parsed text to its offset in the source.
+ *
+ * A text node's source differs from its parsed value in several ways, and
+ * the ones undone here are: backslash escapes, character references, the
+ * whitespace Markdown drops before a soft line break, and the continuation
+ * prefix a blockquote or list item repeats on every line after the first.
+ * Line endings are carried through unchanged by the parser, so both sides
+ * consume their own.
+ *
+ * This list is not claimed to be exhaustive. Each construct that was missed
+ * rejected some piece of ordinary prose, so the cases covered here are the
+ * ones with fixtures, and a failure to align is reported rather than
+ * guessed at.
+ *
+ * Character references are decoded with the same packages the Markdown
+ * parser itself uses, rather than guessed at. Earlier versions inferred an
+ * expansion's length from surrounding text and were wrong in every direction:
+ * `fj` produces two characters, an unknown name produces none, and
+ * `
` produces a line ending. Guessing is what made each round of this
+ * work reject a different piece of ordinary prose.
+ *
+ * @param source - The node's raw source
+ * @param parsed - The node's parsed text
+ * @returns Source offset for each parsed offset, or `undefined` if the two
+ *          could not be aligned
+ */
+export declare function alignParsedToSource(source: string, parsed: string): readonly number[] | undefined;
+//# sourceMappingURL=source-alignment.d.ts.map

package/dist/source-alignment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-alignment.d.ts","sourceRoot":"","sources":["../src/source-alignment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAuCH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,SAAS,MAAM,EAAE,GAAG,SAAS,CA8F/B"}