sinwan-compiler 0.2.3 → 0.2.5

package/dist/cli.d.ts

@@ -8,3 +8,5 @@
  * Writes `.sinwan/reactive-props.json` by default.
  */
 export declare function runAnalyzeCli(args?: string[]): void;
+/** Runs the CLI only when this module is the process entry point. */
+export declare function runCliIfMain(isMain?: boolean, args?: string[]): void;

package/dist/cli.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env bun
 // @bun
 import {
-  runAnalyzeCli
-} from "./chunk-w580fdrf.js";
+  runAnalyzeCli2,
+  runCliIfMain2
+} from "./chunk-m4rk009c.js";
 export {
-  runAnalyzeCli
+  runAnalyzeCli2 as runAnalyzeCli,
+  runCliIfMain2 as runCliIfMain
 };

package/dist/index.js

@@ -1,23 +1,23 @@
 // @bun
 import {
-  AnalyzerCache,
-  analyze,
-  analyzeModule,
-  analyzeProject,
-  autoWrapComponents,
-  buildFullScope,
-  collectComponentCallGraph,
-  collectComponentFunctions,
-  computeLocalScopes,
-  containsReactiveValue,
-  getAllPropNames,
-  isReactiveValue,
-  loadMetadata,
-  propagateReactiveProps,
-  runAnalyzeCli,
-  trackReactiveImports,
-  wrapReactiveExpressions
-} from "./chunk-w580fdrf.js";
+  autoWrapComponents2,
+  analyzeModule2,
+  analyzeProject2,
+  AnalyzerCache2,
+  analyze2,
+  loadMetadata2,
+  trackReactiveImports2,
+  getAllPropNames2,
+  isReactiveValue2,
+  containsReactiveValue2,
+  collectComponentFunctions2,
+  computeLocalScopes2,
+  collectComponentCallGraph2,
+  buildFullScope2,
+  propagateReactiveProps2,
+  wrapReactiveExpressions2,
+  runAnalyzeCli2
+} from "./chunk-m4rk009c.js";
 
 // src/transform.ts
 import { parse } from "@babel/parser";
@@ -183,7 +183,18 @@ function elementToHtml(node, slots, path, filename, counter) {
     if (attrName === "children")
       continue;
     if (attrName === "ref") {
-      throw new Error("Cannot hoist element with ref");
+      if (attr.value?.type === "JSXExpressionContainer") {
+        const expr = attr.value.expression;
+        if (expr.type !== "JSXEmptyExpression") {
+          slots.push({
+            path: [...path],
+            type: "ref",
+            name: "ref",
+            expr
+          });
+        }
+      }
+      continue;
     }
     if (attr.value?.type === "JSXExpressionContainer") {
       const expr = attr.value.expression;
@@ -281,8 +292,8 @@ function transformJSX(code, filename, options = {}) {
     plugins: ["jsx", "typescript"],
     sourceFilename: filename
   });
-  autoWrapComponents(ast, filename);
-  wrapReactiveExpressions(ast, {
+  autoWrapComponents2(ast, filename);
+  wrapReactiveExpressions2(ast, {
     explicitBindings: options.explicitBindings,
     analyze: options.analyze,
     analyzeMetadata: options.analyzeMetadata,
@@ -330,11 +341,11 @@ function transformJSX(code, filename, options = {}) {
       ], t.stringLiteral("sinwan/renderer"));
       ast.program.body.unshift(bindingImport);
     }
-    const result2 = generate(ast, {
+    const result = generate(ast, {
       sourceMaps: true,
       sourceFileName: filename
     });
-    return { code: result2.code, map: result2.map };
+    return { code: result.code, map: result.map };
   }
   const templateDecls = templates.map(({ id, template }) => t.variableDeclaration("const", [
     t.variableDeclarator(t.identifier(id), t.objectExpression([
@@ -416,24 +427,24 @@ function collectExportedComponents(code, filename) {
   return found;
 }
 export {
-  AnalyzerCache,
+  AnalyzerCache2 as AnalyzerCache,
   COMPILER_TEMPLATE_SLOT_PROTOCOL,
-  analyze,
-  analyzeModule,
-  analyzeProject,
-  autoWrapComponents,
-  buildFullScope,
-  collectComponentCallGraph,
-  collectComponentFunctions,
+  analyze2 as analyze,
+  analyzeModule2 as analyzeModule,
+  analyzeProject2 as analyzeProject,
+  autoWrapComponents2 as autoWrapComponents,
+  buildFullScope2 as buildFullScope,
+  collectComponentCallGraph2 as collectComponentCallGraph,
+  collectComponentFunctions2 as collectComponentFunctions,
   collectExportedComponents,
-  computeLocalScopes,
-  containsReactiveValue,
-  getAllPropNames,
-  isReactiveValue,
-  loadMetadata,
-  propagateReactiveProps,
-  runAnalyzeCli,
-  trackReactiveImports,
+  computeLocalScopes2 as computeLocalScopes,
+  containsReactiveValue2 as containsReactiveValue,
+  getAllPropNames2 as getAllPropNames,
+  isReactiveValue2 as isReactiveValue,
+  loadMetadata2 as loadMetadata,
+  propagateReactiveProps2 as propagateReactiveProps,
+  runAnalyzeCli2 as runAnalyzeCli,
+  trackReactiveImports2 as trackReactiveImports,
   transformJSX,
-  wrapReactiveExpressions
+  wrapReactiveExpressions2 as wrapReactiveExpressions
 };

package/dist/reactive-wrap.d.ts

@@ -59,6 +59,7 @@ export interface ReactiveScope {
     bindings: Map<string, Binding>;
 }
 export declare function getAllPropNames(params: t.Node | undefined): Set<string>;
+export declare function resolveLocalObjectLiteral(fn: t.Function, name: string): t.ObjectExpression | null;
 export declare function isReactiveValue(node: t.Node, scope: ReactiveScope): boolean;
 export declare function containsReactiveValue(expr: t.Expression, scope: ReactiveScope): boolean;
 export interface ComponentExpressionInfo {
@@ -66,6 +67,9 @@ export interface ComponentExpressionInfo {
     componentName: string | null;
     attributeName: string | null;
 }
+export declare function getComponentExpressionInfo(exprPath: {
+    parentPath?: unknown;
+}): ComponentExpressionInfo;
 export declare function collectComponentFunctions(ast: t.Node, ccNames: Set<string>): {
     functions: Set<t.Function>;
     names: Map<string, t.Function>;

package/dist/transform.d.ts

@@ -35,9 +35,9 @@ export interface TransformOptions {
  * in sync.
  */
 export declare const COMPILER_TEMPLATE_SLOT_PROTOCOL: {
-    readonly slotPrefix: "s";
-    readonly encodeSlot: (index: number) => string;
-    readonly decodeSlot: (data: string) => number | null;
+    slotPrefix: string;
+    encodeSlot(index: number): string;
+    decodeSlot(data: string): number | null;
 };
 export declare function transformJSX(code: string, filename: string, options?: TransformOptions): {
     code: string;

package/docs/README.md

@@ -1,26 +1,45 @@
-# sinwan-compiler
+# Compiler overview
 
-The shared compiler package for SinwanJS. It provides the JSX transform, the project-wide reactive-prop analyzer, and the dev/HMR cache used by both the Bun and Vite plugins.
+`sinwan-compiler` is the shared engine behind the Bun and Vite plugins. It has three jobs: rewrite JSX, decide which props are reactive, and keep that decision cheap in dev.
 
-## What it does
+If you are building a Sinwan app, start with [Plugins](plugins.md). If you are changing the compiler, start with [Architecture](architecture.md).
 
-- **JSX transform**: Converts reactive JSX expressions into lazy zero-arity functions so the Sinwan runtime can update the DOM efficiently.
-- **Cross-file analysis**: Determines which component props are reactive across the whole project, allowing the transform to avoid wrapping static props in effects.
-- **Dev cache**: Maintains an incremental, persistent cache for Bun and Vite so dev startup and HMR are fast.
+## Pipeline
 
-## Packages
+1. **Auto-`cc`** — exported functions that look like components (`App`, `Card`, …) are wrapped with `cc(...)` so the rest of the pipeline sees the same components the runtime will.
+2. **Reactive wrap** — JSX expressions that read signals, stores, `useState`, or `useFetch` become `() => …` (or explicit binding helpers when that mode is on).
+3. **Template hoist** — static native-element trees become `_$createTemplate(...)` calls with slots for dynamic bits (`child`, `attr`, `event`, `ref`).
+4. **Analyze (optional)** — a project-wide pass marks which *exported* component props are actually reactive, so static strings are not wrapped.
 
-- `src/transform.ts` — JSX transform and reactive expression wrapping.
-- `src/analyze.ts` — `analyze`, `analyzeProject`, `AnalyzerCache`, and import resolution.
-- `src/reactive-wrap.ts` — Helpers for detecting reactive sources, collecting component call graphs, and propagating reactivity.
-- `src/cli.ts` — `sinwan-compiler analyze` CLI.
-- `src/index.ts` — Public package exports.
+```text
+source.tsx
+    │
+    ▼
+autoWrapComponents()     plain `export function App()` → cc(App)
+    │
+    ▼
+wrapReactiveExpressions()   {count.value} → {() => count.value}
+    │
+    ▼
+hoist templates             <div class="card">…</div> → _$tmpl_N
+    │
+    ▼
+generated module
+```
 
-## Documentation
+## When analysis runs
 
-- [`analyzer.md`](analyzer.md) — Cross-file reactive-prop analyzer and cache.
-- [`transform.md`](transform.md) — JSX transform and wrapping rules.
-- [`cli.md`](cli.md) — Command-line usage.
-- [`plugins.md`](plugins.md) — Using the compiler with Bun and Vite.
-- [`api.md`](api.md) — Public API reference.
-- [`architecture.md`](architecture.md) — Internal design and data flow.
+| Mode | Who runs it | What the transform receives |
+| ---- | ----------- | --------------------------- |
+| Dev | Plugin `AnalyzerCache` | In-memory `analyzeMetadata` after each file update |
+| Production | CLI / `analyze()` | JSON file via `analyze: "./.sinwan/reactive-props.json"` |
+| Off | Nobody | Conservative wrapping (exported props treated as reactive) |
+
+## Guides
+
+- [Transform](transform.md) — what gets wrapped, auto-`cc`, hoisting, built-in components
+- [Analyzer](analyzer.md) — call graph, spreads, workspaces, cache
+- [CLI](cli.md) — `sinwan analyze`
+- [Plugins](plugins.md) — wiring Bun and Vite
+- [API](api.md) — exported functions and types
+- [Architecture](architecture.md) — data structures and propagation

package/docs/analyzer.md

@@ -1,16 +1,18 @@
-# Cross-file reactive-prop analyzer
+# Cross-file analyzer
 
-The analyzer determines which props of an exported component are reactive. It runs over the whole project (or a cached subset) and produces a map of `filePath → exportName → Set<propName>`.
+The analyzer answers: **for each exported component, which props actually change?** The transform uses that map so a static `title="Hello"` does not become an effect.
+
+Result shape: `filePath → exportName → Set<propName>`.
 
 ## How it works
 
-1. **Parse** every `.tsx/.ts/.jsx/.js` file into a Babel AST.
-2. **Track imports** of reactive sources (`createMutable`, `createStore`, `signal`, `computed`, `useState`) and the component factory `cc`.
-3. **Collect component functions** defined with `cc(...)`.
-4. **Build a call graph** of local and imported JSX calls (`<Child ... />`).
-5. **Propagate reactivity** bottom-up through the call graph using a fixed-point algorithm.
+1. Scan `.tsx` / `.ts` / `.jsx` / `.js` (or the files you pass in).
+2. Auto-wrap the same exported components the transform would wrap.
+3. Track reactive imports and `cc(...)`.
+4. Build a call graph: local `<Child />` and imported `<Child />`.
+5. Propagate reactivity until the sets stop growing.
 
-A prop is reactive for a given component if any of its callers passes a value that reads a reactive source.
+A prop is reactive if **any** caller passes a value that reads a reactive source (including through another component).
 
 ## Example
 
@@ -23,10 +25,12 @@ export const Child = cc(({ title }) => <h1>{title}</h1>);
 import { cc } from "sinwan/component";
 import { signal } from "sinwan/reactivity";
 import { Child } from "./Child";
-const Parent = cc(() => <Child title={signal.value} />);
-```
 
-The analyzer produces:
+const Parent = cc(() => {
+  const title = signal("Hello");
+  return <Child title={title.value} />;
+});
+```
 
 ```json
 {
@@ -34,64 +38,71 @@ The analyzer produces:
 }
 ```
 
-## Workspace packages
+If every caller passed `title="Hello"`, `Child` would be `[]` and the transform would not wrap `title` inside `Child`.
 
-Cross-file analysis works for local monorepo packages. The analyzer discovers workspace packages from a `package.json` `workspaces` field, a `pnpm-workspace.yaml`, or explicit package paths. Only packages that are actually imported by the project are analyzed.
+Default exports are stored under the name `"default"`.
 
-```ts
-analyzeProject({
-  root: "./apps/web",
-  // From a workspace file
-  workspaces: "../../package.json",
-  // From a pnpm workspace
-  workspaces: "../../pnpm-workspace.yaml",
-  // Explicit package paths or globs
-  workspaces: ["../../packages/sinwan-ui", "../../packages/shared"],
-  // Or combine both
-  workspaces: {
-    file: "../../package.json",
-    include: ["../../packages/sinwan-ui"],
-  },
-});
-```
+## Spreads
+
+The analyzer is precise when it can see the object:
 
-Package imports are resolved to files inside the declared package, typically under the package `src` directory (or the directory of the `source` field in `package.json`). Subpath imports such as `@sinwan/ui/Button` map to `packages/sinwan-ui/src/Button.tsx`.
+```tsx
+<Child {...{ title: "Hello", count: s.value }} />
+// only `count` is reactive
 
+const props = { title: "Hello", count: s.value };
+<Child {...props} />
+// same, if `props` is that object literal in the same function
+```
 
+String keys work (`{ "title": s.value }`). If the spread is an unknown value (`{...rest}` from parameters), **every known prop of the callee**, including `children`, is marked reactive.
 
 ## Import resolution
 
-The analyzer resolves imports in this order:
+Lookups run in this order:
+
+1. `tsconfig.json` `paths` (when a config is passed or `tsconfig.json` exists next to `root`)
+2. `bunfig.toml` aliases (`[install] alias = { … }` or `[install.alias]`)
+3. Workspace packages (see below)
+4. Relative imports (`./Child`, `./ui` → `ui.tsx` or `ui/index.tsx`)
+
+You can replace that with `resolve(source, fromFile)`.
+
+`AnalyzerCache` also resolves **in-memory** modules first (HMR can update a file before it hits disk), including `./ui` → `ui/index.tsx` already in the cache.
 
-1. `tsconfig.json` `paths` (if configured).
-2. `bunfig.toml` aliases (if configured or auto-detected).
-3. Workspace packages (if configured).
-4. Relative imports with the configured extensions.
+## Workspaces
 
-You can also provide a custom resolver:
+Only packages that the app actually imports are pulled in.
 
 ```ts
 analyzeProject({
-  root: "/project",
-  resolve: (source, fromFile) => {
-    // return absolute path or null
-  },
+  root: "./apps/web",
+  workspaces: "../../package.json", // npm/bun `workspaces`
+  // or "../../pnpm-workspace.yaml"
+  // or ["../../packages/ui"]
+  // or { file: "../../package.json", include: ["../../packages/ui"] }
 });
 ```
 
-## Spread props
+`@scope/ui/Button` maps to `packages/ui/src/Button.tsx` (or the directory of `package.json` `"source"`).
+
+## Cache (`AnalyzerCache`)
+
+Dev plugins call `update(file, code)` on each transform. The cache:
+
+- Re-analyzes that file
+- Walks importers **and** imported modules
+- Writes `cachePath` when you set one
+
+`remove(file)` is for deletes / HMR unlinks. It drops the module and **recomputes both**:
 
-Spread props are handled precisely when possible:
+- files that imported it (parents)
+- files it imported (children — their props may become static again)
 
-- `<Child {...{ title: "Hello", count: signal.value }} />` is treated as two named props; only `count` becomes reactive.
-- `<Child {...props} />` is also resolved precisely if `props` is a local variable initialized with an object literal in the same function:
-  ```tsx
-  const props = { title: "Hello", count: signal.value };
-  return <Child {...props} />;
-  ```
-- Spreads of function parameters or other unknown runtime objects fall back to the conservative rule: all known props of the callee are marked reactive.
+If `cachePath` exists, the constructor restores it. Function identities are start/end offsets. If a file changed so those spans no longer match, that module is skipped (no throw); the next `update` rebuilds it.
 
-## Limitations
+## Conservative rules
 
-- Unknown runtime objects (`{...props}` where `props` is not a local object literal) are conservatively treated as reactive.
-- Named slot props and `children` are regular props; they are reactive only when the passed value is reactive.
+- Unknown spreads are conservative (all callee props).
+- `children` is a normal prop.
+- Without metadata, the transform treats **exported** component props as reactive so a parent in another file cannot silently go stale.

package/docs/api.md

@@ -1,25 +1,41 @@
 # API reference
 
-## `transformJSX(code, filename, options?)`
+Import from `sinwan-compiler`. Types below match the package exports.
 
-Transforms a single JSX/TSX file.
+## Transform
+
+### `transformJSX(code, filename, options?)`
+
+Rewrite one module. Returns `{ code: string; map?: unknown }`.
 
 ```ts
 import { transformJSX } from "sinwan-compiler";
 
-const result = transformJSX(code, filename, {
+const { code, map } = transformJSX(source, "src/App.tsx", {
   hoist: true,
+  dev: false,
   explicitBindings: false,
   analyze: "./.sinwan/reactive-props.json",
-  analyzeMetadata: new Map(),
+  analyzeMetadata: cache.reactiveProps,
+  resolveImport: (source, fromFile) => /* absolute path or null */,
 });
 ```
 
-Returns `{ code: string; map?: any }`.
+See [Transform](transform.md) for wrapping rules and options.
+
+### `COMPILER_TEMPLATE_SLOT_PROTOCOL`
+
+`{ slotPrefix, encodeSlot(index), decodeSlot(data) }`. Markers look like `s:0`. Keep this aligned with the Sinwan runtime protocol.
+
+### `autoWrapComponents(ast, filename?)`
 
-## `analyze(options)`
+Mutates a Babel AST: wrap exported component-like functions with `cc(...)`. Returns `true` if anything changed. `transformJSX` already runs this.
 
-Production entry point. Analyzes the project and writes metadata to disk.
+## Analysis
+
+### `analyze(options)`
+
+Scan a project and write JSON to `outFile`.
 
 ```ts
 import { analyze } from "sinwan-compiler";
@@ -27,58 +43,93 @@ import { analyze } from "sinwan-compiler";
 analyze({
   root: "./src",
   outFile: "./.sinwan/reactive-props.json",
+  extensions: [".tsx", ".ts", ".jsx", ".js"], // default
   tsConfigPath: "./tsconfig.json",
   bunfigPath: "./bunfig.toml",
   workspaces: "../../package.json",
+  resolve: (source, fromFile) => null,
 });
 ```
 
-## `analyzeProject(options)`
+Missing `tsconfig.json` / `bunfig.toml` next to `root` are skipped unless you pass the paths explicitly.
+
+### `analyzeProject(options)`
 
-Programmatic analyzer. Returns the full project analysis without writing to disk.
+Same scan, no disk write. Returns `{ modules, reactiveProps }`.
 
 ```ts
 import { analyzeProject } from "sinwan-compiler";
 
 const project = analyzeProject({
   root: "./src",
-  files: { "/project/A.tsx": "..." },
+  files: { "/tmp/A.tsx": "export const A = () => <div/>" }, // optional in-memory map
   tsConfigPath: "./tsconfig.json",
+  workspaces: { file: "../../package.json", include: ["../../packages/ui"] },
 });
 
-project.reactiveProps.get("/project/A.tsx")?.get("Component");
+project.reactiveProps.get("/tmp/A.tsx")?.get("A"); // Set<string> | undefined
 ```
 
-## `AnalyzerCache`
+### `analyzeModule(code, filePath)`
+
+Analyze one file. Used by the cache and tests.
+
+### `loadMetadata(filePath)`
 
-Incremental analyzer for dev/HMR.
+Read analyzer JSON into `Map<file, Map<exportName, Set<prop>>>`. Missing file → empty map.
+
+### `loadWorkspacePackages(workspaces, root)`
+
+Resolve workspace directories from a file, a list of globs/paths, or `{ file, include }`.
+
+### `AnalyzerCache`
+
+Incremental graph for plugins.
 
 ```ts
 import { AnalyzerCache } from "sinwan-compiler";
 
 const cache = new AnalyzerCache({
-  root: "./src",
+  root: process.cwd(),
   tsConfigPath: "./tsconfig.json",
   bunfigPath: "./bunfig.toml",
   workspaces: "../../package.json",
   cachePath: "./.sinwan/cache.json",
+  resolve: (source, fromFile) => null, // optional
 });
 
-cache.update(filePath, newCode);
-const metadata = cache.reactiveProps;
+cache.update(absPath, source);
+cache.remove(absPath); // also recomputes modules this file imported
+cache.save(); // no-op without cachePath
+
+cache.reactiveProps; // Map<file, Map<export, Set<prop>>>
+cache.modules;
 ```
 
-### Methods
+`restore` runs in the constructor when `cachePath` exists. Stale function spans skip that module instead of throwing.
+
+## CLI helpers
+
+### `runAnalyzeCli(args?)`
+
+Parse `analyze [root] [outFile] [--tsconfig] [--bunfig] [--workspaces]` and call `analyze()`. Defaults to `process.argv.slice(2)`. Unknown commands write to stderr and `process.exit(1)`.
+
+## Other exports
 
-- `update(filePath, code)` — re-analyze a file and recompute affected files.
-- `remove(filePath)` — remove a file and recompute affected files.
-- `save()` — persist the cache to `cachePath`.
-- `restore()` — load the cache from `cachePath` (called automatically if `cachePath` exists).
+| Name | Role |
+| ---- | ---- |
+| `collectExportedComponents(code)` | File-local exported component names (no `cc` required) |
+| `wrapReactiveExpressions(ast, options?)` | Reactive wrap without hoisting |
+| `trackReactiveImports(ast)` | Import-name sets for signals, `cc`, `useFetch`, … |
+| `collectComponentFunctions(ast, ccNames)` | `cc(...)` functions, names, and exports |
+| `computeLocalScopes(ast, names)` | Per-function reactive bindings |
+| `collectComponentCallGraph(ast, names)` | Local JSX call sites |
+| `propagateReactiveProps(scopes, graph, fns)` | Fixed-point prop sets |
+| `buildFullScope(scopes, fn, reactiveProps)` | Local bindings plus reactive props |
+| `containsReactiveValue(expr, scope)` | Whether an expression reads a reactive value |
+| `isReactiveValue(node, scope)` | Single-node check |
+| `getAllPropNames(params)` | Prop names from a component parameter (`*` for a bare identifier) |
 
 ## Types
 
-- `CallSite` — local component call site.
-- `ImportedCallSite` — cross-file component call site.
-- `ModuleAnalysis` — analysis of a single module.
-- `ProjectAnalysis` — analysis of the whole project.
-- `WorkspacesConfig` — workspace file path, explicit package paths/globs, or both. Used to enable cross-package analysis in monorepos.
+`AnalyzeOptions`, `WorkspacesConfig`, `ModuleAnalysis`, `ProjectAnalysis`, `ImportInfo`, `ImportedCallSite`, `CallSite`, `ReactiveScope`, `Binding`, `ImportNames`, `ComponentExpressionInfo`, `ExportedComponent`, `TransformOptions`.