sinwan-compiler 0.0.0 → 0.2.0

package/docs/architecture.md

@@ -0,0 +1,75 @@
+# Architecture
+
+## File 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
+```
+
+## 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.
+
+## Key data structures
+
+### `CallSite`
+
+```ts
+{
+  callee: t.Function;
+  props: { name: string; value: t.Expression }[];
+  spreads: t.Expression[];
+}
+```
+
+`spreads` stores the spread expressions. Object-literal spreads are analyzed precisely; unknown spreads are treated conservatively.
+
+### `ModuleAnalysis`
+
+Per-file analysis including:
+
+- imports
+- exports
+- default export
+- component functions
+- local scopes
+- local call graph
+- imported call sites
+
+### `AnalyzerCache`
+
+- 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.
+
+## Propagation algorithm
+
+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.
+
+## Import resolution
+
+The resolver combines multiple sources:
+
+- `tsconfig.json` `paths`
+- `bunfig.toml` aliases
+- Relative imports
+- Custom resolver
+
+Resolution order: tsconfig → bunfig → relative → custom.
+
+## Serialization
+
+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.

package/docs/cli.md

@@ -0,0 +1,46 @@
+# CLI
+
+The `sinwan-compiler` package ships a small CLI for production analysis.
+
+## Command
+
+```bash
+bunx sinwan-compiler 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`).
+
+## Options
+
+| 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. |
+
+## Example
+
+```bash
+bunx sinwan-compiler analyze ./src ./.sinwan/reactive-props.json --tsconfig ./tsconfig.json --workspaces ../../package.json
+```
+
+## Output format
+
+The CLI writes a JSON file mapping each source file to its exported component names and their reactive props:
+
+```json
+{
+  "/project/src/Child.tsx": {
+    "Child": ["title"]
+  }
+}
+```
+
+## Use in plugins
+
+Pass the generated JSON to the Bun or Vite plugin via the `analyze` option:
+
+```ts
+sinwan({ analyze: "./.sinwan/reactive-props.json" });
+```

package/docs/plugins.md

@@ -0,0 +1,60 @@
+# Bun and Vite plugins
+
+Both plugins use the shared compiler package. The cache is optional and enabled by passing the `cache` option.
+
+## Bun plugin
+
+```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",
+      },
+    }),
+  ],
+});
+```
+
+## Vite plugin
+
+```ts
+import { sinwan } from "vite-plugin-sinwan";
+
+export default {
+  plugins: [
+    sinwan({
+      hoist: true,
+      cache: {
+        tsConfigPath: "./tsconfig.json",
+        bunfigPath: "./bunfig.toml",
+        workspaces: "../../package.json",
+        cachePath: "./.sinwan/cache.json",
+      },
+    }),
+  ],
+};
+```
+
+## Cache options
+
+| 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.                                                             |
+
+## 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.

package/docs/transform.md

@@ -0,0 +1,64 @@
+# JSX transform
+
+The transform rewrites JSX so the Sinwan runtime can wrap reactive reads in effects at render time.
+
+## Reactive wrapping
+
+The compiler wraps expressions that read reactive values in zero-arity arrow functions. For example:
+
+```tsx
+<p>{state.name}</p>
+```
+
+becomes:
+
+```tsx
+<p>{() => state.name}</p>
+```
+
+The runtime calls these functions inside an effect so the DOM updates when the value changes.
+
+## What is reactive
+
+The compiler recognizes values from:
+
+- `createMutable` / `createStore` from `sinwan/store`
+- `signal` / `computed` from `sinwan/reactivity`
+- `useState` from `sinwan/react-client`
+
+Reactive reads include:
+
+- Member expressions: `state.name`, `signal.value`
+- Function calls: `getCount()`
+- Derived expressions: `count() + 1`
+
+## What is NOT wrapped
+
+- Plain literals: `"Hello"`, `123`
+- Event handlers: `onClick={handleClick}`
+- Static bindings that the analyzer proved are non-reactive
+
+## Cross-file optimization
+
+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.
+
+```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} />
+```
+
+## 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
+});
+```
+
+## Template hoisting
+
+Static JSX subtrees are hoisted into a top-level template factory so they are not recreated on every render.

package/package.json

@@ -1,11 +1,53 @@
 {
   "name": "sinwan-compiler",
-  "version": "0.0.0",
-  "module": "index.ts",
+  "version": "0.2.0",
+  "description": "Shared compiler core for Sinwan plugins",
   "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "keywords": [
+    "sinwan",
+    "compiler",
+    "jsx",
+    "reactive",
+    "signals"
+  ],
+  "author": "Mohammed Ben Cheikh",
+  "license": "MIT",
+  "bugs": "https://github.com/sinwanjs/sinwan-compiler/issues",
+  "homepage": "https://sinwanjs.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sinwanjs/sinwan-compiler"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "bin": {
+    "sinwan": "./dist/cli.js"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "build": "bun run build.ts",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun run clean && bun run typecheck && bun run test && bun run build"
+  },
   "devDependencies": {
+    "@types/babel__generator": "^7.27.0",
+    "@types/babel__traverse": "^7.28.0",
     "@types/bun": "latest"
   },
+  "dependencies": {
+    "@babel/core": "^7.24.0",
+    "@babel/generator": "^7.24.0",
+    "@babel/parser": "^7.24.0",
+    "@babel/traverse": "^7.24.0",
+    "@babel/types": "^7.24.0"
+  },
   "peerDependencies": {
     "typescript": "^5"
   }