@devinnn/docdrift 0.1.2 → 0.1.4

package/dist/src/cli.js

@@ -1,5 +1,38 @@
 #!/usr/bin/env node
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -17,7 +50,16 @@ function getArg(args, flag) {
 async function main() {
     const [, , command, ...args] = process.argv;
     if (!command) {
-        throw new Error("Usage: docdrift <validate|detect|run|status|sla-check> [options]");
+        throw new Error("Usage: docdrift <validate|detect|run|status|sla-check|setup|generate-yaml> [options]\n  detect|run: [--base SHA] [--head SHA] (defaults: merge-base with main..HEAD)\n  setup|generate-yaml: [--output path] [--force]");
+    }
+    if (command === "setup" || command === "generate-yaml") {
+        require("dotenv").config();
+        const { runSetup } = await Promise.resolve().then(() => __importStar(require("./setup")));
+        await runSetup({
+            outputPath: getArg(args, "--output") ?? "docdrift.yaml",
+            force: args.includes("--force"),
+        });
+        return;
     }
     switch (command) {
         case "validate": {
@@ -25,18 +67,20 @@ async function main() {
             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 });
+            const { baseSha, headSha } = await (0, index_1.resolveBaseHead)(getArg(args, "--base"), getArg(args, "--head"));
+            const trigger = getArg(args, "--trigger") ?? (0, index_1.resolveTrigger)(process.env.GITHUB_EVENT_NAME);
+            const prNum = getArg(args, "--pr-number");
+            const prNumber = prNum ? parseInt(prNum, 10) : (process.env.GITHUB_PR_NUMBER ? parseInt(process.env.GITHUB_PR_NUMBER, 10) : undefined);
+            const result = await (0, index_1.runDetect)({ baseSha, headSha, trigger, prNumber: Number.isFinite(prNumber) ? prNumber : undefined });
             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 });
+            const { baseSha, headSha } = await (0, index_1.resolveBaseHead)(getArg(args, "--base"), getArg(args, "--head"));
+            const trigger = getArg(args, "--trigger") ?? (0, index_1.resolveTrigger)(process.env.GITHUB_EVENT_NAME);
+            const prNum = getArg(args, "--pr-number");
+            const prNumber = prNum ? parseInt(prNum, 10) : (process.env.GITHUB_PR_NUMBER ? parseInt(process.env.GITHUB_PR_NUMBER, 10) : undefined);
+            const results = await (0, index_1.runDocDrift)({ baseSha, headSha, trigger, prNumber: Number.isFinite(prNumber) ? prNumber : undefined });
             const outPath = node_path_1.default.resolve(".docdrift", "run-output.json");
             node_fs_1.default.mkdirSync(node_path_1.default.dirname(outPath), { recursive: true });
             node_fs_1.default.writeFileSync(outPath, JSON.stringify(results, null, 2), "utf-8");

package/dist/src/config/normalize.js

@@ -7,25 +7,84 @@ exports.normalizeConfig = normalizeConfig;
 const node_path_1 = __importDefault(require("node:path"));
 /**
  * Produce a normalized config that the rest of the app consumes.
- * Derives openapi/docsite/exclude/requireHumanReview from docAreas when using legacy config.
+ * Derives specProviders/openapi/docsite from openapi block or docAreas when not using v2 specProviders.
  */
 function normalizeConfig(config) {
+    let specProviders;
     let openapi;
     let docsite;
     let exclude = config.exclude ?? [];
     let requireHumanReview = config.requireHumanReview ?? [];
-    if (config.openapi && config.docsite) {
-        // Simple config
+    let docAreas = config.docAreas ?? [];
+    const allowConceptualOnlyRun = config.allowConceptualOnlyRun ?? false;
+    const inferMode = config.inferMode ?? true;
+    if (config.specProviders && config.specProviders.length >= 1) {
+        specProviders = config.specProviders;
+        const firstOpenApi3 = specProviders.find((p) => p.format === "openapi3");
+        if (firstOpenApi3 && firstOpenApi3.current.type === "export") {
+            openapi = {
+                export: firstOpenApi3.current.command,
+                generated: firstOpenApi3.current.outputPath,
+                published: firstOpenApi3.published,
+            };
+        }
+        else {
+            openapi = {
+                export: "echo",
+                generated: "",
+                published: specProviders[0].published,
+            };
+        }
+        const allPaths = specProviders.flatMap((p) => [p.published]);
+        const roots = new Set();
+        for (const p of allPaths) {
+            const parts = p.split("/").filter(Boolean);
+            if (parts.length >= 2)
+                roots.add(parts[0] + "/" + parts[1]);
+            else if (parts.length === 1)
+                roots.add(parts[0]);
+        }
+        docsite = roots.size > 0 ? [...roots] : config.docsite ? (Array.isArray(config.docsite) ? config.docsite : [config.docsite]) : ["."];
+    }
+    else if (config.openapi && config.docsite) {
+        specProviders = [
+            {
+                format: "openapi3",
+                current: { type: "export", command: config.openapi.export, outputPath: config.openapi.generated },
+                published: config.openapi.published,
+            },
+        ];
         openapi = config.openapi;
         docsite = Array.isArray(config.docsite) ? config.docsite : [config.docsite];
+        if (config.pathMappings?.length) {
+            const pathImpacts = new Set();
+            config.pathMappings.forEach((p) => p.impacts.forEach((i) => pathImpacts.add(i)));
+            requireHumanReview = [...new Set([...requireHumanReview, ...pathImpacts])];
+            docAreas = [
+                ...docAreas,
+                {
+                    name: "pathMappings",
+                    mode: "conceptual",
+                    owners: { reviewers: ["docdrift"] },
+                    detect: { paths: config.pathMappings },
+                    patch: { requireHumanConfirmation: true },
+                },
+            ];
+        }
     }
     else if (config.docAreas && config.docAreas.length > 0) {
-        // Legacy: derive from docAreas
         const firstOpenApiArea = config.docAreas.find((a) => a.detect.openapi);
         if (!firstOpenApiArea?.detect.openapi) {
             throw new Error("Legacy config requires at least one docArea with detect.openapi");
         }
         const o = firstOpenApiArea.detect.openapi;
+        specProviders = [
+            {
+                format: "openapi3",
+                current: { type: "export", command: o.exportCmd, outputPath: o.generatedPath },
+                published: o.publishedPath,
+            },
+        ];
         openapi = {
             export: o.exportCmd,
             generated: o.generatedPath,
@@ -45,7 +104,6 @@ function normalizeConfig(config) {
                 roots.add(parts[0]);
         }
         docsite = roots.size > 0 ? [...roots] : [node_path_1.default.dirname(o.publishedPath) || "."];
-        // Derive requireHumanReview from areas with requireHumanConfirmation or conceptual mode
         const reviewPaths = new Set();
         for (const area of config.docAreas) {
             if (area.patch.requireHumanConfirmation || area.mode === "conceptual") {
@@ -55,14 +113,43 @@ function normalizeConfig(config) {
         }
         requireHumanReview = [...reviewPaths];
     }
+    else if (config.version === 2 && config.pathMappings?.length) {
+        specProviders = [];
+        openapi = { export: "echo", generated: "", published: "" };
+        const pathImpacts = new Set();
+        config.pathMappings.forEach((p) => p.impacts.forEach((i) => pathImpacts.add(i)));
+        requireHumanReview = [...new Set([...requireHumanReview, ...pathImpacts])];
+        docAreas = [
+            {
+                name: "pathMappings",
+                mode: "conceptual",
+                owners: { reviewers: ["docdrift"] },
+                detect: { paths: config.pathMappings },
+                patch: { requireHumanConfirmation: true },
+            },
+        ];
+        const roots = new Set();
+        for (const p of pathImpacts) {
+            const parts = p.split("/").filter(Boolean);
+            if (parts.length >= 2)
+                roots.add(parts[0] + "/" + parts[1]);
+            else if (parts.length === 1)
+                roots.add(parts[0]);
+        }
+        docsite = roots.size > 0 ? [...roots] : config.docsite ? (Array.isArray(config.docsite) ? config.docsite : [config.docsite]) : ["."];
+    }
     else {
-        throw new Error("Config must include (openapi + docsite) or docAreas");
+        throw new Error("Config must include specProviders, (openapi + docsite), or docAreas");
     }
     return {
         ...config,
+        specProviders,
         openapi,
         docsite,
         exclude,
         requireHumanReview,
+        docAreas,
+        allowConceptualOnlyRun,
+        inferMode,
     };
 }

package/dist/src/config/schema.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.docDriftConfigSchema = exports.openApiSimpleSchema = void 0;
+exports.docDriftConfigSchema = exports.docDriftConfigBaseSchema = exports.docAreaBaseSchema = exports.specProviderConfigSchema = exports.openApiSimpleSchema = exports.pathRuleSchema = void 0;
 const zod_1 = require("zod");
-const pathRuleSchema = zod_1.z.object({
+/** Path rule: when `match` changes, `impacts` may need updates. Used by docAreas and by simple `paths` block. */
+exports.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),
 });
@@ -17,18 +18,47 @@ exports.openApiSimpleSchema = zod_1.z.object({
     generated: zod_1.z.string().min(1),
     published: zod_1.z.string().min(1),
 });
+/** Spec source: URL, local path, or export command */
+const specSourceSchema = zod_1.z.discriminatedUnion("type", [
+    zod_1.z.object({ type: zod_1.z.literal("url"), url: zod_1.z.string().url() }),
+    zod_1.z.object({ type: zod_1.z.literal("local"), path: zod_1.z.string().min(1) }),
+    zod_1.z.object({
+        type: zod_1.z.literal("export"),
+        command: zod_1.z.string().min(1),
+        outputPath: zod_1.z.string().min(1),
+    }),
+]);
+const specFormatSchema = zod_1.z.enum(["openapi3", "swagger2", "graphql", "fern", "postman"]);
+/** Single spec provider (v2 config) */
+exports.specProviderConfigSchema = zod_1.z.object({
+    format: specFormatSchema,
+    current: specSourceSchema,
+    published: zod_1.z.string().min(1),
+});
+const docAreaDetectBaseSchema = zod_1.z.object({
+    openapi: openApiDetectSchema.optional(),
+    paths: zod_1.z.array(exports.pathRuleSchema).optional(),
+});
+/** Base schema without refine — for JSON Schema generation (zod-to-json-schema doesn't handle .refine()) */
+exports.docAreaBaseSchema = 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: docAreaDetectBaseSchema,
+    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),
+    }),
+});
 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), {
+    detect: docAreaDetectBaseSchema.refine((v) => Boolean(v.openapi) || Boolean(v.paths?.length), {
         message: "docArea.detect must include openapi or paths",
     }),
     patch: zod_1.z.object({
@@ -59,17 +89,38 @@ const policySchema = zod_1.z.object({
      */
     allowNewFiles: zod_1.z.boolean().optional().default(false),
 });
-exports.docDriftConfigSchema = zod_1.z
-    .object({
-    version: zod_1.z.literal(1),
-    /** Simple config: openapi block (API spec = gate for run) */
+/** Base schema without refine — for JSON Schema generation (zod-to-json-schema doesn't handle .refine()) */
+exports.docDriftConfigBaseSchema = zod_1.z.object({
+    version: zod_1.z.union([zod_1.z.literal(1), zod_1.z.literal(2)]),
+    specProviders: zod_1.z.array(exports.specProviderConfigSchema).optional(),
     openapi: exports.openApiSimpleSchema.optional(),
-    /** Simple config: docsite root path(s) */
     docsite: zod_1.z.union([zod_1.z.string().min(1), zod_1.z.array(zod_1.z.string().min(1))]).optional(),
-    /** Paths we never touch (glob patterns) */
     exclude: zod_1.z.array(zod_1.z.string().min(1)).optional().default([]),
-    /** Paths that require human review when touched (we create issue post-PR) */
     requireHumanReview: zod_1.z.array(zod_1.z.string().min(1)).optional().default([]),
+    pathMappings: zod_1.z.array(exports.pathRuleSchema).optional().default([]),
+    allowConceptualOnlyRun: zod_1.z.boolean().optional().default(false),
+    inferMode: zod_1.z.boolean().optional().default(true),
+    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"]),
+        customInstructions: zod_1.z.array(zod_1.z.string().min(1)).optional(),
+        customInstructionContent: zod_1.z.string().optional(),
+    }),
+    policy: policySchema,
+    docAreas: zod_1.z.array(exports.docAreaBaseSchema).optional().default([]),
+});
+const docDriftConfigObjectSchema = zod_1.z.object({
+    version: zod_1.z.union([zod_1.z.literal(1), zod_1.z.literal(2)]),
+    specProviders: zod_1.z.array(exports.specProviderConfigSchema).optional(),
+    openapi: exports.openApiSimpleSchema.optional(),
+    docsite: zod_1.z.union([zod_1.z.string().min(1), zod_1.z.array(zod_1.z.string().min(1))]).optional(),
+    exclude: zod_1.z.array(zod_1.z.string().min(1)).optional().default([]),
+    requireHumanReview: zod_1.z.array(zod_1.z.string().min(1)).optional().default([]),
+    pathMappings: zod_1.z.array(exports.pathRuleSchema).optional().default([]),
+    allowConceptualOnlyRun: zod_1.z.boolean().optional().default(false),
+    inferMode: zod_1.z.boolean().optional().default(true),
     devin: zod_1.z.object({
         apiVersion: zod_1.z.literal("v1"),
         unlisted: zod_1.z.boolean().default(true),
@@ -79,7 +130,16 @@ exports.docDriftConfigSchema = zod_1.z
         customInstructionContent: zod_1.z.string().optional(),
     }),
     policy: policySchema,
-    /** Legacy: doc areas (optional when openapi+docsite present) */
     docAreas: zod_1.z.array(docAreaSchema).optional().default([]),
-})
-    .refine((v) => (v.openapi && v.docsite) || v.docAreas.length >= 1, { message: "Config must include (openapi + docsite) or docAreas" });
+});
+exports.docDriftConfigSchema = docDriftConfigObjectSchema.refine((v) => {
+    if (v.specProviders && v.specProviders.length >= 1)
+        return true;
+    if (v.openapi && v.docsite)
+        return true;
+    if (v.docAreas.length >= 1)
+        return true;
+    if (v.version === 2 && (v.pathMappings?.length ?? 0) >= 1)
+        return true;
+    return false;
+}, { message: "Config must include specProviders, (openapi + docsite), docAreas, or (v2 + pathMappings)" });

package/dist/src/config/validate.js

@@ -11,11 +11,15 @@ async function validateRuntimeConfig(config) {
     if (config.policy.prCaps.maxFilesTouched < 1) {
         errors.push("policy.prCaps.maxFilesTouched must be >= 1");
     }
-    const commandSet = new Set([
+    const exportCommands = [
         ...config.policy.verification.commands,
         ...(config.openapi ? [config.openapi.export] : []),
         ...(config.docAreas ?? []).map((area) => area.detect.openapi?.exportCmd).filter((value) => Boolean(value)),
-    ]);
+        ...(config.specProviders ?? [])
+            .filter((p) => p.current.type === "export")
+            .map((p) => p.current.command),
+    ];
+    const commandSet = new Set(exportCommands);
     for (const command of commandSet) {
         const binary = commandBinary(command);
         const result = await (0, exec_1.execCommand)(`command -v ${binary}`);

package/dist/src/detect/index.js

@@ -8,7 +8,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const fs_1 = require("../utils/fs");
 const git_1 = require("../utils/git");
 const heuristics_1 = require("./heuristics");
-const openapi_1 = require("./openapi");
+const registry_1 = require("../spec-providers/registry");
 async function buildDriftReport(input) {
     const runInfo = {
         runId: `${Date.now()}`,
@@ -17,6 +17,7 @@ async function buildDriftReport(input) {
         headSha: input.headSha,
         trigger: input.trigger,
         timestamp: new Date().toISOString(),
+        prNumber: input.prNumber,
     };
     const evidenceRoot = node_path_1.default.resolve(".docdrift", "evidence", runInfo.runId);
     (0, fs_1.ensureDir)(evidenceRoot);
@@ -28,10 +29,76 @@ async function buildDriftReport(input) {
         diffSummary,
         commits,
     });
-    // Gate: run OpenAPI detection first. If no OpenAPI drift, exit (no session).
-    const openapiResult = await (0, openapi_1.detectOpenApiDriftFromNormalized)(input.config, evidenceRoot);
-    if (!openapiResult.signal) {
-        // No OpenAPI drift — gate closed. Return empty.
+    const { config } = input;
+    const signals = [];
+    const impactedDocs = new Set();
+    const summaries = [];
+    const evidenceFiles = [];
+    // 1. Run all spec providers (parallel)
+    const providerResults = [];
+    if (config.specProviders.length > 0) {
+        const results = await Promise.all(config.specProviders.map(async (provider) => {
+            const detector = (0, registry_1.getSpecDetector)(provider.format);
+            return detector(provider, evidenceRoot);
+        }));
+        providerResults.push(...results);
+    }
+    const anySpecDrift = providerResults.some((r) => r.hasDrift && r.signal && r.signal.tier <= 1);
+    const allSpecFailedOrNoDrift = providerResults.length === 0 ||
+        providerResults.every((r) => !r.hasDrift || (r.signal?.tier ?? 2) > 1);
+    if (anySpecDrift) {
+        for (const r of providerResults) {
+            if (r.hasDrift && r.signal) {
+                signals.push(r.signal);
+                r.impactedDocs.forEach((d) => impactedDocs.add(d));
+                summaries.push(r.summary);
+                evidenceFiles.push(...r.evidenceFiles);
+            }
+        }
+    }
+    // 2. Path heuristics (always run for aggregation when we have docAreas)
+    for (const docArea of config.docAreas) {
+        if (docArea.detect.paths?.length) {
+            const heuristicResult = (0, heuristics_1.detectHeuristicImpacts)(docArea, changedPaths, evidenceRoot);
+            if (heuristicResult.signal) {
+                signals.push(heuristicResult.signal);
+                heuristicResult.impactedDocs.forEach((d) => impactedDocs.add(d));
+                summaries.push(heuristicResult.summary);
+            }
+        }
+    }
+    const hasHeuristicMatch = signals.some((s) => s.kind === "heuristic_path_impact");
+    // 3. Gate logic
+    let runGate = "none";
+    if (anySpecDrift) {
+        runGate = "spec_drift";
+    }
+    else if (config.allowConceptualOnlyRun && hasHeuristicMatch) {
+        runGate = "conceptual_only";
+    }
+    else if (config.inferMode && (config.specProviders.length === 0 || allSpecFailedOrNoDrift)) {
+        runGate = "infer";
+        if (config.specProviders.length > 0) {
+            for (const r of providerResults) {
+                if (r.signal) {
+                    signals.push(r.signal);
+                    r.impactedDocs.forEach((d) => impactedDocs.add(d));
+                    summaries.push(r.summary);
+                }
+            }
+        }
+        if (signals.length === 0) {
+            signals.push({
+                kind: "infer_mode",
+                tier: 2,
+                confidence: 0.6,
+                evidence: [node_path_1.default.join(evidenceRoot, "changeset.json")],
+            });
+            changedPaths.forEach((p) => impactedDocs.add(p));
+            summaries.push("Infer mode: no spec drift; infer docs from file changes.");
+        }
+    }
+    if (runGate === "none") {
         const report = {
             run: {
                 repo: input.repo,
@@ -50,22 +117,9 @@ async function buildDriftReport(input) {
             evidenceRoot,
             runInfo,
             hasOpenApiDrift: false,
+            runGate: "none",
         };
     }
-    // Gate passed: aggregate signals and impacted docs.
-    const signals = [openapiResult.signal];
-    const impactedDocs = new Set(openapiResult.impactedDocs);
-    const summaries = [openapiResult.summary];
-    for (const docArea of input.config.docAreas) {
-        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);
-        }
-    }
     const aggregated = {
         signals,
         impactedDocs: [...impactedDocs],
@@ -73,7 +127,7 @@ async function buildDriftReport(input) {
     };
     const item = {
         docArea: "docsite",
-        mode: "autogen",
+        mode: runGate === "conceptual_only" ? "conceptual" : "autogen",
         signals: aggregated.signals,
         impactedDocs: aggregated.impactedDocs,
         recommendedAction: aggregated.signals.some((s) => s.tier <= 1) ? "OPEN_PR" : "OPEN_ISSUE",
@@ -96,6 +150,7 @@ async function buildDriftReport(input) {
         changedPaths,
         evidenceRoot,
         runInfo,
-        hasOpenApiDrift: true,
+        hasOpenApiDrift: anySpecDrift,
+        runGate,
     };
 }

package/dist/src/devin/prompts.js

@@ -74,9 +74,52 @@ function buildWholeDocsitePrompt(input) {
     const newFilesRule = allowNewFiles
         ? "8) You MAY add new articles, create new folders, and change information architecture when warranted."
         : "8) You may ONLY edit existing files. Do NOT create new files, new articles, or new folders. Do NOT change information architecture.";
+    const driftSummary = input.aggregated.summary?.trim();
+    const openapiPublished = input.config.openapi?.published;
+    const openapiGenerated = input.config.openapi?.generated;
+    const specLine = openapiPublished && openapiGenerated
+        ? `Update ${openapiPublished} to match the generated spec (${openapiGenerated}). The attachments contain the full diff.`
+        : "Update published docs to match the evidence (attachments).";
+    const driftBlock = driftSummary &&
+        [
+            "DRIFT DETECTED (you must fix this):",
+            "---",
+            driftSummary,
+            "---",
+            specLine,
+            "",
+        ].join("\n");
+    const inferBlock = input.runGate === "infer"
+        ? [
+            "INFER MODE: No API spec diff was available. These file changes may impact docs.",
+            "Infer what documentation might need updates from the changed files. Update or create docs as needed.",
+            "Do NOT invent APIs; only document what you can infer from the code changes.",
+            "",
+        ].join("\n")
+        : "";
+    const draftPrBlock = input.trigger === "pull_request" && input.prNumber
+        ? [
+            "",
+            "This run was triggered by an open API PR. Open a **draft** pull request.",
+            `In the PR description, link to the API PR (#${input.prNumber}) and state: "Merge the API PR first, then review this doc PR."`,
+            "Use a branch name like docdrift/pr-" + input.prNumber + " or docdrift/preview-<short-sha>.",
+            "",
+        ].join("\n")
+        : "";
+    const pathMappings = input.config.pathMappings ?? [];
+    const pathMappingsBlock = pathMappings.length > 0
+        ? [
+            "PATH MAPPINGS (when these code paths change, consider these docs for updates):",
+            ...pathMappings.map((p) => `- ${p.match} → ${p.impacts.join(", ")}`),
+            "",
+        ].join("\n")
+        : "";
     const base = [
         "You are Devin. Task: update the entire docsite to match the API and code changes.",
         "",
+        driftBlock ?? "",
+        inferBlock,
+        pathMappingsBlock,
         "EVIDENCE (attachments):",
         input.attachmentUrls.map((url, i) => `- ATTACHMENT ${i + 1}: ${url}`).join("\n"),
         "",
@@ -86,7 +129,8 @@ function buildWholeDocsitePrompt(input) {
         "3) Update API reference (OpenAPI) and any impacted guides in one PR.",
         "4) Run verification commands and record results:",
         ...input.config.policy.verification.commands.map((c) => `   - ${c}`),
-        "5) Open exactly ONE pull request with a clear title and reviewer-friendly description.",
+        "5) Open exactly ONE pull request with a clear title and reviewer-friendly description." +
+            draftPrBlock,
         `6) Docsite scope: ${input.config.docsite.join(", ")}` +
             excludeNote +
             requireReviewNote +

package/dist/src/devin/v1.js

@@ -91,12 +91,37 @@ async function devinListSessions(apiKey, params = {}) {
     }
     return [];
 }
+const TERMINAL_STATUSES = [
+    "finished",
+    "blocked",
+    "error",
+    "cancelled",
+    "done",
+    "complete",
+    "completed",
+    "success",
+    "terminated",
+];
+function hasPrUrl(session) {
+    if (typeof session.pull_request_url === "string" && session.pull_request_url)
+        return true;
+    if (typeof session.pr_url === "string" && session.pr_url)
+        return true;
+    const structured = (session.structured_output ?? session.data?.structured_output);
+    if (structured?.pr?.url)
+        return true;
+    return false;
+}
 async function pollUntilTerminal(apiKey, sessionId, timeoutMs = 30 * 60_000) {
     const started = Date.now();
     while (Date.now() - started < timeoutMs) {
         const session = await devinGetSession(apiKey, sessionId);
         const status = String(session.status_enum ?? session.status ?? "UNKNOWN").toLowerCase();
-        if (["finished", "blocked", "error", "cancelled", "done", "complete"].includes(status)) {
+        if (TERMINAL_STATUSES.includes(status)) {
+            return session;
+        }
+        // Session already produced a PR; stop polling so we don't timeout waiting for status to flip
+        if (hasPrUrl(session)) {
             return session;
         }
         await new Promise((resolve) => setTimeout(resolve, 5000));

package/dist/src/github/client.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseRepo = parseRepo;
 exports.postCommitComment = postCommitComment;
+exports.postPrComment = postPrComment;
 exports.createIssue = createIssue;
 exports.renderRunComment = renderRunComment;
 exports.renderBlockedIssueBody = renderBlockedIssueBody;
@@ -28,6 +29,18 @@ async function postCommitComment(input) {
     });
     return response.data.html_url;
 }
+/** Post a comment on a pull request (e.g. to link the doc drift PR when trigger is pull_request). */
+async function postPrComment(input) {
+    const octokit = new rest_1.Octokit({ auth: input.token });
+    const { owner, repo } = parseRepo(input.repository);
+    const response = await octokit.issues.createComment({
+        owner,
+        repo,
+        issue_number: input.prNumber,
+        body: input.body,
+    });
+    return response.data.html_url;
+}
 async function createIssue(input) {
     const octokit = new rest_1.Octokit({ auth: input.token });
     const { owner, repo } = parseRepo(input.repository);