dotmd-cli 0.71.3 → 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.3",
+  "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/reference-planner.mjs

@@ -1,10 +1,21 @@
-import { realpathSync } from 'node:fs';
+import { realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter } from './frontmatter.mjs';
 
 function slash(value) { return value.split(path.sep).join('/'); }
 
-function canonicalExisting(filePath) {
+function canonicalExisting(filePath, memo = null) {
+  const key = memo ? path.resolve(filePath) : null;
+  if (memo) {
+    const hit = memo.get(key);
+    if (hit !== undefined) return hit;
+  }
+  const identity = resolveCanonical(filePath);
+  if (memo) memo.set(key, identity);
+  return identity;
+}
+
+function resolveCanonical(filePath) {
   try { return realpathSync(filePath); }
   catch {
     const suffix = [];
@@ -36,31 +47,118 @@ export function configuredReferenceFields(config) {
   ])];
 }
 
+// Marks a case fold shared by two corpus documents. On a case-sensitive
+// filesystem those are genuinely two files, and nothing may collapse them.
+const AMBIGUOUS_FOLD = Symbol('ambiguous case fold');
+
+// The set carries four indexes beside the identities themselves:
+//   canonical — memoized path resolution. Resolving one reference costs two
+//     `canonicalExisting` calls, and the repository-relative spelling usually
+//     does NOT exist, which sends it up the tree doing a realpath per ancestor.
+//     Over a corpus-wide sweep that is tens of thousands of syscalls across a
+//     few hundred distinct paths, and it dominated the reference rewrite. The
+//     memo lives here so it is scoped to one sweep and cannot outlive a
+//     mutation — `dotmd bulk` builds a fresh set per move. Within a sweep it is
+//     also more consistent than re-resolving per token, which could observe the
+//     filesystem changing midway.
+//   paths     — identity to the spelling the corpus used.
+//   names     — identity to every basename it answers to (symlink aliases).
+//   folded    — case fold to identity, for filesystems that fold case.
 export function createReferenceIdentitySet(filePaths) {
   const identities = new Set();
   identities.paths = new Map();
-  for (const filePath of filePaths) {
-    const identity = canonicalExisting(filePath);
-    identities.add(identity);
-    identities.paths.set(identity, path.resolve(filePath));
-  }
+  identities.canonical = new Map();
+  identities.names = new Map();
+  identities.folded = new Map();
+  identities.symlinked = false;
+  for (const filePath of filePaths) registerIdentity(identities, filePath);
   return identities;
 }
 
+function registerIdentity(identities, filePath) {
+  const resolved = path.resolve(filePath);
+  const identity = canonicalExisting(filePath, identities.canonical);
+  // A corpus path whose realpath differs is a symlink, so one document can be
+  // reachable under more than one name. `names` records every one of them —
+  // and `symlinked` warns the candidate prefilter that names are not a
+  // reliable signal in this repo at all.
+  if (identity !== resolved) identities.symlinked = true;
+  identities.add(identity);
+  identities.paths.set(identity, resolved);
+  let names = identities.names.get(identity);
+  if (!names) identities.names.set(identity, names = new Set());
+  names.add(path.basename(resolved).toLowerCase());
+  const key = identity.toLowerCase();
+  const seen = identities.folded.get(key);
+  identities.folded.set(key, seen === undefined || seen === identity ? identity : AMBIGUOUS_FOLD);
+  return identity;
+}
+
+// Can this document possibly hold a reference to `oldIdentity`? Every token the
+// rewriter will touch has to survive `/\.md$/i` and then resolve to the moved
+// file, so the document must spell one of that file's names somewhere. Checking
+// that first skips the fence-aware walk for the ~99% of a corpus that never
+// mentions the file — the measured difference on a 2,000-doc repo is 950ms of
+// rewriting versus 120ms.
+//
+// The comparison mirrors the resolver: case-folded (a case-insensitive
+// filesystem resolves `FOO.MD` to `foo.md`, and folding can only over-include),
+// and with the same backslash escapes unwound, so `my\ plan.md` still matches
+// `my plan.md`. Percent-encoding needs no handling — the resolver does not
+// decode it either, so `foo%20bar.md` never resolves in the first place.
+//
+// The boundary: a symlink whose name differs from its target's. Aliases inside
+// the corpus are covered by `names`; a symlink that is NOT itself a collected
+// doc is not, so any repo that symlinks docs at all fails open to the full walk.
+function mayReferenceIdentity(content, oldIdentity, oldPath, identities) {
+  if (!identities?.names || identities.symlinked) return true;
+  const names = identities.names.get(oldIdentity);
+  const haystack = (content.includes('\\') ? content.replace(/\\([\s()[\]<>])/g, '$1') : content).toLowerCase();
+  if (haystack.includes(path.basename(oldPath).toLowerCase())) return true;
+  if (names) for (const name of names) if (haystack.includes(name)) return true;
+  return false;
+}
+
 // Both interpretations are evaluated. A local document wins only when the
 // repo-relative spelling is absent or names the same identity; disagreement is
 // rejected rather than guessed.
 export function resolveReferenceIdentity(token, documentPath, repoRoot, identities) {
   if (!token || /^(?:[a-z][a-z\d+.-]*:|\/\/|#)/i.test(token)) return null;
   const clean = token.replace(/[?#].*$/, '').replace(/\\([\s()[\]<>])/g, '$1');
-  const local = canonicalExisting(path.resolve(path.dirname(documentPath), clean));
-  const repository = canonicalExisting(path.resolve(repoRoot, clean.replace(/^\/+/, '')));
-  const localExists = identities.has(local);
-  const repositoryExists = identities.has(repository);
-  if (localExists && repositoryExists && local !== repository) {
+  const memo = identities?.canonical ?? null;
+  const local = matchIdentity(canonicalExisting(path.resolve(path.dirname(documentPath), clean), memo), identities);
+  const repository = matchIdentity(canonicalExisting(path.resolve(repoRoot, clean.replace(/^\/+/, '')), memo), identities);
+  if (local && repository && local !== repository) {
     throw new AmbiguousReferenceError(token, documentPath, local, repository);
   }
-  return localExists ? local : (repositoryExists ? repository : null);
+  return local ?? repository ?? null;
+}
+
+// `realpath` resolves symlinks but NOT case: on a case-insensitive filesystem
+// `realpath("CASING.MD")` hands back the caller's spelling, so an exact compare
+// misses a link that names a real document. Validation disagreed — it resolves
+// with `existsSync`, which does not care about case — so `dotmd check` called
+// such a link fine, a move silently left it pointing at the old path, and only
+// THEN did check call it broken.
+//
+// The tie-break is the inode, not a guess about the filesystem: same device and
+// inode means the two spellings are one file, which is only ever true where the
+// filesystem itself folds case. On a case-sensitive filesystem `Foo.md` and
+// `foo.md` are separate inodes and stay separate here, and two corpus documents
+// that differ only by case poison their shared fold so neither is guessed at.
+function matchIdentity(candidate, identities) {
+  if (identities.has(candidate)) return candidate;
+  const folded = identities.folded?.get(candidate.toLowerCase());
+  if (folded === undefined || folded === AMBIGUOUS_FOLD) return null;
+  return sameFileOnDisk(candidate, folded) ? folded : null;
+}
+
+function sameFileOnDisk(left, right) {
+  try {
+    const a = statSync(left);
+    const b = statSync(right);
+    return a.dev === b.dev && a.ino === b.ino && a.ino !== 0;
+  } catch { return false; }
 }
 
 function rewriteToken(token, sourcePath, outputPath, repoRoot, identities, oldIdentity, newPath, rebaseAll, format = 'plain') {
@@ -264,7 +362,10 @@ export function rewriteDocumentReferences(content, {
 }) {
   const { frontmatter, body } = extractFrontmatter(content);
   if (!frontmatter) return content;
-  const oldIdentity = canonicalExisting(oldPath);
+  const oldIdentity = canonicalExisting(oldPath, identities?.canonical ?? null);
+  // `rebaseAll` rewrites every reference the document holds because the
+  // document itself moved, so no single name can gate it.
+  if (!rebaseAll && !mayReferenceIdentity(content, oldIdentity, oldPath, identities)) return content;
   const args = [sourcePath, outputPath, repoRoot, identities, oldIdentity, newPath, rebaseAll];
   const nextFrontmatter = rewriteFrontmatter(frontmatter, referenceFields, args);
   const nextBody = rewriteMarkdown(body, args);
@@ -273,8 +374,9 @@ export function rewriteDocumentReferences(content, {
 
 export function planReferenceMove({ documents, oldPath, newPath, repoRoot, referenceFields = [] }) {
   const identities = createReferenceIdentitySet(documents.map(document => document.path));
-  const oldIdentity = canonicalExisting(oldPath);
-  identities.add(oldIdentity);
+  // Register rather than bare-add: the case fold and name index have to know
+  // about the moved document too, or a differently-cased link to it misses.
+  const oldIdentity = registerIdentity(identities, oldPath);
   const source = documents.find(document => path.resolve(document.path) === path.resolve(oldPath));
   if (!source) throw new Error(`Reference move plan is missing source content: ${oldPath}`);
   const movedContent = rewriteDocumentReferences(source.content, {

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;
+}