@intentius/chant-lexicon-otel 0.81.0

package/src/components/receivers.ts

@@ -0,0 +1,177 @@
+/**
+ * Built-in receivers: otlp, prometheus, hostmetrics, filelog.
+ */
+
+import { defineBuiltin } from "../define";
+import type { Duration, GRPCServerSettings, HTTPServerSettings, TLSClientSettings } from "./common";
+
+// ── otlp ─────────────────────────────────────────────────────────────
+
+export interface OtlpReceiverConfig {
+  protocols?: {
+    grpc?: GRPCServerSettings | null;
+    http?:
+      | (HTTPServerSettings & {
+          traces_url_path?: string;
+          metrics_url_path?: string;
+          logs_url_path?: string;
+        })
+      | null;
+  };
+}
+
+/** Receives OTLP over gRPC (default port 4317) and HTTP (default port 4318). */
+export const OtlpReceiver = defineBuiltin<OtlpReceiverConfig, "receiver", "otlp">({
+  kind: "receiver",
+  type: "otlp",
+  description: "Receives traces, metrics and logs over OTLP gRPC (4317) and HTTP (4318)",
+  validate: (c) =>
+    !c.protocols || (!("grpc" in c.protocols) && !("http" in c.protocols))
+      ? ["protocols enables neither grpc nor http, so the receiver listens on nothing"]
+      : [],
+  endpoints: (c) => {
+    const out: string[] = [];
+    if (c.protocols && "grpc" in c.protocols) out.push(c.protocols.grpc?.endpoint ?? "localhost:4317");
+    if (c.protocols && "http" in c.protocols) out.push(c.protocols.http?.endpoint ?? "localhost:4318");
+    return out;
+  },
+});
+
+// ── prometheus ───────────────────────────────────────────────────────
+
+export interface PrometheusStaticConfig {
+  targets: string[];
+  labels?: Record<string, string>;
+}
+
+/** One Prometheus scrape job. Service-discovery and relabel blocks pass through as written. */
+export interface PrometheusScrapeConfig {
+  job_name: string;
+  scrape_interval?: Duration;
+  scrape_timeout?: Duration;
+  metrics_path?: string;
+  scheme?: "http" | "https";
+  honor_labels?: boolean;
+  honor_timestamps?: boolean;
+  params?: Record<string, string[]>;
+  static_configs?: PrometheusStaticConfig[];
+  kubernetes_sd_configs?: Array<Record<string, unknown>>;
+  file_sd_configs?: Array<Record<string, unknown>>;
+  relabel_configs?: Array<Record<string, unknown>>;
+  metric_relabel_configs?: Array<Record<string, unknown>>;
+  tls_config?: Record<string, unknown>;
+  authorization?: { type?: string; credentials_file?: string };
+  bearer_token_file?: string;
+  sample_limit?: number;
+}
+
+export interface PrometheusReceiverConfig {
+  config: {
+    global?: { scrape_interval?: Duration; scrape_timeout?: Duration; evaluation_interval?: Duration; external_labels?: Record<string, string> };
+    scrape_configs: PrometheusScrapeConfig[];
+  };
+  trim_metric_suffixes?: boolean;
+  use_start_time_metric?: boolean;
+  start_time_metric_regex?: string;
+  target_allocator?: {
+    endpoint: string;
+    interval?: Duration;
+    collector_id?: string;
+    tls?: TLSClientSettings;
+  };
+}
+
+/** Scrapes Prometheus endpoints with Prometheus's own scrape config. */
+export const PrometheusReceiver = defineBuiltin<PrometheusReceiverConfig, "receiver", "prometheus">({
+  kind: "receiver",
+  type: "prometheus",
+  description: "Scrapes Prometheus endpoints using Prometheus scrape_configs",
+  validate: (c) => {
+    const problems: string[] = [];
+    const seen = new Set<string>();
+    for (const job of c.config?.scrape_configs ?? []) {
+      if (seen.has(job.job_name)) problems.push(`scrape job "${job.job_name}" is declared twice`);
+      seen.add(job.job_name);
+    }
+    if ((c.config?.scrape_configs ?? []).length === 0 && !c.target_allocator) {
+      problems.push("config.scrape_configs is empty and no target_allocator is set, so nothing is scraped");
+    }
+    return problems;
+  },
+  endpoints: (c) =>
+    (c.config?.scrape_configs ?? []).flatMap((job) => (job.static_configs ?? []).flatMap((s) => s.targets)),
+});
+
+// ── hostmetrics ──────────────────────────────────────────────────────
+
+export type HostMetricsScraper =
+  | "cpu"
+  | "disk"
+  | "load"
+  | "filesystem"
+  | "memory"
+  | "network"
+  | "paging"
+  | "processes"
+  | "process"
+  | "system";
+
+export interface HostMetricsReceiverConfig {
+  collection_interval?: Duration;
+  initial_delay?: Duration;
+  /** Host root when the collector runs in a container, e.g. `/hostfs`. */
+  root_path?: string;
+  /** Scraper name to its settings; `{}` enables a scraper with its defaults. */
+  scrapers: Partial<Record<HostMetricsScraper, Record<string, unknown>>>;
+}
+
+/** Scrapes CPU, memory, disk, filesystem, network and process metrics from the host. */
+export const HostMetricsReceiver = defineBuiltin<HostMetricsReceiverConfig, "receiver", "hostmetrics">({
+  kind: "receiver",
+  type: "hostmetrics",
+  description: "Scrapes host metrics (cpu, memory, disk, filesystem, network, processes)",
+  validate: (c) => (Object.keys(c.scrapers ?? {}).length === 0 ? ["scrapers is empty, so no host metric is collected"] : []),
+});
+
+// ── filelog ──────────────────────────────────────────────────────────
+
+/** A stanza operator (`regex_parser`, `json_parser`, `move`, …). Its other keys depend on `type`. */
+export interface FileLogOperator {
+  type: string;
+  id?: string;
+  output?: string | string[];
+  [key: string]: unknown;
+}
+
+export interface FileLogReceiverConfig {
+  include: string[];
+  exclude?: string[];
+  start_at?: "beginning" | "end";
+  include_file_name?: boolean;
+  include_file_path?: boolean;
+  include_file_name_resolved?: boolean;
+  include_file_path_resolved?: boolean;
+  poll_interval?: Duration;
+  max_concurrent_files?: number;
+  max_log_size?: string;
+  fingerprint_size?: string;
+  encoding?: string;
+  force_flush_period?: Duration;
+  delete_after_read?: boolean;
+  /** The id of a storage extension, so offsets survive a restart. */
+  storage?: string;
+  multiline?: { line_start_pattern?: string; line_end_pattern?: string; omit_pattern?: boolean };
+  operators?: FileLogOperator[];
+  attributes?: Record<string, string>;
+  resource?: Record<string, string>;
+  retry_on_failure?: { enabled?: boolean; initial_interval?: Duration; max_interval?: Duration; max_elapsed_time?: Duration };
+}
+
+/** Tails log files and parses them with stanza operators. */
+export const FileLogReceiver = defineBuiltin<FileLogReceiverConfig, "receiver", "filelog">({
+  kind: "receiver",
+  type: "filelog",
+  description: "Tails log files and parses each line with stanza operators",
+  validate: (c) => (c.include?.length ? [] : ["include is empty, so no file is read"]),
+  endpoints: (c) => c.include ?? [],
+});

package/src/define.test.ts

@@ -0,0 +1,131 @@
+/**
+ * The extension point: a component chant doesn't ship, defined by a team,
+ * serializes and lints exactly like a built-in, and carries its schema pin.
+ */
+import { describe, expect, test } from "vitest";
+import { load } from "js-yaml";
+import type { Declarable } from "@intentius/chant/declarable";
+import { makePostSynthCtx } from "@intentius/chant-test-utils";
+import { otelSerializer } from "./serializer";
+import { postSynthChecks } from "./lint/post-synth";
+import { BatchProcessor, OtlpExporter, OtlpReceiver } from "./components";
+import { COLLECTOR_PIN, defineComponent, definitionFor, isOTelComponent } from "./define";
+import { Pipeline } from "./pipeline";
+import { collectorTopologyOf } from "./topology";
+
+interface VendorExporterConfig {
+  api: { key: string; site?: string };
+  queue_size?: number;
+}
+
+const VendorExporter = defineComponent<VendorExporterConfig>()({
+  kind: "exporter",
+  type: "vendor2559",
+  pin: { source: "@acme/otel-vendor-exporter", version: "1.4.2", digest: "sha256:0f1e2d" },
+  description: "Sends telemetry to Vendor",
+  validate: (c) => (c.api.key.includes("${") ? [] : ["api.key must be an ${env:...} reference"]),
+  endpoints: (c) => [`https://intake.${c.api.site ?? "vendor.example"}`],
+});
+
+/** A zod-compatible validator, without depending on zod. */
+const RedactProcessor = defineComponent<{ patterns: string[] }>()({
+  kind: "processor",
+  type: "redact2559",
+  pin: { source: "github.com/acme/otel-redact", version: "v0.3.0" },
+  validate: {
+    safeParse: (v: unknown) =>
+      Array.isArray((v as { patterns?: unknown }).patterns) && (v as { patterns: unknown[] }).patterns.length > 0
+        ? { success: true }
+        : { success: false, error: { issues: [{ path: ["patterns"], message: "needs at least one pattern" }] } },
+  },
+});
+
+function build(list: unknown[]) {
+  const entities = new Map(list.map((e, i) => [`e${i}`, e as Declarable]));
+  const out = otelSerializer.serialize(entities);
+  const yaml = typeof out === "string" ? out : out.primary;
+  const ctx = makePostSynthCtx("otel", yaml, entities);
+  const diags = postSynthChecks.flatMap((c) => c.check(ctx));
+  return { yaml, diags, entities };
+}
+
+describe("defineComponent", () => {
+  test("a custom component is a component like any built-in", () => {
+    const v = new VendorExporter({ name: "eu", api: { key: "${env:VENDOR_KEY}", site: "vendor.eu" } });
+    expect(isOTelComponent(v)).toBe(true);
+    expect(v.componentId).toBe("vendor2559/eu");
+    expect(v.entityType).toBe("OTel::Exporter::vendor2559");
+    expect(v.lexicon).toBe("otel");
+    expect(definitionFor(v.entityType)?.builtin).toBe(false);
+  });
+
+  test("it serializes under its section with a # chant: pin header", () => {
+    const otlp = new OtlpReceiver({ protocols: { grpc: {} } });
+    const v = new VendorExporter({ name: "eu", api: { key: "${env:VENDOR_KEY}" }, queue_size: 500 });
+    const { yaml, diags } = build([otlp, v, new Pipeline({ signal: "traces", receivers: [otlp], exporters: [v] })]);
+    expect(yaml.split("\n")[0]).toBe("# chant: exporter vendor2559/eu schema @acme/otel-vendor-exporter@1.4.2 sha256:0f1e2d");
+    const parsed = load(yaml) as any;
+    expect(parsed.exporters["vendor2559/eu"]).toEqual({ api: { key: "${env:VENDOR_KEY}" }, queue_size: 500 });
+    expect(parsed.service.pipelines.traces.exporters).toEqual(["vendor2559/eu"]);
+    expect(diags).toEqual([]);
+  });
+
+  test("built-ins get no header line", () => {
+    const otlp = new OtlpReceiver({ protocols: { grpc: {} } });
+    const x = new OtlpExporter({ endpoint: "x:4317" });
+    const { yaml } = build([otlp, x, new Pipeline({ signal: "traces", receivers: [otlp], exporters: [x] })]);
+    expect(yaml.startsWith("receivers:")).toBe(true);
+  });
+
+  test("its own validate runs as OTEL107, function or safeParse", () => {
+    const otlp = new OtlpReceiver({ protocols: { grpc: {} } });
+    const v = new VendorExporter({ api: { key: "plaintext" } });
+    const r = new RedactProcessor({ patterns: [] });
+    const { diags } = build([otlp, r, v, new Pipeline({ signal: "logs", receivers: [otlp], processors: [r], exporters: [v] })]);
+    expect(diags.map((d) => [d.checkId, d.message])).toEqual([
+      ["OTEL107", 'processor "redact2559": patterns: needs at least one pattern'],
+      ["OTEL107", 'exporter "vendor2559": api.key must be an ${env:...} reference'],
+    ]);
+  });
+
+  test("the reference and pipeline checks apply to it unchanged", () => {
+    const otlp = new OtlpReceiver({ protocols: { grpc: {} } });
+    const unused = new VendorExporter({ name: "idle", api: { key: "${env:K}" } });
+    const batch = new BatchProcessor({});
+    const { diags } = build([
+      otlp,
+      batch,
+      unused,
+      new Pipeline({ signal: "traces", receivers: [otlp], processors: [batch], exporters: ["vendor2559/missing"] }),
+    ]);
+    expect(diags.map((d) => [d.checkId, d.entity])).toEqual([
+      ["OTEL101", "vendor2559/missing"],
+      ["OTEL103", "vendor2559/idle"],
+    ]);
+  });
+
+  test("topology reports its endpoints and its pin", () => {
+    const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" } } });
+    const v = new VendorExporter({ name: "eu", api: { key: "${env:K}", site: "vendor.eu" } });
+    const topo = collectorTopologyOf([otlp, v, new Pipeline({ signal: "metrics", receivers: [otlp], exporters: [v] })]);
+    const component = topo.components.find((c) => c.id === "vendor2559/eu")!;
+    expect(component.builtin).toBe(false);
+    expect(component.schema).toEqual({ source: "@acme/otel-vendor-exporter", version: "1.4.2", digest: "sha256:0f1e2d" });
+    expect(topo.exporters).toEqual([
+      { id: "vendor2559/eu", type: "vendor2559", endpoints: ["https://intake.vendor.eu"], pipelines: ["metrics"], signals: ["metrics"] },
+    ]);
+    expect(topo.components.find((c) => c.id === "otlp")!.schema).toEqual({ ...COLLECTOR_PIN });
+  });
+
+  test("a built-in type cannot be redefined", () => {
+    expect(() =>
+      defineComponent<{ endpoint: string }>()({ kind: "exporter", type: "otlp", pin: { source: "x", version: "1" } }),
+    ).toThrow(/built in/);
+  });
+
+  test("a type that is not collector syntax is refused", () => {
+    expect(() =>
+      defineComponent<object>()({ kind: "exporter", type: "has-dash", pin: { source: "x", version: "1" } }),
+    ).toThrow(/not a collector type/);
+  });
+});

package/src/define.ts

@@ -0,0 +1,249 @@
+/**
+ * `defineComponent()`, the one way a collector component type enters this
+ * lexicon.
+ *
+ * The built-in receivers, processors, exporters and extensions are defined
+ * through it, and so is a component a team or plugin adds for something chant
+ * doesn't ship (a vendor exporter, an in-house processor). Both produce the
+ * same kind of class, register in the same table, serialize through the same
+ * code and are checked by the same post-synth checks, so there is no second
+ * path for a custom component to fall off.
+ *
+ * ## Schema pinning
+ *
+ * Every definition carries a `pin`: the source its config type was written
+ * against and the version of that source. Built-ins share `COLLECTOR_PIN`,
+ * which moves only when this package does, so the chant lexicon version pins
+ * them. A custom definition must name its own pin, typically the npm package
+ * (or Go module) that ships the component and the release its type follows,
+ * optionally with a digest of the schema document. chant records the pin; it
+ * does not fetch or verify the schema. The pin shows up in three places:
+ *
+ * - `collectorTopology()` reports it for every component, built-in or not.
+ * - The serializer writes a `# chant:` comment line per custom component at
+ *   the top of the emitted YAML, so the file says which schema each
+ *   non-built-in component was checked against. The collector ignores it.
+ * - OTEL109 fails a build whose custom component has no usable pin.
+ */
+
+import { createResource } from "@intentius/chant/runtime";
+import type { Declarable } from "@intentius/chant/declarable";
+import { componentId, type ComponentKind } from "./model";
+
+/** Where a component's config schema comes from, and which version of it the type follows. */
+export interface SchemaPin {
+  /** The package, Go module or URL that defines the component's config, e.g. `@acme/otel-datadog`. */
+  source: string;
+  /** The version of `source` the TypeScript config type was written against. */
+  version: string;
+  /** Optional digest of the schema document itself, e.g. `sha256:…`. Recorded as given. */
+  digest?: string;
+}
+
+/**
+ * The collector distribution the built-in config types follow. Bumping it is a
+ * lexicon change like any other, released with this package.
+ */
+export const COLLECTOR_PIN: SchemaPin = Object.freeze({
+  source: "github.com/open-telemetry/opentelemetry-collector-contrib",
+  version: "v0.130.0",
+});
+
+/** A zod-compatible schema: anything with `safeParse`. Keeps zod optional. */
+export interface SafeParseSchema {
+  safeParse(value: unknown): {
+    success: boolean;
+    error?: { issues?: Array<{ path?: ReadonlyArray<PropertyKey>; message: string }>; message?: string };
+  };
+}
+
+/** A config check: a function returning problems, or a zod-compatible schema. */
+export type ConfigValidator<C> = ((config: C) => string[]) | SafeParseSchema;
+
+export interface ComponentDefinition<K extends ComponentKind = ComponentKind, T extends string = string, C = Record<string, unknown>> {
+  kind: K;
+  /** The collector type, the part of the id before `/`. */
+  type: T;
+  /** Where the config schema comes from. Required for a custom component. */
+  pin: SchemaPin;
+  /** True only for the components this package ships. */
+  builtin: boolean;
+  /** One line for hover and docs. */
+  description?: string;
+  /** Extra checks on the config beyond what its TypeScript type enforces (OTEL107). */
+  validate?: ConfigValidator<C>;
+  /** Where this component sends or listens, for `collectorTopology()`. */
+  endpoints?: (config: C) => string[];
+}
+
+/** What a custom component supplies. `builtin` is always false for these. */
+export type CustomComponentOptions<K extends ComponentKind, T extends string, C> = Omit<
+  ComponentDefinition<K, T, C>,
+  "builtin"
+>;
+
+/** Constructor props: the component's own config plus the optional instance `name`. */
+export type ComponentProps<C> = C & {
+  /** The instance name. The component id becomes `type/name`; without it the id is just `type`. */
+  name?: string;
+};
+
+/** A declared collector component. */
+export interface OTelComponent<K extends ComponentKind = ComponentKind, T extends string = string, C = Record<string, unknown>>
+  extends Declarable {
+  readonly props: ComponentProps<C>;
+  readonly componentKind: K;
+  readonly componentType: T;
+  /** The collector id, `type` or `type/name`. */
+  readonly componentId: string;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+type CtorArgs<C> = {} extends C ? [props?: ComponentProps<C>] : [props: ComponentProps<C>];
+
+export interface ComponentClass<K extends ComponentKind = ComponentKind, T extends string = string, C = Record<string, unknown>> {
+  new (...args: CtorArgs<C>): OTelComponent<K, T, C>;
+  readonly definition: ComponentDefinition<K, T, C>;
+}
+
+const KIND_SEGMENT: Record<ComponentKind, string> = {
+  receiver: "Receiver",
+  processor: "Processor",
+  exporter: "Exporter",
+  extension: "Extension",
+};
+
+/** The chant entity type for a component, e.g. `OTel::Exporter::otlp`. */
+export function componentEntityType(kind: ComponentKind, type: string): string {
+  return `OTel::${KIND_SEGMENT[kind]}::${type}`;
+}
+
+// One table per process, keyed by entity type. Held on globalThis so a second
+// copy of this module (a test runner and a built dist, say) shares it.
+const REGISTRY_KEY = Symbol.for("chant.otel.componentDefinitions");
+function registry(): Map<string, ComponentDefinition> {
+  const g = globalThis as unknown as Record<symbol, Map<string, ComponentDefinition> | undefined>;
+  let table = g[REGISTRY_KEY];
+  if (!table) {
+    table = new Map();
+    g[REGISTRY_KEY] = table;
+  }
+  return table;
+}
+
+/** The definition behind an entity type, if one has been registered in this process. */
+export function definitionFor(entityType: string): ComponentDefinition | undefined {
+  return registry().get(entityType);
+}
+
+/** The definition for a collector `kind` + `type`, e.g. the built-in `exporter` `otlp`. */
+export function definitionOf(kind: ComponentKind, type: string): ComponentDefinition | undefined {
+  return registry().get(componentEntityType(kind, type));
+}
+
+/** Every registered definition, built-ins first in registration order. */
+export function registeredDefinitions(): ComponentDefinition[] {
+  return [...registry().values()];
+}
+
+const TYPE_PATTERN = /^[A-Za-z0-9_]+$/;
+
+function makeClass<K extends ComponentKind, T extends string, C>(
+  def: ComponentDefinition<K, T, C>,
+): ComponentClass<K, T, C> {
+  if (!TYPE_PATTERN.test(def.type)) {
+    throw new Error(`otel: component type "${def.type}" is not a collector type (letters, digits and _ only)`);
+  }
+  const entityType = componentEntityType(def.kind, def.type);
+  const existing = registry().get(entityType);
+  if (existing?.builtin && !def.builtin) {
+    throw new Error(
+      `otel: ${def.kind} "${def.type}" is built in. Declare an instance with a name (${def.type}/<name>) instead of defining it again.`,
+    );
+  }
+  registry().set(entityType, def as unknown as ComponentDefinition);
+
+  const Base = createResource(entityType, "otel", {}) as unknown as (this: object, props: Record<string, unknown>) => void;
+  const Cls = function (this: object, props?: Record<string, unknown>) {
+    const p = props ?? {};
+    Base.call(this, p);
+    const name = typeof p.name === "string" ? p.name : undefined;
+    Object.defineProperty(this, "componentKind", { value: def.kind, enumerable: false });
+    Object.defineProperty(this, "componentType", { value: def.type, enumerable: false });
+    Object.defineProperty(this, "componentId", { value: componentId(def.type, name), enumerable: false });
+  };
+  Object.defineProperty(Cls, "name", { value: `${def.type}${KIND_SEGMENT[def.kind]}` });
+  Object.defineProperty(Cls, "definition", { value: def, enumerable: false });
+  return Cls as unknown as ComponentClass<K, T, C>;
+}
+
+/** Internal: how the built-ins in `./components` are defined. */
+export function defineBuiltin<C, K extends ComponentKind = ComponentKind, T extends string = string>(
+  def: Omit<ComponentDefinition<K, T, C>, "builtin" | "pin">,
+): ComponentClass<K, T, C> {
+  return makeClass<K, T, C>({ ...def, pin: COLLECTOR_PIN, builtin: true });
+}
+
+/**
+ * Define a collector component chant doesn't ship.
+ *
+ * @example
+ * ```ts
+ * 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.startsWith("${env:") ? [] : ["api.key should come from ${env:...}"]),
+ *   endpoints: (c) => [`https://api.${c.api.site ?? "datadoghq.com"}`],
+ * });
+ *
+ * export const dd = new DatadogExporter({ api: { key: "${env:DD_API_KEY}" } });
+ * ```
+ *
+ * The curried form lets you name the config type while `kind` and `type` are
+ * still inferred from the literal you pass.
+ */
+export function defineComponent<C>() {
+  return function <K extends ComponentKind, T extends string>(
+    options: CustomComponentOptions<K, T, C>,
+  ): ComponentClass<K, T, C> {
+    return makeClass<K, T, C>({ ...options, builtin: false });
+  };
+}
+
+/** True when `value` is a declared collector component (built-in or custom). */
+export function isOTelComponent(value: unknown): value is OTelComponent {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { componentKind?: unknown }).componentKind === "string" &&
+    typeof (value as { componentId?: unknown }).componentId === "string" &&
+    (value as { lexicon?: unknown }).lexicon === "otel"
+  );
+}
+
+/** Run a definition's validator, normalising both validator forms to a list of messages. */
+export function runValidator<C>(validator: ConfigValidator<C> | undefined, config: C): string[] {
+  if (!validator) return [];
+  if (typeof validator === "function") return validator(config);
+  const result = validator.safeParse(config);
+  if (result.success) return [];
+  const issues = result.error?.issues ?? [];
+  if (issues.length === 0) return [result.error?.message ?? "config does not match its schema"];
+  return issues.map((i) => {
+    const path = (i.path ?? []).map(String).join(".");
+    return path ? `${path}: ${i.message}` : i.message;
+  });
+}
+
+/** A pin is usable when it names a source and a version. */
+export function isUsablePin(pin: unknown): pin is SchemaPin {
+  if (typeof pin !== "object" || pin === null) return false;
+  const p = pin as Record<string, unknown>;
+  return typeof p.source === "string" && p.source.trim() !== "" && typeof p.version === "string" && p.version.trim() !== "";
+}

package/src/detect.ts

@@ -0,0 +1,11 @@
+/**
+ * Template detection for the otel lexicon: a parsed document is a collector
+ * config when it has `service.pipelines` and a receivers or exporters
+ * section. Kept free of the plugin and the TypeScript compiler so it bundles
+ * for edge runtimes, like the other lexicons' `detect` modules.
+ */
+import { looksLikeCollectorConfig } from "./model";
+
+export function detectTemplate(data: unknown): boolean {
+  return looksLikeCollectorConfig(data);
+}

package/src/generated/lexicon-otel.json

@@ -0,0 +1,102 @@
+{
+  "AttributesProcessor": {
+    "resourceType": "OTel::Processor::attributes",
+    "kind": "resource",
+    "lexicon": "otel"
+  },
+  "BatchProcessor": {
+    "resourceType": "OTel::Processor::batch",
+    "kind": "resource",
+    "lexicon": "otel"
+  },
+  "DebugExporter": {
+    "resourceType": "OTel::Exporter::debug",
+    "kind": "resource",
+    "lexicon": "otel"
+  },
+  "FileLogReceiver": {
+    "resourceType": "OTel::Receiver::filelog",
+    "kind": "resource",
+    "lexicon": "otel"
+  },
+  "GoogleCloudExporter": {
+    "resourceType": "OTel::Exporter::googlecloud",
+    "kind": "resource",
+    "lexicon": "otel"
+  },
+  "HealthCheckExtension": {
+    "resourceType": "OTel::Extension::health_check",
+    "kind": "resource",
+    "lexicon": "otel"
+  },
+  "HostMetricsReceiver": {
+    "resourceType": "OTel::Receiver::hostmetrics",
+    "kind": "resource",
+    "lexicon": "otel"
+  },
+  "K8sAttributesProcessor": {
+    "resourceType": "OTel::Processor::k8sattributes",
+    "kind": "resource",
+    "lexicon": "otel"
+  },
+  "MemoryLimiterProcessor": {
+    "resourceType": "OTel::Processor::memory_limiter",
+    "kind": "resource",
+    "lexicon": "otel"
+  },
+  "OtlpExporter": {
+    "resourceType": "OTel::Exporter::otlp",
+    "kind": "resource",
+    "lexicon": "otel"
+  },
+  "OtlpHttpExporter": {
+    "resourceType": "OTel::Exporter::otlphttp",
+    "kind": "resource",
+    "lexicon": "otel"
+  },
+  "OtlpReceiver": {
+    "resourceType": "OTel::Receiver::otlp",
+    "kind": "resource",
+    "lexicon": "otel"
+  },
+  "Pipeline": {
+    "resourceType": "OTel::Pipeline",
+    "kind": "resource",
+    "lexicon": "otel"
+  },
+  "PprofExtension": {
+    "resourceType": "OTel::Extension::pprof",
+    "kind": "resource",
+    "lexicon": "otel"
+  },
+  "PrometheusExporter": {
+    "resourceType": "OTel::Exporter::prometheus",
+    "kind": "resource",
+    "lexicon": "otel"
+  },
+  "PrometheusReceiver": {
+    "resourceType": "OTel::Receiver::prometheus",
+    "kind": "resource",
+    "lexicon": "otel"
+  },
+  "ResourceDetectionProcessor": {
+    "resourceType": "OTel::Processor::resourcedetection",
+    "kind": "resource",
+    "lexicon": "otel"
+  },
+  "ResourceProcessor": {
+    "resourceType": "OTel::Processor::resource",
+    "kind": "resource",
+    "lexicon": "otel"
+  },
+  "Service": {
+    "resourceType": "OTel::Service",
+    "kind": "resource",
+    "lexicon": "otel"
+  },
+  "ZPagesExtension": {
+    "resourceType": "OTel::Extension::zpages",
+    "kind": "resource",
+    "lexicon": "otel"
+  }
+}