@cplieger/deadset-ts 3.3.0 → 3.4.0

package/src/framework-lifecycle.ts

@@ -0,0 +1,280 @@
+/**
+ * The framework-lifecycle class: a member a `ts.lifecycle_contracts` entry lists is held
+ * back on each class that is the entry's component, being a class a decorator or a call
+ * the entry's `components` name is attached to or passes, or one extending, directly or
+ * through a chain, a class its `bases` name. A component's members are its type's, so a
+ * member a base class declares answers for every subclass.
+ */
+
+import {
+  isClassDeclaration,
+  isClassExpression,
+  isHeritageClause,
+  SyntaxKind,
+  type CallExpression,
+  type Node,
+} from "@typescript/native/unstable/ast";
+import type { Type } from "@typescript/native/unstable/sync";
+import { aliasChains, type AliasChains } from "./alias-chain.ts";
+import { calleeName, callsOf, classesPassed, decoratedClasses, decoratorCallee } from "./calls.ts";
+import { classMembers, memberComponent, typesAt, type ClassSide } from "./class-members.ts";
+import type { DeclarationEntry, LifecycleContract } from "./config.ts";
+import {
+  entriesAt,
+  names,
+  namesADeclaration,
+  resolveEntries,
+  spelledEntry,
+  type ResolvedEntry,
+} from "./configured-declarations.ts";
+import type { DetectorInput, Evidence } from "./exempt.ts";
+import { nodeKey, type Inventory } from "./inventory.ts";
+import { renderPosition } from "./position.ts";
+import type { ProjectView } from "./session.ts";
+
+/** One class that is a component of one contract, and what says it is. */
+interface Component {
+  readonly contract: LifecycleContract;
+  readonly id: string;
+  readonly site: Node;
+  readonly detail: string;
+}
+
+/** One contract's declarations, resolved in the project. */
+interface ResolvedContract {
+  readonly contract: LifecycleContract;
+  readonly components: readonly ResolvedEntry[];
+  readonly bases: readonly ResolvedEntry[];
+}
+
+/** Every contract's components and bases, resolved in one pass over the entries. */
+function resolveContracts<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+  contracts: readonly LifecycleContract[],
+): readonly ResolvedContract[] {
+  const entries: DeclarationEntry[] = contracts.flatMap((contract) => [
+    ...contract.components,
+    ...contract.bases,
+  ]);
+  const resolved = resolveEntries(project, held, entries);
+  let next = 0;
+  const take = (count: number): readonly ResolvedEntry[] => {
+    const taken = resolved.slice(next, next + count).filter(namesADeclaration);
+    next += count;
+    return taken;
+  };
+  return contracts.map((contract) => ({
+    contract,
+    components: take(contract.components.length),
+    bases: take(contract.bases.length),
+  }));
+}
+
+/** The classes a decorator or a call the contracts' components name makes a component. */
+function byComponents<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+  chains: AliasChains,
+  contracts: readonly ResolvedContract[],
+): readonly Component[] {
+  const routed = contracts.filter((one) => one.components.length > 0);
+  if (routed.length === 0) {
+    return [];
+  }
+  const contractOf = new Map(
+    routed.flatMap((one) => one.components.map((entry) => [entry, one.contract] as const)),
+  );
+  const calls = callsOf(project);
+  const decorated = decoratedClasses(project, held);
+  const named = entriesAt(
+    project,
+    chains,
+    [
+      ...calls.flatMap((call) => calleeName(call.expression) ?? []),
+      ...decorated.flatMap((one) =>
+        one.decorators.flatMap((decorator) => decoratorCallee(decorator) ?? []),
+      ),
+    ],
+    [...contractOf.keys()],
+  );
+  const naming = (node: Node | undefined): { contract: LifecycleContract; detail: string }[] =>
+    (node === undefined ? [] : (named.get(node) ?? [])).flatMap((entry) => {
+      const contract = contractOf.get(entry);
+      return contract === undefined ? [] : [{ contract, detail: spelledEntry(entry.entry, held) }];
+    });
+
+  const found: Component[] = [];
+  for (const one of decorated) {
+    for (const decorator of one.decorators) {
+      for (const { contract, detail } of naming(decoratorCallee(decorator))) {
+        found.push({ contract, id: one.id, site: decorator, detail: `decorated by @${detail}` });
+      }
+    }
+  }
+  const matched = new Map<CallExpression, { contract: LifecycleContract; detail: string }[]>();
+  for (const call of calls) {
+    const routes = naming(calleeName(call.expression));
+    if (routes.length > 0) {
+      matched.set(call, routes);
+    }
+  }
+  for (const [call, uses] of classesPassed(project, held, chains, [...matched.keys()])) {
+    for (const route of matched.get(call) ?? []) {
+      for (const use of uses) {
+        found.push({
+          contract: route.contract,
+          id: use.id,
+          site: use.site,
+          detail: `registered by ${route.detail}`,
+        });
+      }
+    }
+  }
+  return found;
+}
+
+/** Each class declaration of the target, with its name and the class its `extends` names. */
+interface Declared {
+  readonly id: string;
+  readonly name: Node;
+  readonly extended: Node;
+}
+
+/** The class declarations of the target that extend another class. */
+function extendingClasses<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+): readonly Declared[] {
+  const found: Declared[] = [];
+  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));
+        const clause = (node.heritageClauses ?? []).find(
+          (one) => isHeritageClause(one) && one.token === SyntaxKind.ExtendsKeyword,
+        );
+        const extended =
+          clause !== undefined && isHeritageClause(clause) ? clause.types[0] : undefined;
+        if (id !== undefined && extended !== undefined) {
+          found.push({ id, name: node.name, extended });
+        }
+      }
+      node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+  }
+  return found;
+}
+
+/** The classes that extend, directly or through a chain, a class the contracts' bases name. */
+function byBases<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+  chains: AliasChains,
+  contracts: readonly ResolvedContract[],
+): readonly Component[] {
+  const based = contracts.filter((one) => one.bases.length > 0);
+  if (based.length === 0) {
+    return [];
+  }
+  const classes = extendingClasses(project, held);
+  if (classes.length === 0) {
+    return [];
+  }
+  const checker = project.checker;
+  const ancestry = new Map<number, readonly Type[]>();
+  const ancestorsOf = (type: Type, seen: Set<number>): readonly Type[] => {
+    const known = ancestry.get(type.id);
+    if (known !== undefined) {
+      return known;
+    }
+    const declared = type.isClassOrInterface()
+      ? type
+      : type.isTypeReference()
+        ? type.getTarget()
+        : undefined;
+    if (declared === undefined || !declared.isClassOrInterface() || seen.has(declared.id)) {
+      return [];
+    }
+    seen.add(declared.id);
+    const found = checker
+      .getBaseTypes(declared)
+      .flatMap((base) => [base, ...ancestorsOf(base, seen)]);
+    ancestry.set(type.id, found);
+    return found;
+  };
+  const types = typesAt(
+    project,
+    classes.map((one) => one.name),
+  );
+
+  const found: Component[] = [];
+  classes.forEach((one, index) => {
+    const type = types[index];
+    if (type === undefined) {
+      return;
+    }
+    const ancestors = ancestorsOf(type, new Set()).flatMap((base) => base.getSymbol() ?? []);
+    for (const contract of based) {
+      for (const entry of contract.bases) {
+        if (ancestors.some((symbol) => names(entry, symbol, chains))) {
+          found.push({
+            contract: contract.contract,
+            id: one.id,
+            site: one.extended,
+            detail: `extends ${spelledEntry(entry.entry, held)}`,
+          });
+        }
+      }
+    }
+  });
+  return found;
+}
+
+/**
+ * The framework-lifecycle detector: each member a contract lists, on each class that
+ * is a component of that contract's framework, recorded where the class was found to
+ * be one.
+ */
+export function frameworkLifecycle<Brand>(input: DetectorInput<Brand>): readonly Evidence[] {
+  const { project, held, targetRoot } = input;
+  if (input.ts.lifecycleContracts.length === 0) {
+    return [];
+  }
+  const chains = aliasChains(project, held);
+  const contracts = resolveContracts(project, held, input.ts.lifecycleContracts);
+  const components = [
+    ...byComponents(project, held, chains, contracts),
+    ...byBases(project, held, chains, contracts),
+  ];
+  if (components.length === 0) {
+    return [];
+  }
+  const ids = new Set(components.map((one) => one.id));
+  const sides: readonly ClassSide[] = input.ts.lifecycleContracts.some((contract) =>
+    contract.members.some((name) => name.endsWith(":static")),
+  )
+    ? ["instance", "static"]
+    : ["instance"];
+  const members = sides.map((side) => classMembers(project, held, ids, side));
+  const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
+
+  const found: Evidence[] = [];
+  for (const component of components) {
+    const listed = new Set(component.contract.members);
+    const site = renderPosition(
+      component.site.getSourceFile(),
+      targetRoot,
+      component.site.getStart(),
+    );
+    for (const member of members.flatMap((side) => side.get(component.id) ?? [])) {
+      const symbol = byId.get(member.id);
+      const spelled = symbol === undefined ? undefined : memberComponent(symbol, byId);
+      if (spelled !== undefined && listed.has(spelled)) {
+        found.push({ id: member.id, detail: component.detail, site });
+      }
+    }
+  }
+  return found;
+}

package/src/injection-container.ts

@@ -0,0 +1,141 @@
+/**
+ * The injection-container class: a container constructs a class passed to a call
+ * `ts.injection_registrations` names, or one a parameter of whose constructor carries a
+ * decorator, and populates each of its properties and accessors that carries one, a base
+ * class's included. A constructor and its parameters are no declarations of the
+ * inventory, so the class stands for them and the registration referencing it keeps it.
+ */
+
+import {
+  isClassDeclaration,
+  isClassExpression,
+  isConstructorDeclaration,
+  isGetAccessorDeclaration,
+  isPropertyDeclaration,
+  isSetAccessorDeclaration,
+  type CallExpression,
+  type Node,
+} from "@typescript/native/unstable/ast";
+import { aliasChains } from "./alias-chain.ts";
+import { calleeName, callsOf, classesPassed, decoratorsOf, spelledDecorator } from "./calls.ts";
+import { classMembers, type ClassMember } from "./class-members.ts";
+import {
+  entriesAt,
+  namesADeclaration,
+  resolveEntries,
+  spelledEntry,
+  type ResolvedEntry,
+} from "./configured-declarations.ts";
+import type { DetectorInput, Evidence } from "./exempt.ts";
+import { nodeKey } from "./inventory.ts";
+import { renderPosition } from "./position.ts";
+
+/** One class a container constructs, by the registration that says so. */
+interface Registration {
+  readonly id: string;
+  readonly site: Node;
+  readonly detail: string;
+}
+
+/** Whether one member declaration is a property or an accessor carrying a decorator. */
+function isInjected(node: Node): boolean {
+  return (
+    (isPropertyDeclaration(node) ||
+      isGetAccessorDeclaration(node) ||
+      isSetAccessorDeclaration(node)) &&
+    decoratorsOf(node).length > 0
+  );
+}
+
+/** The classes of the target a call whose callee an entry names passes, with that call's entry. */
+function registrations<Brand>(input: DetectorInput<Brand>): readonly Registration[] {
+  const { project, held } = input;
+  const resolved = resolveEntries(project, held, input.ts.injectionRegistrations);
+  if (!resolved.some(namesADeclaration)) {
+    return [];
+  }
+  const chains = aliasChains(project, held);
+  const calls = callsOf(project);
+  const named = entriesAt(
+    project,
+    chains,
+    calls.flatMap((call) => calleeName(call.expression) ?? []),
+    resolved,
+  );
+  const matched = new Map<CallExpression, ResolvedEntry>();
+  for (const call of calls) {
+    const name = calleeName(call.expression);
+    const [entry] = name === undefined ? [] : (named.get(name) ?? []);
+    if (entry !== undefined) {
+      matched.set(call, entry);
+    }
+  }
+  return [...classesPassed(project, held, chains, [...matched.keys()])].flatMap(([call, uses]) => {
+    const entry = matched.get(call);
+    const detail = entry === undefined ? "" : `registered by ${spelledEntry(entry.entry, held)}`;
+    return uses.map((use) => ({ id: use.id, site: use.site, detail }));
+  });
+}
+
+/** The classes of the target a parameter of whose constructor carries a decorator. */
+function constructedForParameters<Brand>(input: DetectorInput<Brand>): ReadonlySet<string> {
+  const { project, held } = input;
+  const found = new Set<string>();
+  for (const file of project.ownSourceFiles()) {
+    const visit = (node: Node): void => {
+      if (isClassDeclaration(node) || isClassExpression(node)) {
+        const id = held.declarations.get(nodeKey(file, node));
+        const asks = node.members.some(
+          (member) =>
+            isConstructorDeclaration(member) &&
+            member.parameters.some((parameter) => decoratorsOf(parameter).length > 0),
+        );
+        if (id !== undefined && asks) {
+          found.add(id);
+        }
+      }
+      node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+  }
+  return found;
+}
+
+/**
+ * The injection-container detector: each decorated property or accessor of a class a
+ * container constructs, recorded at the registration that names the class, or, for a
+ * class whose constructor asks for its parameters, at the member's own decorator.
+ */
+export function injectionContainer<Brand>(input: DetectorInput<Brand>): readonly Evidence[] {
+  const { project, held, targetRoot } = input;
+  const registered = registrations(input);
+  const constructed = constructedForParameters(input);
+  const classes = new Set([...registered.map((one) => one.id), ...constructed]);
+  if (classes.size === 0) {
+    return [];
+  }
+  const members = classMembers(project, held, classes, "instance");
+  const injected = (id: string): readonly ClassMember[] =>
+    (members.get(id) ?? []).filter((member) => isInjected(member.node));
+  const at = (node: Node) => renderPosition(node.getSourceFile(), targetRoot, node.getStart());
+
+  const found: Evidence[] = [];
+  for (const registration of registered) {
+    for (const member of injected(registration.id)) {
+      found.push({ id: member.id, detail: registration.detail, site: at(registration.site) });
+    }
+  }
+  for (const id of constructed) {
+    for (const member of injected(id)) {
+      const [decorator] = decoratorsOf(member.node);
+      if (decorator !== undefined) {
+        found.push({
+          id: member.id,
+          detail: `injected by ${spelledDecorator(decorator)}`,
+          site: at(decorator),
+        });
+      }
+    }
+  }
+  return found;
+}

package/src/print.ts

@@ -1,4 +1,16 @@
-import { renderOrigin, type Config, type Provenance } from "./config.ts";
+import { renderOrigin, type Config, type DeclarationEntry, type Provenance } from "./config.ts";
+
+/** One declaration entry as a document writes it: the members of its shape alone. */
+function declarationOf(entry: DeclarationEntry): Record<string, string> {
+  switch (entry.shape) {
+    case "symbol":
+      return { symbol: entry.symbol };
+    case "module":
+      return { module: entry.module, name: entry.name };
+    case "global":
+      return { global: entry.global };
+  }
+}
 
 /**
  * The resolved configuration and its provenance as one JSON object, indented,
@@ -47,6 +59,13 @@ export function printConfig(config: Config, provenance: Provenance): string {
     ts: {
       test_files: config.ts.testFiles,
       entry_files: config.ts.entryFiles,
+      injection_registrations: config.ts.injectionRegistrations.map(declarationOf),
+      lifecycle_contracts: config.ts.lifecycleContracts.map((entry) => ({
+        components: entry.components.map(declarationOf),
+        bases: entry.bases.map(declarationOf),
+        members: entry.members,
+      })),
+      serializers: config.ts.serializers.map(declarationOf),
     },
     provenance: Object.fromEntries(
       [...provenance]

package/src/resolve.ts

@@ -6,10 +6,12 @@ import {
   type Config,
   type Confidence,
   type ConsumerTests,
+  type DeclarationEntry,
   type Format,
   type GeneratedFiles,
   type Inputs,
   type Language,
+  type LifecycleContract,
   type Origin,
   type Provenance,
   type Severity,
@@ -94,6 +96,9 @@ interface Doc {
   readonly failOn: Severity | undefined;
   readonly testFiles: readonly string[] | undefined;
   readonly entryFiles: readonly string[] | undefined;
+  readonly injectionRegistrations: readonly DeclarationEntry[] | undefined;
+  readonly lifecycleContracts: readonly LifecycleContract[] | undefined;
+  readonly serializers: readonly DeclarationEntry[] | undefined;
 }
 
 /** One document the resolution reads, with the origin its settings carry. */
@@ -476,6 +481,137 @@ function readExemptions(
   return disabled;
 }
 
+/** The members that name a declaration, each belonging to exactly one shape. */
+const SHAPE_MEMBERS = ["symbol", "module", "name", "global"] as const;
+
+/** The prefix of a stable symbol reference in the TypeScript form. */
+const SYMBOL_PREFIX = "ts://";
+
+/**
+ * A bare specifier: neither relative nor absolute, and not one the package's own
+ * imports field maps, each of which names a file of the analyzed program.
+ */
+const BARE_SPECIFIER = /^[^./#]/u;
+
+/**
+ * One declaration entry, read as the one shape its members name. An entry carrying
+ * members of two shapes, or of none, is refused at the entry, as is a module named
+ * without the declaration's path or a path without its module.
+ */
+function readDeclaration(entry: unknown, at: string, label: string): DeclarationEntry {
+  if (!isRecord(entry)) {
+    throw malformed(label, at, "is not an object");
+  }
+  const named = SHAPE_MEMBERS.filter((name) => Object.hasOwn(entry, name));
+  if (named.length === 1 && named[0] === "symbol") {
+    const symbol = requireMember(
+      readString(entry, "symbol", `${at}.symbol`, label),
+      `${at}.symbol`,
+      label,
+    );
+    if (!symbol.startsWith(SYMBOL_PREFIX)) {
+      throw malformed(label, `${at}.symbol`, `${JSON.stringify(symbol)} is not a ts:// reference`);
+    }
+    return { shape: "symbol", symbol };
+  }
+  if (named.length === 1 && named[0] === "global") {
+    const path = `${at}.global`;
+    return {
+      shape: "global",
+      global: requireMember(readString(entry, "global", path, label), path, label),
+    };
+  }
+  if (named.length === 2 && named.includes("module") && named.includes("name")) {
+    const module = requireMember(
+      readString(entry, "module", `${at}.module`, label),
+      `${at}.module`,
+      label,
+    );
+    if (!BARE_SPECIFIER.test(module)) {
+      throw malformed(
+        label,
+        `${at}.module`,
+        `${JSON.stringify(module)} is not a bare specifier: a file of the analyzed program is named by its symbol`,
+      );
+    }
+    const path = `${at}.name`;
+    return {
+      shape: "module",
+      module,
+      name: requireMember(readString(entry, "name", path, label), path, label),
+    };
+  }
+  throw malformed(
+    label,
+    at,
+    named.length === 0
+      ? 'names no declaration: an entry carries "symbol", "module" with "name", or "global"'
+      : `carries ${spell(named)}, which is not one of "symbol", "module" with "name", or "global"`,
+  );
+}
+
+/** One array of declaration entries, absent where the document does not write it. */
+function readDeclarations(
+  parent: Record<string, unknown> | undefined,
+  name: string,
+  path: string,
+  label: string,
+): readonly DeclarationEntry[] | undefined {
+  const value = member(parent, name);
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(value)) {
+    throw malformed(label, path, "is not an array");
+  }
+  return (value as unknown[]).map((entry, index) =>
+    readDeclaration(entry, `${path}[${String(index)}]`, label),
+  );
+}
+
+/**
+ * One lifecycle contract. The member names are required, and the entry names at least
+ * one component declaration or one base class, because a contract naming neither
+ * makes no class a component and so retains nothing.
+ */
+function readLifecycleContract(entry: unknown, at: string, label: string): LifecycleContract {
+  if (!isRecord(entry)) {
+    throw malformed(label, at, "is not an object");
+  }
+  const components = readDeclarations(entry, "components", `${at}.components`, label) ?? [];
+  const bases = readDeclarations(entry, "bases", `${at}.bases`, label) ?? [];
+  const members = readStrings(entry, "members", `${at}.members`, label, 1);
+  if (members === undefined) {
+    throw malformed(label, `${at}.members`, "is required and names nothing");
+  }
+  if (components.length === 0 && bases.length === 0) {
+    throw malformed(
+      label,
+      at,
+      'names no declaration in "components" and no class in "bases", so it makes no class a component',
+    );
+  }
+  return { components, bases, members };
+}
+
+/** The lifecycle contracts, one per framework the project declares. */
+function readLifecycleContracts(
+  ts: Record<string, unknown> | undefined,
+  label: string,
+): readonly LifecycleContract[] | undefined {
+  const path = "ts.lifecycle_contracts";
+  const value = member(ts, "lifecycle_contracts");
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(value)) {
+    throw malformed(label, path, "is not an array");
+  }
+  return (value as unknown[]).map((entry, index) =>
+    readLifecycleContract(entry, `${path}[${String(index)}]`, label),
+  );
+}
+
 /**
  * Reads one already-parsed configuration document as the settings it supplies,
  * refusing every constraint the closed key list declares that a parse cannot
@@ -545,6 +681,14 @@ function readDoc(value: unknown, label: string): Doc {
     failOn: readEnum(reporters, "fail_on", "reporters.fail_on", label, SEVERITIES),
     testFiles: readStrings(ts, "test_files", "ts.test_files", label, 1),
     entryFiles: readStrings(ts, "entry_files", "ts.entry_files", label, 0),
+    injectionRegistrations: readDeclarations(
+      ts,
+      "injection_registrations",
+      "ts.injection_registrations",
+      label,
+    ),
+    lifecycleContracts: readLifecycleContracts(ts, label),
+    serializers: readDeclarations(ts, "serializers", "ts.serializers", label),
   };
 }
 
@@ -818,6 +962,17 @@ function settleAll(inputs: Inputs): { config: Config; provenance: Map<string, Or
     ts: {
       testFiles: at("ts.test_files", defaults.ts.testFiles, (doc) => doc.testFiles),
       entryFiles: at("ts.entry_files", defaults.ts.entryFiles, (doc) => doc.entryFiles),
+      injectionRegistrations: at(
+        "ts.injection_registrations",
+        defaults.ts.injectionRegistrations,
+        (doc) => doc.injectionRegistrations,
+      ),
+      lifecycleContracts: at(
+        "ts.lifecycle_contracts",
+        defaults.ts.lifecycleContracts,
+        (doc) => doc.lifecycleContracts,
+      ),
+      serializers: at("ts.serializers", defaults.ts.serializers, (doc) => doc.serializers),
     },
   };