dotmd-cli 0.36.3 → 0.37.0

package/bin/dotmd.mjs

@@ -41,7 +41,7 @@ Analyze:
 
 Validate & Fix:
   check [--fix] [--errors-only] [--json]  Validate frontmatter and references
-  doctor [--dry-run]                Auto-fix everything: refs, lint, dates, index
+  doctor [--apply]                  Auto-fix everything: refs, lint, dates, index (preview by default)
   lint [--fix]                      Check and auto-fix frontmatter issues
   fix-refs [--dry-run]              Auto-fix broken reference paths + body links
 
@@ -204,6 +204,11 @@ Options:
   --errors-only          Show only errors, suppress warnings
   --fix                  Auto-fix broken refs, lint issues, and regenerate index
   --json                 Output errors and warnings as JSON
+  --no-collapse          Show every warning per-doc (since 0.37.0, high-frequency
+                         auto-fixable warning categories — singular module/surface
+                         deprecations, updated-behind-git — are collapsed into a
+                         one-line summary with the bulk-fix command). --json output
+                         is unchanged regardless.
   --dry-run, -n          Preview fixes without writing (with --fix)`,
 
   archive: `dotmd archive <file> — archive a document
@@ -342,7 +347,10 @@ Runs in sequence: fix broken references, lint --fix, sync dates from
 git, regenerate index, then show remaining issues.
 
 Modes:
-  (default)              Auto-fix pass (writes by default; honors --dry-run)
+  (default)              Auto-fix pass — previews by default since 0.37.0
+                         (F4). Use --apply (alias --yes) to actually write;
+                         explicit --dry-run still wins over --apply if both
+                         are passed (safety prevails).
   --statuses             Read-only diagnostic: detect overloaded status
                          buckets where one status holds plans pursuing
                          multiple distinct unstuck-actions. Suggests how
@@ -374,7 +382,9 @@ Modes:
                          in their Version History would be misleading).
   --migrate-template --json  Machine-readable result.
 
-Use --dry-run (-n) to preview all changes without writing anything.`,
+--apply (or --yes) opts into writes for the default auto-fix pass.
+Sub-modes (--statuses, --migrate-*) keep their existing contracts:
+they write by default and honor --dry-run.`,
 
   'fix-refs': `dotmd fix-refs — auto-fix broken reference paths
 
@@ -871,7 +881,22 @@ async function main() {
   if (command === 'rename') { const { runRename } = await import('../src/rename.mjs'); await runRename(restArgs, config, { dryRun }); return; }
   if (command === 'migrate') { const { runMigrate } = await import('../src/migrate.mjs'); runMigrate(restArgs, config, { dryRun }); return; }
   if (command === 'fix-refs') { const { runFixRefs } = await import('../src/fix-refs.mjs'); runFixRefs(restArgs, config, { dryRun }); return; }
-  if (command === 'doctor') { const { runDoctor } = await import('../src/doctor.mjs'); runDoctor(restArgs, config, { dryRun }); return; }
+  if (command === 'doctor') {
+    // 0.37.0 (F4): the default auto-fix loop previews by default; --apply
+    // (alias --yes) writes. Explicit --dry-run still works and wins over
+    // --apply (safety prevails). The F4 flip applies ONLY to the default
+    // auto-fix path — sub-modes (--statuses, --migrate-template,
+    // --migrate-prompts) keep their existing "write unless --dry-run"
+    // contract because they're explicit one-shots the user opted into.
+    const subMode = args.includes('--statuses') || args.includes('--migrate-template') || args.includes('--migrate-prompts');
+    const explicitApply = args.includes('--apply') || args.includes('--yes');
+    const explicitDryRun = args.includes('--dry-run') || args.includes('-n');
+    const doctorDryRun = subMode ? dryRun : (explicitDryRun || !explicitApply);
+    const filtered = restArgs.filter(a => a !== '--apply' && a !== '--yes');
+    const { runDoctor } = await import('../src/doctor.mjs');
+    runDoctor(filtered, config, { dryRun: doctorDryRun });
+    return;
+  }
   if (command === 'statuses') { const { runStatuses } = await import('../src/statuses.mjs'); await runStatuses(restArgs, config, { dryRun, type: typeArg }); return; }
 
   // All remaining commands need the index + render modules
@@ -931,6 +956,7 @@ async function main() {
   if (command === 'check') {
     const fix = args.includes('--fix');
     const errorsOnly = args.includes('--errors-only');
+    const noCollapse = args.includes('--no-collapse');
 
     if (fix) {
       // Auto-fix: broken refs, then lint, then rebuild index
@@ -961,7 +987,7 @@ async function main() {
           passed: freshIndex.errors.length === 0,
         }, null, 2) + '\n');
       } else {
-        process.stdout.write('\n' + renderCheck(freshIndex, config, { errorsOnly }));
+        process.stdout.write('\n' + renderCheck(freshIndex, config, { errorsOnly, noCollapse }));
       }
       if (freshIndex.errors.length > 0) process.exitCode = 1;
       return;
@@ -980,7 +1006,7 @@ async function main() {
       return;
     }
 
-    process.stdout.write(renderCheck(index, config, { errorsOnly }));
+    process.stdout.write(renderCheck(index, config, { errorsOnly, noCollapse }));
     if (index.errors.length > 0) process.exitCode = 1;
     return;
   }

package/package.json

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

package/src/check-collapse.mjs

@@ -0,0 +1,75 @@
+// F13 (0.37.0): collapse high-frequency auto-fixable `dotmd check` warnings
+// into one-line remediation hints. Without this, bulk-fixable noise (43
+// `updated behind git history`, N singular-key deprecations) drowns out
+// structural findings in the per-doc list — and forces the reader to
+// reconstruct the fix command per category.
+//
+// Each category names the message regex to match, a short label for the
+// summary line, and the exact `dotmd …` command that bulk-fixes it.
+
+const COLLAPSE_THRESHOLD = 3;
+
+const CATEGORIES = [
+  {
+    key: 'updated-behind-git',
+    match: /^frontmatter `updated:.*` is behind git history/,
+    label: 'docs have `updated` behind git history',
+    fix: 'dotmd touch --git',
+  },
+  {
+    key: 'singular-module',
+    match: /^`module:` \(singular\) is deprecated/,
+    label: 'docs use deprecated singular `module:`',
+    fix: 'dotmd lint --fix',
+  },
+  {
+    key: 'singular-surface',
+    match: /^`surface:` \(singular\) is deprecated/,
+    label: 'docs use deprecated singular `surface:`',
+    fix: 'dotmd lint --fix',
+  },
+];
+
+function categoryFor(message) {
+  for (const cat of CATEGORIES) {
+    if (cat.match.test(message)) return cat;
+  }
+  return null;
+}
+
+// Split warnings into per-doc passthrough lines and collapsed summary buckets.
+// A category that hits ≥COLLAPSE_THRESHOLD warnings is summarized; below the
+// threshold each warning falls through as a normal per-doc line (small counts
+// don't gain from collapse and lose path information).
+export function categorizeWarnings(warnings) {
+  const buckets = new Map();
+  const orphans = [];
+
+  for (const w of warnings) {
+    const cat = categoryFor(w.message);
+    if (!cat) {
+      orphans.push(w);
+      continue;
+    }
+    if (!buckets.has(cat.key)) buckets.set(cat.key, { cat, items: [] });
+    buckets.get(cat.key).items.push(w);
+  }
+
+  const collapsed = [];
+  const passthrough = [...orphans];
+
+  for (const { cat, items } of buckets.values()) {
+    if (items.length >= COLLAPSE_THRESHOLD) {
+      collapsed.push({ key: cat.key, label: cat.label, fix: cat.fix, count: items.length });
+    } else {
+      passthrough.push(...items);
+    }
+  }
+
+  passthrough.sort((a, b) => a.path.localeCompare(b.path));
+  collapsed.sort((a, b) => b.count - a.count || a.key.localeCompare(b.key));
+
+  return { passthrough, collapsed };
+}
+
+export const _internalForTest = { COLLAPSE_THRESHOLD, CATEGORIES };

package/src/doctor.mjs

@@ -53,7 +53,12 @@ export function runDoctor(argv, config, opts = {}) {
   }
 
   const { dryRun } = opts;
-  process.stdout.write(bold('dotmd doctor') + '\n\n');
+  // 0.37.0 (F4): the mode banner makes it impossible to mistake a preview run
+  // for a real one — and tells the user the exact flag that flips it.
+  const modeNote = dryRun
+    ? dim('[preview — run with --apply to write]')
+    : dim('[applying changes]');
+  process.stdout.write(bold('dotmd doctor') + ' ' + modeNote + '\n\n');
 
   // Step 1: Fix broken references
   process.stdout.write(bold('1. Fixing broken references...') + '\n');

package/src/render.mjs

@@ -5,6 +5,7 @@ import { extractFrontmatter } from './frontmatter.mjs';
 import { summarizeDocBody } from './ai.mjs';
 import { bold, red, yellow, green, dim } from './color.mjs';
 import { findStaleLeases } from './lease.mjs';
+import { categorizeWarnings } from './check-collapse.mjs';
 
 // Render `currentState` with an `(auto)` prefix when the value was body-scraped
 // rather than read from frontmatter. Lets a reader see at a glance which docs
@@ -376,7 +377,7 @@ export function renderCheck(index, config, opts = {}) {
 }
 
 function _renderCheck(index, opts = {}) {
-  const { errorsOnly } = opts;
+  const { errorsOnly, noCollapse } = opts;
   const lines = ['Check', ''];
   lines.push(`- docs scanned: ${index.docs.length}`);
   lines.push(`- errors: ${index.errors.length}`);
@@ -393,8 +394,18 @@ function _renderCheck(index, opts = {}) {
 
   if (!errorsOnly && index.warnings.length > 0) {
     lines.push(yellow('Warnings'));
-    for (const issue of index.warnings) {
-      lines.push(`- ${issue.path}: ${issue.message}`);
+    if (noCollapse) {
+      for (const issue of index.warnings) {
+        lines.push(`- ${issue.path}: ${issue.message}`);
+      }
+    } else {
+      const { passthrough, collapsed } = categorizeWarnings(index.warnings);
+      for (const issue of passthrough) {
+        lines.push(`- ${issue.path}: ${issue.message}`);
+      }
+      for (const sum of collapsed) {
+        lines.push(`- ${sum.count} ${sum.label} — run \`${sum.fix}\` to bulk-fix`);
+      }
     }
     lines.push('');
   }