@timiagama/ecr 0.0.1 → 0.1.0

package/dist/heading-source-form.js

@@ -0,0 +1,129 @@
+/**
+ * Heading Source Form
+ *
+ * Checks that a heading carrying a DocID or SectionID is written in the one
+ * source form the published recipes can find (1#9.11 rule 1): an ATX heading
+ * whose line begins with its `#` characters, then exactly one space, then the
+ * identifier in literal characters.
+ *
+ * The Markdown parser accepts far more than that. A setext heading, an
+ * indented one, one inside a blockquote, one with a tab or two spaces after
+ * the hashes, and one whose identifier is emphasised, escaped or written as a
+ * character reference all parse to the same identifier -- and none of them is
+ * found by `^# 8\.1[^0-9.#]` or `^#+ 8\.1#3([^0-9]|$)`. So the check reads the
+ * heading's own source line and asks the question the recipe asks.
+ *
+ * It also asks whether that line is a line at all to a search engine. Two
+ * things can hide a correctly written heading from `^`: a lone carriage
+ * return before it, which Markdown treats as a line ending and the engines do
+ * not, and a byte-order mark before the first line, which ripgrep skips and
+ * GNU grep does not.
+ *
+ * Shared by ECR101 (the H1) and ECR102 (every deeper heading).
+ */
+import { SourceLines } from './source-lines.js';
+/** The `data.cause` of a heading whose source form no recipe can find. */
+export const HEADING_SOURCE_FORM_CAUSE = 'heading-source-form';
+/** The UTF-8 byte-order mark, as it appears at the start of decoded text. */
+const BYTE_ORDER_MARK = '';
+/**
+ * What may follow a DocID on its heading line, per the document recipe
+ * `^# 8\.1[^0-9.#]`: anything but a digit, `.` or `#`, so that `8.1` is not
+ * found as the start of `8.10`, `8.1.3` or `8.1#3`.
+ */
+const AFTER_DOC_ID = /^[^0-9.#]/;
+/**
+ * What may follow a SectionID on its heading line, per the section recipe
+ * `^#+ 8\.1#3([^0-9]|$)`: anything but a digit, or the end of the line.
+ */
+const AFTER_SECTION_ID = /^(?:[^0-9]|$)/;
+/**
+ * Tells whether headings are written where the recipes look for them.
+ */
+export class HeadingSourceForm {
+    /** The document's source, by line; absent when none was supplied. */
+    lines;
+    /**
+     * @param sourceText - The document's raw Markdown. When absent, as in unit
+     *                     tests that supply only parsed heading text, there is
+     *                     no source to consult and every heading passes.
+     */
+    constructor(sourceText) {
+        this.lines = sourceText === undefined ? undefined : new SourceLines(sourceText);
+    }
+    /**
+     * Finds what, if anything, stops the recipe for a heading from finding it.
+     *
+     * @param range - The heading node's range
+     * @param depth - The heading's depth, 1 for the H1
+     * @param identifier - The DocID or SectionID parsed from the heading
+     * @returns The obstruction, or `undefined` when the recipe would find it
+     */
+    findObstruction(range, depth, identifier) {
+        if (this.lines === undefined || range === undefined) {
+            return undefined;
+        }
+        const lineNumber = range.start.line;
+        const line = this.lines.readLine(lineNumber) ?? '';
+        // A mark before the first line is reported only when it is what stands
+        // in the way: after it, the line must be a correct heading. A mark
+        // followed by a newline obstructs nothing, since the H1 then starts a
+        // later line, which both engines find.
+        if (lineNumber === 0 && line.startsWith(BYTE_ORDER_MARK)) {
+            return HeadingSourceForm.tellLineMatches(line.slice(1), depth, identifier)
+                ? 'byte-order-mark'
+                : 'form';
+        }
+        if (!HeadingSourceForm.tellLineMatches(line, depth, identifier)) {
+            return 'form';
+        }
+        return this.lines.tellStartsSearchLine(lineNumber) ? undefined : 'lone-carriage-return';
+    }
+    /**
+     * Reports whether a line reads as the recipe for its heading expects.
+     *
+     * @param line - The heading's source line
+     * @param depth - The heading's depth
+     * @param identifier - The DocID or SectionID parsed from the heading
+     * @returns `true` when the line is `#… identifier` followed by an allowed character
+     */
+    static tellLineMatches(line, depth, identifier) {
+        const prefix = `${'#'.repeat(depth)} ${identifier}`;
+        if (!line.startsWith(prefix)) {
+            return false;
+        }
+        const rest = line.slice(prefix.length);
+        return depth === 1 ? AFTER_DOC_ID.test(rest) : AFTER_SECTION_ID.test(rest);
+    }
+    /**
+     * The explanation a diagnostic gives for an unnavigable heading.
+     *
+     * @param obstruction - What stops the recipe from finding it
+     * @param depth - The heading's depth
+     * @param identifier - The DocID or SectionID parsed from the heading
+     * @returns A message naming the obstruction and the fix
+     */
+    static explain(obstruction, depth, identifier) {
+        const hashes = '#'.repeat(depth);
+        const opening = `The heading for "${identifier}" is not in the source form the navigation ` +
+            `recipes search for, so no search finds it.`;
+        switch (obstruction) {
+            case 'lone-carriage-return':
+                return (`${opening} It follows a lone carriage return (CR) line ending, and search ` +
+                    `tools start a new line only at a line feed, so to them it is the middle of ` +
+                    `the line before. Save the file with LF or CRLF line endings.`);
+            case 'byte-order-mark':
+                // Not `opening`: ripgrep skips the mark and does find this heading.
+                return (`The heading for "${identifier}" is not discoverable by every published ` +
+                    `recipe. The file begins with a UTF-8 byte-order mark, which sits before the ` +
+                    `heading's # characters; ripgrep skips it, but GNU grep reads it as text there ` +
+                    `and finds no heading. Save the file as UTF-8 without a byte-order mark.`);
+            default:
+                return (`${opening} Write it as an ATX heading at the start of its line -- ` +
+                    `"${hashes} ${identifier} - ..." -- with one space after the # characters ` +
+                    `and the identifier in literal characters, without formatting, escapes or ` +
+                    `indentation.`);
+        }
+    }
+}
+//# sourceMappingURL=heading-source-form.js.map

package/dist/heading-source-form.js.map

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

package/dist/identifier-grammar.d.ts

@@ -0,0 +1,212 @@
+/**
+ * DocID and SectionID Grammar Parsing & Validation
+ *
+ * Implements the identifier grammar defined in the ECR specification (1#9.2).
+ *
+ * Grammar:
+ *   DocID       ::= Digit+ ("." Digit+)*
+ *   SectionPath ::= Digit+ ("." Digit+)*
+ *   SectionID   ::= DocID "#" SectionPath
+ *
+ * All operations are deterministic and side-effect-free.
+ */
+import type { DocID, SectionID } from './types.js';
+/**
+ * Represents the outcome of parsing a string as a DocID.
+ *
+ * When parsing succeeds, `valid` is `true` and `docId` holds the parsed value.
+ * When parsing fails, `valid` is `false`.
+ */
+export type DocIdParseResult = {
+    readonly valid: true;
+    readonly docId: DocID;
+} | {
+    readonly valid: false;
+};
+/**
+ * Represents the outcome of parsing a string as a SectionID.
+ *
+ * When parsing succeeds, `valid` is `true`, `sectionId` holds the parsed value,
+ * and `docId` holds the DocID prefix that the SectionID extends.
+ * When parsing fails, `valid` is `false`.
+ */
+export type SectionIdParseResult = {
+    readonly valid: true;
+    readonly sectionId: SectionID;
+    readonly docId: DocID;
+    /** The section path following the `#` separator, e.g. `3.1` in `8.1#3.1`. */
+    readonly sectionPath: string;
+} | {
+    readonly valid: false;
+};
+/**
+ * Represents the outcome of extracting a SectionID and title from a sub-heading.
+ *
+ * When extraction succeeds, `valid` is `true` and both `sectionId` and `title`
+ * are present. When it fails, `valid` is `false`.
+ */
+export type SectionHeadingParseResult = {
+    readonly valid: true;
+    readonly sectionId: SectionID;
+    readonly title: string;
+} | {
+    readonly valid: false;
+};
+/**
+ * Represents the outcome of extracting a DocID and title from an H1 heading string.
+ *
+ * When extraction succeeds, `valid` is `true` and both `docId` and `title` are
+ * present. When extraction fails, `valid` is `false`.
+ */
+export type HeadingParseResult = {
+    readonly valid: true;
+    readonly docId: DocID;
+    readonly title: string;
+} | {
+    readonly valid: false;
+};
+/**
+ * Represents the outcome of validating a heading separator.
+ *
+ * `valid` is `true` when the heading carries a recognisable separator: a
+ * hyphen-minus, en dash or em dash after the identifier. When none is found,
+ * `valid` is `false` and `detectedSeparator` holds the canonical separator
+ * for use in the diagnostic message.
+ */
+export type SeparatorValidationResult = {
+    readonly valid: true;
+} | {
+    readonly valid: false;
+    readonly detectedSeparator: string;
+};
+/**
+ * Provides parsing and validation for DocID and SectionID identifiers
+ * as defined in the ECR specification (1#9.2).
+ *
+ * Grammar:
+ *   DocID       ::= Digit+ ("." Digit+)*
+ *   SectionPath ::= Digit+ ("." Digit+)*
+ *   SectionID   ::= DocID "#" SectionPath
+ *
+ * This class encapsulates all identifier-level grammar operations
+ * required by the ECR structural specification.
+ *
+ * @example
+ * ```ts
+ * const grammar = new IdentifierGrammar();
+ * const result = grammar.parseDocId('3.1');
+ * // { valid: true, docId: '3.1' }
+ * ```
+ */
+export declare class IdentifierGrammar {
+    /**
+     * Parses a string and determines whether it conforms to the DocID grammar.
+     *
+     * A valid DocID consists of one or more numeric segments separated by dots,
+     * where each segment contains one or more digits.
+     *
+     * @param input - The string to parse
+     * @returns A parse result indicating validity and, on success, the parsed DocID
+     */
+    parseDocId(input: string): DocIdParseResult;
+    /**
+     * Parses a string and determines whether it conforms to the SectionID grammar.
+     *
+     * A SectionID is a DocID, the separator `#`, and a section path
+     * of one or more dot-separated numeric segments. The separator is mandatory:
+     * a dotted identifier with no `#` is a DocID, never a SectionID.
+     *
+     * @param input - The string to parse
+     * @returns A parse result indicating validity and, on success, the SectionID,
+     *          the DocID it belongs to, and the section path within that document
+     */
+    parseSectionId(input: string): SectionIdParseResult;
+    /**
+     * Determines whether a SectionID belongs to a given DocID.
+     *
+     * This is an exact comparison of the SectionID's document
+     * part against the supplied DocID. No prefix matching is involved, so a
+     * SectionID of document `8.1.3` does not belong to document `8.1`, and a
+     * SectionID of `8.10` does not belong to `8.1`.
+     *
+     * @param sectionId - The SectionID to check
+     * @param docId - The DocID the SectionID should belong to
+     * @returns `true` if the SectionID names a section of that document
+     */
+    tellSectionIdExtendsDocId(sectionId: SectionID, docId: DocID): boolean;
+    /**
+     * Counts the number of numeric segments in an identifier string.
+     *
+     * Segments are the numeric components separated by `"."`.
+     * For example, `"3.1.2"` has three segments.
+     *
+     * @param identifier - A DocID or SectionID string
+     * @returns The number of numeric segments
+     */
+    showSegmentCount(identifier: string): number;
+    /**
+     * Counts the segments in a SectionID's section path.
+     *
+     * For `8.1#3.1` the section path is `3.1`, so the length is 2. The DocID's
+     * own depth does not contribute.
+     *
+     * @param sectionId - The SectionID to measure
+     * @returns The number of section-path segments, or 0 if the input is not a SectionID
+     */
+    showSectionPathLength(sectionId: SectionID): number;
+    /**
+     * Computes the section-path length required of a heading at a given depth.
+     *
+     * A heading at Markdown depth *d* carries exactly *d - 1*
+     * section-path segments, independent of how deep its document's DocID is.
+     * An H2 carries one segment, an H3 two, and so on.
+     *
+     * @param headingDepth - The Markdown heading depth (2 for H2, 3 for H3, etc.)
+     * @returns The required number of section-path segments
+     */
+    showExpectedSectionPathLength(headingDepth: number): number;
+    /**
+     * Extracts the DocID and title from an H1 heading string.
+     *
+     * The heading must match the pattern: DocID <dash> Title, where the dash
+     * is a hyphen-minus, en dash or em dash with any surrounding whitespace.
+     * The title must be non-empty after trimming leading and trailing
+     * whitespace.
+     *
+     * @param headingText - The plain text content of the H1 heading node
+     * @returns A parse result indicating validity and, on success, the extracted DocID and title
+     */
+    parseHeading(headingText: string): HeadingParseResult;
+    /**
+     * Extracts the SectionID and title from a sub-heading string.
+     *
+     * A sub-heading carries a SectionID, so it must contain the `#` separator.
+     * An H1 carries a DocID and is parsed by {@link IdentifierGrammar.parseHeading}
+     * instead.
+     *
+     * @param headingText - The plain text content of a heading node at depth \>= 2
+     * @returns A parse result indicating validity and, on success, the SectionID and title
+     */
+    parseSectionHeading(headingText: string): SectionHeadingParseResult;
+    /**
+     * Validates that a heading string carries a separator between its
+     * identifier and its title.
+     *
+     * Per the ECR specification (1#9.3, 1#9.4), the separator may be a
+     * hyphen-minus (U+002D), an en dash (U+2013) or an em dash (U+2014), with
+     * any surrounding whitespace. Only a heading with no separator at all is
+     * invalid.
+     *
+     * @param headingText - The plain text content of a heading node
+     * @returns A validation result indicating whether the separator is valid
+     */
+    validateSeparator(headingText: string): SeparatorValidationResult;
+    /**
+     * Tests whether a string matches the DocID grammar: `Digit+ ("." Digit+)*`.
+     *
+     * @param input - The string to test
+     * @returns `true` if the input matches the DocID grammar, `false` otherwise
+     */
+    private matchesDocIdGrammar;
+}
+//# sourceMappingURL=identifier-grammar.d.ts.map

package/dist/identifier-grammar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifier-grammar.d.ts","sourceRoot":"","sources":["../src/identifier-grammar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAMnD;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAE9B;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IACE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,GACD;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GACjC;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/E;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAE9B;;;;;;;GAOG;AACH,MAAM,MAAM,yBAAyB,GACjC;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAAC;AAkElE;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;;OAQG;IACI,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB;IAUlD;;;;;;;;;;OAUG;IACI,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,oBAAoB;IAkB1D;;;;;;;;;;;OAWG;IACI,yBAAyB,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO;IAU7E;;;;;;;;OAQG;IACI,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IASnD;;;;;;;;OAQG;IACI,qBAAqB,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM;IAU1D;;;;;;;;;OASG;IACI,6BAA6B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAIlE;;;;;;;;;;OAUG;IACI,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB;IAyB5D;;;;;;;;;OASG;IACI,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,yBAAyB;IAiB1E;;;;;;;;;;;OAWG;IACI,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,yBAAyB;IAYxE;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;CAG5B"}

package/dist/identifier-grammar.js

@@ -0,0 +1,273 @@
+/**
+ * DocID and SectionID Grammar Parsing & Validation
+ *
+ * Implements the identifier grammar defined in the ECR specification (1#9.2).
+ *
+ * Grammar:
+ *   DocID       ::= Digit+ ("." Digit+)*
+ *   SectionPath ::= Digit+ ("." Digit+)*
+ *   SectionID   ::= DocID "#" SectionPath
+ *
+ * All operations are deterministic and side-effect-free.
+ */
+// ---------------------------------------------------------------------------
+// Internal constants
+// ---------------------------------------------------------------------------
+/**
+ * Regular expression matching the DocID grammar: one or more numeric segments
+ * separated by dots. Each segment is one or more digits.
+ *
+ * Anchored to match the entire string.
+ */
+const DOC_ID_PATTERN = /^\d+(\.\d+)*$/;
+/**
+ * Regular expression matching the SectionID grammar: a DocID, the
+ * separator `#`, and a section path of one or more dot-separated numeric
+ * segments.
+ *
+ * The separator is what makes an identifier unambiguous. Without it, `0.0.2.1`
+ * could denote section 1 of document `0.0.2` or section 2.1 of document `0.0`,
+ * and a corpus numbering its documents hierarchically will contain both.
+ *
+ * Group 1: the DocID. Group 2: the section path.
+ */
+const SECTION_ID_PATTERN = /^(\d+(?:\.\d+)*)#(\d+(?:\.\d+)*)$/;
+/**
+ * Canonical separator, used when a separator must be rendered in a message.
+ */
+const HYPHEN_MINUS_SEPARATOR = ' - ';
+/**
+ * Regular expression matching a heading of the form `DocID <dash> Title`.
+ *
+ * The separator may be a hyphen-minus (U+002D), an en dash (U+2013) or an
+ * em dash (U+2014), with any amount of surrounding whitespace including none.
+ *
+ * Real-world corpora mix all three interchangeably, often within one document,
+ * and the separator carries no structural meaning: identity is carried entirely
+ * by the numeric identifier. Rejecting a dash variant would fail documents that
+ * are perfectly navigable, so all three are accepted.
+ *
+ * Group 1: the candidate DocID. Group 2: the title.
+ */
+const HEADING_PATTERN = /^(\d+(?:\.\d+)*)\s*[-–—]\s*(.+)$/;
+/**
+ * Detects whether a heading carries any recognised separator, irrespective of
+ * which dash variant is used.
+ */
+const ANY_SEPARATOR_PATTERN = /\d\s*[-–—]\s*\S/;
+/**
+ * Regular expression matching a sub-heading of the form `SectionID <dash> Title`.
+ *
+ * Group 1: the SectionID. Group 2: the title.
+ */
+const SECTION_HEADING_PATTERN = /^(\d+(?:\.\d+)*#\d+(?:\.\d+)*)\s*[-\u2013\u2014]\s*(.+)$/;
+// ---------------------------------------------------------------------------
+// Identifier grammar parser
+// ---------------------------------------------------------------------------
+/**
+ * Provides parsing and validation for DocID and SectionID identifiers
+ * as defined in the ECR specification (1#9.2).
+ *
+ * Grammar:
+ *   DocID       ::= Digit+ ("." Digit+)*
+ *   SectionPath ::= Digit+ ("." Digit+)*
+ *   SectionID   ::= DocID "#" SectionPath
+ *
+ * This class encapsulates all identifier-level grammar operations
+ * required by the ECR structural specification.
+ *
+ * @example
+ * ```ts
+ * const grammar = new IdentifierGrammar();
+ * const result = grammar.parseDocId('3.1');
+ * // { valid: true, docId: '3.1' }
+ * ```
+ */
+export class IdentifierGrammar {
+    /**
+     * Parses a string and determines whether it conforms to the DocID grammar.
+     *
+     * A valid DocID consists of one or more numeric segments separated by dots,
+     * where each segment contains one or more digits.
+     *
+     * @param input - The string to parse
+     * @returns A parse result indicating validity and, on success, the parsed DocID
+     */
+    parseDocId(input) {
+        const isValid = this.matchesDocIdGrammar(input);
+        if (isValid) {
+            return { valid: true, docId: input };
+        }
+        return { valid: false };
+    }
+    /**
+     * Parses a string and determines whether it conforms to the SectionID grammar.
+     *
+     * A SectionID is a DocID, the separator `#`, and a section path
+     * of one or more dot-separated numeric segments. The separator is mandatory:
+     * a dotted identifier with no `#` is a DocID, never a SectionID.
+     *
+     * @param input - The string to parse
+     * @returns A parse result indicating validity and, on success, the SectionID,
+     *          the DocID it belongs to, and the section path within that document
+     */
+    parseSectionId(input) {
+        const match = SECTION_ID_PATTERN.exec(input);
+        if (match === null) {
+            return { valid: false };
+        }
+        const docIdValue = match[1] ?? '';
+        const sectionPathValue = match[2] ?? '';
+        return {
+            valid: true,
+            sectionId: input,
+            docId: docIdValue,
+            sectionPath: sectionPathValue,
+        };
+    }
+    /**
+     * Determines whether a SectionID belongs to a given DocID.
+     *
+     * This is an exact comparison of the SectionID's document
+     * part against the supplied DocID. No prefix matching is involved, so a
+     * SectionID of document `8.1.3` does not belong to document `8.1`, and a
+     * SectionID of `8.10` does not belong to `8.1`.
+     *
+     * @param sectionId - The SectionID to check
+     * @param docId - The DocID the SectionID should belong to
+     * @returns `true` if the SectionID names a section of that document
+     */
+    tellSectionIdExtendsDocId(sectionId, docId) {
+        const parseResult = this.parseSectionId(sectionId);
+        if (!parseResult.valid) {
+            return false;
+        }
+        return parseResult.docId === docId;
+    }
+    /**
+     * Counts the number of numeric segments in an identifier string.
+     *
+     * Segments are the numeric components separated by `"."`.
+     * For example, `"3.1.2"` has three segments.
+     *
+     * @param identifier - A DocID or SectionID string
+     * @returns The number of numeric segments
+     */
+    showSegmentCount(identifier) {
+        if (identifier === '') {
+            return 0;
+        }
+        const segments = identifier.split('.');
+        return segments.length;
+    }
+    /**
+     * Counts the segments in a SectionID's section path.
+     *
+     * For `8.1#3.1` the section path is `3.1`, so the length is 2. The DocID's
+     * own depth does not contribute.
+     *
+     * @param sectionId - The SectionID to measure
+     * @returns The number of section-path segments, or 0 if the input is not a SectionID
+     */
+    showSectionPathLength(sectionId) {
+        const parseResult = this.parseSectionId(sectionId);
+        if (!parseResult.valid) {
+            return 0;
+        }
+        return this.showSegmentCount(parseResult.sectionPath);
+    }
+    /**
+     * Computes the section-path length required of a heading at a given depth.
+     *
+     * A heading at Markdown depth *d* carries exactly *d - 1*
+     * section-path segments, independent of how deep its document's DocID is.
+     * An H2 carries one segment, an H3 two, and so on.
+     *
+     * @param headingDepth - The Markdown heading depth (2 for H2, 3 for H3, etc.)
+     * @returns The required number of section-path segments
+     */
+    showExpectedSectionPathLength(headingDepth) {
+        return headingDepth - 1;
+    }
+    /**
+     * Extracts the DocID and title from an H1 heading string.
+     *
+     * The heading must match the pattern: DocID <dash> Title, where the dash
+     * is a hyphen-minus, en dash or em dash with any surrounding whitespace.
+     * The title must be non-empty after trimming leading and trailing
+     * whitespace.
+     *
+     * @param headingText - The plain text content of the H1 heading node
+     * @returns A parse result indicating validity and, on success, the extracted DocID and title
+     */
+    parseHeading(headingText) {
+        const match = HEADING_PATTERN.exec(headingText.trim());
+        if (match === null) {
+            return { valid: false };
+        }
+        const candidateDocId = match[1] ?? '';
+        const title = match[2] ?? '';
+        const docIdResult = this.parseDocId(candidateDocId);
+        if (!docIdResult.valid) {
+            return { valid: false };
+        }
+        const trimmedTitle = title.trim();
+        if (trimmedTitle.length === 0) {
+            return { valid: false };
+        }
+        return { valid: true, docId: docIdResult.docId, title };
+    }
+    /**
+     * Extracts the SectionID and title from a sub-heading string.
+     *
+     * A sub-heading carries a SectionID, so it must contain the `#` separator.
+     * An H1 carries a DocID and is parsed by {@link IdentifierGrammar.parseHeading}
+     * instead.
+     *
+     * @param headingText - The plain text content of a heading node at depth \>= 2
+     * @returns A parse result indicating validity and, on success, the SectionID and title
+     */
+    parseSectionHeading(headingText) {
+        const match = SECTION_HEADING_PATTERN.exec(headingText.trim());
+        if (match === null) {
+            return { valid: false };
+        }
+        const sectionId = match[1] ?? '';
+        const title = match[2] ?? '';
+        if (title.trim().length === 0) {
+            return { valid: false };
+        }
+        return { valid: true, sectionId, title };
+    }
+    /**
+     * Validates that a heading string carries a separator between its
+     * identifier and its title.
+     *
+     * Per the ECR specification (1#9.3, 1#9.4), the separator may be a
+     * hyphen-minus (U+002D), an en dash (U+2013) or an em dash (U+2014), with
+     * any surrounding whitespace. Only a heading with no separator at all is
+     * invalid.
+     *
+     * @param headingText - The plain text content of a heading node
+     * @returns A validation result indicating whether the separator is valid
+     */
+    validateSeparator(headingText) {
+        if (ANY_SEPARATOR_PATTERN.test(headingText)) {
+            return { valid: true };
+        }
+        return { valid: false, detectedSeparator: HYPHEN_MINUS_SEPARATOR };
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Tests whether a string matches the DocID grammar: `Digit+ ("." Digit+)*`.
+     *
+     * @param input - The string to test
+     * @returns `true` if the input matches the DocID grammar, `false` otherwise
+     */
+    matchesDocIdGrammar(input) {
+        return DOC_ID_PATTERN.test(input);
+    }
+}
+//# sourceMappingURL=identifier-grammar.js.map

package/dist/identifier-grammar.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export type { DocID, SectionID, DiagnosticSeverity, Position, PositionRange, Diagnostic, ReferenceDirection, InlineReferenceKind, SectionNode, ReferenceEdge, InlineReferenceEdge, ExtractedDocument, LintInput, LintResult, CorpusDocumentEntry, CorpusIndex, CorpusResult, } from "./types.js";
+export { IdentifierGrammar } from "./identifier-grammar.js";
+export type { DocIdParseResult, SectionIdParseResult, HeadingParseResult, SectionHeadingParseResult, SeparatorValidationResult, } from "./identifier-grammar.js";
+export { DocumentIdentityRule, DOCUMENT_IDENTITY_RULE_ID } from "./document-identity-rule.js";
+export type { HeadingNodeData, DocumentIdentity, DocumentIdentityRuleResult, DocumentIdentityRuleOptions, } from "./document-identity-rule.js";
+export { SectionHierarchyRule, SECTION_HIERARCHY_RULE_ID } from "./section-hierarchy-rule.js";
+export type { SectionHierarchyRuleOptions, SectionHierarchyRuleResult, } from "./section-hierarchy-rule.js";
+export { ReferencesSectionRule, REFERENCES_SECTION_RULE_ID } from "./references-section-rule.js";
+export type { ListItemNodeData, ListItemSegment, ParsedReferenceEntry, ReferencesSectionRuleResult, ReferencesSectionRuleOptions, } from "./references-section-rule.js";
+export { InlineReferenceRule, INLINE_REFERENCE_RULE_ID } from "./inline-reference-rule.js";
+export type { TextNodeData, InlineSegment, InlineSegmentKind, DetectedInlineReference, InlineReferenceRuleResult, InlineReferenceRuleOptions, } from "./inline-reference-rule.js";
+export { PerDocumentVisitor, UNPARSABLE_DOCUMENT_RULE_ID, UNPARSABLE_DOCUMENT_CAUSE, } from "./per-document-visitor.js";
+export type { PerDocumentVisitorOptions, } from "./per-document-visitor.js";
+export { CorpusValidator } from "./corpus-validator.js";
+export { Ecr } from "./ecr.js";
+export type { CorpusDocumentInput } from "./ecr.js";
+export { MetaDocumentFilter, DEFAULT_META_DOCUMENT_NAMES } from "./meta-documents.js";
+export { ECR_SPEC_VERSION } from "./spec-version.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,KAAK,EACL,SAAS,EACT,kBAAkB,EAClB,QAAQ,EACR,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAC9F,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAC9F,YAAY,EACV,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AACjG,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAC3F,YAAY,EACV,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,uBAAuB,EACvB,yBAAyB,EACzB,0BAA0B,GAC3B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AACnC,YAAY,EACV,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,YAAY,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEpD,OAAO,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+export { IdentifierGrammar } from "./identifier-grammar.js";
+export { DocumentIdentityRule, DOCUMENT_IDENTITY_RULE_ID } from "./document-identity-rule.js";
+export { SectionHierarchyRule, SECTION_HIERARCHY_RULE_ID } from "./section-hierarchy-rule.js";
+export { ReferencesSectionRule, REFERENCES_SECTION_RULE_ID } from "./references-section-rule.js";
+export { InlineReferenceRule, INLINE_REFERENCE_RULE_ID } from "./inline-reference-rule.js";
+export { PerDocumentVisitor, UNPARSABLE_DOCUMENT_RULE_ID, UNPARSABLE_DOCUMENT_CAUSE, } from "./per-document-visitor.js";
+export { CorpusValidator } from "./corpus-validator.js";
+export { Ecr } from "./ecr.js";
+export { MetaDocumentFilter, DEFAULT_META_DOCUMENT_NAMES } from "./meta-documents.js";
+export { ECR_SPEC_VERSION } from "./spec-version.js";
+//# sourceMappingURL=index.js.map