@pyreon/compiler 0.16.0 → 0.19.0

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)

package/src/reactivity-lens.ts

@@ -0,0 +1,190 @@
+/**
+ * Reactivity Lens — surface the compiler's already-computed reactivity
+ * analysis back to the author at the source.
+ *
+ * Pyreon's #1 silent footgun class: whether code is reactive is invisible at
+ * the moment you write it. `const {x}=props` compiles fine, types fine,
+ * renders once, and is dead. `<div>{x}</div>` where `x` isn't a signal bakes
+ * once. The `@pyreon/compiler` ALREADY decides this per-expression (it has to,
+ * for codegen) and then throws the analysis away. This module pipes it back.
+ *
+ * `analyzeReactivity()` is the single entry point. It returns a sorted list of
+ * {@link ReactivityFinding}s built from TWO faithful sources, neither of which
+ * is a fresh approximation:
+ *
+ *  1. **Compiler structural facts** — `TransformResult.reactivityLens`. Each
+ *     span is a *record* of a codegen decision (`_bind`/`_bindText`/`_rp`/
+ *     hoist/static-text). The positive "this is live" claim is the codegen
+ *     branch itself, so it is correct by construction (drift-gated).
+ *  2. **Footgun negatives** — the existing `detectPyreonPatterns` AST
+ *     detectors (`props-destructured`, `signal-write-as-call`, …). Already
+ *     shipped, already AST-based; the lens just unifies them under one
+ *     editor-facing taxonomy.
+ *
+ * Absence of a finding is "not asserted", NEVER an implicit static claim —
+ * see the asymmetric-precision commitment in `.claude/plans/reactivity-lens.md`.
+ *
+ * JS-backend only (Phase 1). The native Rust binary emits byte-identical
+ * codegen (527 cross-backend equivalence tests), so the JS path is a sound
+ * oracle for the analysis; Rust-path parity is Phase 3.
+ *
+ * @module
+ */
+
+import { transformJSX_JS } from './jsx'
+import type { ReactivityKind, ReactivitySpan } from './jsx'
+import { detectPyreonPatterns } from './pyreon-intercept'
+import type { PyreonDiagnosticCode } from './pyreon-intercept'
+
+export type { ReactivityKind, ReactivitySpan } from './jsx'
+
+/** A footgun finding adds `'footgun'` to the structural codegen kinds. */
+export type ReactivityFindingKind = ReactivityKind | 'footgun'
+
+export interface ReactivityFinding {
+  /** Structural codegen decision, or `'footgun'` for a detected anti-pattern. */
+  kind: ReactivityFindingKind
+  /** 1-based line. */
+  line: number
+  /** 0-based column. */
+  column: number
+  /** 1-based end line. */
+  endLine: number
+  /** 0-based end column. */
+  endColumn: number
+  /** Editor-facing one-liner. For footguns, the detector's message. */
+  detail: string
+  /**
+   * For `'footgun'` findings: the static-detector code (e.g.
+   * `props-destructured`) so the editor surface can deep-link the
+   * anti-pattern catalogue. Absent for structural findings.
+   */
+  code?: PyreonDiagnosticCode
+  /** For `'footgun'` findings: whether a mechanical auto-fix is safe. */
+  fixable?: boolean
+}
+
+export interface AnalyzeReactivityResult {
+  /** Sorted (line, column) findings — structural facts + footguns merged. */
+  findings: ReactivityFinding[]
+  /**
+   * Raw compiler spans (pre-merge), kept so the drift gate can assert the
+   * lens kind faithfully records the codegen decision without re-deriving.
+   */
+  spans: ReactivitySpan[]
+}
+
+function spanToFinding(s: ReactivitySpan): ReactivityFinding {
+  return {
+    kind: s.kind,
+    line: s.line,
+    column: s.column,
+    endLine: s.endLine,
+    endColumn: s.endColumn,
+    detail: s.detail,
+  }
+}
+
+/**
+ * Analyze a source file's reactivity. Pure, side-effect-free, deterministic.
+ *
+ * @param code      Source text (`.tsx` / `.jsx` / `.ts`).
+ * @param filename  Used only for parse-mode (`tsx` vs `jsx`) detection.
+ * @param options   `knownSignals` is forwarded to the compiler so
+ *                   cross-module imported signals are auto-call-aware.
+ *
+ * @example
+ * const { findings } = analyzeReactivity(
+ *   `function C(){ const {x}=props; return <div>{count()}</div> }`,
+ * )
+ * // → footgun(props-destructured) on `{x}`, reactive on `count()`
+ */
+export function analyzeReactivity(
+  code: string,
+  filename = 'input.tsx',
+  options: { knownSignals?: string[] } = {},
+): AnalyzeReactivityResult {
+  let spans: ReactivitySpan[] = []
+  try {
+    const r = transformJSX_JS(code, filename, {
+      reactivityLens: true,
+      ...(options.knownSignals ? { knownSignals: options.knownSignals } : {}),
+    })
+    spans = r.reactivityLens ?? []
+  } catch {
+    // Parse failure → no structural facts. Footguns may still be derivable
+    // (detectPyreonPatterns uses the TS compiler API independently).
+    spans = []
+  }
+
+  const findings: ReactivityFinding[] = spans.map(spanToFinding)
+
+  let footguns: ReturnType<typeof detectPyreonPatterns> = []
+  try {
+    footguns = detectPyreonPatterns(code, filename)
+  } catch {
+    footguns = []
+  }
+  for (const d of footguns) {
+    // detectPyreonPatterns gives 1-based line / 0-based column + `current`
+    // (the offending source text). Approximate the end as same-line +
+    // current length; multi-line `current` is rare and the editor only
+    // needs a reasonable highlight range.
+    const firstLineLen = d.current.split('\n')[0]?.length ?? d.current.length
+    findings.push({
+      kind: 'footgun',
+      line: d.line,
+      column: d.column,
+      endLine: d.line,
+      endColumn: d.column + firstLineLen,
+      detail: d.message,
+      code: d.code,
+      fixable: d.fixable,
+    })
+  }
+
+  findings.sort((a, b) => a.line - b.line || a.column - b.column)
+  return { findings, spans }
+}
+
+const KIND_BADGE: Record<ReactivityFindingKind, string> = {
+  reactive: '◆ live',
+  'reactive-prop': '◆ live prop',
+  'reactive-attr': '◆ live attr',
+  'static-text': '○ baked once',
+  'hoisted-static': '○ hoisted static',
+  footgun: '⚠ footgun',
+}
+
+/**
+ * Render an annotated source view for CLI / debugging — every analyzed line
+ * followed by its reactivity findings. Not the production surface (that's the
+ * LSP inlay hints); this is the spike's "can you see reactivity flow" probe
+ * and a stable diff target for tests.
+ */
+export function formatReactivityLens(
+  code: string,
+  result: AnalyzeReactivityResult,
+): string {
+  const lines = code.split('\n')
+  const byLine = new Map<number, ReactivityFinding[]>()
+  for (const f of result.findings) {
+    const arr = byLine.get(f.line) ?? []
+    arr.push(f)
+    byLine.set(f.line, arr)
+  }
+  const out: string[] = []
+  for (let i = 0; i < lines.length; i++) {
+    const lineNo = i + 1
+    out.push(`${String(lineNo).padStart(4)} | ${lines[i]}`)
+    const fs = byLine.get(lineNo)
+    if (fs) {
+      for (const f of fs) {
+        const pad = ' '.repeat(7 + f.column)
+        const tag = f.code ? ` [${f.code}]` : ''
+        out.push(`${pad}^ ${KIND_BADGE[f.kind]}${tag} — ${f.detail}`)
+      }
+    }
+  }
+  return out.join('\n')
+}