@intentius/chant-lexicon-otel 0.81.0

package/dist/platform.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 type { Declarable } from "@intentius/chant/declarable";
+import { type OTelComponent } from "./define.js";
+import { type CollectorConfig, type Signal } from "./model.js";
+/** The contrib collector image at the version the built-in components are typed against. */
+export declare const COLLECTOR_IMAGE: string;
+/** Where the platform composites mount the rendered config inside the container. */
+export declare const COLLECTOR_CONFIG_PATH = "/etc/otel/config.yaml";
+export interface OtlpCollectorOptions {
+    /** Where telemetry goes. Default: one `debug` exporter at `basic` verbosity. */
+    exporters?: OTelComponent<"exporter", string, any>[];
+    /** Which signals get a pipeline. Default: traces, metrics and logs. */
+    signals?: Signal[];
+    /** Serve `health_check` on 0.0.0.0:13133. Default: true. */
+    healthCheck?: boolean;
+}
+/**
+ * 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 declare function otlpCollector(options?: OtlpCollectorOptions): Declarable[];
+/** A port a collector config listens on. */
+export interface CollectorPort {
+    /** A name usable as a k8s port name: lowercase, `-` separated, at most 15 characters. */
+    name: string;
+    port: number;
+}
+export interface CollectorEndpoints {
+    /** Ports the receivers listen on, in config order, one entry per port. */
+    ports: CollectorPort[];
+    /**
+     * The `health_check` extension, when the service enables one and it listens
+     * on an address other than localhost. A probe from outside the container
+     * cannot reach a localhost listener.
+     */
+    healthCheck?: {
+        port: number;
+        path: string;
+    };
+}
+/**
+ * The ports a built collector config listens on: every receiver `endpoint`,
+ * named after the receiver and the protocol key above it (`otlp-grpc`,
+ * `otlp-http`), and the `health_check` port if the service enables it.
+ */
+export declare function collectorEndpoints(config: CollectorConfig): CollectorEndpoints;
+//# sourceMappingURL=platform.d.ts.map

package/dist/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAM7D,OAAO,EAA6B,KAAK,eAAe,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAEvF,4FAA4F;AAC5F,eAAO,MAAM,eAAe,QAAoF,CAAC;AAEjH,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D,MAAM,WAAW,oBAAoB;IACnC,gFAAgF;IAChF,SAAS,CAAC,EAAE,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;IACrD,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,UAAU,EAAE,CAoB9E;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB;;;;OAIG;IACH,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C;AA8BD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,kBAAkB,CA6B9E"}

package/dist/plugin.d.ts

@@ -0,0 +1,11 @@
+import type { LexiconPlugin } from "@intentius/chant/lexicon";
+/**
+ * OpenTelemetry Collector lexicon plugin.
+ *
+ * Typed receivers, processors, exporters 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 declare const otelPlugin: LexiconPlugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +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"}

package/dist/rules/component-id-syntax.ts

@@ -0,0 +1,68 @@
+import * as ts from "typescript";
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import { isComponentId } from "../../model";
+import { calleeName, COMPONENT_CLASS, literalText, position, propertyName } from "./otel-ast";
+
+/**
+ * OTEL001: a component id or instance name the collector can't parse.
+ *
+ * A pipeline may name a component by id string (`"otlp/backend"`), and every
+ * component takes an instance `name`. Both end up in the collector's
+ * `type[/name]` syntax, where a space, an empty name or a stray `/` is a
+ * config error at collector start. This catches the literal cases in source,
+ * before a build: a string in a `Pipeline`'s receivers, processors or
+ * exporters that isn't `type` or `type/name`, and a component `name` that is
+ * empty, contains whitespace or starts with `/`.
+ */
+export const componentIdSyntaxRule: LintRule = {
+  id: "OTEL001",
+  severity: "error",
+  category: "correctness",
+  description: "Collector component id or instance name is not valid type[/name] syntax",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const source = context.sourceFile;
+
+    const flag = (node: ts.Node, message: string) => {
+      diagnostics.push({ ruleId: "OTEL001", severity: "error", message, file: context.filePath, ...position(source, node) });
+    };
+
+    const visit = (node: ts.Node) => {
+      if (ts.isNewExpression(node) || ts.isCallExpression(node)) {
+        const name = calleeName(node);
+        const arg = node.arguments?.[0];
+        if (name && arg && ts.isObjectLiteralExpression(arg)) {
+          if (name === "Pipeline") {
+            for (const prop of arg.properties) {
+              const key = propertyName(prop);
+              if (key !== "receivers" && key !== "processors" && key !== "exporters") continue;
+              const init = (prop as ts.PropertyAssignment).initializer;
+              if (!ts.isArrayLiteralExpression(init)) continue;
+              for (const el of init.elements) {
+                const text = literalText(el as ts.Expression);
+                if (text !== undefined && !isComponentId(text)) {
+                  flag(el, `"${text}" in ${key} is not a collector component id; write type or type/name, e.g. "otlp" or "otlp/backend"`);
+                }
+              }
+            }
+          }
+          if (name === "Pipeline" || COMPONENT_CLASS.test(name)) {
+            for (const prop of arg.properties) {
+              if (propertyName(prop) !== "name") continue;
+              const text = literalText((prop as ts.PropertyAssignment).initializer);
+              if (text === undefined) continue;
+              if (text === "" || /\s/.test(text) || text.startsWith("/")) {
+                flag(prop, `instance name "${text}" makes an invalid id; a name is non-empty, has no whitespace and does not start with "/"`);
+              }
+            }
+          }
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+
+    visit(source);
+    return diagnostics;
+  },
+};

package/dist/rules/literal-credential.ts

@@ -0,0 +1,62 @@
+import * as ts from "typescript";
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import { calleeName, COMPONENT_CLASS, literalText, position, propertyName } from "./otel-ast";
+
+/** Keys whose value is a credential. `*_file` keys name a path, which is fine. */
+const SECRET_KEY = /(authorization|api[-_]?key|password|passwd|secret|token|key_pem|x-honeycomb-team)/i;
+
+/**
+ * OTEL002: a credential written as a literal in a component's config.
+ *
+ * Exporters authenticate with headers (`authorization`, `api-key`, vendor
+ * headers) or keys (`api_key`, `password`, `key_pem`). A literal value there
+ * is a secret in the repository and in the emitted YAML. The collector reads
+ * `${env:NAME}` and `${file:/path}` at start-up, so the declaration never
+ * needs the value itself. Any string containing `${` is treated as such a
+ * reference, and keys ending in `_file` name a path and are left alone.
+ */
+export const literalCredentialRule: LintRule = {
+  id: "OTEL002",
+  severity: "error",
+  category: "security",
+  description: "Collector credential declared as a literal instead of ${env:...}",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const source = context.sourceFile;
+
+    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),
+        });
+      }
+    };
+
+    const visit = (node: ts.Node) => {
+      if (ts.isNewExpression(node) || ts.isCallExpression(node)) {
+        const name = calleeName(node);
+        const arg = node.arguments?.[0];
+        if (name && COMPONENT_CLASS.test(name) && arg && ts.isObjectLiteralExpression(arg)) scan(arg);
+      }
+      ts.forEachChild(node, visit);
+    };
+
+    visit(source);
+    return diagnostics;
+  },
+};

package/dist/rules/otel-ast.ts

@@ -0,0 +1,30 @@
+import * as ts from "typescript";
+
+/** The constructor name of a `new X(...)` or `X(...)` expression, if it is a plain or dotted name. */
+export function calleeName(node: ts.CallExpression | ts.NewExpression): string | undefined {
+  const callee = node.expression;
+  if (ts.isIdentifier(callee)) return callee.text;
+  if (ts.isPropertyAccessExpression(callee)) return callee.name.text;
+  return undefined;
+}
+
+/** Built-in and custom collector component classes follow this naming, e.g. `OtlpExporter`. */
+export const COMPONENT_CLASS = /(Receiver|Processor|Exporter|Extension)$/;
+
+/** A property's key as text, for identifier and string-literal keys. */
+export function propertyName(prop: ts.ObjectLiteralElementLike): string | undefined {
+  if (!ts.isPropertyAssignment(prop)) return undefined;
+  if (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) return prop.name.text;
+  return undefined;
+}
+
+/** The text of a string literal or substitution-free template, else undefined. */
+export function literalText(node: ts.Expression): string | undefined {
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+  return undefined;
+}
+
+export function position(source: ts.SourceFile, node: ts.Node): { line: number; column: number } {
+  const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
+  return { line: line + 1, column: character + 1 };
+}

package/dist/rules/otel-helpers.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared plumbing for the otel post-synth checks: find the collector configs
+ * in a build's output, and run the plain-function checks over them.
+ */
+
+import type { PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import type { SerializerResult } from "@intentius/chant/serializer";
+import { loadAll } from "js-yaml";
+import type { Declarable } from "@intentius/chant/declarable";
+import { looksLikeCollectorConfig, type CollectorConfig } from "../../model";
+import { validateCollectorConfig, validateCollectorEntities, type CollectorIssueCode, type CollectorIssue } from "../../validate-config";
+
+/**
+ * Every collector config in the output: the otel lexicon's own, and any YAML
+ * document shaped like one. Parsed with js-yaml rather than `ctx.docs`,
+ * because collector configs are written with flow lists (`[otlp, batch]`)
+ * that core's small YAML reader keeps as strings.
+ */
+export function collectorConfigs(ctx: PostSynthContext): Array<{ source: string; config: CollectorConfig }> {
+  const out: Array<{ source: string; config: CollectorConfig }> = [];
+  for (const [lexicon, output] of ctx.outputs) {
+    const texts: Array<[string, string]> =
+      typeof output === "string"
+        ? [[lexicon, output]]
+        : [[lexicon, (output as SerializerResult).primary], ...Object.entries((output as SerializerResult).files ?? {})];
+    for (const [source, text] of texts) {
+      if (!text) continue;
+      let docs: unknown[];
+      try {
+        docs = loadAll(text);
+      } catch {
+        continue; // not YAML, or not ours
+      }
+      for (const doc of docs) {
+        if (typeof doc !== "object" || doc === null || Array.isArray(doc)) continue;
+        if ((lexicon === "otel" && source === lexicon) || looksLikeCollectorConfig(doc)) {
+          out.push({ source, config: doc as CollectorConfig });
+        }
+      }
+    }
+  }
+  return out;
+}
+
+function toDiagnostic(issue: CollectorIssue, source?: string): PostSynthDiagnostic {
+  return {
+    checkId: issue.code,
+    severity: issue.severity,
+    message: source && source !== "otel" ? `${source}: ${issue.message}` : issue.message,
+    ...(issue.component ? { entity: issue.component } : issue.pipeline ? { entity: issue.pipeline } : {}),
+    lexicon: "otel",
+  };
+}
+
+/** Diagnostics for one config-level code (OTEL101-OTEL106) across every collector config in the output. */
+export function configDiagnostics(ctx: PostSynthContext, code: CollectorIssueCode): PostSynthDiagnostic[] {
+  return collectorConfigs(ctx).flatMap(({ source, config }) =>
+    validateCollectorConfig(config)
+      .filter((i) => i.code === code)
+      .map((i) => toDiagnostic(i, source)),
+  );
+}
+
+/** Diagnostics for one entity-level code (OTEL107-OTEL109) over the build's otel entities. */
+export function entityDiagnostics(ctx: PostSynthContext, code: CollectorIssueCode): PostSynthDiagnostic[] {
+  const otel: Declarable[] = [...(ctx.entities?.values() ?? [])].filter((e) => e?.lexicon === "otel");
+  return validateCollectorEntities(otel)
+    .filter((i) => i.code === code)
+    .map((i) => toDiagnostic(i));
+}

package/dist/rules/otel101.ts

@@ -0,0 +1,17 @@
+/**
+ * OTEL101: A pipeline uses a receiver, processor or exporter that is not declared
+ *
+ * The collector refuses to start on this. Typed entity references cannot go wrong this way, so it mostly catches id strings (`"otlp/backend"`) and hand-edited or parsed configs. A connector id is accepted in receivers and exporters.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { configDiagnostics } from "./otel-helpers";
+
+export const otel101: PostSynthCheck = {
+  id: "OTEL101",
+  description: "A pipeline uses a receiver, processor or exporter that is not declared",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return configDiagnostics(ctx, "OTEL101");
+  },
+};

package/dist/rules/otel102.ts

@@ -0,0 +1,17 @@
+/**
+ * OTEL102: A pipeline has no receivers or no exporters
+ *
+ * A pipeline with no receivers takes in nothing, and one with no exporters sends what it takes in nowhere. The collector rejects both at start.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { configDiagnostics } from "./otel-helpers";
+
+export const otel102: PostSynthCheck = {
+  id: "OTEL102",
+  description: "A pipeline has no receivers or no exporters",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return configDiagnostics(ctx, "OTEL102");
+  },
+};

package/dist/rules/otel103.ts

@@ -0,0 +1,17 @@
+/**
+ * OTEL103: A declared component is never used
+ *
+ * A receiver, processor or exporter no pipeline lists, or an extension missing from service.extensions, is ignored by the collector. Usually it means a pipeline was meant to list it. A warning, since the config still runs.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { configDiagnostics } from "./otel-helpers";
+
+export const otel103: PostSynthCheck = {
+  id: "OTEL103",
+  description: "A declared component is never used",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return configDiagnostics(ctx, "OTEL103");
+  },
+};

package/dist/rules/otel104.ts

@@ -0,0 +1,17 @@
+/**
+ * OTEL104: service.extensions enables an extension that is not declared
+ *
+ * The collector refuses to start when service.extensions names an id with no entry under extensions.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { configDiagnostics } from "./otel-helpers";
+
+export const otel104: PostSynthCheck = {
+  id: "OTEL104",
+  description: "service.extensions enables an extension that is not declared",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return configDiagnostics(ctx, "OTEL104");
+  },
+};

package/dist/rules/otel105.ts

@@ -0,0 +1,17 @@
+/**
+ * OTEL105: memory_limiter is not the first processor in a pipeline
+ *
+ * The collector's own guidance puts memory_limiter first, so it can refuse data before any other processor buffers it. Later in the chain it limits too late to protect the process.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { configDiagnostics } from "./otel-helpers";
+
+export const otel105: PostSynthCheck = {
+  id: "OTEL105",
+  description: "memory_limiter is not the first processor in a pipeline",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return configDiagnostics(ctx, "OTEL105");
+  },
+};

package/dist/rules/otel106.ts

@@ -0,0 +1,17 @@
+/**
+ * OTEL106: A pipeline id or component reference is not valid collector syntax
+ *
+ * A pipeline id is a signal (traces, metrics, logs) optionally followed by /name, and every reference is type or type/name. Anything else is a config error at collector start.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { configDiagnostics } from "./otel-helpers";
+
+export const otel106: PostSynthCheck = {
+  id: "OTEL106",
+  description: "A pipeline id or component reference is not valid collector syntax",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return configDiagnostics(ctx, "OTEL106");
+  },
+};

package/dist/rules/otel107.ts

@@ -0,0 +1,17 @@
+/**
+ * OTEL107: A component's config breaks its definition's rules
+ *
+ * Each component definition, built-in or custom, can check its own config beyond what the TypeScript type says: memory_limiter needs a limit, filelog needs an include, and so on. A custom component supplies its checks through defineComponent's validate.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { entityDiagnostics } from "./otel-helpers";
+
+export const otel107: PostSynthCheck = {
+  id: "OTEL107",
+  description: "A component's config breaks its definition's rules",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return entityDiagnostics(ctx, "OTEL107");
+  },
+};

package/dist/rules/otel108.ts

@@ -0,0 +1,17 @@
+/**
+ * OTEL108: Two components or two pipelines declare the same id
+ *
+ * The collector config is keyed by id, so the second declaration would silently replace the first. The serializer keeps the first and this check fails the build.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { entityDiagnostics } from "./otel-helpers";
+
+export const otel108: PostSynthCheck = {
+  id: "OTEL108",
+  description: "Two components or two pipelines declare the same id",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return entityDiagnostics(ctx, "OTEL108");
+  },
+};

package/dist/rules/otel109.ts

@@ -0,0 +1,17 @@
+/**
+ * OTEL109: A custom component has no schema pin
+ *
+ * defineComponent requires a pin naming the source and version its config type follows, so a reader can tell which schema the component was checked against. This check fails a build whose custom component lost its pin, for instance through an untyped call.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { entityDiagnostics } from "./otel-helpers";
+
+export const otel109: PostSynthCheck = {
+  id: "OTEL109",
+  description: "A custom component has no schema pin",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return entityDiagnostics(ctx, "OTEL109");
+  },
+};

package/dist/serializer.d.ts

@@ -0,0 +1,16 @@
+/**
+ * OpenTelemetry Collector serializer.
+ *
+ * Emits one collector config file from every otel entity in the build: the
+ * YAML `otelcol --config` reads as it is. Section order is fixed (receivers,
+ * processors, exporters, extensions, service); components and pipelines keep
+ * the order they are declared in, and each component's config keeps the key
+ * order it was written in, since collector docs and diffs read that way.
+ *
+ * A collector config has no metadata channel, so there is no ownership marker
+ * to stamp. A custom component's schema pin is written as a `# chant:` comment
+ * line above the config (see `define.ts`).
+ */
+import type { Serializer } from "@intentius/chant/serializer";
+export declare const otelSerializer: Serializer;
+//# sourceMappingURL=serializer.d.ts.map

package/dist/serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAoB,MAAM,6BAA6B,CAAC;AAKhF,eAAO,MAAM,cAAc,EAAE,UAU5B,CAAC"}

package/dist/skill-defs.d.ts

@@ -0,0 +1,3 @@
+/** The otel lexicon's AI skills, read from src/skills/. */
+export declare const otelSkills: () => import("packages/core/src").SkillDefinition[];
+//# sourceMappingURL=skill-defs.d.ts.map

package/dist/skill-defs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-defs.d.ts","sourceRoot":"","sources":["../src/skill-defs.ts"],"names":[],"mappings":"AAEA,2DAA2D;AAC3D,eAAO,MAAM,UAAU,qDAgCrB,CAAC"}

package/dist/skills/chant-otel-custom-components.md

@@ -0,0 +1,51 @@
+---
+skill: chant-otel-custom-components
+description: Add a collector component chant doesn't ship (a vendor exporter, an in-house processor) with defineComponent, and pin its schema
+user-invocable: true
+---
+
+# Custom collector components
+
+chant ships a core set of collector components. For anything else, define the component once and use it like a built-in.
+
+```ts
+import { defineComponent, Pipeline, OtlpReceiver } from "@intentius/chant-lexicon-otel";
+
+export interface DatadogExporterConfig {
+  api: { key: string; site?: string };
+  traces?: { span_name_as_resource_name?: boolean };
+}
+
+export const DatadogExporter = defineComponent<DatadogExporterConfig>()({
+  kind: "exporter",
+  type: "datadog",
+  pin: {
+    source: "github.com/open-telemetry/opentelemetry-collector-contrib/exporter/datadogexporter",
+    version: "v0.130.0",
+  },
+  validate: (c) => (c.api.key.includes("${") ? [] : ["api.key must come from ${env:...}"]),
+  endpoints: (c) => [`https://api.${c.api.site ?? "datadoghq.com"}`],
+});
+
+export const dd = new DatadogExporter({ name: "eu", api: { key: "${env:DD_API_KEY}", site: "datadoghq.eu" } });
+export const traces = new Pipeline({ signal: "traces", receivers: [new OtlpReceiver({ protocols: { grpc: {} } })], exporters: [dd] });
+```
+
+## What you supply
+
+| Field | Required | Meaning |
+|---|---|---|
+| `kind` | yes | receiver, processor, exporter or extension |
+| `type` | yes | the collector type, the part of the id before `/` |
+| `pin` | yes | `{ source, version, digest? }`: where the config schema comes from and which release the type follows |
+| `validate` | no | a function returning problems, or any zod-compatible schema (anything with `safeParse`) |
+| `endpoints` | no | where the component sends or listens, for `collectorTopology()` |
+| `description` | no | one line for docs |
+
+## How it is checked and pinned
+
+- The same serializer emits it, and OTEL101-OTEL108 apply to it as to any built-in. `validate` failures are OTEL107.
+- The pin is written as a `# chant: exporter datadog/eu schema <source>@<version>` comment above the emitted config, and returned by `collectorTopology()`.
+- A definition without a usable pin fails the build (OTEL109).
+- chant records the pin; it does not fetch or verify the schema. Ship the definition in a package and the package version pins it for everyone who imports it.
+- You cannot redefine a built-in type. Declare a named instance instead (`new OtlpExporter({ name: "vendor", ... })`).

package/dist/skills/chant-otel-platforms.md

@@ -0,0 +1,34 @@
+---
+skill: chant-otel-platforms
+description: Run a declared collector config on Kubernetes, GKE, Docker or Fly by rendering it into the platform's own config file
+user-invocable: true
+---
+
+# Running the collector config on a platform
+
+The otel lexicon produces collector YAML. A platform lexicon runs the collector and carries the YAML to it.
+
+## Rendering the YAML inside another lexicon
+
+`collectorYaml(entities)` returns exactly what the otel serializer would emit for those entities. Use it wherever a platform needs the config as a string:
+
+```ts
+import { OtlpReceiver, DebugExporter, Pipeline, collectorYaml } from "@intentius/chant-lexicon-otel";
+import { ConfigMap } from "@intentius/chant-lexicon-k8s";
+
+const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" } } });
+const debug = new DebugExporter({ verbosity: "basic" });
+
+export const collectorConfig = new ConfigMap({
+  metadata: { name: "otel-collector-config" },
+  data: { "config.yaml": collectorYaml([otlp, debug, new Pipeline({ signal: "traces", receivers: [otlp], exporters: [debug] })]) },
+});
+```
+
+## GKE
+
+The k8s lexicon's `GkeOtelCollector` composite is built this way: it declares an otlp receiver, batch and resourcedetection processors and a googlecloud exporter, renders them with `collectorYaml`, and mounts the result from a ConfigMap into a DaemonSet running under Workload Identity.
+
+## Checking a rendered config
+
+`validateCollectorConfig(config)` runs OTEL101-OTEL106 over any parsed collector config, so a composite's generated YAML can be checked in its own tests.

package/dist/skills/chant-otel.md

@@ -0,0 +1,60 @@
+---
+skill: chant-otel
+description: Declare OpenTelemetry Collector config (receivers, processors, exporters, pipelines) as typed chant entities and build collector YAML
+user-invocable: true
+---
+
+# OpenTelemetry Collector config with chant
+
+The otel lexicon (`@intentius/chant-lexicon-otel`) types collector config. Each receiver, processor, exporter and extension is an entity, pipelines reference them, and `chant build` writes one collector config file.
+
+## Project setup
+
+```ts
+// chant.config.ts
+export default { lexicons: ["otel"] };
+```
+
+## Declaring components
+
+Every component class takes the collector's own config keys (snake_case, as in the collector docs) plus an optional `name`. The id is `type`, or `type/name` when `name` is set.
+
+```ts
+import {
+  OtlpReceiver, MemoryLimiterProcessor, BatchProcessor, OtlpExporter, DebugExporter, Pipeline,
+} from "@intentius/chant-lexicon-otel";
+
+export const otlp = new OtlpReceiver({
+  protocols: { grpc: { endpoint: "0.0.0.0:4317" }, http: { endpoint: "0.0.0.0:4318" } },
+});
+export const limiter = new MemoryLimiterProcessor({ check_interval: "1s", limit_percentage: 80, spike_limit_percentage: 20 });
+export const batch = new BatchProcessor({ timeout: "5s" });
+export const backend = new OtlpExporter({ name: "backend", endpoint: "tempo.observability:4317", tls: { insecure: true } });
+
+export const traces = new Pipeline({ signal: "traces", receivers: [otlp], processors: [limiter, batch], exporters: [backend] });
+```
+
+Emits `receivers.otlp`, `processors.memory_limiter` and `processors.batch`, `exporters.otlp/backend`, and `service.pipelines.traces`.
+
+## Built-in set
+
+| Kind | Types |
+|---|---|
+| receivers | otlp, prometheus, hostmetrics, filelog |
+| processors | batch, memory_limiter, resource, attributes, k8sattributes, resourcedetection |
+| exporters | otlp, otlphttp, debug, prometheus, googlecloud |
+| extensions | health_check, pprof, zpages |
+
+Anything else goes through `defineComponent`; see the `chant-otel-custom-components` skill.
+
+## Rules
+
+- Reference components by entity where you can. A string id (`"otlp/backend"`) is allowed for a component declared elsewhere, and OTEL101 fails the build if nothing declares it.
+- Put `memory_limiter` first in `processors` (OTEL105).
+- Never write a credential literally. Use `"${env:NAME}"` and the collector reads it at start-up (OTEL002).
+- 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.
+
+## Reading the result
+
+`collectorTopologyOf(entities)` returns the pipelines, each component's endpoints and schema pin, and for each exporter the signals it carries, as plain data.