@intentius/chant-lexicon-otel 0.97.0 → 0.98.0

package/src/import/parser.ts

@@ -0,0 +1,236 @@
+/**
+ * Collector YAML -> `TemplateIR`, for `chant import`.
+ *
+ * A collector config is one document whose parts name each other: pipelines
+ * list component ids, a connector sits in two pipelines, `service.extensions`
+ * lists extension ids. So the IR carries the whole config as one resource of
+ * type `OTel::Collector`, and the generator lays out the modules itself, with
+ * those names turned into imports of declared entities. (Core splits an IR
+ * with more than three resources into one generate() call per category and
+ * keeps only the first file of each, which would lose the imports between a
+ * pipeline and the components it references.)
+ *
+ * The config is carried as parsed, with nothing dropped from a component's
+ * config. What the lexicon cannot express is named in `warnings`.
+ *
+ * The `# chant:` lines the serializer writes above a config are read back:
+ * a custom component's schema pin becomes the pin of the `defineComponent`
+ * the generator writes for it. A config without them imports against
+ * `COLLECTOR_PIN`.
+ */
+
+import * as jsYaml from "js-yaml";
+import type { TemplateIR, TemplateParser } from "@intentius/chant/import/parser";
+import { GENAI_SEMCONV_PIN, type SchemaPin } from "../define";
+import {
+  COMPONENT_KINDS,
+  SECTION_OF,
+  SIGNALS,
+  parseComponentId,
+  pipelineSignal,
+  type CollectorConfig,
+  type ComponentKind,
+} from "../model";
+
+/** The IR resource type for a whole collector config. */
+export const COLLECTOR_RESOURCE_TYPE = "OTel::Collector";
+
+/** One `# chant: <kind> <id> schema <source>@<version>` header line, read back. */
+export interface HeaderPin {
+  kind: ComponentKind;
+  id: string;
+  pin: SchemaPin;
+}
+
+/** One `# chant: semconv <namespace> <source>@<version>` header line, read back. */
+export interface HeaderSemconv {
+  namespace: string;
+  pin: SchemaPin;
+}
+
+/** What the parser read from a collector YAML file. */
+export interface ParsedCollector {
+  config: CollectorConfig;
+  pins: HeaderPin[];
+  semconv: HeaderSemconv[];
+  warnings: string[];
+}
+
+/** `properties` of the `OTel::Collector` resource. */
+export interface CollectorResourceProperties {
+  config: CollectorConfig;
+}
+
+/** `metadata` of the `OTel::Collector` resource. */
+export interface CollectorResourceMetadata {
+  pins: HeaderPin[];
+  semconv: HeaderSemconv[];
+}
+
+// YAML 1.2 core types plus `<<` merge keys. The default schema would also
+// turn an unquoted date into a Date, which the collector never does.
+// js-yaml exports its built-in types at runtime; @types/js-yaml does not declare them.
+const MERGE_TYPE = (jsYaml as unknown as { types: { merge: jsYaml.Type } }).types.merge;
+const COLLECTOR_YAML_SCHEMA = jsYaml.CORE_SCHEMA.extend({ implicit: [MERGE_TYPE] });
+
+const SECTIONS = new Set<string>(["receivers", "processors", "exporters", "connectors", "extensions", "service"]);
+const SERVICE_KEYS = new Set(["extensions", "telemetry", "pipelines"]);
+const PIPELINE_KEYS = new Set(["receivers", "processors", "exporters"]);
+
+const PIN_LINE = /^#\s*chant:\s*(receiver|processor|exporter|connector|extension)\s+(\S+)\s+schema\s+(\S+)@([^@\s]+)(?:\s+(\S+))?\s*$/;
+const SEMCONV_LINE = /^#\s*chant:\s*semconv\s+(\S+)\s+(\S+)@([^@\s]+)(?:\s+([^\s(]+))?(?:\s+\(.*\))?\s*$/;
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** The `# chant:` lines of the comment block at the top of the file. */
+function readHeader(content: string, warnings: string[]): { pins: HeaderPin[]; semconv: HeaderSemconv[] } {
+  const pins: HeaderPin[] = [];
+  const semconv: HeaderSemconv[] = [];
+  for (const raw of content.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line === "") continue;
+    if (!line.startsWith("#")) break;
+    if (!/^#\s*chant:/.test(line)) continue;
+    const pin = PIN_LINE.exec(line);
+    if (pin) {
+      const [, kind, id, source, version, digest] = pin;
+      if (source === "(unpinned)" || version === "(unpinned)") continue;
+      pins.push({ kind: kind as ComponentKind, id, pin: digest ? { source, version, digest } : { source, version } });
+      continue;
+    }
+    const sc = SEMCONV_LINE.exec(line);
+    if (sc) {
+      const [, namespace, source, version, digest] = sc;
+      semconv.push({ namespace, pin: digest ? { source, version, digest } : { source, version } });
+      if (namespace === "gen_ai" && (source !== GENAI_SEMCONV_PIN.source || version !== GENAI_SEMCONV_PIN.version)) {
+        warnings.push(
+          `the config was built against ${namespace} semantic conventions ${source}@${version}; ` +
+            `this lexicon follows ${GENAI_SEMCONV_PIN.source}@${GENAI_SEMCONV_PIN.version}, which the rebuilt config will name`,
+        );
+      }
+      continue;
+    }
+    warnings.push(`header line "${line}" is not a schema pin chant recognises; it is not carried`);
+  }
+  return { pins, semconv };
+}
+
+/** Parse collector YAML into the plain config model, the header pins and what cannot be carried. */
+export function parseCollectorYaml(content: string): ParsedCollector {
+  const warnings: string[] = [];
+  const { pins, semconv } = readHeader(content, warnings);
+  const doc = content.trim() === "" ? {} : jsYaml.load(content, { schema: COLLECTOR_YAML_SCHEMA });
+  if (doc === null || doc === undefined) return { config: {}, pins, semconv, warnings };
+  if (!isPlainObject(doc)) {
+    throw new Error("an OpenTelemetry Collector config is a YAML mapping; this document is not one");
+  }
+
+  const config: CollectorConfig = {};
+  for (const [key, value] of Object.entries(doc)) {
+    if (!SECTIONS.has(key)) {
+      warnings.push(`top-level section "${key}" is not part of a collector config; it is not carried`);
+      continue;
+    }
+    if (value === null || value === undefined) continue;
+    if (!isPlainObject(value)) {
+      warnings.push(`"${key}" is not a mapping; it is not carried`);
+      continue;
+    }
+    if (key === "service") continue;
+    const section: Record<string, Record<string, unknown> | null> = {};
+    for (const [id, cfg] of Object.entries(value)) {
+      if (!parseComponentId(id)) warnings.push(`${key}: "${id}" is not a type[/name] component id`);
+      if (cfg !== null && cfg !== undefined && !isPlainObject(cfg)) {
+        warnings.push(`${key}.${id} is not a mapping; it is carried as an empty config`);
+        section[id] = null;
+        continue;
+      }
+      if (isPlainObject(cfg) && "name" in cfg) {
+        warnings.push(
+          `${key}.${id} has a config key "name", which chant uses for the instance name; the key is not carried`,
+        );
+      }
+      section[id] = (cfg as Record<string, unknown> | null | undefined) ?? null;
+    }
+    (config as Record<string, unknown>)[key] = section;
+  }
+
+  const service = (doc as Record<string, unknown>).service;
+  if (isPlainObject(service)) {
+    config.service = {};
+    for (const [key, value] of Object.entries(service)) {
+      if (!SERVICE_KEYS.has(key)) {
+        warnings.push(`service.${key} is not carried; chant's Service declares extensions and telemetry`);
+        continue;
+      }
+      if (value === null || value === undefined) continue;
+      if (key === "extensions") {
+        if (!Array.isArray(value)) warnings.push("service.extensions is not a list; it is not carried");
+        else config.service.extensions = value.map(String);
+      } else if (key === "telemetry") {
+        if (!isPlainObject(value)) warnings.push("service.telemetry is not a mapping; it is not carried");
+        else config.service.telemetry = value;
+      } else if (key === "pipelines") {
+        if (!isPlainObject(value)) {
+          warnings.push("service.pipelines is not a mapping; it is not carried");
+          continue;
+        }
+        config.service.pipelines = {};
+        for (const [pid, p] of Object.entries(value)) {
+          const signal = pipelineSignal(pid);
+          if (!(SIGNALS as readonly string[]).includes(signal)) {
+            warnings.push(
+              `pipeline "${pid}" carries signal "${signal}", which Pipeline does not type; it is imported with a type suppression`,
+            );
+          }
+          const entry: Record<string, string[]> = {};
+          if (isPlainObject(p)) {
+            for (const [k, list] of Object.entries(p)) {
+              if (!PIPELINE_KEYS.has(k)) {
+                warnings.push(`service.pipelines.${pid}.${k} is not carried; a Pipeline has receivers, processors and exporters`);
+                continue;
+              }
+              if (list === null || list === undefined) continue;
+              if (!Array.isArray(list)) {
+                warnings.push(`service.pipelines.${pid}.${k} is not a list; it is not carried`);
+                continue;
+              }
+              entry[k] = list.map(String);
+            }
+          }
+          config.service.pipelines[pid] = entry;
+        }
+      }
+    }
+  }
+
+  return { config, pins, semconv, warnings };
+}
+
+/** Which kind a section's components are. */
+export const KIND_OF_SECTION: Record<string, ComponentKind> = Object.fromEntries(
+  COMPONENT_KINDS.map((k) => [SECTION_OF[k], k]),
+);
+
+/** The OpenTelemetry Collector config parser `chant import` runs. */
+export class OtelCollectorParser implements TemplateParser {
+  parse(content: string): TemplateIR {
+    const parsed = parseCollectorYaml(content);
+    const properties: CollectorResourceProperties = { config: parsed.config };
+    const metadata: CollectorResourceMetadata = { pins: parsed.pins, semconv: parsed.semconv };
+    return {
+      resources: [
+        {
+          logicalId: "collector",
+          type: COLLECTOR_RESOURCE_TYPE,
+          properties: properties as unknown as Record<string, unknown>,
+          metadata: metadata as unknown as Record<string, unknown>,
+        },
+      ],
+      parameters: [],
+      warnings: parsed.warnings,
+    };
+  }
+}

package/src/import/roundtrip.test.ts

@@ -0,0 +1,365 @@
+/**
+ * Round trips through `chant import`.
+ *
+ * YAML -> TypeScript -> `chant build` -> YAML must give back the same config
+ * (key order and quoting aside) for every fixture: the otel examples' built
+ * output, a gateway with tail_sampling, loadbalancing and spanmetrics,
+ * `genAiPipeline()` output, the two collector configs of
+ * examples/agent-observability, and collector-contrib example configs at the
+ * pinned release. The generated source must lint clean.
+ *
+ * The other direction too: a config using every built-in's typed fields
+ * survives TypeScript -> YAML -> TypeScript -> YAML.
+ *
+ * Where `otelcol-contrib` is on PATH (or `OTELCOL_BIN` names a contrib
+ * build) the re-emitted configs are also checked by `otelcol validate`.
+ * generated-types.e2e.test.ts type-checks the generated source.
+ */
+
+import { describe, expect, test } from "vitest";
+import { spawnSync } from "child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { load } from "js-yaml";
+import { build } from "@intentius/chant/build";
+import { lintCommand } from "@intentius/chant/cli/commands/lint";
+import { importCommand, importFromContent } from "@intentius/chant/cli/commands/import";
+import { otelSerializer } from "../serializer";
+import { collectorYaml } from "../collector";
+import { registeredDefinitions } from "../define";
+import { genAiPipeline } from "../genai";
+import { SECTION_OF, type CollectorConfig, type ComponentKind } from "../model";
+import * as c from "../components";
+import { OtelCollectorParser } from "./parser";
+import { OtelCollectorGenerator } from "./generator";
+import { everyBuiltin, exampleOutputs, pkgDir, primary, read, UPSTREAM_BUILTIN_ONLY } from "./testdata/fixtures";
+
+// ── helpers ─────────────────────────────────────────────────────────
+
+/** A parsed config with the differences the collector does not see taken out. */
+function normalize(yaml: string): CollectorConfig {
+  const doc = (load(yaml) ?? {}) as CollectorConfig;
+  for (const section of Object.values(SECTION_OF)) {
+    const s = doc[section];
+    if (!s) continue;
+    for (const id of Object.keys(s)) if (s[id] === null) s[id] = {};
+    if (Object.keys(s).length === 0) delete doc[section];
+  }
+  const service = doc.service;
+  if (service) {
+    if (service.extensions?.length === 0) delete service.extensions;
+    for (const p of Object.values(service.pipelines ?? {})) {
+      p.receivers ??= [];
+      p.exporters ??= [];
+      if (!p.processors || p.processors.length === 0) delete p.processors;
+    }
+    if (Object.keys(service).length === 0) delete doc.service;
+  }
+  return doc;
+}
+
+/**
+ * The `# chant:` header lines, with the component list of a semconv line
+ * sorted: the rebuilt config lists components in the order the build
+ * discovers them, which within a module is export-name order.
+ */
+function headerLines(yaml: string): string[] {
+  return yaml
+    .split("\n")
+    .filter((l) => /^#\s*chant:/.test(l))
+    .map((l) => l.replace(/\(([^)]*)\)$/, (_, list: string) => `(${list.split(", ").sort().join(", ")})`));
+}
+
+interface Imported {
+  source: string;
+  warnings: string[];
+  yaml: string;
+  buildErrors: unknown[];
+  lint: { errorCount: number; warningCount: number; output: string };
+}
+
+/** A chant project dir inside the package, so the lexicon resolves as it does for a user. */
+function projectDir(): string {
+  const dir = mkdtempSync(join(pkgDir, ".roundtrip-tmp-"));
+  mkdirSync(join(dir, "src"));
+  writeFileSync(join(dir, "chant.config.ts"), 'export default { lexicons: ["otel"] };\n');
+  writeFileSync(join(dir, "package.json"), '{ "name": "otel-import-roundtrip", "private": true, "type": "module" }\n');
+  return dir;
+}
+
+/** YAML -> IR -> TypeScript -> `chant build` -> YAML, and `chant lint` over the source. */
+async function importAndBuild(yaml: string): Promise<Imported> {
+  const ir = new OtelCollectorParser().parse(yaml);
+  const files = new OtelCollectorGenerator().generate(ir);
+  const dir = projectDir();
+  try {
+    const srcDir = join(dir, "src");
+    for (const file of files) writeFileSync(join(srcDir, file.path), file.content);
+    const result = await build(srcDir, [otelSerializer]);
+    const lint = await lintCommand({ path: srcDir, format: "stylish" });
+    return {
+      source: files.map((f) => `// ${f.path}\n${f.content}`).join("\n"),
+      warnings: ir.warnings ?? [],
+      yaml: primary(result.outputs.get("otel")),
+      buildErrors: result.errors,
+      lint: { errorCount: lint.errorCount, warningCount: lint.warningCount, output: lint.output },
+    };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Every import is expected to rebuild equal and lint clean; a fixture may name lint rules it expects to fire. */
+async function expectRoundTrip(yaml: string, opts: { lintRules?: string[] } = {}): Promise<Imported> {
+  const out = await importAndBuild(yaml);
+  expect(out.buildErrors).toEqual([]);
+  expect(normalize(out.yaml)).toEqual(normalize(yaml));
+  if (opts.lintRules) {
+    for (const rule of opts.lintRules) expect(out.lint.output).toContain(rule);
+  } else {
+    if (out.lint.errorCount + out.lint.warningCount > 0) console.log(out.lint.output);
+    expect(out.lint.errorCount).toBe(0);
+    expect(out.lint.warningCount).toBe(0);
+  }
+  return out;
+}
+
+function findOtelcol(): string | undefined {
+  const candidates = [process.env.OTELCOL_BIN, "otelcol-contrib"].filter((b): b is string => !!b);
+  for (const bin of candidates) {
+    const r = spawnSync(bin, ["--version"], { encoding: "utf-8" });
+    if (r.status === 0) return bin;
+  }
+  return undefined;
+}
+
+const OTELCOL = findOtelcol();
+
+function otelcolValidate(yaml: string): { ok: boolean; output: string } {
+  const dir = mkdtempSync(join(tmpdir(), "chant-otelcol-import-"));
+  try {
+    const file = join(dir, "config.yaml");
+    writeFileSync(file, yaml);
+    const r = spawnSync(OTELCOL!, ["validate", `--config=${file}`], {
+      encoding: "utf-8",
+      timeout: 60_000,
+      env: { ...process.env, TEMPO_TOKEN: "t", DEPLOY_ENV: "test", SPLUNK_HEC_TOKEN: "t", K8S_NODE_NAME: "node-1" },
+    });
+    return { ok: r.status === 0, output: `${r.stdout ?? ""}${r.stderr ?? ""}` };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+describe("YAML -> TypeScript -> YAML", () => {
+  test("the otel examples' built output", async () => {
+    const outputs = await exampleOutputs();
+    expect(outputs.map(([n]) => n)).toEqual(["custom-component", "genai-agent", "getting-started", "k8s-node-agent"]);
+    for (const [name, yaml] of outputs) {
+      const out = await expectRoundTrip(yaml);
+      // The `# chant:` header comes back too: the custom component's pin, the semconv line.
+      expect(headerLines(out.yaml), name).toEqual(headerLines(yaml));
+    }
+  });
+
+  test("a gateway with tail_sampling, loadbalancing and spanmetrics", async () => {
+    const yaml = read("gateway.yaml");
+    const out = await expectRoundTrip(yaml);
+    expect(out.source).toContain("new TailSamplingProcessor(");
+    expect(out.source).toContain("new LoadBalancingExporter(");
+    expect(out.source).toContain("const spanmetrics = new SpanMetricsConnector(");
+    // The connector is one entity, on both sides of the join.
+    expect(out.source).toContain("exporters: [otlpTempo, spanmetrics]");
+    expect(out.source).toContain("receivers: [spanmetrics]");
+    // ${env:VAR} stays a reference.
+    expect(out.source).toContain('authorization: "Bearer ${env:TEMPO_TOKEN}"');
+    expect(out.source).toContain('default: "${env:DEPLOY_ENV}"');
+    // pprof is declared but not enabled, so the Service lists what is.
+    expect(out.source).toContain("extensions: [zpages, healthCheck]");
+    expect(out.source).toContain("const telemetry: ServiceTelemetry = {");
+    // Nested config is lifted into named consts typed by the component's config type (COR001).
+    expect(out.source).toContain('const tailSamplingPolicies: TailSamplingProcessorConfig["policies"] = [');
+    expect(out.warnings).toEqual([]);
+  });
+
+  test("genAiPipeline() output", async () => {
+    const tempo = new c.OtlpExporter({ name: "tempo", endpoint: "tempo:4317", tls: { insecure: true } });
+    const sampler = new c.ProbabilisticSamplerProcessor({ sampling_percentage: 25 });
+    for (const entities of [
+      genAiPipeline(),
+      genAiPipeline({ traceExporters: [tempo], sampling: [sampler], keepContent: true, logs: false }),
+      genAiPipeline({ maskValues: ["\\b[0-9]{13,16}\\b"], hashFunction: "sha3", healthCheck: false }),
+    ]) {
+      const yaml = collectorYaml(entities);
+      const out = await expectRoundTrip(yaml);
+      expect(headerLines(out.yaml)).toEqual(headerLines(yaml));
+    }
+  });
+
+  test("the collector configs of examples/agent-observability", async () => {
+    for (const file of ["agent-observability-agent.yaml", "agent-observability-gateway.yaml"]) {
+      await expectRoundTrip(read(file));
+    }
+  });
+
+  for (const file of UPSTREAM_BUILTIN_ONLY) {
+    test(`collector-contrib v0.130.0: ${file}`, async () => {
+      const out = await expectRoundTrip(read("upstream", file));
+      expect(out.source).not.toContain("defineComponent");
+    });
+  }
+
+  test.skipIf(!OTELCOL)("otelcol validate accepts every re-emitted config", async () => {
+    // Not the agent-observability agent: its k8s resolver needs a cluster to build (that example's own tests swap it for dns).
+    const yamls: Array<[string, string]> = [
+      ["gateway.yaml", read("gateway.yaml")],
+      ["agent-observability-gateway.yaml", read("agent-observability-gateway.yaml")],
+      ["genAiPipeline()", collectorYaml(genAiPipeline())],
+      ...UPSTREAM_BUILTIN_ONLY.map((f): [string, string] => [f, read("upstream", f)]),
+      // hostmetrics' root_path is accepted on linux only, which is where the node agent runs.
+      ...(await exampleOutputs()).filter(([n]) => n !== "k8s-node-agent" || process.platform === "linux"),
+    ];
+    for (const [name, yaml] of yamls) {
+      const { yaml: rebuilt } = await importAndBuild(yaml);
+      const { ok, output } = otelcolValidate(rebuilt);
+      expect(ok, `${name}: ${output}`).toBe(true);
+    }
+  });
+
+});
+
+describe("components chant does not ship", () => {
+  test("go through defineComponent with their config as data, and survive the round trip", async () => {
+    const out = await expectRoundTrip(read("upstream", "fault-tolerant-logs.yaml"));
+    expect(out.source).toContain("const FileStorageExtension = defineComponent<Record<string, unknown>>()({");
+    expect(out.source).toContain("pin: COLLECTOR_PIN,");
+    expect(out.source).toMatch(/\/\/ extension "file_storage" is not a component chant ships/);
+    expect(out.source).toContain('const fileStorageFilelogreceiver = new FileStorageExtension({');
+    expect(out.source).toContain('import { FileStorageExtension } from "./custom-components";');
+    // The typed built-ins keep referring to the storage extension by id, as data.
+    expect(out.source).toContain('storage: "file_storage/filelogreceiver"');
+  });
+
+  test("an unknown receiver and exporter in the loadbalancing agent example", async () => {
+    const out = await expectRoundTrip(read("upstream", "loadbalancing-agent.yaml"));
+    expect(out.source).toContain('type: "fluentforward"');
+    expect(out.source).toContain("new LoadBalancingExporter(");
+  });
+
+  test("nop receivers and exporters around a servicegraph connector", async () => {
+    const out = await expectRoundTrip(read("upstream", "servicegraph-nop.yaml"));
+    expect(out.source).toContain("const NopReceiver = defineComponent");
+    expect(out.source).toContain("const NopExporter = defineComponent");
+    expect(out.source).toContain("const servicegraph = new ServiceGraphConnector(");
+  });
+
+  test("a literal credential is imported as found and reported by OTEL002", async () => {
+    const out = await expectRoundTrip(read("upstream", "couchbase.yaml"), { lintRules: ["OTEL002"] });
+    expect(out.source).toContain('password: "otelpassword"');
+    expect(out.source).toContain("const MetricstransformProcessor = defineComponent");
+  });
+
+  test("a pin from the `# chant:` header is carried back into defineComponent", async () => {
+    const yaml = [
+      "# chant: exporter datadog/eu schema github.com/open-telemetry/opentelemetry-collector-contrib/exporter/datadogexporter@v0.129.0 sha256:abc",
+      "receivers:",
+      "  otlp:",
+      "    protocols:",
+      "      grpc: {}",
+      "exporters:",
+      "  datadog/eu:",
+      "    api:",
+      "      key: ${env:DD_API_KEY}",
+      "      site: datadoghq.eu",
+      "service:",
+      "  pipelines:",
+      "    traces:",
+      "      receivers: [otlp]",
+      "      exporters: [datadog/eu]",
+      "",
+    ].join("\n");
+    const out = await expectRoundTrip(yaml);
+    expect(out.source).toContain('version: "v0.129.0"');
+    expect(out.source).toContain('digest: "sha256:abc"');
+    expect(out.source).not.toContain("COLLECTOR_PIN,");
+    expect(headerLines(out.yaml)).toEqual(headerLines(yaml));
+  });
+});
+
+describe("TypeScript -> YAML -> TypeScript -> YAML", () => {
+  test("every built-in, each using its typed fields", async () => {
+    const entities = everyBuiltin();
+    const first = collectorYaml(entities);
+
+    // The fixture covers every built-in this package registers.
+    const config = load(first) as CollectorConfig;
+    const used = new Set<string>();
+    for (const [kind, section] of Object.entries(SECTION_OF) as Array<[ComponentKind, keyof CollectorConfig]>) {
+      for (const id of Object.keys((config[section] as Record<string, unknown>) ?? {})) used.add(`${kind}:${id.split("/")[0]}`);
+    }
+    const builtins = registeredDefinitions().filter((d) => d.builtin).map((d) => `${d.kind}:${d.type}`);
+    expect([...used].sort()).toEqual([...new Set(builtins)].sort());
+
+    const out = await expectRoundTrip(first);
+    expect(out.source).not.toContain("defineComponent");
+    // Importing is a fixed point from there: the rebuilt YAML (components now in
+    // export-name order within each section) gives the same TypeScript and YAML, text for text.
+    const again = await importAndBuild(out.yaml);
+    const third = await importAndBuild(again.yaml);
+    expect(third.source).toBe(again.source);
+    expect(third.yaml).toBe(again.yaml);
+  });
+});
+
+// ── through core's import command ───────────────────────────────────
+
+test("importFromContent writes one module per section through the otel plugin", async () => {
+  const dir = mkdtempSync(join(pkgDir, ".roundtrip-tmp-"));
+  try {
+    const output = join(dir, "src");
+    const result = await importFromContent({ content: read("gateway.yaml"), lexicon: "otel", output });
+    expect(result.error).toBeUndefined();
+    expect(result.success).toBe(true);
+    expect(result.lexicon).toBe("otel");
+    expect(result.generatedFiles).toEqual([
+      "receivers.ts",
+      "processors.ts",
+      "exporters.ts",
+      "connectors.ts",
+      "extensions.ts",
+      "pipelines.ts",
+      "service.ts",
+    ]);
+    const built = await build(output, [otelSerializer]);
+    expect(built.errors).toEqual([]);
+    expect(normalize(primary(built.outputs.get("otel")))).toEqual(normalize(read("gateway.yaml")));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("chant import collector.yaml", () => {
+  for (const lexicon of [undefined, "otel"]) {
+    test(lexicon ? "with --lexicon otel" : "detected as a collector config", async () => {
+      const dir = projectDir();
+      try {
+        const templatePath = join(dir, "collector.yaml");
+        writeFileSync(templatePath, read("gateway.yaml"));
+        const output = join(dir, "src");
+        const result = await importCommand({ templatePath, output, force: true, lexicon });
+        expect(result.error).toBeUndefined();
+        expect(result.success).toBe(true);
+        expect(result.lexicon).toBe("otel");
+        expect(result.generatedFiles).toContain("pipelines.ts");
+        const built = await build(output, [otelSerializer]);
+        expect(built.errors).toEqual([]);
+        expect(normalize(primary(built.outputs.get("otel")))).toEqual(normalize(read("gateway.yaml")));
+        const lint = await lintCommand({ path: output, format: "stylish" });
+        expect(lint.errorCount + lint.warningCount, lint.output).toBe(0);
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    });
+  }
+});

package/src/import/testdata/agent-observability-agent.yaml

@@ -0,0 +1,54 @@
+# The otel-agent-config ConfigMap's config.yaml from examples/agent-observability,
+# as that example builds it. Regenerate from examples/agent-observability/test/built.ts (agentConfigYaml).
+
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  memory_limiter:
+    check_interval: 1s
+    limit_percentage: 80
+    spike_limit_percentage: 20
+  batch:
+    timeout: 1s
+
+exporters:
+  loadbalancing/gateway:
+    routing_key: traceID
+    protocol:
+      otlp:
+        tls:
+          insecure: true
+    resolver:
+      k8s:
+        service: otel-gateway-headless.observability
+        ports: [4317]
+  otlp/gateway:
+    endpoint: otel-gateway.observability.svc:4317
+    tls:
+      insecure: true
+
+extensions:
+  health_check:
+    endpoint: 0.0.0.0:13133
+
+service:
+  extensions: [health_check]
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [memory_limiter, batch]
+      exporters: [loadbalancing/gateway]
+    metrics:
+      receivers: [otlp]
+      processors: [memory_limiter, batch]
+      exporters: [otlp/gateway]
+    logs:
+      receivers: [otlp]
+      processors: [memory_limiter, batch]
+      exporters: [otlp/gateway]