@intentius/chant-lexicon-otel 0.81.0

package/src/lint/rules/component-id-syntax.ts

@@ -0,0 +1,68 @@
+import * as ts from "typescript";
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import { isComponentId } from "../../model";
+import { calleeName, COMPONENT_CLASS, literalText, position, propertyName } from "./otel-ast";
+
+/**
+ * OTEL001: a component id or instance name the collector can't parse.
+ *
+ * A pipeline may name a component by id string (`"otlp/backend"`), and every
+ * component takes an instance `name`. Both end up in the collector's
+ * `type[/name]` syntax, where a space, an empty name or a stray `/` is a
+ * config error at collector start. This catches the literal cases in source,
+ * before a build: a string in a `Pipeline`'s receivers, processors or
+ * exporters that isn't `type` or `type/name`, and a component `name` that is
+ * empty, contains whitespace or starts with `/`.
+ */
+export const componentIdSyntaxRule: LintRule = {
+  id: "OTEL001",
+  severity: "error",
+  category: "correctness",
+  description: "Collector component id or instance name is not valid type[/name] syntax",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const source = context.sourceFile;
+
+    const flag = (node: ts.Node, message: string) => {
+      diagnostics.push({ ruleId: "OTEL001", severity: "error", message, file: context.filePath, ...position(source, node) });
+    };
+
+    const visit = (node: ts.Node) => {
+      if (ts.isNewExpression(node) || ts.isCallExpression(node)) {
+        const name = calleeName(node);
+        const arg = node.arguments?.[0];
+        if (name && arg && ts.isObjectLiteralExpression(arg)) {
+          if (name === "Pipeline") {
+            for (const prop of arg.properties) {
+              const key = propertyName(prop);
+              if (key !== "receivers" && key !== "processors" && key !== "exporters") continue;
+              const init = (prop as ts.PropertyAssignment).initializer;
+              if (!ts.isArrayLiteralExpression(init)) continue;
+              for (const el of init.elements) {
+                const text = literalText(el as ts.Expression);
+                if (text !== undefined && !isComponentId(text)) {
+                  flag(el, `"${text}" in ${key} is not a collector component id; write type or type/name, e.g. "otlp" or "otlp/backend"`);
+                }
+              }
+            }
+          }
+          if (name === "Pipeline" || COMPONENT_CLASS.test(name)) {
+            for (const prop of arg.properties) {
+              if (propertyName(prop) !== "name") continue;
+              const text = literalText((prop as ts.PropertyAssignment).initializer);
+              if (text === undefined) continue;
+              if (text === "" || /\s/.test(text) || text.startsWith("/")) {
+                flag(prop, `instance name "${text}" makes an invalid id; a name is non-empty, has no whitespace and does not start with "/"`);
+              }
+            }
+          }
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+
+    visit(source);
+    return diagnostics;
+  },
+};

package/src/lint/rules/index.ts

@@ -0,0 +1,9 @@
+import type { LintRule } from "@intentius/chant/lint/rule";
+import { componentIdSyntaxRule } from "./component-id-syntax";
+import { literalCredentialRule } from "./literal-credential";
+
+export { componentIdSyntaxRule } from "./component-id-syntax";
+export { literalCredentialRule } from "./literal-credential";
+
+/** All lint rules provided by this lexicon (imported by plugin.ts's lintRules()). */
+export const rules: LintRule[] = [componentIdSyntaxRule, literalCredentialRule];

package/src/lint/rules/literal-credential.ts

@@ -0,0 +1,62 @@
+import * as ts from "typescript";
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import { calleeName, COMPONENT_CLASS, literalText, position, propertyName } from "./otel-ast";
+
+/** Keys whose value is a credential. `*_file` keys name a path, which is fine. */
+const SECRET_KEY = /(authorization|api[-_]?key|password|passwd|secret|token|key_pem|x-honeycomb-team)/i;
+
+/**
+ * OTEL002: a credential written as a literal in a component's config.
+ *
+ * Exporters authenticate with headers (`authorization`, `api-key`, vendor
+ * headers) or keys (`api_key`, `password`, `key_pem`). A literal value there
+ * is a secret in the repository and in the emitted YAML. The collector reads
+ * `${env:NAME}` and `${file:/path}` at start-up, so the declaration never
+ * needs the value itself. Any string containing `${` is treated as such a
+ * reference, and keys ending in `_file` name a path and are left alone.
+ */
+export const literalCredentialRule: LintRule = {
+  id: "OTEL002",
+  severity: "error",
+  category: "security",
+  description: "Collector credential declared as a literal instead of ${env:...}",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const source = context.sourceFile;
+
+    const scan = (obj: ts.ObjectLiteralExpression) => {
+      for (const prop of obj.properties) {
+        if (!ts.isPropertyAssignment(prop)) continue;
+        const key = propertyName(prop);
+        const init = prop.initializer;
+        if (ts.isObjectLiteralExpression(init)) {
+          scan(init);
+          continue;
+        }
+        if (!key || !SECRET_KEY.test(key) || /_file$/i.test(key)) continue;
+        const text = literalText(init);
+        if (text === undefined || text === "" || text.includes("${")) continue;
+        diagnostics.push({
+          ruleId: "OTEL002",
+          severity: "error",
+          message: `\`${key}\` is a literal credential; write "\${env:NAME}" (or "\${file:/path}") and let the collector read it at start-up`,
+          file: context.filePath,
+          ...position(source, init),
+        });
+      }
+    };
+
+    const visit = (node: ts.Node) => {
+      if (ts.isNewExpression(node) || ts.isCallExpression(node)) {
+        const name = calleeName(node);
+        const arg = node.arguments?.[0];
+        if (name && COMPONENT_CLASS.test(name) && arg && ts.isObjectLiteralExpression(arg)) scan(arg);
+      }
+      ts.forEachChild(node, visit);
+    };
+
+    visit(source);
+    return diagnostics;
+  },
+};

package/src/lint/rules/otel-ast.ts

@@ -0,0 +1,30 @@
+import * as ts from "typescript";
+
+/** The constructor name of a `new X(...)` or `X(...)` expression, if it is a plain or dotted name. */
+export function calleeName(node: ts.CallExpression | ts.NewExpression): string | undefined {
+  const callee = node.expression;
+  if (ts.isIdentifier(callee)) return callee.text;
+  if (ts.isPropertyAccessExpression(callee)) return callee.name.text;
+  return undefined;
+}
+
+/** Built-in and custom collector component classes follow this naming, e.g. `OtlpExporter`. */
+export const COMPONENT_CLASS = /(Receiver|Processor|Exporter|Extension)$/;
+
+/** A property's key as text, for identifier and string-literal keys. */
+export function propertyName(prop: ts.ObjectLiteralElementLike): string | undefined {
+  if (!ts.isPropertyAssignment(prop)) return undefined;
+  if (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) return prop.name.text;
+  return undefined;
+}
+
+/** The text of a string literal or substitution-free template, else undefined. */
+export function literalText(node: ts.Expression): string | undefined {
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+  return undefined;
+}
+
+export function position(source: ts.SourceFile, node: ts.Node): { line: number; column: number } {
+  const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
+  return { line: line + 1, column: character + 1 };
+}

package/src/lint/rules/rules.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "vitest";
+import * as ts from "typescript";
+import type { LintContext } from "@intentius/chant/lint/rule";
+import { componentIdSyntaxRule } from "./component-id-syntax";
+import { literalCredentialRule } from "./literal-credential";
+
+function ctx(code: string): LintContext {
+  const sourceFile = ts.createSourceFile("collector.ts", code, ts.ScriptTarget.Latest, true);
+  return { sourceFile, entities: [], filePath: "collector.ts" };
+}
+
+describe("OTEL001 component id syntax", () => {
+  test("flags a pipeline string that is not type[/name]", () => {
+    const diags = componentIdSyntaxRule.check(
+      ctx(`export const t = new Pipeline({ signal: "traces", receivers: ["otlp/"], exporters: ["otlp backend", "debug"] });`),
+    );
+    expect(diags.map((d) => d.ruleId)).toEqual(["OTEL001", "OTEL001"]);
+    expect(diags[0].message).toContain('"otlp/"');
+    expect(diags[1].message).toContain('"otlp backend"');
+  });
+
+  test("flags an instance name with whitespace, an empty name or a leading slash", () => {
+    const diags = componentIdSyntaxRule.check(
+      ctx(`
+        new OtlpExporter({ name: "my backend", endpoint: "x:4317" });
+        new DebugExporter({ name: "" });
+        new BatchProcessor({ name: "/fast" });
+      `),
+    );
+    expect(diags).toHaveLength(3);
+    expect(diags[0].line).toBe(2);
+  });
+
+  test("accepts ids, names, entity references and non-literal values", () => {
+    const diags = componentIdSyntaxRule.check(
+      ctx(`
+        const n = "dynamic";
+        new OtlpExporter({ name: "backend", endpoint: "x:4317" });
+        new OtlpExporter({ name: n, endpoint: "x:4317" });
+        new Pipeline({ signal: "traces", receivers: [otlp, "otlp/edge"], processors: ["batch"], exporters: ["otlp/backend"] });
+        new Deployment({ name: "not otel at all" });
+      `),
+    );
+    expect(diags).toEqual([]);
+  });
+});
+
+describe("OTEL002 literal credential", () => {
+  test("flags literal credentials in headers and nested keys", () => {
+    const diags = literalCredentialRule.check(
+      ctx(`
+        new OtlpHttpExporter({ endpoint: "https://api.example", headers: { authorization: "Bearer abc123", "x-api-key": "k" } });
+        new DatadogExporter({ api: { key: "x", api_key: "literal" } });
+      `),
+    );
+    expect(diags.map((d) => d.ruleId)).toEqual(["OTEL002", "OTEL002", "OTEL002"]);
+    expect(diags[0].message).toContain("authorization");
+  });
+
+  test("accepts env and file references, *_file paths, and non-component constructors", () => {
+    const diags = literalCredentialRule.check(
+      ctx(`
+        new OtlpExporter({ endpoint: "x:4317", headers: { authorization: "Bearer \${env:TOKEN}" } });
+        new OtlpExporter({ endpoint: "x:4317", tls: { key_file: "/etc/tls/key.pem", cert_file: "/etc/tls/cert.pem" } });
+        new Secret({ password: "not ours to judge" });
+      `),
+    );
+    expect(diags).toEqual([]);
+  });
+});

package/src/lsp/completions.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { completions } from "./completions";
+
+describe("otel LSP completions", () => {
+  it("offers the built-in classes after new", () => {
+    const content = 'import { OtlpReceiver } from "@intentius/chant-lexicon-otel";\nconst r = new Otlp';
+    const items = completions({
+      uri: "file:///collector.ts",
+      content,
+      position: { line: 1, character: content.split("\n")[1].length },
+      wordAtCursor: "Otlp",
+      linePrefix: "const r = new Otlp",
+    });
+    const labels = items.map((i) => i.label);
+    expect(labels).toContain("OtlpReceiver");
+    expect(labels).toContain("OtlpExporter");
+    expect(labels).toContain("OtlpHttpExporter");
+  });
+
+  it("returns an array for an empty context", () => {
+    expect(Array.isArray(completions({} as never))).toBe(true);
+  });
+});

package/src/lsp/completions.ts

@@ -0,0 +1,15 @@
+import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconCompletions } from "@intentius/chant/lsp/lexicon-providers";
+import { lexiconRegistry } from "../catalog";
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  cachedIndex ??= new LexiconIndex(lexiconRegistry());
+  return cachedIndex;
+}
+
+/** Completions for the otel entity classes: the built-in components, Pipeline and Service. */
+export function completions(ctx: CompletionContext): CompletionItem[] {
+  return lexiconCompletions(ctx, getIndex(), "OpenTelemetry Collector entity");
+}

package/src/lsp/hover.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { hover } from "./hover";
+
+describe("otel LSP hover", () => {
+  it("describes a built-in component and its id", () => {
+    const info = hover({
+      uri: "file:///collector.ts",
+      content: "new BatchProcessor({})",
+      position: { line: 0, character: 6 },
+      word: "BatchProcessor",
+      lineText: "new BatchProcessor({})",
+    });
+    expect(info?.contents).toContain("OTel::Processor::batch");
+    expect(info?.contents).toContain("`batch/<name>`");
+  });
+
+  it("returns undefined for an unknown word", () => {
+    expect(hover({ uri: "file:///x.ts", content: "", position: { line: 0, character: 0 }, word: "Nope", lineText: "" })).toBeUndefined();
+  });
+});

package/src/lsp/hover.ts

@@ -0,0 +1,30 @@
+import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconHover, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+import { BUILTIN_CATALOG, lexiconRegistry } from "../catalog";
+import { COLLECTOR_PIN } from "../define";
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  cachedIndex ??= new LexiconIndex(lexiconRegistry());
+  return cachedIndex;
+}
+
+/** Hover for otel entity classes: what the component does and its collector id. */
+export function hover(ctx: HoverContext): HoverInfo | undefined {
+  return lexiconHover(ctx, getIndex(), resourceHover);
+}
+
+function resourceHover(className: string, entry: LexiconEntry): HoverInfo | undefined {
+  const cat = BUILTIN_CATALOG.find((c) => c.className === className);
+  const lines = [`**${className}**`, "", `otel type: \`${entry.resourceType}\``];
+  if (cat?.description) lines.push("", cat.description);
+  if (cat?.type) {
+    lines.push(
+      "",
+      `Collector id \`${cat.type}\`, or \`${cat.type}/<name>\` with \`name\` set. ` +
+        `Config typed against ${COLLECTOR_PIN.source} ${COLLECTOR_PIN.version}.`,
+    );
+  }
+  return { contents: lines.join("\n") };
+}

package/src/model.ts

@@ -0,0 +1,88 @@
+/**
+ * The plain-data model of an OpenTelemetry Collector config.
+ *
+ * Everything else in this lexicon reads or writes this shape: the serializer
+ * builds it from declared entities, the YAML emitter prints it, the checks
+ * validate it, and `collectorTopology()` reads it back for other tools. It is
+ * exactly the collector's own top-level layout, so a parsed collector YAML
+ * file is already a `CollectorConfig` and needs no conversion.
+ */
+
+/** The three signals a collector pipeline can carry. */
+export const SIGNALS = ["traces", "metrics", "logs"] as const;
+export type Signal = (typeof SIGNALS)[number];
+
+/** The component kinds this lexicon types. Connectors are not modeled yet. */
+export const COMPONENT_KINDS = ["receiver", "processor", "exporter", "extension"] as const;
+export type ComponentKind = (typeof COMPONENT_KINDS)[number];
+
+/** The top-level config section each component kind lives under. */
+export const SECTION_OF: Record<ComponentKind, "receivers" | "processors" | "exporters" | "extensions"> = {
+  receiver: "receivers",
+  processor: "processors",
+  exporter: "exporters",
+  extension: "extensions",
+};
+
+/** A component id, `type` or `type/name`, exactly as the collector spells it. */
+export type ComponentId = string;
+
+/** One pipeline under `service.pipelines`. */
+export interface PipelineConfig {
+  receivers?: ComponentId[];
+  processors?: ComponentId[];
+  exporters?: ComponentId[];
+}
+
+export interface ServiceConfig {
+  extensions?: ComponentId[];
+  telemetry?: Record<string, unknown>;
+  pipelines?: Record<string, PipelineConfig>;
+}
+
+/** A whole collector config file. Every section is optional so a partial file still parses. */
+export interface CollectorConfig {
+  receivers?: Record<ComponentId, Record<string, unknown> | null>;
+  processors?: Record<ComponentId, Record<string, unknown> | null>;
+  exporters?: Record<ComponentId, Record<string, unknown> | null>;
+  extensions?: Record<ComponentId, Record<string, unknown> | null>;
+  connectors?: Record<ComponentId, Record<string, unknown> | null>;
+  service?: ServiceConfig;
+}
+
+/** The collector's id grammar: a type, then optionally `/` and a non-empty name. */
+const ID_PATTERN = /^([A-Za-z0-9_]+)(?:\/([^\s/][^\s]*))?$/;
+
+/** Build a component id from a type and an optional instance name. */
+export function componentId(type: string, name?: string): ComponentId {
+  return name === undefined || name === "" ? type : `${type}/${name}`;
+}
+
+/** Split a component id into its type and name, or `undefined` when it isn't valid id syntax. */
+export function parseComponentId(id: string): { type: string; name?: string } | undefined {
+  const m = ID_PATTERN.exec(id);
+  if (!m) return undefined;
+  return m[2] === undefined ? { type: m[1] } : { type: m[1], name: m[2] };
+}
+
+/** True when `id` is a valid `type[/name]` component id. */
+export function isComponentId(id: string): boolean {
+  return ID_PATTERN.test(id);
+}
+
+/** The signal a pipeline id names, e.g. `traces` for `traces/backend`. */
+export function pipelineSignal(pipelineId: string): string {
+  const slash = pipelineId.indexOf("/");
+  return slash === -1 ? pipelineId : pipelineId.slice(0, slash);
+}
+
+/** True when a parsed document has the shape of a collector config. */
+export function looksLikeCollectorConfig(value: unknown): value is CollectorConfig {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const v = value as Record<string, unknown>;
+  const service = v.service;
+  if (typeof service !== "object" || service === null) return false;
+  const pipelines = (service as Record<string, unknown>).pipelines;
+  if (typeof pipelines !== "object" || pipelines === null) return false;
+  return "receivers" in v || "exporters" in v;
+}

package/src/package-cli.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env tsx
+/**
+ * Thin entry point for `npm run bundle` in lexicon-otel.
+ */
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { generate, writeGeneratedFiles } from "./codegen/generate";
+import { packageLexicon } from "./codegen/package";
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+writeGeneratedFiles(await generate({ verbose: true }));
+const { spec, stats } = await packageLexicon({ verbose: true });
+writeBundleSpec(spec, join(pkgDir, "dist"));
+
+console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);

package/src/pipeline.ts

@@ -0,0 +1,89 @@
+/**
+ * `Pipeline` and `Service`: the `service:` half of a collector config.
+ *
+ * A pipeline names its components either by the declared entity, which
+ * keeps the reference checked by TypeScript, or by id string (`otlp/backend`)
+ * for a component declared somewhere chant can't see. OTEL101 catches a
+ * string that names nothing declared.
+ */
+
+import { createResource } from "@intentius/chant/runtime";
+import type { Declarable } from "@intentius/chant/declarable";
+import type { OTelComponent } from "./define";
+import { componentId, type ComponentKind, type Signal } from "./model";
+
+/** A reference to a component of kind `K`: the declared entity, or its id. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ComponentRef<K extends ComponentKind> = OTelComponent<K, string, any> | string;
+
+export interface PipelineProps {
+  signal: Signal;
+  /** The instance name. The pipeline id becomes `signal/name`. */
+  name?: string;
+  receivers: ComponentRef<"receiver">[];
+  processors?: ComponentRef<"processor">[];
+  exporters: ComponentRef<"exporter">[];
+}
+
+export interface PipelineEntity extends Declarable {
+  readonly props: PipelineProps;
+  /** The pipeline id under `service.pipelines`, `signal` or `signal/name`. */
+  readonly pipelineId: string;
+}
+
+export const PIPELINE_TYPE = "OTel::Pipeline";
+export const SERVICE_TYPE = "OTel::Service";
+
+const PipelineBase = createResource(PIPELINE_TYPE, "otel", {}) as unknown as (this: object, props: Record<string, unknown>) => void;
+
+/** One entry under `service.pipelines`. */
+export const Pipeline = function (this: object, props: PipelineProps) {
+  PipelineBase.call(this, props as unknown as Record<string, unknown>);
+  Object.defineProperty(this, "pipelineId", { value: componentId(props.signal, props.name), enumerable: false });
+} as unknown as new (props: PipelineProps) => PipelineEntity;
+Object.defineProperty(Pipeline, "name", { value: "Pipeline" });
+
+export interface ServiceTelemetry {
+  logs?: {
+    level?: "debug" | "info" | "warn" | "error";
+    encoding?: "console" | "json";
+    development?: boolean;
+    output_paths?: string[];
+    error_output_paths?: string[];
+    initial_fields?: Record<string, string>;
+    sampling?: Record<string, unknown>;
+  };
+  metrics?: {
+    level?: "none" | "basic" | "normal" | "detailed";
+    readers?: Array<Record<string, unknown>>;
+  };
+  traces?: {
+    processors?: Array<Record<string, unknown>>;
+    propagators?: string[];
+  };
+  resource?: Record<string, string>;
+}
+
+export interface ServiceProps {
+  /**
+   * Extensions to enable, in start order. Leave it out and every declared
+   * extension is enabled in declaration order.
+   */
+  extensions?: ComponentRef<"extension">[];
+  telemetry?: ServiceTelemetry;
+}
+
+export interface ServiceEntity extends Declarable {
+  readonly props: ServiceProps;
+}
+
+/** `service.extensions` and `service.telemetry`. Optional; declare at most one. */
+export const Service = createResource(SERVICE_TYPE, "otel", {}) as unknown as new (props: ServiceProps) => ServiceEntity;
+
+export function isPipelineEntity(value: unknown): value is PipelineEntity {
+  return typeof value === "object" && value !== null && (value as Declarable).entityType === PIPELINE_TYPE;
+}
+
+export function isServiceEntity(value: unknown): value is ServiceEntity {
+  return typeof value === "object" && value !== null && (value as Declarable).entityType === SERVICE_TYPE;
+}

package/src/platform.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "vitest";
+import { collectorEndpoints, otlpCollector, COLLECTOR_IMAGE, COLLECTOR_CONFIG_PATH } from "./platform";
+import { buildCollectorConfig } from "./collector";
+import { validateCollectorConfig } from "./validate-config";
+import type { CollectorConfig } from "./model";
+
+describe("otlpCollector", () => {
+  test("the default is OTLP in, memory_limiter then batch, debug out, health_check, every signal", () => {
+    const { config } = buildCollectorConfig(otlpCollector());
+    expect(validateCollectorConfig(config)).toEqual([]);
+    expect(Object.keys(config.receivers ?? {})).toEqual(["otlp"]);
+    expect(Object.keys(config.exporters ?? {})).toEqual(["debug"]);
+    expect(config.service?.extensions).toEqual(["health_check"]);
+    expect(Object.keys(config.service?.pipelines ?? {}).sort()).toEqual(["logs", "metrics", "traces"]);
+    expect(config.service?.pipelines?.traces?.processors).toEqual(["memory_limiter", "batch"]);
+  });
+
+  test("signals and healthCheck narrow it", () => {
+    const { config } = buildCollectorConfig(otlpCollector({ signals: ["traces"], healthCheck: false }));
+    expect(Object.keys(config.service?.pipelines ?? {})).toEqual(["traces"]);
+    expect(config.extensions).toBeUndefined();
+  });
+});
+
+describe("collectorEndpoints", () => {
+  test("the default config listens on otlp-grpc and otlp-http, with a health check on 13133", () => {
+    const { config } = buildCollectorConfig(otlpCollector());
+    expect(collectorEndpoints(config)).toEqual({
+      ports: [
+        { name: "otlp-grpc", port: 4317 },
+        { name: "otlp-http", port: 4318 },
+      ],
+      healthCheck: { port: 13133, path: "/" },
+    });
+  });
+
+  test("a named receiver's ports carry its name, and a repeated port is listed once", () => {
+    const config: CollectorConfig = {
+      receivers: {
+        "otlp/edge": { protocols: { grpc: { endpoint: "0.0.0.0:14317" } } },
+        "otlp/again": { protocols: { grpc: { endpoint: "0.0.0.0:14317" } } },
+      },
+    };
+    expect(collectorEndpoints(config).ports).toEqual([{ name: "otlp-edge-grpc", port: 14317 }]);
+  });
+
+  test("port names are cut to 15 characters", () => {
+    const config: CollectorConfig = {
+      receivers: { "otlp/very_long_name": { protocols: { http: { endpoint: "0.0.0.0:4318" } } } },
+    };
+    const [port] = collectorEndpoints(config).ports;
+    expect(port.name.length).toBeLessThanOrEqual(15);
+    expect(port.name).toMatch(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/);
+  });
+
+  test("a health_check on localhost, or one the service does not enable, is not a health check", () => {
+    const local: CollectorConfig = {
+      extensions: { health_check: { endpoint: "localhost:13133" } },
+      service: { extensions: ["health_check"] },
+    };
+    expect(collectorEndpoints(local).healthCheck).toBeUndefined();
+
+    const disabled: CollectorConfig = { extensions: { health_check: { endpoint: "0.0.0.0:13133" } } };
+    expect(collectorEndpoints(disabled).healthCheck).toBeUndefined();
+  });
+
+  test("a health_check path is carried through", () => {
+    const config: CollectorConfig = {
+      extensions: { "health_check/ready": { endpoint: "0.0.0.0:8080", path: "/ready" } },
+      service: { extensions: ["health_check/ready"] },
+    };
+    expect(collectorEndpoints(config).healthCheck).toEqual({ port: 8080, path: "/ready" });
+  });
+});
+
+test("the image is the contrib collector at a pinned version, and the config lives under /etc/otel", () => {
+  expect(COLLECTOR_IMAGE).toMatch(/^otel\/opentelemetry-collector-contrib:\d+\.\d+\.\d+$/);
+  expect(COLLECTOR_CONFIG_PATH).toBe("/etc/otel/config.yaml");
+});