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

package/src/adapters/terraform.ts

@@ -0,0 +1,261 @@
+/**
+ * Terraform/HCL adapter (architecture.md §20: "Ressourcen, Module,
+ * Variablen").
+ *
+ * Same brace-depth line scanning approach as the Protobuf adapter: a
+ * top-level `resource "type" "name" {`, `data "type" "name" {`, `module
+ * "name" {`, `variable "name" {`, `output "name" {`, `provider "name" {`,
+ * or `locals {` block runs to its matching `}`. Whitespace/comments
+ * between blocks are not chunked — `buildArtifactSkipLedger` surfaces
+ * those gaps with reason `"whitespace_or_comment"`, never silently.
+ *
+ * The brace counter skips `"..."` string literals, `#`/`//`/`/* *\/`
+ * comments and heredoc bodies (`<<EOT` … `EOT`, WP-118) (WP-81 review, same defect class as the Protobuf adapter's own
+ * fix: a `{`/`}` inside a multi-line `/* *\/` comment must never move the
+ * depth counter, or it desyncs permanently and "runs to EOF", silently
+ * swallowing every following top-level block). `scanLine` carries the
+ * open-block-comment state across lines through one continuous scan — the
+ * SAME scan that finds block boundaries, not a separate look-ahead with its
+ * own independent counter, so there is exactly one source of truth for "is
+ * this brace really code right now".
+ *
+ * KNOWN, UNFIXED gap in the same defect class (documented, not silent):
+ * `BLOCK_PATTERNS` match against a full physical LINE (`^\s*keyword...`), so
+ * two block openers sharing one physical line (`resource "a" "b" {} module
+ * "m" {}`) — valid but extremely unidiomatic HCL that `terraform fmt` would
+ * never produce — only detects the first; the second's bytes still land
+ * inside the first block's `content` (nothing is dropped from the document,
+ * only mis-titled), rather than getting its own chunk. Fixing this fully
+ * would need the same byte-precise, sub-line splitting the SQL adapter now
+ * uses for multiple statements per line; left as an open issue given how
+ * rare well-formed HCL makes this shape.
+ */
+import type {
+  ArtifactAdapter,
+  ArtifactChunk,
+  ArtifactDocument,
+  ArtifactInput,
+  ArtifactLink,
+} from "@untangle-code/domain";
+
+import type { DelimiterScanOptions } from "../text/delimiter-balance.js";
+import { describeDelimiterImbalances, findDelimiterImbalances } from "../text/delimiter-balance.js";
+import { buildLineIndex, splitLines } from "../text/line-index.js";
+
+import type { ChunkDraft, ChunkPlausibilityCheck, SkipLedgerReporter } from "./shared.js";
+import { buildChunksReportingSkips, buildDocuments } from "./shared.js";
+
+const TERRAFORM_EXTENSION = /\.(tf|tf\.json|hcl)$/i;
+
+interface BlockPattern {
+  kind: string;
+  re: RegExp;
+  title: (match: RegExpExecArray) => string;
+}
+
+const BLOCK_PATTERNS: BlockPattern[] = [
+  {
+    kind: "terraform_resource",
+    re: /^\s*resource\s+"([^"]+)"\s+"([^"]+)"\s*\{/,
+    title: (m) => `${m[1]!}.${m[2]!}`,
+  },
+  {
+    kind: "terraform_data",
+    re: /^\s*data\s+"([^"]+)"\s+"([^"]+)"\s*\{/,
+    title: (m) => `${m[1]!}.${m[2]!}`,
+  },
+  { kind: "terraform_module", re: /^\s*module\s+"([^"]+)"\s*\{/, title: (m) => m[1]! },
+  { kind: "terraform_variable", re: /^\s*variable\s+"([^"]+)"\s*\{/, title: (m) => m[1]! },
+  { kind: "terraform_output", re: /^\s*output\s+"([^"]+)"\s*\{/, title: (m) => m[1]! },
+  { kind: "terraform_provider", re: /^\s*provider\s+"([^"]+)"\s*\{/, title: (m) => m[1]! },
+  { kind: "terraform_locals", re: /^\s*locals\s*\{/, title: () => "locals" },
+];
+
+/**
+ * Öffner eines Heredocs (`<<EOT` / `<<-EOT`); die Gruppe ist die Endmarke.
+ * Sticky, damit er an einer Position geprüft werden kann, ohne die Zeile zu
+ * kopieren.
+ */
+const HEREDOC_OPEN = /<<-?([A-Za-z_][A-Za-z0-9_]*)/y;
+
+/** Cross-line scanner state: whether the scan is currently inside an open `/* *\/` block comment or heredoc. */
+interface ScanState {
+  inBlockComment: boolean;
+  /** Endmarke des offenen Heredocs, sonst `undefined`. */
+  heredocTag: string | undefined;
+}
+
+/**
+ * Net brace delta for one line, skipping `"..."` string literals and
+ * `#`/`//`/`/* *\/` comments. `state.inBlockComment` is mutated for a
+ * comment that is still open at the end of this line — the next call for
+ * the following line continues from exactly that state. String state is
+ * NOT carried across lines: an HCL double-quoted string cannot contain a
+ * literal newline (only `\n` escapes), so it is always fully open and
+ * closed within one physical line.
+ */
+function scanLine(line: string, state: ScanState): number {
+  // WP-118: Ein Heredoc ist ROHTEXT. Ein `{` in einem eingebetteten
+  // Shell-Skript (`user_data = <<-EOT ... EOT`) hat den Klammerzähler
+  // bisher dauerhaft verschoben — der laufende Block „lief bis Dateiende"
+  // und verschluckte jeden folgenden Top-Level-Block, bei lückenloser
+  // Byte-Abdeckung und damit ohne einen einzigen Ledger-Eintrag. Genau
+  // dieselbe Blindstelle wie die des SQL-Zerlegers, nur mit anderem
+  // Auslöser.
+  if (state.heredocTag !== undefined) {
+    if (line.trim() === state.heredocTag) state.heredocTag = undefined;
+    return 0;
+  }
+  let delta = 0;
+  let inDouble = false;
+  for (let i = 0; i < line.length; i += 1) {
+    const c = line[i];
+    const next = line[i + 1];
+    if (state.inBlockComment) {
+      if (c === "*" && next === "/") {
+        state.inBlockComment = false;
+        i += 1;
+      }
+      continue;
+    }
+    if (inDouble) {
+      if (c === '"' && line[i - 1] !== "\\") inDouble = false;
+      continue;
+    }
+    if (c === "#" || (c === "/" && next === "/")) break; // line comment: rest of the line is never code
+    if (c === "/" && next === "*") {
+      state.inBlockComment = true;
+      i += 1;
+      continue;
+    }
+    if (c === '"') {
+      inDouble = true;
+      continue;
+    }
+    if (c === "<" && next === "<") {
+      HEREDOC_OPEN.lastIndex = i;
+      const heredoc = HEREDOC_OPEN.exec(line);
+      if (heredoc !== null) {
+        state.heredocTag = heredoc[1]!;
+        return delta; // alles hinter dem Öffner gehört zum Heredoc-Inhalt
+      }
+    }
+    if (c === "{") delta += 1;
+    else if (c === "}") delta -= 1;
+  }
+  return delta;
+}
+
+function terraformDrafts(lines: string[]): ChunkDraft[] {
+  const drafts: ChunkDraft[] = [];
+  const state: ScanState = { inBlockComment: false, heredocTag: undefined };
+  let depth = 0;
+  let pending: { kind: string; title: string; startLine: number } | undefined;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i] ?? "";
+    if (
+      depth === 0 &&
+      pending === undefined &&
+      !state.inBlockComment &&
+      state.heredocTag === undefined
+    ) {
+      for (const pattern of BLOCK_PATTERNS) {
+        const match = pattern.re.exec(line);
+        if (match) {
+          pending = { kind: pattern.kind, title: pattern.title(match), startLine: i + 1 };
+          break;
+        }
+      }
+    }
+    depth += scanLine(line, state);
+    if (pending !== undefined && depth === 0) {
+      drafts.push({
+        kind: pending.kind,
+        startLine: pending.startLine,
+        endLine: i + 1,
+        title: pending.title,
+      });
+      pending = undefined;
+    }
+  }
+  if (pending !== undefined) {
+    // Unterminated top-level block (malformed source, or a still-open
+    // block comment at EOF): degrade to "runs to EOF" rather than dropping
+    // it — never silently, see the module doc.
+    drafts.push({
+      kind: pending.kind,
+      startLine: pending.startLine,
+      endLine: Math.max(lines.length, pending.startLine),
+      title: pending.title,
+    });
+  }
+  return drafts;
+}
+
+/**
+ * Trennzeichen-Konventionen für die Plausibilitätsprüfung (WP-118).
+ * Heredocs (`<<EOF` / `<<-EOF`) sind Rohtext: eingebettete Skripte
+ * enthalten regelmäßig unpaarige Klammern und Anführungszeichen, die kein
+ * Befund sind. Der Prüfer überliest sie deshalb vollständig — und meldet
+ * dafür ein Heredoc, dessen Endmarke im Fragment fehlt.
+ */
+const TERRAFORM_SCAN_OPTIONS: DelimiterScanOptions = {
+  quotes: [
+    { open: '"', close: '"', backslashEscapes: true, doubledEscapes: false, spansLines: false },
+  ],
+  brackets: [
+    { open: "{", close: "}" },
+    { open: "(", close: ")" },
+    { open: "[", close: "]" },
+  ],
+  lineComments: ["#", "//"],
+  blockComment: { open: "/*", close: "*/" },
+  heredocs: "hcl",
+};
+
+/**
+ * WP-118 (dieselbe Blindstelle wie in `sql.ts`): ein unabgeschlossener
+ * Top-Level-Block wurde bisher still zu „läuft bis Dateiende" degradiert —
+ * lückenlose Byte-Abdeckung, kein leerer Chunk, also kein Ledger-Eintrag,
+ * obwohl der Klammerzähler nachweislich aus dem Tritt war. Dasselbe gilt
+ * für ein Heredoc, dessen `{` den Zähler verschoben hat (der Zähler dieses
+ * Adapters kennt Heredocs nicht). Beides ist jetzt ein sichtbarer Befund.
+ */
+const checkTerraformPlausibility: ChunkPlausibilityCheck = (chunk) => {
+  const imbalances = findDelimiterImbalances(chunk.content, TERRAFORM_SCAN_OPTIONS);
+  return imbalances.length === 0 ? undefined : describeDelimiterImbalances(imbalances);
+};
+
+export interface TerraformAdapterOptions {
+  /** Overrides how a real skip-ledger finding surfaces from `chunk()` (default: a stderr warning) — see `coverage.ts`'s `SkipLedgerReporter`. */
+  onSkipLedgerGap?: SkipLedgerReporter;
+}
+
+export function createTerraformAdapter(options: TerraformAdapterOptions = {}): ArtifactAdapter {
+  return {
+    supports(type: string, path: string): boolean {
+      return type === "terraform" || (type === "auto" && TERRAFORM_EXTENSION.test(path));
+    },
+
+    async read(input: ArtifactInput): Promise<ArtifactDocument[]> {
+      return buildDocuments(input, "terraform");
+    },
+
+    chunk(document: ArtifactDocument): ArtifactChunk[] {
+      const { lines } = splitLines(document.content);
+      const index = buildLineIndex(document.content);
+      return buildChunksReportingSkips(
+        document,
+        index,
+        terraformDrafts(lines),
+        options.onSkipLedgerGap,
+        checkTerraformPlausibility,
+      );
+    },
+
+    links(): ArtifactLink[] {
+      return [];
+    },
+  };
+}

package/src/adapters/text.ts

@@ -0,0 +1,72 @@
+/**
+ * Generic text fallback adapter (spec.md §19.2 "sicherer Text-Fallback";
+ * architecture.md §22.2 "Parserfehler degradieren auf Textanalyse").
+ *
+ * `supports()` matches everything the registry hasn't already routed to a
+ * more specific adapter — it is always registered LAST, as the registry's
+ * catch-all, so no file is ever left unindexable just because its format
+ * has no dedicated adapter (rule 4 / E4: nothing is silently skipped, it
+ * is degraded to fixed-size line windows instead).
+ *
+ * Windows are contiguous and non-overlapping, covering the ENTIRE file —
+ * `buildArtifactSkipLedger` reports zero gaps for a text-fallback document,
+ * by construction.
+ */
+import type {
+  ArtifactAdapter,
+  ArtifactChunk,
+  ArtifactDocument,
+  ArtifactInput,
+  ArtifactLink,
+} from "@untangle-code/domain";
+
+import { buildLineIndex } from "../text/line-index.js";
+
+import type { ChunkDraft, SkipLedgerReporter } from "./shared.js";
+import { buildChunksReportingSkips, buildDocuments } from "./shared.js";
+
+/** Lines per window — generous enough to keep a chunk's content meaningfully self-contained, small enough to stay embeddable. */
+export const TEXT_WINDOW_LINES = 200;
+
+function windowDrafts(lineCount: number): ChunkDraft[] {
+  const total = Math.max(lineCount, 1);
+  const drafts: ChunkDraft[] = [];
+  for (let start = 1; start <= total; start += TEXT_WINDOW_LINES) {
+    const end = Math.min(start + TEXT_WINDOW_LINES - 1, total);
+    drafts.push({ kind: "text_window", startLine: start, endLine: end });
+  }
+  return drafts;
+}
+
+export interface TextFallbackAdapterOptions {
+  /** Overrides how a real skip-ledger finding surfaces from `chunk()` (default: a stderr warning) — see `coverage.ts`'s `SkipLedgerReporter`. Never actually fires here: windows are gapless by construction (see module doc). */
+  onSkipLedgerGap?: SkipLedgerReporter;
+}
+
+export function createTextFallbackAdapter(
+  options: TextFallbackAdapterOptions = {},
+): ArtifactAdapter {
+  return {
+    supports(): boolean {
+      return true; // catch-all; the registry only reaches this adapter once nothing else claimed the file.
+    },
+
+    async read(input: ArtifactInput): Promise<ArtifactDocument[]> {
+      return buildDocuments(input, "text");
+    },
+
+    chunk(document: ArtifactDocument): ArtifactChunk[] {
+      const index = buildLineIndex(document.content);
+      return buildChunksReportingSkips(
+        document,
+        index,
+        windowDrafts(index.lineCount),
+        options.onSkipLedgerGap,
+      );
+    },
+
+    links(): ArtifactLink[] {
+      return [];
+    },
+  };
+}

package/src/config-validation.ts

@@ -0,0 +1,41 @@
+/**
+ * Cross-artifact configuration validation (spec.md §19.2: "Name MUSS
+ * projektweit eindeutig sein.").
+ */
+import type { ContextArtifactConfig } from "@untangle-code/domain";
+import { configInvalidError } from "@untangle-code/observability";
+
+/**
+ * Validates a whole project's `ContextArtifactConfig` list: every `name`
+ * must be non-empty and unique across the list (case-sensitive — two
+ * artifacts differing only by case are almost certainly a copy/paste bug,
+ * and case-insensitive uniqueness would silently reject that legitimate
+ * edge case too, so this stays deliberately literal).
+ *
+ * Throws `UntangleError("CONFIG_INVALID", …)` (rule 8) with every offending
+ * name listed in `context.duplicateNames`, not just the first one found, so
+ * a single fix-and-rerun cycle can catch everything at once.
+ */
+export function validateArtifactConfigs(configs: readonly ContextArtifactConfig[]): void {
+  const seen = new Map<string, number>();
+  const emptyNameCount = configs.filter((config) => config.name.trim().length === 0).length;
+  if (emptyNameCount > 0) {
+    throw configInvalidError(
+      `${emptyNameCount} context artifact config(s) have an empty "name" (spec.md §19.2 requires a project-wide unique name)`,
+      { context: { emptyNameCount } },
+    );
+  }
+  for (const config of configs) {
+    seen.set(config.name, (seen.get(config.name) ?? 0) + 1);
+  }
+  const duplicateNames = [...seen.entries()]
+    .filter(([, count]) => count > 1)
+    .map(([name]) => name)
+    .sort();
+  if (duplicateNames.length > 0) {
+    throw configInvalidError(
+      `context artifact name(s) are not project-wide unique (spec.md §19.2): ${duplicateNames.join(", ")}`,
+      { context: { duplicateNames } },
+    );
+  }
+}