@timiagama/ecr 0.0.1 → 0.1.0

package/src/ecr.ts

@@ -0,0 +1,298 @@
+/**
+ * ECR Public API -- Ecr Facade
+ *
+ * Top-level public API for the ECR structural linter.
+ *
+ * Derived from section 1#13 (Public Interface Contract) and
+ * section 1#10 (Output Schema) of the ECR Structural Specification (doc 1).
+ *
+ * This module provides the {@link Ecr} facade, which delegates
+ * per-document validation to {@link PerDocumentVisitor} and
+ * corpus-wide integrity checks to {@link CorpusValidator}.
+ *
+ * Per-document results are returned exactly as the visitor produces
+ * them: every severity is set by the rule that reports the finding.
+ *
+ * The facade applies one orchestration-level policy:
+ *
+ * **Cross-document duplicate SectionID detection**: The corpus
+ *    validator only sees SectionIDs that survive per-document
+ *    extraction (i.e., those that pass ECR102). A heading like
+ *    `## 3.1#1 - X` inside a document with DocID `4.1` fails ECR102
+ *    (it names another document) and is never extracted — yet its
+ *    SectionID text is still globally significant. The facade
+ *    performs an additional cross-document duplicate check by
+ *    collecting SectionIDs from both extracted sections and
+ *    per-document diagnostics that carry a `sectionId` field.
+ */
+
+import type {
+  LintResult,
+  CorpusResult,
+  CorpusDocumentEntry,
+  Diagnostic,
+  SectionID,
+} from "./types.js";
+
+import { PerDocumentVisitor } from "./per-document-visitor.js";
+import { CorpusValidator } from "./corpus-validator.js";
+
+// ---------------------------------------------------------------------------
+// Input Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A single document supplied to corpus validation.
+ *
+ * Each entry provides the Markdown text and an opaque, host-provided URI
+ * that identifies the document instance.
+ */
+export interface CorpusDocumentInput {
+  /** Opaque, host-provided URI identifying the document instance. */
+  readonly uri: string;
+
+  /** Raw Markdown text of the document. */
+  readonly markdownText: string;
+
+  /** Optional version tag for the document instance. */
+  readonly version?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * The corpus-level rule ID for duplicate SectionIDs detected by the facade.
+ */
+const CORPUS_DUPLICATE_SECTION_ID_RULE_ID: string = 'corpus/duplicate-section-id';
+
+// ---------------------------------------------------------------------------
+// Public Facade
+// ---------------------------------------------------------------------------
+
+/**
+ * Top-level public API for the ECR structural linter.
+ *
+ * Provides two operations:
+ * - Single-document linting via {@link Ecr.lintDocument}
+ * - Corpus-wide validation via {@link Ecr.validateCorpus}
+ *
+ * This class is stateless across invocations. Successive calls with
+ * identical inputs produce identical results.
+ */
+export class Ecr {
+  /**
+   * Lint a single Markdown document against per-document ECR structural invariants.
+   *
+   * Creates a {@link PerDocumentVisitor} for the given document and delegates
+   * the linting operation to it.
+   *
+   * @param uri - Opaque, host-provided URI identifying the document instance.
+   * @param markdownText - Raw Markdown text of the document.
+   * @param version - Optional version tag propagated through to the result.
+   * @returns Structured lint result containing diagnostics and optionally extracted artefacts.
+   */
+  public lintDocument(
+    uri: string,
+    markdownText: string,
+    version?: number,
+  ): LintResult {
+    const visitor: PerDocumentVisitor = new PerDocumentVisitor({
+      uri,
+      ...(version !== undefined ? { version } : {}),
+    });
+
+    return visitor.lint(markdownText);
+  }
+
+  /**
+   * Validate a corpus of Markdown documents.
+   *
+   * Executes per-document linting on every document (Pass 1), then performs
+   * corpus-wide integrity checks on successfully linted documents (Pass 2).
+   *
+   * After the standard corpus validation, the facade performs an additional
+   * cross-document duplicate SectionID check that considers SectionIDs from
+   * per-document diagnostics (not just extracted sections), ensuring that
+   * headings rejected by ECR102 (e.g., wrong DocID prefix) still participate
+   * in global uniqueness enforcement.
+   *
+   * @param documents - Collection of documents to validate.
+   * @returns Corpus result containing per-document results, corpus-wide diagnostics, and an optional global identifier index.
+   */
+  public validateCorpus(
+    documents: readonly CorpusDocumentInput[],
+  ): CorpusResult {
+    // Pass 1: Per-document linting
+    const entries: readonly CorpusDocumentEntry[] = documents.map(
+      (document: CorpusDocumentInput): CorpusDocumentEntry => {
+        const lintResult: LintResult = this.lintDocument(
+          document.uri,
+          document.markdownText,
+          document.version,
+        );
+
+        return {
+          uri: document.uri,
+          result: lintResult,
+        };
+      },
+    );
+
+    // Pass 2: Corpus-wide validation (standard checks)
+    const validator: CorpusValidator = new CorpusValidator();
+    const baseCorpusResult: CorpusResult = validator.validateCorpus(entries);
+
+    // Pass 2b: Additional facade-level cross-document duplicate SectionID check
+    const additionalDiagnostics: readonly Diagnostic[] =
+      this.detectCrossDocumentDuplicateSectionIds(entries);
+
+    if (additionalDiagnostics.length === 0) {
+      return baseCorpusResult;
+    }
+
+    // Merge additional diagnostics into the corpus result
+    const mergedDiagnostics: readonly Diagnostic[] = [
+      ...baseCorpusResult.diagnostics,
+      ...additionalDiagnostics,
+    ];
+
+    const corpusResult: CorpusResult = {
+      documents: baseCorpusResult.documents,
+      diagnostics: mergedDiagnostics,
+      ...(baseCorpusResult.index !== undefined
+        ? { index: baseCorpusResult.index }
+        : {}),
+    };
+
+    return corpusResult;
+  }
+
+  // -------------------------------------------------------------------------
+  // Private: Cross-document duplicate SectionID detection
+  // -------------------------------------------------------------------------
+
+  /**
+   * Detects duplicate SectionIDs across documents by examining both
+   * extracted sections and per-document diagnostics.
+   *
+   * The standard {@link CorpusValidator} only checks extracted sections
+   * (those that pass ECR102). This method extends coverage to include
+   * SectionIDs mentioned in per-document diagnostics — for example,
+   * a heading `## 3.1#1 - X` inside a document with DocID `4.1` fails
+   * ECR102 (it names another document) but the SectionID `3.1#1` is still
+   * present in the diagnostic's `sectionId` field. If document `3.1` also
+   * defines `3.1#1`, that is a corpus-level duplicate.
+   *
+   * This method only emits diagnostics for duplicates NOT already
+   * detected by the standard corpus validator (i.e., duplicates involving
+   * at least one SectionID from a diagnostic rather than an extracted section).
+   *
+   * @param entries - The per-document lint entries from Pass 1
+   * @returns Additional corpus-level diagnostics for duplicate SectionIDs
+   */
+  private detectCrossDocumentDuplicateSectionIds(
+    entries: readonly CorpusDocumentEntry[],
+  ): readonly Diagnostic[] {
+    // Collect all SectionIDs per document from both extracted sections
+    // and per-document diagnostics
+    const sectionIdToUris: Map<SectionID, string[]> =
+      new Map<SectionID, string[]>();
+
+    for (const entry of entries) {
+      const documentSectionIds: Set<SectionID> = new Set<SectionID>();
+
+      // Collect from extracted sections
+      if (entry.result.extracted !== undefined) {
+        for (const section of entry.result.extracted.sections) {
+          // Skip root H1 nodes — their id is the DocID, handled separately
+          if (section.headingDepth === 1) {
+            continue;
+          }
+
+          documentSectionIds.add(section.id);
+        }
+      }
+
+      // Collect from per-document diagnostics that carry a sectionId field
+      for (const diagnostic of entry.result.diagnostics) {
+        if (diagnostic.sectionId !== undefined) {
+          documentSectionIds.add(diagnostic.sectionId);
+        }
+      }
+
+      // Register each SectionID from this document
+      for (const sectionId of documentSectionIds) {
+        const existingUris: string[] | undefined = sectionIdToUris.get(sectionId);
+
+        if (existingUris !== undefined) {
+          // Only add this URI if it is not already listed
+          // (a document may have both an extracted section and a diagnostic
+          // for the same SectionID)
+          if (!existingUris.includes(entry.uri)) {
+            existingUris.push(entry.uri);
+          }
+        } else {
+          sectionIdToUris.set(sectionId, [entry.uri]);
+        }
+      }
+    }
+
+    // Find duplicates — SectionIDs that appear in more than one document
+    const additionalDiagnostics: Diagnostic[] = [];
+
+    for (const [sectionId, uris] of sectionIdToUris) {
+      if (uris.length <= 1) {
+        continue;
+      }
+
+      // The corpus validator detects a duplicate when the SectionID
+      // appears in extracted.sections of 2+ documents. Count how many
+      // of the duplicate URIs have this SectionID in their extracted
+      // sections to avoid emitting redundant diagnostics.
+      let extractedCount: number = 0;
+
+      for (const uri of uris) {
+        const entryForUri: CorpusDocumentEntry | undefined = entries.find(
+          (candidateEntry: CorpusDocumentEntry): boolean =>
+            candidateEntry.uri === uri,
+        );
+
+        if (entryForUri?.result.extracted !== undefined) {
+          const hasExtractedSection: boolean =
+            entryForUri.result.extracted.sections.some(
+              (section): boolean =>
+                section.headingDepth !== 1 && section.id === sectionId,
+            );
+
+          if (hasExtractedSection) {
+            extractedCount = extractedCount + 1;
+          }
+        }
+      }
+
+      // If 2+ documents have this SectionID in their extracted sections,
+      // the corpus validator already detected the duplicate. Skip.
+      if (extractedCount >= 2) {
+        continue;
+      }
+
+      // Emit diagnostics for this duplicate
+      for (const uri of uris) {
+        const diagnosticForUri: Diagnostic = {
+          severity: 'error',
+          ruleId: CORPUS_DUPLICATE_SECTION_ID_RULE_ID,
+          message: `Duplicate SectionID '${sectionId}' found in multiple documents`,
+          uri,
+          sectionId,
+          data: { duplicateUris: uris },
+        };
+
+        additionalDiagnostics.push(diagnosticForUri);
+      }
+    }
+
+    return additionalDiagnostics;
+  }
+}

package/src/glob-pattern.ts

@@ -0,0 +1,242 @@
+/**
+ * Glob Patterns
+ *
+ * The minimal glob syntax used by `--ignore` and `.ecrignore`: `*` matches any
+ * run of characters except `/`, `**` matches any run including `/`, a `**`
+ * immediately before a slash matches zero or more whole directories, and `?`
+ * matches one character other than `/`. Everything else matches literally, and
+ * a pattern must match a whole path.
+ *
+ * A pattern is matched by walking the path once for each part of the pattern,
+ * so the work is bounded by the pattern's length times the path's length. An
+ * equivalent regular expression is not: patterns such as `*a*a*a*a*a*a*a*ab`
+ * make a backtracking engine explore exponentially many ways to divide the
+ * path between the wildcards, which let a single crafted ignore pattern hang
+ * the linter. Matching here is a table, so no such pattern exists.
+ */
+
+/** One part of a compiled pattern. */
+type GlobPart =
+  /** Characters that must appear exactly. */
+  | { readonly kind: 'literal'; readonly text: string }
+  /** `?`: one character other than `/`. */
+  | { readonly kind: 'oneCharacter' }
+  /** `*`: any run of characters within one path segment. */
+  | { readonly kind: 'withinSegment' }
+  /** `**` not followed by `/`: any run of characters at all. */
+  | { readonly kind: 'acrossSegments' }
+  /** `**` before a slash: zero or more whole directories. */
+  | { readonly kind: 'wholeDirectories' };
+
+/**
+ * A compiled glob pattern that can be matched against a path.
+ */
+export class GlobPattern {
+  /** The pattern's parts, in order. */
+  private readonly parts: readonly GlobPart[];
+
+  /**
+   * Compiles a pattern.
+   *
+   * @param pattern - The glob pattern
+   */
+  public constructor(pattern: string) {
+    this.parts = GlobPattern.compile(pattern);
+  }
+
+  /**
+   * Determines whether a path matches the whole pattern.
+   *
+   * @param path - The path to match, using forward slashes
+   * @returns `true` when the pattern matches all of it
+   */
+  public matches(path: string): boolean {
+    const length: number = path.length;
+
+    // `reached[index]` says whether the parts considered so far can match the
+    // rest of the path from `index`. It starts as the answer for no parts at
+    // all: only a path already consumed to its end matches nothing more.
+    let reached: boolean[] = new Array<boolean>(length + 1).fill(false);
+    reached[length] = true;
+
+    // Each part is added in front of the answer for the parts after it, so
+    // they are considered last one first.
+    for (const part of [...this.parts].reverse()) {
+      reached = GlobPattern.matchPart(part, path, reached);
+    }
+
+    return reached[0] ?? false;
+  }
+
+  /**
+   * Works out, for every position in the path, whether one part followed by
+   * the parts after it can match the rest of the path from there.
+   *
+   * @param part - The part being added in front
+   * @param path - The path being matched
+   * @param following - The same answer for the parts after this one
+   * @returns The answer for this part and everything after it
+   */
+  private static matchPart(part: GlobPart, path: string, following: readonly boolean[]): boolean[] {
+    switch (part.kind) {
+      case 'literal':
+        return GlobPattern.matchLiteral(part.text, path, following);
+
+      case 'oneCharacter':
+        return GlobPattern.matchOneCharacter(path, following);
+
+      case 'withinSegment':
+        return GlobPattern.matchWildcard(path, following, true);
+
+      case 'acrossSegments':
+        return GlobPattern.matchWildcard(path, following, false);
+
+      case 'wholeDirectories':
+        return GlobPattern.matchWholeDirectories(path, following);
+    }
+  }
+
+  /**
+   * Matches characters that must appear exactly.
+   *
+   * @param text - The characters the pattern gives
+   * @param path - The path being matched
+   * @param following - Where the parts after this one can match from
+   * @returns Where this part and everything after it can match from
+   */
+  private static matchLiteral(
+    text: string,
+    path: string,
+    following: readonly boolean[],
+  ): boolean[] {
+    const reached: boolean[] = new Array<boolean>(path.length + 1).fill(false);
+
+    for (let index: number = 0; index + text.length <= path.length; index += 1) {
+      reached[index] = path.startsWith(text, index) && (following[index + text.length] ?? false);
+    }
+
+    return reached;
+  }
+
+  /**
+   * Matches `?`: exactly one character, which may not be a separator.
+   *
+   * @param path - The path being matched
+   * @param following - Where the parts after this one can match from
+   * @returns Where this part and everything after it can match from
+   */
+  private static matchOneCharacter(path: string, following: readonly boolean[]): boolean[] {
+    const reached: boolean[] = new Array<boolean>(path.length + 1).fill(false);
+
+    for (let index: number = 0; index < path.length; index += 1) {
+      reached[index] = path[index] !== '/' && (following[index + 1] ?? false);
+    }
+
+    return reached;
+  }
+
+  /**
+   * Matches `*` or `**`: a run of any length.
+   *
+   * A wildcard either stops where it is and lets the parts after it match, or
+   * takes one more character and asks itself the same question. Answering
+   * from the end of the path backwards means each position is settled once,
+   * whereas a regular expression would try the divisions one after another.
+   *
+   * @param path - The path being matched
+   * @param following - Where the parts after this one can match from
+   * @param withinSegment - Whether the run must stay inside one path segment
+   * @returns Where this part and everything after it can match from
+   */
+  private static matchWildcard(
+    path: string,
+    following: readonly boolean[],
+    withinSegment: boolean,
+  ): boolean[] {
+    const reached: boolean[] = new Array<boolean>(path.length + 1).fill(false);
+
+    for (let index: number = path.length; index >= 0; index -= 1) {
+      const canTakeOneMore: boolean =
+        index < path.length && (!withinSegment || path[index] !== '/');
+
+      reached[index] =
+        (following[index] ?? false) || (canTakeOneMore && (reached[index + 1] ?? false));
+    }
+
+    return reached;
+  }
+
+  /**
+   * Matches a `**` immediately before a slash: zero or more whole directories.
+   *
+   * @param path - The path being matched
+   * @param following - Where the parts after this one can match from
+   * @returns Where this part and everything after it can match from
+   */
+  private static matchWholeDirectories(path: string, following: readonly boolean[]): boolean[] {
+    // Whole directories are taken whole, so this part matches either nothing
+    // at all, or a run of characters ending at a separator.
+    const endsAtSlash: boolean[] = new Array<boolean>(path.length + 1).fill(false);
+
+    for (let index: number = path.length - 1; index >= 0; index -= 1) {
+      endsAtSlash[index] =
+        (path[index] === '/' && (following[index + 1] ?? false)) ||
+        (endsAtSlash[index + 1] ?? false);
+    }
+
+    return endsAtSlash.map(
+      (endsHere: boolean, index: number): boolean => (following[index] ?? false) || endsHere,
+    );
+  }
+
+  /**
+   * Splits a pattern into its parts, gathering runs of ordinary characters
+   * into one literal.
+   *
+   * @param pattern - The glob pattern
+   * @returns The parts, in order
+   */
+  private static compile(pattern: string): readonly GlobPart[] {
+    const parts: GlobPart[] = [];
+    let literal: string = '';
+
+    /** Closes off any literal gathered so far. */
+    const flushLiteral = (): void => {
+      if (literal !== '') {
+        parts.push({ kind: 'literal', text: literal });
+        literal = '';
+      }
+    };
+
+    for (let index: number = 0; index < pattern.length; index += 1) {
+      const character: string = pattern[index] ?? '';
+
+      if (character === '*') {
+        flushLiteral();
+
+        if (pattern[index + 1] === '*' && pattern[index + 2] === '/') {
+          parts.push({ kind: 'wholeDirectories' });
+          index += 2;
+        } else if (pattern[index + 1] === '*') {
+          parts.push({ kind: 'acrossSegments' });
+          index += 1;
+        } else {
+          parts.push({ kind: 'withinSegment' });
+        }
+        continue;
+      }
+
+      if (character === '?') {
+        flushLiteral();
+        parts.push({ kind: 'oneCharacter' });
+        continue;
+      }
+
+      literal += character;
+    }
+
+    flushLiteral();
+
+    return parts;
+  }
+}