dotmd-cli 0.76.4 → 0.76.6

package/package.json

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

package/src/body-link.mjs

@@ -0,0 +1,40 @@
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+function isWithin(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+// Markdown body links are filesystem paths relative to the document that
+// contains them. They deliberately do not inherit frontmatter references'
+// repo-root fallback: that fallback can make a broken Markdown link look valid.
+export function resolveBodyLinkTarget(href, docDir, repoRoot) {
+  if (!href) return { ok: false, reason: 'missing' };
+
+  const root = path.resolve(repoRoot);
+  const candidate = path.resolve(docDir, href);
+  if (!isWithin(root, candidate)) return { ok: false, reason: 'outside-repo' };
+  if (!existsSync(candidate)) return { ok: false, reason: 'missing' };
+
+  let canonicalRoot;
+  let canonicalTarget;
+  try {
+    canonicalRoot = realpathSync(root);
+    canonicalTarget = realpathSync(candidate);
+  } catch {
+    return { ok: false, reason: 'unreadable' };
+  }
+  if (!isWithin(canonicalRoot, canonicalTarget)) return { ok: false, reason: 'outside-repo' };
+
+  try {
+    const stat = statSync(canonicalTarget);
+    if (!stat.isFile() && !stat.isDirectory()) return { ok: false, reason: 'unsupported-target' };
+  } catch {
+    return { ok: false, reason: 'unreadable' };
+  }
+  // Return the authored lexical route after using the canonical route only for
+  // containment. Callers index documents by their repo-relative spelling (and
+  // may intentionally include an in-repo symlink alias).
+  return { ok: true, path: candidate, realPath: canonicalTarget };
+}

package/src/extractors.mjs

@@ -53,16 +53,28 @@ export function extractBodyLinks(body) {
     .replace(/^```[\s\S]*?^```/gm, '')
     .replace(/`[^`]+`/g, match => 'x'.repeat(match.length));
   const links = [];
-  // Match [text](path.md) or [text](path.md#anchor), skip images (preceded by !)
-  const regex = /(?<!!)\[([^\]]+)\]\(([^)]+\.md(?:#[^)]*)?)\)/g;
+  // Supported inline destinations are a whitespace-free token (with Markdown
+  // backslash escapes) or an angle-bracket destination, plus an optional
+  // quoted/parenthesized title. Reference links, HTML links, and nested
+  // unescaped parentheses remain deliberately outside this lightweight parser.
+  const regex = /(?<!!)\[([^\]\n]+)\]\(\s*(<[^>\n]+>|(?:\\.|[^\s()])+)(?:\s+(?:"[^"\n]*"|'[^'\n]*'|\([^\n)]*\)))?\s*\)/g;
   let match;
   while ((match = regex.exec(stripped)) !== null) {
-    const href = match[2];
-    // Skip external URLs
-    if (/^https?:\/\//i.test(href)) continue;
-    // Strip anchor fragment for path resolution
-    const cleanHref = href.replace(/#.*$/, '');
-    links.push({ text: match[1], href: cleanHref });
+    const destination = match[2];
+    const angle = destination.startsWith('<') && destination.endsWith('>');
+    const rawHref = angle ? destination.slice(1, -1) : destination;
+    // These destinations are meaningful to a renderer or another application,
+    // not portable repo-local filesystem targets.
+    if (/^(?:#|\/|[a-z][a-z\d+.-]*:)/i.test(rawHref)) continue;
+
+    const rawPath = rawHref.replace(/[?#].*$/, '');
+    if (!rawPath) continue;
+    const unescaped = rawPath.replace(/\\([\s()[\]<>])/g, '$1');
+    let href;
+    try { href = decodeURIComponent(unescaped); }
+    catch { href = unescaped; }
+    const targetKind = /\.md$/i.test(href) ? 'document' : 'file';
+    links.push({ text: match[1], rawHref, href, targetKind, angle });
   }
   return links;
 }

package/src/fix-refs.mjs

@@ -102,7 +102,9 @@ export function fixBrokenRefs(config, opts = {}) {
 
   for (const doc of index.docs) {
     const brokenBodyWarnings = doc.warnings.filter(w =>
-      w.message.startsWith('body link') && w.message.includes('does not resolve')
+      w.meta?.kind === 'body-link-resolution'
+        && w.meta?.targetKind === 'document'
+        && w.meta?.reason === 'missing'
     );
     if (!brokenBodyWarnings.length) continue;
 
@@ -112,12 +114,14 @@ export function fixBrokenRefs(config, opts = {}) {
     let newBody = body;
     const docDir = path.dirname(absPath);
     const bodyFixes = [];
+    const seenBodyTargets = new Set();
 
     for (const warn of brokenBodyWarnings) {
-      const match = warn.message.match(/body link `([^`]+)` does not resolve/);
-      if (!match) continue;
-
-      const brokenHref = match[1];
+      const brokenHref = warn.meta.relPath;
+      const rawHref = warn.meta.rawHref ?? brokenHref;
+      const targetKey = `${warn.meta.angle ? 'angle' : 'plain'}:${rawHref}`;
+      if (seenBodyTargets.has(targetKey)) continue;
+      seenBodyTargets.add(targetKey);
       const brokenBasename = path.basename(brokenHref);
 
       if (duplicateBasenames.has(brokenBasename)) continue;
@@ -127,14 +131,21 @@ export function fixBrokenRefs(config, opts = {}) {
       const correctHref = path.relative(docDir, resolved).split(path.sep).join('/');
       if (correctHref === brokenHref) continue;
 
+      const suffixAt = rawHref.search(/[?#]/);
+      const suffix = suffixAt === -1 ? '' : rawHref.slice(suffixAt);
+      const renderedHref = warn.meta.angle
+        ? `<${correctHref}${suffix}>`
+        : `${correctHref.replace(/([\s()[\]<>])/g, '\\$1')}${suffix}`;
       const linkRegex = new RegExp(
-        '(?<!!)\\[([^\\]]+)\\]\\(' + escapeRegex(brokenHref) + '(#[^)]*)?\\)',
+        '(\\]\\(\\s*)' + (warn.meta.angle ? '<' : '') + escapeRegex(rawHref) + (warn.meta.angle ? '>' : '') + '(?=\\s|\\))',
         'g'
       );
-      newBody = newBody.replace(linkRegex, (_, text, anchor) =>
-        `[${text}](${correctHref}${anchor ?? ''})`
-      );
-      bodyFixes.push({ brokenHref, correctHref });
+      let replacements = 0;
+      newBody = newBody.replace(linkRegex, (_, prefix) => {
+        replacements++;
+        return `${prefix}${renderedHref}`;
+      });
+      for (let i = 0; i < replacements; i++) bodyFixes.push({ brokenHref, correctHref });
     }
 
     if (bodyFixes.length > 0 && newBody !== body) {

package/src/hub-membership.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { extractFrontmatter } from './frontmatter.mjs';
 import { resolveRefPath, toRepoPath } from './util.mjs';
 import { detectBodyRunlistRefs, isHubDoc } from './hub.mjs';
+import { resolveBodyLinkTarget } from './body-link.mjs';
 
 // Membership drift: a hub's list of children and the plans that claim it via
 // `parent_plan:` are two halves of one relationship, and either half can go
@@ -41,7 +42,8 @@ export function checkHubMembershipDrift(docs, config) {
   const warnings = [];
   // Per-doc: warning suppression is type-scoped, so a status name quiet for one
   // type stays loud for another that declared the same name.
-  const quiet = (d) => config.lifecycle?.terminalStatuses?.has(d.status)
+  const quiet = (d) => (config.lifecycle?.isTerminal?.(d.status, d.type)
+      ?? config.lifecycle?.terminalStatuses?.has(d.status))
     || config.lifecycle?.skipsWarnings(d.status, d.type);
   const byPath = new Map(docs.map(doc => [doc.path, doc]));
   const refFields = [
@@ -54,6 +56,11 @@ export function checkHubMembershipDrift(docs, config) {
     const abs = resolveRefPath(String(ref).replace(/#.*$/, ''), dir, config.repoRoot);
     return abs ? byPath.get(toRepoPath(abs, config.repoRoot)) ?? null : null;
   };
+  const resolveBody = (link, dir) => {
+    if (link.targetKind && link.targetKind !== 'document') return null;
+    const result = resolveBodyLinkTarget(link.href, dir, config.repoRoot);
+    return result.ok ? byPath.get(toRepoPath(result.path, config.repoRoot)) ?? null : null;
+  };
 
   // Everything a hub says about other docs: every configured reference field
   // plus every body link. Config-driven rather than a hardcoded field list, so a
@@ -68,7 +75,7 @@ export function checkHubMembershipDrift(docs, config) {
       }
     }
     for (const link of (hub.bodyLinks ?? [])) {
-      const target = resolve(link.href, dir);
+      const target = resolveBody(link, dir);
       if (target) known.add(target.path);
     }
     return known;

package/src/prompts.mjs

@@ -118,7 +118,7 @@ function findPromptTarget(promptDoc, config) {
   }
 
   const links = promptDoc.bodyLinks ?? [];
-  const mdLink = links.find(l => /\.md(?:#|$)/.test(l.href ?? ''));
+  const mdLink = links.find(l => l.targetKind === 'document');
   if (mdLink) return resolveBodyLink(mdLink.href, promptDoc.path);
   return null;
 }

package/src/render.mjs

@@ -454,7 +454,13 @@ export function classifyIssueAction(issue) {
   if (/`modules` is required/.test(message)) {
     return { action: `edit ${file} modules: or run dotmd lint --fix if scaffolded empty`, fixable: false, label: 'module metadata' };
   }
-  if (/entry `.*` does not resolve|body link `.*` does not resolve/.test(message)) {
+  if (issue?.meta?.kind === 'body-link-resolution') {
+    if (issue.meta.targetKind === 'document' && issue.meta.reason === 'missing') {
+      return { action: 'dotmd fix-refs --dry-run', fixable: true, label: 'document links' };
+    }
+    return { action: `edit ${file}: correct the linked file, asset, or directory`, fixable: false, label: 'file links' };
+  }
+  if (/entry `.*` does not resolve/.test(message)) {
     return { action: 'dotmd fix-refs --dry-run', fixable: true, label: 'references' };
   }
 

package/src/sync-status.mjs

@@ -1,9 +1,10 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, normalizeEol } from './frontmatter.mjs';
-import { die, isArchivedPath, resolveRefPath, toRepoPath } from './util.mjs';
+import { die, isArchivedPath, toRepoPath } from './util.mjs';
 import { cyan, dim, green, red, yellow } from './color.mjs';
 import { authorizeManagedSweep } from './managed-path.mjs';
+import { resolveBodyLinkTarget } from './body-link.mjs';
 import {
   MARKER_CLOSE,
   MARKER_OPEN,
@@ -21,8 +22,8 @@ import {
 // dotmd already reads those rows to compute next-pickup, so the guard is
 // standing next to the data it needs. Everything it needs is already owned:
 // `config.types[<type>].statuses` for the vocabulary (type-aware, so a `doc`
-// rowed in a plan hub is judged by the doc vocabulary), `resolveRefPath` for
-// the link (case-fold-aware), the index for the child's real status, and
+// rowed in a plan hub is judged by the doc vocabulary), the strict Markdown
+// body-link resolver, the index for the child's real status, and
 // archive-dir-outranks-frontmatter for archived children.
 //
 // The three-way split below is the part that is easy to get wrong. A row with
@@ -79,7 +80,7 @@ function truncate(text, max = 60) {
 // for that hub by name, so the noise-control rule doesn't apply).
 export function collectHubStatusRows(docs, config, { hubPaths = null } = {}) {
   const docByPath = new Map(docs.map(doc => [doc.path, doc]));
-  // `resolveRefPath` is case-fold-aware, so on a case-folding filesystem a row
+  // The filesystem resolver is case-fold-aware, so on a case-folding filesystem a row
   // linking `BILLING-A.md` resolves to the file that is indexed as
   // `billing-a.md` — a path string the exact map can't answer. Fold as a
   // fallback, and only when the fold is unambiguous: on a case-SENSITIVE
@@ -91,7 +92,8 @@ export function collectHubStatusRows(docs, config, { hubPaths = null } = {}) {
   }
   // Per-doc: warning suppression is type-scoped, so a status name quiet for one
   // type stays loud for another that declared the same name.
-  const quiet = (d) => config.lifecycle?.terminalStatuses?.has(d.status)
+  const quiet = (d) => (config.lifecycle?.isTerminal?.(d.status, d.type)
+      ?? config.lifecycle?.terminalStatuses?.has(d.status))
     || config.lifecycle?.skipsWarnings(d.status, d.type);
   const out = [];
 
@@ -108,11 +110,11 @@ export function collectHubStatusRows(docs, config, { hubPaths = null } = {}) {
     const rows = [];
     for (const row of scanHubStatusRows(body)) {
       const href = row.ref.replace(/#.*$/, '');
-      const abs = resolveRefPath(href, hubDir, config.repoRoot);
+      const resolution = resolveBodyLinkTarget(href, hubDir, config.repoRoot);
       // A row whose link is broken is already a body-link finding. Reporting it
       // again as unreadable status would double-report one problem.
-      if (!abs) continue;
-      const repoPath = toRepoPath(abs, config.repoRoot);
+      if (!resolution.ok) continue;
+      const repoPath = toRepoPath(resolution.path, config.repoRoot);
       const target = docByPath.get(repoPath) ?? docByFoldedPath.get(repoPath.toLowerCase()) ?? null;
       if (!target || target.path === hub.path) continue;
       const actual = effectiveStatus(target, config);

package/src/validate.mjs

@@ -3,6 +3,7 @@ import { asString, resolveRefPath, suggestCandidates } from './util.mjs';
 import { getGitLastModified, getGitLastModifiedBatch, getGitLastSubstantiveModifiedBatch } from './git.mjs';
 import { toRepoPath } from './util.mjs';
 import { detectMarker, isPhaseHeading, phaseMarkerConflict, walkSections } from './section.mjs';
+import { resolveBodyLinkTarget } from './body-link.mjs';
 
 const NOW = new Date();
 
@@ -262,29 +263,39 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
   const skipRefValidation = config.lifecycle.isTerminal?.(doc.status, doc.type)
     ?? config.lifecycle.terminalStatuses.has(doc.status);
   if (!skipRefValidation) {
-    const compatibilityWarning = config.lifecycle.skipsWarnings(doc.status, doc.type);
     for (const field of allRefFields) {
       for (const relPath of (doc.refFields[field] || [])) {
         if (!resolveRefPath(relPath, docDir, config.repoRoot)) {
-          const issue = {
+          doc.errors.push({
             path: doc.path,
-            level: compatibilityWarning ? 'warning' : 'error',
+            level: 'error',
             message: `${field} entry \`${relPath}\` does not resolve to an existing file.`,
-            meta: { kind: compatibilityWarning ? 'ref-resolution-compat' : 'ref-resolution', field, relPath },
-          };
-          (compatibilityWarning ? doc.warnings : doc.errors).push(issue);
+            meta: { kind: 'ref-resolution', field, relPath },
+          });
         }
       }
     }
 
     // Validate body links resolve to existing files
     for (const link of (doc.bodyLinks || [])) {
-      if (!resolveRefPath(link.href, docDir, config.repoRoot)) {
+      const resolution = resolveBodyLinkTarget(link.href, docDir, config.repoRoot);
+      if (!resolution.ok) {
+        const shownHref = link.rawHref ?? link.href;
         doc.warnings.push({
           path: doc.path,
           level: 'warning',
-          message: `body link \`${link.href}\` does not resolve to an existing file.`,
-          meta: { kind: 'ref-resolution', field: 'body-link', relPath: link.href },
+          message: resolution.reason === 'outside-repo'
+            ? `body link \`${shownHref}\` escapes the repository.`
+            : `body link \`${shownHref}\` does not resolve to an existing file or directory.`,
+          meta: {
+            kind: 'body-link-resolution',
+            field: 'body-link',
+            relPath: link.href,
+            rawHref: shownHref,
+            targetKind: link.targetKind ?? 'document',
+            angle: link.angle === true,
+            reason: resolution.reason,
+          },
         });
       }
     }
@@ -328,7 +339,9 @@ function candidatePathsForType(docs, type) {
 // name implies one (e.g. `related_plans` → plans only).
 export function enrichRefErrorSuggestions(docs, config) {
   const enrich = (entry) => {
-    if (!entry?.meta || !['ref-resolution', 'ref-resolution-compat'].includes(entry.meta.kind)) return;
+    if (!entry?.meta || !['ref-resolution', 'body-link-resolution'].includes(entry.meta.kind)) return;
+    if (entry.meta.kind === 'body-link-resolution'
+      && (entry.meta.targetKind !== 'document' || entry.meta.reason !== 'missing')) return;
     if (entry._suggested) return;
     const inferred = inferRefFieldType(entry.meta.field);
     const candidates = candidatePathsForType(docs, inferred);