autotel-schema 1.0.0 → 2.0.0

package/src/cli.ts

@@ -1,117 +0,0 @@
-#!/usr/bin/env node
-/**
- * autotel-schema CLI — the CI gate for your telemetry's public API.
- *
- *   autotel-schema diff <baseline.json> <current.json>   # classify changes
- *   autotel-schema check <baseline.json> <current.json>  # exit 1 on breaking
- *
- * Both operate on snapshot JSON produced by `serializeSnapshot(contractToSnapshot(contract))`.
- * Commit the baseline; regenerate `current` in CI; gate the merge on `check`.
- */
-
-import { readFileSync } from 'node:fs';
-import path from 'node:path';
-import { parseSnapshot } from './snapshot.js';
-import {
-  diffSnapshots,
-  formatDiff,
-  hasBreakingChanges,
-  type SnapshotDiff,
-} from './diff.js';
-
-interface Parsed {
-  command: string | undefined;
-  baseline: string | undefined;
-  current: string | undefined;
-  json: boolean;
-}
-
-function parseArgs(argv: string[]): Parsed {
-  const positional: string[] = [];
-  let json = false;
-  for (const arg of argv) {
-    if (arg === '--json') json = true;
-    else if (arg === '-h' || arg === '--help') positional.unshift('help');
-    else positional.push(arg);
-  }
-  return {
-    command: positional[0],
-    baseline: positional[1],
-    current: positional[2],
-    json,
-  };
-}
-
-const USAGE = `autotel-schema — treat your trace surface like a versioned public API
-
-Usage:
-  autotel-schema diff  <baseline.json> <current.json> [--json]
-  autotel-schema check <baseline.json> <current.json> [--json]
-
-Commands:
-  diff    Print every change (breaking / additive / neutral). Always exits 0.
-  check   Like diff, but exits 1 if any breaking change is found (CI gate).
-
-Snapshots are produced with serializeSnapshot(contractToSnapshot(contract)).`;
-
-function loadDiff(baseline: string, current: string): SnapshotDiff {
-  const prev = parseSnapshot(readFileSync(baseline, 'utf8'));
-  const next = parseSnapshot(readFileSync(current, 'utf8'));
-  return diffSnapshots(prev, next);
-}
-
-function emit(diff: SnapshotDiff, json: boolean): void {
-  if (json) {
-    console.log(JSON.stringify(diff, null, 2));
-  } else {
-    console.log(formatDiff(diff));
-  }
-}
-
-export function run(argv: string[]): number {
-  const { command, baseline, current, json } = parseArgs(argv);
-
-  if (!command || command === 'help') {
-    console.log(USAGE);
-    return command ? 0 : 1;
-  }
-
-  if (command !== 'diff' && command !== 'check') {
-    console.error(`autotel-schema: unknown command "${command}"\n\n${USAGE}`);
-    return 1;
-  }
-
-  if (!baseline || !current) {
-    console.error('autotel-schema: both <baseline.json> and <current.json> are required\n');
-    console.error(USAGE);
-    return 1;
-  }
-
-  let diff: SnapshotDiff;
-  try {
-    diff = loadDiff(baseline, current);
-  } catch (error) {
-    console.error(
-      `autotel-schema: ${error instanceof Error ? error.message : String(error)}`,
-    );
-    return 1;
-  }
-
-  emit(diff, json);
-
-  if (command === 'check' && hasBreakingChanges(diff)) {
-    console.error(
-      `\nautotel-schema: ${diff.breaking.length} breaking change(s) to the telemetry contract. ` +
-        `Bump the contract major version and update the committed snapshot.`,
-    );
-    return 1;
-  }
-  return 0;
-}
-
-// Only auto-run when invoked directly as the binary, not when imported in tests.
-// Match the basename so a repo path containing "autotel-schema" can't trigger it.
-const entry = process.argv[1] ? path.basename(process.argv[1]) : '';
-if (entry === 'autotel-schema' || entry === 'cli.js' || entry === 'cli.cjs') {
-  process.exit(run(process.argv.slice(2)));
-}

package/src/contract.test.ts

@@ -1,67 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import {
-  allowsAdditionalAttributes,
-  defineContract,
-  resolveAttributeSpec,
-  type TelemetryContract,
-} from './contract.js';
-
-const base: TelemetryContract = {
-  service: 'checkout',
-  version: '1.2.0',
-  commonAttributes: {
-    'user.id': { type: 'string', highCardinality: true },
-  },
-  spans: {
-    'checkout.charge': {
-      attributes: {
-        'payment.provider': { type: 'string', required: true, enum: ['stripe', 'paypal'] },
-        'payment.amount_cents': { type: 'number', required: true },
-      },
-    },
-  },
-};
-
-describe('defineContract', () => {
-  it('accepts and freezes a valid contract', () => {
-    const c = defineContract(base);
-    expect(Object.isFrozen(c)).toBe(true);
-    expect(c.service).toBe('checkout');
-  });
-
-  it('rejects an empty service', () => {
-    expect(() => defineContract({ ...base, service: '' })).toThrowError(/service/);
-  });
-
-  it('rejects a non-semver version', () => {
-    expect(() => defineContract({ ...base, version: 'v1' })).toThrowError(/semver/);
-  });
-
-  it('rejects an unknown attribute type', () => {
-    expect(() =>
-      defineContract({
-        ...base,
-        spans: { 'x.y': { attributes: { k: { type: 'uuid' as never } } } },
-      }),
-    ).toThrow();
-  });
-});
-
-describe('resolveAttributeSpec', () => {
-  it('prefers span-specific over common attributes', () => {
-    expect(resolveAttributeSpec(base, 'checkout.charge', 'payment.provider')?.required).toBe(true);
-    expect(resolveAttributeSpec(base, 'checkout.charge', 'user.id')?.highCardinality).toBe(true);
-    expect(resolveAttributeSpec(base, 'checkout.charge', 'nope')).toBeUndefined();
-  });
-});
-
-describe('allowsAdditionalAttributes', () => {
-  it('defaults to false (declared-only)', () => {
-    expect(allowsAdditionalAttributes(base, 'checkout.charge')).toBe(false);
-  });
-  it('honors span- then contract-level overrides', () => {
-    const loose = { ...base, additionalAttributes: true };
-    expect(allowsAdditionalAttributes(loose, 'checkout.charge')).toBe(true);
-  });
-});

package/src/contract.ts

@@ -1,231 +0,0 @@
-/**
- * Telemetry contract model.
- *
- * The premise: when the primary reader of your telemetry is an agent, your
- * span names and attribute keys are a **public API**. Renaming `fast_path_hit`
- * to `fast_path_taken` in a refactor PR silently breaks every prompt that
- * mentions it — there is no compiler to catch it, because to the compiler these
- * are just strings in a JSON blob.
- *
- * `defineContract()` makes that surface explicit, typed, and versionable: you
- * declare which spans your service emits and which attributes live on them,
- * then validate live spans against it ({@link ./validate}) and diff it across
- * commits to catch breaking changes before they ship ({@link ./diff}).
- *
- * This module is dependency-free and side-effect-free by design — safe to
- * import anywhere (browser, edge, CLI) without pulling in the OpenTelemetry SDK.
- */
-
-/** Scalar and array attribute types permitted on a span (OTLP value shapes). */
-export type AttributeType =
-  | 'string'
-  | 'number'
-  | 'boolean'
-  | 'string[]'
-  | 'number[]'
-  | 'boolean[]';
-
-export const ATTRIBUTE_TYPES: readonly AttributeType[] = [
-  'string',
-  'number',
-  'boolean',
-  'string[]',
-  'number[]',
-  'boolean[]',
-];
-
-/**
- * Lifecycle of a span or attribute, mirroring how the OpenTelemetry semantic
- * conventions stage their own surface. `stable` is a promise to agent readers
- * that the name will not change without a major contract bump.
- */
-export type Stability = 'stable' | 'experimental' | 'deprecated';
-
-export const STABILITIES: readonly Stability[] = [
-  'stable',
-  'experimental',
-  'deprecated',
-];
-
-/** Declaration for a single attribute key on a span. */
-export interface AttributeSpec {
-  /** OTLP value shape. Validated at runtime against the emitted value. */
-  type: AttributeType;
-  /** Lifecycle stage. Defaults to `stable`. */
-  stability?: Stability;
-  /** When `true`, the attribute must be present on every matching span. */
-  required?: boolean;
-  /** Human/agent-facing description of what the attribute means. */
-  description?: string;
-  /**
-   * Marks an attribute as intentionally high-cardinality (user id, sender
-   * domain, request id). For an agent reader these are the single most useful
-   * fields on a trace, so {@link ./redaction.highCardinalityKeys} surfaces them
-   * as a *protect* list — telling redactors/normalizers NOT to strip them.
-   */
-  highCardinality?: boolean;
-  /** Closed set of permitted values. Reported as `enum_violation` if exceeded. */
-  enum?: readonly (string | number)[];
-  /** Set when `stability: 'deprecated'`; explains what to use instead. */
-  replacedBy?: string;
-  /** Free-text note shown alongside deprecation warnings. */
-  deprecatedReason?: string;
-}
-
-/** Declaration for a single span name your service emits. */
-export interface SpanSpec {
-  /** Human/agent-facing description of when this span is produced. */
-  description?: string;
-  /** Lifecycle stage. Defaults to `stable`. */
-  stability?: Stability;
-  /** Attributes specific to this span, keyed by attribute name. */
-  attributes?: Record<string, AttributeSpec>;
-  /**
-   * When `true`, attributes not declared here are allowed without an
-   * `unknown_attribute` violation. Defaults to the contract-level setting.
-   */
-  additionalAttributes?: boolean;
-}
-
-/** The full telemetry contract for one service. */
-export interface TelemetryContract {
-  /** `service.name` this contract describes. */
-  service: string;
-  /**
-   * Semver of the *contract itself* (not the app). Bumped when the trace
-   * surface changes; surfaced to readers as the `telemetry.schema.version`
-   * resource attribute via {@link ./attrs.SCHEMA_ATTRS}.
-   */
-  version: string;
-  /** Spans this service emits, keyed by span name. */
-  spans: Record<string, SpanSpec>;
-  /** Attributes permitted on *any* span (e.g. `user.id`, `tenant.id`). */
-  commonAttributes?: Record<string, AttributeSpec>;
-  /**
-   * Default for `SpanSpec.additionalAttributes` when a span does not set it.
-   * Defaults to `false` (declared-only — the stricter, agent-friendlier mode).
-   */
-  additionalAttributes?: boolean;
-}
-
-const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[\w.]+)?$/;
-
-function assert(condition: unknown, message: string): asserts condition {
-  if (!condition) {
-    throw new Error(`autotel-schema: ${message}`);
-  }
-}
-
-function validateAttribute(
-  scope: string,
-  key: string,
-  spec: AttributeSpec,
-): void {
-  assert(
-    ATTRIBUTE_TYPES.includes(spec.type),
-    `${scope} attribute "${key}" has invalid type "${spec.type}"`,
-  );
-  if (spec.stability) {
-    assert(
-      STABILITIES.includes(spec.stability),
-      `${scope} attribute "${key}" has invalid stability "${spec.stability}"`,
-    );
-  }
-  if (spec.stability === 'deprecated') {
-    assert(
-      spec.replacedBy !== undefined || spec.deprecatedReason !== undefined,
-      `${scope} attribute "${key}" is deprecated but has no replacedBy or deprecatedReason`,
-    );
-  }
-  if (spec.enum) {
-    assert(
-      spec.enum.length > 0,
-      `${scope} attribute "${key}" declares an empty enum`,
-    );
-  }
-}
-
-/**
- * Validate and freeze a telemetry contract. Throws on structural mistakes
- * (bad semver, unknown attribute type, deprecation with no replacement) so the
- * contract fails loudly at module load, not silently at runtime.
- *
- * @example
- * ```ts
- * export const contract = defineContract({
- *   service: 'checkout',
- *   version: '1.2.0',
- *   commonAttributes: {
- *     'user.id': { type: 'string', highCardinality: true, description: 'Authenticated user' },
- *   },
- *   spans: {
- *     'checkout.charge': {
- *       description: 'Charge a payment method',
- *       attributes: {
- *         'payment.provider': { type: 'string', required: true, enum: ['stripe', 'paypal'] },
- *         'payment.amount_cents': { type: 'number', required: true },
- *       },
- *     },
- *   },
- * });
- * ```
- */
-export function defineContract(contract: TelemetryContract): TelemetryContract {
-  assert(
-    typeof contract.service === 'string' && contract.service.length > 0,
-    'contract.service must be a non-empty string',
-  );
-  assert(
-    SEMVER_RE.test(contract.version),
-    `contract.version "${contract.version}" is not valid semver (e.g. "1.2.0")`,
-  );
-  assert(
-    contract.spans && typeof contract.spans === 'object',
-    'contract.spans must be an object',
-  );
-
-  for (const [spanName, spanSpec] of Object.entries(contract.spans)) {
-    if (spanSpec.stability) {
-      assert(
-        STABILITIES.includes(spanSpec.stability),
-        `span "${spanName}" has invalid stability "${spanSpec.stability}"`,
-      );
-    }
-    for (const [key, spec] of Object.entries(spanSpec.attributes ?? {})) {
-      validateAttribute(`span "${spanName}"`, key, spec);
-    }
-  }
-  for (const [key, spec] of Object.entries(contract.commonAttributes ?? {})) {
-    validateAttribute('common', key, spec);
-  }
-
-  return Object.freeze(contract);
-}
-
-/**
- * Resolve the effective attribute spec for `key` on `spanName`: span-specific
- * attributes win over common attributes. Returns `undefined` when the key is
- * declared nowhere.
- */
-export function resolveAttributeSpec(
-  contract: TelemetryContract,
-  spanName: string,
-  key: string,
-): AttributeSpec | undefined {
-  return (
-    contract.spans[spanName]?.attributes?.[key] ??
-    contract.commonAttributes?.[key]
-  );
-}
-
-/** Whether attributes outside the declared set are tolerated for a span. */
-export function allowsAdditionalAttributes(
-  contract: TelemetryContract,
-  spanName: string,
-): boolean {
-  return (
-    contract.spans[spanName]?.additionalAttributes ??
-    contract.additionalAttributes ??
-    false
-  );
-}

package/src/diff.ts

@@ -1,282 +0,0 @@
-/**
- * Snapshot diffing — the CI gate that catches breaking changes to your trace
- * surface before they ship.
- *
- * "If you wouldn't ship a rename to your public API without a changelog, don't
- * do it to your traces." This module is what makes that enforceable: classify
- * every change between two snapshots as breaking, additive, or neutral, and let
- * CI fail on the breaking ones.
- */
-
-import type { ContractSnapshot, SnapshotAttribute } from './snapshot.js';
-
-export type ChangeKind = 'breaking' | 'additive' | 'neutral';
-
-export type ChangeType =
-  | 'span_removed'
-  | 'span_added'
-  | 'attribute_removed'
-  | 'attribute_added'
-  | 'type_changed'
-  | 'required_added'
-  | 'required_removed'
-  | 'enum_value_removed'
-  | 'enum_value_added'
-  | 'stability_downgraded'
-  | 'stability_advanced'
-  | 'deprecated'
-  | 'replacement_documented';
-
-export interface SnapshotChange {
-  kind: ChangeKind;
-  type: ChangeType;
-  /** Span the change applies to (`*` = common attributes / contract-wide). */
-  span: string;
-  attribute?: string;
-  message: string;
-}
-
-export interface SnapshotDiff {
-  service: string;
-  previousVersion: string;
-  nextVersion: string;
-  breaking: SnapshotChange[];
-  additive: SnapshotChange[];
-  neutral: SnapshotChange[];
-}
-
-/**
- * How every cross-stability transition is classified. Keyed `prev->next` so all
- * six transitions are explicit and auditable — no silent fall-through. Same-
- * stability transitions are absent (no change to report).
- */
-const STABILITY_TRANSITIONS: Record<
-  string,
-  { kind: ChangeKind; type: ChangeType }
-> = {
-  'stable->experimental': { kind: 'breaking', type: 'stability_downgraded' },
-  'stable->deprecated': { kind: 'additive', type: 'deprecated' },
-  'experimental->stable': { kind: 'neutral', type: 'stability_advanced' },
-  'experimental->deprecated': { kind: 'additive', type: 'deprecated' },
-  'deprecated->stable': { kind: 'neutral', type: 'stability_advanced' },
-  'deprecated->experimental': { kind: 'breaking', type: 'stability_downgraded' },
-};
-
-function stabilityMessage(
-  type: ChangeType,
-  attribute: string,
-  prev: SnapshotAttribute,
-  next: SnapshotAttribute,
-): string {
-  if (type === 'deprecated') {
-    return `attribute "${attribute}" was deprecated${next.replacedBy ? ` (use "${next.replacedBy}")` : ''}`;
-  }
-  if (type === 'stability_downgraded') {
-    return `attribute "${attribute}" stability downgraded ${prev.stability} → ${next.stability}`;
-  }
-  return `attribute "${attribute}" promoted ${prev.stability} → ${next.stability}`;
-}
-
-function push(
-  diff: SnapshotDiff,
-  change: SnapshotChange,
-): void {
-  if (change.kind === 'breaking') diff.breaking.push(change);
-  else if (change.kind === 'additive') diff.additive.push(change);
-  else diff.neutral.push(change);
-}
-
-function diffAttribute(
-  diff: SnapshotDiff,
-  span: string,
-  attribute: string,
-  prev: SnapshotAttribute,
-  next: SnapshotAttribute,
-): void {
-  if (prev.type !== next.type) {
-    push(diff, {
-      kind: 'breaking',
-      type: 'type_changed',
-      span,
-      attribute,
-      message: `attribute "${attribute}" changed type ${prev.type} → ${next.type}`,
-    });
-  }
-
-  if (!prev.required && next.required) {
-    push(diff, {
-      kind: 'breaking',
-      type: 'required_added',
-      span,
-      attribute,
-      message: `attribute "${attribute}" became required`,
-    });
-  } else if (prev.required && !next.required) {
-    push(diff, {
-      kind: 'additive',
-      type: 'required_removed',
-      span,
-      attribute,
-      message: `attribute "${attribute}" is no longer required`,
-    });
-  }
-
-  // Enum: removing a permitted value can break a producer that still emits it.
-  if (prev.enum && next.enum) {
-    const nextSet = new Set(next.enum);
-    const removed = prev.enum.filter((v) => !nextSet.has(v));
-    const prevSet = new Set(prev.enum);
-    const added = next.enum.filter((v) => !prevSet.has(v));
-    if (removed.length > 0) {
-      push(diff, {
-        kind: 'breaking',
-        type: 'enum_value_removed',
-        span,
-        attribute,
-        message: `attribute "${attribute}" dropped enum value(s) ${JSON.stringify(removed)}`,
-      });
-    }
-    if (added.length > 0) {
-      push(diff, {
-        kind: 'additive',
-        type: 'enum_value_added',
-        span,
-        attribute,
-        message: `attribute "${attribute}" added enum value(s) ${JSON.stringify(added)}`,
-      });
-    }
-  }
-
-  if (prev.stability !== next.stability) {
-    const transition =
-      STABILITY_TRANSITIONS[`${prev.stability}->${next.stability}`];
-    if (transition) {
-      push(diff, {
-        ...transition,
-        span,
-        attribute,
-        message: stabilityMessage(transition.type, attribute, prev, next),
-      });
-    }
-  }
-}
-
-function diffAttributeMaps(
-  diff: SnapshotDiff,
-  span: string,
-  prev: Record<string, SnapshotAttribute>,
-  next: Record<string, SnapshotAttribute>,
-): void {
-  for (const [key, prevAttr] of Object.entries(prev)) {
-    const nextAttr = next[key];
-    if (!nextAttr) {
-      // A removed attribute whose replacement is named is a documented
-      // migration (still breaking — but reported as such with the pointer).
-      push(diff, {
-        kind: 'breaking',
-        type: prevAttr.replacedBy ? 'replacement_documented' : 'attribute_removed',
-        span,
-        attribute: key,
-        message: prevAttr.replacedBy
-          ? `attribute "${key}" removed — replaced by "${prevAttr.replacedBy}"`
-          : `attribute "${key}" was removed`,
-      });
-      continue;
-    }
-    diffAttribute(diff, span, key, prevAttr, nextAttr);
-  }
-  for (const key of Object.keys(next)) {
-    if (!prev[key]) {
-      const added = next[key];
-      // Always `attribute_added` (the event is "new attribute"); severity rides
-      // on `kind` — a new *required* attribute breaks existing producers.
-      push(diff, {
-        kind: added.required ? 'breaking' : 'additive',
-        type: 'attribute_added',
-        span,
-        attribute: key,
-        message: added.required
-          ? `new required attribute "${key}" added`
-          : `new attribute "${key}" added`,
-      });
-    }
-  }
-}
-
-/**
- * Diff two snapshots, classifying every change. The `breaking` array is what a
- * CI gate keys off; `hasBreakingChanges()` is the convenience predicate.
- */
-export function diffSnapshots(
-  previous: ContractSnapshot,
-  next: ContractSnapshot,
-): SnapshotDiff {
-  const diff: SnapshotDiff = {
-    service: next.service,
-    previousVersion: previous.version,
-    nextVersion: next.version,
-    breaking: [],
-    additive: [],
-    neutral: [],
-  };
-
-  diffAttributeMaps(diff, '*', previous.commonAttributes, next.commonAttributes);
-
-  for (const [name, prevSpan] of Object.entries(previous.spans)) {
-    const nextSpan = next.spans[name];
-    if (!nextSpan) {
-      push(diff, {
-        kind: 'breaking',
-        type: 'span_removed',
-        span: name,
-        message: `span "${name}" was removed`,
-      });
-      continue;
-    }
-    diffAttributeMaps(diff, name, prevSpan.attributes, nextSpan.attributes);
-  }
-  for (const name of Object.keys(next.spans)) {
-    if (!previous.spans[name]) {
-      push(diff, {
-        kind: 'additive',
-        type: 'span_added',
-        span: name,
-        message: `new span "${name}" added`,
-      });
-    }
-  }
-
-  return diff;
-}
-
-/** `true` when the diff contains at least one breaking change. */
-export function hasBreakingChanges(diff: SnapshotDiff): boolean {
-  return diff.breaking.length > 0;
-}
-
-/** Markdown rendering of a diff — for CI logs and PR comments. */
-export function formatDiff(diff: SnapshotDiff): string {
-  const lines: string[] = [ 
-    `# Telemetry contract diff: ${diff.service} ${diff.previousVersion} → ${diff.nextVersion}`,
-    ''];
-  const section = (title: string, changes: SnapshotChange[]) => {
-    if (changes.length === 0) return;
-    lines.push(`## ${title} (${changes.length})`, '');
-    for (const c of changes) {
-      const where = c.attribute ? `\`${c.span}.${c.attribute}\`` : `\`${c.span}\``;
-      lines.push(`- ${where}: ${c.message}`);
-    }
-    lines.push('');
-  };
-  section('💥 Breaking', diff.breaking);
-  section('➕ Additive', diff.additive);
-  section('• Neutral', diff.neutral);
-  if (
-    diff.breaking.length === 0 &&
-    diff.additive.length === 0 &&
-    diff.neutral.length === 0
-  ) {
-    lines.push('No changes to the telemetry contract.', '');
-  }
-  return lines.join('\n');
-}