@timiagama/ecr 0.0.1 → 0.1.0

package/dist/source-alignment.js

@@ -0,0 +1,166 @@
+/**
+ * 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.
+ */
+import { decodeNamedCharacterReference } from 'decode-named-character-reference';
+import { decodeNumericCharacterReference } from 'micromark-util-decode-numeric-character-reference';
+/** A line ending as Markdown recognises it. */
+const LINE_ENDING = /^(?:\r\n|\n|\r)/;
+/**
+ * The prefix a container repeats on its continuation lines.
+ *
+ * A paragraph inside a blockquote or a list item carries `> ` or indentation
+ * on every line after the first. The parser strips it; the source keeps it.
+ */
+const CONTINUATION_PREFIX = /^[ \t>]*/;
+/**
+ * Whitespace the parser drops from the end of a line.
+ *
+ * Markdown discards spaces and tabs before a soft line break, so the source
+ * carries them and the parsed text does not.
+ */
+const TRAILING_WHITESPACE = /^[ \t]*/;
+/** A named character reference, such as `&` or `fj`. */
+const NAMED_REFERENCE = /^&[a-zA-Z][a-zA-Z0-9]{1,31};/;
+/** A numeric character reference, decimal or hexadecimal. */
+const NUMERIC_REFERENCE = /^&#(?:([0-9]{1,7})|[xX]([0-9a-fA-F]{1,6}));/;
+/**
+ * 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 function alignParsedToSource(source, parsed) {
+    const map = [];
+    let sourceIndex = 0;
+    let parsedIndex = 0;
+    while (parsedIndex < parsed.length) {
+        if (sourceIndex >= source.length) {
+            return undefined;
+        }
+        const remaining = source.slice(sourceIndex);
+        const parsedCharacter = parsed.charAt(parsedIndex);
+        // A character reference, decoded exactly. Tested first because `&` also
+        // begins its own expansion (`&amp;` parses to `&`), and because a
+        // reference can produce a line ending: `&#10;` decodes to a line feed
+        // while the source holds no line break at all.
+        const expansion = readCharacterReference(remaining);
+        if (expansion !== undefined) {
+            if (!parsed.startsWith(expansion.text, parsedIndex)) {
+                return undefined;
+            }
+            for (let unit = 0; unit < expansion.text.length; unit += 1) {
+                map[parsedIndex + unit] = sourceIndex;
+            }
+            sourceIndex += expansion.length;
+            parsedIndex += expansion.text.length;
+            continue;
+        }
+        // A soft line break, and any container prefix on the line that follows.
+        //
+        // The parser does not normalise line endings: a CRLF document yields a
+        // text node whose value still contains CRLF. The source ending therefore
+        // decides how much is consumed, on both sides. Taking the parsed text's
+        // own ending instead was wrong twice over -- consuming one character for
+        // a two-character ending desynchronised every multi-line paragraph in a
+        // CRLF checkout, and consuming two for a one-character ending swallowed
+        // the line feed that a following `&#10;` had produced.
+        const parsedEnding = LINE_ENDING.exec(parsed.slice(parsedIndex))?.[0];
+        if (parsedEnding !== undefined) {
+            // Spaces and tabs before the break exist only in the source.
+            const dropped = TRAILING_WHITESPACE.exec(remaining)?.[0] ?? '';
+            const sourceEnding = LINE_ENDING.exec(remaining.slice(dropped.length))?.[0];
+            if (sourceEnding === undefined) {
+                return undefined;
+            }
+            // Consume exactly what the source spent, not what the parsed text
+            // could match. The two differ when a literal CR is followed by an
+            // encoded line feed: the parsed value then holds `CR LF`, of which
+            // only the CR came from this line ending. Taking both would swallow
+            // the entity's own character and strand the reference that produced it.
+            if (!parsed.startsWith(sourceEnding, parsedIndex)) {
+                return undefined;
+            }
+            for (let unit = 0; unit < sourceEnding.length; unit += 1) {
+                map[parsedIndex + unit] = sourceIndex;
+            }
+            sourceIndex += dropped.length + sourceEnding.length;
+            sourceIndex +=
+                CONTINUATION_PREFIX.exec(source.slice(sourceIndex))?.[0].length ?? 0;
+            parsedIndex += sourceEnding.length;
+            continue;
+        }
+        // A backslash escape: two source characters produce one.
+        if (remaining.startsWith(`\\${parsedCharacter}`)) {
+            map[parsedIndex] = sourceIndex;
+            sourceIndex += 2;
+            parsedIndex += 1;
+            continue;
+        }
+        if (remaining.startsWith(parsedCharacter)) {
+            map[parsedIndex] = sourceIndex;
+            sourceIndex += 1;
+            parsedIndex += 1;
+            continue;
+        }
+        return undefined;
+    }
+    return map;
+}
+/**
+ * Decodes a character reference at the start of `remaining`, if there is one.
+ *
+ * An unrecognised name is not a reference at all -- `&NotAnEntity;` stays
+ * literal -- and is reported as such by returning `undefined`, so the
+ * ordinary literal comparison handles it.
+ *
+ * @param remaining - Source text beginning at the candidate reference
+ * @returns The decoded text and the reference's source length, or `undefined`
+ */
+function readCharacterReference(remaining) {
+    const numeric = NUMERIC_REFERENCE.exec(remaining);
+    if (numeric !== null) {
+        const decimal = numeric[1];
+        const value = decimal ?? numeric[2] ?? '';
+        return {
+            text: decodeNumericCharacterReference(value, decimal === undefined ? 16 : 10),
+            length: numeric[0].length,
+        };
+    }
+    const named = NAMED_REFERENCE.exec(remaining);
+    if (named === null) {
+        return undefined;
+    }
+    const decoded = decodeNamedCharacterReference(named[0].slice(1, -1));
+    return decoded === false ? undefined : { text: decoded, length: named[0].length };
+}
+//# sourceMappingURL=source-alignment.js.map

package/dist/source-alignment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-alignment.js","sourceRoot":"","sources":["../src/source-alignment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,6BAA6B,EAAE,MAAM,kCAAkC,CAAC;AACjF,OAAO,EAAE,+BAA+B,EAAE,MAAM,mDAAmD,CAAC;AAUpG,+CAA+C;AAC/C,MAAM,WAAW,GAAW,iBAAiB,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,mBAAmB,GAAW,UAAU,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,mBAAmB,GAAW,SAAS,CAAC;AAE9C,iEAAiE;AACjE,MAAM,eAAe,GAAW,8BAA8B,CAAC;AAE/D,6DAA6D;AAC7D,MAAM,iBAAiB,GAAW,6CAA6C,CAAC;AAGhF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAc,EACd,MAAc;IAEd,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,WAAW,GAAW,CAAC,CAAC;IAC5B,IAAI,WAAW,GAAW,CAAC,CAAC;IAE5B,OAAO,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;QACnC,IAAI,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YACjC,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,SAAS,GAAW,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QACpD,MAAM,eAAe,GAAW,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAE3D,wEAAwE;QACxE,kEAAkE;QAClE,sEAAsE;QACtE,+CAA+C;QAC/C,MAAM,SAAS,GACb,sBAAsB,CAAC,SAAS,CAAC,CAAC;QAEpC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,CAAC;gBACpD,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;gBAC3D,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,WAAW,CAAC;YACxC,CAAC;YAED,WAAW,IAAI,SAAS,CAAC,MAAM,CAAC;YAChC,WAAW,IAAI,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC;YACrC,SAAS;QACX,CAAC;QAED,wEAAwE;QACxE,EAAE;QACF,uEAAuE;QACvE,yEAAyE;QACzE,wEAAwE;QACxE,yEAAyE;QACzE,wEAAwE;QACxE,wEAAwE;QACxE,uDAAuD;QACvD,MAAM,YAAY,GAAuB,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAE1F,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAC/B,6DAA6D;YAC7D,MAAM,OAAO,GAAW,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACvE,MAAM,YAAY,GAChB,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YAEzD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;gBAC/B,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,kEAAkE;YAClE,kEAAkE;YAClE,mEAAmE;YACnE,oEAAoE;YACpE,wEAAwE;YACxE,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,YAAY,EAAE,WAAW,CAAC,EAAE,CAAC;gBAClD,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,YAAY,CAAC,MAAM,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;gBACzD,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,WAAW,CAAC;YACxC,CAAC;YAED,WAAW,IAAI,OAAO,CAAC,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC;YACpD,WAAW;gBACT,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;YACvE,WAAW,IAAI,YAAY,CAAC,MAAM,CAAC;YACnC,SAAS;QACX,CAAC;QAED,yDAAyD;QACzD,IAAI,SAAS,CAAC,UAAU,CAAC,KAAK,eAAe,EAAE,CAAC,EAAE,CAAC;YACjD,GAAG,CAAC,WAAW,CAAC,GAAG,WAAW,CAAC;YAC/B,WAAW,IAAI,CAAC,CAAC;YACjB,WAAW,IAAI,CAAC,CAAC;YACjB,SAAS;QACX,CAAC;QAED,IAAI,SAAS,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;YAC1C,GAAG,CAAC,WAAW,CAAC,GAAG,WAAW,CAAC;YAC/B,WAAW,IAAI,CAAC,CAAC;YACjB,WAAW,IAAI,CAAC,CAAC;YACjB,SAAS;QACX,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,sBAAsB,CAAC,SAAiB;IAC/C,MAAM,OAAO,GAA2B,iBAAiB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAE1E,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,MAAM,OAAO,GAAuB,OAAO,CAAC,CAAC,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAW,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAElD,OAAO;YACL,IAAI,EAAE,+BAA+B,CAAC,KAAK,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7E,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM;SAC1B,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAA2B,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAEtE,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,OAAO,GAAmB,6BAA6B,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAErF,OAAO,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;AACpF,CAAC"}

package/dist/source-lines.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Source Lines
+ *
+ * Reads a document's raw Markdown by line, for the source-form checks of the
+ * navigation guarantee (1#9.11). The published recipes search raw text line
+ * by line, so the rules that promise a recipe will find something have to
+ * look at the same lines the recipe does.
+ */
+import type { Position, PositionRange } from './types.js';
+/**
+ * Records where each line of a source begins.
+ *
+ * Markdown treats LF, CRLF and a lone CR as line endings. Indexing only LF
+ * left a CR-only document with a single line start, so every offset beyond
+ * the first line failed to resolve and source validation was silently
+ * skipped -- exactly the documents that most need it.
+ *
+ * @param sourceText - The document's raw Markdown
+ * @returns Absolute offset of the first character of each line
+ */
+export declare function indexLineStarts(sourceText: string): readonly number[];
+/**
+ * A document's raw source, addressable by line.
+ */
+export declare class SourceLines {
+    /** The document's raw Markdown. */
+    private readonly sourceText;
+    /** Absolute offset at which each line begins. */
+    private readonly lineStarts;
+    /**
+     * Indexes a source for line access.
+     *
+     * @param sourceText - The document's raw Markdown
+     */
+    constructor(sourceText: string);
+    /**
+     * Returns one line of the source, without its line ending.
+     *
+     * @param line - Zero-based line number
+     * @returns The line's text, or `undefined` when the line does not exist
+     */
+    readLine(line: number): string | undefined;
+    /**
+     * Reports whether a Markdown line also begins a line for a search engine.
+     *
+     * Markdown ends a line at LF, CRLF or a lone CR; ripgrep and grep end one
+     * only at LF. So a line that follows a lone CR is, to a search, the middle
+     * of the line before it, and no recipe anchored with `^` can match it.
+     *
+     * @param line - Zero-based Markdown line number
+     * @returns `true` when the line starts the file or follows an LF
+     */
+    tellStartsSearchLine(line: number): boolean;
+    /**
+     * Returns the source a range covers.
+     *
+     * @param range - A range within the document
+     * @returns Its raw source, or `undefined` when it lies outside the document
+     */
+    slice(range: PositionRange): string | undefined;
+    /**
+     * Converts a line/character position into an absolute source offset.
+     *
+     * @param position - A position within the document
+     * @returns The offset, or `undefined` when the line is out of range
+     */
+    offsetOf(position: Position): number | undefined;
+}
+//# sourceMappingURL=source-lines.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"source-lines.d.ts","sourceRoot":"","sources":["../src/source-lines.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAoBrE;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB,mCAAmC;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,iDAAiD;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAE/C;;;;OAIG;gBACgB,UAAU,EAAE,MAAM;IAKrC;;;;;OAKG;IACI,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAYjD;;;;;;;;;OASG;IACI,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAMlD;;;;;OAKG;IACI,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS;IAOtD;;;;;OAKG;IACI,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS;CAKxD"}

package/dist/source-lines.js

@@ -0,0 +1,104 @@
+/**
+ * Source Lines
+ *
+ * Reads a document's raw Markdown by line, for the source-form checks of the
+ * navigation guarantee (1#9.11). The published recipes search raw text line
+ * by line, so the rules that promise a recipe will find something have to
+ * look at the same lines the recipe does.
+ */
+/**
+ * Records where each line of a source begins.
+ *
+ * Markdown treats LF, CRLF and a lone CR as line endings. Indexing only LF
+ * left a CR-only document with a single line start, so every offset beyond
+ * the first line failed to resolve and source validation was silently
+ * skipped -- exactly the documents that most need it.
+ *
+ * @param sourceText - The document's raw Markdown
+ * @returns Absolute offset of the first character of each line
+ */
+export function indexLineStarts(sourceText) {
+    const starts = [0];
+    for (let index = 0; index < sourceText.length; index += 1) {
+        const character = sourceText.charAt(index);
+        if (character === '\r') {
+            const isCarriageReturnLineFeed = sourceText.charAt(index + 1) === '\n';
+            starts.push(index + (isCarriageReturnLineFeed ? 2 : 1));
+            if (isCarriageReturnLineFeed) {
+                index += 1;
+            }
+        }
+        else if (character === '\n') {
+            starts.push(index + 1);
+        }
+    }
+    return starts;
+}
+/**
+ * A document's raw source, addressable by line.
+ */
+export class SourceLines {
+    /** The document's raw Markdown. */
+    sourceText;
+    /** Absolute offset at which each line begins. */
+    lineStarts;
+    /**
+     * Indexes a source for line access.
+     *
+     * @param sourceText - The document's raw Markdown
+     */
+    constructor(sourceText) {
+        this.sourceText = sourceText;
+        this.lineStarts = indexLineStarts(sourceText);
+    }
+    /**
+     * Returns one line of the source, without its line ending.
+     *
+     * @param line - Zero-based line number
+     * @returns The line's text, or `undefined` when the line does not exist
+     */
+    readLine(line) {
+        const start = this.lineStarts[line];
+        if (start === undefined) {
+            return undefined;
+        }
+        const next = this.lineStarts[line + 1] ?? this.sourceText.length;
+        return this.sourceText.slice(start, next).replace(/(?:\r\n|\n|\r)$/, '');
+    }
+    /**
+     * Reports whether a Markdown line also begins a line for a search engine.
+     *
+     * Markdown ends a line at LF, CRLF or a lone CR; ripgrep and grep end one
+     * only at LF. So a line that follows a lone CR is, to a search, the middle
+     * of the line before it, and no recipe anchored with `^` can match it.
+     *
+     * @param line - Zero-based Markdown line number
+     * @returns `true` when the line starts the file or follows an LF
+     */
+    tellStartsSearchLine(line) {
+        const start = this.lineStarts[line];
+        return start === 0 || (start !== undefined && this.sourceText.charAt(start - 1) === '\n');
+    }
+    /**
+     * Returns the source a range covers.
+     *
+     * @param range - A range within the document
+     * @returns Its raw source, or `undefined` when it lies outside the document
+     */
+    slice(range) {
+        const start = this.offsetOf(range.start);
+        const end = this.offsetOf(range.end);
+        return start === undefined || end === undefined ? undefined : this.sourceText.slice(start, end);
+    }
+    /**
+     * Converts a line/character position into an absolute source offset.
+     *
+     * @param position - A position within the document
+     * @returns The offset, or `undefined` when the line is out of range
+     */
+    offsetOf(position) {
+        const lineStart = this.lineStarts[position.line];
+        return lineStart === undefined ? undefined : lineStart + position.character;
+    }
+}
+//# sourceMappingURL=source-lines.js.map

package/dist/source-lines.js.map

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

package/dist/spec-version.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Specification Version
+ *
+ * The version of the ECR specification this package implements.
+ *
+ * The specification and the package are versioned independently: a linter bug
+ * fix is a package release that leaves the grammar untouched, and a
+ * specification clarification may need no package release at all. Tying the
+ * two numbers together would force one to move whenever the other did.
+ *
+ * This constant is the single source of truth for the implemented version. A
+ * test asserts that the specification document and the README state the same
+ * number, so the three cannot drift apart.
+ */
+/**
+ * The ECR specification version implemented by this package.
+ */
+export declare const ECR_SPEC_VERSION: string;
+//# sourceMappingURL=spec-version.d.ts.map

package/dist/spec-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-version.d.ts","sourceRoot":"","sources":["../src/spec-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAgB,CAAC"}

package/dist/spec-version.js

@@ -0,0 +1,19 @@
+/**
+ * Specification Version
+ *
+ * The version of the ECR specification this package implements.
+ *
+ * The specification and the package are versioned independently: a linter bug
+ * fix is a package release that leaves the grammar untouched, and a
+ * specification clarification may need no package release at all. Tying the
+ * two numbers together would force one to move whenever the other did.
+ *
+ * This constant is the single source of truth for the implemented version. A
+ * test asserts that the specification document and the README state the same
+ * number, so the three cannot drift apart.
+ */
+/**
+ * The ECR specification version implemented by this package.
+ */
+export const ECR_SPEC_VERSION = '2.0.0';
+//# sourceMappingURL=spec-version.js.map

package/dist/spec-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-version.js","sourceRoot":"","sources":["../src/spec-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAW,OAAO,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,219 @@
+/**
+ * ECR Output Schema Types
+ *
+ * Derived from section 1#10 of the ECR Structural Specification (doc 1).
+ *
+ * These types define the normative output schema produced by the ECR linter.
+ * The schema is host-agnostic and designed for consumption by graph engines,
+ * Language Servers, Obsidian plugins, and other host environments.
+ */
+/**
+ * Stable document identity.
+ *
+ * Grammar: `Digit+ ("." Digit+)*`
+ *
+ * @example "3.1"
+ */
+export type DocID = string;
+/**
+ * Stable section identity.
+ *
+ * Grammar: `DocID "#" SectionPath`, where `SectionPath ::= Digit+ ("." Digit+)*`
+ *
+ * The text before the `#` is the owning document's DocID.
+ *
+ * @example "3.1#2"
+ */
+export type SectionID = string;
+/**
+ * Severity level for a diagnostic emitted by the ECR linter.
+ */
+export type DiagnosticSeverity = "error" | "warning" | "info";
+/**
+ * A zero-based line/character position within a document.
+ */
+export interface Position {
+    /** Zero-based line number. */
+    readonly line: number;
+    /** Zero-based character offset within the line. */
+    readonly character: number;
+}
+/**
+ * A contiguous range within a document defined by a start and end position.
+ */
+export interface PositionRange {
+    /** Inclusive start of the range. */
+    readonly start: Position;
+    /** Exclusive end of the range. */
+    readonly end: Position;
+}
+/**
+ * A host-agnostic diagnostic produced by the ECR linter.
+ *
+ * Diagnostics can be mapped into LSP diagnostics or rendered in other UIs.
+ */
+export interface Diagnostic {
+    /** Severity of this diagnostic. */
+    readonly severity: DiagnosticSeverity;
+    /** Identifier of the validation rule that produced this diagnostic. */
+    readonly ruleId: string;
+    /** Human-readable description of the issue. */
+    readonly message: string;
+    /** Opaque, host-provided URI of the source document. */
+    readonly uri: string;
+    /**
+     * Positional range within the source document.
+     * Optional; depends on whether the Markdown parser provides positional metadata.
+     */
+    readonly range?: PositionRange;
+    /** DocID of the document, when determinable. */
+    readonly docId?: DocID;
+    /** SectionID providing structural context, when determinable. */
+    readonly sectionId?: SectionID;
+    /** Arbitrary structured data associated with this diagnostic. */
+    readonly data?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Semantic direction label for a document-level reference edge.
+ *
+ * Direction describes the relationship meaning; it does not alter edge orientation.
+ */
+export type ReferenceDirection = "authority" | "dependency" | "constraint" | "contract";
+/**
+ * The keyword form of an inline reference.
+ */
+export type InlineReferenceKind = "see" | "per";
+/**
+ * A single section extracted from a validated ECR document.
+ *
+ * The H1 heading is represented as the root section node. All numbered
+ * headings of depth \>= 2 are child section nodes.
+ */
+export interface SectionNode {
+    /** DocID (for the root H1 node) or SectionID (for sub-headings). */
+    readonly id: DocID | SectionID;
+    /**
+     * Human-readable heading text.
+     * Extracted for display and diagnostics only; not part of ECR structural identity.
+     */
+    readonly title: string;
+    /** Markdown heading depth (1 for H1, 2 for H2, etc.). */
+    readonly headingDepth: number;
+    /**
+     * Identifier of the nearest preceding heading whose depth is exactly
+     * `headingDepth - 1`. Absent for the root H1 node.
+     */
+    readonly parentId?: DocID | SectionID;
+}
+/**
+ * A document-level typed edge extracted from a `## References` list item.
+ *
+ * Edges are directed from the current document to the referenced document.
+ */
+export interface ReferenceEdge {
+    /** DocID of the document containing the reference. */
+    readonly fromDocId: DocID;
+    /** Target DocID declared in the References entry. */
+    readonly toDocId: DocID;
+    /** Semantic direction label for this edge. */
+    readonly direction: ReferenceDirection;
+    /** Non-empty explanation text extracted from the References entry. */
+    readonly explanation: string;
+    /**
+     * Non-empty title text extracted from the References entry.
+     * For display and diagnostics only; not part of ECR structural identity.
+     */
+    readonly title: string;
+}
+/**
+ * A section-attributed edge extracted from an inline `see` or `per` reference.
+ */
+export interface InlineReferenceEdge {
+    /** Identifier of the section context where the inline reference occurs. */
+    readonly fromId: DocID | SectionID;
+    /** Target identifier referenced by the inline form. */
+    readonly toId: DocID | SectionID;
+    /** The keyword form (`see` or `per`) that produced this edge. */
+    readonly kind: InlineReferenceKind;
+}
+/**
+ * Canonical structural representation of a single validated ECR document.
+ */
+export interface ExtractedDocument {
+    /** DocID extracted from the H1 heading. */
+    readonly docId: DocID;
+    /**
+     * Document title extracted from the H1 heading.
+     * For display and diagnostics only; not part of ECR structural identity.
+     */
+    readonly title: string;
+    /** All section nodes extracted from numbered headings, including the root H1. */
+    readonly sections: readonly SectionNode[];
+    /** Document-level reference edges extracted from the `## References` section. */
+    readonly references: readonly ReferenceEdge[];
+    /** Section-level inline reference edges extracted from valid `see`/`per` forms. */
+    readonly inlineReferences: readonly InlineReferenceEdge[];
+}
+/**
+ * Input descriptor for a single-document lint operation.
+ */
+export interface LintInput {
+    /** Opaque, host-provided URI identifying the document instance. */
+    readonly uri: string;
+    /** Optional version tag for the document instance. */
+    readonly version?: number;
+}
+/**
+ * Result of a lint operation over a single Markdown document.
+ */
+export interface LintResult {
+    /** Input descriptor identifying the document that was validated. */
+    readonly input: LintInput;
+    /** Whether the document satisfies per-document ECR structural invariants. */
+    readonly ok: boolean;
+    /** Diagnostics produced during validation. */
+    readonly diagnostics: readonly Diagnostic[];
+    /**
+     * Extracted structural artefacts from the document.
+     * Present when a valid DocID is recovered and structural extraction succeeds.
+     */
+    readonly extracted?: ExtractedDocument;
+}
+/**
+ * A single document entry within a corpus validation result.
+ */
+export interface CorpusDocumentEntry {
+    /** Opaque, host-provided URI identifying the document instance. */
+    readonly uri: string;
+    /** Per-document lint result. */
+    readonly result: LintResult;
+}
+/**
+ * Global identifier index built from a validated corpus.
+ *
+ * Maps each unique identifier to the URI of the document that defines it.
+ */
+export interface CorpusIndex {
+    /** Mapping from each DocID to the URI of its defining document. */
+    readonly docIds: Readonly<Record<DocID, string>>;
+    /** Mapping from each SectionID to the URI of its defining document. */
+    readonly sectionIds: Readonly<Record<SectionID, string>>;
+}
+/**
+ * Result of validating a corpus of ECR documents.
+ *
+ * Includes per-document results, corpus-wide diagnostics, and an optional
+ * global identifier index suitable for graph construction.
+ */
+export interface CorpusResult {
+    /** Per-document lint results for every document in the corpus. */
+    readonly documents: readonly CorpusDocumentEntry[];
+    /**
+     * Global identifier index.
+     * Present when corpus-wide indexing succeeds.
+     */
+    readonly index?: CorpusIndex;
+    /** Corpus-wide diagnostics (e.g. duplicate DocIDs, unresolved references). */
+    readonly diagnostics: readonly Diagnostic[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,11 @@
+/**
+ * ECR Output Schema Types
+ *
+ * Derived from section 1#10 of the ECR Structural Specification (doc 1).
+ *
+ * These types define the normative output schema produced by the ECR linter.
+ * The schema is host-agnostic and designed for consumption by graph engines,
+ * Language Servers, Obsidian plugins, and other host environments.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}