fix: verify nix dependency hash for lock-only changes (#293)

## Related Issue
No tracking issue. Maintainer follow-up to #291.

## Problem
The pre-push freshness proxy rejects lockfile changes whenever flake.nix
is unchanged, even when the fetched dependency output still matches the
pinned hash. A forced dependency rebuild confirmed this false positive
after #291.

## What changed
- Keep the existing fast path for unchanged lockfiles or changed flakes.
- For lock-only changes, rebuild the dependency derivation from the
exact committed HEAD with a ten-minute timeout. A missing Nix executable
or failed verification still blocks the push.
- Update the hook failure message and cover successful and failed
verification in the existing script tests.

Validation: three regression tests, CLI tsc and tsgo, actual dependency
rebuild, and all pre-push checks passed. Full repository validation is
in progress.

## Checklist
- [x] I have read the CONTRIBUTING document.
- [ ] I have linked a related issue (no tracking issue; maintainer
follow-up).
- [x] I have added tests that prove the changed behavior.
- [x] Ran gen-changesets; no changeset needed for development-only
tooling.
- [x] No user documentation update is needed; script and hook guidance
are updated.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Bug Fixes**
* Nix dependency hash checks now verify the committed dependency build
directly, improving detection of stale hashes.
* Verification failures now clearly report build errors or unavailable
Nix and direct users to the relevant output.
* Lockfile-only changes are accepted when the dependency rebuild
succeeds.
* **Tests**
* Added coverage for successful and failed dependency-hash verification
scenarios.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: elkaix

apps/pythinker-code/test/scripts/check-nix-hash-fresh.test.ts

@@ -46,7 +46,17 @@ describe('check-nix-hash-fresh', () => {
 
     const result = runCheck(root);
     expect(result.status, result.stderr).toBe(1);
-    expect(result.stderr).toContain('pnpm-lock.yaml changed on this branch but flake.nix did not');
+    expect(result.stderr).toContain('could not verify the committed dependency hash');
+  });
+
+  it('accepts a lock-only change when the dependency rebuild verifies its hash', () => {
+    const root = makeRepository('feature');
+    setRemoteRef(root, 'main', revParse(root, 'HEAD'));
+    writeFileSync(join(root, 'pnpm-lock.yaml'), 'equivalent dependency closure\n');
+    commit(root, 'update lock without changing fetched dependencies');
+
+    const result = runCheck(root, 0);
+    expect(result.status, result.stderr).toBe(0);
   });
 });
 
@@ -84,6 +94,11 @@ function git(root: string, args: string[]): string {
   return execFileSync('git', args, { cwd: root, encoding: 'utf8' }).trim();
 }
 
-function runCheck(root: string): SpawnSyncReturns<string> {
-  return spawnSync(process.execPath, [checkScript], { cwd: root, encoding: 'utf8' });
+function runCheck(root: string, nixExitCode = 1): SpawnSyncReturns<string> {
+  writeFileSync(join(root, 'nix'), `#!/bin/sh\nexit ${nixExitCode}\n`, { mode: 0o755 });
+  return spawnSync(process.execPath, [checkScript], {
+    cwd: root,
+    encoding: 'utf8',
+    env: { ...process.env, PATH: `${root}:${process.env['PATH']}` },
+  });
 }

scripts/check-nix-hash-fresh.mjs

@@ -1,17 +1,9 @@
 #!/usr/bin/env node
-// Cheap proxy for the Nix fetchPnpmDeps hash going stale.
-//
-// flake.nix pins a `hash = "sha256-..."` for pkgs.fetchPnpmDeps, computed
-// from pnpm-lock.yaml. If the lockfile changes and nobody refreshes that
-// hash, `nix build` fails in CI with a hash mismatch. Recomputing the real
-// hash requires `nix`, which may not be installed locally, so this checks a
-// proxy instead: did pnpm-lock.yaml change on this branch without flake.nix
-// also changing? That's not proof the hash is stale (a flake.nix edit could
-// be unrelated), but it's the cheap signal that catches the common case.
-//
-// ponytail: proxy check, not a real hash recompute — upgrade to `nix build
-// --dry-run` locally if false positives/negatives become a problem.
+// Use the branch diff as a fast path, then verify inconclusive lock-only changes
+// against the committed dependency derivation. Rebuild fixed-output dependencies
+// so a cached store path cannot hide a stale hash.
 import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
 
 function git(args) {
   return execFileSync('git', args, { encoding: 'utf8' }).trim();
@@ -60,10 +52,20 @@ if (!lockChanged || flakeChanged) {
   process.exit(0);
 }
 
-console.error(
-  '❌ pnpm-lock.yaml changed on this branch but flake.nix did not.\n' +
-    '   flake.nix pins a fetchPnpmDeps hash of pnpm-lock.yaml, so its hash may be stale.\n' +
-    '   Refresh it: run a nix build (e.g. `nix build .#pythinker-code`), take the sha256-... hash\n' +
-    '   from the mismatch error, paste it into the `hash = "sha256-...";` line in flake.nix, commit, and re-push.',
-);
-process.exit(1);
+console.log('[nix-hash-freshness] lockfile changed without flake.nix; verifying the committed dependency hash.');
+try {
+  const source = pathToFileURL(git(['rev-parse', '--show-toplevel']));
+  source.searchParams.set('rev', git(['rev-parse', 'HEAD']));
+  source.hash = 'pythinker-code.pnpmDeps';
+  execFileSync('nix', ['build', `git+${source.href}`, '--rebuild', '--no-link'], {
+    stdio: 'inherit',
+    timeout: 600_000,
+  });
+} catch (error) {
+  console.error(
+    '[nix-hash-freshness] could not verify the committed dependency hash. ' +
+      'Install Nix if unavailable, resolve build errors, or refresh flake.nix with the reported hash.',
+  );
+  console.error(error.message);
+  process.exit(1);
+}

scripts/pre-push.sh

@@ -71,9 +71,9 @@ step "lint" pnpm run lint || fail "lint" "oxlint reported errors"
 step "web-bundle-freshness" node apps/pythinker-code/scripts/check-web-assets.mjs ||
   fail "build" "apps/pythinker-web changed without restaging dist-web (run 'pnpm run build:web')"
 
-# 5. Nix fetchPnpmDeps hash freshness proxy (CI: nix build).
+# 5. Nix fetchPnpmDeps hash freshness (CI: nix build).
 step "nix-hash-freshness" node scripts/check-nix-hash-fresh.mjs ||
-  fail "nix build (flake.nix)" "pnpm-lock.yaml changed without refreshing flake.nix's pnpmDeps hash"
+  fail "nix build (flake.nix)" "could not verify flake.nix's pnpmDeps hash (see Nix output above)"
 
 # 6. Typecheck, scoped to packages changed since $base_ref (CI: `pnpm run
 #    typecheck`). Full typecheck builds every package first and takes