@pyreon/compiler 0.16.0 → 0.19.0

package/src/index.ts

@@ -1,7 +1,20 @@
 // @pyreon/compiler — JSX reactive transform for Pyreon
 
-export type { CompilerWarning, TransformResult } from './jsx'
+export type { DeferInlineResult, DeferInlineWarning } from './defer-inline'
+export { transformDeferInline } from './defer-inline'
+export type {
+  CompilerWarning,
+  ReactivityKind,
+  ReactivitySpan,
+  TransformResult,
+} from './jsx'
 export { transformJSX, transformJSX_JS } from './jsx'
+export type {
+  AnalyzeReactivityResult,
+  ReactivityFinding,
+  ReactivityFindingKind,
+} from './reactivity-lens'
+export { analyzeReactivity, formatReactivityLens } from './reactivity-lens'
 export type { ComponentInfo, IslandInfo, ProjectContext, RouteInfo } from './project-scanner'
 export { generateContext } from './project-scanner'
 export type {

package/src/jsx.ts

@@ -39,7 +39,13 @@ import { loadNativeBinding } from './load-native'
 // environment, WASM runtime like StackBlitz, missing per-platform package).
 //
 // See `load-native.ts` for the resolution logic.
-type NativeTransformFn = (code: string, filename: string, ssr: boolean, knownSignals: string[] | null) => TransformResult
+type NativeTransformFn = (
+  code: string,
+  filename: string,
+  ssr: boolean,
+  knownSignals: string[] | null,
+  reactivityLens: boolean,
+) => TransformResult
 const nativeBinding = loadNativeBinding(import.meta.url)
 const nativeTransformJsx: NativeTransformFn | null = nativeBinding
   ? (nativeBinding.transformJsx as NativeTransformFn)
@@ -60,6 +66,41 @@ export interface CompilerWarning {
     | 'circular-prop-derived'
 }
 
+/**
+ * Reactivity-lens kinds. Each is a RECORD of a codegen decision the compiler
+ * already made — never an approximation. Positive claims (`reactive*`) are
+ * emitted ONLY where the compiler provably wrapped/tracked the span; absence
+ * of a span is "not asserted", never an implicit static claim. `static-text`
+ * is the high-precision negative: the literal `else` branch of the
+ * reactive-vs-static text decision (the "this `{x}` is baked once / dead"
+ * footgun signal when the author expected reactivity).
+ */
+export type ReactivityKind =
+  | 'reactive' // expression re-evaluates on signal change (_bind/_bindText/`() =>` wrap)
+  | 'reactive-prop' // component prop tracked into the child (_rp(() => …))
+  | 'reactive-attr' // DOM attribute re-applied on signal change
+  | 'static-text' // text expression baked once into the DOM, never re-renders
+  | 'hoisted-static' // JSX hoisted to module scope, never re-evaluated
+
+export interface ReactivitySpan {
+  /** Source byte offset (start) of the spanned expression in the INPUT. */
+  start: number
+  /** Source byte offset (end). */
+  end: number
+  /** 1-based start line. */
+  line: number
+  /** 0-based start column. */
+  column: number
+  /** 1-based end line. */
+  endLine: number
+  /** 0-based end column. */
+  endColumn: number
+  /** Which codegen decision this span records. */
+  kind: ReactivityKind
+  /** Human-readable, editor-facing one-liner explaining the decision. */
+  detail: string
+}
+
 export interface TransformResult {
   /** Transformed source code (JSX preserved, only expression containers modified) */
   code: string
@@ -67,6 +108,13 @@ export interface TransformResult {
   usesTemplates?: boolean
   /** Compiler warnings for common mistakes */
   warnings: CompilerWarning[]
+  /**
+   * Reactivity-lens spans — populated ONLY when `TransformOptions.reactivityLens`
+   * is `true`. Additive: codegen output is byte-identical whether or not this is
+   * collected. Each span is a faithful record of a reactivity decision the
+   * compiler made for that source range. See {@link ReactivitySpan}.
+   */
+  reactivityLens?: ReactivitySpan[]
 }
 
 // Props that should never be wrapped in a reactive getter
@@ -103,6 +151,15 @@ export interface TransformOptions {
    * // {count} in JSX → {() => count()}
    */
   knownSignals?: string[]
+
+  /**
+   * Collect the {@link ReactivitySpan} sidecar (`TransformResult.reactivityLens`).
+   * Default `false`. Purely additive — the emitted `code` is byte-identical
+   * whether this is on or off (asserted by the compiler equivalence tests).
+   * The lens records reactivity decisions the compiler ALREADY makes for
+   * codegen; it never runs a second analysis pass.
+   */
+  reactivityLens?: boolean
 }
 
 // ─── oxc ESTree helpers ───────────────────────────────────────────────────────
@@ -189,7 +246,13 @@ export function transformJSX(
   // of crashing the Vite dev server.
   if (nativeTransformJsx) {
     try {
-      return nativeTransformJsx(code, filename, options.ssr === true, options.knownSignals ?? null)
+      return nativeTransformJsx(
+        code,
+        filename,
+        options.ssr === true,
+        options.knownSignals ?? null,
+        options.reactivityLens === true,
+      )
     } catch {
       // Native transform failed — fall through to JS implementation
     }
@@ -227,6 +290,25 @@ export function transformJSX_JS(
     warnings.push({ message, line, column, code: warnCode })
   }
 
+  // ── Reactivity lens (opt-in, additive — never affects `result`) ───────────
+  const collectLens = options.reactivityLens === true
+  const reactivityLens: ReactivitySpan[] = []
+  function lens(start: number, end: number, kind: ReactivityKind, detail: string): void {
+    if (!collectLens) return
+    const a = locate(start)
+    const b = locate(end)
+    reactivityLens.push({
+      start,
+      end,
+      line: a.line,
+      column: a.column,
+      endLine: b.line,
+      endColumn: b.column,
+      kind,
+      detail,
+    })
+  }
+
   // ── Parent + children maps (built once, eliminates repeated Object.keys) ──
   const parentMap = new WeakMap<object, N>()
   const childrenMap = new WeakMap<object, N[]>()
@@ -273,6 +355,7 @@ export function transformJSX_JS(
   let hoistIdx = 0
   let needsTplImport = false
   let needsRpImport = false
+  let needsWrapSpreadImport = false
   let needsBindTextImportGlobal = false
   let needsBindDirectImportGlobal = false
   let needsBindImportGlobal = false
@@ -287,6 +370,12 @@ export function transformJSX_JS(
       const name = `_$h${hoistIdx++}`
       const text = code.slice(node.start as number, node.end as number)
       hoists.push({ name, text })
+      lens(
+        node.start as number,
+        node.end as number,
+        'hoisted-static',
+        'static — hoisted once to module scope, never re-evaluated',
+      )
       return name
     }
     return null
@@ -300,6 +389,7 @@ export function transformJSX_JS(
       ? `() => (${sliced})`
       : `() => ${sliced}`
     replacements.push({ start, end, text })
+    lens(start, end, 'reactive', 'live — re-evaluates whenever its signals change')
   }
 
   function hoistOrWrap(expr: N): void {
@@ -344,6 +434,46 @@ export function transformJSX_JS(
     }
   }
 
+  /**
+   * Wrap component-JSX spread arguments with `_wrapSpread(...)` so
+   * getter-shaped reactive props survive esbuild's JS-level spread emit.
+   *
+   * esbuild compiles `<Comp {...source}>` to `jsx(Comp, { ...source })`.
+   * The JS spread fires every getter on `source` and stores the resolved
+   * values — collapsing compiler-emitted reactive props (`_rp` thunks
+   * later converted to getters by `makeReactiveProps`) to static values
+   * before the receiving component sees them.
+   *
+   * `_wrapSpread` replaces getter descriptors with `_rp`-branded thunks,
+   * so the JS-level spread carries function values instead. The runtime
+   * `makeReactiveProps` step converts them back to getters on the
+   * component's props object — preserving the live signal subscription.
+   *
+   * Lowercase tags (DOM elements) go through the template path's
+   * `_applyProps` which already handles spread reactively — no need to
+   * wrap there.
+   */
+  function handleJsxSpreadAttribute(attr: N, parentElement: N): void {
+    const tagName = jsxTagName(parentElement)
+    const isComponent =
+      tagName.length > 0 && tagName.charAt(0) !== tagName.charAt(0).toLowerCase()
+    if (!isComponent) return
+    const arg = attr.argument
+    if (!arg) return
+    // Skip already-wrapped sources (idempotent compilation guard).
+    if (
+      arg.type === 'CallExpression' &&
+      arg.callee?.type === 'Identifier' &&
+      arg.callee.name === '_wrapSpread'
+    )
+      return
+    const start = arg.start as number
+    const end = arg.end as number
+    const sliced = sliceExpr(arg)
+    replacements.push({ start, end, text: `_wrapSpread(${sliced})` })
+    needsWrapSpreadImport = true
+  }
+
   function handleJsxAttribute(node: N, parentElement: N): void {
     const name = node.name?.type === 'JSXIdentifier' ? node.name.name : ''
     if (SKIP_PROPS.has(name) || EVENT_RE.test(name)) return
@@ -370,6 +500,7 @@ export function transformJSX_JS(
         const inner = expr.type === 'ObjectExpression' ? `(${sliced})` : sliced
         replacements.push({ start, end, text: `_rp(() => ${inner})` })
         needsRpImport = true
+        lens(start, end, 'reactive-prop', 'live prop — signal reads here are tracked into the component')
       }
     } else {
       hoistOrWrap(expr)
@@ -733,6 +864,7 @@ export function transformJSX_JS(
       checkForWarnings(node)
       for (const attr of jsxAttrs(node)) {
         if (attr.type === 'JSXAttribute') handleJsxAttribute(attr, node)
+        else if (attr.type === 'JSXSpreadAttribute') handleJsxSpreadAttribute(attr, node)
       }
       for (const child of jsxChildren(node)) {
         if (child.type === 'JSXExpressionContainer') handleJsxExpression(child)
@@ -761,7 +893,9 @@ export function transformJSX_JS(
 
   walkNode(program)
 
-  if (replacements.length === 0 && hoists.length === 0) return { code, warnings }
+  if (replacements.length === 0 && hoists.length === 0) {
+    return collectLens ? { code, warnings, reactivityLens } : { code, warnings }
+  }
 
   replacements.sort((a, b) => a.start - b.start)
   const outParts: string[] = []
@@ -793,11 +927,16 @@ export function transformJSX_JS(
       output
   }
 
-  if (needsRpImport) {
-    output = `import { _rp } from "@pyreon/core";\n` + output
+  if (needsRpImport || needsWrapSpreadImport) {
+    const coreImports: string[] = []
+    if (needsRpImport) coreImports.push('_rp')
+    if (needsWrapSpreadImport) coreImports.push('_wrapSpread')
+    output = `import { ${coreImports.join(', ')} } from "@pyreon/core";\n` + output
   }
 
-  return { code: output, usesTemplates: needsTplImport, warnings }
+  return collectLens
+    ? { code: output, usesTemplates: needsTplImport, warnings, reactivityLens }
+    : { code: output, usesTemplates: needsTplImport, warnings }
 
   // ── Template emission helpers ─────────────────────────────────────────────
 
@@ -972,6 +1111,12 @@ export function transformJSX_JS(
         bindLines.push(attrSetter(htmlAttrName, varName, expr))
         return
       }
+      lens(
+        exprNode.start as number,
+        exprNode.end as number,
+        'reactive-attr',
+        `live attribute — \`${htmlAttrName}\` re-applies whenever its signals change`,
+      )
       const directRef = tryDirectSignalRef(exprNode)
       if (directRef) {
         needsBindDirectImport = true
@@ -1176,9 +1321,22 @@ export function transformJSX_JS(
         bindLines.push(`const ${d} = _mountSlot(${expr}, ${parentRef}, ${placeholder})`)
         return '<!>'
       }
+      const cx = child.expression
       if (isReactive) {
+        lens(
+          cx.start as number,
+          cx.end as number,
+          'reactive',
+          'live — this text re-renders whenever its signals change',
+        )
         return emitReactiveTextChild(expr, child.expression, varName, parentRef, childNodeIdx, needsPlaceholder)
       }
+      lens(
+        cx.start as number,
+        cx.end as number,
+        'static-text',
+        'baked once into the DOM — never re-renders (no signal read here)',
+      )
       return emitStaticTextChild(expr, varName, parentRef, childNodeIdx, needsPlaceholder)
     }
 

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.',
+    },
+  ],
+})