autotel-eventcatalog 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,196 @@
+# Changelog
+
+## 1.0.0
+
+### Minor Changes
+
+- de31d28: The "get to 10" pass. Closes the review-board's outstanding watch items
+  and a couple they didn't surface.
+
+  **Public JSON contract.** Three versioned JSON Schemas ship with the
+  package: `schemas/drift-report-v0.1.0.json`,
+  `schemas/drift-summary-v0.1.0.json`, and
+  `schemas/stamp-summary-v0.1.0.json`. Each output envelope carries a
+  `spec:` field downstream consumers can read to refuse unknown major
+  versions. New `contract.test.ts` validates emitted output against the
+  schemas AND byte-compares against committed golden fixtures, so a PR
+  that silently changes a published field name now fails CI with a clear
+  message.
+
+  **Renderers as adapters.** The Markdown / Terminal / JSON renderers
+  moved into `src/renderers/` with a small `Renderer` interface and a
+  `getRenderer(name)` registry. The CLI's `--format` flag now dispatches
+  through the registry instead of hardcoding two cases — adding SARIF,
+  Slack-flavoured markdown, GitHub Check Runs API, etc. is a single new
+  file. The core diff and policy modules don't move and never reference
+  the registry. Backwards-compatible: `import { renderMarkdown } from
+'autotel-eventcatalog'` still works.
+
+  **Action hardening.**
+  - `marocchino/sticky-pull-request-comment` pinned to a specific commit
+    SHA (supply-chain control).
+  - A failure of the comment step is downgraded to a `::warning::` so the
+    drift signal is never lost to a flaky GitHub API call. Behind
+    `continue-on-comment-failure` input (defaults to `true`; set to
+    `false` to keep the old behaviour).
+  - `package-version` default changed from `latest` to `^0` so a new
+    major release doesn't silently land on user CI.
+
+  **README.** Opens with the dual-tool framing (drift verifier + stamp
+  generator). New "What this package does NOT do" boundary statement. New
+  "Public JSON contract" and "Renderers (advanced)" sections.
+
+  Backwards-compatible for every existing CLI and library consumer.
+
+  Total tests: 78 unit + 11 e2e (was 58 + 11 before this changeset).
+
+- de31d28: Initial release of `autotel-eventcatalog`. Diffs an autotel architecture
+  snapshot against an EventCatalog and reports the drift: events observed but
+  undocumented, events documented but never observed, field paths in payloads
+  not declared in the schema, and producers / channels seen but not catalogued.
+
+  Ships as a library and a CLI:
+
+  ```bash
+  autotel-eventcatalog drift \
+    --snapshot ./services/test/snapshot.json \
+    --catalog ./catalog \
+    --output drift.md \
+    --fail-on-drift   # exit 1 when drift is detected — wire this into CI
+  ```
+
+  v0 covers existence drift and field-path drift. Type drift, value drift, and
+  auto-writing missing catalog entries are deferred to later releases.
+
+- de31d28: Three small follow-ups from review notes, applied:
+  1. **Count extraction moved next to the diff types**. `countDriftReport`
+     (in `diff.ts`) and `countDriftEntries` / `countDriftDelta` (in
+     `diff-vs-base.ts`) produce the per-category and total counts that
+     dashboards, CI summaries, and reports need. `cli.ts`'s `buildSummary`
+     no longer duplicates the extraction logic. `hasDrift` is now a thin
+     wrapper around `countDriftReport(...).total > 0`. The new `total`
+     field matches the dashboard's existing `countDrift()` semantic
+     (individual paths inside `fieldDrift` are counted, not just events).
+     New `DriftCounts` type exported from the library.
+  2. **`stamp --summary-output` ships**. Mirrors the existing `drift
+--summary-output` so CI can answer "did this PR need to re-stamp?"
+     from a structured JSON file rather than parsing stderr. The summary
+     carries a versioned `spec: 'autotel-eventcatalog-stamp-summary/v0.1.0'`
+     marker and reports `attempted / inserts / replaces / changedFiles /
+skipped / hadChanges`. `StampUpdate` gains a `changed: boolean` flag
+     so re-stamping with identical content correctly reports as a no-op
+     replace.
+  3. **`renderTerminal` becomes a real export**. Tests cover the
+     structure-preserved-decorations-stripped contract. Added
+     `renderDeltaTerminal` for symmetric coverage of the PR-style delta
+     view. Both useful for Slack messages, log files, and anywhere a
+     plain-text rendering beats markdown.
+
+  13 new tests, all passing (58 unit + 11 e2e total).
+
+- de31d28: Add `--base-snapshot` mode and a composite GitHub Action for PR drift checking.
+
+  `autotel-eventcatalog drift --base-snapshot <path> --snapshot <path> --catalog <path>`
+  reports only the drift the PR introduces, ignoring pre-existing drift. New
+  `compareDriftReports()` and `renderDeltaMarkdown()` library exports do the
+  same thing programmatically.
+
+  The new `action.yml` ships in the package so any repository can wire drift
+  checking into its PR pipeline with one step:
+
+  ```yaml
+  - uses: jagreehal/autotel-eventcatalog@v0
+    with:
+      snapshot: ./services/test/snapshot.json
+      catalog: ./catalog
+      base-ref: origin/${{ github.base_ref }}
+      fail-on-drift: true
+      comment-on-pr: true
+  ```
+
+  The action runs the CLI, posts a sticky comment with the drift report on
+  the PR, and fails the check only when the PR introduces _new_ drift.
+
+- de31d28: Add a `stamp` subcommand to `autotel-eventcatalog` that writes a runtime
+  evidence block into each event mdx between
+  `<!-- autotel:stamp-start -->` and `<!-- autotel:stamp-end -->` markers.
+
+  The block carries everything autotel observed in the snapshot for that
+  event — volume, last-seen, producer, channel, and the full list of dotted
+  field paths — so the static catalog page itself shows runtime evidence
+  alongside the hand-written narrative, not in a separate dashboard.
+
+  ```bash
+  autotel-eventcatalog stamp \
+    --snapshot ./services/test/snapshot.json \
+    --catalog ./catalog
+  ```
+
+  Subsequent runs are idempotent: content between the markers is replaced,
+  not duplicated. `--dry-run` prints the update plan without writing files,
+  suitable for a CI sanity check. The library also exposes `stampCatalog()`
+  and `buildStampBlock()` for programmatic use.
+
+### Patch Changes
+
+- de31d28: Two correctness fixes flagged in code review:
+
+  **P0**: The CLI only exits non-zero on drift when `--fail-on-drift` is set.
+  The bundled GitHub Action's internal script captured `STATUS=$?` from the
+  CLI without passing `--fail-on-drift`, so the action's `drift-detected`
+  output and the downstream "Fail on drift" step never fired even when
+  drift was present. Fixed by always passing `--fail-on-drift` from the
+  action's internal script — the user-facing `fail-on-drift` input now
+  governs whether the workflow step fails, but the action's drift signal
+  is no longer gated on it.
+
+  **P1**: `readCatalogState` matched literal `'/'` separators for
+  directory classification. On Windows runners the path separator is `\`,
+  so the `'/versioned/'` exclusion and the `services/events/channels`
+  classification both silently misbehaved. Paths are now normalised to a
+  canonical POSIX form before string-matching, so classification works
+  identically on every platform.
+
+  The CLI exit-code contract is now documented as:
+
+  0 — no drift
+  1 — drift detected (only when `--fail-on-drift` is set)
+  2 — bad arguments
+  other — hard failure (surface to the user)
+
+- de31d28: Tighten the policy layer based on a code-review pass.
+  - `PolicyEvaluationResult` drops the redundant `mode` field. `reason` is
+    retained and now used: the CLI prints it on stderr at the end of every
+    drift run so CI logs say _"Drift detected in current snapshot."_ or
+    _"No new drift introduced compared to baseline snapshot."_ — explaining
+    the exit code rather than just emitting it.
+  - The CLI no longer silently rewrites `--policy all` to `--policy
+new-only` when `--base-snapshot` is present. The effective policy is
+    derived at the use site: explicit flag wins, otherwise default to
+    `new-only` when a baseline is supplied, else `all`. Same behaviour for
+    users who omit `--policy`; no more "we secretly mutated your flag"
+    surprise for users who set it explicitly.
+  - The JSON output (`--format json`) is now versioned with a
+    `spec: 'autotel-eventcatalog-report/v0.1.0'` marker on every envelope,
+    so downstream tooling can detect and refuse unknown major versions.
+    Exported as `REPORT_SPEC` from the library.
+  - New e2e test suite (`cli.e2e.test.ts`) spawns the built CLI against
+    fixture catalogs and asserts exit codes + outputs for: clean state
+    with `--fail-on-drift`, drift with `--fail-on-drift`, drift without
+    `--fail-on-drift` (the original P0 regression class), `--policy
+new-only` without `--base-snapshot`, versioned JSON output, unknown
+    flags, and `stamp --dry-run`. Run via `pnpm test:e2e`.
+
+- Updated dependencies [de31d28]
+  - autotel-subscribers@32.1.0
+
+All notable changes to `autotel-eventcatalog` land here. Entries are
+generated by [Changesets](https://github.com/changesets/changesets) at
+release time from the files in `.changeset/`; this file is the
+authoritative history once each release ships.
+
+For the current scope of the package, see [README.md](README.md). For
+the version policy (when shapes change, when contracts break), see
+[docs/UPGRADING.md](docs/UPGRADING.md).
+
+<!-- Future Changesets-generated entries will be inserted above this line. -->

package/CONTRIBUTING.md

@@ -0,0 +1,212 @@
+# Contributing to autotel-eventcatalog
+
+A short, opinionated guide. The package is small enough that you can read all
+of it in an afternoon; this doc is here so you don't have to.
+
+## Where things live
+
+```
+packages/autotel-eventcatalog/
+├── src/
+│   ├── snapshot.ts          load + type-check an autotel architecture snapshot
+│   ├── catalog.ts           read the catalog from disk (POSIX-normalised paths)
+│   ├── diff.ts              compute drift between snapshot and catalog (pure)
+│   ├── diff-vs-base.ts      compute drift delta (PR head vs base) (pure)
+│   ├── policy.ts            "should this drift fail CI?" (pure)
+│   ├── stamp.ts             write runtime evidence into catalog mdx files
+│   ├── renderers/           render adapters
+│   │   ├── types.ts         the Renderer interface
+│   │   ├── markdown.ts      Markdown (GitHub-flavoured), the default
+│   │   ├── terminal.ts      plain text (decorations stripped)
+│   │   ├── json.ts          versioned envelope; the public JSON contract
+│   │   └── index.ts         registry + getRenderer(name)
+│   ├── report.ts            backwards-compat re-export shim over renderers/
+│   ├── cli.ts               argument parsing + command dispatch + I/O
+│   ├── __fixtures__/        golden JSON files for contract tests
+│   └── *.test.ts            unit tests
+│   └── cli.e2e.test.ts      e2e tests (spawn the built CLI)
+│   └── contract.test.ts     versioned-JSON contract tests
+├── schemas/
+│   ├── drift-report-v0.1.0.json
+│   ├── drift-summary-v0.1.0.json
+│   └── stamp-summary-v0.1.0.json
+├── action.yml               composite GitHub Action (used by external repos)
+├── docs/                    this folder
+└── README.md
+```
+
+## Module dependency rules
+
+The DAG is one-way by design:
+
+```
+snapshot.ts ──┐
+              ├──► diff.ts ──► diff-vs-base.ts ──► policy.ts
+catalog.ts ───┤                                    ▲
+              │                                    │
+              ├──► stamp.ts                        │
+              │                                    │
+              └────► renderers/ ◄──────────────────┘
+
+cli.ts ─► everything (the only place all branches meet)
+```
+
+**Rules:**
+
+1. `diff.ts` / `diff-vs-base.ts` / `policy.ts` import only from each other,
+   `snapshot.ts`, and `catalog.ts`. They never import a renderer.
+2. `renderers/*` import from the core but the core never imports a renderer.
+3. `cli.ts` is the dispatcher; nothing else imports from `cli.ts`.
+4. `stamp.ts` is independent of `diff.ts`. They share inputs but no logic.
+
+If a future change wants to break one of these rules, that's the signal to
+stop and ask whether the new feature belongs in this package.
+
+## Load-bearing invariants
+
+These are the rules I'd commit to keeping. Future-me, future-contributors:
+when in doubt, push back.
+
+### 1. No new top-level commands without a user
+
+The CLI has two: `drift` (verify) and `stamp` (generate). Three would be
+the limit before splitting `cli.ts` into per-command modules. Four is the
+signal to question whether the third and fourth belong in this package
+at all.
+
+A new command needs:
+
+- A user with a concrete workflow that demands it
+- Tests proving the behaviour
+- A docs entry explaining when to reach for it
+
+A new command does NOT need:
+
+- "It would be nice to have"
+- "Just in case"
+- "While I'm in here"
+
+### 2. No runtime servers, daemons, watchers, or LSPs
+
+This package is a CLI plus library plus composite GitHub Action. It runs,
+does its job, and exits. Anything that needs to stay running (a live
+dashboard, a file watcher, an LSP server, an MCP server, a webhook
+listener) lives in [`autotel-subscribers`](../autotel-subscribers/) or in
+example apps.
+
+The reason: long-running processes have a different lifecycle from
+command-line tools. Process management, signal handling, restart
+semantics, observability. Mixing the two doubles the operational surface
+for no clarity gain.
+
+### 3. No domain-specific extensions to the core
+
+`diff.ts`, `diff-vs-base.ts`, and `policy.ts` work at one abstraction:
+events, services, channels, field paths. Adding a SARIF renderer should
+never require a `severity` field on `DriftCounts`. Adding a Slack
+renderer should never require a `messageColor` field on `DriftReport`.
+
+If a new renderer wants information that doesn't fit the existing types,
+the renderer should derive it locally, not push back into the core. If
+multiple renderers want the same derived information, _then_ it earns a
+place in `diff.ts`. Pause and confirm it's about drift, not about
+presentation.
+
+## How to do common things
+
+### Run the tests
+
+```bash
+pnpm test          # unit tests, fast, no build required
+pnpm test:e2e      # builds dist/, spawns the CLI, checks exit codes
+pnpm test:watch    # unit tests in watch mode
+pnpm quality       # type-check + unit + e2e + lint + format
+```
+
+### Add a renderer
+
+See [docs/EXTENDING.md](docs/EXTENDING.md) for the full walkthrough. Short
+version: create `src/renderers/<name>.ts` that exports a `Renderer`,
+register it in `src/renderers/index.ts`, write tests that round-trip the
+shape, document it in the README.
+
+### Change the public JSON shape
+
+You can't change it silently. The `schemas/*.json` files and the
+byte-equal golden fixtures in `src/__fixtures__/*.golden.json` will fail
+CI on any shape change. Either:
+
+- **Add an optional field**: bump the schema's _minor_ version (`v0.1.0` →
+  `v0.2.0`). Add the field with sensible defaults so existing consumers
+  keep working. Update goldens.
+- **Break the shape** (rename a field, change a type, remove a field):
+  bump the schema's _major_ version (`v0.1.0` → `v1.0.0`). Document the
+  migration. Old consumers should refuse to parse the new envelope by
+  checking the `spec` field.
+
+The `spec` field on every envelope is your one-way out.
+
+### Add a CLI flag
+
+Update the parser in `cli.ts`, add it to the usage string, write an e2e
+test that exercises it (`cli.e2e.test.ts`). If it changes which output is
+produced, also update the golden fixture for that scenario.
+
+### Add a new diff category
+
+(e.g. "tags observed but undocumented"; hypothetical)
+
+1. Add it to `DriftReport` in `diff.ts`
+2. Compute it in `diffCatalogAgainstSnapshot`
+3. Add it to `countDriftReport` in `diff.ts` so the total stays correct
+4. Add it to every renderer in `src/renderers/`
+5. Add it to the `DriftDelta` shape in `diff-vs-base.ts`
+6. Add it to `countDriftEntries`
+7. Bump the JSON schemas (probably minor)
+8. Update golden fixtures
+9. Tests for each of the above
+
+New categories cost a lot. The reason this list is long is to make you
+pause before adding one.
+
+## Commit conventions
+
+Conventional Commits. The monorepo uses changesets; every PR with a
+public-API change should include a changeset file (`pnpm changeset`).
+
+For changes inside this package:
+
+- `feat(autotel-eventcatalog): ...` for new functionality
+- `fix(autotel-eventcatalog): ...` for bug fixes
+- `refactor(autotel-eventcatalog): ...` for internal restructuring
+- `docs(autotel-eventcatalog): ...` for documentation only
+- `chore(autotel-eventcatalog): ...` for build, deps, tooling
+
+## Review checklist
+
+Before opening a PR:
+
+- [ ] `pnpm quality` passes locally
+- [ ] If the public JSON shape changed, schema + golden fixtures + spec
+      version are all updated together
+- [ ] If a new CLI flag landed, the usage string and e2e tests reflect it
+- [ ] If a renderer landed, it's in the registry and has tests
+- [ ] If the action.yml changed, any input default change is documented
+      in the README's action snippet
+- [ ] Changeset present (`pnpm changeset`)
+- [ ] The README's "What this package does NOT do" boundary is still true
+
+## Questions worth asking before adding anything
+
+- Could this live in a downstream consumer instead of in this package?
+- Is the new code reachable from an existing path, or is it a fork in the
+  road? (Forks are fine, but be deliberate.)
+- Will the next contributor be confused about whether to put related code
+  with the existing thing or with the new thing? (If yes, the new thing
+  is in the wrong place.)
+- Does this require a long-running process? (See invariant #2.)
+- Does this require breaking the renderer-as-adapter pattern? (See
+  invariant #3.)
+
+If you can't comfortably answer "no" or "this is fine", open an issue
+first.