@cplieger/deadset-ts 8.0.0-dev.20 → 8.0.0-dev.21

package/src/exemptions/installed-globals.ts

@@ -0,0 +1,255 @@
+/**
+ * The classes a program installs as globals: a class value written into a property of
+ * the global object, which code outside the analysis that names the global constructs.
+ * The checker finds each write: the receiver's type is the global object's, the callee is
+ * the standard library's `Object.defineProperty` or a test runner's stub, and the
+ * property is the one of the key's name that `typeof globalThis` declares.
+ */
+
+import {
+  isIdentifier,
+  isNoSubstitutionTemplateLiteral,
+  isObjectLiteralExpression,
+  isPropertyAssignment,
+  isShorthandPropertyAssignment,
+  isStringLiteral,
+  type Expression,
+  type Node,
+} from "@typescript/native/ast";
+import {
+  SignatureKind,
+  SymbolFlags,
+  type Symbol as TSSymbol,
+  type Type,
+} from "@typescript/native/sync";
+import type { AliasChains } from "../alias-chain.ts";
+import { typesAt } from "../class-members.ts";
+import { packageOfPath } from "../dependencies.ts";
+import type { Inventory } from "../inventory.ts";
+import { must } from "../query.ts";
+import type { ProjectView } from "../session.ts";
+import { parenthesesRemoved, unwrapped } from "../unwrap.ts";
+import { spansOf } from "./argument-places.ts";
+import { classesCarried } from "./calls.ts";
+import type { ProjectSites } from "./sites.ts";
+
+/** A call that writes a value into a property of an object, by the places of its arguments. */
+interface Writer {
+  /** The object's place, none where the object is the global one. */
+  readonly object: number | undefined;
+  readonly key: number;
+  readonly value: number;
+  /** Whether the value is the `value` member of a property descriptor. */
+  readonly described: boolean;
+}
+
+/**
+ * The test runners' stubs of a global, by method name and the packages that declare it:
+ * `vi.stubGlobal` of vitest, and `jest.replaceProperty`, which `@jest/environment` types
+ * for `@jest/globals` and `@types/jest` declares for the `jest` global.
+ */
+const STUBS: ReadonlyMap<string, Writer & { readonly packages: ReadonlySet<string> }> = new Map([
+  [
+    "stubGlobal",
+    { packages: new Set(["vitest"]), object: undefined, key: 0, value: 1, described: false },
+  ],
+  [
+    "replaceProperty",
+    {
+      packages: new Set(["@jest/environment", "@jest/globals", "@types/jest"]),
+      object: 0,
+      key: 1,
+      value: 2,
+      described: false,
+    },
+  ],
+]);
+
+/** `Object.defineProperty(object, key, descriptor)`. */
+const DEFINE: Writer = { object: 0, key: 1, value: 2, described: true };
+
+/** One write of a value into a property a written key names. */
+interface Write {
+  readonly site: Node;
+  /** The object written to, none where it is the global one. */
+  readonly receiver: Expression | undefined;
+  readonly key: string;
+  readonly value: Expression;
+}
+
+/** One class a write installs as a global, and the instance types the global constructs. */
+interface Installed {
+  readonly id: string;
+  readonly site: Node;
+  readonly global: string;
+  readonly instances: readonly Type[];
+}
+
+/** The text of a key written as a string literal. */
+function keyText(node: Expression | undefined): string | undefined {
+  const key = node === undefined ? undefined : parenthesesRemoved(node);
+  return key !== undefined && (isStringLiteral(key) || isNoSubstitutionTemplateLiteral(key))
+    ? key.text
+    : undefined;
+}
+
+/** Whether a property's name is `value`. */
+function named(name: Node): boolean {
+  return (isIdentifier(name) || isStringLiteral(name)) && name.text === "value";
+}
+
+/** The value a property descriptor written as an object literal gives. */
+function describedValue(node: Expression | undefined): Expression | undefined {
+  const descriptor = node === undefined ? undefined : parenthesesRemoved(node);
+  if (descriptor === undefined || !isObjectLiteralExpression(descriptor)) {
+    return undefined;
+  }
+  for (const property of descriptor.properties) {
+    if (isPropertyAssignment(property) && named(property.name)) {
+      return property.initializer;
+    }
+    if (
+      isShorthandPropertyAssignment(property) &&
+      isIdentifier(property.name) &&
+      named(property.name)
+    ) {
+      return property.name;
+    }
+  }
+  return undefined;
+}
+
+/** How a call's callee writes a property: the standard library's `Object.defineProperty` or a runner's stub. */
+function writerOf<Brand>(project: ProjectView<Brand>, method: TSSymbol): Writer | undefined {
+  if (method.name === "defineProperty") {
+    const standard = method.declarations.some(
+      (handle) => project.program.getSourceFileMetadata(handle.path)?.isDefaultLibrary === true,
+    );
+    return standard && must(project.queries.parentOf(method))?.name === "ObjectConstructor"
+      ? DEFINE
+      : undefined;
+  }
+  const stub = STUBS.get(method.name);
+  return stub !== undefined &&
+    method.declarations.some((handle) => stub.packages.has(packageOfPath(handle.path) ?? ""))
+    ? stub
+    : undefined;
+}
+
+/** Each write of one project's own files that may install a value as a global, read from syntax and the callee. */
+function writesOf<Brand>(project: ProjectView<Brand>, sites: ProjectSites): readonly Write[] {
+  const found: Write[] = sites.stores.map((store) => ({
+    site: store.store,
+    receiver: store.receiver,
+    key: store.key,
+    value: store.value,
+  }));
+  for (const { call } of sites.calls) {
+    const method = sites.invocations.callee(call);
+    const writer = method === undefined ? undefined : writerOf(project, method);
+    if (writer === undefined) {
+      continue;
+    }
+    const invoked = sites.invocations.of(call);
+    // With no types asked, a spread has no known length, so only a place no spread
+    // comes at or before is read.
+    const spans = spansOf(project, invoked.arguments, invoked.listed, []);
+    const at = (place: number): Expression | undefined => {
+      const span = spans.find((one) => !one.open && one.first === place);
+      return span === undefined ? undefined : invoked.arguments[span.argument];
+    };
+    const key = keyText(at(writer.key));
+    const receiver = writer.object === undefined ? undefined : at(writer.object);
+    const value = writer.described ? describedValue(at(writer.value)) : at(writer.value);
+    if (
+      key !== undefined &&
+      value !== undefined &&
+      (writer.object === undefined || receiver !== undefined)
+    ) {
+      found.push({ site: call, receiver, key, value });
+    }
+  }
+  return found;
+}
+
+/**
+ * The classes one project installs as globals. A write installs one where its object is
+ * the global object, as the checker types it (`window` and `self` are intersections that
+ * hold `typeof globalThis`, and an object asserted to `any` is read inside the
+ * assertion), and where the global object declares a property of the key's name with a
+ * construct signature, whose instances code outside the analysis makes.
+ */
+export function installedGlobals<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+  chains: AliasChains,
+  sites: ProjectSites,
+): readonly Installed[] {
+  const { queries } = project;
+  const writes = writesOf(project, sites);
+  if (writes.length === 0) {
+    return [];
+  }
+  const global = must(queries.resolveName("globalThis", SymbolFlags.Value, undefined, false));
+  const globalType = global === undefined ? undefined : must(queries.typeOfSymbol(global));
+  if (global === undefined || globalType === undefined) {
+    return [];
+  }
+  const properties = new Map(
+    must(queries.propertiesOf(globalType)).map((property) => [property.name, property]),
+  );
+  const keyed = writes.filter((write) => properties.has(write.key));
+  const objects = keyed.flatMap((write) =>
+    write.receiver === undefined ? [] : [unwrapped(write.receiver)],
+  );
+  const objectTypes = new Map(
+    typesAt(project, objects).map((type, at) => [objects[at], type] as const),
+  );
+  const globals = new Map<number, boolean>();
+  const isGlobal = (type: Type | undefined): boolean => {
+    if (type === undefined) {
+      return false;
+    }
+    let known = globals.get(type.id);
+    if (known === undefined) {
+      const parts =
+        type.isUnionType() || type.isIntersectionType() ? must(queries.constituents(type)) : [type];
+      known = parts.some((part) => must(queries.symbolOfType(part))?.id === global.id);
+      globals.set(type.id, known);
+    }
+    return known;
+  };
+  const installs = keyed.filter(
+    (write) => write.receiver === undefined || isGlobal(objectTypes.get(unwrapped(write.receiver))),
+  );
+  if (installs.length === 0) {
+    return [];
+  }
+  const instances = new Map<string, readonly Type[]>();
+  const instancesOf = (key: string): readonly Type[] => {
+    let made = instances.get(key);
+    if (made === undefined) {
+      const property = properties.get(key);
+      const type = property === undefined ? undefined : must(queries.typeOfSymbol(property));
+      made = (
+        type === undefined ? [] : must(queries.signaturesOf(type, SignatureKind.Construct))
+      ).flatMap((signature) => must(queries.returnTypeOf(signature)) ?? []);
+      instances.set(key, made);
+    }
+    return made;
+  };
+  const carried = classesCarried(
+    project,
+    held,
+    chains,
+    sites,
+    installs.map((write) => [write.value]),
+  );
+  return installs.flatMap((write, at) => {
+    const uses = carried[at] ?? [];
+    const made = uses.length === 0 ? [] : instancesOf(write.key);
+    return made.length === 0
+      ? []
+      : uses.map((use) => ({ id: use.id, site: write.site, global: write.key, instances: made }));
+  });
+}

package/src/{interface-satisfaction.ts → exemptions/interface-satisfaction.ts}

@@ -3,40 +3,30 @@
  * reaches a position typed as an interface, or an object type a type alias names, that
  * requires the member: an `implements` entry, a typed initializer, an assignment, an
  * argument, a return, an array element, an object property or an `as` or `satisfies`
- * operand. `this` is a value of its class; a type parameter reaches its constraint. The
+ * operand. `this` is a value of its class; a type parameter reaches its constraint. A
+ * class installed as a global reaches the instance type the global constructs, whether
+ * or not it is assignable to it, because a stub answers only what its caller uses. The
  * contextual lookup has no batch form, so it is asked only of a value of a target class.
  */
 
 import {
   isCallExpression,
-  isClassDeclaration,
-  isClassExpression,
-  isClassStaticBlockDeclaration,
-  isFunctionDeclaration,
-  isFunctionExpression,
-  isGetAccessorDeclaration,
   isHeritageClause,
-  isMethodDeclaration,
   isNewExpression,
-  isObjectLiteralExpression,
-  isSetAccessorDeclaration,
   isTypeLiteralNode,
-  ModifierFlags,
   SyntaxKind,
+  type ClassLikeDeclaration,
   type Expression,
   type Node,
-  type SourceFile,
 } from "@typescript/native/ast";
 import { SymbolFlags, type Type } from "@typescript/native/sync";
-import { aliasChains } from "./alias-chain.ts";
-import { emptyImplementation } from "./findings/implementations.ts";
-import type { DetectorInput, Evidence } from "./exempt.ts";
-import type { Reference } from "./references.ts";
-import type { Exemption } from "./exempt.ts";
-import { nodeKey, type Inventory } from "./inventory.ts";
-import { renderPosition } from "./position.ts";
-import { must } from "./query.ts";
-import { handedOn, valuesOf } from "./value-flow.ts";
+import { aliasChains } from "../alias-chain.ts";
+import { emptyImplementation } from "../findings/implementations.ts";
+import { installedGlobals } from "./installed-globals.ts";
+import type { DetectorInput, Evidence } from "./lifecycle.ts";
+import { renderPosition } from "../position.ts";
+import { must } from "../query.ts";
+import type { ProjectSites } from "./sites.ts";
 
 /** One class the inventory holds, by its declaration. */
 interface ClassAt {
@@ -45,6 +35,7 @@ interface ClassAt {
   readonly name: Node;
   /** Whether the class declares type parameters, so its values carry instantiations of it. */
   readonly generic: boolean;
+  readonly node: ClassLikeDeclaration;
 }
 
 /** One value that flows into a position the checker types from its context. */
@@ -73,6 +64,8 @@ interface Pair {
   readonly target: Type;
   readonly name: string;
   readonly sites: Node[];
+  /** The global the class is installed as, which holds the members without assignability. */
+  installed?: string;
 }
 
 /** Whether a type alias names one type: the client's type object carries the alias it was written through. */
@@ -80,23 +73,7 @@ function aliased(type: Type): boolean {
   return (type as { readonly aliasSymbol?: unknown }).aliasSymbol !== undefined;
 }
 
-/** Whether one node declares a static member, whose `this` is the class itself. */
-function isStatic(node: Node): boolean {
-  const flags = (node as { readonly modifierFlags?: number }).modifierFlags ?? 0;
-  return (flags & ModifierFlags.Static) !== 0;
-}
-
-/** Whether one node is a method or an accessor of an object literal, whose `this` is the literal. */
-function isObjectLiteralMethod(node: Node): boolean {
-  return (
-    (isMethodDeclaration(node) ||
-      isGetAccessorDeclaration(node) ||
-      isSetAccessorDeclaration(node)) &&
-    isObjectLiteralExpression(node.parent)
-  );
-}
-
-/** What one project's walk found to resolve. */
+/** What one project's sites hold that this class reads. */
 interface Walked {
   readonly classes: readonly ClassAt[];
   readonly clauses: readonly Clause[];
@@ -104,59 +81,30 @@ interface Walked {
 }
 
 /**
- * The classes, the `implements` entries and the flowing values of one project's own
- * files. `this` is the class an instance member belongs to, so a function that is not
- * an arrow, a static member and a static block each stop it.
+ * The named classes, the `implements` entries and the flowing values of one project's own
+ * files, a value `this` standing for the class it is an instance of.
  */
-function walk(files: readonly SourceFile[], declarations: ReadonlyMap<string, string>): Walked {
-  const classes: ClassAt[] = [];
-  const clauses: Clause[] = [];
-  const flows: Flow[] = [];
-  for (const file of files) {
-    const visit = (node: Node, self: ClassAt | undefined): void => {
-      let inner = self;
-      if (isClassDeclaration(node) || isClassExpression(node)) {
-        const id = declarations.get(nodeKey(file, node));
-        const name = node.name;
-        const owner =
-          id === undefined || name === undefined
-            ? undefined
-            : { id, name, generic: node.typeParameters !== undefined };
-        if (owner !== undefined) {
-          classes.push(owner);
-          for (const clause of node.heritageClauses ?? []) {
-            if (isHeritageClause(clause) && clause.token === SyntaxKind.ImplementsKeyword) {
-              clauses.push(...clause.types.map((entry) => ({ owner, entry })));
-            }
-          }
-        }
-        inner = owner;
-      } else if (
-        isFunctionDeclaration(node) ||
-        isFunctionExpression(node) ||
-        isClassStaticBlockDeclaration(node) ||
-        isStatic(node) ||
-        isObjectLiteralMethod(node)
-      ) {
-        inner = undefined;
-      }
-      for (const written of handedOn(node)) {
-        for (const value of valuesOf(written)) {
-          flows.push({
-            value,
-            self: value.kind === SyntaxKind.ThisKeyword ? inner : undefined,
-          });
-        }
-      }
-      node.forEachChild((child) => {
-        visit(child, inner);
-      });
-    };
-    file.forEachChild((child) => {
-      visit(child, undefined);
-    });
-  }
-  return { classes, clauses, flows };
+function walked(sites: ProjectSites): Walked {
+  const classes = sites.classes.flatMap(({ id, node }) =>
+    node.name === undefined
+      ? []
+      : [{ id, name: node.name, generic: node.typeParameters !== undefined, node }],
+  );
+  const byId = new Map(classes.map((owner) => [owner.id, owner]));
+  return {
+    classes,
+    clauses: classes.flatMap((owner) =>
+      (owner.node.heritageClauses ?? []).flatMap((clause) =>
+        isHeritageClause(clause) && clause.token === SyntaxKind.ImplementsKeyword
+          ? clause.types.map((entry) => ({ owner, entry }))
+          : [],
+      ),
+    ),
+    flows: sites.flows.map((flow) => ({
+      value: flow.value,
+      self: flow.self === undefined ? undefined : byId.get(flow.self),
+    })),
+  };
 }
 
 /**
@@ -167,8 +115,8 @@ function walk(files: readonly SourceFile[], declarations: ReadonlyMap<string, st
 export function interfaceSatisfaction<Brand>(input: DetectorInput<Brand>): readonly Evidence[] {
   const { project, held, targetRoot } = input;
   const queries = project.queries;
-  const files = project.ownSourceFiles();
-  const { classes, clauses, flows } = walk(files, held.declarations);
+  const chains = aliasChains(project, held);
+  const { classes, clauses, flows } = walked(input.sites);
   if (classes.length === 0) {
     return [];
   }
@@ -283,14 +231,16 @@ export function interfaceSatisfaction<Brand>(input: DetectorInput<Brand>): reado
   };
 
   const pairs = new Map<string, Pair>();
-  const reach = (owner: ClassAt, source: Type, target: Type, name: string, site: Node): void => {
+  const reach = (owner: ClassAt, source: Type, target: Type, name: string, site: Node): Pair => {
     const key = `${String(source.id)}:${String(target.id)}`;
-    const pair = pairs.get(key);
+    let pair = pairs.get(key);
     if (pair === undefined) {
-      pairs.set(key, { owner, source, target, name, sites: [site] });
+      pair = { owner, source, target, name, sites: [site] };
+      pairs.set(key, pair);
     } else {
       pair.sites.push(site);
     }
+    return pair;
   };
 
   for (const clause of clauses) {
@@ -328,14 +278,29 @@ export function interfaceSatisfaction<Brand>(input: DetectorInput<Brand>): reado
     }
   });
 
-  const chains = aliasChains(project, held);
+  const byId = new Map(classes.map((owner) => [owner.id, owner]));
+  for (const one of installedGlobals(project, held, chains, input.sites)) {
+    const owner = byId.get(one.id);
+    const source = instanceOf.get(one.id);
+    if (owner === undefined || source === undefined) {
+      continue;
+    }
+    for (const instance of one.instances) {
+      reach(owner, source, instance, one.global, one.site).installed = one.global;
+    }
+  }
+
   const required = new Map<number, ReadonlyMap<string, readonly string[]>>();
   const members = new Map<string, ReadonlyMap<string, Answering>>();
   const found: Evidence[] = [];
-  const asking = [...pairs.values()];
-  const assignable = queries.assignableEach(asking);
-  for (const [index, pair] of asking.entries()) {
-    if (!must(assignable[index] ?? false)) {
+  const asking = [...pairs.values()].filter((pair) => pair.installed === undefined);
+  const assignable = new Set(
+    queries
+      .assignableEach(asking)
+      .flatMap((answer, index) => (must(answer) ? [asking[index]] : [])),
+  );
+  for (const pair of pairs.values()) {
+    if (pair.installed === undefined && !assignable.has(pair)) {
       continue;
     }
     let names = required.get(pair.target.id);
@@ -362,7 +327,10 @@ export function interfaceSatisfaction<Brand>(input: DetectorInput<Brand>): reado
       );
       members.set(pair.owner.id, answering);
     }
-    const detail = `satisfies ${pair.name}`;
+    const detail =
+      pair.installed === undefined
+        ? `satisfies ${pair.name}`
+        : `installed as the global ${pair.installed}`;
     for (const [name, methods] of names) {
       const member = answering.get(name);
       for (const id of member?.ids ?? []) {
@@ -379,62 +347,3 @@ export function interfaceSatisfaction<Brand>(input: DetectorInput<Brand>): reado
   }
   return found;
 }
-
-/** One project's interface-satisfaction records settled against the run's calls. */
-interface Settled {
-  readonly evidence: readonly Exemption[];
-  /** A reference from each uncalled interface method to each implementation it alone keeps. */
-  readonly references: readonly Reference[];
-}
-
-/**
- * Each project's records with every record dropped whose member implements only interface
- * methods nothing calls, unless every implementation of such a method is empty, and a
- * reference from each such method to the member, which then falls with the method.
- * `references` is every reference of the run, a consumer's included.
- */
-export function settledSatisfaction(
-  projects: readonly { readonly evidence: readonly Exemption[]; readonly held: Inventory }[],
-  references: readonly Reference[],
-): readonly Settled[] {
-  const methods = new Set(
-    projects.flatMap((one) =>
-      one.held.symbols.filter((symbol) => symbol.kind === "interface-method").map((one) => one.id),
-    ),
-  );
-  const called = new Set(references.map((reference) => reference.to));
-  const bodies = new Map<string, boolean>();
-  for (const record of projects.flatMap((one) => one.evidence)) {
-    for (const method of record.implementing?.methods ?? []) {
-      bodies.set(method, (bodies.get(method) ?? true) && record.implementing?.empty === true);
-    }
-  }
-  const uncalled = (method: string): boolean =>
-    methods.has(method) && !called.has(method) && bodies.get(method) !== true;
-  return projects.map(({ evidence }) => {
-    const kept: Exemption[] = [];
-    const added: Reference[] = [];
-    for (const record of evidence) {
-      const implemented = record.implementing?.methods ?? [];
-      if (
-        record.class !== "interface-satisfaction" ||
-        implemented.length === 0 ||
-        !implemented.every(uncalled)
-      ) {
-        kept.push(record);
-        continue;
-      }
-      for (const method of implemented) {
-        added.push({
-          from: method,
-          to: record.id,
-          position: record.site,
-          use: "read",
-          resolution: "override",
-          test: false,
-        });
-      }
-    }
-    return { evidence: kept, references: added };
-  });
-}