@transclude/core 0.1.0

package/src/compiler/interp.js

@@ -0,0 +1,82 @@
+// Splits raw text / attribute values into static + `${expr}` parts.
+// Brace matching is quote-aware so `${a ? "}" : "x"}` does not terminate early.
+
+/**
+ * @typedef {{ type: 'text', value: string } | { type: 'expr', value: string }} Part
+ */
+
+/**
+ * Text and `${expr}` in source order.
+ *
+ * There is no escape for a literal `${`, so anything documenting the syntax has
+ * to pass its examples in as data rather than write them in a template.
+ *
+ * @param {string} str raw text or an attribute value
+ * @returns {Part[]} empty only for an empty string
+ * @throws if a `${` is never closed
+ */
+export function splitInterpolations(str) {
+  const parts = [];
+  let text = '';
+  let i = 0;
+
+  while (i < str.length) {
+    // \${ escapes an interpolation
+    if (str[i] === '\\' && str[i + 1] === '$' && str[i + 2] === '{') {
+      text += '${';
+      i += 3;
+      continue;
+    }
+    if (str[i] === '$' && str[i + 1] === '{') {
+      if (text) {
+        parts.push({ type: 'text', value: text });
+        text = '';
+      }
+      const { expr, end } = readExpr(str, i + 2);
+      parts.push({ type: 'expr', value: expr });
+      i = end;
+      continue;
+    }
+    text += str[i];
+    i++;
+  }
+
+  if (text) parts.push({ type: 'text', value: text });
+  return parts;
+}
+
+/**
+ * Whether a string holds an interpolation, without parsing one.
+ *
+ * A `\${` is a literal and does not count, which is what the leading character
+ * in the pattern is checking.
+ *
+ * @param {string} str
+ * @returns {boolean}
+ */
+export function hasInterpolation(str) {
+  return /(^|[^\\])\$\{/.test(str);
+}
+
+function readExpr(str, start) {
+  let depth = 1;
+  let quote = null;
+  let i = start;
+
+  while (i < str.length) {
+    const c = str[i];
+    if (quote) {
+      if (c === '\\') i++;
+      else if (c === quote) quote = null;
+    } else if (c === '"' || c === "'" || c === '`') {
+      quote = c;
+    } else if (c === '{') {
+      depth++;
+    } else if (c === '}') {
+      depth--;
+      if (depth === 0) return { expr: str.slice(start, i), end: i + 1 };
+    }
+    i++;
+  }
+  throw new Error('unterminated ${ ... } interpolation');
+}

package/src/compiler/script.js

@@ -0,0 +1,620 @@
+// Real ESM handling for <script server>, <script props> and <script>.
+//
+// These blocks are authored as modules so editors treat them as JS, but they end
+// up spliced into a generated module (or, for client blocks, into a function
+// body). Doing that with regex silently mangles `export default` inside a
+// comment, multi-line imports, and anything else that merely looks like one.
+// acorn gives exact node ranges, so every rewrite here is a string splice at a
+// position the parser vouched for.
+
+import { parse } from 'acorn';
+
+export class ScriptError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ScriptError';
+  }
+}
+
+const PARSE_OPTIONS = {
+  ecmaVersion: 'latest',
+  sourceType: 'module',
+  allowAwaitOutsideFunction: true,
+};
+
+/**
+ * Rewrites `export default <thing>` to `const <name> = <thing>` in place,
+ * leaving imports and named exports exactly where the author put them.
+ * Returns the exported names so callers can check them against the names the
+ * generated module already uses.
+ *
+ * @param {{ code: string, line?: number }} block
+ * @param {string} name what to bind the default export to
+ * @param {string} label for an error
+ * @param {{ flags?: string[] }} [options]
+ * @returns {{ code: string, exports: string[],
+ *   imports: Array<{ source: string, specifiers: string }>,
+ *   defaultNode: object|null, flags: object }}
+ */
+export function bindDefaultExport(block, name, label, { flags = [] } = {}) {
+  const { code: source, line = 1 } = block;
+  const ast = parseOrThrow(source, label, line);
+
+  // A flag is a fact about the element rather than part of this block's own
+  // shape. Each is read out here and blanked, not removed, so every offset
+  // after it still points where it did.
+  const found = {};
+  const cuts = [];
+  for (const flag of flags) {
+    const hit = literalExport(ast, flag, source, line, label);
+    found[flag] = hit ? hit.value : null;
+    if (hit) cuts.push([hit.start, hit.end]);
+  }
+  const code = cuts.length ? blank(source, cuts) : source;
+
+  // acorn rejects a duplicate `default` itself, so there is at most one.
+  const node = ast.body.find((s) => s.type === 'ExportDefaultDeclaration') ?? null;
+  const exports = namedExportsOf(ast, source, line, label).filter((n) => !flags.includes(n));
+  const imports = importsOf(ast);
+
+  if (!node) {
+    return { code: `${code}\nconst ${name} = null;`, exports, imports, defaultNode: null, flags: found };
+  }
+
+  // Slicing the *declaration* rather than the statement means
+  // `export default function f() {}` becomes `const x = function f() {}`,
+  // which is a valid expression for every form of default export.
+  const rewritten =
+    code.slice(0, node.start) +
+    `const ${name} = ` +
+    code.slice(node.declaration.start, node.declaration.end) +
+    ';' +
+    code.slice(node.end);
+
+  return { code: rewritten, exports, imports, defaultNode: node.declaration, flags: found };
+}
+
+/**
+ * `export const NAME = true` or `= false`, read out of a block.
+ *
+ * `null` when the block does not declare it, which is not the same as declaring
+ * it false. A component may say so in one block or the other, and telling those
+ * apart is what makes "declared in both" reportable.
+ */
+function literalExport(ast, flag, code, line, label) {
+  for (const statement of ast.body) {
+    if (!statement.type.startsWith('Export')) continue;
+
+    const value = booleanExport(statement, flag);
+    if (value !== null) return { value, start: statement.start, end: statement.end };
+
+    if (namesExport(statement, flag)) {
+      throw new ScriptError(
+        `${label}: \`${flag}\` must be \`true\` or \`false\`. It becomes a static ` +
+          `class field, the same for every element of this tag, so it cannot be decided at ` +
+          `run time (line ${lineOf(statement, code, line)})`,
+      );
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Turns a client <script> into a function body: imports are lifted out (they
+ * have to stay at module top level) and everything else is left alone, blanked
+ * in place so line and column numbers still line up with the .html file.
+ *
+ * `lift` names one export that is not setup code: the element's members. It goes
+ * to module scope, and so does anything it reads, because a prototype is shared by
+ * every instance and the function body is not.
+ *
+ * @param {Array<{ code: string, line?: number }>} blocks
+ * @param {string} label
+ * @param {{ lift?: object|null, binding?: string, flags?: string[] }} [options]
+ * @returns {{ imports: string, hoisted: string, body: string,
+ *   lifted: object|null, flags: object, warnings: string[] }}
+ */
+export function toFunctionBody(blocks, label, { lift = null, binding = '__members', flags = [] } = {}) {
+  const imports = [];
+  const hoisted = [];
+  const bodies = [];
+  const warnings = [];
+  let lifted = null;
+  // `null` until a block declares one, so "not said" and "said false" differ.
+  const found = Object.fromEntries(flags.map((flag) => [flag, null]));
+
+  for (const block of blocks) {
+    const { code, line = 1 } = block;
+    // This block becomes a function body, so a top-level `return` is legal here
+    // even though it would not be in a module. That is how cleanup is declared.
+    const ast = parseOrThrow(code, label, line, { allowReturnOutsideFunction: true });
+    const cuts = [];
+
+    warnUnsignalled(ast, code, line, warnings);
+
+    const plan = lift ? planLift(ast, lift) : null;
+    if (plan) {
+      if (lifted) {
+        throw new ScriptError(
+          `${label}: \`${lift}\` is exported twice (line ${lineOf(plan.statement, code, line)})`,
+        );
+      }
+      if (plan.reaches.length) {
+        throw new ScriptError(
+          `${label}: \`${lift}\` reaches \`${plan.reaches.join('`, `')}\`, which exists once ` +
+            `per element. Members live on the prototype and are shared by every instance, ` +
+            `so they reach their own element through \`this\` instead ` +
+            `(line ${lineOf(plan.statement, code, line)})`,
+        );
+      }
+
+      // Order is preserved, so the hoisted code means exactly what it would have
+      // meant written at the top of the block.
+      for (const dependency of plan.deps) {
+        hoisted.push(code.slice(dependency.start, dependency.end));
+        cuts.push([dependency.start, dependency.end]);
+      }
+      hoisted.push(`const ${binding} = ${code.slice(plan.init.start, plan.init.end)};`);
+      cuts.push([plan.statement.start, plan.statement.end]);
+      lifted = plan.init;
+    }
+
+    for (const statement of ast.body) {
+      if (statement.type === 'ImportDeclaration') {
+        imports.push(code.slice(statement.start, statement.end));
+        cuts.push([statement.start, statement.end]);
+        continue;
+      }
+      if (statement.type.startsWith('Export')) {
+        if (plan && statement === plan.statement) continue;
+
+        // A flag decides something about the tag rather than about one element,
+        // so it has to be a literal. A computed value would look like a
+        // per-element choice and could not be one.
+        let taken = false;
+        for (const flag of flags) {
+          const value = booleanExport(statement, flag);
+          if (value !== null) {
+            found[flag] = value;
+            cuts.push([statement.start, statement.end]);
+            taken = true;
+            break;
+          }
+          if (namesExport(statement, flag)) {
+            throw new ScriptError(
+              `${label}: \`${flag}\` must be \`true\` or \`false\`. It decides something ` +
+                `about the tag, the same for every element of it, so it cannot be decided at ` +
+                `run time (line ${lineOf(statement, code, line)})`,
+            );
+          }
+        }
+        if (taken) continue;
+
+        throw new ScriptError(
+          `${label}: a client <script> runs as setup code, so it cannot export` +
+            (lift ? ` anything but \`${[lift, ...flags].join('`, `')}\`` : '') +
+            ` (line ${lineOf(statement, code, line)})`,
+        );
+      }
+    }
+
+    bodies.push(blank(code, cuts));
+  }
+
+  return {
+    imports: imports.join('\n'),
+    hoisted: hoisted.join('\n\n'),
+    body: bodies.join('\n'),
+    lifted,
+    flags: found,
+    warnings,
+  };
+}
+
+/** Targets that outlive the element listening to them. */
+const OUTLIVES = new Set(['document', 'window', 'globalThis', 'screen', 'navigator', 'visualViewport']);
+
+/**
+ * A listener on something that outlives this element, with no `signal`.
+ *
+ * A listener on `host` is collected with the element, so it needs nothing. One
+ * on `document` is not: the element goes and the listener stays, holding the
+ * closure and everything it captured, and every element after it adds another.
+ * Nothing reports that, which is why it is worth saying at compile time.
+ */
+function warnUnsignalled(ast, code, line, warnings) {
+  const seen = new Set();
+
+  const looksSignalled = (arg) => {
+    if (!arg) return false;
+    // A boolean third argument is `capture`, which is the old spelling and
+    // carries no signal.
+    if (arg.type === 'Literal' && typeof arg.value === 'boolean') return false;
+    // Anything else that is not a plain object could hold one, so this only
+    // reports the shapes it can read.
+    if (arg.type !== 'ObjectExpression') return true;
+    return arg.properties.some(
+      (property) =>
+        property.type === 'SpreadElement' ||
+        property.key?.name === 'signal' ||
+        property.key?.value === 'signal',
+    );
+  };
+
+  const visit = (node) => {
+    if (!node || typeof node.type !== 'string') return;
+
+    if (
+      node.type === 'CallExpression' &&
+      node.callee?.type === 'MemberExpression' &&
+      node.callee.property?.name === 'addEventListener' &&
+      node.callee.object?.type === 'Identifier' &&
+      OUTLIVES.has(node.callee.object.name) &&
+      !looksSignalled(node.arguments[2])
+    ) {
+      const target = node.callee.object.name;
+      const event = node.arguments[0]?.value;
+      const at = lineOf(node, code, line);
+      const message =
+        `${target}.addEventListener(${event ? `"${event}"` : '…'}) has no \`signal\`, so the ` +
+        `listener stays after this element leaves the document. Pass \`{ signal }\` ` +
+        `(line ${at})`;
+      if (!seen.has(message)) {
+        seen.add(message);
+        warnings.push(message);
+      }
+    }
+
+    for (const key of Object.keys(node)) {
+      const value = node[key];
+      if (Array.isArray(value)) value.forEach(visit);
+      else if (value && typeof value.type === 'string') visit(value);
+    }
+  };
+
+  visit(ast);
+}
+
+/** What only exists once the element does, and so cannot be reached from a prototype. */
+const PER_INSTANCE = ['host', 'shadow', 'signal', 'internals'];
+
+/** `export const NAME = true` / `= false`, or null when it is not that. */
+function booleanExport(statement, name) {
+  const declared = namesExport(statement, name);
+  const init = declared?.init;
+  if (init?.type === 'Literal' && typeof init.value === 'boolean') return init.value;
+  return null;
+}
+
+function namesExport(statement, name) {
+  if (statement.type !== 'ExportNamedDeclaration') return null;
+  if (statement.declaration?.type !== 'VariableDeclaration') return null;
+  return (
+    statement.declaration.declarations.find(
+      (d) => d.id.type === 'Identifier' && d.id.name === name,
+    ) ?? null
+  );
+}
+
+/**
+ * The plan for hoisting one named export out of a client block: the statement
+ * itself, its initializer, and the top-level declarations it reads. Those have to
+ * come along, or the hoisted code names things that stayed behind.
+ *
+ * Shared with the shim, which copies the same slices so tsc resolves what the
+ * generated module resolves.
+ *
+ * @param {object} ast an acorn program
+ * @param {string} name the binding members land on
+ * @param {Set<string>|string[]} [perInstance] names a member may not reach
+ * @returns {object|null} what to hoist, or null when nothing is exported
+ */
+export function planLift(ast, name, perInstance = PER_INSTANCE) {
+  const statement = ast.body.find(
+    (node) =>
+      node.type === 'ExportNamedDeclaration' &&
+      node.declaration?.type === 'VariableDeclaration' &&
+      node.declaration.declarations.length === 1 &&
+      node.declaration.declarations[0].id.type === 'Identifier' &&
+      node.declaration.declarations[0].id.name === name &&
+      node.declaration.declarations[0].init,
+  );
+  if (!statement) return null;
+
+  const init = statement.declaration.declarations[0].init;
+  const owners = new Map();
+  for (const node of ast.body) {
+    if (node === statement) continue;
+    for (const declared of declaredNames(node)) owners.set(declared, node);
+  }
+
+  const instance = new Set(perInstance);
+  const reaches = new Set();
+  const reads = new Set();
+  const deps = [];
+  const seen = new Set();
+  const queue = [init];
+
+  while (queue.length) {
+    for (const free of freeNames(queue.shift(), new Set(), new Set())) {
+      reads.add(free);
+      if (instance.has(free)) reaches.add(free);
+      const owner = owners.get(free);
+      if (!owner || seen.has(owner)) continue;
+      seen.add(owner);
+      deps.push(owner);
+      queue.push(owner);
+    }
+  }
+
+  deps.sort((a, b) => a.start - b.start);
+  return { statement, init, deps, reads, reaches: [...reaches] };
+}
+
+/** The names a top-level statement binds. */
+function declaredNames(statement) {
+  const node = statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement;
+  if (node?.type === 'VariableDeclaration') {
+    return node.declarations.flatMap((declarator) => patternNames(declarator.id));
+  }
+  if (node?.type === 'FunctionDeclaration' || node?.type === 'ClassDeclaration') {
+    return node.id ? [node.id.name] : [];
+  }
+  return [];
+}
+
+function scopedNames(statements) {
+  return (statements ?? []).flatMap(declaredNames);
+}
+
+/**
+ * Identifiers a subtree reads from outside itself.
+ *
+ * Scopes are tracked rather than ignored: a method with a parameter named
+ * `host` is not reaching for the element, and reporting it as one would be a
+ * confusing error about code that is correct.
+ */
+function freeNames(node, bound, out) {
+  if (!node || typeof node !== 'object') return out;
+  if (Array.isArray(node)) {
+    for (const child of node) freeNames(child, bound, out);
+    return out;
+  }
+  if (typeof node.type !== 'string') return out;
+
+  switch (node.type) {
+    case 'Identifier':
+      if (!bound.has(node.name)) out.add(node.name);
+      return out;
+
+    // `a.b` reads `a`; `b` is a property name, not a binding.
+    case 'MemberExpression':
+      freeNames(node.object, bound, out);
+      if (node.computed) freeNames(node.property, bound, out);
+      return out;
+    case 'Property':
+    case 'PropertyDefinition':
+    case 'MethodDefinition':
+      if (node.computed) freeNames(node.key, bound, out);
+      freeNames(node.value, bound, out);
+      return out;
+
+    case 'FunctionDeclaration':
+    case 'FunctionExpression':
+    case 'ArrowFunctionExpression': {
+      const inner = new Set(bound);
+      if (node.id) inner.add(node.id.name);
+      for (const param of node.params) for (const name of patternNames(param)) inner.add(name);
+      if (node.body.type === 'BlockStatement') for (const name of scopedNames(node.body.body)) inner.add(name);
+      // A default is evaluated in the function's own scope, so it sees the params.
+      for (const param of node.params) freeNames(param, inner, out);
+      freeNames(node.body, inner, out);
+      return out;
+    }
+    case 'BlockStatement': {
+      const inner = new Set(bound);
+      for (const name of scopedNames(node.body)) inner.add(name);
+      for (const statement of node.body) freeNames(statement, inner, out);
+      return out;
+    }
+    case 'ForStatement':
+    case 'ForOfStatement':
+    case 'ForInStatement': {
+      const inner = new Set(bound);
+      const head = node.init ?? node.left;
+      if (head?.type === 'VariableDeclaration') {
+        for (const declarator of head.declarations) {
+          for (const name of patternNames(declarator.id)) inner.add(name);
+        }
+      }
+      for (const key of ['init', 'left', 'right', 'test', 'update', 'body']) {
+        if (node[key]) freeNames(node[key], inner, out);
+      }
+      return out;
+    }
+    case 'CatchClause': {
+      const inner = new Set(bound);
+      if (node.param) for (const name of patternNames(node.param)) inner.add(name);
+      freeNames(node.body, inner, out);
+      return out;
+    }
+    case 'ClassDeclaration':
+    case 'ClassExpression': {
+      const inner = new Set(bound);
+      if (node.id) inner.add(node.id.name);
+      freeNames(node.superClass, inner, out);
+      freeNames(node.body, inner, out);
+      return out;
+    }
+    // The declared name is bound by the enclosing block already; a destructuring
+    // pattern can still carry defaults that read from outside.
+    case 'VariableDeclarator':
+      if (node.id.type !== 'Identifier') freeNames(node.id, bound, out);
+      freeNames(node.init, bound, out);
+      return out;
+
+    case 'ImportDeclaration':
+    case 'ExportAllDeclaration':
+    case 'BreakStatement':
+    case 'ContinueStatement':
+      return out;
+
+    default:
+      for (const key of Object.keys(node)) {
+        if (key === 'type' || key === 'start' || key === 'end' || key === 'loc' || key === 'range') continue;
+        freeNames(node[key], bound, out);
+      }
+      return out;
+  }
+}
+
+/**
+ * Module-level client code (a page entry) only needs validating.
+ *
+ * @param {Array<{ code: string, line?: number }>} blocks
+ * @param {string} label
+ * @returns {void}
+ * @throws with the offset mapped back to the .html file
+ */
+export function assertModule(blocks, label) {
+  for (const block of blocks) parseOrThrow(block.code, label, block.line ?? 1);
+  return blocks.map((b) => b.code).join('\n');
+}
+
+/**
+ * Bindings a `<script server>` block pulls in, so the shapes of imported values
+ * can be resolved by whoever owns the filesystem.
+ */
+function importsOf(ast) {
+  const out = [];
+  for (const statement of ast.body) {
+    if (statement.type !== 'ImportDeclaration') continue;
+    out.push({
+      source: statement.source.value,
+      specifiers: statement.specifiers.map((spec) => ({
+        local: spec.local.name,
+        imported:
+          spec.type === 'ImportDefaultSpecifier'
+            ? 'default'
+            : (spec.imported?.name ?? spec.imported?.value ?? spec.local.name),
+        namespace: spec.type === 'ImportNamespaceSpecifier',
+      })),
+    });
+  }
+  return out;
+}
+
+/**
+ * Guards against a block exporting a name the generated module already uses.
+ *
+ * @param {string[]} exports
+ * @param {Set<string>} reserved
+ * @param {string} label
+ * @returns {void}
+ * @throws naming the first collision
+ */
+export function assertNoCollisions(exports, reserved, label) {
+  for (const name of exports) {
+    if (reserved.has(name)) {
+      throw new ScriptError(
+        `${label}: exports "${name}", which the generated module already defines. ` +
+          `Reserved: ${[...reserved].join(', ')}.`,
+      );
+    }
+  }
+}
+
+/**
+ * A page's handlers are verb exports. An `actions` object is what they used to
+ * be, and nothing reads one now, so leaving it would answer 405 to every form
+ * on the page and say nothing about why.
+ *
+ * @param {string[]} exports
+ * @param {string} label
+ * @returns {void}
+ * @throws because nothing reads one, so a page keeping it would 405 in silence
+ */
+export function assertNoActionsObject(exports, label) {
+  if (!exports.includes('actions')) return;
+
+  throw new ScriptError(
+    `${label}: exports "actions", which nothing reads. Handlers are named for ` +
+      `their method now: export const POST = (ctx) => …, and the same for PUT, ` +
+      `PATCH and DELETE.`,
+  );
+}
+
+// ---- internals ------------------------------------------------------------
+
+function parseOrThrow(code, label, lineOffset, extra = {}) {
+  try {
+    return parse(code, { ...PARSE_OPTIONS, ...extra });
+  } catch (err) {
+    const line = (err.loc?.line ?? 1) + lineOffset - 1;
+    const message = String(err.message).replace(/\s*\(\d+:\d+\)$/, '');
+    throw new ScriptError(`${label}: ${message} (line ${line})`);
+  }
+}
+
+function namedExportsOf(ast, code, lineOffset, label) {
+  const names = [];
+
+  for (const statement of ast.body) {
+    if (statement.type === 'ExportAllDeclaration') {
+      throw new ScriptError(
+        `${label}: \`export *\` is not supported here. Its names cannot be checked ` +
+          `against the generated module (line ${lineOf(statement, code, lineOffset)})`,
+      );
+    }
+    if (statement.type !== 'ExportNamedDeclaration') continue;
+
+    if (statement.declaration) {
+      const decl = statement.declaration;
+      if (decl.type === 'VariableDeclaration') {
+        for (const d of decl.declarations) names.push(...patternNames(d.id));
+      } else if (decl.id) {
+        names.push(decl.id.name);
+      }
+      continue;
+    }
+    for (const spec of statement.specifiers) {
+      names.push(spec.exported.name ?? spec.exported.value);
+    }
+  }
+
+  return names;
+}
+
+function patternNames(node) {
+  switch (node.type) {
+    case 'Identifier':
+      return [node.name];
+    case 'ObjectPattern':
+      return node.properties.flatMap((p) =>
+        p.type === 'RestElement' ? patternNames(p.argument) : patternNames(p.value),
+      );
+    case 'ArrayPattern':
+      return node.elements.filter(Boolean).flatMap(patternNames);
+    case 'AssignmentPattern':
+      return patternNames(node.left);
+    case 'RestElement':
+      return patternNames(node.argument);
+    default:
+      return [];
+  }
+}
+
+// Blanks out ranges without changing any other character's line or column, so
+// stack traces into the generated module still point at the right spot.
+function blank(code, cuts) {
+  let out = code;
+  for (const [start, end] of cuts) {
+    out = out.slice(0, start) + code.slice(start, end).replace(/[^\n]/g, ' ') + out.slice(end);
+  }
+  return out;
+}
+
+function lineOf(node, code, lineOffset) {
+  return code.slice(0, node.start).split('\n').length + lineOffset - 1;
+}