@devinnn/docdrift 0.1.0

package/README.md

@@ -0,0 +1,147 @@
+# Devin Doc Drift (Client E: DataStack)
+
+Docs that never lie: detect drift between merged code and docs, then open low-noise, evidence-grounded remediation via Devin sessions.
+
+## Deliverables
+- TypeScript CLI package (`docdrift`)
+  - `validate`
+  - `detect --base <sha> --head <sha>`
+  - `run --base <sha> --head <sha>`
+  - `status --since 24h`
+- GitHub Action: `/Users/cameronking/Desktop/sideproject/docdrift/.github/workflows/devin-doc-drift.yml`
+- Repo-local config: `/Users/cameronking/Desktop/sideproject/docdrift/docdrift.yaml`
+- Demo API + OpenAPI exporter + driftable docs
+- PR template + Loom script
+
+## Why this is low-noise
+- One PR per doc area per day (bundling rule).
+- Global PR/day cap.
+- Confidence gating and allowlist enforcement.
+- Conceptual docs default to issue escalation with targeted questions.
+- Idempotency key prevents duplicate actions for same repo/SHAs/action.
+
+## Detection tiers
+- Tier 0: docs checks (`npm run docs:check`)
+- Tier 1: OpenAPI drift (`openapi/generated.json` vs `docs/reference/openapi.json`)
+- Tier 2: heuristic path impacts (e.g. `apps/api/src/auth/**` -> `docs/guides/auth.md`)
+
+Output artifacts (under `.docdrift/`):
+- `drift_report.json`
+- `metrics.json` (after `run`)
+
+When you run docdrift as a package (e.g. `npx docdrift` or from another repo), all of this is written to **that repo’s** `.docdrift/` — i.e. the current working directory where the CLI is invoked, not inside the package. Add `.docdrift/` to the consuming repo’s `.gitignore` if you don’t want to commit run artifacts.
+
+## Core flow (`docdrift run`)
+1. Validate config and command availability.
+2. Build drift report.
+3. Policy decision (`OPEN_PR | UPDATE_EXISTING_PR | OPEN_ISSUE | NOOP`).
+4. Build evidence bundle (`.docdrift/evidence/<runId>/<docArea>` + tarball).
+5. Upload attachments to Devin v1 and create session.
+6. Poll session to terminal status.
+7. Surface result via GitHub commit comment; open issue on blocked/low-confidence paths.
+8. Persist state in `.docdrift/state.json` and write `.docdrift/metrics.json`.
+
+## Local usage
+```bash
+npm install
+npx tsx src/cli.ts validate
+npm run openapi:export
+npx tsx src/cli.ts detect --base <sha> --head <sha>
+DEVIN_API_KEY=... GITHUB_TOKEN=... GITHUB_REPOSITORY=owner/repo GITHUB_SHA=<sha> npx tsx src/cli.ts run --base <sha> --head <sha>
+```
+
+## Local demo (no GitHub)
+
+You can run a full end-to-end demo locally with no remote repo. Ensure `.env` has `DEVIN_API_KEY` (and optionally `GITHUB_TOKEN` only when you have a real repo).
+
+1. **One-time setup (already done if you have two commits with drift)**  
+   - Git is inited; baseline commit has docs in sync with API.  
+   - A later commit changes `apps/api/src/model.ts` (e.g. `name` → `fullName`) and runs `npm run openapi:export`, so `openapi/generated.json` drifts from `docs/reference/openapi.json`.
+
+2. **Run the pipeline**
+   ```bash
+   npm install
+   npx tsx src/cli.ts validate
+   npx tsx src/cli.ts detect --base b0f624f --head 6030902
+   ```
+   - Use your own `git log --oneline -3` to get `base` (older) and `head` (newer) SHAs if you recreated the demo.
+
+3. **Run with Devin (no GitHub calls)**  
+   Omit `GITHUB_TOKEN` so the CLI does not post comments or create issues. Devin session still runs; results are printed to stdout and written to `.docdrift/state.json` and `metrics.json`.
+   ```bash
+   export $(grep -v '^#' .env | xargs)
+   unset GITHUB_TOKEN GITHUB_REPOSITORY GITHUB_SHA
+   npx tsx src/cli.ts run --base b0f624f --head 6030902
+   ```
+   - `run` can take 1–3 minutes while the Devin session runs.
+
+4. **What you’ll see**
+   - `.docdrift/drift_report.json` — drift items (e.g. OpenAPI `name` → `fullName`).
+   - `.docdrift/evidence/<runId>/` — evidence bundles and OpenAPI diff.
+   - Stdout — per–doc-area outcome (e.g. PR opened by Devin or blocked).
+   - `.docdrift/metrics.json` — counts and timing.
+
+## CI usage
+
+- Add secret: `DEVIN_API_KEY`
+- Push to `main` or run `workflow_dispatch`
+- Action uploads:
+  - `.docdrift/drift_report.json`
+  - `.docdrift/evidence/**`
+  - `.docdrift/metrics.json`
+
+## Run on GitHub
+
+1. **Create a repo** on GitHub (e.g. `your-org/docdrift`), then add the remote and push:
+   ```bash
+   git remote add origin https://github.com/your-org/docdrift.git
+   git push -u origin main
+   ```
+
+2. **Add secret**  
+   Repo → **Settings** → **Secrets and variables** → **Actions** → **New repository secret**  
+   - Name: `DEVIN_API_KEY`  
+   - Value: your Devin API key (same as in `.env` locally)
+
+   `GITHUB_TOKEN` is provided automatically; the workflow uses it for commit comments and issues.
+
+3. **Trigger the workflow**
+   - **Push to `main`** — runs on every push (compares previous commit vs current).
+   - **Manual run** — **Actions** tab → **devin-doc-drift** → **Run workflow** (uses `HEAD` and `HEAD^` as head/base).
+
+## Using in another repo (published package)
+
+Once published to npm, any repo can use the CLI locally or in GitHub Actions.
+
+1. **In the consuming repo** add a `docdrift.yaml` at the root (see this repo’s `docdrift.yaml` and `docdrift-yml.md`).
+2. **CLI**
+   ```bash
+   npx docdrift@latest validate
+   npx docdrift@latest detect --base <base-sha> --head <head-sha>
+   # With env for run:
+   DEVIN_API_KEY=... GITHUB_TOKEN=... GITHUB_REPOSITORY=owner/repo GITHUB_SHA=<sha> npx docdrift@latest run --base <base-sha> --head <head-sha>
+   ```
+3. **GitHub Actions** — add a step that runs the CLI (e.g. after checkout and setting base/head):
+   ```yaml
+   - run: npx docdrift@latest run --base ${{ steps.shas.outputs.base }} --head ${{ steps.shas.outputs.head }}
+     env:
+       DEVIN_API_KEY: ${{ secrets.DEVIN_API_KEY }}
+       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+       GITHUB_REPOSITORY: ${{ github.repository }}
+       GITHUB_SHA: ${{ github.sha }}
+   ```
+   Add repo secret `DEVIN_API_KEY`; `GITHUB_TOKEN` is provided by the runner.
+
+## Publishing the package
+
+- Set `"private": false` in `package.json` (or omit it).
+- Set `"repository": { "type": "git", "url": "https://github.com/your-org/docdrift.git" }`.
+- Run `pnpm build` (or `npm run build`), then `npm publish` (for a scoped package use `npm publish --access public`).
+- Only the `dist/` directory is included (`files` in `package.json`). Consumers get the built CLI; they provide their own `docdrift.yaml` in their repo.
+
+## Demo scenario
+- Autogen drift: rename a field in `apps/api/src/model.ts`, merge to `main`, observe docs PR path.
+- Conceptual drift: change auth behavior under `apps/api/src/auth/**`, merge to `main`, observe single escalation issue.
+
+## Loom
+See `/Users/cameronking/Desktop/sideproject/docdrift/loom.md` for the minute-by-minute recording script.

package/dist/src/cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+function getArg(args, flag) {
+    const index = args.indexOf(flag);
+    if (index === -1) {
+        return undefined;
+    }
+    return args[index + 1];
+}
+async function main() {
+    const [, , command, ...args] = process.argv;
+    if (!command) {
+        throw new Error("Usage: docdrift <validate|detect|run|status> [options]");
+    }
+    switch (command) {
+        case "validate": {
+            await (0, index_1.runValidate)();
+            return;
+        }
+        case "detect": {
+            const baseSha = (0, index_1.requireSha)(getArg(args, "--base"), "--base");
+            const headSha = (0, index_1.requireSha)(getArg(args, "--head"), "--head");
+            const trigger = (0, index_1.resolveTrigger)(process.env.GITHUB_EVENT_NAME);
+            const result = await (0, index_1.runDetect)({ baseSha, headSha, trigger });
+            process.exitCode = result.hasDrift ? 1 : 0;
+            return;
+        }
+        case "run": {
+            const baseSha = (0, index_1.requireSha)(getArg(args, "--base"), "--base");
+            const headSha = (0, index_1.requireSha)(getArg(args, "--head"), "--head");
+            const trigger = (0, index_1.resolveTrigger)(process.env.GITHUB_EVENT_NAME);
+            const results = await (0, index_1.runDocDrift)({ baseSha, headSha, trigger });
+            console.log(JSON.stringify(results, null, 2));
+            return;
+        }
+        case "status": {
+            const since = getArg(args, "--since");
+            const sinceHours = (0, index_1.parseDurationHours)(since);
+            await (0, index_1.runStatus)(sinceHours);
+            return;
+        }
+        default:
+            throw new Error(`Unknown command: ${command}`);
+    }
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});

package/dist/src/config/load.js

@@ -0,0 +1,25 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const schema_1 = require("./schema");
+function loadConfig(configPath = "docdrift.yaml") {
+    const resolved = node_path_1.default.resolve(configPath);
+    if (!node_fs_1.default.existsSync(resolved)) {
+        throw new Error(`Config file not found: ${resolved}`);
+    }
+    const parsed = js_yaml_1.default.load(node_fs_1.default.readFileSync(resolved, "utf8"));
+    const result = schema_1.docDriftConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        const message = result.error.errors
+            .map((e) => `${e.path.join(".") || "root"}: ${e.message}`)
+            .join("\n");
+        throw new Error(`Invalid config:\n${message}`);
+    }
+    return result.data;
+}

package/dist/src/config/schema.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.docDriftConfigSchema = void 0;
+const zod_1 = require("zod");
+const pathRuleSchema = zod_1.z.object({
+    match: zod_1.z.string().min(1),
+    impacts: zod_1.z.array(zod_1.z.string().min(1)).min(1)
+});
+const openApiDetectSchema = zod_1.z.object({
+    exportCmd: zod_1.z.string().min(1),
+    generatedPath: zod_1.z.string().min(1),
+    publishedPath: zod_1.z.string().min(1)
+});
+const docAreaSchema = zod_1.z.object({
+    name: zod_1.z.string().min(1),
+    mode: zod_1.z.enum(["autogen", "conceptual"]),
+    owners: zod_1.z.object({
+        reviewers: zod_1.z.array(zod_1.z.string().min(1)).min(1)
+    }),
+    detect: zod_1.z
+        .object({
+        openapi: openApiDetectSchema.optional(),
+        paths: zod_1.z.array(pathRuleSchema).optional()
+    })
+        .refine((v) => Boolean(v.openapi) || Boolean(v.paths?.length), {
+        message: "docArea.detect must include openapi or paths"
+    }),
+    patch: zod_1.z.object({
+        targets: zod_1.z.array(zod_1.z.string().min(1)).optional(),
+        requireHumanConfirmation: zod_1.z.boolean().optional().default(false)
+    })
+});
+exports.docDriftConfigSchema = zod_1.z.object({
+    version: zod_1.z.literal(1),
+    devin: zod_1.z.object({
+        apiVersion: zod_1.z.literal("v1"),
+        unlisted: zod_1.z.boolean().default(true),
+        maxAcuLimit: zod_1.z.number().int().positive().default(2),
+        tags: zod_1.z.array(zod_1.z.string().min(1)).default(["docdrift"])
+    }),
+    policy: zod_1.z.object({
+        prCaps: zod_1.z.object({
+            maxPrsPerDay: zod_1.z.number().int().positive().default(1),
+            maxFilesTouched: zod_1.z.number().int().positive().default(12)
+        }),
+        confidence: zod_1.z.object({
+            autopatchThreshold: zod_1.z.number().min(0).max(1).default(0.8)
+        }),
+        allowlist: zod_1.z.array(zod_1.z.string().min(1)).min(1),
+        verification: zod_1.z.object({
+            commands: zod_1.z.array(zod_1.z.string().min(1)).min(1)
+        })
+    }),
+    docAreas: zod_1.z.array(docAreaSchema).min(1)
+});

package/dist/src/config/validate.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateRuntimeConfig = validateRuntimeConfig;
+const exec_1 = require("../utils/exec");
+function commandBinary(command) {
+    return command.trim().split(/\s+/)[0] ?? "";
+}
+async function validateRuntimeConfig(config) {
+    const errors = [];
+    const warnings = [];
+    if (config.policy.prCaps.maxFilesTouched < 1) {
+        errors.push("policy.prCaps.maxFilesTouched must be >= 1");
+    }
+    const commandSet = new Set([
+        ...config.policy.verification.commands,
+        ...config.docAreas
+            .map((area) => area.detect.openapi?.exportCmd)
+            .filter((value) => Boolean(value))
+    ]);
+    for (const command of commandSet) {
+        const binary = commandBinary(command);
+        const result = await (0, exec_1.execCommand)(`command -v ${binary}`);
+        if (result.exitCode !== 0) {
+            errors.push(`Command not found for '${command}' (binary: ${binary})`);
+        }
+    }
+    for (const area of config.docAreas) {
+        if (area.mode === "autogen" && !area.patch.targets?.length) {
+            warnings.push(`docArea '${area.name}' is autogen but has no patch.targets`);
+        }
+        if (area.mode === "conceptual" && !area.detect.paths?.length) {
+            warnings.push(`docArea '${area.name}' is conceptual but has no detect.paths rules`);
+        }
+    }
+    return { errors, warnings };
+}

package/dist/src/detect/docsCheck.js

@@ -0,0 +1,48 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDocsChecks = runDocsChecks;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const exec_1 = require("../utils/exec");
+const fs_1 = require("../utils/fs");
+async function runDocsChecks(commands, evidenceDir) {
+    (0, fs_1.ensureDir)(evidenceDir);
+    const logs = [];
+    const commandResults = [];
+    for (const [index, command] of commands.entries()) {
+        const result = await (0, exec_1.execCommand)(command);
+        const logPath = node_path_1.default.join(evidenceDir, `docs-check.${index + 1}.log`);
+        node_fs_1.default.writeFileSync(logPath, [
+            `$ ${command}`,
+            `exitCode: ${result.exitCode}`,
+            "\n--- stdout ---",
+            result.stdout,
+            "\n--- stderr ---",
+            result.stderr
+        ].join("\n"), "utf8");
+        logs.push(logPath);
+        commandResults.push({ command, exitCode: result.exitCode, logPath });
+    }
+    const failed = commandResults.filter((result) => result.exitCode !== 0);
+    if (!failed.length) {
+        return {
+            logs,
+            commandResults,
+            summary: "Docs checks passed"
+        };
+    }
+    return {
+        logs,
+        commandResults,
+        summary: `Docs checks failed (${failed.length}/${commandResults.length})`,
+        signal: {
+            kind: "docs_check_failed",
+            tier: 0,
+            confidence: 0.99,
+            evidence: failed.map((result) => result.logPath)
+        }
+    };
+}

package/dist/src/detect/heuristics.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectHeuristicImpacts = detectHeuristicImpacts;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const glob_1 = require("../utils/glob");
+function detectHeuristicImpacts(docArea, changedPaths, evidenceDir) {
+    const rules = docArea.detect.paths ?? [];
+    if (!rules.length) {
+        return { impactedDocs: [], summary: "No heuristic rules configured", evidenceFiles: [] };
+    }
+    const matched = [];
+    const impactedDocs = new Set();
+    for (const rule of rules) {
+        for (const changedPath of changedPaths) {
+            if ((0, glob_1.matchesGlob)(rule.match, changedPath)) {
+                matched.push({ rule: rule.match, path: changedPath, impacts: rule.impacts });
+                rule.impacts.forEach((doc) => impactedDocs.add(doc));
+            }
+        }
+    }
+    if (!matched.length) {
+        return { impactedDocs: [], summary: "No heuristic conceptual impacts", evidenceFiles: [] };
+    }
+    const evidencePath = node_path_1.default.join(evidenceDir, `${docArea.name}.heuristics.txt`);
+    const body = matched
+        .map((entry) => `${entry.path} matched ${entry.rule} -> ${entry.impacts.join(", ")}`)
+        .join("\n");
+    node_fs_1.default.writeFileSync(evidencePath, body, "utf8");
+    return {
+        impactedDocs: [...impactedDocs],
+        evidenceFiles: [evidencePath],
+        summary: `Heuristic impacts detected (${matched.length} matches)`,
+        signal: {
+            kind: "heuristic_path_impact",
+            tier: 2,
+            confidence: 0.67,
+            evidence: [evidencePath]
+        }
+    };
+}

package/dist/src/detect/index.js

@@ -0,0 +1,92 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDriftReport = buildDriftReport;
+const node_path_1 = __importDefault(require("node:path"));
+const fs_1 = require("../utils/fs");
+const git_1 = require("../utils/git");
+const docsCheck_1 = require("./docsCheck");
+const heuristics_1 = require("./heuristics");
+const openapi_1 = require("./openapi");
+function defaultRecommendation(mode, signals) {
+    if (!signals.length) {
+        return "NOOP";
+    }
+    if (mode === "autogen") {
+        return signals.some((s) => s.tier <= 1) ? "OPEN_PR" : "OPEN_ISSUE";
+    }
+    return "OPEN_ISSUE";
+}
+async function buildDriftReport(input) {
+    const runInfo = {
+        runId: `${Date.now()}`,
+        repo: input.repo,
+        baseSha: input.baseSha,
+        headSha: input.headSha,
+        trigger: input.trigger,
+        timestamp: new Date().toISOString()
+    };
+    const evidenceRoot = node_path_1.default.resolve(".docdrift", "evidence", runInfo.runId);
+    (0, fs_1.ensureDir)(evidenceRoot);
+    const changedPaths = await (0, git_1.gitChangedPaths)(input.baseSha, input.headSha);
+    const diffSummary = await (0, git_1.gitDiffSummary)(input.baseSha, input.headSha);
+    const commits = await (0, git_1.gitCommitList)(input.baseSha, input.headSha);
+    const docsCheck = await (0, docsCheck_1.runDocsChecks)(input.config.policy.verification.commands, evidenceRoot);
+    const items = [];
+    const checkSummaries = [docsCheck.summary];
+    for (const docArea of input.config.docAreas) {
+        const signals = [];
+        const impactedDocs = new Set(docArea.patch.targets ?? []);
+        const summaries = [];
+        if (docsCheck.signal) {
+            signals.push(docsCheck.signal);
+            summaries.push(docsCheck.summary);
+        }
+        if (docArea.detect.openapi) {
+            const openapiResult = await (0, openapi_1.detectOpenApiDrift)(docArea, evidenceRoot);
+            if (openapiResult.signal) {
+                signals.push(openapiResult.signal);
+            }
+            openapiResult.impactedDocs.forEach((doc) => impactedDocs.add(doc));
+            summaries.push(openapiResult.summary);
+        }
+        if (docArea.detect.paths?.length) {
+            const heuristicResult = (0, heuristics_1.detectHeuristicImpacts)(docArea, changedPaths, evidenceRoot);
+            if (heuristicResult.signal) {
+                signals.push(heuristicResult.signal);
+            }
+            heuristicResult.impactedDocs.forEach((doc) => impactedDocs.add(doc));
+            summaries.push(heuristicResult.summary);
+        }
+        if (!signals.length) {
+            continue;
+        }
+        items.push({
+            docArea: docArea.name,
+            mode: docArea.mode,
+            signals,
+            impactedDocs: [...impactedDocs],
+            recommendedAction: defaultRecommendation(docArea.mode, signals),
+            summary: summaries.filter(Boolean).join(" | ")
+        });
+    }
+    const report = {
+        run: {
+            repo: input.repo,
+            baseSha: input.baseSha,
+            headSha: input.headSha,
+            trigger: input.trigger,
+            timestamp: runInfo.timestamp
+        },
+        items
+    };
+    (0, fs_1.writeJsonFile)(node_path_1.default.resolve(".docdrift", "drift_report.json"), report);
+    (0, fs_1.writeJsonFile)(node_path_1.default.join(evidenceRoot, "changeset.json"), {
+        changedPaths,
+        diffSummary,
+        commits
+    });
+    return { report, changedPaths, evidenceRoot, runInfo, checkSummaries };
+}

package/dist/src/detect/openapi.js

@@ -0,0 +1,123 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectOpenApiDrift = detectOpenApiDrift;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const exec_1 = require("../utils/exec");
+const fs_1 = require("../utils/fs");
+const json_1 = require("../utils/json");
+function responseFields(spec) {
+    const fields = new Set();
+    const paths = spec?.paths ?? {};
+    for (const [pathName, methods] of Object.entries(paths)) {
+        for (const [method, methodDef] of Object.entries(methods)) {
+            const schema = methodDef?.responses?.["200"]?.content?.["application/json"]?.schema;
+            const properties = schema?.properties ?? {};
+            for (const key of Object.keys(properties)) {
+                fields.add(`${String(method).toUpperCase()} ${pathName}: ${key}`);
+            }
+        }
+    }
+    return fields;
+}
+function summarizeSpecDelta(previousSpec, currentSpec) {
+    const previous = responseFields(previousSpec);
+    const current = responseFields(currentSpec);
+    const added = [...current].filter((item) => !previous.has(item)).sort();
+    const removed = [...previous].filter((item) => !current.has(item)).sort();
+    const lines = [];
+    if (added.length) {
+        lines.push(`Added response fields (${added.length}):`);
+        lines.push(...added.map((value) => `+ ${value}`));
+    }
+    if (removed.length) {
+        lines.push(`Removed response fields (${removed.length}):`);
+        lines.push(...removed.map((value) => `- ${value}`));
+    }
+    if (!lines.length) {
+        return "OpenAPI changed, but no top-level response field changes were detected in 200 responses.";
+    }
+    return lines.join("\n");
+}
+async function detectOpenApiDrift(docArea, evidenceDir) {
+    if (!docArea.detect.openapi) {
+        return { impactedDocs: [], evidenceFiles: [], summary: "No OpenAPI detector configured" };
+    }
+    (0, fs_1.ensureDir)(evidenceDir);
+    const openapi = docArea.detect.openapi;
+    const exportLogPath = node_path_1.default.join(evidenceDir, `${docArea.name}.openapi-export.log`);
+    const exportResult = await (0, exec_1.execCommand)(openapi.exportCmd);
+    node_fs_1.default.writeFileSync(exportLogPath, [
+        `$ ${openapi.exportCmd}`,
+        `exitCode: ${exportResult.exitCode}`,
+        "\n--- stdout ---",
+        exportResult.stdout,
+        "\n--- stderr ---",
+        exportResult.stderr
+    ].join("\n"), "utf8");
+    if (exportResult.exitCode !== 0) {
+        return {
+            impactedDocs: [openapi.publishedPath],
+            evidenceFiles: [exportLogPath],
+            summary: "OpenAPI export command failed",
+            signal: {
+                kind: "weak_evidence",
+                tier: 2,
+                confidence: 0.35,
+                evidence: [exportLogPath]
+            }
+        };
+    }
+    if (!node_fs_1.default.existsSync(openapi.generatedPath) || !node_fs_1.default.existsSync(openapi.publishedPath)) {
+        return {
+            impactedDocs: [openapi.generatedPath, openapi.publishedPath],
+            evidenceFiles: [exportLogPath],
+            summary: "OpenAPI file(s) missing",
+            signal: {
+                kind: "weak_evidence",
+                tier: 2,
+                confidence: 0.35,
+                evidence: [exportLogPath]
+            }
+        };
+    }
+    const generatedRaw = node_fs_1.default.readFileSync(openapi.generatedPath, "utf8");
+    const publishedRaw = node_fs_1.default.readFileSync(openapi.publishedPath, "utf8");
+    const generatedJson = JSON.parse(generatedRaw);
+    const publishedJson = JSON.parse(publishedRaw);
+    const normalizedGenerated = (0, json_1.stableStringify)(generatedJson);
+    const normalizedPublished = (0, json_1.stableStringify)(publishedJson);
+    if (normalizedGenerated === normalizedPublished) {
+        return {
+            impactedDocs: [openapi.publishedPath],
+            evidenceFiles: [exportLogPath],
+            summary: "No OpenAPI drift detected"
+        };
+    }
+    const summary = summarizeSpecDelta(publishedJson, generatedJson);
+    const diffPath = node_path_1.default.join(evidenceDir, `${docArea.name}.openapi.diff.txt`);
+    node_fs_1.default.writeFileSync(diffPath, [
+        "# OpenAPI Drift Summary",
+        summary,
+        "",
+        "# Published (normalized)",
+        normalizedPublished,
+        "",
+        "# Generated (normalized)",
+        normalizedGenerated
+    ].join("\n"), "utf8");
+    return {
+        impactedDocs: [...new Set([openapi.publishedPath, ...(docArea.patch.targets ?? [])])],
+        evidenceFiles: [exportLogPath, diffPath],
+        summary,
+        signal: {
+            kind: "openapi_diff",
+            tier: 1,
+            confidence: 0.95,
+            evidence: [diffPath]
+        }
+    };
+}