@cplieger/deadset-ts 3.3.1 → 3.4.0

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),
     },
   };
 

package/src/schema.ts

@@ -28,6 +28,12 @@ export interface KeyNode {
 
 const leaf: KeyNode = { kind: "leaf" };
 
+/** A list of declarations, each entry in one of the three shapes the `ts` section states. */
+const declarations: KeyNode = {
+  kind: "list",
+  members: { symbol: leaf, module: leaf, name: leaf, global: leaf },
+};
+
 /**
  * The closed key list the Contract's configuration schema declares, derived from
  * that schema key by key. A test pins the two equal, so a Contract change that
@@ -72,7 +78,19 @@ export const SCHEMA_ROOT: KeyNode = {
       },
     },
     go: { kind: "section", members: {} },
-    ts: { kind: "section", members: { test_files: leaf, entry_files: leaf } },
+    ts: {
+      kind: "section",
+      members: {
+        test_files: leaf,
+        entry_files: leaf,
+        injection_registrations: declarations,
+        lifecycle_contracts: {
+          kind: "list",
+          members: { components: declarations, bases: declarations, members: leaf },
+        },
+        serializers: declarations,
+      },
+    },
     provenance: { kind: "map" },
   },
 };