@devinnn/docdrift 0.1.2 → 0.1.4

package/dist/src/setup/onboard.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureDocdriftDir = ensureDocdriftDir;
+exports.createCustomInstructionsFile = createCustomInstructionsFile;
+exports.ensureGitignore = ensureGitignore;
+exports.addGitHubWorkflow = addGitHubWorkflow;
+exports.runOnboarding = runOnboarding;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const DOCDRIFT_DIR = ".docdrift";
+const CUSTOM_INSTRUCTIONS_FILE = ".docdrift/DocDrift.md";
+const GITIGNORE_BLOCK = `
+# Docdrift run artifacts
+.docdrift/evidence
+.docdrift/*.log
+.docdrift/state.json
+.docdrift/run-output.json
+`;
+const WORKFLOW_CONTENT = "name: docdrift\n\non:\n  push:\n    branches: [\"main\"]\n  pull_request:\n    branches: [\"main\"]\n  workflow_dispatch:\n\njobs:\n  docdrift:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: write\n      pull-requests: write\n      issues: write\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n\n      - uses: actions/setup-node@v4\n        with:\n          node-version: \"20\"\n\n      - run: npm install\n\n      - name: Determine SHAs\n        id: shas\n        run: |\n          if [ \"${{ github.event_name }}\" = \"pull_request\" ]; then\n            HEAD_SHA=\"${{ github.event.pull_request.head.sha }}\"\n            BASE_SHA=\"${{ github.event.pull_request.base.sha }}\"\n          else\n            HEAD_SHA=\"${{ github.sha }}\"\n            BASE_SHA=\"${{ github.event.before }}\"\n            if [ -z \"$BASE_SHA\" ] || [ \"$BASE_SHA\" = \"0000000000000000000000000000000000000000\" ]; then\n              BASE_SHA=\"$(git rev-parse HEAD^)\"\n            fi\n          fi\n          echo \"head=${HEAD_SHA}\" >> $GITHUB_OUTPUT\n          echo \"base=${BASE_SHA}\" >> $GITHUB_OUTPUT\n          echo \"pr_number=${{ github.event.pull_request.number || '' }}\" >> $GITHUB_OUTPUT\n\n      - name: Validate config\n        run: npx docdrift validate\n\n      - name: Run Doc Drift\n        env:\n          DEVIN_API_KEY: ${{ secrets.DEVIN_API_KEY }}\n          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n          GITHUB_REPOSITORY: ${{ github.repository }}\n          GITHUB_SHA: ${{ github.sha }}\n          GITHUB_EVENT_NAME: ${{ github.event_name }}\n          GITHUB_PR_NUMBER: ${{ steps.shas.outputs.pr_number }}\n        run: |\n          PR_ARGS=\"\"\n          if [ -n \"$GITHUB_PR_NUMBER\" ]; then\n            PR_ARGS=\"--trigger pull_request --pr-number $GITHUB_PR_NUMBER\"\n          fi\n          npx docdrift run --base ${{ steps.shas.outputs.base }} --head ${{ steps.shas.outputs.head }} $PR_ARGS\n\n      - name: Upload artifacts\n        if: always()\n        uses: actions/upload-artifact@v4\n        with:\n          name: docdrift-artifacts\n          path: |\n            .docdrift/drift_report.json\n            .docdrift/metrics.json\n            .docdrift/run-output.json\n            .docdrift/evidence/**\n            .docdrift/state.json\n";
+function ensureDocdriftDir(cwd) {
+    const dir = node_path_1.default.resolve(cwd, DOCDRIFT_DIR);
+    node_fs_1.default.mkdirSync(dir, { recursive: true });
+}
+const CUSTOM_INSTRUCTIONS_TEMPLATE = `# DocDrift custom instructions
+
+- **PR titles:** Start every pull request title with \`[docdrift]\`.
+- Add project-specific guidance for Devin here (e.g. terminology, tone, what to avoid).
+`;
+function createCustomInstructionsFile(cwd) {
+    const filePath = node_path_1.default.resolve(cwd, CUSTOM_INSTRUCTIONS_FILE);
+    ensureDocdriftDir(cwd);
+    node_fs_1.default.writeFileSync(filePath, CUSTOM_INSTRUCTIONS_TEMPLATE.trimStart(), "utf8");
+}
+const GITIGNORE_ENTRIES = [
+    ".docdrift/evidence",
+    ".docdrift/*.log",
+    ".docdrift/state.json",
+    ".docdrift/run-output.json",
+];
+function hasGitignoreBlock(content) {
+    return GITIGNORE_ENTRIES.every((e) => content.includes(e));
+}
+function ensureGitignore(cwd) {
+    const gitignorePath = node_path_1.default.resolve(cwd, ".gitignore");
+    let content = "";
+    if (node_fs_1.default.existsSync(gitignorePath)) {
+        content = node_fs_1.default.readFileSync(gitignorePath, "utf8");
+        if (hasGitignoreBlock(content))
+            return;
+    }
+    const toAppend = content.endsWith("\n") ? GITIGNORE_BLOCK.trimStart() : GITIGNORE_BLOCK;
+    node_fs_1.default.writeFileSync(gitignorePath, content + toAppend, "utf8");
+}
+function addGitHubWorkflow(cwd) {
+    const workflowsDir = node_path_1.default.resolve(cwd, ".github", "workflows");
+    node_fs_1.default.mkdirSync(workflowsDir, { recursive: true });
+    const workflowPath = node_path_1.default.join(workflowsDir, "docdrift.yml");
+    node_fs_1.default.writeFileSync(workflowPath, WORKFLOW_CONTENT, "utf8");
+}
+function runOnboarding(cwd, choices) {
+    const created = [];
+    ensureDocdriftDir(cwd);
+    created.push(".docdrift/");
+    if (choices.addCustomInstructions) {
+        createCustomInstructionsFile(cwd);
+        created.push("DocDrift.md");
+    }
+    if (choices.addGitignore) {
+        ensureGitignore(cwd);
+        created.push(".gitignore");
+    }
+    if (choices.addWorkflow) {
+        addGitHubWorkflow(cwd);
+        created.push(".github/workflows/docdrift.yml");
+    }
+    return { created };
+}

package/dist/src/setup/prompts.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYSTEM_PROMPT = void 0;
+exports.SYSTEM_PROMPT = `You are a docdrift config expert. Given a repo fingerprint (file tree, package.json scripts, and detected paths), infer a partial docdrift.yaml configuration and a list of interactive choices for the user.
+
+## Docdrift config (simple mode)
+
+Minimal valid config uses: version, openapi, docsite, pathMappings, devin, policy.
+
+Example:
+\`\`\`yaml
+version: 1
+openapi:
+  export: "npm run openapi:export"
+  generated: "openapi/generated.json"
+  published: "apps/docs-site/openapi/openapi.json"
+docsite: "apps/docs-site"
+pathMappings:
+  - match: "apps/api/**"
+    impacts: ["apps/docs-site/docs/**", "apps/docs-site/openapi/**"]
+exclude: ["**/CHANGELOG*", "apps/docs-site/blog/**"]
+requireHumanReview: []
+devin:
+  apiVersion: v1
+  unlisted: true
+  maxAcuLimit: 2
+  tags: ["docdrift"]
+policy:
+  prCaps: { maxPrsPerDay: 5, maxFilesTouched: 30 }
+  confidence: { autopatchThreshold: 0.8 }
+  allowlist: ["openapi/**", "apps/**"]
+  verification:
+    commands: ["npm run docs:gen", "npm run docs:build"]
+  slaDays: 7
+  slaLabel: docdrift
+  allowNewFiles: false
+\`\`\`
+
+## Field rules
+
+- openapi.export: Command to generate OpenAPI spec (e.g. "npm run openapi:export"). Prefer an existing script from root or workspace package.json.
+- openapi.generated: Path where the export writes the spec (e.g. "openapi/generated.json").
+- openapi.published: Path where the docsite consumes the spec (often under docsite, e.g. "apps/docs-site/openapi/openapi.json").
+- docsite: Path to the docs site root (Docusaurus, Next.js docs, VitePress, MkDocs). Single string or array of strings.
+- pathMappings: Array of { match, impacts }. match = glob for source/API code; impacts = globs for doc files that may need updates when match changes.
+- policy.verification.commands: Commands to run after patching (e.g. "npm run docs:gen", "npm run docs:build"). Must exist in repo.
+- exclude: Globs to never touch (e.g. blog, CHANGELOG).
+- requireHumanReview: Globs that require human review when touched (e.g. guides).
+
+## Common patterns
+
+- Docusaurus: docsite often has docusaurus.config.*; docs:gen may be "docusaurus -- gen-api-docs api"; openapi published path often under docsite/openapi/.
+- Next/VitePress/MkDocs: docsite is the app root; look for docs/ or similar.
+
+## Output rules
+
+1. Infer suggestedConfig from the fingerprint. Only include fields you can confidently infer. Use existing paths and scripts from the fingerprint; do not invent paths that are not present.
+2. For each field where confidence is medium or low, OR where multiple valid options exist, add an entry to choices with: key (e.g. "openapi.export"), question, options (array of { value, label, recommended? }), defaultIndex, help?, warning?, confidence ("high"|"medium"|"low").
+3. Add to skipQuestions the keys for which you are highly confident so the CLI will not ask the user.
+4. Prefer fewer, high-quality choices. If truly uncertain, set confidence to "low" and provide 2–3 options.
+5. Do not suggest paths that do not exist in the fingerprint. Prefer existing package.json scripts for export and verification commands.
+6. suggestedConfig must be a valid partial docdrift config; policy.allowlist and policy.verification.commands are required if you include policy. devin.apiVersion must be "v1" if you include devin.`;

package/dist/src/setup/repo-fingerprint.js

@@ -0,0 +1,155 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRepoFingerprint = buildRepoFingerprint;
+exports.fingerprintHash = fingerprintHash;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const IGNORE_DIRS = new Set(["node_modules", ".git", "dist", "build", "coverage", ".docdrift"]);
+const DOC_HINTS = ["openapi", "swagger", "docusaurus", "mkdocs", "next", "vitepress"];
+const MAX_TREE_DEPTH = 3;
+function walkDir(dir, depth, tree) {
+    if (depth > MAX_TREE_DEPTH)
+        return;
+    let entries;
+    try {
+        entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const relDir = node_path_1.default.relative(process.cwd(), dir) || ".";
+    const names = [];
+    for (const e of entries) {
+        if (e.name.startsWith(".") && e.name !== ".env")
+            continue;
+        if (IGNORE_DIRS.has(e.name))
+            continue;
+        names.push(e.isDirectory() ? `${e.name}/` : e.name);
+    }
+    names.sort();
+    tree[relDir] = names;
+    for (const e of entries) {
+        if (!e.isDirectory() || IGNORE_DIRS.has(e.name))
+            continue;
+        walkDir(node_path_1.default.join(dir, e.name), depth + 1, tree);
+    }
+}
+function findMatchingFiles(cwd, test) {
+    const out = [];
+    function walk(dir, depth) {
+        if (depth > 5)
+            return;
+        let entries;
+        try {
+            entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith(".") && e.name !== ".env")
+                continue;
+            if (IGNORE_DIRS.has(e.name))
+                continue;
+            const full = node_path_1.default.join(dir, e.name);
+            const rel = node_path_1.default.relative(cwd, full);
+            if (e.isFile() && test(rel, e.name))
+                out.push(rel);
+            else if (e.isDirectory())
+                walk(full, depth + 1);
+        }
+    }
+    walk(cwd, 0);
+    return out;
+}
+function findDirsNamed(cwd, name) {
+    const out = [];
+    function scan(dir, depth) {
+        if (depth > 2)
+            return;
+        let entries;
+        try {
+            entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith(".") || IGNORE_DIRS.has(e.name))
+                continue;
+            const full = node_path_1.default.join(dir, e.name);
+            const rel = node_path_1.default.relative(cwd, full);
+            if (e.isDirectory()) {
+                if (e.name === name)
+                    out.push(rel);
+                scan(full, depth + 1);
+            }
+        }
+    }
+    scan(cwd, 0);
+    return out;
+}
+function buildRepoFingerprint(cwd = process.cwd()) {
+    const fileTree = {};
+    walkDir(cwd, 0, fileTree);
+    let rootPackage = { scripts: {}, dependencies: [], workspaces: [] };
+    const pkgPath = node_path_1.default.join(cwd, "package.json");
+    if (node_fs_1.default.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(node_fs_1.default.readFileSync(pkgPath, "utf8"));
+            rootPackage.scripts = pkg.scripts || {};
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+            rootPackage.dependencies = Object.keys(deps || {}).filter((k) => DOC_HINTS.some((h) => k.toLowerCase().includes(h)));
+            if (pkg.workspaces) {
+                rootPackage.workspaces = Array.isArray(pkg.workspaces) ? pkg.workspaces : [pkg.workspaces];
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    const workspacePackages = [];
+    if (rootPackage.workspaces?.length) {
+        for (const w of rootPackage.workspaces) {
+            const base = w.replace("/*", "").replace("*", "");
+            const dir = node_path_1.default.join(cwd, base);
+            if (!node_fs_1.default.existsSync(dir) || !node_fs_1.default.statSync(dir).isDirectory())
+                continue;
+            const subdirs = base.includes("*") ? node_fs_1.default.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => node_path_1.default.join(dir, e.name)) : [dir];
+            for (const sub of subdirs) {
+                const pj = node_path_1.default.join(sub, "package.json");
+                if (!node_fs_1.default.existsSync(pj))
+                    continue;
+                try {
+                    const pkg = JSON.parse(node_fs_1.default.readFileSync(pj, "utf8"));
+                    workspacePackages.push({
+                        path: node_path_1.default.relative(cwd, sub),
+                        scripts: pkg.scripts || {},
+                    });
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+    }
+    const openapi = findMatchingFiles(cwd, (_, name) => /^openapi.*\.json$/i.test(name));
+    const swagger = findMatchingFiles(cwd, (_, name) => /^swagger.*\.json$/i.test(name));
+    const docusaurusConfig = findMatchingFiles(cwd, (_, name) => name.startsWith("docusaurus.config."));
+    const mkdocs = findMatchingFiles(cwd, (_, name) => name === "mkdocs.yml");
+    const docsDirs = findDirsNamed(cwd, "docs");
+    return {
+        fileTree,
+        rootPackage,
+        workspacePackages,
+        foundPaths: { openapi, swagger, docusaurusConfig, mkdocs, docsDirs },
+    };
+}
+function fingerprintHash(fingerprint) {
+    const canonical = JSON.stringify(fingerprint, Object.keys(fingerprint).sort());
+    return node_crypto_1.default.createHash("sha256").update(canonical).digest("hex");
+}

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