@devinnn/docdrift 0.1.1 → 0.1.3

package/dist/src/detect/index.js

@@ -7,18 +7,8 @@ exports.buildDriftReport = buildDriftReport;
 const node_path_1 = __importDefault(require("node:path"));
 const fs_1 = require("../utils/fs");
 const git_1 = require("../utils/git");
-const docsCheck_1 = require("./docsCheck");
 const heuristics_1 = require("./heuristics");
-const openapi_1 = require("./openapi");
-function defaultRecommendation(mode, signals) {
-    if (!signals.length) {
-        return "NOOP";
-    }
-    if (mode === "autogen") {
-        return signals.some((s) => s.tier <= 1) ? "OPEN_PR" : "OPEN_ISSUE";
-    }
-    return "OPEN_ISSUE";
-}
+const registry_1 = require("../spec-providers/registry");
 async function buildDriftReport(input) {
     const runInfo = {
         runId: `${Date.now()}`,
@@ -27,51 +17,122 @@ 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);
     const changedPaths = await (0, git_1.gitChangedPaths)(input.baseSha, input.headSha);
     const diffSummary = await (0, git_1.gitDiffSummary)(input.baseSha, input.headSha);
     const commits = await (0, git_1.gitCommitList)(input.baseSha, input.headSha);
-    const docsCheck = await (0, docsCheck_1.runDocsChecks)(input.config.policy.verification.commands, evidenceRoot);
-    const items = [];
-    const checkSummaries = [docsCheck.summary];
-    for (const docArea of input.config.docAreas) {
-        const signals = [];
-        const impactedDocs = new Set(docArea.patch.targets ?? []);
-        const summaries = [];
-        if (docsCheck.signal) {
-            signals.push(docsCheck.signal);
-            summaries.push(docsCheck.summary);
-        }
-        if (docArea.detect.openapi) {
-            const openapiResult = await (0, openapi_1.detectOpenApiDrift)(docArea, evidenceRoot);
-            if (openapiResult.signal) {
-                signals.push(openapiResult.signal);
+    (0, fs_1.writeJsonFile)(node_path_1.default.join(evidenceRoot, "changeset.json"), {
+        changedPaths,
+        diffSummary,
+        commits,
+    });
+    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);
             }
-            openapiResult.impactedDocs.forEach((doc) => impactedDocs.add(doc));
-            summaries.push(openapiResult.summary);
         }
+    }
+    // 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);
+                }
             }
-            heuristicResult.impactedDocs.forEach((doc) => impactedDocs.add(doc));
-            summaries.push(heuristicResult.summary);
         }
-        if (!signals.length) {
-            continue;
+        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.");
         }
-        items.push({
-            docArea: docArea.name,
-            mode: docArea.mode,
-            signals,
-            impactedDocs: [...impactedDocs],
-            recommendedAction: defaultRecommendation(docArea.mode, signals),
-            summary: summaries.filter(Boolean).join(" | "),
-        });
     }
+    if (runGate === "none") {
+        const report = {
+            run: {
+                repo: input.repo,
+                baseSha: input.baseSha,
+                headSha: input.headSha,
+                trigger: input.trigger,
+                timestamp: runInfo.timestamp,
+            },
+            items: [],
+        };
+        (0, fs_1.writeJsonFile)(node_path_1.default.resolve(".docdrift", "drift_report.json"), report);
+        return {
+            report,
+            aggregated: null,
+            changedPaths,
+            evidenceRoot,
+            runInfo,
+            hasOpenApiDrift: false,
+            runGate: "none",
+        };
+    }
+    const aggregated = {
+        signals,
+        impactedDocs: [...impactedDocs],
+        summary: summaries.filter(Boolean).join(" | "),
+    };
+    const item = {
+        docArea: "docsite",
+        mode: runGate === "conceptual_only" ? "conceptual" : "autogen",
+        signals: aggregated.signals,
+        impactedDocs: aggregated.impactedDocs,
+        recommendedAction: aggregated.signals.some((s) => s.tier <= 1) ? "OPEN_PR" : "OPEN_ISSUE",
+        summary: aggregated.summary,
+    };
     const report = {
         run: {
             repo: input.repo,
@@ -80,13 +141,16 @@ async function buildDriftReport(input) {
             trigger: input.trigger,
             timestamp: runInfo.timestamp,
         },
-        items,
+        items: [item],
     };
     (0, fs_1.writeJsonFile)(node_path_1.default.resolve(".docdrift", "drift_report.json"), report);
-    (0, fs_1.writeJsonFile)(node_path_1.default.join(evidenceRoot, "changeset.json"), {
+    return {
+        report,
+        aggregated,
         changedPaths,
-        diffSummary,
-        commits,
-    });
-    return { report, changedPaths, evidenceRoot, runInfo, checkSummaries };
+        evidenceRoot,
+        runInfo,
+        hasOpenApiDrift: anySpecDrift,
+        runGate,
+    };
 }

package/dist/src/detect/openapi.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectOpenApiDrift = detectOpenApiDrift;
+exports.detectOpenApiDriftFromNormalized = detectOpenApiDriftFromNormalized;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const exec_1 = require("../utils/exec");
@@ -121,3 +122,85 @@ async function detectOpenApiDrift(docArea, evidenceDir) {
         },
     };
 }
+/** Run OpenAPI drift detection from normalized config (simple openapi block). Used as gate. */
+async function detectOpenApiDriftFromNormalized(config, evidenceDir) {
+    const openapi = config.openapi;
+    const exportLogPath = node_path_1.default.join(evidenceDir, "openapi-export.log");
+    const exportResult = await (0, exec_1.execCommand)(openapi.export);
+    node_fs_1.default.writeFileSync(exportLogPath, [
+        `$ ${openapi.export}`,
+        `exitCode: ${exportResult.exitCode}`,
+        "\n--- stdout ---",
+        exportResult.stdout,
+        "\n--- stderr ---",
+        exportResult.stderr,
+    ].join("\n"), "utf8");
+    if (exportResult.exitCode !== 0) {
+        return {
+            impactedDocs: [openapi.published],
+            evidenceFiles: [exportLogPath],
+            summary: "OpenAPI export command failed",
+            signal: {
+                kind: "weak_evidence",
+                tier: 2,
+                confidence: 0.35,
+                evidence: [exportLogPath],
+            },
+        };
+    }
+    if (!node_fs_1.default.existsSync(openapi.generated) || !node_fs_1.default.existsSync(openapi.published)) {
+        return {
+            impactedDocs: [openapi.generated, openapi.published],
+            evidenceFiles: [exportLogPath],
+            summary: "OpenAPI file(s) missing",
+            signal: {
+                kind: "weak_evidence",
+                tier: 2,
+                confidence: 0.35,
+                evidence: [exportLogPath],
+            },
+        };
+    }
+    const generatedRaw = node_fs_1.default.readFileSync(openapi.generated, "utf8");
+    const publishedRaw = node_fs_1.default.readFileSync(openapi.published, "utf8");
+    const generatedJson = JSON.parse(generatedRaw);
+    const publishedJson = JSON.parse(publishedRaw);
+    const normalizedGenerated = (0, json_1.stableStringify)(generatedJson);
+    const normalizedPublished = (0, json_1.stableStringify)(publishedJson);
+    if (normalizedGenerated === normalizedPublished) {
+        return {
+            impactedDocs: [openapi.published],
+            evidenceFiles: [exportLogPath],
+            summary: "No OpenAPI drift detected",
+        };
+    }
+    const summary = summarizeSpecDelta(publishedJson, generatedJson);
+    const diffPath = node_path_1.default.join(evidenceDir, "openapi.diff.txt");
+    node_fs_1.default.writeFileSync(diffPath, [
+        "# OpenAPI Drift Summary",
+        summary,
+        "",
+        "# Published (normalized)",
+        normalizedPublished,
+        "",
+        "# Generated (normalized)",
+        normalizedGenerated,
+    ].join("\n"), "utf8");
+    const impactedDocs = [
+        ...new Set([
+            openapi.published,
+            ...config.docAreas.flatMap((a) => a.patch.targets ?? []).filter(Boolean),
+        ]),
+    ].filter(Boolean);
+    return {
+        impactedDocs,
+        evidenceFiles: [exportLogPath, diffPath],
+        summary,
+        signal: {
+            kind: "openapi_diff",
+            tier: 1,
+            confidence: 0.95,
+            evidence: [diffPath],
+        },
+    };
+}

package/dist/src/devin/prompts.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildAutogenPrompt = buildAutogenPrompt;
 exports.buildConceptualPrompt = buildConceptualPrompt;
+exports.buildWholeDocsitePrompt = buildWholeDocsitePrompt;
 function attachmentBlock(attachmentUrls) {
     return attachmentUrls.map((url, index) => `- ATTACHMENT ${index + 1}: ${url}`).join("\n");
 }
@@ -61,3 +62,89 @@ function buildConceptualPrompt(input) {
     }
     return base;
 }
+/** Whole-docsite prompt for single-session runs */
+function buildWholeDocsitePrompt(input) {
+    const excludeNote = input.config.exclude?.length > 0
+        ? `\n6) NEVER modify files matching these patterns: ${input.config.exclude.join(", ")}`
+        : "";
+    const requireReviewNote = input.config.requireHumanReview?.length > 0
+        ? `\n7) If you touch files under: ${input.config.requireHumanReview.join(", ")} — note it in the PR description (a follow-up issue will flag for human review).`
+        : "";
+    const allowNewFiles = input.config.policy.allowNewFiles ?? false;
+    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"),
+        "",
+        "Rules (hard):",
+        `1) Only modify files under: ${input.config.policy.allowlist.join(", ")}`,
+        "2) Make the smallest change that makes docs correct.",
+        "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." +
+            draftPrBlock,
+        `6) Docsite scope: ${input.config.docsite.join(", ")}` +
+            excludeNote +
+            requireReviewNote +
+            `\n${newFilesRule}`,
+        "",
+        "Structured Output:",
+        "- Maintain structured output in the provided JSON schema.",
+        "- Update it at: planning, editing, verifying, open-pr, blocked, done.",
+        "- If blocked, fill blocked.questions with concrete questions.",
+        "",
+        "Goal: Produce ONE PR that updates the whole docsite (API reference + guides) using only the evidence.",
+    ].join("\n");
+    if (input.config.devin.customInstructionContent) {
+        return base + "\n\n---\n\nCustom instructions:\n\n" + input.config.devin.customInstructionContent;
+    }
+    return base;
+}

package/dist/src/github/client.js

@@ -1,9 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRepo = parseRepo;
 exports.postCommitComment = postCommitComment;
+exports.postPrComment = postPrComment;
 exports.createIssue = createIssue;
 exports.renderRunComment = renderRunComment;
 exports.renderBlockedIssueBody = renderBlockedIssueBody;
+exports.renderRequireHumanReviewIssueBody = renderRequireHumanReviewIssueBody;
+exports.renderSlaIssueBody = renderSlaIssueBody;
+exports.isPrOpen = isPrOpen;
+exports.listOpenPrsWithLabel = listOpenPrsWithLabel;
 const rest_1 = require("@octokit/rest");
 function parseRepo(full) {
     const [owner, repo] = full.split("/");
@@ -23,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);
@@ -84,3 +102,73 @@ function renderBlockedIssueBody(input) {
     }
     return lines.join("\n");
 }
+function renderRequireHumanReviewIssueBody(input) {
+    const lines = [];
+    lines.push("## Why this issue");
+    lines.push("");
+    lines.push("This doc-drift PR touches paths that require human review (guides, prose, or other non-technical docs).");
+    lines.push("");
+    lines.push("## What to do");
+    lines.push("");
+    lines.push(`1. Review the PR: ${input.prUrl}`);
+    lines.push("2. Confirm the changes are correct or request modifications.");
+    lines.push("3. Merge or close the PR.");
+    lines.push("");
+    if (input.touchedPaths.length > 0) {
+        lines.push("## Touched paths (require review)");
+        lines.push("");
+        for (const p of input.touchedPaths.slice(0, 20)) {
+            lines.push(`- \`${p}\``);
+        }
+        if (input.touchedPaths.length > 20) {
+            lines.push(`- ... and ${input.touchedPaths.length - 20} more`);
+        }
+    }
+    return lines.join("\n");
+}
+function renderSlaIssueBody(input) {
+    const lines = [];
+    lines.push("## Why this issue");
+    lines.push("");
+    lines.push(`Doc-drift PR(s) have been open for ${input.slaDays}+ days. Docs may be out of sync.`);
+    lines.push("");
+    lines.push("## What to do");
+    lines.push("");
+    lines.push("Please review and merge or close the following PR(s):");
+    lines.push("");
+    for (const url of input.prUrls) {
+        lines.push(`- ${url}`);
+    }
+    lines.push("");
+    lines.push("If the PR is no longer needed, close it to resolve this reminder.");
+    return lines.join("\n");
+}
+/** Check if a PR is still open. URL format: https://github.com/owner/repo/pull/123 */
+async function isPrOpen(token, prUrl) {
+    const match = prUrl.match(/github\.com[/]([^/]+)[/]([^/]+)[/]pull[/](\d+)/);
+    if (!match)
+        return { open: false };
+    const [, owner, repo, numStr] = match;
+    const number = parseInt(numStr ?? "0", 10);
+    if (!owner || !repo || !Number.isFinite(number))
+        return { open: false };
+    const octokit = new rest_1.Octokit({ auth: token });
+    const { data } = await octokit.pulls.get({ owner, repo, pull_number: number });
+    return { open: data.state === "open", number: data.number };
+}
+/** List open PRs with a given label */
+async function listOpenPrsWithLabel(token, repository, label) {
+    const octokit = new rest_1.Octokit({ auth: token });
+    const { owner, repo } = parseRepo(repository);
+    const { data } = await octokit.pulls.list({
+        owner,
+        repo,
+        state: "open",
+        labels: label,
+    });
+    return data.map((pr) => ({
+        url: pr.html_url ?? "",
+        number: pr.number,
+        created_at: pr.created_at ?? "",
+    }));
+}