@untangle-code/context-artifacts 0.0.0-stage → 0.1.1

package/src/staleness.ts

@@ -0,0 +1,69 @@
+/**
+ * Staleness detection (spec.md §19.2: "Artefaktkonfiguration und
+ * Inhaltshash MÜSSEN Staleness bestimmen.").
+ *
+ * A context artifact goes stale when EITHER its configuration changes
+ * (e.g. `include`/`exclude` edited, `description` reworded, `path`
+ * repointed) OR its underlying file content changes (a file was edited,
+ * added, or removed), independently of each other — so both are hashed
+ * separately and compared separately; collapsing them into one combined
+ * hash would make "what changed" undiagnosable from the stored snapshot
+ * alone.
+ */
+import type { ArtifactDocument, ContextArtifactConfig } from "@untangle-code/domain";
+import { canonicalJson, sha256Hex } from "@untangle-code/domain";
+
+/** The two independent inputs to staleness (spec.md §19.2), snapshotted together. */
+export interface ArtifactStalenessSnapshot {
+  /** SHA-256 of the canonical JSON of the artifact's `ContextArtifactConfig`. */
+  configHash: string;
+  /**
+   * SHA-256 combining every current document's path and content hash
+   * (spec.md §19.2's "Inhaltshash"). Sorted by path first so the result is
+   * independent of file-discovery order.
+   */
+  contentHash: string;
+}
+
+/** SHA-256 of an artifact's canonical configuration (spec.md §19.2). */
+export function computeArtifactConfigHash(config: ContextArtifactConfig): string {
+  return sha256Hex(canonicalJson(config));
+}
+
+/**
+ * Combines the per-document `contentHash`es (already SHA-256 of each
+ * document's raw content, per `ArtifactDocument.contentHash`) into one
+ * artifact-level content hash. A directory-backed artifact is stale when
+ * any file's content changes, a file is added, or a file is removed — all
+ * three change this combined hash.
+ */
+export function computeArtifactContentHash(documents: readonly ArtifactDocument[]): string {
+  const sorted = [...documents]
+    .map((document) => ({ path: document.path, contentHash: document.contentHash }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+  return sha256Hex(canonicalJson(sorted));
+}
+
+/** Snapshots both staleness inputs for one artifact's current config + documents. */
+export function computeArtifactStalenessSnapshot(
+  config: ContextArtifactConfig,
+  documents: readonly ArtifactDocument[],
+): ArtifactStalenessSnapshot {
+  return {
+    configHash: computeArtifactConfigHash(config),
+    contentHash: computeArtifactContentHash(documents),
+  };
+}
+
+/**
+ * True when `current` differs from the last-indexed `previous` snapshot in
+ * either the config hash or the content hash (spec.md §19.2) — a pure
+ * comparison; persisting/loading the previous snapshot is a metadata-store
+ * concern outside this package.
+ */
+export function isArtifactStale(
+  previous: ArtifactStalenessSnapshot,
+  current: ArtifactStalenessSnapshot,
+): boolean {
+  return previous.configHash !== current.configHash || previous.contentHash !== current.contentHash;
+}

package/src/text/delimiter-balance.ts

@@ -0,0 +1,295 @@
+/**
+ * Plausibilitätsprüfung von Fragmentgrenzen (WP-118, BUILD_PLAN §12 E4).
+ *
+ * `coverage.ts` beantwortet die Frage „**fehlt** etwas?" — es rechnet
+ * Byte-Abdeckung und meldet jeden Bereich, der in keinem Chunk landet.
+ * Diese Frage ist blind gegenüber dem zweiten Fehlerbild: es fehlt nichts,
+ * aber es ist **falsch geschnitten**. Der Auslöser war die SQL-Zerlegung
+ * (`adapters/sql.ts`), die `INSERT INTO t VALUES ('it\'s a test; nested
+ * clause', 2);` in zwei syntaktisch kaputte Fragmente zerriss — bei
+ * lückenloser Byte-Abdeckung, ohne leere oder überlappende Ranges, also bei
+ * **null** Ledger-Einträgen. Der Verlust ist real (kein Fragment ist ein
+ * gültiges Statement, die Einbettung beider ist Müll), nur eben unsichtbar.
+ *
+ * Dieses Modul liefert das fehlende Signal, format-agnostisch und ohne
+ * Grammatik: ein korrekt geschnittenes Fragment einer klammer- und
+ * zeichenketten-strukturierten Sprache ist in sich **ausbalanciert**. Bleibt
+ * eine Zeichenkette, ein Blockkommentar, ein Heredoc oder eine Klammer am
+ * Fragmentende offen, dann verlief die Schnittkante mitten durch ein
+ * Konstrukt — unabhängig davon, welcher Adapter geschnitten hat und warum.
+ *
+ * Bewusste Asymmetrie zum jeweiligen Zerleger: dieser Prüfer darf
+ * **misstrauischer** sein als der Zerleger. Ein Fehlalarm kostet eine
+ * Warnzeile, ein verschwiegener Fehlschnitt kostet einen unbrauchbaren
+ * Chunk (E4). Deshalb kennt er z. B. Dollar-Quoting auch dort, wo ein
+ * Dialekt es nicht erwarten ließe.
+ *
+ * Was er NICHT ist: ein Parser. Er kennt keine Schlüsselwörter, keine
+ * Ausdrücke, keine Typen. Ein Fragment, das balanciert und trotzdem
+ * bedeutungslos ist (`FROM orders WHERE`), passiert ihn unbeanstandet. Das
+ * ist die dokumentierte Grenze — er schließt die Lücke „mitten durch ein
+ * Konstrukt geschnitten", nicht „semantisch unvollständig".
+ */
+
+/** Eine Zeichenketten-/Bezeichner-Anführungskonvention (`'…'`, `"…"`, `` `…` ``). */
+export interface QuoteRule {
+  /** Öffnende Zeichenfolge, meist ein einzelnes Zeichen. */
+  readonly open: string;
+  /** Schließende Zeichenfolge; bei symmetrischen Anführungszeichen gleich `open`. */
+  readonly close: string;
+  /** Ob ein `\` innerhalb des Literals das folgende Zeichen maskiert (dialektabhängig, siehe `adapters/sql.ts`). */
+  readonly backslashEscapes: boolean;
+  /** Ob ein verdoppeltes Schlusszeichen (`''`) im Literal ein maskiertes Anführungszeichen ist. */
+  readonly doubledEscapes: boolean;
+  /** Ob das Literal einen Zeilenumbruch enthalten darf. Ist es das nicht, ist ein Zeilenende im Literal selbst schon ein Befund. */
+  readonly spansLines: boolean;
+}
+
+/** Ein Klammerpaar, dessen Verschachtelung aufgehen muss. */
+export interface BracketRule {
+  readonly open: string;
+  readonly close: string;
+}
+
+/** Ein Blockkommentar-Paar (`/*` … `*\/`). */
+export interface BlockCommentRule {
+  readonly open: string;
+  readonly close: string;
+}
+
+/**
+ * Heredoc-Konvention. Bisher nur `"hcl"`: `<<TAG` bzw. `<<-TAG`, beendet
+ * durch eine Zeile, deren getrimmter Inhalt genau `TAG` ist. Der Inhalt
+ * eines Heredocs ist Rohtext — Klammern und Anführungszeichen darin zählen
+ * nicht, sonst meldet jedes eingebettete Shell-Skript einen Fehlalarm.
+ */
+export type HeredocStyle = "hcl";
+
+export interface DelimiterScanOptions {
+  readonly quotes: readonly QuoteRule[];
+  readonly brackets: readonly BracketRule[];
+  /** Zeilenkommentar-Präfixe (`"--"`, `"//"`, `"#"`), in Prüfreihenfolge. */
+  readonly lineComments: readonly string[];
+  readonly blockComment?: BlockCommentRule;
+  /**
+   * `$tag$ … $tag$`-Literale erkennen. Ein Öffner zählt nur, wenn davor
+   * kein Bezeichnerzeichen steht — sonst würde ein Bezeichner mit zwei
+   * `$` (`my$col$x`) fälschlich ein Literal öffnen.
+   */
+  readonly dollarQuotedStrings?: boolean;
+  readonly heredocs?: HeredocStyle;
+}
+
+export type DelimiterImbalanceKind =
+  | "unterminated_string"
+  | "unterminated_block_comment"
+  | "unterminated_heredoc"
+  | "unclosed_bracket"
+  | "unmatched_closing_bracket";
+
+export interface DelimiterImbalance {
+  readonly kind: DelimiterImbalanceKind;
+  /** Das beteiligte Trennzeichen, wörtlich (`"'"`, `"("`, `"<<EOF"`). */
+  readonly delimiter: string;
+  /** 0-basierter Offset in der geprüften Zeichenkette (UTF-16-Einheiten), an dem das Konstrukt geöffnet wurde. */
+  readonly offset: number;
+  /** 1-basierte Zeile INNERHALB des geprüften Fragments (nicht des Dokuments). */
+  readonly line: number;
+}
+
+const IDENTIFIER_CHARACTER = /[A-Za-z0-9_]/;
+const IDENTIFIER_START = /[A-Za-z_]/;
+const HEREDOC_OPEN = /<<-?([A-Za-z_][A-Za-z0-9_]*)/y;
+
+/** Höchstzahl gemeldeter Befunde je Fragment — ein durchgehend kaputtes Fragment soll den Ledger nicht fluten. */
+const MAX_IMBALANCES = 8;
+
+function lineOf(text: string, offset: number): number {
+  let line = 1;
+  for (let i = 0; i < offset && i < text.length; i += 1) {
+    if (text[i] === "\n") line += 1;
+  }
+  return line;
+}
+
+/**
+ * `$tag$`-Öffner an Position `i`, oder `undefined`. Der Tag darf leer sein
+ * (`$$`); ein vorangehendes Bezeichnerzeichen verhindert die Erkennung.
+ */
+function matchDollarQuote(text: string, i: number): string | undefined {
+  if (text[i] !== "$") return undefined;
+  const before = i > 0 ? text[i - 1]! : "";
+  if (before !== "" && (IDENTIFIER_CHARACTER.test(before) || before === "$")) return undefined;
+  let j = i + 1;
+  if (j < text.length && IDENTIFIER_START.test(text[j]!)) {
+    j += 1;
+    while (j < text.length && IDENTIFIER_CHARACTER.test(text[j]!)) j += 1;
+  }
+  if (text[j] !== "$") return undefined;
+  return text.slice(i, j + 1);
+}
+
+interface QuoteScanResult {
+  /** Position nach dem Literal (bzw. am Zeilenumbruch/Textende, wenn es offen blieb). */
+  readonly next: number;
+  readonly terminated: boolean;
+}
+
+/** Überliest ein Literal ab dem Öffner an `start`. */
+function scanQuoted(text: string, start: number, rule: QuoteRule): QuoteScanResult {
+  let i = start + rule.open.length;
+  while (i < text.length) {
+    if (!rule.spansLines && text[i] === "\n") return { next: i, terminated: false };
+    if (rule.backslashEscapes && text[i] === "\\") {
+      i += 2;
+      continue;
+    }
+    if (text.startsWith(rule.close, i)) {
+      if (rule.doubledEscapes && text.startsWith(rule.close, i + rule.close.length)) {
+        i += rule.close.length * 2;
+        continue;
+      }
+      return { next: i + rule.close.length, terminated: true };
+    }
+    i += 1;
+  }
+  return { next: text.length, terminated: false };
+}
+
+/** Überliest ein `$tag$`-Literal ab dem Öffner an `start`. */
+function scanDollarQuoted(text: string, start: number, tag: string): QuoteScanResult {
+  const close = text.indexOf(tag, start + tag.length);
+  if (close === -1) return { next: text.length, terminated: false };
+  return { next: close + tag.length, terminated: true };
+}
+
+/** Überliest ein Heredoc ab dem `<<TAG`-Öffner an `start`. */
+function scanHeredoc(text: string, start: number, opener: string, tag: string): QuoteScanResult {
+  let lineStart = text.indexOf("\n", start + opener.length);
+  if (lineStart === -1) return { next: text.length, terminated: false };
+  lineStart += 1;
+  while (lineStart <= text.length) {
+    const newline = text.indexOf("\n", lineStart);
+    const lineEnd = newline === -1 ? text.length : newline;
+    if (text.slice(lineStart, lineEnd).trim() === tag) return { next: lineEnd, terminated: true };
+    if (newline === -1) break;
+    lineStart = newline + 1;
+  }
+  return { next: text.length, terminated: false };
+}
+
+/**
+ * Findet jede Stelle, an der `text` mitten durch ein Konstrukt geschnitten
+ * ist. Ergebnis ist deterministisch nach Offset sortiert (numerisch, kein
+ * `localeCompare`) und auf {@link MAX_IMBALANCES} Einträge begrenzt.
+ */
+export function findDelimiterImbalances(
+  text: string,
+  options: DelimiterScanOptions,
+): DelimiterImbalance[] {
+  const found: { kind: DelimiterImbalanceKind; delimiter: string; offset: number }[] = [];
+  const openBrackets: { delimiter: string; close: string; offset: number }[] = [];
+  const { blockComment } = options;
+
+  let i = 0;
+  while (i < text.length) {
+    if (blockComment !== undefined && text.startsWith(blockComment.open, i)) {
+      const close = text.indexOf(blockComment.close, i + blockComment.open.length);
+      if (close === -1) {
+        found.push({ kind: "unterminated_block_comment", delimiter: blockComment.open, offset: i });
+        i = text.length;
+        break;
+      }
+      i = close + blockComment.close.length;
+      continue;
+    }
+
+    const lineComment = options.lineComments.find((prefix) => text.startsWith(prefix, i));
+    if (lineComment !== undefined) {
+      const newline = text.indexOf("\n", i);
+      i = newline === -1 ? text.length : newline + 1;
+      continue;
+    }
+
+    if (options.heredocs === "hcl" && text.startsWith("<<", i)) {
+      HEREDOC_OPEN.lastIndex = i;
+      const match = HEREDOC_OPEN.exec(text);
+      if (match !== null) {
+        const result = scanHeredoc(text, i, match[0], match[1]!);
+        if (!result.terminated)
+          found.push({ kind: "unterminated_heredoc", delimiter: match[0], offset: i });
+        i = result.next;
+        continue;
+      }
+    }
+
+    if (options.dollarQuotedStrings === true) {
+      const tag = matchDollarQuote(text, i);
+      if (tag !== undefined) {
+        const result = scanDollarQuoted(text, i, tag);
+        if (!result.terminated)
+          found.push({ kind: "unterminated_string", delimiter: tag, offset: i });
+        i = result.next;
+        continue;
+      }
+    }
+
+    const quote = options.quotes.find((rule) => text.startsWith(rule.open, i));
+    if (quote !== undefined) {
+      const result = scanQuoted(text, i, quote);
+      if (!result.terminated)
+        found.push({ kind: "unterminated_string", delimiter: quote.open, offset: i });
+      i = Math.max(result.next, i + 1);
+      continue;
+    }
+
+    const opening = options.brackets.find((rule) => text.startsWith(rule.open, i));
+    if (opening !== undefined) {
+      openBrackets.push({ delimiter: opening.open, close: opening.close, offset: i });
+      i += opening.open.length;
+      continue;
+    }
+
+    const closing = options.brackets.find((rule) => text.startsWith(rule.close, i));
+    if (closing !== undefined) {
+      const top = openBrackets.at(-1);
+      if (top !== undefined && top.close === closing.close) {
+        openBrackets.pop();
+      } else {
+        // Ein Schlusszeichen ohne passenden Öffner IM FRAGMENT: die
+        // Schnittkante lag hinter dem zugehörigen Öffner.
+        found.push({ kind: "unmatched_closing_bracket", delimiter: closing.close, offset: i });
+      }
+      i += closing.close.length;
+      continue;
+    }
+
+    i += 1;
+  }
+
+  for (const open of openBrackets) {
+    found.push({ kind: "unclosed_bracket", delimiter: open.delimiter, offset: open.offset });
+  }
+
+  return found
+    .sort((a, b) => a.offset - b.offset)
+    .slice(0, MAX_IMBALANCES)
+    .map((entry) => ({ ...entry, line: lineOf(text, entry.offset) }));
+}
+
+const IMBALANCE_LABELS: Record<DelimiterImbalanceKind, string> = {
+  unterminated_string: "unterminated string literal opened by",
+  unterminated_block_comment: "unterminated block comment opened by",
+  unterminated_heredoc: "unterminated heredoc opened by",
+  unclosed_bracket: "unclosed bracket",
+  unmatched_closing_bracket: "closing bracket without a matching opener in this fragment:",
+};
+
+/** Einzeilige, menschenlesbare Zusammenfassung für den `contentPreview` eines Ledger-Eintrags. */
+export function describeDelimiterImbalances(imbalances: readonly DelimiterImbalance[]): string {
+  const parts = imbalances.map(
+    (entry) =>
+      `${IMBALANCE_LABELS[entry.kind]} ${JSON.stringify(entry.delimiter)} at fragment line ${entry.line}`,
+  );
+  return `implausible fragment boundary: ${parts.join("; ")}`;
+}

package/src/text/line-index.ts

@@ -0,0 +1,108 @@
+/**
+ * Line-oriented byte indexing shared by every format adapter.
+ *
+ * Every adapter in this package chunks by *line range* (headings, top-level
+ * SQL statements, brace-delimited blocks, YAML documents, …), never by raw
+ * character offset, so a single small utility converts a 1-based inclusive
+ * line span into the byte-accurate `SourceRange` domain requires
+ * (`startLine`/`endLine` 1-based inclusive, `startByte`/`endByte` 0-based
+ * half-open — see `packages/domain/src/types/common.ts`).
+ *
+ * Splitting only ever happens right after a `\n` (0x0A, single ASCII byte,
+ * never a UTF-8 continuation byte), so every line boundary this module
+ * produces is automatically a safe UTF-8 boundary — no separate multi-byte
+ * safety check is needed the way the chunker package needs one for
+ * mid-line token-boundary splits.
+ */
+import type { SourceRange } from "@untangle-code/domain";
+
+export interface LineIndex {
+  readonly buffer: Buffer;
+  /**
+   * Byte offset of the start of each line (0-based), one entry per line,
+   * PLUS one trailing sentinel equal to `buffer.length` — so
+   * `lineStarts[lineCount]` is always a valid "end of file" byte offset.
+   */
+  readonly lineStarts: number[];
+  readonly lineCount: number;
+}
+
+/** Builds a `LineIndex` from full document content (a decoded UTF-8 string). */
+export function buildLineIndex(content: string): LineIndex {
+  const buffer = Buffer.from(content, "utf8");
+  const lineStarts: number[] = [0];
+  for (let i = 0; i < buffer.length; i += 1) {
+    if (buffer[i] === 0x0a) {
+      lineStarts.push(i + 1);
+    }
+  }
+  const lineCount = lineStarts.length;
+  lineStarts.push(buffer.length);
+  return { buffer, lineStarts, lineCount };
+}
+
+function lineStartByte(index: LineIndex, line: number): number {
+  const clamped = Math.min(Math.max(line, 1), index.lineStarts.length);
+  return index.lineStarts[clamped - 1] ?? index.buffer.length;
+}
+
+/**
+ * 1-based line number containing byte offset `byteOffset` (clamped into
+ * `[0, buffer.length]`). Binary search over `lineStarts` (sorted ascending,
+ * one entry per line plus the EOF sentinel — see {@link LineIndex}), used by
+ * any scanner that tracks byte offsets directly (e.g. the SQL adapter's
+ * per-statement spans) and needs the matching 1-based line number without
+ * re-walking the buffer from the start.
+ */
+export function lineNumberForByte(index: LineIndex, byteOffset: number): number {
+  const target = Math.min(Math.max(byteOffset, 0), index.buffer.length);
+  let low = 0;
+  let high = index.lineCount - 1;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if ((index.lineStarts[mid] ?? 0) <= target) {
+      low = mid;
+    } else {
+      high = mid - 1;
+    }
+  }
+  return low + 1;
+}
+
+/**
+ * Builds a `SourceRange` for the 1-based inclusive line span
+ * `[startLine, endLine]`. `endByte` is the byte offset of the start of the
+ * line AFTER `endLine` (or end-of-file for the last line), so two chunks
+ * built from adjacent line spans (`endLine` of one === `startLine - 1` of
+ * the next) are byte-adjacent with no gap and no overlap.
+ */
+export function rangeForLines(index: LineIndex, startLine: number, endLine: number): SourceRange {
+  const startByte = lineStartByte(index, startLine);
+  const endByte = lineStartByte(index, endLine + 1);
+  return { startLine, endLine, startByte, endByte };
+}
+
+/** Decodes the UTF-8 bytes `[startByte, endByte)` as a string. */
+export function sliceBytes(index: LineIndex, startByte: number, endByte: number): string {
+  return index.buffer.toString("utf8", startByte, endByte);
+}
+
+/** Convenience: raw content of the 1-based inclusive line span. */
+export function sliceLines(index: LineIndex, startLine: number, endLine: number): string {
+  const range = rangeForLines(index, startLine, endLine);
+  return sliceBytes(index, range.startByte, range.endByte);
+}
+
+/**
+ * Splits content into physical lines WITHOUT their line terminator, plus a
+ * `LineIndex` for range/byte lookups. Adapters that scan line-by-line
+ * (Markdown headings, Dockerfile `FROM`, brace-block scanners, …) use this
+ * once per document.
+ */
+export function splitLines(content: string): { lines: string[]; index: LineIndex } {
+  const index = buildLineIndex(content);
+  // `\r\n` and `\n` both split correctly here; a trailing `\r` (if any) is
+  // stripped so heading/keyword regexes don't have to account for it.
+  const lines = content.split("\n").map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line));
+  return { lines, index };
+}