sinwan-compiler 0.2.3 → 0.2.5

package/docs/architecture.md

@@ -1,75 +1,78 @@
 # Architecture
 
-## File layout
+This page is for people changing the compiler. App authors can stay on [Transform](transform.md) and [Plugins](plugins.md).
+
+## Layout
 
 ```
 src/
-  index.ts          Public exports
-  transform.ts      JSX transform and template hoisting
-  reactive-wrap.ts  Reactive source detection, call graph, propagation
-  analyze.ts        Cross-file analyzer, cache, import resolution, CLI
-  cli.ts            CLI entry point
+  index.ts           Public exports
+  auto-cc.ts         Exported function → cc(...)
+  reactive-wrap.ts   Imports, scopes, call graph, wrap
+  transform.ts       Hoist + transformJSX
+  analyze.ts         Project scan, resolution, AnalyzerCache
+  cli.ts             analyze CLI
+  exports.ts         collectExportedComponents
 ```
 
 ## Data flow
 
-1. **Transform**: receives source code and optional reactive-prop metadata.
-2. **Analyzer (dev)**: builds `AnalyzerCache` incrementally as files are transformed.
-3. **Analyzer (production)**: `analyzeProject()` scans the whole project and writes metadata.
-4. **Propagation**: `propagateReactiveProps()` runs a fixed-point algorithm over the call graph.
+```text
+transformJSX
+  autoWrapComponents
+  wrapReactiveExpressions   ← analyze / analyzeMetadata / resolveImport
+  hoist JSXElement roots    ← _$createTemplate + slots
+
+analyze / AnalyzerCache.update
+  autoWrapComponents
+  analyzeModule             ← scopes + local + imported call sites
+  buildProjectReactiveProps
+  propagateReactiveProps
+```
 
-## Key data structures
+Dev plugins call `cache.update` on each file, then pass `cache.reactiveProps` into `transformJSX` as `analyzeMetadata`. Production writes the same map to JSON (`analyze`) and the plugin sets `analyze: path`.
 
-### `CallSite`
+## Call graph
 
-```ts
-{
-  callee: t.Function;
-  props: { name: string; value: t.Expression }[];
-  spreads: t.Expression[];
-}
-```
+A **local** site is `<Child />` where `Child` is `cc(...)` in the same file.
 
-`spreads` stores the spread expressions. Object-literal spreads are analyzed precisely; unknown spreads are treated conservatively.
+An **imported** site stores `{ caller, source, name, props, spreads }`. The project pass resolves `source` to a file and attaches the site to that file’s export (or `"default"`).
 
-### `ModuleAnalysis`
+`spreads` are analyzed when the expression is an object literal or a local `const props = { … }` in the caller. Otherwise every known callee prop is marked reactive.
 
-Per-file analysis including:
+## Propagation
 
-- imports
-- exports
-- default export
-- component functions
-- local scopes
-- local call graph
-- imported call sites
+1. Seed callee sets from values that are already reactive in the caller’s local scope.
+2. Worklist over all component functions.
+3. For each site, add prop names whose values are reactive in the caller’s **full** scope (local bindings + that function’s own reactive props).
+4. Repeat until sets stop growing.
 
-### `AnalyzerCache`
+Cycles terminate because sets only grow.
 
-- Stores `ModuleAnalysis` objects keyed by absolute file path.
-- Maintains `reactiveProps: Map<filePath, Map<exportName, Set<propName>>>`.
-- Maintains a reverse importer index for targeted incremental propagation.
-- Serializes to JSON for persistence across process restarts.
+## Import resolution
 
-## Propagation algorithm
+`createResolver` order:
 
-1. Initialize every exported component with an empty reactive-prop set.
-2. For each component function, build a full scope that includes its own bindings and the reactive props of its parent.
-3. For each call site, check every named prop and object-literal spread key. If the value contains a reactive read, add the prop name to the callee's reactive set.
-4. For unknown spreads, add all known callee prop names.
-5. If a callee's reactive set grows, add the callee to the worklist and repeat until stable.
+1. `tsconfig` `paths`
+2. `bunfig.toml` aliases
+3. Workspace package name + subpath
+4. Relative path + extensions / `index.*`
 
-## Import resolution
+`AnalyzerCache` wraps that with an in-memory lookup so HMR can resolve `./Child` to a module that exists only in the cache.
+
+## Cache persistence
+
+Serialized modules store function **start/end** offsets. Restore re-parses the file and remaps those spans. If a span is gone (the file was edited), `restoreModule` returns `null` and that entry is dropped. The next `update` fills it in.
 
-The resolver combines multiple sources:
+`remove(path)`:
 
-- `tsconfig.json` `paths`
-- `bunfig.toml` aliases
-- Relative imports
-- Custom resolver
+1. Collect importers of `path` and modules `path` imported
+2. Delete the module and importer index entries
+3. `recomputeFor` that set
+4. `save()` if `cachePath` is set
 
-Resolution order: tsconfig → bunfig → relative → custom.
+That second set matters: deleting a parent must let the child’s props become static again.
 
-## Serialization
+## Template protocol
 
-The cache serializes modules using function start/end positions as stable identifiers. When restoring, the source file is re-parsed and functions are matched by position. This allows the cache to survive source edits as long as the analyzed functions remain at the same positions.
+`COMPILER_TEMPLATE_SLOT_PROTOCOL` in `transform.ts` is duplicated from the runtime (`sinwan` template protocol). A drift test in the `sinwan` package keeps the two in sync. Slot types: `child`, `attr`, `event`, `ref`.

package/docs/cli.md

@@ -1,46 +1,53 @@
 # CLI
 
-The `sinwan-compiler` package ships a small CLI for production analysis.
+Production analysis is a single command. Dev servers do not need it; plugins keep a live cache.
 
-## Command
+The published binary name is `sinwan` (see `package.json` `"bin"`). After install you can also run the package name:
 
 ```bash
 bunx sinwan-compiler analyze [root] [outFile] [options]
+# same after a local install:
+sinwan analyze [root] [outFile] [options]
 ```
 
-- `root` — project root to scan (default: current working directory).
-- `outFile` — path for the output JSON (default: `<root>/.sinwan/reactive-props.json`).
+| Argument | Default |
+| -------- | ------- |
+| `root` | Current working directory |
+| `outFile` | `<root>/.sinwan/reactive-props.json` |
 
-## Options
+| Flag | Meaning |
+| ---- | ------- |
+| `--tsconfig`, `-t` | `tsconfig.json` for `paths` |
+| `--bunfig`, `-b` | `bunfig.toml` for Bun aliases |
+| `--workspaces`, `-w` | `package.json`, `pnpm-workspace.yaml`, or a package directory |
 
-| Flag                 | Description                                                                       |
-| -------------------- | --------------------------------------------------------------------------------- |
-| `--tsconfig`, `-t`   | Path to `tsconfig.json` for path alias resolution.                                |
-| `--bunfig`, `-b`     | Path to `bunfig.toml` for Bun alias resolution.                                   |
-| `--workspaces`, `-w` | Path to a `package.json` or `pnpm-workspace.yaml` to discover workspace packages. |
+Anything other than `analyze` prints a short usage line and exits with code `1`.
 
 ## Example
 
 ```bash
-bunx sinwan-compiler analyze ./src ./.sinwan/reactive-props.json --tsconfig ./tsconfig.json --workspaces ../../package.json
+bunx sinwan-compiler analyze ./src ./.sinwan/reactive-props.json \
+  --tsconfig ./tsconfig.json \
+  --workspaces ../../package.json
 ```
 
-## Output format
+## Output
 
-The CLI writes a JSON file mapping each source file to its exported component names and their reactive props:
+JSON: absolute file path → export name → reactive prop names.
 
 ```json
 {
   "/project/src/Child.tsx": {
-    "Child": ["title"]
+    "Child": ["title"],
+    "default": ["label"]
   }
 }
 ```
 
-## Use in plugins
-
-Pass the generated JSON to the Bun or Vite plugin via the `analyze` option:
+Pass that file to a plugin:
 
 ```ts
 sinwan({ analyze: "./.sinwan/reactive-props.json" });
 ```
+
+Programmatic equivalent: `analyze({ root, outFile, tsConfigPath, bunfigPath, workspaces })` from [API](api.md).

package/docs/plugins.md

@@ -1,60 +1,63 @@
-# Bun and Vite plugins
+# Using the compiler from Bun and Vite
 
-Both plugins use the shared compiler package. The cache is optional and enabled by passing the `cache` option.
+App projects should depend on **`bun-plugin-sinwan`** or **`vite-plugin-sinwan`**. Those packages import `sinwan-compiler` and pass the right options. You do not add `sinwan-compiler` unless you customize the pipeline.
 
-## Bun plugin
+## Bun
 
 ```ts
 import { sinwan } from "bun-plugin-sinwan";
 
-Bun.build({
-  entrypoints: ["./src/index.tsx"],
-  plugins: [
-    sinwan({
-      hoist: true,
-      cache: {
-        root: "./src",
-        tsConfigPath: "./tsconfig.json",
-        bunfigPath: "./bunfig.toml",
-        workspaces: "../../package.json",
-        cachePath: "./.sinwan/cache.json",
-      },
-    }),
-  ],
+export default sinwan({
+  hoist: true,
+  cache: {
+    root: process.cwd(),
+    tsConfigPath: "./tsconfig.json",
+    bunfigPath: "./bunfig.toml",
+    workspaces: "../../package.json",
+    cachePath: "./.sinwan/cache.json",
+  },
 });
 ```
 
-## Vite plugin
+`bunfig.toml` `[serve.static] plugins` can only load a **ready-made** plugin object. Scaffolded apps keep a small `sinwan-plugin.ts` that calls `sinwan({ cache: … })` and export that object.
+
+The Bun plugin pins `sinwan` / `sinwan/*` to the **app** `node_modules` so a `file:` or `link:` package (for example `sinwan-router`) does not load a second runtime.
+
+## Vite
 
 ```ts
 import { sinwan } from "vite-plugin-sinwan";
+import { defineConfig } from "vite";
 
-export default {
+export default defineConfig({
   plugins: [
     sinwan({
       hoist: true,
       cache: {
         tsConfigPath: "./tsconfig.json",
-        bunfigPath: "./bunfig.toml",
-        workspaces: "../../package.json",
         cachePath: "./.sinwan/cache.json",
       },
     }),
   ],
-};
+});
 ```
 
-## Cache options
+The Vite plugin sets `resolve.dedupe: ["sinwan"]` for the same duplicate-runtime problem.
 
-| Option         | Description                                                                                           |
-| -------------- | ----------------------------------------------------------------------------------------------------- |
-| `root`         | Project root for the analyzer.                                                                        |
-| `tsConfigPath` | Path to `tsconfig.json`.                                                                              |
-| `bunfigPath`   | Path to `bunfig.toml`. If omitted, the plugin tries to auto-detect `bunfig.toml` in the project root. |
-| `workspaces`   | Path to a workspace file (`package.json` or `pnpm-workspace.yaml`) or explicit package paths/globs.   |
-| `cachePath`    | Path to a JSON file for persistent cache.                                                             |
+## Shared plugin options
+
+| Option | Default | Role |
+| ------ | ------- | ---- |
+| `hoist` | `true` | Template hoisting |
+| `explicitBindings` | `false` | `_$bind*` helpers instead of bare `() =>` |
+| `analyze` | unset | Path to CLI JSON (production) |
+| `cache` | `true` | Incremental analyzer in dev. `false` turns it off. An object sets `root`, `tsConfigPath`, `bunfigPath`, `workspaces`, `cachePath` |
+| `fastRefresh` | `true` (Vite) | In-place component HMR in `vite serve` only |
 
 ## Dev vs production
 
-- In **dev**, enable the `cache` option for incremental HMR analysis.
-- In **production**, run the CLI ahead of time and pass the generated JSON via the `analyze` option for deterministic builds.
+**Dev** — leave `cache` on (the default). Each transformed file calls `AnalyzerCache.update`. No CLI step.
+
+**Production** — run [the CLI](cli.md) (or `analyze()`) and set `analyze` to that JSON so every CI machine uses the same metadata.
+
+If a file is deleted in HMR, the plugin should call `cache.remove(path)` so child components drop reactive props that only that caller needed. The compiler’s `remove` updates both importers and imported modules.

package/docs/transform.md

@@ -1,64 +1,139 @@
 # JSX transform
 
-The transform rewrites JSX so the Sinwan runtime can wrap reactive reads in effects at render time.
+`transformJSX(code, filename, options?)` rewrites one module so the Sinwan runtime can track reactive reads and reuse static markup.
 
-## Reactive wrapping
+You normally get this through a plugin. Call it yourself only in tests or custom tooling.
 
-The compiler wraps expressions that read reactive values in zero-arity arrow functions. For example:
+## Quick example
 
 ```tsx
-<p>{state.name}</p>
+import { cc } from "sinwan/component";
+import { signal } from "sinwan/reactivity";
+
+export const Counter = cc(() => {
+  const count = signal(0);
+  return <p>{count.value}</p>;
+});
 ```
 
-becomes:
+The compiler turns the child into a lazy getter:
 
 ```tsx
-<p>{() => state.name}</p>
+<p>{() => count.value}</p>
 ```
 
-The runtime calls these functions inside an effect so the DOM updates when the value changes.
+The runtime runs that function inside an effect and updates the text when `count` changes.
 
-## What is reactive
+## Automatic `cc()` wrapping
 
-The compiler recognizes values from:
+Exported functions that look like components are wrapped for you. You can write React-style components and still get a Sinwan instance and `displayName`.
 
-- `createMutable` / `createStore` from `sinwan/store`
-- `signal` / `computed` from `sinwan/reactivity`
-- `useState` from `sinwan/react-client`
+A candidate must be:
 
-Reactive reads include:
+- **Exported** (named or default)
+- **Uppercase** (or an anonymous `export default function ()`)
+- **0 or 1 parameter**
+- **Returning JSX** in that function (not only in a nested helper)
+- **Not already** `cc(...)` (or a local alias of `cc`)
 
-- Member expressions: `state.name`, `signal.value`
-- Function calls: `getCount()`
-- Derived expressions: `count() + 1`
+```tsx
+export function App() {
+  return <h1>Hello</h1>;
+}
+
+// becomes
+import { cc } from "sinwan/component";
+export const App = cc(function App() {
+  return <h1>Hello</h1>;
+});
+```
 
-## What is NOT wrapped
+Not wrapped: lowercase helpers, generators, multi-argument functions, or functions that never return JSX. If `cc` is not imported yet, the compiler adds `import { cc } from "sinwan/component"`.
 
-- Plain literals: `"Hello"`, `123`
-- Event handlers: `onClick={handleClick}`
-- Static bindings that the analyzer proved are non-reactive
+`cc` may be imported from `sinwan` or `sinwan/component`.
 
-## Cross-file optimization
+## What counts as reactive
 
-When the analyzer is enabled, the transform can skip wrapping a prop if the analyzer determined that all callers pass a static value. This reduces runtime overhead.
+Tracked imports:
 
-```tsx
-// Without analyzer: onClick={handleClick} is safe to skip wrapping
-// With analyzer: title="Hello" is also known static, so it is skipped
-<Child title="Hello" onClick={handleClick} />
-```
+| Module | Names |
+| ------ | ----- |
+| `sinwan/store` | `createMutable`, `createStore` |
+| `sinwan/reactivity` | `signal`, `computed` |
+| `sinwan/react` | `useState` |
+| `sinwan/hook` | `useFetch` |
+
+Reads the compiler wraps:
+
+- Store / mutable fields: `state.name`, destructured `const { name } = state`
+- Signals and computeds: `count.value`, including `count.value?.n` and `count.value!.n`
+- `useState` getters: `count()`
+- `useFetch` signal values: `f.data.value` (not the shell `f` or `f.data`)
+- Calls to a **local** function whose body reads one of the above
+
+Not wrapped:
+
+- Literals and plain identifiers
+- Event-handler functions (`onClick={fn}` or `onClick={() => …}`)
+- Nested function *values* passed as props (`title={() => s.value}` stays a render prop)
+- `useFetch` methods such as `abort` / `execute`
+- Static values the [analyzer](analyzer.md) proved never change
+
+## DOM vs component JSX
+
+**Native elements** (`div`, `p`, `button`, …): wrap reactive children and attributes.
+
+**User components** (`<Child title={…} />`): wrap a prop only if that prop is reactive for `Child` (local call graph, analyzer metadata, or a conservative fallback for exported components). Children forwarded to a user component stay unwrapped so the child can read `children` itself.
+
+**Built-in control-flow** components wrap specific props, and they *do* wrap reactive expression children (those children render directly):
+
+| Component | Reactive props |
+| --------- | -------------- |
+| `For`, `Index`, `Virtual` | `each` |
+| `Show`, `Switch`, `Match`, `Key` | `when` |
+| `Dynamic` | `component` |
+| `Visible` | `when`, `style` |
+| `Portal` | `mount` |
+| `Activity` | `mode` |
+
+`Suspense` is not in this list; its props are left alone.
+
+## Template hoisting
+
+Static native trees become a module-level template plus `_$createTemplate(tmpl, [dynamic…])`.
+
+Slots:
+
+| Type | When |
+| ---- | ---- |
+| `child` | `{expr}`, or a capitalized child component |
+| `attr` | Dynamic attribute (not `on*`) |
+| `event` | `onClick={…}` and other `on*` handlers |
+| `ref` | `ref={fn}` or `ref={object}` |
+
+Static `style` objects and strings are written into the HTML (`backgroundColor` → `background-color`). Quoted style strings that contain `${…}` log a warning in the compiler: use a template literal, `style={\`…${x}\`}`.
+
+Hoisting is skipped (the JSX is left as JSX) when the root is a component, the tag is a member expression (`Icons.Star` as the root), or a spread is on a native element (`<div {...props}>`). In `dev: true`, skipped hoists log a warning.
+
+Boolean attributes without a value are emitted as HTML flags: `<button disabled>`.
+
+The slot marker format is `COMPILER_TEMPLATE_SLOT_PROTOCOL` (`s:0`, `s:1`, …). It must stay aligned with the runtime protocol in `sinwan`.
 
 ## Options
 
 ```ts
-transformJSX(code, filename, {
-  hoist: true,              // template hoisting
-  explicitBindings: false,  // emit compiler-driven binding descriptors
-  analyze: "path/to/reactive-props.json", // production metadata
-  analyzeMetadata: cache?.reactiveProps,  // dev cache metadata
+transformJSX(code, "src/App.tsx", {
+  hoist: true, // default true
+  dev: false, // warn when hoisting is skipped
+  explicitBindings: false, // emit _$bindText / _$bindAttr / …
+  analyze: "./.sinwan/reactive-props.json",
+  analyzeMetadata: cache.reactiveProps,
+  resolveImport: (source, fromFile) => absolutePathOrNull,
 });
 ```
 
-## Template hoisting
+- **`analyze` / `analyzeMetadata`** — cross-file reactive props. Invalid JSON is ignored (transform still succeeds).
+- **`resolveImport`** — maps `./Child` to an absolute file so imported components can use analyzer metadata. Without it, imported call sites are not wrapped at the parent.
+- **`explicitBindings`** — wrap with `_$bindText` / `_$bindAttr` / `_$bindStyle` / `_$bindClass` from `sinwan/renderer` instead of a bare `() => …`.
 
-Static JSX subtrees are hoisted into a top-level template factory so they are not recreated on every render.
+Returns `{ code, map }` with a source map.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sinwan-compiler",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Shared compiler core for Sinwan plugins",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,7 +30,7 @@
     "sinwan": "./dist/cli.js"
   },
   "scripts": {
-    "test": "bun test",
+    "test": "bun run scripts/run-tests.ts",
     "typecheck": "tsc --noEmit",
     "build": "bun run build.ts",
     "clean": "rm -rf dist",