hypomnema 1.7.3 → 1.7.4

package/scripts/lib/slug-resolver.mjs

@@ -0,0 +1,181 @@
+// scripts/lib/slug-resolver.mjs — shared slug resolution, extracted from
+// lint.mjs and rename.mjs so a future consumer does not grow its own copy.
+//
+// Exposes TWO modes, deliberately not folded into one:
+//
+//   - existence-check (lint)         — buildSlugMap: a Set, membership only.
+//     Fast, but cannot say WHICH page owns a form or whether it is shared.
+//   - collision-aware owner (rename) — buildFormIndex + classifyTarget +
+//     newTargetFor: a form → Set<rel> map, so a caller can tell an
+//     unambiguous resolution from a shared one and refuse to auto-rewrite
+//     the latter.
+//
+// Folding these into one structure would be a regression: lint only needs to
+// know a link resolves to SOMETHING, while rename must refuse to touch a link
+// whose form is shared by more than one page. Collectors stay separate too —
+// lint's target universe is pages/projects/journal plus root .md and
+// sources/* (collectLinkTargets, still in lint.mjs); rename scans the whole
+// vault root and treats journal/session-log/weekly/archive/postmortems and
+// sources/* as immutable link SOURCES (preservationClass, below).
+//
+// Masking, link-body parsing, and the immutability/realpath-containment rules
+// travel with owner mode because rename's rewrite pipeline needs all of them
+// together: mask non-wikilink regions, parse a link body, classify it against
+// the form index, and refuse a target that resolves outside the vault.
+
+import { lstatSync, realpathSync } from 'fs';
+import { dirname, sep } from 'path';
+import { slugForms } from './wikilink.mjs';
+
+// ── existence-check slug map (lint mode) ────────────────────────────────────
+// `extraTargets` are link-target-only slugs (root *.md, sources/*) that
+// resolve wikilinks but are not themselves linted — added verbatim, with NO
+// derived basename/dir-relative aliases, so they can't mask an unrelated
+// broken link.
+export function buildSlugMap(pages, extraTargets = []) {
+  const map = new Set();
+  for (const { rel } of pages) {
+    const noExt = rel.replace(/\.md$/, '').replace(/\\/g, '/');
+    const { full, bare, dirRel } = slugForms(noExt);
+    map.add(full);
+    map.add(bare);
+    if (dirRel) map.add(dirRel);
+  }
+  for (const t of extraTargets) map.add(t);
+  return map;
+}
+
+// ── collision-aware form index (owner mode) ─────────────────────────────────
+export const dirRelForm = (slug) => slugForms(slug).dirRel;
+
+// Unlike buildSlugMap above (a Set that silently dedups collisions), owner
+// mode needs to KNOW when a form is shared, so it maps each form to the SET
+// of page rels that expose it. Precedence forms per page: full noExt slug,
+// bare basename, dir-relative (drop the leading scan-dir segment).
+export function buildFormIndex(pages) {
+  const index = new Map(); // form → Set<rel>
+  const add = (form, rel) => {
+    if (!form) return;
+    if (!index.has(form)) index.set(form, new Set());
+    index.get(form).add(rel);
+  };
+  for (const p of pages) {
+    add(p.slug, p.rel);
+    // sources/* are full-slug-only link targets, exactly as lint's
+    // collectLinkTargets treats them: a bare `[[name]]` must NOT resolve to a
+    // source file. Adding their bare/dir-relative aliases here would make a
+    // real page's bare link look ambiguous and skip a legitimate rewrite.
+    if (/(^|\/)sources(\/|$)/.test(p.rel)) continue;
+    add(p.bare, p.rel);
+    add(dirRelForm(p.slug), p.rel);
+  }
+  return index;
+}
+
+// Classify a link target against the from-page. Returns the form KIND when
+// the target points at from-page, plus whether that form is ambiguous
+// (shared with another page → unsafe to auto-rewrite).
+export function classifyTarget(target, fromPage, formIndex) {
+  const owners = formIndex.get(target);
+  if (!owners || !owners.has(fromPage.rel)) return { kind: null, ambiguous: false };
+  const ambiguous = owners.size > 1;
+  let kind = null;
+  if (target === fromPage.slug) kind = 'full';
+  else if (target === dirRelForm(fromPage.slug)) kind = 'dirrel';
+  else if (target === fromPage.bare) kind = 'bare';
+  return { kind, ambiguous };
+}
+
+// The new target string for a matched form kind — same kind, new page.
+export function newTargetFor(kind, toPage) {
+  if (kind === 'full') return toPage.slug;
+  if (kind === 'dirrel') return dirRelForm(toPage.slug) ?? toPage.bare;
+  return toPage.bare; // bare
+}
+
+// ── wikilink masking (owner mode) ───────────────────────────────────────────
+// Blank out fenced code, inline code, and HTML comments WITHOUT changing
+// length, so a [[ref]] match index in the mask aligns with the same index in
+// the source. Rewriting then edits the source at those exact spans, never
+// touching a link that only appears inside a code sample.
+export function maskNonWikilinkRegions(content) {
+  let out = content;
+  out = out.replace(/^[ \t]{0,3}```[\s\S]*?^[ \t]{0,3}```/gm, (m) => m.replace(/[^\n]/g, ' '));
+  out = out.replace(/^[ \t]{0,3}~~~[\s\S]*?^[ \t]{0,3}~~~/gm, (m) => m.replace(/[^\n]/g, ' '));
+  out = out.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, ' '));
+  out = out.replace(/``[^`\n]*``/g, (m) => ' '.repeat(m.length));
+  out = out.replace(/`[^`\n]*`/g, (m) => ' '.repeat(m.length));
+  return out;
+}
+
+// Parse the inside of a `[[ ... ]]` into { target, suffix } where suffix is
+// the alias/anchor tail to preserve verbatim (including a table-escaped
+// `\|`). The target capture stops before an optional `\` preceding the
+// `|`/`#` delimiter, matching lint's extractor exactly.
+export function splitLinkBody(body) {
+  const m = body.match(/^([^|#\\]+?)(\\?[|#][\s\S]*)?$/);
+  if (!m) return null;
+  return { target: m[1].trim(), suffix: m[2] || '' };
+}
+
+// ── preservation class of a link-source path (owner mode) ──────────────────
+// Two distinct reasons a file is normally skipped as a link SOURCE, kept
+// separate because directory-mode renames treat them differently:
+//
+//   'timerecord' — append-only snapshots (journal / session-log / weekly /
+//      archive / postmortems + root log.md). Rewriting a [[old]] inside a
+//      past entry would falsify that moment.
+//   'sources'    — sources/* immutable CAPTURED material. Never rewritten,
+//      not even inside a moved subtree.
+//
+// Matches a path SEGMENT so `pages/journal/x.md` and
+// `projects/p/session-log/y.md` both qualify. Returns null for ordinary live
+// pages.
+export function preservationClass(rel) {
+  const p = rel.replace(/\\/g, '/');
+  if (/(^|\/)sources(\/|$)/.test(p)) return 'sources';
+  if (p === 'log.md') return 'timerecord';
+  if (/(^|\/)(journal|session-log|weekly|archive|postmortems)(\/|$)/.test(p)) return 'timerecord';
+  return null;
+}
+
+// A rename elsewhere in the vault must never churn a frozen snapshot or a
+// source — both preservation classes count as a preserved link SOURCE.
+export function isPreservedSource(rel) {
+  return preservationClass(rel) !== null;
+}
+
+// ── realpath containment (owner mode) ───────────────────────────────────────
+// Verify a path resolves, following any symlink ANCESTOR, to a location
+// inside the real vault root. A lexical ../-check cannot catch this: a
+// symlinked directory that is lexically in-vault can still resolve outside
+// it. The destination may not exist, so the deepest existing prefix is
+// resolved (its realpath is where a write would actually land). Fail-closed:
+// returns false on any resolution error.
+//
+// The walk uses lstat (NOT existsSync) so a DANGLING symlink prefix is
+// detected as present-but-unresolvable rather than skipped as absent —
+// otherwise the walk would step past it to an in-vault parent and wrongly
+// report containment.
+export function realContainedInVault(absPath, realRoot) {
+  let probe = absPath;
+  for (;;) {
+    let exists = true;
+    try {
+      lstatSync(probe);
+    } catch {
+      exists = false;
+    }
+    if (exists) break;
+    const parent = dirname(probe);
+    if (parent === probe) return false;
+    probe = parent;
+  }
+  let real;
+  try {
+    real = realpathSync(probe); // follows links; throws on a dangling symlink
+  } catch {
+    return false;
+  }
+  return real === realRoot || real.startsWith(realRoot + sep);
+}

package/scripts/lint.mjs

@@ -30,8 +30,9 @@ import {
 import { findDesignHistoryStale } from './lib/design-history-stale.mjs';
 import { FEEDBACK_SCOPE_RE } from './lib/feedback-scope.mjs';
 import { FAILURE_TYPE_ENUM } from './lib/failure-type.mjs';
-import { collectPagesLint, collectPagesLinkable, slugForms } from './lib/wikilink.mjs';
+import { collectPagesLint, collectPagesLinkable } from './lib/wikilink.mjs';
 import { parseFrontmatter, SEQUENCE_ENTRY_RE } from './lib/frontmatter.mjs';
+import { buildSlugMap } from './lib/slug-resolver.mjs';
 
 // ── arg parsing ──────────────────────────────────────────────────────────────
 
@@ -176,28 +177,9 @@ const TYPE_ENUM_FIELDS = {
 };
 
 // ── page collector ────────────────────────────────────────────────────────────
-
-// ── slug map ─────────────────────────────────────────────────────────────────
-
-// `extraTargets` are link-target-only slugs (root *.md, sources/*) that resolve
-// wikilinks but are not themselves linted — added verbatim, with NO derived
-// basename/dir-relative aliases, so they can't mask an unrelated broken link.
-function buildSlugMap(pages, extraTargets = []) {
-  const map = new Set();
-  for (const { rel } of pages) {
-    const noExt = rel.replace(/\.md$/, '').replace(/\\/g, '/');
-    // full slug + bare basename + dir-relative alias (drop the leading scan-dir
-    // segment so the convention link [[learnings/foo]] resolves to
-    // pages/learnings/foo.md). slugForms returns dirRel=null when the slug has no
-    // `/` (a page directly under a scan dir has no extra segment to drop).
-    const { full, bare, dirRel } = slugForms(noExt);
-    map.add(full);
-    map.add(bare);
-    if (dirRel) map.add(dirRel);
-  }
-  for (const t of extraTargets) map.add(t);
-  return map;
-}
+//
+// buildSlugMap (existence-check mode) now lives in ./lib/slug-resolver.mjs,
+// shared with rename.mjs's collision-aware owner mode.
 
 // Link-target-only slugs: files that are valid wikilink destinations but are
 // NOT linted themselves. Root-level *.md (hot.md / log.md / hypo-guide.md /
@@ -308,6 +290,10 @@ const issues = [];
 //   W3 missing-updated  → excluded (auto-repaired by --fix).
 //   W8 design-history-stale → excluded (hypo-personal-check handles it; would
 //                             double-gate).
+//   W14 design-history-missing → excluded, same reason as W8, and deliberately
+//                             a different id so hypo-shared.mjs's W8-only
+//                             blocker filter never sees it (stays warn, never
+//                             hard-blocks PreCompact).
 // NOTE: no gate currently passes --strict (npm run lint / CI / release.yml /
 // crystallize / the close-gate all run plain lint), so promotion is
 // forward-looking: these surface as warnings today. The deliverable is
@@ -602,7 +588,25 @@ for (const rel of closeRootTargets) {
 // project (not per page) — runs outside the page loop. POSIX-separated path
 // literal (not path.join) so consumers can rely on `file.split('/')` shape
 // regardless of host OS — `hooks/hypo-personal-check.mjs:246` depends on this.
+//
+// W14: design-history.md does not exist at all, but session-log carries a
+// design-relevant entry with nowhere to land. Distinct id from W8 on purpose —
+// hypo-shared.mjs's PreCompact gate filters strictly on `w.id === 'W8'` to
+// hard-block an active project on staleness, and W14 must NOT enter that path
+// (a bootstrapping gap on 14 of 16 live projects would block every one of
+// them). W14 stays a plain warn: never added to STRICT_PROMOTE_IDS, never
+// matched by that W8-only filter.
 for (const s of findDesignHistoryStale(args.hypoDir)) {
+  if (s.kind === 'missing') {
+    issue(
+      'warn',
+      `projects/${s.project}/design-history.md`,
+      `design-history missing: session-log 설계-관련 최신=${s.lastSession}인데 projects/${s.project}/design-history.md가 없습니다 — 파일을 새로 만들어 설계 변경 사항을 append 하는 것을 권고합니다`,
+      null,
+      'W14',
+    );
+    continue;
+  }
   const gap = s.diffDays != null ? ` (${s.diffDays}일 차이)` : '';
   issue(
     'warn',

package/scripts/rename.mjs

@@ -48,11 +48,22 @@ import {
   chmodSync,
   rmSync,
 } from 'fs';
-import { join, basename, dirname, normalize, isAbsolute, sep } from 'path';
+import { join, basename, dirname, normalize, isAbsolute } from 'path';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
 import { loadHypoIgnore } from './lib/hypo-ignore.mjs';
-import { collectPagesRename, slugForms } from './lib/wikilink.mjs';
+import { collectPagesRename } from './lib/wikilink.mjs';
 import { RENAME_MARKER_REL, renameMarkerPath, readRenameMarker } from './lib/rename-marker.mjs';
+import {
+  dirRelForm,
+  buildFormIndex,
+  classifyTarget,
+  newTargetFor,
+  maskNonWikilinkRegions,
+  splitLinkBody,
+  preservationClass,
+  isPreservedSource,
+  realContainedInVault,
+} from './lib/slug-resolver.mjs';
 
 // ── arg parsing ───────────────────────────────────────────────────────────────
 
@@ -69,108 +80,16 @@ function parseArgs(argv) {
   return args;
 }
 
-// ── preservation class of a link-source path ───────────────────────────────────
-// Two distinct reasons a file is normally skipped as a link SOURCE, kept separate
-// because directory mode treats them differently (codex design BLOCKER):
-//
-//   'timerecord' — append-only snapshots (journal / session-log / weekly / archive
-//      / postmortems + root log.md). Rewriting a [[old]] inside a past entry would
-//      falsify that moment. BUT a directory move relocates the whole subtree, so a
-//      time-record INSIDE the moved subtree that links a moving sibling must update
-//      that intra-subtree path label (the page genuinely moved); see runDirectory.
-//
-//   'sources'    — sources/* immutable CAPTURED material. Never rewritten, not even
-//      inside a moved subtree: a directory move must not claim ownership over the
-//      bytes of an external source we transcribed verbatim.
-//
-// Matches a path SEGMENT so `pages/journal/x.md` and `projects/p/session-log/y.md`
-// both qualify. Returns null for ordinary live pages.
-function preservationClass(rel) {
-  const p = rel.replace(/\\/g, '/');
-  if (/(^|\/)sources(\/|$)/.test(p)) return 'sources';
-  if (p === 'log.md') return 'timerecord';
-  if (/(^|\/)(journal|session-log|weekly|archive|postmortems)(\/|$)/.test(p)) return 'timerecord';
-  return null;
-}
-
-// Single-page mode preserves BOTH classes as link sources (unchanged behavior): a
-// rename elsewhere in the vault must never churn a frozen snapshot or a source.
-function isPreservedSource(rel) {
-  return preservationClass(rel) !== null;
-}
-
-// ── slug-form index (resolution with collision detection) ──────────────────────
-// Unlike lint's buildSlugMap (a Set that silently dedups collisions), rename
-// needs to KNOW when a form is shared, so it maps each form → the set of page
-// rels that expose it. precedence forms per page: full noExt slug, bare
-// basename, dir-relative (drop the leading scan-dir segment).
-const dirRelForm = (slug) => slugForms(slug).dirRel;
-
-function buildFormIndex(pages) {
-  const index = new Map(); // form → Set<rel>
-  const add = (form, rel) => {
-    if (!form) return;
-    if (!index.has(form)) index.set(form, new Set());
-    index.get(form).add(rel);
-  };
-  for (const p of pages) {
-    add(p.slug, p.rel);
-    // sources/* are full-slug-only link targets, exactly as lint's
-    // collectLinkTargets treats them: a bare `[[name]]` must NOT resolve to a
-    // source file. Adding their bare/dir-relative aliases here would make a real
-    // page's bare link look ambiguous and skip a legitimate rewrite.
-    if (/(^|\/)sources(\/|$)/.test(p.rel)) continue;
-    add(p.bare, p.rel);
-    add(dirRelForm(p.slug), p.rel);
-  }
-  return index;
-}
-
-// Classify a link target against the from-page. Returns the form KIND when the
-// target points at from-page, plus whether that form is ambiguous (shared with
-// another page → unsafe to auto-rewrite).
-function classifyTarget(target, fromPage, formIndex) {
-  const owners = formIndex.get(target);
-  if (!owners || !owners.has(fromPage.rel)) return { kind: null, ambiguous: false };
-  const ambiguous = owners.size > 1;
-  let kind = null;
-  if (target === fromPage.slug) kind = 'full';
-  else if (target === dirRelForm(fromPage.slug)) kind = 'dirrel';
-  else if (target === fromPage.bare) kind = 'bare';
-  return { kind, ambiguous };
-}
-
-// The new target string for a matched form kind — same kind, new page.
-function newTargetFor(kind, toPage) {
-  if (kind === 'full') return toPage.slug;
-  if (kind === 'dirrel') return dirRelForm(toPage.slug) ?? toPage.bare;
-  return toPage.bare; // bare
-}
-
-// ── wikilink masking (mirror lint.mjs stripNonWikilinkRegions) ──────────────────
-// Blank out fenced code, inline code, and HTML comments WITHOUT changing length,
-// so a [[ref]] match index in the mask aligns with the same index in the source.
-// Rewriting then edits the source at those exact spans, never touching a link
-// that only appears inside a code sample.
-function maskNonWikilinkRegions(content) {
-  let out = content;
-  out = out.replace(/^[ \t]{0,3}```[\s\S]*?^[ \t]{0,3}```/gm, (m) => m.replace(/[^\n]/g, ' '));
-  out = out.replace(/^[ \t]{0,3}~~~[\s\S]*?^[ \t]{0,3}~~~/gm, (m) => m.replace(/[^\n]/g, ' '));
-  out = out.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, ' '));
-  out = out.replace(/``[^`\n]*``/g, (m) => ' '.repeat(m.length));
-  out = out.replace(/`[^`\n]*`/g, (m) => ' '.repeat(m.length));
-  return out;
-}
-
-// Parse the inside of a `[[ ... ]]` into { target, suffix } where suffix is the
-// alias/anchor tail to preserve verbatim (including a table-escaped `\|`). The
-// target capture stops before an optional `\` preceding the `|`/`#` delimiter,
-// matching lint's extractor exactly.
-function splitLinkBody(body) {
-  const m = body.match(/^([^|#\\]+?)(\\?[|#][\s\S]*)?$/);
-  if (!m) return null;
-  return { target: m[1].trim(), suffix: m[2] || '' };
-}
+// ── preservation class of a link-source path, form index, masking, and link-body
+// parsing (preservationClass / isPreservedSource / dirRelForm / buildFormIndex /
+// classifyTarget / newTargetFor / maskNonWikilinkRegions / splitLinkBody) now
+// live in ./lib/slug-resolver.mjs, shared with lint.mjs's existence-check mode.
+// Directory mode's own notes on the two preservation classes: 'timerecord' is
+// skipped as a link SOURCE outside the moved subtree, but a time-record INSIDE
+// the moved subtree that links a moving sibling must update that intra-subtree
+// path label (the page genuinely moved); see runDirectory. 'sources' is never
+// rewritten even inside a moved subtree: a directory move must not claim
+// ownership over the bytes of an external source transcribed verbatim.
 
 // Rewrite every inbound reference to fromPage in `content`. Returns
 // { content, rewrites, ambiguous } where rewrites/ambiguous list the links
@@ -316,7 +235,9 @@ function guardExistingMarker(args, thisMarker) {
     );
   }
   const same =
-    marker.mode === thisMarker.mode && marker.from === thisMarker.from && marker.to === thisMarker.to;
+    marker.mode === thisMarker.mode &&
+    marker.from === thisMarker.from &&
+    marker.to === thisMarker.to;
   if (!same) {
     fail(
       args,
@@ -468,40 +389,10 @@ function rewriteContentDir(content, movedByRel, formIndex, aliasPreserve) {
   return { content: out, rewrites, ambiguous };
 }
 
-// Verify a path resolves — following any symlink ANCESTOR — to a location inside
-// the real vault root. A lexical ../-check cannot catch this: `projects/link/new`
-// where `projects/link` → /tmp/outside is lexically in-vault, yet renameSync would
-// follow the symlink and write across the vault boundary. The destination may not
-// exist, so the deepest existing prefix is resolved (its realpath is where a write
-// would actually land). Fail-closed: returns false on any resolution error.
-//
-// The walk uses lstat (NOT existsSync) so a DANGLING symlink prefix is detected as
-// present-but-unresolvable rather than skipped as absent — otherwise the walk would
-// step past it to an in-vault parent and wrongly report containment, letting an
-// external rewrite land before renameSync crashes on the dangling target.
-function realContainedInVault(absPath, realRoot) {
-  let probe = absPath;
-  // Walk up to the deepest path component that exists as a link-or-real entry.
-  for (;;) {
-    let exists = true;
-    try {
-      lstatSync(probe);
-    } catch {
-      exists = false;
-    }
-    if (exists) break;
-    const parent = dirname(probe);
-    if (parent === probe) return false;
-    probe = parent;
-  }
-  let real;
-  try {
-    real = realpathSync(probe); // follows links; throws on a dangling symlink
-  } catch {
-    return false;
-  }
-  return real === realRoot || real.startsWith(realRoot + sep);
-}
+// realContainedInVault now lives in ./lib/slug-resolver.mjs (imported above),
+// reused as-is: `projects/link/new` where `projects/link` → /tmp/outside is
+// lexically in-vault, yet renameSync would follow the symlink and write
+// across the vault boundary, which is exactly what it guards against below.
 
 // The destination's deepest existing ancestor must be a directory. Otherwise
 // mkdirSync(dirname, {recursive}) fails with ENOTDIR — but only AFTER the inbound
@@ -760,7 +651,10 @@ function runDirectory(args, fromDirRel, ignorePatterns) {
       // instead of an unsafe write-then-remove fallback; every write above is
       // already atomic, so a re-run picks up cleanly.
       if (err.code !== 'EXDEV') throw err;
-      fail(args, `--from and --to ended up on different filesystems mid-run — refusing an unsafe fallback move.`);
+      fail(
+        args,
+        `--from and --to ended up on different filesystems mid-run — refusing an unsafe fallback move.`,
+      );
     }
     clearRenameMarker(args);
     moved = true;
@@ -974,7 +868,10 @@ function run(args) {
         // removes. fromPage.path still holds the valid (possibly rewritten)
         // body, so a re-run picks up cleanly once the device issue is gone.
         if (err.code !== 'EXDEV') throw err;
-        fail(args, `--from and --to ended up on different filesystems mid-run — refusing an unsafe fallback move.`);
+        fail(
+          args,
+          `--from and --to ended up on different filesystems mid-run — refusing an unsafe fallback move.`,
+        );
       }
     }
     clearRenameMarker(args);