@devinnn/docdrift 0.1.3 → 0.1.6

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,23 @@ 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]\n  detect|run: [--base SHA] [--head SHA] (defaults: merge-base with main..HEAD)");
+        throw new Error("Usage: docdrift <validate|detect|run|status|sla-check|setup|generate-yaml> [options]\n" +
+            "  validate          Validate docdrift.yaml (v2 config)\n" +
+            "  detect            Check for drift [--base SHA] [--head SHA]\n" +
+            "  run               Full run with Devin [--base SHA] [--head SHA]\n" +
+            "  status            Show run status [--since 24h]\n" +
+            "  sla-check         Check SLA for unmerged PRs\n" +
+            "  setup             Interactive setup (generates v2 docdrift.yaml)\n" +
+            "  generate-yaml     Generate config [--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": {

package/dist/src/config/normalize.js

@@ -16,8 +16,7 @@ function normalizeConfig(config) {
     let exclude = config.exclude ?? [];
     let requireHumanReview = config.requireHumanReview ?? [];
     let docAreas = config.docAreas ?? [];
-    const allowConceptualOnlyRun = config.allowConceptualOnlyRun ?? false;
-    const inferMode = config.inferMode ?? true;
+    const mode = config.mode ?? "strict";
     if (config.specProviders && config.specProviders.length >= 1) {
         specProviders = config.specProviders;
         const firstOpenApi3 = specProviders.find((p) => p.format === "openapi3");
@@ -149,7 +148,6 @@ function normalizeConfig(config) {
         exclude,
         requireHumanReview,
         docAreas,
-        allowConceptualOnlyRun,
-        inferMode,
+        mode,
     };
 }

package/dist/src/config/schema.js

@@ -98,8 +98,8 @@ exports.docDriftConfigBaseSchema = zod_1.z.object({
     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),
+    /** strict: only run on spec drift. auto: also run when pathMappings match (no spec drift). */
+    mode: zod_1.z.enum(["strict", "auto"]).optional().default("strict"),
     devin: zod_1.z.object({
         apiVersion: zod_1.z.literal("v1"),
         unlisted: zod_1.z.boolean().default(true),
@@ -119,8 +119,8 @@ const docDriftConfigObjectSchema = zod_1.z.object({
     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),
+    /** strict: only run on spec drift. auto: also run when pathMappings match (no spec drift). */
+    mode: zod_1.z.enum(["strict", "auto"]).optional().default("strict"),
     devin: zod_1.z.object({
         apiVersion: zod_1.z.literal("v1"),
         unlisted: zod_1.z.boolean().default(true),

package/dist/src/detect/index.js

@@ -7,6 +7,7 @@ exports.buildDriftReport = buildDriftReport;
 const node_path_1 = __importDefault(require("node:path"));
 const fs_1 = require("../utils/fs");
 const git_1 = require("../utils/git");
+const glob_1 = require("../utils/glob");
 const heuristics_1 = require("./heuristics");
 const registry_1 = require("../spec-providers/registry");
 async function buildDriftReport(input) {
@@ -68,15 +69,21 @@ async function buildDriftReport(input) {
         }
     }
     const hasHeuristicMatch = signals.some((s) => s.kind === "heuristic_path_impact");
+    const pathMappings = config.pathMappings ?? [];
+    const hasPathMappingMatch = pathMappings.length > 0 &&
+        changedPaths.some((p) => pathMappings.some((m) => (0, glob_1.matchesGlob)(m.match, p)));
     // 3. Gate logic
+    const isAuto = config.mode === "auto";
     let runGate = "none";
     if (anySpecDrift) {
         runGate = "spec_drift";
     }
-    else if (config.allowConceptualOnlyRun && hasHeuristicMatch) {
+    else if (isAuto && hasHeuristicMatch) {
         runGate = "conceptual_only";
     }
-    else if (config.inferMode && (config.specProviders.length === 0 || allSpecFailedOrNoDrift)) {
+    else if (isAuto &&
+        hasPathMappingMatch &&
+        (config.specProviders.length === 0 || allSpecFailedOrNoDrift)) {
         runGate = "infer";
         if (config.specProviders.length > 0) {
             for (const r of providerResults) {

package/dist/src/devin/prompts.js

@@ -97,15 +97,29 @@ function buildWholeDocsitePrompt(input) {
             "",
         ].join("\n")
         : "";
-    const draftPrBlock = input.trigger === "pull_request" && input.prNumber
-        ? [
+    const draftPrBlock = (() => {
+        if (input.trigger !== "pull_request" || !input.prNumber)
+            return "";
+        if (input.existingDocdriftPr) {
+            return [
+                "",
+                "CRITICAL: An existing doc-drift PR already exists for this API PR.",
+                `You MUST UPDATE that PR — do NOT create a new one.`,
+                `- Existing PR: #${input.existingDocdriftPr.number} (${input.existingDocdriftPr.url})`,
+                `- Branch to update: ${input.existingDocdriftPr.headRef}`,
+                "Checkout that branch, pull latest main, apply your doc changes, push. The existing PR will update.",
+                "Do NOT open a new pull request.",
+                "",
+            ].join("\n");
+        }
+        return [
             "",
             "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>.",
+            "Use branch name docdrift/pr-" + input.prNumber + " (required for future runs to update this PR).",
             "",
-        ].join("\n")
-        : "";
+        ].join("\n");
+    })();
     const pathMappings = input.config.pathMappings ?? [];
     const pathMappingsBlock = pathMappings.length > 0
         ? [

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

@@ -10,6 +10,7 @@ exports.renderRequireHumanReviewIssueBody = renderRequireHumanReviewIssueBody;
 exports.renderSlaIssueBody = renderSlaIssueBody;
 exports.isPrOpen = isPrOpen;
 exports.listOpenPrsWithLabel = listOpenPrsWithLabel;
+exports.findExistingDocdriftPrForSource = findExistingDocdriftPrForSource;
 const rest_1 = require("@octokit/rest");
 function parseRepo(full) {
     const [owner, repo] = full.split("/");
@@ -172,3 +173,26 @@ async function listOpenPrsWithLabel(token, repository, label) {
         created_at: pr.created_at ?? "",
     }));
 }
+/** Find an existing open docdrift PR for a given source PR number.
+ * Looks for PRs from branch docdrift/pr-{sourcePrNumber} (Devin's convention).
+ * Returns the first match so we can instruct Devin to update it instead of creating a new one.
+ */
+async function findExistingDocdriftPrForSource(token, repository, sourcePrNumber) {
+    const octokit = new rest_1.Octokit({ auth: token });
+    const { owner, repo } = parseRepo(repository);
+    const branchName = `docdrift/pr-${sourcePrNumber}`;
+    const { data } = await octokit.pulls.list({
+        owner,
+        repo,
+        state: "open",
+        head: branchName,
+    });
+    const pr = data[0];
+    if (!pr)
+        return null;
+    return {
+        number: pr.number,
+        url: pr.html_url ?? "",
+        headRef: pr.head?.ref ?? branchName,
+    };
+}

package/dist/src/index.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.STATE_PATH = void 0;
+exports.runSetup = exports.STATE_PATH = void 0;
 exports.runDetect = runDetect;
 exports.runDocDrift = runDocDrift;
 exports.runValidate = runValidate;
@@ -97,6 +97,7 @@ async function executeSessionSingle(input) {
         runGate: input.runGate,
         trigger: input.trigger,
         prNumber: input.prNumber,
+        existingDocdriftPr: input.existingDocdriftPr,
     });
     const session = await (0, v1_1.devinCreateSession)(input.apiKey, {
         prompt,
@@ -256,6 +257,16 @@ async function runDocDrift(options) {
     }
     const bundle = await (0, bundle_1.buildEvidenceBundle)({ runInfo, item, evidenceRoot });
     const attachmentPaths = [...new Set([bundle.archivePath, ...bundle.attachmentPaths])];
+    let existingDocdriftPr;
+    if (githubToken && runInfo.trigger === "pull_request" && runInfo.prNumber) {
+        existingDocdriftPr = (await (0, client_1.findExistingDocdriftPrForSource)(githubToken, repo, runInfo.prNumber)) ?? undefined;
+        if (existingDocdriftPr) {
+            (0, log_1.logInfo)("Found existing docdrift PR for source PR; will instruct Devin to update it", {
+                existingPr: existingDocdriftPr.number,
+                headRef: existingDocdriftPr.headRef,
+            });
+        }
+    }
     let sessionOutcome = {
         outcome: "NO_CHANGE",
         summary: "Skipped Devin session",
@@ -276,6 +287,7 @@ async function runDocDrift(options) {
             runGate,
             trigger: runInfo.trigger,
             prNumber: runInfo.prNumber,
+            existingDocdriftPr,
         });
         metrics.timeToSessionTerminalMs.push(Date.now() - sessionStart);
     }
@@ -296,7 +308,7 @@ async function runDocDrift(options) {
         metrics.prsOpened += 1;
         state.lastDocDriftPrUrl = sessionOutcome.prUrl;
         state.lastDocDriftPrOpenedAt = new Date().toISOString();
-        if (githubToken && runInfo.trigger === "pull_request" && runInfo.prNumber) {
+        if (githubToken && runInfo.trigger === "pull_request" && runInfo.prNumber && !existingDocdriftPr) {
             await (0, client_1.postPrComment)({
                 token: githubToken,
                 repository: repo,
@@ -322,19 +334,18 @@ async function runDocDrift(options) {
         }
     }
     else if (githubToken &&
-        (decision.action === "OPEN_ISSUE" ||
-            sessionOutcome.outcome === "BLOCKED" ||
-            sessionOutcome.outcome === "NO_CHANGE")) {
+        sessionOutcome.outcome === "BLOCKED" &&
+        sessionOutcome.summary.includes("DEVIN_API_KEY")) {
         issueUrl = await (0, client_1.createIssue)({
             token: githubToken,
             repository: repo,
             issue: {
-                title: "[docdrift] docsite: docs drift requires input",
+                title: "[docdrift] Configuration required — set DEVIN_API_KEY",
                 body: (0, client_1.renderBlockedIssueBody)({
                     docArea: item.docArea,
-                    evidenceSummary: item.summary,
+                    evidenceSummary: sessionOutcome.summary,
                     questions: sessionOutcome.questions ?? [
-                        "Please confirm intended behavior and doc wording.",
+                        "Set DEVIN_API_KEY in GitHub Actions secrets or environment.",
                     ],
                     sessionUrl: sessionOutcome.sessionUrl,
                 }),
@@ -342,10 +353,11 @@ async function runDocDrift(options) {
             },
         });
         metrics.issuesOpened += 1;
-        if (sessionOutcome.outcome !== "PR_OPENED") {
-            sessionOutcome.outcome = "ISSUE_OPENED";
-        }
     }
+    // Note: We do NOT create "docs drift requires input" issues for Devin-reported BLOCKED
+    // (evidence questions) or for OPEN_ISSUE/NO_CHANGE. Issues are only created for:
+    // (1) requireHumanReview when a PR touches those paths, (2) 7-day SLA reminders,
+    // and (3) DEVIN_API_KEY missing. See docdrift-yml.md.
     if (sessionOutcome.outcome === "BLOCKED") {
         metrics.blockedCount += 1;
     }
@@ -534,3 +546,5 @@ async function resolveBaseHead(baseArg, headArg) {
     return resolveDefaultBaseHead(headRef);
 }
 exports.STATE_PATH = node_path_1.default.resolve(".docdrift", "state.json");
+var setup_1 = require("./setup");
+Object.defineProperty(exports, "runSetup", { enumerable: true, get: function () { return setup_1.runSetup; } });

package/dist/src/setup/ai-infer.js

@@ -0,0 +1,217 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferConfigFromFingerprint = inferConfigFromFingerprint;
+const gateway_1 = require("@ai-sdk/gateway");
+const ai_1 = require("ai");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const zod_1 = require("zod");
+const repo_fingerprint_1 = require("./repo-fingerprint");
+const prompts_1 = require("./prompts");
+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 specProviderSchema = zod_1.z.object({
+    format: zod_1.z.enum(["openapi3", "swagger2", "graphql", "fern", "postman"]),
+    current: zod_1.z.object({
+        type: zod_1.z.literal("export"),
+        command: zod_1.z.string().min(1),
+        outputPath: zod_1.z.string().min(1),
+    }),
+    published: zod_1.z.string().min(1),
+});
+const InferenceSchema = zod_1.z.object({
+    suggestedConfig: zod_1.z.object({
+        version: zod_1.z.literal(2).optional(),
+        specProviders: zod_1.z.array(specProviderSchema).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(),
+        requireHumanReview: zod_1.z.array(zod_1.z.string().min(1)).optional(),
+        pathMappings: zod_1.z.array(pathRuleSchema).optional(),
+        mode: zod_1.z.enum(["strict", "auto"]).optional(),
+        devin: zod_1.z
+            .object({
+            apiVersion: zod_1.z.literal("v1"),
+            unlisted: zod_1.z.boolean().optional(),
+            maxAcuLimit: zod_1.z.number().optional(),
+            tags: zod_1.z.array(zod_1.z.string()).optional(),
+            customInstructions: zod_1.z.array(zod_1.z.string()).optional(),
+        })
+            .optional(),
+        policy: zod_1.z
+            .object({
+            prCaps: zod_1.z.object({ maxPrsPerDay: zod_1.z.number(), maxFilesTouched: zod_1.z.number() }).optional(),
+            confidence: zod_1.z.object({ autopatchThreshold: zod_1.z.number() }).optional(),
+            allowlist: zod_1.z.array(zod_1.z.string().min(1)).optional(),
+            verification: zod_1.z.object({ commands: zod_1.z.array(zod_1.z.string().min(1)) }).optional(),
+            slaDays: zod_1.z.number().optional(),
+            slaLabel: zod_1.z.string().optional(),
+            allowNewFiles: zod_1.z.boolean().optional(),
+        })
+            .optional(),
+    }),
+    choices: zod_1.z.array(zod_1.z.object({
+        key: zod_1.z.string(),
+        question: zod_1.z.string(),
+        options: zod_1.z.array(zod_1.z.object({
+            value: zod_1.z.string(),
+            label: zod_1.z.string(),
+            recommended: zod_1.z.boolean().optional(),
+        })),
+        defaultIndex: zod_1.z.number(),
+        help: zod_1.z.string().optional(),
+        warning: zod_1.z.string().optional(),
+        confidence: zod_1.z.enum(["high", "medium", "low"]),
+    })),
+    skipQuestions: zod_1.z.array(zod_1.z.string()).optional(),
+});
+const CACHE_DIR = ".docdrift";
+const CACHE_FILE = "setup-cache.json";
+function getCachePath(cwd) {
+    return node_path_1.default.resolve(cwd, CACHE_DIR, CACHE_FILE);
+}
+function readCache(cwd) {
+    const cachePath = getCachePath(cwd);
+    if (!node_fs_1.default.existsSync(cachePath))
+        return null;
+    try {
+        const raw = JSON.parse(node_fs_1.default.readFileSync(cachePath, "utf8"));
+        const parsed = InferenceSchema.safeParse(raw.inference);
+        if (!parsed.success)
+            return null;
+        return {
+            fingerprintHash: String(raw.fingerprintHash),
+            inference: parsed.data,
+            timestamp: Number(raw.timestamp) || 0,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(cwd, fingerprintHash, inference) {
+    const dir = node_path_1.default.resolve(cwd, CACHE_DIR);
+    node_fs_1.default.mkdirSync(dir, { recursive: true });
+    node_fs_1.default.writeFileSync(getCachePath(cwd), JSON.stringify({ fingerprintHash, inference, timestamp: Date.now() }, null, 2), "utf8");
+}
+function heuristicInference(fingerprint) {
+    const scripts = fingerprint.rootPackage.scripts || {};
+    const scriptNames = Object.keys(scripts);
+    const openapiScriptName = scriptNames.find((s) => s === "openapi:export" || s === "openapi:generate");
+    const openapiExport = openapiScriptName ? `npm run ${openapiScriptName}` : "npm run openapi:export";
+    const firstOpenapi = fingerprint.foundPaths.openapi[0];
+    const firstDocsite = fingerprint.foundPaths.docusaurusConfig[0]
+        ? node_path_1.default.dirname(fingerprint.foundPaths.docusaurusConfig[0]).replace(/\\/g, "/")
+        : fingerprint.foundPaths.docsDirs[0]
+            ? node_path_1.default.dirname(fingerprint.foundPaths.docsDirs[0]).replace(/\\/g, "/")
+            : "apps/docs-site";
+    const published = firstOpenapi && firstOpenapi.includes(firstDocsite)
+        ? firstOpenapi
+        : `${firstDocsite}/openapi/openapi.json`;
+    const generated = firstOpenapi && !firstOpenapi.includes(firstDocsite)
+        ? firstOpenapi
+        : "openapi/generated.json";
+    const verificationCommands = [];
+    if (scripts["docs:gen"])
+        verificationCommands.push("npm run docs:gen");
+    if (scripts["docs:build"])
+        verificationCommands.push("npm run docs:build");
+    if (verificationCommands.length === 0)
+        verificationCommands.push("npm run build");
+    const treeKeys = Object.keys(fingerprint.fileTree);
+    const hasAppsApi = treeKeys.some((k) => k === "apps/api" || k.startsWith("apps/api/"));
+    const matchGlob = hasAppsApi ? "apps/api/**" : "**/api/**";
+    const allowlist = treeKeys.some((k) => k === "apps" || k.startsWith("apps/"))
+        ? ["openapi/**", "apps/**"]
+        : ["openapi/**", `${firstDocsite}/**`];
+    const requireHumanReview = fingerprint.foundPaths.docsDirs.length > 0
+        ? [`${firstDocsite}/docs/guides/**`]
+        : [];
+    return {
+        suggestedConfig: {
+            version: 2,
+            specProviders: [
+                {
+                    format: "openapi3",
+                    current: { type: "export", command: openapiExport, outputPath: generated },
+                    published,
+                },
+            ],
+            docsite: firstDocsite,
+            exclude: ["**/CHANGELOG*", "**/blog/**"],
+            requireHumanReview,
+            pathMappings: [{ match: matchGlob, impacts: [`${firstDocsite}/docs/**`, `${firstDocsite}/openapi/**`] }],
+            mode: "strict",
+            devin: { apiVersion: "v1", unlisted: true, maxAcuLimit: 2, tags: ["docdrift"] },
+            policy: {
+                prCaps: { maxPrsPerDay: 5, maxFilesTouched: 30 },
+                confidence: { autopatchThreshold: 0.8 },
+                allowlist,
+                verification: { commands: verificationCommands },
+                slaDays: 7,
+                slaLabel: "docdrift",
+                allowNewFiles: false,
+            },
+        },
+        choices: [
+            {
+                key: "specProviders.0.current.command",
+                question: "OpenAPI export command",
+                options: [{ value: openapiExport, label: openapiExport, recommended: true }],
+                defaultIndex: 0,
+                help: "Use the npm script that generates the spec (e.g. npm run openapi:export).",
+                confidence: "medium",
+            },
+            {
+                key: "docsite",
+                question: "Docsite path",
+                options: [{ value: firstDocsite, label: firstDocsite, recommended: true }],
+                defaultIndex: 0,
+                confidence: "medium",
+            },
+        ],
+        skipQuestions: [],
+    };
+}
+async function inferConfigFromFingerprint(fingerprint, cwd = process.cwd()) {
+    const apiKey = process.env.AI_GATEWAY_API_KEY?.trim();
+    const hash = (0, repo_fingerprint_1.fingerprintHash)(fingerprint);
+    const cached = readCache(cwd);
+    if (cached && cached.fingerprintHash === hash)
+        return cached.inference;
+    if (!apiKey)
+        return heuristicInference(fingerprint);
+    const gateway = (0, gateway_1.createGateway)({
+        apiKey,
+        baseURL: "https://ai-gateway.vercel.sh/v1/ai",
+    });
+    const prompt = `Repo fingerprint:\n${JSON.stringify(fingerprint, null, 2)}`;
+    try {
+        const result = await (0, ai_1.generateText)({
+            model: gateway("anthropic/claude-opus-4.6"),
+            system: prompts_1.SYSTEM_PROMPT,
+            prompt,
+            experimental_output: ai_1.Output.object({
+                schema: InferenceSchema,
+            }),
+            maxRetries: 2,
+            abortSignal: AbortSignal.timeout(60_000),
+        });
+        const output = result.experimental_output;
+        if (!output)
+            throw new Error("No structured output");
+        const parsed = InferenceSchema.safeParse(output);
+        if (!parsed.success)
+            throw new Error(parsed.error.message);
+        const inference = parsed.data;
+        writeCache(cwd, hash, inference);
+        return inference;
+    }
+    catch {
+        return heuristicInference(fingerprint);
+    }
+}

package/dist/src/setup/generate-yaml.js

@@ -0,0 +1,132 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildConfigFromInference = buildConfigFromInference;
+exports.writeConfig = writeConfig;
+exports.validateGeneratedConfig = validateGeneratedConfig;
+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("../config/schema");
+function deepMerge(target, source) {
+    const out = { ...target };
+    for (const key of Object.keys(source)) {
+        const s = source[key];
+        const t = out[key];
+        if (s != null && typeof s === "object" && !Array.isArray(s) && t != null && typeof t === "object" && !Array.isArray(t)) {
+            out[key] = deepMerge(t, s);
+        }
+        else if (s !== undefined) {
+            out[key] = s;
+        }
+    }
+    return out;
+}
+function applyOverrides(base, overrides) {
+    for (const [key, value] of Object.entries(overrides)) {
+        setByKey(base, key, value);
+    }
+}
+function setByKey(obj, key, value) {
+    const parts = key.split(".");
+    let cur = obj;
+    let i = 0;
+    while (i < parts.length - 1) {
+        const p = parts[i];
+        const nextPart = parts[i + 1];
+        const isArrayIndex = nextPart !== undefined && /^\d+$/.test(nextPart);
+        const existing = cur[p];
+        if (existing != null && typeof existing === "object") {
+            if (Array.isArray(existing) && isArrayIndex) {
+                const idx = parseInt(nextPart, 10);
+                let el = existing[idx];
+                if (el == null || typeof el !== "object") {
+                    el = {};
+                    existing[idx] = el;
+                }
+                cur = el;
+                i += 2;
+                continue;
+            }
+            if (!Array.isArray(existing)) {
+                cur = existing;
+            }
+            else {
+                cur[p] = isArrayIndex ? [] : {};
+                cur = cur[p];
+            }
+        }
+        else {
+            const next = isArrayIndex ? [] : {};
+            cur[p] = next;
+            cur = next;
+        }
+        i++;
+    }
+    cur[parts[parts.length - 1]] = value;
+}
+const DEFAULT_CONFIG = {
+    version: 2,
+    specProviders: [
+        {
+            format: "openapi3",
+            current: {
+                type: "export",
+                command: "npm run openapi:export",
+                outputPath: "openapi/generated.json",
+            },
+            published: "apps/docs-site/openapi/openapi.json",
+        },
+    ],
+    docsite: "apps/docs-site",
+    exclude: [],
+    requireHumanReview: [],
+    pathMappings: [],
+    mode: "strict",
+    devin: {
+        apiVersion: "v1",
+        unlisted: true,
+        maxAcuLimit: 2,
+        tags: ["docdrift"],
+    },
+    policy: {
+        prCaps: { maxPrsPerDay: 5, maxFilesTouched: 30 },
+        confidence: { autopatchThreshold: 0.8 },
+        allowlist: ["openapi/**", "apps/**"],
+        verification: { commands: ["npm run docs:gen", "npm run docs:build"] },
+        slaDays: 7,
+        slaLabel: "docdrift",
+        allowNewFiles: false,
+    },
+};
+function buildConfigFromInference(inference, formResult) {
+    const base = deepMerge({ ...DEFAULT_CONFIG }, inference.suggestedConfig);
+    applyOverrides(base, formResult.configOverrides);
+    return base;
+}
+function writeConfig(config, outputPath) {
+    const dir = node_path_1.default.dirname(outputPath);
+    node_fs_1.default.mkdirSync(dir, { recursive: true });
+    const yamlContent = [
+        "# yaml-language-server: $schema=./docdrift.schema.json",
+        js_yaml_1.default.dump(config, { lineWidth: 120, noRefs: true }),
+    ].join("\n");
+    node_fs_1.default.writeFileSync(outputPath, yamlContent, "utf8");
+}
+function validateGeneratedConfig(configPath) {
+    try {
+        const content = node_fs_1.default.readFileSync(configPath, "utf8");
+        const parsed = js_yaml_1.default.load(content);
+        const result = schema_1.docDriftConfigSchema.safeParse(parsed);
+        if (!result.success) {
+            const errors = result.error.errors.map((e) => `${e.path.join(".") || "root"}: ${e.message}`);
+            return { ok: false, errors };
+        }
+        return { ok: true, errors: [] };
+    }
+    catch (err) {
+        return { ok: false, errors: [err instanceof Error ? err.message : String(err)] };
+    }
+}

package/dist/src/setup/index.js

@@ -0,0 +1,109 @@
+"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 };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSetup = runSetup;
+const node_path_1 = __importDefault(require("node:path"));
+const repo_fingerprint_1 = require("./repo-fingerprint");
+const ai_infer_1 = require("./ai-infer");
+const interactive_form_1 = require("./interactive-form");
+const generate_yaml_1 = require("./generate-yaml");
+const onboard_1 = require("./onboard");
+const index_1 = require("../index");
+async function runSetup(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const outputPath = node_path_1.default.resolve(cwd, options.outputPath ?? "docdrift.yaml");
+    const configExists = await Promise.resolve().then(() => __importStar(require("node:fs"))).then((fs) => fs.existsSync(outputPath));
+    if (configExists && !options.force) {
+        const { confirm } = await Promise.resolve().then(() => __importStar(require("@inquirer/prompts")));
+        const overwrite = await confirm({
+            message: "Config already exists. Overwrite?",
+            default: false,
+        });
+        if (!overwrite) {
+            console.log("Setup cancelled.");
+            return;
+        }
+    }
+    process.stdout.write("Analyzing your repo…\n");
+    const fingerprint = (0, repo_fingerprint_1.buildRepoFingerprint)(cwd);
+    process.stdout.write("Generating suggestions…\n");
+    const inference = await (0, ai_infer_1.inferConfigFromFingerprint)(fingerprint, cwd);
+    const formResult = await (0, interactive_form_1.runInteractiveForm)(inference, cwd);
+    let config = (0, generate_yaml_1.buildConfigFromInference)(inference, formResult);
+    if (formResult.onboarding.addCustomInstructions) {
+        const devin = config.devin ?? {};
+        config.devin = {
+            ...devin,
+            customInstructions: [".docdrift/DocDrift.md"],
+        };
+    }
+    (0, generate_yaml_1.writeConfig)(config, outputPath);
+    const { created } = (0, onboard_1.runOnboarding)(cwd, formResult.onboarding);
+    const validation = (0, generate_yaml_1.validateGeneratedConfig)(outputPath);
+    if (!validation.ok) {
+        console.error("Config validation failed:\n" + validation.errors.join("\n"));
+        throw new Error("Generated config is invalid. Fix the errors above or edit docdrift.yaml manually.");
+    }
+    if (outputPath === node_path_1.default.resolve(cwd, "docdrift.yaml")) {
+        try {
+            await (0, index_1.runValidate)();
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            throw err;
+        }
+    }
+    console.log("\ndocdrift setup complete\n");
+    console.log("  docdrift.yaml     written and validated");
+    for (const item of created) {
+        if (item === ".docdrift/")
+            console.log("  .docdrift/        created");
+        else if (item === "DocDrift.md")
+            console.log("  DocDrift.md       created (edit for custom instructions)");
+        else if (item === ".gitignore")
+            console.log("  .gitignore        updated");
+        else if (item.endsWith("docdrift.yml"))
+            console.log("  " + item + "  added");
+    }
+    console.log("\nNext steps:");
+    console.log("  1. Set DEVIN_API_KEY (local: .env or export; CI: repo secrets)");
+    console.log("  2. Set GITHUB_TOKEN in repo secrets for PR comments and issues");
+    console.log("  3. Run: docdrift validate   — verify config");
+    console.log("  4. Run: docdrift detect     — check for drift");
+    console.log("  5. Run: docdrift run        — create Devin session (requires DEVIN_API_KEY)");
+}

package/dist/src/setup/interactive-form.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInteractiveForm = runInteractiveForm;
+const prompts_1 = require("@inquirer/prompts");
+async function runInteractiveForm(inference, _cwd = process.cwd()) {
+    const configOverrides = {};
+    const skip = new Set(inference.skipQuestions ?? []);
+    for (const choice of inference.choices) {
+        if (skip.has(choice.key))
+            continue;
+        const options = choice.options;
+        if (options.length === 0)
+            continue;
+        const defaultOption = options[choice.defaultIndex] ?? options[0];
+        const choices = options.map((o, i) => ({
+            name: o.recommended ? `${o.label} (recommended)` : o.label,
+            value: o.value,
+        }));
+        const answer = await (0, prompts_1.select)({
+            message: choice.question,
+            choices,
+            default: defaultOption?.value,
+        });
+        configOverrides[choice.key] = answer;
+    }
+    const addCustomInstructions = await (0, prompts_1.confirm)({
+        message: "Add a custom instructions file for Devin? (PR titles, tone, project-specific guidance)",
+        default: true,
+    });
+    const addGitignore = await (0, prompts_1.confirm)({
+        message: "Add .docdrift artifact entries to .gitignore?",
+        default: true,
+    });
+    const addWorkflow = await (0, prompts_1.confirm)({
+        message: "Add GitHub Actions workflow for docdrift? (runs on push/PR to main)",
+        default: false,
+    });
+    const confirmed = await (0, prompts_1.confirm)({
+        message: "Write docdrift.yaml and complete setup? (will run validate)",
+        default: true,
+    });
+    if (!confirmed) {
+        throw new Error("Setup cancelled");
+    }
+    return {
+        configOverrides,
+        onboarding: { addCustomInstructions, addGitignore, addWorkflow },
+    };
+}

package/dist/src/setup/onboard.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureDocdriftDir = ensureDocdriftDir;
+exports.createCustomInstructionsFile = createCustomInstructionsFile;
+exports.ensureGitignore = ensureGitignore;
+exports.addGitHubWorkflow = addGitHubWorkflow;
+exports.runOnboarding = runOnboarding;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const DOCDRIFT_DIR = ".docdrift";
+const CUSTOM_INSTRUCTIONS_FILE = ".docdrift/DocDrift.md";
+const GITIGNORE_BLOCK = `
+# Docdrift run artifacts
+.docdrift/evidence
+.docdrift/*.log
+.docdrift/state.json
+.docdrift/run-output.json
+`;
+const WORKFLOW_CONTENT = "name: docdrift\n\non:\n  push:\n    branches: [\"main\"]\n  pull_request:\n    branches: [\"main\"]\n  workflow_dispatch:\n\njobs:\n  docdrift:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: write\n      pull-requests: write\n      issues: write\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n\n      - uses: actions/setup-node@v4\n        with:\n          node-version: \"20\"\n\n      - run: npm install\n\n      - name: Determine SHAs\n        id: shas\n        run: |\n          if [ \"${{ github.event_name }}\" = \"pull_request\" ]; then\n            HEAD_SHA=\"${{ github.event.pull_request.head.sha }}\"\n            BASE_SHA=\"${{ github.event.pull_request.base.sha }}\"\n          else\n            HEAD_SHA=\"${{ github.sha }}\"\n            BASE_SHA=\"${{ github.event.before }}\"\n            if [ -z \"$BASE_SHA\" ] || [ \"$BASE_SHA\" = \"0000000000000000000000000000000000000000\" ]; then\n              BASE_SHA=\"$(git rev-parse HEAD^)\"\n            fi\n          fi\n          echo \"head=${HEAD_SHA}\" >> $GITHUB_OUTPUT\n          echo \"base=${BASE_SHA}\" >> $GITHUB_OUTPUT\n          echo \"pr_number=${{ github.event.pull_request.number || '' }}\" >> $GITHUB_OUTPUT\n\n      - name: Validate config\n        run: npx docdrift validate\n\n      - name: Run Doc Drift\n        env:\n          DEVIN_API_KEY: ${{ secrets.DEVIN_API_KEY }}\n          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n          GITHUB_REPOSITORY: ${{ github.repository }}\n          GITHUB_SHA: ${{ github.sha }}\n          GITHUB_EVENT_NAME: ${{ github.event_name }}\n          GITHUB_PR_NUMBER: ${{ steps.shas.outputs.pr_number }}\n        run: |\n          PR_ARGS=\"\"\n          if [ -n \"$GITHUB_PR_NUMBER\" ]; then\n            PR_ARGS=\"--trigger pull_request --pr-number $GITHUB_PR_NUMBER\"\n          fi\n          npx docdrift run --base ${{ steps.shas.outputs.base }} --head ${{ steps.shas.outputs.head }} $PR_ARGS\n\n      - name: Upload artifacts\n        if: always()\n        uses: actions/upload-artifact@v4\n        with:\n          name: docdrift-artifacts\n          path: |\n            .docdrift/drift_report.json\n            .docdrift/metrics.json\n            .docdrift/run-output.json\n            .docdrift/evidence/**\n            .docdrift/state.json\n";
+function ensureDocdriftDir(cwd) {
+    const dir = node_path_1.default.resolve(cwd, DOCDRIFT_DIR);
+    node_fs_1.default.mkdirSync(dir, { recursive: true });
+}
+const CUSTOM_INSTRUCTIONS_TEMPLATE = `# DocDrift custom instructions
+
+- **PR titles:** Start every pull request title with \`[docdrift]\`.
+- Add project-specific guidance for Devin here (e.g. terminology, tone, what to avoid).
+`;
+function createCustomInstructionsFile(cwd) {
+    const filePath = node_path_1.default.resolve(cwd, CUSTOM_INSTRUCTIONS_FILE);
+    ensureDocdriftDir(cwd);
+    node_fs_1.default.writeFileSync(filePath, CUSTOM_INSTRUCTIONS_TEMPLATE.trimStart(), "utf8");
+}
+const GITIGNORE_ENTRIES = [
+    ".docdrift/evidence",
+    ".docdrift/*.log",
+    ".docdrift/state.json",
+    ".docdrift/run-output.json",
+];
+function hasGitignoreBlock(content) {
+    return GITIGNORE_ENTRIES.every((e) => content.includes(e));
+}
+function ensureGitignore(cwd) {
+    const gitignorePath = node_path_1.default.resolve(cwd, ".gitignore");
+    let content = "";
+    if (node_fs_1.default.existsSync(gitignorePath)) {
+        content = node_fs_1.default.readFileSync(gitignorePath, "utf8");
+        if (hasGitignoreBlock(content))
+            return;
+    }
+    const toAppend = content.endsWith("\n") ? GITIGNORE_BLOCK.trimStart() : GITIGNORE_BLOCK;
+    node_fs_1.default.writeFileSync(gitignorePath, content + toAppend, "utf8");
+}
+function addGitHubWorkflow(cwd) {
+    const workflowsDir = node_path_1.default.resolve(cwd, ".github", "workflows");
+    node_fs_1.default.mkdirSync(workflowsDir, { recursive: true });
+    const workflowPath = node_path_1.default.join(workflowsDir, "docdrift.yml");
+    node_fs_1.default.writeFileSync(workflowPath, WORKFLOW_CONTENT, "utf8");
+}
+function runOnboarding(cwd, choices) {
+    const created = [];
+    ensureDocdriftDir(cwd);
+    created.push(".docdrift/");
+    if (choices.addCustomInstructions) {
+        createCustomInstructionsFile(cwd);
+        created.push("DocDrift.md");
+    }
+    if (choices.addGitignore) {
+        ensureGitignore(cwd);
+        created.push(".gitignore");
+    }
+    if (choices.addWorkflow) {
+        addGitHubWorkflow(cwd);
+        created.push(".github/workflows/docdrift.yml");
+    }
+    return { created };
+}

package/dist/src/setup/prompts.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYSTEM_PROMPT = void 0;
+exports.SYSTEM_PROMPT = `You are a docdrift config expert. Given a repo fingerprint (file tree, package.json scripts, and detected paths), infer a partial docdrift.yaml configuration and a list of interactive choices for the user.
+
+## Docdrift config (v2)
+
+Minimal valid config uses: version: 2, specProviders (or pathMappings only for path-only setups), docsite, devin, policy.
+
+Example:
+\`\`\`yaml
+version: 2
+specProviders:
+  - format: openapi3
+    current:
+      type: export
+      command: "npm run openapi:export"
+      outputPath: "openapi/generated.json"
+    published: "apps/docs-site/openapi/openapi.json"
+docsite: "apps/docs-site"
+pathMappings:
+  - match: "apps/api/**"
+    impacts: ["apps/docs-site/docs/**", "apps/docs-site/openapi/**"]
+exclude: ["**/CHANGELOG*", "apps/docs-site/blog/**"]
+requireHumanReview: []
+mode: strict
+devin:
+  apiVersion: v1
+  unlisted: true
+  maxAcuLimit: 2
+  tags: ["docdrift"]
+policy:
+  prCaps: { maxPrsPerDay: 5, maxFilesTouched: 30 }
+  confidence: { autopatchThreshold: 0.8 }
+  allowlist: ["openapi/**", "apps/**"]
+  verification:
+    commands: ["npm run docs:gen", "npm run docs:build"]
+  slaDays: 7
+  slaLabel: docdrift
+  allowNewFiles: false
+\`\`\`
+
+## Field rules
+
+- version: Always use 2.
+- specProviders: Array of spec sources. For OpenAPI: format "openapi3", current.type "export", current.command = npm script (e.g. "npm run openapi:export"), current.outputPath = where export writes (e.g. "openapi/generated.json"), published = docsite path (e.g. "apps/docs-site/openapi/openapi.json"). Never use raw script body; use "npm run <scriptName>".
+- docsite: Path to the docs site root (Docusaurus, Next.js docs, VitePress, MkDocs). Single string or array of strings.
+- pathMappings: Array of { match, impacts }. match = glob for source/API code; impacts = globs for doc files that may need updates when match changes.
+- mode: "strict" (only run on spec drift) or "auto" (also run when pathMappings match without spec drift). Default: strict.
+- policy.verification.commands: Commands to run after patching (e.g. "npm run docs:gen", "npm run docs:build"). Must exist in repo.
+- exclude: Globs to never touch (e.g. blog, CHANGELOG).
+- requireHumanReview: Globs that require human review when touched (e.g. guides).
+
+## Path-only config (no OpenAPI)
+
+If no OpenAPI/spec found, use version: 2 with pathMappings only (no specProviders):
+\`\`\`yaml
+version: 2
+docsite: "apps/docs-site"
+pathMappings: [...]
+mode: auto
+\`\`\`
+
+## Common patterns
+
+- Docusaurus: docsite often has docusaurus.config.*; docs:gen may be "docusaurus -- gen-api-docs api"; published path often under docsite/openapi/.
+- Next/VitePress/MkDocs: docsite is the app root; look for docs/ or similar.
+
+## Output rules
+
+1. Infer suggestedConfig from the fingerprint. Use version: 2. Only include fields you can confidently infer. Use existing paths and scripts from the fingerprint; do not invent paths that are not present.
+2. For each field where confidence is medium or low, OR where multiple valid options exist, add an entry to choices with: key (e.g. "specProviders.0.current.command"), question, options (array of { value, label, recommended? }), defaultIndex, help?, warning?, confidence ("high"|"medium"|"low").
+3. Add to skipQuestions the keys for which you are highly confident so the CLI will not ask the user.
+4. Prefer fewer, high-quality choices. If truly uncertain, set confidence to "low" and provide 2–3 options.
+5. Do not suggest paths that do not exist in the fingerprint. Prefer existing package.json scripts for export and verification commands.
+6. suggestedConfig must be a valid partial docdrift config; policy.allowlist and policy.verification.commands are required if you include policy. devin.apiVersion must be "v1" if you include devin.
+
+## Example docdrift.yaml
+# yaml-language-server: $schema=./docdrift.schema.json
+version: 2
+
+specProviders:
+  - format: openapi3
+    current:
+      type: export
+      command: "npm run openapi:export"
+      outputPath: "openapi/generated.json"
+    published: "apps/docs-site/openapi/openapi.json"
+
+docsite: "apps/docs-site"
+mode: strict
+
+pathMappings:
+  - match: "apps/api/**"
+    impacts: ["apps/docs-site/docs/**", "apps/docs-site/openapi/**"]
+
+exclude:
+  - "apps/docs-site/blog/**"
+  - "**/CHANGELOG*"
+
+requireHumanReview:
+  - "apps/docs-site/docs/guides/**"
+
+devin:
+  apiVersion: v1
+  unlisted: true
+  maxAcuLimit: 2
+  tags:
+    - docdrift
+  customInstructions:
+    - "DocDrift.md"
+
+policy:
+  prCaps:
+    maxPrsPerDay: 5
+    maxFilesTouched: 30
+  confidence:
+    autopatchThreshold: 0.8
+  allowlist:
+    - "openapi/**"
+    - "apps/**"
+  verification:
+    commands:
+      - "npm run docs:gen"
+      - "npm run docs:build"
+  slaDays: 7
+  slaLabel: docdrift
+  allowNewFiles: false
+`;

package/dist/src/setup/repo-fingerprint.js

@@ -0,0 +1,155 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRepoFingerprint = buildRepoFingerprint;
+exports.fingerprintHash = fingerprintHash;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const IGNORE_DIRS = new Set(["node_modules", ".git", "dist", "build", "coverage", ".docdrift"]);
+const DOC_HINTS = ["openapi", "swagger", "docusaurus", "mkdocs", "next", "vitepress"];
+const MAX_TREE_DEPTH = 3;
+function walkDir(dir, depth, tree) {
+    if (depth > MAX_TREE_DEPTH)
+        return;
+    let entries;
+    try {
+        entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const relDir = node_path_1.default.relative(process.cwd(), dir) || ".";
+    const names = [];
+    for (const e of entries) {
+        if (e.name.startsWith(".") && e.name !== ".env")
+            continue;
+        if (IGNORE_DIRS.has(e.name))
+            continue;
+        names.push(e.isDirectory() ? `${e.name}/` : e.name);
+    }
+    names.sort();
+    tree[relDir] = names;
+    for (const e of entries) {
+        if (!e.isDirectory() || IGNORE_DIRS.has(e.name))
+            continue;
+        walkDir(node_path_1.default.join(dir, e.name), depth + 1, tree);
+    }
+}
+function findMatchingFiles(cwd, test) {
+    const out = [];
+    function walk(dir, depth) {
+        if (depth > 5)
+            return;
+        let entries;
+        try {
+            entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith(".") && e.name !== ".env")
+                continue;
+            if (IGNORE_DIRS.has(e.name))
+                continue;
+            const full = node_path_1.default.join(dir, e.name);
+            const rel = node_path_1.default.relative(cwd, full);
+            if (e.isFile() && test(rel, e.name))
+                out.push(rel);
+            else if (e.isDirectory())
+                walk(full, depth + 1);
+        }
+    }
+    walk(cwd, 0);
+    return out;
+}
+function findDirsNamed(cwd, name) {
+    const out = [];
+    function scan(dir, depth) {
+        if (depth > 2)
+            return;
+        let entries;
+        try {
+            entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith(".") || IGNORE_DIRS.has(e.name))
+                continue;
+            const full = node_path_1.default.join(dir, e.name);
+            const rel = node_path_1.default.relative(cwd, full);
+            if (e.isDirectory()) {
+                if (e.name === name)
+                    out.push(rel);
+                scan(full, depth + 1);
+            }
+        }
+    }
+    scan(cwd, 0);
+    return out;
+}
+function buildRepoFingerprint(cwd = process.cwd()) {
+    const fileTree = {};
+    walkDir(cwd, 0, fileTree);
+    let rootPackage = { scripts: {}, dependencies: [], workspaces: [] };
+    const pkgPath = node_path_1.default.join(cwd, "package.json");
+    if (node_fs_1.default.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(node_fs_1.default.readFileSync(pkgPath, "utf8"));
+            rootPackage.scripts = pkg.scripts || {};
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+            rootPackage.dependencies = Object.keys(deps || {}).filter((k) => DOC_HINTS.some((h) => k.toLowerCase().includes(h)));
+            if (pkg.workspaces) {
+                rootPackage.workspaces = Array.isArray(pkg.workspaces) ? pkg.workspaces : [pkg.workspaces];
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    const workspacePackages = [];
+    if (rootPackage.workspaces?.length) {
+        for (const w of rootPackage.workspaces) {
+            const base = w.replace("/*", "").replace("*", "");
+            const dir = node_path_1.default.join(cwd, base);
+            if (!node_fs_1.default.existsSync(dir) || !node_fs_1.default.statSync(dir).isDirectory())
+                continue;
+            const subdirs = base.includes("*") ? node_fs_1.default.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => node_path_1.default.join(dir, e.name)) : [dir];
+            for (const sub of subdirs) {
+                const pj = node_path_1.default.join(sub, "package.json");
+                if (!node_fs_1.default.existsSync(pj))
+                    continue;
+                try {
+                    const pkg = JSON.parse(node_fs_1.default.readFileSync(pj, "utf8"));
+                    workspacePackages.push({
+                        path: node_path_1.default.relative(cwd, sub),
+                        scripts: pkg.scripts || {},
+                    });
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+    }
+    const openapi = findMatchingFiles(cwd, (_, name) => /^openapi.*\.json$/i.test(name));
+    const swagger = findMatchingFiles(cwd, (_, name) => /^swagger.*\.json$/i.test(name));
+    const docusaurusConfig = findMatchingFiles(cwd, (_, name) => name.startsWith("docusaurus.config."));
+    const mkdocs = findMatchingFiles(cwd, (_, name) => name === "mkdocs.yml");
+    const docsDirs = findDirsNamed(cwd, "docs");
+    return {
+        fileTree,
+        rootPackage,
+        workspacePackages,
+        foundPaths: { openapi, swagger, docusaurusConfig, mkdocs, docsDirs },
+    };
+}
+function fingerprintHash(fingerprint) {
+    const canonical = JSON.stringify(fingerprint, Object.keys(fingerprint).sort());
+    return node_crypto_1.default.createHash("sha256").update(canonical).digest("hex");
+}

package/docdrift.schema.json

@@ -183,13 +183,13 @@
       },
       "default": []
     },
-    "allowConceptualOnlyRun": {
-      "type": "boolean",
-      "default": false
-    },
-    "inferMode": {
-      "type": "boolean",
-      "default": true
+    "mode": {
+      "type": "string",
+      "enum": [
+        "strict",
+        "auto"
+      ],
+      "default": "strict"
     },
     "devin": {
       "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devinnn/docdrift",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "private": false,
   "description": "Detect and remediate documentation drift with Devin sessions",
   "main": "dist/src/index.js",
@@ -42,7 +42,11 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "@ai-sdk/gateway": "^1.0.0",
+    "@inquirer/prompts": "^7.2.0",
     "@octokit/rest": "^21.1.1",
+    "ai": "^4.0.0",
+    "dotenv": "^16.4.5",
     "fastify": "^5.2.1",
     "js-yaml": "^4.1.0",
     "zod": "^3.24.1"
@@ -57,4 +61,4 @@
     "vitest": "^3.0.5",
     "zod-to-json-schema": "^3.25.1"
   }
-}
+}