docgov-cli 0.2.0

package/core/find.js

@@ -0,0 +1,61 @@
+import { AUTHORITY } from './taxonomy.js';
+import { vectorize, cosine } from './similarity.js';
+
+/**
+ * Authority-aware search (PRD §32).
+ *
+ * The ranking is deliberately not pure relevance: an agent that reads the user
+ * guide before the canonical spec writes confidently wrong code. Authority is a
+ * first-class ranking term.
+ */
+export function find({ docs, query, limit = 10 }) {
+  const q = String(query || '').toLowerCase().trim();
+  if (!q) return [];
+  const terms = q.match(/[a-z][a-z0-9_-]{1,}/g) || [q];
+
+  const pseudo = { id: '__query__', tokens: () => terms };
+  const vecs = vectorize([...docs, pseudo]);
+  const qv = vecs.get('__query__');
+
+  const results = docs.map((d) => {
+    const text = `${d.title}\n${d.path}\n${d.body}`.toLowerCase();
+    let lexical = 0;
+    for (const t of terms) {
+      const hits = text.split(t).length - 1;
+      if (!hits) continue;
+      lexical += Math.min(30, 6 + hits * 2);
+      if ((d.title || '').toLowerCase().includes(t)) lexical += 18;
+      if (d.path.toLowerCase().includes(t)) lexical += 12;
+      if (d.id.toLowerCase().includes(t)) lexical += 14;
+      if ((d.domain || '').toLowerCase() === t) lexical += 25;
+    }
+    if (text.includes(q)) lexical += 25;
+    const semantic = Math.round(cosine(qv, vecs.get(d.id)) * 60);
+    const rank = AUTHORITY[d.authority]?.rank ?? 9;
+    const authorityBonus = Math.max(0, (8 - rank) * 5);
+    const statusPenalty = d.status === 'deprecated' || d.status === 'superseded' ? 30 : 0;
+    return {
+      path: d.path, id: d.id, title: d.title, type: d.type, authority: d.authority,
+      label: AUTHORITY[d.authority]?.label || d.authority, domain: d.domain, status: d.status,
+      score: lexical + semantic + authorityBonus - statusPenalty,
+      snippet: snippet(d.body, terms),
+    };
+  }).filter((r) => r.score > authorityOnly(r));
+
+  return results.sort((a, b) =>
+    (AUTHORITY[a.authority]?.rank ?? 9) - (AUTHORITY[b.authority]?.rank ?? 9) ||
+    b.score - a.score).slice(0, limit);
+}
+
+/** A document must match on content, not merely be authoritative. */
+function authorityOnly(r) { return Math.max(0, (8 - (AUTHORITY[r.authority]?.rank ?? 9)) * 5); }
+
+function snippet(body, terms, width = 160) {
+  const text = body.replace(/```[\s\S]*?```/g, ' ').replace(/\s+/g, ' ');
+  const lower = text.toLowerCase();
+  let at = -1;
+  for (const t of terms) { at = lower.indexOf(t); if (at >= 0) break; }
+  if (at < 0) return text.slice(0, width).trim();
+  const start = Math.max(0, at - 50);
+  return `${start > 0 ? '…' : ''}${text.slice(start, start + width).trim()}…`;
+}

package/core/frontmatter.js

@@ -0,0 +1,65 @@
+import * as yaml from './yaml.js';
+import { DocGovError } from './util.js';
+
+const FENCE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(\r?\n|$)/;
+
+/**
+ * @param {string} source
+ * @returns {{data:object, body:string, raw:string|null, hasFrontmatter:boolean}}
+ */
+export function parse(source) {
+  const m = FENCE.exec(source);
+  if (!m) return { data: {}, body: source, raw: null, hasFrontmatter: false };
+  let data;
+  try { data = yaml.parse(m[1]) || {}; }
+  catch (e) { throw new DocGovError(`invalid frontmatter YAML: ${e.message}`); }
+  if (typeof data !== 'object' || Array.isArray(data)) throw new DocGovError('frontmatter must be a mapping');
+  return { data, body: source.slice(m[0].length), raw: m[1], hasFrontmatter: true };
+}
+
+/** Rewrite (or insert) frontmatter, preserving body byte-for-byte. */
+export function stringify(data, body) {
+  const keys = Object.keys(data || {});
+  if (keys.length === 0) return body;
+  return `---\n${yaml.stringify(data)}---\n${body.startsWith('\n') ? body.slice(1) : body}`;
+}
+
+/** Merge patch into a document's `docgov` block without touching other frontmatter keys. */
+export function patchDocgov(source, patch) {
+  const { data, body } = parse(source);
+  const next = { ...data, docgov: { ...(data.docgov || {}), ...patch } };
+  if (!('docgov' in data)) {
+    // keep docgov first so the governance block is the first thing a reader sees
+    const reordered = { docgov: next.docgov };
+    for (const k of Object.keys(data)) reordered[k] = data[k];
+    return stringify(reordered, body);
+  }
+  return stringify(next, body);
+}
+
+/** First markdown H1, used as a title fallback. */
+export function firstHeading(body) {
+  const m = /^#[ \t]+(.+?)[ \t]*$/m.exec(body);
+  return m ? m[1].trim() : null;
+}
+
+/** Top-level section map: H2 title -> {start,end,lines}. */
+export function sections(body, level = 2) {
+  const prefix = '#'.repeat(level);
+  const lines = body.split('\n');
+  const out = [];
+  let cur = null;
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    if (/^\s*(```|~~~)/.test(l)) inFence = !inFence;
+    if (inFence) continue;
+    const m = new RegExp(`^${prefix}[ \\t]+(.+?)[ \\t]*$`).exec(l);
+    if (m) {
+      if (cur) { cur.end = i; cur.lines = cur.end - cur.start; out.push(cur); }
+      cur = { title: m[1].trim(), start: i, end: lines.length, lines: 0 };
+    }
+  }
+  if (cur) { cur.lines = cur.end - cur.start; out.push(cur); }
+  return out;
+}

package/core/git.js

@@ -0,0 +1,113 @@
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { exists, toPosix } from './util.js';
+
+/** Git is the audit log (PRD §38). DocGov reads it, never replaces it. */
+
+function git(root, args, { allowFail = false } = {}) {
+  try {
+    return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  } catch (e) {
+    if (allowFail) return '';
+    throw new Error(`git ${args.join(' ')} failed: ${String(e.stderr || e.message).trim()}`);
+  }
+}
+
+export function isRepo(root) { return exists(path.join(root, '.git')); }
+
+/**
+ * Is the tree clean enough to migrate?
+ *
+ * DocGov's own state under .docgov/ does not count: `review` writes the plan that
+ * `migrate` then executes, so counting it would make the two commands mutually
+ * exclusive. Everything else must be committed, because that is what makes a
+ * migration revertible.
+ */
+export function isClean(root, { ignore = ['.docgov/'] } = {}) {
+  if (!isRepo(root)) return false;
+  const out = git(root, ['status', '--porcelain'], { allowFail: true });
+  if (out === '') return true;
+  return out.split('\n').filter(Boolean).every((line) => {
+    const p = line.slice(3).replace(/^"|"$/g, '');
+    return ignore.some((prefix) => p.startsWith(prefix));
+  });
+}
+
+/** Paths with uncommitted changes, excluding DocGov's own state. */
+export function dirtyPaths(root, { ignore = ['.docgov/'] } = {}) {
+  if (!isRepo(root)) return [];
+  return git(root, ['status', '--porcelain'], { allowFail: true })
+    .split('\n').filter(Boolean)
+    .map((line) => line.slice(3).replace(/^"|"$/g, ''))
+    .filter((p) => !ignore.some((prefix) => p.startsWith(prefix)));
+}
+
+export function currentBranch(root) {
+  return git(root, ['rev-parse', '--abbrev-ref', 'HEAD'], { allowFail: true }) || 'HEAD';
+}
+
+export function headSha(root) { return git(root, ['rev-parse', 'HEAD'], { allowFail: true }); }
+
+/** @returns {{path:string, status:string, oldPath?:string}[]} */
+export function changedFiles(root, base = 'HEAD') {
+  if (!isRepo(root)) return [];
+  const out = git(root, ['diff', '--name-status', '-M', base], { allowFail: true });
+  const staged = git(root, ['diff', '--name-status', '-M', '--cached', base], { allowFail: true });
+  const untracked = git(root, ['ls-files', '--others', '--exclude-standard'], { allowFail: true });
+  const seen = new Map();
+  for (const block of [out, staged]) {
+    for (const line of block.split('\n').filter(Boolean)) {
+      const parts = line.split('\t');
+      const status = parts[0][0];
+      if (status === 'R') seen.set(toPosix(parts[2]), { path: toPosix(parts[2]), status: 'R', oldPath: toPosix(parts[1]) });
+      else seen.set(toPosix(parts[1]), { path: toPosix(parts[1]), status });
+    }
+  }
+  for (const f of untracked.split('\n').filter(Boolean)) {
+    if (!seen.has(toPosix(f))) seen.set(toPosix(f), { path: toPosix(f), status: 'A' });
+  }
+  return [...seen.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/** Unified diff for one path, used to extract changed values for drift review. */
+export function diffFor(root, relPath, base = 'HEAD') {
+  return git(root, ['diff', '-U2', base, '--', relPath], { allowFail: true });
+}
+
+/** Commits touching a path since `since`. */
+export function commitsSince(root, relPath, since = '90 days ago') {
+  const out = git(root, ['log', `--since=${since}`, '--format=%H%x09%an%x09%ad%x09%s', '--date=short', '--', relPath], { allowFail: true });
+  return out.split('\n').filter(Boolean).map((l) => {
+    const [sha, author, date, subject] = l.split('\t');
+    return { sha, author, date, subject };
+  });
+}
+
+export function lastCommitDate(root, relPath) {
+  const d = git(root, ['log', '-1', '--format=%ad', '--date=short', '--', relPath], { allowFail: true });
+  return d || null;
+}
+
+/** Primary author of a path, as an owner hint for `docgov review`. */
+export function primaryAuthor(root, relPath) {
+  const out = git(root, ['shortlog', '-sne', 'HEAD', '--', relPath], { allowFail: true });
+  const first = out.split('\n').filter(Boolean)[0];
+  if (!first) return null;
+  const m = /^\s*\d+\s+(.+?)\s+<(.+?)>/.exec(first);
+  return m ? { name: m[1], email: m[2] } : null;
+}
+
+export function move(root, from, to) {
+  const dir = path.dirname(path.join(root, to));
+  execFileSync('mkdir', ['-p', dir]);
+  git(root, ['mv', '-f', from, to]);
+}
+
+export function createBranch(root, name) { git(root, ['checkout', '-b', name]); }
+export function checkout(root, ref) { git(root, ['checkout', ref]); }
+export function stashPush(root, msg) { return git(root, ['stash', 'push', '-u', '-m', msg], { allowFail: true }); }
+export function resetHard(root, ref = 'HEAD') { git(root, ['reset', '--hard', ref]); }
+export function add(root, paths) { git(root, ['add', '--', ...paths]); }
+export function commit(root, message) { git(root, ['commit', '-m', message, '--no-verify']); }
+export function revParse(root, ref) { return git(root, ['rev-parse', ref], { allowFail: true }); }
+export function mergeBase(root, a, b) { return git(root, ['merge-base', a, b], { allowFail: true }); }

package/core/graph.js

@@ -0,0 +1,182 @@
+import path from 'node:path';
+import { RELATIONSHIPS, AUTHORITY } from './taxonomy.js';
+import { write, read, exists, matchAny } from './util.js';
+
+export const GRAPH_PATH = '.docgov/graph.json';
+
+/**
+ * The documentation graph (PRD §8). Nodes are documents, contracts and code
+ * path-globs; edges are typed relationships plus their inverses, so impact
+ * analysis can walk in either direction.
+ */
+export class Graph {
+  constructor() {
+    /** @type {Map<string, {id:string,path:string,type:string,authority:string,visibility:string,domain:string|null,kind:string}>} */
+    this.nodes = new Map();
+    /** @type {{from:string,to:string,rel:string,inferred?:boolean}[]} */
+    this.edges = [];
+    this._out = new Map();
+    this._in = new Map();
+  }
+
+  addNode(n) { this.nodes.set(n.id, n); return n; }
+
+  addEdge(from, to, rel, inferred = false) {
+    this.edges.push({ from, to, rel, inferred });
+    (this._out.get(from) ?? this._out.set(from, []).get(from)).push({ to, rel, inferred });
+    (this._in.get(to) ?? this._in.set(to, []).get(to)).push({ from, rel, inferred });
+  }
+
+  out(id, rel) { return (this._out.get(id) || []).filter((e) => !rel || e.rel === rel); }
+  in(id, rel) { return (this._in.get(id) || []).filter((e) => !rel || e.rel === rel); }
+
+  /** Breadth-first closure over chosen edge directions. */
+  reach(startIds, { rels = null, direction = 'out', maxDepth = 4 } = {}) {
+    const seen = new Map();
+    let frontier = [...startIds];
+    for (let depth = 1; depth <= maxDepth && frontier.length; depth++) {
+      const next = [];
+      for (const id of frontier) {
+        const edges = direction === 'out' ? this.out(id) : this.in(id);
+        for (const e of edges) {
+          if (rels && !rels.includes(e.rel)) continue;
+          const target = direction === 'out' ? e.to : e.from;
+          if (seen.has(target) || startIds.includes(target)) continue;
+          seen.set(target, { depth, via: e.rel, from: id });
+          next.push(target);
+        }
+      }
+      frontier = next;
+    }
+    return seen;
+  }
+
+  /**
+   * Documents nothing can reach and which reach nothing (PRD §31).
+   *
+   * Inferred link edges count: a document that links to others is visible to impact
+   * analysis, which is what this rule actually cares about. Only a document with no
+   * edge of any kind is invisible, and invisible means nothing will ever tell anyone
+   * it went stale.
+   */
+  orphans() {
+    return [...this.nodes.values()]
+      .filter((n) => n.kind === 'document' && this.out(n.id).length === 0 && this.in(n.id).length === 0);
+  }
+
+  /** Edges that point at a node the graph does not contain. */
+  dangling() {
+    return this.edges.filter((e) => !this.nodes.has(e.to)).map((e) => ({ ...e, fromPath: this.nodes.get(e.from)?.path }));
+  }
+
+  /**
+   * A lower-authority document claiming authority over a higher one is a
+   * structural error, not a matter of taste (PRD §5).
+   */
+  authorityViolations() {
+    const out = [];
+    for (const e of this.edges) {
+      if (e.rel !== 'defines' && e.rel !== 'supersedes') continue;
+      const from = this.nodes.get(e.from), to = this.nodes.get(e.to);
+      if (!from || !to) continue;
+      const fr = AUTHORITY[from.authority]?.rank ?? 9;
+      const tr = AUTHORITY[to.authority]?.rank ?? 9;
+      if (fr > tr) out.push({ from: from.path, to: to.path, rel: e.rel, fromAuthority: from.authority, toAuthority: to.authority });
+    }
+    return out;
+  }
+
+  toJSON() {
+    return {
+      version: 1,
+      generated: new Date().toISOString().slice(0, 10),
+      nodes: [...this.nodes.values()],
+      edges: this.edges,
+    };
+  }
+}
+
+/**
+ * Build the graph from documents + registry + config domains.
+ * @param {import('./document.js').Document[]} docs
+ * @param {object} registry
+ * @param {object} cfg
+ * @param {{path:string,kind:string}[]} [contracts]
+ */
+export function build(docs, registry, cfg, contracts = []) {
+  const g = new Graph();
+  const byPath = new Map();
+
+  for (const d of docs) {
+    const n = g.addNode({ id: d.id, path: d.path, type: d.type, authority: d.authority,
+      visibility: d.visibility, domain: d.domain, status: d.status, kind: 'document',
+      lines: d.lines, hash: d.hash, generated: d.isGenerated });
+    byPath.set(d.path, n);
+  }
+  for (const c of contracts) {
+    const id = c.path.replace(/\.[^.]+$/, '').replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-|-$/g, '').toLowerCase();
+    if (!g.nodes.has(id)) g.addNode({ id, path: c.path, type: `contract.${c.kind}`, authority: 'machine-contract',
+      visibility: 'internal', domain: null, kind: 'contract' });
+  }
+
+  // Declared relationships, plus their inverses so traversal works both ways.
+  for (const d of docs) {
+    for (const [rel, targets] of Object.entries(d.relationships)) {
+      for (const t of targets) {
+        g.addEdge(d.id, t, rel);
+        const inv = RELATIONSHIPS[rel]?.inverse;
+        if (inv && g.nodes.has(t)) g.addEdge(t, d.id, inv, true);
+      }
+    }
+  }
+
+  // Inferred `references` edges from internal markdown links: free, and the main
+  // reason a greenfield repo's graph is not empty on day one.
+  for (const d of docs) {
+    for (const target of d.links().internal) {
+      const resolved = resolveLink(d.path, target);
+      const node = byPath.get(resolved);
+      if (node && node.id !== d.id) g.addEdge(d.id, node.id, 'references', true);
+    }
+  }
+
+  // Domain -> code path edges from config, so impact analysis can map a code diff
+  // to the documents that claim to describe it.
+  for (const [domain, spec] of Object.entries(cfg.domains || {})) {
+    const nodeId = `code:${domain}`;
+    g.addNode({ id: nodeId, path: (spec.paths || []).join(', '), type: 'code.domain', authority: 'implementation',
+      visibility: 'internal', domain, kind: 'code', paths: spec.paths || [] });
+    for (const docId of spec.docs || []) if (g.nodes.has(docId)) g.addEdge(docId, nodeId, 'documents');
+  }
+  // `documents:` in frontmatter is the per-document version of the same mapping.
+  for (const d of docs) {
+    const globs = d.meta.documents;
+    if (!globs) continue;
+    const list = Array.isArray(globs) ? globs : [globs];
+    const nodeId = `code:${d.id}`;
+    g.addNode({ id: nodeId, path: list.join(', '), type: 'code.paths', authority: 'implementation',
+      visibility: 'internal', domain: d.domain, kind: 'code', paths: list });
+    g.addEdge(d.id, nodeId, 'documents');
+  }
+
+  return g;
+}
+
+export function resolveLink(fromPath, target) {
+  const dir = path.posix.dirname(fromPath);
+  let p = path.posix.normalize(path.posix.join(dir, target));
+  if (p.startsWith('./')) p = p.slice(2);
+  return p;
+}
+
+export function save(root, g) { return write(path.join(root, GRAPH_PATH), JSON.stringify(g.toJSON(), null, 2) + '\n'); }
+
+export function loadSaved(root) {
+  const f = path.join(root, GRAPH_PATH);
+  return exists(f) ? JSON.parse(read(f)) : null;
+}
+
+/** Which code-node globs does a changed file belong to? */
+export function codeNodesFor(g, changedPath) {
+  return [...g.nodes.values()].filter((n) => n.kind === 'code' && matchAny(changedPath, n.paths || []));
+}

package/core/health.js

@@ -0,0 +1,101 @@
+import { AUTHORITY, TYPES } from './taxonomy.js';
+import { pct } from './util.js';
+import { inboundCounts } from './links.js';
+import { coverageGaps } from './inventory.js';
+import { limitFor, qualityFor } from './config.js';
+
+/**
+ * Documentation health (PRD §31).
+ *
+ * Every component here is computed from countable facts, so the number moves for
+ * a reason you can point at. Nothing is a model's opinion.
+ */
+export function health({ cfg, docs, inv, graph, registry, findings, stale = [] }) {
+  const n = Math.max(1, docs.length);
+  const gaps = coverageGaps(inv);
+  const inbound = inboundCounts(docs);
+
+  const classified = docs.filter((d) => d.type !== 'unknown').length;
+  const registered = docs.filter((d) => d.registered).length;
+  // Coverage has two halves: how much of what exists is understood, and how much
+  // of what the repository's stack implies actually exists.
+  const expected = gaps.length + new Set(docs.map((d) => d.type)).size;
+  const coverage = Math.round(0.5 * pct(classified, n) + 0.5 * pct(expected - gaps.length, expected));
+
+  const staleRisk = stale.length ? Math.round(stale.reduce((a, s) => a + s.risk, 0) / stale.length) : 0;
+  const freshness = Math.max(0, 100 - Math.round(staleRisk * (stale.length / n)));
+
+  const byCheck = (c) => findings.filter((f) => f.check === c).length;
+  const consistency = clamp(100
+    - byCheck('duplicate-id') * 20
+    - byCheck('authority-violation') * 20
+    - byCheck('unknown-reference') * 8
+    - byCheck('duplicate-candidate') * 4
+    - byCheck('invalid-relationship') * 4);
+
+  const structure = clamp(100
+    - byCheck('wrong-location') * 6
+    - byCheck('hard-limit') * 8
+    - byCheck('soft-limit') * 2
+    - byCheck('missing-sections') * 3
+    - byCheck('new-root-document') * 5);
+
+  const linked = [...inbound.values()].filter((c) => c > 0).length;
+  const discoverability = clamp(Math.round(0.6 * pct(linked, n) + 0.4 * (100 - byCheck('missing-index') * 10)));
+
+  const withRels = docs.filter((d) => Object.keys(d.relationships).length > 0).length;
+  const crossLinking = clamp(Math.round(0.5 * pct(withRels, n) + 0.5 * (100 - byCheck('broken-link') * 8)));
+
+  const canonical = docs.filter((d) => (AUTHORITY[d.authority]?.rank ?? 9) <= 1);
+  const canonicalIntegrity = clamp(100
+    - graph.authorityViolations().length * 25
+    - canonical.filter((d) => d.missingSections().length).length * 8
+    - canonical.filter((d) => !d.registered).length * 10);
+
+  const metadata = clamp(Math.round(pct(registered, n)
+    - byCheck('missing-visibility') * 2
+    - byCheck('missing-owner') * 2));
+
+  const components = { coverage: clamp(coverage), freshness, consistency, structure, discoverability,
+    'cross-linking': crossLinking, 'canonical integrity': canonicalIntegrity, metadata };
+
+  const weights = { coverage: 0.18, freshness: 0.14, consistency: 0.16, structure: 0.13,
+    discoverability: 0.11, 'cross-linking': 0.10, 'canonical integrity': 0.12, metadata: 0.06 };
+  const overall = Math.round(Object.entries(components).reduce((a, [k, v]) => a + v * weights[k], 0));
+
+  return {
+    overall, components,
+    issues: {
+      stale: stale.filter((s) => s.risk >= (cfg.drift?.stale_threshold ?? 60)).length,
+      oversized: byCheck('hard-limit') + byCheck('soft-limit'),
+      orphans: byCheck('orphan'),
+      brokenLinks: byCheck('broken-link'),
+      unclassified: byCheck('unclassified'),
+      missingCrossReferences: byCheck('unknown-reference'),
+      duplicateCandidates: byCheck('duplicate-candidate'),
+      coverageGaps: gaps.length,
+    },
+    gaps,
+    counts: { documents: docs.length, classified, registered, canonical: canonical.length,
+      contracts: inv.contracts.length, lines: inv.counts.markdownLines },
+  };
+}
+
+function clamp(n) { return Math.max(0, Math.min(100, Math.round(n))); }
+
+/** Quality-gate scaffolding (PRD §20). Deterministic dimensions only; the rest is the reviewer agent's. */
+export function qualityFloor({ cfg, doc, findings }) {
+  const mine = findings.filter((f) => f.path === doc.path);
+  const threshold = qualityFor(cfg, doc.type);
+  const { soft, hard } = limitFor(cfg, doc.type);
+  const structure = clamp(100 - doc.missingSections().length * 12 - (hard && doc.lines > hard ? 20 : 0));
+  const grounding = clamp(100 - mine.filter((f) => f.check === 'broken-link').length * 15
+    - mine.filter((f) => f.check === 'unknown-reference').length * 10);
+  const crossRefs = clamp(Object.keys(doc.relationships).length ? 100 : 55);
+  const freshness = doc.status === 'draft' ? 60 : 100;
+  return {
+    path: doc.path, type: doc.type, threshold,
+    deterministic: { structure, 'technical grounding': grounding, 'cross references': crossRefs, freshness },
+    note: 'Clarity, completeness, audience fit and security judgement are scored by the quality-reviewer agent and are advisory.',
+  };
+}

package/core/impact.js

@@ -0,0 +1,146 @@
+import { changedFiles, isRepo } from './git.js';
+import { codeNodesFor } from './graph.js';
+import { AUTHORITY } from './taxonomy.js';
+import { matchAny } from './util.js';
+import { MD_RE, CONTRACT_RE, TEST_RE, isCode, isMappable } from './paths.js';
+
+/**
+ * Change impact analysis (PRD §25) and the documentation change checklist (PRD §27).
+ *
+ * Impact is a graph reachability question, so it is fully deterministic. The
+ * checklist turns the answer into a checklist an agent can work through and a
+ * CI job can verify.
+ */
+
+
+/**
+ * @param {{root:string,cfg:object,docs:any[],graph:any,base?:string,paths?:string[]}} ctx
+ */
+export function analyze({ root, cfg, docs, graph, base = 'HEAD', paths = null }) {
+  const changed = paths
+    ? paths.map((p) => ({ path: p, status: 'M' }))
+    : (isRepo(root) ? changedFiles(root, base) : []);
+  const changedPaths = changed.map((c) => c.path);
+  const changedDocs = new Set(changedPaths.filter((p) => MD_RE.test(p)));
+
+  const domains = new Set();
+  for (const [domain, spec] of Object.entries(cfg.domains || {})) {
+    if (changedPaths.some((p) => matchAny(p, spec.paths || []))) domains.add(domain);
+  }
+
+  // Seed: documents directly mapped to changed code, plus changed documents themselves.
+  const seeds = new Set();
+  const reasons = new Map();
+  const note = (id, why) => { if (!reasons.has(id)) reasons.set(id, []); reasons.get(id).push(why); };
+
+  for (const c of changed) {
+    if (isMappable(c.path)) {
+      for (const node of codeNodesFor(graph, c.path)) {
+        for (const e of graph.in(node.id, 'documents')) { seeds.add(e.from); note(e.from, `maps ${c.path}`); }
+        if (node.domain) domains.add(node.domain);
+      }
+      const contractNode = [...graph.nodes.values()].find((n) => n.path === c.path);
+      if (contractNode) {
+        for (const e of graph.in(contractNode.id)) { seeds.add(e.from); note(e.from, `${e.rel} ${c.path}`); }
+      }
+    }
+    if (MD_RE.test(c.path)) {
+      const n = [...graph.nodes.values()].find((x) => x.path === c.path);
+      if (n) { seeds.add(n.id); note(n.id, 'changed in this diff'); if (n.domain) domains.add(n.domain); }
+    }
+  }
+  for (const d of docs) {
+    if (d.domain && domains.has(d.domain) && !seeds.has(d.id)) { seeds.add(d.id); note(d.id, `domain ${d.domain} affected`); }
+  }
+
+  // Propagate along dependency edges: whatever depends on a seed is also impacted.
+  const reached = graph.reach([...seeds], { direction: 'in', rels: ['depends_on', 'derived_from', 'implements', 'references'], maxDepth: 3 });
+  for (const [id, info] of reached) note(id, `${info.via} a document that changed (depth ${info.depth})`);
+
+  const affected = [];
+  for (const id of new Set([...seeds, ...reached.keys()])) {
+    const n = graph.nodes.get(id);
+    if (!n || n.kind !== 'document') continue;
+    const rank = AUTHORITY[n.authority]?.rank ?? 9;
+    const direct = seeds.has(id);
+    affected.push({
+      id, path: n.path, type: n.type, authority: n.authority, domain: n.domain,
+      updated: changedDocs.has(n.path),
+      required: direct && rank <= 3,
+      reasons: reasons.get(id) || [],
+    });
+  }
+  affected.sort((a, b) => Number(b.required) - Number(a.required) || a.path.localeCompare(b.path));
+
+  const behaviorChanged = changedPaths.some((p) => isCode(p) && !TEST_RE.test(p));
+  const apiChanged = changedPaths.some((p) => CONTRACT_RE.test(p)) ||
+    changedPaths.some((p) => /(^|\/)(api|routes?|controllers?|handlers?|endpoints?)\//.test(p));
+  const securityChanged = changedPaths.some((p) => /(^|\/)(auth|authz|authentication|authorization|security|crypto|session|permissions?)\//i.test(p));
+  const testsChanged = changedPaths.some((p) => TEST_RE.test(p));
+  const userVisible = apiChanged || changedPaths.some((p) => /(^|\/)(ui|components?|pages?|views?|cli)\//.test(p));
+
+  return {
+    changed, domains: [...domains].sort(), affected,
+    signals: { behaviorChanged, apiChanged, securityChanged, testsChanged, userVisible },
+    level: level(affected, { behaviorChanged, apiChanged, securityChanged }),
+  };
+}
+
+function level(affected, s) {
+  const req = affected.filter((a) => a.required).length;
+  if (s.securityChanged || req >= 4) return 'HIGH';
+  if (s.apiChanged || req >= 2) return 'MEDIUM';
+  if (req >= 1 || s.behaviorChanged) return 'LOW';
+  return 'NONE';
+}
+
+/** PRD §27 manifest: a deterministic checklist, written to .docgov/checklist.yaml. */
+export function checklist(impact) {
+  const required = impact.affected.filter((a) => a.required);
+  return {
+    change: {
+      domain: impact.domains,
+      behavior_changed: impact.signals.behaviorChanged,
+      api_changed: impact.signals.apiChanged,
+      security_changed: impact.signals.securityChanged,
+      user_visible: impact.signals.userVisible,
+      tests_changed: impact.signals.testsChanged,
+      impact_level: impact.level,
+    },
+    docs: {
+      required: required.map((a) => a.id),
+      reviewed: required.filter((a) => a.updated).map((a) => a.id),
+      outstanding: required.filter((a) => !a.updated).map((a) => a.id),
+      optional: impact.affected.filter((a) => !a.required).map((a) => a.id),
+    },
+  };
+}
+
+/** The PR comment body (PRD §26). Deterministic; blocking is the caller's choice. */
+export function prReport(impact, drift, cfg) {
+  const m = checklist(impact);
+  const L = [];
+  L.push('DocGov Documentation Review');
+  L.push('───────────────────────────');
+  L.push(`Code impact: ${impact.level}`);
+  L.push(`Documentation impact: ${m.docs.required.length ? (m.docs.outstanding.length ? 'OUTSTANDING' : 'COVERED') : 'NONE'}`);
+  L.push('');
+  const tick = (ok, text) => L.push(`${ok ? '✓' : '✗'} ${text}`);
+  if (impact.signals.apiChanged) tick(impact.changed.some((c) => /openapi|\.proto$|\.graphql$/.test(c.path)), 'API contract updated');
+  if (impact.signals.behaviorChanged) tick(impact.signals.testsChanged, 'tests updated');
+  for (const a of impact.affected.filter((x) => x.required)) tick(a.updated, `${a.path} (${a.authority})`);
+  if (impact.signals.securityChanged) L.push('⚠ security-sensitive paths changed — security documentation review recommended');
+  for (const a of impact.affected.filter((x) => !x.required && !x.updated).slice(0, 5)) L.push(`· optional: ${a.path}`);
+  if (drift?.findings?.length) {
+    L.push('');
+    L.push(`Drift: ${drift.findings.filter((f) => f.severity === 'critical').length} critical, ` +
+      `${drift.findings.filter((f) => f.severity === 'high').length} high, ` +
+      `${drift.findings.filter((f) => f.severity === 'medium').length} medium`);
+    for (const f of drift.findings.slice(0, 5)) L.push(`  ${f.severity.toUpperCase().padEnd(8)} ${f.id} ${f.document} — ${f.why}`);
+  }
+  L.push('');
+  const blocked = m.docs.outstanding.length > 0 && !cfg.governance.warn_only;
+  L.push(`Documentation readiness: ${blocked ? 'REVIEW REQUIRED' : 'OK'}`);
+  if (blocked) L.push(`Outstanding: ${m.docs.outstanding.join(', ')}`);
+  return { text: L.join('\n'), checklist: m, blocked };
+}