@tinvar/renderer 0.0.0-stage → 0.4.1

package/src/eslint.js

@@ -0,0 +1,469 @@
+// The lint rule that keeps state out of server components.
+//
+// tinvar-spec.md, "Renderer hardening": "Per-render isolation. Each render
+// runs in its own AsyncLocalStorage context. The renderer never caches query
+// results across requests. A lint rule rejects mutable module-level state in
+// server files."
+//
+// A server module is evaluated once per renderer process, and every render
+// that process serves -- every user's -- runs against that one instance.
+// What the framework holds for a render lives in the render's context, but a
+// `let` at the top of a page, or a Map a component fills, sits outside it:
+// what one user's render leaves there, the next user's render reads. The
+// render context cannot stop that, so the source is held to it before it
+// ships.
+//
+// A server file is a module of the rsc graph. The graph exists whole only
+// while the bundler has it (vite.js), so the config names the directories
+// whose modules are server components -- `configs.server` covers the app's
+// pages and components -- and the rule leaves out what @vitejs/plugin-rsc
+// leaves out of the graph: a module with a 'use client' directive in its
+// prologue, which the rsc environment replaces with a client reference. A
+// declaration file holds no code and is left out too.
+//
+// Mutable module state is:
+//   - a top-level `let` or `var`, reported where it is declared -- exported,
+//     with a message of its own, since every importer reads it live;
+//   - any other top-level binding -- a const, a function, a class, an import
+//     -- reassigned anywhere in the file;
+//   - a top-level binding whose value the file mutates anywhere: a property
+//     assigned, deleted or incremented; the value handed to Object.assign(),
+//     Object.defineProperty() or the like as the target; or a call of a
+//     method that changes an array, Map, Set or WeakMap: push, pop, shift,
+//     unshift, splice, sort, reverse, fill, copyWithin, set, add, delete,
+//     clear. A write through it to a nested value counts the same;
+//   - a variable a closure keeps from when the module loaded -- one declared
+//     in a function invoked at the top as it is written, or in a top-level
+//     block -- that a function made there reassigns or mutates;
+//   - a write to a global: `globalThis.x = ...`, `process.env.X = ...`.
+//
+// Building a constant at the top -- `const ROUTES = new Map()` and then
+// `ROUTES.set(...)` -- is reported too, as the spec words it: the rule cannot
+// tell set-up at load from a write a render makes, and a value built whole in
+// its initializer needs no write.
+//
+// Frozen and `as const` values. A constant is only reported when the file
+// writes it, so one it never writes is never reported, frozen or not.
+// Object.freeze() of an object or array literal exempts writes to the frozen
+// value's own properties: in a module, which is strict code, they throw
+// rather than change anything. A write through it to a nested value is still
+// reported, since freezing is shallow, and so is a write to a frozen Map, Set
+// or instance, whose methods freezing does not stop. `as const` exempts
+// nothing: TypeScript already refuses a write to one, so a write this rule
+// sees went past the type through a cast, and it changes the value at
+// runtime all the same.
+//
+// What it cannot see: state behind a function -- a factory called at the top
+// that returns a closure, a memoizer from a dependency, a method that writes
+// `this` -- and a binding reached through an alias (`const a = list;
+// a.push()`). It reads one file's syntax, not what its code does when it
+// runs.
+//
+// The plugin's other rule, for a query called inside a can() branch, is in
+// can-branch.js.
+
+import { authorizeQueriesInCanBranches } from './can-branch.js';
+
+/** Methods that change the array, Map, Set or WeakMap they are called on. */
+const MUTATORS = new Set([
+  'push',
+  'pop',
+  'shift',
+  'unshift',
+  'splice',
+  'sort',
+  'reverse',
+  'fill',
+  'copyWithin',
+  'set',
+  'add',
+  'delete',
+  'clear',
+]);
+
+/** Those an array has, which a frozen array refuses by throwing. */
+const ARRAY_MUTATORS = new Set([
+  'push',
+  'pop',
+  'shift',
+  'unshift',
+  'splice',
+  'sort',
+  'reverse',
+  'fill',
+  'copyWithin',
+]);
+
+/** Built-ins that write onto the value they are handed first. */
+const TARGET_WRITERS = new Map([
+  ['Object', new Set(['assign', 'defineProperty', 'defineProperties', 'setPrototypeOf'])],
+  ['Reflect', new Set(['set', 'defineProperty', 'deleteProperty', 'setPrototypeOf'])],
+]);
+
+/** Nodes around an expression that leave its value as it is: TypeScript's assertions, an optional chain. */
+const WRAPPERS = new Set([
+  'ChainExpression',
+  'TSAsExpression',
+  'TSNonNullExpression',
+  'TSSatisfiesExpression',
+  'TSTypeAssertion',
+  'TSInstantiationExpression',
+]);
+
+const DECLARATION_FILE = /\.d\.[cm]?ts$/;
+
+/** The modules `configs.server` holds to the rule: the app's pages and components. */
+export const SERVER_FILES = [
+  'resources/pages/**/*.{js,jsx,mjs,ts,tsx,mts}',
+  'resources/components/**/*.{js,jsx,mjs,ts,tsx,mts}',
+];
+
+const WHY =
+  'A server module is loaded once and every render shares it, so what one render leaves there the next one reads, and one user\'s data can reach another user\'s page (tinvar-spec.md, "Per-render isolation").';
+
+/** @type {import('eslint').Rule.RuleModule} */
+export const noMutableModuleState = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        "Disallow mutable module-level state in server components: every render shares it, so one user's data can reach another's render.",
+    },
+    schema: [],
+    messages: {
+      topLevel: `'{{name}}' is a top-level \`{{kind}}\`. ${WHY} Keep a per-render value inside the component, or make this a \`const\` nothing writes; a module that only runs in the browser says so with 'use client'.`,
+      exported: `'{{name}}' is an exported top-level \`{{kind}}\`, which every importer reads live. ${WHY} Export a \`const\` nothing writes, or a function that builds the value for each render.`,
+      reassigned: `'{{name}}' is module state, and this reassigns it. ${WHY} Keep a per-render value inside the component.`,
+      mutated: `'{{name}}' is module state, and this mutates it. ${WHY} Build the value inside the render, or build it whole where it is declared and never write it.`,
+      global: `This writes to '{{name}}', a global. One renderer process serves every render, so what this render leaves there the next one reads, and one user's data can reach another user's page (tinvar-spec.md, "Per-render isolation").`,
+    },
+  },
+  create(context) {
+    if (DECLARATION_FILE.test(context.filename)) return {};
+    const sourceCode = context.sourceCode;
+
+    return {
+      // At the end, when every node has its parent and the scopes are whole.
+      'Program:exit'(program) {
+        if (isClientModule(program)) return;
+        check(context, sourceCode, program);
+      },
+    };
+  },
+};
+
+/**
+ * Whether @vitejs/plugin-rsc takes the module for a client reference: a
+ * 'use client' directive anywhere in its prologue, as its hasDirective()
+ * reads it. A string later in the file is no directive, to it or here.
+ */
+function isClientModule(program) {
+  return program.body.some(
+    (/** @type {any} */ statement) =>
+      statement.type === 'ExpressionStatement' && statement.directive === 'use client',
+  );
+}
+
+/**
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {any} program
+ */
+function check(context, sourceCode, program) {
+  const globalScope = /** @type {any} */ (sourceCode.scopeManager).globalScope;
+  // The module's own scope: a module, or the function CommonJS wraps it in.
+  // A script has none, and its top-level bindings are the global scope's.
+  const top =
+    globalScope.childScopes.find(
+      (/** @type {any} */ scope) =>
+        scope.block === program && (scope.type === 'module' || scope.type === 'function'),
+    ) ?? globalScope;
+
+  const isGlobal = (/** @type {any} */ identifier) => {
+    for (let scope = sourceCode.getScope(identifier); scope; scope = scope.upper) {
+      const variable = /** @type {any} */ (scope.set.get(identifier.name));
+      if (variable !== undefined && variable.isValueVariable !== false) return variable.defs.length === 0;
+    }
+    return true;
+  };
+
+  /** Reports a write through one reference to a binding that outlives the render. */
+  const reportWrite = (/** @type {any} */ reference, /** @type {string} */ name, frozen) => {
+    if (reference.isValueReference === false) return;
+    if (reference.isWrite()) {
+      if (reference.init) return;
+      context.report({ node: reference.identifier, messageId: 'reassigned', data: { name } });
+      return;
+    }
+    const mutation = mutationOf(reference.identifier, isGlobal);
+    if (mutation === null) return;
+    // A frozen literal's own properties throw when written, so nothing changes.
+    if (
+      frozen !== null &&
+      mutation.level === 0 &&
+      (mutation.method === null || (frozen === 'array' && ARRAY_MUTATORS.has(mutation.method)))
+    ) {
+      return;
+    }
+    context.report({ node: mutation.node, messageId: 'mutated', data: { name } });
+  };
+
+  // The module's top level: every binding, every write, wherever it is made.
+  for (const variable of top.variables) {
+    if (variable.isValueVariable === false || variable.defs.length === 0) continue;
+
+    const declared = variable.defs.find(
+      (/** @type {any} */ def) =>
+        def.type === 'Variable' &&
+        (def.parent.kind === 'let' || def.parent.kind === 'var') &&
+        !def.parent.declare,
+    );
+    if (declared !== undefined) {
+      // One report, where it is declared: its writes are what the `let` is for.
+      context.report({
+        node: declared.name,
+        messageId: isExported(variable, declared) ? 'exported' : 'topLevel',
+        data: { name: variable.name, kind: declared.parent.kind },
+      });
+      continue;
+    }
+
+    const frozen = frozenLiteral(variable, isGlobal);
+    for (const reference of variable.references) reportWrite(reference, variable.name, frozen);
+  }
+
+  // What a closure made at load keeps: written by a function made there, it
+  // lives, and changes, as long as the module.
+  for (const scope of /** @type {any} */ (sourceCode.scopeManager).scopes) {
+    if (scope === top || scope === globalScope || !runsAtLoad(scope, top)) continue;
+    for (const variable of /** @type {any} */ (scope).variables) {
+      if (variable.isValueVariable === false || variable.defs.length === 0) continue;
+      const frozen = frozenLiteral(variable, isGlobal);
+      for (const reference of variable.references) {
+        if (fromClosure(reference.from, scope)) reportWrite(reference, variable.name, frozen);
+      }
+    }
+  }
+
+  // Globals: what the parser could not resolve, and the built-ins and
+  // configured globals, which are declared nowhere in the file.
+  const globals = [
+    ...globalScope.through,
+    ...globalScope.variables
+      .filter((/** @type {any} */ variable) => variable.defs.length === 0)
+      .flatMap((/** @type {any} */ variable) => variable.references),
+  ];
+  for (const reference of globals) {
+    if (reference.isValueReference === false) continue;
+    const mutation = reference.isWrite()
+      ? { node: reference.identifier }
+      : mutationOf(reference.identifier, isGlobal);
+    if (mutation !== null) {
+      context.report({ node: mutation.node, messageId: 'global', data: { name: reference.identifier.name } });
+    }
+  }
+}
+
+/**
+ * Whether a reference changes the value its binding holds, rather than the
+ * binding: a write to a property of it, or of anything reached through it,
+ * a mutating method called on either, or either handed to a built-in that
+ * writes onto it.
+ *
+ * `level` counts the properties between the binding and the value changed:
+ * 0 for `list.push(x)` and `config.mode = x`, 1 for `state.items.push(x)`.
+ * A frozen literal's exemption holds at 0 alone.
+ *
+ * @param {any} identifier
+ * @param {(identifier: any) => boolean} isGlobal
+ * @returns {{ node: any, level: number, method: string | null } | null}
+ */
+function mutationOf(identifier, isGlobal) {
+  let node = identifier;
+  let member = null;
+  let depth = 0;
+  for (let parent = node.parent; parent; parent = node.parent) {
+    if (WRAPPERS.has(parent.type) && parent.expression === node) {
+      node = parent;
+    } else if (parent.type === 'MemberExpression' && parent.object === node) {
+      node = parent;
+      member = parent;
+      depth += 1;
+    } else {
+      break;
+    }
+  }
+
+  const parent = node.parent;
+  if (member !== null) {
+    if (isWriteTarget(node, parent)) return { node, level: depth - 1, method: null };
+    if (parent?.type === 'CallExpression' && parent.callee === node && !writesTarget(parent, isGlobal)) {
+      const method = propertyName(member);
+      if (method !== null && MUTATORS.has(method)) return { node: parent, level: depth - 1, method };
+    }
+  }
+  if (parent?.type === 'CallExpression' && parent.arguments[0] === node && writesTarget(parent, isGlobal)) {
+    return { node: parent, level: depth, method: null };
+  }
+  return null;
+}
+
+/** Whether `node`, a member expression, is what its parent assigns, deletes, increments or destructures into. */
+function isWriteTarget(node, parent) {
+  switch (parent?.type) {
+    case 'AssignmentExpression':
+    case 'AssignmentPattern':
+    case 'ForInStatement':
+    case 'ForOfStatement':
+      return parent.left === node;
+    case 'UpdateExpression':
+    case 'RestElement':
+      return parent.argument === node;
+    case 'UnaryExpression':
+      return parent.operator === 'delete' && parent.argument === node;
+    case 'ArrayPattern':
+      return parent.elements.includes(node);
+    case 'Property':
+      return parent.value === node && parent.parent?.type === 'ObjectPattern';
+    default:
+      return false;
+  }
+}
+
+/** `Object.assign(target, ...)` and its like, with `Object` or `Reflect` the built-in, not a binding of the file's. */
+function writesTarget(call, isGlobal) {
+  const callee = unwrap(call.callee);
+  if (callee?.type !== 'MemberExpression' || callee.object.type !== 'Identifier') return false;
+  const methods = TARGET_WRITERS.get(callee.object.name);
+  const method = propertyName(callee);
+  return methods !== undefined && method !== null && methods.has(method) && isGlobal(callee.object);
+}
+
+/** A member's property as written, or null when it is computed from something other than a literal. */
+function propertyName(member) {
+  const property = member.property;
+  if (!member.computed) return property.type === 'Identifier' ? property.name : null;
+  if (property.type === 'Literal' && typeof property.value === 'string') return property.value;
+  if (property.type === 'TemplateLiteral' && property.expressions.length === 0) {
+    return property.quasis[0]?.value.cooked ?? null;
+  }
+  return null;
+}
+
+function unwrap(node) {
+  while (node && WRAPPERS.has(node.type)) node = node.expression;
+  return node;
+}
+
+/**
+ * 'object' or 'array' for a const bound to Object.freeze() of that literal,
+ * through any TypeScript assertion around either; null for anything else,
+ * a frozen Map or instance among them.
+ */
+function frozenLiteral(variable, isGlobal) {
+  if (variable.defs.length !== 1) return null;
+  const def = variable.defs[0];
+  if (def.type !== 'Variable' || def.parent.kind !== 'const' || def.node.id.type !== 'Identifier')
+    return null;
+
+  const init = unwrap(def.node.init);
+  if (init?.type !== 'CallExpression') return null;
+  const callee = unwrap(init.callee);
+  if (
+    callee?.type !== 'MemberExpression' ||
+    callee.object.type !== 'Identifier' ||
+    callee.object.name !== 'Object' ||
+    propertyName(callee) !== 'freeze' ||
+    !isGlobal(callee.object)
+  ) {
+    return null;
+  }
+
+  const value = unwrap(init.arguments[0]);
+  if (value?.type === 'ObjectExpression') return 'object';
+  if (value?.type === 'ArrayExpression') return 'array';
+  return null;
+}
+
+/** Whether a top-level `let` or `var` is exported: in its declaration, or by an export list naming it. */
+function isExported(variable, def) {
+  if (def.parent.parent?.type === 'ExportNamedDeclaration') return true;
+  return variable.references.some(
+    (/** @type {any} */ reference) =>
+      reference.identifier.parent?.type === 'ExportSpecifier' &&
+      reference.identifier.parent.local === reference.identifier,
+  );
+}
+
+/**
+ * Whether a scope's code runs once, as the module loads: the module's own,
+ * and a block, a class body, a static field or block, or a function invoked
+ * where it is written, inside it. Any other function runs when called -- a
+ * render's own variables are its own.
+ */
+function runsAtLoad(scope, top) {
+  for (let current = scope; current !== top; current = current.upper) {
+    if (current === null || current.type === 'global') return false;
+    if (current.type === 'function' && !isInvokedInPlace(current.block)) return false;
+    if (current.type === 'class-field-initializer' && current.block.parent?.static !== true) return false;
+  }
+  return true;
+}
+
+/** Whether a reference is made from inside a function nested in `scope`, which may run long after it. */
+function fromClosure(from, scope) {
+  for (let current = from; current !== null && current !== scope; current = current.upper) {
+    if (current.type === 'function' && !isInvokedInPlace(current.block)) return true;
+    if (current.type === 'class-field-initializer' && current.block.parent?.static !== true) return true;
+  }
+  return false;
+}
+
+/** `(() => { ... })()`, `(function () { ... }).call(this)`: a function run once, where it is written. */
+function isInvokedInPlace(fn) {
+  if (fn.type !== 'FunctionExpression' && fn.type !== 'ArrowFunctionExpression') return false;
+  let node = fn;
+  while (node.parent && WRAPPERS.has(node.parent.type)) node = node.parent;
+  const parent = node.parent;
+  if ((parent?.type === 'CallExpression' || parent?.type === 'NewExpression') && parent.callee === node) {
+    return true;
+  }
+  return (
+    parent?.type === 'MemberExpression' &&
+    parent.object === node &&
+    (propertyName(parent) === 'call' || propertyName(parent) === 'apply') &&
+    parent.parent?.type === 'CallExpression' &&
+    parent.parent.callee === parent
+  );
+}
+
+/**
+ * The plugin: `import tinvar from '@tinvar/renderer/eslint'`, then
+ * `tinvar.configs.server` in a flat config, or a rule by name --
+ * `'@tinvar/no-mutable-module-state'`,
+ * `'@tinvar/authorize-queries-in-can-branches'` -- in a block of the app's
+ * own for another layout. The second reads what `tinvar codegen` wrote
+ * (QUERY_MAP) from where ESLint runs, or from its `queryMap` option.
+ */
+const plugin = {
+  meta: { name: '@tinvar/renderer/eslint', namespace: '@tinvar' },
+  rules: {
+    'no-mutable-module-state': noMutableModuleState,
+    'authorize-queries-in-can-branches': authorizeQueriesInCanBranches,
+  },
+  configs: /** @type {Record<string, object>} */ ({}),
+};
+
+plugin.configs.server = {
+  name: '@tinvar/server',
+  files: SERVER_FILES,
+  plugins: { '@tinvar': plugin },
+  rules: {
+    '@tinvar/no-mutable-module-state': 'error',
+    '@tinvar/authorize-queries-in-can-branches': 'error',
+  },
+};
+
+export { authorizeQueriesInCanBranches };
+export const { rules, configs } = plugin;
+export default plugin;