@timiagama/ecr 0.0.1 → 0.1.0

package/src/source-alignment.ts

@@ -0,0 +1,209 @@
+/**
+ * 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 decoded character reference: its text, and how much source it occupied. */
+interface Expansion {
+  /** The characters the reference produces. */
+  readonly text: string;
+  /** How many source characters the reference itself spans. */
+  readonly length: number;
+}
+
+/** A line ending as Markdown recognises it. */
+const LINE_ENDING: RegExp = /^(?:\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: RegExp = /^[ \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: RegExp = /^[ \t]*/;
+
+/** A named character reference, such as `&` or `fj`. */
+const NAMED_REFERENCE: RegExp = /^&[a-zA-Z][a-zA-Z0-9]{1,31};/;
+
+/** A numeric character reference, decimal or hexadecimal. */
+const NUMERIC_REFERENCE: RegExp = /^&#(?:([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: string,
+  parsed: string,
+): readonly number[] | undefined {
+  const map: number[] = [];
+  let sourceIndex: number = 0;
+  let parsedIndex: number = 0;
+
+  while (parsedIndex < parsed.length) {
+    if (sourceIndex >= source.length) {
+      return undefined;
+    }
+
+    const remaining: string = source.slice(sourceIndex);
+    const parsedCharacter: string = 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: Expansion | undefined =
+      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: string | undefined = LINE_ENDING.exec(parsed.slice(parsedIndex))?.[0];
+
+    if (parsedEnding !== undefined) {
+      // Spaces and tabs before the break exist only in the source.
+      const dropped: string = TRAILING_WHITESPACE.exec(remaining)?.[0] ?? '';
+      const sourceEnding: string | undefined =
+        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: string): Expansion | undefined {
+  const numeric: RegExpExecArray | null = NUMERIC_REFERENCE.exec(remaining);
+
+  if (numeric !== null) {
+    const decimal: string | undefined = numeric[1];
+    const value: string = decimal ?? numeric[2] ?? '';
+
+    return {
+      text: decodeNumericCharacterReference(value, decimal === undefined ? 16 : 10),
+      length: numeric[0].length,
+    };
+  }
+
+  const named: RegExpExecArray | null = NAMED_REFERENCE.exec(remaining);
+
+  if (named === null) {
+    return undefined;
+  }
+
+  const decoded: string | false = decodeNamedCharacterReference(named[0].slice(1, -1));
+
+  return decoded === false ? undefined : { text: decoded, length: named[0].length };
+}

package/src/source-lines.ts

@@ -0,0 +1,123 @@
+/**
+ * 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 function indexLineStarts(sourceText: string): readonly number[] {
+  const starts: number[] = [0];
+
+  for (let index = 0; index < sourceText.length; index += 1) {
+    const character: string = sourceText.charAt(index);
+
+    if (character === '\r') {
+      const isCarriageReturnLineFeed: boolean = 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. */
+  private readonly sourceText: string;
+
+  /** Absolute offset at which each line begins. */
+  private readonly lineStarts: readonly number[];
+
+  /**
+   * Indexes a source for line access.
+   *
+   * @param sourceText - The document's raw Markdown
+   */
+  public constructor(sourceText: string) {
+    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
+   */
+  public readLine(line: number): string | undefined {
+    const start: number | undefined = this.lineStarts[line];
+
+    if (start === undefined) {
+      return undefined;
+    }
+
+    const next: number = 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
+   */
+  public tellStartsSearchLine(line: number): boolean {
+    const start: number | undefined = 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
+   */
+  public slice(range: PositionRange): string | undefined {
+    const start: number | undefined = this.offsetOf(range.start);
+    const end: number | undefined = 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
+   */
+  public offsetOf(position: Position): number | undefined {
+    const lineStart: number | undefined = this.lineStarts[position.line];
+
+    return lineStart === undefined ? undefined : lineStart + position.character;
+  }
+}

package/src/spec-version.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 const ECR_SPEC_VERSION: string = '2.0.0';

package/src/types.ts

@@ -0,0 +1,267 @@
+/**
+ * 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.
+ */
+
+// ---------------------------------------------------------------------------
+// Identity Type Aliases (per 1#9.2)
+// ---------------------------------------------------------------------------
+
+/**
+ * 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;
+
+// ---------------------------------------------------------------------------
+// Diagnostic Types (per 1#10.3)
+// ---------------------------------------------------------------------------
+
+/**
+ * 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>>;
+}
+
+// ---------------------------------------------------------------------------
+// Reference Direction Types (per 1#9.7, 1#10.6)
+// ---------------------------------------------------------------------------
+
+/**
+ * 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";
+
+// ---------------------------------------------------------------------------
+// Inline Reference Kind (per 1#10.7)
+// ---------------------------------------------------------------------------
+
+/**
+ * The keyword form of an inline reference.
+ */
+export type InlineReferenceKind = "see" | "per";
+
+// ---------------------------------------------------------------------------
+// Extracted Structural Artefacts (per 1#10.4 - 1#10.7)
+// ---------------------------------------------------------------------------
+
+/**
+ * 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). */
+  // eslint-disable-next-line @typescript-eslint/no-duplicate-type-constituents -- Semantically distinct: DocID for H1, SectionID for depth >= 2
+  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.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-duplicate-type-constituents -- Semantically distinct: parent may be DocID (H1) or SectionID
+  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. */
+  // eslint-disable-next-line @typescript-eslint/no-duplicate-type-constituents -- Semantically distinct: source may be DocID or SectionID
+  readonly fromId: DocID | SectionID;
+  /** Target identifier referenced by the inline form. */
+  // eslint-disable-next-line @typescript-eslint/no-duplicate-type-constituents -- Semantically distinct: target may be DocID or SectionID
+  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[];
+}
+
+// ---------------------------------------------------------------------------
+// Lint Result Types (per 1#10.2)
+// ---------------------------------------------------------------------------
+
+/**
+ * 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;
+}
+
+// ---------------------------------------------------------------------------
+// Corpus Result Types (per 1#10.8)
+// ---------------------------------------------------------------------------
+
+/**
+ * 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[];
+}