autotel-eventcatalog 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,267 @@
+import { ArchitectureSnapshot, EventObservation } from 'autotel-subscribers/architecture-snapshot';
+export { ArchitectureSnapshot, EventObservation } from 'autotel-subscribers/architecture-snapshot';
+import { Channel, Event, Service } from '@eventcatalog/sdk';
+
+declare function loadSnapshot(path: string): Promise<ArchitectureSnapshot>;
+
+type SchemaConstraint = {
+    types?: string[];
+    enumValues?: unknown[];
+};
+type CatalogEvent = Event & {
+    /** Absolute path to the event's `index.mdx`, resolved via SDK. */
+    filePath: string;
+    /** Field paths declared in the event's JSON Schema (if present). */
+    declaredFieldPaths?: string[];
+    declaredSchemaConstraints?: Record<string, SchemaConstraint>;
+};
+type CatalogService = Service & {
+    filePath: string;
+};
+type CatalogChannel = Channel & {
+    filePath: string;
+};
+type CatalogState = {
+    events: Map<string, CatalogEvent>;
+    services: Map<string, CatalogService>;
+    channels: Map<string, CatalogChannel>;
+};
+declare function readCatalogState(catalogPath: string): Promise<CatalogState>;
+/**
+ * Extract field paths from a JSON Schema. Mirrors the dotted-path convention
+ * used by the snapshot subscriber: arrays collapse to `[]`, nested objects
+ * use `.`. We walk `properties` (objects) and `items` (arrays).
+ */
+declare function extractDeclaredFieldPaths(schema: unknown, prefix?: string): string[];
+
+type EventDrift = {
+    /** Event names observed in the snapshot but not present in the catalog. */
+    observedButUndocumented: string[];
+    /** Event names declared in the catalog but never observed in the snapshot. */
+    documentedButUnseen: string[];
+    /** Per-event field-path mismatches. */
+    fieldDrift: FieldDrift[];
+    /** Per-event field type mismatches against declared schema types. */
+    typeDrift: TypeDrift[];
+    /** Per-event enum/value mismatches against declared schema enums. */
+    valueDrift: ValueDrift[];
+};
+type FieldDrift = {
+    event: string;
+    /** Field paths in the observed payload but not declared in the schema. */
+    extra: string[];
+    /** Field paths declared in the schema but never observed in a payload. */
+    missing: string[];
+};
+type TypeDrift = {
+    event: string;
+    path: string;
+    declared: string[];
+    observed: string[];
+};
+type ValueDrift = {
+    event: string;
+    path: string;
+    declared: unknown[];
+    observed: unknown[];
+};
+type ServiceDrift = {
+    /** Producers in the snapshot but not present in the catalog as services. */
+    observedButUndocumented: string[];
+};
+type ChannelDrift = {
+    /** Channels in the snapshot but not present in the catalog. */
+    observedButUndocumented: string[];
+};
+type DriftReport = {
+    snapshotGeneratedAt: string;
+    snapshotService: string;
+    events: EventDrift;
+    services: ServiceDrift;
+    channels: ChannelDrift;
+};
+/** True if the report contains any drift worth surfacing in a PR check. */
+declare function hasDrift(report: DriftReport): boolean;
+/**
+ * Per-category counts for a DriftReport. Keeps the dashboard's hero meter,
+ * the CLI's summary-output, and the action's structured output all agreeing
+ * on what "N findings" means.
+ */
+type DriftCounts = {
+    /** Total of all categories — what a dashboard "drift findings" badge shows. */
+    total: number;
+    observedButUndocumentedEvents: number;
+    documentedButUnseenEvents: number;
+    /** Number of distinct events with field-path drift entries. */
+    fieldDriftEvents: number;
+    /** Sum of every individual extra + missing path across all fieldDrift entries. */
+    fieldDriftPaths: number;
+    typeDriftPaths: number;
+    valueDriftPaths: number;
+    undocumentedServices: number;
+    undocumentedChannels: number;
+};
+declare function countDriftReport(report: DriftReport): DriftCounts;
+declare function diffCatalogAgainstSnapshot(snapshot: ArchitectureSnapshot, catalog: CatalogState): DriftReport;
+
+type DriftDelta = {
+    /** Drift entries present in head but not in base. */
+    introduced: DriftEntries;
+    /** Drift entries present in base but not in head — the PR fixed these. */
+    resolved: DriftEntries;
+    /** True if `introduced` has any non-empty section. */
+    hasNewDrift: boolean;
+};
+type DriftEntries = {
+    events: {
+        observedButUndocumented: string[];
+        documentedButUnseen: string[];
+        fieldDrift: FieldDrift[];
+        typeDrift: TypeDrift[];
+        valueDrift: ValueDrift[];
+    };
+    services: {
+        observedButUndocumented: string[];
+    };
+    channels: {
+        observedButUndocumented: string[];
+    };
+};
+declare function compareDriftReports(base: DriftReport, head: DriftReport): DriftDelta;
+/**
+ * Per-category counts for one side of a DriftDelta (introduced or resolved).
+ * Same shape as DriftCounts so dashboards and CI can render the
+ * introduced/resolved sections with identical accounting.
+ */
+declare function countDriftEntries(entries: DriftEntries): DriftCounts;
+declare function countDriftDelta(delta: DriftDelta): {
+    introduced: DriftCounts;
+    resolved: DriftCounts;
+};
+
+type RenderReport = (report: DriftReport) => string;
+type RenderDelta = (delta: DriftDelta) => string;
+interface Renderer {
+    /** Short name used by the CLI's `--format` flag. */
+    readonly name: string;
+    /** One-line human description shown in CLI help and the README. */
+    readonly description: string;
+    readonly renderReport: RenderReport;
+    readonly renderDelta: RenderDelta;
+}
+
+declare function renderMarkdown(report: DriftReport): string;
+/**
+ * Render the diff-of-diffs as a PR-comment-friendly markdown block. Sections
+ * appear only when they have content, so a clean PR produces a tight message.
+ */
+declare function renderDeltaMarkdown(delta: DriftDelta): string;
+
+declare function renderTerminal(report: DriftReport): string;
+declare function renderDeltaTerminal(delta: DriftDelta): string;
+
+/**
+ * Versioned identifier baked into the JSON envelope. Bumping it is a
+ * breaking change for downstream consumers — add fields rather than rename.
+ */
+declare const REPORT_SPEC: "autotel-eventcatalog-report/v0.2.0";
+type JsonReport = {
+    mode: 'all';
+    report: DriftReport;
+} | {
+    mode: 'new-only';
+    delta: DriftDelta;
+};
+type JsonReportEnvelope = {
+    spec: typeof REPORT_SPEC;
+} & JsonReport;
+declare function renderJson(data: JsonReport): string;
+
+declare const RENDERERS: readonly Renderer[];
+declare const RENDERER_NAMES: string[];
+declare function getRenderer(name: string): Renderer | undefined;
+type RendererName = (typeof RENDERER_NAMES)[number];
+
+type DriftPolicyMode = 'all' | 'new-only';
+type PolicyEvaluationInput = {
+    mode: 'all';
+    report: DriftReport;
+} | {
+    mode: 'new-only';
+    delta: DriftDelta;
+};
+type PolicyEvaluationResult = {
+    shouldFail: boolean;
+    reason: string;
+};
+declare function evaluatePolicy(input: PolicyEvaluationInput): PolicyEvaluationResult;
+
+declare const STAMP_START = "<!-- autotel:stamp-start -->";
+declare const STAMP_END = "<!-- autotel:stamp-end -->";
+interface StampOptions {
+    /** Loaded snapshot, OR pass `loadSnapshot(path)` from the caller. */
+    snapshot: ArchitectureSnapshot;
+    /** Catalog root (the directory containing eventcatalog.config.*). */
+    catalogPath: string;
+    /** If true, do not write files — just return the diff plan. */
+    dryRun?: boolean;
+    /** Override "now" for deterministic tests. */
+    now?: () => Date;
+}
+type StampUpdate = {
+    /** Catalog event id, e.g. `OrderPlaced`. */
+    catalogId: string;
+    /** Snapshot event name, e.g. `order.placed`. */
+    snapshotName: string;
+    /** Absolute path to the mdx file that was (or would be) updated. */
+    filePath: string;
+    /** Was this an insert (no prior markers) or a replace? */
+    action: 'insert' | 'replace';
+    /**
+     * True if the proposed content differs from what's on disk. False when a
+     * replace would write byte-identical content — meaning no real change.
+     * Used by `--summary-output` so CI can answer "did this PR need stamping?"
+     * without diffing files.
+     */
+    changed: boolean;
+};
+type StampSkip = {
+    snapshotName: string;
+    reason: 'no-catalog-match';
+};
+type StampResult = {
+    updates: StampUpdate[];
+    skips: StampSkip[];
+};
+declare function stampCatalog(opts: StampOptions): Promise<StampResult>;
+/**
+ * Render the evidence block. Designed to be readable in raw mdx AND visually
+ * distinct when rendered by EventCatalog (uses the existing
+ * `.evidence-callout` class, plus a small header label).
+ */
+declare function buildStampBlock(obs: EventObservation): string;
+/** Versioned identifier for the stamp summary JSON file. */
+declare const STAMP_SUMMARY_SPEC: "autotel-eventcatalog-stamp-summary/v0.1.0";
+type StampSummary = {
+    spec: typeof STAMP_SUMMARY_SPEC;
+    dryRun: boolean;
+    /** Total snapshot events the stamp run considered (matched + skipped). */
+    attempted: number;
+    /** Skipped events (no catalog match). */
+    skipped: number;
+    /** Matched events that resulted in an insert action. */
+    inserts: number;
+    /** Matched events that resulted in a replace action. */
+    replaces: number;
+    /** Number of files whose content actually changed (or would change in dry-run). */
+    changedFiles: number;
+    /**
+     * True when the run produced (or would produce) any real change. CI can
+     * gate on this: "if the committed catalog is stamped, this should be
+     * false after running stamp; if not, the PR forgot to re-stamp."
+     */
+    hadChanges: boolean;
+};
+declare function buildStampSummary(result: StampResult, dryRun: boolean): StampSummary;
+
+export { type CatalogChannel, type CatalogEvent, type CatalogService, type CatalogState, type ChannelDrift, type DriftCounts, type DriftDelta, type DriftEntries, type DriftPolicyMode, type DriftReport, type EventDrift, type FieldDrift, type JsonReport, type JsonReportEnvelope, type PolicyEvaluationInput, type PolicyEvaluationResult, RENDERERS, RENDERER_NAMES, REPORT_SPEC, type Renderer, type RendererName, STAMP_END, STAMP_START, STAMP_SUMMARY_SPEC, type ServiceDrift, type StampOptions, type StampResult, type StampSkip, type StampSummary, type StampUpdate, buildStampBlock, buildStampSummary, compareDriftReports, countDriftDelta, countDriftEntries, countDriftReport, diffCatalogAgainstSnapshot, evaluatePolicy, extractDeclaredFieldPaths, getRenderer, hasDrift, loadSnapshot, readCatalogState, renderDeltaMarkdown, renderDeltaTerminal, renderJson, renderMarkdown, renderTerminal, stampCatalog };