@intentius/chant-lexicon-otel 0.106.4 → 0.108.0

package/src/op/activities/otelcol.ts

@@ -0,0 +1,233 @@
+/**
+ * `otelcol validate` and `otelcol components` as Op steps (#3369).
+ *
+ * - `otelcolValidate` runs the collector binary's own `validate` over a
+ *   config file. Before it does, it reads the binary's version and refuses
+ *   when that is not the version chant's config types follow
+ *   (`COLLECTOR_PIN`): a different collector accepts and rejects different
+ *   fields, so its verdict is not about the config chant built. A step that
+ *   names a `version` checks the binary against that version instead.
+ * - `otelcolComponents` reads the binary's component list and refuses a
+ *   config that uses a receiver, processor, exporter, connector or
+ *   extension the binary was not built with: the failure a custom or core
+ *   distribution gives at start, found before it starts.
+ *
+ * The binary is `bin`, else `$OTELCOL_BIN`, else `otelcol-contrib` on PATH.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { load } from "js-yaml";
+import { nonRetryableFailure } from "@intentius/chant/op";
+import { COLLECTOR_PIN } from "../../define";
+import { COMPONENT_KINDS, SECTION_OF, canonicalComponentType, parseComponentId, type ComponentKind } from "../../model";
+import { defaultExec, type ExecRunner } from "./exec";
+
+export interface OtelcolValidateArgs {
+  /** The collector config file, relative to the working directory. */
+  config: string;
+  /** The collector binary. Default `$OTELCOL_BIN`, else `otelcol-contrib`. */
+  bin?: string;
+  /**
+   * The collector version the binary must be, e.g. `v0.131.0`. Default
+   * `COLLECTOR_PIN`'s version: the one chant's config types follow.
+   */
+  version?: string;
+  /** Replaces the child process. For tests. */
+  _exec?: ExecRunner;
+}
+
+export interface OtelcolValidateResult {
+  config: string;
+  bin: string;
+  /** The binary's version, `v`-prefixed. */
+  version: string;
+  /** Always true: a config the binary rejects fails the step. */
+  ok: boolean;
+  output: string;
+}
+
+export interface OtelcolComponentsArgs {
+  /** The collector config file, relative to the working directory. */
+  config: string;
+  /** The collector binary. Default `$OTELCOL_BIN`, else `otelcol-contrib`. */
+  bin?: string;
+  /** Replaces the child process. For tests. */
+  _exec?: ExecRunner;
+}
+
+export interface MissingComponent {
+  kind: ComponentKind;
+  /** The component id as the config writes it, e.g. `spanmetrics/genai`. */
+  id: string;
+  type: string;
+}
+
+export interface OtelcolComponentsResult {
+  config: string;
+  bin: string;
+  /** The binary's version from its build info, when it prints one. */
+  version?: string;
+  /** Components the config declares, by kind. */
+  used: Record<ComponentKind, string[]>;
+  /** Always empty: a config that uses a missing component fails the step. */
+  missing: MissingComponent[];
+}
+
+/** The binary a step runs. */
+export function otelcolBin(explicit?: string, env: NodeJS.ProcessEnv = process.env): string {
+  return explicit ?? env.OTELCOL_BIN ?? "otelcol-contrib";
+}
+
+/** Normalise `0.130.0`, `v0.130.0` and `v0.130.0-dev` to `v0.130.0` for comparison. */
+function normalizeVersion(v: string): string {
+  const m = /v?(\d+\.\d+\.\d+)/.exec(v.trim());
+  return m ? `v${m[1]}` : v.trim();
+}
+
+/**
+ * The version `otelcol --version` prints: `otelcol-contrib version 0.130.0`.
+ * Undefined when the output names none.
+ */
+export function parseOtelcolVersion(output: string): string | undefined {
+  const m = /version\s+v?(\d+\.\d+\.\d+[^\s]*)/i.exec(output);
+  return m ? `v${m[1]}` : undefined;
+}
+
+function readConfig(path: string, cwd: string): Record<string, unknown> {
+  const text = readFileSync(resolve(cwd, path), "utf8");
+  const value = load(text);
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw nonRetryableFailure(`${path} is not a collector config: it does not hold a YAML mapping`, "OtelcolConfigInvalid");
+  }
+  return value as Record<string, unknown>;
+}
+
+async function binaryVersion(exec: ExecRunner, bin: string): Promise<string> {
+  const r = await exec(bin, ["--version"], { timeoutMs: 30_000 });
+  if (r.code === null) throw new Error(`could not run ${bin}: ${r.error ?? "not found"}. Install the collector or set bin or $OTELCOL_BIN.`);
+  const version = parseOtelcolVersion(`${r.stdout}\n${r.stderr}`);
+  if (r.code !== 0 || !version) throw new Error(`${bin} --version printed no version (exit ${r.code}): ${(r.stdout + r.stderr).trim().slice(0, 200)}`);
+  return version;
+}
+
+/** Run `otelcol validate` over `config`, after checking the binary is the pinned (or the given) version. */
+export async function otelcolValidate(args: OtelcolValidateArgs): Promise<OtelcolValidateResult> {
+  const exec = args._exec ?? defaultExec;
+  const bin = otelcolBin(args.bin);
+  const want = normalizeVersion(args.version ?? COLLECTOR_PIN.version);
+  const have = await binaryVersion(exec, bin);
+  if (normalizeVersion(have) !== want) {
+    const why = args.version
+      ? `the step asks for ${want}`
+      : `chant's collector config types follow ${COLLECTOR_PIN.version} (COLLECTOR_PIN); pass version to validate with another collector`;
+    throw nonRetryableFailure(`${bin} is ${have}, and ${why}`, "OtelcolVersionMismatch");
+  }
+  // Fail on a missing or unreadable file here, with its name, rather than through the binary's message.
+  readConfig(args.config, process.cwd());
+  const r = await exec(bin, ["validate", `--config=${resolve(args.config)}`], { timeoutMs: 120_000 });
+  const output = `${r.stdout}${r.stderr}`.trim();
+  if (r.code !== 0) {
+    throw nonRetryableFailure(`${bin} validate rejected ${args.config} (exit ${r.code ?? "none"}):\n${output}`, "OtelcolConfigInvalid");
+  }
+  return { config: args.config, bin, version: have, ok: true, output };
+}
+
+const KIND_OF_SECTION: Record<string, ComponentKind> = {
+  receivers: "receiver",
+  processors: "processor",
+  exporters: "exporter",
+  connectors: "connector",
+  extensions: "extension",
+};
+
+/** What `otelcol components` lists, by kind: component type names. */
+export interface OtelcolComponentList {
+  version?: string;
+  components: Record<ComponentKind, Set<string>>;
+}
+
+/**
+ * Read `otelcol components` output. The format is YAML and marked unstable
+ * upstream, so this reads what it can: each section may be a list of
+ * objects with a `name` (v0.130.0), a list of plain names (older builds),
+ * or a mapping keyed by name. Unknown top-level keys are ignored.
+ */
+export function parseComponentsOutput(text: string): OtelcolComponentList {
+  let doc: unknown;
+  try {
+    doc = load(text);
+  } catch (err) {
+    throw new Error(`otelcol components printed output that is not YAML: ${(err as Error).message}`);
+  }
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) throw new Error("otelcol components printed no YAML mapping");
+  const d = doc as Record<string, unknown>;
+  const components = Object.fromEntries(COMPONENT_KINDS.map((k) => [k, new Set<string>()])) as Record<ComponentKind, Set<string>>;
+  let found = false;
+  for (const [section, kind] of Object.entries(KIND_OF_SECTION)) {
+    const value = d[section];
+    if (value === undefined || value === null) continue;
+    found = true;
+    const names: unknown[] = Array.isArray(value)
+      ? value.map((e) => (e && typeof e === "object" ? ((e as Record<string, unknown>).name ?? (e as Record<string, unknown>).type) : e))
+      : typeof value === "object"
+        ? Object.keys(value as Record<string, unknown>)
+        : [];
+    for (const n of names) if (typeof n === "string" && n !== "") components[kind].add(n);
+  }
+  if (!found) throw new Error("otelcol components listed no receivers, processors, exporters, connectors or extensions");
+  const build = d.buildinfo as Record<string, unknown> | undefined;
+  const v = build && (typeof build.version === "string" || typeof build.version === "number") ? String(build.version) : undefined;
+  return { ...(v ? { version: normalizeVersion(v) } : {}), components };
+}
+
+/** The component ids a config declares, by kind. */
+export function configComponents(config: Record<string, unknown>): Record<ComponentKind, string[]> {
+  const out = Object.fromEntries(COMPONENT_KINDS.map((k) => [k, [] as string[]])) as Record<ComponentKind, string[]>;
+  for (const kind of COMPONENT_KINDS) {
+    const section = config[SECTION_OF[kind]];
+    if (!section || typeof section !== "object" || Array.isArray(section)) continue;
+    out[kind] = Object.keys(section as Record<string, unknown>);
+  }
+  return out;
+}
+
+/**
+ * The components `used` names that `list` lacks. A renamed built-in counts
+ * under either name: a binary that lists `otlp_grpc` runs a config that says
+ * `otlp`, and the other way round.
+ */
+export function missingComponents(used: Record<ComponentKind, string[]>, list: OtelcolComponentList): MissingComponent[] {
+  const missing: MissingComponent[] = [];
+  for (const kind of COMPONENT_KINDS) {
+    const have = list.components[kind];
+    const canonicalHave = new Set([...have].map((t) => canonicalComponentType(kind, t)));
+    for (const id of used[kind]) {
+      const type = parseComponentId(id)?.type ?? id;
+      if (have.has(type) || canonicalHave.has(canonicalComponentType(kind, type))) continue;
+      missing.push({ kind, id, type });
+    }
+  }
+  return missing;
+}
+
+/** Check `config` uses only components the binary was built with, from `otelcol components`. */
+export async function otelcolComponents(args: OtelcolComponentsArgs): Promise<OtelcolComponentsResult> {
+  const exec = args._exec ?? defaultExec;
+  const bin = otelcolBin(args.bin);
+  const config = readConfig(args.config, process.cwd());
+  const r = await exec(bin, ["components"], { timeoutMs: 60_000 });
+  if (r.code === null) throw new Error(`could not run ${bin}: ${r.error ?? "not found"}. Install the collector or set bin or $OTELCOL_BIN.`);
+  if (r.code !== 0) throw new Error(`${bin} components exited ${r.code}: ${(r.stdout + r.stderr).trim().slice(0, 400)}`);
+  const list = parseComponentsOutput(r.stdout);
+  const used = configComponents(config);
+  const missing = missingComponents(used, list);
+  if (missing.length > 0) {
+    const lines = missing.map((m) => `  ${m.kind} ${m.id}`).join("\n");
+    throw nonRetryableFailure(
+      `${args.config} uses ${missing.length} component(s) ${bin}${list.version ? ` ${list.version}` : ""} was not built with:\n${lines}`,
+      "OtelcolComponentMissing",
+    );
+  }
+  return { config: args.config, bin, ...(list.version ? { version: list.version } : {}), used, missing };
+}

package/src/op/activity-contracts.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "vitest";
+import {
+  ConvergeOp,
+  eq,
+  isActivityContract,
+  loadActivities,
+  loadActivityContracts,
+  report,
+  stepOutput,
+  validateActivitySteps,
+  validateStepOutputRefs,
+  when,
+  type ActivityContract,
+  type ResourceSymptom,
+  type StepOutputRef,
+} from "@intentius/chant/op";
+import * as contracts from "./activity-contracts";
+import * as activities from "./activities";
+import { collectorAudit, collectorHealthObserve, otelcolComponents, otelcolValidate } from "./builders";
+import { CollectorAuditOp } from "./audit-op";
+
+const CONTRACTS: Map<string, ActivityContract> = new Map(
+  Object.values(contracts).filter(isActivityContract).map((c) => [c.name, c]),
+);
+
+const op = (steps: unknown[]) => ({ name: "check", phases: [{ name: "Check", steps: steps as never[] }] });
+
+describe("otel activity contracts (#3369)", () => {
+  test("every exported activity has a contract with a return schema, and nothing else is exported", () => {
+    for (const [key, value] of Object.entries(contracts)) {
+      expect(isActivityContract(value), `${key} is not an ActivityContract`).toBe(true);
+      expect((value as ActivityContract).returns).toBeDefined();
+    }
+    const fns = Object.entries(activities).filter(([, v]) => typeof v === "function").map(([k]) => k).sort();
+    expect([...CONTRACTS.keys()].sort()).toEqual(fns);
+    expect(fns).toEqual(["collectorAudit", "collectorHealthObserve", "otelcolComponents", "otelcolValidate"]);
+  });
+
+  test("the builders' steps validate, and a misspelled key is an error", () => {
+    const steps = [
+      otelcolValidate({ config: "dist/collector.yaml" }),
+      otelcolValidate({ config: "dist/collector.yaml", version: "v0.131.0", bin: "/opt/otelcol-contrib" }),
+      otelcolComponents({ config: "dist/collector.yaml" }),
+      collectorAudit({ mode: "pull-request" }),
+    ];
+    expect(validateActivitySteps(op(steps), CONTRACTS)).toEqual([]);
+    const issues = validateActivitySteps(op([{ kind: "activity", fn: "otelcolValidate", args: { conifg: "x.yaml" } }]), CONTRACTS);
+    expect(issues.some((i) => i.message.includes("conifg"))).toBe(true);
+  });
+
+  test("ConvergeOp({ observe: collectorHealthObserve }) passes OPS012 and OPS013", () => {
+    const { op: converge } = ConvergeOp({
+      name: "collector-health",
+      env: "local",
+      schedule: "*/5 * * * *",
+      observe: collectorHealthObserve({ collectors: [{ name: "gateway", config: "dist/gateway.yaml", host: "127.0.0.1" }] }),
+      rules: [when<ResourceSymptom>(eq("status", "drifted"), report("collector unhealthy"), { id: "collector-down", why: "say so" })],
+    });
+    expect(validateActivitySteps(converge.props as never, CONTRACTS)).toEqual([]);
+    expect(validateStepOutputRefs(converge.props as never, CONTRACTS)).toEqual([]);
+    // Without the contracts the observer's output has no schema (OPS013).
+    expect(validateStepOutputRefs(converge.props as never, new Map()).length).toBeGreaterThan(0);
+  });
+
+  test("CollectorAuditOp is one collectorAudit step, its findings the run's outcome", () => {
+    const { op: audit } = CollectorAuditOp({ name: "collector-audit", schedule: "0 6 * * 1", onFinding: "pull-request" });
+    const props = audit.props as unknown as { schedule?: unknown; phases: Array<{ steps: Array<{ fn: string; args: Record<string, unknown>; outcomeAttribute: unknown }> }> };
+    expect(props.schedule).toEqual({ cron: "0 6 * * 1", overlap: "skip" });
+    expect(props.phases[0].steps[0]).toMatchObject({ fn: "collectorAudit", args: { mode: "pull-request" }, outcomeAttribute: { name: "Findings", from: "findings" } });
+    expect(validateActivitySteps(props as never, CONTRACTS)).toEqual([]);
+    expect(CollectorAuditOp({ name: "a" }).op.props).not.toHaveProperty("schedule");
+  });
+
+  test("builders route profile and id to the step, and take step-output refs", () => {
+    const s = otelcolValidate({ config: "x.yaml", id: "validate", profile: "longInfra" });
+    expect(s).toMatchObject({ fn: "otelcolValidate", args: { config: "x.yaml" }, id: "validate", profile: "longInfra" });
+    const ref: StepOutputRef = s.out.version;
+    expect(ref.step).toBe("validate");
+    const t = otelcolComponents({ config: stepOutput("render", "path") });
+    expect(t.args?.config).toMatchObject({ step: "render" });
+    expect(collectorAudit().profile).toBe("fastIdempotent");
+  });
+
+  test("loadActivities and loadActivityContracts find them by the otel lexicon's name", async () => {
+    const acts = await loadActivities(["otel"]);
+    for (const fn of ["otelcolValidate", "otelcolComponents", "collectorHealthObserve", "collectorAudit"]) expect(acts.has(fn), fn).toBe(true);
+    const loaded = await loadActivityContracts(["otel"]);
+    expect(loaded.get("collectorHealthObserve")?.returns).toBeDefined();
+  });
+});
+
+// ── Compile-time only ────────────────────────────────────────────────
+function _typeChecksOnly(): void {
+  // @ts-expect-error: config is required.
+  otelcolValidate({});
+  // @ts-expect-error: a collector needs a name.
+  collectorHealthObserve({ collectors: [{ config: "x.yaml" }] });
+  // @ts-expect-error: the test seam is not an authoring option.
+  otelcolComponents({ config: "x.yaml", _exec: async () => ({ code: 0, stdout: "", stderr: "" }) });
+  // @ts-expect-error: mode is report, issue or pull-request.
+  collectorAudit({ mode: "merge-request" });
+}
+void _typeChecksOnly;

package/src/op/activity-contracts.ts

@@ -0,0 +1,92 @@
+/**
+ * Activity contracts for this lexicon's `op/activities` (#3369).
+ *
+ * Resolved by convention at `@intentius/chant-lexicon-otel/op/activity-contracts`:
+ * `loadActivityContracts` merges them into the map OPS012 checks each step's
+ * args against and OPS013 checks each step-output reference against. Every
+ * activity here has one. `collectorHealthObserve` needs its return schema
+ * most: it is the observer of a `ConvergeOp({ observe })`, whose Converge
+ * step reads the observer's whole output.
+ *
+ * Each `args` schema mirrors the `*Args` interface in `./activities/`,
+ * without the `_`-prefixed test seams, and is a `z.strictObject`, so a
+ * misspelled key fails the build.
+ */
+
+import { z } from "zod";
+import { activityContract } from "@intentius/chant/op";
+
+const componentKind = z.enum(["receiver", "processor", "exporter", "connector", "extension"]);
+const byKind = z.object({
+  receiver: z.array(z.string()),
+  processor: z.array(z.string()),
+  exporter: z.array(z.string()),
+  connector: z.array(z.string()),
+  extension: z.array(z.string()),
+});
+
+export const otelcolValidateContract = activityContract(
+  "otelcolValidate",
+  z.strictObject({ config: z.string(), bin: z.string().optional(), version: z.string().optional() }),
+  z.object({ config: z.string(), bin: z.string(), version: z.string(), ok: z.boolean(), output: z.string() }),
+);
+
+export const otelcolComponentsContract = activityContract(
+  "otelcolComponents",
+  z.strictObject({ config: z.string(), bin: z.string().optional() }),
+  z.object({
+    config: z.string(),
+    bin: z.string(),
+    version: z.string().optional(),
+    used: byKind,
+    missing: z.array(z.object({ kind: componentKind, id: z.string(), type: z.string() })),
+  }),
+);
+
+const endpointOverrides = z.strictObject({ healthCheck: z.string().optional(), zpages: z.string().optional(), telemetry: z.string().optional() });
+
+export const collectorHealthObserveContract = activityContract(
+  "collectorHealthObserve",
+  z.strictObject({
+    collectors: z.array(
+      z.strictObject({
+        name: z.string(),
+        config: z.string().optional(),
+        configObject: z.record(z.string(), z.unknown()).optional(),
+        host: z.string().optional(),
+        endpoints: endpointOverrides.optional(),
+      }),
+    ),
+    timeoutMs: z.number().optional(),
+    probes: z.number().optional(),
+    probeIntervalMs: z.number().optional(),
+  }),
+  z.object({
+    resources: z.array(z.object({ name: z.string(), status: z.enum(["in-sync", "drifted", "unknown"]), detail: z.string() })),
+  }),
+);
+
+const pinState = z.object({ pin: z.string(), latest: z.string().nullable(), behind: z.number() });
+
+export const collectorAuditContract = activityContract(
+  "collectorAudit",
+  z.strictObject({
+    mode: z.enum(["report", "issue", "pull-request"]).optional(),
+    lexiconDir: z.string().optional(),
+    stability: z.boolean().optional(),
+    stabilityBudget: z.number().optional(),
+    branch: z.string().optional(),
+  }),
+  z.object({
+    mode: z.enum(["report", "issue", "pull-request"]),
+    collector: pinState,
+    semconv: pinState,
+    findings: z.array(
+      z.object({ kind: z.enum(["collector-pin-behind", "semconv-pin-behind", "stability-changed", "deprecated"]), subject: z.string(), detail: z.string() }),
+    ),
+    unchecked: z.array(z.string()),
+    summary: z.string(),
+    issueUrl: z.string().optional(),
+    prUrl: z.string().optional(),
+  }),
+);

package/src/op/audit-op.ts

@@ -0,0 +1,53 @@
+/**
+ * `CollectorAuditOp`: the otel lexicon's pins against upstream, as an Op
+ * with an optional schedule (#3369). It sits at observe, like
+ * `WorkflowAuditOp`: one `collectorAudit` step reads the contrib release
+ * list against `COLLECTOR_PIN`, each built-in component's stability from its
+ * `metadata.yaml`, and `GENAI_SEMCONV_PIN` against the semantic-conventions
+ * releases. `onFinding` says what happens with findings: `report` (the
+ * default), `issue`, or `pull-request`, which bumps the pins on a proposal
+ * branch and opens a pull request. Review and merge of that pull request
+ * are the approval.
+ *
+ * @example
+ * ```typescript
+ * export const { op } = CollectorAuditOp({ name: "collector-audit", schedule: "0 6 * * 1", onFinding: "pull-request" });
+ * ```
+ */
+
+import { Op, phase, type OpResource } from "@intentius/chant/op";
+import { collectorAudit } from "./builders";
+import type { CollectorAuditMode } from "./activities/collector-audit";
+
+export interface CollectorAuditOpConfig {
+  /** Op name (kebab-case). */
+  name: string;
+  /** Cron expression; omit for one-shot `chant run`. */
+  schedule?: string;
+  /** @default "report" */
+  onFinding?: CollectorAuditMode;
+  /** The otel lexicon's directory a pull request edits. Default `lexicons/otel`. */
+  lexiconDir?: string;
+  /** At most this many `metadata.yaml` reads. Default 200. */
+  stabilityBudget?: number;
+}
+
+export interface CollectorAuditOpResources {
+  op: InstanceType<typeof OpResource>;
+}
+
+export function CollectorAuditOp(config: CollectorAuditOpConfig): CollectorAuditOpResources {
+  const step = collectorAudit({
+    mode: config.onFinding ?? "report",
+    ...(config.lexiconDir ? { lexiconDir: config.lexiconDir } : {}),
+    ...(config.stabilityBudget !== undefined ? { stabilityBudget: config.stabilityBudget } : {}),
+  });
+  const op = Op({
+    name: config.name,
+    overview: "Audit the otel lexicon's collector and semantic-convention pins and its components' stability against upstream releases",
+    labels: { Audit: "true", Surface: "otel-collector" },
+    ...(config.schedule ? { schedule: { cron: config.schedule, overlap: "skip" as const } } : {}),
+    phases: [phase("Audit", [{ ...step, outcomeAttribute: { name: "Findings", from: "findings" } }])],
+  });
+  return { op };
+}

package/src/op/builders.ts

@@ -0,0 +1,52 @@
+/**
+ * Typed step builders for this lexicon's Op activities (#3369), following
+ * the helm and fly builders: each one's options ARE the activity's own
+ * `*Args` interface (minus its `_`-prefixed test seams), so the builder and
+ * the implementation cannot drift, and every field also takes a
+ * `StepOutputRef`. `profile` and `id` go to the step, never into args, so
+ * `.out` works once an id is given.
+ */
+
+import { activity, takeProfileAndId, type ActivityStep, type NamedActivityStep, type WithStepRefs } from "@intentius/chant/op";
+import type { OtelcolValidateArgs, OtelcolComponentsArgs } from "./activities/otelcol";
+import type { CollectorHealthObserveArgs } from "./activities/collector-health";
+import type { CollectorAuditArgs } from "./activities/collector-audit";
+
+type StepOpts = { profile?: ActivityStep["profile"]; id?: string };
+/** An activity's args as an author writes them: without the test seams. */
+type Authored<T> = Omit<T, `_${string}`>;
+
+function step<Args>(fn: string, defaultProfile: NonNullable<ActivityStep["profile"]>) {
+  return (args: WithStepRefs<Authored<Args>> & StepOpts): NamedActivityStep => {
+    const { args: rest, profile, id } = takeProfileAndId(args as Record<string, unknown>);
+    return activity(fn, rest, { profile: profile ?? defaultProfile, ...(id ? { id } : {}) });
+  };
+}
+
+/**
+ * Run `otelcol validate` over a collector config file. Refuses when the
+ * binary is not `COLLECTOR_PIN`'s version, unless `version` names the one it
+ * must be. Defaults to the `fastIdempotent` profile.
+ */
+export const otelcolValidate = step<OtelcolValidateArgs>("otelcolValidate", "fastIdempotent");
+
+/**
+ * Check a collector config uses only components the binary was built with,
+ * from `otelcol components`. Defaults to the `fastIdempotent` profile.
+ */
+export const otelcolComponents = step<OtelcolComponentsArgs>("otelcolComponents", "fastIdempotent");
+
+/**
+ * Observe running collectors for a `ConvergeOp({ observe })`: one resource
+ * per collector, from the health_check, zpages and internal-telemetry
+ * endpoints its config declares. No `health_check` in `service.extensions`
+ * is `unknown`. Defaults to the `fastIdempotent` profile.
+ */
+export const collectorHealthObserve = step<CollectorHealthObserveArgs>("collectorHealthObserve", "fastIdempotent");
+
+/**
+ * Audit the lexicon's pins against upstream releases (the step of
+ * `CollectorAuditOp`). Defaults to the `fastIdempotent` profile.
+ */
+export const collectorAudit = (args: WithStepRefs<Authored<CollectorAuditArgs>> & StepOpts = {}): NamedActivityStep =>
+  step<CollectorAuditArgs>("collectorAudit", "fastIdempotent")(args);

package/src/op/testdata/otelcol-components-v0.130.0.yaml

@@ -0,0 +1,82 @@
+# The shape `otelcol-contrib components` prints at v0.130.0, cut down to a
+# few entries per section. The format is marked unstable upstream; the
+# components parser is pinned to it by src/op/activities/otelcol.test.ts.
+buildinfo:
+    command: otelcol-contrib
+    description: OpenTelemetry Collector Contrib
+    version: 0.130.0
+receivers:
+    - name: otlp
+      module: go.opentelemetry.io/collector/receiver/otlpreceiver v0.130.0
+      stability:
+        logs: Stable
+        metrics: Stable
+        traces: Stable
+    - name: k8s_cluster
+      module: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/k8sclusterreceiver v0.130.0
+      stability:
+        logs: Development
+        metrics: Beta
+    - name: prometheus
+      module: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/prometheusreceiver v0.130.0
+      stability:
+        metrics: Beta
+processors:
+    - name: batch
+      module: go.opentelemetry.io/collector/processor/batchprocessor v0.130.0
+      stability:
+        logs: Beta
+        metrics: Beta
+        traces: Beta
+    - name: memory_limiter
+      module: go.opentelemetry.io/collector/processor/memorylimiterprocessor v0.130.0
+      stability:
+        logs: Beta
+        metrics: Beta
+        traces: Beta
+    - name: tail_sampling
+      module: github.com/open-telemetry/opentelemetry-collector-contrib/processor/tailsamplingprocessor v0.130.0
+      stability:
+        traces: Beta
+exporters:
+    - name: debug
+      module: go.opentelemetry.io/collector/exporter/debugexporter v0.130.0
+      stability:
+        logs: Development
+        metrics: Development
+        traces: Development
+    - name: otlp
+      module: go.opentelemetry.io/collector/exporter/otlpexporter v0.130.0
+      stability:
+        logs: Stable
+        metrics: Stable
+        traces: Stable
+    - name: prometheus
+      module: github.com/open-telemetry/opentelemetry-collector-contrib/exporter/prometheusexporter v0.130.0
+      stability:
+        metrics: Beta
+connectors:
+    - name: forward
+      module: go.opentelemetry.io/collector/connector/forwardconnector v0.130.0
+      stability:
+        logs-to-logs: Beta
+        metrics-to-metrics: Beta
+        traces-to-traces: Beta
+    - name: spanmetrics
+      module: github.com/open-telemetry/opentelemetry-collector-contrib/connector/spanmetricsconnector v0.130.0
+      stability:
+        traces-to-metrics: Alpha
+extensions:
+    - name: health_check
+      module: github.com/open-telemetry/opentelemetry-collector-contrib/extension/healthcheckextension v0.130.0
+      stability:
+        extension: Beta
+    - name: zpages
+      module: go.opentelemetry.io/collector/extension/zpagesextension v0.130.0
+      stability:
+        extension: Beta
+providers:
+    - scheme: env
+      module: go.opentelemetry.io/collector/confmap/provider/envprovider v1.36.0
+    - scheme: file
+      module: go.opentelemetry.io/collector/confmap/provider/fileprovider v1.36.0