@intentius/chant-lexicon-otel 0.124.30 → 0.124.32

package/dist/attribution.js

@@ -0,0 +1,391 @@
+/**
+ * OTEL118: a collector processor that can remove or replace a resource
+ * attribute chant's telemetry attribution stamps (ws-060, #3375).
+ *
+ * A workload built inside a workspace carries `service.name`,
+ * `service.version`, `deployment.environment.name`, `vcs.ref.head.revision`
+ * and `chant.*` keys on its resource. hud and behold join a span to a member,
+ * a release and a graph node by them. A collector between the workload and the
+ * backend can undo that, and these are the processors that can:
+ *
+ * - `resource`: a `delete`, `update`, `upsert` or `hash` action on a protected
+ *   `key`, or a `delete` or `hash` whose `pattern` matches one. `insert` only
+ *   adds a missing key. `extract` writes the pattern's named groups, and an RE2
+ *   group name has no dot, so it can't name a protected key.
+ * - `transform`: an OTTL statement on the resource's attributes that calls
+ *   `set`, `delete_key` or `delete_matching_keys` on a protected key, or
+ *   `keep_keys` or `keep_matching_keys` that leaves one out. This is a text
+ *   match over the statement, not a parse.
+ * - `resourcedetection` with `override` on (its default at contrib v0.130.0,
+ *   `factory.go` `createDefaultConfig`) and a detector that can write a
+ *   protected key: `env` (the collector's own `OTEL_RESOURCE_ATTRIBUTES`, and
+ *   the default detector list), `dynatrace` (any key in its properties file),
+ *   `heroku` (`service.name`, `service.version`) and `elastic_beanstalk`
+ *   (`service.version`), per each detector's `metadata.yaml` at that tag.
+ * - `groupbyattrs`: a protected key in `keys`. A record attribute with that
+ *   key is copied over the resource's (`attribute_groups.go`
+ *   `buildReferenceResource`).
+ * - `redaction`: it runs over resource attributes too. With `allow_all_keys`
+ *   off, its default, every key not in `allowed_keys` or `ignored_keys` is
+ *   deleted; a `blocked_key_patterns` entry matching a protected key that isn't
+ *   ignored masks its value. `blocked_values` matches values, which a config
+ *   doesn't show, so it is not checked.
+ * - `sumologic`: `translate_attributes`, on by default, renames `service.name`
+ *   to `service` on log and metric resources; `nest_attributes` (off by
+ *   default) turns dotted keys into maps; an `aggregate_attributes` prefix
+ *   moves the keys it matches.
+ * - `schema`: a target in the `https://opentelemetry.io/schemas/` family below
+ *   1.29.0 renames `vcs.ref.head.revision` back to
+ *   `vcs.repository.ref.revision`, and below 1.27.0 renames
+ *   `deployment.environment.name` back to `deployment.environment`, for data
+ *   with a newer schema URL.
+ * - `metricstransform`: a `group` transform whose `group_resource_labels`
+ *   sets a protected key.
+ * - `logstransform`: an operator that adds, removes, moves or copies onto a
+ *   `resource["<key>"]` field for a protected key, a `retain` that lists
+ *   resource fields and leaves one out, or a parser with `parse_to: resource`.
+ *
+ * `k8sattributes` can extract `service.name` and `service.version`, but it
+ * writes pod metadata only where the key is absent or empty
+ * (`processor.go` `setResourceAttribute`), so it never replaces the
+ * workload's value. The `attributes` processor acts on span, log and metric
+ * attributes, not the resource's. Neither is checked. Only processors some
+ * pipeline lists are.
+ */
+import { TELEMETRY_ATTRIBUTES } from "@intentius/chant/telemetry-attribution";
+import { canonicalTypeOf } from "./model.js";
+/** The keys the attribution stamps. Any other `chant.*` key is protected too. */
+export const PROTECTED_RESOURCE_ATTRIBUTES = TELEMETRY_ATTRIBUTES.map((a) => a.key);
+/** True for a key OTEL118 protects: one of `PROTECTED_RESOURCE_ATTRIBUTES`, or any `chant.*` key. */
+export function isProtectedResourceAttribute(key) {
+    return PROTECTED_RESOURCE_ATTRIBUTES.includes(key) || key.startsWith("chant.");
+}
+/** The protected keys a regular expression matches. An RE2 pattern JavaScript can't compile matches none. */
+function protectedMatching(pattern) {
+    let re;
+    try {
+        re = new RegExp(pattern);
+    }
+    catch {
+        return [];
+    }
+    return PROTECTED_RESOURCE_ATTRIBUTES.filter((k) => re.test(k));
+}
+function quoteAll(keys) {
+    return keys.map((k) => `"${k}"`).join(", ");
+}
+const REPLACING_ACTIONS = {
+    delete: "removes",
+    update: "replaces",
+    upsert: "replaces",
+    hash: "replaces with its hash",
+};
+function resourceActionFindings(body) {
+    const out = [];
+    const actions = Array.isArray(body.attributes) ? body.attributes : [];
+    for (const raw of actions) {
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        const { key, action, pattern } = raw;
+        const verb = typeof action === "string" ? REPLACING_ACTIONS[action] : undefined;
+        if (!verb)
+            continue;
+        if (typeof key === "string" && isProtectedResourceAttribute(key)) {
+            out.push(`its ${action} action ${verb} "${key}"`);
+        }
+        else if (typeof pattern === "string" && (action === "delete" || action === "hash")) {
+            const hit = protectedMatching(pattern);
+            if (hit.length > 0)
+                out.push(`its ${action} action's pattern "${pattern}" matches ${quoteAll(hit)}`);
+        }
+    }
+    return out;
+}
+// ── transform: a text match over OTTL ────────────────────────────────
+const OTTL_CALL = /\b(set|delete_key|delete_matching_keys|keep_keys|keep_matching_keys)\s*\(/g;
+/** The top-level arguments of the call whose `(` is at `open`, as written. */
+function callArguments(text, open) {
+    const args = [];
+    let depth = 0;
+    let start = open + 1;
+    let quoted = false;
+    for (let i = open; i < text.length; i++) {
+        const c = text[i];
+        if (quoted) {
+            if (c === "\\")
+                i++;
+            else if (c === '"')
+                quoted = false;
+            continue;
+        }
+        if (c === '"')
+            quoted = true;
+        else if (c === "(" || c === "[" || c === "{")
+            depth++;
+        else if (c === ")" || c === "]" || c === "}") {
+            depth--;
+            if (depth === 0) {
+                args.push(text.slice(start, i).trim());
+                return args;
+            }
+        }
+        else if (c === "," && depth === 1) {
+            args.push(text.slice(start, i).trim());
+            start = i + 1;
+        }
+    }
+    return args;
+}
+/** The OTTL string literals in `text`, unescaped. */
+function stringLiterals(text) {
+    return [...text.matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((m) => m[1].replace(/\\(["\\])/g, "$1"));
+}
+/**
+ * Whether `path` is the resource's attribute map, and the key it indexes.
+ * `resource.attributes` always is; a bare `attributes` is only in a statement
+ * group whose context is `resource`.
+ */
+function resourcePath(path, resourceContext) {
+    const m = /^(resource\.)?attributes\s*(?:\[\s*"((?:[^"\\]|\\.)*)"\s*\])?$/.exec(path);
+    if (!m || (!m[1] && !resourceContext))
+        return undefined;
+    return m[2] === undefined ? {} : { key: m[2].replace(/\\(["\\])/g, "$1") };
+}
+function statementFindings(statement, resourceContext) {
+    const out = [];
+    for (const call of statement.matchAll(OTTL_CALL)) {
+        const fn = call[1];
+        const args = callArguments(statement, call.index + call[0].length - 1);
+        const target = resourcePath(args[0] ?? "", resourceContext);
+        if (!target)
+            continue;
+        const [literal] = stringLiterals(args[1] ?? "");
+        if (fn === "set") {
+            if (target.key === undefined)
+                out.push(`set replaces the whole resource attribute map`);
+            else if (isProtectedResourceAttribute(target.key))
+                out.push(`set replaces "${target.key}"`);
+        }
+        else if (target.key !== undefined) {
+            continue;
+        }
+        else if (fn === "delete_key" && literal !== undefined && isProtectedResourceAttribute(literal)) {
+            out.push(`delete_key removes "${literal}"`);
+        }
+        else if (fn === "delete_matching_keys" && literal !== undefined) {
+            const hit = protectedMatching(literal);
+            if (hit.length > 0)
+                out.push(`delete_matching_keys "${literal}" removes ${quoteAll(hit)}`);
+        }
+        else if (fn === "keep_keys") {
+            const kept = new Set(stringLiterals(args[1] ?? ""));
+            const dropped = PROTECTED_RESOURCE_ATTRIBUTES.filter((k) => !kept.has(k));
+            if (dropped.length > 0)
+                out.push(`keep_keys drops ${quoteAll(dropped)}`);
+        }
+        else if (fn === "keep_matching_keys" && literal !== undefined) {
+            const hit = new Set(protectedMatching(literal));
+            const dropped = PROTECTED_RESOURCE_ATTRIBUTES.filter((k) => !hit.has(k));
+            if (dropped.length > 0)
+                out.push(`keep_matching_keys "${literal}" drops ${quoteAll(dropped)}`);
+        }
+    }
+    return out;
+}
+function transformFindings(body) {
+    const out = [];
+    for (const [field, groups] of Object.entries(body)) {
+        if (!field.endsWith("_statements") || !Array.isArray(groups))
+            continue;
+        for (const group of groups) {
+            // A plain string infers its context from its paths, so only `resource.` paths reach the resource.
+            const [statements, resourceContext] = typeof group === "string"
+                ? [[group], false]
+                : typeof group === "object" && group !== null
+                    ? [group.statements, group.context === "resource"]
+                    : [[], false];
+            if (!Array.isArray(statements))
+                continue;
+            for (const statement of statements) {
+                if (typeof statement !== "string")
+                    continue;
+                for (const finding of statementFindings(statement, resourceContext)) {
+                    out.push(`the OTTL text \`${statement}\` matches a call where ${finding}`);
+                }
+            }
+        }
+    }
+    return out;
+}
+// ── resourcedetection ────────────────────────────────────────────────
+/** Detectors that can write a protected key, and which. */
+const OVERRIDING_DETECTORS = {
+    env: "any key in the collector's own OTEL_RESOURCE_ATTRIBUTES",
+    dynatrace: "any key in the Dynatrace properties file",
+    heroku: '"service.name" and "service.version"',
+    elastic_beanstalk: '"service.version"',
+};
+function detectionFindings(body) {
+    // `override` defaults to true, and `detectors` to [env], at contrib v0.130.0.
+    if (body.override === false)
+        return [];
+    const detectors = Array.isArray(body.detectors) ? body.detectors : ["env"];
+    const how = body.override === true ? "override: true" : "override on by default";
+    return detectors
+        .filter((d) => typeof d === "string" && d in OVERRIDING_DETECTORS)
+        .map((d) => `with ${how}, the ${d} detector writes ${OVERRIDING_DETECTORS[d]} over the service's own value; set override: false`);
+}
+// ── processors that rewrite the resource as a side effect ─────────────
+function strings(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+function groupByAttrsFindings(body) {
+    const keys = strings(body.keys).filter(isProtectedResourceAttribute);
+    return keys.length > 0 ? [`it groups by ${quoteAll(keys)}, so a record attribute with that key is copied over the resource's value`] : [];
+}
+function redactionFindings(body) {
+    const out = [];
+    const ignored = new Set(strings(body.ignored_keys));
+    const allowed = new Set(strings(body.allowed_keys));
+    const exposed = PROTECTED_RESOURCE_ATTRIBUTES.filter((k) => !ignored.has(k));
+    if (body.allow_all_keys !== true) {
+        const deleted = exposed.filter((k) => !allowed.has(k));
+        if (deleted.length > 0) {
+            const how = body.allow_all_keys === false ? "allow_all_keys: false" : "allow_all_keys off by default";
+            out.push(`with ${how}, it deletes resource keys missing from allowed_keys and ignored_keys: ${quoteAll(deleted)}`);
+        }
+    }
+    for (const pattern of strings(body.blocked_key_patterns)) {
+        const masked = exposed.filter((k) => protectedMatching(pattern).includes(k));
+        if (masked.length > 0)
+            out.push(`its blocked_key_patterns entry "${pattern}" masks the value of ${quoteAll(masked)}`);
+    }
+    return out;
+}
+function sumologicFindings(body) {
+    const out = [];
+    // `translate_attributes` defaults to true at contrib v0.130.0.
+    if (body.translate_attributes !== false) {
+        out.push(`translate_attributes${body.translate_attributes === true ? "" : " (on by default)"} renames "service.name" to "service" on log and metric resources`);
+    }
+    const nest = body.nest_attributes;
+    if (typeof nest === "object" && nest !== null && nest.enabled === true) {
+        const include = strings(nest.include);
+        const exclude = strings(nest.exclude);
+        const nested = PROTECTED_RESOURCE_ATTRIBUTES.filter((k) => (include.length === 0 || include.some((p) => k.startsWith(p))) && !exclude.some((p) => k.startsWith(p)));
+        if (nested.length > 0)
+            out.push(`nest_attributes turns ${quoteAll(nested)} into nested maps`);
+    }
+    for (const pair of Array.isArray(body.aggregate_attributes) ? body.aggregate_attributes : []) {
+        const prefixes = strings(pair?.prefixes);
+        const moved = PROTECTED_RESOURCE_ATTRIBUTES.filter((k) => prefixes.some((p) => k.startsWith(p)));
+        if (moved.length > 0)
+            out.push(`aggregate_attributes prefixes ${quoteAll(prefixes)} move ${quoteAll(moved)} into one attribute`);
+    }
+    return out;
+}
+// Schema versions whose `all` changes rename a protected key, in semantic-conventions' schemas/1.37.0.
+const SCHEMA_RENAMES = [
+    { version: [1, 29, 0], from: "vcs.repository.ref.revision", to: "vcs.ref.head.revision" },
+    { version: [1, 27, 0], from: "deployment.environment", to: "deployment.environment.name" },
+];
+function schemaFindings(body) {
+    const out = [];
+    for (const target of strings(body.targets)) {
+        const m = /^https?:\/\/opentelemetry\.io\/schemas\/(\d+)\.(\d+)\.(\d+)$/.exec(target);
+        if (!m)
+            continue;
+        const v = [Number(m[1]), Number(m[2]), Number(m[3])];
+        const older = (r) => v[0] < r[0] || (v[0] === r[0] && (v[1] < r[1] || (v[1] === r[1] && v[2] < r[2])));
+        for (const rename of SCHEMA_RENAMES) {
+            if (older(rename.version))
+                out.push(`its target ${target} renames "${rename.to}" back to "${rename.from}" on data with a newer schema URL`);
+        }
+    }
+    return out;
+}
+function metricsTransformFindings(body) {
+    const out = [];
+    for (const t of Array.isArray(body.transforms) ? body.transforms : []) {
+        if (typeof t !== "object" || t === null || t.action !== "group")
+            continue;
+        const labels = t.group_resource_labels;
+        const keys = typeof labels === "object" && labels !== null ? Object.keys(labels).filter(isProtectedResourceAttribute) : [];
+        if (keys.length > 0)
+            out.push(`a group transform's group_resource_labels sets ${quoteAll(keys)} on the new resource`);
+    }
+    return out;
+}
+/** The key of a stanza `resource["<key>"]` field, or undefined. */
+function resourceField(field) {
+    if (typeof field !== "string")
+        return undefined;
+    const m = /^resource\[\s*["']([^"']*)["']\s*\]$/.exec(field.trim());
+    return m?.[1];
+}
+function logsTransformFindings(body) {
+    const out = [];
+    for (const raw of Array.isArray(body.operators) ? body.operators : []) {
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        const op = raw;
+        const type = String(op.type ?? "");
+        const touched = [
+            ...(type === "add" || type === "remove" ? [resourceField(op.field)] : []),
+            ...(type === "move" ? [resourceField(op.from), resourceField(op.to)] : []),
+            ...(type === "copy" ? [resourceField(op.to)] : []),
+        ].filter((k) => k !== undefined && isProtectedResourceAttribute(k));
+        if (touched.length > 0)
+            out.push(`its ${type} operator writes or removes ${quoteAll(touched)}`);
+        if (type === "retain") {
+            const kept = strings(op.fields).map(resourceField).filter((k) => k !== undefined);
+            const dropped = PROTECTED_RESOURCE_ATTRIBUTES.filter((k) => !kept.includes(k));
+            if (kept.length > 0 && dropped.length > 0)
+                out.push(`its retain operator keeps only the resource fields it lists, dropping ${quoteAll(dropped)}`);
+        }
+        if (op.parse_to === "resource")
+            out.push(`its ${type} operator parses into the resource, so a parsed key can replace any protected key`);
+    }
+    return out;
+}
+const FINDINGS = {
+    resource: resourceActionFindings,
+    transform: transformFindings,
+    resourcedetection: detectionFindings,
+    groupbyattrs: groupByAttrsFindings,
+    redaction: redactionFindings,
+    sumologic: sumologicFindings,
+    schema: schemaFindings,
+    metricstransform: metricsTransformFindings,
+    logstransform: logsTransformFindings,
+};
+/**
+ * OTEL118 over one collector config: each processor a pipeline lists that can
+ * remove or replace a protected resource attribute. Not part of
+ * `validateCollectorConfig`, because it applies only to a build that stamps
+ * the attribution: the post-synth check runs it when the context carries
+ * `telemetry`.
+ */
+export function attributionIssues(config) {
+    const pipelinesOf = new Map();
+    for (const [pipeline, body] of Object.entries(config.service?.pipelines ?? {})) {
+        for (const id of body?.processors ?? [])
+            pipelinesOf.set(String(id), [...(pipelinesOf.get(String(id)) ?? []), pipeline]);
+    }
+    const issues = [];
+    for (const [id, pipelines] of pipelinesOf) {
+        const raw = config.processors?.[id];
+        const body = typeof raw === "object" && raw !== null ? raw : {};
+        const type = canonicalTypeOf("processor", id);
+        const findings = Object.prototype.hasOwnProperty.call(FINDINGS, type) ? FINDINGS[type](body) : [];
+        for (const finding of findings) {
+            issues.push({
+                code: "OTEL118",
+                severity: "warning",
+                component: id,
+                message: `processor "${id}" (pipelines ${pipelines.join(", ")}): ${finding}. Chant's telemetry attribution stamps those resource attributes, and a span that loses them can't be joined to its member, release or declaration`,
+            });
+        }
+    }
+    return issues;
+}

package/dist/catalog.js

@@ -0,0 +1,42 @@
+/**
+ * The built-in entity catalog: every class this package exports, keyed by
+ * class name. It feeds the packaged registry (`dist/meta.json`), LSP
+ * completions and hover, and the docs.
+ */
+import { componentEntityType } from "./define.js";
+import * as components from "./components/index.js";
+import { PIPELINE_TYPE, SERVICE_TYPE } from "./pipeline.js";
+function isComponentClass(v) {
+    return typeof v === "function" && typeof v.definition === "object";
+}
+export const BUILTIN_CATALOG = [
+    ...Object.entries(components)
+        .filter((e) => isComponentClass(e[1]))
+        .map(([className, cls]) => ({
+        className,
+        entityType: componentEntityType(cls.definition.kind, cls.definition.type),
+        kind: cls.definition.kind,
+        type: cls.definition.type,
+        description: cls.definition.description ?? "",
+    })),
+    {
+        className: "Pipeline",
+        entityType: PIPELINE_TYPE,
+        kind: "pipeline",
+        description: "One pipeline under service.pipelines: receivers, then processors, then exporters, for one signal",
+    },
+    {
+        className: "Service",
+        entityType: SERVICE_TYPE,
+        kind: "service",
+        description: "service.extensions and service.telemetry",
+    },
+];
+/** The catalog as a chant lexicon registry, keyed by class name. */
+export function lexiconRegistry() {
+    const out = {};
+    for (const e of [...BUILTIN_CATALOG].sort((a, b) => a.className.localeCompare(b.className))) {
+        out[e.className] = { resourceType: e.entityType, kind: "resource", lexicon: "otel" };
+    }
+    return out;
+}

package/dist/codegen/docs-cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env tsx
+import { generateDocs } from "./docs.js";
+await generateDocs({ verbose: true });

package/dist/codegen/docs.js

@@ -0,0 +1,101 @@
+/**
+ * Documentation generation for the otel lexicon: the generated reference
+ * pages from the core docs pipeline, plus the authored pages in docs/pages/.
+ */
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { docsPipeline, writeDocsSite } from "@intentius/chant/codegen/docs";
+function serviceFromType(resourceType) {
+    const parts = resourceType.split("::");
+    return parts.length >= 2 ? parts[1] : "OTel";
+}
+const overview = `The otel lexicon types [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)
+config: receivers, processors, exporters, connectors, extensions and the
+pipelines that connect them. \`chant build\` emits one collector config file, the YAML
+\`otelcol --config\` reads as it is.
+
+\`\`\`ts
+import { OtlpReceiver, BatchProcessor, OtlpExporter, Pipeline } from "@intentius/chant-lexicon-otel";
+
+export const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" } } });
+export const batch = new BatchProcessor({ timeout: "5s" });
+export const backend = new OtlpExporter({ name: "backend", endpoint: "tempo.observability:4317" });
+
+export const traces = new Pipeline({
+  signal: "traces",
+  receivers: [otlp],
+  processors: [batch],
+  exporters: [backend],
+});
+\`\`\`
+
+The built-in component set is otlp, prometheus, hostmetrics, filelog,
+k8s_cluster and kubeletstats receivers; batch, memory_limiter, resource,
+attributes, k8sattributes, resourcedetection, filter, transform, redaction,
+tail_sampling, probabilistic_sampler and deltatocumulative processors; otlp, otlphttp, debug,
+prometheus, googlecloud and loadbalancing exporters; spanmetrics,
+servicegraph, routing, forward, count, sum and signaltometrics connectors; and the
+health_check, pprof, zpages and k8s_leader_elector extensions. \`genAiPipeline()\` is a preset for
+GenAI workloads: it removes prompt and completion content and derives agent
+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. \`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
+pipeline uses (OTEL103), a connector joining pipelines of signals it can't
+convert (OTEL112), pipelines feeding each other in a cycle (OTEL113), a
+connector id shared with a receiver or exporter (OTEL114), a \`routing\` route
+to a pipeline that doesn't receive from it (OTEL115), a connector
+splitting metrics by a per-request GenAI attribute such as
+\`gen_ai.conversation.id\` (OTEL116), two started components listening
+on the same address (OTEL117), and a literal credential in source (OTEL002)
+or in the config (OTEL120). Others report deprecated fields (OTEL119),
+credentials sent in plaintext (OTEL121), zpages or pprof off loopback
+(OTEL122), detailed debug output beside a backend (OTEL123), delivery and
+batching settings (OTEL124, OTEL125), and k8sattributes fields or
+resourcedetection detectors the collector doesn't know (OTEL126, OTEL127). In
+a build that stamps telemetry attribution, OTEL118 reports a processor that can
+drop or overwrite one of the attribution's resource attributes.
+`;
+const outputFormat = `The otel lexicon serializes every otel entity in a build into **one
+collector config file** in YAML, the file \`otelcol --config\` reads.
+
+- Sections come out as receivers, processors, exporters, connectors, extensions, service,
+  separated by a blank line. Empty sections are left out.
+- A component's id is its collector type, or \`type/name\` when its \`name\` is
+  set. The export name in source never appears in the output.
+- A list of scalars is written in flow style (\`receivers: [otlp]\`), any
+  other list in block style. Strings are plain where YAML reads them back
+  unchanged and double-quoted otherwise.
+- Declared extensions are enabled in declaration order unless a \`Service\`
+  lists \`extensions\`.
+- Each custom component adds a \`# chant:\` comment line above the config
+  naming its schema pin. Built-ins add none.
+- A collector config has no metadata channel, so no ownership marker is
+  stamped.
+`;
+export async function generateDocs(opts) {
+    const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    const config = {
+        name: "otel",
+        displayName: "OpenTelemetry Collector",
+        description: "Typed OpenTelemetry Collector config: receivers, processors, exporters and pipelines",
+        distDir: join(pkgDir, "dist"),
+        outDir: join(pkgDir, "docs"),
+        basePath: process.env.DOCS_BASE_PATH ?? "/chant/lexicons/otel/",
+        overview,
+        outputFormat,
+        serviceFromType,
+        srcDir: join(pkgDir, "src"),
+        examplesDir: join(pkgDir, "examples"),
+    };
+    const result = docsPipeline(config);
+    writeDocsSite(config, result);
+    if (opts?.verbose) {
+        console.error(`Generated ${result.pages.size} documentation pages`);
+    }
+}

package/dist/codegen/generate-cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for `npm run generate` in lexicon-otel.
+ */
+import { generate, writeGeneratedFiles } from "./generate.js";
+const result = await generate({ verbose: true });
+writeGeneratedFiles(result);

package/dist/codegen/generate.js

@@ -0,0 +1,43 @@
+/**
+ * The otel lexicon's "generation" step.
+ *
+ * There is no upstream schema to fetch: the collector defines each
+ * component's config as a Go struct, and publishes no machine-readable schema
+ * for the set as a whole. The built-in types are written by hand against the
+ * collector release named in `COLLECTOR_PIN` (src/define.ts), and this step
+ * derives the registry from them, so the packaged `dist/meta.json` can never
+ * disagree with the classes the package exports.
+ */
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { mkdirSync, writeFileSync } from "fs";
+import { BUILTIN_CATALOG, lexiconRegistry } from "../catalog.js";
+/** The packaged types entry re-exports the compiled declarations, which carry every config type. */
+const TYPES_DTS = `// The otel lexicon's entity classes and config types are hand-written in
+// src/ and compiled to dist/index.d.ts; this entry re-exports them.
+export * from "../index.js";
+`;
+export async function generate(opts) {
+    const registry = lexiconRegistry();
+    const lexiconJSON = `${JSON.stringify(registry, null, 2)}\n`;
+    const components = BUILTIN_CATALOG.filter((c) => c.type !== undefined).length;
+    if (opts?.verbose) {
+        console.error(`otel: ${components} built-in components, plus Pipeline and Service (${BUILTIN_CATALOG.length} entities)`);
+    }
+    return {
+        lexiconJSON,
+        typesDTS: TYPES_DTS,
+        indexTS: "",
+        resources: BUILTIN_CATALOG.length,
+        properties: 0,
+        enums: 0,
+        warnings: [],
+    };
+}
+/** Write the registry to src/generated/lexicon-otel.json, for tools that read it from there. */
+export function writeGeneratedFiles(result) {
+    const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    const dir = join(pkgDir, "src", "generated");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "lexicon-otel.json"), result.lexiconJSON);
+}

package/dist/codegen/package.js

@@ -0,0 +1,28 @@
+/**
+ * otel lexicon packaging, delegating to core's packagePipeline.
+ */
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import { packagePipeline, collectSkills, } from "@intentius/chant/codegen/package";
+import { generate } from "./generate.js";
+import { otelSkills } from "../skill-defs.js";
+// src/codegen/package.ts -> src/
+const srcDir = dirname(moduleSourceDir(import.meta.url));
+export async function packageLexicon(opts = {}) {
+    const pkgJson = JSON.parse(readFileSync(join(srcDir, "..", "package.json"), "utf-8"));
+    return packagePipeline({
+        generate: (genOpts) => generate({ verbose: genOpts.verbose, force: genOpts.force }),
+        buildManifest: () => ({
+            name: "otel",
+            version: pkgJson.version ?? "0.0.1",
+            chantVersion: ">=0.1.0",
+            namespace: "OTel",
+            intrinsics: [],
+            pseudoParameters: {},
+        }),
+        srcDir,
+        collectSkills: () => collectSkills(otelSkills()),
+        version: pkgJson.version ?? "0.0.1",
+    }, opts);
+}