hypomnema 1.6.2 → 1.7.0

package/scripts/lib/check-bilingual.mjs

@@ -1,244 +0,0 @@
-/**
- * lib/check-bilingual.mjs — pure validators for the bilingual release-doc rule.
- *
- * Rule source: CLAUDE.md learned_behaviors release-doc-bilingual (2026-05-24).
- * Every Hypomnema OSS ship must carry an English body PLUS a Korean summary
- * block in both the CHANGELOG section and the git tag annotation. This module
- * exports the parsing/validation primitives; the CLI wrapper in
- * scripts/check-bilingual.mjs handles I/O and exit codes.
- *
- * Scope (deliberate): this gate only enforces the KOREAN half. The English
- * half has been historically present in every ship — the rule exists because
- * the Korean half is what gets silently dropped under time pressure (see
- * release-doc-bilingual feedback page). A tag body of "---" + Korean with an
- * empty English section would technically pass these validators, but that's
- * acceptable because such a body is not a realistic failure mode for a
- * maintainer who already wrote the English release notes. If "English missing"
- * ever becomes a real regression vector, add an English-half threshold.
- *
- * Why pure functions: lets tests/runner.mjs construct synthetic CHANGELOG /
- * tag-body strings without touching real git or real CHANGELOG.md.
- */
-
-// AC00–D7A3 covers all precomposed Hangul syllables. We NFC-normalize the
-// input before counting so jamo-only inputs (decomposed) still match after
-// composition.
-export const HANGUL_RE = /[가-힣]/g;
-export const HANGUL_BODY_THRESHOLD = 10;
-
-export function countHangul(text) {
-  return (text.normalize('NFC').match(HANGUL_RE) || []).length;
-}
-
-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 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, 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.
-  const sectionRe = new RegExp(`^## \\[${versionEsc}\\](\\s.*)?$`);
-
-  const startIndices = [];
-  for (let i = 0; i < lines.length; i++) {
-    if (sectionRe.test(lines[i])) startIndices.push(i);
-  }
-  if (startIndices.length === 0) {
-    return { ok: false, reason: `no "## [${version}]" section in CHANGELOG.md` };
-  }
-  if (startIndices.length > 1) {
-    return {
-      ok: false,
-      reason: `duplicate "## [${version}]" sections (${startIndices.length}) in CHANGELOG.md`,
-    };
-  }
-
-  const start = startIndices[0];
-  let sectionEnd = lines.length;
-  for (let i = start + 1; i < lines.length; i++) {
-    if (/^## /.test(lines[i])) {
-      sectionEnd = i;
-      break;
-    }
-  }
-  const blockLines = lines.slice(start + 1, sectionEnd);
-  const sections = sliceSections(blockLines, 3);
-  const gated = sections.filter((s) => GATED_HEADINGS.includes(s.title));
-
-  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 };
-  }
-
-  // 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;
-  }
-  if (total < HANGUL_BODY_THRESHOLD) {
-    return {
-      ok: false,
-      reason:
-        `section [${version}] total Korean is ${total} Hangul chars ` +
-        `(threshold: ${HANGUL_BODY_THRESHOLD}). Write real Korean summaries in the "#### 한국어" sub-blocks.`,
-    };
-  }
-  return { ok: true, hangulCount: total };
-}
-
-/**
- * Validate that a git tag annotation body has a "---" separator with Korean
- * text after the LAST such separator. Tolerates earlier "---" markdown
- * horizontal rules in the English body.
- *
- * @param {string} body  Tag annotation body, as returned by
- *                       `git tag -l --format='%(contents)' <ref>`.
- * @returns {{ok: true, hangulCount: number} | {ok: false, reason: string}}
- */
-export function validateTagBody(body) {
-  const lines = body.replace(/\r\n/g, '\n').split('\n');
-  let lastSepIdx = -1;
-  for (let i = lines.length - 1; i >= 0; i--) {
-    if (lines[i].trim() === '---') {
-      lastSepIdx = i;
-      break;
-    }
-  }
-  if (lastSepIdx === -1) {
-    return {
-      ok: false,
-      reason:
-        'tag annotation has no "---" separator line (expected: English body + "---" + Korean)',
-    };
-  }
-  const tail = lines.slice(lastSepIdx + 1).join('\n');
-  const count = countHangul(tail);
-  if (count < HANGUL_BODY_THRESHOLD) {
-    return {
-      ok: false,
-      reason:
-        `tag body after the last "---" has only ${count} Hangul chars ` +
-        `(threshold: ${HANGUL_BODY_THRESHOLD}). Write a real Korean summary after the separator.`,
-    };
-  }
-  return { ok: true, hangulCount: count };
-}

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

@@ -1,217 +0,0 @@
-/**
- * lib/check-tracker-ids.mjs — pure scanner for wiki-internal tracker IDs.
- *
- * The OSS repo must not ship references to the maintainer's PRIVATE wiki issue
- * tracker (`ISSUE-N`) or fix tracker (`fix #N`) in public artifacts: an OSS user
- * who opens a shipped file or reads the README/CHANGELOG just sees a dangling
- * pointer into a tracker they cannot access. GitHub references (`PR #N`, `(#N)`,
- * bare `#N`, issue URLs) are legitimate and must NOT be flagged.
- *
- * This module is PURE (no fs, no git, no process) so it is unit-testable; the
- * CLI wrapper (scripts/check-tracker-ids.mjs) does the file/git/commit-msg I/O.
- *
- * Blocked everywhere in scope (examples use an `N` placeholder, NOT a real
- * digit, so this file itself scans clean and is NOT exempted from --all):
- *   - /\bISSUE-\d+\b/i      → the wiki issue tracker, any case (e.g. ISSUE-N)
- *   - /\bfix[ \t ]+#\d+\b/i → the wiki fix tracker, any case (e.g. fix #N)
- *   - /\bFEAT-\d+\b/i       → the wiki feature tracker, any case (e.g. FEAT-N)
- *   - /\bIMPR-\d+\b/i       → the wiki improvement tracker, any case (e.g. IMPR-N)
- *   - /\bPRAC-\d+\b/i       → the wiki practice tracker, any case (e.g. PRAC-N)
- *
- * FEAT-/IMPR-/PRAC- were once exempt inside shipped code comments; that exemption
- * shipped dangling pointers into the maintainer's private wiki to OSS users, so it
- * was removed. They now block everywhere in scope; the maintainer keeps them only
- * in tests/, qa-runs/, and local notes. The verifier subsystem that legitimately
- * carries `decisions/NNNN` runtime data is excluded from the scan instead (see the
- * CLI's EXCLUDED_FILES).
- *
- * `ADR NNNN` / `ADR-NNNN` / `decisions/NNNN` (DECISION_PATTERNS) are dangling
- * pointers into the maintainer's private wiki ADR set. They block everywhere in
- * scope EXCEPT CHANGELOG.md, whose version history legitimately cites the decision
- * behind a release line. The CLI applies these per-file via patternsFor().
- *
- * Accepted edge cases (documented, not bugs):
- *   - FALSE POSITIVE: `FOO-ISSUE-N` matches (the `-` gives a word boundary
- *     before ISSUE). Such a string in this repo would still be a tracker ref.
- *   - The `fix #N` matcher requires the literal word `fix` immediately before the
- *     `#`, so `prefix #N`, `suffix #N`, `PR #N`, `(#N)`, and bare `#N` are all
- *     safe — none start the word `fix` right before the `#`.
- */
-
-// `ADR NNNN` / `ADR-NNNN` / `decisions/NNNN` point into the maintainer's private
-// wiki ADR set, which an OSS user does not have. The CLI applies this set to every
-// in-scope file EXCEPT CHANGELOG.md (version history may cite a decision); the
-// verifier subsystem that carries decisions/ paths as runtime data is removed by
-// EXCLUDED_FILES first. The ADR matcher tolerates a space, tab, or hyphen between
-// `ADR` and the number. Examples below use `NNNN`, not real digits, so this file
-// scans clean.
-export const DECISION_PATTERNS = [
-  {
-    name: 'ADR NNNN',
-    label: 'wiki ADR pointer',
-    re: /\bADR[ \t-]+\d{3,4}\b/gi,
-  },
-  {
-    name: 'decisions/NNNN',
-    label: 'wiki decisions path',
-    re: /\bdecisions\/\d{3,4}\b/gi,
-  },
-];
-
-// Each entry: a named, /g/i regex over a single line of text.
-export const BLOCKED_PATTERNS = [
-  {
-    name: 'ISSUE-N',
-    label: 'wiki issue-tracker id',
-    re: /\bISSUE-\d+\b/gi,
-  },
-  {
-    name: 'fix #N',
-    label: 'wiki fix-tracker id',
-    re: /\bfix[ \t ]+#\d+\b/gi,
-  },
-  // FEAT-/IMPR-/PRAC- were a tag-body-only set until they were promoted here so
-  // they block in shipped code comments too (the old exemption leaked dead wiki
-  // pointers to OSS users). Examples below use `N`, not a real digit, so this
-  // file scans clean and is NOT exempted from --all.
-  { 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,
-// republished verbatim by `gh release create --notes-from-tag`). It equals
-// BLOCKED_PATTERNS now that FEAT-/IMPR-/PRAC- live there; ADR/decisions anchors
-// are intentionally allowed in the tag body (release notes cite decisions the way
-// CHANGELOG history does). The CHANGELOG's own surface-ID-0 is held by the section
-// migration + a grep regression test (changelog-pr-guide §5).
-export const TAG_BODY_PATTERNS = [...BLOCKED_PATTERNS];
-
-// Strip a leading comment-continuation marker (`*`, `//`, `#`) so a wrapped
-// comment line can be re-joined to its predecessor as flowing text.
-const COMMENT_CONT_RE = /^[ \t]*(?:\*|\/\/|#+)[ \t]?/;
-
-/**
- * Scan a blob of text against `patterns` (default BLOCKED_PATTERNS). Returns hits:
- *   { pattern, label, match, line, col, lineText }
- * `line`/`col` are 1-based. Empty array => clean. The CLI passes the broader
- * [...BLOCKED_PATTERNS, ...DECISION_PATTERNS] set for every in-scope file but the
- * CHANGELOG.
- *
- * Tracker tokens also line-wrap inside comments (`... continuing (ADR\n * 0045)`).
- * A pure per-line scan misses those, so each line is ALSO scanned joined to the
- * next (with the next line's comment-continuation marker collapsed to a space);
- * only matches that START on the current line and CROSS the join are kept, so a
- * wrap is reported exactly once at its prefix line and non-wrapped tokens are
- * never double-counted.
- */
-export function scanText(text, patterns = BLOCKED_PATTERNS) {
-  if (typeof text !== 'string' || text.length === 0) return [];
-  const hits = [];
-  const lines = text.split(/\r?\n/);
-  for (let i = 0; i < lines.length; i++) {
-    const lineText = lines[i];
-    for (const { name, label, re } of patterns) {
-      re.lastIndex = 0; // reset shared /g regex between lines
-      let m;
-      while ((m = re.exec(lineText)) !== null) {
-        hits.push({
-          pattern: name,
-          label,
-          match: m[0],
-          line: i + 1,
-          col: m.index + 1,
-          lineText,
-        });
-        if (m.index === re.lastIndex) re.lastIndex++; // never-zero-width guard
-      }
-    }
-    // Wrapped-token guard: a token can line-wrap at two points — between its
-    // prefix WORD and its number (`ADR\n0045`, where the break stands in for a
-    // space) OR right at its separator (`ISSUE-\n9`, `decisions/\n0031`,
-    // `fix #\n37`, where the digit must sit flush against `-`/`/`/`#`). So scan
-    // this line joined to the next BOTH with a space (space-separated forms) and
-    // with no gap (separator-flush forms), keeping only matches that begin on this
-    // line and cross the join. A token reconstructed by both joins (e.g. the ADR
-    // hyphen form) is de-duplicated by its whitespace-collapsed text.
-    if (i + 1 < lines.length) {
-      const lt = lineText.length;
-      const tail = lines[i + 1].replace(COMMENT_CONT_RE, '');
-      const seen = new Set();
-      for (const [joined, tailAt] of [
-        [lineText + ' ' + tail, lt + 1],
-        [lineText + tail, lt],
-      ]) {
-        for (const { name, label, re } of patterns) {
-          re.lastIndex = 0;
-          let m;
-          while ((m = re.exec(joined)) !== null) {
-            if (m.index < lt && m.index + m[0].length > tailAt) {
-              const key = name + ':' + m[0].replace(/\s+/g, '');
-              if (!seen.has(key)) {
-                seen.add(key);
-                hits.push({
-                  pattern: name,
-                  label,
-                  match: m[0],
-                  line: i + 1,
-                  col: m.index + 1,
-                  lineText: joined,
-                });
-              }
-            }
-            if (m.index === re.lastIndex) re.lastIndex++;
-          }
-        }
-      }
-    }
-  }
-  return hits;
-}
-
-/**
- * Strip a `--verbose` commit diff: everything from the scissors line onward is
- * dropped by git before the commit is recorded, so it must not be scanned. The
- * scissors art is comment-char-prefixed but the `>8` token is constant across
- * comment chars, so match on that. Returns the text up to (excluding) the
- * scissors line. If no scissors line is present, returns the input unchanged.
- */
-// git's real scissors line is COMMENT-prefixed (`# ----- >8 -----`); a bare
-// `--- >8 ---` line is NOT a scissors marker (git keeps it as body), so it must
-// not trigger truncation. Require the leading comment char (default `#`, or `;`).
-const SCISSORS_RE = /^[ \t]*[#;][ \t]*-{2,}[ \t]*>8[ \t]*-{2,}/;
-
-export function stripScissors(text) {
-  if (typeof text !== 'string') return '';
-  const lines = text.split(/\r?\n/);
-  const idx = lines.findIndex((l) => SCISSORS_RE.test(l));
-  if (idx === -1) return text;
-  return lines.slice(0, idx).join('\n');
-}
-
-/**
- * Does a commit-message file carry git's auto-generated template? git ONLY adds
- * the instructional / status comment block (and the --verbose scissors) when the
- * effective cleanup mode will STRIP comment lines (the editor default). In the
- * comment-PRESERVING modes (`git commit -m` → whitespace, `--cleanup=verbatim`)
- * git adds NO template, so a `#` line there is real committed content.
- *
- * The commit-msg hook therefore decides comment handling by template presence,
- * not by config alone: template present ⇒ scan the strip-comments view (matches
- * git, no false-positive on the template's branch/file names); template absent ⇒
- * scan the raw view so a `#`-prefixed tracker id git WILL keep is still caught.
- *
- * Markers cover the default English git template + the scissors line. Other
- * locales may miss the template and fall through to the raw (comment-keeping)
- * scan — which is the SAFE direction for a gate (catches more, never less).
- */
-export function messageHasGitTemplate(text) {
-  if (typeof text !== 'string') return false;
-  if (SCISSORS_RE_M.test(text)) return true; // --verbose scissors (comment-prefixed)
-  return /^[#;] *(Please enter the commit message|On branch |Changes to be committed:|Changes not staged for commit:|Untracked files:|Your branch (is|and))/m.test(
-    text,
-  );
-}
-
-// Multiline form of SCISSORS_RE for whole-message detection.
-const SCISSORS_RE_M = /^[ \t]*[#;][ \t]*-{2,}[ \t]*>8[ \t]*-{2,}/m;