@devinnn/docdrift 0.1.2 → 0.1.3

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

@@ -0,0 +1,193 @@
+"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.detectPostmanSpecDrift = detectPostmanSpecDrift;
+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");
+const fetch_1 = require("../utils/fetch");
+function extractEndpoints(collection) {
+    const endpoints = new Set();
+    const info = collection?.info ?? collection?.information;
+    const items = collection?.item ?? [];
+    function walk(items, prefix = "") {
+        for (const item of items) {
+            if (!item)
+                continue;
+            const name = item.name ?? item.id ?? "";
+            if (item.request) {
+                const req = typeof item.request === "string" ? { url: item.request, method: "GET" } : item.request;
+                const url = req?.url?.raw ?? req?.url ?? "";
+                const method = (req?.method ?? "GET").toUpperCase();
+                if (url) {
+                    endpoints.add(`${method} ${url}`);
+                }
+            }
+            else if (item.item) {
+                walk(item.item, `${prefix}/${name}`);
+            }
+        }
+    }
+    walk(Array.isArray(items) ? items : [items]);
+    return endpoints;
+}
+async function getCurrentContent(config) {
+    const current = config.current;
+    if (current.type === "url") {
+        return (0, fetch_1.fetchSpec)(current.url);
+    }
+    if (current.type === "local") {
+        if (!node_fs_1.default.existsSync(current.path)) {
+            throw new Error(`Postman collection 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(`Postman export failed: ${result.stderr}`);
+    }
+    if (!node_fs_1.default.existsSync(current.outputPath)) {
+        throw new Error(`Postman export did not create: ${current.outputPath}`);
+    }
+    return node_fs_1.default.readFileSync(current.outputPath, "utf8");
+}
+async function detectPostmanSpecDrift(config, evidenceDir) {
+    if (config.format !== "postman") {
+        return {
+            hasDrift: false,
+            summary: `Format ${config.format} is not postman`,
+            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, "postman-export.log");
+        node_fs_1.default.writeFileSync(logPath, msg, "utf8");
+        return {
+            hasDrift: true,
+            summary: `Postman 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: "Postman published file missing",
+            evidenceFiles: [],
+            impactedDocs: [config.published],
+            signal: {
+                kind: "weak_evidence",
+                tier: 2,
+                confidence: 0.35,
+                evidence: [],
+            },
+        };
+    }
+    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: "Postman collection invalid JSON",
+            evidenceFiles: [],
+            impactedDocs: [config.published],
+            signal: {
+                kind: "weak_evidence",
+                tier: 2,
+                confidence: 0.35,
+                evidence: [],
+            },
+        };
+    }
+    const currentEndpoints = extractEndpoints(currentJson);
+    const publishedEndpoints = extractEndpoints(publishedJson);
+    const added = [...currentEndpoints].filter((e) => !publishedEndpoints.has(e)).sort();
+    const removed = [...publishedEndpoints].filter((e) => !currentEndpoints.has(e)).sort();
+    if (added.length === 0 && removed.length === 0) {
+        return {
+            hasDrift: false,
+            summary: "No Postman collection drift detected",
+            evidenceFiles: [],
+            impactedDocs: [config.published],
+        };
+    }
+    const lines = [];
+    if (added.length) {
+        lines.push(`Added endpoints (${added.length}):`);
+        lines.push(...added.map((v) => `+ ${v}`));
+    }
+    if (removed.length) {
+        lines.push(`Removed endpoints (${removed.length}):`);
+        lines.push(...removed.map((v) => `- ${v}`));
+    }
+    const summary = lines.join("\n");
+    const diffPath = node_path_1.default.join(evidenceDir, "postman.diff.txt");
+    node_fs_1.default.writeFileSync(diffPath, ["# Postman Drift Summary", summary, "", "# Current endpoints", (0, json_1.stableStringify)([...currentEndpoints].sort()), "", "# Published endpoints", (0, json_1.stableStringify)([...publishedEndpoints].sort())].join("\n"), "utf8");
+    return {
+        hasDrift: true,
+        summary,
+        evidenceFiles: [diffPath],
+        impactedDocs: [config.published],
+        signal: {
+            kind: "postman_diff",
+            tier: 1,
+            confidence: 0.95,
+            evidence: [diffPath],
+        },
+    };
+}

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

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSpecDetector = getSpecDetector;
+exports.getSupportedFormats = getSupportedFormats;
+const openapi_1 = require("./openapi");
+const swagger2_1 = require("./swagger2");
+const graphql_1 = require("./graphql");
+const fern_1 = require("./fern");
+const postman_1 = require("./postman");
+const registry = {
+    openapi3: openapi_1.detectOpenApiSpecDrift,
+    swagger2: swagger2_1.detectSwagger2SpecDrift,
+    graphql: graphql_1.detectGraphQLSpecDrift,
+    fern: fern_1.detectFernSpecDrift,
+    postman: postman_1.detectPostmanSpecDrift,
+};
+function getSpecDetector(format) {
+    const detector = registry[format];
+    if (!detector) {
+        throw new Error(`Unknown spec format: ${format}`);
+    }
+    return detector;
+}
+function getSupportedFormats() {
+    return Object.keys(registry);
+}

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

@@ -0,0 +1,229 @@
+"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.detectSwagger2SpecDrift = detectSwagger2SpecDrift;
+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");
+const fetch_1 = require("../utils/fetch");
+function resolveRef(spec, ref) {
+    if (!ref || !ref.startsWith("#/"))
+        return null;
+    const parts = ref.slice(2).split("/");
+    let cur = spec;
+    for (const p of parts) {
+        cur = cur?.[p];
+    }
+    return cur;
+}
+function getResponseFieldsSwagger2(spec) {
+    const fields = new Set();
+    const paths = spec?.paths ?? {};
+    const definitions = spec?.definitions ?? {};
+    for (const [pathName, pathItem] of Object.entries(paths)) {
+        const item = pathItem;
+        for (const method of ["get", "post", "put", "patch", "delete"]) {
+            const op = item[method];
+            if (!op)
+                continue;
+            const res = op.responses?.["200"];
+            if (!res)
+                continue;
+            let schema = res.schema;
+            if (schema?.$ref) {
+                schema = resolveRef({ paths, definitions }, schema.$ref) ?? schema;
+            }
+            const properties = schema?.properties ?? {};
+            for (const key of Object.keys(properties)) {
+                fields.add(`${method.toUpperCase()} ${pathName}: ${key}`);
+            }
+        }
+    }
+    return fields;
+}
+function summarizeSwagger2Delta(previousSpec, currentSpec) {
+    const previous = getResponseFieldsSwagger2(previousSpec);
+    const current = getResponseFieldsSwagger2(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 "Swagger 2 changed, but no top-level response field changes were detected in 200 responses.";
+    }
+    return lines.join("\n");
+}
+async function getCurrentContent(config) {
+    const current = config.current;
+    if (current.type === "url") {
+        return (0, fetch_1.fetchSpec)(current.url);
+    }
+    if (current.type === "local") {
+        if (!node_fs_1.default.existsSync(current.path)) {
+            throw new Error(`Swagger 2 local path not found: ${current.path}`);
+        }
+        return node_fs_1.default.readFileSync(current.path, "utf8");
+    }
+    // export: run command then read outputPath
+    const { execCommand } = await Promise.resolve().then(() => __importStar(require("../utils/exec")));
+    const result = await execCommand(current.command);
+    if (result.exitCode !== 0) {
+        throw new Error(`Swagger 2 export failed: ${result.stderr}`);
+    }
+    if (!node_fs_1.default.existsSync(current.outputPath)) {
+        throw new Error(`Swagger 2 export did not create: ${current.outputPath}`);
+    }
+    return node_fs_1.default.readFileSync(current.outputPath, "utf8");
+}
+async function detectSwagger2SpecDrift(config, evidenceDir) {
+    if (config.format !== "swagger2") {
+        return {
+            hasDrift: false,
+            summary: `Format ${config.format} is not swagger2`,
+            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, "swagger2-export.log");
+        node_fs_1.default.writeFileSync(logPath, msg, "utf8");
+        return {
+            hasDrift: true,
+            summary: `Swagger 2 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: "Swagger 2 published file missing",
+            evidenceFiles: [],
+            impactedDocs: [config.published],
+            signal: {
+                kind: "weak_evidence",
+                tier: 2,
+                confidence: 0.35,
+                evidence: [],
+            },
+        };
+    }
+    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: "Swagger 2 invalid JSON",
+            evidenceFiles: [],
+            impactedDocs: [config.published],
+            signal: {
+                kind: "weak_evidence",
+                tier: 2,
+                confidence: 0.35,
+                evidence: [],
+            },
+        };
+    }
+    if (currentJson.swagger !== "2.0") {
+        return {
+            hasDrift: false,
+            summary: "Not a Swagger 2.0 spec",
+            evidenceFiles: [],
+            impactedDocs: [],
+        };
+    }
+    const normalizedCurrent = (0, json_1.stableStringify)(currentJson);
+    const normalizedPublished = (0, json_1.stableStringify)(publishedJson);
+    if (normalizedCurrent === normalizedPublished) {
+        return {
+            hasDrift: false,
+            summary: "No Swagger 2 drift detected",
+            evidenceFiles: [],
+            impactedDocs: [config.published],
+        };
+    }
+    const summary = summarizeSwagger2Delta(publishedJson, currentJson);
+    const diffPath = node_path_1.default.join(evidenceDir, "swagger2.diff.txt");
+    node_fs_1.default.writeFileSync(diffPath, [
+        "# Swagger 2 Drift Summary",
+        summary,
+        "",
+        "# Published (normalized)",
+        normalizedPublished,
+        "",
+        "# Current (normalized)",
+        normalizedCurrent,
+    ].join("\n"), "utf8");
+    return {
+        hasDrift: true,
+        summary,
+        evidenceFiles: [diffPath],
+        impactedDocs: [config.published],
+        signal: {
+            kind: "swagger2_diff",
+            tier: 1,
+            confidence: 0.95,
+            evidence: [diffPath],
+        },
+    };
+}

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/utils/fetch.js

@@ -0,0 +1,87 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchSpec = fetchSpec;
+exports.fetchSpecPost = fetchSpecPost;
+const node_https_1 = __importDefault(require("node:https"));
+const node_http_1 = __importDefault(require("node:http"));
+const TIMEOUT_MS = 30_000;
+function getAgent(_url) {
+    const proxy = process.env.HTTPS_PROXY || process.env.HTTP_PROXY;
+    if (proxy) {
+        try {
+            const { HttpsProxyAgent } = require("https-proxy-agent");
+            return new HttpsProxyAgent(proxy);
+        }
+        catch {
+            // Optional dependency not installed
+        }
+    }
+    return undefined;
+}
+/**
+ * Fetch a URL and return the response body as string.
+ * Respects HTTP_PROXY, HTTPS_PROXY; 30s timeout; follows redirects.
+ */
+async function fetchSpec(url) {
+    const parsed = new URL(url);
+    const isHttps = parsed.protocol === "https:";
+    const agent = getAgent(url);
+    return new Promise((resolve, reject) => {
+        const req = (isHttps ? node_https_1.default : node_http_1.default).get(url, { agent: agent ?? undefined, timeout: TIMEOUT_MS }, (res) => {
+            const redirect = res.headers.location;
+            if (redirect && [301, 302, 307, 308].includes(res.statusCode ?? 0)) {
+                req.destroy();
+                fetchSpec(new URL(redirect, url).href).then(resolve).catch(reject);
+                return;
+            }
+            const chunks = [];
+            res.on("data", (chunk) => chunks.push(chunk));
+            res.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+            res.on("error", reject);
+        });
+        req.on("timeout", () => {
+            req.destroy();
+            reject(new Error(`Fetch timeout after ${TIMEOUT_MS}ms`));
+        });
+        req.on("error", reject);
+    });
+}
+/**
+ * POST to a URL with JSON body (e.g. GraphQL introspection).
+ */
+async function fetchSpecPost(url, body) {
+    const parsed = new URL(url);
+    const isHttps = parsed.protocol === "https:";
+    const agent = getAgent(url);
+    const bodyStr = JSON.stringify(body);
+    return new Promise((resolve, reject) => {
+        const options = {
+            hostname: parsed.hostname,
+            port: parsed.port || (isHttps ? 443 : 80),
+            path: parsed.pathname + parsed.search,
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Content-Length": Buffer.byteLength(bodyStr),
+            },
+            ...(agent && { agent }),
+            timeout: TIMEOUT_MS,
+        };
+        const req = (isHttps ? node_https_1.default : node_http_1.default).request(options, (res) => {
+            const chunks = [];
+            res.on("data", (chunk) => chunks.push(chunk));
+            res.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+            res.on("error", reject);
+        });
+        req.on("timeout", () => {
+            req.destroy();
+            reject(new Error(`Fetch timeout after ${TIMEOUT_MS}ms`));
+        });
+        req.on("error", reject);
+        req.write(bodyStr);
+        req.end();
+    });
+}

package/dist/src/utils/git.js

@@ -1,9 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDefaultBaseHead = resolveDefaultBaseHead;
 exports.gitChangedPaths = gitChangedPaths;
 exports.gitDiffSummary = gitDiffSummary;
 exports.gitCommitList = gitCommitList;
 const exec_1 = require("./exec");
+/** Resolve default base/head when not provided. Uses GITHUB_* in CI, else merge-base(main, headRef)..headRef. */
+async function resolveDefaultBaseHead(headRef = process.env.GITHUB_SHA ?? "HEAD") {
+    const headSha = headRef;
+    const baseSha = process.env.GITHUB_BASE_SHA;
+    if (baseSha) {
+        return { baseSha, headSha };
+    }
+    for (const branch of ["origin/main", "origin/master", "main", "master"]) {
+        const res = await (0, exec_1.execCommand)(`git merge-base ${branch} ${headRef}`);
+        if (res.exitCode === 0 && res.stdout.trim()) {
+            return { baseSha: res.stdout.trim(), headSha };
+        }
+    }
+    const fallback = await (0, exec_1.execCommand)(`git rev-parse ${headRef}^`);
+    if (fallback.exitCode === 0 && fallback.stdout.trim()) {
+        return { baseSha: fallback.stdout.trim(), headSha };
+    }
+    return { baseSha: headSha, headSha };
+}
 async function gitChangedPaths(baseSha, headSha) {
     const res = await (0, exec_1.execCommand)(`git diff --name-only ${baseSha} ${headSha}`);
     if (res.exitCode !== 0) {