hypomnema 1.6.2 → 1.7.0

package/scripts/lib/pre-commit-format.mjs

@@ -1,251 +0,0 @@
-/**
- * lib/pre-commit-format.mjs — pure logic for the auto-format-on-commit hook.
- *
- * Rule source: CLAUDE.md <formatting> directive. Pre-commit hook auto-runs the
- * project formatter on STAGED files only. Formatter failure is non-blocking;
- * only `git add` failure on restage is a true commit block.
- *
- * Why pure: lets tests construct synthetic staged sets without touching real
- * git or invoking prettier. The CLI shim in scripts/pre-commit-format.mjs
- * handles env resolution / repo-identity guards / process exit codes.
- *
- * Env discipline: every `git` spawn here MUST receive a caller-supplied `env`.
- * The lib never reads `process.env` for git operations — that defence is what
- * blocks GIT_DIR / GIT_WORK_TREE override attacks (see CONTRIBUTING.md).
- */
-
-import { spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-
-const STATUS_FILTER = 'ACMR';
-
-/**
- * Parse the NUL-token stream emitted by `git diff --cached --name-status -z`.
- *
- * Token shape (verified live against git 2.50): records are NUL-separated.
- *   A\0path\0          (added)
- *   M\0path\0          (modified)
- *   D\0path\0          (deleted — filtered out by --diff-filter)
- *   T\0path\0          (type change — filtered out)
- *   R<score>\0old\0new\0   (rename)
- *   C<score>\0old\0new\0   (copy)
- *
- * Paths containing TAB are valid — TAB is not a separator here (it appears in
- * the non-`-z` output, never in `-z`). Only NUL separates records.
- *
- * @param {string} buf  Raw stdout from `git diff --cached --name-status -z`.
- * @returns {Array<{path: string, status: string}>}
- */
-export function parseNameStatus(buf) {
-  const tokens = buf.split('\0');
-  // Trailing NUL leaves an empty token; drop it (and any stray empties).
-  while (tokens.length && tokens[tokens.length - 1] === '') tokens.pop();
-  const out = [];
-  for (let i = 0; i < tokens.length; ) {
-    const status = tokens[i++];
-    if (!status) continue;
-    const head = status[0];
-    if (head === 'R' || head === 'C') {
-      // Two-path record. Old is irrelevant for formatting — only the new path
-      // exists in the staged tree.
-      i++; // consume old
-      const next = tokens[i++];
-      if (next) out.push({ path: next, status: head });
-    } else if (head === 'A' || head === 'M') {
-      const p = tokens[i++];
-      if (p) out.push({ path: p, status: head });
-    } else {
-      // D, T, U, X — consume one path, drop. --diff-filter should exclude
-      // these but we defensively skip.
-      i++;
-    }
-  }
-  return out;
-}
-
-/**
- * Parse `git ls-files --stage -z` output to map paths → file mode strings.
- * Output shape: `<mode> <hash> <stage>\t<path>\0`
- */
-export function parseLsFilesStage(buf) {
-  const map = new Map();
-  const records = buf.split('\0');
-  for (const rec of records) {
-    if (!rec) continue;
-    const tabIdx = rec.indexOf('\t');
-    if (tabIdx < 0) continue;
-    const meta = rec.slice(0, tabIdx);
-    const path = rec.slice(tabIdx + 1);
-    const mode = meta.split(' ')[0];
-    map.set(path, mode);
-  }
-  return map;
-}
-
-/**
- * Drop symlinks (120000) and gitlinks/submodules (160000). Regular file modes
- * (100644, 100755) are kept.
- */
-export function filterRegularFiles(entries, modeMap) {
-  return entries.filter((e) => {
-    const m = modeMap.get(e.path);
-    if (!m) return false; // not in index — defensively skip
-    return m !== '120000' && m !== '160000';
-  });
-}
-
-/**
- * Partition staged paths into safe vs partial (also has unstaged hunks).
- * Partial files are skipped to avoid swallowing unstaged work.
- */
-export function partitionStagedFiles(entries, unstagedDirty) {
-  const safe = [];
-  const partial = [];
-  for (const e of entries) {
-    if (unstagedDirty.has(e.path)) partial.push(e);
-    else safe.push(e);
-  }
-  return { safe, partial };
-}
-
-/**
- * Formatter dispatch table. Other entries (eslint, black, gofmt, cargo fmt)
- * are placeholders — the table is data, not a branch tree. Activate by
- * filling in an entry similar to `prettier`.
- *
- * Critically: NEVER use `npx` here. `npx prettier` may try a network install
- * on a cold machine; we want a local-only binary or no-op.
- */
-export function selectFormatter(repoRoot) {
-  const prettierBin = join(repoRoot, 'node_modules', '.bin', 'prettier');
-  if (existsSync(prettierBin)) {
-    return {
-      name: 'prettier',
-      bin: prettierBin,
-      buildArgs: (files) => ['--write', '--', ...files],
-    };
-  }
-  return null;
-}
-
-/**
- * Run the formatter once with all safe files. Captures exit status; never
- * throws.
- */
-export function formatFiles(safe, formatter, { env, cwd } = {}) {
-  if (!safe.length || !formatter) {
-    return { ran: false, formatterFailed: false, reason: 'noop' };
-  }
-  const paths = safe.map((e) => e.path);
-  const res = spawnSync(formatter.bin, formatter.buildArgs(paths), {
-    cwd,
-    env,
-    encoding: 'utf-8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
-  return {
-    ran: true,
-    formatterFailed: res.status !== 0,
-    exitCode: res.status,
-    stdout: res.stdout || '',
-    stderr: res.stderr || '',
-  };
-}
-
-/**
- * Re-stage the formatted files. Returns `{gitAddFailed: bool, stderr}`.
- * Prettier `--write` only writes on actual content change, so re-adding
- * unchanged files is a cheap no-op. Doing it unconditionally avoids a
- * before/after hash comparison.
- */
-export function restageFormatted(files, { env, cwd } = {}) {
-  if (!files.length) return { gitAddFailed: false };
-  const res = spawnSync('git', ['add', '--', ...files], {
-    cwd,
-    env,
-    encoding: 'utf-8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
-  return {
-    gitAddFailed: res.status !== 0,
-    stderr: res.stderr || '',
-  };
-}
-
-/**
- * Top-level orchestrator used by the CLI shim. The caller supplies `cwd`
- * (the Hypomnema toplevel) and a sanitized `env` (no inherited `GIT_*`
- * except optionally a validated `GIT_INDEX_FILE`).
- *
- * @returns {{gitAddFailed: boolean, summary: string}}
- */
-export async function runPreCommitFormat({ cwd, env }) {
-  const summary = [];
-  const stagedRes = spawnSync(
-    'git',
-    ['diff', '--cached', '--name-status', '-z', `--diff-filter=${STATUS_FILTER}`, '--'],
-    { cwd, env, encoding: 'utf-8' },
-  );
-  if (stagedRes.status !== 0) {
-    return { gitAddFailed: false, summary: 'git diff --cached failed; skipping' };
-  }
-  const staged = parseNameStatus(stagedRes.stdout || '');
-  if (!staged.length) return { gitAddFailed: false, summary: 'no staged files' };
-
-  // Filter out symlinks / submodules.
-  const lsRes = spawnSync(
-    'git',
-    ['ls-files', '--stage', '-z', '--', ...staged.map((e) => e.path)],
-    { cwd, env, encoding: 'utf-8' },
-  );
-  let regular = staged;
-  if (lsRes.status === 0) {
-    const modeMap = parseLsFilesStage(lsRes.stdout || '');
-    regular = filterRegularFiles(staged, modeMap);
-  }
-  if (!regular.length) return { gitAddFailed: false, summary: 'no regular staged files' };
-
-  // Unstaged-dirty set for partition.
-  const unstRes = spawnSync('git', ['diff', '--name-only', '-z', '--'], {
-    cwd,
-    env,
-    encoding: 'utf-8',
-  });
-  const unstaged = new Set();
-  if (unstRes.status === 0) {
-    for (const p of (unstRes.stdout || '').split('\0')) {
-      if (p) unstaged.add(p);
-    }
-  }
-  const { safe, partial } = partitionStagedFiles(regular, unstaged);
-  if (partial.length) {
-    summary.push(`skipped ${partial.length} partially-staged file(s)`);
-  }
-  if (!safe.length) return { gitAddFailed: false, summary: summary.join('; ') || 'no safe files' };
-
-  const formatter = selectFormatter(cwd);
-  if (!formatter) {
-    return {
-      gitAddFailed: false,
-      summary: [...summary, 'no formatter (node_modules/.bin/prettier missing)'].join('; '),
-    };
-  }
-  const fmt = formatFiles(safe, formatter, { env, cwd });
-  if (fmt.formatterFailed) {
-    summary.push(`${formatter.name} exit ${fmt.exitCode} (non-blocking)`);
-    return { gitAddFailed: false, summary: summary.join('; ') };
-  }
-  const restage = restageFormatted(
-    safe.map((e) => e.path),
-    { env, cwd },
-  );
-  if (restage.gitAddFailed) {
-    return {
-      gitAddFailed: true,
-      summary: `git add failed: ${restage.stderr.trim()}`,
-    };
-  }
-  summary.push(`formatted ${safe.length} file(s) via ${formatter.name}`);
-  return { gitAddFailed: false, summary: summary.join('; ') };
-}

package/scripts/pre-commit-format.mjs

@@ -1,198 +0,0 @@
-#!/usr/bin/env node
-/**
- * scripts/pre-commit-format.mjs — Node-side entry for the pre-commit hook.
- *
- * Invoked by the shell shim installed at <git-dir>/hooks/pre-commit. The shim
- * already verifies HYPOMNEMA_ROOT + HYPOMNEMA_GIT_DIR; this script is the
- * second layer of identity defence and the only place that may exit nonzero
- * (only when `git add` fails on restage).
- *
- * Env discipline:
- *   - probes git twice with ambient env to learn what Git thinks the repo is
- *   - builds `cleanEnv` by stripping every name from `git rev-parse --local-env-vars`
- *     plus GIT_NAMESPACE / GIT_CEILING_DIRECTORIES / GIT_CONFIG_* (belt-and-suspenders)
- *   - validates inherited GIT_INDEX_FILE: preserve if inside HYPOMNEMA_GIT_DIR
- *     (Git exports this for commit -am / commit -- path / commit --amend);
- *     otherwise refuse — that's a foreign-index attack vector
- *   - lib spawns get `cleanEnv` only; lib never touches process.env directly
- *
- * Why dynamic import: keeping the lib import behind every guard makes the
- * fail-open story water-tight. A static import at file head would throw at
- * module load if the lib were missing or syntactically broken, before any
- * identity check could exit 0.
- *
- * Why pathToFileURL for the import: absolute filesystem paths fed to
- * `import()` break when the checkout path contains URL-significant characters
- * (#, %). pathToFileURL is the canonical Node way to bridge.
- */
-
-try {
-  const { execFileSync } = await import('node:child_process');
-  const fs = await import('node:fs');
-  const path = await import('node:path');
-  const { pathToFileURL, fileURLToPath } = await import('node:url');
-
-  const probe = (args, env) => execFileSync('git', args, { encoding: 'utf8', env }).trim();
-
-  // (0) Derive expectedRoot from THIS script's filesystem location. The shell
-  //     shim already verifies HYPOMNEMA_ROOT/HYPOMNEMA_GIT_DIR before exec'ing
-  //     us, but a direct `node scripts/pre-commit-format.mjs` invocation with
-  //     hostile GIT_DIR/GIT_WORK_TREE pointing at another repo that ALSO calls
-  //     itself "hypomnema" would bypass the package.json identity check unless
-  //     we anchor on the script's own location. import.meta.url cannot be
-  //     redirected by ambient env.
-  let expectedRoot;
-  try {
-    const here = path.dirname(fileURLToPath(import.meta.url));
-    expectedRoot = fs.realpathSync(path.resolve(here, '..'));
-  } catch {
-    process.exit(0);
-  }
-
-  // (1) Probe with ambient env to learn what Git thinks the repo is.
-  let toplevel, absGitDir, commonDir;
-  try {
-    toplevel = probe(['rev-parse', '--show-toplevel'], process.env);
-    absGitDir = probe(['rev-parse', '--absolute-git-dir'], process.env);
-    commonDir = probe(['rev-parse', '--git-common-dir'], process.env);
-  } catch {
-    process.exit(0);
-  }
-
-  // (2) Realpath-resolve for stable comparison.
-  let absGitDirR, commonDirR, toplevelR;
-  try {
-    absGitDirR = fs.realpathSync(absGitDir);
-    const cdAbs = path.isAbsolute(commonDir) ? commonDir : path.join(absGitDir, '..', commonDir);
-    commonDirR = fs.realpathSync(cdAbs);
-    toplevelR = fs.realpathSync(toplevel);
-  } catch {
-    process.exit(0);
-  }
-
-  // (3) Trust anchor — refuse to run against any toplevel other than this
-  //     script's own checkout. Closes the GIT_DIR/GIT_WORK_TREE attack where a
-  //     foreign hypomnema-named repo would otherwise pass the package.json check.
-  if (toplevelR !== expectedRoot) process.exit(0);
-
-  // (3a) Anchor the git dir to the expected location too. Without this, a
-  //      mixed-env attack — GIT_DIR=/foreign/.git + GIT_WORK_TREE=expectedRoot
-  //      + GIT_INDEX_FILE=/foreign/.git/index — would let `absGitDirR` point at
-  //      the foreign repo while `--show-toplevel` reports expectedRoot. The
-  //      subsequent GIT_INDEX_FILE check would then pass relative to the
-  //      foreign git dir, and the lib would operate on a foreign index while
-  //      mutating real files. (Live-verified by codex round 7.)
-  let expectedGitDirR;
-  try {
-    expectedGitDirR = fs.realpathSync(path.join(expectedRoot, '.git'));
-  } catch {
-    process.exit(0);
-  }
-  if (absGitDirR !== expectedGitDirR) process.exit(0);
-
-  // (4) Linked worktree → main-worktree only (documented limitation).
-  if (absGitDirR !== commonDirR) process.exit(0);
-
-  // (5) Repo identity check — package.json name must be "hypomnema" (defence in
-  //     depth alongside the expectedRoot anchor above).
-  const pkgPath = path.join(toplevelR, 'package.json');
-  if (!fs.existsSync(pkgPath)) process.exit(0);
-  let pkg;
-  try {
-    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-  } catch {
-    process.exit(0);
-  }
-  if (pkg?.name !== 'hypomnema') process.exit(0);
-
-  // (5) Build trusted env from --local-env-vars + GIT_CONFIG_* belt.
-  let localEnvList;
-  try {
-    localEnvList = probe(['rev-parse', '--local-env-vars'], process.env)
-      .split(/\r?\n/)
-      .filter(Boolean);
-  } catch {
-    // Static fallback (Git versions where --local-env-vars is unavailable).
-    localEnvList = [
-      'GIT_DIR',
-      'GIT_WORK_TREE',
-      'GIT_INDEX_FILE',
-      'GIT_OBJECT_DIRECTORY',
-      'GIT_ALTERNATE_OBJECT_DIRECTORIES',
-      'GIT_COMMON_DIR',
-      'GIT_CONFIG',
-      'GIT_CONFIG_PARAMETERS',
-      'GIT_PREFIX',
-      'GIT_IMPLICIT_WORK_TREE',
-      'GIT_GRAFT_FILE',
-      'GIT_NO_REPLACE_OBJECTS',
-      'GIT_REPLACE_REF_BASE',
-      'GIT_SHALLOW_FILE',
-    ];
-  }
-  const scrub = new Set([
-    ...localEnvList,
-    'GIT_NAMESPACE',
-    'GIT_CEILING_DIRECTORIES',
-    ...Object.keys(process.env).filter((k) => /^GIT_CONFIG_/.test(k)),
-  ]);
-  const cleanEnv = Object.fromEntries(Object.entries(process.env).filter(([k]) => !scrub.has(k)));
-
-  // (6) GIT_INDEX_FILE preservation gated on shim invocation. Git legitimately
-  //     exports this for these commit shapes (verified live by codex round 5/9
-  //     on Git 2.50.1):
-  //       - .git/index             normal commit, commit --amend, merge commit
-  //       - .git/index.lock        commit -am, commit -p, commit --interactive
-  //       - .git/next-index-*.lock commit -- <pathspec>, rebase partial commit
-  //     The basename whitelist used in v8/v9 had a residual gap: a crafted
-  //     .git/next-index-attack.lock matches the `next-index-*` prefix even
-  //     though Git itself uses `next-index-<pid>.lock` (codex round 9 live
-  //     replay). Closing that prefix gap by tightening pattern just invites
-  //     more attacker iteration.
-  //
-  //     The cleaner defence: only honour inherited GIT_INDEX_FILE when we
-  //     were invoked from our own trusted shell shim (HYPOMNEMA_HOOK_INVOCATION
-  //     sentinel set there). Direct invocation — which is the only path an
-  //     attacker can use to plant a crafted index — drops the inherited value
-  //     and lets git fall back to the default `.git/index`, i.e. the real
-  //     staged set. The hook then either has nothing to do (no real stage) or
-  //     formats the real stage (correct behaviour). An attacker that can also
-  //     set HYPOMNEMA_HOOK_INVOCATION already has full env control and can
-  //     mutate files directly without going through the hook gadget.
-  const fromShim = process.env.HYPOMNEMA_HOOK_INVOCATION === '1';
-  if (fromShim && process.env.GIT_INDEX_FILE) {
-    // Even when trusted, sanity-check that the path lives inside our git dir.
-    // Belt-and-suspenders against shim invocation with an inherited but
-    // misdirected GIT_INDEX_FILE (e.g. by a wrapper that exec'd our shim).
-    const inherited = process.env.GIT_INDEX_FILE;
-    const lexical = path.isAbsolute(inherited) ? inherited : path.join(toplevelR, inherited);
-    let absIdx;
-    try {
-      absIdx = fs.realpathSync(lexical);
-    } catch {
-      absIdx = path.resolve(lexical);
-    }
-    if (path.dirname(absIdx) === absGitDirR) {
-      cleanEnv.GIT_INDEX_FILE = inherited;
-    }
-  }
-  // If !fromShim, GIT_INDEX_FILE stays scrubbed → lib uses default .git/index.
-
-  // (7) Dynamic-import the lib through a file:// URL so checkout paths with
-  //     URL-significant chars (#, %) don't break ESM resolution. We import
-  //     from expectedRoot, not toplevel — the script's own location is the
-  //     anchor of trust.
-  const libPath = path.join(expectedRoot, 'scripts/lib/pre-commit-format.mjs');
-  let lib;
-  try {
-    lib = await import(pathToFileURL(libPath).href);
-  } catch {
-    process.exit(0);
-  }
-
-  const result = await lib.runPreCommitFormat({ cwd: toplevelR, env: cleanEnv });
-  if (result.summary) process.stderr.write(`[pre-commit-format] ${result.summary}\n`);
-  process.exit(result.gitAddFailed ? 1 : 0);
-} catch {
-  process.exit(0);
-}