@devinnn/docdrift 0.1.1 → 0.1.3

package/README.md

@@ -9,6 +9,7 @@ Docs that never lie: detect drift between merged code and docs, then open low-no
   - `detect --base <sha> --head <sha>`
   - `run --base <sha> --head <sha>`
   - `status --since 24h`
+  - `sla-check` — Check for doc-drift PRs open 7+ days and open a reminder issue
 - GitHub Action: `/Users/cameronking/Desktop/sideproject/docdrift/.github/workflows/devin-doc-drift.yml`
 - Repo-local config: `/Users/cameronking/Desktop/sideproject/docdrift/docdrift.yaml`
 - Demo API + OpenAPI exporter + driftable docs
@@ -16,17 +17,18 @@ Docs that never lie: detect drift between merged code and docs, then open low-no
 
 ## Why this is low-noise
 
-- One PR per doc area per day (bundling rule).
-- Global PR/day cap.
-- Confidence gating and allowlist enforcement.
-- Conceptual docs default to issue escalation with targeted questions.
+- **Single session, single PR** — One Devin session handles the whole docsite (API reference + guides).
+- **Gate on API spec diff** — We only run when OpenAPI drift is detected; no session for docs-check-only failures.
+- **requireHumanReview** — When the PR touches guides/prose, we open an issue after the PR to direct attention.
+- **7-day SLA** — If a doc-drift PR is open 7+ days, we open a reminder issue (configurable `slaDays`; use `sla-check` CLI or cron workflow).
+- Confidence gating and allowlist/exclude enforcement.
 - Idempotency key prevents duplicate actions for same repo/SHAs/action.
 
-## Detection tiers
+## Detection and gate
 
-- Tier 0: docsite verification (`npm run docs:gen` then `npm run docs:build`)
-- Tier 1: OpenAPI drift (`openapi/generated.json` vs `apps/docs-site/openapi/openapi.json`)
-- Tier 2: heuristic path impacts (e.g. `apps/api/src/auth/**` -> `apps/docs-site/docs/guides/auth.md`)
+- **Gate:** We only run a Devin session when **OpenAPI drift** is detected. No drift → no session.
+- Tier 1: OpenAPI drift (`openapi/generated.json` vs published spec)
+- Tier 2: Heuristic path impacts from docAreas (e.g. `apps/api/src/auth/**` → guides)
 
 Output artifacts (under `.docdrift/`):
 
@@ -38,13 +40,13 @@ When you run docdrift as a package (e.g. `npx docdrift` or from another repo), a
 ## Core flow (`docdrift run`)
 
 1. Validate config and command availability.
-2. Build drift report.
+2. Build drift report. **Gate:** If no OpenAPI drift, exit (no session).
 3. Policy decision (`OPEN_PR | UPDATE_EXISTING_PR | OPEN_ISSUE | NOOP`).
-4. Build evidence bundle (`.docdrift/evidence/<runId>/<docArea>` + tarball).
-5. Upload attachments to Devin v1 and create session.
-6. Poll session to terminal status.
+4. Build one aggregated evidence bundle for the whole docsite.
+5. One Devin session with whole-docsite prompt; poll to terminal status.
+6. If PR opened and touches `requireHumanReview` paths → create issue to direct attention.
 7. Surface result via GitHub commit comment; open issue on blocked/low-confidence paths.
-8. Persist state in `.docdrift/state.json` and write `.docdrift/metrics.json`.
+8. Persist state (including `lastDocDriftPrUrl` for SLA); write `.docdrift/metrics.json`.
 
 ## Where the docs are (this repo)
 

package/dist/src/cli.js

@@ -17,7 +17,7 @@ function getArg(args, flag) {
 async function main() {
     const [, , command, ...args] = process.argv;
     if (!command) {
-        throw new Error("Usage: docdrift <validate|detect|run|status> [options]");
+        throw new Error("Usage: docdrift <validate|detect|run|status|sla-check> [options]\n  detect|run: [--base SHA] [--head SHA] (defaults: merge-base with main..HEAD)");
     }
     switch (command) {
         case "validate": {
@@ -25,18 +25,20 @@ async function main() {
             return;
         }
         case "detect": {
-            const baseSha = (0, index_1.requireSha)(getArg(args, "--base"), "--base");
-            const headSha = (0, index_1.requireSha)(getArg(args, "--head"), "--head");
-            const trigger = (0, index_1.resolveTrigger)(process.env.GITHUB_EVENT_NAME);
-            const result = await (0, index_1.runDetect)({ baseSha, headSha, trigger });
+            const { baseSha, headSha } = await (0, index_1.resolveBaseHead)(getArg(args, "--base"), getArg(args, "--head"));
+            const trigger = getArg(args, "--trigger") ?? (0, index_1.resolveTrigger)(process.env.GITHUB_EVENT_NAME);
+            const prNum = getArg(args, "--pr-number");
+            const prNumber = prNum ? parseInt(prNum, 10) : (process.env.GITHUB_PR_NUMBER ? parseInt(process.env.GITHUB_PR_NUMBER, 10) : undefined);
+            const result = await (0, index_1.runDetect)({ baseSha, headSha, trigger, prNumber: Number.isFinite(prNumber) ? prNumber : undefined });
             process.exitCode = result.hasDrift ? 1 : 0;
             return;
         }
         case "run": {
-            const baseSha = (0, index_1.requireSha)(getArg(args, "--base"), "--base");
-            const headSha = (0, index_1.requireSha)(getArg(args, "--head"), "--head");
-            const trigger = (0, index_1.resolveTrigger)(process.env.GITHUB_EVENT_NAME);
-            const results = await (0, index_1.runDocDrift)({ baseSha, headSha, trigger });
+            const { baseSha, headSha } = await (0, index_1.resolveBaseHead)(getArg(args, "--base"), getArg(args, "--head"));
+            const trigger = getArg(args, "--trigger") ?? (0, index_1.resolveTrigger)(process.env.GITHUB_EVENT_NAME);
+            const prNum = getArg(args, "--pr-number");
+            const prNumber = prNum ? parseInt(prNum, 10) : (process.env.GITHUB_PR_NUMBER ? parseInt(process.env.GITHUB_PR_NUMBER, 10) : undefined);
+            const results = await (0, index_1.runDocDrift)({ baseSha, headSha, trigger, prNumber: Number.isFinite(prNumber) ? prNumber : undefined });
             const outPath = node_path_1.default.resolve(".docdrift", "run-output.json");
             node_fs_1.default.mkdirSync(node_path_1.default.dirname(outPath), { recursive: true });
             node_fs_1.default.writeFileSync(outPath, JSON.stringify(results, null, 2), "utf-8");
@@ -49,6 +51,10 @@ async function main() {
             await (0, index_1.runStatus)(sinceHours);
             return;
         }
+        case "sla-check": {
+            await (0, index_1.runSlaCheck)();
+            return;
+        }
         default:
             throw new Error(`Unknown command: ${command}`);
     }

package/dist/src/config/load.js

@@ -4,9 +4,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadConfig = loadConfig;
+exports.loadNormalizedConfig = loadNormalizedConfig;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const js_yaml_1 = __importDefault(require("js-yaml"));
+const normalize_1 = require("./normalize");
 const schema_1 = require("./schema");
 function loadConfig(configPath = "docdrift.yaml") {
     const resolved = node_path_1.default.resolve(configPath);
@@ -36,3 +38,8 @@ function loadConfig(configPath = "docdrift.yaml") {
     }
     return data;
 }
+/** Load and normalize config for use by detection/run (always has openapi, docsite, etc.) */
+function loadNormalizedConfig(configPath = "docdrift.yaml") {
+    const config = loadConfig(configPath);
+    return (0, normalize_1.normalizeConfig)(config);
+}

package/dist/src/config/normalize.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.normalizeConfig = normalizeConfig;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Produce a normalized config that the rest of the app consumes.
+ * Derives specProviders/openapi/docsite from openapi block or docAreas when not using v2 specProviders.
+ */
+function normalizeConfig(config) {
+    let specProviders;
+    let openapi;
+    let docsite;
+    let exclude = config.exclude ?? [];
+    let requireHumanReview = config.requireHumanReview ?? [];
+    let docAreas = config.docAreas ?? [];
+    const allowConceptualOnlyRun = config.allowConceptualOnlyRun ?? false;
+    const inferMode = config.inferMode ?? true;
+    if (config.specProviders && config.specProviders.length >= 1) {
+        specProviders = config.specProviders;
+        const firstOpenApi3 = specProviders.find((p) => p.format === "openapi3");
+        if (firstOpenApi3 && firstOpenApi3.current.type === "export") {
+            openapi = {
+                export: firstOpenApi3.current.command,
+                generated: firstOpenApi3.current.outputPath,
+                published: firstOpenApi3.published,
+            };
+        }
+        else {
+            openapi = {
+                export: "echo",
+                generated: "",
+                published: specProviders[0].published,
+            };
+        }
+        const allPaths = specProviders.flatMap((p) => [p.published]);
+        const roots = new Set();
+        for (const p of allPaths) {
+            const parts = p.split("/").filter(Boolean);
+            if (parts.length >= 2)
+                roots.add(parts[0] + "/" + parts[1]);
+            else if (parts.length === 1)
+                roots.add(parts[0]);
+        }
+        docsite = roots.size > 0 ? [...roots] : config.docsite ? (Array.isArray(config.docsite) ? config.docsite : [config.docsite]) : ["."];
+    }
+    else if (config.openapi && config.docsite) {
+        specProviders = [
+            {
+                format: "openapi3",
+                current: { type: "export", command: config.openapi.export, outputPath: config.openapi.generated },
+                published: config.openapi.published,
+            },
+        ];
+        openapi = config.openapi;
+        docsite = Array.isArray(config.docsite) ? config.docsite : [config.docsite];
+        if (config.pathMappings?.length) {
+            const pathImpacts = new Set();
+            config.pathMappings.forEach((p) => p.impacts.forEach((i) => pathImpacts.add(i)));
+            requireHumanReview = [...new Set([...requireHumanReview, ...pathImpacts])];
+            docAreas = [
+                ...docAreas,
+                {
+                    name: "pathMappings",
+                    mode: "conceptual",
+                    owners: { reviewers: ["docdrift"] },
+                    detect: { paths: config.pathMappings },
+                    patch: { requireHumanConfirmation: true },
+                },
+            ];
+        }
+    }
+    else if (config.docAreas && config.docAreas.length > 0) {
+        const firstOpenApiArea = config.docAreas.find((a) => a.detect.openapi);
+        if (!firstOpenApiArea?.detect.openapi) {
+            throw new Error("Legacy config requires at least one docArea with detect.openapi");
+        }
+        const o = firstOpenApiArea.detect.openapi;
+        specProviders = [
+            {
+                format: "openapi3",
+                current: { type: "export", command: o.exportCmd, outputPath: o.generatedPath },
+                published: o.publishedPath,
+            },
+        ];
+        openapi = {
+            export: o.exportCmd,
+            generated: o.generatedPath,
+            published: o.publishedPath,
+        };
+        const allPaths = [o.publishedPath];
+        for (const area of config.docAreas) {
+            area.patch.targets?.forEach((t) => allPaths.push(t));
+            area.detect.paths?.forEach((p) => p.impacts.forEach((i) => allPaths.push(i)));
+        }
+        const roots = new Set();
+        for (const p of allPaths) {
+            const parts = p.split("/").filter(Boolean);
+            if (parts.length >= 2)
+                roots.add(parts[0] + "/" + parts[1]);
+            else if (parts.length === 1)
+                roots.add(parts[0]);
+        }
+        docsite = roots.size > 0 ? [...roots] : [node_path_1.default.dirname(o.publishedPath) || "."];
+        const reviewPaths = new Set();
+        for (const area of config.docAreas) {
+            if (area.patch.requireHumanConfirmation || area.mode === "conceptual") {
+                area.patch.targets?.forEach((t) => reviewPaths.add(t));
+                area.detect.paths?.forEach((p) => p.impacts.forEach((i) => reviewPaths.add(i)));
+            }
+        }
+        requireHumanReview = [...reviewPaths];
+    }
+    else if (config.version === 2 && config.pathMappings?.length) {
+        specProviders = [];
+        openapi = { export: "echo", generated: "", published: "" };
+        const pathImpacts = new Set();
+        config.pathMappings.forEach((p) => p.impacts.forEach((i) => pathImpacts.add(i)));
+        requireHumanReview = [...new Set([...requireHumanReview, ...pathImpacts])];
+        docAreas = [
+            {
+                name: "pathMappings",
+                mode: "conceptual",
+                owners: { reviewers: ["docdrift"] },
+                detect: { paths: config.pathMappings },
+                patch: { requireHumanConfirmation: true },
+            },
+        ];
+        const roots = new Set();
+        for (const p of pathImpacts) {
+            const parts = p.split("/").filter(Boolean);
+            if (parts.length >= 2)
+                roots.add(parts[0] + "/" + parts[1]);
+            else if (parts.length === 1)
+                roots.add(parts[0]);
+        }
+        docsite = roots.size > 0 ? [...roots] : config.docsite ? (Array.isArray(config.docsite) ? config.docsite : [config.docsite]) : ["."];
+    }
+    else {
+        throw new Error("Config must include specProviders, (openapi + docsite), or docAreas");
+    }
+    return {
+        ...config,
+        specProviders,
+        openapi,
+        docsite,
+        exclude,
+        requireHumanReview,
+        docAreas,
+        allowConceptualOnlyRun,
+        inferMode,
+    };
+}

package/dist/src/config/schema.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.docDriftConfigSchema = void 0;
+exports.docDriftConfigSchema = exports.docDriftConfigBaseSchema = exports.docAreaBaseSchema = exports.specProviderConfigSchema = exports.openApiSimpleSchema = exports.pathRuleSchema = void 0;
 const zod_1 = require("zod");
-const pathRuleSchema = zod_1.z.object({
+/** Path rule: when `match` changes, `impacts` may need updates. Used by docAreas and by simple `paths` block. */
+exports.pathRuleSchema = zod_1.z.object({
     match: zod_1.z.string().min(1),
     impacts: zod_1.z.array(zod_1.z.string().min(1)).min(1),
 });
@@ -11,18 +12,53 @@ const openApiDetectSchema = zod_1.z.object({
     generatedPath: zod_1.z.string().min(1),
     publishedPath: zod_1.z.string().min(1),
 });
+/** Simple config: short field names for openapi block */
+exports.openApiSimpleSchema = zod_1.z.object({
+    export: zod_1.z.string().min(1),
+    generated: zod_1.z.string().min(1),
+    published: zod_1.z.string().min(1),
+});
+/** Spec source: URL, local path, or export command */
+const specSourceSchema = zod_1.z.discriminatedUnion("type", [
+    zod_1.z.object({ type: zod_1.z.literal("url"), url: zod_1.z.string().url() }),
+    zod_1.z.object({ type: zod_1.z.literal("local"), path: zod_1.z.string().min(1) }),
+    zod_1.z.object({
+        type: zod_1.z.literal("export"),
+        command: zod_1.z.string().min(1),
+        outputPath: zod_1.z.string().min(1),
+    }),
+]);
+const specFormatSchema = zod_1.z.enum(["openapi3", "swagger2", "graphql", "fern", "postman"]);
+/** Single spec provider (v2 config) */
+exports.specProviderConfigSchema = zod_1.z.object({
+    format: specFormatSchema,
+    current: specSourceSchema,
+    published: zod_1.z.string().min(1),
+});
+const docAreaDetectBaseSchema = zod_1.z.object({
+    openapi: openApiDetectSchema.optional(),
+    paths: zod_1.z.array(exports.pathRuleSchema).optional(),
+});
+/** Base schema without refine — for JSON Schema generation (zod-to-json-schema doesn't handle .refine()) */
+exports.docAreaBaseSchema = zod_1.z.object({
+    name: zod_1.z.string().min(1),
+    mode: zod_1.z.enum(["autogen", "conceptual"]),
+    owners: zod_1.z.object({
+        reviewers: zod_1.z.array(zod_1.z.string().min(1)).min(1),
+    }),
+    detect: docAreaDetectBaseSchema,
+    patch: zod_1.z.object({
+        targets: zod_1.z.array(zod_1.z.string().min(1)).optional(),
+        requireHumanConfirmation: zod_1.z.boolean().optional().default(false),
+    }),
+});
 const docAreaSchema = zod_1.z.object({
     name: zod_1.z.string().min(1),
     mode: zod_1.z.enum(["autogen", "conceptual"]),
     owners: zod_1.z.object({
         reviewers: zod_1.z.array(zod_1.z.string().min(1)).min(1),
     }),
-    detect: zod_1.z
-        .object({
-        openapi: openApiDetectSchema.optional(),
-        paths: zod_1.z.array(pathRuleSchema).optional(),
-    })
-        .refine((v) => Boolean(v.openapi) || Boolean(v.paths?.length), {
+    detect: docAreaDetectBaseSchema.refine((v) => Boolean(v.openapi) || Boolean(v.paths?.length), {
         message: "docArea.detect must include openapi or paths",
     }),
     patch: zod_1.z.object({
@@ -30,8 +66,61 @@ const docAreaSchema = zod_1.z.object({
         requireHumanConfirmation: zod_1.z.boolean().optional().default(false),
     }),
 });
-exports.docDriftConfigSchema = zod_1.z.object({
-    version: zod_1.z.literal(1),
+const policySchema = zod_1.z.object({
+    prCaps: zod_1.z.object({
+        maxPrsPerDay: zod_1.z.number().int().positive().default(1),
+        maxFilesTouched: zod_1.z.number().int().positive().default(12),
+    }),
+    confidence: zod_1.z.object({
+        autopatchThreshold: zod_1.z.number().min(0).max(1).default(0.8),
+    }),
+    allowlist: zod_1.z.array(zod_1.z.string().min(1)).min(1),
+    verification: zod_1.z.object({
+        commands: zod_1.z.array(zod_1.z.string().min(1)).min(1),
+    }),
+    /** Days before opening SLA issue for unmerged doc-drift PRs. 0 = disabled. */
+    slaDays: zod_1.z.number().int().min(0).optional().default(7),
+    /** Label to identify doc-drift PRs for SLA check (only these PRs count). */
+    slaLabel: zod_1.z.string().min(1).optional().default("docdrift"),
+    /**
+     * If false (default): Devin may only edit existing files. No new articles, no new folders.
+     * If true: Devin may add new articles, create folders, change information architecture.
+     * Gives teams control to prevent doc sprawl; mainly applies to conceptual/guides.
+     */
+    allowNewFiles: zod_1.z.boolean().optional().default(false),
+});
+/** Base schema without refine — for JSON Schema generation (zod-to-json-schema doesn't handle .refine()) */
+exports.docDriftConfigBaseSchema = zod_1.z.object({
+    version: zod_1.z.union([zod_1.z.literal(1), zod_1.z.literal(2)]),
+    specProviders: zod_1.z.array(exports.specProviderConfigSchema).optional(),
+    openapi: exports.openApiSimpleSchema.optional(),
+    docsite: zod_1.z.union([zod_1.z.string().min(1), zod_1.z.array(zod_1.z.string().min(1))]).optional(),
+    exclude: zod_1.z.array(zod_1.z.string().min(1)).optional().default([]),
+    requireHumanReview: zod_1.z.array(zod_1.z.string().min(1)).optional().default([]),
+    pathMappings: zod_1.z.array(exports.pathRuleSchema).optional().default([]),
+    allowConceptualOnlyRun: zod_1.z.boolean().optional().default(false),
+    inferMode: zod_1.z.boolean().optional().default(true),
+    devin: zod_1.z.object({
+        apiVersion: zod_1.z.literal("v1"),
+        unlisted: zod_1.z.boolean().default(true),
+        maxAcuLimit: zod_1.z.number().int().positive().default(2),
+        tags: zod_1.z.array(zod_1.z.string().min(1)).default(["docdrift"]),
+        customInstructions: zod_1.z.array(zod_1.z.string().min(1)).optional(),
+        customInstructionContent: zod_1.z.string().optional(),
+    }),
+    policy: policySchema,
+    docAreas: zod_1.z.array(exports.docAreaBaseSchema).optional().default([]),
+});
+const docDriftConfigObjectSchema = zod_1.z.object({
+    version: zod_1.z.union([zod_1.z.literal(1), zod_1.z.literal(2)]),
+    specProviders: zod_1.z.array(exports.specProviderConfigSchema).optional(),
+    openapi: exports.openApiSimpleSchema.optional(),
+    docsite: zod_1.z.union([zod_1.z.string().min(1), zod_1.z.array(zod_1.z.string().min(1))]).optional(),
+    exclude: zod_1.z.array(zod_1.z.string().min(1)).optional().default([]),
+    requireHumanReview: zod_1.z.array(zod_1.z.string().min(1)).optional().default([]),
+    pathMappings: zod_1.z.array(exports.pathRuleSchema).optional().default([]),
+    allowConceptualOnlyRun: zod_1.z.boolean().optional().default(false),
+    inferMode: zod_1.z.boolean().optional().default(true),
     devin: zod_1.z.object({
         apiVersion: zod_1.z.literal("v1"),
         unlisted: zod_1.z.boolean().default(true),
@@ -40,18 +129,17 @@ exports.docDriftConfigSchema = zod_1.z.object({
         customInstructions: zod_1.z.array(zod_1.z.string().min(1)).optional(),
         customInstructionContent: zod_1.z.string().optional(),
     }),
-    policy: zod_1.z.object({
-        prCaps: zod_1.z.object({
-            maxPrsPerDay: zod_1.z.number().int().positive().default(1),
-            maxFilesTouched: zod_1.z.number().int().positive().default(12),
-        }),
-        confidence: zod_1.z.object({
-            autopatchThreshold: zod_1.z.number().min(0).max(1).default(0.8),
-        }),
-        allowlist: zod_1.z.array(zod_1.z.string().min(1)).min(1),
-        verification: zod_1.z.object({
-            commands: zod_1.z.array(zod_1.z.string().min(1)).min(1),
-        }),
-    }),
-    docAreas: zod_1.z.array(docAreaSchema).min(1),
+    policy: policySchema,
+    docAreas: zod_1.z.array(docAreaSchema).optional().default([]),
 });
+exports.docDriftConfigSchema = docDriftConfigObjectSchema.refine((v) => {
+    if (v.specProviders && v.specProviders.length >= 1)
+        return true;
+    if (v.openapi && v.docsite)
+        return true;
+    if (v.docAreas.length >= 1)
+        return true;
+    if (v.version === 2 && (v.pathMappings?.length ?? 0) >= 1)
+        return true;
+    return false;
+}, { message: "Config must include specProviders, (openapi + docsite), docAreas, or (v2 + pathMappings)" });

package/dist/src/config/validate.js

@@ -11,12 +11,15 @@ async function validateRuntimeConfig(config) {
     if (config.policy.prCaps.maxFilesTouched < 1) {
         errors.push("policy.prCaps.maxFilesTouched must be >= 1");
     }
-    const commandSet = new Set([
+    const exportCommands = [
         ...config.policy.verification.commands,
-        ...config.docAreas
-            .map((area) => area.detect.openapi?.exportCmd)
-            .filter((value) => Boolean(value)),
-    ]);
+        ...(config.openapi ? [config.openapi.export] : []),
+        ...(config.docAreas ?? []).map((area) => area.detect.openapi?.exportCmd).filter((value) => Boolean(value)),
+        ...(config.specProviders ?? [])
+            .filter((p) => p.current.type === "export")
+            .map((p) => p.current.command),
+    ];
+    const commandSet = new Set(exportCommands);
     for (const command of commandSet) {
         const binary = commandBinary(command);
         const result = await (0, exec_1.execCommand)(`command -v ${binary}`);
@@ -24,7 +27,7 @@ async function validateRuntimeConfig(config) {
             errors.push(`Command not found for '${command}' (binary: ${binary})`);
         }
     }
-    for (const area of config.docAreas) {
+    for (const area of config.docAreas ?? []) {
         if (area.mode === "autogen" && !area.patch.targets?.length) {
             warnings.push(`docArea '${area.name}' is autogen but has no patch.targets`);
         }