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

package/src/adapters/__golden__/app-compose-services.json

@@ -0,0 +1,24 @@
+[
+  {
+    "content": "    build: .\n    ports:\n      - \"3000:3000\"\n",
+    "kind": "compose_service",
+    "range": {
+      "endByte": 61,
+      "endLine": 5,
+      "startByte": 17,
+      "startLine": 3
+    },
+    "title": "api"
+  },
+  {
+    "content": "    image: postgres:16\n    environment:\n      POSTGRES_PASSWORD: secret\n",
+    "kind": "compose_service",
+    "range": {
+      "endByte": 139,
+      "endLine": 9,
+      "startByte": 67,
+      "startLine": 7
+    },
+    "title": "db"
+  }
+]

package/src/adapters/__golden__/app-image-stages.json

@@ -0,0 +1,24 @@
+[
+  {
+    "content": "FROM node:22-slim AS build\nWORKDIR /app\nCOPY . .\nRUN npm ci && npm run build\n\n",
+    "kind": "docker_stage",
+    "range": {
+      "endByte": 78,
+      "endLine": 5,
+      "startByte": 0,
+      "startLine": 1
+    },
+    "title": "build"
+  },
+  {
+    "content": "FROM node:22-slim\nWORKDIR /app\nCOPY --from=build /app/dist ./dist\nCMD [\"node\", \"dist/index.js\"]\n",
+    "kind": "docker_stage",
+    "range": {
+      "endByte": 174,
+      "endLine": 10,
+      "startByte": 78,
+      "startLine": 6
+    },
+    "title": "stage 1 (node:22-slim)"
+  }
+]

package/src/adapters/__golden__/infra-main-sections.json

@@ -0,0 +1,46 @@
+[
+  {
+    "content": "variable \"region\" {\n  type    = string\n  default = \"eu-central-1\"\n}\n",
+    "kind": "terraform_variable",
+    "range": {
+      "endByte": 123,
+      "endLine": 5,
+      "startByte": 55,
+      "startLine": 2
+    },
+    "title": "region"
+  },
+  {
+    "content": "resource \"aws_s3_bucket\" \"data\" {\n  bucket = \"my-data-bucket\"\n  tags = {\n    Owner = \"platform\"\n  }\n}\n",
+    "kind": "terraform_resource",
+    "range": {
+      "endByte": 226,
+      "endLine": 12,
+      "startByte": 124,
+      "startLine": 7
+    },
+    "title": "aws_s3_bucket.data"
+  },
+  {
+    "content": "module \"network\" {\n  source = \"./modules/network\"\n  cidr   = \"10.0.0.0/16\"\n}\n",
+    "kind": "terraform_module",
+    "range": {
+      "endByte": 304,
+      "endLine": 17,
+      "startByte": 227,
+      "startLine": 14
+    },
+    "title": "network"
+  },
+  {
+    "content": "output \"bucket_arn\" {\n  value = aws_s3_bucket.data.arn\n}\n",
+    "kind": "terraform_output",
+    "range": {
+      "endByte": 362,
+      "endLine": 21,
+      "startByte": 305,
+      "startLine": 19
+    },
+    "title": "bucket_arn"
+  }
+]

package/src/adapters/__golden__/orders-events-operations.json

@@ -0,0 +1,24 @@
+[
+  {
+    "content": "      operationId: onOrderCreated\n      summary: Emitted when a new order is placed\n",
+    "kind": "asyncapi_operation",
+    "range": {
+      "endByte": 190,
+      "endLine": 9,
+      "startByte": 106,
+      "startLine": 8
+    },
+    "title": "order.created subscribe (onOrderCreated)"
+  },
+  {
+    "content": "      operationId: publishOrderCancelled\n",
+    "kind": "asyncapi_operation",
+    "range": {
+      "endByte": 263,
+      "endLine": 12,
+      "startByte": 222,
+      "startLine": 12
+    },
+    "title": "order.cancelled publish (publishOrderCancelled)"
+  }
+]

package/src/adapters/__golden__/orders-proto-sections.json

@@ -0,0 +1,57 @@
+[
+  {
+    "content": "message Order {\n  string id = 1;\n  string customer_id = 2;\n  int64 total_cents = 3;\n}\n",
+    "kind": "protobuf_message",
+    "range": {
+      "endByte": 126,
+      "endLine": 9,
+      "startByte": 40,
+      "startLine": 5
+    },
+    "title": "Order"
+  },
+  {
+    "content": "message OrderItem {\n  string sku = 1;\n  int32 qty = 2;\n}\n",
+    "kind": "protobuf_message",
+    "range": {
+      "endByte": 184,
+      "endLine": 14,
+      "startByte": 127,
+      "startLine": 11
+    },
+    "title": "OrderItem"
+  },
+  {
+    "content": "service OrderService {\n  rpc GetOrder(GetOrderRequest) returns (Order);\n  rpc CreateOrder(CreateOrderRequest)\n      returns (Order);\n}\n",
+    "kind": "protobuf_service",
+    "range": {
+      "endByte": 320,
+      "endLine": 20,
+      "startByte": 185,
+      "startLine": 16
+    },
+    "title": "OrderService"
+  },
+  {
+    "content": "  rpc GetOrder(GetOrderRequest) returns (Order);\n",
+    "kind": "protobuf_rpc",
+    "range": {
+      "endByte": 257,
+      "endLine": 17,
+      "startByte": 208,
+      "startLine": 17
+    },
+    "title": "OrderService.GetOrder"
+  },
+  {
+    "content": "  rpc CreateOrder(CreateOrderRequest)\n      returns (Order);\n",
+    "kind": "protobuf_rpc",
+    "range": {
+      "endByte": 318,
+      "endLine": 19,
+      "startByte": 257,
+      "startLine": 18
+    },
+    "title": "OrderService.CreateOrder"
+  }
+]

package/src/adapters/__golden__/orders-schema-statements.json

@@ -0,0 +1,68 @@
+[
+  {
+    "content": "-- schema for the orders service\nCREATE TABLE IF NOT EXISTS orders (\n  id UUID PRIMARY KEY,\n  customer_id UUID NOT NULL,\n  total_cents INTEGER NOT NULL,\n  status TEXT NOT NULL DEFAULT 'pending' -- semicolons in comments; must not split statements\n);\n",
+    "kind": "sql_table",
+    "range": {
+      "endByte": 250,
+      "endLine": 7,
+      "startByte": 0,
+      "startLine": 1
+    },
+    "title": "orders"
+  },
+  {
+    "content": "\nCREATE TABLE order_items (\n  order_id UUID NOT NULL REFERENCES orders(id),\n  sku TEXT NOT NULL,\n  qty INTEGER NOT NULL\n);\n",
+    "kind": "sql_table",
+    "range": {
+      "endByte": 373,
+      "endLine": 13,
+      "startByte": 250,
+      "startLine": 8
+    },
+    "title": "order_items"
+  },
+  {
+    "content": "\nCREATE UNIQUE INDEX idx_orders_customer ON orders (customer_id);\n",
+    "kind": "sql_index",
+    "range": {
+      "endByte": 439,
+      "endLine": 15,
+      "startByte": 373,
+      "startLine": 14
+    },
+    "title": "idx_orders_customer ON orders"
+  },
+  {
+    "content": "\nCREATE VIEW open_orders AS\n  SELECT * FROM orders WHERE status <> 'closed';\n",
+    "kind": "sql_view",
+    "range": {
+      "endByte": 516,
+      "endLine": 18,
+      "startByte": 439,
+      "startLine": 16
+    },
+    "title": "open_orders"
+  },
+  {
+    "content": "\nALTER TABLE order_items ADD CONSTRAINT fk_order_items_order FOREIGN KEY (order_id) REFERENCES orders(id);\n",
+    "kind": "sql_constraint",
+    "range": {
+      "endByte": 623,
+      "endLine": 20,
+      "startByte": 516,
+      "startLine": 19
+    },
+    "title": "fk_order_items_order ON order_items"
+  },
+  {
+    "content": "\nINSERT INTO orders (id, customer_id, total_cents, status) VALUES ('seed', 'seed', 0, 'pending');\n",
+    "kind": "sql_statement",
+    "range": {
+      "endByte": 721,
+      "endLine": 22,
+      "startByte": 623,
+      "startLine": 21
+    },
+    "title": "INSERT"
+  }
+]

package/src/adapters/__golden__/users-api-operations.json

@@ -0,0 +1,46 @@
+[
+  {
+    "content": "  title: Users API\n  version: \"1.0.0\"\n",
+    "kind": "openapi_info",
+    "range": {
+      "endByte": 59,
+      "endLine": 4,
+      "startByte": 21,
+      "startLine": 3
+    },
+    "title": "info: Users API"
+  },
+  {
+    "content": "      operationId: listUsers\n      summary: List users\n      responses:\n        \"200\":\n          description: OK\n",
+    "kind": "openapi_operation",
+    "range": {
+      "endByte": 198,
+      "endLine": 12,
+      "startByte": 85,
+      "startLine": 8
+    },
+    "title": "GET /users (listUsers)"
+  },
+  {
+    "content": "      operationId: createUser\n      summary: Create a user\n      responses:\n        \"201\":\n          description: Created\n",
+    "kind": "openapi_operation",
+    "range": {
+      "endByte": 330,
+      "endLine": 18,
+      "startByte": 208,
+      "startLine": 14
+    },
+    "title": "POST /users (createUser)"
+  },
+  {
+    "content": "      operationId: getUserById\n      summary: Get a single user\n      responses:\n        \"200\":\n          description: OK\n",
+    "kind": "openapi_operation",
+    "range": {
+      "endByte": 476,
+      "endLine": 25,
+      "startByte": 354,
+      "startLine": 21
+    },
+    "title": "GET /users/{id} (getUserById)"
+  }
+]

package/src/adapters/__golden__/web-manifests-resources.json

@@ -0,0 +1,24 @@
+[
+  {
+    "content": "apiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: web\nspec:\n  replicas: 2\n  template:\n    spec:\n      containers:\n        - name: web\n          image: web:latest\n",
+    "kind": "kubernetes_resource",
+    "range": {
+      "endByte": 167,
+      "endLine": 11,
+      "startByte": 0,
+      "startLine": 1
+    },
+    "title": "apps/v1/Deployment web"
+  },
+  {
+    "content": "apiVersion: v1\nkind: Service\nmetadata:\n  name: web\nspec:\n  selector:\n    app: web\n  ports:\n    - port: 80\n",
+    "kind": "kubernetes_resource",
+    "range": {
+      "endByte": 277,
+      "endLine": 22,
+      "startByte": 171,
+      "startLine": 13
+    },
+    "title": "v1/Service web"
+  }
+]

package/src/adapters/asyncapi.ts

@@ -0,0 +1,147 @@
+/**
+ * AsyncAPI adapter (architecture.md §20: "je Channel ein Abschnitt,
+ * Operation-IDs erhalten").
+ *
+ * AsyncAPI v2's shape (`channels.<channel>.subscribe`/`.publish`, each
+ * optionally carrying `operationId`) is what this adapter targets — one
+ * chunk per channel operation, kind `"asyncapi_operation"`, titled
+ * `"<channel> <subscribe|publish> (<operationId>)"`. A channel with
+ * neither `subscribe` nor `publish` (rare, but not invalid AsyncAPI) still
+ * gets a whole-channel `"asyncapi_channel"` chunk rather than being
+ * dropped. Malformed documents degrade the same way `openapi.ts` does.
+ */
+import type {
+  ArtifactAdapter,
+  ArtifactChunk,
+  ArtifactDocument,
+  ArtifactInput,
+  ArtifactLink,
+} from "@untangle-code/domain";
+
+import { buildLineIndex } from "../text/line-index.js";
+import {
+  mapGet,
+  parseYamlNode,
+  scalarString,
+  YamlParseError,
+  type YamlNode,
+} from "../text/yaml-lite.js";
+
+import type { ChunkDraft, SkipLedgerReporter } from "./shared.js";
+import {
+  buildChunks,
+  buildChunksReportingSkips,
+  buildDocuments,
+  wholeDocumentDraft,
+} from "./shared.js";
+
+const ASYNCAPI_NAME_HINT = /asyncapi/i;
+const YAML_OR_JSON_EXTENSION = /\.(ya?ml|json)$/i;
+
+const OPERATION_KEYS = ["subscribe", "publish"] as const;
+
+function asyncApiDrafts(root: YamlNode | null): ChunkDraft[] {
+  if (root === null || root.kind !== "map") return [];
+  const drafts: ChunkDraft[] = [];
+  const channels = mapGet(root, "channels");
+  if (channels === undefined || channels.kind !== "map") return drafts;
+
+  for (const channelEntry of channels.entries) {
+    if (channelEntry.value.kind !== "map") continue;
+    let foundOperation = false;
+    for (const operationKey of OPERATION_KEYS) {
+      const operation = mapGet(channelEntry.value, operationKey);
+      if (operation === undefined) continue;
+      foundOperation = true;
+      const operationId = scalarString(mapGet(operation, "operationId"));
+      const title =
+        operationId === undefined
+          ? `${channelEntry.key} ${operationKey}`
+          : `${channelEntry.key} ${operationKey} (${operationId})`;
+      drafts.push({
+        kind: "asyncapi_operation",
+        startLine: operation.startLine,
+        endLine: operation.endLine,
+        title,
+      });
+    }
+    if (!foundOperation) {
+      drafts.push({
+        kind: "asyncapi_channel",
+        startLine: channelEntry.value.startLine,
+        endLine: channelEntry.value.endLine,
+        title: channelEntry.key,
+      });
+    }
+  }
+  return drafts;
+}
+
+function operationIdOf(chunk: ArtifactChunk): string | undefined {
+  if (chunk.kind !== "asyncapi_operation" || chunk.title === undefined) return undefined;
+  const match = /\(([^()]+)\)$/.exec(chunk.title);
+  return match?.[1];
+}
+
+function draftsFor(document: ArtifactDocument): ChunkDraft[] {
+  try {
+    return asyncApiDrafts(parseYamlNode(document.content));
+  } catch (error) {
+    const reason = error instanceof YamlParseError ? error.message : "unknown parse error";
+    return [
+      wholeDocumentDraft(
+        "asyncapi_parse_error",
+        buildLineIndex(document.content),
+        `parse error: ${reason}`,
+      ),
+    ];
+  }
+}
+
+export interface AsyncApiAdapterOptions {
+  /** Overrides how a real skip-ledger finding surfaces from `chunk()` (default: a stderr warning) — see `coverage.ts`'s `SkipLedgerReporter`. */
+  onSkipLedgerGap?: SkipLedgerReporter;
+}
+
+export function createAsyncApiAdapter(options: AsyncApiAdapterOptions = {}): ArtifactAdapter {
+  return {
+    supports(type: string, path: string): boolean {
+      return (
+        type === "asyncapi" ||
+        (type === "auto" && ASYNCAPI_NAME_HINT.test(path) && YAML_OR_JSON_EXTENSION.test(path))
+      );
+    },
+
+    async read(input: ArtifactInput): Promise<ArtifactDocument[]> {
+      return buildDocuments(input, "asyncapi");
+    },
+
+    chunk(document: ArtifactDocument): ArtifactChunk[] {
+      return buildChunksReportingSkips(
+        document,
+        buildLineIndex(document.content),
+        draftsFor(document),
+        options.onSkipLedgerGap,
+      );
+    },
+
+    /** Heuristic, same convention as the OpenAPI adapter's `operationId` link. */
+    links(document: ArtifactDocument): ArtifactLink[] {
+      const chunks = buildChunks(document, buildLineIndex(document.content), draftsFor(document));
+      const links: ArtifactLink[] = [];
+      for (const chunk of chunks) {
+        const operationId = operationIdOf(chunk);
+        if (operationId === undefined) continue;
+        links.push({
+          fromChunkId: chunk.chunkId,
+          targetKind: "symbol",
+          targetName: operationId,
+          heuristic: true,
+          confidence: 0.5,
+          note: `naming-convention guess: AsyncAPI operationId "${operationId}" → a handler method of the same name`,
+        });
+      }
+      return links;
+    },
+  };
+}

package/src/adapters/docker.ts

@@ -0,0 +1,170 @@
+/**
+ * Docker / Compose adapter (architecture.md §20: "Services, Stages").
+ *
+ * spec.md §19.1's `ContextArtifactType` union has no `"docker"` (or
+ * `"compose"`) literal — see README "Entscheidungen" and this WP's
+ * openIssues entry. `ArtifactDocument.type` is therefore `"text"` for
+ * documents this adapter produces (the closest fit in the frozen contract).
+ * `supports()` matches on filename for BOTH `type === "auto"` and
+ * `type === "text"` — `"text"` is the only literal an explicit config
+ * could even use for a Dockerfile/Compose artifact, so treating it the
+ * same as `"auto"` here is what lets an explicit `type: "text"` still get
+ * real stage/service chunking instead of being indistinguishable from a
+ * plain text file; the registry's `resolve()` tries this adapter before
+ * the text fallback either way, so a genuine plain-text file is never
+ * misrouted here. `ArtifactDocument.language` carries which of the two a
+ * given document is (`"dockerfile"` / `"docker-compose"`), so this
+ * adapter's own `chunk()` (and the registry's document→adapter dispatch)
+ * can tell a Dockerfile from a Compose file from a genuinely generic text
+ * document — `language` is a general-purpose optional field on the frozen
+ * contract, so this uses it without needing any contract change.
+ *
+ * Dockerfile: each `FROM ... [AS name]` starts a build stage that runs to
+ * the line before the next `FROM` (or EOF) — kind `"docker_stage"`.
+ * Compose: each entry under top-level `services:` becomes one chunk — kind
+ * `"compose_service"`.
+ *
+ * `FROM` detection skips heredoc bodies (WP-81 review's defect class,
+ * applied here: a separator-looking token inside a "quoted" region must
+ * never be mistaken for a real one). A modern Dockerfile can write
+ * `RUN <<EOF` / `COPY <<-EOF /dst` and have arbitrary script text up to a
+ * closing `EOF` line — that text is user content, not Dockerfile
+ * instructions, so a line reading e.g. `FROM scratch` inside such a heredoc
+ * (a Python/shell snippet building its OWN Dockerfile-ish text, or just a
+ * coincidence) must never be read as a new build stage.
+ */
+import type {
+  ArtifactAdapter,
+  ArtifactChunk,
+  ArtifactDocument,
+  ArtifactInput,
+  ArtifactLink,
+} from "@untangle-code/domain";
+
+import { buildLineIndex, splitLines } from "../text/line-index.js";
+import { mapGet, parseYamlNode, YamlParseError } from "../text/yaml-lite.js";
+
+import type { ChunkDraft, SkipLedgerReporter } from "./shared.js";
+import { buildChunksReportingSkips, buildDocuments, wholeDocumentDraft } from "./shared.js";
+
+const DOCKERFILE_NAME = /(^|\/)Dockerfile(\.[\w-]+)?$/;
+const COMPOSE_NAME = /(^|\/)(docker-)?compose\.ya?ml$/i;
+
+const FROM_RE = /^\s*FROM\s+(\S+)(?:\s+AS\s+(\S+))?\s*$/i;
+
+/** `RUN <<EOF`, `COPY <<-'EOF' /dst`, … — an optional `-` (strip leading tabs on the closing line) and an optional quoted/bare delimiter word. */
+const HEREDOC_OPEN_RE = /<<(-)?\s*(['"]?)([A-Za-z_][\w]*)\2/;
+
+function dockerfileDrafts(lines: string[]): ChunkDraft[] {
+  const stageStarts: { line: number; base: string; name?: string }[] = [];
+  let heredocDelimiter: string | null = null;
+  let heredocStripLeadingTabs = false;
+  for (const [index, line] of lines.entries()) {
+    if (heredocDelimiter !== null) {
+      const closingCandidate = heredocStripLeadingTabs ? line.replace(/^\t+/, "") : line;
+      if (closingCandidate === heredocDelimiter) {
+        heredocDelimiter = null;
+      }
+      continue; // heredoc body: never Dockerfile instructions, whatever they contain
+    }
+    const heredocOpen = HEREDOC_OPEN_RE.exec(line);
+    if (heredocOpen) {
+      heredocDelimiter = heredocOpen[3]!;
+      heredocStripLeadingTabs = heredocOpen[1] === "-";
+      continue; // the opener line itself (e.g. "RUN <<EOF") is never a FROM either
+    }
+    const match = FROM_RE.exec(line);
+    if (match) {
+      const entry: { line: number; base: string; name?: string } = {
+        line: index + 1,
+        base: match[1]!,
+      };
+      stageStarts.push(match[2] === undefined ? entry : { ...entry, name: match[2] });
+    }
+  }
+  const totalLines = Math.max(lines.length, 1);
+  return stageStarts.map((stage, position) => {
+    const endLine =
+      position + 1 < stageStarts.length ? stageStarts[position + 1]!.line - 1 : totalLines;
+    return {
+      kind: "docker_stage",
+      startLine: stage.line,
+      endLine,
+      title: stage.name === undefined ? `stage ${position} (${stage.base})` : stage.name,
+    };
+  });
+}
+
+function composeDrafts(document: ArtifactDocument): ChunkDraft[] {
+  try {
+    const root = parseYamlNode(document.content);
+    const services = mapGet(root, "services");
+    if (services === undefined || services.kind !== "map") return [];
+    return services.entries.map((entry): ChunkDraft => ({
+      kind: "compose_service",
+      startLine: entry.value.startLine,
+      endLine: entry.value.endLine,
+      title: entry.key,
+    }));
+  } catch (error) {
+    const reason = error instanceof YamlParseError ? error.message : "unknown parse error";
+    return [
+      wholeDocumentDraft(
+        "compose_parse_error",
+        buildLineIndex(document.content),
+        `parse error: ${reason}`,
+      ),
+    ];
+  }
+}
+
+export interface DockerAdapterOptions {
+  /** Overrides how a real skip-ledger finding surfaces from `chunk()` (default: a stderr warning) — see `coverage.ts`'s `SkipLedgerReporter`. */
+  onSkipLedgerGap?: SkipLedgerReporter;
+}
+
+export function createDockerAdapter(options: DockerAdapterOptions = {}): ArtifactAdapter {
+  return {
+    supports(type: string, path: string): boolean {
+      return (
+        (type === "auto" || type === "text") &&
+        (DOCKERFILE_NAME.test(path) || COMPOSE_NAME.test(path))
+      );
+    },
+
+    async read(input: ArtifactInput): Promise<ArtifactDocument[]> {
+      const dockerfiles = input.files.filter((file) => DOCKERFILE_NAME.test(file.path));
+      const composeFiles = input.files.filter((file) => COMPOSE_NAME.test(file.path));
+      return [
+        ...buildDocuments({ config: input.config, files: dockerfiles }, "text", "dockerfile"),
+        ...buildDocuments({ config: input.config, files: composeFiles }, "text", "docker-compose"),
+      ];
+    },
+
+    chunk(document: ArtifactDocument): ArtifactChunk[] {
+      const index = buildLineIndex(document.content);
+      if (document.language === "dockerfile") {
+        const { lines } = splitLines(document.content);
+        return buildChunksReportingSkips(
+          document,
+          index,
+          dockerfileDrafts(lines),
+          options.onSkipLedgerGap,
+        );
+      }
+      // Anything else (including "docker-compose" and any unrecognized
+      // label an external caller might set) is treated as Compose YAML —
+      // the only other shape this adapter's own `read()` ever produces.
+      return buildChunksReportingSkips(
+        document,
+        index,
+        composeDrafts(document),
+        options.onSkipLedgerGap,
+      );
+    },
+
+    links(): ArtifactLink[] {
+      return [];
+    },
+  };
+}