@intentius/chant-lexicon-otel 0.97.0 → 0.98.0

package/README.md

@@ -52,6 +52,10 @@ Each connector supports fixed signal pairs (`spanmetrics`: traces to metrics). O
 
 `defineComponent<Config>()({ kind, type, pin, validate?, endpoints?, connects? })` returns a class that serializes and lints like a built-in. `pin` records the schema source and version the config type follows; it is written as a `# chant:` comment above the emitted config and returned by `collectorTopology()`.
 
+## Importing an existing config
+
+`chant import otel-collector-config.yaml --output src` turns a collector config into this lexicon's TypeScript: one module per section plus `pipelines.ts`, each component a constant of its built-in class (`otlp/tempo` becomes `const otlpTempo = new OtlpExporter({ name: "tempo", ... })`), each connector one constant listed on both sides of its join. `${env:VAR}` references stay references. A component type chant doesn't ship is declared with `defineComponent` in `custom-components.ts`, config carried as data, pinned to the `# chant:` header's pin when the file has one and to `COLLECTOR_PIN` otherwise. `chant build` on the result gives back the same config; the round-trip tests in `src/import/roundtrip.test.ts` hold every example, a sampling gateway, `genAiPipeline()` output and collector-contrib's example configs to that.
+
 ## Checks
 
 OTEL001 and OTEL002 run on source (id syntax, literal credentials). OTEL101 to OTEL109 and OTEL112 run after a build: undeclared or unused components (a connector must be on both sides), empty pipelines, extension wiring, `memory_limiter` placement, id syntax, each component's own config rules, duplicate ids, missing schema pins, and connector signal pairs.
@@ -71,4 +75,5 @@ OTEL001 and OTEL002 run on source (id syntax, literal credentials). OTEL101 to O
 - `src/validate-config.ts`, `src/lint/`: checks
 - `src/topology.ts`, `src/semconv.ts`: the read surface
 - `src/genai.ts`: the GenAI preset
+- `src/import/`: `chant import` for collector YAML (parser, generator, round-trip tests and fixtures)
 - `examples/`: getting-started, k8s-node-agent, genai-agent, custom-component

package/dist/codegen/docs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/codegen/docs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAqEH,wBAAsB,YAAY,CAAC,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB9E"}
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/codegen/docs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAsEH,wBAAsB,YAAY,CAAC,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB9E"}

package/dist/import/generator.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `TemplateIR` -> TypeScript, for `chant import`.
+ *
+ * Writes the collector the way the lexicon's examples are written: a module
+ * per section with one constant per component, typed by its built-in class
+ * (`const otlpTempo = new OtlpExporter({ name: "tempo", ... })`), nested
+ * settings lifted into consts typed by the component's config type (COR001),
+ * at most eight declarables per module (COR009), and an `export { ... }` list
+ * at the end of each. `pipelines.ts` declares a `Pipeline` per pipeline that
+ * references those constants, and `service.ts` a `Service` when
+ * `service.extensions` or `service.telemetry` needs one. A connector is one
+ * constant, listed in the exporters of the pipeline that feeds it and the
+ * receivers of the pipeline it feeds.
+ *
+ * A component type chant does not ship gets a `defineComponent` in
+ * `custom-components.ts`, with its config carried as data and a comment
+ * saying so. Its pin is the one the config's `# chant:` header named, or
+ * `COLLECTOR_PIN`.
+ */
+import type { GeneratedFile, TypeScriptGenerator } from "@intentius/chant/import/generator";
+import type { TemplateIR } from "@intentius/chant/import/parser";
+import { type CollectorConfig, type ComponentKind } from "../model.js";
+import { type CollectorResourceMetadata } from "./parser.js";
+/** The class name of the built-in for `kind` + `type`, if chant ships one. */
+export declare function builtinClassName(kind: ComponentKind, type: string): string | undefined;
+/** A value as a TypeScript expression, starting at column `col`, indented by `indent` spaces. */
+export declare function tsLiteral(v: unknown, indent: number, col?: number): string;
+/**
+ * Generate the TypeScript declaring one collector config: one module per
+ * section (split at eight declarables, as COR009 asks), `pipelines.ts`,
+ * `service.ts` when the config needs a Service, and `custom-components.ts`
+ * for component types chant does not ship.
+ */
+export declare function generateCollectorFiles(config: CollectorConfig, meta?: Partial<CollectorResourceMetadata>): GeneratedFile[];
+/** The OpenTelemetry Collector TypeScript generator `chant import` runs. */
+export declare class OtelCollectorGenerator implements TypeScriptGenerator {
+    generate(ir: TemplateIR): GeneratedFile[];
+}
+//# sourceMappingURL=generator.d.ts.map

package/dist/import/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../src/import/generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAC5F,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAG7E,OAAO,EAML,KAAK,eAAe,EACpB,KAAK,aAAa,EACnB,MAAM,UAAU,CAAC;AAClB,OAAO,EAEL,KAAK,yBAAyB,EAG/B,MAAM,UAAU,CAAC;AAsBlB,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEtF;AAsED,iGAAiG;AACjG,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,CAmB1E;AAoJD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,GAAE,OAAO,CAAC,yBAAyB,CAAM,GAAG,aAAa,EAAE,CA6L9H;AAED,4EAA4E;AAC5E,qBAAa,sBAAuB,YAAW,mBAAmB;IAChE,QAAQ,CAAC,EAAE,EAAE,UAAU,GAAG,aAAa,EAAE;CAQ1C"}

package/dist/import/parser.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 type { TemplateIR, TemplateParser } from "@intentius/chant/import/parser";
+import { type SchemaPin } from "../define.js";
+import { type CollectorConfig, type ComponentKind } from "../model.js";
+/** The IR resource type for a whole collector config. */
+export declare 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[];
+}
+/** Parse collector YAML into the plain config model, the header pins and what cannot be carried. */
+export declare function parseCollectorYaml(content: string): ParsedCollector;
+/** Which kind a section's components are. */
+export declare const KIND_OF_SECTION: Record<string, ComponentKind>;
+/** The OpenTelemetry Collector config parser `chant import` runs. */
+export declare class OtelCollectorParser implements TemplateParser {
+    parse(content: string): TemplateIR;
+}
+//# sourceMappingURL=parser.d.ts.map

package/dist/import/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/import/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACjF,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAML,KAAK,eAAe,EACpB,KAAK,aAAa,EACnB,MAAM,UAAU,CAAC;AAElB,yDAAyD;AACzD,eAAO,MAAM,uBAAuB,oBAAoB,CAAC;AAEzD,mFAAmF;AACnF,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,aAAa,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,SAAS,CAAC;CAChB;AAED,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,SAAS,CAAC;CAChB;AAED,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,eAAe,CAAC;IACxB,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,sDAAsD;AACtD,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,eAAe,CAAC;CACzB;AAED,oDAAoD;AACpD,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAoDD,oGAAoG;AACpG,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAyFnE;AAED,6CAA6C;AAC7C,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAEzD,CAAC;AAEF,qEAAqE;AACrE,qBAAa,mBAAoB,YAAW,cAAc;IACxD,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;CAiBnC"}

package/dist/integrity.json

@@ -1,11 +1,11 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "216f9080194cb20bc1e2a40f1b2ac110fa1d4fcc329c966f620c96556c79e91b",
+    "manifest.json": "cb39957cd5d360c633841a23f79c656f248a58e5b696b23df6560b92b993ecf3",
     "meta.json": "664490c2bee6c839f22994b789adc4708b01a37195f9c193dfb3c974959c5d74",
     "types/index.d.ts": "a1070fd1cb3e8d8a9002fc5a75a80b3bdda02965be351e8aed2dbc2f63d36e3c",
     "rules/component-id-syntax.ts": "95f507614d2626159140d906bce9d086e8ecba18ede22f5ddfbda13ac1c08169",
-    "rules/literal-credential.ts": "7a48049b25a157cb36942399d5fcec810e9aba4c6fc318fb5b098296eb37069c",
+    "rules/literal-credential.ts": "48a235a772476bd56cdaaae3f6e90f8a9b2675317be6dcb48c89e54d2f7a5708",
     "rules/otel-ast.ts": "cf286102f778bd010d130ad8de6adc279de517fffffcd49d7cfb3c419b4bec66",
     "rules/otel-helpers.ts": "22f5ed00f5cf33638558eb4363c7deeeefa2cdc3e666404f5235caf471fb1466",
     "rules/otel101.ts": "9a9d5f79403fb07e78752f904741ab4cec8c0f00975b44fe0b6eace63fda4c13",
@@ -18,9 +18,9 @@
     "rules/otel108.ts": "5eddca667b3ec563a1a7bc745139738d438c4307b4861b999a4d8cff975856b6",
     "rules/otel109.ts": "db025b5f09cc8c5199b420fdfd6e4bae0dd5abd1860903d8c9b4d625162a32b9",
     "rules/otel112.ts": "0a6d9a7d6ba281f3b011dde18646f7c15280dcb8cfeddaa6d20c6080a2c92cb0",
-    "skills/chant-otel.md": "ffb9463406afe9a5b275e71cd3af4bb57bb181bec77ec9a1d4e0bf8d453cb8dd",
+    "skills/chant-otel.md": "f77c11e59c9ee782525fd28b1450397754762c045f917735b7d2697a4ee608b5",
     "skills/chant-otel-custom-components.md": "82e53bb482281f79b428e66fb80a1c194ead74a1a34a88bbebb11c6ad5493258",
     "skills/chant-otel-platforms.md": "c90836952dc5c88d668b890152a5063bdb656bce73fc7fa3233a3ea58ad85686"
   },
-  "composite": "94c7fcb5e740ab1e7e02ef11c9a210b358c7e89fcdea641c198b628a2798d5d8"
+  "composite": "22fa6fb9f67ca60493659623c02cf1141c9231c7a5c4691a14c72a9e44ecfef2"
 }

package/dist/lint/rules/literal-credential.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"literal-credential.d.ts","sourceRoot":"","sources":["../../../src/lint/rules/literal-credential.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAA+B,MAAM,4BAA4B,CAAC;AAMxF;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,EAAE,QA4CnC,CAAC"}
+{"version":3,"file":"literal-credential.d.ts","sourceRoot":"","sources":["../../../src/lint/rules/literal-credential.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAA+B,MAAM,4BAA4B,CAAC;AAMxF;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,EAAE,QAyEnC,CAAC"}

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "otel",
-  "version": "0.97.0",
+  "version": "0.98.0",
   "chantVersion": ">=0.1.0",
   "namespace": "OTel",
   "intrinsics": [],

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAyB9D;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,EAAE,aA6ExB,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AA2B9D;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,EAAE,aAqFxB,CAAC"}

package/dist/rules/literal-credential.ts

@@ -25,25 +25,54 @@ export const literalCredentialRule: LintRule = {
     const diagnostics: LintDiagnostic[] = [];
     const source = context.sourceFile;
 
+    // `const x = { ... }` (or `[...]`, or a string) anywhere in the file, so a
+    // config value lifted out of the constructor into a named const, the way
+    // COR001 asks, is scanned where it is used.
+    const consts = new Map<string, ts.Expression>();
+    const collect = (node: ts.Node) => {
+      if (ts.isVariableDeclarationList(node) && node.flags & ts.NodeFlags.Const) {
+        for (const d of node.declarations) {
+          if (ts.isIdentifier(d.name) && d.initializer) consts.set(d.name.text, d.initializer);
+        }
+      }
+      ts.forEachChild(node, collect);
+    };
+    collect(source);
+
+    const flag = (key: string, node: ts.Node) =>
+      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, node),
+      });
+
+    const scanned = new Set<ts.Node>();
+    const scanValue = (key: string | undefined, value: ts.Expression) => {
+      let init: ts.Expression = value;
+      if (ts.isIdentifier(init)) {
+        const resolved = consts.get(init.text);
+        if (!resolved) return;
+        init = resolved;
+      }
+      if (ts.isObjectLiteralExpression(init) || ts.isArrayLiteralExpression(init)) {
+        if (scanned.has(init)) return;
+        scanned.add(init);
+        if (ts.isObjectLiteralExpression(init)) scan(init);
+        else for (const el of init.elements) scanValue(undefined, el as ts.Expression);
+        return;
+      }
+      if (!key || !SECRET_KEY.test(key) || /_file$/i.test(key)) return;
+      const text = literalText(init);
+      if (text === undefined || text === "" || text.includes("${")) return;
+      flag(key, value);
+    };
+
     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),
-        });
+        if (ts.isShorthandPropertyAssignment(prop)) scanValue(prop.name.text, prop.name);
+        else if (ts.isPropertyAssignment(prop)) scanValue(propertyName(prop), prop.initializer);
       }
     };
 

package/dist/skills/chant-otel.md

@@ -78,6 +78,17 @@ It deletes prompt, completion, system-instruction and tool-call content from spa
 - Every pipeline needs at least one receiver and one exporter (OTEL102). A declared component no pipeline uses is a warning (OTEL103).
 - Declared extensions are enabled in declaration order unless a `Service` lists `extensions` itself.
 
+## Starting from an existing config
+
+When the user already has a collector config file, import it rather than retyping it:
+
+```bash
+chant import otel-collector-config.yaml --output src
+chant build src --lexicon otel -o collector.yaml   # the same config back
+```
+
+The importer writes `receivers.ts`, `processors.ts`, `exporters.ts`, `connectors.ts`, `extensions.ts`, `pipelines.ts`, and `service.ts` when extensions or telemetry need a `Service`. A component type with no built-in class lands in `custom-components.ts` as a `defineComponent` whose config is untyped data; offer to give it a config interface. Settings outside a built-in's config type still import and build, but `tsc` flags them. Read the warnings `chant import` prints: they name anything the lexicon has no place for.
+
 ## Reading the result
 
 `collectorTopologyOf(entities)` returns the pipelines, each component's endpoints and schema pin, for each exporter the signals it carries, the connector `edges` between pipelines, and under `semconv` the semantic-conventions version (`GENAI_SEMCONV_PIN`) the config's `gen_ai.` keys follow, as plain data.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-otel",
-  "version": "0.97.0",
+  "version": "0.98.0",
   "description": "OpenTelemetry Collector lexicon for chant — typed receivers, processors, exporters, connectors, extensions and pipelines, serialized to collector YAML",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -68,7 +68,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.97.0",
+    "@intentius/chant": "^0.98.0",
     "typescript": "^5.9.3"
   }
 }

package/src/codegen/docs.ts

@@ -44,7 +44,8 @@ RED and token metrics.
 Their config types follow the collector-contrib release named on the
 Custom components page. A component chant doesn't ship is added with
 \`defineComponent\`, and it is serialized and checked the same way as the
-built-ins.
+built-ins. \`chant import\` turns an existing collector config file into this
+TypeScript (see Importing a Collector Config).
 
 Checks catch a pipeline that uses a component nobody declared (OTEL101), a
 pipeline with no receivers or exporters (OTEL102), a declared component no

package/src/import/generated-types.e2e.test.ts

@@ -0,0 +1,75 @@
+/**
+ * The generated source type-checks against the lexicon's config types.
+ * Compiling a dozen generated projects takes longer than the unit-test
+ * budget allows, so this runs with the e2e tests.
+ */
+import { describe, expect, test } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import * as ts from "typescript";
+import { collectorYaml } from "../collector";
+import { genAiPipeline } from "../genai";
+import { OtelCollectorParser } from "./parser";
+import { OtelCollectorGenerator } from "./generator";
+import { everyBuiltin, exampleOutputs, pkgDir, read, repoRoot, UPSTREAM_BUILTIN_ONLY } from "./testdata/fixtures";
+
+/** Type errors in generated projects, compiled together against the lexicon's source with the repo's compiler options. */
+function typeErrors(projects: Record<string, Array<{ path: string; content: string }>>): string[] {
+  const dir = mkdtempSync(join(pkgDir, ".roundtrip-tmp-"));
+  try {
+    const files: string[] = [];
+    for (const [name, generated] of Object.entries(projects)) {
+      const sub = join(dir, name.replace(/[^A-Za-z0-9]+/g, "-"));
+      mkdirSync(sub);
+      for (const f of generated) {
+        writeFileSync(join(sub, f.path), f.content);
+        files.push(join(sub, f.path));
+      }
+    }
+    const configFile = ts.readConfigFile(join(repoRoot, "tsconfig.json"), ts.sys.readFile);
+    const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, repoRoot);
+    const program = ts.createProgram(files, { ...parsed.options, noEmit: true });
+    const real = (f: string) => ts.sys.realpath?.(f) ?? f;
+    const fileSet = new Set(files.map(real));
+    const diagnostics = ts.getPreEmitDiagnostics(program).filter((d) => d.file && fileSet.has(real(d.file.fileName)));
+    // A program that saw none of the files would pass vacuously.
+    expect(files.every((f) => program.getSourceFile(f) !== undefined)).toBe(true);
+    return diagnostics.map((d) => {
+      const at = real(d.file!.fileName).slice(real(dir).length + 1);
+      return `${at}: ${ts.flattenDiagnosticMessageText(d.messageText, "\n")}`;
+    });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const generate = (yaml: string) => new OtelCollectorGenerator().generate(new OtelCollectorParser().parse(yaml));
+
+describe("the generated source type-checks against the lexicon's config types", () => {
+  test("for every fixture whose config stays within the typed fields", async () => {
+    const projects: Record<string, Array<{ path: string; content: string }>> = {
+      gateway: generate(read("gateway.yaml")),
+      agent: generate(read("agent-observability-agent.yaml")),
+      agentGateway: generate(read("agent-observability-gateway.yaml")),
+      genai: generate(collectorYaml(genAiPipeline())),
+      everyBuiltin: generate(collectorYaml(everyBuiltin())),
+      faultTolerant: generate(read("upstream", "fault-tolerant-logs.yaml")),
+      ...Object.fromEntries(UPSTREAM_BUILTIN_ONLY.map((f) => [f, generate(read("upstream", f))])),
+      ...Object.fromEntries((await exampleOutputs()).map(([n, y]) => [n, generate(y)])),
+    };
+    expect(typeErrors(projects)).toEqual([]);
+  }, 120_000);
+
+  test("a value outside a built-in's typed config is carried as found, and tsc points at it", () => {
+    // couchbase uses the filter processor's legacy match syntax and a scrape job's basic_auth,
+    // neither of which the lexicon's config types cover.
+    const couchbase = typeErrors({ couchbase: generate(read("upstream", "couchbase.yaml")) });
+    expect(couchbase).toEqual([
+      expect.stringMatching(/^couchbase\/processors\.ts: .*'exclude' does not exist/),
+      expect.stringMatching(/^couchbase\/receivers\.ts: .*'basic_auth' does not exist in type 'PrometheusScrapeConfig'/),
+    ]);
+    // The servicegraph test config writes bucket durations as bare integers (nanoseconds); Duration is a string.
+    const servicegraph = typeErrors({ servicegraph: generate(read("upstream", "servicegraph-nop.yaml")) });
+    expect(servicegraph).toEqual(Array(5).fill("servicegraph/connectors.ts: Type 'number' is not assignable to type 'string'."));
+  }, 120_000);
+});

package/src/import/generator.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect, test } from "vitest";
+import type { CollectorConfig } from "../model";
+import { builtinClassName, generateCollectorFiles, OtelCollectorGenerator, tsLiteral } from "./generator";
+import { OtelCollectorParser } from "./parser";
+
+const files = (config: CollectorConfig, meta = {}) =>
+  Object.fromEntries(generateCollectorFiles(config, meta).map((f) => [f.path, f.content]));
+
+describe("builtinClassName", () => {
+  test("maps every built-in kind and type to its exported class", () => {
+    expect(builtinClassName("receiver", "otlp")).toBe("OtlpReceiver");
+    expect(builtinClassName("exporter", "otlp")).toBe("OtlpExporter");
+    expect(builtinClassName("processor", "tail_sampling")).toBe("TailSamplingProcessor");
+    expect(builtinClassName("connector", "spanmetrics")).toBe("SpanMetricsConnector");
+    expect(builtinClassName("connector", "sum")).toBe("SumConnector");
+    expect(builtinClassName("receiver", "k8s_cluster")).toBe("K8sClusterReceiver");
+    expect(builtinClassName("extension", "health_check")).toBe("HealthCheckExtension");
+    expect(builtinClassName("exporter", "datadog")).toBeUndefined();
+  });
+});
+
+describe("tsLiteral", () => {
+  test("writes plain keys bare, quotes the rest, and prefers single quotes for OTTL", () => {
+    expect(tsLiteral({ a: 1, "b.c": true, d: null }, 0)).toBe('{ a: 1, "b.c": true, d: null }');
+    expect(tsLiteral('attributes["x"] == "y"', 0)).toBe(`'attributes["x"] == "y"'`);
+    expect(tsLiteral(`it's "both"`, 0)).toBe(JSON.stringify(`it's "both"`));
+    expect(tsLiteral("${env:X}", 0)).toBe('"${env:X}"');
+  });
+
+  test("breaks a value across lines past 100 columns", () => {
+    const out = tsLiteral({ list: Array.from({ length: 12 }, (_, i) => `item-${i}`) }, 0);
+    expect(out.split("\n").length).toBeGreaterThan(1);
+    expect(out.split("\n").every((l) => l.length <= 100)).toBe(true);
+  });
+});
+
+describe("generateCollectorFiles", () => {
+  test("one module per section, pipelines importing what they reference", () => {
+    const out = files({
+      receivers: { otlp: { protocols: { grpc: null } } },
+      processors: { batch: null },
+      exporters: { "otlp/tempo": { endpoint: "tempo:4317" } },
+      service: { pipelines: { traces: { receivers: ["otlp"], processors: ["batch"], exporters: ["otlp/tempo"] } } },
+    });
+    expect(Object.keys(out)).toEqual(["receivers.ts", "processors.ts", "exporters.ts", "pipelines.ts"]);
+    expect(out["receivers.ts"]).toContain('const otlpProtocols: OtlpReceiverConfig["protocols"] = { grpc: null };');
+    expect(out["receivers.ts"]).toContain("const otlp = new OtlpReceiver({ protocols: otlpProtocols });");
+    expect(out["receivers.ts"]).toContain("export { otlp };");
+    expect(out["processors.ts"]).toContain("const batch = new BatchProcessor();");
+    expect(out["exporters.ts"]).toContain('const otlpTempo = new OtlpExporter({ name: "tempo", endpoint: "tempo:4317" });');
+    expect(out["pipelines.ts"]).toContain('import { otlpTempo } from "./exporters";');
+    expect(out["pipelines.ts"]).toContain(
+      [
+        "const traces = new Pipeline({",
+        '  signal: "traces",',
+        "  receivers: [otlp],",
+        "  processors: [batch],",
+        "  exporters: [otlpTempo],",
+        "});",
+      ].join("\n"),
+    );
+    expect(out["pipelines.ts"]).toContain("export { traces };");
+  });
+
+  test("an id shared across kinds gets a kind suffix; a connector is one constant on both sides", () => {
+    const out = files({
+      receivers: { otlp: {}, prometheus: { config: { scrape_configs: [] } } },
+      exporters: { otlp: { endpoint: "x:4317" }, prometheus: { endpoint: "0.0.0.0:8889" } },
+      connectors: { spanmetrics: {} },
+      service: {
+        pipelines: {
+          traces: { receivers: ["otlp"], exporters: ["otlp", "spanmetrics"] },
+          metrics: { receivers: ["prometheus", "spanmetrics"], exporters: ["prometheus"] },
+        },
+      },
+    });
+    expect(out["receivers.ts"]).toContain("const otlpReceiver = new OtlpReceiver();");
+    expect(out["exporters.ts"]).toContain('const otlpExporter = new OtlpExporter({ endpoint: "x:4317" });');
+    expect(out["pipelines.ts"]).toContain("  receivers: [otlpReceiver],\n  exporters: [otlpExporter, spanmetrics],");
+    expect(out["pipelines.ts"]).toContain("  receivers: [prometheusReceiver, spanmetrics],\n  exporters: [prometheusExporter],");
+    expect(out["pipelines.ts"]).toContain('import { spanmetrics } from "./connectors";');
+  });
+
+  test("a component type chant does not ship is defined once with defineComponent and COLLECTOR_PIN", () => {
+    const out = files({
+      exporters: { "datadog/a": { api: { key: "${env:DD}" } }, "datadog/b": {}, otlp_http: {} },
+      service: { pipelines: { logs: { receivers: [], exporters: ["datadog/a", "datadog/b", "otlp_http"] } } },
+    });
+    const custom = out["custom-components.ts"];
+    expect(custom).toContain('import { COLLECTOR_PIN, defineComponent } from "@intentius/chant-lexicon-otel";');
+    expect(custom.match(/defineComponent<Record<string, unknown>>\(\)/g)).toHaveLength(2);
+    expect(custom).toContain('const DatadogExporter = defineComponent<Record<string, unknown>>()({\n  kind: "exporter",\n  type: "datadog",\n  pin: COLLECTOR_PIN,\n});');
+    // `OtlpHttpExporter` is the built-in otlphttp exporter's class, so this one is numbered.
+    expect(custom).toContain("const OtlpHttpExporter2 = defineComponent");
+    expect(custom).toContain("export { DatadogExporter, OtlpHttpExporter2 };");
+    expect(out["exporters.ts"]).toContain('import { DatadogExporter, OtlpHttpExporter2 } from "./custom-components";');
+    expect(out["exporters.ts"]).toContain("const datadogAApi = { key: \"${env:DD}\" };");
+    expect(out["exporters.ts"]).toContain('const datadogA = new DatadogExporter({ name: "a", api: datadogAApi });');
+  });
+
+  test("a pin named by the header replaces COLLECTOR_PIN", () => {
+    const out = files(
+      { exporters: { "acme/x": {} } },
+      { pins: [{ kind: "exporter", id: "acme/x", pin: { source: "@acme/otel", version: "2.0.0", digest: "sha256:1" } }] },
+    );
+    expect(out["custom-components.ts"]).toContain('pin: { source: "@acme/otel", version: "2.0.0", digest: "sha256:1" },');
+    expect(out["custom-components.ts"]).not.toContain("COLLECTOR_PIN");
+  });
+
+  test("a Service only when extensions or telemetry differ from the default", () => {
+    const ext = { health_check: null, zpages: null };
+    expect(files({ extensions: ext, service: { extensions: ["health_check", "zpages"] } })["service.ts"]).toBeUndefined();
+    expect(files({ extensions: ext, service: { extensions: ["zpages", "health_check"] } })["service.ts"]).toContain(
+      "const service = new Service({ extensions: [zpages, healthCheck] });",
+    );
+    // Declared but not enabled: an empty list, so the rebuilt config enables none either.
+    expect(files({ extensions: ext })["service.ts"]).toContain("const service = new Service({ extensions: [] });");
+    const withTelemetry = files({ service: { telemetry: { logs: { level: "warn" } } } })["service.ts"];
+    expect(withTelemetry).toContain('const telemetry: ServiceTelemetry = { logs: { level: "warn" } };');
+    expect(withTelemetry).toContain("const service = new Service({ telemetry });");
+  });
+
+  test("more than eight declarables of one section split into numbered modules", () => {
+    const processors = Object.fromEntries(Array.from({ length: 10 }, (_, i) => [`batch/b${i}`, null]));
+    const out = files({ processors });
+    expect(Object.keys(out)).toEqual(["processors-1.ts", "processors-2.ts"]);
+    expect(out["processors-1.ts"].match(/new BatchProcessor/g)).toHaveLength(8);
+    expect(out["processors-2.ts"].match(/new BatchProcessor/g)).toHaveLength(2);
+  });
+
+  test("an id nothing declares stays a string; a signal Pipeline does not type is suppressed with a reason", () => {
+    const out = files({ service: { pipelines: { "profiles/x": { receivers: ["otlp"], exporters: ["debug"] } } } });
+    expect(out["pipelines.ts"]).toContain(
+      [
+        "const profilesX = new Pipeline({",
+        '  // @ts-expect-error "profiles" is a collector signal Pipeline does not type',
+        '  signal: "profiles",',
+        '  name: "x",',
+        '  receivers: ["otlp"],',
+        '  exporters: ["debug"],',
+        "});",
+      ].join("\n"),
+    );
+  });
+
+  test("names are valid identifiers even from awkward ids", () => {
+    const out = files({
+      exporters: { "otlp/2": { endpoint: "a:1" }, "otlp/my-backend.eu": { endpoint: "b:1" }, "debug/new": {} },
+      service: { pipelines: { "traces/default": { receivers: [], exporters: ["otlp/2"] } } },
+    });
+    expect(out["exporters.ts"]).toContain("const otlp2 = new OtlpExporter(");
+    expect(out["exporters.ts"]).toContain("const otlpMyBackendEu = new OtlpExporter(");
+    expect(out["exporters.ts"]).toContain("const debugNew = new DebugExporter(");
+    expect(out["pipelines.ts"]).toContain("const tracesDefault = new Pipeline(");
+  });
+});
+
+describe("OtelCollectorGenerator", () => {
+  test("generates from the parser's IR, and returns a file for an empty config", () => {
+    const gen = new OtelCollectorGenerator();
+    const ir = new OtelCollectorParser().parse("receivers:\n  otlp: {}\n");
+    expect(gen.generate(ir).map((f) => f.path)).toEqual(["receivers.ts"]);
+    expect(gen.generate({ resources: [], parameters: [] })).toHaveLength(1);
+  });
+});