docguard-cli 0.40.5 → 0.41.0

package/cli/commands/hooks.mjs

@@ -1,6 +1,7 @@
 /**
  * Hooks Command — Generate pre-commit/pre-push hooks for DocGuard
  * Creates git hooks that run guard/score before commits.
+ * @implements docguard.adoption-workflow-integrity#FR-003
  */
 
 import { existsSync, mkdirSync, chmodSync, readFileSync, unlinkSync } from 'node:fs';
@@ -54,6 +55,29 @@ function spliceManagedBlock(existing, newBody) {
   const bodyNoShebang = newBody.replace(/^#!.*\n/, '');
   return `${before}${BEGIN_MARKER}\n${bodyNoShebang.replace(/\n+$/, '')}\n${END_MARKER}${after}`;
 }
+
+function hookState(name, hooksDir) {
+  const path = resolve(hooksDir, name);
+  if (!existsSync(path)) return { kind: 'missing', path, content: '' };
+  let content;
+  try { content = readFileSync(path, 'utf-8'); }
+  catch { return { kind: 'unreadable', path, content: '' }; }
+  if (content.includes(BEGIN_MARKER) && content.includes(END_MARKER)) {
+    return { kind: 'managed', path, content };
+  }
+  const legacySignature = new RegExp(`^# DocGuard ${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')} hook(?: \\(auto-fix mode\\))?$`, 'm');
+  if (legacySignature.test(content)) return { kind: 'legacy', path, content };
+  return { kind: 'foreign', path, content };
+}
+
+function removeManagedBlock(content) {
+  const start = content.indexOf(BEGIN_MARKER);
+  const end = content.indexOf(END_MARKER);
+  if (start === -1 || end === -1 || end < start) return null;
+  const remaining = `${content.slice(0, start)}${content.slice(end + END_MARKER.length)}`
+    .replace(/\n{3,}/g, '\n\n');
+  return remaining;
+}
 import { resolve, relative, basename } from 'node:path';
 import { c } from '../shared.mjs';
 import { safeWrite } from '../writers/generate-io.mjs';
@@ -278,8 +302,16 @@ export function runHooks(projectDir, config, flags) {
   if (flags.list) {
     console.log(`  ${c.bold}Available hooks:${c.reset}\n`);
     for (const [name, hook] of Object.entries(HOOKS)) {
-      const installed = existsSync(resolve(hooksDir, name));
-      const status = installed ? `${c.green}✅ installed${c.reset}` : `${c.dim}not installed${c.reset}`;
+      const state = hookState(name, hooksDir);
+      const status = state.kind === 'managed'
+        ? `${c.green}✅ DocGuard installed${c.reset}`
+        : state.kind === 'legacy'
+          ? `${c.yellow}⚠ legacy DocGuard hook — upgrade with --force${c.reset}`
+          : state.kind === 'foreign'
+            ? `${c.yellow}existing non-DocGuard hook${c.reset}`
+            : state.kind === 'unreadable'
+              ? `${c.red}unreadable hook${c.reset}`
+              : `${c.dim}not installed${c.reset}`;
       console.log(`    ${c.cyan}${name}${c.reset}: ${hook.description} [${status}]`);
     }
     console.log(`\n  ${c.dim}Install: docguard hooks --type <name>${c.reset}`);
@@ -291,16 +323,25 @@ export function runHooks(projectDir, config, flags) {
   if (flags.remove) {
     let removed = 0;
     for (const name of hookTypes) {
-      const hookPath = resolve(hooksDir, name);
-      if (existsSync(hookPath)) {
-        const content = readFileSync(hookPath, 'utf-8');
-        if (content.includes('DocGuard')) {
-          unlinkSync(hookPath);
-          console.log(`  ${c.yellow}🗑️  Removed: ${name}${c.reset}`);
-          removed++;
+      const state = hookState(name, hooksDir);
+      if (state.kind === 'managed') {
+        const remaining = removeManagedBlock(state.content);
+        const meaningful = remaining.replace(/^#!.*(?:\n|$)/, '').trim();
+        if (meaningful) {
+          safeWrite(state.path, remaining);
+          chmodSync(state.path, 0o755);
+          console.log(`  ${c.yellow}🗑️  Removed DocGuard block from ${name}; preserved other hook commands${c.reset}`);
         } else {
-          console.log(`  ${c.dim}⏭️  ${name}: not a DocGuard hook (skipped)${c.reset}`);
+          unlinkSync(state.path);
+          console.log(`  ${c.yellow}🗑️  Removed: ${name}${c.reset}`);
         }
+        removed++;
+      } else if (state.kind === 'legacy') {
+        unlinkSync(state.path);
+        console.log(`  ${c.yellow}🗑️  Removed legacy DocGuard hook: ${name}${c.reset}`);
+        removed++;
+      } else if (state.kind !== 'missing') {
+        console.log(`  ${c.dim}⏭️  ${name}: not a recognized DocGuard hook (skipped)${c.reset}`);
       }
     }
     console.log(`\n  Removed: ${removed}\n`);

package/cli/commands/init.mjs

@@ -199,6 +199,18 @@ function shouldRunGenerate(projectDir, flags) {
 }
 
 export async function runInit(projectDir, config, flags) {
+  // `--list` is read-only inventory owned by the hooks scaffolder. Routing it
+  // through normal init can start prompts or create documentation before the
+  // requested inventory is shown, which violates the command's read-only intent.
+  if (flags.list && Array.isArray(flags.with)) {
+    if (flags.with.length !== 1 || flags.with[0] !== 'hooks') {
+      console.error(`${c.red}--list is supported only with \`docguard init --with hooks\`.${c.reset}`);
+      process.exitCode = 1;
+      return;
+    }
+    const { runHooks } = await import('./hooks.mjs');
+    return runHooks(projectDir, config, flags);
+  }
   if (true) assertDefaultDocWrites(config);
   // v0.20: `--wizard` dispatches to the full interactive onboarding (formerly
   // `docguard setup`). Done before profile validation so the wizard can ask
@@ -381,6 +393,9 @@ export async function runInit(projectDir, config, flags) {
       // Empty by default — every validator uses 'medium'. Add entries to dial
       // strictness up (CI-critical checks) or down (experimental validators).
       severity: {},
+      // Exact stable-code overrides. Use this when one rule needs a different
+      // policy without weakening or escalating every finding in its validator.
+      findingSeverity: {},
     };
 
     writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2) + '\n', 'utf-8');

package/cli/commands/reconcile.mjs

@@ -7,12 +7,19 @@
 import { buildReconciliationPlan } from '../scanners/reconciliation.mjs';
 import { runSync } from './sync.mjs';
 
-function printPlan(result) {
+function printPlan(result, flags = {}) {
   console.log(`Reconciliation: ${result.status}`);
   console.log(`Revision: ${result.baseRevision || 'unknown'} → ${result.revision || 'unknown'}`);
-  for (const item of result.classifications) {
+  if (result.range) console.log(`Range: ${result.range.commitCount ?? 'unknown'} commit(s), ${result.range.changedFileCount} changed file(s)`);
+  if (result.coverage?.status !== 'complete') {
+    console.log(`Coverage: ${result.coverage.status} — ${result.coverage.reason}`);
+  }
+  const maximum = flags.verbose ? result.classifications.length : 20;
+  for (const item of result.classifications.slice(0, maximum)) {
     console.log(`  [${item.confidence}] ${item.path || item.kind}: ${item.disposition}`);
   }
+  const elided = result.classifications.length - maximum;
+  if (elided > 0) console.log(`  … ${elided} more classification(s); rerun with --verbose to list all.`);
   if (result.writes.length) console.log(`Mechanical write available: ${result.writes[0].command}`);
 }
 
@@ -29,7 +36,7 @@ export function runReconcile(projectDir, config, flags = {}) {
     }
     const result = { command: 'reconcile', ...plan, applied: Boolean(flags.write), mechanical };
     if (flags.format === 'json') console.log(JSON.stringify(result, null, 2));
-    else printPlan(result);
+    else printPlan(result, flags);
     if (flags.check && !['READY'].includes(result.status)) process.exitCode = 2;
     return result;
   } catch (error) {

package/cli/commands/report.mjs

@@ -29,6 +29,7 @@ import { runGuardInternal } from './guard.mjs';
 import { runScoreInternal, computeAlcoaCompliance } from './score.mjs';
 import { getHeadInfo, isGitRepo } from '../shared-git.mjs';
 import { loadFixMemory } from '../writers/fix-memory.mjs';
+import { buildReadinessAssessment } from '../assessment.mjs';
 
 const _PKG = JSON.parse(readFileSync(resolvePath(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json'), 'utf-8'));
 const CLI_VERSION = _PKG.version;
@@ -44,6 +45,7 @@ export function buildReport(projectDir, config) {
   const alcoa = computeAlcoaCompliance(projectDir, config, scoreData.categories);
   const git = isGitRepo(projectDir) ? getHeadInfo(projectDir) : null;
   const fixMemory = loadFixMemory(projectDir);
+  const assessment = buildReadinessAssessment(guardData, scoreData);
 
   // Findings grouped by stable code — auditors care about "how many of
   // which class", not the per-file noise. Codeless findings group as OTHER.
@@ -65,6 +67,7 @@ export function buildReport(projectDir, config) {
       type: config.projectType || 'unknown',
     },
     git: git ? { commit: git.commit, branch: git.branch, dirty: git.dirty } : null,
+    assessment,
     guard: {
       status: guardData.status,
       passed: guardData.passed,
@@ -126,7 +129,8 @@ export function toMarkdown(r) {
   lines.push('');
   lines.push('| Metric | Value |');
   lines.push('|--------|-------|');
-  lines.push(`| CDD Score (structural maturity) | ${r.score.score}/100 (${r.score.grade}) |`);
+  lines.push(`| Readiness | **${r.assessment.status}** — ${r.assessment.summary} |`);
+  lines.push(`| Structural Maturity | ${r.score.score}/100 (${r.score.grade}); this is not a guard verdict |`);
   lines.push(`| Factual accuracy | Unverified — ${r.score.assurance.unverifiedClaims ?? 'unknown number of'} extracted claim(s); discovery is heuristic |`);
   lines.push(`| Guard | ${r.guard.status.toUpperCase()} — ${r.guard.passed}/${r.guard.total} checks, ${r.guard.errors} error(s), ${r.guard.warnings} warning(s) |`);
   if (r.guard.baselineSuppressed > 0) {

package/cli/commands/score.mjs

@@ -160,7 +160,7 @@ export function runScore(projectDir, config, flags) {
   // mixed ANSI escapes with JSON.
   const isJson = flags.format === 'json';
   if (!isJson) {
-    console.log(`${c.bold}📊 DocGuard Score — ${config.projectName}${c.reset}`);
+    console.log(`${c.bold}📊 DocGuard Structural Maturity — ${config.projectName}${c.reset}`);
     console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
   }
 
@@ -222,6 +222,7 @@ export function runScore(projectDir, config, flags) {
 
   const gradeColor = totalScore >= 80 ? c.green : totalScore >= 60 ? c.yellow : c.red;
   console.log(`  ${gradeColor}${c.bold}CDD Maturity Score: ${totalScore}/100 (${grade})${c.reset}`);
+  console.log(`  ${c.dim}Structural Maturity only — this score is not a guard verdict. Run ${c.cyan}docguard guard${c.dim} for PASS/WARN/FAIL.${c.reset}`);
   // Memory framing: is the documentation memory COMPLETE and ACCURATE?
   const memColor = (s) => s >= 80 ? c.green : s >= 60 ? c.yellow : c.red;
   console.log(`  ${c.dim}Memory:${c.reset} ${memColor(memory.completeness)}Completeness ${memory.completeness}%${c.reset} ${c.dim}·${c.reset} ${c.cyan}Factual accuracy: unverified${c.reset}`);

package/cli/commands/upgrade.mjs

@@ -129,6 +129,9 @@ export function migrateSchema(cfg, fromVersion) {
     // additive: existing projects get an empty severity map and default
     // (medium) behavior. No behavioral change unless they explicitly opt in.
     '0.5': (c) => ({ ...c, severity: c.severity || {}, version: '0.5' }),
+    // v0.6 — exact finding-code enforcement overrides. Empty by default, so
+    // existing validator-level behavior remains unchanged after migration.
+    '0.6': (c) => ({ ...c, findingSeverity: c.findingSeverity || {}, version: '0.6' }),
   };
   let current = { ...cfg };
   let changed = false;
@@ -211,7 +214,7 @@ function openUpgradePR(projectDir, migratedConfig, fromVersion, toVersion) {
     `Automated schema migration from \`${fromVersion}\` → \`${toVersion}\`.\n\n` +
     `This PR was opened by \`docguard upgrade --apply --pr\`. It updates the\n` +
     `\`.docguard.json\` schema version and any additive fields the new schema\n` +
-    `introduces (e.g. \`severity: {}\` for v0.5).\n\n` +
+    `introduces (for example \`findingSeverity: {}\` for v0.6).\n\n` +
     `Review and merge to keep your team's DocGuard config in sync.\n\n` +
     `> 🤖 Generated by [DocGuard](https://github.com/raccioly/docguard)`;
   r = spawnSync('gh', [

package/cli/commands/verify.mjs

@@ -208,8 +208,8 @@ function runEvidenceVerification(projectDir, config, flags) {
 function runInstructionAudit(projectDir, config, flags) {
   const isJson = flags.format === 'json';
   const { rules, deterministic, tasks } = auditInstructions(projectDir, config);
-  const { duplicates, negations, stalePointers, staleCommands } = deterministic;
-  const findingCount = duplicates.length + negations.length + stalePointers.length + staleCommands.length;
+  const { duplicates, negations, stalePointers, ambiguousPointers = [], unsafePointers = [], staleCommands } = deterministic;
+  const findingCount = duplicates.length + negations.length + stalePointers.length + ambiguousPointers.length + unsafePointers.length + staleCommands.length;
   // Structured change context helps the agent judge whether a rule about code
   // has been invalidated by a recent change (feat 6).
   const changeContext = buildChangeContext(projectDir, flags.since);
@@ -254,6 +254,13 @@ function runInstructionAudit(projectDir, config, flags) {
     for (const s of stalePointers) {
       console.log(`    ${c.yellow}⚠${c.reset} stale pointer — ${s.file}:${s.line}: ${c.cyan}${s.path}${c.reset} does not exist`);
     }
+    for (const pointer of ambiguousPointers) {
+      console.log(`    ${c.yellow}AMBIGUOUS POINTER${c.reset} ${pointer.file}:${pointer.line} — ${pointer.path}`);
+      console.log(`      ${c.dim}${pointer.matchCount} matches: ${pointer.matches.join(', ')}${c.reset}`);
+    }
+    for (const pointer of unsafePointers) {
+      console.log(`    ${c.yellow}UNSAFE POINTER${c.reset} ${pointer.file}:${pointer.line} — ${pointer.path}`);
+    }
     for (const s of staleCommands) {
       console.log(`    ${c.yellow}⚠${c.reset} stale command — ${s.file}:${s.line}: ${c.cyan}docguard ${s.command}${c.reset} is not a docguard command`);
     }

package/cli/commands/watch.mjs

@@ -8,7 +8,7 @@
  */
 
 import { watch as fsWatch, readdirSync, lstatSync } from 'node:fs';
-import { resolve, extname } from 'node:path';
+import { resolve, extname, basename } from 'node:path';
 import { c } from '../shared.mjs';
 import { runGuardInternal } from './guard.mjs';
 import { clearMemoryPlanCache } from '../scanners/memory-plan.mjs';
@@ -24,7 +24,8 @@ export function runWatch(projectDir, config, flags = {}, runtime = {}) {
   const watch = runtime.watch || fsWatch;
   const guard = runtime.guard || runGuardInternal;
   const clearCache = runtime.clearCache || clearMemoryPlanCache;
-  console.log(`${c.bold}👁️  DocGuard Watch — ${config.projectName}${c.reset}`);
+  const projectName = config.projectName || basename(resolve(projectDir)) || 'project';
+  console.log(`${c.bold}👁️  DocGuard Watch — ${projectName}${c.reset}`);
   console.log(`${c.dim}   Directory: ${projectDir}${c.reset}`);
   if (flags.autoFix) {
     console.log(`${c.cyan}   Mode: auto-fix (will output AI prompts on failures)${c.reset}`);

package/cli/config.mjs

@@ -14,6 +14,7 @@ import { applyDocRoles } from './shared-doc-roles.mjs';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve, basename } from 'node:path';
 import { c, PROFILES, SEVERITY_LEVELS } from './shared.mjs';
+import { CODES } from './findings.mjs';
 import { mergeIgnoreFile } from './shared-ignore.mjs';
 import { detectProjectName } from './scanners/project-type.mjs';
 
@@ -91,6 +92,7 @@ export function loadConfig(projectDir) {
       referenceExistence: true,
       apiDocSmells: true,
     },
+    findingSeverity: {},
   };
 
   if (existsSync(configPath)) {
@@ -123,6 +125,16 @@ export function loadConfig(projectDir) {
           }
         }
       }
+      if (merged.findingSeverity && typeof merged.findingSeverity === 'object') {
+        for (const [code, val] of Object.entries(merged.findingSeverity)) {
+          if (!Object.hasOwn(CODES, code)) {
+            throw new Error(`findingSeverity.${code} is not a known finding code`);
+          }
+          if (typeof val !== 'string' || !SEVERITY_LEVELS.has(val.toLowerCase())) {
+            throw new Error(`findingSeverity.${code} must be high, medium, or low`);
+          }
+        }
+      }
 
       // Auto-detect project type if not set
       if (!merged.projectType) {
@@ -249,6 +261,17 @@ function normalizeConfig(cfg) {
   const out = { ...cfg };
   if (out.validators) out.validators = _normalizeValidatorKeys(out.validators);
   if (out.severity)   out.severity   = _normalizeValidatorKeys(out.severity);
+  if (out.findingSeverity && typeof out.findingSeverity === 'object' && !Array.isArray(out.findingSeverity)) {
+    const normalized = {};
+    for (const [rawCode, value] of Object.entries(out.findingSeverity)) {
+      const code = rawCode.toUpperCase();
+      if (Object.hasOwn(normalized, code)) {
+        throw new Error(`findingSeverity contains duplicate code ${code}`);
+      }
+      normalized[code] = typeof value === 'string' ? value.toLowerCase() : value;
+    }
+    out.findingSeverity = normalized;
+  }
   return out;
 }
 

package/cli/evidence/adapters.mjs

@@ -9,6 +9,7 @@
 import { lstatSync, readdirSync, realpathSync } from 'node:fs';
 import { isAbsolute, relative, resolve, sep } from 'node:path';
 import { buildIgnoreFilter, compileGlob, DEFAULT_IGNORE_DIRS, relPosix } from '../shared-ignore.mjs';
+import { countPythonLiteralEntries } from './python-literal.mjs';
 
 const MAX_COLLECTION_FILES = 20_000;
 const MAX_REPORT_FINDINGS = 10_000;
@@ -194,6 +195,19 @@ export function readEvidenceSource(projectDir, declaration, read, config = {}) {
     }
     return result;
   }
+  if (source.adapter === 'python-literal-count') {
+    const snapshot = read(source.path);
+    if (snapshot.content === null) {
+      return answer('inconclusive', `source-${snapshot.evidence.reason}`, `Cannot safely read Python source ${source.path}.`);
+    }
+    const parsed = countPythonLiteralEntries(snapshot.content, source.symbol);
+    const extra = { sourceEvidence: snapshot.evidence, inputHashes: [] };
+    if (Object.hasOwn(parsed, 'value')) extra.value = parsed.value;
+    if (parsed.status === 'ok' && parsed.value === 0 && !source.allowEmpty) {
+      return answer('inconclusive', 'empty-python-literal-not-allowed', 'Python literal has no entries and allowEmpty is false.', extra);
+    }
+    return answer(parsed.status, parsed.reasonCode, parsed.message, extra);
+  }
   if (source.adapter === 'oasdiff') return oasdiffReport(source, read);
   if (source.adapter === 'buf') return bufReport(source, read);
   return answer('unsupported', 'unsupported-adapter', `Adapter ${source.adapter} is unsupported.`);

package/cli/evidence/manifest.mjs

@@ -7,6 +7,7 @@
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { createEvidenceReader } from '../scanners/semantic-claims.mjs';
+import { PYTHON_SYMBOL_RE } from './python-literal.mjs';
 
 export const EVIDENCE_MANIFEST_PATH = '.docguard-evidence.json';
 export const EVIDENCE_SCHEMA_URL = 'https://raccioly.github.io/docguard/schemas/docguard-evidence.schema.json';
@@ -90,6 +91,17 @@ function validateSource(source, errors, id) {
     if (typeof source.allowEmpty !== 'boolean') errors.push(issue(`${id}.source.allowEmpty must be boolean.`, id));
     return;
   }
+  if (source.adapter === 'python-literal-count') {
+    exactKeys(source, ['adapter', 'path', 'symbol', 'allowEmpty'], `${id}.source`, errors, id);
+    if (!isSafeEvidencePath(source.path) || !source.path.endsWith('.py')) {
+      errors.push(issue(`${id}.source.path must be a safe repository-relative Python path.`, id));
+    }
+    if (!PYTHON_SYMBOL_RE.test(source.symbol || '')) {
+      errors.push(issue(`${id}.source.symbol must be an ASCII Python identifier containing at most 128 characters.`, id));
+    }
+    if (typeof source.allowEmpty !== 'boolean') errors.push(issue(`${id}.source.allowEmpty must be boolean.`, id));
+    return;
+  }
   if (REPORT_ADAPTERS.has(source.adapter)) {
     exactKeys(source, ['adapter', 'adapterVersion', 'path', 'producerVersion', 'command', 'inputs'], `${id}.source`, errors, id);
     if (!Number.isInteger(source.adapterVersion) || source.adapterVersion < 1 || source.adapterVersion > 100) {
@@ -143,6 +155,9 @@ function validatePredicate(predicate, source, statement, errors, id) {
   if (source?.adapter === 'collection-count' && predicate.kind !== 'count-equals') {
     errors.push(issue(`${id} must combine collection-count with count-equals.`, id));
   }
+  if (source?.adapter === 'python-literal-count' && predicate.kind !== 'count-equals') {
+    errors.push(issue(`${id} must combine python-literal-count with count-equals.`, id));
+  }
   if (REPORT_ADAPTERS.has(source?.adapter) && predicate.kind !== 'no-findings') {
     errors.push(issue(`${id} must combine ${source.adapter} with no-findings.`, id));
   }