@solidjs/start 2.0.4 → 2.0.6

package/dist/directives/plugin.js

@@ -1,12 +1,14 @@
 import * as t from "@babel/types";
 import { bubbleFunctionDeclaration } from "./bubble-function-declaration.js";
 import { generateUniqueName } from "./generate-unique-name.js";
-import { getDescriptiveName } from "./get-descriptive-name.js";
+import { getHierarchicalName } from "./get-hierarchical-name.js";
 import { getImportIdentifier } from "./get-import-identifier.js";
 import { getRootStatementPath } from "./get-root-statement-path.js";
 import { isStatementTopLevel } from "./is-statement-top-level.js";
 import { isPathValid, unwrapPath } from "./paths.js";
 import { removeUnusedVariables } from "./remove-unused-variables.js";
+import xxHash32 from "./xxhash32.js";
+import { assertHoistable, assertNoMethodDirectives, collectMisplacedDirectives, } from "./validate.js";
 function isValidFunction(node) {
     return t.isArrowFunctionExpression(node) || t.isFunctionExpression(node);
 }
@@ -41,12 +43,19 @@ function isFunctionDirectiveValid(ctx, path) {
     }
     return false;
 }
-function createID(ctx, name) {
-    const base = `${ctx.hash}-${ctx.count++}`;
+function createID(ctx, path) {
+    const name = getHierarchicalName(path);
+    // Two functions can still share a name path, such as two arrows passed to
+    // the same call, so repeats are numbered.
+    const seen = ctx.names.get(name) ?? 0;
+    ctx.names.set(name, seen + 1);
+    const unique = seen === 0 ? name : `${name}$${seen}`;
+    ctx.count++;
     if (ctx.env === "development") {
-        return `${base}-${name}`;
+        return `${ctx.hash}-${unique}`;
     }
-    return base;
+    // Production ids stay opaque, so source names are not shipped to the browser.
+    return `${ctx.hash}-${xxHash32(unique).toString(16)}`;
 }
 function transformFunction(ctx, path, direct) {
     if (!direct) {
@@ -55,10 +64,13 @@ function transformFunction(ctx, path, direct) {
         }
         cleanFunctionDirectives(ctx, path);
     }
+    // The function is about to be moved to the top level of the module, so
+    // everything it reads has to still resolve from there.
+    assertHoistable(path, ctx.directive);
     // First, get root statement
     const rootStatement = getRootStatementPath(path);
     // Create a unique ID for the function
-    const fnID = createID(ctx, getDescriptiveName(path, "anonymous"));
+    const fnID = createID(ctx, path);
     if (ctx.mode === "server") {
         // Create a "source" function on the root-level
         const sourceReference = t.callExpression(getImportIdentifier(ctx.imports, path, ctx.definitions.register), [t.stringLiteral(fnID), path.node]);
@@ -109,163 +121,186 @@ function traceBinding(path, name) {
             return undefined;
     }
 }
-function transformBindingForServer(ctx, binding) {
-    if (isPathValid(binding.path, t.isVariableDeclarator)) {
-        const right = unwrapPath(binding.path.get("init"), isValidFunction);
-        if (right) {
-            transformFunction(ctx, right, true);
-        }
+/**
+ * An export a `"${directive}"` module cannot serve is left out of the client
+ * build, so client code importing it gets a missing binding. The transform
+ * cannot tell a wrapped function such as `query(fn, key)` from a plain value,
+ * so this reports the export instead of failing the build.
+ */
+function droppedExport(ctx, path, detail) {
+    const line = path.node.loc?.start.line;
+    ctx.warnings.push(`A "${ctx.directive}" module can only serve the functions it declares, so this export is left out of the client build` +
+        `${line == null ? "" : ` (line ${line})`}. ${detail}`);
+}
+function isTypeOnlyDeclaration(node) {
+    switch (node?.type) {
+        case "TSInterfaceDeclaration":
+        case "TSTypeAliasDeclaration":
+        case "TSDeclareFunction":
+        case "TSModuleDeclaration":
+            return true;
+        default:
+            return false;
     }
 }
-function transformModuleLevelDirective(ctx, program) {
-    cleanDirectives(program, ctx.directive);
+function resolveExportedFunction(path, name) {
+    const binding = traceBinding(path, name);
+    if (binding && isPathValid(binding.path, t.isVariableDeclarator)) {
+        return unwrapPath(binding.path.get("init"), isValidFunction);
+    }
+    return undefined;
+}
+/**
+ * Every function a `"use server"` module exports, in source order, with the
+ * names it is exported under. Both modes walk this list in the same order,
+ * which is what keeps the ids generated on the two sides pointing at each
+ * other.
+ */
+function collectModuleExports(ctx, program) {
+    const entries = [];
+    const byNode = new Map();
+    function add(name, path) {
+        const existing = byNode.get(path.node);
+        if (existing) {
+            existing.names.push(name);
+            return;
+        }
+        const entry = { names: [name], path };
+        byNode.set(path.node, entry);
+        entries.push(entry);
+    }
     program.traverse({
-        FunctionDeclaration(child) {
-            // We only need to move top-level functions
-            if (isStatementTopLevel(child)) {
-                bubbleFunctionDeclaration(child);
+        ExportAllDeclaration(path) {
+            if (path.node.exportKind === "type") {
+                return;
             }
+            droppedExport(ctx, path, '"export * from" re-exports nothing the client can call. Re-export from a module without the directive instead.');
         },
-    });
-    program.scope.crawl();
-    if (ctx.mode === "server") {
-        // Trace bindings
-        const bindings = new Set();
-        program.traverse({
-            ExportDefaultDeclaration(path) {
-                const id = unwrapPath(path.get("declaration"), t.isIdentifier);
-                if (id) {
-                    const binding = traceBinding(path, id.node.name);
-                    if (binding) {
-                        bindings.add(binding);
-                    }
-                }
-            },
-            ExportNamedDeclaration(path) {
-                if (path.node.source || path.node.exportKind === "type") {
-                    return;
+        ExportDefaultDeclaration(path) {
+            const declaration = path.get("declaration");
+            const id = unwrapPath(declaration, t.isIdentifier);
+            if (id) {
+                const fn = resolveExportedFunction(path, id.node.name);
+                if (fn) {
+                    add("default", fn);
                 }
-                for (const specifier of path.get("specifiers")) {
-                    if (isPathValid(specifier, t.isExportSpecifier)) {
-                        const binding = traceBinding(specifier, specifier.node.local.name);
-                        if (binding) {
-                            bindings.add(binding);
-                        }
-                    }
+                else {
+                    droppedExport(ctx, path, `"${id.node.name}" is not a function declared in this module.`);
                 }
-                const declarations = path.get("declaration");
-                if (isPathValid(declarations, t.isVariableDeclaration)) {
-                    for (const declaration of declarations.get("declarations")) {
-                        // Check if left is identifier
-                        const left = unwrapPath(declaration.get("id"), t.isIdentifier);
-                        if (left) {
-                            const binding = traceBinding(left, left.node.name);
-                            if (binding) {
-                                bindings.add(binding);
-                            }
-                        }
-                    }
+                return;
+            }
+            // `export default async function () {}` is only a declaration by
+            // position and has no binding to trace, so read it as an expression.
+            if (isPathValid(declaration, t.isFunctionDeclaration) && !declaration.node.id) {
+                const node = declaration.node;
+                declaration.replaceWith(t.functionExpression(null, node.params, node.body, node.generator, node.async));
+            }
+            const fn = unwrapPath(path.get("declaration"), isValidFunction);
+            if (fn) {
+                add("default", fn);
+            }
+            else {
+                droppedExport(ctx, path, "The default export is not a function declared in this module.");
+            }
+        },
+        ExportNamedDeclaration(path) {
+            if (path.node.exportKind === "type") {
+                return;
+            }
+            if (path.node.source) {
+                droppedExport(ctx, path, "Re-exporting from another module is not supported. Export a function declared here that calls it instead.");
+                return;
+            }
+            for (const specifier of path.get("specifiers")) {
+                if (!isPathValid(specifier, t.isExportSpecifier)) {
+                    droppedExport(ctx, specifier, "Only named exports of functions are supported.");
+                    continue;
                 }
-            },
-        });
-        for (const binding of bindings) {
-            transformBindingForServer(ctx, binding);
-        }
-    }
-    else {
-        // Trace bindings
-        const uniqueBindings = new Set();
-        const exportedBindings = new Map();
-        program.traverse({
-            ExportDefaultDeclaration(path) {
-                const id = unwrapPath(path.get("declaration"), t.isIdentifier);
-                if (id) {
-                    const binding = traceBinding(path, id.node.name);
-                    if (binding) {
-                        uniqueBindings.add(binding);
-                        exportedBindings.set("default", binding);
-                    }
+                if (specifier.node.exportKind === "type") {
+                    continue;
                 }
-            },
-            ExportNamedDeclaration(path) {
-                if (path.node.source || path.node.exportKind === "type") {
-                    return;
+                const local = specifier.node.local.name;
+                const fn = resolveExportedFunction(specifier, local);
+                if (!fn) {
+                    droppedExport(ctx, specifier, `"${local}" is not a function declared in this module.`);
+                    continue;
                 }
-                for (const specifier of path.get("specifiers")) {
-                    if (isPathValid(specifier, t.isExportSpecifier)) {
-                        const binding = traceBinding(specifier, specifier.node.local.name);
-                        if (binding) {
-                            const key = t.isIdentifier(specifier.node.exported)
-                                ? specifier.node.exported.name
-                                : specifier.node.exported.value;
-                            uniqueBindings.add(binding);
-                            exportedBindings.set(key, binding);
-                        }
+                const exported = specifier.node.exported;
+                add(t.isIdentifier(exported) ? exported.name : exported.value, fn);
+            }
+            const declaration = path.get("declaration");
+            if (isPathValid(declaration, t.isVariableDeclaration)) {
+                for (const declarator of declaration.get("declarations")) {
+                    const left = unwrapPath(declarator.get("id"), t.isIdentifier);
+                    if (!left) {
+                        droppedExport(ctx, declarator, "Destructured exports are not supported.");
+                        continue;
                     }
-                }
-                const declarations = path.get("declaration");
-                if (isPathValid(declarations, t.isVariableDeclaration)) {
-                    for (const declaration of declarations.get("declarations")) {
-                        // Check if left is identifier
-                        const left = unwrapPath(declaration.get("id"), t.isIdentifier);
-                        if (left) {
-                            const binding = traceBinding(left, left.node.name);
-                            if (binding) {
-                                uniqueBindings.add(binding);
-                                exportedBindings.set(left.node.name, binding);
-                            }
-                        }
+                    const fn = resolveExportedFunction(left, left.node.name);
+                    if (!fn) {
+                        droppedExport(ctx, declarator, `"${left.node.name}" is not a function.`);
+                        continue;
                     }
-                }
-            },
-        });
-        // generate ids for each unique binding
-        const sourceIDs = new Map();
-        for (const binding of uniqueBindings) {
-            if (isPathValid(binding.path, t.isVariableDeclarator)) {
-                const init = unwrapPath(binding.path.get("init"), isValidFunction);
-                if (init) {
-                    sourceIDs.set(binding, createID(ctx, getDescriptiveName(init, "anonymous")));
+                    add(left.node.name, fn);
                 }
             }
-        }
-        // clear body
-        program.node.body = [];
-        const declarations = [];
-        const specifiers = [];
-        const declarationMap = new Map();
-        // Declare all client functions
-        for (const [exported, binding] of exportedBindings) {
-            let currentIdentifier = declarationMap.get(binding);
-            if (!currentIdentifier) {
-                currentIdentifier = generateUniqueName(program, "fn");
-                const fnID = sourceIDs.get(binding);
-                if (fnID) {
-                    declarations.push(t.variableDeclarator(currentIdentifier, t.callExpression(getImportIdentifier(ctx.imports, program, ctx.definitions.clone), [
-                        t.stringLiteral(fnID),
-                    ])));
-                    declarationMap.set(binding, currentIdentifier);
-                }
+            else if (declaration.node &&
+                !isPathValid(declaration, t.isFunctionDeclaration) &&
+                !isTypeOnlyDeclaration(declaration.node)) {
+                droppedExport(ctx, declaration, "Only functions can be exported.");
             }
-            if (currentIdentifier) {
-                specifiers.push(t.exportSpecifier(currentIdentifier, t.stringLiteral(exported)));
+        },
+    });
+    return entries;
+}
+function transformModuleLevelDirective(ctx, program) {
+    cleanDirectives(program, ctx.directive);
+    program.traverse({
+        FunctionDeclaration(child) {
+            // We only need to move top-level functions
+            if (isStatementTopLevel(child)) {
+                bubbleFunctionDeclaration(child);
             }
+        },
+    });
+    program.scope.crawl();
+    const entries = collectModuleExports(ctx, program);
+    if (ctx.mode === "server") {
+        for (const entry of entries) {
+            transformFunction(ctx, entry.path, true);
         }
-        const body = [];
-        if (declarations.length > 0) {
-            body.push(t.variableDeclaration("const", declarations));
-        }
-        if (specifiers.length > 0) {
-            body.push(t.exportNamedDeclaration(null, specifiers, null));
+        return;
+    }
+    const ids = entries.map(entry => createID(ctx, entry.path));
+    // clear body
+    program.node.body = [];
+    const declarations = [];
+    const specifiers = [];
+    for (let i = 0, len = entries.length; i < len; i++) {
+        const local = generateUniqueName(program, "fn");
+        declarations.push(t.variableDeclarator(local, t.callExpression(getImportIdentifier(ctx.imports, program, ctx.definitions.clone), [
+            t.stringLiteral(ids[i]),
+        ])));
+        for (const name of entries[i].names) {
+            specifiers.push(t.exportSpecifier(local, t.stringLiteral(name)));
         }
-        program.pushContainer("body", body);
     }
+    const body = [];
+    if (declarations.length > 0) {
+        body.push(t.variableDeclaration("const", declarations));
+    }
+    if (specifiers.length > 0) {
+        body.push(t.exportNamedDeclaration(null, specifiers, null));
+    }
+    program.pushContainer("body", body);
 }
 export function directivesPlugin() {
     return {
         name: "solid-start:directives",
         visitor: {
             Program(program, ctx) {
+                assertNoMethodDirectives(program, ctx.opts.directive);
+                ctx.opts.warnings.push(...collectMisplacedDirectives(program, ctx.opts.directive));
                 const isModuleLevel = isDirectiveValid(ctx.opts, program.node.directives);
                 if (isModuleLevel) {
                     transformModuleLevelDirective(ctx.opts, program);

package/dist/directives/validate.d.ts

@@ -0,0 +1,17 @@
+import type * as babel from "@babel/core";
+import * as t from "@babel/types";
+type HoistableFunction = t.ArrowFunctionExpression | t.FunctionExpression;
+export declare function assertHoistable(path: babel.NodePath<HoistableFunction>, directive: string): void;
+/**
+ * A directive only applies to a function body. The transform ignores one in a
+ * method, which ships the method body and every module it imports to the
+ * browser.
+ */
+export declare function assertNoMethodDirectives(program: babel.NodePath<t.Program>, directive: string): void;
+/**
+ * A directive string that is not in a directive prologue does nothing. It is
+ * almost always meant to be one, so report it. Otherwise the module compiles as
+ * if it had no server functions.
+ */
+export declare function collectMisplacedDirectives(program: babel.NodePath<t.Program>, directive: string): string[];
+export {};

package/dist/directives/validate.js

@@ -0,0 +1,176 @@
+import * as t from "@babel/types";
+/**
+ * A server function is moved to the top level of its module. Anything it reads
+ * from an enclosing scope stops resolving once it is moved. These checks report
+ * that at build time. Without them the code compiles and then fails at runtime,
+ * or stops parsing.
+ */
+function isTypeOnlyPosition(path, boundary) {
+    let current = path;
+    while (current && current !== boundary) {
+        if (current.node.type.startsWith("TS") || current.node.type.startsWith("Type")) {
+            return true;
+        }
+        current = current.parentPath;
+    }
+    return false;
+}
+/**
+ * The nearest ancestor that decides what `this` and `arguments` mean.
+ * Arrow functions are transparent. Every other function form is not.
+ */
+function getThisBoundary(path) {
+    let previous = path;
+    let current = path.parentPath;
+    while (current) {
+        switch (current.node.type) {
+            case "FunctionExpression":
+            case "FunctionDeclaration":
+            case "ObjectMethod":
+            case "ClassMethod":
+            case "ClassPrivateMethod":
+            case "StaticBlock":
+            case "Program":
+                return current;
+            case "ClassProperty":
+            case "ClassPrivateProperty":
+                // Only the initializer is bound to the instance.
+                if (previous.node === current.node.value) {
+                    return current;
+                }
+                break;
+            default:
+                break;
+        }
+        previous = current;
+        current = current.parentPath;
+    }
+    return null;
+}
+function findAncestor(path, boundary, types) {
+    let current = path.parentPath;
+    while (current && current !== boundary) {
+        if (types.includes(current.node.type)) {
+            return current;
+        }
+        current = current.parentPath;
+    }
+    return null;
+}
+export function assertHoistable(path, directive) {
+    const program = path.scope.getProgramParent().path;
+    // A function expression keeps its own `this` and `arguments` wherever it is
+    // moved. An arrow takes both from where it is written.
+    const isArrow = path.node.type === "ArrowFunctionExpression";
+    const boundary = getThisBoundary(path);
+    // An arrow written at the top level already reads `this` from the module.
+    const lexicalSelfIsModule = boundary === null || boundary.node.type === "Program";
+    /**
+     * Whether `this` or `arguments` at this position is bound by something that
+     * stays behind when the server function moves. A function expression keeps
+     * both wherever it lands, and a nested function binds its own.
+     */
+    function isLexicallyOutside(child) {
+        const binder = getThisBoundary(child);
+        if (binder && binder !== path && binder.isDescendant(path)) {
+            return false;
+        }
+        if (binder === path && !isArrow) {
+            return false;
+        }
+        return !lexicalSelfIsModule;
+    }
+    function unsupported(target, what, hint) {
+        throw target.buildCodeFrameError(`${what} cannot be used inside a "${directive}" function, because the function is moved to the top level of the module. ${hint}`);
+    }
+    // `super` and private members are reported first. When both apply to the same
+    // expression, such as `this.#value`, they are the more specific cause.
+    path.traverse({
+        Super(child) {
+            const home = findAncestor(child, path, ["ObjectMethod", "ClassMethod", "ClassPrivateMethod"]);
+            if (!home) {
+                unsupported(child, "`super`", "Move the server function out of the method and pass what it needs as an argument.");
+            }
+        },
+        PrivateName(child) {
+            const owner = findAncestor(child, path, ["ClassBody"]);
+            if (!owner) {
+                unsupported(child, "A private class member", "Read it outside the server function and pass it as an argument.");
+            }
+        },
+    });
+    path.traverse({
+        ThisExpression(child) {
+            if (!isLexicallyOutside(child)) {
+                return;
+            }
+            unsupported(child, "`this`", "Pass the value it refers to as an argument instead.");
+        },
+        Identifier(child) {
+            if (!child.isReferencedIdentifier() || isTypeOnlyPosition(child, path)) {
+                return;
+            }
+            const { name } = child.node;
+            if (name === "arguments") {
+                if (!isLexicallyOutside(child)) {
+                    return;
+                }
+                unsupported(child, "`arguments`", "Declare the parameters the server function needs instead.");
+            }
+            const binding = child.scope.getBinding(name);
+            // No binding means a global, which is still a global after the move.
+            if (!binding) {
+                return;
+            }
+            // Declared by the function itself, so it moves along with it.
+            if (binding.path === path || binding.path.isDescendant(path)) {
+                return;
+            }
+            // Declared at the top level of the module, where the function lands.
+            if (binding.scope.path === program) {
+                return;
+            }
+            throw child.buildCodeFrameError(`"${name}" is declared outside the "${directive}" function that uses it, and the function is moved to the top level of the module, so "${name}" is not in scope when it runs. Pass it as an argument instead.`);
+        },
+    });
+}
+/**
+ * A directive only applies to a function body. The transform ignores one in a
+ * method, which ships the method body and every module it imports to the
+ * browser.
+ */
+export function assertNoMethodDirectives(program, directive) {
+    function check(child) {
+        for (const current of child.node.body.directives) {
+            if (current.value.value === directive) {
+                throw child.buildCodeFrameError(`"${directive}" is not supported in a method. Move the body into a function and call it from the method:\n` +
+                    `  const handler = async () => { "${directive}"; /* ... */ };`);
+            }
+        }
+    }
+    program.traverse({
+        ObjectMethod: check,
+        ClassMethod: check,
+        ClassPrivateMethod: check,
+    });
+}
+/**
+ * A directive string that is not in a directive prologue does nothing. It is
+ * almost always meant to be one, so report it. Otherwise the module compiles as
+ * if it had no server functions.
+ */
+export function collectMisplacedDirectives(program, directive) {
+    const warnings = [];
+    program.traverse({
+        ExpressionStatement(child) {
+            const expression = child.node.expression;
+            if (!t.isStringLiteral(expression) || expression.value !== directive) {
+                return;
+            }
+            const line = child.node.loc?.start.line;
+            warnings.push(`"${directive}" on line ${line ?? "?"} is ignored because it is not the first statement of a function body or of the module. ` +
+                `Move it to the top of the body, before any other statement.`);
+        },
+    });
+    return warnings;
+}