@intentius/chant-lexicon-otel 0.124.45 → 0.124.48

package/src/distribution.test.ts

@@ -0,0 +1,250 @@
+import { describe, expect, test } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { load } from "js-yaml";
+import { makePostSynthCtx } from "@intentius/chant-test-utils";
+import type { Declarable } from "@intentius/chant/declarable";
+import type { ProcessRunner } from "@intentius/chant/components/verbs/process-runner";
+import { BUILTIN_CATALOG } from "./catalog";
+import { COLLECTOR_PIN, defineComponent } from "./define";
+import { otelSerializer } from "./serializer";
+import { otel128 } from "./lint/post-synth/otel128";
+import {
+  BUILTIN_MODULES,
+  DISTRIBUTION_MANIFEST_FILE,
+  Distribution,
+  distributionManifest,
+  distributionYaml,
+  moduleComponentType,
+} from "./distribution";
+import { createOcbBuildCapability, ocbOutputPath } from "./build/ocb-build";
+import { otelCapabilityPlugin, ocbBuild } from "./build/capability-plugin";
+import {
+  BatchProcessor,
+  DebugExporter,
+  OtlpExporter,
+  OtlpReceiver,
+  Pipeline,
+  SpanMetricsConnector,
+  TransformProcessor,
+  otelPlugin,
+} from "./index";
+
+const V = COLLECTOR_PIN.version;
+const CORE = "go.opentelemetry.io/collector";
+const CONTRIB = "github.com/open-telemetry/opentelemetry-collector-contrib";
+
+const AcmeExporter = defineComponent<{ endpoint: string }>()({
+  kind: "exporter",
+  type: "acme",
+  pin: { source: "github.com/acme/otel/exporter/acmeexporter", version: "v1.4.2" },
+});
+
+/**
+ * The keys of the builder's `Config`, `Distribution` and `Module` structs at
+ * v0.130.0 (`cmd/builder/internal/builder/config.go`). ocb reads the manifest
+ * strictly, so a key outside these fails the build.
+ */
+const OCB_CONFIG_KEYS = ["dist", "receivers", "processors", "exporters", "connectors", "extensions", "providers", "converters", "replaces", "excludes", "conf_resolver"];
+const OCB_DIST_KEYS = ["module", "name", "go", "description", "output_path", "version", "build_tags", "debug_compilation", "cgo_enabled", "use_absolute_replace_paths"];
+const OCB_MODULE_KEYS = ["gomod", "import", "name", "path"];
+
+function entities(record: Record<string, unknown>): Map<string, Declarable> {
+  return new Map(Object.entries(record) as Array<[string, Declarable]>);
+}
+
+function distribution(extra: Partial<ConstructorParameters<typeof Distribution>[0]> = {}) {
+  return new Distribution({
+    dist: { name: "otelcol-acme", description: "Acme collector", output_path: "./_build", version: "1.0.0" },
+    receivers: [OtlpReceiver],
+    processors: [BatchProcessor, TransformProcessor],
+    exporters: [OtlpExporter, DebugExporter, AcmeExporter],
+    ...extra,
+  });
+}
+
+describe("Distribution manifest (#3374)", () => {
+  test("every built-in has a Go module, and the table names nothing else", () => {
+    const builtins = BUILTIN_CATALOG.filter((e) => e.type).map((e) => `${e.kind}:${e.type}`).sort();
+    expect(Object.keys(BUILTIN_MODULES).sort()).toEqual(builtins);
+    for (const path of Object.values(BUILTIN_MODULES)) expect(path.startsWith(CORE) || path.startsWith(CONTRIB)).toBe(true);
+  });
+
+  test("built-ins write their module at COLLECTOR_PIN, a custom component its own pin", () => {
+    const m = distributionManifest(distribution({ providers: [{ gomod: `${CORE}/confmap/provider/envprovider v1.36.0` }] }));
+    expect(m).toEqual({
+      dist: { name: "otelcol-acme", description: "Acme collector", output_path: "./_build", version: "1.0.0" },
+      receivers: [{ gomod: `${CORE}/receiver/otlpreceiver ${V}` }],
+      processors: [{ gomod: `${CORE}/processor/batchprocessor ${V}` }, { gomod: `${CONTRIB}/processor/transformprocessor ${V}` }],
+      exporters: [
+        { gomod: `${CORE}/exporter/otlpexporter ${V}` },
+        { gomod: `${CORE}/exporter/debugexporter ${V}` },
+        { gomod: "github.com/acme/otel/exporter/acmeexporter v1.4.2" },
+      ],
+      providers: [{ gomod: `${CORE}/confmap/provider/envprovider v1.36.0` }],
+    });
+  });
+
+  test("the YAML holds only keys ocb's config knows, and reads back to the manifest", () => {
+    const d = distribution({
+      dist: { module: "github.com/acme/otelcol", name: "otelcol-acme", go: "/usr/local/go/bin/go", output_path: "./_build", build_tags: "netgo", debug_compilation: false, cgo_enabled: false, use_absolute_replace_paths: true },
+      connectors: [SpanMetricsConnector],
+      extensions: [{ gomod: "github.com/acme/otel/extension/acmeauthextension v1.4.2", import: "github.com/acme/otel/extension/acmeauthextension/v2", name: "acmeauth", path: "./acmeauth" }],
+      converters: [{ gomod: "github.com/acme/otel/converter v0.1.0" }],
+      replaces: ["github.com/acme/otel => ../otel"],
+      excludes: ["github.com/bad/mod v1.0.0"],
+      conf_resolver: { default_uri_scheme: "env" },
+    });
+    const doc = load(distributionYaml(d)) as Record<string, unknown>;
+    expect(doc).toEqual(distributionManifest(d));
+    for (const k of Object.keys(doc)) expect(OCB_CONFIG_KEYS).toContain(k);
+    for (const k of Object.keys(doc.dist as object)) expect(OCB_DIST_KEYS).toContain(k);
+    for (const list of ["receivers", "processors", "exporters", "connectors", "extensions", "providers", "converters"]) {
+      for (const mod of (doc[list] as Array<Record<string, unknown>> | undefined) ?? []) {
+        for (const k of Object.keys(mod)) expect(OCB_MODULE_KEYS).toContain(k);
+        expect(mod.gomod).toMatch(/^\S+ v\d+\.\d+\.\d+\S*$/);
+      }
+    }
+  });
+
+  test("a component listed under the wrong kind is refused", () => {
+    const d = new Distribution({ dist: {}, receivers: [OtlpExporter as never] });
+    expect(() => distributionManifest(d)).toThrow(/otlp is a exporter, listed under the distribution's receivers/);
+  });
+
+  test("a module's component type is read from a built-in's path or a contrib-style name", () => {
+    expect(moduleComponentType("receiver", `${CORE}/receiver/otlpreceiver ${V}`)).toBe("otlp");
+    expect(moduleComponentType("extension", `${CONTRIB}/extension/k8sleaderelector ${V}`)).toBe("k8s_leader_elector");
+    expect(moduleComponentType("exporter", `${CONTRIB}/exporter/datadogexporter ${V}`)).toBe("datadog");
+    expect(moduleComponentType("exporter", "github.com/acme/otel/vendor-out v1.0.0")).toBeUndefined();
+  });
+});
+
+describe("otel serializer with a Distribution (#3374)", () => {
+  const config = () => {
+    const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" } } });
+    const debug = new DebugExporter({});
+    return { otlp, debug, traces: new Pipeline({ signal: "traces", receivers: [otlp], exporters: [debug] }) };
+  };
+
+  test("writes the builder manifest beside the config", () => {
+    const out = otelSerializer.serialize(entities({ ...config(), dist: distribution() }));
+    expect(typeof out).toBe("object");
+    const files = (out as { files?: Record<string, string> }).files!;
+    expect(Object.keys(files)).toEqual([DISTRIBUTION_MANIFEST_FILE]);
+    expect(load(files[DISTRIBUTION_MANIFEST_FILE])).toEqual(distributionManifest(distribution()));
+  });
+
+  test("a project without a Distribution serializes as before", () => {
+    const out = otelSerializer.serialize(entities(config()));
+    expect(typeof out).toBe("string");
+  });
+
+  test("the Distribution is not part of the collector config", () => {
+    const withDist = otelSerializer.serialize(entities({ ...config(), dist: distribution() }));
+    expect((withDist as { primary: string }).primary).toBe(otelSerializer.serialize(entities(config())));
+  });
+});
+
+describe("OTEL128: the config uses only what the Distribution builds (#3374)", () => {
+  function run(extra: Record<string, unknown>, dist?: unknown) {
+    const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" } } });
+    const all = { otlp, ...extra };
+    const yaml = otelSerializer.serialize(entities(all));
+    const primary = typeof yaml === "string" ? yaml : yaml.primary;
+    return otel128.check(makePostSynthCtx("otel", primary, entities(dist ? { ...all, dist } : all)));
+  }
+
+  test("reports a component missing from the Distribution", () => {
+    const diags = run({ otlpOut: new OtlpExporter({ endpoint: "tempo:4317" }), spans: new SpanMetricsConnector({}) }, distribution());
+    expect(diags.map((d) => [d.checkId, d.severity, d.entity])).toEqual([["OTEL128", "error", "spanmetrics"]]);
+    expect(diags[0].message).toContain('connector "spanmetrics" is not in the Distribution');
+  });
+
+  test("a config the Distribution covers has no finding", () => {
+    expect(run({ otlpOut: new OtlpExporter({ endpoint: "tempo:4317" }), batch: new BatchProcessor({}) }, distribution())).toEqual([]);
+  });
+
+  test("a project without a Distribution is not checked", () => {
+    expect(run({ spans: new SpanMetricsConnector({}) })).toEqual([]);
+  });
+
+  test("a module whose type can't be told makes a missing component a warning that names it", () => {
+    const d = distribution({ connectors: [{ gomod: "github.com/acme/otel/joiner v1.0.0" }] });
+    const diags = run({ spans: new SpanMetricsConnector({}) }, d);
+    expect(diags.map((x) => x.severity)).toEqual(["warning"]);
+    expect(diags[0].message).toContain('"github.com/acme/otel/joiner"');
+  });
+
+  test("is registered and catalogued", () => {
+    expect(otelPlugin.postSynthChecks!().map((c) => c.id)).toContain("OTEL128");
+  });
+});
+
+describe("ocb-build (#3374)", () => {
+  function runner(available = true) {
+    const calls: Array<{ command: string; cwd?: string }> = [];
+    const r: ProcessRunner = {
+      async run(command, options) {
+        calls.push({ command, cwd: options?.cwd });
+        return { stdout: "", stderr: "" };
+      },
+      async available() {
+        return available;
+      },
+    };
+    return { r, calls };
+  }
+
+  function manifest(text: string): { dir: string; path: string } {
+    const dir = mkdtempSync(join(tmpdir(), "ocb-build-"));
+    const path = join(dir, DISTRIBUTION_MANIFEST_FILE);
+    writeFileSync(path, text);
+    return { dir, path };
+  }
+
+  test("runs ocb in the manifest's directory and hands on the output directory", async () => {
+    const m = manifest(distributionYaml(distribution()));
+    try {
+      const { r, calls } = runner();
+      const out = await createOcbBuildCapability(r).run({ env: "dev", component: "collector" }, { config: m.path, skipCompilation: true });
+      expect(calls).toEqual([{ command: `'ocb' --config '${m.path}' --skip-compilation`, cwd: m.dir }]);
+      expect(out.kind).toBe("dir");
+      expect(out.dir).toBe(join(m.dir, "_build"));
+      expect(out.manifestDigest).toMatch(/^sha256:[0-9a-f]{64}$/);
+    } finally {
+      rmSync(m.dir, { recursive: true, force: true });
+    }
+  });
+
+  test("refuses a manifest with no dist.output_path before running ocb", async () => {
+    const m = manifest(distributionYaml(new Distribution({ dist: { name: "x" }, receivers: [OtlpReceiver] })));
+    try {
+      const { r, calls } = runner();
+      await expect(createOcbBuildCapability(r).run({ env: "dev", component: "c" }, { config: m.path })).rejects.toThrow(/sets no dist.output_path/);
+      expect(calls).toEqual([]);
+    } finally {
+      rmSync(m.dir, { recursive: true, force: true });
+    }
+  });
+
+  test("says when ocb is not installed", async () => {
+    const m = manifest(distributionYaml(distribution()));
+    try {
+      await expect(createOcbBuildCapability(runner(false).r).run({ env: "dev", component: "c" }, { config: m.path })).rejects.toThrow(/"ocb" is not installed/);
+    } finally {
+      rmSync(m.dir, { recursive: true, force: true });
+    }
+  });
+
+  test("an absolute output_path is kept", () => {
+    expect(ocbOutputPath("dist:\n  output_path: /opt/build\n", "/work")).toBe("/opt/build");
+  });
+
+  test("the lexicon contributes it as a build verb", () => {
+    expect(otelCapabilityPlugin.capabilities().map((c) => c.kind)).toEqual(["ocb-build"]);
+    expect(otelCapabilityPlugin.families!()).toEqual({ build: ["ocb-build"] });
+    expect(ocbBuild({ config: "dist/builder-config.yaml" })).toEqual({ kind: "ocb-build", config: "dist/builder-config.yaml" });
+  });
+});

package/src/distribution.ts

@@ -0,0 +1,305 @@
+/**
+ * `Distribution`, the builder manifest `ocb` (the OpenTelemetry Collector
+ * Builder) builds a custom collector from (#3374).
+ *
+ * The fields are the builder's `Config` as read at v0.130.0
+ * (`cmd/builder/internal/builder/config.go` in opentelemetry-collector):
+ * `dist`, a module list per component kind, `providers`,
+ * `converters`, `replaces`, `excludes` and `conf_resolver`. `telemetry`
+ * (v0.146.0) is not in it, and `otelcol_version`, removed in v0.113.0, is
+ * not either.
+ *
+ * A component list takes a module (`{ gomod, import?, name?, path? }`) or a
+ * component class. A built-in class writes its module at `COLLECTOR_PIN`
+ * (`OtlpReceiver` is `go.opentelemetry.io/collector/receiver/otlpreceiver
+ * v0.162.0`), and a `defineComponent` class writes its own pin's source and
+ * version, so the manifest names the same versions the config was typed
+ * against.
+ *
+ * The serializer writes the manifest as `builder-config.yaml` beside the
+ * collector config when a project declares a `Distribution`. OTEL128 then
+ * checks that the collector config uses only components the distribution
+ * builds. A project without one sees no change.
+ */
+
+import { createResource } from "@intentius/chant/runtime";
+import type { Declarable } from "@intentius/chant/declarable";
+import { dump } from "js-yaml";
+import { COLLECTOR_PIN, isUsablePin, type ComponentClass, type ComponentDefinition } from "./define";
+import { canonicalComponentType, canonicalTypeOf, COMPONENT_KINDS, SECTION_OF, type CollectorConfig, type ComponentKind } from "./model";
+import type { CollectorIssue } from "./validate-config";
+
+export const DISTRIBUTION_TYPE = "OTel::Distribution";
+
+/** Where the serializer writes the builder manifest, beside the collector config. */
+export const DISTRIBUTION_MANIFEST_FILE = "builder-config.yaml";
+
+/** A Go module the builder adds, as the manifest writes it. */
+export interface DistributionModule {
+  /** The module and its version, as in `go.mod`: `github.com/acme/otel/exporter/acmeexporter v1.2.0`. */
+  gomod: string;
+  /** The Go import path, when it differs from the module path. */
+  import?: string;
+  /** The package name the generated code imports it as. */
+  name?: string;
+  /** A local path the module is replaced with. */
+  path?: string;
+}
+
+/** A component the distribution builds: a component class (built-in or `defineComponent`), or its module. */
+export type DistributionComponent = ComponentClass<ComponentKind, string, any> | DistributionModule;
+
+/** The `dist` section. */
+export interface DistributionDist {
+  /** The Go module of the generated collector. */
+  module?: string;
+  /** The binary's name. */
+  name?: string;
+  /** The `go` binary to build with. */
+  go?: string;
+  /** The description `--help` prints. */
+  description?: string;
+  /** Where the generated sources and the binary go. */
+  output_path?: string;
+  /** The version the binary reports. */
+  version?: string;
+  /** Go build tags. */
+  build_tags?: string;
+  /** Build with debug symbols. */
+  debug_compilation?: boolean;
+  /** Build with cgo enabled. */
+  cgo_enabled?: boolean;
+  /** Write `replace` paths as absolute paths in the generated `go.mod`. */
+  use_absolute_replace_paths?: boolean;
+}
+
+export interface DistributionProps {
+  dist: DistributionDist;
+  receivers?: DistributionComponent[];
+  processors?: DistributionComponent[];
+  exporters?: DistributionComponent[];
+  connectors?: DistributionComponent[];
+  extensions?: DistributionComponent[];
+  /** confmap providers (`env`, `file`, `http`, ...). The builder adds its defaults when none are listed. */
+  providers?: DistributionModule[];
+  /** confmap converters. */
+  converters?: DistributionModule[];
+  /** `replace` directives for the generated `go.mod`. */
+  replaces?: string[];
+  /** `exclude` directives for the generated `go.mod`. */
+  excludes?: string[];
+  conf_resolver?: { default_uri_scheme?: string };
+}
+
+export interface DistributionEntity extends Declarable {
+  readonly props: DistributionProps;
+}
+
+/** A custom collector's builder manifest. Declare at most one per project. */
+export const Distribution = createResource(DISTRIBUTION_TYPE, "otel", {}) as unknown as new (
+  props: DistributionProps,
+) => DistributionEntity;
+
+export function isDistributionEntity(value: unknown): value is DistributionEntity {
+  return typeof value === "object" && value !== null && (value as Declarable).entityType === DISTRIBUTION_TYPE;
+}
+
+const CORE = "go.opentelemetry.io/collector";
+const CONTRIB = "github.com/open-telemetry/opentelemetry-collector-contrib";
+
+/**
+ * The Go module of every built-in, by `kind:type`. The core collector's
+ * components are in opentelemetry-collector, the rest in contrib; both are
+ * released at `COLLECTOR_PIN`'s version. A built-in added to `./components`
+ * needs a row here (distribution.test.ts checks).
+ */
+export const BUILTIN_MODULES: Readonly<Record<string, string>> = Object.freeze({
+  "receiver:otlp": `${CORE}/receiver/otlpreceiver`,
+  "receiver:filelog": `${CONTRIB}/receiver/filelogreceiver`,
+  "receiver:hostmetrics": `${CONTRIB}/receiver/hostmetricsreceiver`,
+  "receiver:prometheus": `${CONTRIB}/receiver/prometheusreceiver`,
+  "receiver:k8s_cluster": `${CONTRIB}/receiver/k8sclusterreceiver`,
+  "receiver:kubeletstats": `${CONTRIB}/receiver/kubeletstatsreceiver`,
+  "processor:batch": `${CORE}/processor/batchprocessor`,
+  "processor:memory_limiter": `${CORE}/processor/memorylimiterprocessor`,
+  "processor:attributes": `${CONTRIB}/processor/attributesprocessor`,
+  "processor:deltatocumulative": `${CONTRIB}/processor/deltatocumulativeprocessor`,
+  "processor:k8sattributes": `${CONTRIB}/processor/k8sattributesprocessor`,
+  "processor:resourcedetection": `${CONTRIB}/processor/resourcedetectionprocessor`,
+  "processor:resource": `${CONTRIB}/processor/resourceprocessor`,
+  "processor:filter": `${CONTRIB}/processor/filterprocessor`,
+  "processor:redaction": `${CONTRIB}/processor/redactionprocessor`,
+  "processor:transform": `${CONTRIB}/processor/transformprocessor`,
+  "processor:probabilistic_sampler": `${CONTRIB}/processor/probabilisticsamplerprocessor`,
+  "processor:tail_sampling": `${CONTRIB}/processor/tailsamplingprocessor`,
+  "exporter:debug": `${CORE}/exporter/debugexporter`,
+  "exporter:otlp": `${CORE}/exporter/otlpexporter`,
+  "exporter:otlphttp": `${CORE}/exporter/otlphttpexporter`,
+  "exporter:googlecloud": `${CONTRIB}/exporter/googlecloudexporter`,
+  "exporter:prometheus": `${CONTRIB}/exporter/prometheusexporter`,
+  "exporter:loadbalancing": `${CONTRIB}/exporter/loadbalancingexporter`,
+  "exporter:clickhouse": `${CONTRIB}/exporter/clickhouseexporter`,
+  "connector:forward": `${CORE}/connector/forwardconnector`,
+  "connector:count": `${CONTRIB}/connector/countconnector`,
+  "connector:routing": `${CONTRIB}/connector/routingconnector`,
+  "connector:servicegraph": `${CONTRIB}/connector/servicegraphconnector`,
+  "connector:signaltometrics": `${CONTRIB}/connector/signaltometricsconnector`,
+  "connector:spanmetrics": `${CONTRIB}/connector/spanmetricsconnector`,
+  "connector:sum": `${CONTRIB}/connector/sumconnector`,
+  "extension:zpages": `${CORE}/extension/zpagesextension`,
+  "extension:health_check": `${CONTRIB}/extension/healthcheckextension`,
+  "extension:k8s_leader_elector": `${CONTRIB}/extension/k8sleaderelector`,
+  "extension:pprof": `${CONTRIB}/extension/pprofextension`,
+});
+
+const KIND_OF_LIST = {
+  receivers: "receiver",
+  processors: "processor",
+  exporters: "exporter",
+  connectors: "connector",
+  extensions: "extension",
+} as const satisfies Record<string, ComponentKind>;
+
+type ComponentList = keyof typeof KIND_OF_LIST;
+
+const COMPONENT_LISTS = Object.keys(KIND_OF_LIST) as ComponentList[];
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isComponentClass(v: unknown): v is ComponentClass<ComponentKind, string, any> {
+  return typeof v === "function" && typeof (v as { definition?: unknown }).definition === "object";
+}
+
+/** The module a component class is built from, at the version its config type follows. */
+export function componentModule(def: ComponentDefinition): DistributionModule {
+  if (def.builtin) {
+    const path = BUILTIN_MODULES[`${def.kind}:${def.type}`];
+    if (!path) throw new Error(`otel: no Go module is recorded for the built-in ${def.kind} "${def.type}"`);
+    return { gomod: `${path} ${COLLECTOR_PIN.version}` };
+  }
+  if (!isUsablePin(def.pin)) {
+    throw new Error(`otel: the custom ${def.kind} "${def.type}" has no pin, so its Go module is unknown; list it as { gomod } instead`);
+  }
+  return { gomod: `${def.pin.source} ${def.pin.version}` };
+}
+
+function copyModule(entry: DistributionModule): DistributionModule {
+  const out: DistributionModule = { gomod: entry.gomod };
+  if (entry.import !== undefined) out.import = entry.import;
+  if (entry.name !== undefined) out.name = entry.name;
+  if (entry.path !== undefined) out.path = entry.path;
+  return out;
+}
+
+function moduleOf(entry: DistributionComponent, list: ComponentList): DistributionModule {
+  if (isComponentClass(entry)) {
+    const def = entry.definition as ComponentDefinition;
+    if (def.kind !== KIND_OF_LIST[list]) {
+      throw new Error(`otel: ${def.type} is a ${def.kind}, listed under the distribution's ${list}`);
+    }
+    return componentModule(def);
+  }
+  return copyModule(entry);
+}
+
+/** The builder manifest a distribution writes, as the object `ocb --config` reads. */
+export function distributionManifest(dist: DistributionEntity | DistributionProps): Record<string, unknown> {
+  const p = isDistributionEntity(dist) ? dist.props : dist;
+  const out: Record<string, unknown> = {};
+  const d: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(p.dist ?? {})) if (v !== undefined) d[k] = v;
+  out.dist = d;
+  for (const list of COMPONENT_LISTS) {
+    const entries = p[list];
+    if (entries && entries.length > 0) out[list] = entries.map((e) => moduleOf(e, list));
+  }
+  if (p.providers && p.providers.length > 0) out.providers = p.providers.map(copyModule);
+  if (p.converters && p.converters.length > 0) out.converters = p.converters.map(copyModule);
+  if (p.replaces && p.replaces.length > 0) out.replaces = [...p.replaces];
+  if (p.excludes && p.excludes.length > 0) out.excludes = [...p.excludes];
+  if (p.conf_resolver && p.conf_resolver.default_uri_scheme !== undefined) {
+    out.conf_resolver = { default_uri_scheme: p.conf_resolver.default_uri_scheme };
+  }
+  return out;
+}
+
+/** The builder manifest as the YAML `ocb --config` reads. */
+export function distributionYaml(dist: DistributionEntity | DistributionProps): string {
+  return dump(distributionManifest(dist), { lineWidth: -1, noRefs: true });
+}
+
+/** The module path of a `gomod` line: everything before the version. */
+function modulePath(gomod: string): string {
+  return gomod.trim().split(/\s+/)[0];
+}
+
+const BUILTIN_BY_PATH = new Map(Object.entries(BUILTIN_MODULES).map(([key, path]) => [path, key.split(":")[1]]));
+
+/**
+ * The component type a module builds, when it can be told: a built-in's
+ * module, or a module path ending `<type><kind>` as contrib's do
+ * (`.../exporter/datadogexporter` is `datadog`). Undefined otherwise.
+ */
+export function moduleComponentType(kind: ComponentKind, gomod: string): string | undefined {
+  const path = modulePath(gomod);
+  const builtin = BUILTIN_BY_PATH.get(path);
+  if (builtin !== undefined) return builtin;
+  const last = path.split("/").pop() ?? "";
+  return last.endsWith(kind) && last.length > kind.length ? last.slice(0, -kind.length) : undefined;
+}
+
+/** What a distribution builds, per kind: the component types it names, and the modules whose type can't be told. */
+export interface DistributionComponents {
+  types: Record<ComponentKind, Set<string>>;
+  unknown: Record<ComponentKind, string[]>;
+}
+
+export function distributionComponents(dist: DistributionEntity | DistributionProps): DistributionComponents {
+  const p = isDistributionEntity(dist) ? dist.props : dist;
+  const types = { receiver: new Set<string>(), processor: new Set<string>(), exporter: new Set<string>(), connector: new Set<string>(), extension: new Set<string>() };
+  const unknown: Record<ComponentKind, string[]> = { receiver: [], processor: [], exporter: [], connector: [], extension: [] };
+  for (const list of COMPONENT_LISTS) {
+    const kind = KIND_OF_LIST[list];
+    for (const entry of p[list] ?? []) {
+      if (isComponentClass(entry)) {
+        types[kind].add(canonicalComponentType(kind, (entry.definition as ComponentDefinition).type));
+        continue;
+      }
+      const type = moduleComponentType(kind, entry.gomod);
+      if (type === undefined) unknown[kind].push(entry.gomod);
+      else types[kind].add(canonicalComponentType(kind, type));
+    }
+  }
+  return { types, unknown };
+}
+
+/**
+ * OTEL128: the components `config` declares that `dist` does not build. A
+ * collector built from the distribution refuses such a config at start with
+ * "unknown type". When a kind lists a module whose type can't be told from
+ * its path, a missing component may be that module, so it is a warning
+ * naming the module rather than an error.
+ */
+export function distributionIssues(config: CollectorConfig, dist: DistributionEntity | DistributionProps): CollectorIssue[] {
+  const { types, unknown } = distributionComponents(dist);
+  const issues: CollectorIssue[] = [];
+  for (const kind of COMPONENT_KINDS) {
+    const section = (config as Record<string, unknown>)[SECTION_OF[kind]];
+    if (typeof section !== "object" || section === null) continue;
+    for (const id of Object.keys(section)) {
+      const type = canonicalTypeOf(kind, id);
+      if (types[kind].has(type)) continue;
+      const unsure = unknown[kind];
+      issues.push({
+        code: "OTEL128",
+        severity: unsure.length > 0 ? "warning" : "error",
+        component: id,
+        message:
+          `${kind} "${id}" is not in the Distribution, so a collector built from it does not know the type "${type}"` +
+          (unsure.length > 0
+            ? `, unless it is built by ${unsure.map((m) => `"${modulePath(m)}"`).join(", ")}, whose type can't be read from its path`
+            : `. Add it to the Distribution's ${SECTION_OF[kind]}, or remove it from the config`),
+      });
+    }
+  }
+  return issues;
+}