@pyreon/compiler 0.18.0 → 0.19.0

package/src/tests/defer-inline.test.ts

@@ -121,22 +121,10 @@ export function App() {
 }
 `
     const result = transformDeferInline(input, 'app.tsx')
-    // No transform fires (multi-child shape doesn't match the inline-eligible
-    // single-component-child pattern). No warning either — v1 just leaves it
-    // alone; downstream Defer's runtime behaviour handles the malformed shape.
-    expect(result.changed).toBe(false)
-  })
-
-  test('skips Defer whose child has props (multi-prop closure capture)', () => {
-    const input = `
-import { Defer } from '@pyreon/core'
-import { Modal } from './Modal'
-export function App() {
-  return <Defer when={() => true}><Modal title="hi" /></Defer>
-}
-`
-    const result = transformDeferInline(input, 'app.tsx')
+    // v2 now emits a `multiple-children` warning so the author knows to use
+    // the explicit `chunk` form. v1 was silent — that was a footgun.
     expect(result.changed).toBe(false)
+    expect(result.warnings[0]?.code).toBe('defer-inline/multiple-children')
   })
 
   test('fast-path: no Defer in source returns unchanged', () => {
@@ -157,7 +145,74 @@ export const count = signal(0)
     expect(result.code).toBe(input)
   })
 
-  test('skips renamed imports — { Modal as M } not handled in v1', () => {
+  // v1 bailed on `{ Modal as M }`. v2 handles renamed imports — the
+  // local name in JSX is `M`, but the chunk extracts `__m.Modal` (the
+  // original exported name). See the positive test in the v2 section.
+})
+
+describe('transformDeferInline — v2 capabilities', () => {
+  test('preserves props on inline child', () => {
+    const input = `
+import { Defer } from '@pyreon/core'
+import { Modal } from './Modal'
+export function App() {
+  return <Defer when={() => true}><Modal title="Confirm" size="md" /></Defer>
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(true)
+    expect(result.code).not.toContain("import { Modal }")
+    // Props pass through verbatim. Only the component name is replaced.
+    expect(result.code).toContain('{(__C) => <__C title="Confirm" size="md" />}')
+  })
+
+  test('preserves nested children on inline child (non-self-closing)', () => {
+    const input = `
+import { Defer } from '@pyreon/core'
+import { Modal } from './Modal'
+export function App() {
+  return (
+    <Defer when={() => true}>
+      <Modal title="Hello">
+        <p>nested content</p>
+      </Modal>
+    </Defer>
+  )
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(true)
+    // Both opening AND closing tag names replaced with __C; nested JSX intact.
+    expect(result.code).toContain('<__C title="Hello">')
+    expect(result.code).toContain('</__C>')
+    expect(result.code).toContain('<p>nested content</p>')
+  })
+
+  test('captures closure variables via render-prop scope (signal in handler)', () => {
+    const input = `
+import { Defer } from '@pyreon/core'
+import { signal } from '@pyreon/reactivity'
+import { Modal } from './Modal'
+
+export function App() {
+  const open = signal(false)
+  const count = signal(0)
+  return (
+    <Defer when={open}>
+      <Modal count={count} onClose={() => open.set(false)} />
+    </Defer>
+  )
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(true)
+    // The render-prop arrow naturally captures `count` + `open.set` from
+    // the App function's scope — no closure-tracking pass needed, JS
+    // lexical scope just works.
+    expect(result.code).toContain('<__C count={count} onClose={() => open.set(false)} />')
+  })
+
+  test('handles renamed imports — { Modal as M }', () => {
     const input = `
 import { Defer } from '@pyreon/core'
 import { Modal as M } from './Modal'
@@ -166,11 +221,32 @@ export function App() {
 }
 `
     const result = transformDeferInline(input, 'app.tsx')
-    expect(result.changed).toBe(false)
-    // Renamed-import case is not yet supported — falls through to the
-    // import-not-found warning (no specifier whose `local.name === 'M'`
-    // AND `imported.name === local.name` matches).
-    expect(result.warnings[0]?.code).toBe('defer-inline/import-not-found')
+    expect(result.changed).toBe(true)
+    // Local name `M` is used at the JSX site, but the chunk extracts
+    // `__m.Modal` (the original exported name from './Modal').
+    expect(result.code).toContain(`chunk={() => import('./Modal').then((__m) => ({ default: __m.Modal }))}`)
+    expect(result.code).not.toContain("import { Modal as M }")
+    expect(result.code).toContain('{(__C) => <__C />}')
+  })
+
+  test('multi-specifier import: drops only the Defer-targeted binding', () => {
+    const input = `
+import { Defer } from '@pyreon/core'
+import { Modal, OtherThing } from './shared'
+export function App() {
+  const use = OtherThing
+  return <Defer when={() => true}><Modal /></Defer>
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(true)
+    // OtherThing is referenced elsewhere — its import must survive.
+    expect(result.code).toContain("OtherThing")
+    expect(result.code).toMatch(/import \{\s*OtherThing\s*\} from '\.\/shared'/)
+    // Modal binding is gone from the import declaration.
+    expect(result.code).not.toMatch(/import \{[^}]*\bModal\b[^}]*\}/)
+    // ...but the dynamic chunk pulls Modal from './shared' (same source).
+    expect(result.code).toContain(`chunk={() => import('./shared').then((__m) => ({ default: __m.Modal }))}`)
   })
 })
 
@@ -197,3 +273,115 @@ export function App() {
     expect(result.code).toContain(`chunk={() => import('./Comments').then((__m) => ({ default: __m.Comments }))}`)
   })
 })
+
+// Gap 4 from the v2 follow-up roadmap. Namespace imports were the last
+// inline-Defer shape that fell back to the explicit form — closing this
+// gap means EVERY common import shape is supported by the inline form.
+describe('transformDeferInline — namespace imports (v3)', () => {
+  test('rewrites <M.Modal /> with namespace import — chunk extracts __m.Modal', () => {
+    const input = `
+import { Defer } from '@pyreon/core'
+import * as M from './Modal'
+export function App() {
+  return <Defer when={() => true}><M.Modal /></Defer>
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(true)
+    expect(result.code).toContain(`chunk={() => import('./Modal').then((__m) => ({ default: __m.Modal }))}`)
+    // M.Modal in the JSX replaced with __C (the whole member expression
+    // is the "name" range that gets substituted).
+    expect(result.code).toContain('{(__C) => <__C />}')
+    expect(result.code).not.toContain('import * as M from')
+  })
+
+  test('rewrites with props on member-expression child', () => {
+    const input = `
+import { Defer } from '@pyreon/core'
+import * as M from './Modal'
+export function App() {
+  return <Defer when={() => true}><M.Modal title="hi" /></Defer>
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(true)
+    expect(result.code).toContain('{(__C) => <__C title="hi" />}')
+  })
+
+  test('non-self-closing member-expression child preserves opening + closing replacement', () => {
+    const input = `
+import { Defer } from '@pyreon/core'
+import * as M from './Modal'
+export function App() {
+  return <Defer when={() => true}><M.Modal title="hi"><span>body</span></M.Modal></Defer>
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(true)
+    expect(result.code).toContain('{(__C) => <__C title="hi"><span>body</span></__C>}')
+  })
+
+  test('bails when namespace is referenced elsewhere in the file', () => {
+    // `M` is used for multiple components. Removing the static import
+    // would break the other usage AND the dynamic import becomes a
+    // no-op (Rolldown bundles the module statically when ANY part is
+    // referenced).
+    const input = `
+import { Defer } from '@pyreon/core'
+import * as M from './Modal'
+export function App() {
+  void M.Settings
+  return <Defer when={() => true}><M.Modal /></Defer>
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(false)
+    expect(result.warnings).toHaveLength(1)
+    expect(result.warnings[0]!.code).toBe('defer-inline/import-used-elsewhere')
+  })
+
+  test('bails on deeper member expression — <M.Sub.X /> not supported', () => {
+    const input = `
+import { Defer } from '@pyreon/core'
+import * as M from './Modal'
+export function App() {
+  return <Defer when={() => true}><M.Sub.Modal /></Defer>
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    // analyzeChildElement returns null for non-depth-1 member
+    // expressions → no match in findDeferMatches → no warning. The
+    // Defer is left alone; runtime errors with "missing chunk".
+    expect(result.changed).toBe(false)
+  })
+
+  test('bails when member property is lowercase — <M.helper /> is not a component', () => {
+    const input = `
+import { Defer } from '@pyreon/core'
+import * as M from './lib'
+export function App() {
+  return <Defer when={() => true}><M.helper /></Defer>
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(false)
+  })
+
+  test('bails when member expression but import is default (not namespace)', () => {
+    // `import M from './X'` (default) followed by `<M.Modal />` is a
+    // member access on the default-exported component itself, not a
+    // namespace lookup. Different semantics; out of scope. Compiler
+    // emits `unsupported-import-shape` so the author knows why.
+    const input = `
+import { Defer } from '@pyreon/core'
+import M from './Modal'
+export function App() {
+  return <Defer when={() => true}><M.Modal /></Defer>
+}
+`
+    const result = transformDeferInline(input, 'app.tsx')
+    expect(result.changed).toBe(false)
+    expect(result.warnings).toHaveLength(1)
+    expect(result.warnings[0]!.code).toBe('defer-inline/unsupported-import-shape')
+  })
+})

package/src/tests/detector-tag-consistency.test.ts

@@ -30,6 +30,7 @@ const COMPILER_CODES = [
   'for-missing-by',
   'for-with-key',
   'props-destructured',
+  'props-destructured-body',
   'process-dev-gate',
   'empty-theme',
   'raw-add-event-listener',
@@ -40,6 +41,7 @@ const COMPILER_CODES = [
   'static-return-null-conditional',
   'as-unknown-as-vnodechild',
   'island-never-with-registry-entry',
+  'query-options-as-function',
 ] as const
 type CompilerCode = (typeof COMPILER_CODES)[number]
 

package/src/tests/manifest-snapshot.test.ts

@@ -0,0 +1,55 @@
+import {
+  renderApiReferenceEntries,
+  renderLlmsFullSection,
+  renderLlmsTxtLine,
+} from '@pyreon/manifest'
+import manifest from '../manifest'
+
+describe('gen-docs — compiler snapshot', () => {
+  it('renders a llms.txt bullet starting with the package prefix', () => {
+    const line = renderLlmsTxtLine(manifest)
+    expect(line.startsWith('- @pyreon/compiler —')).toBe(true)
+  })
+
+  it('renders a llms-full.txt section with the right header', () => {
+    const section = renderLlmsFullSection(manifest)
+    expect(section.startsWith('## @pyreon/compiler —')).toBe(true)
+    expect(section).toContain('```typescript')
+  })
+
+  it('renders MCP api-reference entries for every api[] item', () => {
+    const record = renderApiReferenceEntries(manifest)
+    expect(Object.keys(record).sort()).toEqual([
+      'compiler/analyzeReactivity',
+      'compiler/auditIslands',
+      'compiler/auditSsg',
+      'compiler/auditTestEnvironment',
+      'compiler/detectPyreonPatterns',
+      'compiler/detectReactPatterns',
+      'compiler/diagnoseError',
+      'compiler/formatIslandAudit',
+      'compiler/formatReactivityLens',
+      'compiler/formatSsgAudit',
+      'compiler/formatTestAudit',
+      'compiler/generateContext',
+      'compiler/hasPyreonPatterns',
+      'compiler/hasReactPatterns',
+      'compiler/migrateReactCode',
+      'compiler/transformDeferInline',
+      'compiler/transformJSX',
+      'compiler/transformJSX_JS',
+    ])
+  })
+
+  it('flags the experimental Reactivity-Lens entries', () => {
+    const r = renderApiReferenceEntries(manifest)
+    expect(r['compiler/analyzeReactivity']?.notes).toContain('[EXPERIMENTAL]')
+    expect(r['compiler/formatReactivityLens']?.notes).toContain('[EXPERIMENTAL]')
+  })
+
+  it('carries the foot-gun catalog into MCP mistakes for flagship APIs', () => {
+    const r = renderApiReferenceEntries(manifest)
+    expect(r['compiler/transformJSX']?.mistakes).toBeTruthy()
+    expect(r['compiler/detectPyreonPatterns']?.mistakes).toContain('fixable')
+  })
+})

package/src/tests/native-equivalence.test.ts

@@ -5,11 +5,23 @@
  * between the two backends.
  */
 import { transformJSX_JS } from '../jsx'
+import type { ReactivitySpan } from '../jsx'
 
 // Load native if available
-let nativeTransform: ((code: string, filename: string, ssr: boolean, knownSignals: string[] | null) => {
-  code: string; usesTemplates?: boolean | null; warnings: Array<{ message: string; line: number; column: number; code: string }>
-}) | null = null
+let nativeTransform:
+  | ((
+      code: string,
+      filename: string,
+      ssr: boolean,
+      knownSignals: string[] | null,
+      reactivityLens?: boolean,
+    ) => {
+      code: string
+      usesTemplates?: boolean | null
+      warnings: Array<{ message: string; line: number; column: number; code: string }>
+      reactivityLens?: ReactivitySpan[] | null
+    })
+  | null = null
 
 try {
   const path = require('node:path')
@@ -39,6 +51,50 @@ function compareSsr(input: string) {
   expect(rs.code).toBe(js.code)
 }
 
+// Reactivity-lens cross-backend gate (Phase 3). Asserts the Rust binary
+// emits the SAME sidecar the JS oracle does. Two contracts:
+//   1. ADDITIVE — `code` is byte-identical with the lens collected vs
+//      not, on BOTH backends (the option never affects codegen).
+//   2. PARITY — the SET of recorded spans is identical JS↔Rust.
+// Spans are compared order-independently: the LSP consumer sorts before
+// rendering, so traversal order is NOT part of the contract — the SET of
+// codegen decisions is. Sorting by (start,end,kind,detail) makes a
+// missing/extra/wrong span fail loudly while ignoring walk order.
+function canon(spans: ReactivitySpan[] | null | undefined): string[] {
+  return (spans ?? [])
+    .map(
+      (s) =>
+        `${s.start}|${s.end}|${s.line}|${s.column}|${s.endLine}|${s.endColumn}|${s.kind}|${s.detail}`,
+    )
+    .sort()
+}
+
+function compareLens(input: string, filename = 'test.tsx') {
+  const jsOff = transformJSX_JS(input, filename)
+  const jsOn = transformJSX_JS(input, filename, { reactivityLens: true })
+  const rsOff = nativeTransform!(input, filename, false, null, false)
+  const rsOn = nativeTransform!(input, filename, false, null, true)
+
+  // (1) additive — collecting the lens never changes emitted code, on
+  // either backend, and both backends still agree on that code.
+  expect(jsOn.code).toBe(jsOff.code)
+  expect(rsOn.code).toBe(rsOff.code)
+  expect(rsOn.code).toBe(jsOn.code)
+
+  // The opt-out path must NOT carry the sidecar (parity with JS, which
+  // omits the field entirely when not collecting).
+  expect(rsOff.reactivityLens == null).toBe(true)
+  expect(jsOff.reactivityLens == null).toBe(true)
+
+  // (2) parity — identical SET of spans.
+  const j = canon(jsOn.reactivityLens)
+  const r = canon(rsOn.reactivityLens)
+  expect(r).toEqual(j)
+  // Guard against the degenerate "both empty → trivially equal" pass:
+  // every fixture below is chosen to produce ≥1 span.
+  expect(j.length).toBeGreaterThan(0)
+}
+
 // ─── Cross-backend equivalence ──────────────────────────────────────────────
 
 describeNative('Native vs JS equivalence — basic', () => {
@@ -729,3 +785,48 @@ describeNative('Native vs JS equivalence — DOM properties', () => {
     compare('<div><input title={x()} /></div>')
   })
 })
+
+// ─── Reactivity-lens parity (Phase 3) ───────────────────────────────────────
+// The Rust binary must emit the SAME sidecar as the JS oracle so the
+// ~80% of users on the native path get the Lens too. Each fixture is
+// chosen to exercise one of the five structural kinds; `compareLens`
+// also asserts the additive guarantee (codegen byte-identical with the
+// option on vs off, both backends) so this block doubles as the native
+// regression guard for "the lens option must never affect output".
+//
+// Bisect-verified: removing ANY of the 6 `ctx.lens(...)` calls in
+// native/src/lib.rs fails the matching fixture below with an
+// array-length / element mismatch in `compareLens`'s parity assertion
+// (e.g. dropping the `reactive-prop` call → `<Comp value={x()} />` fails
+// `expect(r).toEqual(j)` because the Rust set is missing that span);
+// restored → 9/9 pass.
+describeNative('Reactivity-lens — JS↔Rust span parity', () => {
+  test('reactive text child (_bindText)', () =>
+    compareLens('<div>{count()}</div>'))
+
+  test('reactive accessor text child (() => …)', () =>
+    compareLens('<div>{() => count()}</div>'))
+
+  test('static-text child (baked once — the high-precision negative)', () =>
+    compareLens('<div>{someConst}</div>'))
+
+  test('reactive-prop on a component (_rp(() => …))', () =>
+    compareLens('<Comp value={count()} />'))
+
+  test('reactive-attr on a DOM element (live binding)', () =>
+    compareLens('<div><span title={count()}>hi</span></div>'))
+
+  test('hoisted-static (module-scope hoist)', () =>
+    compareLens('<Comp>{<b class="x">hi</b>}</Comp>'))
+
+  test('mixed: reactive + static + prop in one tree', () =>
+    compareLens(
+      '<section><Comp value={count()} /><p>{count()}</p><p>{label}</p></section>',
+    ))
+
+  test('multi-line source — line/column parity across newlines', () =>
+    compareLens('<div>\n  {count()}\n  <span title={other()}>\n  z</span>\n</div>'))
+
+  test('signal auto-call shape — declared signal, bare {count} → reactive', () =>
+    compareLens('const count = signal(0); const App = () => <div>{count}</div>', 'auto.tsx'))
+})

package/src/tests/pyreon-intercept.test.ts

@@ -84,6 +84,137 @@ describe('detectPyreonPatterns', () => {
     })
   })
 
+  describe('props-destructured-body', () => {
+    const only = (code: string) =>
+      detectPyreonPatterns(code).filter((d) => d.code === 'props-destructured-body')
+
+    it('flags `const { x } = props` in an arrow component body', () => {
+      const code = `
+        const Greeting = (props: { name: string }) => {
+          const { name } = props
+          return <div>Hello {name}</div>
+        }
+      `
+      const diags = only(code)
+      expect(diags).toHaveLength(1)
+      expect(diags[0]!.code).toBe('props-destructured-body')
+      expect(diags[0]!.message).toContain('ONCE')
+      expect(diags[0]!.fixable).toBe(false)
+    })
+
+    it('flags it in a function-declaration component', () => {
+      const code = `
+        function Greeting(props: { name: string }) {
+          const { name } = props
+          return <div>Hello {name}</div>
+        }
+      `
+      expect(only(code)).toHaveLength(1)
+    })
+
+    it('flags let / var / alias / default / rest / nested shapes', () => {
+      const code = `
+        const A = (props: any) => { let { a } = props; return <i>{a}</i> }
+        const B = (props: any) => { var { b } = props; return <i>{b}</i> }
+        const C = (props: any) => { const { c: cc } = props; return <i>{cc}</i> }
+        const D = (props: any) => { const { d = 1 } = props; return <i>{d}</i> }
+        const E = (props: any) => { const { ...rest } = props; return <i>{rest.x}</i> }
+        const F = (props: any) => { const { f: { g } } = props; return <i>{g}</i> }
+      `
+      expect(only(code)).toHaveLength(6)
+    })
+
+    it('flags a destructure nested inside a body-scope if-block (still synchronous)', () => {
+      const code = `
+        const Gate = (props: any) => {
+          if (props.cond) { const { x } = props; return <i>{x}</i> }
+          return <i />
+        }
+      `
+      expect(only(code)).toHaveLength(1)
+    })
+
+    it('unwraps `as` / `satisfies` / `!` / parens on the initializer', () => {
+      const code = `
+        const A = (props: any) => { const { a } = props as Props; return <i>{a}</i> }
+        const B = (props: any) => { const { b } = (props); return <i>{b}</i> }
+        const C = (props: any) => { const { c } = props!; return <i>{c}</i> }
+        const D = (props: any) => { const { d } = props satisfies Props; return <i>{d}</i> }
+      `
+      expect(only(code)).toHaveLength(4)
+    })
+
+    it('does NOT flag `const x = props` (alias, no destructure)', () => {
+      const code = `
+        const Greeting = (props: any) => { const p = props; return <div>{p.name}</div> }
+      `
+      expect(only(code)).toEqual([])
+    })
+
+    it('does NOT flag a destructure off a non-props identifier', () => {
+      const code = `
+        const Greeting = (props: any) => {
+          const store = useStore()
+          const { name } = store
+          return <div>{name}{props.x}</div>
+        }
+      `
+      expect(only(code)).toEqual([])
+    })
+
+    it('does NOT flag `const { x } = props.nested` (member, out of canonical scope by design)', () => {
+      const code = `
+        const Greeting = (props: any) => { const { x } = props.nested; return <div>{x}</div> }
+      `
+      expect(only(code)).toEqual([])
+    })
+
+    it('does NOT flag destructures inside nested functions (handler / effect / returned accessor)', () => {
+      const code = `
+        const Handler = (props: any) => {
+          const onClick = () => { const { id } = props; doThing(id) }
+          effect(() => { const { y } = props; track(y) })
+          return <button onClick={onClick}>{() => { const { z } = props; return z }}</button>
+        }
+      `
+      expect(only(code)).toEqual([])
+    })
+
+    it('does NOT flag the returned reactive-accessor fix shape', () => {
+      const code = `
+        const Greeting = (props: any) =>
+          (() => { const { name } = props; return <div>Hello {name}</div> })
+      `
+      // The body is an arrow expression returning a nested accessor — the
+      // destructure lives inside the nested fn, which re-reads props.
+      expect(only(code)).toEqual([])
+    })
+
+    it('does NOT flag the parameter-destructure shape (props-destructured owns it)', () => {
+      const code = `
+        const Greeting = ({ name }: { name: string }) => <div>Hello {name}</div>
+      `
+      const diags = detectPyreonPatterns(code)
+      expect(diags.filter((d) => d.code === 'props-destructured-body')).toEqual([])
+      expect(diags.filter((d) => d.code === 'props-destructured')).toHaveLength(1)
+    })
+
+    it('does NOT flag non-component helpers that destructure an arg named props', () => {
+      const code = `
+        function mergeProps(props: any) { const { a, b } = props; return a + b }
+        const reducer = (props: any) => { const { x } = props; return x }
+      `
+      expect(only(code)).toEqual([])
+    })
+
+    it('does NOT flag a lowercase JSX-returning function (not component-shaped)', () => {
+      const code = `
+        const renderRow = (props: any) => { const { cell } = props; return <td>{cell}</td> }
+      `
+      expect(only(code)).toEqual([])
+    })
+  })
+
   describe('process-dev-gate', () => {
     it('flags typeof process + NODE_ENV production gates', () => {
       const code = `
@@ -624,4 +755,62 @@ describe('detectPyreonPatterns', () => {
       ).toBe(true)
     })
   })
+
+  describe('query-options-as-function', () => {
+    it('flags useQuery with an object-literal first arg', () => {
+      const code = `const q = useQuery({ queryKey: ['user', id()], queryFn: fetchUser })`
+      const diags = detectPyreonPatterns(code)
+      const d = diags.find((x) => x.code === 'query-options-as-function')
+      expect(d).toBeDefined()
+      expect(d!.fixable).toBe(false)
+      expect(d!.message).toContain('FUNCTION')
+      expect(d!.suggested).toBe(
+        "useQuery(() => ({ queryKey: ['user', id()], queryFn: fetchUser }))",
+      )
+    })
+
+    it('flags useInfiniteQuery / useQueries / useSuspenseQuery too', () => {
+      for (const hook of [
+        'useInfiniteQuery',
+        'useQueries',
+        'useSuspenseQuery',
+      ]) {
+        const diags = detectPyreonPatterns(`const r = ${hook}({ queryKey: ['k'] })`)
+        expect(
+          diags.some((d) => d.code === 'query-options-as-function'),
+        ).toBe(true)
+      }
+    })
+
+    it('does NOT flag the correct function form', () => {
+      const code = `const q = useQuery(() => ({ queryKey: ['user', id()], queryFn: fetchUser }))`
+      const diags = detectPyreonPatterns(code)
+      expect(
+        diags.some((d) => d.code === 'query-options-as-function'),
+      ).toBe(false)
+    })
+
+    it('does NOT flag useMutation (options are a plain object by design)', () => {
+      const code = `const m = useMutation({ mutationFn: save, onSuccess })`
+      const diags = detectPyreonPatterns(code)
+      expect(
+        diags.some((d) => d.code === 'query-options-as-function'),
+      ).toBe(false)
+    })
+
+    it('does NOT flag an identifier / call options arg (unprovable)', () => {
+      const code = `const a = useQuery(opts); const b = useQuery(makeOpts())`
+      const diags = detectPyreonPatterns(code)
+      expect(
+        diags.some((d) => d.code === 'query-options-as-function'),
+      ).toBe(false)
+    })
+
+    it('hasPyreonPatterns pre-filter recognizes the object-literal form', () => {
+      expect(hasPyreonPatterns(`useQuery({ queryKey: ['k'] })`)).toBe(true)
+      expect(hasPyreonPatterns(`useQuery(() => ({ queryKey: ['k'] }))`)).toBe(
+        false,
+      )
+    })
+  })
 })