hypomnema 1.3.4 → 1.4.1

package/scripts/lib/check-bilingual.mjs

@@ -34,20 +34,99 @@ export function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+// Section model (changelog-pr-guide format.md §1/§2). A version block carries
+// gated sections, each split into "#### English" / "#### 한국어" sub-blocks at
+// and after the Korean cutoff. Highlights is gated too (it has a curated Korean
+// half); Changelog and the migration callout are NOT gated (language-neutral).
+export const GATED_HEADINGS = ['Highlights', 'New Features', 'Bug Fixes', 'Chores'];
+
+// Korean-summary cutoff: 1.2.0 is the first release that shipped a Korean half
+// (empirically the first "### 한글 요약" in CHANGELOG.md). 1.0.0–1.1.0 are
+// English-only; we never fabricate a Korean half for them (format.md §9).
+export const KOREAN_CUTOFF = [1, 2, 0];
+
+// Parse "major.minor.patch" (ignoring any prerelease/build suffix) into a number
+// triple, or null if it does not look like semver.
+export function parseSemver(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(String(v == null ? '' : v).trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+// Is `version` at or past the Korean cutoff (>= 1.2.0)? A prerelease of a
+// cutoff version (1.2.0-rc.1) counts as in-era. Unparseable → treated as not
+// meeting the cutoff (the gate then only checks English presence).
+export function meetsKoreanCutoff(version) {
+  const s = parseSemver(version);
+  if (!s) return false;
+  for (let i = 0; i < 3; i++) {
+    if (s[i] !== KOREAN_CUTOFF[i]) return s[i] > KOREAN_CUTOFF[i];
+  }
+  return true;
+}
+
+// Split `lines` into the sections introduced by a heading of exactly `hashes`
+// '#'. A section ends at the next same-level heading OR any higher-level (fewer
+// '#') heading; a deeper heading (more '#') stays inside the section body. So
+// slicing a version block at level 3 keeps each "### Section" with its nested
+// "#### English/한국어" lines, and re-slicing a section at level 4 yields those
+// sub-blocks. Returns [{ title, body: string[] }].
+function sliceSections(lines, hashes) {
+  const headRe = new RegExp(`^#{${hashes}} (.+?)\\s*$`);
+  const sameOrHigherRe = new RegExp(`^#{1,${hashes}} `);
+  const out = [];
+  let cur = null;
+  for (const line of lines) {
+    const m = headRe.exec(line);
+    if (m) {
+      if (cur) out.push(cur);
+      cur = { title: m[1].trim(), body: [] };
+      continue;
+    }
+    if (cur) {
+      // a same-or-higher level heading (that is not our own level) closes the
+      // open section without opening a tracked one.
+      if (sameOrHigherRe.test(line)) {
+        out.push(cur);
+        cur = null;
+        continue;
+      }
+      cur.body.push(line);
+    }
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+
+// List the versions a CHANGELOG documents, in file order (skips "Unreleased").
+export function listChangelogVersions(content) {
+  const lines = content.replace(/\r\n/g, '\n').split('\n');
+  const re = /^## \[([^\]]+)\](\s.*)?$/;
+  const out = [];
+  for (const l of lines) {
+    const m = re.exec(l);
+    if (m && m[1] !== 'Unreleased') out.push(m[1]);
+  }
+  return out;
+}
+
 /**
- * Validate that CHANGELOG.md content has a "## [<version>]" section containing
- * a "### 한글 요약" sub-section with >= HANGUL_BODY_THRESHOLD Hangul chars.
+ * Validate one CHANGELOG version block against the section model.
+ *
+ * At/after the Korean cutoff (>= 1.2.0): the block must carry at least one gated
+ * section, and EVERY gated section present must hold both a "#### English" and a
+ * "#### 한국어" sub-block, the Korean one non-empty, with the version's total
+ * Korean >= HANGUL_BODY_THRESHOLD. Before the cutoff (1.0.0–1.1.0): English-only
+ * era — the block need only carry content; no Korean is required or fabricated.
  *
  * @param {string} content  CHANGELOG.md raw content (CRLF tolerated).
  * @param {string} version  Semver string to look up (e.g. "1.2.1").
- * @returns {{ok: true, hangulCount: number} | {ok: false, reason: string}}
+ * @returns {{ok: true, hangulCount: number, koreanExempt?: boolean} | {ok: false, reason: string}}
  */
 export function validateChangelog(content, version) {
   if (!version) return { ok: false, reason: 'no version supplied' };
   const lines = content.replace(/\r\n/g, '\n').split('\n');
   const versionEsc = escapeRegex(version);
   // Anchor closing bracket so 1.2.1 does NOT match the prefix of 1.2.10.
-  // Allow trailing " - YYYY-MM-DD" or nothing.
   const sectionRe = new RegExp(`^## \\[${versionEsc}\\](\\s.*)?$`);
 
   const startIndices = [];
@@ -72,34 +151,58 @@ export function validateChangelog(content, version) {
       break;
     }
   }
-  const sectionLines = lines.slice(start, sectionEnd);
+  const blockLines = lines.slice(start + 1, sectionEnd);
+  const sections = sliceSections(blockLines, 3);
+  const gated = sections.filter((s) => GATED_HEADINGS.includes(s.title));
 
-  const koreanHeadIdx = sectionLines.findIndex((l) => l.trim() === '### 한글 요약');
-  if (koreanHeadIdx === -1) {
-    return { ok: false, reason: `section [${version}] missing "### 한글 요약" sub-section` };
+  if (!meetsKoreanCutoff(version)) {
+    // Pre-cutoff English-only era: require content (a non-heading body line),
+    // never a Korean half.
+    const hasContent = blockLines.some((l) => l.trim() && !/^#/.test(l));
+    if (!hasContent) {
+      return { ok: false, reason: `section [${version}] has no content` };
+    }
+    return { ok: true, hangulCount: 0, koreanExempt: true };
   }
 
-  // Bound the Korean block: stop at the next H2 OR H3. CHANGELOG.md has
-  // sibling H3s like "### Internal", "### Fixed" — Hangul in those sections
-  // does not count toward the "### 한글 요약" requirement.
-  let koreanEnd = sectionLines.length;
-  for (let i = koreanHeadIdx + 1; i < sectionLines.length; i++) {
-    if (/^(##|###) /.test(sectionLines[i])) {
-      koreanEnd = i;
-      break;
+  // Cutoff+: enforce the per-section bilingual structure.
+  if (gated.length === 0) {
+    return {
+      ok: false,
+      reason:
+        `section [${version}] has no gated section ` +
+        `(one of ${GATED_HEADINGS.join(' / ')} is required at >= 1.2.0)`,
+    };
+  }
+  let total = 0;
+  for (const sec of gated) {
+    const subs = sliceSections(sec.body, 4);
+    const hasEnglish = subs.some((s) => s.title === 'English');
+    const korean = subs.find((s) => s.title === '한국어');
+    if (!hasEnglish) {
+      return { ok: false, reason: `[${version}] "${sec.title}" missing "#### English" sub-block` };
+    }
+    if (!korean) {
+      return { ok: false, reason: `[${version}] "${sec.title}" missing "#### 한국어" sub-block` };
     }
+    const koCount = countHangul(korean.body.join('\n'));
+    if (koCount < 1) {
+      return {
+        ok: false,
+        reason: `[${version}] "${sec.title}" "#### 한국어" has no Korean text (heading alone does not count)`,
+      };
+    }
+    total += koCount;
   }
-  const body = sectionLines.slice(koreanHeadIdx + 1, koreanEnd).join('\n');
-  const count = countHangul(body);
-  if (count < HANGUL_BODY_THRESHOLD) {
+  if (total < HANGUL_BODY_THRESHOLD) {
     return {
       ok: false,
       reason:
-        `section [${version}] "### 한글 요약" body has ${count} Hangul chars ` +
-        `(threshold: ${HANGUL_BODY_THRESHOLD}). Heading alone does not count — write real Korean summary.`,
+        `section [${version}] total Korean is ${total} Hangul chars ` +
+        `(threshold: ${HANGUL_BODY_THRESHOLD}). Write real Korean summaries in the "#### 한국어" sub-blocks.`,
     };
   }
-  return { ok: true, hangulCount: count };
+  return { ok: true, hangulCount: total };
 }
 
 /**

package/scripts/lib/check-tracker-ids.mjs

@@ -61,6 +61,25 @@ export const BLOCKED_PATTERNS = [
   },
 ];
 
+// The remaining wiki tracker prefixes (FEAT-/IMPR-/PRAC-). These are NOT in
+// BLOCKED_PATTERNS because shipped CODE COMMENTS legitimately cite them for
+// maintainer context (e.g. `// FEAT-17 hardening`), exactly like ADR anchors —
+// blocking them everywhere would flag ~20 real in-code references. They ARE
+// blocked on the PUBLIC RELEASE SURFACE that carries no code: the annotated tag
+// body (the source of the GitHub Release via --notes-from-tag). The CLI applies
+// [...BLOCKED_PATTERNS, ...SURFACE_TRACKER_PATTERNS] only in --tag mode. The
+// CHANGELOG's own surface-ID-0 is held by the section migration + a grep
+// regression test, not by widening this file-scan set (changelog-pr-guide §5).
+// Examples below use `N`, not a real digit, so this file scans clean.
+export const SURFACE_TRACKER_PATTERNS = [
+  { name: 'FEAT-N', label: 'wiki feature-tracker id', re: /\bFEAT-\d+\b/gi },
+  { name: 'IMPR-N', label: 'wiki improvement-tracker id', re: /\bIMPR-\d+\b/gi },
+  { name: 'PRAC-N', label: 'wiki practice-tracker id', re: /\bPRAC-\d+\b/gi },
+];
+
+// The full tracker-ID set for a no-code public surface (the annotated tag body).
+export const TAG_BODY_PATTERNS = [...BLOCKED_PATTERNS, ...SURFACE_TRACKER_PATTERNS];
+
 /**
  * Scan a blob of text against `patterns` (default BLOCKED_PATTERNS). Returns hits:
  *   { pattern, label, match, line, col, lineText }

package/scripts/lib/failure-type.mjs

@@ -0,0 +1,33 @@
+// Feedback page `failure_type:` field vocabulary — shared single source of truth.
+//
+// Consumed by:
+//   - scripts/lint.mjs      (lint-time enum validation of feedback frontmatter)
+//   - scripts/feedback.mjs  (create/append-time --failure-type validation)
+// Keep this the ONLY definition; both consumers import it so the two validators
+// never drift (mirrors feedback-scope.mjs / ADR 0034). stats.mjs aggregates by
+// plain string and does not validate, so it is intentionally not a consumer.
+//
+// `failure_type` is an OPTIONAL field: it classifies feedback that came from a
+// real failure incident. Pure preferences / new conventions ("always do X")
+// omit it. Order below is the precedence used when classifying — most specific
+// first (a failure that matches several is labeled by the earliest match):
+//   hallucination       fabricated a fact / API / path
+//   false-completion    declared "done" without running the required gate/test
+//   process-stall       stopped instead of asking / continuing when it should
+//   over-caution        re-asked / re-gated despite standing authority
+//   overreach           acted beyond the requested scope
+//   incompleteness      started correctly but omitted a required step / scope
+//   instruction-miss    ignored an explicit this-session instruction
+//   convention-violation broke a standing documented convention (not restated)
+// The runtime does NOT enforce the precedence tree — it only validates that a
+// supplied value is one of these eight; classification is a human judgement.
+export const FAILURE_TYPE_ENUM = [
+  'hallucination',
+  'false-completion',
+  'process-stall',
+  'over-caution',
+  'overreach',
+  'incompleteness',
+  'instruction-miss',
+  'convention-violation',
+];

package/scripts/lib/frontmatter.mjs

@@ -1,14 +1,35 @@
+// A YAML block sequence entry: `-` followed by whitespace or end-of-line.
+// Narrower than `startsWith('-')` so a (nonstandard) plain key like `-key:` is
+// still read rather than mistaken for a list item.
+export const SEQUENCE_ENTRY_RE = /^-(\s|$)/;
+
+// Lenient, top-level-only frontmatter field extractor (NOT a YAML parser).
+// Reads only unindented `key: value` lines, skipping indented lines and list
+// items, so a nested mapping (e.g. a `type:` inside a `relations:` list) cannot
+// clobber the page's real top-level field. Without this a `learning` page
+// carrying a relations block was mis-read as `type: depends_on` and silently
+// dropped by type-routed consumers (doctor's verify-freshness scan, lint's
+// type check). First-wins on a repeated top-level key. Assumes the Hypomnema
+// convention of unindented root fields (templates/SCHEMA.md §3). scripts/lint.mjs
+// imports this and adds a separate W9 pass for invalid-YAML classes a real
+// parser would reject.
 export function parseFrontmatter(content) {
   const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (!m) return null;
   const fm = {};
   for (const line of m[1].split(/\r?\n/)) {
+    if (/^\s/.test(line) || SEQUENCE_ENTRY_RE.test(line)) continue; // nested / list item
     const idx = line.indexOf(':');
     if (idx < 0) continue;
-    fm[line.slice(0, idx).trim()] = line
+    const key = line.slice(0, idx).trim();
+    if (!key || Object.hasOwn(fm, key)) continue; // first-wins
+    fm[key] = line
       .slice(idx + 1)
       .trim()
-      .replace(/\s*#.*$/, '')
+      // strip a trailing YAML comment: `#` must follow whitespace to start one,
+      // so `concept#bad` stays literal (and still trips lint's unknown-type W2)
+      // while `concept # note` loses the comment.
+      .replace(/\s+#.*$/, '')
       .replace(/^["']|["']$/g, '');
   }
   return fm;

package/scripts/lib/schema-vocab.mjs

@@ -94,3 +94,38 @@ export function parseSchemaPageDirs(hypoDir) {
   }
   return dirs;
 }
+
+// Type-token shape: lowercase identifier (a-z, digits, hyphen). Excludes
+// memory-layer rows whose first cell is a filename (`hot.md`, `log.md`) — those
+// carry a `.` and never match — so only real type names survive.
+const TYPE_TOKEN_RE = /^[a-z][a-z0-9-]+$/;
+
+// Derive the set of valid page `type` values from the SCHEMA "Page Type
+// Taxonomy" table — the FIRST backticked cell of each table row (the type
+// column). Single source of truth, mirroring parseSchemaPageDirs: adding a type
+// row to a vault's SCHEMA automatically widens the accepted types, so a
+// vault-local extension (e.g. working-doc / draft / qa-run) stops tripping the
+// W2 unknown-type warning without editing lint. Returns an empty Set when
+// SCHEMA.md or the table is absent — callers union this with a hardcoded core so
+// the core types never depend on a present/complete SCHEMA.
+export function parseSchemaTypes(hypoDir) {
+  const path = join(hypoDir, 'SCHEMA.md');
+  if (!existsSync(path)) return new Set();
+  const content = readFileSync(path, 'utf-8');
+
+  const headerMatch = TYPE_TAXONOMY_HEADER_RE.exec(content);
+  if (!headerMatch) return new Set();
+
+  const sectionStart = headerMatch.index + headerMatch[0].length;
+  const rest = content.slice(sectionStart);
+  const nextH2 = NEXT_H2_RE.exec(rest);
+  const section = nextH2 ? rest.slice(0, nextH2.index) : rest;
+
+  const types = new Set();
+  for (const rawLine of section.split('\n')) {
+    if (!rawLine.trimStart().startsWith('|')) continue;
+    const m = rawLine.match(/`([^`]+)`/); // first backtick token = type column
+    if (m && TYPE_TOKEN_RE.test(m[1].trim())) types.add(m[1].trim());
+  }
+  return types;
+}

package/scripts/lib/template-schema-version.mjs

@@ -0,0 +1,21 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { parseFrontmatter } from './frontmatter.mjs';
+
+// The SCHEMA version this package ships, read from templates/SCHEMA.md
+// frontmatter. init.mjs / upgrade.mjs stamp it into hypo-pkg.json metadata;
+// deriving it here (rather than hardcoding a literal at each write site) keeps
+// the stamped value from going stale on a schema bump — the failure mode that
+// FEAT-1's 2.0 → 2.1 bump would otherwise have introduced. Returns null only if
+// the template is missing/unreadable (a broken package), in which case callers
+// keep their prior literal default.
+export function templateSchemaVersion(pkgRoot) {
+  const p = join(pkgRoot, 'templates', 'SCHEMA.md');
+  if (!existsSync(p)) return null;
+  try {
+    const v = (parseFrontmatter(readFileSync(p, 'utf-8')) || {}).version;
+    return v ? String(v) : null;
+  } catch {
+    return null;
+  }
+}

package/scripts/lib/wikilink.mjs

@@ -0,0 +1,156 @@
+// Shared wikilink primitives — the ONE source of truth for vault traversal,
+// slug-form generation, and bare wikilink extraction.
+//
+// Consumed by:
+//   - scripts/lint.mjs        (slug map, page collection, link-target scan)
+//   - scripts/rename.mjs      (form index with collision detection, page scan)
+//   - scripts/graph.mjs       (slug index, page collection, link extraction)
+//   - scripts/crystallize.mjs (page collection, link extraction)
+//
+// IMPR-13 consolidation. Before this lib, each script carried its own copy of
+// collectPages + a slug-form deriver, drifting in subtle ways. The four
+// collectPages variants are NOT interchangeable — they differ deliberately in
+// traversal/security/output-shape policy (codex design review, CONCERN):
+//
+//   - rename uses lstat + skips symlinks   → a vault scan can never escape via a
+//     symlinked dir/file (security boundary).
+//   - lint skips `_`-prefixed DIRECTORIES  → pages/feedback/_drafts scaffolds
+//     stay out of the lint set, while `_`-prefixed FILES (e.g. _index.md) lint.
+//   - crystallize skips ANY `.`-prefixed entry (dir AND file).
+//   - graph/lint/rename skip only `.`-prefixed FILES.
+//   - graph/crystallize emit raw `rel`/`slug`; lint keeps OS-native `rel`
+//     (its own buildSlugMap POSIX-normalizes downstream); rename/graph
+//     POSIX-normalize the slug at scan time.
+//
+// So this lib exposes ONE walker core plus four NAMED PRESETS, not a pile of
+// boolean flags — each preset pins exactly one caller's historical behavior and
+// is fixed by a unit test. readdirSync order is preserved verbatim (NO sort):
+// graph's bare-first slug index is order-sensitive (first page wins a shared
+// bare form), so adding a sort would silently change resolution.
+//
+// Collision RESOLUTION is intentionally NOT shared: lint dedups into a Set
+// (membership), rename detects ambiguity to refuse unsafe auto-rewrites, graph
+// is first-wins. Each caller builds its own structure from slugForms(); only the
+// form GENERATION lives here.
+
+import { existsSync, readdirSync, statSync, lstatSync } from 'fs';
+import { join, relative, extname, basename } from 'path';
+import { isScanIgnored } from './hypo-ignore.mjs';
+
+// ── markdown page walker (shared core) ─────────────────────────────────────────
+// `policy` keys (all optional):
+//   lstat            — stat with lstatSync and skip symlinks (rename's security
+//                      boundary). Default: statSync, symlinks followed.
+//   skipDotEntry     — skip ANY entry (dir or file) whose name starts with `.`
+//                      BEFORE the ignore check (crystallize).
+//   skipUnderscoreDir— skip directories whose name starts with `_` (lint).
+//   skipDotFile      — among `.md` files, skip names starting with `.`.
+//   shape(full)      — build the per-page record pushed onto the accumulator.
+function walkMarkdown(dir, root, ignorePatterns, policy, acc) {
+  if (!existsSync(dir)) return acc;
+  for (const entry of readdirSync(dir)) {
+    if (policy.skipDotEntry && entry.startsWith('.')) continue;
+    const full = join(dir, entry);
+    if (isScanIgnored(full, root, ignorePatterns)) continue;
+    const st = policy.lstat ? lstatSync(full) : statSync(full);
+    if (policy.lstat && st.isSymbolicLink()) continue;
+    if (st.isDirectory()) {
+      if (policy.skipUnderscoreDir && entry.startsWith('_')) continue;
+      walkMarkdown(full, root, ignorePatterns, policy, acc);
+    } else if (extname(entry) === '.md' && !(policy.skipDotFile && entry.startsWith('.'))) {
+      acc.push(policy.shape(full));
+    }
+  }
+  return acc;
+}
+
+const posixSlug = (full, root) => relative(root, full).replace(/\.md$/, '').replace(/\\/g, '/');
+
+// lint: `_`-dir skip + `_`-file kept; OS-native `rel` (buildSlugMap normalizes).
+export function collectPagesLint(dir, root, ignorePatterns = []) {
+  return walkMarkdown(
+    dir,
+    root,
+    ignorePatterns,
+    {
+      skipDotFile: true,
+      skipUnderscoreDir: true,
+      shape: (full) => ({ path: full, rel: relative(root, full) }),
+    },
+    [],
+  );
+}
+
+// graph: POSIX slug + bare, no `rel`.
+export function collectPagesGraph(dir, root, ignorePatterns = []) {
+  return walkMarkdown(
+    dir,
+    root,
+    ignorePatterns,
+    {
+      skipDotFile: true,
+      shape: (full) => ({ path: full, slug: posixSlug(full, root), bare: basename(full, '.md') }),
+    },
+    [],
+  );
+}
+
+// rename: lstat + symlink skip (security); POSIX rel/slug/bare.
+export function collectPagesRename(dir, root, ignorePatterns = []) {
+  return walkMarkdown(
+    dir,
+    root,
+    ignorePatterns,
+    {
+      lstat: true,
+      skipDotFile: true,
+      shape: (full) => {
+        const rel = relative(root, full).replace(/\\/g, '/');
+        return { path: full, rel, slug: rel.replace(/\.md$/, ''), bare: basename(full, '.md') };
+      },
+    },
+    [],
+  );
+}
+
+// crystallize: skip ANY `.`-prefixed entry; OS-native `rel`.
+export function collectPagesCrystallize(dir, root, ignorePatterns = []) {
+  return walkMarkdown(
+    dir,
+    root,
+    ignorePatterns,
+    { skipDotEntry: true, shape: (full) => ({ path: full, rel: relative(root, full) }) },
+    [],
+  );
+}
+
+// ── slug-form generation ───────────────────────────────────────────────────────
+// From a POSIX no-extension slug (e.g. `pages/learnings/foo`), derive the three
+// link forms a [[wikilink]] may use:
+//   full   — the whole slug                       [[pages/learnings/foo]]
+//   bare   — the basename                         [[foo]]
+//   dirRel — slug minus the leading scan-dir seg  [[learnings/foo]]  (null if the
+//            slug has no `/`, i.e. nothing to drop)
+// Callers pick which forms to register and own their own collision policy. Do NOT
+// apply this to link-target-only slugs (lint's root-md/sources extraTargets,
+// rename's sources/*) — those resolve VERBATIM, with no derived alias, so a bare
+// form can't mask an unrelated broken link or block a safe rewrite.
+export function slugForms(slug) {
+  const slash = slug.indexOf('/');
+  return { full: slug, bare: basename(slug), dirRel: slash === -1 ? null : slug.slice(slash + 1) };
+}
+
+// ── bare wikilink extraction (graph/crystallize variant) ───────────────────────
+// Raw extraction: matches [[target]] / [[target|alias]] / [[target#anchor]]
+// anywhere, INCLUDING inside code fences (graph counts those as edges, and
+// crystallize counts them for unlinked-page detection — preserving that is
+// behavior-stable). lint uses a DIFFERENT extractor (strips code regions and
+// handles table-escaped `\|`); rename uses length-preserving masking. Neither
+// shares this one.
+export function extractWikilinks(content) {
+  const links = [];
+  for (const m of content.matchAll(/\[\[([^\]|#]+?)(?:[|#][^\]]*?)?\]\]/g)) {
+    links.push(m[1].trim());
+  }
+  return links;
+}