sinwan-compiler 0.0.0 → 0.2.0

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env bun
+/**
+ * SinwanJS CLI — project-wide reactive prop analyzer.
+ *
+ * Usage:
+ *   bunx sinwan-compiler analyze [root] [outFile]
+ *
+ * Writes `.sinwan/reactive-props.json` by default.
+ */
+export declare function runAnalyzeCli(args?: string[]): void;

package/dist/cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env bun
+// @bun
+import {
+  runAnalyzeCli
+} from "./chunk-ba0546ea.js";
+export {
+  runAnalyzeCli
+};

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * SinwanJS Compiler — shared core.
+ *
+ * Exports the JSX transform, reactive prop analysis, and metadata helpers
+ * used by the Bun and Vite plugins.
+ */
+export { transformJSX, type TransformOptions } from "./transform";
+export { analyze, analyzeProject, analyzeModule, loadMetadata, AnalyzerCache, type AnalyzeOptions, type ModuleAnalysis, type ProjectAnalysis, type ImportedCallSite, type ImportInfo, type WorkspacesConfig, } from "./analyze";
+export { runAnalyzeCli } from "./cli";
+export { wrapReactiveExpressions, trackReactiveImports, collectComponentFunctions, computeLocalScopes, collectComponentCallGraph, propagateReactiveProps, buildFullScope, containsReactiveValue, getAllPropNames, isReactiveValue, type ReactiveScope, type Binding, type CallSite, type ImportNames, type ComponentExpressionInfo, } from "./reactive-wrap";

package/dist/index.js

@@ -0,0 +1,329 @@
+// @bun
+import {
+  AnalyzerCache,
+  analyze,
+  analyzeModule,
+  analyzeProject,
+  buildFullScope,
+  collectComponentCallGraph,
+  collectComponentFunctions,
+  computeLocalScopes,
+  containsReactiveValue,
+  getAllPropNames,
+  isReactiveValue,
+  loadMetadata,
+  propagateReactiveProps,
+  runAnalyzeCli,
+  trackReactiveImports,
+  wrapReactiveExpressions
+} from "./chunk-ba0546ea.js";
+
+// src/transform.ts
+import { parse } from "@babel/parser";
+import _generate from "@babel/generator";
+import * as t from "@babel/types";
+import _traverse from "@babel/traverse";
+var generate = typeof _generate === "function" ? _generate : _generate.default ?? _generate;
+var traverse = typeof _traverse === "function" ? _traverse : _traverse.default ?? _traverse;
+var SLOT_PREFIX = "s";
+var slotId = 0;
+function nextSlotId() {
+  return `<!--${SLOT_PREFIX}:${slotId++}-->`;
+}
+var VOID_ELEMENTS = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr"
+]);
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function cleanJSXText(value) {
+  const lines = value.split(/\r\n|\n|\r/);
+  let lastNonEmptyLine = 0;
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    if (/[^ \t]/.exec(line)) {
+      lastNonEmptyLine = i;
+    }
+  }
+  let str = "";
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const isFirstLine = i === 0;
+    const isLastLine = i === lines.length - 1;
+    const isLastNonEmptyLine = i === lastNonEmptyLine;
+    let trimmedLine = line.replace(/\t/g, " ");
+    if (!isFirstLine) {
+      trimmedLine = trimmedLine.replace(/^ +/, "");
+    }
+    if (!isLastLine) {
+      trimmedLine = trimmedLine.replace(/ +$/, "");
+    }
+    if (trimmedLine) {
+      if (!isLastNonEmptyLine) {
+        trimmedLine += " ";
+      }
+      str += trimmedLine;
+    }
+  }
+  return str;
+}
+function extractTemplate(node, filename) {
+  slotId = 0;
+  const slots = [];
+  const html = elementToHtml(node, slots, [], filename);
+  return { html, slots };
+}
+function warnSuspectedStyleInterpolation(attrValue, filename, line) {
+  if (!attrValue.includes("${"))
+    return;
+  const location = line ? `:${line}` : "";
+  console.warn('[Sinwan] JSX string literal style attribute contains "${...}" which will not be interpolated. ' + "Use style={`...${...}`} instead. (" + filename + location + ")");
+}
+function isLiteralStyleValue(expr) {
+  return t.isStringLiteral(expr) || t.isNumericLiteral(expr) || t.isBooleanLiteral(expr) || t.isNullLiteral(expr);
+}
+function isStaticStyleValue(expr) {
+  if (t.isStringLiteral(expr))
+    return true;
+  if (t.isTemplateLiteral(expr) && expr.expressions.length === 0)
+    return true;
+  if (!t.isObjectExpression(expr))
+    return false;
+  for (const prop of expr.properties) {
+    if (!t.isObjectProperty(prop))
+      return false;
+    if (prop.computed)
+      return false;
+    if (!isLiteralStyleValue(prop.value))
+      return false;
+  }
+  return true;
+}
+function toKebabCase(value) {
+  return value.includes("-") ? value : value.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
+}
+function serializeStyleValue(expr) {
+  if (t.isStringLiteral(expr))
+    return expr.value;
+  if (t.isTemplateLiteral(expr) && expr.expressions.length === 0) {
+    return expr.quasis[0]?.value?.raw ?? "";
+  }
+  if (!t.isObjectExpression(expr))
+    return "";
+  const parts = [];
+  for (const prop of expr.properties) {
+    if (!t.isObjectProperty(prop))
+      continue;
+    const key = prop.key;
+    let name = null;
+    if (t.isIdentifier(key))
+      name = key.name;
+    else if (t.isStringLiteral(key))
+      name = key.value;
+    if (!name)
+      continue;
+    const val = prop.value;
+    if (t.isNullLiteral(val))
+      continue;
+    if (t.isBooleanLiteral(val) && !val.value)
+      continue;
+    let valueStr = "";
+    if (t.isStringLiteral(val))
+      valueStr = val.value;
+    else if (t.isNumericLiteral(val))
+      valueStr = String(val.value);
+    else if (t.isBooleanLiteral(val))
+      valueStr = String(val.value);
+    if (valueStr === "")
+      continue;
+    parts.push(`${toKebabCase(name)}:${valueStr}`);
+  }
+  return parts.join(";");
+}
+function elementToHtml(node, slots, path, filename) {
+  const tagName = jsxNameToString(node.openingElement.name);
+  if (tagName === "")
+    return "";
+  const firstChar = tagName.charAt(0);
+  if (firstChar && firstChar === firstChar.toUpperCase()) {
+    throw new Error("Cannot hoist element containing component calls");
+  }
+  const isVoid = VOID_ELEMENTS.has(tagName);
+  let html = `<${tagName}`;
+  for (const attr of node.openingElement.attributes) {
+    if (attr.type === "JSXSpreadAttribute") {
+      throw new Error("Cannot hoist element with spread attributes");
+    }
+    const attrName = attr.name.name;
+    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")
+        continue;
+      if (attrName === "style" && t.isExpression(expr) && isStaticStyleValue(expr)) {
+        const serialized = serializeStyleValue(expr);
+        html += ` ${attrName}="${escapeHtml(serialized)}"`;
+        continue;
+      }
+      slots.push({
+        path: [...path],
+        type: attrName.startsWith("on") ? "event" : "attr",
+        name: attrName,
+        expr
+      });
+      html += ` ${attrName}=""`;
+      continue;
+    }
+    if (attr.value?.type === "JSXText" || attr.value?.type === "StringLiteral") {
+      const rawValue = attr.value.value;
+      if (attrName === "style") {
+        warnSuspectedStyleInterpolation(rawValue, filename, attr.value.loc?.start?.line);
+      }
+      html += ` ${attrName}="${escapeHtml(rawValue)}"`;
+    } else if (!attr.value) {
+      html += ` ${attrName}`;
+    }
+  }
+  html += isVoid ? " />" : ">";
+  if (isVoid)
+    return html;
+  let childIndex = 0;
+  for (const child of node.children) {
+    if (child.type === "JSXText") {
+      const text = cleanJSXText(child.value ?? "");
+      if (text) {
+        html += escapeHtml(text);
+        childIndex++;
+      }
+    } else if (child.type === "JSXExpressionContainer") {
+      if (child.expression.type === "JSXEmptyExpression")
+        continue;
+      const slot = nextSlotId();
+      slots.push({
+        path: [...path, childIndex],
+        type: "child",
+        expr: child.expression
+      });
+      html += slot;
+      childIndex++;
+    } else if (child.type === "JSXElement") {
+      html += elementToHtml(child, slots, [...path, childIndex], filename);
+      childIndex++;
+    }
+  }
+  html += `</${tagName}>`;
+  return html;
+}
+function jsxNameToString(name) {
+  if (name.type === "JSXIdentifier")
+    return name.name;
+  if (name.type === "JSXMemberExpression") {
+    return jsxNameToString(name.object) + "." + jsxNameToString(name.property);
+  }
+  return "";
+}
+function transformJSX(code, filename, options = {}) {
+  const ast = parse(code, {
+    sourceType: "module",
+    plugins: ["jsx", "typescript"],
+    sourceFilename: filename
+  });
+  wrapReactiveExpressions(ast, {
+    explicitBindings: options.explicitBindings,
+    analyze: options.analyze,
+    analyzeMetadata: options.analyzeMetadata,
+    filename
+  });
+  const hoist = options.hoist !== false;
+  const templates = [];
+  let templateCounter = 0;
+  traverse(ast, {
+    JSXElement(path) {
+      if (!hoist)
+        return;
+      if (path.findParent((p) => p.isJSXElement()))
+        return;
+      const opening = path.node.openingElement;
+      const tagName = opening.name;
+      if (tagName.type !== "JSXIdentifier")
+        return;
+      const name = tagName.name;
+      if (!name || name[0] !== name[0].toLowerCase())
+        return;
+      try {
+        const extracted = extractTemplate(path.node, filename);
+        const tmplId = `_$tmpl_${templateCounter++}`;
+        templates.push({ id: tmplId, template: extracted });
+        const dynamicExprs = extracted.slots.filter((s) => s.expr).map((s) => s.expr);
+        const templateExpr = t.callExpression(t.identifier("_$createTemplate"), [t.identifier(tmplId), t.arrayExpression(dynamicExprs)]);
+        const parentIsJSX = path.parentPath?.isJSXElement() || path.parentPath?.isJSXFragment();
+        path.replaceWith(parentIsJSX ? t.jsxExpressionContainer(templateExpr) : templateExpr);
+      } catch {}
+    }
+  });
+  if (templates.length === 0) {
+    const result2 = generate(ast, {
+      sourceMaps: true,
+      sourceFileName: filename
+    });
+    return { code: result2.code, map: result2.map };
+  }
+  const templateDecls = templates.map(({ id, template }) => t.variableDeclaration("const", [
+    t.variableDeclarator(t.identifier(id), t.objectExpression([
+      t.objectProperty(t.identifier("html"), t.stringLiteral(template.html)),
+      t.objectProperty(t.identifier("slots"), t.arrayExpression(template.slots.map((slot) => t.objectExpression([
+        t.objectProperty(t.identifier("path"), t.arrayExpression(slot.path.map((i) => t.numericLiteral(i)))),
+        t.objectProperty(t.identifier("type"), t.stringLiteral(slot.type)),
+        ...slot.name ? [
+          t.objectProperty(t.identifier("name"), t.stringLiteral(slot.name))
+        ] : []
+      ]))))
+    ]))
+  ]));
+  const importSpecifiers = [
+    t.importSpecifier(t.identifier("_$createTemplate"), t.identifier("_$createTemplate"))
+  ];
+  if (options.explicitBindings) {
+    importSpecifiers.push(t.importSpecifier(t.identifier("_$bindText"), t.identifier("_$bindText")), t.importSpecifier(t.identifier("_$bindAttr"), t.identifier("_$bindAttr")), t.importSpecifier(t.identifier("_$bindStyle"), t.identifier("_$bindStyle")), t.importSpecifier(t.identifier("_$bindClass"), t.identifier("_$bindClass")));
+  }
+  const importDecl = t.importDeclaration(importSpecifiers, t.stringLiteral("sinwan/renderer"));
+  ast.program.body.unshift(importDecl, ...templateDecls);
+  const result = generate(ast, { sourceMaps: true, sourceFileName: filename });
+  return { code: result.code, map: result.map };
+}
+export {
+  wrapReactiveExpressions,
+  transformJSX,
+  trackReactiveImports,
+  runAnalyzeCli,
+  propagateReactiveProps,
+  loadMetadata,
+  isReactiveValue,
+  getAllPropNames,
+  containsReactiveValue,
+  computeLocalScopes,
+  collectComponentFunctions,
+  collectComponentCallGraph,
+  buildFullScope,
+  analyzeProject,
+  analyzeModule,
+  analyze,
+  AnalyzerCache
+};

package/dist/reactive-wrap.d.ts

@@ -0,0 +1,80 @@
+/**
+ * SinwanJS Compiler — Reactive JSX Expression Wrapping
+ *
+ * Wraps JSX expressions that read reactive values in zero-arity arrow
+ * functions so the runtime renderer can create an effect and update the DOM
+ * when the value changes.
+ *
+ * Supported reactive sources:
+ *   - `createMutable` / `createStore` from `sinwan/store`
+ *   - `signal` / `computed` from `sinwan/reactivity`
+ *   - `useState` from `sinwan/react-client`
+ *
+ * Example:
+ *   <p>{state.name}</p>        → <p>{() => state.name}</p>
+ *   <p>{count.value}</p>        → <p>{() => count.value}</p>
+ *   <p>{getCount()}</p>         → <p>{() => getCount()}</p>
+ */
+import * as t from "@babel/types";
+export interface ImportNames {
+    createMutable: Set<string>;
+    createStore: Set<string>;
+    signal: Set<string>;
+    computed: Set<string>;
+    useState: Set<string>;
+    cc: Set<string>;
+}
+export declare function trackReactiveImports(ast: t.Node): ImportNames;
+export interface MutableBinding {
+    kind: "mutable";
+    root: string;
+    path: string[];
+}
+export interface SignalBinding {
+    kind: "signal";
+}
+export interface ComputedBinding {
+    kind: "computed";
+}
+export interface GetterBinding {
+    kind: "getter";
+}
+export interface PropBinding {
+    kind: "prop";
+}
+export type Binding = MutableBinding | SignalBinding | ComputedBinding | GetterBinding | PropBinding;
+export interface ReactiveScope {
+    bindings: Map<string, Binding>;
+}
+export declare function getAllPropNames(params: t.Node | undefined): Set<string>;
+export declare function isReactiveValue(node: t.Identifier | t.MemberExpression, scope: ReactiveScope): boolean;
+export declare function containsReactiveValue(expr: t.Expression, scope: ReactiveScope): boolean;
+export interface ComponentExpressionInfo {
+    isComponent: boolean;
+    componentName: string | null;
+    attributeName: string | null;
+}
+export declare function collectComponentFunctions(ast: t.Node, ccNames: Set<string>): {
+    functions: Set<t.Function>;
+    names: Map<string, t.Function>;
+    exported: Set<t.Function>;
+};
+export declare function computeLocalScopes(ast: t.Node, names: ImportNames): Map<t.Function, ReactiveScope>;
+export type CallSite = {
+    callee: t.Function;
+    props: {
+        name: string;
+        value: t.Expression;
+    }[];
+    /** Spread expressions forwarded to the child. */
+    spreads: t.Expression[];
+};
+export declare function collectComponentCallGraph(ast: t.Node, componentNames: Map<string, t.Function>): Map<t.Function, CallSite[]>;
+export declare function buildFullScope(localScopes: Map<t.Function, ReactiveScope>, fn: t.Function, reactiveProps: Set<string>): ReactiveScope | null;
+export declare function propagateReactiveProps(localScopes: Map<t.Function, ReactiveScope>, callGraph: Map<t.Function, CallSite[]>, componentFunctions: Set<t.Function>): Map<t.Function, Set<string>>;
+export declare function wrapReactiveExpressions(ast: t.Node, options?: {
+    explicitBindings?: boolean;
+    analyze?: string;
+    analyzeMetadata?: Map<string, Map<string, Set<string>>>;
+    filename?: string;
+}): void;

package/dist/transform.d.ts

@@ -0,0 +1,23 @@
+/**
+ * SinwanJS Compiler — JSX Transform
+ *
+ * Transforms JSX AST to use template hoisting.
+ * Static JSX elements are extracted to module-level template strings
+ * and replaced with optimized template creation calls.
+ */
+export interface TransformOptions {
+    /** Enable template hoisting (default: true) */
+    hoist?: boolean;
+    /** Enable dev mode (source maps, etc.) */
+    dev?: boolean;
+    /** Emit explicit compiler-driven binding descriptors (Phase 2). */
+    explicitBindings?: boolean;
+    /** Path to the reactive-props metadata file produced by `sinwan analyze`. */
+    analyze?: string;
+    /** In-memory reactive-props metadata (used by plugin-level caches). */
+    analyzeMetadata?: Map<string, Map<string, Set<string>>>;
+}
+export declare function transformJSX(code: string, filename: string, options?: TransformOptions): {
+    code: string;
+    map?: any;
+};

package/docs/README.md

@@ -0,0 +1,26 @@
+# sinwan-compiler
+
+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.
+
+## What it does
+
+- **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.
+
+## Packages
+
+- `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.
+
+## Documentation
+
+- [`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.

package/docs/analyzer.md

@@ -0,0 +1,97 @@
+# Cross-file reactive-prop 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>`.
+
+## 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.
+
+A prop is reactive for a given component if any of its callers passes a value that reads a reactive source.
+
+## Example
+
+```tsx
+// Child.tsx
+import { cc } from "sinwan/component";
+export const Child = cc(({ title }) => <h1>{title}</h1>);
+
+// Parent.tsx
+import { cc } from "sinwan/component";
+import { signal } from "sinwan/reactivity";
+import { Child } from "./Child";
+const Parent = cc(() => <Child title={signal.value} />);
+```
+
+The analyzer produces:
+
+```json
+{
+  "/project/Child.tsx": { "Child": ["title"] }
+}
+```
+
+## Workspace packages
+
+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.
+
+```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"],
+  },
+});
+```
+
+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`.
+
+
+
+## Import resolution
+
+The analyzer resolves imports in this order:
+
+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.
+
+You can also provide a custom resolver:
+
+```ts
+analyzeProject({
+  root: "/project",
+  resolve: (source, fromFile) => {
+    // return absolute path or null
+  },
+});
+```
+
+## Spread props
+
+Spread props are handled precisely when possible:
+
+- `<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.
+
+## Limitations
+
+- 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.

package/docs/api.md

@@ -0,0 +1,84 @@
+# API reference
+
+## `transformJSX(code, filename, options?)`
+
+Transforms a single JSX/TSX file.
+
+```ts
+import { transformJSX } from "sinwan-compiler";
+
+const result = transformJSX(code, filename, {
+  hoist: true,
+  explicitBindings: false,
+  analyze: "./.sinwan/reactive-props.json",
+  analyzeMetadata: new Map(),
+});
+```
+
+Returns `{ code: string; map?: any }`.
+
+## `analyze(options)`
+
+Production entry point. Analyzes the project and writes metadata to disk.
+
+```ts
+import { analyze } from "sinwan-compiler";
+
+analyze({
+  root: "./src",
+  outFile: "./.sinwan/reactive-props.json",
+  tsConfigPath: "./tsconfig.json",
+  bunfigPath: "./bunfig.toml",
+  workspaces: "../../package.json",
+});
+```
+
+## `analyzeProject(options)`
+
+Programmatic analyzer. Returns the full project analysis without writing to disk.
+
+```ts
+import { analyzeProject } from "sinwan-compiler";
+
+const project = analyzeProject({
+  root: "./src",
+  files: { "/project/A.tsx": "..." },
+  tsConfigPath: "./tsconfig.json",
+});
+
+project.reactiveProps.get("/project/A.tsx")?.get("Component");
+```
+
+## `AnalyzerCache`
+
+Incremental analyzer for dev/HMR.
+
+```ts
+import { AnalyzerCache } from "sinwan-compiler";
+
+const cache = new AnalyzerCache({
+  root: "./src",
+  tsConfigPath: "./tsconfig.json",
+  bunfigPath: "./bunfig.toml",
+  workspaces: "../../package.json",
+  cachePath: "./.sinwan/cache.json",
+});
+
+cache.update(filePath, newCode);
+const metadata = cache.reactiveProps;
+```
+
+### Methods
+
+- `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).
+
+## 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.