@intentius/chant-lexicon-otel 0.124.31 → 0.124.32

package/dist/op/activities/otelcol.js

@@ -0,0 +1,173 @@
+/**
+ * `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.js";
+import { COMPONENT_KINDS, SECTION_OF, canonicalComponentType, parseComponentId } from "../../model.js";
+import { defaultExec } from "./exec.js";
+/** The binary a step runs. */
+export function otelcolBin(explicit, env = process.env) {
+    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) {
+    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) {
+    const m = /version\s+v?(\d+\.\d+\.\d+[^\s]*)/i.exec(output);
+    return m ? `v${m[1]}` : undefined;
+}
+function readConfig(path, cwd) {
+    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;
+}
+async function binaryVersion(exec, bin) {
+    const r = await exec(bin, ["--version"], { timeoutMs: 30000 });
+    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) {
+    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: 120000 });
+    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 = {
+    receivers: "receiver",
+    processors: "processor",
+    exporters: "exporter",
+    connectors: "connector",
+    extensions: "extension",
+};
+/**
+ * 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) {
+    let doc;
+    try {
+        doc = load(text);
+    }
+    catch (err) {
+        throw new Error(`otelcol components printed output that is not YAML: ${err.message}`);
+    }
+    if (!doc || typeof doc !== "object" || Array.isArray(doc))
+        throw new Error("otelcol components printed no YAML mapping");
+    const d = doc;
+    const components = Object.fromEntries(COMPONENT_KINDS.map((k) => [k, new Set()]));
+    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 = Array.isArray(value)
+            ? value.map((e) => (e && typeof e === "object" ? (e.name ?? e.type) : e))
+            : typeof value === "object"
+                ? Object.keys(value)
+                : [];
+        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;
+    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) {
+    const out = Object.fromEntries(COMPONENT_KINDS.map((k) => [k, []]));
+    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);
+    }
+    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, list) {
+    const missing = [];
+    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) {
+    const exec = args._exec ?? defaultExec;
+    const bin = otelcolBin(args.bin);
+    const config = readConfig(args.config, process.cwd());
+    const r = await exec(bin, ["components"], { timeoutMs: 60000 });
+    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/dist/op/activity-contracts.js

@@ -0,0 +1,64 @@
+/**
+ * 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/dist/op/audit-op.js

@@ -0,0 +1,33 @@
+/**
+ * `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 } from "@intentius/chant/op";
+import { collectorAudit } from "./builders.js";
+export function CollectorAuditOp(config) {
+    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" } } : {}),
+        phases: [phase("Audit", [{ ...step, outcomeAttribute: { name: "Findings", from: "findings" } }])],
+    });
+    return { op };
+}

package/dist/op/builders.js

@@ -0,0 +1,38 @@
+/**
+ * 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 } from "@intentius/chant/op";
+function step(fn, defaultProfile) {
+    return (args) => {
+        const { args: rest, profile, id } = takeProfileAndId(args);
+        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("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("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("collectorHealthObserve", "fastIdempotent");
+/**
+ * Audit the lexicon's pins against upstream releases (the step of
+ * `CollectorAuditOp`). Defaults to the `fastIdempotent` profile.
+ */
+export const collectorAudit = (args = {}) => step("collectorAudit", "fastIdempotent")(args);

package/dist/package-cli.js

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

package/dist/pipeline.js

@@ -0,0 +1,31 @@
+/**
+ * `Pipeline` and `Service`: the `service:` half of a collector config.
+ *
+ * A pipeline names its components either by the declared entity, which
+ * keeps the reference checked by TypeScript, or by id string (`otlp/backend`)
+ * for a component declared somewhere chant can't see. OTEL101 catches a
+ * string that names nothing declared.
+ *
+ * A connector goes in `exporters` of the pipeline that feeds it and in
+ * `receivers` of the pipeline it feeds. The same entity on both sides is what
+ * joins the two pipelines.
+ */
+import { createResource } from "@intentius/chant/runtime";
+import { componentId } from "./model.js";
+export const PIPELINE_TYPE = "OTel::Pipeline";
+export const SERVICE_TYPE = "OTel::Service";
+const PipelineBase = createResource(PIPELINE_TYPE, "otel", {});
+/** One entry under `service.pipelines`. */
+export const Pipeline = function (props) {
+    PipelineBase.call(this, props);
+    Object.defineProperty(this, "pipelineId", { value: componentId(props.signal, props.name), enumerable: false });
+};
+Object.defineProperty(Pipeline, "name", { value: "Pipeline" });
+/** `service.extensions` and `service.telemetry`. Optional; declare at most one. */
+export const Service = createResource(SERVICE_TYPE, "otel", {});
+export function isPipelineEntity(value) {
+    return typeof value === "object" && value !== null && value.entityType === PIPELINE_TYPE;
+}
+export function isServiceEntity(value) {
+    return typeof value === "object" && value !== null && value.entityType === SERVICE_TYPE;
+}

package/dist/platform.js

@@ -0,0 +1,144 @@
+/**
+ * What the platform composites share: a default collector config, the image
+ * that runs it, where the config is mounted, and the ports a rendered config
+ * listens on.
+ *
+ * The docker, k8s and fly collector composites build on this. A composite
+ * declares its config with this lexicon, renders it with `collectorYaml`, and
+ * reads the listening ports back from the built config, so the ports it
+ * publishes follow whatever config the caller declared.
+ */
+import { COLLECTOR_PIN } from "./define.js";
+import { OtlpReceiver } from "./components/receivers.js";
+import { BatchProcessor, MemoryLimiterProcessor } from "./components/processors.js";
+import { DebugExporter } from "./components/exporters.js";
+import { HealthCheckExtension } from "./components/extensions.js";
+import { Pipeline } from "./pipeline.js";
+import { SIGNALS, parseComponentId } from "./model.js";
+import { listenerPaths } from "./validate-config.js";
+/** The contrib collector image at the version the built-in components are typed against. */
+export const COLLECTOR_IMAGE = `otel/opentelemetry-collector-contrib:${COLLECTOR_PIN.version.replace(/^v/, "")}`;
+/** Where the platform composites mount the rendered config inside the container. */
+export const COLLECTOR_CONFIG_PATH = "/etc/otel/config.yaml";
+/** The receiver and processors `otlpCollector()` and `OtlpCollector` start from. */
+function collectorBase() {
+    const otlp = new OtlpReceiver({
+        protocols: {
+            grpc: { endpoint: "0.0.0.0:4317" },
+            http: { endpoint: "0.0.0.0:4318" },
+        },
+    });
+    const memoryLimiter = new MemoryLimiterProcessor({
+        check_interval: "1s",
+        limit_percentage: 80,
+        spike_limit_percentage: 20,
+    });
+    const batch = new BatchProcessor({});
+    return { otlp, memoryLimiter, batch };
+}
+/** `otlpCollector()`'s config by part, for the `OtlpCollector` composite. A signal listed twice gets one pipeline. */
+export function otlpCollectorParts(options = {}) {
+    const { exporters = [new DebugExporter({ verbosity: "basic" })], signals = [...SIGNALS], healthCheck = true } = options;
+    const { otlp, memoryLimiter, batch } = collectorBase();
+    const pipelines = {};
+    for (const signal of signals) {
+        pipelines[signal] ?? (pipelines[signal] = new Pipeline({ signal, receivers: [otlp], processors: [memoryLimiter, batch], exporters }));
+    }
+    return {
+        otlp,
+        memoryLimiter,
+        batch,
+        exporters,
+        ...(healthCheck ? { health: new HealthCheckExtension({ endpoint: "0.0.0.0:13133" }) } : {}),
+        pipelines,
+    };
+}
+/**
+ * The entities of a small OTLP collector: an `otlp` receiver on 4317 (gRPC)
+ * and 4318 (HTTP), `memory_limiter` then `batch`, the given exporters, and a
+ * `health_check` extension. Pass the result to `collectorYaml`.
+ */
+export function otlpCollector(options = {}) {
+    const { exporters = [new DebugExporter({ verbosity: "basic" })], signals = [...SIGNALS], healthCheck = true } = options;
+    const { otlp, memoryLimiter, batch } = collectorBase();
+    const entities = [otlp, memoryLimiter, batch, ...exporters];
+    if (healthCheck)
+        entities.push(new HealthCheckExtension({ endpoint: "0.0.0.0:13133" }));
+    for (const signal of signals) {
+        entities.push(new Pipeline({ signal, receivers: [otlp], processors: [memoryLimiter, batch], exporters }));
+    }
+    return entities;
+}
+function portOf(endpoint) {
+    if (typeof endpoint !== "string")
+        return undefined;
+    const m = endpoint.match(/^(.*):(\d+)$/);
+    if (!m)
+        return undefined;
+    return { host: m[1], port: Number(m[2]) };
+}
+function portName(parts) {
+    const name = parts
+        .join("-")
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    return name.slice(0, 15).replace(/-$/, "");
+}
+/** The value at a key path, if every key on the way is there. */
+function valueAt(value, path) {
+    let cur = value;
+    for (const key of path) {
+        if (!cur || typeof cur !== "object" || Array.isArray(cur))
+            return undefined;
+        cur = cur[key];
+    }
+    return cur;
+}
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+/**
+ * The ports a built collector config listens on: the address every receiver
+ * and exporter that listens sets (the types OTEL117 knows: otlp, jaeger,
+ * statsd, syslog, the `prometheus` exporter's scrape endpoint and the rest),
+ * named after the component and the key above the address (`otlp-grpc`,
+ * `syslog-udp`), and the `health_check` port if the service enables it. A
+ * component whose `endpoint` is a server it connects to, such as
+ * kubeletstats' kubelet, adds no port, and neither does a type the table
+ * doesn't list. A UDP listener gets `protocol: "UDP"`.
+ */
+export function collectorEndpoints(config) {
+    const ports = [];
+    const seen = new Set();
+    const sections = [
+        ["receiver", config.receivers],
+        ["exporter", config.exporters],
+    ];
+    for (const [kind, section] of sections) {
+        for (const [id, body] of Object.entries(section ?? {})) {
+            const parsed = parseComponentId(id);
+            const base = parsed ? [parsed.type, ...(parsed.name ? [parsed.name] : [])] : [id];
+            for (const { path, transport } of listenerPaths(kind, parsed?.type ?? id, body)) {
+                const p = portOf(valueAt(body, path));
+                if (!p || seen.has(`${p.port}/${transport}`))
+                    continue;
+                seen.add(`${p.port}/${transport}`);
+                const protocol = path.slice(0, -1).filter((k) => k !== "protocols");
+                ports.push({ name: portName([...base, ...protocol]), port: p.port, ...(transport === "udp" ? { protocol: "UDP" } : {}) });
+            }
+        }
+    }
+    let healthCheck;
+    const enabled = config.service?.extensions ?? [];
+    for (const id of enabled) {
+        if (parseComponentId(id)?.type !== "health_check")
+            continue;
+        const ext = (config.extensions?.[id] ?? {});
+        const p = portOf(ext.endpoint ?? "localhost:13133");
+        if (!p || LOCAL_HOSTS.has(p.host))
+            continue;
+        healthCheck = { port: p.port, path: typeof ext.path === "string" ? ext.path : "/" };
+        break;
+    }
+    return { ports, ...(healthCheck ? { healthCheck } : {}) };
+}

package/dist/plugin.js

@@ -0,0 +1,126 @@
+import { createDiffTool } from "@intentius/chant/lexicon-plugin-helpers";
+import { otelSerializer } from "./serializer.js";
+import { rules } from "./lint/rules/index.js";
+import { postSynthChecks } from "./lint/post-synth/index.js";
+import { otelAuditCatalog } from "./lint/audit-catalog.js";
+import { completions } from "./lsp/completions.js";
+import { hover } from "./lsp/hover.js";
+import { detectTemplate } from "./detect.js";
+import { OtelCollectorParser } from "./import/parser.js";
+import { OtelCollectorGenerator } from "./import/generator.js";
+import { collectorConfigImporter } from "./import/embedded.js";
+import { otelSkills } from "./skill-defs.js";
+import { BUILTIN_CATALOG } from "./catalog.js";
+import { compositeCatalog } from "./composites/catalog.js";
+import { DEFAULT_TEMPLATE, GENAI_TEMPLATE, K8S_AGENT_TEMPLATE } from "./init-templates.js";
+import { COLLECTOR_PIN } from "./define.js";
+import { collectorTopologyOf } from "./topology.js";
+const catalogResource = {
+    uri: "otel:resource-catalog",
+    name: "OpenTelemetry Collector component catalog",
+    description: "The collector components, pipelines and service block this lexicon types, with the collector release they follow",
+    mimeType: "application/json",
+    async handler() {
+        return JSON.stringify({ pin: COLLECTOR_PIN, entities: BUILTIN_CATALOG });
+    },
+};
+/**
+ * OpenTelemetry Collector lexicon plugin.
+ *
+ * Typed receivers, processors, exporters, connectors and extensions, pipelines and the
+ * service block, serialized to one collector config file. A component chant
+ * doesn't ship comes in through `defineComponent`, and is serialized and
+ * checked the same way as the built-ins.
+ */
+export const otelPlugin = {
+    name: "otel",
+    serializer: otelSerializer,
+    // ── Required lifecycle methods ────────────────────────────────
+    async generate(options) {
+        const { generate, writeGeneratedFiles } = await import("./codegen/generate.js");
+        writeGeneratedFiles(await generate(options));
+    },
+    async validate(_options) {
+        const { validate } = await import("./validate.js");
+        const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+        printValidationResult(await validate());
+    },
+    async coverage(_options) {
+        const components = BUILTIN_CATALOG.filter((c) => c.type !== undefined);
+        const byKind = new Map();
+        for (const c of components)
+            byKind.set(c.kind, [...(byKind.get(c.kind) ?? []), c.type]);
+        console.error(`otel: ${components.length} built-in components, typed against ${COLLECTOR_PIN.source} ${COLLECTOR_PIN.version}`);
+        for (const [kind, types] of byKind)
+            console.error(`  ${kind}s: ${types.join(", ")}`);
+        console.error("  anything else: defineComponent (see docs: custom components)");
+    },
+    async package(options) {
+        const { packageLexicon } = await import("./codegen/package.js");
+        const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+        const { join, dirname } = await import("path");
+        const { fileURLToPath } = await import("url");
+        const { spec, stats } = await packageLexicon(options);
+        const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+        writeBundleSpec(spec, join(pkgDir, "dist"));
+        console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+    },
+    // ── Optional extensions ────────────────────────────────────
+    lintRules() {
+        return rules;
+    },
+    // Where this project's telemetry goes, for `chant workspace graph` (#2559).
+    // A project with no collector pipeline and no component reports nothing.
+    graphMeta(entities) {
+        const topology = collectorTopologyOf(entities.values());
+        if (topology.pipelines.length === 0 && topology.components.length === 0)
+            return undefined;
+        return { collector: topology };
+    },
+    postSynthChecks() {
+        return postSynthChecks;
+    },
+    auditCatalog() {
+        return otelAuditCatalog;
+    },
+    skills: otelSkills,
+    composites() {
+        return compositeCatalog;
+    },
+    mcpTools() {
+        return [createDiffTool(otelSerializer, "Compare current collector config output against the previous build", "otel")];
+    },
+    mcpResources() {
+        return [catalogResource];
+    },
+    // `chant init --lexicon otel [--template k8s-agent|genai]`; see ./init-templates.ts.
+    initTemplates(template) {
+        if (template === "k8s-agent")
+            return K8S_AGENT_TEMPLATE;
+        if (template === "genai")
+            return GENAI_TEMPLATE;
+        return DEFAULT_TEMPLATE;
+    },
+    detectTemplate(data) {
+        return detectTemplate(data);
+    },
+    templateParser() {
+        return new OtelCollectorParser();
+    },
+    templateGenerator() {
+        return new OtelCollectorGenerator();
+    },
+    embeddedImporters() {
+        return [collectorConfigImporter];
+    },
+    completionProvider(ctx) {
+        return completions(ctx);
+    },
+    hoverProvider(ctx) {
+        return hover(ctx);
+    },
+    async docs(options) {
+        const { generateDocs } = await import("./codegen/docs.js");
+        return generateDocs(options);
+    },
+};