@tinvar/renderer 0.0.0-stage → 0.4.0

package/src/client-props.js

@@ -0,0 +1,540 @@
+// No function handed from a server component to a client one, refused by
+// the build.
+//
+// tinvar-spec.md, "Client components": "Props across the boundary must be
+// serializable: Data objects, primitives, promises (see queries) and server
+// actions. Closures are refused at build time where detectable and at render
+// time otherwise."
+//
+// At render, React refuses a function prop to a client component as it
+// serializes the tree, and the renderer classifies the failure
+// NOT_SERIALIZABLE (classify.js): the page fails for the visitor who reached
+// it, in whichever branch of it held the function. The build can see most
+// of these first, where they are written: a client component is a module the
+// RSC plugin made a client reference of, and a function written into its
+// props is syntax.
+//
+// So, over the rsc environment's graph once it is whole, each of the
+// application's server modules is read with the bundler's parser, and each
+// JSX element whose tag is imported is resolved: through the import, and
+// through any re-exports on the way -- a kit's barrel -- to the module that
+// defines it. Where that module is a client reference, every prop written to
+// the element is read for a function:
+//   - a function or class written in place: `onClick={() => ...}`;
+//   - a name bound in the file to one -- a function declaration, or a
+//     `const`, `let` or `var` initialized with one -- in the scopes around
+//     the element;
+//   - `fn.bind(...)`, which makes a function;
+//   - any of those inside an object or array written in place, either branch
+//     of a conditional, either side of `&&`, `||` or `??`;
+// and a function written as a child, a render prop. A server action is no
+// function here: under `react-server` an `@actions/*` reference is the
+// action's name (action-server.js), and Tinvar has no `'use server'`
+// functions -- the renderer decodes no client calls (tinvar-spec.md, "No
+// client input") -- so one of those is refused like any other function.
+//
+// What it cannot see, React still refuses at render: a function reached
+// through a parameter, an import or a spread, and a tag whose module the
+// build cannot read. Those are unknowns, not refusals: a server component
+// may hand a function to another server component, and widening an unknown
+// to "client" would refuse that. What it can see, it refuses, with every
+// place named; and an application module it cannot parse fails the build.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { extname, relative } from 'node:path';
+import { getPluginApi } from '@vitejs/plugin-rsc';
+import { parseAst } from 'vite';
+
+const SOURCE = /\.(?:[cm]?[jt]sx?)$/;
+
+/** What wraps a value and leaves it the same value. */
+const SAME_VALUE = new Set([
+  'TSAsExpression',
+  'TSSatisfiesExpression',
+  'TSNonNullExpression',
+  'TSTypeAssertion',
+  'TSInstantiationExpression',
+  'ParenthesizedExpression',
+  'ChainExpression',
+]);
+
+/** Why the build refuses a module's props. */
+export class UnserializableProp extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message);
+    this.name = 'UnserializableProp';
+  }
+}
+
+/**
+ * The plugin. Only the rsc build has the server component graph, and the
+ * client references the RSC plugin made of it.
+ *
+ * @returns {import('vite').Plugin}
+ */
+export function serializableProps() {
+  /** @type {import('vite').ResolvedConfig | null} */
+  let resolved = null;
+
+  return {
+    name: 'tinvar:serializable-props',
+    apply: 'build',
+    configResolved(config) {
+      resolved = config;
+    },
+    applyToEnvironment(environment) {
+      return environment.name === 'rsc';
+    },
+    async generateBundle() {
+      const manager = resolved === null ? undefined : getPluginApi(resolved)?.manager;
+      if (manager === undefined) {
+        throw new Error('[tinvar] serializableProps() needs @vitejs/plugin-rsc in the same config.');
+      }
+      const references = new Set(Object.keys(manager.clientReferenceMetaMap));
+      const root = resolved?.root ?? process.cwd();
+
+      /** @type {string[]} */
+      const found = [];
+      const clients = clientExports(
+        references,
+        async (specifier, importer) => (await this.resolve(specifier, importer))?.id ?? null,
+      );
+      for (const id of this.getModuleIds()) {
+        const file = fileOf(id);
+        if (id.startsWith('\0') || references.has(id) || isDependency(file) || !SOURCE.test(file)) continue;
+        if (!existsSync(file)) continue;
+
+        const source = readFileSync(file, 'utf8');
+        for (const violation of await functionProps(source, file, (specifier, name) =>
+          clients(specifier, name, id),
+        )) {
+          found.push(`${relative(root, file)}:${violation.line} ${violation.message}`);
+        }
+      }
+
+      if (found.length > 0) {
+        throw new UnserializableProp(
+          `[tinvar] A server component hands a client component a function, which React refuses as the page renders (NOT_SERIALIZABLE):\n  ${found.join('\n  ')}\n` +
+            'Hand it data, or an action from @actions/*, and let the client component make the function it needs.',
+        );
+      }
+    },
+  };
+}
+
+/**
+ * Whether a name imported from a module is a client component: the module
+ * is a client reference, or re-exports the name from one. Answers are kept
+ * for the build, since every page imports the same kit.
+ *
+ * @param {Set<string>} references the client references' module ids
+ * @param {(specifier: string, importer: string) => Promise<string | null>} resolveId
+ * @returns {(specifier: string, name: string, importer: string) => Promise<boolean>}
+ */
+export function clientExports(references, resolveId) {
+  /** @type {Map<string, Promise<boolean>>} */
+  const answers = new Map();
+
+  /** @type {(id: string, name: string, seen: Set<string>) => Promise<boolean>} */
+  const exportsClient = (id, name, seen) => {
+    const key = `${id}\0${name}`;
+    // The path first: a cycle comes back to an answer still being worked
+    // out, and awaiting it would await itself.
+    if (seen.has(key)) return Promise.resolve(false);
+    const known = answers.get(key);
+    if (known !== undefined) return known;
+    seen.add(key);
+
+    const answer = (async () => {
+      if (references.has(id)) return true;
+      const file = fileOf(id);
+      if (id.startsWith('\0') || !SOURCE.test(file) || !existsSync(file)) return false;
+
+      let program;
+      try {
+        program = parse(readFileSync(file, 'utf8'), file);
+      } catch {
+        // The bundler read it, under its own options; what this cannot, it
+        // leaves to React at render.
+        return false;
+      }
+
+      /** @type {Map<string, { from: string, name: string }>} what the module imports by name */
+      const imported = new Map();
+      for (const node of program.body) {
+        if (node.type !== 'ImportDeclaration' || node.importKind === 'type') continue;
+        for (const specifier of node.specifiers) {
+          if (specifier.type === 'ImportSpecifier') {
+            imported.set(specifier.local.name, { from: node.source.value, name: nameOf(specifier.imported) });
+          } else if (specifier.type === 'ImportDefaultSpecifier') {
+            imported.set(specifier.local.name, { from: node.source.value, name: 'default' });
+          }
+        }
+      }
+
+      const follow = async (/** @type {string} */ specifier, /** @type {string} */ inner) => {
+        const target = await resolveId(specifier, id);
+        return target !== null && exportsClient(target, inner, seen);
+      };
+
+      for (const node of program.body) {
+        if (node.type === 'ExportNamedDeclaration' && node.exportKind !== 'type') {
+          for (const specifier of node.specifiers ?? []) {
+            if (nameOf(specifier.exported) !== name) continue;
+            const local = nameOf(specifier.local);
+            if (node.source) return follow(node.source.value, local);
+            const through = imported.get(local);
+            return through === undefined ? false : follow(through.from, through.name);
+          }
+        } else if (node.type === 'ExportDefaultDeclaration' && name === 'default') {
+          const value = node.declaration;
+          const through = value?.type === 'Identifier' ? imported.get(value.name) : undefined;
+          return through === undefined ? false : follow(through.from, through.name);
+        } else if (node.type === 'ExportAllDeclaration' && node.exported === null && name !== 'default') {
+          if (await follow(node.source.value, name)) return true;
+        }
+      }
+      return false;
+    })();
+    answers.set(key, answer);
+    return answer;
+  };
+
+  return async (specifier, name, importer) => {
+    const id = await resolveId(specifier, importer);
+    return id !== null && exportsClient(id, name, new Set());
+  };
+}
+
+/**
+ * Every function a module's server components write into a client
+ * component's props.
+ *
+ * @param {string} source the module's own source, as written
+ * @param {string} file its path, which says how to parse it
+ * @param {(specifier: string, name: string) => Promise<boolean>} isClient whether
+ *        the name imported from the specifier is a client component
+ * @returns {Promise<Array<{ line: number, message: string }>>}
+ * @throws {UnserializableProp} for a module that cannot be parsed
+ */
+export async function functionProps(source, file, isClient) {
+  let program;
+  try {
+    program = parse(source, file);
+  } catch (error) {
+    throw new UnserializableProp(
+      `[tinvar] ${file} cannot be parsed, so the props it hands client components cannot be checked: ${/** @type {Error} */ (error).message}`,
+    );
+  }
+  // A client module renders in the browser: what it hands its children is
+  // never serialized.
+  if (program.body.some((node) => node.type === 'ExpressionStatement' && node.directive === 'use client')) {
+    return [];
+  }
+
+  /** @type {Map<string, { from: string, name: string | null }>} each value imported: by name, or whole (null) */
+  const imported = new Map();
+  for (const node of program.body) {
+    if (node.type !== 'ImportDeclaration' || node.importKind === 'type') continue;
+    for (const specifier of node.specifiers) {
+      if (specifier.importKind === 'type') continue;
+      imported.set(specifier.local.name, {
+        from: node.source.value,
+        name:
+          specifier.type === 'ImportSpecifier'
+            ? nameOf(specifier.imported)
+            : specifier.type === 'ImportDefaultSpecifier'
+              ? 'default'
+              : null,
+      });
+    }
+  }
+
+  /** @type {Array<{ element: any, tag: string, ancestors: any[], from: string, name: string }>} */
+  const elements = [];
+  walk(program, [], (node, ancestors) => {
+    if (node.type !== 'JSXElement') return;
+    const tag = node.openingElement.name;
+    let local;
+    let name;
+    if (tag.type === 'JSXIdentifier') {
+      // A lowercase tag is the platform's element, never a component.
+      if (!/^[A-Z_$]/.test(tag.name)) return;
+      local = tag.name;
+    } else if (tag.type === 'JSXMemberExpression' && tag.object.type === 'JSXIdentifier') {
+      local = tag.object.name;
+      name = tag.property.name;
+    } else {
+      return;
+    }
+    const from = imported.get(local);
+    if (from === undefined || shadowed(local, ancestors)) return;
+    const exported = from.name === null ? name : name === undefined ? from.name : null;
+    if (exported === undefined || exported === null) return;
+    elements.push({
+      element: node,
+      tag: name === undefined ? local : `${local}.${name}`,
+      ancestors,
+      from: from.from,
+      name: exported,
+    });
+  });
+
+  /** @type {Array<{ line: number, message: string }>} */
+  const found = [];
+  for (const { element, tag, ancestors, from, name } of elements) {
+    /** @type {Array<{ prop: string, node: any }>} */
+    const functions = [];
+    for (const attribute of element.openingElement.attributes) {
+      if (attribute.type !== 'JSXAttribute' || attribute.value?.type !== 'JSXExpressionContainer') continue;
+      const fn = functionIn(attribute.value.expression, [...ancestors, element]);
+      if (fn !== null) functions.push({ prop: nameOf(attribute.name), node: fn });
+    }
+    for (const child of element.children) {
+      if (child.type !== 'JSXExpressionContainer') continue;
+      const fn = functionIn(child.expression, [...ancestors, element]);
+      if (fn !== null) functions.push({ prop: 'children', node: fn });
+    }
+    if (functions.length === 0 || !(await isClient(from, name))) continue;
+
+    for (const { prop, node } of functions) {
+      found.push({
+        line: lineOf(source, node.start),
+        message: `hands <${tag}>, a client component from '${from}', a function as '${prop}'.`,
+      });
+    }
+  }
+  return found;
+}
+
+/**
+ * The function an expression is, or holds where it is written -- null for
+ * one it is not, or cannot be seen to be.
+ *
+ * @param {any} expression
+ * @param {any[]} ancestors the nodes around it, outermost first
+ * @returns {any | null}
+ */
+function functionIn(expression, ancestors) {
+  let node = expression;
+  while (node && SAME_VALUE.has(node.type)) node = node.expression;
+  if (!node) return null;
+
+  switch (node.type) {
+    case 'ArrowFunctionExpression':
+    case 'FunctionExpression':
+    case 'ClassExpression':
+      return node;
+    case 'Identifier': {
+      const binding = bindingOf(node.name, ancestors);
+      return binding === null ? null : node;
+    }
+    case 'CallExpression': {
+      const callee = node.callee;
+      const bound =
+        callee.type === 'MemberExpression' &&
+        !callee.computed &&
+        callee.property.type === 'Identifier' &&
+        callee.property.name === 'bind';
+      return bound ? node : null;
+    }
+    case 'ObjectExpression':
+      for (const property of node.properties) {
+        if (property.type !== 'Property') continue;
+        if (property.method || property.kind === 'get' || property.kind === 'set') return property;
+        const inner = functionIn(property.value, ancestors);
+        if (inner !== null) return inner;
+      }
+      return null;
+    case 'ArrayExpression':
+      for (const element of node.elements) {
+        const inner =
+          element === null || element.type === 'SpreadElement' ? null : functionIn(element, ancestors);
+        if (inner !== null) return inner;
+      }
+      return null;
+    case 'ConditionalExpression':
+      return functionIn(node.consequent, ancestors) ?? functionIn(node.alternate, ancestors);
+    case 'LogicalExpression':
+      return functionIn(node.left, ancestors) ?? functionIn(node.right, ancestors);
+    default:
+      return null;
+  }
+}
+
+/**
+ * The function a name is bound to, in the nearest scope around a node that
+ * declares it: a function or class declaration, or a variable initialized
+ * with a function or class. Null for anything else -- a parameter, an
+ * import, a value -- and for a name nothing here declares.
+ *
+ * @param {string} name
+ * @param {any[]} ancestors outermost first
+ * @returns {any | null}
+ */
+function bindingOf(name, ancestors) {
+  for (let index = ancestors.length - 1; index >= 0; index--) {
+    const scope = ancestors[index];
+    if (isFunction(scope)) {
+      if (scope.params.some((/** @type {any} */ param) => declares(param, name))) return null;
+      if (scope.id?.name === name && scope.type !== 'FunctionDeclaration') return scope;
+    }
+    if (scope.type === 'CatchClause' && scope.param && declares(scope.param, name)) return null;
+    if (scope.type === 'ForStatement' || scope.type === 'ForInStatement' || scope.type === 'ForOfStatement') {
+      const declaration = scope.init ?? scope.left;
+      if (
+        declaration?.type === 'VariableDeclaration' &&
+        declaration.declarations.some((d) => declares(d.id, name))
+      ) {
+        return null;
+      }
+    }
+    const body =
+      scope.type === 'Program' || scope.type === 'BlockStatement' || scope.type === 'StaticBlock'
+        ? scope.body
+        : scope.type === 'SwitchCase'
+          ? scope.consequent
+          : null;
+    if (body === null) continue;
+
+    for (let statement of body) {
+      if (
+        (statement.type === 'ExportNamedDeclaration' || statement.type === 'ExportDefaultDeclaration') &&
+        statement.declaration
+      ) {
+        statement = statement.declaration;
+      }
+      if (
+        (statement.type === 'FunctionDeclaration' || statement.type === 'ClassDeclaration') &&
+        statement.id?.name === name
+      ) {
+        return statement;
+      }
+      if (statement.type === 'VariableDeclaration') {
+        for (const declarator of statement.declarations) {
+          if (!declares(declarator.id, name)) continue;
+          if (declarator.id.type !== 'Identifier') return null;
+          let init = declarator.init;
+          while (init && SAME_VALUE.has(init.type)) init = init.expression;
+          return init &&
+            (init.type === 'ArrowFunctionExpression' ||
+              init.type === 'FunctionExpression' ||
+              init.type === 'ClassExpression')
+            ? init
+            : null;
+        }
+      }
+      if (statement.type === 'ImportDeclaration' && statement.specifiers.some((s) => s.local.name === name)) {
+        return null;
+      }
+    }
+  }
+  return null;
+}
+
+/** Whether a component's local name is declared again between it and the module's imports. */
+function shadowed(name, ancestors) {
+  for (const scope of ancestors) {
+    if (scope.type === 'Program') continue;
+    if (isFunction(scope) && scope.params.some((/** @type {any} */ param) => declares(param, name)))
+      return true;
+    const body = scope.type === 'BlockStatement' ? scope.body : null;
+    if (body === null) continue;
+    for (const statement of body) {
+      if (
+        statement.type === 'VariableDeclaration' &&
+        statement.declarations.some((d) => declares(d.id, name))
+      ) {
+        return true;
+      }
+      if (
+        (statement.type === 'FunctionDeclaration' || statement.type === 'ClassDeclaration') &&
+        statement.id?.name === name
+      ) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/** Whether a binding pattern declares a name. */
+function declares(pattern, name) {
+  if (!pattern) return false;
+  switch (pattern.type) {
+    case 'Identifier':
+      return pattern.name === name;
+    case 'AssignmentPattern':
+      return declares(pattern.left, name);
+    case 'RestElement':
+      return declares(pattern.argument, name);
+    case 'ArrayPattern':
+      return pattern.elements.some((/** @type {any} */ element) => declares(element, name));
+    case 'ObjectPattern':
+      return pattern.properties.some((/** @type {any} */ property) =>
+        declares(property.type === 'RestElement' ? property : property.value, name),
+      );
+    case 'TSParameterProperty':
+      return declares(pattern.parameter, name);
+    default:
+      return false;
+  }
+}
+
+function isFunction(node) {
+  return (
+    node.type === 'FunctionDeclaration' ||
+    node.type === 'FunctionExpression' ||
+    node.type === 'ArrowFunctionExpression'
+  );
+}
+
+/** An identifier's name, or a string literal's value: how an import or export names a binding. */
+function nameOf(node) {
+  if (node.type === 'JSXNamespacedName') return `${node.namespace.name}:${node.name.name}`;
+  return node.type === 'Identifier' || node.type === 'JSXIdentifier' ? node.name : String(node.value);
+}
+
+function lineOf(source, offset) {
+  return typeof offset === 'number' ? source.slice(0, offset).split('\n').length : 0;
+}
+
+function parse(source, file) {
+  const extension = extname(file);
+  const lang = extension === '.tsx' ? 'tsx' : /^\.[cm]?ts$/.test(extension) ? 'ts' : 'jsx';
+  return parseAst(source, { lang }, file);
+}
+
+/** A module id as the file it was read from: no query, no hash. */
+function fileOf(id) {
+  return id.replace(/[?#].*$/, '');
+}
+
+/** Whether a module's file is a dependency's: anywhere under a node_modules directory. */
+function isDependency(file) {
+  return file.split(/[\\/]/).includes('node_modules');
+}
+
+/**
+ * Depth-first over every node, with the nodes around each, outermost first.
+ *
+ * @param {any} node
+ * @param {any[]} ancestors
+ * @param {(node: any, ancestors: any[]) => void} visit
+ */
+function walk(node, ancestors, visit) {
+  if (node === null || typeof node !== 'object') return;
+  if (Array.isArray(node)) {
+    for (const child of node) walk(child, ancestors, visit);
+    return;
+  }
+  if (typeof node.type !== 'string') return;
+  visit(node, ancestors);
+  const inner = [...ancestors, node];
+  for (const key of Object.keys(node)) {
+    if (key === 'type' || key === 'start' || key === 'end' || key === 'range' || key === 'loc') continue;
+    const child = node[key];
+    if (child !== null && typeof child === 'object') walk(child, inner, visit);
+  }
+}