@devinnn/docdrift 0.1.2 → 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 };
 };
@@ -12,6 +45,7 @@ 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");
@@ -60,6 +94,9 @@ async function executeSessionSingle(input) {
         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,
@@ -123,14 +160,15 @@ async function runDetect(options) {
     }
     const repo = process.env.GITHUB_REPOSITORY ?? "local/docdrift";
     const normalized = (0, load_1.loadNormalizedConfig)();
-    const { report, hasOpenApiDrift } = await (0, detect_1.buildDriftReport)({
+    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} (hasOpenApiDrift: ${hasOpenApiDrift})`);
+    (0, log_1.logInfo)(`Drift items detected: ${report.items.length} (runGate: ${runGate})`);
     return { hasDrift: report.items.length > 0 };
 }
 async function runDocDrift(options) {
@@ -144,16 +182,17 @@ async function runDocDrift(options) {
     const commitSha = process.env.GITHUB_SHA ?? options.headSha;
     const githubToken = process.env.GITHUB_TOKEN;
     const devinApiKey = process.env.DEVIN_API_KEY;
-    const { report, aggregated, runInfo, evidenceRoot, hasOpenApiDrift } = await (0, detect_1.buildDriftReport)({
+    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,
     });
-    // Gate: no OpenAPI drift — exit early, no session
-    if (!hasOpenApiDrift || report.items.length === 0) {
-        (0, log_1.logInfo)("No OpenAPI drift; skipping session");
+    // 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];
@@ -234,6 +273,9 @@ async function runDocDrift(options) {
             aggregated: aggregated,
             attachmentPaths,
             config: normalized,
+            runGate,
+            trigger: runInfo.trigger,
+            prNumber: runInfo.prNumber,
         });
         metrics.timeToSessionTerminalMs.push(Date.now() - sessionStart);
     }
@@ -254,6 +296,14 @@ async function runDocDrift(options) {
         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,
+                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.`,
+            });
+        }
         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)({
@@ -450,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) {
@@ -475,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/spec-providers/fern.js

@@ -0,0 +1,123 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectFernSpecDrift = detectFernSpecDrift;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const fs_1 = require("../utils/fs");
+const json_1 = require("../utils/json");
+function readFernDefinitionDir(dirPath) {
+    const out = {};
+    if (!node_fs_1.default.existsSync(dirPath) || !node_fs_1.default.statSync(dirPath).isDirectory()) {
+        return out;
+    }
+    const entries = node_fs_1.default.readdirSync(dirPath, { withFileTypes: true });
+    for (const e of entries) {
+        const full = node_path_1.default.join(dirPath, e.name);
+        if (e.isDirectory()) {
+            Object.assign(out, readFernDefinitionDir(full));
+        }
+        else if (e.isFile() && (e.name.endsWith(".yml") || e.name.endsWith(".yaml"))) {
+            out[full] = node_fs_1.default.readFileSync(full, "utf8");
+        }
+    }
+    return out;
+}
+async function getCurrentContent(config) {
+    const current = config.current;
+    if (current.type !== "local") {
+        throw new Error("Fern provider only supports local definition folder");
+    }
+    return readFernDefinitionDir(current.path);
+}
+function contentSignature(files) {
+    const sorted = Object.keys(files).sort();
+    return (0, json_1.stableStringify)(sorted.map((k) => ({ path: k, content: files[k] })));
+}
+async function detectFernSpecDrift(config, evidenceDir) {
+    if (config.format !== "fern") {
+        return {
+            hasDrift: false,
+            summary: `Format ${config.format} is not fern`,
+            evidenceFiles: [],
+            impactedDocs: [],
+        };
+    }
+    (0, fs_1.ensureDir)(evidenceDir);
+    let currentFiles;
+    try {
+        currentFiles = await getCurrentContent(config);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const logPath = node_path_1.default.join(evidenceDir, "fern-export.log");
+        node_fs_1.default.writeFileSync(logPath, msg, "utf8");
+        return {
+            hasDrift: true,
+            summary: `Fern definition read failed: ${msg}`,
+            evidenceFiles: [logPath],
+            impactedDocs: [config.published],
+            signal: {
+                kind: "weak_evidence",
+                tier: 2,
+                confidence: 0.35,
+                evidence: [logPath],
+            },
+        };
+    }
+    const publishedPath = config.published;
+    let publishedSignature;
+    if (node_fs_1.default.existsSync(publishedPath) && node_fs_1.default.statSync(publishedPath).isDirectory()) {
+        const publishedFiles = readFernDefinitionDir(publishedPath);
+        publishedSignature = contentSignature(publishedFiles);
+    }
+    else if (node_fs_1.default.existsSync(publishedPath)) {
+        publishedSignature = node_fs_1.default.readFileSync(publishedPath, "utf8");
+    }
+    else {
+        return {
+            hasDrift: true,
+            summary: "Fern published path missing",
+            evidenceFiles: [],
+            impactedDocs: [config.published],
+            signal: {
+                kind: "weak_evidence",
+                tier: 2,
+                confidence: 0.35,
+                evidence: [],
+            },
+        };
+    }
+    const currentSignature = contentSignature(currentFiles);
+    if (currentSignature === publishedSignature) {
+        return {
+            hasDrift: false,
+            summary: "No Fern definition drift detected",
+            evidenceFiles: [],
+            impactedDocs: [config.published],
+        };
+    }
+    const summary = "Fern definition YAML changed.";
+    const diffPath = node_path_1.default.join(evidenceDir, "fern.diff.txt");
+    node_fs_1.default.writeFileSync(diffPath, [
+        "# Fern Drift Summary",
+        summary,
+        "",
+        "# Current definition signature (file list + content hash)",
+        currentSignature.slice(0, 12000),
+    ].join("\n"), "utf8");
+    return {
+        hasDrift: true,
+        summary,
+        evidenceFiles: [diffPath],
+        impactedDocs: [config.published],
+        signal: {
+            kind: "fern_diff",
+            tier: 1,
+            confidence: 0.95,
+            evidence: [diffPath],
+        },
+    };
+}

package/dist/src/spec-providers/graphql.js

@@ -0,0 +1,168 @@
+"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.detectGraphQLSpecDrift = detectGraphQLSpecDrift;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const fs_1 = require("../utils/fs");
+const fetch_1 = require("../utils/fetch");
+const GRAPHQL_INTROSPECTION_QUERY = `
+  query IntrospectionQuery {
+    __schema {
+      types { name kind }
+      queryType { name }
+      mutationType { name }
+    }
+  }
+`;
+function normalizeGraphQLSchema(content) {
+    // Strip comments and normalize whitespace for comparison
+    return content
+        .replace(/#[^\n]*/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+async function getCurrentContent(config) {
+    const current = config.current;
+    if (current.type === "url") {
+        const body = { query: GRAPHQL_INTROSPECTION_QUERY };
+        const res = await (0, fetch_1.fetchSpecPost)(current.url, body);
+        const json = JSON.parse(res);
+        const schema = json?.data?.__schema;
+        if (!schema) {
+            throw new Error("GraphQL introspection did not return __schema");
+        }
+        return JSON.stringify(schema, null, 2);
+    }
+    if (current.type === "local") {
+        if (!node_fs_1.default.existsSync(current.path)) {
+            throw new Error(`GraphQL local path not found: ${current.path}`);
+        }
+        return node_fs_1.default.readFileSync(current.path, "utf8");
+    }
+    const { execCommand } = await Promise.resolve().then(() => __importStar(require("../utils/exec")));
+    const result = await execCommand(current.command);
+    if (result.exitCode !== 0) {
+        throw new Error(`GraphQL export failed: ${result.stderr}`);
+    }
+    if (!node_fs_1.default.existsSync(current.outputPath)) {
+        throw new Error(`GraphQL export did not create: ${current.outputPath}`);
+    }
+    return node_fs_1.default.readFileSync(current.outputPath, "utf8");
+}
+async function detectGraphQLSpecDrift(config, evidenceDir) {
+    if (config.format !== "graphql") {
+        return {
+            hasDrift: false,
+            summary: `Format ${config.format} is not graphql`,
+            evidenceFiles: [],
+            impactedDocs: [],
+        };
+    }
+    (0, fs_1.ensureDir)(evidenceDir);
+    let currentContent;
+    try {
+        currentContent = await getCurrentContent(config);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const logPath = node_path_1.default.join(evidenceDir, "graphql-export.log");
+        node_fs_1.default.writeFileSync(logPath, msg, "utf8");
+        return {
+            hasDrift: true,
+            summary: `GraphQL current spec failed: ${msg}`,
+            evidenceFiles: [logPath],
+            impactedDocs: [config.published],
+            signal: {
+                kind: "weak_evidence",
+                tier: 2,
+                confidence: 0.35,
+                evidence: [logPath],
+            },
+        };
+    }
+    if (!node_fs_1.default.existsSync(config.published)) {
+        return {
+            hasDrift: true,
+            summary: "GraphQL published file missing",
+            evidenceFiles: [],
+            impactedDocs: [config.published],
+            signal: {
+                kind: "weak_evidence",
+                tier: 2,
+                confidence: 0.35,
+                evidence: [],
+            },
+        };
+    }
+    const publishedContent = node_fs_1.default.readFileSync(config.published, "utf8");
+    const normalizedCurrent = normalizeGraphQLSchema(currentContent);
+    const normalizedPublished = normalizeGraphQLSchema(publishedContent);
+    if (normalizedCurrent === normalizedPublished) {
+        return {
+            hasDrift: false,
+            summary: "No GraphQL schema drift detected",
+            evidenceFiles: [],
+            impactedDocs: [config.published],
+        };
+    }
+    const summary = "GraphQL schema changed (types or fields differ).";
+    const diffPath = node_path_1.default.join(evidenceDir, "graphql.diff.txt");
+    node_fs_1.default.writeFileSync(diffPath, [
+        "# GraphQL Drift Summary",
+        summary,
+        "",
+        "# Published (excerpt)",
+        normalizedPublished.slice(0, 8000),
+        "",
+        "# Current (excerpt)",
+        normalizedCurrent.slice(0, 8000),
+    ].join("\n"), "utf8");
+    return {
+        hasDrift: true,
+        summary,
+        evidenceFiles: [diffPath],
+        impactedDocs: [config.published],
+        signal: {
+            kind: "graphql_diff",
+            tier: 1,
+            confidence: 0.95,
+            evidence: [diffPath],
+        },
+    };
+}

package/dist/src/spec-providers/openapi.js

@@ -0,0 +1,181 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectOpenApiSpecDrift = detectOpenApiSpecDrift;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const exec_1 = require("../utils/exec");
+const fs_1 = require("../utils/fs");
+const json_1 = require("../utils/json");
+const fetch_1 = require("../utils/fetch");
+function responseFields(spec) {
+    const fields = new Set();
+    const paths = spec?.paths ?? {};
+    for (const [pathName, methods] of Object.entries(paths)) {
+        for (const [method, methodDef] of Object.entries(methods)) {
+            const schema = methodDef?.responses?.["200"]?.content?.["application/json"]?.schema;
+            const properties = schema?.properties ?? {};
+            for (const key of Object.keys(properties)) {
+                fields.add(`${String(method).toUpperCase()} ${pathName}: ${key}`);
+            }
+        }
+    }
+    return fields;
+}
+function summarizeSpecDelta(previousSpec, currentSpec) {
+    const previous = responseFields(previousSpec);
+    const current = responseFields(currentSpec);
+    const added = [...current].filter((item) => !previous.has(item)).sort();
+    const removed = [...previous].filter((item) => !current.has(item)).sort();
+    const lines = [];
+    if (added.length) {
+        lines.push(`Added response fields (${added.length}):`);
+        lines.push(...added.map((value) => `+ ${value}`));
+    }
+    if (removed.length) {
+        lines.push(`Removed response fields (${removed.length}):`);
+        lines.push(...removed.map((value) => `- ${value}`));
+    }
+    if (!lines.length) {
+        return "OpenAPI changed, but no top-level response field changes were detected in 200 responses.";
+    }
+    return lines.join("\n");
+}
+async function getCurrentSpecContent(current, evidenceDir, logPath) {
+    const evidenceFiles = [];
+    if (current.type === "url") {
+        const content = await (0, fetch_1.fetchSpec)(current.url);
+        return { content, evidenceFiles };
+    }
+    if (current.type === "local") {
+        if (!node_fs_1.default.existsSync(current.path)) {
+            throw new Error(`OpenAPI local path not found: ${current.path}`);
+        }
+        const content = node_fs_1.default.readFileSync(current.path, "utf8");
+        return { content, evidenceFiles };
+    }
+    // current.type === "export"
+    const exportResult = await (0, exec_1.execCommand)(current.command);
+    node_fs_1.default.writeFileSync(logPath, [
+        `$ ${current.command}`,
+        `exitCode: ${exportResult.exitCode}`,
+        "\n--- stdout ---",
+        exportResult.stdout,
+        "\n--- stderr ---",
+        exportResult.stderr,
+    ].join("\n"), "utf8");
+    evidenceFiles.push(logPath);
+    if (exportResult.exitCode !== 0) {
+        throw new Error(`OpenAPI export failed: ${exportResult.stderr}`);
+    }
+    if (!node_fs_1.default.existsSync(current.outputPath)) {
+        throw new Error(`OpenAPI export did not create: ${current.outputPath}`);
+    }
+    const content = node_fs_1.default.readFileSync(current.outputPath, "utf8");
+    return { content, evidenceFiles };
+}
+async function detectOpenApiSpecDrift(config, evidenceDir) {
+    if (config.format !== "openapi3") {
+        return {
+            hasDrift: false,
+            summary: `Format ${config.format} is not openapi3`,
+            evidenceFiles: [],
+            impactedDocs: [],
+        };
+    }
+    (0, fs_1.ensureDir)(evidenceDir);
+    const logPath = node_path_1.default.join(evidenceDir, "openapi3-export.log");
+    let currentContent;
+    let evidenceFiles;
+    try {
+        const result = await getCurrentSpecContent(config.current, evidenceDir, logPath);
+        currentContent = result.content;
+        evidenceFiles = result.evidenceFiles;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            hasDrift: true,
+            summary: `OpenAPI current spec failed: ${msg}`,
+            evidenceFiles: [logPath],
+            impactedDocs: [config.published],
+            signal: {
+                kind: "weak_evidence",
+                tier: 2,
+                confidence: 0.35,
+                evidence: [logPath],
+            },
+        };
+    }
+    if (!node_fs_1.default.existsSync(config.published)) {
+        return {
+            hasDrift: true,
+            summary: "OpenAPI published file missing",
+            evidenceFiles,
+            impactedDocs: [config.published],
+            signal: {
+                kind: "weak_evidence",
+                tier: 2,
+                confidence: 0.35,
+                evidence: evidenceFiles,
+            },
+        };
+    }
+    const publishedRaw = node_fs_1.default.readFileSync(config.published, "utf8");
+    let currentJson;
+    let publishedJson;
+    try {
+        currentJson = JSON.parse(currentContent);
+        publishedJson = JSON.parse(publishedRaw);
+    }
+    catch {
+        return {
+            hasDrift: true,
+            summary: "OpenAPI invalid JSON",
+            evidenceFiles,
+            impactedDocs: [config.published],
+            signal: {
+                kind: "weak_evidence",
+                tier: 2,
+                confidence: 0.35,
+                evidence: evidenceFiles,
+            },
+        };
+    }
+    const normalizedCurrent = (0, json_1.stableStringify)(currentJson);
+    const normalizedPublished = (0, json_1.stableStringify)(publishedJson);
+    if (normalizedCurrent === normalizedPublished) {
+        return {
+            hasDrift: false,
+            summary: "No OpenAPI drift detected",
+            evidenceFiles,
+            impactedDocs: [config.published],
+        };
+    }
+    const summary = summarizeSpecDelta(publishedJson, currentJson);
+    const diffPath = node_path_1.default.join(evidenceDir, "openapi3.diff.txt");
+    node_fs_1.default.writeFileSync(diffPath, [
+        "# OpenAPI Drift Summary",
+        summary,
+        "",
+        "# Published (normalized)",
+        normalizedPublished,
+        "",
+        "# Current (normalized)",
+        normalizedCurrent,
+    ].join("\n"), "utf8");
+    return {
+        hasDrift: true,
+        summary,
+        evidenceFiles: [...evidenceFiles, diffPath],
+        impactedDocs: [config.published],
+        signal: {
+            kind: "openapi_diff",
+            tier: 1,
+            confidence: 0.95,
+            evidence: [diffPath],
+        },
+    };
+}