@devinnn/docdrift 0.1.1 → 0.1.3

package/dist/src/index.js

@@ -1,4 +1,37 @@
 "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 };
 };
@@ -7,10 +40,12 @@ exports.STATE_PATH = void 0;
 exports.runDetect = runDetect;
 exports.runDocDrift = runDocDrift;
 exports.runValidate = runValidate;
+exports.runSlaCheck = runSlaCheck;
 exports.runStatus = runStatus;
 exports.resolveTrigger = resolveTrigger;
 exports.parseDurationHours = parseDurationHours;
 exports.requireSha = requireSha;
+exports.resolveBaseHead = resolveBaseHead;
 const node_path_1 = __importDefault(require("node:path"));
 const load_1 = require("./config/load");
 const validate_1 = require("./config/validate");
@@ -21,6 +56,7 @@ const engine_1 = require("./policy/engine");
 const state_1 = require("./policy/state");
 const log_1 = require("./utils/log");
 const prompts_1 = require("./devin/prompts");
+const glob_1 = require("./utils/glob");
 const schemas_1 = require("./devin/schemas");
 const v1_1 = require("./devin/v1");
 function parseStructured(session) {
@@ -48,29 +84,20 @@ function inferQuestions(structured) {
         "What are the exact user-visible semantics after this merge?",
     ];
 }
-async function executeSession(input) {
+async function executeSessionSingle(input) {
     const attachmentUrls = [];
     for (const attachmentPath of input.attachmentPaths) {
         const url = await (0, v1_1.devinUploadAttachment)(input.apiKey, attachmentPath);
         attachmentUrls.push(url);
     }
-    const prompt = input.item.mode === "autogen"
-        ? (0, prompts_1.buildAutogenPrompt)({
-            item: input.item,
-            attachmentUrls,
-            verificationCommands: input.config.policy.verification.commands,
-            allowlist: input.config.policy.allowlist,
-            confidenceThreshold: input.config.policy.confidence.autopatchThreshold,
-            customAppend: input.config.devin.customInstructionContent ?? undefined,
-        })
-        : (0, prompts_1.buildConceptualPrompt)({
-            item: input.item,
-            attachmentUrls,
-            verificationCommands: input.config.policy.verification.commands,
-            allowlist: input.config.policy.allowlist,
-            confidenceThreshold: input.config.policy.confidence.autopatchThreshold,
-            customAppend: input.config.devin.customInstructionContent ?? undefined,
-        });
+    const prompt = (0, prompts_1.buildWholeDocsitePrompt)({
+        aggregated: input.aggregated,
+        config: input.config,
+        attachmentUrls,
+        runGate: input.runGate,
+        trigger: input.trigger,
+        prNumber: input.prNumber,
+    });
     const session = await (0, v1_1.devinCreateSession)(input.apiKey, {
         prompt,
         unlisted: input.config.devin.unlisted,
@@ -132,14 +159,16 @@ async function runDetect(options) {
         throw new Error(`Config validation failed:\n${runtimeValidation.errors.join("\n")}`);
     }
     const repo = process.env.GITHUB_REPOSITORY ?? "local/docdrift";
-    const { report } = await (0, detect_1.buildDriftReport)({
-        config,
+    const normalized = (0, load_1.loadNormalizedConfig)();
+    const { report, runGate } = await (0, detect_1.buildDriftReport)({
+        config: normalized,
         repo,
         baseSha: options.baseSha,
         headSha: options.headSha,
         trigger: options.trigger ?? "manual",
+        prNumber: options.prNumber,
     });
-    (0, log_1.logInfo)(`Drift items detected: ${report.items.length}`);
+    (0, log_1.logInfo)(`Drift items detected: ${report.items.length} (runGate: ${runGate})`);
     return { hasDrift: report.items.length > 0 };
 }
 async function runDocDrift(options) {
@@ -148,183 +177,245 @@ async function runDocDrift(options) {
     if (runtimeValidation.errors.length) {
         throw new Error(`Config validation failed:\n${runtimeValidation.errors.join("\n")}`);
     }
+    const normalized = (0, load_1.loadNormalizedConfig)();
     const repo = process.env.GITHUB_REPOSITORY ?? "local/docdrift";
     const commitSha = process.env.GITHUB_SHA ?? options.headSha;
     const githubToken = process.env.GITHUB_TOKEN;
     const devinApiKey = process.env.DEVIN_API_KEY;
-    const { report, runInfo, evidenceRoot } = await (0, detect_1.buildDriftReport)({
-        config,
+    const { report, aggregated, runInfo, evidenceRoot, runGate } = await (0, detect_1.buildDriftReport)({
+        config: normalized,
         repo,
         baseSha: options.baseSha,
         headSha: options.headSha,
         trigger: options.trigger ?? "manual",
+        prNumber: options.prNumber,
     });
-    const docAreaByName = new Map(config.docAreas.map((area) => [area.name, area]));
+    // Gate: no run (spec drift, conceptual-only, or infer) — exit early, no session
+    if (runGate === "none" || report.items.length === 0) {
+        (0, log_1.logInfo)("No drift; skipping session");
+        return [];
+    }
+    const item = report.items[0];
+    const docAreaConfig = {
+        name: "docsite",
+        mode: "autogen",
+        owners: { reviewers: [] },
+        detect: { openapi: { exportCmd: normalized.openapi.export, generatedPath: normalized.openapi.generated, publishedPath: normalized.openapi.published }, paths: [] },
+        patch: { targets: [], requireHumanConfirmation: false },
+    };
     let state = (0, state_1.loadState)();
     const startedAt = Date.now();
     const results = [];
     const metrics = {
-        driftItemsDetected: report.items.length,
+        driftItemsDetected: 1,
         prsOpened: 0,
         issuesOpened: 0,
         blockedCount: 0,
         timeToSessionTerminalMs: [],
-        docAreaCounts: {},
+        docAreaCounts: { docsite: 1 },
         noiseRateProxy: 0,
     };
-    for (const item of report.items) {
-        metrics.docAreaCounts[item.docArea] = (metrics.docAreaCounts[item.docArea] ?? 0) + 1;
-        const areaConfig = docAreaByName.get(item.docArea);
-        if (!areaConfig) {
-            continue;
-        }
-        const decision = (0, engine_1.decidePolicy)({
-            item,
-            docAreaConfig: areaConfig,
-            config,
+    const decision = (0, engine_1.decidePolicy)({
+        item,
+        docAreaConfig,
+        config,
+        state,
+        repo,
+        baseSha: options.baseSha,
+        headSha: options.headSha,
+    });
+    if (decision.action === "NOOP") {
+        results.push({
+            docArea: item.docArea,
+            decision,
+            outcome: "NO_CHANGE",
+            summary: decision.reason,
+        });
+        (0, bundle_1.writeMetrics)(metrics);
+        return results;
+    }
+    if (decision.action === "UPDATE_EXISTING_PR") {
+        const existingPr = state.areaLatestPr["docsite"];
+        results.push({
+            docArea: item.docArea,
+            decision,
+            outcome: existingPr ? "NO_CHANGE" : "BLOCKED",
+            summary: existingPr ? `Bundled into existing PR: ${existingPr}` : "PR cap reached",
+            prUrl: existingPr,
+        });
+        state = (0, engine_1.applyDecisionToState)({
             state,
-            repo,
-            baseSha: options.baseSha,
-            headSha: options.headSha,
+            decision,
+            docArea: "docsite",
+            outcome: existingPr ? "NO_CHANGE" : "BLOCKED",
+            link: existingPr,
         });
-        if (decision.action === "NOOP") {
-            results.push({
-                docArea: item.docArea,
-                decision,
-                outcome: "NO_CHANGE",
-                summary: decision.reason,
-            });
-            continue;
-        }
-        if (decision.action === "UPDATE_EXISTING_PR") {
-            const existingPr = state.areaLatestPr[item.docArea];
-            const summary = existingPr
-                ? `Bundled into existing PR: ${existingPr}`
-                : "PR cap reached and no existing area PR; escalated";
-            const outcome = existingPr ? "NO_CHANGE" : "BLOCKED";
-            results.push({
-                docArea: item.docArea,
-                decision,
-                outcome,
-                summary,
-                prUrl: existingPr,
-            });
-            state = (0, engine_1.applyDecisionToState)({
-                state,
-                decision,
-                docArea: item.docArea,
-                outcome,
-                link: existingPr,
-            });
-            continue;
-        }
-        const bundle = await (0, bundle_1.buildEvidenceBundle)({ runInfo, item, evidenceRoot });
-        const attachmentPaths = [...new Set([bundle.archivePath, ...bundle.attachmentPaths])];
-        let sessionOutcome = {
-            outcome: "NO_CHANGE",
-            summary: "Skipped Devin session",
-            verification: config.policy.verification.commands.map((command) => ({
+        (0, state_1.saveState)(state);
+        (0, bundle_1.writeMetrics)(metrics);
+        return results;
+    }
+    const bundle = await (0, bundle_1.buildEvidenceBundle)({ runInfo, item, evidenceRoot });
+    const attachmentPaths = [...new Set([bundle.archivePath, ...bundle.attachmentPaths])];
+    let sessionOutcome = {
+        outcome: "NO_CHANGE",
+        summary: "Skipped Devin session",
+        verification: normalized.policy.verification.commands.map((command) => ({
+            command,
+            result: "not run",
+        })),
+    };
+    if (devinApiKey) {
+        const sessionStart = Date.now();
+        sessionOutcome = await executeSessionSingle({
+            apiKey: devinApiKey,
+            repository: repo,
+            item,
+            aggregated: aggregated,
+            attachmentPaths,
+            config: normalized,
+            runGate,
+            trigger: runInfo.trigger,
+            prNumber: runInfo.prNumber,
+        });
+        metrics.timeToSessionTerminalMs.push(Date.now() - sessionStart);
+    }
+    else {
+        (0, log_1.logWarn)("DEVIN_API_KEY not set; running fallback behavior", { docArea: item.docArea });
+        sessionOutcome = {
+            outcome: "BLOCKED",
+            summary: "DEVIN_API_KEY missing; cannot start Devin session",
+            questions: ["Set DEVIN_API_KEY in environment or GitHub Actions secrets"],
+            verification: normalized.policy.verification.commands.map((command) => ({
                 command,
                 result: "not run",
             })),
         };
-        if (devinApiKey) {
-            const sessionStart = Date.now();
-            sessionOutcome = await executeSession({
-                apiKey: devinApiKey,
+    }
+    let issueUrl;
+    if (sessionOutcome.outcome === "PR_OPENED" && sessionOutcome.prUrl) {
+        metrics.prsOpened += 1;
+        state.lastDocDriftPrUrl = sessionOutcome.prUrl;
+        state.lastDocDriftPrOpenedAt = new Date().toISOString();
+        if (githubToken && runInfo.trigger === "pull_request" && runInfo.prNumber) {
+            await (0, client_1.postPrComment)({
+                token: githubToken,
                 repository: repo,
-                item,
-                attachmentPaths,
-                config,
+                prNumber: runInfo.prNumber,
+                body: `## Doc drift detected\n\nDraft doc PR: ${sessionOutcome.prUrl}\n\nMerge your API changes first, then review and merge this doc PR.`,
             });
-            metrics.timeToSessionTerminalMs.push(Date.now() - sessionStart);
-        }
-        else {
-            (0, log_1.logWarn)("DEVIN_API_KEY not set; running fallback behavior", { docArea: item.docArea });
-            sessionOutcome = {
-                outcome: "BLOCKED",
-                summary: "DEVIN_API_KEY missing; cannot start Devin session",
-                questions: ["Set DEVIN_API_KEY in environment or GitHub Actions secrets"],
-                verification: config.policy.verification.commands.map((command) => ({
-                    command,
-                    result: "not run",
-                })),
-            };
         }
-        let issueUrl;
-        if (githubToken &&
-            (decision.action === "OPEN_ISSUE" ||
-                sessionOutcome.outcome === "BLOCKED" ||
-                sessionOutcome.outcome === "NO_CHANGE")) {
+        const touchedRequireReview = (item.impactedDocs ?? []).filter((p) => normalized.requireHumanReview.some((glob) => (0, glob_1.matchesGlob)(glob, p)));
+        if (githubToken && touchedRequireReview.length > 0) {
             issueUrl = await (0, client_1.createIssue)({
                 token: githubToken,
                 repository: repo,
                 issue: {
-                    title: `[docdrift] ${item.docArea}: docs drift requires input`,
-                    body: (0, client_1.renderBlockedIssueBody)({
-                        docArea: item.docArea,
-                        evidenceSummary: item.summary,
-                        questions: sessionOutcome.questions ?? [
-                            "Please confirm intended behavior and doc wording.",
-                        ],
-                        sessionUrl: sessionOutcome.sessionUrl,
+                    title: "[docdrift] Docs out of sync — review doc drift PR",
+                    body: (0, client_1.renderRequireHumanReviewIssueBody)({
+                        prUrl: sessionOutcome.prUrl,
+                        touchedPaths: touchedRequireReview,
                     }),
                     labels: ["docdrift"],
                 },
             });
             metrics.issuesOpened += 1;
-            sessionOutcome.outcome = "ISSUE_OPENED";
-        }
-        if (sessionOutcome.outcome === "PR_OPENED") {
-            metrics.prsOpened += 1;
         }
-        if (sessionOutcome.outcome === "BLOCKED") {
-            metrics.blockedCount += 1;
+    }
+    else if (githubToken &&
+        (decision.action === "OPEN_ISSUE" ||
+            sessionOutcome.outcome === "BLOCKED" ||
+            sessionOutcome.outcome === "NO_CHANGE")) {
+        issueUrl = await (0, client_1.createIssue)({
+            token: githubToken,
+            repository: repo,
+            issue: {
+                title: "[docdrift] docsite: docs drift requires input",
+                body: (0, client_1.renderBlockedIssueBody)({
+                    docArea: item.docArea,
+                    evidenceSummary: item.summary,
+                    questions: sessionOutcome.questions ?? [
+                        "Please confirm intended behavior and doc wording.",
+                    ],
+                    sessionUrl: sessionOutcome.sessionUrl,
+                }),
+                labels: ["docdrift"],
+            },
+        });
+        metrics.issuesOpened += 1;
+        if (sessionOutcome.outcome !== "PR_OPENED") {
+            sessionOutcome.outcome = "ISSUE_OPENED";
         }
-        const result = {
+    }
+    if (sessionOutcome.outcome === "BLOCKED") {
+        metrics.blockedCount += 1;
+    }
+    const result = {
+        docArea: item.docArea,
+        decision,
+        outcome: sessionOutcome.outcome,
+        summary: sessionOutcome.summary,
+        sessionUrl: sessionOutcome.sessionUrl,
+        prUrl: sessionOutcome.prUrl,
+        issueUrl,
+    };
+    results.push(result);
+    state = (0, engine_1.applyDecisionToState)({
+        state,
+        decision,
+        docArea: "docsite",
+        outcome: sessionOutcome.outcome,
+        link: sessionOutcome.prUrl ?? issueUrl,
+    });
+    if (sessionOutcome.outcome === "PR_OPENED" && sessionOutcome.prUrl) {
+        state.lastDocDriftPrUrl = sessionOutcome.prUrl;
+        state.lastDocDriftPrOpenedAt = new Date().toISOString();
+    }
+    (0, state_1.saveState)(state);
+    if (githubToken) {
+        const body = (0, client_1.renderRunComment)({
             docArea: item.docArea,
-            decision,
-            outcome: sessionOutcome.outcome,
             summary: sessionOutcome.summary,
+            decision: decision.action,
+            outcome: sessionOutcome.outcome,
             sessionUrl: sessionOutcome.sessionUrl,
             prUrl: sessionOutcome.prUrl,
             issueUrl,
-        };
-        results.push(result);
-        if (githubToken) {
-            const body = (0, client_1.renderRunComment)({
-                docArea: item.docArea,
-                summary: sessionOutcome.summary,
-                decision: decision.action,
-                outcome: sessionOutcome.outcome,
-                sessionUrl: sessionOutcome.sessionUrl,
-                prUrl: sessionOutcome.prUrl,
-                issueUrl,
-                validation: sessionOutcome.verification,
-            });
-            await (0, client_1.postCommitComment)({
+            validation: sessionOutcome.verification,
+        });
+        await (0, client_1.postCommitComment)({
+            token: githubToken,
+            repository: repo,
+            commitSha,
+            body,
+        });
+    }
+    const slaDays = normalized.policy.slaDays ?? 0;
+    if (githubToken && slaDays > 0 && state.lastDocDriftPrUrl && state.lastDocDriftPrOpenedAt) {
+        const openedAt = Date.parse(state.lastDocDriftPrOpenedAt);
+        const daysOld = (Date.now() - openedAt) / (24 * 60 * 60 * 1000);
+        const lastSla = state.lastSlaIssueOpenedAt ? Date.parse(state.lastSlaIssueOpenedAt) : 0;
+        const slaCooldown = 6 * 24 * 60 * 60 * 1000;
+        if (daysOld >= slaDays && Date.now() - lastSla > slaCooldown) {
+            const slaIssueUrl = await (0, client_1.createIssue)({
                 token: githubToken,
                 repository: repo,
-                commitSha,
-                body,
+                issue: {
+                    title: "[docdrift] Docs out of sync — merge doc drift PR(s)",
+                    body: (0, client_1.renderSlaIssueBody)({
+                        prUrls: [state.lastDocDriftPrUrl],
+                        slaDays,
+                    }),
+                    labels: ["docdrift"],
+                },
             });
+            state.lastSlaIssueOpenedAt = new Date().toISOString();
+            (0, state_1.saveState)(state);
         }
-        state = (0, engine_1.applyDecisionToState)({
-            state,
-            decision,
-            docArea: item.docArea,
-            outcome: sessionOutcome.outcome,
-            link: sessionOutcome.prUrl ?? issueUrl,
-        });
     }
-    (0, state_1.saveState)(state);
-    metrics.noiseRateProxy =
-        metrics.driftItemsDetected === 0
-            ? 0
-            : Number((metrics.prsOpened / metrics.driftItemsDetected).toFixed(4));
+    metrics.noiseRateProxy = metrics.prsOpened;
     (0, bundle_1.writeMetrics)(metrics);
     (0, log_1.logInfo)("Run complete", {
-        items: report.items.length,
+        items: 1,
         elapsedMs: Date.now() - startedAt,
     });
     return results;
@@ -338,6 +429,54 @@ async function runValidate() {
     runtimeValidation.warnings.forEach((warning) => (0, log_1.logWarn)(warning));
     (0, log_1.logInfo)("Config is valid");
 }
+async function runSlaCheck() {
+    const githubToken = process.env.GITHUB_TOKEN;
+    if (!githubToken) {
+        throw new Error("GITHUB_TOKEN is required for sla-check command");
+    }
+    const repo = process.env.GITHUB_REPOSITORY;
+    if (!repo) {
+        throw new Error("GITHUB_REPOSITORY is required for sla-check command");
+    }
+    const normalized = (0, load_1.loadNormalizedConfig)();
+    const slaDays = normalized.policy.slaDays ?? 0;
+    const slaLabel = normalized.policy.slaLabel ?? "docdrift";
+    if (slaDays <= 0) {
+        (0, log_1.logInfo)("SLA check disabled (slaDays <= 0)");
+        return { issueOpened: false };
+    }
+    const cutoff = new Date(Date.now() - slaDays * 24 * 60 * 60 * 1000);
+    const openPrs = await (0, client_1.listOpenPrsWithLabel)(githubToken, repo, slaLabel);
+    const stalePrs = openPrs.filter((pr) => {
+        const created = pr.created_at ? Date.parse(pr.created_at) : Date.now();
+        return Number.isFinite(created) && created <= cutoff.getTime();
+    });
+    if (stalePrs.length === 0) {
+        (0, log_1.logInfo)("No doc-drift PRs open longer than slaDays; nothing to do");
+        return { issueOpened: false };
+    }
+    let state = (0, state_1.loadState)();
+    const lastSla = state.lastSlaIssueOpenedAt ? Date.parse(state.lastSlaIssueOpenedAt) : 0;
+    const slaCooldown = 6 * 24 * 60 * 60 * 1000;
+    if (Date.now() - lastSla < slaCooldown) {
+        (0, log_1.logInfo)("SLA issue cooldown; skipping");
+        return { issueOpened: false };
+    }
+    const prUrls = stalePrs.map((p) => p.url).filter(Boolean);
+    await (0, client_1.createIssue)({
+        token: githubToken,
+        repository: repo,
+        issue: {
+            title: "[docdrift] Docs out of sync — merge doc drift PR(s)",
+            body: (0, client_1.renderSlaIssueBody)({ prUrls, slaDays }),
+            labels: ["docdrift"],
+        },
+    });
+    state.lastSlaIssueOpenedAt = new Date().toISOString();
+    (0, state_1.saveState)(state);
+    (0, log_1.logInfo)(`Opened SLA issue for ${prUrls.length} stale PR(s)`);
+    return { issueOpened: true };
+}
 async function runStatus(sinceHours = 24) {
     const apiKey = process.env.DEVIN_API_KEY;
     if (!apiKey) {
@@ -361,12 +500,12 @@ async function runStatus(sinceHours = 24) {
     }
 }
 function resolveTrigger(eventName) {
-    if (eventName === "push") {
+    if (eventName === "push")
         return "push";
-    }
-    if (eventName === "schedule") {
+    if (eventName === "schedule")
         return "schedule";
-    }
+    if (eventName === "pull_request")
+        return "pull_request";
     return "manual";
 }
 function parseDurationHours(value) {
@@ -386,4 +525,12 @@ function requireSha(value, label) {
     }
     return value;
 }
+async function resolveBaseHead(baseArg, headArg) {
+    const headRef = headArg ?? process.env.GITHUB_SHA ?? "HEAD";
+    if (baseArg) {
+        return { baseSha: baseArg, headSha: headRef };
+    }
+    const { resolveDefaultBaseHead } = await Promise.resolve().then(() => __importStar(require("./utils/git")));
+    return resolveDefaultBaseHead(headRef);
+}
 exports.STATE_PATH = node_path_1.default.resolve(".docdrift", "state.json");

package/dist/src/policy/engine.js

@@ -21,7 +21,8 @@ function decidePolicy(input) {
     const capReached = prCountToday >= config.policy.prCaps.maxPrsPerDay;
     const areaDailyKey = `${today}:${item.docArea}`;
     const exceedsFileCap = item.impactedDocs.length > config.policy.prCaps.maxFilesTouched;
-    const hasPathOutsideAllowlist = item.impactedDocs.some((filePath) => filePath && !(0, glob_1.isPathAllowed)(filePath, config.policy.allowlist));
+    const exclude = "exclude" in config && Array.isArray(config.exclude) ? config.exclude : [];
+    const hasPathOutsideAllowlist = item.impactedDocs.some((filePath) => filePath && !(0, glob_1.isPathAllowedAndNotExcluded)(filePath, config.policy.allowlist, exclude));
     let action = "NOOP";
     let reason = "No action needed";
     if (hasPathOutsideAllowlist) {