@cplieger/deadset-ts 3.3.1 → 3.4.0

package/src/calls.ts

@@ -0,0 +1,224 @@
+/**
+ * The calls and decorators of one project that the configured classes read: what each
+ * callee resolves to, and which of the target's classes a call passes or a decorator
+ * is attached to. A class is passed as an argument, or as an element of an array
+ * literal or a property value of an object literal written as one, at any depth, and a
+ * decorator written as a call is a call.
+ */
+
+import {
+  isArrayLiteralExpression,
+  isCallExpression,
+  isClassDeclaration,
+  isDecorator,
+  isIdentifier,
+  isObjectLiteralExpression,
+  isParenthesizedExpression,
+  isPropertyAccessExpression,
+  isPropertyAssignment,
+  isShorthandPropertyAssignment,
+  isSpreadElement,
+  type CallExpression,
+  type Decorator,
+  type Expression,
+  type Node,
+} from "@typescript/native/unstable/ast";
+import { SymbolFlags, type Symbol as TSSymbol } from "@typescript/native/unstable/sync";
+import type { AliasChains } from "./alias-chain.ts";
+import { nodeKey, type Inventory } from "./inventory.ts";
+import { DEFAULT_BATCH_CAP } from "./references.ts";
+import type { ProjectView } from "./session.ts";
+
+/** One value written where a call passes it, and the node its declaration is resolved from. */
+export interface PassedValue {
+  /** Where the value is written, which is where a record of it sits. */
+  readonly site: Node;
+  /** The name the value is resolved through, or the shorthand assignment that holds it. */
+  readonly name: Node;
+  readonly shorthand: boolean;
+}
+
+/** One class of the target a call passes or a decorator is attached to, and where. */
+export interface ClassUse {
+  /** The inventory's identifier of the class. */
+  readonly id: string;
+  readonly site: Node;
+}
+
+/** The name node a callee or a decorator expression resolves through, where it has one. */
+export function calleeName(expression: Expression): Node | undefined {
+  if (isParenthesizedExpression(expression)) {
+    return calleeName(expression.expression);
+  }
+  if (isPropertyAccessExpression(expression)) {
+    return expression.name;
+  }
+  return isIdentifier(expression) ? expression : undefined;
+}
+
+/** The callee one decorator names: its expression, or the callee of the call it writes. */
+export function decoratorCallee(decorator: Decorator): Node | undefined {
+  const expression = decorator.expression;
+  return calleeName(isCallExpression(expression) ? expression.expression : expression);
+}
+
+/** How one decorator is spelled in a record: its expression, without a call's arguments. */
+export function spelledDecorator(decorator: Decorator): string {
+  const expression = decorator.expression;
+  const named = isCallExpression(expression) ? expression.expression : expression;
+  return `@${named.getText().replace(/\s+/gu, "")}`;
+}
+
+/** The decorators written on one declaration. */
+export function decoratorsOf(node: Node): readonly Decorator[] {
+  return ((node as { readonly modifiers?: readonly Node[] }).modifiers ?? []).filter(isDecorator);
+}
+
+/**
+ * What each of a batch of nodes resolves to, every alias followed to the declaration
+ * it stands for. A node the checker resolves to nothing, and an alias that resolves
+ * to nothing, are absent from the answer. Each alias is followed once.
+ */
+export function resolvedTargets<Brand>(
+  project: ProjectView<Brand>,
+  nodes: readonly Node[],
+): ReadonlyMap<Node, TSSymbol> {
+  const followed = new Map<number, TSSymbol | undefined>();
+  const targets = new Map<Node, TSSymbol>();
+  for (let from = 0; from < nodes.length; from += DEFAULT_BATCH_CAP) {
+    const run = nodes.slice(from, from + DEFAULT_BATCH_CAP);
+    project.symbolsAt(run.map((node) => project.handle(node))).forEach((symbol, index) => {
+      const node = run[index];
+      if (symbol === undefined || node === undefined) {
+        return;
+      }
+      let target: TSSymbol | undefined = symbol;
+      if ((symbol.flags & SymbolFlags.Alias) !== 0) {
+        if (!followed.has(symbol.id)) {
+          const aliased = project.checker.getAliasedSymbol(symbol);
+          followed.set(symbol.id, aliased.declarations.length === 0 ? undefined : aliased);
+        }
+        target = followed.get(symbol.id);
+      }
+      if (target !== undefined) {
+        targets.set(node, target);
+      }
+    });
+  }
+  return targets;
+}
+
+/** The values one expression passes: itself, or what an array or object literal holds. */
+function passedIn(expression: Expression, found: PassedValue[]): void {
+  if (isParenthesizedExpression(expression)) {
+    passedIn(expression.expression, found);
+    return;
+  }
+  if (isArrayLiteralExpression(expression)) {
+    for (const element of expression.elements) {
+      passedIn(isSpreadElement(element) ? element.expression : element, found);
+    }
+    return;
+  }
+  if (isObjectLiteralExpression(expression)) {
+    for (const property of expression.properties) {
+      if (isPropertyAssignment(property)) {
+        passedIn(property.initializer, found);
+      } else if (isShorthandPropertyAssignment(property)) {
+        found.push({ site: property.name, name: property, shorthand: true });
+      }
+    }
+    return;
+  }
+  const name = calleeName(expression);
+  if (name !== undefined) {
+    found.push({ site: expression, name, shorthand: false });
+  }
+}
+
+/** The values one argument passes, a spread argument's included. */
+export function valuesPassed(argument: Expression): readonly PassedValue[] {
+  const found: PassedValue[] = [];
+  passedIn(isSpreadElement(argument) ? argument.expression : argument, found);
+  return found;
+}
+
+/**
+ * The classes of the target each call passes, by the call. A value that names no
+ * class of the target, a class of another program included, passes nothing here.
+ */
+export function classesPassed<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+  chains: AliasChains,
+  calls: readonly CallExpression[],
+): ReadonlyMap<CallExpression, readonly ClassUse[]> {
+  const passed = new Map(
+    calls.map((call) => [call, call.arguments.flatMap((argument) => valuesPassed(argument))]),
+  );
+  const all = [...passed.values()].flat();
+  const targets = resolvedTargets(
+    project,
+    all.filter((value) => !value.shorthand).map((value) => value.name),
+  );
+  const classes = new Set(
+    held.symbols.filter((symbol) => symbol.kind === "class").map((symbol) => symbol.id),
+  );
+  const classesOf = (value: PassedValue): readonly string[] => {
+    const symbol = value.shorthand
+      ? project.shorthandValueAt(project.handle(value.name))
+      : targets.get(value.name);
+    return symbol === undefined
+      ? []
+      : chains.declarationsOf(symbol).filter((id) => classes.has(id));
+  };
+  return new Map(
+    [...passed].map(([call, values]) => [
+      call,
+      values.flatMap((value) => classesOf(value).map((id) => ({ id, site: value.site }))),
+    ]),
+  );
+}
+
+/** One class declaration of the target and the decorators written on it. */
+export interface DecoratedClass {
+  readonly id: string;
+  readonly decorators: readonly Decorator[];
+}
+
+/** Every class declaration of the target that carries a decorator. */
+export function decoratedClasses<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+): readonly DecoratedClass[] {
+  const found: DecoratedClass[] = [];
+  for (const file of project.ownSourceFiles()) {
+    const visit = (node: Node): void => {
+      if (isClassDeclaration(node)) {
+        const id = held.declarations.get(nodeKey(file, node));
+        const decorators = decoratorsOf(node);
+        if (id !== undefined && decorators.length > 0) {
+          found.push({ id, decorators });
+        }
+      }
+      node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+  }
+  return found;
+}
+
+/** Every call expression of the project's own files, decorators written as calls included. */
+export function callsOf<Brand>(project: ProjectView<Brand>): readonly CallExpression[] {
+  const found: CallExpression[] = [];
+  for (const file of project.ownSourceFiles()) {
+    const visit = (node: Node): void => {
+      if (isCallExpression(node)) {
+        found.push(node);
+      }
+      node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+  }
+  return found;
+}

package/src/class-members.ts

@@ -0,0 +1,136 @@
+/**
+ * The members a value of one of the target's classes carries, as the checker answers
+ * for the class's type, so a member a base class declares is a member of every class
+ * that extends it and a member a subclass overrides is the subclass's own.
+ */
+
+import { isClassDeclaration, isClassExpression, type Node } from "@typescript/native/unstable/ast";
+import type { Symbol as TSSymbol, SymbolFlags, Type } from "@typescript/native/unstable/sync";
+import { nodeKey, type Inventory, type InventorySymbol } from "./inventory.ts";
+import { DEFAULT_BATCH_CAP } from "./references.ts";
+import type { ProjectView } from "./session.ts";
+
+/** One member of a class's value that the target declares. */
+export interface ClassMember {
+  /** The inventory's identifier of the declaration. */
+  readonly id: string;
+  /** The declaring node, whose syntax says whether it is a property, an accessor or a method. */
+  readonly node: Node;
+  /** The member's symbol flags, as the checker reads it on this class. */
+  readonly flags: SymbolFlags;
+}
+
+/** Which side of a class a reading asks for: its instances, or the class itself. */
+export type ClassSide = "instance" | "static";
+
+/** The name node of each class declaration of the target, by the class's identifier. */
+export function classNames<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+): ReadonlyMap<string, Node> {
+  const names = new Map<string, Node>();
+  for (const file of project.ownSourceFiles()) {
+    const visit = (node: Node): void => {
+      if ((isClassDeclaration(node) || isClassExpression(node)) && node.name !== undefined) {
+        const id = held.declarations.get(nodeKey(file, node));
+        if (id !== undefined) {
+          names.set(id, node.name);
+        }
+      }
+      node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+  }
+  return names;
+}
+
+/** The types of a batch of nodes, asked in capped batches. */
+export function typesAt<Brand>(
+  project: ProjectView<Brand>,
+  nodes: readonly Node[],
+): (Type | undefined)[] {
+  const types: (Type | undefined)[] = [];
+  for (let from = 0; from < nodes.length; from += DEFAULT_BATCH_CAP) {
+    types.push(...project.checker.getTypeAtLocation(nodes.slice(from, from + DEFAULT_BATCH_CAP)));
+  }
+  return types;
+}
+
+/**
+ * The type one side of each class is: the instance type at the class's name, or the
+ * type of the class's own symbol, which is its constructor's.
+ */
+function sideTypes<Brand>(
+  project: ProjectView<Brand>,
+  nodes: readonly Node[],
+  side: ClassSide,
+): (Type | undefined)[] {
+  if (side === "instance") {
+    return typesAt(project, nodes);
+  }
+  const symbols = project.symbolsAt(nodes.map((node) => project.handle(node)));
+  const present = symbols.filter((symbol): symbol is TSSymbol => symbol !== undefined);
+  const types = present.length === 0 ? [] : project.checker.getTypeOfSymbol(present);
+  let next = 0;
+  return symbols.map((symbol) => (symbol === undefined ? undefined : types[next++]));
+}
+
+/**
+ * The members one side of each class carries that the target declares, by the class.
+ * A member declared in a file outside the project's own, and the `prototype` a class
+ * carries on its static side, are not declarations of the target and are left out.
+ */
+export function classMembers<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+  classIds: ReadonlySet<string>,
+  side: ClassSide,
+): ReadonlyMap<string, readonly ClassMember[]> {
+  const named = [...classNames(project, held)].filter(([id]) => classIds.has(id));
+  const own = new Set(project.ownSourceFiles().map((file) => file.fileName));
+  const types = sideTypes(
+    project,
+    named.map(([, node]) => node),
+    side,
+  );
+  const members = new Map<string, readonly ClassMember[]>();
+  named.forEach(([id], index) => {
+    const type = types[index];
+    if (type === undefined) {
+      return;
+    }
+    const found: ClassMember[] = [];
+    for (const property of project.checker.getPropertiesOfType(type)) {
+      for (const handle of property.declarations) {
+        if (!own.has(handle.path)) {
+          continue;
+        }
+        const node = project.declarationAt(handle)?.node;
+        const declared =
+          node === undefined
+            ? undefined
+            : held.declarations.get(nodeKey(node.getSourceFile(), node));
+        if (node !== undefined && declared !== undefined) {
+          found.push({ id: declared, node, flags: property.flags });
+        }
+      }
+    }
+    members.set(id, found);
+  });
+  return members;
+}
+
+/**
+ * The last component of one member's stable reference, `:static` included, which is
+ * how a configuration names a member; undefined for a declaration that is no member.
+ */
+export function memberComponent(
+  symbol: InventorySymbol,
+  byId: ReadonlyMap<string, InventorySymbol>,
+): string | undefined {
+  const parent = byId.get(symbol.parent);
+  if (parent === undefined || !symbol.ref.startsWith(`${parent.ref}.`)) {
+    return undefined;
+  }
+  return symbol.ref.slice(parent.ref.length + 1);
+}

package/src/config.ts

@@ -97,10 +97,38 @@ export interface Reporters {
   readonly failOn: Severity;
 }
 
+/**
+ * One declaration a configuration entry names, in exactly one of three shapes: a
+ * declaration of the analyzed program by its stable symbol reference, a declaration a
+ * module exports by the bare specifier an import writes for the module and the
+ * declaration's path from its exports, or a declaration of the global scope by its
+ * path from that scope. A path joins the name and each member with dots and spells a
+ * static member with `:static` after it.
+ */
+export type DeclarationEntry =
+  | { readonly shape: "symbol"; readonly symbol: string }
+  | { readonly shape: "module"; readonly module: string; readonly name: string }
+  | { readonly shape: "global"; readonly global: string };
+
+/**
+ * One framework's lifecycle contract: the declarations whose use makes a class one of
+ * the framework's components, the classes whose subclasses are its components, and the
+ * names of the members the framework calls on a component, each spelled as the last
+ * component of a member's stable symbol reference.
+ */
+export interface LifecycleContract {
+  readonly components: readonly DeclarationEntry[];
+  readonly bases: readonly DeclarationEntry[];
+  readonly members: readonly string[];
+}
+
 /** The section the TypeScript analyzer owns. */
 export interface TSSection {
   readonly testFiles: readonly string[];
   readonly entryFiles: readonly string[];
+  readonly injectionRegistrations: readonly DeclarationEntry[];
+  readonly lifecycleContracts: readonly LifecycleContract[];
+  readonly serializers: readonly DeclarationEntry[];
 }
 
 /**
@@ -159,6 +187,9 @@ export function defaultConfig(): Config {
     ts: {
       testFiles: ["**/*.test.{ts,tsx,mts,cts}"],
       entryFiles: [],
+      injectionRegistrations: [],
+      lifecycleContracts: [],
+      serializers: [],
     },
   };
 }