@pyreon/compiler 0.18.0 → 0.19.0

package/lib/types/index.d.ts

@@ -5,41 +5,44 @@
  * Rewrites:
  *
  *     import { Modal } from './Modal'
- *     <Defer when={open()}><Modal /></Defer>
+ *     <Defer when={open()}><Modal title="hi" /></Defer>
  *
  * into:
  *
- *     <Defer when={open()} chunk={() => import('./Modal').then(m => ({ default: m.Modal }))}>
- *       {C => <C />}
+ *     <Defer when={open()} chunk={() => import('./Modal').then((__m) => ({ default: __m.Modal }))}>
+ *       {(__C) => <__C title="hi" />}
  *     </Defer>
  *
  * The static `import { Modal } from './Modal'` is removed when `Modal` is
  * referenced ONLY inside the Defer subtree — otherwise Rolldown would
  * bundle the module statically and the dynamic import becomes a no-op.
  *
- * Scope of v1 (this file):
- *   - Single Defer element per file (no nested handling — bail otherwise).
- *   - Children: exactly ONE JSXElement, self-closing, capitalised name
- *     (component reference), no props. Props or multiple children → leave
- *     the Defer untransformed (user must use the explicit `chunk` form).
- *   - Imports: named OR default. Namespace imports (`import * as Mod`)
- *     and destructured-renamed (`{ X as Y }`) not handled in v1.
+ * Scope (v2 — post #587 + this PR):
+ *   - Multiple Defer elements per file: each rewritten independently.
+ *   - Children: exactly ONE JSXElement, capitalised name (component
+ *     reference). Self-closing OR with children. **Props ARE allowed**
+ *     (post-v2) and pass through unchanged into the render-prop body —
+ *     closure capture works naturally because the render-prop arrow
+ *     captures the surrounding lexical scope.
+ *   - Multiple non-whitespace children → bail with a warning.
+ *     User must use the explicit `chunk` form with a render-prop.
+ *   - Imports: default, named, **renamed** (`{ X as Y }`). Namespace
+ *     imports (`* as M` + `<M.X />`) NOT supported — bail with a warning.
+ *   - **Multi-specifier imports** (`{ A, B } from './x'`): only the
+ *     binding used in Defer is removed; siblings stay intact.
  *   - Triggers (`when={...}`, `on="visible"`, `on="idle"`) pass through.
  *   - Other props on `<Defer>` (e.g. `fallback`) pass through.
  *
  * The transform is intentionally conservative — anything unusual leaves
- * the source unchanged + emits a warning. v2 follow-ups can relax these
- * constraints with closure-capture handling, namespace imports, etc.
- *
- * Pipeline: this runs BEFORE `transformJSX()` in the vite plugin. The
- * output is still JSX — `transformJSX` then converts it to `h()` /
- * `_tpl()` calls as usual.
+ * the source unchanged + emits a warning. Pipeline: runs BEFORE
+ * `transformJSX()` in the vite plugin. The output is still JSX —
+ * `transformJSX` then converts to runtime calls as usual.
  */
 interface DeferInlineWarning {
   message: string;
   line: number;
   column: number;
-  code: 'defer-inline/multiple-children' | 'defer-inline/non-component-child' | 'defer-inline/child-has-props' | 'defer-inline/import-not-found' | 'defer-inline/import-used-elsewhere' | 'defer-inline/unsupported-import-shape';
+  code: 'defer-inline/multiple-children' | 'defer-inline/non-component-child' | 'defer-inline/import-not-found' | 'defer-inline/import-used-elsewhere' | 'defer-inline/unsupported-import-shape';
 }
 interface DeferInlineResult {
   /** Transformed source — same as input when no transform applied. */
@@ -49,23 +52,6 @@ interface DeferInlineResult {
   /** Soft warnings for cases the transform deliberately skipped. */
   warnings: DeferInlineWarning[];
 }
-/**
- * Main entry. Returns the (possibly transformed) source plus the list
- * of warnings for cases the transform deliberately skipped.
- *
- * Bails (returns input unchanged with `changed: false`) when:
- *   - No `<Defer>` JSX element appears in the file (fast path).
- *   - The file fails to parse (syntax error — let downstream handle).
- *   - No `<Defer>` matches the inline-eligible shape.
- *
- * Per-Defer skips with a warning:
- *   - Multiple children → user must use render-prop form
- *   - Child has props → user must use render-prop form
- *   - Child name isn't imported → can't resolve the chunk source
- *   - Child binding is used outside the Defer subtree → can't remove
- *     the static import (dynamic import would be a no-op via Rolldown's
- *     same-module dedup)
- */
 declare function transformDeferInline(code: string, filename?: string): DeferInlineResult;
 //#endregion
 //#region src/jsx.d.ts
@@ -108,6 +94,34 @@ interface CompilerWarning {
   /** Warning code for filtering */
   code: 'signal-call-in-jsx' | 'missing-key-on-for' | 'signal-in-static-prop' | '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).
+ */
+type ReactivityKind = 'reactive' | 'reactive-prop' | 'reactive-attr' | 'static-text' | 'hoisted-static';
+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;
+}
 interface TransformResult {
   /** Transformed source code (JSX preserved, only expression containers modified) */
   code: string;
@@ -115,6 +129,13 @@ 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[];
 }
 interface TransformOptions {
   /**
@@ -136,102 +157,19 @@ 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;
 }
 declare function transformJSX(code: string, filename?: string, options?: TransformOptions): TransformResult;
 /** JS fallback implementation — used when the native binary isn't available. */
 declare function transformJSX_JS(code: string, filename?: string, options?: TransformOptions): TransformResult;
 //#endregion
-//#region src/project-scanner.d.ts
-/**
- * Project scanner — extracts route, component, and island information from source files.
- */
-interface RouteInfo {
-  path: string;
-  name?: string | undefined;
-  component?: string | undefined;
-  hasLoader: boolean;
-  hasGuard: boolean;
-  params: string[];
-}
-interface ComponentInfo {
-  name: string;
-  file: string;
-  hasSignals: boolean;
-  signalNames: string[];
-  props: string[];
-}
-interface IslandInfo {
-  name: string;
-  file: string;
-  hydrate: string;
-}
-interface ProjectContext {
-  framework: 'pyreon';
-  version: string;
-  generatedAt: string;
-  routes: RouteInfo[];
-  components: ComponentInfo[];
-  islands: IslandInfo[];
-}
-declare function generateContext(cwd: string): ProjectContext;
-//#endregion
-//#region src/react-intercept.d.ts
-/**
- * React Pattern Interceptor — detects React/Vue patterns in code and provides
- * structured diagnostics with exact fix suggestions for AI-assisted migration.
- *
- * Two modes:
- *  - `detectReactPatterns(code)` — returns diagnostics only (non-destructive)
- *  - `migrateReactCode(code)` — applies auto-fixes and returns transformed code
- *
- * Designed for three consumers:
- *  1. Compiler pre-pass (warnings during build)
- *  2. CLI `pyreon doctor` (project-wide scanning)
- *  3. MCP server `migrate_react` / `validate` tools (AI agent integration)
- */
-type ReactDiagnosticCode = 'react-import' | 'react-dom-import' | 'react-router-import' | 'use-state' | 'use-effect-mount' | 'use-effect-deps' | 'use-effect-no-deps' | 'use-memo' | 'use-callback' | 'use-ref-dom' | 'use-ref-box' | 'use-reducer' | 'use-layout-effect' | 'memo-wrapper' | 'forward-ref' | 'class-name-prop' | 'html-for-prop' | 'on-change-input' | 'dangerously-set-inner-html' | 'dot-value-signal' | 'array-map-jsx' | 'key-on-for-child' | 'create-context-import' | 'use-context-import';
-interface ReactDiagnostic {
-  /** Machine-readable code for filtering and programmatic handling */
-  code: ReactDiagnosticCode;
-  /** Human-readable message explaining the issue */
-  message: string;
-  /** 1-based line number */
-  line: number;
-  /** 0-based column */
-  column: number;
-  /** The code as written */
-  current: string;
-  /** The suggested Pyreon equivalent */
-  suggested: string;
-  /** Whether migrateReactCode can auto-fix this */
-  fixable: boolean;
-}
-interface MigrationChange {
-  type: 'replace' | 'remove' | 'add';
-  line: number;
-  description: string;
-}
-interface MigrationResult {
-  /** Transformed source code */
-  code: string;
-  /** All detected patterns (including unfixable ones) */
-  diagnostics: ReactDiagnostic[];
-  /** Description of changes applied */
-  changes: MigrationChange[];
-}
-declare function detectReactPatterns(code: string, filename?: string): ReactDiagnostic[];
-declare function migrateReactCode(code: string, filename?: string): MigrationResult;
-/** Fast regex check — returns true if code likely contains React patterns worth analyzing */
-declare function hasReactPatterns(code: string): boolean;
-interface ErrorDiagnosis {
-  cause: string;
-  fix: string;
-  fixCode?: string | undefined;
-  related?: string | undefined;
-}
-/** Diagnose an error message and return structured fix information */
-declare function diagnoseError(error: string): ErrorDiagnosis | null;
-//#endregion
 //#region src/pyreon-intercept.d.ts
 /**
  * Pyreon Pattern Interceptor — detects Pyreon-specific anti-patterns in
@@ -249,6 +187,12 @@ declare function diagnoseError(error: string): ErrorDiagnosis | null;
  *                       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
@@ -304,7 +248,7 @@ declare function diagnoseError(error: string): ErrorDiagnosis | null;
  *  2. CLI `pyreon doctor`
  *  3. MCP server `validate` tool
  */
-type PyreonDiagnosticCode = 'for-missing-by' | 'for-with-key' | 'props-destructured' | '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';
+type PyreonDiagnosticCode = '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' | 'query-options-as-function';
 interface PyreonDiagnostic {
   /** Machine-readable code for filtering + programmatic handling */
   code: PyreonDiagnosticCode;
@@ -325,6 +269,156 @@ declare function detectPyreonPatterns(code: string, filename?: string): PyreonDi
 /** Fast regex pre-filter — returns true if the code is worth a full AST walk. */
 declare function hasPyreonPatterns(code: string): boolean;
 //#endregion
+//#region src/reactivity-lens.d.ts
+/** A footgun finding adds `'footgun'` to the structural codegen kinds. */
+type ReactivityFindingKind = ReactivityKind | 'footgun';
+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;
+}
+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[];
+}
+/**
+ * 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()`
+ */
+declare function analyzeReactivity(code: string, filename?: string, options?: {
+  knownSignals?: string[];
+}): AnalyzeReactivityResult;
+/**
+ * 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.
+ */
+declare function formatReactivityLens(code: string, result: AnalyzeReactivityResult): string;
+//#endregion
+//#region src/project-scanner.d.ts
+/**
+ * Project scanner — extracts route, component, and island information from source files.
+ */
+interface RouteInfo {
+  path: string;
+  name?: string | undefined;
+  component?: string | undefined;
+  hasLoader: boolean;
+  hasGuard: boolean;
+  params: string[];
+}
+interface ComponentInfo {
+  name: string;
+  file: string;
+  hasSignals: boolean;
+  signalNames: string[];
+  props: string[];
+}
+interface IslandInfo {
+  name: string;
+  file: string;
+  hydrate: string;
+}
+interface ProjectContext {
+  framework: 'pyreon';
+  version: string;
+  generatedAt: string;
+  routes: RouteInfo[];
+  components: ComponentInfo[];
+  islands: IslandInfo[];
+}
+declare function generateContext(cwd: string): ProjectContext;
+//#endregion
+//#region src/react-intercept.d.ts
+/**
+ * React Pattern Interceptor — detects React/Vue patterns in code and provides
+ * structured diagnostics with exact fix suggestions for AI-assisted migration.
+ *
+ * Two modes:
+ *  - `detectReactPatterns(code)` — returns diagnostics only (non-destructive)
+ *  - `migrateReactCode(code)` — applies auto-fixes and returns transformed code
+ *
+ * Designed for three consumers:
+ *  1. Compiler pre-pass (warnings during build)
+ *  2. CLI `pyreon doctor` (project-wide scanning)
+ *  3. MCP server `migrate_react` / `validate` tools (AI agent integration)
+ */
+type ReactDiagnosticCode = 'react-import' | 'react-dom-import' | 'react-router-import' | 'use-state' | 'use-effect-mount' | 'use-effect-deps' | 'use-effect-no-deps' | 'use-memo' | 'use-callback' | 'use-ref-dom' | 'use-ref-box' | 'use-reducer' | 'use-layout-effect' | 'memo-wrapper' | 'forward-ref' | 'class-name-prop' | 'html-for-prop' | 'on-change-input' | 'dangerously-set-inner-html' | 'dot-value-signal' | 'array-map-jsx' | 'key-on-for-child' | 'create-context-import' | 'use-context-import';
+interface ReactDiagnostic {
+  /** Machine-readable code for filtering and programmatic handling */
+  code: ReactDiagnosticCode;
+  /** Human-readable message explaining the issue */
+  message: string;
+  /** 1-based line number */
+  line: number;
+  /** 0-based column */
+  column: number;
+  /** The code as written */
+  current: string;
+  /** The suggested Pyreon equivalent */
+  suggested: string;
+  /** Whether migrateReactCode can auto-fix this */
+  fixable: boolean;
+}
+interface MigrationChange {
+  type: 'replace' | 'remove' | 'add';
+  line: number;
+  description: string;
+}
+interface MigrationResult {
+  /** Transformed source code */
+  code: string;
+  /** All detected patterns (including unfixable ones) */
+  diagnostics: ReactDiagnostic[];
+  /** Description of changes applied */
+  changes: MigrationChange[];
+}
+declare function detectReactPatterns(code: string, filename?: string): ReactDiagnostic[];
+declare function migrateReactCode(code: string, filename?: string): MigrationResult;
+/** Fast regex check — returns true if code likely contains React patterns worth analyzing */
+declare function hasReactPatterns(code: string): boolean;
+interface ErrorDiagnosis {
+  cause: string;
+  fix: string;
+  fixCode?: string | undefined;
+  related?: string | undefined;
+}
+/** Diagnose an error message and return structured fix information */
+declare function diagnoseError(error: string): ErrorDiagnosis | null;
+//#endregion
 //#region src/test-audit.d.ts
 type AuditRisk = 'high' | 'medium' | 'low';
 interface TestAuditEntry {
@@ -457,5 +551,5 @@ interface SsgAuditFormatOptions {
 }
 declare function formatSsgAudit(result: SsgAuditResult, _options?: SsgAuditFormatOptions): string;
 //#endregion
-export { type AuditFormatOptions, type AuditRisk, type CompilerWarning, type ComponentInfo, type DeferInlineResult, type DeferInlineWarning, type ErrorDiagnosis, type IslandAuditFormatOptions, type IslandAuditResult, type IslandFinding, type IslandFindingCode, type IslandInfo, type IslandLocation, type MigrationChange, type MigrationResult, type ProjectContext, type PyreonDiagnostic, type PyreonDiagnosticCode, type ReactDiagnostic, type ReactDiagnosticCode, type RouteInfo, type SsgAuditFormatOptions, type SsgAuditResult, type SsgFinding, type SsgFindingCode, type SsgLocation, type TestAuditEntry, type TestAuditResult, type TransformResult, auditIslands, auditSsg, auditTestEnvironment, detectPyreonPatterns, detectReactPatterns, diagnoseError, formatIslandAudit, formatSsgAudit, formatTestAudit, generateContext, hasPyreonPatterns, hasReactPatterns, migrateReactCode, transformDeferInline, transformJSX, transformJSX_JS };
+export { type AnalyzeReactivityResult, type AuditFormatOptions, type AuditRisk, type CompilerWarning, type ComponentInfo, type DeferInlineResult, type DeferInlineWarning, type ErrorDiagnosis, type IslandAuditFormatOptions, type IslandAuditResult, type IslandFinding, type IslandFindingCode, type IslandInfo, type IslandLocation, type MigrationChange, type MigrationResult, type ProjectContext, type PyreonDiagnostic, type PyreonDiagnosticCode, type ReactDiagnostic, type ReactDiagnosticCode, type ReactivityFinding, type ReactivityFindingKind, type ReactivityKind, type ReactivitySpan, type RouteInfo, type SsgAuditFormatOptions, type SsgAuditResult, type SsgFinding, type SsgFindingCode, type SsgLocation, type TestAuditEntry, type TestAuditResult, type TransformResult, analyzeReactivity, auditIslands, auditSsg, auditTestEnvironment, detectPyreonPatterns, detectReactPatterns, diagnoseError, formatIslandAudit, formatReactivityLens, formatSsgAudit, formatTestAudit, generateContext, hasPyreonPatterns, hasReactPatterns, migrateReactCode, transformDeferInline, transformJSX, transformJSX_JS };
 //# sourceMappingURL=index2.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/compiler",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Template and JSX compiler for Pyreon",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/compiler#readme",
   "bugs": {
@@ -47,19 +47,20 @@
     "oxc-parser": "^0.129.0"
   },
   "optionalDependencies": {
-    "@pyreon/compiler-darwin-arm64": "workspace:^",
-    "@pyreon/compiler-darwin-x64": "workspace:^",
-    "@pyreon/compiler-linux-arm64-gnu": "workspace:^",
-    "@pyreon/compiler-linux-arm64-musl": "workspace:^",
-    "@pyreon/compiler-linux-x64-gnu": "workspace:^",
-    "@pyreon/compiler-linux-x64-musl": "workspace:^",
-    "@pyreon/compiler-win32-x64-msvc": "workspace:^"
+    "@pyreon/compiler-darwin-arm64": "^0.19.0",
+    "@pyreon/compiler-darwin-x64": "^0.19.0",
+    "@pyreon/compiler-linux-arm64-gnu": "^0.19.0",
+    "@pyreon/compiler-linux-arm64-musl": "^0.19.0",
+    "@pyreon/compiler-linux-x64-gnu": "^0.19.0",
+    "@pyreon/compiler-linux-x64-musl": "^0.19.0",
+    "@pyreon/compiler-win32-x64-msvc": "^0.19.0"
   },
   "devDependencies": {
-    "@pyreon/core": "^0.18.0",
-    "@pyreon/reactivity": "^0.18.0",
-    "@pyreon/runtime-dom": "^0.18.0",
-    "@pyreon/test-utils": "^0.13.5",
+    "@pyreon/core": "^0.19.0",
+    "@pyreon/manifest": "0.13.1",
+    "@pyreon/reactivity": "^0.19.0",
+    "@pyreon/runtime-dom": "^0.19.0",
+    "@pyreon/test-utils": "^0.13.6",
     "happy-dom": "^20.8.3"
   },
   "peerDependencies": {