From a0b2ecee2bd6e938e7ad63fa84c8e1106809429b Mon Sep 17 00:00:00 2001 From: Danijel Martinek Date: Tue, 12 May 2026 23:56:34 +0200 Subject: [PATCH 1/5] =?UTF-8?q?docs(work):=20story=2004=20=E2=80=94=20CI?= =?UTF-8?q?=20drift=20gate?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../04-ci-drift-gate/_story.md | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 docs/work/conformance-system-v1/04-ci-drift-gate/_story.md diff --git a/docs/work/conformance-system-v1/04-ci-drift-gate/_story.md b/docs/work/conformance-system-v1/04-ci-drift-gate/_story.md new file mode 100644 index 0000000..03ba9c8 --- /dev/null +++ b/docs/work/conformance-system-v1/04-ci-drift-gate/_story.md @@ -0,0 +1,47 @@ +--- +id: 04-ci-drift-gate +epic: conformance-system-v1 +title: CI drift gate — pnpm conformance with cross-feature event closure +type: technical-story +status: in-progress +feature: scripts +depends-on: [03-b-ast-eslint-rules] +blocks: [05-generator-updates] +--- + +## Goal +`pnpm conformance` aggregates cross-feature checks that no single-file +ESLint rule can perform — most importantly, event closure: every event +declared in any manifest's `consumes` must have at least one matching +`publishes` somewhere in the repo. + +## Why +Per-file lint can't see cross-feature contracts. Without this gate, a +feature can declare it consumes `X` while no feature publishes `X` — +silent until the broken handler is exercised in prod. + +## Done when +- `pnpm conformance` exits 0 when manifests are consistent; non-zero + with a clear error message on orphan consumers +- Wired into `turbo.json` as the `conformance` task +- Wired into `.github/workflows/ci.yml` after `pnpm lint` + +## In scope +- `scripts/conformance.mjs` — orphan-consumer check +- Tests via vitest +- turbo.json + CI wiring + +## Out of scope +- Scaffold drift check (regenerate via `turbo gen feature`, diff against + on-disk state) — depends on generator updates landing +- Repository write outside use-cases check — separate concern +- Reverse check (orphan publishers — events nothing consumes) — many + events are intentionally "fire and forget"; not a closure violation + +## Tasks +- [ ] Story scaffold +- [ ] `scripts/conformance.mjs` implementation +- [ ] Tests for the script +- [ ] Wire into root package.json + turbo.json +- [ ] Wire into ci.yml +- [ ] Final verification + closeout From 24769eb442dfa1274928b64578db2cd26e601b98 Mon Sep 17 00:00:00 2001 From: Danijel Martinek Date: Tue, 12 May 2026 23:57:52 +0200 Subject: [PATCH 2/5] feat(scripts): conformance drift gate + tests --- scripts/conformance.mjs | 102 +++++++++++++++++++++++++++++++++++ scripts/conformance.test.mjs | 83 ++++++++++++++++++++++++++++ 2 files changed, 185 insertions(+) create mode 100644 scripts/conformance.mjs create mode 100644 scripts/conformance.test.mjs diff --git a/scripts/conformance.mjs b/scripts/conformance.mjs new file mode 100644 index 0000000..397d3a2 --- /dev/null +++ b/scripts/conformance.mjs @@ -0,0 +1,102 @@ +#!/usr/bin/env node +/** + * pnpm conformance — cross-feature drift gate. + * + * Walks every `packages/*\/src/feature.manifest.ts`, reuses the AST parser + * from `@repo/core-eslint` to extract per-use-case publishes/consumes, + * builds global publish + consume sets across all features, and fails on: + * + * - Orphan consumer: a feature declares `consumes: ["X"]` but no + * feature publishes "X". + * + * Exits 0 on success, 1 on any violation. Prints a tabular summary of + * the event graph for transparency. + */ +import fs from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { parseManifestUseCases } from "../packages/core-eslint/rules/_manifest-ast.js"; + +const __dirname = path.dirname(fileURLToPath(import.meta.url)); +const REPO_ROOT = path.resolve(__dirname, ".."); + +export function findAllManifests(repoRoot = REPO_ROOT) { + const packagesDir = path.join(repoRoot, "packages"); + if (!fs.existsSync(packagesDir)) return []; + const out = []; + for (const entry of fs.readdirSync(packagesDir)) { + const manifestPath = path.join(packagesDir, entry, "src", "feature.manifest.ts"); + if (fs.existsSync(manifestPath)) { + out.push({ feature: entry, path: manifestPath }); + } + } + return out; +} + +export function buildEventGraph(manifests) { + const graph = new Map(); + for (const { feature, path: manifestPath } of manifests) { + const useCases = parseManifestUseCases(manifestPath); + if (!useCases) continue; + for (const [useCase, entry] of Object.entries(useCases)) { + for (const event of entry.publishes) { + if (!graph.has(event)) graph.set(event, { publishers: [], consumers: [] }); + graph.get(event).publishers.push({ feature, useCase }); + } + for (const event of entry.consumes) { + if (!graph.has(event)) graph.set(event, { publishers: [], consumers: [] }); + graph.get(event).consumers.push({ feature, useCase }); + } + } + } + return graph; +} + +export function findOrphanConsumers(graph) { + const orphans = []; + for (const [event, { publishers, consumers }] of graph.entries()) { + if (consumers.length > 0 && publishers.length === 0) { + orphans.push({ event, consumers }); + } + } + return orphans; +} + +function main() { + const manifests = findAllManifests(); + console.log(`Found ${manifests.length} feature manifest(s):`); + for (const { feature } of manifests) console.log(` - ${feature}`); + console.log(); + + const graph = buildEventGraph(manifests); + if (graph.size === 0) { + console.log("No cross-feature events declared yet — nothing to check."); + process.exit(0); + } + + console.log(`Event graph (${graph.size} event(s)):`); + for (const [event, { publishers, consumers }] of graph.entries()) { + console.log(` ${event}`); + console.log(` publishers: ${publishers.length === 0 ? "(none)" : publishers.map((p) => `${p.feature}.${p.useCase}`).join(", ")}`); + console.log(` consumers: ${consumers.length === 0 ? "(none)" : consumers.map((c) => `${c.feature}.${c.useCase}`).join(", ")}`); + } + console.log(); + + const orphans = findOrphanConsumers(graph); + if (orphans.length === 0) { + console.log("✓ pnpm conformance — passed"); + process.exit(0); + } + console.error(`✗ pnpm conformance — ${orphans.length} orphan consumer(s):`); + for (const { event, consumers } of orphans) { + console.error(` ${event}`); + for (const c of consumers) { + console.error(` consumed by ${c.feature}.${c.useCase}, but no feature publishes it`); + } + } + process.exit(1); +} + +if (import.meta.url === `file://${process.argv[1]}`) { + main(); +} diff --git a/scripts/conformance.test.mjs b/scripts/conformance.test.mjs new file mode 100644 index 0000000..3ebbc0f --- /dev/null +++ b/scripts/conformance.test.mjs @@ -0,0 +1,83 @@ +import { describe, it, expect } from "vitest"; +import path from "node:path"; +import os from "node:os"; +import fs from "node:fs"; +import { findAllManifests, buildEventGraph, findOrphanConsumers } from "./conformance.mjs"; + +function makeRepo(features) { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "conformance-")); + for (const [name, useCases] of Object.entries(features)) { + const dir = path.join(root, "packages", name, "src"); + fs.mkdirSync(dir, { recursive: true }); + const useCasesStr = Object.entries(useCases) + .map(([ucName, uc]) => + ` ${ucName}: { mutates: ${uc.mutates ?? false}, audits: [], publishes: [${(uc.publishes ?? []).map((p) => `"${p}"`).join(", ")}], consumes: [${(uc.consumes ?? []).map((c) => `"${c}"`).join(", ")}] },`, + ) + .join("\n"); + fs.writeFileSync( + path.join(dir, "feature.manifest.ts"), + `export const ${name}Manifest = defineFeature({ + name: "${name}", + requiredCores: [], + useCases: { +${useCasesStr} + }, + realtimeChannels: [], + jobs: [], +} as const);`, + ); + } + return root; +} + +describe("conformance script", () => { + describe("findAllManifests", () => { + it("returns one entry per feature with a manifest", () => { + const root = makeRepo({ + auth: { signIn: {} }, + blog: { getArticles: {} }, + }); + const ms = findAllManifests(root); + expect(ms.map((m) => m.feature).sort()).toEqual(["auth", "blog"]); + }); + + it("skips packages without a manifest", () => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "conformance-empty-")); + fs.mkdirSync(path.join(root, "packages", "no-manifest", "src"), { recursive: true }); + expect(findAllManifests(root)).toEqual([]); + }); + }); + + describe("buildEventGraph + findOrphanConsumers", () => { + it("finds zero orphans when consumers and publishers line up", () => { + const root = makeRepo({ + auth: { signUp: { mutates: true, publishes: ["auth.signed-up"] } }, + marketing: { onAuthSignedUp: { consumes: ["auth.signed-up"] } }, + }); + const manifests = findAllManifests(root); + const graph = buildEventGraph(manifests); + expect(findOrphanConsumers(graph)).toEqual([]); + }); + + it("flags orphan consumers", () => { + const root = makeRepo({ + marketing: { onAuthSignedUp: { consumes: ["auth.signed-up"] } }, + }); + const manifests = findAllManifests(root); + const graph = buildEventGraph(manifests); + const orphans = findOrphanConsumers(graph); + expect(orphans).toHaveLength(1); + expect(orphans[0].event).toBe("auth.signed-up"); + expect(orphans[0].consumers).toEqual([{ feature: "marketing", useCase: "onAuthSignedUp" }]); + }); + + it("treats publish-only events as fine (no consumers is not an orphan)", () => { + const root = makeRepo({ + auth: { signUp: { mutates: true, publishes: ["auth.signed-up"] } }, + }); + const manifests = findAllManifests(root); + const graph = buildEventGraph(manifests); + expect(findOrphanConsumers(graph)).toEqual([]); + }); + }); +}); From dfd6e1c3cc57ffe32e30e43915c7c60f33970e7b Mon Sep 17 00:00:00 2001 From: Danijel Martinek Date: Tue, 12 May 2026 23:58:10 +0200 Subject: [PATCH 3/5] feat: wire pnpm conformance script + turbo task --- package.json | 1 + turbo.json | 8 ++++++++ 2 files changed, 9 insertions(+) diff --git a/package.json b/package.json index 853067d..8ff87ba 100644 --- a/package.json +++ b/package.json @@ -13,6 +13,7 @@ "test:e2e": "turbo run test:e2e", "test:stories": "turbo run test:stories", "typecheck": "turbo run typecheck", + "conformance": "node scripts/conformance.mjs", "format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md}\"", "format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,json,md}\"" }, diff --git a/turbo.json b/turbo.json index 694fd7d..c2ec817 100644 --- a/turbo.json +++ b/turbo.json @@ -75,6 +75,14 @@ "typecheck": { "dependsOn": [] }, + "conformance": { + "inputs": [ + "packages/*/src/feature.manifest.ts", + "scripts/conformance.mjs", + "packages/core-eslint/rules/_manifest-ast.js" + ], + "outputs": [] + }, "build-storybook": { "outputs": ["storybook-static/**"] }, From 132ebc689f3bd2d56441852b80a3e5857af78eef Mon Sep 17 00:00:00 2001 From: Danijel Martinek Date: Tue, 12 May 2026 23:58:20 +0200 Subject: [PATCH 4/5] ci: add conformance step after lint --- .github/workflows/ci.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 817890b..c829863 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -49,6 +49,7 @@ jobs: - run: pnpm install --frozen-lockfile - run: pnpm typecheck - run: pnpm lint + - run: pnpm conformance - run: pnpm turbo boundaries - name: Test with coverage env: From f374d8b8742d95f00b454794d3097cbe8c81c86d Mon Sep 17 00:00:00 2001 From: Danijel Martinek Date: Tue, 12 May 2026 23:58:51 +0200 Subject: [PATCH 5/5] =?UTF-8?q?docs(work):=20close=20story=2004=20?= =?UTF-8?q?=E2=80=94=20CI=20drift=20gate?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../04-ci-drift-gate/_story.md | 14 +++++++------- docs/work/conformance-system-v1/_epic.md | 2 +- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/work/conformance-system-v1/04-ci-drift-gate/_story.md b/docs/work/conformance-system-v1/04-ci-drift-gate/_story.md index 03ba9c8..64adff9 100644 --- a/docs/work/conformance-system-v1/04-ci-drift-gate/_story.md +++ b/docs/work/conformance-system-v1/04-ci-drift-gate/_story.md @@ -3,7 +3,7 @@ id: 04-ci-drift-gate epic: conformance-system-v1 title: CI drift gate — pnpm conformance with cross-feature event closure type: technical-story -status: in-progress +status: done feature: scripts depends-on: [03-b-ast-eslint-rules] blocks: [05-generator-updates] @@ -39,9 +39,9 @@ silent until the broken handler is exercised in prod. events are intentionally "fire and forget"; not a closure violation ## Tasks -- [ ] Story scaffold -- [ ] `scripts/conformance.mjs` implementation -- [ ] Tests for the script -- [ ] Wire into root package.json + turbo.json -- [ ] Wire into ci.yml -- [ ] Final verification + closeout +- [x] Story scaffold +- [x] `scripts/conformance.mjs` implementation +- [x] Tests for the script +- [x] Wire into root package.json + turbo.json +- [x] Wire into ci.yml +- [x] Final verification + closeout diff --git a/docs/work/conformance-system-v1/_epic.md b/docs/work/conformance-system-v1/_epic.md index ff74758..4edaa4d 100644 --- a/docs/work/conformance-system-v1/_epic.md +++ b/docs/work/conformance-system-v1/_epic.md @@ -35,7 +35,7 @@ See `docs/architecture/feature-conformance-explainer.html` and - [x] 03 — AST-aware ESLint rules (both halves shipped) - [x] [03.a — Structural rules](03-a-structural-eslint-rules/_story.md) - [x] [03.b — Manifest-aware AST rules](03-b-ast-eslint-rules/_story.md) -- [ ] 04 — CI drift gate (later plan) +- [x] [04 — CI drift gate](04-ci-drift-gate/_story.md) - [ ] 05 — Generator emits manifest + contracts + test stubs (later plan) - [ ] 06 — Documentation rewrite (later plan) - [ ] 07 — Migrate auth feature reference (later plan)