Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

17.4 KB
Raw Blame
// @vitest-environment node

/**
 * Repo-wide guard: `hooks/useMounted.js` is the only mounted-guard ref.
 *
 * Two rules, one bug class.
 *
 * ## 1. A mounted-guard ref must re-arm itself on mount
 *
 * The broken shape is a ref seeded `useRef(true)` whose ONLY assignment is
 * `false` in an effect cleanup:
 *
 *   const mountedRef = useRef(true);
 *   useEffect(() => () => { mountedRef.current = false; }, []);   // ← no setup body
 *
 * It reads as correct, and it is — in production. But the app runs under
 * `React.StrictMode` (`client/src/main.jsx`), and React's dev build mounts every
 * component as setup → cleanup → setup on the SAME instance. Refs survive that
 * cycle, so the cleanup flips the flag to `false` and nothing ever flips it back:
 * every `if (mountedRef.current) setX(...)` in the component is dead for the rest
 * of the dev session. That shipped as two user-visible freezes — MusicGenPanel
 * stuck on "Loading generators…" forever, and every `useAsyncAction` button stuck
 * in its disabled/spinner state after one click (#3264).
 *
 * The rule is deliberately shape-based rather than name-based — a ref called
 * `editorMountedRef` carries the identical bug, and one of the sites this guard
 * was written for was named exactly that.
 *
 * ## 2. Nothing may hand-roll the guard at all, even correctly
 *
 * `#3264` fixed fourteen sites that hand-rolled the guard *wrong*; thirteen more
 * hand-rolled it *right* and were therefore invisible to rule 1. Those thirteen
 * were the supply line: copying one of them and dropping the setup line
 * reproduces #3264 exactly, and several carried multi-line comments re-deriving
 * the StrictMode hazard from first principles — evidence the hazard was being
 * rediscovered per site instead of read off the hook name. So rule 2 rejects the
 * correct hand-roll too (#3266), leaving `useMounted()` as the only spelling.
 *
 * Rule 2 keys on the *behavior* — one effect that raises a `useRef(true)` and then
 * lowers it — not on the hook's characters. A rule that matched the body verbatim
 * would be defeated by any re-spelling (`||=`, a concise cleanup arrow, a non-empty
 * dep array, a `clearTimeout` next to the flag), and the last of those is exactly
 * the form `Ask.jsx` and `ReactionTimeRunner` were in before #3266. The fix there
 * is the general one: the real cleanup moves to its own effect, and only the ref
 * bookkeeping becomes `useMounted()`.
 *
 * ## What this guard CANNOT see
 *
 * It is a source grep, not a scope-aware AST pass, so these semantically identical
 * shapes slip through. They are listed so the next person extending it knows where
 * the floor is rather than trusting a green run too far:
 *
 *   - `let`/`var` declarations (the pattern hardcodes `const`).
 *   - A non-literal seed: `const INIT = true; const r = useRef(INIT)`.
 *   - Two components in ONE file where A is correct and B is broken — rule 1's scan
 *     is file-scoped, so A's `= true` satisfies B. (Rule 2 is per-effect, so A's
 *     effect can't vouch for B's.)
 *   - A ref created in one file and lowered in another (a hook returning its ref to
 *     a caller that writes `ref.current = false`).
 *   - Aliasing (`const g = mountedRef; g.current = false`), computed access
 *     (`ref['current']`), or assignment funneled through a setter function.
 *   - Anything lexical. There is no comment/string/regex-literal stripping, so an
 *     assignment written only inside a comment counts, and — the other direction —
 *     an unbalanced `(` or `)` inside a string, comment, or regex literal skews
 *     rule 2's paren walk and can truncate the effect it was reading. Both are
 *     pinned by fixtures below so the boundary is executable rather than a claim.
 *   - Rule 2 requires the raise and the lower in the SAME `useEffect` call. Split
 *     across two effects, or funneled through a helper the effect calls, it reads
 *     as ordinary ref use and only rule 1 applies.
 *
 * Tightening any of these means moving to an AST pass; the shapes above are all
 * unusual enough in this codebase that the grep earns its keep as-is.
 */

import { describe, it, expect } from 'vitest';
import { readFileSync } from 'fs';
import { join, dirname } from 'path';
import { fileURLToPath } from 'url';
import { trackedSourceFiles } from '../test/trackedFiles.js';
import { escapeRegExp } from '../lib/textUtils.js';

const CLIENT_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');

// The one file allowed to contain the shape — it IS the shape.
const HOOK_FILE = 'src/hooks/useMounted.js';

// `const <name> = useRef(true)` — the seed value that marks a mounted-style guard.
// A ref seeded `useRef(false)` and raised to `true` on mount is a different (and
// correct) pattern, so it is intentionally out of scope.
const TRUE_SEEDED_REF = /const\s+([A-Za-z_$][\w$]*)\s*=\s*useRef\(\s*true\s*\)/g;

// `=` and `||=` both count as re-arming. Matching only `=` would report a ref
// re-armed with `ref.current ||= true` as broken — a false positive that would
// push someone to "fix" already-correct code. The name is escaped because ref
// names may legally contain `$`, which is a regex anchor — interpolating one raw
// would silently make the pattern unmatchable and pass the offender.
const assignsRe = (name, value) => new RegExp(`\\b${escapeRegExp(name)}\\.current\\s*(?:\\|\\|)?=\\s*${value}\\b`);

const USE_EFFECT_OPEN = /\buseEffect\s*\(/g;

/**
 * Text between the `(` at `open` and its matching `)`. A fixed char window or a
 * lazy `[^)]*` would stop at the first `)` inside the effect — every real effect
 * has several — and inspect a truncated body, so the walk counts depth instead.
 * Returns null on an unbalanced run (a truncated file), which reads as "nothing
 * to inspect" rather than a silent partial match.
 */
function balancedArgs(src, open) {
  let depth = 0;
  for (let i = open; i < src.length; i += 1) {
    if (src[i] === '(') depth += 1;
    else if (src[i] === ')') {
      depth -= 1;
      if (depth === 0) return src.slice(open + 1, i);
    }
  }
  return null;
}

/** The full argument text (callback + deps) of every `useEffect(...)` in `src`. */
function effectCalls(src) {
  const calls = [];
  for (const match of src.matchAll(USE_EFFECT_OPEN)) {
    const args = balancedArgs(src, match.index + match[0].length - 1);
    if (args !== null) calls.push(args);
  }
  return calls;
}

/** Refs in `src` that are lowered to false but never re-raised to true. */
function findOneWayRefs(src) {
  const offenders = [];
  for (const match of src.matchAll(TRUE_SEEDED_REF)) {
    const name = match[1];
    if (assignsRe(name, 'false').test(src) && !assignsRe(name, 'true').test(src)) {
      offenders.push(name);
    }
  }
  return offenders;
}

/**
 * Refs in `src` whose mount bookkeeping is hand-rolled instead of delegated to
 * `useMounted()`: a `useRef(true)` that ONE effect raises and then lowers.
 *
 * Matching on that ordered pair rather than on the hook's body verbatim is what
 * makes the rule hold up. Every re-spelling of the same guard — `||=`, a concise
 * cleanup arrow, a non-empty dep array, extra work alongside the flag in either
 * half — still raises before it lowers inside one effect, so all of them are
 * caught. Two effects that happen to touch the same ref are not: the lower must
 * appear inside the same call as the raise.
 */
function findInlinedUseMounted(src) {
  const offenders = [];
  const calls = effectCalls(src);
  for (const match of src.matchAll(TRUE_SEEDED_REF)) {
    const name = match[1];
    if (offenders.includes(name)) continue;
    const raise = assignsRe(name, 'true');
    const lower = assignsRe(name, 'false');
    const handRolled = calls.some((call) => {
      const raisedAt = call.search(raise);
      // Raise in the setup half, lower after it (the cleanup) — in that order.
      return raisedAt !== -1 && call.search(lower) > raisedAt;
    });
    if (handRolled) offenders.push(name);
  }
  return offenders;
}

describe('mounted-guard refs re-arm on mount (StrictMode)', () => {
  it('has no ref that is only ever set to false', () => {
    const files = trackedSourceFiles(CLIENT_ROOT);
    // A broken `git ls-files` (wrong cwd, detached checkout) would otherwise make
    // this guard pass by scanning nothing at all.
    expect(files.length).toBeGreaterThan(100);

    const violations = [];
    for (const file of files) {
      const src = readFileSync(join(CLIENT_ROOT, file), 'utf8');
      for (const name of findOneWayRefs(src)) violations.push(`${file}: ${name}`);
    }

    expect(
      violations,
      'These refs are seeded `useRef(true)` and set to `false` on cleanup, but never '
      + 'back to `true` on setup. Under React.StrictMode the dev mount→cleanup→mount '
      + 'cycle reuses the same ref, so each one is permanently false after first mount '
      + 'and every setState it guards silently no-ops.\n'
      + 'Fix: replace the ref + its cleanup effect with `useMounted()` from '
      + '`client/src/hooks/useMounted.js`.\n'
      + `Offenders:\n  ${violations.join('\n  ')}`,
    ).toEqual([]);
  });

  // Guards the guard: if the detector stops recognizing the broken shape, the test
  // above goes vacuously green and the bug class walks straight back in.
  it('detects the broken shape and accepts every correct re-arm', () => {
    const broken = `
      const mountedRef = useRef(true);
      useEffect(() => () => { mountedRef.current = false; }, []);
    `;
    const brokenRenamed = `
      const editorMountedRef = useRef(true);
      useEffect(() => () => { editorMountedRef.current = false; }, []);
    `;
    // Re-arms correctly, so rule 1 passes it. (Rule 2 rejects it separately —
    // it is `useMounted`'s body inlined. See the second describe block.)
    const handRolled = `
      const mountedRef = useRef(true);
      useEffect(() => {
        mountedRef.current = true;
        return () => { mountedRef.current = false; };
      }, []);
    `;
    // `||=` re-arms just as well as `=`; flagging it would be a false positive.
    const fixedLogicalAssign = `
      const mountedRef = useRef(true);
      useEffect(() => {
        mountedRef.current ||= true;
        return () => { mountedRef.current = false; };
      }, []);
    `;
    // A ref that is never lowered has nothing to re-arm.
    const neverLowered = 'const readyRef = useRef(true);';

    expect(findOneWayRefs(broken)).toEqual(['mountedRef']);
    expect(findOneWayRefs(brokenRenamed)).toEqual(['editorMountedRef']);
    expect(findOneWayRefs(handRolled)).toEqual([]);
    expect(findOneWayRefs(fixedLogicalAssign)).toEqual([]);
    expect(findOneWayRefs(neverLowered)).toEqual([]);
  });
});

describe('mounted-guard refs call useMounted() instead of inlining it', () => {
  it('has no file re-implementing the hook', () => {
    const files = trackedSourceFiles(CLIENT_ROOT).filter((f) => f !== HOOK_FILE);
    expect(files.length).toBeGreaterThan(100);

    const violations = [];
    for (const file of files) {
      const src = readFileSync(join(CLIENT_ROOT, file), 'utf8');
      for (const name of findInlinedUseMounted(src)) violations.push(`${file}: ${name}`);
    }

    expect(
      violations,
      'These refs hand-roll `useMounted` — one effect raises the flag on setup and '
      + 'lowers it on cleanup — instead of calling it. They work today, but they are '
      + 'how the #3264 freezes got written: copy one, drop the setup line, and the '
      + 'ref is permanently false under StrictMode.\n'
      + 'Fix: `const mountedRef = useMounted();` — import `useMounted` from '
      + '`client/src/hooks/useMounted.js` and delete the ref + its effect. If the '
      + 'effect also does real cleanup (clearTimeout, abort), keep THAT in its own '
      + '`useEffect` and move only the ref bookkeeping to the hook.\n'
      + `Offenders:\n  ${violations.join('\n  ')}`,
    ).toEqual([]);
  });

  // Guards the guard, in both directions. A detector that only knew the hook's
  // exact characters would be trivially defeated by re-spelling it, so every
  // re-spelling that still raises-then-lowers is asserted caught here.
  it('catches every re-spelling of the hand-rolled guard', () => {
    const verbatim = `
      const mountedRef = useRef(true);
      useEffect(() => {
        mountedRef.current = true;
        return () => { mountedRef.current = false; };
      }, []);
    `;
    const oneLine = 'const m = useRef(true);'
      + 'useEffect(() => { m.current = true; return () => { m.current = false; }; }, []);';
    const logicalAssign = `
      const mountedRef = useRef(true);
      useEffect(() => {
        mountedRef.current ||= true;
        return () => { mountedRef.current = false; };
      }, []);
    `;
    const conciseCleanup = `
      const mountedRef = useRef(true);
      useEffect(() => {
        mountedRef.current = true;
        return () => (mountedRef.current = false);
      }, []);
    `;
    // The pre-#3266 shape in Ask.jsx / ReactionTimeRunner: real cleanup work
    // alongside the flag. Still a hand-rolled guard — the fix is to split the
    // real work into its own effect, which is what this PR did.
    const extraCleanup = `
      const mountedRef = useRef(true);
      useEffect(() => {
        mountedRef.current = true;
        return () => { mountedRef.current = false; abortRef.current?.abort(); };
      }, []);
    `;
    const nonEmptyDeps = `
      const mountedRef = useRef(true);
      useEffect(() => {
        mountedRef.current = true;
        return () => { mountedRef.current = false; };
      }, [jobId]);
    `;

    expect(findInlinedUseMounted(verbatim)).toEqual(['mountedRef']);
    expect(findInlinedUseMounted(oneLine)).toEqual(['m']);
    expect(findInlinedUseMounted(logicalAssign)).toEqual(['mountedRef']);
    expect(findInlinedUseMounted(conciseCleanup)).toEqual(['mountedRef']);
    expect(findInlinedUseMounted(extraCleanup)).toEqual(['mountedRef']);
    expect(findInlinedUseMounted(nonEmptyDeps)).toEqual(['mountedRef']);
  });

  it('leaves refs that are not hand-rolled mount guards alone', () => {
    // The sanctioned form has no effect to match.
    const usesHook = 'const mountedRef = useMounted();';
    // A ref seeded `true` that is toggled as ordinary UI state (SongBook's
    // follow-the-playhead flag) is not a mount guard and must not be flagged.
    const unrelatedToggle = `
      const followRef = useRef(true);
      const onPlay = () => { followRef.current = true; };
      const onPan = () => { followRef.current = false; };
    `;
    // Raise and lower in SEPARATE effects is not the copy-paste this rule bans;
    // requiring both inside one call is what keeps the two cases apart.
    const separateEffects = `
      const activeRef = useRef(true);
      useEffect(() => { activeRef.current = true; }, [id]);
      useEffect(() => () => { activeRef.current = false; }, []);
    `;
    // Lowered first, raised after — a re-entrancy latch, not a mount guard.
    const lowerThenRaise = `
      const idleRef = useRef(true);
      useEffect(() => {
        idleRef.current = false;
        return () => { idleRef.current = true; };
      }, [busy]);
    `;
    // The broken shape has no setup half, so rule 1 owns it exclusively.
    const broken = `
      const mountedRef = useRef(true);
      useEffect(() => () => { mountedRef.current = false; }, []);
    `;

    expect(findInlinedUseMounted(usesHook)).toEqual([]);
    expect(findInlinedUseMounted(unrelatedToggle)).toEqual([]);
    expect(findInlinedUseMounted(separateEffects)).toEqual([]);
    expect(findInlinedUseMounted(lowerThenRaise)).toEqual([]);
    expect(findInlinedUseMounted(broken)).toEqual([]);
  });

  // The paren walk is the part most likely to be "simplified" into a regex later,
  // so pin the case that breaks one: an effect body with its own nested calls.
  it('reads the whole effect, not up to the first inner close-paren', () => {
    const parensBeforeCleanup = `
      const mountedRef = useRef(true);
      useEffect(() => {
        mountedRef.current = true;
        load(runId).then((res) => setRows(res.rows));
        return () => { mountedRef.current = false; };
      }, []);
    `;
    expect(findInlinedUseMounted(parensBeforeCleanup)).toEqual(['mountedRef']);
  });

  // The known lexical blind spot, pinned rather than described. The walk counts
  // every paren, so an unbalanced one inside a string or comment closes the slice
  // early and the guard reads a truncated effect. Closing this means lexing JS,
  // which is the AST-pass threshold the file docblock draws; until someone crosses
  // it, this fixture is what tells the next reader the boundary is known and where
  // it sits. If a future change DOES make the walk lexical, this test fails —
  // flip it to `['mountedRef']` and drop the caveat from the docblock.
  it('is defeated by an unbalanced paren inside a string (known floor)', () => {
    const evadesTheWalk = `
      const mountedRef = useRef(true);
      useEffect(() => {
        log(')');
        mountedRef.current = true;
        return () => { mountedRef.current = false; };
      }, []);
    `;
    expect(findInlinedUseMounted(evadesTheWalk)).toEqual([]);
  });

  // The hook itself is the one sanctioned copy — if the exclusion ever stops
  // matching (file moved/renamed), this fails instead of the guard going quiet.
  it('excludes the hook itself, and the hook still matches the banned shape', () => {
    expect(trackedSourceFiles(CLIENT_ROOT)).toContain(HOOK_FILE);
    const src = readFileSync(join(CLIENT_ROOT, HOOK_FILE), 'utf8');
    expect(findInlinedUseMounted(src)).toEqual(['mountedRef']);
  });
});