Merge branch 'worktree-conformance-milestone-iv': conformance milestone iv — CI drift gate

.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:

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: done
+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
+- [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

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)

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}\""
   },

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();
+}

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([]);
+    });
+  });
+});

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/**"]
     },