@firsthandjs/compiler 0.2.0 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 The build-time half of Firsthand. Nothing here ships to the browser.
 
-**Documentation:** [guide](https://github.com/firsthandjs/firsthand/blob/main/docs/guide/14-building.md) · [API reference](https://github.com/firsthandjs/firsthand/blob/main/docs/reference/compiler.md) · [all docs](https://github.com/firsthandjs/firsthand/blob/main/docs/README.md)
+**Documentation:** [guide](https://github.com/firsthandjs/firsthand/blob/main/docs/guide/16-building.md) · [API reference](https://github.com/firsthandjs/firsthand/blob/main/docs/reference/compiler.md) · [all docs](https://github.com/firsthandjs/firsthand/blob/main/docs/README.md)
 
 ```ts
 // vite.config.ts

package/dist/api.d.ts

@@ -7,7 +7,49 @@ export interface TransformOptions extends FirsthandPluginOptions {
      * source-map hops.
      */
     typescript?: boolean;
+    /** Produce a source map, so a debugger shows the JSX rather than the output. */
+    sourceMaps?: boolean;
 }
-/** Compiles one module. Used by the Vite plugin and by the compiler tests. */
+/**
+ * A source map, in the shape every bundler expects one.
+ *
+ * Spelled out rather than typed as `object`, which is what it was: a bundler
+ * plugin's `transform` has to return something assignable to Rollup's
+ * `SourceMapInput`, and `object` is not. The mistake type-checks everywhere
+ * inside this repository and fails in the first application that puts the
+ * plugin into `vite.config.ts` — which is the one place it matters.
+ */
+export interface SourceMap {
+    version: number;
+    mappings: string;
+    names: string[];
+    sources: string[];
+    sourcesContent?: string[];
+    sourceRoot?: string;
+    file?: string;
+}
+/** A compiled module, and the map back to what was written. */
+export interface Compiled {
+    code: string;
+    /**
+     * A source map, when one was asked for.
+     *
+     * Without it a debugger shows the compiled output: hoisted templates and
+     * calls into the runtime protocol, rather than the JSX someone wrote. That
+     * is the difference between a framework you can step through and one you
+     * cannot, so the Vite plugin always asks.
+     */
+    map: SourceMap | null;
+}
+/**
+ * Compiles one module, and maps it back.
+ *
+ * The map is Babel's, which tracks the nodes this transform moves. It is
+ * approximate where a template was hoisted out of the markup it came from —
+ * there is no original position for a `<template>` that the compiler invented
+ * — and exact everywhere a statement survived.
+ */
+export declare function compileModule(code: string, options?: TransformOptions): Compiled;
+/** Compiles one module. Used by the compiler's own tests. */
 export declare function transform(code: string, options?: TransformOptions): string;
 //# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAGA,OAAwB,EAAE,KAAK,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAE9E,MAAM,WAAW,gBAAiB,SAAQ,sBAAsB;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAW9E"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAGA,OAAwB,EAAE,KAAK,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAE9E,MAAM,WAAW,gBAAiB,SAAQ,sBAAsB;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gFAAgF;IAChF,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAKlB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,+DAA+D;AAC/D,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,GAAG,EAAE,SAAS,GAAG,IAAI,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,QAAQ,CAqBpF;AAED,6DAA6D;AAC7D,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAE9E"}

package/dist/{chunk-HHKCDDN2.js → chunk-UYA7HB5G.js}

@@ -128,7 +128,12 @@ function firsthandPlugin(_api, options = {}) {
         path.replaceWith(compileNode(path, state));
       },
       CallExpression(path, state) {
-        annotateComponent(path, state);
+        annotateComponent(path, state, options);
+      },
+      VariableDeclarator(path, state) {
+        if (options.devtools === true) {
+          nameCell(path, state);
+        }
       }
     }
   };
@@ -157,7 +162,7 @@ function runtime(state, name, source = RUNTIME) {
   }
   return t.cloneNode(local);
 }
-function annotateComponent(path, state) {
+function annotateComponent(path, state, options) {
   const callee = path.node.callee;
   if (!t.isIdentifier(callee, { name: "component" }) || path.node.arguments.length > 2) {
     return;
@@ -172,6 +177,9 @@ function annotateComponent(path, state) {
   }
   const name = declaredName(path);
   rewritePropsDestructuring(path, name, state);
+  if (options.strictReactivity !== false) {
+    checkKeptReads(path.get("arguments.0"), name);
+  }
   path.node.arguments = [
     setup,
     path.node.arguments[1] ?? t.identifier("undefined"),
@@ -179,6 +187,94 @@ function annotateComponent(path, state) {
     t.stringLiteral(name)
   ];
 }
+function checkKeptReads(setup, name) {
+  const parameter = setup.node.params[0];
+  const propsName = t.isIdentifier(parameter) ? parameter.name : null;
+  const body = setup.get("body");
+  if (!body.isBlockStatement()) {
+    return;
+  }
+  body.traverse({
+    Function(nested) {
+      nested.skip();
+    },
+    VariableDeclarator(declarator) {
+      const init = declarator.node.init;
+      if (init === null || init === void 0 || !readsOnly(init, propsName)) {
+        return;
+      }
+      const target = declarator.node.id;
+      const label = t.isIdentifier(target) ? `\`${target.name}\`` : "This value";
+      throw declarator.buildCodeFrameError(
+        `${name}: ${label} is read once, here, and then kept. A setup runs one time per instance, so this value will not change again.
+
+Move the read into the part, handler, effect or computed that should re-read it \u2014 or wrap it in snapshot(() => \u2026) if reading once is what you meant.`
+      );
+    }
+  });
+}
+function readsOnly(node, propsName) {
+  let read = false;
+  const walk = (current) => {
+    if (t.isIdentifier(current) || t.isLiteral(current)) {
+      if (t.isTemplateLiteral(current)) {
+        return current.expressions.every((part) => walk(part));
+      }
+      return true;
+    }
+    if (t.isMemberExpression(current)) {
+      const property = current.property;
+      if (!current.computed && t.isIdentifier(property, { name: "value" })) {
+        read = true;
+      }
+      if (propsName !== null && t.isIdentifier(current.object, { name: propsName })) {
+        read = true;
+      }
+      return walk(current.object) && (!current.computed || walk(property));
+    }
+    if (t.isUnaryExpression(current)) {
+      return walk(current.argument);
+    }
+    if (t.isBinaryExpression(current) || t.isLogicalExpression(current)) {
+      return walk(current.left) && walk(current.right);
+    }
+    if (t.isConditionalExpression(current)) {
+      return walk(current.test) && walk(current.consequent) && walk(current.alternate);
+    }
+    return false;
+  };
+  return walk(node) && read;
+}
+var NAMED = /* @__PURE__ */ new Map([
+  ["signal", "signal"],
+  ["computed", "computed"],
+  ["deepSignal", "signal"]
+]);
+function nameCell(path, state) {
+  const init = path.node.init;
+  const target = path.node.id;
+  if (!t.isCallExpression(init) || !t.isIdentifier(target) || !t.isIdentifier(init.callee)) {
+    return;
+  }
+  const kind = NAMED.get(init.callee.name);
+  if (kind === void 0) {
+    return;
+  }
+  const binding = path.scope.getBinding(init.callee.name);
+  if (binding === void 0 || !isFirsthandImport(binding)) {
+    return;
+  }
+  const line = init.loc.start.line;
+  const source = state.filename;
+  const cut = Math.max(source.lastIndexOf("/"), source.lastIndexOf(String.fromCharCode(92)));
+  const where = `${source.slice(cut + 1)}:${String(line)}`;
+  const call = t.callExpression(runtime(state, "label"), [
+    init,
+    t.stringLiteral(kind),
+    t.stringLiteral(`${target.name} (${where})`)
+  ]);
+  path.node.init = call;
+}
 function isFirsthandImport(binding) {
   const parent = binding.path.parentPath;
   if (!parent.isImportDeclaration()) {
@@ -225,7 +321,7 @@ function rewritePropsDestructuring(call, name, state) {
   for (const entry of references) {
     for (const reference of entry.paths) {
       if (entry.access !== propsId) {
-        reference.replaceWith(t.cloneNode(entry.access));
+        reference.replaceWith(located(t.cloneNode(entry.access), reference.node));
       }
     }
   }
@@ -498,7 +594,10 @@ function emitAttribute(attribute, build, self, state, deferred, tag) {
     build.statements.push(
       expressionStatement2(
         t.callExpression(runtime(state, "bind"), [
-          t.arrowFunctionExpression([], dynamicAttributeCall(name, value, self, state, tag))
+          located(
+            t.arrowFunctionExpression([], dynamicAttributeCall(name, value, self, state, tag)),
+            value
+          )
         ])
       )
     );
@@ -682,7 +781,7 @@ function emitChildren(children, build, self, state) {
       t.cloneNode(self),
       // A list part is already a thunk that owns its rows; wrapping it would
       // rebuild the whole list on every evaluation.
-      entry.kind === "list" ? entry.expression : t.arrowFunctionExpression([], entry.expression)
+      entry.kind === "list" ? entry.expression : thunk(entry.expression)
     ];
     if (!isLast) {
       build.html.push("<!>");
@@ -806,23 +905,50 @@ function compileChildren(children, state) {
   }
   return result;
 }
+function thunk(expression) {
+  const arrow = t.arrowFunctionExpression([], expression);
+  const loc = expression.loc;
+  if (loc !== null && loc !== void 0) {
+    arrow.loc = { ...loc, end: loc.start };
+    expression.loc = null;
+  }
+  return arrow;
+}
 function expressionStatement2(expression) {
-  return t.expressionStatement(expression);
+  return located(t.expressionStatement(expression), expression);
+}
+function located(node, source) {
+  if (source == null || source.loc == null) {
+    return node;
+  }
+  node.loc = source.loc;
+  return node;
 }
 
 // packages/compiler/src/api.ts
 import { transformSync } from "@babel/core";
 import jsxSyntax from "@babel/plugin-syntax-jsx";
 import typescriptSyntax from "@babel/plugin-syntax-typescript";
-function transform(code, options = {}) {
+function compileModule(code, options = {}) {
   const result = transformSync(code, {
-    ...options.filename === void 0 ? {} : { filename: options.filename },
+    ...options.filename === void 0 ? {} : {
+      filename: options.filename,
+      // The full path, not the basename Babel would default to. A map
+      // whose `sources` is `comp.tsx` resolves, relative to a module
+      // served at `/src/comp.tsx`, to that very URL — so a debugger ends
+      // up with two files under one address, shows both, and puts the
+      // breakpoint in the wrong one.
+      sourceFileName: options.filename
+    },
     babelrc: false,
     configFile: false,
-    sourceMaps: false,
+    sourceMaps: options.sourceMaps === true,
     plugins: buildPlugins(options)
   });
-  return result.code;
+  return { code: result.code, map: result.map };
+}
+function transform(code, options = {}) {
+  return compileModule(code, options).code;
 }
 function buildPlugins(options) {
   const plugins = [];
@@ -830,12 +956,20 @@ function buildPlugins(options) {
     plugins.push([typescriptSyntax, { isTSX: true }]);
   }
   plugins.push(jsxSyntax);
-  plugins.push([firsthandPlugin, { packageName: options.packageName }]);
+  plugins.push([
+    firsthandPlugin,
+    {
+      packageName: options.packageName,
+      strictReactivity: options.strictReactivity,
+      devtools: options.devtools
+    }
+  ]);
   return plugins;
 }
 
 export {
   stableId,
   firsthandPlugin,
+  compileModule,
   transform
 };

package/dist/index.d.ts

@@ -7,6 +7,7 @@
  */
 export { default as firsthandPlugin } from './transform.js';
 export type { FirsthandPluginOptions } from './transform.js';
-export { transform } from './api.js';
+export { compileModule, transform } from './api.js';
+export type { Compiled, SourceMap, TransformOptions } from './api.js';
 export { stableId } from './ids.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC5D,YAAY,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC5D,YAAY,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACpD,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -1,9 +1,11 @@
 import {
+  compileModule,
   firsthandPlugin,
   stableId,
   transform
-} from "./chunk-HHKCDDN2.js";
+} from "./chunk-UYA7HB5G.js";
 export {
+  compileModule,
   firsthandPlugin,
   stableId,
   transform

package/dist/transform.d.ts

@@ -27,6 +27,28 @@ declare module '@babel/core' {
 export interface FirsthandPluginOptions {
     /** Package name used when hashing stable component ids (ADR-0004). */
     packageName?: string;
+    /**
+     * Refuse to compile a value that is read once in a setup and then kept.
+     *
+     * **On by default.** The rule only sees declarations whose initialiser is
+     * nothing but a read, which is the shape that is almost always a mistake;
+     * anything containing a call is left alone. `false` turns it off for a
+     * codebase that has such a read on purpose and would rather not mark it with
+     * `snapshot()` — see `checkKeptReads` (ADR-0019).
+     */
+    strictReactivity?: boolean;
+    /**
+     * Name the cells a module creates, for devtools.
+     *
+     * A runtime cannot see that `const count = signal(0)` is called `count`, and
+     * `new Error().stack` reports a position in the *compiled* module — the
+     * browser does not apply source maps to `error.stack`, so the line it names
+     * is not the line that was written. The compiler knows both, so it says so.
+     *
+     * Off by default and turned on by the Vite plugin while serving: a
+     * production build emits nothing.
+     */
+    devtools?: boolean;
 }
 export default function firsthandPlugin(_api: unknown, options?: FirsthandPluginOptions): PluginObject;
 export {};

package/dist/transform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../src/transform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,aAAa,CAAC;AAE5D,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAelC,UAAU,cAAc;IACtB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;IACnC,SAAS,EAAE,CAAC,CAAC,kBAAkB,EAAE,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,OAAO,QAAQ,aAAa,CAAC;IAC3B,UAAU,UAAU;QAClB,SAAS,EAAE,cAAc,CAAC;KAC3B;CACF;AAUD,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,CAAC,OAAO,UAAU,eAAe,CACrC,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,sBAA2B,GACnC,YAAY,CAgDd"}
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../src/transform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,aAAa,CAAC;AAE5D,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAelC,UAAU,cAAc;IACtB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;IACnC,SAAS,EAAE,CAAC,CAAC,kBAAkB,EAAE,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,OAAO,QAAQ,aAAa,CAAC;IAC3B,UAAU,UAAU;QAClB,SAAS,EAAE,cAAc,CAAC;KAC3B;CACF;AAUD,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,CAAC,OAAO,UAAU,eAAe,CACrC,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,sBAA2B,GACnC,YAAY,CAsDd"}

package/dist/vite.d.ts

@@ -1,11 +1,15 @@
+import { type SourceMap } from './api.js';
 import type { FirsthandPluginOptions } from './transform.js';
 /** Minimal shape of the Vite plugin contract, so the package needs no Vite dependency. */
 export interface VitePluginLike {
     name: string;
     enforce: 'pre';
+    configResolved(config: {
+        command: string;
+    }): void;
     transform(code: string, id: string): {
         code: string;
-        map: null;
+        map: SourceMap | null;
     } | null;
 }
 /**

package/dist/vite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAE7D,0FAA0F;AAC1F,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,KAAK,CAAC;IACf,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CACzE;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,sBAA2B,GAAG,cAAc,CAmB9E"}
+{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AACzD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAE7D,0FAA0F;AAC1F,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,KAAK,CAAC;IACf,cAAc,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAClD,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CACrF;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,sBAA2B,GAAG,cAAc,CA0B9E"}

package/dist/vite.js

@@ -1,25 +1,28 @@
 import {
-  transform
-} from "./chunk-HHKCDDN2.js";
+  compileModule
+} from "./chunk-UYA7HB5G.js";
 
 // packages/compiler/src/vite.ts
 function firsthand(options = {}) {
+  let serving = false;
   return {
     name: "firsthand",
     enforce: "pre",
+    configResolved(config) {
+      serving = config.command === "serve";
+    },
     transform(code, id) {
       const file = id.split("?")[0];
       if (!file.endsWith(".tsx") && !file.endsWith(".jsx")) {
         return null;
       }
-      return {
-        code: transform(code, {
-          filename: file,
-          typescript: file.endsWith(".tsx"),
-          ...options
-        }),
-        map: null
-      };
+      return compileModule(code, {
+        filename: file,
+        typescript: file.endsWith(".tsx"),
+        devtools: serving,
+        sourceMaps: true,
+        ...options
+      });
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firsthandjs/compiler",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Build-time TSX transform for Firsthand: static markup into templates, dynamic expressions into DOM parts.",
   "license": "MIT",
   "type": "module",