feat(hooks): add shared resolve-formatter utility with caching

Extract project-root discovery, formatter detection, and binary
resolution into a reusable module. Caches results per-process to
avoid redundant filesystem lookups on every Edit hook invocation.

This is the foundation for eliminating npx overhead in format hooks.

scripts/lib/resolve-formatter.js

@@ -0,0 +1,156 @@
+/**
+ * Shared formatter resolution utilities with caching.
+ *
+ * Extracts project-root discovery, formatter detection, and binary
+ * resolution into a single module so that post-edit-format.js and
+ * quality-gate.js avoid duplicating work and filesystem lookups.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ── Caches (per-process, cleared on next hook invocation) ───────────
+const projectRootCache = new Map();
+const formatterCache = new Map();
+const binCache = new Map();
+
+// ── Public helpers ──────────────────────────────────────────────────
+
+/**
+ * Walk up from `startDir` until a directory containing package.json is found.
+ * Returns `startDir` as fallback when no package.json exists above it.
+ *
+ * @param {string} startDir - Absolute directory path to start from
+ * @returns {string} Absolute path to the project root
+ */
+function findProjectRoot(startDir) {
+  if (projectRootCache.has(startDir)) return projectRootCache.get(startDir);
+
+  let dir = startDir;
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) {
+      projectRootCache.set(startDir, dir);
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+
+  projectRootCache.set(startDir, startDir);
+  return startDir;
+}
+
+/**
+ * Detect the formatter configured in the project.
+ * Biome takes priority over Prettier.
+ *
+ * @param {string} projectRoot - Absolute path to the project root
+ * @returns {'biome' | 'prettier' | null}
+ */
+function detectFormatter(projectRoot) {
+  if (formatterCache.has(projectRoot)) return formatterCache.get(projectRoot);
+
+  const biomeConfigs = ['biome.json', 'biome.jsonc'];
+  for (const cfg of biomeConfigs) {
+    if (fs.existsSync(path.join(projectRoot, cfg))) {
+      formatterCache.set(projectRoot, 'biome');
+      return 'biome';
+    }
+  }
+
+  const prettierConfigs = [
+    '.prettierrc',
+    '.prettierrc.json',
+    '.prettierrc.js',
+    '.prettierrc.cjs',
+    '.prettierrc.mjs',
+    '.prettierrc.yml',
+    '.prettierrc.yaml',
+    '.prettierrc.toml',
+    'prettier.config.js',
+    'prettier.config.cjs',
+    'prettier.config.mjs',
+  ];
+  for (const cfg of prettierConfigs) {
+    if (fs.existsSync(path.join(projectRoot, cfg))) {
+      formatterCache.set(projectRoot, 'prettier');
+      return 'prettier';
+    }
+  }
+
+  formatterCache.set(projectRoot, null);
+  return null;
+}
+
+/**
+ * Resolve the formatter binary, preferring the local node_modules/.bin
+ * installation over npx to avoid package-resolution overhead.
+ *
+ * @param {string} projectRoot - Absolute path to the project root
+ * @param {'biome' | 'prettier'} formatter - Detected formatter name
+ * @returns {{ bin: string, prefix: string[] }}
+ *   `bin`    – executable path (absolute local path or npx/npx.cmd)
+ *   `prefix` – extra args to prepend (e.g. ['@biomejs/biome'] when using npx)
+ */
+function resolveFormatterBin(projectRoot, formatter) {
+  const cacheKey = `${projectRoot}:${formatter}`;
+  if (binCache.has(cacheKey)) return binCache.get(cacheKey);
+
+  const isWin = process.platform === 'win32';
+  const npxBin = isWin ? 'npx.cmd' : 'npx';
+
+  if (formatter === 'biome') {
+    const localBin = path.join(
+      projectRoot,
+      'node_modules',
+      '.bin',
+      isWin ? 'biome.cmd' : 'biome',
+    );
+    if (fs.existsSync(localBin)) {
+      const result = { bin: localBin, prefix: [] };
+      binCache.set(cacheKey, result);
+      return result;
+    }
+    const result = { bin: npxBin, prefix: ['@biomejs/biome'] };
+    binCache.set(cacheKey, result);
+    return result;
+  }
+
+  if (formatter === 'prettier') {
+    const localBin = path.join(
+      projectRoot,
+      'node_modules',
+      '.bin',
+      isWin ? 'prettier.cmd' : 'prettier',
+    );
+    if (fs.existsSync(localBin)) {
+      const result = { bin: localBin, prefix: [] };
+      binCache.set(cacheKey, result);
+      return result;
+    }
+    const result = { bin: npxBin, prefix: ['prettier'] };
+    binCache.set(cacheKey, result);
+    return result;
+  }
+
+  const result = { bin: npxBin, prefix: [] };
+  binCache.set(cacheKey, result);
+  return result;
+}
+
+/**
+ * Clear all caches. Useful for testing.
+ */
+function clearCaches() {
+  projectRootCache.clear();
+  formatterCache.clear();
+  binCache.clear();
+}
+
+module.exports = {
+  findProjectRoot,
+  detectFormatter,
+  resolveFormatterBin,
+  clearCaches,
+};

tests/lib/resolve-formatter.test.js

@@ -0,0 +1,198 @@
+/**
+ * Tests for scripts/lib/resolve-formatter.js
+ *
+ * Run with: node tests/lib/resolve-formatter.test.js
+ */
+
+const assert = require('assert');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const {
+  findProjectRoot,
+  detectFormatter,
+  resolveFormatterBin,
+  clearCaches,
+} = require('../../scripts/lib/resolve-formatter');
+
+// Test helper
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  ✓ ${name}`);
+    return true;
+  } catch (err) {
+    console.log(`  ✗ ${name}`);
+    console.log(`    Error: ${err.message}`);
+    return false;
+  }
+}
+
+function makeTmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'resolve-fmt-'));
+}
+
+function runTests() {
+  console.log('\n=== Testing resolve-formatter.js ===\n');
+
+  let passed = 0;
+  let failed = 0;
+
+  function run(name, fn) {
+    clearCaches();
+    if (test(name, fn)) passed++;
+    else failed++;
+  }
+
+  // ── findProjectRoot ───────────────────────────────────────────
+
+  run('findProjectRoot: finds package.json in parent dir', () => {
+    const root = makeTmpDir();
+    const sub = path.join(root, 'src', 'lib');
+    fs.mkdirSync(sub, { recursive: true });
+    fs.writeFileSync(path.join(root, 'package.json'), '{}');
+
+    assert.strictEqual(findProjectRoot(sub), root);
+  });
+
+  run('findProjectRoot: returns startDir when no package.json', () => {
+    const root = makeTmpDir();
+    const sub = path.join(root, 'deep');
+    fs.mkdirSync(sub, { recursive: true });
+
+    // No package.json anywhere in tmp → falls back to startDir
+    assert.strictEqual(findProjectRoot(sub), sub);
+  });
+
+  run('findProjectRoot: caches result for same startDir', () => {
+    const root = makeTmpDir();
+    fs.writeFileSync(path.join(root, 'package.json'), '{}');
+
+    const first = findProjectRoot(root);
+    // Remove package.json — cache should still return the old result
+    fs.unlinkSync(path.join(root, 'package.json'));
+    const second = findProjectRoot(root);
+
+    assert.strictEqual(first, second);
+  });
+
+  // ── detectFormatter ───────────────────────────────────────────
+
+  run('detectFormatter: detects biome.json', () => {
+    const root = makeTmpDir();
+    fs.writeFileSync(path.join(root, 'biome.json'), '{}');
+    assert.strictEqual(detectFormatter(root), 'biome');
+  });
+
+  run('detectFormatter: detects biome.jsonc', () => {
+    const root = makeTmpDir();
+    fs.writeFileSync(path.join(root, 'biome.jsonc'), '{}');
+    assert.strictEqual(detectFormatter(root), 'biome');
+  });
+
+  run('detectFormatter: detects .prettierrc', () => {
+    const root = makeTmpDir();
+    fs.writeFileSync(path.join(root, '.prettierrc'), '{}');
+    assert.strictEqual(detectFormatter(root), 'prettier');
+  });
+
+  run('detectFormatter: detects prettier.config.js', () => {
+    const root = makeTmpDir();
+    fs.writeFileSync(path.join(root, 'prettier.config.js'), 'module.exports = {}');
+    assert.strictEqual(detectFormatter(root), 'prettier');
+  });
+
+  run('detectFormatter: biome takes priority over prettier', () => {
+    const root = makeTmpDir();
+    fs.writeFileSync(path.join(root, 'biome.json'), '{}');
+    fs.writeFileSync(path.join(root, '.prettierrc'), '{}');
+    assert.strictEqual(detectFormatter(root), 'biome');
+  });
+
+  run('detectFormatter: returns null when no config found', () => {
+    const root = makeTmpDir();
+    assert.strictEqual(detectFormatter(root), null);
+  });
+
+  // ── resolveFormatterBin ───────────────────────────────────────
+
+  run('resolveFormatterBin: uses local biome binary when available', () => {
+    const root = makeTmpDir();
+    const binDir = path.join(root, 'node_modules', '.bin');
+    fs.mkdirSync(binDir, { recursive: true });
+    const binName = process.platform === 'win32' ? 'biome.cmd' : 'biome';
+    fs.writeFileSync(path.join(binDir, binName), '');
+
+    const result = resolveFormatterBin(root, 'biome');
+    assert.strictEqual(result.bin, path.join(binDir, binName));
+    assert.deepStrictEqual(result.prefix, []);
+  });
+
+  run('resolveFormatterBin: falls back to npx for biome', () => {
+    const root = makeTmpDir();
+    const result = resolveFormatterBin(root, 'biome');
+    const expectedBin = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+    assert.strictEqual(result.bin, expectedBin);
+    assert.deepStrictEqual(result.prefix, ['@biomejs/biome']);
+  });
+
+  run('resolveFormatterBin: uses local prettier binary when available', () => {
+    const root = makeTmpDir();
+    const binDir = path.join(root, 'node_modules', '.bin');
+    fs.mkdirSync(binDir, { recursive: true });
+    const binName = process.platform === 'win32' ? 'prettier.cmd' : 'prettier';
+    fs.writeFileSync(path.join(binDir, binName), '');
+
+    const result = resolveFormatterBin(root, 'prettier');
+    assert.strictEqual(result.bin, path.join(binDir, binName));
+    assert.deepStrictEqual(result.prefix, []);
+  });
+
+  run('resolveFormatterBin: falls back to npx for prettier', () => {
+    const root = makeTmpDir();
+    const result = resolveFormatterBin(root, 'prettier');
+    const expectedBin = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+    assert.strictEqual(result.bin, expectedBin);
+    assert.deepStrictEqual(result.prefix, ['prettier']);
+  });
+
+  run('resolveFormatterBin: caches resolved binary', () => {
+    const root = makeTmpDir();
+    const binDir = path.join(root, 'node_modules', '.bin');
+    fs.mkdirSync(binDir, { recursive: true });
+    const binName = process.platform === 'win32' ? 'biome.cmd' : 'biome';
+    fs.writeFileSync(path.join(binDir, binName), '');
+
+    const first = resolveFormatterBin(root, 'biome');
+    fs.unlinkSync(path.join(binDir, binName));
+    const second = resolveFormatterBin(root, 'biome');
+
+    assert.strictEqual(first.bin, second.bin);
+  });
+
+  // ── clearCaches ───────────────────────────────────────────────
+
+  run('clearCaches: clears all cached values', () => {
+    const root = makeTmpDir();
+    fs.writeFileSync(path.join(root, 'package.json'), '{}');
+    fs.writeFileSync(path.join(root, 'biome.json'), '{}');
+
+    findProjectRoot(root);
+    detectFormatter(root);
+    resolveFormatterBin(root, 'biome');
+
+    clearCaches();
+
+    // After clearing, removing config should change detection
+    fs.unlinkSync(path.join(root, 'biome.json'));
+    assert.strictEqual(detectFormatter(root), null);
+  });
+
+  // ── Summary ───────────────────────────────────────────────────
+
+  console.log(`\n  ${passed} passed, ${failed} failed\n`);
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+runTests();