@pyreon/compiler 0.18.0 → 0.20.0

package/src/load-native.ts

@@ -37,6 +37,7 @@ export interface NativeBinding {
     filename: string,
     ssr: boolean,
     knownSignals: string[] | null,
+    reactivityLens: boolean,
   ) => unknown
 }
 

package/src/manifest.ts

@@ -0,0 +1,280 @@
+import { defineManifest } from '@pyreon/manifest'
+
+export default defineManifest({
+  name: '@pyreon/compiler',
+  title: 'JSX Reactive Transform',
+  tagline:
+    'JSX reactive transform (Rust native + JS fallback) plus the Reactivity-Lens sidecar, React→Pyreon migration, and project audits',
+  description:
+    "Pyreon's JSX-to-reactive transform. `transformJSX` dispatches to a Rust native binary (napi-rs, 3.7-8.9× faster) and falls back per-call to the pure-JS `transformJSX_JS` when the binary is unavailable (CI, WASM, wrong platform); the two backends are asserted byte-identical by 180+ cross-backend equivalence tests. Emits `_tpl()` (cloneNode templates) + per-text-node `_bind()`, hoists static JSX, inlines `const`-from-`props`, and auto-calls bare signal references in JSX. Also ships the experimental Reactivity-Lens sidecar (`analyzeReactivity` — surfaces the compiler's own per-expression reactive/static decision back to editors), React-pattern detection + one-shot migration, the Pyreon anti-pattern detector behind the MCP `validate` tool, and the syntactic project audits powering `pyreon doctor` (test-environment / islands / SSG).",
+  category: 'universal',
+  features: [
+    'Dual-backend transformJSX — Rust native (napi-rs) with automatic per-call JS fallback, byte-identical output',
+    'Reactivity-Lens: analyzeReactivity / formatReactivityLens surface the compiler’s reactive-vs-static decision (experimental)',
+    'Scope-aware signal auto-call: bare {count} → {() => count()}, shadowing-correct, knownSignals seeds cross-module',
+    'detectReactPatterns + migrateReactCode — "coming from React" diagnostics + one-shot codemod',
+    'detectPyreonPatterns — 14 "using Pyreon wrong" anti-pattern codes (the MCP validate detector)',
+    'Project audits: auditTestEnvironment / auditIslands / auditSsg (power pyreon doctor)',
+    'transformDeferInline — <Defer> namespace-import inlining pass',
+    'generateContext — project scanner producing the AI .pyreon/context.json',
+  ],
+  api: [
+    {
+      name: 'transformJSX',
+      kind: 'function',
+      signature:
+        'transformJSX(code: string, filename?: string, options?: TransformOptions): TransformResult',
+      summary:
+        'The production entry point. Tries the Rust native binary first (3.7-8.9× faster) and falls back per-call to `transformJSX_JS` inside a try/catch so a native panic never crashes the Vite dev server. Output (`{ code, usesTemplates?, warnings, reactivityLens? }`) is byte-identical across both backends. `options.ssr` skips the `_tpl()` template optimization so `@pyreon/runtime-server` can walk the VNode tree; `options.knownSignals` seeds cross-module signal auto-call; `options.reactivityLens` collects the additive `ReactivitySpan[]` sidecar (codegen is byte-identical whether or not it is collected).',
+      example: `import { transformJSX } from "@pyreon/compiler"
+
+const { code, warnings } = transformJSX(
+  "export const App = () => <div>{count()}</div>",
+  "App.tsx",
+  { knownSignals: ["count"] },
+)`,
+      mistakes: [
+        'Expecting `transformJSX` to throw on a native panic — it never does; it silently falls back to the JS backend (correctness-equivalent, just slower)',
+        'Passing user component source WITHOUT `ssr: true` when feeding the result to `@pyreon/runtime-server` — SSR needs the `h()` VNode tree, not `_tpl()` clone templates',
+        'Assuming bare `{count}` is auto-called for an IMPORTED signal without seeding `knownSignals` — the compiler only tracks `const count = signal(...)` declared in the same file unless told otherwise',
+      ],
+      seeAlso: ['transformJSX_JS', 'analyzeReactivity'],
+    },
+    {
+      name: 'transformJSX_JS',
+      kind: 'function',
+      signature:
+        'transformJSX_JS(code: string, filename?: string, options?: TransformOptions): TransformResult',
+      summary:
+        'The pure-JS reactive pass (parses via `oxc-parser`). Same signature and byte-identical output to the native path — `transformJSX` calls it as the fallback. Call it directly only when you need backend-deterministic output (the Reactivity-Lens forces this path so the sidecar is always emitted regardless of whether the native binary is installed).',
+      example: `import { transformJSX_JS } from "@pyreon/compiler"
+
+// Backend-deterministic — never dispatches to the native binary.
+const { code } = transformJSX_JS("<div>{name()}</div>", "x.tsx")`,
+      seeAlso: ['transformJSX'],
+    },
+    {
+      name: 'analyzeReactivity',
+      kind: 'function',
+      signature:
+        "analyzeReactivity(code: string, filename?: string, options?: { knownSignals?: string[] }): AnalyzeReactivityResult",
+      summary:
+        "Reactivity-Lens entry point (experimental). The compiler ALREADY decides per-expression whether code is reactive while emitting codegen; this surfaces that ground truth back to the author instead of discarding it. Returns `{ findings, spans }` — `findings` merges the structural codegen decisions (`reactive` / `reactive-prop` / `reactive-attr` / `static-text` / `hoisted-static`) with the EXISTING `detectPyreonPatterns` footguns (`kind: 'footgun'`, carrying the detector `code`) under one (line, column)-sorted taxonomy. Forces the JS backend so the sidecar is always present. Absence of a span is “not asserted”, never an implicit static claim.",
+      example: `import { analyzeReactivity, formatReactivityLens } from "@pyreon/compiler"
+
+const result = analyzeReactivity(
+  "const A = (props) => <div>{props.name}</div>",
+  "A.tsx",
+)
+for (const f of result.findings) console.log(f.line, f.kind, f.detail)
+console.log(formatReactivityLens(code, result)) // annotated-source debug view`,
+      mistakes: [
+        'Treating the absence of a span as a static guarantee — the Lens is asymmetric: positive spans are RECORDS of a codegen branch; silence means "not analyzed", not "proven static"',
+        'Expecting it to reflect the native backend — it deliberately forces `transformJSX_JS`; codegen is byte-identical so the analysis is sound, native just does not emit the sidecar at production bundle time (it is an editor-only feature)',
+        'Calling it on a hot build path — it is an authoring-time / LSP tool, not part of the production transform pipeline',
+      ],
+      stability: 'experimental',
+      seeAlso: ['formatReactivityLens', 'detectPyreonPatterns', 'transformJSX_JS'],
+    },
+    {
+      name: 'formatReactivityLens',
+      kind: 'function',
+      signature:
+        'formatReactivityLens(code: string, result: AnalyzeReactivityResult): string',
+      summary:
+        'Renders an `analyzeReactivity` result as an annotated-source CLI / debug view — each spanned expression gets an inline `live` / `static` / `live·prop` / `hoisted` / footgun tag. The LSP surface in `@pyreon/lint --lsp` consumes the structured `findings` directly (inlay hints + diagnostics); this string renderer is for terminals and bug reports.',
+      example: `import { analyzeReactivity, formatReactivityLens } from "@pyreon/compiler"
+
+const r = analyzeReactivity(src, "App.tsx")
+process.stdout.write(formatReactivityLens(src, r))`,
+      stability: 'experimental',
+      seeAlso: ['analyzeReactivity'],
+    },
+    {
+      name: 'detectReactPatterns',
+      kind: 'function',
+      signature:
+        "detectReactPatterns(code: string, filename?: string): ReactDiagnostic[]",
+      summary:
+        'AST-based detector for "coming from React" mistakes — `useState` / `useEffect`, `className` / `htmlFor`, `onChange` on inputs, `.value` writes on signals, React-package imports. Pairs with `detectPyreonPatterns` inside the MCP `validate` tool; the merged result is sorted by line + column.',
+      example: `import { detectReactPatterns } from "@pyreon/compiler"
+
+const diags = detectReactPatterns("const [n,setN] = useState(0)", "x.tsx")
+console.log(diags[0]?.code) // "react-use-state"`,
+      seeAlso: ['migrateReactCode', 'detectPyreonPatterns', 'hasReactPatterns'],
+    },
+    {
+      name: 'migrateReactCode',
+      kind: 'function',
+      signature:
+        "migrateReactCode(code: string, filename?: string): MigrationResult",
+      summary:
+        'One-shot React→Pyreon codemod — `useState`→`signal`, `useEffect`→`effect`/`onMount`, `className`→`class`, etc. Returns the rewritten code plus the list of applied `MigrationChange`s. Mechanical only: shapes it cannot safely rewrite are left as `detectReactPatterns` diagnostics for the human.',
+      example: `import { migrateReactCode } from "@pyreon/compiler"
+
+const { code, changes } = migrateReactCode(reactSource, "C.tsx")`,
+      seeAlso: ['detectReactPatterns'],
+    },
+    {
+      name: 'hasReactPatterns',
+      kind: 'function',
+      signature: 'hasReactPatterns(code: string): boolean',
+      summary:
+        'Fast regex pre-filter — returns whether `code` is worth a full `detectReactPatterns` AST walk. Cheap gate for batch scanners; never reports diagnostics itself.',
+      example: `import { hasReactPatterns, detectReactPatterns } from "@pyreon/compiler"
+
+if (hasReactPatterns(src)) report(detectReactPatterns(src, file))`,
+      seeAlso: ['detectReactPatterns'],
+    },
+    {
+      name: 'diagnoseError',
+      kind: 'function',
+      signature: 'diagnoseError(error: string): ErrorDiagnosis | null',
+      summary:
+        'Maps a raw runtime/build error string to a structured `ErrorDiagnosis` (likely cause + actionable fix) for known Pyreon failure shapes. Returns `null` when the error is unrecognised — callers fall back to the raw message.',
+      example: `import { diagnoseError } from "@pyreon/compiler"
+
+const d = diagnoseError("props.when is not a function")
+if (d) console.log(d.cause, d.fix)`,
+    },
+    {
+      name: 'detectPyreonPatterns',
+      kind: 'function',
+      signature:
+        "detectPyreonPatterns(code: string, filename?: string): PyreonDiagnostic[]",
+      summary:
+        'AST-based (TypeScript compiler API) detector for "using Pyreon wrong" mistakes — 14 codes today (`for-missing-by`, `for-with-key`, `props-destructured`, `props-destructured-body`, `process-dev-gate`, `empty-theme`, `raw-add-event-listener`, `raw-remove-event-listener`, `date-math-random-id`, `on-click-undefined`, `signal-write-as-call`, `static-return-null-conditional`, `as-unknown-as-vnodechild`, `island-never-with-registry-entry`). The detector arm behind the MCP `validate` tool and `pyreon doctor --check-pyreon-patterns`. Every diagnostic reports `fixable: false` (invariant — no `migrate_pyreon` codemod ships yet).',
+      example: `import { detectPyreonPatterns } from "@pyreon/compiler"
+
+const diags = detectPyreonPatterns(
+  "const A = (props) => { const { x } = props; return <i>{x}</i> }",
+  "A.tsx",
+)
+console.log(diags[0]?.code) // "props-destructured-body"`,
+      mistakes: [
+        'Reading `fixable` as sometimes-true — it is an enforced `false` invariant for every Pyreon code; wiring auto-fix UX off it applies nothing',
+        'Expecting it to flag `const { x } = props.nested` or an `onMount`-scoped destructure — `props-destructured-body` is deliberately scoped to the canonical `= props` body-scope shape for zero false positives',
+      ],
+      seeAlso: ['hasPyreonPatterns', 'detectReactPatterns', 'analyzeReactivity'],
+    },
+    {
+      name: 'hasPyreonPatterns',
+      kind: 'function',
+      signature: 'hasPyreonPatterns(code: string): boolean',
+      summary:
+        'Fast regex pre-filter for `detectPyreonPatterns` — deliberately loose (the AST walker is the precise gate); only has to avoid skipping a file that might contain a pattern.',
+      example: `import { hasPyreonPatterns, detectPyreonPatterns } from "@pyreon/compiler"
+
+if (hasPyreonPatterns(src)) report(detectPyreonPatterns(src, file))`,
+      seeAlso: ['detectPyreonPatterns'],
+    },
+    {
+      name: 'auditTestEnvironment',
+      kind: 'function',
+      signature: 'auditTestEnvironment(startDir: string): TestAuditResult',
+      summary:
+        'Scans every `*.test.ts(x)` under `startDir` for the mock-vnode anti-pattern (constructing `{ type, props, children }` literals or a `vnode()` helper instead of going through real `h()`), the bug class behind PR #197’s silent metadata drop. Classifies each file HIGH / MEDIUM / LOW. Powers the MCP `audit_test_environment` tool and `pyreon doctor --audit-tests`.',
+      example: `import { auditTestEnvironment, formatTestAudit } from "@pyreon/compiler"
+
+const r = auditTestEnvironment(process.cwd())
+console.log(formatTestAudit(r, { minRisk: "high" }))`,
+      seeAlso: ['formatTestAudit', 'auditIslands', 'auditSsg'],
+    },
+    {
+      name: 'formatTestAudit',
+      kind: 'function',
+      signature:
+        'formatTestAudit(result: TestAuditResult, options?: AuditFormatOptions): string',
+      summary:
+        'Human-readable renderer for an `auditTestEnvironment` result; `options.minRisk` filters the floor (`high` | `medium` | `low`). The CLI / MCP surfaces also have a JSON path — this is the text view.',
+      example: `import { auditTestEnvironment, formatTestAudit } from "@pyreon/compiler"
+
+console.log(formatTestAudit(auditTestEnvironment("."), { minRisk: "medium" }))`,
+      seeAlso: ['auditTestEnvironment'],
+    },
+    {
+      name: 'auditIslands',
+      kind: 'function',
+      signature: 'auditIslands(rootDir: string): IslandAuditResult',
+      summary:
+        'Project-wide syntactic island audit — five cross-file detectors (`duplicate-name`, `never-with-registry-entry`, `registry-mismatch`, `nested-island`, `dead-island`) that auto-registry and the per-file detector cannot reach. No type-check pass / module resolution; entirely TypeScript-compiler-API syntactic. Powers `pyreon doctor --check-islands` + the MCP `audit_islands` tool.',
+      example: `import { auditIslands, formatIslandAudit } from "@pyreon/compiler"
+
+const r = auditIslands(process.cwd())
+for (const f of r.findings) console.log(f.code, f.location.file)`,
+      seeAlso: ['formatIslandAudit', 'auditTestEnvironment', 'auditSsg'],
+    },
+    {
+      name: 'formatIslandAudit',
+      kind: 'function',
+      signature:
+        'formatIslandAudit(result: IslandAuditResult, options?: IslandAuditFormatOptions): string',
+      summary:
+        'Text renderer for an `auditIslands` result — each finding with file path + line/column + an actionable fix suggestion. The `--json` CLI path bypasses this for CI gates.',
+      example: `import { auditIslands, formatIslandAudit } from "@pyreon/compiler"
+
+console.log(formatIslandAudit(auditIslands(".")))`,
+      seeAlso: ['auditIslands'],
+    },
+    {
+      name: 'auditSsg',
+      kind: 'function',
+      signature: 'auditSsg(rootDir: string): SsgAuditResult',
+      summary:
+        'Project-wide syntactic SSG audit — three detectors: `404-outside-layout-dir` (`_404.tsx` not co-located with `_layout.tsx` → no layout chrome), `dynamic-route-missing-get-static-paths` (`[id].tsx` without `getStaticPaths` → silently skipped by SSG auto-detect), `non-literal-revalidate-export` (`export const revalidate = TTL` → dropped from the build-time ISR manifest). API routes (`src/routes/api/` or no `export default`) are skipped. Powers `pyreon doctor --check-ssg`.',
+      example: `import { auditSsg, formatSsgAudit } from "@pyreon/compiler"
+
+const r = auditSsg(process.cwd())
+for (const f of r.findings) console.log(f.code, f.location.file)`,
+      seeAlso: ['formatSsgAudit', 'auditIslands'],
+    },
+    {
+      name: 'formatSsgAudit',
+      kind: 'function',
+      signature:
+        'formatSsgAudit(result: SsgAuditResult, options?: SsgAuditFormatOptions): string',
+      summary:
+        'Text renderer for an `auditSsg` result — file path + line/column + actionable fix per finding. CI gates use the JSON path instead.',
+      example: `import { auditSsg, formatSsgAudit } from "@pyreon/compiler"
+
+console.log(formatSsgAudit(auditSsg(".")))`,
+      seeAlso: ['auditSsg'],
+    },
+    {
+      name: 'transformDeferInline',
+      kind: 'function',
+      signature:
+        'transformDeferInline(code: string, filename?: string): DeferInlineResult',
+      summary:
+        'Standalone pre-pass that inlines `<Defer>` namespace-import boundaries. Fast-paths out entirely when the source contains no `Defer` mention (no parse). Returns `{ code, changed, warnings }`; runs before the JSX transform in the Vite plugin chain.',
+      example: `import { transformDeferInline } from "@pyreon/compiler"
+
+const { code, changed } = transformDeferInline(src, "page.tsx")`,
+    },
+    {
+      name: 'generateContext',
+      kind: 'function',
+      signature: 'generateContext(cwd: string): ProjectContext',
+      summary:
+        'Project scanner — walks the source tree and produces a structured `ProjectContext` (routes, islands, components) that `@pyreon/vite-plugin` regenerates into `.pyreon/context.json` for AI agents. Syntactic only; no type-check / bundle.',
+      example: `import { generateContext } from "@pyreon/compiler"
+
+const ctx = generateContext(process.cwd())
+console.log(ctx.routes.length, ctx.islands.length)`,
+    },
+  ],
+  gotchas: [
+    {
+      label: 'Dual backend',
+      note: 'Reverting `src/jsx.ts` (the JS path) is INVISIBLE to anything that goes through the native binary — the Rust path in `native/src/lib.rs` is a parallel implementation, kept byte-identical by the cross-backend equivalence tests. Edits to transform behavior must land in BOTH; the equivalence suite is the gate.',
+    },
+    {
+      label: 'Reactivity-Lens is editor-only',
+      note: '`analyzeReactivity` / `formatReactivityLens` are authoring-time tools (LSP inlay hints via `@pyreon/lint --lsp`, CLI debug). They are NOT consumed at production bundle time and force the JS backend — they never affect emitted code (`reactivityLens` is an additive, byte-neutral sidecar).',
+    },
+    {
+      label: 'Detectors are not codemods',
+      note: '`detectPyreonPatterns` always reports `fixable: false` (enforced invariant). `detectReactPatterns` is paired with the real `migrateReactCode` codemod; the Pyreon detector has no companion codemod yet, so consumers must not wire auto-fix UX off its `fixable` flag.',
+    },
+  ],
+})

package/src/pyreon-intercept.ts

@@ -14,6 +14,12 @@
  *                       the component signature; reading is captured once
  *                       and loses reactivity. Access `props.foo` instead
  *                       or use `splitProps(props, [...])`.
+ *  - `props-destructured-body` — `const { foo } = props` written
+ *                       SYNCHRONOUSLY in a component body — the body-scope
+ *                       companion to `props-destructured`. Same capture-
+ *                       once death; nested-function destructures (handler
+ *                       / effect / returned accessor) are NOT flagged
+ *                       (they re-read `props` per invocation).
  *  - `process-dev-gate` — `typeof process !== 'undefined' &&
  *                       process.env.NODE_ENV !== 'production'` is dead
  *                       code in real Vite browser bundles. Use
@@ -80,6 +86,7 @@ export type PyreonDiagnosticCode =
   | 'for-missing-by'
   | 'for-with-key'
   | 'props-destructured'
+  | 'props-destructured-body'
   | 'process-dev-gate'
   | 'empty-theme'
   | 'raw-add-event-listener'
@@ -90,6 +97,7 @@ export type PyreonDiagnosticCode =
   | 'static-return-null-conditional'
   | 'as-unknown-as-vnodechild'
   | 'island-never-with-registry-entry'
+  | 'query-options-as-function'
 
 export interface PyreonDiagnostic {
   /** Machine-readable code for filtering + programmatic handling */
@@ -285,6 +293,110 @@ function detectPropsDestructured(
   )
 }
 
+// ═══════════════════════════════════════════════════════════════════════════════
+// Pattern: body-scope `const { x } = props` destructure
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Strip the wrappers that can sit between `=` and the props identifier
+ * (`const { x } = (props as Props)!`) so we can compare the base
+ * expression's identity to the component's first-parameter name.
+ */
+function unwrapInitializer(expr: ts.Expression): ts.Expression {
+  let cur = expr
+  let prev: ts.Expression | undefined
+  while (cur !== prev) {
+    prev = cur
+    if (ts.isParenthesizedExpression(cur)) cur = cur.expression
+    else if (ts.isAsExpression(cur)) cur = cur.expression
+    else if (ts.isSatisfiesExpression(cur)) cur = cur.expression
+    else if (ts.isNonNullExpression(cur)) cur = cur.expression
+  }
+  return cur
+}
+
+/**
+ * Body-scope companion to {@link detectPropsDestructured}. Flags
+ * `const { x } = props` (also `let` / `var`, aliases, defaults, rest,
+ * nested patterns) written SYNCHRONOUSLY in a component's body.
+ *
+ * Why this is the footgun: the compiler emits `<C prop={sig()} />` as a
+ * getter-shaped reactive prop. `const { x } = props` fires that getter
+ * exactly ONCE at setup — `x` is a dead snapshot, never re-reads when
+ * the signal changes. `props.x` (live member access inside a tracking
+ * scope) or `splitProps(props, ['x'])` preserve the subscription.
+ *
+ * Precision (zero false positives is the priority — a missed body-scope
+ * destructure is acceptable, a wrong one is not):
+ *  - Only PascalCase, JSX-rendering functions (`isComponentShapedFunction`
+ *    + `containsJsx`) — a plain helper that happens to destructure an
+ *    options bag named `props` is NOT a component and is left alone.
+ *  - The initializer must be the bare first-parameter identifier
+ *    (`= props`), unwrapped through paren / `as` / `satisfies` / `!`.
+ *    `const { x } = props.nested` and `= someOtherObject` are NOT
+ *    flagged (rarer shapes; out of the canonical scope).
+ *  - The destructure must be at the component-body top scope. A nested
+ *    function boundary (`onClick` handler, `effect(() => …)`, a returned
+ *    reactive accessor) re-reads `props` on each invocation, so those
+ *    destructures are reactivity-correct — the walk does NOT descend
+ *    into nested functions.
+ *  - The first parameter must itself be a plain identifier; the
+ *    parameter-destructure shape (`({ x }) => …`) is the existing
+ *    `detectPropsDestructured`'s job, not this one.
+ */
+function detectPropsDestructuredBody(
+  ctx: DetectContext,
+  node: ts.ArrowFunction | ts.FunctionDeclaration | ts.FunctionExpression,
+): void {
+  if (!isComponentShapedFunction(node)) return
+  if (!containsJsx(node)) return
+  if (!node.parameters.length) return
+  const first = node.parameters[0]
+  // First param must be a plain identifier — the destructured-param
+  // shape is detectPropsDestructured's domain.
+  if (!first || !ts.isIdentifier(first.name)) return
+  const paramName = first.name.text
+  const body = node.body
+  if (!body || !ts.isBlock(body)) return
+
+  function walk(n: ts.Node): void {
+    // Do NOT descend into nested functions: a `const { x } = props`
+    // inside a handler / effect / returned accessor re-reads on every
+    // invocation and is reactivity-correct.
+    if (
+      ts.isArrowFunction(n) ||
+      ts.isFunctionExpression(n) ||
+      ts.isFunctionDeclaration(n) ||
+      ts.isMethodDeclaration(n) ||
+      ts.isGetAccessorDeclaration(n) ||
+      ts.isSetAccessorDeclaration(n)
+    ) {
+      return
+    }
+    if (
+      ts.isVariableDeclaration(n) &&
+      ts.isObjectBindingPattern(n.name) &&
+      n.name.elements.length > 0 &&
+      n.initializer
+    ) {
+      const base = unwrapInitializer(n.initializer)
+      if (ts.isIdentifier(base) && base.text === paramName) {
+        pushDiag(
+          ctx,
+          n,
+          'props-destructured-body',
+          `Destructuring \`${paramName}\` in the component body captures the values ONCE during setup — the compiler emits signal-driven props as getters, so the destructured locals are dead snapshots that never update when the parent rewrites them. Read \`${paramName}.x\` directly inside the reactive scope (JSX / effect / computed), or use \`splitProps(${paramName}, ['x', ...])\` to carve out a group while preserving reactivity.`,
+          getNodeText(ctx, n),
+          `// read ${paramName}.x directly, or: const [local] = splitProps(${paramName}, ['x'])`,
+          false,
+        )
+      }
+    }
+    ts.forEachChild(n, walk)
+  }
+  for (const stmt of body.statements) walk(stmt)
+}
+
 // ═══════════════════════════════════════════════════════════════════════════════
 // Pattern: typeof process !== 'undefined' && process.env.NODE_ENV !== 'production'
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -362,6 +474,48 @@ function detectEmptyTheme(ctx: DetectContext, node: ts.CallExpression): void {
   )
 }
 
+// ═══════════════════════════════════════════════════════════════════════════════
+// Pattern: @pyreon/query hook options passed as an object literal
+// ═══════════════════════════════════════════════════════════════════════════════
+
+// `useQuery` / `useInfiniteQuery` / `useQueries` / `useSuspenseQuery` take
+// options as a FUNCTION so `queryKey` (etc.) can read Pyreon signals —
+// changing a tracked signal re-runs the options and refetches. An object
+// LITERAL is evaluated once at call time, so the query never reacts to
+// signal changes. `useMutation` is deliberately NOT flagged: its options
+// are a plain object (mutations are imperative, no tracking).
+const QUERY_OPTS_HOOKS = new Set([
+  'useQuery',
+  'useInfiniteQuery',
+  'useQueries',
+  'useSuspenseQuery',
+])
+
+function detectQueryOptionsAsFunction(
+  ctx: DetectContext,
+  node: ts.CallExpression,
+): void {
+  if (!ts.isIdentifier(node.expression)) return
+  const hook = node.expression.text
+  if (!QUERY_OPTS_HOOKS.has(hook)) return
+  const arg0 = node.arguments[0]
+  // Only the unambiguous object-literal-first-arg shape. An identifier /
+  // call / function arg can't be statically proven wrong — stay silent.
+  if (!arg0 || !ts.isObjectLiteralExpression(arg0)) return
+
+  const objText = getNodeText(ctx, arg0)
+  pushDiag(
+    ctx,
+    node,
+    'query-options-as-function',
+    `\`${hook}\` takes options as a FUNCTION so \`queryKey\` can read signals and refetch reactively — an object literal is captured once and never reacts. Wrap it: \`${hook}(() => (...))\`.`,
+    getNodeText(ctx, node),
+    `${hook}(() => (${objText}))`,
+    // No `migrate_pyreon` tool yet — claiming fixable would mislead.
+    false,
+  )
+}
+
 // ═══════════════════════════════════════════════════════════════════════════════
 // Pattern: raw addEventListener / removeEventListener
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -780,6 +934,7 @@ function visitNode(ctx: DetectContext, node: ts.Node): void {
     ts.isFunctionExpression(node)
   ) {
     detectPropsDestructured(ctx, node)
+    detectPropsDestructuredBody(ctx, node)
     detectStaticReturnNullConditional(ctx, node)
   }
   if (ts.isBinaryExpression(node)) {
@@ -794,6 +949,7 @@ function visitNode(ctx: DetectContext, node: ts.Node): void {
     detectRawEventListener(ctx, node)
     detectSignalWriteAsCall(ctx, node)
     detectIslandNeverWithRegistry(ctx, node)
+    detectQueryOptionsAsFunction(ctx, node)
   }
   if (ts.isJsxAttribute(node)) {
     detectOnClickUndefined(ctx, node)
@@ -839,12 +995,20 @@ export function hasPyreonPatterns(code: string): boolean {
     (/\bDate\.now\s*\(/.test(code) && /\bMath\.random\s*\(/.test(code)) ||
     /on[A-Z]\w*\s*=\s*\{\s*undefined\s*\}/.test(code) ||
     /=\s*\(\s*\{[^}]+\}\s*[:)]/.test(code) ||
+    // props-destructured-body: `const { … } = <ident>` anywhere. Loose
+    // on purpose — the AST walker is the precise gate; this only has to
+    // avoid skipping the full walk.
+    /\b(?:const|let|var)\s+\{[^}]*\}\s*=\s*[A-Za-z_$]/.test(code) ||
     // signal-write-as-call: `const X = signal(` declaration anywhere
     /\b(?:signal|computed)\s*[<(]/.test(code) ||
     // static-return-null-conditional: `if (...) return null` anywhere
     /\bif\s*\([^)]+\)\s*\{?\s*return\s+null\b/.test(code) ||
     // as-unknown-as-vnodechild
     /\bas\s+unknown\s+as\s+VNodeChild\b/.test(code) ||
+    // query-options-as-function: a query hook called with an object literal
+    /\b(?:useQuery|useInfiniteQuery|useQueries|useSuspenseQuery)\s*\(\s*\{/.test(
+      code,
+    ) ||
     // island-never-with-registry-entry: a never-strategy declaration AND a
     // hydrateIslands call must both appear in the same source for the bug
     // shape to trigger. Pre-filter on EITHER half — the AST walker fast-

package/src/react-intercept.ts

@@ -181,6 +181,55 @@ interface DetectContext {
   code: string
   diagnostics: ReactDiagnostic[]
   reactImportedHooks: Set<string>
+  /**
+   * Identifiers bound to a signal factory (`const x = signal(...)` /
+   * `computed(...)` / `useSignal(...)` / `createSignal(...)`) anywhere in the
+   * file. Only `const` declarations are tracked — `let`/`var` may be
+   * reassigned to a non-signal value, so a `.value` write through them
+   * wouldn't be a reliable signal-write. The collection is scope-blind for
+   * the same reason `collectSignalBindings` in `pyreon-intercept.ts` is — the
+   * rare shadow-a-signal-name case is acceptable noise; the precision win is
+   * eliminating the `input.value = ''` / `cell.value = x` / `o.value = y`
+   * false-positive class entirely.
+   */
+  signalBindings: Set<string>
+}
+
+/**
+ * Collects every identifier bound to a signal factory call. Mirrors
+ * `pyreon-intercept.ts:collectSignalBindings` but also recognises the
+ * `useSignal` / `createSignal` aliases (Solid / hook-style) so the React
+ * detector — which runs on cross-framework migration input — doesn't miss a
+ * genuine `mySignal.value = x` written by someone coming from Solid/Vue.
+ */
+function collectDetectSignalBindings(sf: ts.SourceFile): Set<string> {
+  const names = new Set<string>()
+  function isSignalFactoryCall(init: ts.Expression | undefined): boolean {
+    if (!init || !ts.isCallExpression(init)) return false
+    const callee = init.expression
+    if (!ts.isIdentifier(callee)) return false
+    return (
+      callee.text === 'signal' ||
+      callee.text === 'computed' ||
+      callee.text === 'useSignal' ||
+      callee.text === 'createSignal'
+    )
+  }
+  function walk(node: ts.Node): void {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+      const list = node.parent
+      if (
+        ts.isVariableDeclarationList(list) &&
+        (list.flags & ts.NodeFlags.Const) !== 0 &&
+        isSignalFactoryCall(node.initializer)
+      ) {
+        names.add(node.name.text)
+      }
+    }
+    ts.forEachChild(node, walk)
+  }
+  walk(sf)
+  return names
 }
 
 function detectGetNodeText(ctx: DetectContext, node: ts.Node): string {
@@ -497,6 +546,15 @@ function detectJsxAttributes(ctx: DetectContext, node: ts.JsxAttribute): void {
 
 function detectDotValueSignal(ctx: DetectContext, node: ts.PropertyAccessExpression): void {
   const varName = (node.expression as ts.Identifier).text
+  // Precision gate: only flag `X.value = …` when X is actually a tracked
+  // signal binding. Without this, the detector false-positived on every
+  // DOM-element / data-object `.value` write — `input.value = ''`,
+  // `cell.value = x`, `o.value = y`, `ref.current.value = z` (the receiver
+  // there is the `.current` PropertyAccess, already excluded by
+  // `isDotValueAccess` requiring an Identifier receiver). Require positive
+  // evidence the receiver is a `const X = signal(...)` / `computed(...)` /
+  // `useSignal(...)` / `createSignal(...)` binding before emitting.
+  if (!ctx.signalBindings.has(varName)) return
   const parent = node.parent
   if (ts.isBinaryExpression(parent) && parent.left === node) {
     detectDiag(
@@ -598,6 +656,7 @@ export function detectReactPatterns(code: string, filename = 'input.tsx'): React
     code,
     diagnostics: [],
     reactImportedHooks: new Set<string>(),
+    signalBindings: collectDetectSignalBindings(sf),
   }
 
   detectVisit(ctx, sf)