autotel-schema 0.1.0

package/src/snapshot.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+
+import { defineContract, type TelemetryContract } from './contract.js';
+import {
+  diffSnapshots,
+  formatDiff,
+  hasBreakingChanges,
+} from './diff.js';
+import { highCardinalityKeys, isHighCardinalityKey } from './redaction.js';
+import {
+  contractToSnapshot,
+  parseSnapshot,
+  serializeSnapshot,
+} from './snapshot.js';
+
+const v1: TelemetryContract = defineContract({
+  service: 'checkout',
+  version: '1.0.0',
+  commonAttributes: { 'user.id': { type: 'string', highCardinality: true } },
+  spans: {
+    'checkout.charge': {
+      attributes: {
+        'payment.provider': { type: 'string', required: true },
+      },
+    },
+  },
+});
+
+describe('snapshot round-trip', () => {
+  it('is deterministic regardless of key insertion order', () => {
+    const reordered = defineContract({
+      version: '1.0.0',
+      service: 'checkout',
+      spans: {
+        'checkout.charge': {
+          attributes: { 'payment.provider': { type: 'string', required: true } },
+        },
+      },
+      commonAttributes: { 'user.id': { type: 'string', highCardinality: true } },
+    });
+    expect(serializeSnapshot(contractToSnapshot(v1))).toBe(
+      serializeSnapshot(contractToSnapshot(reordered)),
+    );
+  });
+
+  it('serializes and parses back', () => {
+    const snap = contractToSnapshot(v1);
+    expect(parseSnapshot(serializeSnapshot(snap))).toEqual(snap);
+  });
+
+  it('rejects an unknown snapshot spec', () => {
+    expect(() => parseSnapshot('{"spec":"nope/v9","service":"x","version":"1.0.0"}')).toThrowError(
+      /unexpected snapshot spec/,
+    );
+  });
+});
+
+describe('diffSnapshots', () => {
+  it('classifies a removed span as breaking', () => {
+    const v2 = defineContract({ ...v1, version: '2.0.0', spans: {} });
+    const diff = diffSnapshots(contractToSnapshot(v1), contractToSnapshot(v2));
+    expect(hasBreakingChanges(diff)).toBe(true);
+    expect(diff.breaking.some((c) => c.type === 'span_removed')).toBe(true);
+    expect(formatDiff(diff)).toMatch(/1\.0\.0 → 2\.0\.0/);
+  });
+
+  it('classifies a new span as additive, not breaking', () => {
+    const v2 = defineContract({
+      ...v1,
+      version: '1.1.0',
+      spans: {
+        ...v1.spans,
+        'checkout.refund': { attributes: {} },
+      },
+    });
+    const diff = diffSnapshots(contractToSnapshot(v1), contractToSnapshot(v2));
+    expect(hasBreakingChanges(diff)).toBe(false);
+    expect(diff.additive.some((c) => c.type === 'span_added')).toBe(true);
+  });
+});
+
+describe('redaction helpers', () => {
+  it('collects high-cardinality keys across common + span attributes', () => {
+    expect(highCardinalityKeys(v1)).toEqual(['user.id']);
+    expect(isHighCardinalityKey(v1, 'user.id')).toBe(true);
+    expect(isHighCardinalityKey(v1, 'payment.provider')).toBe(false);
+  });
+});

package/src/snapshot.ts

@@ -0,0 +1,119 @@
+/**
+ * Snapshots — the serializable form of a contract that gets committed and
+ * diffed across versions. Checking a snapshot into the repo turns "did this
+ * refactor rename a span?" into a reviewable line in a PR instead of a silent
+ * break the agent reader discovers at 3am.
+ */
+
+import { SNAPSHOT_SPEC } from './attrs.js';
+import type {
+  AttributeSpec,
+  AttributeType,
+  Stability,
+  TelemetryContract,
+} from './contract.js';
+
+/** Flattened, fully-resolved attribute record in a snapshot. */
+export interface SnapshotAttribute {
+  type: AttributeType;
+  stability: Stability;
+  required: boolean;
+  highCardinality: boolean;
+  enum?: readonly (string | number)[];
+  replacedBy?: string;
+  description?: string;
+}
+
+export interface SnapshotSpan {
+  stability: Stability;
+  additionalAttributes: boolean;
+  description?: string;
+  attributes: Record<string, SnapshotAttribute>;
+}
+
+/** Canonical, comparable representation of a {@link TelemetryContract}. */
+export interface ContractSnapshot {
+  spec: typeof SNAPSHOT_SPEC;
+  service: string;
+  version: string;
+  commonAttributes: Record<string, SnapshotAttribute>;
+  spans: Record<string, SnapshotSpan>;
+}
+
+function normalizeAttribute(spec: AttributeSpec): SnapshotAttribute {
+  const out: SnapshotAttribute = {
+    type: spec.type,
+    stability: spec.stability ?? 'stable',
+    required: spec.required ?? false,
+    highCardinality: spec.highCardinality ?? false,
+  };
+  if (spec.enum) out.enum = [...spec.enum];
+  if (spec.replacedBy) out.replacedBy = spec.replacedBy;
+  if (spec.description) out.description = spec.description;
+  return out;
+}
+
+function sortRecord<T>(record: Record<string, T>): Record<string, T> {
+  const out: Record<string, T> = {};
+  for (const key of Object.keys(record).toSorted()) {
+    out[key] = record[key];
+  }
+  return out;
+}
+
+/**
+ * Produce a deterministic, JSON-serializable snapshot from a contract. Keys are
+ * sorted so two snapshots of the same logical contract are byte-identical —
+ * important for clean `git diff`s and stable CI comparisons.
+ */
+export function contractToSnapshot(
+  contract: TelemetryContract,
+): ContractSnapshot {
+  const commonAttributes: Record<string, SnapshotAttribute> = {};
+  for (const [key, spec] of Object.entries(contract.commonAttributes ?? {})) {
+    commonAttributes[key] = normalizeAttribute(spec);
+  }
+
+  const spans: Record<string, SnapshotSpan> = {};
+  for (const [name, spanSpec] of Object.entries(contract.spans)) {
+    const attributes: Record<string, SnapshotAttribute> = {};
+    for (const [key, spec] of Object.entries(spanSpec.attributes ?? {})) {
+      attributes[key] = normalizeAttribute(spec);
+    }
+    const span: SnapshotSpan = {
+      stability: spanSpec.stability ?? 'stable',
+      additionalAttributes:
+        spanSpec.additionalAttributes ?? contract.additionalAttributes ?? false,
+      attributes: sortRecord(attributes),
+    };
+    if (spanSpec.description) span.description = spanSpec.description;
+    spans[name] = span;
+  }
+
+  return {
+    spec: SNAPSHOT_SPEC,
+    service: contract.service,
+    version: contract.version,
+    commonAttributes: sortRecord(commonAttributes),
+    spans: sortRecord(spans),
+  };
+}
+
+/** Pretty, deterministic JSON for writing a snapshot to disk. */
+export function serializeSnapshot(snapshot: ContractSnapshot): string {
+  return JSON.stringify(snapshot, null, 2) + '\n';
+}
+
+/** Parse and structurally validate a snapshot read from disk. */
+export function parseSnapshot(json: string): ContractSnapshot {
+  const data = JSON.parse(json) as ContractSnapshot;
+  if (data.spec !== SNAPSHOT_SPEC) {
+    throw new Error(
+      `autotel-schema: unexpected snapshot spec "${data.spec}" (expected "${SNAPSHOT_SPEC}")`,
+    );
+  }
+  if (typeof data.service !== 'string' || typeof data.version !== 'string') {
+    throw new Error('autotel-schema: snapshot is missing service/version');
+  }
+  return data;
+}

package/src/validate.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+
+import { defineContract, type TelemetryContract } from './contract.js';
+import {
+  formatViolation,
+  hasErrors,
+  validateSpan,
+} from './validate.js';
+
+const contract: TelemetryContract = defineContract({
+  service: 'checkout',
+  version: '1.0.0',
+  commonAttributes: { 'user.id': { type: 'string' } },
+  spans: {
+    'checkout.charge': {
+      attributes: {
+        'payment.provider': { type: 'string', required: true, enum: ['stripe', 'paypal'] },
+        'payment.amount_cents': { type: 'number', required: true },
+      },
+    },
+  },
+});
+
+describe('validateSpan', () => {
+  it('passes a fully-conformant span', () => {
+    const v = validateSpan(
+      {
+        name: 'checkout.charge',
+        attributes: { 'payment.provider': 'stripe', 'payment.amount_cents': 999 },
+      },
+      contract,
+    );
+    expect(v).toEqual([]);
+  });
+
+  it('flags a missing required attribute as an error', () => {
+    const v = validateSpan(
+      { name: 'checkout.charge', attributes: { 'payment.provider': 'stripe' } },
+      contract,
+    );
+    expect(v).toHaveLength(1);
+    expect(v[0]).toMatchObject({ code: 'missing_required', attribute: 'payment.amount_cents' });
+    expect(hasErrors(v)).toBe(true);
+  });
+
+  it('flags a wrong type', () => {
+    const v = validateSpan(
+      {
+        name: 'checkout.charge',
+        attributes: { 'payment.provider': 'stripe', 'payment.amount_cents': '999' },
+      },
+      contract,
+    );
+    expect(v.some((x) => x.code === 'type_mismatch')).toBe(true);
+  });
+
+  it('flags an enum violation', () => {
+    const v = validateSpan(
+      {
+        name: 'checkout.charge',
+        attributes: { 'payment.provider': 'bitcoin', 'payment.amount_cents': 1 },
+      },
+      contract,
+    );
+    expect(v.some((x) => x.code === 'enum_violation')).toBe(true);
+  });
+
+  it('warns on an undeclared attribute and suggests a near key', () => {
+    const v = validateSpan(
+      {
+        name: 'checkout.charge',
+        attributes: {
+          'payment.provider': 'stripe',
+          'payment.amount_cents': 1,
+          'payment.providr': 'x', // typo of a declared key
+        },
+      },
+      contract,
+    );
+    const unknown = v.find((x) => x.code === 'unknown_attribute');
+    expect(unknown?.severity).toBe('warning');
+    expect(unknown?.suggestion).toBe('payment.provider');
+  });
+
+  it('ignores unknown spans unless strictSpanNames is set', () => {
+    expect(validateSpan({ name: 'mystery', attributes: {} }, contract)).toEqual([]);
+    const strict = validateSpan({ name: 'mystery', attributes: {} }, contract, {
+      strictSpanNames: true,
+    });
+    expect(strict[0]?.code).toBe('unknown_span');
+  });
+
+  it('formats a violation legibly', () => {
+    const v = validateSpan(
+      { name: 'checkout.charge', attributes: { 'payment.provider': 'stripe' } },
+      contract,
+    );
+    expect(formatViolation(v[0])).toMatch(/\[error\] missing_required @ checkout.charge.payment.amount_cents/);
+  });
+});

package/src/validate.ts

@@ -0,0 +1,237 @@
+/**
+ * Pure span-vs-contract validation. No SDK, no side effects — the same engine
+ * the runtime processor ({@link ./processor}) and any test harness can call.
+ */
+
+import {
+  allowsAdditionalAttributes,
+  resolveAttributeSpec,
+  type AttributeSpec,
+  type AttributeType,
+  type TelemetryContract,
+} from './contract.js';
+
+/** Severity of a contract violation. `error` = a breaking-shaped problem. */
+export type ViolationSeverity = 'error' | 'warning';
+
+export type ViolationCode =
+  | 'unknown_span'
+  | 'unknown_attribute'
+  | 'type_mismatch'
+  | 'missing_required'
+  | 'deprecated_attribute'
+  | 'enum_violation';
+
+/** A single discrepancy between an emitted span and the contract. */
+export interface SchemaViolation {
+  code: ViolationCode;
+  severity: ViolationSeverity;
+  spanName: string;
+  /** Attribute key involved, when the violation is attribute-scoped. */
+  attribute?: string;
+  message: string;
+  /** Nearest declared key, for likely typos (`unknown_attribute` only). */
+  suggestion?: string;
+}
+
+/** Minimal emitted-span shape — avoids a hard dependency on the OTel SDK. */
+export interface SpanShape {
+  name: string;
+  attributes: Record<string, unknown>;
+}
+
+export interface ValidateOptions {
+  /** Report `unknown_span` for span names not in the contract. Default `false`. */
+  strictSpanNames?: boolean;
+}
+
+/** `'empty[]'` is a distinct marker: an empty array satisfies any array type. */
+function actualType(value: unknown): AttributeType | 'empty[]' | 'unknown' {
+  if (typeof value === 'string') return 'string';
+  if (typeof value === 'number') return 'number';
+  if (typeof value === 'boolean') return 'boolean';
+  if (Array.isArray(value)) {
+    const first = value.find((v) => v !== null && v !== undefined);
+    if (first === undefined) return 'empty[]';
+    if (typeof first === 'string') return 'string[]';
+    if (typeof first === 'number') return 'number[]';
+    if (typeof first === 'boolean') return 'boolean[]';
+  }
+  return 'unknown';
+}
+
+function typeMatches(expected: AttributeType, value: unknown): boolean {
+  const actual = actualType(value);
+  if (actual === 'unknown') return false;
+  if (actual === 'empty[]') return expected.endsWith('[]');
+  return actual === expected;
+}
+
+/** Levenshtein distance — small, allocation-light, good enough for key typos. */
+function editDistance(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = Array.from({ length: n + 1 }, (_, i) => i);
+  let curr = Array.from<number>({ length: n + 1 });
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}
+
+/**
+ * Closest declared key to `key`, when one is within a small edit distance.
+ * Turns "you emitted an attribute I don't know" into "did you mean `user.id`?".
+ */
+function nearestKey(key: string, candidates: string[]): string | undefined {
+  let best: string | undefined;
+  let bestDistance = Infinity;
+  const threshold = Math.max(1, Math.floor(key.length / 4) + 1);
+  for (const candidate of candidates) {
+    const d = editDistance(key, candidate);
+    if (d < bestDistance && d <= threshold) {
+      best = candidate;
+      bestDistance = d;
+    }
+  }
+  return best;
+}
+
+function declaredKeysFor(
+  contract: TelemetryContract,
+  spanName: string,
+): string[] {
+  return [
+    ...Object.keys(contract.spans[spanName]?.attributes ?? {}),
+    ...Object.keys(contract.commonAttributes ?? {}),
+  ];
+}
+
+function checkValue(
+  spanName: string,
+  key: string,
+  value: unknown,
+  spec: AttributeSpec,
+  out: SchemaViolation[],
+): void {
+  if (!typeMatches(spec.type, value)) {
+    out.push({
+      code: 'type_mismatch',
+      severity: 'error',
+      spanName,
+      attribute: key,
+      message: `attribute "${key}" should be ${spec.type} but got ${actualType(value)}`,
+    });
+    return; // a wrong type makes enum/deprecation checks noise
+  }
+  if (spec.enum && (typeof value === 'string' || typeof value === 'number') && !spec.enum.includes(value)) {
+      out.push({
+        code: 'enum_violation',
+        severity: 'error',
+        spanName,
+        attribute: key,
+        message: `attribute "${key}" value ${JSON.stringify(value)} is not one of ${JSON.stringify(spec.enum)}`,
+      });
+    }
+  if (spec.stability === 'deprecated') {
+    const hint = spec.replacedBy
+      ? ` — use "${spec.replacedBy}" instead`
+      : spec.deprecatedReason
+        ? ` — ${spec.deprecatedReason}`
+        : '';
+    out.push({
+      code: 'deprecated_attribute',
+      severity: 'warning',
+      spanName,
+      attribute: key,
+      message: `attribute "${key}" is deprecated${hint}`,
+      suggestion: spec.replacedBy,
+    });
+  }
+}
+
+/**
+ * Validate one emitted span against the contract, returning every discrepancy.
+ * Order is deterministic: required-but-missing first, then per-attribute checks
+ * in attribute insertion order.
+ */
+export function validateSpan(
+  span: SpanShape,
+  contract: TelemetryContract,
+  options: ValidateOptions = {},
+): SchemaViolation[] {
+  const out: SchemaViolation[] = [];
+  const spanSpec = contract.spans[span.name];
+
+  if (!spanSpec) {
+    if (options.strictSpanNames) {
+      out.push({
+        code: 'unknown_span',
+        severity: 'warning',
+        spanName: span.name,
+        message: `span "${span.name}" is not declared in the contract`,
+      });
+    }
+    return out; // unknown span → no attribute contract to check against
+  }
+
+  // Required attributes that never showed up.
+  const required = [
+    ...Object.entries(spanSpec.attributes ?? {}),
+    ...Object.entries(contract.commonAttributes ?? {}),
+  ].filter(([, spec]) => spec.required);
+  for (const [key] of required) {
+    if (!(key in span.attributes)) {
+      out.push({
+        code: 'missing_required',
+        severity: 'error',
+        spanName: span.name,
+        attribute: key,
+        message: `required attribute "${key}" is missing`,
+      });
+    }
+  }
+
+  const allowExtra = allowsAdditionalAttributes(contract, span.name);
+  const declared = allowExtra ? [] : declaredKeysFor(contract, span.name);
+
+  for (const [key, value] of Object.entries(span.attributes)) {
+    if (value === null || value === undefined) continue;
+    const spec = resolveAttributeSpec(contract, span.name, key);
+    if (!spec) {
+      if (!allowExtra) {
+        out.push({
+          code: 'unknown_attribute',
+          severity: 'warning',
+          spanName: span.name,
+          attribute: key,
+          message: `attribute "${key}" is not declared on span "${span.name}"`,
+          suggestion: nearestKey(key, declared),
+        });
+      }
+      continue;
+    }
+    checkValue(span.name, key, value, spec, out);
+  }
+
+  return out;
+}
+
+/** `true` when any violation is `error` severity. */
+export function hasErrors(violations: SchemaViolation[]): boolean {
+  return violations.some((v) => v.severity === 'error');
+}
+
+/** One-line human/agent-readable rendering of a violation. */
+export function formatViolation(v: SchemaViolation): string {
+  const where = v.attribute ? `${v.spanName}.${v.attribute}` : v.spanName;
+  const suffix = v.suggestion ? ` (did you mean "${v.suggestion}"?)` : '';
+  return `[${v.severity}] ${v.code} @ ${where}: ${v.message}${suffix}`;
+}