@pyreon/compiler 0.13.1 → 0.15.0

package/lib/types/index.d.ts

@@ -18,20 +18,15 @@
  *    values, and all children are text nodes or other static JSX nodes.
  *
  * Template emission:
- *  - JSX element trees with ≥ 2 DOM elements (no components, no spread attrs)
- *    are compiled to `_tpl(html, bindFn)` calls instead of nested `h()` calls.
+ *  - JSX element trees with ≥ 1 DOM elements (no components, no spread attrs on
+ *    inner elements) are compiled to `_tpl(html, bindFn)` calls instead of nested
+ *    `h()` calls.
  *  - The HTML string is parsed once via <template>.innerHTML, then cloneNode(true)
  *    for each instance (~5-10x faster than sequential createElement calls).
  *  - Static attributes are baked into the HTML string; dynamic attributes and
  *    text content use renderEffect in the bind function.
  *
- * Implementation: TypeScript parser for positions + magic-string replacements.
- * No extra runtime dependencies — `typescript` is already in devDependencies.
- *
- * Known limitation (v0): expressions inside *nested* JSX within a child
- * expression container are not individually wrapped. They are still reactive
- * because the outer wrapper re-evaluates the whole subtree, just at a coarser
- * granularity. Fine-grained nested wrapping is planned for a future pass.
+ * Implementation: Rust native binary (napi-rs) when available, JS fallback via oxc-parser.
  */
 interface CompilerWarning {
   /** Warning message */
@@ -54,14 +49,27 @@ interface TransformResult {
 interface TransformOptions {
   /**
    * Compile for server-side rendering. When true, the compiler skips the
-   * `_tpl()` template optimization (which mutates a real DOM via
-   * `document.createElement` etc.) and falls back to plain `h()` calls so
-   * `@pyreon/runtime-server` can walk the VNode tree. Client builds keep
-   * the `_tpl()` fast path. Default: false.
+   * `_tpl()` template optimization and falls back to plain `h()` calls so
+   * `@pyreon/runtime-server` can walk the VNode tree. Default: false.
    */
   ssr?: boolean;
+  /**
+   * Known signal variable names from resolved imports.
+   * The Vite plugin maintains a cross-module signal export registry and
+   * passes imported signal names here so the compiler can auto-call them
+   * in JSX even though the `signal()` declaration is in another file.
+   *
+   * @example
+   * // store.ts: export const count = signal(0)
+   * // component.tsx: import { count } from './store'
+   * transformJSX(code, 'component.tsx', { knownSignals: ['count'] })
+   * // {count} in JSX → {() => count()}
+   */
+  knownSignals?: string[];
 }
 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
 /**
@@ -154,5 +162,135 @@ interface ErrorDiagnosis {
 /** Diagnose an error message and return structured fix information */
 declare function diagnoseError(error: string): ErrorDiagnosis | null;
 //#endregion
-export { type CompilerWarning, type ComponentInfo, type ErrorDiagnosis, type IslandInfo, type MigrationChange, type MigrationResult, type ProjectContext, type ReactDiagnostic, type ReactDiagnosticCode, type RouteInfo, type TransformResult, detectReactPatterns, diagnoseError, generateContext, hasReactPatterns, migrateReactCode, transformJSX };
+//#region src/pyreon-intercept.d.ts
+/**
+ * Pyreon Pattern Interceptor — detects Pyreon-specific anti-patterns in
+ * code that has ALREADY committed to the framework (imports are Pyreon,
+ * not React). Complements `react-intercept.ts` — the React detector
+ * catches "coming from React" mistakes; this one catches "using Pyreon
+ * wrong" mistakes.
+ *
+ * Catalog of detected patterns (grounded in `.claude/rules/anti-patterns.md`):
+ *
+ *  - `for-missing-by` — `<For each={...}>` without a `by` prop
+ *  - `for-with-key`   — `<For key={...}>` (JSX reserves `key`; the keying
+ *                       prop is `by` in Pyreon)
+ *  - `props-destructured` — `({ foo }: Props) => <JSX />` destructures at
+ *                       the component signature; reading is captured once
+ *                       and loses reactivity. Access `props.foo` instead
+ *                       or use `splitProps(props, [...])`.
+ *  - `process-dev-gate` — `typeof process !== 'undefined' &&
+ *                       process.env.NODE_ENV !== 'production'` is dead
+ *                       code in real Vite browser bundles. Use
+ *                       `import.meta.env?.DEV` instead.
+ *  - `empty-theme`    — `.theme({})` chain is a no-op; remove it.
+ *  - `raw-add-event-listener` — raw `addEventListener(...)` in a component
+ *                       or hook body. Use `useEventListener(...)` from
+ *                       `@pyreon/hooks` for auto-cleanup.
+ *  - `raw-remove-event-listener` — same, for removeEventListener.
+ *  - `date-math-random-id` — `Date.now() + Math.random()` / template-concat
+ *                       variants. Under rapid operations (paste, clone)
+ *                       collision probability is non-trivial. Use a
+ *                       monotonic counter.
+ *  - `on-click-undefined` — `onClick={undefined}` explicitly; the runtime
+ *                       used to crash on this pattern. Omit the prop.
+ *  - `signal-write-as-call` — `sig(value)` is a no-op read that ignores
+ *                       its argument; the runtime warns in dev. Static
+ *                       detector spots it pre-runtime when `sig` was
+ *                       declared as `const sig = signal(...)` /
+ *                       `computed(...)` and called with ≥1 argument.
+ *  - `static-return-null-conditional` — `if (cond) return null` at the
+ *                       top of a component body runs ONCE; signal changes
+ *                       in `cond` never re-evaluate the early-return.
+ *                       Wrap in a returned reactive accessor.
+ *  - `as-unknown-as-vnodechild` — defensive `as unknown as VNodeChild`
+ *                       cast on JSX returns is unnecessary (`JSX.Element`
+ *                       is already assignable to `VNodeChild`).
+ *
+ * Two-mode surface mirrors `react-intercept.ts`:
+ *  - `detectPyreonPatterns(code)` — diagnostics only
+ *  - `hasPyreonPatterns(code)`   — fast regex pre-filter
+ *
+ * ## fixable: false (invariant)
+ *
+ * Every Pyreon diagnostic reports `fixable: false` — no exceptions.
+ * The `migrate_react` MCP tool only knows React mappings, so claiming
+ * a Pyreon code is auto-fixable would mislead a consumer who wires
+ * their UX off the flag and finds nothing applies the fix. Flip to
+ * `true` ONLY when a companion `migrate_pyreon` tool ships in a
+ * subsequent PR. The invariant is locked in
+ * `tests/pyreon-intercept.test.ts` under "fixable contract".
+ *
+ * Designed for three consumers:
+ *  1. Compiler pre-pass warnings during build
+ *  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';
+interface PyreonDiagnostic {
+  /** Machine-readable code for filtering + programmatic handling */
+  code: PyreonDiagnosticCode;
+  /** 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 fix */
+  suggested: string;
+  /** Whether a mechanical auto-fix is safe */
+  fixable: boolean;
+}
+declare function detectPyreonPatterns(code: string, filename?: string): PyreonDiagnostic[];
+/** Fast regex pre-filter — returns true if the code is worth a full AST walk. */
+declare function hasPyreonPatterns(code: string): boolean;
+//#endregion
+//#region src/test-audit.d.ts
+type AuditRisk = 'high' | 'medium' | 'low';
+interface TestAuditEntry {
+  /** Absolute path to the test file */
+  path: string;
+  /** Path relative to the repo root for readable reporting */
+  relPath: string;
+  /** Count of object-literal `{ type: ..., props: ..., children: ... }` patterns */
+  mockVNodeLiteralCount: number;
+  /** Count of `vnode` / `mockVNode` / `createVNode` helper DEFINITIONS */
+  mockHelperCount: number;
+  /**
+   * Count of CALLS to a known mock-helper name. Captures pervasiveness:
+   * a file with one helper definition and 50 call-sites has the same
+   * `mockHelperCount` (1) as one with zero calls, but very different
+   * exposure. This metric surfaces that.
+   */
+  mockHelperCallCount: number;
+  /** Count of lines that look like real `h(...)` calls (`h(Tag, props)` / `h(Component, ...)` shape) */
+  realHCallCount: number;
+  /** True if the file imports `h` from `@pyreon/core` */
+  importsH: boolean;
+  /** Risk classification */
+  risk: AuditRisk;
+}
+interface TestAuditResult {
+  /** Repo root discovered by walking up for `packages/` */
+  root: string | null;
+  /** Every test file scanned, sorted by risk (high → low) then path */
+  entries: TestAuditEntry[];
+  /** Total files scanned */
+  totalScanned: number;
+}
+declare function auditTestEnvironment(startDir: string): TestAuditResult;
+interface AuditFormatOptions {
+  /** Only include entries at or above this risk level. Default 'medium'. */
+  minRisk?: AuditRisk | undefined;
+  /** Maximum entries to show per risk group. Default 20. */
+  limit?: number | undefined;
+}
+declare function formatTestAudit(result: TestAuditResult, {
+  minRisk,
+  limit
+}?: AuditFormatOptions): string;
+//#endregion
+export { type AuditFormatOptions, type AuditRisk, type CompilerWarning, type ComponentInfo, type ErrorDiagnosis, type IslandInfo, type MigrationChange, type MigrationResult, type ProjectContext, type PyreonDiagnostic, type PyreonDiagnosticCode, type ReactDiagnostic, type ReactDiagnosticCode, type RouteInfo, type TestAuditEntry, type TestAuditResult, type TransformResult, auditTestEnvironment, detectPyreonPatterns, detectReactPatterns, diagnoseError, formatTestAudit, generateContext, hasPyreonPatterns, hasReactPatterns, migrateReactCode, transformJSX, transformJSX_JS };
 //# sourceMappingURL=index2.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/compiler",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description": "Template and JSX compiler for Pyreon",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/compiler#readme",
   "bugs": {
@@ -14,6 +14,7 @@
   },
   "files": [
     "lib",
+    "!lib/**/*.map",
     "src",
     "README.md",
     "LICENSE"
@@ -41,6 +42,16 @@
     "lint": "oxlint .",
     "prepublishOnly": "bun run build"
   },
+  "dependencies": {
+    "oxc-parser": "^0.129.0"
+  },
+  "devDependencies": {
+    "@pyreon/core": "^0.15.0",
+    "@pyreon/reactivity": "^0.15.0",
+    "@pyreon/runtime-dom": "^0.15.0",
+    "@pyreon/test-utils": "^0.13.2",
+    "happy-dom": "^20.8.3"
+  },
   "peerDependencies": {
     "typescript": ">=5.0.0"
   }

package/src/event-names.ts

@@ -0,0 +1,65 @@
+/**
+ * React-style → DOM event-name remap.
+ *
+ * The compiler translates JSX event handler attributes (`onClick`,
+ * `onMouseEnter`, ...) to DOM event names by stripping the `on` prefix
+ * and lowercasing. That rule covers MOST React event-name conventions
+ * because the underlying DOM event name happens to be the lowercased
+ * multi-word form (e.g. `onKeyDown` → `keydown`, `onMouseEnter` →
+ * `mouseenter`, `onPointerLeave` → `pointerleave`,
+ * `onAnimationStart` → `animationstart`, `onContextMenu` → `contextmenu`).
+ *
+ * **The exceptions** — where lowercasing produces the WRONG DOM event
+ * name — are listed in `REACT_EVENT_REMAP` below. Each entry maps the
+ * lowercased React form to the actual DOM event name.
+ *
+ * Today there is exactly ONE remap: `doubleclick → dblclick`. React
+ * inherits this mismatch from the DOM spec — `dblclick` is the canonical
+ * event name (RFC at `https://dom.spec.whatwg.org/#interface-mouseevent`),
+ * while React's component-prop convention is the `onDoubleClick` shape.
+ *
+ * **Audit completeness.** The full React event-prop list from
+ * `https://react.dev/reference/react-dom/components/common` was checked
+ * against canonical DOM event names. Every multi-word event other than
+ * `onDoubleClick` lowercases correctly:
+ *   - Pointer family: `onPointerDown` → `pointerdown`, `onGotPointerCapture` → `gotpointercapture`, …
+ *   - Mouse family: `onMouseEnter` → `mouseenter`, `onMouseLeave` → `mouseleave`, …
+ *   - Drag family: `onDragStart` → `dragstart`, `onDragEnd` → `dragend`, …
+ *   - Touch family: `onTouchStart` → `touchstart`, `onTouchEnd` → `touchend`, …
+ *   - Composition family: `onCompositionEnd` → `compositionend`, …
+ *   - Animation/transition: `onAnimationStart` → `animationstart`, `onTransitionEnd` → `transitionend`, …
+ *   - Media family: `onCanPlayThrough` → `canplaythrough`, `onLoadedData` → `loadeddata`, `onTimeUpdate` → `timeupdate`, `onVolumeChange` → `volumechange`, …
+ *   - Form family: `onContextMenu` → `contextmenu`, `onBeforeInput` → `beforeinput`, …
+ *
+ * If a future React release adds a new event-prop with a non-trivial
+ * mismatch, append the entry here. Both compiler backends (JS and Rust)
+ * read the same shape — the Rust port lives in `native/src/lib.rs` next
+ * to `emit_event_listener`. Keep them in sync.
+ *
+ * **Testing.** `packages/core/compiler/src/tests/runtime/events.test.ts`
+ * exercises this table end-to-end via a real-Chromium harness:
+ *   - `onDoubleClick fires (multi-word + delegated)` — locks in the remap.
+ *   - `onContextMenu fires (multi-word, lowercases to contextmenu)` —
+ *     locks in the no-remap default for an adjacent multi-word event.
+ *   - `event-name-remap-table sanity` — asserts that every entry in
+ *     `REACT_EVENT_REMAP` has a corresponding runtime test.
+ */
+export const REACT_EVENT_REMAP: Readonly<Record<string, string>> = Object.freeze({
+  doubleclick: 'dblclick',
+})
+
+/**
+ * Translate a React-style event prop name (`onDoubleClick`) to the
+ * canonical DOM event name (`dblclick`). Returns null for non-event
+ * attribute names (anything not starting with `on` or shorter than 3
+ * characters — single-letter `on*` props don't correspond to DOM events).
+ *
+ * The compiler uses the returned name in two emission shapes:
+ *   - Delegated events (in `DELEGATED_EVENTS`): `el.__ev_${eventName} = handler`
+ *   - Direct listeners: `el.addEventListener("${eventName}", handler)`
+ */
+export function reactEventToDom(attrName: string): string | null {
+  if (attrName.length <= 2 || !attrName.startsWith('on')) return null
+  const lower = attrName.slice(2).toLowerCase()
+  return REACT_EVENT_REMAP[lower] ?? lower
+}

package/src/index.ts

@@ -1,7 +1,7 @@
 // @pyreon/compiler — JSX reactive transform for Pyreon
 
 export type { CompilerWarning, TransformResult } from './jsx'
-export { transformJSX } from './jsx'
+export { transformJSX, transformJSX_JS } from './jsx'
 export type { ComponentInfo, IslandInfo, ProjectContext, RouteInfo } from './project-scanner'
 export { generateContext } from './project-scanner'
 export type {
@@ -17,3 +17,12 @@ export {
   hasReactPatterns,
   migrateReactCode,
 } from './react-intercept'
+export type { PyreonDiagnostic, PyreonDiagnosticCode } from './pyreon-intercept'
+export { detectPyreonPatterns, hasPyreonPatterns } from './pyreon-intercept'
+export type {
+  AuditFormatOptions,
+  AuditRisk,
+  TestAuditEntry,
+  TestAuditResult,
+} from './test-audit'
+export { auditTestEnvironment, formatTestAudit } from './test-audit'