@h-rig/docs-drift-plugin 0.0.6-alpha.156

package/dist/src/plugin.js

@@ -0,0 +1,665 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// packages/docs-drift-plugin/src/drift/metadata.ts
+import { Schema } from "effect";
+import { StageMutation as StageMutationSchema } from "@rig/contracts";
+var DOCS_DRIFT_VALIDATOR_ID = "std:docs-drift", DOCS_DRIFT_CLI_ID = "std:drift", DOCS_DRIFT_STAGE_ID = "docs-drift", DOCS_DRIFT_CAPABILITY_ID = "std:docs-drift-capability", DOCS_DRIFT_VALIDATOR, DOCS_DRIFT_STAGE_MUTATION, DOCS_DRIFT_CLI_COMMAND = "rig drift [--docs <csv>] [--ignore <csv>] [--fail-on-drift] [--json]";
+var init_metadata = __esm(() => {
+  DOCS_DRIFT_VALIDATOR = {
+    id: DOCS_DRIFT_VALIDATOR_ID,
+    category: "regression",
+    description: "Detect documentation references that drifted from the source tree."
+  };
+  DOCS_DRIFT_STAGE_MUTATION = Schema.decodeUnknownSync(StageMutationSchema)({
+    op: "insert",
+    stage: {
+      id: DOCS_DRIFT_STAGE_ID,
+      kind: "gate",
+      before: ["merge-gate"],
+      after: ["open-pr"],
+      priority: 0,
+      protected: false
+    },
+    contributedBy: DOCS_DRIFT_STAGE_ID
+  });
+});
+
+// packages/docs-drift-plugin/src/drift/extract-refs.ts
+function stripFenceLines(markdown) {
+  const lines = markdown.split(/\r?\n/);
+  let fenced = false;
+  return lines.map((line) => {
+    if (/^\s*(```|~~~)/.test(line)) {
+      fenced = !fenced;
+      return "";
+    }
+    return fenced ? "" : line;
+  });
+}
+function normalizeToken(raw) {
+  return raw.trim().replace(/^['"]|['"]$/g, "").replace(/[),.;:]+$/g, "").replace(/#L\d+(?:-L\d+)?$/i, "");
+}
+function classifyReference(raw) {
+  if (raw.startsWith("@"))
+    return null;
+  if (PATH_REF.test(raw))
+    return "path";
+  if (SYMBOL_REF.test(raw))
+    return "symbol";
+  return null;
+}
+function pushReference(refs, seen, raw, line) {
+  const value = normalizeToken(raw);
+  if (!value)
+    return;
+  const kind = classifyReference(value);
+  if (!kind)
+    return;
+  const key = `${kind}:${value}:${line}`;
+  if (seen.has(key))
+    return;
+  seen.add(key);
+  refs.push({ kind, value, line });
+}
+function extractDriftReferences(markdown) {
+  const refs = [];
+  const seen = new Set;
+  const lines = stripFenceLines(markdown);
+  for (const [index, line] of lines.entries()) {
+    const lineNumber = index + 1;
+    for (const match of line.matchAll(INLINE_CODE)) {
+      pushReference(refs, seen, match[1] ?? "", lineNumber);
+    }
+    for (const match of line.matchAll(MARKDOWN_LINK)) {
+      pushReference(refs, seen, match[1] ?? "", lineNumber);
+    }
+  }
+  return refs;
+}
+var INLINE_CODE, MARKDOWN_LINK, SYMBOL_REF, PATH_REF;
+var init_extract_refs = __esm(() => {
+  INLINE_CODE = /`([^`\n]+)`/g;
+  MARKDOWN_LINK = /\[[^\]]+\]\(([^)\s]+)\)/g;
+  SYMBOL_REF = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)?$/;
+  PATH_REF = /^(?:\.\.?\/)?(?:[A-Za-z0-9_.-]+\/)+[A-Za-z0-9_.-]+$|^[A-Za-z0-9_.-]+\.(?:ts|tsx|js|jsx|mjs|cjs|json|md|mdx|css|scss|html|yml|yaml|toml|rs|go|py|rb|java|kt|swift|c|cc|cpp|h|hpp)$/;
+});
+
+// packages/docs-drift-plugin/src/drift/git-adapter.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+function processError(value) {
+  return value && typeof value === "object" ? value : null;
+}
+function lineCount(output) {
+  const trimmed = output.trim();
+  return trimmed ? trimmed.split(/\r?\n/).length : 0;
+}
+function makeDriftGit(projectRoot) {
+  async function git(args) {
+    const result = await execFileAsync("git", [...args], {
+      cwd: projectRoot,
+      encoding: "utf8",
+      maxBuffer: 10 * 1024 * 1024
+    });
+    return String(result.stdout);
+  }
+  async function grepCountAt(symbolOrPath, commit) {
+    try {
+      return lineCount(await git(["grep", "-F", "-n", "-e", symbolOrPath, commit, "--"]));
+    } catch (error) {
+      const detail = processError(error);
+      if (detail?.code === 1)
+        return 0;
+      throw error;
+    }
+  }
+  return {
+    async lastCommitTouching(path) {
+      const commit = (await git(["log", "-n", "1", "--format=%H", "--", path])).trim();
+      return commit || "HEAD";
+    },
+    async grepCount(symbolOrPath) {
+      return grepCountAt(symbolOrPath, "HEAD");
+    },
+    async grepCountAtCommit(symbolOrPath, commit) {
+      return grepCountAt(symbolOrPath, commit);
+    },
+    async wasRenamed(symbolOrPath, sinceCommit) {
+      if (!symbolOrPath.includes("/") && !symbolOrPath.includes("."))
+        return false;
+      try {
+        const output = await git(["log", "--name-status", "--format=", `${sinceCommit}..HEAD`]);
+        return output.split(/\r?\n/).some((line) => {
+          const match = line.match(/^R\d*\s+(.+?)\s+(.+)$/);
+          return Boolean(match && (match[1] === symbolOrPath || match[2] === symbolOrPath));
+        });
+      } catch (error) {
+        const detail = processError(error);
+        if (detail?.code === 128)
+          return false;
+        throw error;
+      }
+    }
+  };
+}
+var execFileAsync;
+var init_git_adapter = __esm(() => {
+  execFileAsync = promisify(execFile);
+});
+
+// packages/docs-drift-plugin/src/drift/detect.ts
+var exports_detect = {};
+__export(exports_detect, {
+  detectStaleAnchors: () => detectStaleAnchors,
+  detectDrift: () => detectDrift,
+  detectDeletedReferences: () => detectDeletedReferences
+});
+import { existsSync } from "fs";
+import { readdir, readFile, stat } from "fs/promises";
+import { basename, extname, relative, resolve } from "path";
+function globLikeMatch(path, pattern) {
+  if (pattern === path)
+    return true;
+  if (pattern.startsWith("**/*"))
+    return path.endsWith(pattern.slice(4));
+  if (pattern.endsWith("/**"))
+    return path.startsWith(pattern.slice(0, -3));
+  if (pattern.includes("*")) {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    return new RegExp(`^${escaped}$`).test(path);
+  }
+  return path.startsWith(pattern);
+}
+function isDefaultDoc(path) {
+  const lower = basename(path).toLowerCase();
+  return (path.endsWith(".md") || path.endsWith(".mdx")) && !lower.startsWith("changelog") && !lower.includes("generated");
+}
+function isIgnored(path, patterns) {
+  return (patterns ?? []).some((pattern) => globLikeMatch(path, pattern));
+}
+async function collectFiles(root, options) {
+  const files = [];
+  async function visit(dir) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      if (entry.isDirectory() && DEFAULT_IGNORED_DIRS[entry.name])
+        continue;
+      const absolute = resolve(dir, entry.name);
+      const rel = relative(root, absolute).replace(/\\/g, "/");
+      if (isIgnored(rel, options.ignore))
+        continue;
+      if (entry.isDirectory()) {
+        await visit(absolute);
+        continue;
+      }
+      if (!entry.isFile())
+        continue;
+      if (options.docs) {
+        const matchesConfigured = options.patterns && options.patterns.length > 0 ? options.patterns.some((pattern) => globLikeMatch(rel, pattern)) : isDefaultDoc(rel);
+        if (matchesConfigured)
+          files.push(rel);
+        continue;
+      }
+      if (SOURCE_EXTENSIONS[extname(entry.name)])
+        files.push(rel);
+    }
+  }
+  await visit(root);
+  return files.sort();
+}
+async function sourceReferenceCount(projectRoot, reference, docPath) {
+  if (reference.kind === "path")
+    return existsSync(resolve(projectRoot, reference.value)) ? 1 : 0;
+  let count = 0;
+  const sourceFiles = await collectFiles(projectRoot, { docs: false });
+  for (const sourceFile of sourceFiles) {
+    if (sourceFile === docPath)
+      continue;
+    const text = await readFile(resolve(projectRoot, sourceFile), "utf8").catch(() => "");
+    if (text.includes(reference.value))
+      count += 1;
+  }
+  return count;
+}
+function deletedReferenceFinding(docPath, reference) {
+  return {
+    kind: "deleted-reference",
+    docPath,
+    line: reference.line,
+    reference: reference.value,
+    detail: `Documented reference "${reference.value}" no longer exists in the source tree.`,
+    confidence: "high"
+  };
+}
+function staleAnchorFinding(docPath, reference) {
+  return {
+    kind: "stale-anchor",
+    docPath,
+    line: reference.line,
+    reference: reference.value,
+    detail: `Documented path "${reference.value}" changed after this doc was last updated.`,
+    confidence: "medium"
+  };
+}
+async function detectDeletedReferences(projectRoot, docPath, git = makeDriftGit(projectRoot)) {
+  const markdown = await readFile(resolve(projectRoot, docPath), "utf8");
+  const docCommit = await git.lastCommitTouching(docPath);
+  const findings = [];
+  for (const reference of extractDriftReferences(markdown)) {
+    if (await sourceReferenceCount(projectRoot, reference, docPath) > 0)
+      continue;
+    if (await git.wasRenamed(reference.value, docCommit))
+      continue;
+    findings.push(deletedReferenceFinding(docPath, reference));
+  }
+  return findings;
+}
+async function detectStaleAnchors(projectRoot, docPath, git = makeDriftGit(projectRoot)) {
+  const markdown = await readFile(resolve(projectRoot, docPath), "utf8");
+  const docCommit = await git.lastCommitTouching(docPath);
+  const findings = [];
+  for (const reference of extractDriftReferences(markdown).filter((ref) => ref.kind === "path")) {
+    if (!existsSync(resolve(projectRoot, reference.value)))
+      continue;
+    const sourceStat = await stat(resolve(projectRoot, reference.value)).catch(() => null);
+    if (!sourceStat?.isFile())
+      continue;
+    const sourceCommit = await git.lastCommitTouching(reference.value);
+    if (sourceCommit !== docCommit && !await git.wasRenamed(reference.value, docCommit)) {
+      findings.push(staleAnchorFinding(docPath, reference));
+    }
+  }
+  return findings;
+}
+async function detectDrift(options) {
+  const git = options.git ?? makeDriftGit(options.projectRoot);
+  const docs = await collectFiles(options.projectRoot, {
+    docs: true,
+    ...options.docsGlobs !== undefined ? { patterns: options.docsGlobs } : {},
+    ...options.ignoreGlobs !== undefined ? { ignore: options.ignoreGlobs } : {}
+  });
+  const findings = [];
+  let degraded = false;
+  for (const docPath of docs) {
+    try {
+      findings.push(...await detectDeletedReferences(options.projectRoot, docPath, git));
+      findings.push(...await detectStaleAnchors(options.projectRoot, docPath, git));
+    } catch {
+      degraded = true;
+    }
+  }
+  return {
+    generatedAt: new Date().toISOString(),
+    scanned: docs.length,
+    degraded,
+    findings
+  };
+}
+var DEFAULT_IGNORED_DIRS, SOURCE_EXTENSIONS;
+var init_detect = __esm(() => {
+  init_extract_refs();
+  init_git_adapter();
+  DEFAULT_IGNORED_DIRS = {
+    ".git": true,
+    node_modules: true,
+    dist: true,
+    build: true,
+    coverage: true,
+    ".next": true,
+    vendor: true
+  };
+  SOURCE_EXTENSIONS = {
+    ".ts": true,
+    ".tsx": true,
+    ".js": true,
+    ".jsx": true,
+    ".mjs": true,
+    ".cjs": true,
+    ".rs": true,
+    ".go": true,
+    ".py": true,
+    ".rb": true,
+    ".java": true,
+    ".kt": true,
+    ".swift": true,
+    ".c": true,
+    ".cc": true,
+    ".cpp": true,
+    ".h": true,
+    ".hpp": true,
+    ".json": true,
+    ".toml": true,
+    ".yml": true,
+    ".yaml": true
+  };
+});
+
+// packages/docs-drift-plugin/src/drift/plugin.ts
+var exports_plugin = {};
+__export(exports_plugin, {
+  runDriftCli: () => runDriftCli,
+  runDocsDriftValidation: () => runDocsDriftValidation,
+  highConfidenceDriftFindings: () => highConfidenceDriftFindings,
+  executeDrift: () => executeDrift,
+  driftGateResult: () => driftGateResult,
+  createDocsDriftValidator: () => createDocsDriftValidator,
+  createDocsDriftRuntimeCliCommand: () => createDocsDriftRuntimeCliCommand,
+  createDocsDriftGateStage: () => createDocsDriftGateStage,
+  DOCS_DRIFT_VALIDATOR_ID: () => DOCS_DRIFT_VALIDATOR_ID,
+  DOCS_DRIFT_VALIDATOR: () => DOCS_DRIFT_VALIDATOR,
+  DOCS_DRIFT_STAGE_MUTATION: () => DOCS_DRIFT_STAGE_MUTATION,
+  DOCS_DRIFT_STAGE_ID: () => DOCS_DRIFT_STAGE_ID,
+  DOCS_DRIFT_RUNTIME_CLI_COMMAND: () => DOCS_DRIFT_RUNTIME_CLI_COMMAND,
+  DOCS_DRIFT_CLI_ID: () => DOCS_DRIFT_CLI_ID,
+  DOCS_DRIFT_CLI_COMMAND: () => DOCS_DRIFT_CLI_COMMAND,
+  DOCS_DRIFT_CAPABILITY_ID: () => DOCS_DRIFT_CAPABILITY_ID
+});
+function highConfidenceDriftFindings(report) {
+  return report.findings.filter((finding) => finding.confidence === "high");
+}
+function driftGateResult(report, mode = "enforce") {
+  const high = highConfidenceDriftFindings(report);
+  if (mode === "enforce" && high.length > 0) {
+    return { kind: "block", reason: `${high.length} high-confidence documentation drift finding(s).` };
+  }
+  return { kind: "allow" };
+}
+function createDocsDriftGateStage(options = {}) {
+  return async (ctx) => {
+    const projectRoot = typeof ctx.metadata?.projectRoot === "string" ? ctx.metadata.projectRoot : process.cwd();
+    const report = await detectDrift({
+      projectRoot,
+      ...options.docsGlobs !== undefined ? { docsGlobs: options.docsGlobs } : {},
+      ...options.ignoreGlobs !== undefined ? { ignoreGlobs: options.ignoreGlobs } : {}
+    });
+    return driftGateResult(report, options.failOnDrift ? "enforce" : "observe");
+  };
+}
+async function runDocsDriftValidation(options) {
+  const report = await detectDrift(options);
+  const high = highConfidenceDriftFindings(report);
+  const passed = options.failOnDrift ? high.length === 0 : true;
+  const findingWord = report.findings.length === 1 ? "finding" : "findings";
+  return {
+    id: DOCS_DRIFT_VALIDATOR_ID,
+    passed,
+    summary: `docs drift scanned ${report.scanned} doc(s), ${report.findings.length} ${findingWord}`,
+    details: JSON.stringify(report)
+  };
+}
+function createDocsDriftValidator(options = {}) {
+  return {
+    ...DOCS_DRIFT_VALIDATOR,
+    async run(ctx) {
+      return runDocsDriftValidation({
+        projectRoot: ctx.workspaceRoot,
+        ...options.docsGlobs !== undefined ? { docsGlobs: options.docsGlobs } : {},
+        ...options.ignoreGlobs !== undefined ? { ignoreGlobs: options.ignoreGlobs } : {},
+        ...options.failOnDrift !== undefined ? { failOnDrift: options.failOnDrift } : {}
+      });
+    }
+  };
+}
+function takeOptionValue(args, index, flag) {
+  const value = args[index + 1];
+  if (!value)
+    throw new Error(`${flag} requires a value`);
+  return value;
+}
+function takeFlag(args, flag) {
+  const rest = [...args];
+  const index = rest.indexOf(flag);
+  if (index < 0)
+    return { value: false, rest };
+  rest.splice(index, 1);
+  return { value: true, rest };
+}
+function takeOption(args, flag) {
+  const rest = [...args];
+  const index = rest.indexOf(flag);
+  if (index < 0)
+    return { rest };
+  const value = rest[index + 1];
+  if (!value || value.startsWith("-"))
+    throw new Error(`${flag} requires a value.`);
+  rest.splice(index, 2);
+  return { value, rest };
+}
+function requireNoExtraArgs(args, usage) {
+  if (args.length > 0)
+    throw new Error(`Unexpected argument: ${args[0]}
+Usage: ${usage}`);
+}
+function parseCsv(value) {
+  return value?.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0) ?? [];
+}
+function driftSummary(report) {
+  const highConfidence = highConfidenceDriftFindings(report).length;
+  return { total: report.findings.length, highConfidence, degraded: report.degraded };
+}
+async function executeDrift(context, args, options = {}) {
+  const json = takeFlag(args, "--json");
+  const docs = takeOption(json.rest, "--docs");
+  const ignore = takeOption(docs.rest, "--ignore");
+  const failOnDrift = takeFlag(ignore.rest, "--fail-on-drift");
+  requireNoExtraArgs(failOnDrift.rest, "rig drift [--docs <csv>] [--ignore <csv>] [--fail-on-drift] [--json]");
+  const docsGlobs = parseCsv(docs.value);
+  const ignoreGlobs = parseCsv(ignore.value);
+  const effectiveDocsGlobs = docsGlobs.length > 0 ? docsGlobs : options.docsGlobs;
+  const effectiveIgnoreGlobs = ignoreGlobs.length > 0 ? ignoreGlobs : options.ignoreGlobs;
+  const effectiveFailOnDrift = failOnDrift.value || options.failOnDrift === true;
+  const report = await detectDrift({
+    projectRoot: context.projectRoot,
+    ...effectiveDocsGlobs !== undefined ? { docsGlobs: effectiveDocsGlobs } : {},
+    ...effectiveIgnoreGlobs !== undefined ? { ignoreGlobs: effectiveIgnoreGlobs } : {}
+  });
+  const failed = effectiveFailOnDrift && highConfidenceDriftFindings(report).length > 0;
+  const details = { report, summary: driftSummary(report), failOnDrift: effectiveFailOnDrift, failed };
+  if (context.outputMode === "text") {
+    if (json.value)
+      console.log(JSON.stringify(details, null, 2));
+    else
+      console.log(report.findings.length === 0 ? `No drift findings across ${report.scanned} documents.` : report.findings.map((finding) => `${finding.docPath}:${finding.line ?? "?"}	${finding.kind}	${finding.confidence}	${finding.detail}`).join(`
+`));
+  }
+  return { ok: !failed, group: "drift", command: "scan", details };
+}
+function createDocsDriftRuntimeCliCommand(options = {}) {
+  return {
+    id: DOCS_DRIFT_CLI_ID,
+    family: "drift",
+    command: DOCS_DRIFT_CLI_COMMAND,
+    description: "Scan documentation for stale code references.",
+    usage: DOCS_DRIFT_CLI_COMMAND,
+    projectRequired: true,
+    run: (context, args) => executeDrift(context, args, options)
+  };
+}
+async function runDriftCli(args, options = {}) {
+  const docsGlobs = [];
+  const ignoreGlobs = [];
+  let json = false;
+  let failOnDrift = false;
+  for (let index = 0;index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--json") {
+      json = true;
+      continue;
+    }
+    if (arg === "--fail-on-drift") {
+      failOnDrift = true;
+      continue;
+    }
+    if (arg === "--docs") {
+      docsGlobs.push(takeOptionValue(args, index, arg));
+      index += 1;
+      continue;
+    }
+    if (arg === "--ignore") {
+      ignoreGlobs.push(takeOptionValue(args, index, arg));
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown rig drift argument: ${arg}`);
+  }
+  const report = await detectDrift({
+    projectRoot: options.projectRoot ?? process.cwd(),
+    ...docsGlobs.length > 0 ? { docsGlobs } : {},
+    ...ignoreGlobs.length > 0 ? { ignoreGlobs } : {}
+  });
+  const write = options.write ?? ((message) => console.log(message));
+  if (json) {
+    write(JSON.stringify(report));
+  } else {
+    write(`Scanned ${report.scanned} doc(s); ${report.findings.length} drift finding(s).`);
+    for (const finding of report.findings) {
+      write(`${finding.confidence.toUpperCase()} ${finding.kind} ${finding.docPath}${finding.line ? `:${finding.line}` : ""} ${finding.reference ?? ""} \u2014 ${finding.detail}`);
+    }
+  }
+  const high = highConfidenceDriftFindings(report);
+  if (failOnDrift && high.length > 0) {
+    options.writeError?.(`${high.length} high-confidence drift finding(s).`);
+    return 2;
+  }
+  return 0;
+}
+var DOCS_DRIFT_RUNTIME_CLI_COMMAND;
+var init_plugin = __esm(() => {
+  init_detect();
+  init_metadata();
+  init_metadata();
+  DOCS_DRIFT_RUNTIME_CLI_COMMAND = createDocsDriftRuntimeCliCommand();
+});
+
+// packages/docs-drift-plugin/src/plugin.ts
+init_metadata();
+init_metadata();
+import { definePlugin } from "@rig/core/config";
+var DOCS_HEALTH_PANEL_ID = "docs-health";
+function isRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function panelProjectRoot(context) {
+  return isRecord(context) && typeof context.projectRoot === "string" && context.projectRoot.length > 0 ? context.projectRoot : null;
+}
+function driftFindingPanelId(finding, index) {
+  return `${finding.docPath}:${finding.line ?? index}:${finding.kind}`;
+}
+function createDocsHealthPanelProducer(options = {}) {
+  return async (context) => {
+    const projectRoot = panelProjectRoot(context);
+    if (!projectRoot)
+      return;
+    const { detectDrift: detectDrift2 } = await Promise.resolve().then(() => (init_detect(), exports_detect));
+    const report = await detectDrift2({
+      projectRoot,
+      ...options.docsGlobs !== undefined ? { docsGlobs: options.docsGlobs } : {},
+      ...options.ignoreGlobs !== undefined ? { ignoreGlobs: options.ignoreGlobs } : {}
+    });
+    return {
+      findings: report.findings.map((finding, index) => ({
+        id: driftFindingPanelId(finding, index),
+        docPath: finding.docPath,
+        kind: finding.kind,
+        confidence: finding.confidence,
+        summary: finding.detail,
+        taskId: null
+      })),
+      degraded: report.degraded ? "drift scan degraded" : null
+    };
+  };
+}
+function createLazyDocsDriftValidator(options = {}) {
+  return {
+    ...DOCS_DRIFT_VALIDATOR,
+    async run(ctx) {
+      const { runDocsDriftValidation: runDocsDriftValidation2 } = await Promise.resolve().then(() => (init_plugin(), exports_plugin));
+      return runDocsDriftValidation2({
+        projectRoot: ctx.workspaceRoot,
+        ...options.docsGlobs !== undefined ? { docsGlobs: options.docsGlobs } : {},
+        ...options.ignoreGlobs !== undefined ? { ignoreGlobs: options.ignoreGlobs } : {},
+        ...options.failOnDrift !== undefined ? { failOnDrift: options.failOnDrift } : {}
+      });
+    }
+  };
+}
+function createLazyDocsDriftGateStage(options = {}) {
+  return async (ctx) => {
+    const { createDocsDriftGateStage: createDocsDriftGateStage2 } = await Promise.resolve().then(() => (init_plugin(), exports_plugin));
+    return createDocsDriftGateStage2(options)(ctx);
+  };
+}
+function createLazyDocsDriftRuntimeCliCommand(options = {}) {
+  return {
+    id: DOCS_DRIFT_CLI_ID,
+    family: "drift",
+    command: DOCS_DRIFT_CLI_COMMAND,
+    description: "Scan documentation for stale code references.",
+    usage: DOCS_DRIFT_CLI_COMMAND,
+    projectRequired: true,
+    run: async (context, args) => {
+      const { executeDrift: executeDrift2 } = await Promise.resolve().then(() => (init_plugin(), exports_plugin));
+      return executeDrift2(context, args, options);
+    }
+  };
+}
+function createStandardDocsDriftPlugin(opts = {}) {
+  return definePlugin({
+    name: "@rig/standard-plugin:docs-drift",
+    version: "0.1.0",
+    contributes: {
+      validators: [DOCS_DRIFT_VALIDATOR],
+      capabilities: [
+        { id: DOCS_DRIFT_CAPABILITY_ID, title: "Documentation drift detection", commandId: DOCS_DRIFT_CLI_ID, panelId: DOCS_HEALTH_PANEL_ID }
+      ],
+      panels: [
+        { id: DOCS_HEALTH_PANEL_ID, slot: "capability", title: "Documentation drift", capabilityId: DOCS_DRIFT_CAPABILITY_ID }
+      ],
+      cliCommands: [
+        {
+          id: DOCS_DRIFT_CLI_ID,
+          family: "drift",
+          command: DOCS_DRIFT_CLI_COMMAND,
+          description: "Scan documentation for stale code references.",
+          projectRequired: true
+        }
+      ],
+      stageMutations: [DOCS_DRIFT_STAGE_MUTATION]
+    }
+  }, {
+    validators: [createLazyDocsDriftValidator(opts)],
+    stages: { [DOCS_DRIFT_STAGE_ID]: createLazyDocsDriftGateStage(opts) },
+    featureCapabilities: [
+      { id: DOCS_DRIFT_CAPABILITY_ID, title: "Documentation drift detection", commandId: DOCS_DRIFT_CLI_ID, panelId: DOCS_HEALTH_PANEL_ID }
+    ],
+    panels: [
+      { id: DOCS_HEALTH_PANEL_ID, slot: "capability", title: "Documentation drift", capabilityId: DOCS_DRIFT_CAPABILITY_ID, produce: createDocsHealthPanelProducer(opts) }
+    ],
+    cliCommands: [createLazyDocsDriftRuntimeCliCommand(opts)]
+  });
+}
+export {
+  createStandardDocsDriftPlugin,
+  DOCS_HEALTH_PANEL_ID,
+  DOCS_DRIFT_VALIDATOR_ID,
+  DOCS_DRIFT_VALIDATOR,
+  DOCS_DRIFT_STAGE_MUTATION,
+  DOCS_DRIFT_STAGE_ID,
+  DOCS_DRIFT_CLI_ID,
+  DOCS_DRIFT_CLI_COMMAND,
+  DOCS_DRIFT_CAPABILITY_ID
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@h-rig/docs-drift-plugin",
+  "version": "0.0.6-alpha.156",
+  "type": "module",
+  "description": "First-party documentation drift detection capability plugin for Rig.",
+  "license": "UNLICENSED",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/plugin.d.ts",
+      "import": "./dist/src/plugin.js"
+    },
+    "./plugin": {
+      "types": "./dist/src/plugin.d.ts",
+      "import": "./dist/src/plugin.js"
+    },
+    "./drift/*": {
+      "types": "./dist/src/drift/*.d.ts",
+      "import": "./dist/src/drift/*.js"
+    }
+  },
+  "engines": {
+    "bun": ">=1.3.11"
+  },
+  "dependencies": {
+    "@rig/contracts": "npm:@h-rig/contracts@0.0.6-alpha.156",
+    "@rig/core": "npm:@h-rig/core@0.0.6-alpha.156",
+    "effect": "4.0.0-beta.90"
+  }
+}