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

31.8 KB
Raw Blame
// @vitest-environment node

/**
 * Repo-wide guard: an async effect keyed to a switchable identity must drop a
 * superseded response.
 *
 * The broken shape is an effect that fetches on a dependency and writes the
 * answer straight into state:
 *
 *   useEffect(() => {
 *     loadBible(work.id).then(setCharacters);   // ← no disposal guard
 *   }, [work.id]);
 *
 * Switch work A → work B faster than the first request resolves and A's answer
 * lands after B's, so B is displayed holding A's records. `useMounted()` does
 * NOT cover this — the component never unmounted, only its subject changed —
 * which is exactly why this guard exists alongside
 * `hooks/mountedRefConventions.test.js` rather than inside it.
 *
 * It is not always a transient flicker. `WorkEditor` passed its bible lists
 * down as controlled props, and `BibleSection` returns early rather than
 * refetching when it receives them, so nothing re-read the server: the wrong
 * characters and places stayed until the user manually re-ran an extraction,
 * and in the meantime enriched the image-gen prompts behind persisted
 * storyboard renders. Issues #6996, #6997, #6998, #6999 and #7000 were each
 * filed and fixed as one site of this same class; #7242 swept the rest and
 * added this test, because fixing them one at a time never stopped new ones
 * from landing.
 *
 * ## The sanctioned fixes
 *
 * Three shapes count as a guard, matched on structure rather than on a name —
 * the tree spells the flag `active`, `cancelled`, `canceled`, `live`, `current`
 * and `ignore`, and a rule keyed to that list would be defeated by the next
 * synonym:
 *
 *   1. **A local flip flag** — the dominant idiom, ~150 files:
 *      `let active = true;` … `if (active) setX(v);` … `return () => { active = false; };`
 *   2. **A request-generation ref** — for an effect whose response must be
 *      matched against the LATEST request rather than merely dropped:
 *      `const gen = ++genRef.current;` … `if (gen !== genRef.current) return;`
 *   3. **An `AbortController`** whose `.abort()` runs in the cleanup.
 *
 * ## What this guard CANNOT see
 *
 * It is a lexical scan, not a scope-aware AST pass. The boundary, so a green
 * run is not trusted further than it earns:
 *
 *   - It cannot tell a setter that truly runs in the async continuation from
 *     one that merely appears later in the source than the first `await` /
 *     `.then(`. A synchronous `setX()` written below an unrelated `.then()`
 *     reads as a violation; those sites are on the allowlist with that reason.
 *   - A flag must be declared, flipped, and read, but the read is not traced to
 *     the setter: a flag that gates the WRONG `set*` call still counts, and so
 *     does a flip written outside the returned cleanup.
 *   - One guarded request exempts the whole effect, so a second unguarded fetch
 *     added beside it is invisible. Pinning that needs per-statement dataflow,
 *     which a lexical scan cannot do; the allowlist rows are deliberately
 *     file-scoped for the same reason.
 *   - The self-retrigger rule reads control flow only as far as "this block's
 *     last statement is a `return`". A path that leaves by `throw`, or through a
 *     branch whose return sits anywhere but last, reads as reachable — which
 *     errs toward reporting, so the cost is an allowlist row, not a miss.
 *   - The fetch/apply pair moved into a helper the effect calls is invisible,
 *     and so is a guard living in that helper.
 *   - `depsAllStable` resolves a `useRef` / `useMounted` handle only by a
 *     file-local `const` declaration, so a stable handle arriving as a prop
 *     still reads as switchable.
 *   - Regex literals are not lexed. A `(`, `)` or quote inside one skews the
 *     paren walk and can truncate the effect being read — which fails open for
 *     that effect. Strings, template literals and comments ARE blanked, and
 *     both directions are pinned by fixtures below.
 */

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

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

/**
 * Effects exempt from the rule, each with the reason. Adding a row is the
 * moment to ask whether the dependency can really never select a different
 * record — if it can, the fix is a guard, not a row here.
 *
 * Keyed by file: an effect's line number moves on every edit above it, so
 * keying on one would make this list conflict on unrelated commits. The
 * trade-off is that a file listed here is exempt for ALL of its effects, so
 * rows are meant to stay rare.
 */
const ALLOWED = {
  'src/components/QuickBrainCapture.jsx':
    'seededRef latches on the first run, so the fetch fires at most once per mount',
  'src/components/brain/tabs/FeedsTab.jsx':
    'setLoading(false) is a load-finished latch, not a response written into state',
  'src/components/codeAnimation/CodeAnimationGallery.jsx':
    'deps are [items] of one fixed gallery query; each poster answer is applied by its own job id, so none can land under another record',
  'src/components/voice/VoiceWidget.jsx':
    'deps are [enabled, navigate] — a session toggle, not a record identity',
  'src/hooks/useImageGenPageRuntime.js':
    'the active-job read is adopted through useMediaJobSse.start, whose run owner drops it when superseded or unmounted (ifIdle makes a re-run a no-op)',
  'src/pages/Browser.jsx':
    'deps are [showConfig, config] — a panel toggle re-reading its own config',
};

// ---------------------------------------------------------------------------
// Lexing
// ---------------------------------------------------------------------------

/**
 * Blank out comments, string literals and the literal spans of template
 * literals, preserving offsets and line breaks so reported line numbers stay
 * true. A `(` inside a toast message would otherwise skew the paren walk below
 * and truncate the effect it was reading; `${...}` spans are kept because they
 * hold real code.
 */
export function blankLexical(src) {
  let out = '';
  let i = 0;
  while (i < src.length) {
    const c = src[i];
    const next = src[i + 1];
    if (c === '/' && next === '/') {
      while (i < src.length && src[i] !== '\n') { out += ' '; i += 1; }
      continue;
    }
    if (c === '/' && next === '*') {
      out += '  '; i += 2;
      while (i < src.length && !(src[i] === '*' && src[i + 1] === '/')) {
        out += src[i] === '\n' ? '\n' : ' '; i += 1;
      }
      out += '  '; i += 2;
      continue;
    }
    if (c === "'" || c === '"') {
      out += ' '; i += 1;
      while (i < src.length && src[i] !== c) {
        if (src[i] === '\\') { out += '  '; i += 2; continue; }
        out += src[i] === '\n' ? '\n' : ' '; i += 1;
      }
      out += ' '; i += 1;
      continue;
    }
    if (c === '`') {
      out += ' '; i += 1;
      while (i < src.length && src[i] !== '`') {
        if (src[i] === '\\') { out += '  '; i += 2; continue; }
        if (src[i] === '$' && src[i + 1] === '{') {
          out += '  '; i += 2;
          let depth = 1;
          while (i < src.length && depth > 0) {
            if (src[i] === '{') depth += 1;
            else if (src[i] === '}') {
              depth -= 1;
              if (depth === 0) { out += ' '; i += 1; break; }
            }
            out += src[i]; i += 1;
          }
          continue;
        }
        out += src[i] === '\n' ? '\n' : ' '; i += 1;
      }
      out += ' '; i += 1;
      continue;
    }
    out += c; i += 1;
  }
  return out;
}

/**
 * Text between the `(` at `open` and its matching `)`. A lazy `[^)]*` would
 * stop at the first `)` inside the effect — every real effect has several — so
 * the walk counts depth instead. Returns null on an unbalanced run, which
 * reads as "nothing to inspect".
 */
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;
}

/**
 * Split a `useEffect(...)` argument list into its callback body and its
 * dependency array, at the last top-level comma. Returns null when the call has
 * no literal dep array — an effect that runs on every render is a different
 * (and louder) bug that this rule does not own.
 */
export function splitDeps(args) {
  let depth = 0;
  for (let i = args.length - 1; i >= 0; i -= 1) {
    const c = args[i];
    if (c === ')' || c === ']' || c === '}') depth += 1;
    else if (c === '(' || c === '[' || c === '{') depth -= 1;
    else if (c === ',' && depth === 0) {
      const tail = args.slice(i + 1).trim();
      if (tail.startsWith('[') && tail.endsWith(']')) {
        return { body: args.slice(0, i), deps: tail.slice(1, -1) };
      }
      return null;
    }
  }
  return null;
}

// ---------------------------------------------------------------------------
// Detection
// ---------------------------------------------------------------------------

const ASYNC_BOUNDARY = /\bawait\b|\.then\s*\(/;

// `set[A-Z]` also spells the timer APIs; they set no React state.
const TIMER_SETTERS = new Set(['setTimeout', 'setInterval', 'setImmediate']);

// A bare `setFoo` reference. Deliberately not anchored to an open paren: the
// tree writes state both as `setFoo(v)` and as `.then(setFoo)`, and the second
// spelling is the more dangerous one — it applies the raw response. The leading
// class keeps `obj.setFoo` out; a method on a fetched object is not this
// component's state.
const SETTER_CALL = /(^|[^.\w$])(set[A-Z][\w$]*)\b/g;

const FLAG_DECL = /\b(?:let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(true|false)\b/g;
const GENERATION_BUMP = /\+\+\s*[\w$.]+\.current|[\w$.]+\.current\s*\+=\s*1|[\w$.]+\.current\s*=\s*[\w$.]+\.current\s*\+\s*1/;
const GENERATION_COMPARE = /[\w$.]+\.current\s*(?:!==|===|!=|==)|(?:!==|===|!=|==)\s*[\w$.]+\.current/;
const ABORT_CONTROLLER = /new\s+AbortController\s*\(/;
const ABORT_CALL = /\.abort\s*\(/;

// `const x = useRef(...)` / `const x = useMounted()` — a handle whose identity
// is fixed for the life of the component.
const STABLE_DECL = /\bconst\s+([A-Za-z_$][\w$]*)\s*=\s*(?:useRef|useMounted)\s*\(/g;

/**
 * A flag declared inside the effect, later assigned its opposite value, AND
 * read at least once somewhere else.
 *
 * The read requirement is what stops the guard from being cosmetic. Declaring
 * and flipping a flag that gates nothing —
 * `let active = true; load(id).then(setValue); return () => { active = false; };`
 * — keeps the exact race this rule exists to reject, and a declaration+flip
 * check alone would pass it.
 */
function flipFlagEnd(body) {
  for (const match of body.matchAll(FLAG_DECL)) {
    const opposite = match[2] === 'true' ? 'false' : 'true';
    // Names may legally contain `$`, a regex anchor — escaping it keeps the
    // pattern from silently becoming unmatchable and passing the offender.
    const name = match[1].replace(/\$/g, '\\$');
    const flip = new RegExp(`\\b${name}\\s*=\\s*${opposite}\\b`);
    const end = match.index + match[0].length;
    const rest = body.slice(end);
    if (!flip.test(rest)) continue;
    // A READ — an occurrence not being assigned to. Counting bare occurrences
    // would let a second write stand in for a read (`active = true; … active =
    // false;`), which is the cosmetic guard this check exists to reject. `==`
    // and `===` are comparisons, so they stay reads.
    const read = new RegExp(`\\b${name}\\b(?!\\s*=[^=])`);
    if (read.test(rest)) return end;
  }
  return -1;
}

const hasFlipFlag = (body) => flipFlagEnd(body) !== -1;

/** Whether `body` disposes of a superseded response by any sanctioned shape. */
export function hasDisposalGuard(body) {
  return hasFlipFlag(body)
    || (GENERATION_BUMP.test(body) && GENERATION_COMPARE.test(body))
    || (ABORT_CONTROLLER.test(body) && ABORT_CALL.test(body));
}

/** The first `set*` call positioned after the effect's first async boundary. */
function setterAfterAsync(body) {
  const async = ASYNC_BOUNDARY.exec(body);
  if (!async) return null;
  for (const match of body.matchAll(SETTER_CALL)) {
    if (TIMER_SETTERS.has(match[2])) continue;
    if (match.index + match[1].length > async.index) return match[2];
  }
  return null;
}

/**
 * Every dep is a ref handle, so the array can never select a different record —
 * the effect is a mount-only load wearing a dep array to satisfy the lint rule.
 */
function depsAllStable(deps, stableNames) {
  const entries = deps.split(',').map((d) => d.trim()).filter(Boolean);
  return entries.length > 0 && entries.every((d) => stableNames.has(d));
}

/** Identity-keyed async effects in `src` that apply their response unguarded. */
export function unguardedEffects(src) {
  const blanked = blankLexical(src);
  const stableNames = new Set([...blanked.matchAll(STABLE_DECL)].map((m) => m[1]));
  const found = [];
  for (const match of blanked.matchAll(/\buseEffect\s*\(/g)) {
    const args = balancedArgs(blanked, match.index + match[0].length - 1);
    if (args === null) continue;
    const split = splitDeps(args);
    if (!split || !split.deps.trim()) continue;
    if (depsAllStable(split.deps, stableNames)) continue;
    const setter = setterAfterAsync(split.body);
    if (!setter) continue;
    if (hasDisposalGuard(split.body)) continue;
    found.push({
      line: blanked.slice(0, match.index).split('\n').length,
      deps: split.deps.replace(/\s+/g, ' ').trim(),
      setter,
    });
  }
  return found;
}

/**
 * Whether a block's own last statement is a `return`, so every path through it
 * leaves the effect.
 *
 * "Contains a return" is not enough: `{ setLoading(true); if (cached) return; }`
 * falls through whenever `cached` is false, and the write still re-triggers.
 * Nested `{…}` become `;` so the statement split sees `if (b) {…}` as finished
 * and `{ if (b) { setX(); } return; }` still reads as an unconditional bail.
 */
function alwaysReturns(inner) {
  let flat = '';
  let depth = 0;
  for (const char of inner) {
    if (char === '{') { depth += 1; if (depth === 1) flat += ';'; continue; }
    if (char === '}') { depth = Math.max(0, depth - 1); continue; }
    if (depth === 0) flat += char;
  }
  const statements = flat.split(';').map((s) => s.trim()).filter(Boolean);
  return /^return\b/.test(statements.at(-1) || '');
}

/**
 * Spans of the nested `{…}` blocks in an effect body that always return.
 *
 * Anything inside one is on a path that leaves the effect, so it cannot reach —
 * and therefore cannot cancel — a request set up after it. The callback's own
 * outermost block is excluded: it holds the cleanup's `return`, so counting it
 * would swallow the whole body.
 *
 * Nesting matters (`if (a) { if (b) { setX(); } return; }` bails too), so every
 * enclosing block is reported, not just the innermost.
 */
function bailingBlocks(body) {
  const spans = [];
  const open = [];
  for (let i = 0; i < body.length; i += 1) {
    if (body[i] === '{') open.push(i);
    else if (body[i] === '}' && open.length) {
      const start = open.pop();
      // depth 1 is the callback body itself
      if (open.length >= 1 && alwaysReturns(body.slice(start + 1, i))) spans.push([start, i]);
    }
  }
  return spans;
}

/**
 * The mirror-image mistake: a lifetime-scoped flip flag in an effect that
 * SYNCHRONOUSLY writes a state value appearing in its own dependency array.
 *
 *   useEffect(() => {
 *     let active = true;
 *     setLoadingOutput(true);              // ← re-runs this effect immediately
 *     load(id).then((v) => { if (active) setValue(v); });
 *     return () => { active = false; };    // ← …whose cleanup fires here
 *   }, [id, loadingOutput]);
 *
 * The re-run's cleanup flips the flag before the response lands, so the update
 * is silently dropped — the guard does not merely fail to help, it breaks the
 * feature. That shipped four times while sweeping #7242 (it took AgentCard's
 * transcript, the pipeline ledger/outline re-reads, and the post-download
 * upscale re-probe offline) and only one of them had a test to catch it.
 *
 * The fix is a request-generation ref: the re-run early-returns without
 * bumping, so the in-flight request stays current.
 *
 * Only a SYNCHRONOUS write counts, and only one that can actually reach the
 * request. The same setter inside `.then()` runs after the response has already
 * been applied, so it cannot cancel itself; and one inside a block that returns
 * (`if (!enabled) { setOffset(0); return; }`) is on a path that bails before any
 * request exists.
 */
export function selfDisposingEffects(src) {
  const blanked = blankLexical(src);
  const found = [];
  for (const match of blanked.matchAll(/\buseEffect\s*\(/g)) {
    const args = balancedArgs(blanked, match.index + match[0].length - 1);
    if (args === null) continue;
    const split = splitDeps(args);
    if (!split || !split.deps.trim()) continue;
    const { body, deps } = split;
    const async = ASYNC_BOUNDARY.exec(body);
    if (!async) continue;
    if (flipFlagEnd(body) === -1) continue;
    const bailing = bailingBlocks(body);
    const depNames = new Set(deps.split(',').map((d) => d.trim()).filter(Boolean));
    for (const setter of body.matchAll(SETTER_CALL)) {
      if (TIMER_SETTERS.has(setter[2])) continue;
      const at = setter.index + setter[1].length;
      if (at > async.index) continue;
      if (bailing.some(([open, close]) => at > open && at < close)) continue;
      // `setLoadingOutput` → `loadingOutput`, the state value it writes.
      const stateName = setter[2][3].toLowerCase() + setter[2].slice(4);
      if (!depNames.has(stateName)) continue;
      found.push({
        line: blanked.slice(0, match.index).split('\n').length,
        setter: setter[2],
        dep: stateName,
      });
      break;
    }
  }
  return found;
}

const violationsIn = (file) => unguardedEffects(readFileSync(join(CLIENT_ROOT, file), 'utf8'))
  .map((v) => `${file}:${v.line}  deps=[${v.deps}] → ${v.setter}()`);

const selfDisposingIn = (file) => selfDisposingEffects(readFileSync(join(CLIENT_ROOT, file), 'utf8'))
  .map((v) => `${file}:${v.line}  ${v.setter}() re-runs the effect via dep \`${v.dep}\``);

describe('identity-keyed async effects drop superseded responses', () => {
  it('has no unguarded identity-keyed async effect outside the allowlist', () => {
    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 = files
      .filter((file) => !(file in ALLOWED))
      .flatMap(violationsIn);

    expect(
      violations,
      'These effects fetch on a dependency and write the answer into state with no '
      + 'disposal guard. Change the dependency faster than the request resolves and the '
      + "superseded record's data is rendered under the current one — and it does not "
      + 'self-correct, because nothing refetches.\n'
      + 'Fix: `let active = true;` at the top of the effect, gate every `set*` on it, and '
      + '`return () => { active = false; };`. Match whichever spelling the file already '
      + 'uses. Where the response must be matched against the newest request rather than '
      + 'merely dropped, bump and compare a generation ref instead.\n'
      + '`useMounted()` does NOT fix this — the component stays mounted; only its subject '
      + 'changed.\n'
      + 'If the dependency genuinely cannot select a different record (a drawer `open` '
      + 'flag, a once-only latch), add the file to ALLOWED in this file with a one-line '
      + `reason.\nOffenders:\n  ${violations.join('\n  ')}`,
    ).toEqual([]);
  });

  it('has no lifetime flag in an effect that re-triggers itself', () => {
    const files = trackedSourceFiles(CLIENT_ROOT);
    expect(files.length).toBeGreaterThan(100);

    const violations = files.flatMap(selfDisposingIn);

    expect(
      violations,
      'These effects hold a `let active`-style flag AND synchronously write a state '
      + 'value that is in their own dependency array. The write re-runs the effect at '
      + "once, and the re-run's cleanup flips the flag before the response lands — so "
      + 'the update is silently dropped. The guard does not just fail to help here, it '
      + 'breaks the feature.\n'
      + 'Fix: use a request-generation ref instead — `const req = ++fooRef.current;` at '
      + 'request time, `if (req === fooRef.current)` at apply time. The re-run '
      + 'early-returns without bumping, so the in-flight request stays current.\n'
      + `Offenders:\n  ${violations.join('\n  ')}`,
    ).toEqual([]);
  });

  // Burn-down: an allowlist entry that no longer needs to be there must go, or
  // the list quietly becomes a list of files nobody has looked at in a year.
  it('has no stale allowlist entry', () => {
    const missing = Object.keys(ALLOWED).filter((file) => !existsSync(join(CLIENT_ROOT, file)));
    expect(missing, `Allowlisted files that no longer exist:\n  ${missing.join('\n  ')}`).toEqual([]);

    const noLongerNeeded = Object.keys(ALLOWED).filter((file) => violationsIn(file).length === 0);
    expect(
      noLongerNeeded,
      'These files are allowlisted but no longer trip the rule. Delete their rows from '
      + `ALLOWED.\n  ${noLongerNeeded.join('\n  ')}`,
    ).toEqual([]);
  });

  it('gives every allowlist entry a reason', () => {
    const unexplained = Object.entries(ALLOWED)
      .filter(([, reason]) => !reason || reason.trim().length < 20)
      .map(([file]) => file);
    expect(
      unexplained,
      `These rows need a one-line reason the dependency cannot switch:\n  ${unexplained.join('\n  ')}`,
    ).toEqual([]);
  });

  // Guards the guard: a detector that stopped recognizing the broken shape would
  // make the scan above vacuously green and let the bug class walk straight back in.
  describe('detector', () => {
    it('flags an identity-keyed fetch that applies its response unguarded', () => {
      const found = unguardedEffects(`
        useEffect(() => {
          loadBible(work.id).then(setCharacters);
        }, [work.id]);
      `);
      expect(found).toHaveLength(1);
      expect(found[0].setter).toBe('setCharacters');
      expect(found[0].deps).toBe('work.id');
    });

    it('flags an unguarded await, not just a .then', () => {
      expect(unguardedEffects(`
        useEffect(() => {
          (async () => {
            const rows = await listItems(subjectId);
            setRows(rows);
          })();
        }, [subjectId]);
      `)).toHaveLength(1);
    });

    it('accepts every sanctioned guard shape', () => {
      // 1. The flip flag, in each spelling the tree uses.
      for (const flag of ['active', 'cancelled', 'canceled', 'live', 'current', 'ignore']) {
        expect(unguardedEffects(`
          useEffect(() => {
            let ${flag} = true;
            load(id).then((v) => { if (${flag}) setValue(v); });
            return () => { ${flag} = false; };
          }, [id]);
        `), `flag spelled \`${flag}\``).toEqual([]);
      }

      // A flag seeded false and raised in the cleanup is the same idiom inverted.
      expect(unguardedEffects(`
        useEffect(() => {
          let stale = false;
          load(id).then((v) => { if (!stale) setValue(v); });
          return () => { stale = true; };
        }, [id]);
      `)).toEqual([]);

      // 2. A request-generation ref.
      expect(unguardedEffects(`
        useEffect(() => {
          const gen = ++genRef.current;
          load(id).then((v) => { if (gen === genRef.current) setValue(v); });
        }, [id]);
      `)).toEqual([]);

      // 3. An AbortController aborted in the cleanup.
      expect(unguardedEffects(`
        useEffect(() => {
          const controller = new AbortController();
          load(id, { signal: controller.signal }).then(setValue);
          return () => controller.abort();
        }, [id]);
      `)).toEqual([]);
    });

    it('ignores effects that cannot strand a superseded response', () => {
      // No dependency array at all — a different bug, not this rule's.
      expect(unguardedEffects('useEffect(() => { load().then(setValue); });')).toEqual([]);

      // Mount-only.
      expect(unguardedEffects('useEffect(() => { load().then(setValue); }, []);')).toEqual([]);

      // Nothing async.
      expect(unguardedEffects('useEffect(() => { setValue(id); }, [id]);')).toEqual([]);

      // Async, but nothing written into state.
      expect(unguardedEffects('useEffect(() => { track(id).then(() => log(id)); }, [id]);')).toEqual([]);

      // A setter that runs BEFORE the async boundary is not a stranded response.
      expect(unguardedEffects(`
        useEffect(() => {
          setLoading(true);
          void refresh(id);
        }, [id]);
      `)).toEqual([]);

      // Timer APIs spell `set[A-Z]` but set no React state.
      expect(unguardedEffects(`
        useEffect(() => {
          load(id).then(() => setTimeout(done, 10));
        }, [id]);
      `)).toEqual([]);

      // A method on the fetched value is not this component's state.
      expect(unguardedEffects('useEffect(() => { load(id).then((r) => r.setName(x)); }, [id]);')).toEqual([]);
    });

    it('treats a dep array of only ref handles as mount-only', () => {
      const src = `
        const mountedRef = useMounted();
        useEffect(() => {
          load().then((v) => { if (mountedRef.current) setValue(v); });
        }, [mountedRef]);
      `;
      expect(unguardedEffects(src)).toEqual([]);

      // …but one switchable dep alongside it still counts.
      expect(unguardedEffects(src.replace('[mountedRef]', '[workId, mountedRef]'))).toHaveLength(1);
    });

    it('does not accept a flag that gates nothing', () => {
      // Declared and flipped, but never consulted — the response is applied
      // unconditionally, so the race is exactly the one being rejected.
      expect(unguardedEffects(`
        useEffect(() => {
          let active = true;
          load(id).then(setValue);
          return () => { active = false; };
        }, [id]);
      `)).toHaveLength(1);

      // A second WRITE is not a read; it must not stand in for one.
      expect(unguardedEffects(`
        useEffect(() => {
          let active = true;
          active = true;
          load(id).then(setValue);
          return () => { active = false; };
        }, [id]);
      `)).toHaveLength(1);

      // A comparison IS a read — `==`/`===` must not be mistaken for assignment.
      expect(unguardedEffects(`
        useEffect(() => {
          let active = true;
          load(id).then((v) => { if (active === true) setValue(v); });
          return () => { active = false; };
        }, [id]);
      `)).toEqual([]);
    });

    it('does not accept a mounted guard as an identity guard', () => {
      // The component never unmounted — `mountedRef.current` is true the whole
      // time — so this is the exact shape the rule exists to reject.
      expect(unguardedEffects(`
        useEffect(() => {
          load(workId).then((v) => { if (mountedRef.current) setValue(v); });
        }, [workId]);
      `)).toHaveLength(1);
    });

    it('reads through parens and braces inside strings, templates and comments', () => {
      // Each of these would truncate the effect (or fake a guard) without lexing.
      expect(unguardedEffects(`
        useEffect(() => {
          toast.error('could not load :( ');
          load(id).then(setValue);
        }, [id]);
      `)).toHaveLength(1);

      expect(unguardedEffects(`
        useEffect(() => {
          const label = \`item (\${id}\`;
          load(label).then(setValue);
        }, [id]);
      `)).toHaveLength(1);

      // A guard written only inside a comment is not a guard.
      expect(unguardedEffects(`
        useEffect(() => {
          // let active = true; return () => { active = false; };
          load(id).then(setValue);
        }, [id]);
      `)).toHaveLength(1);

      // …and a real guard is still seen when a comment sits next to it.
      expect(unguardedEffects(`
        useEffect(() => {
          let active = true; // dropped if \`id\` changes first
          load(id).then((v) => { if (active) setValue(v); });
          return () => { active = false; };
        }, [id]);
      `)).toEqual([]);
    });

    it('flags a lifetime flag beside a synchronous write to its own dep', () => {
      const found = selfDisposingEffects(`
        useEffect(() => {
          let active = true;
          setLoading(true);
          load(id).then((v) => { if (active) setValue(v); });
          return () => { active = false; };
        }, [id, loading]);
      `);
      expect(found).toHaveLength(1);
      expect(found[0].setter).toBe('setLoading');
      expect(found[0].dep).toBe('loading');
    });

    it('does not flag a write that cannot re-trigger the effect first', () => {
      const flagged = (src) => selfDisposingEffects(src).length;

      // The setter's value is not a dependency, so the write re-runs nothing.
      expect(flagged(`
        useEffect(() => {
          let active = true;
          setLoading(true);
          load(id).then((v) => { if (active) setValue(v); });
          return () => { active = false; };
        }, [id]);
      `)).toBe(0);

      // Written only inside `.then()` — the response has already been applied
      // by the time the re-run's cleanup could fire, so it cannot self-cancel.
      expect(flagged(`
        useEffect(() => {
          let active = true;
          load(id).then((v) => { if (active) setConsents(v); });
          return () => { active = false; };
        }, [id, consents]);
      `)).toBe(0);

      // Written in an early-return branch ABOVE the flag: that path bails
      // before the request exists, so it cannot cancel one.
      expect(flagged(`
        useEffect(() => {
          if (!enabled) {
            setOffset(0);
            return;
          }
          let cancelled = false;
          load(offset).then((v) => { if (!cancelled) setItems(v); });
          return () => { cancelled = true; };
        }, [enabled, offset]);
      `)).toBe(0);

      // …but a bare `return` guard above it does NOT put the write on a bailing
      // path: `setLoading(true)` here still runs, and still re-triggers.
      expect(flagged(`
        useEffect(() => {
          if (loading) return;
          setLoading(true);
          let active = true;
          load(id).then((v) => { if (active) setValue(v); });
          return () => { active = false; };
        }, [id, loading]);
      `)).toBe(1);

      // Nested inside a block that bails, two levels down.
      expect(flagged(`
        useEffect(() => {
          if (a) {
            if (b) { setOffset(0); }
            return;
          }
          let active = true;
          load(offset).then((v) => { if (active) setItems(v); });
          return () => { active = false; };
        }, [a, b, offset]);
      `)).toBe(0);

      // A block that only CONDITIONALLY returns does not exempt the write —
      // with `cached` false, execution falls through to the request.
      expect(flagged(`
        useEffect(() => {
          if (enabled) {
            setLoading(true);
            if (cached) return;
          }
          let active = true;
          load(id).then((v) => { if (active) setValue(v); });
          return () => { active = false; };
        }, [id, loading]);
      `)).toBe(1);

      // A generation ref is the sanctioned fix, not a violation.
      expect(flagged(`
        useEffect(() => {
          const req = ++genRef.current;
          setLoading(true);
          load(id).then((v) => { if (req === genRef.current) setValue(v); });
        }, [id, loading]);
      `)).toBe(0);
    });

    it('reports the line of the offending effect', () => {
      const found = unguardedEffects([
        'const a = 1;',
        'const b = 2;',
        'useEffect(() => {',
        '  load(id).then(setValue);',
        '}, [id]);',
      ].join('\n'));
      expect(found[0].line).toBe(3);
    });
  });
});