@intentius/chant-lexicon-otel 0.124.46 → 0.124.49

package/src/lsp/properties.ts

@@ -0,0 +1,141 @@
+/**
+ * Property-level completion and hover for the built-in components (#3361),
+ * from the descriptions in upstream's `config.schema.yaml`.
+ *
+ * Generation writes each built-in's property tree to
+ * `src/generated/properties.json`. Inside `new OtlpReceiver({ … })` the
+ * cursor's position is resolved to a path of keys (`protocols.grpc`), and the
+ * properties at that path are offered, with upstream's description and a short
+ * type. A word under the cursor at such a position hovers with the same text.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import type { PropertyDoc } from "../spec/parse";
+
+type PropertyTrees = Record<string, Record<string, PropertyDoc>>;
+
+let cached: PropertyTrees | undefined;
+
+/** The generated property trees, or an empty set before `generate` has run. */
+export function propertyTrees(): PropertyTrees {
+  if (cached) return cached;
+  const file = join(dirname(moduleSourceDir(import.meta.url)), "generated", "properties.json");
+  cached = existsSync(file) ? (JSON.parse(readFileSync(file, "utf-8")) as PropertyTrees) : {};
+  return cached;
+}
+
+/** Test seam: replace the loaded trees. */
+export function setPropertyTrees(trees: PropertyTrees | undefined): void {
+  cached = trees;
+}
+
+/** Where the cursor is inside a constructor's config object. */
+export interface PropertyPosition {
+  className: string;
+  /** The keys of the objects enclosing the cursor, outermost first. */
+  path: string[];
+}
+
+/**
+ * Resolve the text before the cursor to the built-in whose constructor
+ * argument holds it and the keys of the objects around it. Undefined when the
+ * cursor is not inside `new X({ … })`.
+ */
+export function propertyPosition(before: string): PropertyPosition | undefined {
+  const re = /\bnew\s+(\w+)\s*\(\s*\{/g;
+  let match: RegExpExecArray | null;
+  let last: { className: string; start: number } | undefined;
+  while ((match = re.exec(before)) !== null) last = { className: match[1], start: match.index + match[0].length };
+  if (!last) return undefined;
+
+  // Walk from the constructor's `{`: each `{` opens the object of the key
+  // written just before it; `[` opens a list whose objects share that key.
+  const stack: Array<string | null> = [];
+  let pendingKey: string | null = null;
+  let i = last.start;
+  const text = before;
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const end = skipString(text, i);
+      const literal = text.slice(i + 1, end - 1);
+      // A quoted key: `"k8s.pod.name": …`
+      if (/^\s*:/.test(text.slice(end))) pendingKey = literal;
+      i = end;
+      continue;
+    }
+    if (ch === "/" && text[i + 1] === "/") {
+      const nl = text.indexOf("\n", i);
+      i = nl < 0 ? text.length : nl;
+      continue;
+    }
+    if (ch === "/" && text[i + 1] === "*") {
+      const close = text.indexOf("*/", i + 2);
+      i = close < 0 ? text.length : close + 2;
+      continue;
+    }
+    const ident = /^[A-Za-z_$][\w$]*/.exec(text.slice(i));
+    if (ident) {
+      if (/^\s*:/.test(text.slice(i + ident[0].length))) pendingKey = ident[0];
+      i += ident[0].length;
+      continue;
+    }
+    if (ch === "{" || ch === "[") {
+      // A list keeps its key, so its objects resolve to the list's items.
+      stack.push(ch === "[" ? `[${pendingKey ?? ""}` : pendingKey);
+      pendingKey = null;
+    } else if (ch === "}" || ch === "]") {
+      if (stack.length === 0) return undefined; // the constructor's object closed
+      stack.pop();
+    } else if (ch === "," || ch === "(" || ch === ")") {
+      pendingKey = null;
+    }
+    i++;
+  }
+
+  const path: string[] = [];
+  let inList: string | undefined;
+  for (const entry of stack) {
+    if (entry === null) {
+      if (inList === undefined) return undefined; // an object whose key is unknown
+      inList = undefined; // an item of the list just entered
+      continue;
+    }
+    if (entry.startsWith("[")) {
+      inList = entry.slice(1);
+      if (inList) path.push(inList);
+      continue;
+    }
+    path.push(entry);
+    inList = undefined;
+  }
+  if (inList !== undefined) return undefined; // directly inside a list, not an item
+  return { className: last.className, path };
+}
+
+function skipString(text: string, start: number): number {
+  const quote = text[start];
+  let i = start + 1;
+  while (i < text.length && text[i] !== quote) i += text[i] === "\\" ? 2 : 1;
+  return Math.min(i + 1, text.length);
+}
+
+/** The properties at a path of a built-in's tree, or undefined when the path leaves it. */
+export function propertiesAt(position: PropertyPosition): Record<string, PropertyDoc> | undefined {
+  let level: Record<string, PropertyDoc> | undefined = propertyTrees()[position.className];
+  for (const key of position.path) {
+    level = level?.[key]?.properties;
+    if (!level) return undefined;
+  }
+  return level;
+}
+
+/** Markdown for one property: its type, deprecation and upstream description. */
+export function propertyMarkdown(name: string, doc: PropertyDoc, className: string): string {
+  const lines = [`**${name}**: \`${doc.type}\`${doc.deprecated ? " (deprecated)" : ""}`];
+  if (doc.description) lines.push("", doc.description);
+  lines.push("", `\`${className}\` config, from upstream config.schema.yaml.`);
+  return lines.join("\n");
+}

package/src/metric-names.test.ts

@@ -57,6 +57,17 @@ describe("spanMetricsNames", () => {
     expect(spanMetricsNames(connector, { add_metric_suffixes: false }).duration?.prometheus).toBe("spans_duration");
   });
 
+  test("the prometheus exporter's translation_strategy decides suffixes; it ignores add_metric_suffixes at the pin", () => {
+    const connector = new SpanMetricsConnector({ namespace: "spans", histogram: { unit: "s" } });
+    const without = new PrometheusExporter({ endpoint: "0.0.0.0:8889", translation_strategy: "UnderscoreEscapingWithoutSuffixes" });
+    expect(spanMetricsNames(connector, without).duration?.prometheus).toBe("spans_duration");
+    const ignored = new PrometheusExporter({ endpoint: "0.0.0.0:8889", add_metric_suffixes: false });
+    expect(spanMetricsNames(connector, ignored).duration?.prometheus).toBe("spans_duration_seconds");
+    const utf8 = new PrometheusExporter({ endpoint: "0.0.0.0:8889", translation_strategy: "NoUTF8EscapingWithSuffixes" });
+    expect(spanMetricsNames(connector, utf8).calls.prometheus).toBe("spans.calls_total");
+    expect(spanMetricsNames(connector, { translation_strategy: "NoTranslation" }).calls.prometheus).toBe("spans.calls");
+  });
+
   test("only a spanmetrics connector", () => {
     expect(() => spanMetricsNames(new PrometheusExporter({ endpoint: "0.0.0.0:8889" }) as never)).toThrow(/spanmetrics/);
   });

package/src/metric-names.ts

@@ -11,9 +11,16 @@
  * with the exporter's defaults: `.` and any other character Prometheus does
  * not allow become `_`; counters take `_total`; a unit becomes a suffix
  * (`ms` is `_milliseconds`, `s` is `_seconds`); the exporter's `namespace`
- * is a prefix joined with `_`; `add_metric_suffixes: false` drops the
- * suffixes. Attribute names become label names the same way
- * (`service.name` is `service_name`).
+ * is a prefix joined with `_`. The exporter's `translation_strategy` decides
+ * the escaping and the suffixes: the default, `UnderscoreEscapingWithSuffixes`,
+ * is what is described here; `UnderscoreEscapingWithoutSuffixes` drops the
+ * suffixes; `NoUTF8EscapingWithSuffixes` keeps the name's characters;
+ * `NoTranslation` does neither. From collector-contrib v0.154.0 the
+ * `prometheus` exporter ignores the deprecated `add_metric_suffixes`, so a
+ * name read from that exporter follows `translation_strategy` alone; the
+ * `prometheusremotewrite` exporter still honours it when no strategy is set.
+ * Attribute names become label names the same way (`service.name` is
+ * `service_name`).
  *
  * This module holds types and string functions only, so a lexicon that
  * builds queries from it does not load the collector components.
@@ -52,14 +59,54 @@ const UNIT_WORDS: Record<string, string> = {
   "1": "ratio",
 };
 
+/** The `translation_strategy` values the Prometheus exporters take. */
+export type PrometheusTranslationStrategy =
+  | "UnderscoreEscapingWithSuffixes"
+  | "UnderscoreEscapingWithoutSuffixes"
+  | "NoUTF8EscapingWithSuffixes"
+  | "NoTranslation";
+
 /** How the `prometheus` exporter is configured, as far as naming goes. */
 export interface PrometheusNaming {
   /** The exporter's `namespace`, put in front of every name and joined with `_`. */
   namespace?: string;
-  /** The exporter's `add_metric_suffixes` (default true): unit and `_total` suffixes. */
+  /** The exporter's `translation_strategy`. Default `UnderscoreEscapingWithSuffixes`. */
+  translation_strategy?: PrometheusTranslationStrategy | (string & {});
+  /**
+   * `false` drops the unit and `_total` suffixes when no `translation_strategy`
+   * is set, as the `prometheusremotewrite` exporter reads it. The `prometheus`
+   * exporter ignores it at the pinned release, and {@link exporterNaming}
+   * leaves it out for that exporter.
+   *
+   * @deprecated Upstream deprecates it for `translation_strategy`.
+   */
   add_metric_suffixes?: boolean;
 }
 
+/**
+ * The naming a declared `prometheus` exporter (or its config) applies: its
+ * `namespace` and `translation_strategy`. `add_metric_suffixes` is left out,
+ * since the exporter ignores it at the pinned release. A plain
+ * `PrometheusNaming` is returned as given.
+ */
+export function exporterNaming(exporter: PrometheusNaming | { props?: PrometheusNaming; componentType?: unknown } | undefined): PrometheusNaming {
+  if (!exporter) return {};
+  if ("props" in exporter && typeof exporter.props === "object" && exporter.props !== null) {
+    const { add_metric_suffixes: _ignored, ...rest } = exporter.props;
+    return { ...(rest.namespace !== undefined ? { namespace: rest.namespace } : {}), ...(rest.translation_strategy !== undefined ? { translation_strategy: rest.translation_strategy } : {}) };
+  }
+  return exporter as PrometheusNaming;
+}
+
+/** Whether a naming escapes names to `[A-Za-z0-9_:]` and whether it adds suffixes. */
+function strategyOf(naming: PrometheusNaming): { escape: boolean; suffixes: boolean } {
+  const strategy = naming.translation_strategy ?? (naming.add_metric_suffixes === false ? "UnderscoreEscapingWithoutSuffixes" : "UnderscoreEscapingWithSuffixes");
+  return {
+    escape: strategy.startsWith("UnderscoreEscaping"),
+    suffixes: strategy !== "UnderscoreEscapingWithoutSuffixes" && strategy !== "NoTranslation",
+  };
+}
+
 /** An attribute name as a Prometheus label: `service.name` is `service_name`. */
 export function prometheusLabel(attribute: string): string {
   const label = attribute.replace(/[^A-Za-z0-9_]/g, "_");
@@ -73,9 +120,11 @@ export function prometheusLabel(attribute: string): string {
  * @param unit The metric's unit, e.g. `ms`. Units in braces (`{call}`) add nothing.
  */
 export function prometheusMetricName(name: string, type: "sum" | "histogram", unit?: string, naming: PrometheusNaming = {}): string {
-  let out = name.replace(/[^A-Za-z0-9_:]/g, "_");
-  if (naming.namespace) out = `${naming.namespace.replace(/[^A-Za-z0-9_:]/g, "_")}_${out}`;
-  if (naming.add_metric_suffixes === false) return out;
+  const { escape, suffixes } = strategyOf(naming);
+  const clean = (s: string) => (escape ? s.replace(/[^A-Za-z0-9_:]/g, "_") : s);
+  let out = clean(name);
+  if (naming.namespace) out = `${clean(naming.namespace)}_${out}`;
+  if (!suffixes) return out;
   const word = unit && !unit.startsWith("{") ? (UNIT_WORDS[unit] ?? unit.replace(/[^A-Za-z0-9_:]/g, "_")) : undefined;
   if (word && !out.endsWith(`_${word}`)) out = `${out}_${word}`;
   if (type === "sum" && !out.endsWith("_total")) out = `${out}_total`;
@@ -85,11 +134,11 @@ export function prometheusMetricName(name: string, type: "sum" | "histogram", un
 /** The parts of a spanmetrics config the metric names depend on. */
 export interface SpanMetricsNamingConfig {
   namespace?: string;
-  dimensions?: Array<{ name: string }>;
-  calls_dimensions?: Array<{ name: string }>;
+  dimensions?: Array<{ name?: string }>;
+  calls_dimensions?: Array<{ name?: string }>;
   exclude_dimensions?: string[];
-  histogram?: { disable?: boolean; unit?: "ms" | "s"; dimensions?: Array<{ name: string }> };
-  events?: { enabled?: boolean; dimensions?: Array<{ name: string }> };
+  histogram?: { disable?: boolean; unit?: "ms" | "s"; dimensions?: Array<{ name?: string }> };
+  events?: { enabled?: boolean; dimensions?: Array<{ name?: string }> };
 }
 
 /** The metrics one `spanmetrics` connector emits, and the labels a query selects them by. */
@@ -139,13 +188,13 @@ export function spanMetricsNames(
   exporter?: PrometheusNaming | { props?: PrometheusNaming },
 ): SpanMetricsNames {
   const c = configOf(connector);
-  const naming: PrometheusNaming =
-    exporter && "props" in exporter && typeof exporter.props === "object" ? (exporter.props as PrometheusNaming) : ((exporter ?? {}) as PrometheusNaming);
+  const naming = exporterNaming(exporter);
   const namespace = c.namespace ?? SPANMETRICS_DEFAULT_NAMESPACE;
   const metricName = (n: string) => (namespace === "" ? n : `${namespace}.${n}`);
   const excluded = new Set(c.exclude_dimensions ?? []);
   const defaults = SPANMETRICS_DEFAULT_DIMENSIONS.filter((d) => !excluded.has(d));
-  const names = (extra?: Array<{ name: string }>) => (extra ?? []).map((d) => d.name);
+  // A `glob` dimension names no single attribute, so it adds no fixed label.
+  const names = (extra?: Array<{ name?: string }>) => (extra ?? []).flatMap((d) => (d.name === undefined ? [] : [d.name]));
   const common = [...defaults, ...names(c.dimensions)];
 
   const metric = (n: string, type: "sum" | "histogram", dims: string[], unit?: string): CollectorMetric => ({
@@ -215,8 +264,7 @@ export function serviceGraphNames(
     throw new Error(`serviceGraphNames: expected a servicegraph connector, got ${d.componentType}`);
   }
   const c = (typeof d.componentType === "string" ? (d.props ?? {}) : connector) as ServiceGraphNamingConfig;
-  const naming: PrometheusNaming =
-    exporter && "props" in exporter && typeof exporter.props === "object" ? (exporter.props as PrometheusNaming) : ((exporter ?? {}) as PrometheusNaming);
+  const naming = exporterNaming(exporter);
   const dimensions = [
     "client",
     "server",

package/src/model.ts

@@ -125,7 +125,7 @@ export interface ComponentTypeAlias {
 
 /**
  * The renamed built-ins. chant emits `builtin`, which the pinned collector
- * (`COLLECTOR_PIN`, v0.130.0) knows and newer ones still accept. A config
+ * (`COLLECTOR_PIN`) still accepts as each component's deprecated type. A config
  * written for a newer collector may use `type`, so code that reads a config
  * (the importer, the checks, the k8s composites) accepts both.
  */

package/src/op/activities/collector-audit.test.ts

@@ -61,17 +61,19 @@ describe("collectorAudit's pieces", () => {
     ]);
   });
 
-  test("bumpPins moves only the two pin versions in define.ts", () => {
-    const text = readFileSync(join(import.meta.dirname, "..", "..", "define.ts"), "utf8");
-    const out = bumpPins(text, { collector: "v0.140.0", genai: "v1.50.0" });
+  test("bumpPins moves only the two pin versions, in spec/pin.ts and define.ts", () => {
+    const define = readFileSync(join(import.meta.dirname, "..", "..", "define.ts"), "utf8");
+    const pin = readFileSync(join(import.meta.dirname, "..", "..", "spec", "pin.ts"), "utf8");
+    const out = bumpPins({ define, pin }, { collector: "v0.170.0", genai: "v1.50.0" });
     const block = (text: string, name: string) => new RegExp(`export const ${name}: SchemaPin = Object\\.freeze\\(\\{[^}]*\\}`).exec(text)![0];
-    expect(block(out, "COLLECTOR_PIN")).toContain('version: "v0.140.0"');
-    expect(block(out, "GENAI_SEMCONV_PIN")).toContain('version: "v1.50.0"');
-    // SEMCONV_PIN, and the custom-component pin in define.ts's doc comment, are left alone.
-    expect(block(out, "SEMCONV_PIN")).toBe(block(text, "SEMCONV_PIN"));
-    const changed = out.split("\n").filter((l, i) => l !== text.split("\n")[i]);
-    expect(changed).toHaveLength(2);
-    expect(() => bumpPins("nothing", { collector: "v1.0.0" })).toThrow(/no COLLECTOR_PIN/);
+    expect(out.pin).toContain('export const OTELCOL_CONTRIB_VERSION = "v0.170.0";');
+    expect(block(out.define, "GENAI_SEMCONV_PIN")).toContain('version: "v1.50.0"');
+    // SEMCONV_PIN, the k8s distribution pin and the custom-component pin in define.ts's doc comment are left alone.
+    expect(block(out.define, "SEMCONV_PIN")).toBe(block(define, "SEMCONV_PIN"));
+    const changed = (a: string, b: string) => a.split("\n").filter((l, i) => l !== b.split("\n")[i]);
+    expect(changed(out.define, define)).toHaveLength(1);
+    expect(changed(out.pin, pin)).toHaveLength(1);
+    expect(() => bumpPins({ define: "nothing", pin: "nothing" }, { collector: "v1.0.0" })).toThrow(/no OTELCOL_CONTRIB_VERSION/);
   });
 
   test("semver ordering", () => {
@@ -80,6 +82,11 @@ describe("collectorAudit's pieces", () => {
   });
 });
 
+/** The releases after the pin, whatever it is. */
+const minorAfter = (v: string, n: number) => v.replace(/^v(\d+)\.(\d+)\.\d+$/, (_, major: string, minor: string) => `v${major}.${Number(minor) + n}.0`);
+const NEXT = minorAfter(COLLECTOR_PIN.version, 1);
+const AFTER_NEXT = minorAfter(COLLECTOR_PIN.version, 2);
+
 describe("collectorAudit", () => {
   test("current pins and no stability reading: no findings, report mode does nothing else", async () => {
     const { f } = fakeFetch([COLLECTOR_PIN.version, "v0.129.0"], [GENAI_SEMCONV_PIN.version]);
@@ -90,30 +97,30 @@ describe("collectorAudit", () => {
   });
 
   test("pins behind the newest releases are findings, prereleases ignored", async () => {
-    const { f } = fakeFetch(["v0.132.0", "v0.131.0", COLLECTOR_PIN.version], ["v1.42.0", GENAI_SEMCONV_PIN.version]);
+    const { f } = fakeFetch([AFTER_NEXT, NEXT, COLLECTOR_PIN.version], ["v1.42.0", GENAI_SEMCONV_PIN.version]);
     const r = await collectorAudit({ stability: false, _fetch: f });
     expect(r.findings.map((x) => x.kind)).toEqual(["collector-pin-behind", "semconv-pin-behind"]);
-    expect(r.collector).toEqual({ pin: COLLECTOR_PIN.version, latest: "v0.132.0", behind: 2 });
+    expect(r.collector).toEqual({ pin: COLLECTOR_PIN.version, latest: AFTER_NEXT, behind: 2 });
     expect(r.semconv.behind).toBe(1);
   });
 
   test("component stability at the pin and at the newest release, contrib then core, within the budget", async () => {
     const meta = {
       // otlp is a core component: contrib answers 404 for it.
-      [`opentelemetry-collector/v0.131.0/receiver/otlpreceiver`]: stability({ stable: ["traces"], deprecated: ["logs"] }),
+      [`opentelemetry-collector/${NEXT}/receiver/otlpreceiver`]: stability({ stable: ["traces"], deprecated: ["logs"] }),
       [`opentelemetry-collector/${COLLECTOR_PIN.version}/receiver/otlpreceiver`]: stability({ stable: ["traces", "logs"] }),
     };
-    const { f, urls } = fakeFetch(["v0.131.0", COLLECTOR_PIN.version], [GENAI_SEMCONV_PIN.version], meta);
+    const { f, urls } = fakeFetch([NEXT, COLLECTOR_PIN.version], [GENAI_SEMCONV_PIN.version], meta);
     const r = await collectorAudit({ _fetch: f, stabilityBudget: 500 });
-    expect(r.findings).toContainEqual({ kind: "deprecated", subject: "receiver/otlp", detail: "logs deprecated at v0.131.0" });
+    expect(r.findings).toContainEqual({ kind: "deprecated", subject: "receiver/otlp", detail: `logs deprecated at ${NEXT}` });
     expect(r.unchecked).not.toContain("receiver/otlp");
     expect(r.unchecked.length).toBe(builtinComponents().length - 1);
     // Looked for in contrib first, then core.
-    const otlp = urls.filter((u) => u.includes("/v0.131.0/receiver/otlpreceiver/"));
+    const otlp = urls.filter((u) => u.includes(`/${NEXT}/receiver/otlpreceiver/`));
     expect(otlp[0]).toContain("opentelemetry-collector-contrib");
     expect(otlp[1]).toContain("open-telemetry/opentelemetry-collector/");
 
-    const capped = fakeFetch(["v0.131.0", COLLECTOR_PIN.version], [GENAI_SEMCONV_PIN.version], meta);
+    const capped = fakeFetch([NEXT, COLLECTOR_PIN.version], [GENAI_SEMCONV_PIN.version], meta);
     await collectorAudit({ _fetch: capped.f, stabilityBudget: 3 });
     expect(capped.urls.filter((u) => u.includes("raw.githubusercontent.com"))).toHaveLength(3);
   });
@@ -127,7 +134,7 @@ describe("collectorAudit", () => {
   });
 
   test("pull-request mode bumps the pins in a worktree and opens a pull request", async () => {
-    const { f } = fakeFetch(["v0.131.0", COLLECTOR_PIN.version], [GENAI_SEMCONV_PIN.version]);
+    const { f } = fakeFetch([NEXT, COLLECTOR_PIN.version], [GENAI_SEMCONV_PIN.version]);
     const calls: string[] = [];
     const lexiconDir = join(import.meta.dirname, "..", "..", "..");
     const run: CommandRunner = async (bin, args) => {
@@ -143,7 +150,7 @@ describe("collectorAudit", () => {
   });
 
   test("pull-request mode end to end against a recorded git and gh", async () => {
-    const { f } = fakeFetch(["v0.131.0", COLLECTOR_PIN.version], [GENAI_SEMCONV_PIN.version]);
+    const { f } = fakeFetch([NEXT, COLLECTOR_PIN.version], [GENAI_SEMCONV_PIN.version]);
     const calls: string[] = [];
     const lexiconDir = join(import.meta.dirname, "..", "..", "..");
     const { mkdirSync } = await import("node:fs");
@@ -151,15 +158,15 @@ describe("collectorAudit", () => {
       calls.push(`${bin} ${args.join(" ")}`);
       if (args[0] === "rev-parse") return join(lexiconDir, "..", "..") + "\n";
       if (args[0] === "symbolic-ref") return "origin/main\n";
-      if (args[0] === "worktree" && args[1] === "add") mkdirSync(join(args[5], "lexicons", "otel", "src"), { recursive: true });
+      if (args[0] === "worktree" && args[1] === "add") mkdirSync(join(args[5], "lexicons", "otel", "src", "spec"), { recursive: true });
       if (bin === "gh" && args[1] === "list") return "[]";
       if (bin === "gh" && args[1] === "create") return "https://github.com/INTENTIUS/chant/pull/1\n";
       return "";
     };
     const r = await collectorAudit({ mode: "pull-request", stability: false, lexiconDir, _fetch: f, _run: run });
     expect(r.prUrl).toBe("https://github.com/INTENTIUS/chant/pull/1");
-    expect(calls).toContain("git add lexicons/otel/src/define.ts");
-    expect(calls.some((c) => c.startsWith("git commit -m chore(otel): move COLLECTOR_PIN to v0.131.0"))).toBe(true);
+    expect(calls).toContain("git add lexicons/otel/src/spec/pin.ts");
+    expect(calls.some((c) => c.startsWith(`git commit -m chore(otel): move COLLECTOR_PIN to ${NEXT}`))).toBe(true);
     expect(calls.some((c) => c.startsWith("git push --force origin HEAD:refs/heads/chant/otel-pins"))).toBe(true);
     expect(calls.some((c) => c.startsWith("gh pr create --head chant/otel-pins --base main"))).toBe(true);
   });

package/src/op/activities/collector-audit.ts

@@ -16,10 +16,12 @@
  *
  * `mode` says what to do with the findings: `report` returns them;
  * `issue` keeps one open issue current; `pull-request` also bumps the pins
- * in the lexicon's `src/define.ts` on a proposal branch and opens (or
+ * (`OTELCOL_CONTRIB_VERSION` in `src/spec/pin.ts` for `COLLECTOR_PIN`, and
+ * `GENAI_SEMCONV_PIN` in `src/define.ts`) on a proposal branch and opens (or
  * edits) a pull request with the findings as its body. Only the pin values
- * change: the config types written against the old pin are the reviewer's
- * to move, which the body says.
+ * change: refreshing the schema snapshot the config types are generated from
+ * (`just snapshot`, #3361) is the reviewer's, which the body says, and
+ * generation refuses until it is done.
  */
 
 import { mkdtempSync, readFileSync } from "node:fs";
@@ -164,17 +166,27 @@ function behindCount(releases: Release[], pin: string): number {
   return releases.filter((r) => compareSemver(r.tag, pin) > 0).length;
 }
 
-/** `src/define.ts` with `COLLECTOR_PIN` and `GENAI_SEMCONV_PIN` moved to the given versions. */
-export function bumpPins(text: string, to: { collector?: string; genai?: string }): string {
-  let out = text;
-  const bump = (name: string, version: string) => {
-    const re = new RegExp(`(export const ${name}: SchemaPin = Object\\.freeze\\(\\{[^}]*?version:\\s*")([^"]+)(")`);
-    if (!re.test(out)) throw new Error(`define.ts has no ${name} with a version to bump`);
-    out = out.replace(re, `$1${version}$3`);
-  };
-  if (to.collector) bump("COLLECTOR_PIN", to.collector);
-  if (to.genai) bump("GENAI_SEMCONV_PIN", to.genai);
-  return out;
+/**
+ * The pin files with `COLLECTOR_PIN` and `GENAI_SEMCONV_PIN` moved to the
+ * given versions: `COLLECTOR_PIN` follows `OTELCOL_CONTRIB_VERSION` in
+ * `src/spec/pin.ts`, and `GENAI_SEMCONV_PIN` is in `src/define.ts`.
+ */
+export function bumpPins(
+  texts: { define: string; pin: string },
+  to: { collector?: string; genai?: string },
+): { define: string; pin: string } {
+  let { define, pin } = texts;
+  if (to.collector) {
+    const re = /(export const OTELCOL_CONTRIB_VERSION = ")([^"]+)(")/;
+    if (!re.test(pin)) throw new Error("spec/pin.ts has no OTELCOL_CONTRIB_VERSION (COLLECTOR_PIN) to bump");
+    pin = pin.replace(re, `$1${to.collector}$3`);
+  }
+  if (to.genai) {
+    const re = /(export const GENAI_SEMCONV_PIN: SchemaPin = Object\.freeze\(\{[^}]*?version:\s*")([^"]+)(")/;
+    if (!re.test(define)) throw new Error("define.ts has no GENAI_SEMCONV_PIN with a version to bump");
+    define = define.replace(re, `$1${to.genai}$3`);
+  }
+  return { define, pin };
 }
 
 export function renderCollectorAuditSummary(r: Omit<CollectorAuditResult, "summary" | "mode">): string {
@@ -248,16 +260,24 @@ export async function collectorAudit(args: CollectorAuditArgs = {}): Promise<Col
   const lexiconDir = resolve(args.lexiconDir ?? join(cwd, "lexicons", "otel"));
   const root = (await run("git", ["rev-parse", "--show-toplevel"], lexiconDir)).trim();
   const definePath = join(lexiconDir, "src", "define.ts");
-  const content = bumpPins(readFileSync(definePath, "utf8"), to);
+  const pinPath = join(lexiconDir, "src", "spec", "pin.ts");
+  const bumped = bumpPins({ define: readFileSync(definePath, "utf8"), pin: readFileSync(pinPath, "utf8") }, to);
+  const files = [
+    ...(to.collector ? [{ path: relative(root, pinPath), content: bumped.pin }] : []),
+    ...(to.genai ? [{ path: relative(root, definePath), content: bumped.define }] : []),
+  ];
   const moved = [to.collector ? `COLLECTOR_PIN to ${to.collector}` : "", to.genai ? `GENAI_SEMCONV_PIN to ${to.genai}` : ""].filter(Boolean).join(" and ");
   result.prUrl = await proposePullRequest(run, {
     root,
     branch: args.branch ?? "chant/otel-pins",
     title: `chore(otel): move ${moved}`,
     body:
-      `${summary}\n\nThis moves the pin values only. The config types, defaults and checks written against ${collector.pin} ` +
-      "still need reading against the release notes before this merges.\n",
-    files: [{ path: relative(root, definePath), content }],
+      `${summary}\n\nThis moves the pin values only. ` +
+      (to.collector
+        ? "Run `just snapshot` in lexicons/otel, paste the printed OTEL_SPEC_PIN and regenerate: the config types are generated from the snapshot, and generation refuses a snapshot taken at another version. "
+        : "") +
+      `The defaults and checks written against ${collector.pin} still need reading against the release notes before this merges.\n`,
+    files,
     commitMessage: `chore(otel): move ${moved}`,
     worktreeDir: join(mkdtempSync(join(tmpdir(), "chant-otel-pins-")), "wt"),
   });

package/src/plugin.test.ts

@@ -44,6 +44,8 @@ describe("otel plugin", () => {
       "OTEL125",
       "OTEL126",
       "OTEL127",
+      "OTEL128",
+      "OTEL129",
     ]);
     for (const id of ids) expect(id.startsWith("OTEL")).toBe(true);
   });

package/src/plugin.ts

@@ -18,6 +18,19 @@ import { compositeCatalog } from "./composites/catalog";
 import { DEFAULT_TEMPLATE, GENAI_TEMPLATE, K8S_AGENT_TEMPLATE } from "./init-templates";
 import { COLLECTOR_PIN } from "./define";
 import { collectorTopologyOf } from "./topology";
+import { otelWorkspaceLinks } from "./workspace-links";
+
+/** opentelemetry-collector-releases also tags its tools (`cmd/builder/v0.163.2`); only the plain release tags are distributions. */
+function releaseTag(tag: string): string | null {
+  return /^v\d+\.\d+\.\d+$/.test(tag) ? tag : null;
+}
+
+const SNAPSHOT_MOVES =
+  "The schema snapshot and its digest move with the version: set the version in src/spec/pin.ts, run `just snapshot` " +
+  "(lexicons/otel) on a networked machine, paste the printed OTEL_SPEC_PIN into src/spec/pin.ts, run `npm run generate`, " +
+  "and read the diffs of src/spec/otel-schemas.snapshot.json and the generated types. Moving otelcol-contrib also moves " +
+  "COLLECTOR_PIN and COLLECTOR_IMAGE, the default image of the k8s, docker and fly collector composites, so it is a " +
+  "level-0 change that needs an entry on the exceptions list (#2525).";
 
 const catalogResource: McpResourceContribution = {
   uri: "otel:resource-catalog",
@@ -54,15 +67,47 @@ export const otelPlugin: LexiconPlugin = {
     printValidationResult(await validate());
   },
 
-  async coverage(_options?: { verbose?: boolean; minOverall?: number }): Promise<void> {
-    const components = BUILTIN_CATALOG.filter((c) => c.type !== undefined);
-    const byKind = new Map<string, string[]>();
-    for (const c of components) byKind.set(c.kind, [...(byKind.get(c.kind) ?? []), c.type!]);
-    console.error(`otel: ${components.length} built-in components, typed against ${COLLECTOR_PIN.source} ${COLLECTOR_PIN.version}`);
-    for (const [kind, types] of byKind) console.error(`  ${kind}s: ${types.join(", ")}`);
+  async coverage(options?: { verbose?: boolean; minOverall?: number }): Promise<void> {
+    const { coverageReport, formatCoverage } = await import("./coverage");
+    const report = coverageReport();
+    console.error(formatCoverage(report));
+    if (options?.verbose) {
+      for (const d of report.distributions) {
+        console.error(`  ${d.distribution}, reached through defineComponent: ${[...d.schemaNotBuiltin, ...d.noSchemaNotBuiltin].join(", ")}`);
+      }
+    }
     console.error("  anything else: defineComponent (see docs: custom components)");
   },
 
+  // #3361: coverage against the otelcol-contrib manifest, offline from the
+  // committed schema snapshot.
+  async coverageReport(): Promise<{ unaccountedKinds?: string[] }> {
+    const { coverageReport } = await import("./coverage");
+    return coverageReport();
+  },
+
+  // The distribution manifests the generated config types are scoped by
+  // (#3361): otelcol-contrib, which COLLECTOR_PIN and COLLECTOR_IMAGE follow,
+  // and otelcol-k8s for the coverage report.
+  upstreamPin: {
+    label: "otelcol-contrib",
+    file: "src/spec/pin.ts",
+    pattern: /export const OTELCOL_CONTRIB_VERSION = "([^"]+)"/,
+    replace: (v: string, line: string) => line.replace(/= "[^"]+"/, `= "${v}"`),
+    alsoMoves: SNAPSHOT_MOVES,
+    upstream: { owner: "open-telemetry", repo: "opentelemetry-collector-releases", kind: "releases", tagVersion: releaseTag },
+  },
+  upstreamPins: [
+    {
+      label: "otelcol-k8s",
+      file: "src/spec/pin.ts",
+      pattern: /export const OTELCOL_K8S_VERSION = "([^"]+)"/,
+      replace: (v: string, line: string) => line.replace(/= "[^"]+"/, `= "${v}"`),
+      alsoMoves: SNAPSHOT_MOVES,
+      upstream: { owner: "open-telemetry", repo: "opentelemetry-collector-releases", kind: "releases", tagVersion: releaseTag },
+    },
+  ],
+
   async package(options?: { verbose?: boolean; force?: boolean }): Promise<void> {
     const { packageLexicon } = await import("./codegen/package");
     const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
@@ -88,6 +133,12 @@ export const otelPlugin: LexiconPlugin = {
     return { collector: topology };
   },
 
+  // The tables and columns a clickhouse exporter writes, as links to the sql
+  // member that declares them (#4397), for `chant workspace check`.
+  workspaceLinks(entities) {
+    return otelWorkspaceLinks(entities);
+  },
+
   postSynthChecks() {
     return postSynthChecks;
   },

package/src/serializer.ts

@@ -7,6 +7,9 @@
  * the order they are declared in, and each component's config keeps the key
  * order it was written in, since collector docs and diffs read that way.
  *
+ * A project that declares a `Distribution` also gets the ocb builder manifest,
+ * as `builder-config.yaml` beside the config (see `distribution.ts`).
+ *
  * A collector config has no metadata channel, so there is no ownership marker
  * to stamp. A custom component's schema pin is written as a `# chant:` comment
  * line above the config (see `define.ts`).
@@ -17,6 +20,7 @@ import type { Serializer, SerializerResult } from "@intentius/chant/serializer";
 import type { LexiconOutput } from "@intentius/chant/lexicon-output";
 import { buildCollectorConfig } from "./collector";
 import { emitCollectorYaml } from "./yaml";
+import { DISTRIBUTION_MANIFEST_FILE, distributionYaml, isDistributionEntity } from "./distribution";
 
 export const otelSerializer: Serializer = {
   name: "otel",
@@ -25,7 +29,12 @@ export const otelSerializer: Serializer = {
   serialize(entities: Map<string, Declarable>, _outputs?: LexiconOutput[]): string | SerializerResult {
     const built = buildCollectorConfig(entities);
     const yaml = emitCollectorYaml(built.config, { header: built.header });
-    if (built.warnings.length === 0) return yaml;
-    return { primary: yaml, warnings: built.warnings };
+    const warnings = [...built.warnings];
+    // A declared Distribution (#3374) adds the ocb builder manifest beside the config.
+    const distributions = [...entities.values()].filter(isDistributionEntity);
+    if (distributions.length > 1) warnings.push("otel: more than one Distribution is declared; the first one is written");
+    const files = distributions.length > 0 ? { [DISTRIBUTION_MANIFEST_FILE]: distributionYaml(distributions[0]) } : undefined;
+    if (warnings.length === 0 && !files) return yaml;
+    return { primary: yaml, ...(files ? { files } : {}), ...(warnings.length > 0 ? { warnings } : {}) };
   },
 };