runlist 0.0.0 → 0.94.2

package/src/lint.mjs

@@ -0,0 +1,386 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter, replaceFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath, escapeRegex, warn } from './util.mjs';
+import { buildIndex, collectDocFiles } from './index.mjs';
+import { updateFrontmatter } from './lifecycle.mjs';
+import { runModel } from './ai.mjs';
+import { bold, green, yellow, dim } from './color.mjs';
+import { authorizeManagedSweep, findLexicalDocsRoot } from './managed-path.mjs';
+
+const KEY_RENAMES = {
+  nextStep: 'next_step',
+  currentState: 'current_state',
+  auditLevel: 'audit_level',
+  sourceOfTruth: 'source_of_truth',
+  relatedPlans: 'related_plans',
+  supportsPlans: 'supports_plans',
+};
+
+function frontmatterFieldBlock(frontmatter, field) {
+  const lines = frontmatter.split(/\r?\n/);
+  const fieldRe = new RegExp(`^${escapeRegex(field)}:`);
+  const start = lines.findIndex(line => fieldRe.test(line));
+  if (start < 0) return null;
+  let end = start + 1;
+  while (end < lines.length) {
+    if (/^[ \t]/.test(lines[end]) || lines[end].trim() === '') {
+      end++;
+      continue;
+    }
+    if (lines[end].trimStart().startsWith('#')) {
+      let next = end + 1;
+      while (next < lines.length && (lines[next].trim() === '' || lines[next].trimStart().startsWith('#'))) next++;
+      if (next < lines.length && /^[ \t]/.test(lines[next])) {
+        end++;
+        continue;
+      }
+    }
+    break;
+  }
+  return { lines, start, end };
+}
+
+function replaceFrontmatterFieldBlock(frontmatter, field, replacement = '') {
+  const block = frontmatterFieldBlock(frontmatter, field);
+  if (!block) return frontmatter;
+  const { lines, start, end } = block;
+  lines.splice(start, end - start, ...(replacement ? replacement.split('\n') : []));
+  return lines.join('\n');
+}
+
+function frontmatterFieldComments(frontmatter, field) {
+  const block = frontmatterFieldBlock(frontmatter, field);
+  if (!block) return [];
+  return block.lines
+    .slice(block.start + 1, block.end)
+    .map(line => line.trim())
+    .filter(line => line.startsWith('#'));
+}
+
+function isAutoFixableString(value) {
+  return typeof value === 'string' && !/(^|\s)#/.test(value);
+}
+
+function formatYamlScalar(value) {
+  return /^[A-Za-z0-9_./-]+$/.test(value) ? value : JSON.stringify(value);
+}
+
+export function runLint(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const fix = argv.includes('--fix');
+  const allFiles = collectDocFiles(config);
+  const fixable = [];
+
+  for (const filePath of allFiles) {
+    const raw = readFileSync(filePath, 'utf8');
+    const { frontmatter } = extractFrontmatter(raw);
+    if (!frontmatter) continue;
+    const parsed = parseSimpleFrontmatter(frontmatter);
+    const repoPath = toRepoPath(filePath, config.repoRoot);
+    const fixes = [];
+    const skipWarnings = config.lifecycle.skipsWarnings(asString(parsed.status), asString(parsed.type));
+
+    // Missing type (fixable — infer from root: plans → 'plan', else 'doc')
+    if (!asString(parsed.type)) {
+      const docRoot = findLexicalDocsRoot(filePath, config) ?? config.docsRoot;
+      const rootLabel = path.relative(config.repoRoot, docRoot).split(path.sep).join('/');
+      // If the root label contains 'plan' (e.g. 'docs/plans'), default to plan type
+      const inferredType = rootLabel.includes('plan') ? 'plan' : 'doc';
+      fixes.push({ field: 'type', oldValue: null, newValue: inferredType, type: 'add' });
+    }
+
+    // Missing status (fixable via AI inference)
+    if (!asString(parsed.status)) {
+      fixes.push({ field: 'status', oldValue: null, newValue: null, type: 'infer-status' });
+    }
+
+    // Missing updated
+    if (!asString(parsed.updated) && asString(parsed.status) && !skipWarnings) {
+      const today = new Date().toISOString().slice(0, 10);
+      fixes.push({ field: 'updated', oldValue: null, newValue: today, type: 'add' });
+    }
+
+    // Status casing — check against type-specific or global valid statuses
+    const status = asString(parsed.status);
+    const docType = asString(parsed.type);
+    const typeSet = docType ? config.typeStatuses?.get(docType) : null;
+    const effectiveStatuses = typeSet ?? config.validStatuses;
+    if (status && status !== status.toLowerCase() && effectiveStatuses.has(status.toLowerCase())) {
+      fixes.push({ field: 'status', oldValue: status, newValue: status.toLowerCase(), type: 'update' });
+    }
+
+    // Key renames
+    for (const [oldKey, newKey] of Object.entries(KEY_RENAMES)) {
+      if (parsed[oldKey] !== undefined && parsed[newKey] === undefined) {
+        fixes.push({ field: oldKey, oldValue: oldKey, newValue: newKey, type: 'rename-key' });
+      }
+    }
+
+    // Singular `module:` / `surface:` → plural array (F18 deprecation).
+    // Any singular use migrates, regardless of comma — comma-containing values
+    // split on `,`, single values become a one-item list. Merging with any
+    // existing plural array happens at apply-time so the message reflects
+    // just what's being introduced from the singular form.
+    if (!skipWarnings) {
+      for (const { singular, plural } of [{ singular: 'module', plural: 'modules' }, { singular: 'surface', plural: 'surfaces' }]) {
+        const rawVal = parsed[singular];
+        const rawPluralVal = parsed[plural];
+        const val = asString(rawVal);
+        const scalarValue = val && isAutoFixableString(val) ? val : null;
+        const blockValues = Array.isArray(rawVal) && rawVal.every(isAutoFixableString)
+          ? rawVal.map(item => item.trim()).filter(Boolean)
+          : [];
+        const pluralAutoFixable = rawPluralVal === undefined
+          || isAutoFixableString(rawPluralVal)
+          || (Array.isArray(rawPluralVal) && rawPluralVal.every(isAutoFixableString));
+        if (pluralAutoFixable && (scalarValue || blockValues.length > 0)) {
+          const values = blockValues.length > 0
+            ? blockValues
+            : scalarValue.includes(',')
+              ? scalarValue.split(',').map(s => s.trim()).filter(Boolean)
+              : [scalarValue];
+          fixes.push({ field: singular, oldValue: scalarValue || blockValues.join(', '), newValue: values, pluralKey: plural, type: 'singular-to-plural' });
+        } else if (pluralAutoFixable && singular in parsed && (
+          (typeof rawVal === 'string' && !rawVal.trim())
+          || (Array.isArray(rawVal) && rawVal.every(item => typeof item === 'string' && !item.trim()))
+        )) {
+          fixes.push({ field: singular, pluralKey: plural, type: 'drop-singular' });
+        }
+      }
+    }
+
+    // Trailing whitespace in values
+    for (const line of frontmatter.split('\n')) {
+      const m = line.match(/^([A-Za-z0-9_-]+):(.+\S)\s+$/);
+      if (m) {
+        fixes.push({ field: m[1], oldValue: m[2] + line.slice(line.indexOf(m[2]) + m[2].length), newValue: m[2], type: 'trim' });
+      }
+    }
+
+    // Missing newline at EOF
+    if (!raw.endsWith('\n')) {
+      fixes.push({ field: '(eof)', oldValue: 'missing', newValue: 'newline', type: 'eof' });
+    }
+
+    if (fixes.length > 0) {
+      fixable.push({ filePath, repoPath, fixes });
+    }
+  }
+
+  let nonFixable = [];
+  if (!fix) {
+    // Report-only mode also gets non-fixable issues from the index. Fix mode
+    // does not render these and must not pay for a full validation/Git scan.
+    const index = buildIndex(config);
+    const fixablePaths = new Set(fixable.map(f => f.repoPath));
+    // Singular-key deprecation warnings whose fix `lint --fix` will actually make.
+    // Without this, those warnings landed in BOTH the "fixable" preview and the
+    // "non-fixable" list, so the header claimed "N non-fixable" while every line
+    // told you to run `lint --fix` (issue #17, item 8).
+    const fixableSingularKeys = new Set();
+    for (const { repoPath, fixes } of fixable) {
+      for (const f of fixes) {
+        if (f.type === 'singular-to-plural' || f.type === 'drop-singular') {
+          fixableSingularKeys.add(`${repoPath}::${f.field}`);
+        }
+      }
+    }
+    nonFixable = [...index.errors, ...index.warnings].filter(issue => {
+      if (issue.message.includes('Missing frontmatter `status`') && fixablePaths.has(issue.path)) return false;
+      const dep = issue.message.match(/^`(module|surface):` \(singular\) is deprecated/);
+      if (dep && fixableSingularKeys.has(`${issue.path}::${dep[1]}`)) return false;
+      return true;
+    });
+  }
+
+  if (!fix) {
+    // Report mode
+    if (fixable.length > 0) {
+      process.stdout.write(bold(`${fixable.length} file(s) with fixable issues:\n\n`));
+      for (const { repoPath, fixes } of fixable) {
+        process.stdout.write(`  ${repoPath}\n`);
+        for (const f of fixes) {
+          if (f.type === 'rename-key') {
+            process.stdout.write(dim(`    ${f.oldValue} → ${f.newValue}\n`));
+          } else if (f.type === 'infer-status') {
+            process.stdout.write(dim(`    missing status (fixable via AI)\n`));
+          } else if (f.type === 'singular-to-plural') {
+            process.stdout.write(dim(`    ${f.field}: "${f.oldValue}" → ${f.pluralKey}: [${f.newValue.join(', ')}]\n`));
+          } else if (f.type === 'drop-singular') {
+            process.stdout.write(dim(`    remove deprecated \`${f.field}:\` (empty; \`${f.pluralKey}:\` is the live key)\n`));
+          } else if (f.type === 'eof') {
+            process.stdout.write(dim(`    missing newline at end of file\n`));
+          } else if (f.type === 'add') {
+            process.stdout.write(dim(`    add ${f.field}: ${f.newValue}\n`));
+          } else {
+            process.stdout.write(dim(`    ${f.field}: ${f.oldValue} → ${f.newValue}\n`));
+          }
+        }
+      }
+      process.stdout.write(`\nRun ${bold('runlist lint --fix')} to auto-fix.\n`);
+    }
+
+    if (nonFixable.length > 0) {
+      process.stdout.write(`\n${yellow(`${nonFixable.length} non-fixable issue(s)`)} (manual attention needed):\n`);
+      for (const issue of nonFixable) {
+        process.stdout.write(`  ${issue.path}: ${issue.message}\n`);
+      }
+    }
+
+    if (fixable.length === 0 && nonFixable.length === 0) {
+      process.stdout.write(green('No issues found.') + '\n');
+    }
+    return;
+  }
+
+  // Fix mode
+  authorizeManagedSweep(fixable.map(item => item.filePath), config, { kind: 'Lint fix source' });
+  const prefix = dryRun ? dim('[dry-run] ') : '';
+  let totalFixes = 0;
+
+  for (const { filePath, repoPath, fixes } of fixable) {
+    const updates = {};
+    const keyRenames = [];
+    let needsEofFix = false;
+    const trimFixes = [];
+    const singularToPlural = [];
+    const dropSingular = [];
+
+    for (const f of fixes) {
+      if (f.type === 'rename-key') {
+        keyRenames.push(f);
+      } else if (f.type === 'eof') {
+        needsEofFix = true;
+      } else if (f.type === 'trim') {
+        trimFixes.push(f);
+      } else if (f.type === 'singular-to-plural') {
+        singularToPlural.push(f);
+      } else if (f.type === 'drop-singular') {
+        dropSingular.push(f);
+      } else {
+        updates[f.field] = f.newValue;
+      }
+    }
+
+    if (!dryRun) {
+      // Apply infer-status fixes via AI
+      for (const f of fixes.filter(f => f.type === 'infer-status')) {
+        const raw = readFileSync(filePath, 'utf8');
+        const { frontmatter: fmInfer } = extractFrontmatter(raw);
+        const parsedInfer = parseSimpleFrontmatter(fmInfer);
+        const inferType = asString(parsedInfer.type);
+        const inferTypeSet = inferType ? config.typeStatuses?.get(inferType) : null;
+        const statusList = inferTypeSet ? [...inferTypeSet].join(', ') : config.statusOrder.join(', ');
+        const { body } = extractFrontmatter(raw);
+        const prompt = `Given this markdown document, classify it into exactly one of these statuses: ${statusList}.\nReply with ONLY the status word, nothing else.\n\nFile: ${repoPath}\n\n${(body ?? '').slice(0, 4000)}`;
+        const result = runModel(prompt, { maxTokens: 10 });
+        const suggested = result?.trim().toLowerCase().split(/\s+/)[0];
+        const inferValid = inferTypeSet ?? config.validStatuses;
+        if (suggested && inferValid.has(suggested)) {
+          updateFrontmatter(filePath, { status: suggested });
+          f.newValue = suggested;
+        }
+      }
+
+      // Apply singular-to-plural fixes (module/surface → modules/surfaces array).
+      // Removes the singular key block; merges its value(s) into the plural array,
+      // or creates the plural block if absent. Duplicates are skipped.
+      for (const sa of singularToPlural) {
+        let raw = readFileSync(filePath, 'utf8');
+        const { frontmatter: fm } = extractFrontmatter(raw);
+        const parsedFm = parseSimpleFrontmatter(fm);
+        const pluralValue = parsedFm[sa.pluralKey];
+        const existing = Array.isArray(pluralValue)
+          ? pluralValue.filter(value => typeof value === 'string' && value.trim())
+          : asString(pluralValue) ? [asString(pluralValue)] : [];
+        const merged = [...new Set([...sa.newValue, ...existing])];
+        const comments = [...frontmatterFieldComments(fm, sa.field), ...frontmatterFieldComments(fm, sa.pluralKey)];
+        let newFm = replaceFrontmatterFieldBlock(fm, sa.field);
+        const pluralLines = [sa.pluralKey + ':', ...comments.map(comment => `  ${comment}`), ...merged.map(v => `  - ${formatYamlScalar(v)}`)];
+        const pluralBlock = pluralLines.join('\n');
+        if (Object.prototype.hasOwnProperty.call(parsedFm, sa.pluralKey)) {
+          newFm = replaceFrontmatterFieldBlock(newFm, sa.pluralKey, pluralBlock);
+        } else {
+          newFm = `${newFm.trim()}\n${pluralBlock}`;
+        }
+        raw = replaceFrontmatter(raw, newFm.trim());
+        writeFileSync(filePath, raw, 'utf8');
+      }
+
+      // Drop empty deprecated singular keys. The value is known-empty (the fix
+      // is only emitted for `[]`/`''`), so this matches the bare `key:` line
+      // exactly — never a line carrying content — and removes it.
+      for (const ds of dropSingular) {
+        let raw = readFileSync(filePath, 'utf8');
+        const { frontmatter: fm } = extractFrontmatter(raw);
+        const comments = frontmatterFieldComments(fm, ds.field);
+        const newFm = replaceFrontmatterFieldBlock(fm, ds.field, comments.join('\n'));
+        raw = replaceFrontmatter(raw, newFm.trim());
+        writeFileSync(filePath, raw, 'utf8');
+      }
+
+      // Apply key renames and trim fixes via raw string manipulation
+      if (keyRenames.length > 0 || trimFixes.length > 0) {
+        let raw = readFileSync(filePath, 'utf8');
+        const { frontmatter: fm } = extractFrontmatter(raw);
+        let newFm = fm;
+        for (const kr of keyRenames) {
+          const regex = new RegExp(`^${escapeRegex(kr.oldValue)}:`, 'm');
+          newFm = newFm.replace(regex, `${kr.newValue}:`);
+        }
+        for (const tf of trimFixes) {
+          const regex = new RegExp(`^(${escapeRegex(tf.field)}:)${escapeRegex(tf.oldValue)}$`, 'm');
+          newFm = newFm.replace(regex, `$1${tf.newValue}`);
+        }
+        if (newFm !== fm) {
+          raw = replaceFrontmatter(raw, newFm);
+          writeFileSync(filePath, raw, 'utf8');
+        }
+      }
+
+      // Apply value updates via updateFrontmatter
+      if (Object.keys(updates).length > 0) {
+        updateFrontmatter(filePath, updates);
+      }
+
+      // EOF fix
+      if (needsEofFix) {
+        const current = readFileSync(filePath, 'utf8');
+        if (!current.endsWith('\n')) {
+          writeFileSync(filePath, current + '\n', 'utf8');
+        }
+      }
+    }
+
+    process.stdout.write(`${prefix}${green('Fixed')}: ${repoPath} (${fixes.length} issue${fixes.length > 1 ? 's' : ''})\n`);
+    for (const f of fixes) {
+      if (f.type === 'rename-key') {
+        process.stdout.write(`${prefix}  ${dim(`${f.oldValue} → ${f.newValue}`)}\n`);
+      } else if (f.type === 'eof') {
+        process.stdout.write(`${prefix}  ${dim('added newline at EOF')}\n`);
+      } else if (f.type === 'infer-status') {
+        if (f.newValue) {
+          process.stdout.write(`${prefix}  ${dim(`status: (missing) → ${f.newValue} (AI-inferred)`)}\n`);
+        } else {
+          process.stdout.write(`${prefix}  ${dim('status: (missing) — AI inference unavailable')}\n`);
+        }
+      } else if (f.type === 'singular-to-plural') {
+        process.stdout.write(`${prefix}  ${dim(`${f.field}: "${f.oldValue}" → ${f.pluralKey}: [${f.newValue.join(', ')}]`)}\n`);
+      } else if (f.type === 'drop-singular') {
+        process.stdout.write(`${prefix}  ${dim(`removed deprecated \`${f.field}:\` (empty)`)}\n`);
+      } else if (f.type === 'add') {
+        process.stdout.write(`${prefix}  ${dim(`add ${f.field}: ${f.newValue}`)}\n`);
+      } else {
+        process.stdout.write(`${prefix}  ${dim(`${f.field}: ${f.oldValue} → ${f.newValue}`)}\n`);
+      }
+    }
+    totalFixes += fixes.length;
+
+    if (!dryRun) {
+      try { config.hooks.onLint?.({ path: repoPath, fixes }); } catch (err) { warn(`Hook 'onLint' threw: ${err.message}`); }
+    }
+  }
+
+  process.stdout.write(`\n${prefix}${totalFixes} fix${totalFixes !== 1 ? 'es' : ''} applied across ${fixable.length} file(s).\n`);
+}

package/src/managed-path.mjs

@@ -0,0 +1,192 @@
+import { existsSync, lstatSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+// These checks are authorization preflights, not filesystem transactions. A
+// concurrent actor can still replace a checked ancestor before the later write
+// (TOCTOU); eliminating that residual boundary requires descriptor-relative IO.
+
+function contains(parent, child) {
+  const rel = path.relative(parent, child);
+  return rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel));
+}
+
+function sameNode(a, b) {
+  try {
+    const left = statSync(a, { bigint: true });
+    const right = statSync(b, { bigint: true });
+    return left.dev === right.dev && left.ino === right.ino;
+  } catch { return false; }
+}
+
+// realpath on case-insensitive macOS volumes may preserve the caller's casing.
+// Prove an alias by inode before treating it as contained; lowercase string
+// comparison alone would be unsafe on case-sensitive volumes.
+function aliasContainment(parent, child) {
+  if (contains(parent, child)) return { contained: true, relative: path.relative(parent, child) };
+  const parentParts = path.resolve(parent).split(path.sep).filter(Boolean);
+  const childParts = path.resolve(child).split(path.sep).filter(Boolean);
+  if (childParts.length < parentParts.length) return { contained: false, relative: null };
+  const childPrefix = `${path.parse(path.resolve(child)).root}${childParts.slice(0, parentParts.length).join(path.sep)}`;
+  if (!sameNode(parent, childPrefix)) return { contained: false, relative: null };
+  return { contained: true, relative: childParts.slice(parentParts.length).join(path.sep) };
+}
+
+function lexicalRootsFor(config) {
+  return (config.docsRoots ?? [config.docsRoot]).map(configuredPath => ({
+    configuredPath,
+    lexicalPath: path.resolve(configuredPath),
+  }));
+}
+
+function rootsFor(config) {
+  return lexicalRootsFor(config).map(root => {
+    const { configuredPath, lexicalPath } = root;
+    let canonicalPath;
+    try {
+      canonicalPath = realpathSync(lexicalPath);
+    } catch (err) {
+      throw new Error(`Configured docs root cannot be resolved: ${lexicalPath} (${err.message})`);
+    }
+    return { configuredPath, lexicalPath, canonicalPath };
+  });
+}
+
+function rootsMessage(roots) {
+  return roots.map(root => root.lexicalPath).join(', ');
+}
+
+function markdown(pathname, kind, roots) {
+  if (!pathname.endsWith('.md')) {
+    throw new Error(`${kind} must be a Markdown file ending in .md: ${pathname}\nConfigured docs roots: ${rootsMessage(roots)}`);
+  }
+}
+
+function nearestExistingAncestor(input, roots, kind) {
+  let current = input;
+  while (!existsSync(current)) {
+    try {
+      // existsSync is false for dangling symlinks, but lstat still sees them.
+      if (lstatSync(current).isSymbolicLink()) {
+        throw new Error(`dangling symlink: ${current}`);
+      }
+    } catch (err) {
+      if (err?.code !== 'ENOENT' && err?.code !== 'ENOTDIR') {
+        throw new Error(`${kind} has an unsafe existing ancestor: ${current} (${err.message})\nConfigured docs roots: ${rootsMessage(roots)}`);
+      }
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  try {
+    return realpathSync(current);
+  } catch (err) {
+    throw new Error(`${kind} ancestor cannot be resolved: ${current} (${err.message})\nConfigured docs roots: ${rootsMessage(roots)}`);
+  }
+}
+
+function lexicalOwner(input, roots) {
+  return roots
+    .filter(root => contains(root.lexicalPath, input))
+    .sort((a, b) => b.lexicalPath.length - a.lexicalPath.length)[0] ?? null;
+}
+
+export function findLexicalDocsRoot(input, config) {
+  return lexicalOwner(path.resolve(input), lexicalRootsFor(config))?.lexicalPath ?? null;
+}
+
+export function authorizeManagedSource(input, config, { kind = 'Managed mutation source' } = {}) {
+  const roots = rootsFor(config);
+  const lexicalPath = path.resolve(input);
+  markdown(lexicalPath, kind, roots);
+
+  if (!existsSync(lexicalPath)) {
+    throw new Error(`${kind} does not exist: ${lexicalPath}\nConfigured docs roots: ${rootsMessage(roots)}`);
+  }
+  if (lstatSync(lexicalPath).isSymbolicLink()) {
+    throw new Error(`${kind} may not be a symlink: ${lexicalPath}\nConfigured docs roots: ${rootsMessage(roots)}`);
+  }
+
+  let canonicalPath;
+  try {
+    canonicalPath = realpathSync(lexicalPath);
+  } catch (err) {
+    throw new Error(`${kind} cannot be resolved: ${lexicalPath} (${err.message})\nConfigured docs roots: ${rootsMessage(roots)}`);
+  }
+  if (!statSync(canonicalPath).isFile()) {
+    throw new Error(`${kind} is not a file: ${lexicalPath}\nConfigured docs roots: ${rootsMessage(roots)}`);
+  }
+
+  const lexical = lexicalOwner(lexicalPath, roots);
+  if (lexical && !aliasContainment(lexical.canonicalPath, canonicalPath).contained) {
+    throw new Error(`${kind} is lexically owned by ${lexical.lexicalPath} but resolves outside that root: ${lexicalPath} -> ${canonicalPath}\nConfigured docs roots: ${rootsMessage(roots)}`);
+  }
+  const root = lexical
+    ?? roots.filter(candidate => aliasContainment(candidate.canonicalPath, canonicalPath).contained)
+      .sort((a, b) => b.canonicalPath.length - a.canonicalPath.length)[0];
+  if (!root) {
+    throw new Error(`${kind} resolves outside configured docs roots: ${lexicalPath} -> ${canonicalPath}\nConfigured docs roots: ${rootsMessage(roots)}`);
+  }
+
+  // Keep operations on the configured root spelling (important when the root
+  // itself is a symlink), while normalizing OS-level aliases such as /var ->
+  // /private/var back through the owning root.
+  const managedPath = lexical
+    ? lexicalPath
+    : path.join(root.lexicalPath, aliasContainment(root.canonicalPath, canonicalPath).relative);
+  return { path: managedPath, canonicalPath, root };
+}
+
+export function authorizeManagedDestination(input, config, { root: requiredRoot = null, kind = 'Managed mutation destination' } = {}) {
+  const roots = rootsFor(config);
+  const lexicalPath = path.resolve(input);
+  markdown(lexicalPath, kind, roots);
+
+  const root = requiredRoot
+    ? roots.find(candidate => candidate.lexicalPath === requiredRoot.lexicalPath && candidate.canonicalPath === requiredRoot.canonicalPath)
+    : lexicalOwner(lexicalPath, roots);
+  if (!root || !contains(root.lexicalPath, lexicalPath)) {
+    const ownership = requiredRoot ? `Owning docs root: ${requiredRoot.lexicalPath}\n` : '';
+    throw new Error(`${kind} is lexically outside its configured docs root: ${lexicalPath}\n${ownership}Configured docs roots: ${rootsMessage(roots)}`);
+  }
+
+  const ancestor = nearestExistingAncestor(lexicalPath, roots, kind);
+  if (!aliasContainment(root.canonicalPath, ancestor).contained) {
+    throw new Error(`${kind} escapes through an existing symlinked parent: ${lexicalPath} -> ${ancestor}\nOwning docs root: ${root.lexicalPath}\nConfigured docs roots: ${rootsMessage(roots)}`);
+  }
+  return { path: lexicalPath, canonicalPath: existsSync(lexicalPath) ? realpathSync(lexicalPath) : null, root };
+}
+
+export function authorizeManagedMove(source, destination, config, options = {}) {
+  const authorizedSource = authorizeManagedSource(source, config, options);
+  const authorizedDestination = authorizeManagedDestination(destination, config, {
+    ...options,
+    kind: options.destinationKind ?? 'Managed mutation destination',
+    root: authorizedSource.root,
+  });
+  return { source: authorizedSource, destination: authorizedDestination };
+}
+
+export function authorizeManagedSweep(files, config, { kind = 'Managed mutation sweep' } = {}) {
+  return files.map(file => authorizeManagedSource(file, config, { kind }));
+}
+
+export function authorizeRepoGeneratedPath(input, config, { kind = 'Repository-generated destination' } = {}) {
+  const lexicalPath = path.resolve(input);
+  const repoRoot = path.resolve(config.repoRoot);
+  let canonicalRepo;
+  try { canonicalRepo = realpathSync(repoRoot); }
+  catch (err) { throw new Error(`Repository root cannot be resolved: ${repoRoot} (${err.message})`); }
+
+  if (!contains(repoRoot, lexicalPath)) {
+    throw new Error(`${kind} is outside the repository: ${lexicalPath}\nRepository root: ${repoRoot}`);
+  }
+  const ancestor = nearestExistingAncestor(lexicalPath, [{ lexicalPath: repoRoot }], kind);
+  if (!contains(canonicalRepo, ancestor)) {
+    throw new Error(`${kind} escapes through an existing symlinked parent: ${lexicalPath} -> ${ancestor}\nRepository root: ${repoRoot}`);
+  }
+  if (existsSync(lexicalPath) && lstatSync(lexicalPath).isSymbolicLink()) {
+    throw new Error(`${kind} may not be a symlink: ${lexicalPath}\nRepository root: ${repoRoot}`);
+  }
+  return { path: lexicalPath, canonicalPath: existsSync(lexicalPath) ? realpathSync(lexicalPath) : null };
+}

package/src/markdown-code-spans.mjs

@@ -0,0 +1,58 @@
+function mask(text) {
+  return text.includes('\n') ? text.replace(/[^\n]/g, 'x') : 'x'.repeat(text.length);
+}
+
+// Markdown code spans close only on a backtick run of the same length as their
+// opener. The mask is deliberately the same length as the source so consumers
+// can inspect neutralized Markdown while applying any edits at source offsets.
+// `state` lets the conservative multiline behavior used by the reference
+// rewriter survive: after an unmatched opener, nothing is treated as prose
+// until a compatible closer appears.
+export function maskInlineCodeLine(line, state = { run: null }) {
+  if (!line.includes('`')) return state.run === null ? line : mask(line);
+
+  const runs = [...line.matchAll(/`+/g)];
+  const findCloser = (from, length) => {
+    for (let i = from; i < runs.length; i++) if (runs[i][0].length === length) return i;
+    return -1;
+  };
+  const ranges = [];
+  let index = 0;
+
+  if (state.run !== null) {
+    const closingIndex = findCloser(0, state.run);
+    if (closingIndex === -1) return mask(line);
+    const closing = runs[closingIndex];
+    ranges.push([0, closing.index + closing[0].length]);
+    index = closingIndex + 1;
+    state.run = null;
+  }
+
+  for (; index < runs.length; index++) {
+    const opening = runs[index];
+    const closingIndex = findCloser(index + 1, opening[0].length);
+    if (closingIndex === -1) {
+      ranges.push([opening.index, line.length]);
+      state.run = opening[0].length;
+      break;
+    }
+    const closing = runs[closingIndex];
+    ranges.push([opening.index, closing.index + closing[0].length]);
+    index = closingIndex;
+  }
+
+  // Ranges are ascending and disjoint, so one left-to-right pass builds the
+  // result instead of re-copying the whole line once per span.
+  let out = '';
+  let cursor = 0;
+  for (const [start, end] of ranges) {
+    out += line.slice(cursor, start) + mask(line.slice(start, end));
+    cursor = end;
+  }
+  return out + line.slice(cursor);
+}
+
+export function maskInlineCodeSpans(value) {
+  const state = { run: null };
+  return value.split('\n').map(line => maskInlineCodeLine(line, state)).join('\n');
+}