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

package/src/adapters/kubernetes.ts

@@ -0,0 +1,103 @@
+/**
+ * Kubernetes YAML adapter (architecture.md §20: "je Dokument eine
+ * Ressource, apiVersion/kind/name erhalten").
+ *
+ * Each `---`-separated YAML document in the file becomes exactly one
+ * chunk, kind `"kubernetes_resource"`, spanning that document's full line
+ * range — Kubernetes manifests are not sectioned further, since a
+ * Deployment's `spec.template` is meaningless read apart from its
+ * `metadata`. A document whose YAML fails to parse still gets its full raw
+ * span turned into a chunk (kind `"kubernetes_resource_parse_error"`, title
+ * carries the reason) rather than aborting the whole file: one malformed
+ * manifest in a directory of many must not hide the rest (architecture.md
+ * §22.2's cross-repo-search principle, applied at document granularity).
+ */
+import type {
+  ArtifactAdapter,
+  ArtifactChunk,
+  ArtifactDocument,
+  ArtifactInput,
+  ArtifactLink,
+} from "@untangle-code/domain";
+
+import { buildLineIndex } from "../text/line-index.js";
+import {
+  mapGet,
+  parseYamlNode,
+  scalarString,
+  splitYamlDocuments,
+  YamlParseError,
+} from "../text/yaml-lite.js";
+
+import type { ChunkDraft, SkipLedgerReporter } from "./shared.js";
+import { buildChunksReportingSkips, buildDocuments } from "./shared.js";
+
+const YAML_EXTENSION = /\.ya?ml$/i;
+const COMPOSE_FILENAME = /(^|\/)(docker-)?compose\.ya?ml$/i;
+
+function kubernetesDrafts(content: string): ChunkDraft[] {
+  return splitYamlDocuments(content).map((span): ChunkDraft => {
+    try {
+      const root = parseYamlNode(span.text);
+      const apiVersion = scalarString(mapGet(root, "apiVersion"));
+      const kind = scalarString(mapGet(root, "kind"));
+      const name = scalarString(mapGet(mapGet(root, "metadata"), "name"));
+      const title =
+        [apiVersion, kind].filter((part) => part !== undefined).join("/") +
+        (name === undefined ? "" : ` ${name}`);
+      return {
+        kind: "kubernetes_resource",
+        startLine: span.startLine,
+        endLine: span.endLine,
+        ...(title.trim().length === 0 ? {} : { title: title.trim() }),
+      };
+    } catch (error) {
+      const reason = error instanceof YamlParseError ? error.message : "unknown parse error";
+      return {
+        kind: "kubernetes_resource_parse_error",
+        startLine: span.startLine,
+        endLine: span.endLine,
+        title: `parse error: ${reason}`,
+      };
+    }
+  });
+}
+
+export interface KubernetesAdapterOptions {
+  /** Overrides how a real skip-ledger finding surfaces from `chunk()` (default: a stderr warning) — see `coverage.ts`'s `SkipLedgerReporter`. */
+  onSkipLedgerGap?: SkipLedgerReporter;
+}
+
+export function createKubernetesAdapter(options: KubernetesAdapterOptions = {}): ArtifactAdapter {
+  return {
+    supports(type: string, path: string): boolean {
+      // "auto" detection only claims .yaml/.yml files that are not a
+      // Compose file (see docker.ts) — every other ambiguous case (a plain
+      // config .yaml, an OpenAPI/AsyncAPI file without a name hint) should
+      // be configured with an explicit `type`, since path alone cannot
+      // disambiguate them (spec.md §19.1's `supports` has no content
+      // access — see README "Entscheidungen").
+      return (
+        type === "kubernetes" ||
+        (type === "auto" && YAML_EXTENSION.test(path) && !COMPOSE_FILENAME.test(path))
+      );
+    },
+
+    async read(input: ArtifactInput): Promise<ArtifactDocument[]> {
+      return buildDocuments(input, "kubernetes");
+    },
+
+    chunk(document: ArtifactDocument): ArtifactChunk[] {
+      return buildChunksReportingSkips(
+        document,
+        buildLineIndex(document.content),
+        kubernetesDrafts(document.content),
+        options.onSkipLedgerGap,
+      );
+    },
+
+    links(): ArtifactLink[] {
+      return [];
+    },
+  };
+}

package/src/adapters/markdown.ts

@@ -0,0 +1,88 @@
+/**
+ * Markdown / ADR adapter (architecture.md §20, spec.md §19.2 "semantische
+ * Abschnitte statt fester Zeilenfenster").
+ *
+ * ADRs are not a separate `ContextArtifactType` (spec.md §19.1's type union
+ * has no "adr" literal — an Architecture Decision Record IS a Markdown
+ * document, conventionally with `## Status`/`## Context`/`## Decision`/
+ * `## Consequences` headings) — this one adapter's heading-based sectioning
+ * handles both.
+ *
+ * WP-110: the sectioning itself no longer lives here. It moved verbatim to
+ * `@untangle-code/domain`'s `outlineMarkdown()` so that the SAME partition
+ * also serves ordinary `.md` files through the parser-registry prose adapter
+ * and the prose metrics — before that move, a configured artifact got
+ * breadcrumbed sections while the identical file outside an artifact
+ * configuration got arbitrary line windows. Behaviour here is unchanged; the
+ * implementation is simply no longer duplicated.
+ *
+ * Sectioning (defined on `outlineMarkdown`): each ATX heading (`#` …
+ * `######`, ignored inside fenced code blocks) starts a new chunk that runs
+ * up to the START of the very next heading of ANY level (or EOF) — a flat
+ * partition of the file with no overlap. Each chunk's `title` carries the
+ * breadcrumb (ancestor headings joined by " › ") instead, so the hierarchy
+ * is still fully recoverable even though `content` stays the exact raw slice
+ * — the breadcrumb is never spliced into the preserved raw content
+ * (spec.md §19.2).
+ */
+import type {
+  ArtifactAdapter,
+  ArtifactChunk,
+  ArtifactDocument,
+  ArtifactInput,
+  ArtifactLink,
+} from "@untangle-code/domain";
+import { outlineMarkdown } from "@untangle-code/domain";
+
+import { buildLineIndex, splitLines } from "../text/line-index.js";
+
+import type { ChunkDraft, SkipLedgerReporter } from "./shared.js";
+import { buildChunksReportingSkips, buildDocuments } from "./shared.js";
+
+const MARKDOWN_EXTENSION = /\.(md|markdown|mdx)$/i;
+
+function markdownDrafts(lines: string[]): ChunkDraft[] {
+  return outlineMarkdown(lines).map((section) => {
+    const draft: ChunkDraft = {
+      kind: "markdown_section",
+      startLine: section.startLine,
+      endLine: section.endLine,
+    };
+    // Der Vorspann vor der ersten Ueberschrift hat keinen Breadcrumb; ein
+    // leerer `title` waere eine Behauptung ueber eine Ueberschrift, die es
+    // nicht gibt.
+    return section.breadcrumb === "" ? draft : { ...draft, title: section.breadcrumb };
+  });
+}
+
+export interface MarkdownAdapterOptions {
+  /** Overrides how a real skip-ledger finding surfaces from `chunk()` (default: a stderr warning) — see `coverage.ts`'s `SkipLedgerReporter`. */
+  onSkipLedgerGap?: SkipLedgerReporter;
+}
+
+export function createMarkdownAdapter(options: MarkdownAdapterOptions = {}): ArtifactAdapter {
+  return {
+    supports(type: string, path: string): boolean {
+      return type === "markdown" || (type === "auto" && MARKDOWN_EXTENSION.test(path));
+    },
+
+    async read(input: ArtifactInput): Promise<ArtifactDocument[]> {
+      return buildDocuments(input, "markdown");
+    },
+
+    chunk(document: ArtifactDocument): ArtifactChunk[] {
+      const { lines } = splitLines(document.content);
+      const index = buildLineIndex(document.content);
+      return buildChunksReportingSkips(
+        document,
+        index,
+        markdownDrafts(lines),
+        options.onSkipLedgerGap,
+      );
+    },
+
+    links(): ArtifactLink[] {
+      return [];
+    },
+  };
+}

package/src/adapters/openapi.ts

@@ -0,0 +1,156 @@
+/**
+ * OpenAPI adapter (architecture.md §20: "je Operation ein Abschnitt,
+ * Operation-IDs erhalten").
+ *
+ * Parses the document with the package's YAML subset parser
+ * (`text/yaml-lite.ts`) and emits one chunk per `paths.<path>.<method>`
+ * operation, titled with the HTTP method, path and (when present)
+ * `operationId` — never dropped even when absent from the title, since
+ * `content` is always the exact raw YAML block, `operationId` field
+ * included. A malformed document degrades to a single whole-document
+ * `"openapi_parse_error"` chunk (architecture.md §22.2) rather than
+ * throwing — the raw content is still fully preserved in that chunk.
+ */
+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 OPENAPI_NAME_HINT = /openapi/i;
+const YAML_OR_JSON_EXTENSION = /\.(ya?ml|json)$/i;
+
+const HTTP_METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"] as const;
+
+function openApiDrafts(root: YamlNode | null): ChunkDraft[] {
+  if (root === null || root.kind !== "map") return [];
+  const drafts: ChunkDraft[] = [];
+
+  const info = mapGet(root, "info");
+  if (info !== undefined) {
+    const title = scalarString(mapGet(info, "title"));
+    drafts.push({
+      kind: "openapi_info",
+      startLine: info.startLine,
+      endLine: info.endLine,
+      ...(title === undefined ? {} : { title: `info: ${title}` }),
+    });
+  }
+
+  const paths = mapGet(root, "paths");
+  if (paths !== undefined && paths.kind === "map") {
+    for (const pathEntry of paths.entries) {
+      if (pathEntry.value.kind !== "map") continue;
+      for (const methodEntry of pathEntry.value.entries) {
+        const method = methodEntry.key.toLowerCase();
+        if (!(HTTP_METHODS as readonly string[]).includes(method)) continue;
+        const operationId = scalarString(mapGet(methodEntry.value, "operationId"));
+        const title =
+          operationId === undefined
+            ? `${method.toUpperCase()} ${pathEntry.key}`
+            : `${method.toUpperCase()} ${pathEntry.key} (${operationId})`;
+        drafts.push({
+          kind: "openapi_operation",
+          startLine: methodEntry.value.startLine,
+          endLine: methodEntry.value.endLine,
+          title,
+        });
+      }
+    }
+  }
+  return drafts;
+}
+
+function operationIdOf(chunk: ArtifactChunk): string | undefined {
+  if (chunk.kind !== "openapi_operation" || chunk.title === undefined) return undefined;
+  const match = /\(([^()]+)\)$/.exec(chunk.title);
+  return match?.[1];
+}
+
+function draftsFor(document: ArtifactDocument): ChunkDraft[] {
+  try {
+    return openApiDrafts(parseYamlNode(document.content));
+  } catch (error) {
+    const reason = error instanceof YamlParseError ? error.message : "unknown parse error";
+    return [
+      wholeDocumentDraft(
+        "openapi_parse_error",
+        buildLineIndex(document.content),
+        `parse error: ${reason}`,
+      ),
+    ];
+  }
+}
+
+export interface OpenApiAdapterOptions {
+  /** Overrides how a real skip-ledger finding surfaces from `chunk()` (default: a stderr warning) — see `coverage.ts`'s `SkipLedgerReporter`. */
+  onSkipLedgerGap?: SkipLedgerReporter;
+}
+
+export function createOpenApiAdapter(options: OpenApiAdapterOptions = {}): ArtifactAdapter {
+  return {
+    supports(type: string, path: string): boolean {
+      return (
+        type === "openapi" ||
+        (type === "auto" && OPENAPI_NAME_HINT.test(path) && YAML_OR_JSON_EXTENSION.test(path))
+      );
+    },
+
+    async read(input: ArtifactInput): Promise<ArtifactDocument[]> {
+      return buildDocuments(input, "openapi");
+    },
+
+    chunk(document: ArtifactDocument): ArtifactChunk[] {
+      return buildChunksReportingSkips(
+        document,
+        buildLineIndex(document.content),
+        draftsFor(document),
+        options.onSkipLedgerGap,
+      );
+    },
+
+    /**
+     * Heuristic (architecture.md §20's canonical example): assumes the
+     * common REST-codegen convention that a controller method is named
+     * after the operation's `operationId`. No AST/symbol table is
+     * consulted here — `targetId` stays unset; a later graph-linking stage
+     * resolves `targetName` against real symbols, if any match.
+     */
+    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: OpenAPI operationId "${operationId}" → a controller method of the same name`,
+        });
+      }
+      return links;
+    },
+  };
+}

package/src/adapters/protobuf.ts

@@ -0,0 +1,286 @@
+/**
+ * Protobuf adapter (architecture.md §20: "Messages, Services, RPCs").
+ *
+ * Brace-depth line scanning (no full grammar needed): a top-level
+ * (depth-0) `message Foo {` or `service Foo {` opens a block that runs to
+ * its matching `}`. Nested `message`s inside another message are part of
+ * the parent's content (not chunked separately — a deliberate scope limit,
+ * see README "Entscheidungen"; their bytes are still fully present in the
+ * parent chunk's content, so nothing is silently dropped). Inside a
+ * `service` block, each `rpc Name(...) returns (...);` additionally gets
+ * its own finer-grained chunk — intentionally OVERLAPPING the enclosing
+ * service chunk's range, so a search hit on one RPC's name returns a tight
+ * chunk while a hit on shared service-level comments/options still returns
+ * full context.
+ *
+ * The brace counter is string/comment-aware (WP-81 review finding: a `{` or
+ * `}` inside a string default value, e.g. `[default = "{"]`, or inside a
+ * `//`/`/* *\/` comment, must never move the depth counter — a naive raw
+ * count desyncs PERMANENTLY on such a line, degrading "runs to EOF" and
+ * silently swallowing every following top-level block). `scanLine` below
+ * carries string/block-comment state across lines through ONE continuous
+ * scan (a single shared `ScanState`, not a fresh one per block) — depth is
+ * tracked exactly once per line, not once in this function and again in a
+ * separate look-ahead, so there is only one source of truth for "are we
+ * inside a string/comment right now" across the whole file.
+ */
+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 { buildChunks, buildChunksReportingSkips, buildDocuments } from "./shared.js";
+
+const PROTO_EXTENSION = /\.proto$/i;
+const MESSAGE_RE = /^\s*message\s+([\w.]+)\s*\{/;
+const SERVICE_RE = /^\s*service\s+([\w.]+)\s*\{/;
+const RPC_RE = /^\s*rpc\s+(\w+)\s*\(/;
+
+/** Cross-line scanner state: which of a string literal / block comment (if any) the scan is currently inside. */
+interface ScanState {
+  inSingle: boolean;
+  inDouble: boolean;
+  inBlockComment: boolean;
+}
+
+/**
+ * Net brace delta for one line, skipping `'...'`/`"..."` string literals
+ * (with `\`-escapes) and `//`/`/* *\/` comments, so a brace character
+ * inside either never affects depth. `state` is mutated in place for
+ * anything that spans past this line's end (an unterminated string or an
+ * open block comment) — the NEXT call for the following line continues
+ * from exactly that state, which is what makes the counter immune to
+ * per-line resets.
+ */
+function scanLine(line: string, state: ScanState): number {
+  let delta = 0;
+  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 (state.inSingle) {
+      if (c === "\\") {
+        i += 1;
+      } else if (c === "'") {
+        state.inSingle = false;
+      }
+      continue;
+    }
+    if (state.inDouble) {
+      if (c === "\\") {
+        i += 1;
+      } else if (c === '"') {
+        state.inDouble = false;
+      }
+      continue;
+    }
+    if (c === "/" && next === "/") {
+      break; // line comment: rest of the line is never code, and cannot itself open a block comment
+    }
+    if (c === "/" && next === "*") {
+      state.inBlockComment = true;
+      i += 1;
+      continue;
+    }
+    if (c === "'") {
+      state.inSingle = true;
+      continue;
+    }
+    if (c === '"') {
+      state.inDouble = true;
+      continue;
+    }
+    if (c === "{") delta += 1;
+    else if (c === "}") delta -= 1;
+  }
+  return delta;
+}
+
+/**
+ * Letzte Zeile einer `rpc`-Deklaration.
+ *
+ * Zwei Formen: die Kurzform endet an ihrem `;` (das bei mehrzeiliger
+ * Signatur erst auf einer späteren Zeile steht), die Langform an der
+ * schließenden `}` ihres Optionsrumpfs. WP-118: bisher wurde nur die erste
+ * Form erkannt, also endete `rpc A(X) returns (Y) {` schon an der ersten
+ * `;` IM RUMPF — mitten im Konstrukt, mit fehlender schließender Klammer,
+ * und ohne Ledger-Eintrag, weil die Range des Service-Chunks alles
+ * abdeckte. Der Klammerstand wird deshalb mitgezählt.
+ */
+function findRpcEnd(lines: string[], startIndex: number, hardLimit: number): number {
+  const state: ScanState = { inSingle: false, inDouble: false, inBlockComment: false };
+  let depth = 0;
+  for (let i = startIndex; i < hardLimit; i += 1) {
+    const line = lines[i] ?? "";
+    const depthBefore = depth;
+    depth += scanLine(line, state);
+    if (depthBefore > 0 && depth === 0) return i + 1; // Optionsrumpf geschlossen
+    if (depthBefore === 0 && depth === 0 && (line.includes(";") || line.includes("}")))
+      return i + 1;
+  }
+  return hardLimit;
+}
+
+/** Pushes `pending`'s finished draft (and, for a service, its nested RPC drafts scanned from its now-final range) into `drafts`. */
+function finalizePendingBlock(
+  drafts: ChunkDraft[],
+  lines: string[],
+  pending: { kind: "protobuf_message" | "protobuf_service"; title: string; startLine: number },
+  endLine: number,
+): void {
+  drafts.push({ kind: pending.kind, startLine: pending.startLine, endLine, title: pending.title });
+  if (pending.kind !== "protobuf_service") return;
+  for (let j = pending.startLine - 1; j < endLine; j += 1) {
+    const rpc = RPC_RE.exec(lines[j] ?? "");
+    if (rpc) {
+      const rpcEnd = findRpcEnd(lines, j, endLine);
+      drafts.push({
+        kind: "protobuf_rpc",
+        startLine: j + 1,
+        endLine: rpcEnd,
+        title: `${pending.title}.${rpc[1]!}`,
+      });
+    }
+  }
+}
+
+function protobufDrafts(lines: string[]): ChunkDraft[] {
+  const drafts: ChunkDraft[] = [];
+  const state: ScanState = { inSingle: false, inDouble: false, inBlockComment: false };
+  let depth = 0;
+  let pending:
+    { kind: "protobuf_message" | "protobuf_service"; title: string; startLine: number } | undefined;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i] ?? "";
+    if (depth === 0 && pending === undefined) {
+      const message = MESSAGE_RE.exec(line);
+      const service = SERVICE_RE.exec(line);
+      if (message) {
+        pending = { kind: "protobuf_message", title: message[1]!, startLine: i + 1 };
+      } else if (service) {
+        pending = { kind: "protobuf_service", title: service[1]!, startLine: i + 1 };
+      }
+    }
+    depth += scanLine(line, state);
+    if (pending !== undefined && depth === 0) {
+      finalizePendingBlock(drafts, lines, pending, i + 1);
+      pending = undefined;
+    }
+  }
+  if (pending !== undefined) {
+    // Unterminated top-level block (malformed source, or a still-open
+    // string/comment at EOF): degrade to "runs to EOF" rather than
+    // dropping it — never silently, see the module doc.
+    finalizePendingBlock(drafts, lines, pending, Math.max(lines.length, pending.startLine));
+  }
+  return drafts;
+}
+
+/**
+ * Trennzeichen-Konventionen für die Plausibilitätsprüfung (WP-118).
+ * Zeichenketten dürfen keine Zeile überschreiten — ein Anführungszeichen,
+ * das bis zum Zeilenende offen bleibt, ist in Protobuf bereits ein Befund.
+ */
+const PROTOBUF_SCAN_OPTIONS: DelimiterScanOptions = {
+  quotes: [
+    { open: "'", close: "'", backslashEscapes: true, doubledEscapes: false, spansLines: false },
+    { open: '"', close: '"', backslashEscapes: true, doubledEscapes: false, spansLines: false },
+  ],
+  brackets: [
+    { open: "{", close: "}" },
+    { open: "(", close: ")" },
+    { open: "[", close: "]" },
+  ],
+  lineComments: ["//"],
+  blockComment: { open: "/*", close: "*/" },
+};
+
+/**
+ * WP-118 (dieselbe Blindstelle wie in `sql.ts`): der Blockzähler dieses
+ * Adapters degradiert einen unabgeschlossenen Top-Level-Block zu „läuft
+ * bis Dateiende". Die Byte-Abdeckung bleibt dabei lückenlos, der Chunk ist
+ * weder leer noch überlappend — der Ledger sah also NICHTS, obwohl der
+ * Blockzähler nachweislich aus dem Tritt geraten war. Ein Fragment mit
+ * offener Klammer, offener Zeichenkette oder offenem Kommentar ist jetzt
+ * ein Befund.
+ */
+const checkProtobufPlausibility: ChunkPlausibilityCheck = (chunk) => {
+  const imbalances = findDelimiterImbalances(chunk.content, PROTOBUF_SCAN_OPTIONS);
+  return imbalances.length === 0 ? undefined : describeDelimiterImbalances(imbalances);
+};
+
+function messageName(chunk: ArtifactChunk): string | undefined {
+  return chunk.kind === "protobuf_service" ? chunk.title : undefined;
+}
+
+export interface ProtobufAdapterOptions {
+  /** Overrides how a real skip-ledger finding surfaces from `chunk()` (default: a stderr warning) — see `coverage.ts`'s `SkipLedgerReporter`. */
+  onSkipLedgerGap?: SkipLedgerReporter;
+}
+
+export function createProtobufAdapter(options: ProtobufAdapterOptions = {}): ArtifactAdapter {
+  return {
+    supports(type: string, path: string): boolean {
+      return type === "protobuf" || (type === "auto" && PROTO_EXTENSION.test(path));
+    },
+
+    async read(input: ArtifactInput): Promise<ArtifactDocument[]> {
+      return buildDocuments(input, "protobuf");
+    },
+
+    chunk(document: ArtifactDocument): ArtifactChunk[] {
+      const { lines } = splitLines(document.content);
+      const index = buildLineIndex(document.content);
+      return buildChunksReportingSkips(
+        document,
+        index,
+        protobufDrafts(lines),
+        options.onSkipLedgerGap,
+        checkProtobufPlausibility,
+      );
+    },
+
+    /**
+     * Heuristic (architecture.md §20): a gRPC service `FooService` often
+     * backs a generated/handwritten server symbol named `FooServiceServer`
+     * or `FooServiceImpl`. Both are offered as separate low-confidence
+     * hints — this is a naming guess, not a resolved reference.
+     */
+    links(document: ArtifactDocument): ArtifactLink[] {
+      const { lines } = splitLines(document.content);
+      const index = buildLineIndex(document.content);
+      const chunks = buildChunks(document, index, protobufDrafts(lines));
+      const links: ArtifactLink[] = [];
+      for (const chunk of chunks) {
+        const name = messageName(chunk);
+        if (name === undefined) continue;
+        for (const suffix of ["Server", "Impl"]) {
+          links.push({
+            fromChunkId: chunk.chunkId,
+            targetKind: "symbol",
+            targetName: `${name}${suffix}`,
+            heuristic: true,
+            confidence: 0.3,
+            note: `naming-convention guess: gRPC service "${name}" → generated/handwritten server symbol`,
+          });
+        }
+      }
+      return links;
+    },
+  };
+}