dotmd-cli 0.32.0 → 0.32.1

package/package.json

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

package/src/graph.mjs

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { toSlug, toRepoPath, warn } from './util.mjs';
+import { toSlug, toRepoPath, warn, resolveRefPath } from './util.mjs';
 import { bold, red, green, dim } from './color.mjs';
 
 const STATUS_COLORS = {
@@ -60,7 +60,7 @@ export function buildGraph(index, config, filters = {}) {
 
     for (const field of allRefFields) {
       for (const relPath of (doc.refFields[field] || [])) {
-        const resolved = path.resolve(docDir, relPath);
+        const resolved = resolveRefPath(relPath, docDir, config.repoRoot) ?? path.resolve(docDir, relPath);
         const targetPath = toRepoPath(resolved, config.repoRoot);
         const edgeKey = `${doc.path}|${targetPath}|${field}`;
         if (edgeKeys.has(edgeKey)) continue;

package/src/lifecycle.mjs

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter, replaceFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, warn, resolveDocPath, escapeRegex, nowIso } from './util.mjs';
+import { asString, toRepoPath, die, warn, resolveDocPath, resolveRefPath, escapeRegex, nowIso } from './util.mjs';
 import { gitMv, getGitLastModified, getGitLastModifiedBatch } from './git.mjs';
 import { buildIndex, collectDocFiles } from './index.mjs';
 import { renderIndexFile, writeIndex } from './index-file.mjs';
@@ -717,12 +717,17 @@ function updateRefsFromMovedFile(oldPath, newPath, config) {
   let raw = readFileSync(newPath, 'utf8');
   const { frontmatter, body } = extractFrontmatter(raw);
 
-  // Fix frontmatter ref fields (YAML list items like  - ./path.md)
+  // Fix frontmatter ref fields (YAML list items like  - ./path.md).
+  // Resolve doc-relative first, then repo-root-relative — so a ref like
+  // `docs/foo/bar.md` written from any nesting level gets rewritten correctly
+  // when the source moves. Without the repo-root fallback, repo-relative refs
+  // silently skipped rewriting (existsSync on the doubled doc-relative path
+  // returned false).
   let newFm = frontmatter;
   const refRegex = /^(\s+-\s+)(\S+\.md)$/gm;
   newFm = newFm.replace(refRegex, (match, prefix, refPath) => {
-    const absTarget = path.resolve(oldDir, refPath);
-    if (!existsSync(absTarget)) return match;
+    const absTarget = resolveRefPath(refPath, oldDir, config.repoRoot);
+    if (!absTarget) return match;
     const newRelPath = path.relative(newDir, absTarget).split(path.sep).join('/');
     return `${prefix}${newRelPath}`;
   });
@@ -732,8 +737,8 @@ function updateRefsFromMovedFile(oldPath, newPath, config) {
   const linkRegex = /(\[[^\]]*\]\()([^)]+\.md)(\))/g;
   newBody = newBody.replace(linkRegex, (match, pre, href, post) => {
     if (href.startsWith('http')) return match;
-    const absTarget = path.resolve(oldDir, href);
-    if (!existsSync(absTarget)) return match;
+    const absTarget = resolveRefPath(href, oldDir, config.repoRoot);
+    if (!absTarget) return match;
     const newHref = path.relative(newDir, absTarget).split(path.sep).join('/');
     return `${pre}${newHref}${post}`;
   });

package/src/validate.mjs

@@ -106,7 +106,7 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
     doc.errors.push({ path: doc.path, level: 'error', message: '`module` is required for active/ready/planned/blocked docs; use a real module, `platform`, or `none`. Accepts singular `module:` or plural `modules:` list.' });
   }
 
-  if (config.validSurfaces) {
+  if (config.validSurfaces && !config.lifecycle.skipWarningsFor.has(doc.status)) {
     for (const surface of doc.surfaces) {
       if (!config.validSurfaces.has(surface)) {
         doc.warnings.push({ path: doc.path, level: 'warning', message: `Unknown surface \`${surface}\`; expected a known surface taxonomy value.` });
@@ -164,21 +164,28 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
     }
   }
 
-  // Validate reference fields resolve to existing files
+  // Validate reference fields resolve to existing files. Terminal statuses
+  // (archived, deprecated, etc.) document historical state — their refs may
+  // legitimately point at moved/deleted targets and shouldn't gate the
+  // exit code with a hard error.
   const docDir = path.dirname(path.join(config.repoRoot, doc.path));
   const allRefFields = [...(config.referenceFields.bidirectional || []), ...(config.referenceFields.unidirectional || [])];
-  for (const field of allRefFields) {
-    for (const relPath of (doc.refFields[field] || [])) {
-      if (!resolveRefPath(relPath, docDir, config.repoRoot)) {
-        doc.errors.push({ path: doc.path, level: 'error', message: `${field} entry \`${relPath}\` does not resolve to an existing file.` });
+  const skipRefValidation = config.lifecycle.terminalStatuses.has(doc.status)
+    || config.lifecycle.skipWarningsFor.has(doc.status);
+  if (!skipRefValidation) {
+    for (const field of allRefFields) {
+      for (const relPath of (doc.refFields[field] || [])) {
+        if (!resolveRefPath(relPath, docDir, config.repoRoot)) {
+          doc.errors.push({ path: doc.path, level: 'error', message: `${field} entry \`${relPath}\` does not resolve to an existing file.` });
+        }
       }
     }
-  }
 
-  // Validate body links resolve to existing files
-  for (const link of (doc.bodyLinks || [])) {
-    if (!resolveRefPath(link.href, docDir, config.repoRoot)) {
-      doc.warnings.push({ path: doc.path, level: 'warning', message: `body link \`${link.href}\` does not resolve to an existing file.` });
+    // Validate body links resolve to existing files
+    for (const link of (doc.bodyLinks || [])) {
+      if (!resolveRefPath(link.href, docDir, config.repoRoot)) {
+        doc.warnings.push({ path: doc.path, level: 'warning', message: `body link \`${link.href}\` does not resolve to an existing file.` });
+      }
     }
   }
 }
@@ -271,19 +278,24 @@ export function validatePlanShape(doc, body, frontmatter, config) {
     });
   }
 
-  // 3. surface AND surfaces both populated
-  if (frontmatter.surface && Array.isArray(frontmatter.surfaces) && frontmatter.surfaces.length > 0) {
+  // 3. surface AND surfaces both populated with DIVERGENT values. When the
+  // singular value is already a member of the plural array, src/index.mjs
+  // merges them transparently — warning would be noise. Only divergence
+  // actually risks data loss when readers consult one form vs. the other.
+  if (frontmatter.surface && Array.isArray(frontmatter.surfaces) && frontmatter.surfaces.length > 0
+      && !frontmatter.surfaces.includes(frontmatter.surface)) {
     doc.warnings.push({
       path: doc.path,
       level: 'warning',
-      message: 'Both `surface` (singular) and `surfaces` (array) are set. Pick one — prefer `surfaces` array form.',
+      message: `Both \`surface\` (singular: \`${frontmatter.surface}\`) and \`surfaces\` (array) are set with different values. Pick one — prefer \`surfaces\` array form.`,
     });
   }
-  if (frontmatter.module && Array.isArray(frontmatter.modules) && frontmatter.modules.length > 0) {
+  if (frontmatter.module && Array.isArray(frontmatter.modules) && frontmatter.modules.length > 0
+      && !frontmatter.modules.includes(frontmatter.module)) {
     doc.warnings.push({
       path: doc.path,
       level: 'warning',
-      message: 'Both `module` (singular) and `modules` (array) are set. Pick one — prefer `modules` array form.',
+      message: `Both \`module\` (singular: \`${frontmatter.module}\`) and \`modules\` (array) are set with different values. Pick one — prefer \`modules\` array form.`,
     });
   }