autotel-eventcatalog 1.0.0

package/docs/EXTENDING.md

@@ -0,0 +1,248 @@
+# Extending autotel-eventcatalog
+
+The package is designed to be extended in **one** direction: new
+renderers. Everything else (the diff engine, the policy layer, the
+stamper) is deliberately stable. See [CONTRIBUTING.md](../CONTRIBUTING.md#3-no-domain-specific-extensions-to-the-core)
+for why.
+
+## Writing a custom renderer
+
+A renderer is a small adapter that turns a drift result into output
+text. The built-ins are `markdown`, `terminal`, and `json`. To add a new
+one (e.g. SARIF, Slack-flavoured markdown, GitHub Check Runs API JSON,
+your in-house dashboard payload), implement the `Renderer` interface and
+register it.
+
+### Step 1: implement the interface
+
+```typescript
+// src/renderers/sarif.ts
+import type { DriftReport } from '../diff';
+import type { DriftDelta } from '../diff-vs-base';
+import type { Renderer } from './types';
+
+function renderReport(report: DriftReport): string {
+  // SARIF (https://sarifweb.azurewebsites.net) wants a fixed envelope
+  // with `runs[].results[]`. Each drift finding becomes one result.
+  const results = [
+    ...report.events.observedButUndocumented.map((name) => ({
+      ruleId: 'autotel/event-undocumented',
+      level: 'warning',
+      message: { text: `Event \`${name}\` is emitted but not documented.` },
+      locations: [
+        {
+          physicalLocation: {
+            artifactLocation: { uri: `events/${name}` },
+          },
+        },
+      ],
+    })),
+    // ... documented-but-unseen, field drift, services, channels
+  ];
+
+  return JSON.stringify(
+    {
+      version: '2.1.0',
+      $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+      runs: [
+        {
+          tool: {
+            driver: {
+              name: 'autotel-eventcatalog',
+              informationUri: 'https://github.com/jagreehal/autotel',
+            },
+          },
+          results,
+        },
+      ],
+    },
+    null,
+    2,
+  );
+}
+
+function renderDelta(delta: DriftDelta): string {
+  // For PR-mode runs, emit results only for `delta.introduced`.
+  // ... similar shape ...
+  return JSON.stringify({
+    /* ... */
+  });
+}
+
+export const sarifRenderer: Renderer = {
+  name: 'sarif',
+  description:
+    'Static Analysis Results Interchange Format (GitHub Code Scanning).',
+  renderReport,
+  renderDelta,
+};
+```
+
+### Step 2: register it
+
+Add the renderer to the registry in `src/renderers/index.ts`:
+
+```typescript
+import { sarifRenderer } from './sarif';
+
+export const RENDERERS: readonly Renderer[] = [
+  markdownRenderer,
+  terminalRenderer,
+  jsonRenderer,
+  sarifRenderer, // ← new
+];
+```
+
+That's it. The CLI's `--format sarif` will automatically work, the help
+text will mention it, and the validator that catches bad `--format`
+values will accept it.
+
+### Step 3: write the tests
+
+```typescript
+// src/renderers/sarif.test.ts
+import { describe, it, expect } from 'vitest';
+import { sarifRenderer } from './sarif';
+import type { DriftReport } from '../diff';
+
+const driftyReport: DriftReport = {
+  snapshotGeneratedAt: '2026-05-22T00:00:00.000Z',
+  snapshotService: 'fixture',
+  events: {
+    observedButUndocumented: ['order.cancelled'],
+    documentedButUnseen: [],
+    fieldDrift: [],
+  },
+  services: { observedButUndocumented: [] },
+  channels: { observedButUndocumented: [] },
+};
+
+describe('sarifRenderer', () => {
+  it('emits a valid SARIF v2.1.0 envelope', () => {
+    const out = JSON.parse(sarifRenderer.renderReport(driftyReport));
+    expect(out.version).toBe('2.1.0');
+    expect(out.runs[0].tool.driver.name).toBe('autotel-eventcatalog');
+    expect(out.runs[0].results).toHaveLength(1);
+    expect(out.runs[0].results[0].ruleId).toBe('autotel/event-undocumented');
+  });
+});
+```
+
+### Step 4 (optional): document it
+
+If the renderer is going to be a first-class citizen, add a row to the
+"Renderers" section in the README and bump the changeset (`pnpm
+changeset`).
+
+## What a good renderer looks like
+
+- **Pure function from input to string.** No I/O, no globals, no side
+  effects. The CLI is responsible for writing output; the renderer is
+  responsible for shaping it.
+- **Handles both `renderReport` and `renderDelta`.** Even if you don't
+  care about the delta mode, return _something_. Clean delta output is
+  often "no new findings" plus the resolved section.
+- **Self-contained.** A renderer should not import from `cli.ts`, from
+  `policy.ts`, or from another renderer's internals. The core types
+  (`DriftReport`, `DriftDelta`) are the only contract.
+- **Deterministic.** Same input, same output. No timestamps from
+  `Date.now()`, no random IDs. (The snapshot already carries
+  `snapshotGeneratedAt` if you need a timestamp.)
+- **Compact.** The Markdown renderer is ~120 lines. If yours is
+  significantly longer, you're probably doing logic that belongs in
+  the core. Push back to the renderer interface.
+
+## When NOT to write a renderer
+
+- **"I want to send drift to my dashboard."** Don't write a renderer for
+  that. Your dashboard should poll the snapshot/drift endpoints (or
+  parse the JSON envelope on its own). Renderers are for tools that
+  consume the _output_, not the _event stream_.
+- **"I want to gate CI differently."** That's a policy concern, not a
+  rendering concern. See `policy.ts` and `evaluatePolicy`.
+- **"I want field-level severity (P0/P1/P2)."** Severity classification
+  is a policy decision that the renderer applies. A SARIF renderer can
+  map every drift category to a SARIF level; that mapping lives in the
+  renderer, not in the core types.
+
+## A larger example: Slack Block Kit
+
+```typescript
+// src/renderers/slack.ts
+import type { DriftReport } from '../diff';
+import type { DriftDelta } from '../diff-vs-base';
+import { countDriftReport } from '../diff';
+import type { Renderer } from './types';
+
+export const slackRenderer: Renderer = {
+  name: 'slack',
+  description: 'Slack Block Kit JSON. Post directly to a webhook.',
+  renderReport(report) {
+    const counts = countDriftReport(report);
+    return JSON.stringify({
+      blocks: [
+        {
+          type: 'header',
+          text: { type: 'plain_text', text: `${counts.total} drift findings` },
+        },
+        {
+          type: 'section',
+          text: {
+            type: 'mrkdwn',
+            text:
+              report.events.observedButUndocumented.length > 0
+                ? `*Undocumented:* ${report.events.observedButUndocumented.map((n) => `\`${n}\``).join(', ')}`
+                : '_No new events to document._',
+          },
+        },
+      ],
+    });
+  },
+  renderDelta(delta) {
+    /* ... */
+    return JSON.stringify({ blocks: [] });
+  },
+};
+```
+
+Register, test, ship. Now `--format slack` produces JSON you can `curl`
+straight to a Slack webhook URL.
+
+## Library-mode renderers (out-of-tree)
+
+If you don't want to upstream your renderer, the library API lets you
+plug one in at runtime in your own code:
+
+```typescript
+import {
+  diffCatalogAgainstSnapshot,
+  readCatalogState,
+  loadSnapshot,
+} from 'autotel-eventcatalog';
+import { myRenderer } from './my-renderer';
+
+const snapshot = await loadSnapshot('./snapshot.json');
+const catalog = await readCatalogState('./catalog');
+const report = diffCatalogAgainstSnapshot(snapshot, catalog);
+
+console.log(myRenderer.renderReport(report));
+```
+
+You don't have to modify the package to use your own renderer. Upstreaming
+is for when the renderer has general value to other users.
+
+## What's NOT extendable (and why)
+
+| Surface             | Extension allowed?            | Why                                                                                                       |
+| ------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Renderers           | Yes (registry pattern)        | Output targets vary; core data does not                                                                   |
+| New CLI commands    | No (without a user)           | See [CONTRIBUTING.md invariant #1](../CONTRIBUTING.md#1-no-new-top-level-commands-without-a-user)         |
+| New diff categories | No (without ecosystem buy-in) | Each category cascades through diff/delta/counts/renderers/schemas                                        |
+| Custom policies     | Yes, but file an issue first  | `evaluatePolicy` is small; an extension might earn its place but probably wants a new policy mode in core |
+| Snapshot format     | No                            | Owned by `autotel-subscribers`; this package only consumes                                                |
+| Stamp marker syntax | No                            | Backwards compatibility with previously-stamped catalogs                                                  |
+
+If you find yourself wanting to extend something marked "no", the answer
+is almost always: file an issue describing the use case, and we'll figure
+out whether it belongs in this package, in `autotel-subscribers`, in a
+new sister package, or in your own downstream code.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,220 @@
+# Troubleshooting
+
+## Exit codes
+
+The `drift` CLI exits with a documented set of codes:
+
+| Code  | Meaning        | When                                                               |
+| ----- | -------------- | ------------------------------------------------------------------ |
+| `0`   | Clean          | No drift, OR drift exists but `--fail-on-drift` was not set        |
+| `1`   | Drift detected | `--fail-on-drift` was set AND the policy decided this is a failure |
+| `2`   | Bad arguments  | Missing required flag, unknown flag, invalid value                 |
+| other | Hard error     | The CLI itself crashed; surface the stderr                         |
+
+The `stamp` CLI exits `0` on success, `2` on bad arguments. It does not
+have a drift-style failure mode; it either writes or it doesn't.
+
+**If you wrap the CLI in a script:** check for codes 0/1 as expected
+behaviour and treat anything else as a hard error to surface. The
+[bundled action](../action.yml) does exactly this.
+
+## Common errors
+
+### "Both --snapshot and --catalog are required."
+
+You omitted one of the two required arguments. Either is fine to forget;
+the message says which.
+
+### "--policy new-only requires --base-snapshot."
+
+`--policy new-only` compares your current snapshot against a baseline.
+Without a baseline, there's no "new" to compute. Either:
+
+- Drop `--policy new-only` (defaults to `all` without a baseline), or
+- Add `--base-snapshot <path>` pointing to the baseline snapshot.
+
+In the GitHub Action, the baseline is fetched automatically from the PR's
+base branch; supply `base-ref: origin/${{ github.base_ref }}`.
+
+### "Invalid --format value: foo. Available renderers: markdown, terminal, json."
+
+`--format` accepts a renderer name registered in
+`src/renderers/index.ts`. If you added a custom renderer, it needs to be
+in `RENDERERS`. See [EXTENDING.md](EXTENDING.md).
+
+### "autotel-eventcatalog did not produce a summary output."
+
+The action's drift step expected `--summary-output` to write a file but
+couldn't find it after the CLI exited. The CLI itself probably crashed
+_before_ writing the summary. Check stderr in the job log; the error
+is up there.
+
+### "Not an autotel architecture snapshot (missing spec marker)"
+
+The file you passed to `--snapshot` doesn't look like a snapshot. It
+needs to:
+
+- Be valid JSON
+- Have a `spec` field starting with `autotel-architecture/`
+
+If the file is empty or zero-bytes, the snapshot subscriber probably
+didn't run. Verify your test suite (or whatever produces the snapshot)
+finished and wrote to disk before the CLI ran.
+
+### Drift CLI reports events I expect to be in the catalog
+
+The catalog reader walks `<catalog>/**/index.mdx` looking for an `id:`
+field in the frontmatter. If your event mdx files use a different
+filename or don't have proper frontmatter, they're invisible.
+
+Check:
+
+1. The event mdx file is named `index.mdx` (not `event.mdx`, not
+   `OrderPlaced.mdx`).
+2. The path matches `.../events/<X>/index.mdx`.
+3. The frontmatter has an `id:` (matched case-insensitively, with dots
+   and underscores normalised).
+
+### Drift CLI doesn't see field-path drift even though I know it exists
+
+Field-path drift is only computed for events with a `schemaPath:` in
+their frontmatter. If your event mdx doesn't declare a schema, the
+field-path check is skipped (you'll only get existence checks).
+
+To enable field-path drift:
+
+```yaml
+---
+id: OrderPlaced
+schemaPath: schema.json # ← relative to the event mdx
+---
+```
+
+The schema file needs to be a JSON Schema with `properties` keys and
+(optionally) nested `items` for arrays.
+
+### Stamp output looks weird / duplicated
+
+Stamps are scoped to the markers:
+
+```
+<!-- autotel:stamp-start -->
+...
+<!-- autotel:stamp-end -->
+```
+
+If you see duplicate stamp blocks, either:
+
+- Someone manually copied the marker pair without realising they're
+  load-bearing, or
+- A previous run was interrupted before completing.
+
+Fix: delete the malformed marker pair manually, then re-run `stamp`. The
+stamp command will detect the first `<!-- autotel:stamp-start -->` and
+the first `<!-- autotel:stamp-end -->` and replace between them; manual
+cleanup is only needed if those don't bracket the block correctly.
+
+### `pnpm catalog:stamp` failed but my catalog wasn't updated
+
+`stamp` is mostly read-only (it reads the snapshot, reads the catalog,
+plans what to write, then writes). If it fails mid-flight, you may
+have a few files updated and the rest not.
+
+The stamp summary JSON (`--summary-output`) tells you exactly which files
+were inserts vs. replaces vs. skipped. Compare against your git status to
+see what landed.
+
+### The action posted no comment on my PR
+
+Three possibilities:
+
+1. **The repository doesn't allow comments from Actions.** Check
+   `Settings > Actions > General > Workflow permissions`. Needs
+   "Read and write permissions" or at least the `pull-requests: write`
+   permission in the workflow file.
+2. **The sticky-comment action failed.** With
+   `continue-on-comment-failure: true` (the default), this is a
+   warning, not a failure. Look for the warning in the job log.
+3. **You're not running on a `pull_request` event.** The action only
+   comments on PRs. On push events, it'll still run and write the
+   summary file, but the comment step is skipped.
+
+### "autotel-eventcatalog drift CLI failed with exit $STATUS"
+
+Any non-0, non-1 exit code from the CLI surfaces as a hard error in the
+action. Look for the CLI output above this line in the job log; the
+CLI's stderr will explain.
+
+## Debugging tips
+
+### See exactly what the catalog reader found
+
+Add this to your local script:
+
+```typescript
+import { readCatalogState } from 'autotel-eventcatalog';
+
+const state = await readCatalogState('./catalog');
+console.log('events:', [...state.events.keys()]);
+console.log('services:', [...state.services.keys()]);
+console.log('channels:', [...state.channels.keys()]);
+```
+
+If your event isn't listed, the reader didn't pick it up. Check the
+filename, the frontmatter, and (on Windows) make sure the path
+contains valid `services/.../events/` segments.
+
+### See what the snapshot looked like
+
+```bash
+# Pretty-print, restricted to the event you care about:
+node -e "const s=JSON.parse(require('fs').readFileSync('snapshot.json','utf8'));console.log(JSON.stringify(s.events['order.placed'],null,2))"
+```
+
+### Reproduce a CI failure locally
+
+```bash
+# Same flags the bundled action passes internally:
+pnpm autotel-eventcatalog drift \
+  --snapshot ./services/test/snapshot.json \
+  --catalog ./catalog \
+  --policy all \
+  --output ./drift.md \
+  --summary-output ./drift-summary.json \
+  --fail-on-drift
+echo "exit: $?"
+cat drift-summary.json
+```
+
+If this reproduces locally with the same exit code and the same
+summary, you've isolated the issue from CI-specific state.
+
+### Reset to a known clean state
+
+If you suspect the working tree has gone weird (e.g. partial stamp
+runs), the surest reset is:
+
+```bash
+git restore apps/example-eventcatalog/catalog
+git clean -fd apps/example-eventcatalog/catalog
+pnpm services:snapshot
+pnpm catalog:stamp
+```
+
+After that, `git status` should show the catalog unchanged. If it
+doesn't, your snapshot has changed since the last commit; that's an
+intended diff, not a tooling problem.
+
+## Still stuck?
+
+Open an issue with:
+
+- The exact command you ran
+- The stderr output (full)
+- The exit code
+- The `spec:` field from your snapshot, drift report, or stamp summary
+- Your Node version and OS
+
+Most issues turn out to be one of: missing frontmatter, missing
+schemaPath, paths not normalised on Windows, or the action being asked
+to comment without `pull-requests: write` permission.

package/docs/UPGRADING.md

@@ -0,0 +1,202 @@
+# Upgrading
+
+The package follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+for the **npm package version** and for the **JSON contract version**
+(the `vX.Y.Z` segment in each schema's `$id`).
+
+These two versions usually move together but are conceptually
+independent. The npm version changes when _any_ user-facing thing
+changes (CLI flags, library exports, action inputs). The contract
+version changes only when one of the **three published JSON shapes**
+changes.
+
+## Quick reference
+
+| Change                                          | npm version | Contract version                 |
+| ----------------------------------------------- | ----------- | -------------------------------- |
+| Bug fix, internal refactor                      | patch       | unchanged                        |
+| New optional CLI flag, new library export       | minor       | unchanged                        |
+| New optional field in a JSON output             | minor       | minor                            |
+| Renamed / removed JSON field, changed JSON type | major       | major                            |
+| Removed CLI flag, removed library export        | major       | unchanged (if JSON shape stable) |
+| Changed CLI exit code semantics                 | major       | unchanged                        |
+
+## Reading the version
+
+Three places to look:
+
+1. **`package.json`**: the npm version. `pnpm list autotel-eventcatalog`
+   from your project root.
+2. **The `spec:` field on every JSON output**: the contract version.
+3. **The schema URLs** in `schemas/`: the contract version, with
+   `https://autotel.dev/schemas/...` so downstream tooling can validate
+   without depending on the npm package.
+
+## Patch upgrade (e.g. `0.1.0 → 0.1.1`)
+
+Bug fixes, internal refactors, dependency updates.
+
+**What you do:** `pnpm update autotel-eventcatalog`. Nothing else.
+
+**What might happen:** Behaviour changes that you weren't relying on
+(e.g. an error message wording, the order of items in stderr logs).
+Real public-API behaviour is preserved.
+
+## Minor upgrade (e.g. `0.1.0 → 0.2.0`)
+
+New optional CLI flags, new optional fields in JSON outputs, new
+renderers in the registry, new exported types or functions.
+
+**What you do:** `pnpm update autotel-eventcatalog`.
+
+**What might happen:**
+
+- A new field shows up in the JSON output. Existing parsers that ignore
+  unknown fields keep working. Parsers that explicitly reject unknown
+  fields (some strict schema validators) need to bump the schema they
+  validate against.
+- A new renderer becomes available via `--format`. Existing `--format
+markdown` / `--format json` calls keep working.
+- A new library export exists. Existing imports keep working.
+
+**Validating after a minor JSON upgrade**
+
+If you're using a strict validator (`additionalProperties: false` in
+your own schema, for example), you'll want to point it at the new
+schema file:
+
+```diff
+- import schema from 'autotel-eventcatalog/schemas/drift-summary-v0.1.0.json';
++ import schema from 'autotel-eventcatalog/schemas/drift-summary-v0.2.0.json';
+```
+
+If you're using `oneOf` on the `spec:` field, add the new value:
+
+```diff
+  if (![
+    'autotel-eventcatalog-drift-summary/v0.1.0',
++   'autotel-eventcatalog-drift-summary/v0.2.0',
+  ].includes(summary.spec)) {
+    throw new Error(`Unknown drift summary version: ${summary.spec}`);
+  }
+```
+
+## Major upgrade (e.g. `0.x → 1.0.0` or `1.x → 2.0.0`)
+
+Breaking changes: renamed JSON fields, removed CLI flags, changed
+behaviour.
+
+**What you do:** read the CHANGELOG, update your code or workflow, then
+`pnpm update autotel-eventcatalog`.
+
+Major upgrades within `0.x` (e.g. `0.1.0 → 0.2.0` if it ever ships as a
+breaking change) are signalled by the **JSON contract spec version**,
+not just by the npm version. The package version may bump in lockstep,
+but the contract version is what your downstream consumers need to know
+about.
+
+**A worked example.** Imagine v1.0.0 renames `counts.total` to
+`counts.findings` in the drift summary. Steps:
+
+1. **Detect the mismatch.** Your consumer's `spec:` check catches it:
+
+   ```typescript
+   if (summary.spec !== 'autotel-eventcatalog-drift-summary/v0.1.0') {
+     throw new Error(
+       `Drift summary spec ${summary.spec} is not v0.1.0; refusing to parse.`,
+     );
+   }
+   ```
+
+   The throw is the signal to read the upgrade notes.
+
+2. **Read the CHANGELOG** for the new version.
+
+3. **Update your consumer code:**
+
+   ```diff
+   - if (summary.counts.total > 0) { ... }
+   + if (summary.counts.findings > 0) { ... }
+   ```
+
+4. **Update the spec check** to allow the new version.
+
+5. **Update the schema file you validate against**, if any.
+
+6. **Bump the npm package** in your `package.json`.
+
+## Detecting an unexpected version
+
+The `spec:` field is your defence against silent shape changes. Every
+JSON envelope this package produces carries it. Downstream tooling
+should always check it before parsing.
+
+Pattern: explicit allowlist of accepted spec values, with a clear
+error message when something unexpected lands.
+
+```typescript
+const ACCEPTED_SPECS = new Set([
+  'autotel-eventcatalog-drift-summary/v0.1.0',
+  // Add new minors here as you update; reject anything else.
+]);
+
+function parseSummary(json: string): DriftSummary {
+  const parsed = JSON.parse(json);
+  if (!ACCEPTED_SPECS.has(parsed.spec)) {
+    throw new Error(
+      `Drift summary spec "${parsed.spec}" is not in the accepted set. ` +
+        `Read the autotel-eventcatalog CHANGELOG and update this consumer.`,
+    );
+  }
+  return parsed as DriftSummary;
+}
+```
+
+This is intentionally noisy. A silent fallback to "best effort parse"
+is exactly how downstream consumers lose track of contracts.
+
+## Renderer compatibility
+
+The CLI's `--format` flag accepts any name registered in the renderer
+registry. Adding a new renderer is a **minor** bump (it doesn't break
+existing callers). Removing a renderer would be a **major** bump
+(callers using `--format <removed>` would fail).
+
+The built-in renderers (`markdown`, `terminal`, `json`) are intended to
+stay forever. If a future major version retires one of them, the
+CHANGELOG will name the migration target.
+
+## Action upgrade
+
+The GitHub Action uses semver via the `package-version` input. Default
+is `^0`, major-version-pinned to v0.
+
+When v1.0.0 ships, your workflow keeps running on the latest v0 release
+until you explicitly opt in:
+
+```yaml
+- uses: jagreehal/autotel-eventcatalog@v0 # always latest v0
+- uses: jagreehal/autotel-eventcatalog@v1 # opt into v1
+- uses: jagreehal/autotel-eventcatalog@v0.1.0 # pin exactly
+```
+
+Inside the action itself, the `package-version` input controls which
+npm release runs:
+
+```yaml
+- uses: jagreehal/autotel-eventcatalog@v0
+  with:
+    package-version: '0.1.0'   # exact pin
+    # OR
+    package-version: '^0.1'    # minor-range
+```
+
+## When in doubt
+
+- The CHANGELOG is the source of truth for what changed.
+- The schemas in `schemas/` are the source of truth for the JSON shape.
+- The `spec:` field is the source of truth for which schema a given
+  output matches.
+
+If something looks like an undocumented breaking change, file an
+issue; that's a bug in the release process, not in your code.