dotmd-cli 0.71.4 → 0.72.0

package/bin/dotmd.mjs

@@ -526,6 +526,10 @@ Options:
   --errors-only          Show only errors, suppress warnings entirely
   --fix                  Auto-fix broken refs, lint issues, and regenerate index
   --json                 Output errors and warnings as JSON (always full detail)
+  --min-docs <n>         Fail if fewer than <n> docs were scanned — a floor that
+                         tells "nothing is wrong" apart from "nothing was looked
+                         at". Overrides \`minDocs\` in config for this run;
+                         skipped when checking specific paths.
   --dry-run, -n          Preview fixes without writing (with --fix)`,
 
   archive: `dotmd archive <file-or-slug> — archive a document
@@ -1760,7 +1764,19 @@ async function main() {
     const errorsOnly = args.includes('--errors-only');
     const noCollapse = args.includes('--no-collapse');
     const verbose = args.includes('--verbose');
-    const checkTargets = restArgs.filter(arg => !arg.startsWith('-'));
+    // `--min-docs N` overrides the configured floor for this run (CI passes it
+    // without editing config). Its value is not a path target.
+    const minDocsFlagIdx = restArgs.indexOf('--min-docs');
+    const minDocsRaw = minDocsFlagIdx === -1 ? null : restArgs[minDocsFlagIdx + 1];
+    if (minDocsFlagIdx !== -1 && !/^\d+$/.test(minDocsRaw ?? '')) {
+      die('`--min-docs` needs a positive integer, e.g. `dotmd check --min-docs 500`.');
+    }
+    const minDocsOverride = minDocsRaw == null ? null : Number(minDocsRaw);
+    const minDocsValueIdx = minDocsFlagIdx === -1 ? -1 : minDocsFlagIdx + 1;
+    const checkTargets = restArgs.filter((arg, i) => !arg.startsWith('-') && i !== minDocsValueIdx);
+    const { applyScanFloor } = await import('../src/validate.mjs');
+    const scanFloorConfig = minDocsOverride == null ? config : { ...config, minDocs: minDocsOverride };
+    const applyFloor = (idx) => applyScanFloor(idx, scanFloorConfig, { scoped: checkTargets.length > 0 });
     const skippedCheckHooks = config._execution?.suppressSideEffects
       ? ['validate', 'transformDoc', 'formatSnapshot', 'renderCheck']
           .filter(name => typeof config.hooks?.[name] === 'function')
@@ -1810,6 +1826,7 @@ async function main() {
       const freshIndex = buildIndex(config);
       applyIndexFilters(freshIndex);
       applyPathScopeToIndex(freshIndex, config, checkTargets);
+      applyFloor(freshIndex);
       if (args.includes('--json')) {
         process.stdout.write(JSON.stringify(checkJson(freshIndex), null, 2) + '\n');
       } else {
@@ -1821,6 +1838,7 @@ async function main() {
     }
 
     applyPathScopeToIndex(index, config, checkTargets);
+    applyFloor(index);
 
     if (args.includes('--json')) {
       process.stdout.write(JSON.stringify(checkJson(index), null, 2) + '\n');

package/dotmd.config.example.mjs

@@ -13,6 +13,14 @@ export const archiveDir = 'archived';
 // Directories to skip when scanning
 export const excludeDirs = ['evidence'];
 
+// Floor under the scan surface. `dotmd check` fails when it scans fewer docs than
+// this, so a broken root or an over-eager exclude can't read as a clean estate —
+// zero errors and zero docs look identical otherwise. Off when unset. Set it well
+// below your real count (round down hard); raise it as the corpus grows.
+// Override for one run with `dotmd check --min-docs <n>`; skipped for path-scoped
+// checks, which are deliberate subsets.
+// export const minDocs = 500;
+
 // Document types — each type has its own status vocabulary and context layout.
 // Defaults: plan, doc, prompt. Override to customize statuses per type, or add new types.
 //

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.71.4",
+  "version": "0.72.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/commands.mjs

@@ -142,7 +142,7 @@ const definitions = [
     form('migrate <type>', { subcommands: ['migrate'], args: positionals(1, 1), options: [flag('--yes', '-y'), flag('--json'), flag('--ignore-lifecycle-override')] }),
     form('', { options: [value('--type'), flag('--json')] }),
   ]),
-  command('check', mutates('managed fix sweeps and repo-generated index; otherwise validation'), 'mutate', [form('[paths...]', { args: positionals(0, Infinity), options: [flag('--fix'), flag('--errors-only'), flag('--no-collapse'), flag('--json'), flag('--verbose')] })]),
+  command('check', mutates('managed fix sweeps and repo-generated index; otherwise validation'), 'mutate', [form('[paths...]', { args: positionals(0, Infinity), options: [flag('--fix'), flag('--errors-only'), flag('--no-collapse'), flag('--json'), flag('--verbose'), value('--min-docs')] })]),
   command('index', mutates('repo-generated index destination; --print is read-only'), 'mutate', [form('', { options: [flag('--print')] })]),
 
   command('self-check', none, 'internal', [form('', { options: [flag('--json')] })], { visibility: 'internal' }),

package/src/config.mjs

@@ -20,6 +20,8 @@ const DEFAULTS = {
   root: '.',
   archiveDir: 'archived',
   excludeDirs: [],
+  // Floor under the scan surface; null = off. See `applyScanFloor` in validate.mjs.
+  minDocs: null,
 
   types: {
     plan: {
@@ -517,6 +519,18 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     }
   }
 
+  // A floor under the scan surface. Unset (the default) is off, so no existing
+  // repo changes behavior. See `applyScanFloor` in src/validate.mjs for why a
+  // silent zero-doc pass is the failure mode worth spending a config key on.
+  let minDocs = null;
+  if (config.minDocs !== undefined && config.minDocs !== null) {
+    if (!Number.isInteger(config.minDocs) || config.minDocs < 1) {
+      earlyWarnings.push(`Config: minDocs must be a positive integer; ignoring \`${config.minDocs}\`.`);
+    } else {
+      minDocs = config.minDocs;
+    }
+  }
+
   const configWarnings = [...earlyWarnings, ...validateConfig(userConfig, config, validStatuses, indexPath)];
 
   return {
@@ -531,6 +545,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     archiveDir: config.archiveDir,
     excludeDirs: new Set(config.excludeDirs),
     docsRootPrefix,
+    minDocs,
 
     statusOrder,
     validStatuses,

package/src/query.mjs

@@ -396,14 +396,33 @@ function scanBodyForKeyword(doc, needle, config) {
   const lines = body.split('\n');
   const matches = [];
   for (let i = 0; i < lines.length && matches.length < MAX_BODY_MATCHES; i++) {
-    const text = lines[i].trim();
-    const at = text.toLowerCase().indexOf(needle);
+    const raw = lines[i].trim();
+    const at = raw.toLowerCase().indexOf(needle);
     if (at === -1) continue;
-    matches.push({ line: bodyLineOffset + i + 1, text: excerptAround(text, at, needle.length) });
+    const { text, at: shown } = displayableExcerptLine(raw, at, needle);
+    matches.push({ line: bodyLineOffset + i + 1, text: excerptAround(text, shown, needle.length) });
   }
   return matches;
 }
 
+// HTML comments are invisible when the markdown renders, so they are noise in an
+// excerpt — and dotmd's own conventions put them inline (a managed status token in
+// a hub table row reads as `| [x](x.md) | <!--s-->active<!--/s--> — next |`), which
+// is paid on every agent read of every search result.
+//
+// Matching still happens against the raw line, so a needle that only occurs INSIDE
+// a comment is never lost: if stripping would hide the match, the raw line is shown
+// instead. Whitespace is squeezed only on lines a strip actually touched.
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+
+export function displayableExcerptLine(raw, at, needle) {
+  if (!raw.includes('<!--')) return { text: raw, at };
+  const stripped = raw.replace(HTML_COMMENT_RE, '').replace(/[ \t]{2,}/g, ' ').trim();
+  const shown = stripped.toLowerCase().indexOf(needle);
+  if (shown === -1) return { text: raw, at };
+  return { text: stripped, at: shown };
+}
+
 // Window a long line around the match so the needle is always visible.
 function excerptAround(text, at, needleLen) {
   if (text.length <= EXCERPT_WIDTH) return text;

package/src/render.mjs

@@ -501,7 +501,8 @@ function _renderCheck(index, opts = {}) {
   if (index.errors.length > 0) {
     lines.push(red('Errors'));
     for (const issue of index.errors) {
-      lines.push(`- ${issue.path}: ${issue.message}`);
+      // Repo-level findings (e.g. the scan floor) carry no path.
+      lines.push(issue.path ? `- ${issue.path}: ${issue.message}` : `- ${issue.message}`);
     }
     lines.push('');
     const actions = renderManualFixes({ errors: index.errors, warnings: [] }).trimEnd();

package/src/validate.mjs

@@ -703,3 +703,34 @@ export function computeChecklistCompletionRate(checklist) {
   if (!checklist.total) return null;
   return Number((checklist.completed / checklist.total).toFixed(4));
 }
+
+// A floor under the scan surface.
+//
+// Every other check in this file asks "is this doc wrong?" — none of them can ask
+// "did we look at anything?". If the scan surface breaks (a root that stopped
+// resolving, a config edit that narrowed the tree, a rename that moved docs/ out
+// from under us), `dotmd check` reports zero errors, and that output is
+// byte-identical to a clean estate. A guard's whole failure mode is going quiet,
+// and this is the one that would go quiet silently.
+//
+// Off unless `minDocs` is configured — a floor is a claim about YOUR corpus size
+// and dotmd cannot guess it. Deliberately an error, not a warning: a warning exits
+// 0, which is the exact outcome this exists to prevent.
+export function applyScanFloor(index, config, { scoped = false } = {}) {
+  const floor = config?.minDocs;
+  if (!floor) return index;
+  // A path-scoped check (`dotmd check docs/plans/x.md`) is a deliberate subset, so
+  // the floor would fire on every single-file check. Not a corpus claim at all.
+  if (scoped) return index;
+  if (index.docs.length >= floor) return index;
+
+  index.errors.push({
+    path: null,
+    level: 'error',
+    message: `only ${index.docs.length} docs in the scan surface (expected at least ${floor}) — `
+      + 'the file list broke, so a pass here would mean nothing. Check `root`/`excludeDirs` in '
+      + 'your config, or lower `minDocs` if the corpus genuinely shrank.',
+    meta: { kind: 'scan-floor', found: index.docs.length, floor },
+  });
+  return index;
+}