@devinnn/docdrift 0.1.0 → 0.1.2

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");
@@ -56,7 +57,7 @@ async function detectOpenApiDrift(docArea, evidenceDir) {
         "\n--- stdout ---",
         exportResult.stdout,
         "\n--- stderr ---",
-        exportResult.stderr
+        exportResult.stderr,
     ].join("\n"), "utf8");
     if (exportResult.exitCode !== 0) {
         return {
@@ -67,8 +68,8 @@ async function detectOpenApiDrift(docArea, evidenceDir) {
                 kind: "weak_evidence",
                 tier: 2,
                 confidence: 0.35,
-                evidence: [exportLogPath]
-            }
+                evidence: [exportLogPath],
+            },
         };
     }
     if (!node_fs_1.default.existsSync(openapi.generatedPath) || !node_fs_1.default.existsSync(openapi.publishedPath)) {
@@ -80,8 +81,8 @@ async function detectOpenApiDrift(docArea, evidenceDir) {
                 kind: "weak_evidence",
                 tier: 2,
                 confidence: 0.35,
-                evidence: [exportLogPath]
-            }
+                evidence: [exportLogPath],
+            },
         };
     }
     const generatedRaw = node_fs_1.default.readFileSync(openapi.generatedPath, "utf8");
@@ -94,7 +95,7 @@ async function detectOpenApiDrift(docArea, evidenceDir) {
         return {
             impactedDocs: [openapi.publishedPath],
             evidenceFiles: [exportLogPath],
-            summary: "No OpenAPI drift detected"
+            summary: "No OpenAPI drift detected",
         };
     }
     const summary = summarizeSpecDelta(publishedJson, generatedJson);
@@ -107,7 +108,7 @@ async function detectOpenApiDrift(docArea, evidenceDir) {
         normalizedPublished,
         "",
         "# Generated (normalized)",
-        normalizedGenerated
+        normalizedGenerated,
     ].join("\n"), "utf8");
     return {
         impactedDocs: [...new Set([openapi.publishedPath, ...(docArea.patch.targets ?? [])])],
@@ -117,7 +118,89 @@ async function detectOpenApiDrift(docArea, evidenceDir) {
             kind: "openapi_diff",
             tier: 1,
             confidence: 0.95,
-            evidence: [diffPath]
-        }
+            evidence: [diffPath],
+        },
+    };
+}
+/** 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,11 +2,12 @@
 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");
 }
 function buildAutogenPrompt(input) {
-    return [
+    const base = [
         "You are Devin. Task: update API reference docs to match actual code/spec changes.",
         "",
         "EVIDENCE (attachments):",
@@ -30,12 +31,16 @@ function buildAutogenPrompt(input) {
         "  e) get blocked (status=BLOCKED + questions),",
         "  f) complete (status=DONE).",
         "",
-        `Goal: Produce a PR for doc area ${input.item.docArea} using only the evidence.`
+        `Goal: Produce a PR for doc area ${input.item.docArea} using only the evidence.`,
     ].join("\n");
+    if (input.customAppend) {
+        return base + "\n\n---\n\nCustom instructions:\n\n" + input.customAppend;
+    }
+    return base;
 }
 function buildConceptualPrompt(input) {
-    return [
-        "You are Devin. Task: propose minimal edits to conceptual docs potentially impacted by code changes.",
+    const base = [
+        "You are Devin. Task: propose minimal edits to conceptual docs potentially impacted by code changes. i..e GUIDES",
         "",
         "EVIDENCE (attachments):",
         attachmentBlock(input.attachmentUrls),
@@ -50,6 +55,52 @@ function buildConceptualPrompt(input) {
         "- Update at planning, editing, verifying, open-pr, blocked, done milestones.",
         "- If blocked, fill blocked.questions with concrete, reviewer-actionable questions.",
         "",
-        "Goal: either open a very small PR with confidence or open an issue/comment with crisp questions and suggested patch text."
+        "Goal: either open a very small PR with confidence or open an issue/comment with crisp questions and suggested patch text.",
     ].join("\n");
+    if (input.customAppend) {
+        return base + "\n\n---\n\nCustom instructions:\n\n" + input.customAppend;
+    }
+    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 base = [
+        "You are Devin. Task: update the entire docsite to match the API and code changes.",
+        "",
+        "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.",
+        `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/devin/schemas.js

@@ -13,7 +13,7 @@ exports.PatchPlanSchema = {
         "evidence",
         "filesToEdit",
         "verification",
-        "nextAction"
+        "nextAction",
     ],
     properties: {
         status: { enum: ["PLANNING", "EDITING", "VERIFYING", "OPENED_PR", "BLOCKED", "DONE"] },
@@ -27,8 +27,8 @@ exports.PatchPlanSchema = {
             required: ["attachments", "diffSummary"],
             properties: {
                 attachments: { type: "array", items: { type: "string" } },
-                diffSummary: { type: "string" }
-            }
+                diffSummary: { type: "string" },
+            },
         },
         filesToEdit: { type: "array", items: { type: "string" } },
         verification: {
@@ -37,8 +37,8 @@ exports.PatchPlanSchema = {
             required: ["commands"],
             properties: {
                 commands: { type: "array", items: { type: "string" } },
-                results: { type: "array", items: { type: "string" } }
-            }
+                results: { type: "array", items: { type: "string" } },
+            },
         },
         nextAction: { enum: ["OPEN_PR", "OPEN_ISSUE", "NOOP"] },
         pr: {
@@ -46,18 +46,18 @@ exports.PatchPlanSchema = {
             additionalProperties: false,
             properties: {
                 title: { type: "string" },
-                url: { type: "string" }
-            }
+                url: { type: "string" },
+            },
         },
         blocked: {
             type: "object",
             additionalProperties: false,
             properties: {
                 reason: { type: "string" },
-                questions: { type: "array", items: { type: "string" } }
-            }
-        }
-    }
+                questions: { type: "array", items: { type: "string" } },
+            },
+        },
+    },
 };
 exports.PatchResultSchema = {
     type: "object",
@@ -74,8 +74,8 @@ exports.PatchResultSchema = {
             required: ["commands", "results"],
             properties: {
                 commands: { type: "array", items: { type: "string" } },
-                results: { type: "array", items: { type: "string" } }
-            }
+                results: { type: "array", items: { type: "string" } },
+            },
         },
         links: {
             type: "object",
@@ -84,16 +84,16 @@ exports.PatchResultSchema = {
             properties: {
                 sessionUrl: { type: "string" },
                 prUrl: { type: "string" },
-                issueUrl: { type: "string" }
-            }
+                issueUrl: { type: "string" },
+            },
         },
         blocked: {
             type: "object",
             additionalProperties: false,
             properties: {
                 reason: { type: "string" },
-                questions: { type: "array", items: { type: "string" } }
-            }
-        }
-    }
+                questions: { type: "array", items: { type: "string" } },
+            },
+        },
+    },
 };

package/dist/src/devin/v1.js

@@ -24,9 +24,9 @@ async function devinUploadAttachment(apiKey, filePath) {
     const response = await fetch("https://api.devin.ai/v1/attachments", {
         method: "POST",
         headers: {
-            Authorization: `Bearer ${apiKey}`
+            Authorization: `Bearer ${apiKey}`,
         },
-        body: form
+        body: form,
     });
     const text = await response.text();
     ensureOk(response, text, "Upload attachment");
@@ -49,9 +49,9 @@ async function devinCreateSession(apiKey, body) {
         method: "POST",
         headers: {
             Authorization: `Bearer ${apiKey}`,
-            "Content-Type": "application/json"
+            "Content-Type": "application/json",
         },
-        body: JSON.stringify(body)
+        body: JSON.stringify(body),
     });
     const text = await response.text();
     ensureOk(response, text, "Create session");
@@ -60,8 +60,8 @@ async function devinCreateSession(apiKey, body) {
 async function devinGetSession(apiKey, sessionId) {
     const response = await fetch(`https://api.devin.ai/v1/sessions/${sessionId}`, {
         headers: {
-            Authorization: `Bearer ${apiKey}`
-        }
+            Authorization: `Bearer ${apiKey}`,
+        },
     });
     const text = await response.text();
     ensureOk(response, text, "Get session");
@@ -77,8 +77,8 @@ async function devinListSessions(apiKey, params = {}) {
     }
     const response = await fetch(url, {
         headers: {
-            Authorization: `Bearer ${apiKey}`
-        }
+            Authorization: `Bearer ${apiKey}`,
+        },
     });
     const text = await response.text();
     ensureOk(response, text, "List sessions");

package/dist/src/evidence/bundle.js

@@ -52,7 +52,7 @@ async function buildEvidenceBundle(input) {
             baseSha: input.runInfo.baseSha,
             headSha: input.runInfo.headSha,
             trigger: input.runInfo.trigger,
-            timestamp: input.runInfo.timestamp
+            timestamp: input.runInfo.timestamp,
         },
         docArea: input.item.docArea,
         mode: input.item.mode,
@@ -60,7 +60,7 @@ async function buildEvidenceBundle(input) {
         signals: input.item.signals,
         impactedDocs: input.item.impactedDocs,
         copiedEvidence,
-        copiedDocs
+        copiedDocs,
     });
     const archivePath = `${bundleDir}.tar.gz`;
     const parent = node_path_1.default.dirname(bundleDir);
@@ -73,7 +73,7 @@ async function buildEvidenceBundle(input) {
         bundleDir,
         archivePath,
         manifestPath,
-        attachmentPaths: [archivePath, manifestPath]
+        attachmentPaths: [archivePath, manifestPath],
     };
 }
 function writeMetrics(metrics) {

package/dist/src/github/client.js

@@ -1,9 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRepo = parseRepo;
 exports.postCommitComment = postCommitComment;
 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("/");
@@ -19,7 +24,7 @@ async function postCommitComment(input) {
         owner,
         repo,
         commit_sha: input.commitSha,
-        body: input.body
+        body: input.body,
     });
     return response.data.html_url;
 }
@@ -31,7 +36,7 @@ async function createIssue(input) {
         repo,
         title: input.issue.title,
         body: input.issue.body,
-        labels: input.issue.labels
+        labels: input.issue.labels,
     });
     return response.data.html_url;
 }
@@ -84,3 +89,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 ?? "",
+    }));
+}