@devinnn/docdrift 0.1.2 → 0.1.4

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],
+        },
+    };
+}

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 });