@cplieger/deadset-ts 3.2.0 → 3.3.0

package/src/exempt.ts

@@ -13,13 +13,16 @@ import {
   EXEMPTION_CLASSES,
   isExemptionClass,
   TS_EXEMPTION_CLASSES,
+  typescriptVisibilityOf,
   type ExemptionClass,
   type TSExemptionClass,
+  type TypeScriptVisibility,
 } from "./exempt-classes.ts";
-import type { Inventory, InventorySymbol } from "./inventory.ts";
+import type { Inventory, InventorySymbol, Visibility } from "./inventory.ts";
 import type { Matrix } from "./matrix.ts";
 import { byPosition, positionKey, type Position } from "./position.ts";
 import type { ProjectView } from "./session.ts";
+import type { Templates } from "./template-field.ts";
 import { sweep, type Exemption, type Mode, type SweepInput } from "./sweep.ts";
 
 /** One declaration a detector holds back, and where and why. */
@@ -36,6 +39,8 @@ export interface DetectorInput<Brand> {
   readonly project: ProjectView<Brand>;
   readonly held: Inventory;
   readonly targetRoot: string;
+  /** The configured templates, read once for the run. */
+  readonly templates: Templates;
 }
 
 /**
@@ -77,23 +82,44 @@ export function disabledClasses(config: Config): ReadonlySet<ExemptionClass> {
   return disabled;
 }
 
+/**
+ * Whether a class whose row states `allowed` may retain a member of one visibility. A
+ * declaration the inventory does not hold has no visibility to refuse it by.
+ */
+function retainable(allowed: TypeScriptVisibility, visibility: Visibility | undefined): boolean {
+  if (visibility === "private") {
+    return allowed.private;
+  }
+  if (visibility === "private-name") {
+    return allowed.privateName;
+  }
+  return true;
+}
+
 /**
  * The records one project's detectors found, each class in the vocabulary's order and
- * none of a switched-off class. Under a production mode a record whose evidence is
- * written in a test file holds nothing, as a reference a test file makes is none there.
+ * none of a switched-off class. Evidence on a private member the class's row says it
+ * cannot retain is dropped first, whatever the detector found. Under a production mode
+ * a record whose evidence is written in a test file holds nothing, as a reference a
+ * test file makes is none there.
  */
 export function computeExemptions<Brand>(
   input: DetectorInput<Brand>,
   detectors: Detectors,
   holding: Holding,
 ): readonly Exemption[] {
+  const visibility = new Map(input.held.symbols.map((symbol) => [symbol.id, symbol.visibility]));
   const found: Exemption[] = [];
   for (const exemptionClass of TS_EXEMPTION_CLASSES) {
     const detect = detectors.get(exemptionClass);
     if (detect === undefined || holding.disabled.has(exemptionClass)) {
       continue;
     }
+    const allowed = typescriptVisibilityOf(exemptionClass);
     for (const evidence of detect(input)) {
+      if (!retainable(allowed, visibility.get(evidence.id))) {
+        continue;
+      }
       if (holding.mode.production && holding.testFiles.has(evidence.site.path)) {
         continue;
       }

package/src/interface-satisfaction.ts

@@ -0,0 +1,417 @@
+/**
+ * The interface-satisfaction class: a class member is held back when a value of the
+ * class reaches a position the checker types as an interface requiring a member of
+ * that name, so a caller reaches the member through the interface while no name in
+ * the program resolves to it.
+ *
+ * A value reaches such a position as an `implements` entry, the initializer of a
+ * declaration whose type is written, an assignment, an argument, a returned value, an
+ * array element, an object property, or the operand of `as` or `satisfies`, read
+ * through parentheses, conditionals and the operators whose result is an operand.
+ * `this` in an instance member is a value of its class. Types are asked in batches;
+ * the contextual lookup has none, so it is asked only of a value whose type is a class
+ * of the target, and each distinct pair, interface and class is asked once.
+ */
+
+import {
+  isArrayLiteralExpression,
+  isArrowFunction,
+  isAsExpression,
+  isBinaryExpression,
+  isCallExpression,
+  isClassDeclaration,
+  isClassExpression,
+  isClassStaticBlockDeclaration,
+  isConditionalExpression,
+  isFunctionDeclaration,
+  isFunctionExpression,
+  isGetAccessorDeclaration,
+  isHeritageClause,
+  isIdentifier,
+  isMethodDeclaration,
+  isNewExpression,
+  isObjectLiteralExpression,
+  isParameterDeclaration,
+  isParenthesizedExpression,
+  isPropertyAssignment,
+  isPropertyDeclaration,
+  isReturnStatement,
+  isSatisfiesExpression,
+  isSetAccessorDeclaration,
+  isShorthandPropertyAssignment,
+  isSpreadElement,
+  isVariableDeclaration,
+  ModifierFlags,
+  SyntaxKind,
+  type Expression,
+  type Node,
+  type SourceFile,
+} from "@typescript/native/unstable/ast";
+import { SymbolFlags, type Type } from "@typescript/native/unstable/sync";
+import { aliasChains } from "./alias-chain.ts";
+import type { DetectorInput, Evidence } from "./exempt.ts";
+import { nodeKey } from "./inventory.ts";
+import { renderPosition } from "./position.ts";
+import { DEFAULT_BATCH_CAP } from "./references.ts";
+
+/** One class the inventory holds, by its declaration. */
+interface ClassAt {
+  readonly id: string;
+  /** The name node, whose type is the class's instance type. */
+  readonly name: Node;
+  /** Whether the class declares type parameters, so its values carry instantiations of it. */
+  readonly generic: boolean;
+}
+
+/** One value that flows into a position the checker types from its context. */
+interface Flow {
+  readonly value: Expression;
+  /** The class `this` stands for, where the value is `this`. */
+  readonly self: ClassAt | undefined;
+}
+
+/** One entry of a class's `implements` clause. */
+interface Clause {
+  readonly owner: ClassAt;
+  readonly entry: Node;
+}
+
+/** One class type reaching one interface type, and the places it does. */
+interface Pair {
+  readonly owner: ClassAt;
+  readonly source: Type;
+  readonly target: Type;
+  readonly name: string;
+  readonly sites: Node[];
+}
+
+/** The operators of an assignment whose right side is stored into the left side's type. */
+const STORES: ReadonlySet<SyntaxKind> = new Set([
+  SyntaxKind.EqualsToken,
+  SyntaxKind.QuestionQuestionEqualsToken,
+  SyntaxKind.BarBarEqualsToken,
+  SyntaxKind.AmpersandAmpersandEqualsToken,
+]);
+
+/** 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)
+  );
+}
+
+/** Whether a declaration writes its type, so its initializer is read in that type's context. */
+function writesType(node: Node): boolean {
+  return (node as { readonly type?: Node }).type !== undefined;
+}
+
+/**
+ * The values one written expression hands on: the expression itself, or what it
+ * evaluates to through parentheses, a conditional and the operators whose result is
+ * one of their operands.
+ */
+function valuesOf(expression: Expression): readonly Expression[] {
+  if (isParenthesizedExpression(expression)) {
+    return valuesOf(expression.expression);
+  }
+  if (isConditionalExpression(expression)) {
+    return [...valuesOf(expression.whenTrue), ...valuesOf(expression.whenFalse)];
+  }
+  if (isBinaryExpression(expression)) {
+    const operator = expression.operatorToken.kind;
+    if (operator === SyntaxKind.QuestionQuestionToken || operator === SyntaxKind.BarBarToken) {
+      return [...valuesOf(expression.left), ...valuesOf(expression.right)];
+    }
+    if (operator === SyntaxKind.AmpersandAmpersandToken || operator === SyntaxKind.CommaToken) {
+      return valuesOf(expression.right);
+    }
+  }
+  return [expression];
+}
+
+/** The expressions one node hands to a position typed by its context. */
+function handedOn(node: Node): readonly Expression[] {
+  if (
+    (isVariableDeclaration(node) || isPropertyDeclaration(node) || isParameterDeclaration(node)) &&
+    node.initializer !== undefined &&
+    writesType(node)
+  ) {
+    return [node.initializer];
+  }
+  if (isBinaryExpression(node) && STORES.has(node.operatorToken.kind)) {
+    return [node.right];
+  }
+  if (isCallExpression(node) || isNewExpression(node)) {
+    return (node.arguments ?? []).filter((argument) => !isSpreadElement(argument));
+  }
+  if (isReturnStatement(node)) {
+    return node.expression === undefined ? [] : [node.expression];
+  }
+  if (isArrowFunction(node)) {
+    return node.body.kind === SyntaxKind.Block ? [] : [node.body];
+  }
+  if (isArrayLiteralExpression(node)) {
+    return node.elements.filter(
+      (element) => !isSpreadElement(element) && element.kind !== SyntaxKind.OmittedExpression,
+    );
+  }
+  if (isPropertyAssignment(node)) {
+    return [node.initializer];
+  }
+  if (isShorthandPropertyAssignment(node)) {
+    return isIdentifier(node.name) ? [node.name] : [];
+  }
+  if (isAsExpression(node) || isSatisfiesExpression(node)) {
+    return [node.expression];
+  }
+  return [];
+}
+
+/** What one project's walk found to resolve. */
+interface Walked {
+  readonly classes: readonly ClassAt[];
+  readonly clauses: readonly Clause[];
+  readonly flows: readonly Flow[];
+}
+
+/**
+ * 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.
+ */
+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 };
+}
+
+/**
+ * The interface-satisfaction detector: for each class type that reaches an interface
+ * type it is assignable to, the class's members whose names the interface's members
+ * carry, each recorded at the place the value flows.
+ */
+export function interfaceSatisfaction<Brand>(input: DetectorInput<Brand>): readonly Evidence[] {
+  const { project, held, targetRoot } = input;
+  const checker = project.checker;
+  const files = project.ownSourceFiles();
+  const { classes, clauses, flows } = walk(files, held.declarations);
+  if (classes.length === 0) {
+    return [];
+  }
+
+  // One list, so the batches are capped runs of the whole project rather than of a
+  // file: a class's name, an `implements` entry and a value are each one question.
+  const asked = [
+    ...classes.map((owner) => owner.name),
+    ...clauses.map((clause) => clause.entry),
+    ...flows.filter((flow) => flow.self === undefined).map((flow) => flow.value),
+  ];
+  const typeAt = new Map<Node, Type>();
+  for (let from = 0; from < asked.length; from += DEFAULT_BATCH_CAP) {
+    const run = asked.slice(from, from + DEFAULT_BATCH_CAP);
+    checker.getTypeAtLocation(run).forEach((type, index) => {
+      const node = run[index];
+      if (type !== undefined && node !== undefined) {
+        typeAt.set(node, type);
+      }
+    });
+  }
+
+  const classOfType = new Map<number, ClassAt>();
+  const instanceOf = new Map<string, Type>();
+  for (const owner of classes) {
+    const type = typeAt.get(owner.name);
+    if (type !== undefined) {
+      classOfType.set(type.id, owner);
+      instanceOf.set(owner.id, type);
+    }
+  }
+  const instantiates = classes.some((owner) => owner.generic);
+
+  const constituents = new Map<number, readonly Type[]>();
+  const partsOf = (type: Type): readonly Type[] => {
+    if (!type.isUnionType() && !type.isIntersectionType()) {
+      return [type];
+    }
+    let parts = constituents.get(type.id);
+    if (parts === undefined) {
+      parts = type.getTypes();
+      constituents.set(type.id, parts);
+    }
+    return parts;
+  };
+
+  const targets = new Map<number, ClassAt | undefined>();
+  /** The classes of the target one value's type is an instance of, with the instance type. */
+  const classesOf = (type: Type): readonly { owner: ClassAt; type: Type }[] =>
+    partsOf(type).flatMap((part) => {
+      const direct = classOfType.get(part.id);
+      if (direct !== undefined) {
+        return [{ owner: direct, type: part }];
+      }
+      if (!instantiates || !part.isTypeReference()) {
+        return [];
+      }
+      if (!targets.has(part.id)) {
+        targets.set(part.id, classOfType.get(part.getTarget().id));
+      }
+      const generic = targets.get(part.id);
+      return generic === undefined ? [] : [{ owner: generic, type: part }];
+    });
+
+  const interfaceNames = new Map<number, string | undefined>();
+  /** The interface types one position's type is or holds, each with the interface's name. */
+  const interfacesOf = (type: Type): readonly { type: Type; name: string }[] =>
+    partsOf(type).flatMap((part) => {
+      if (!interfaceNames.has(part.id)) {
+        const symbol = part.isObjectType() ? part.getSymbol() : undefined;
+        interfaceNames.set(
+          part.id,
+          symbol !== undefined && (symbol.flags & SymbolFlags.Interface) !== 0
+            ? symbol.name
+            : undefined,
+        );
+      }
+      const name = interfaceNames.get(part.id);
+      return name === undefined ? [] : [{ type: part, name }];
+    });
+
+  const pairs = new Map<string, Pair>();
+  const reach = (owner: ClassAt, source: Type, target: Type, name: string, site: Node): void => {
+    const key = `${String(source.id)}:${String(target.id)}`;
+    const pair = pairs.get(key);
+    if (pair === undefined) {
+      pairs.set(key, { owner, source, target, name, sites: [site] });
+    } else {
+      pair.sites.push(site);
+    }
+  };
+
+  for (const clause of clauses) {
+    const source = instanceOf.get(clause.owner.id);
+    const target = typeAt.get(clause.entry);
+    if (source === undefined || target === undefined) {
+      continue;
+    }
+    for (const reached of interfacesOf(target)) {
+      reach(clause.owner, source, reached.type, reached.name, clause.entry);
+    }
+  }
+
+  for (const flow of flows) {
+    const self = flow.self === undefined ? undefined : instanceOf.get(flow.self.id);
+    const valueType = typeAt.get(flow.value);
+    const sources =
+      flow.self !== undefined && self !== undefined
+        ? [{ owner: flow.self, type: self }]
+        : valueType === undefined
+          ? []
+          : classesOf(valueType);
+    if (sources.length === 0) {
+      continue;
+    }
+    const position = checker.getContextualType(flow.value);
+    if (position === undefined) {
+      continue;
+    }
+    for (const reached of interfacesOf(position)) {
+      for (const source of sources) {
+        reach(source.owner, source.type, reached.type, reached.name, flow.value);
+      }
+    }
+  }
+
+  const chains = aliasChains(project, held);
+  const required = new Map<number, ReadonlySet<string>>();
+  const members = new Map<string, ReadonlyMap<string, readonly string[]>>();
+  const found: Evidence[] = [];
+  for (const pair of pairs.values()) {
+    if (!checker.isTypeAssignableTo(pair.source, pair.target)) {
+      continue;
+    }
+    let names = required.get(pair.target.id);
+    if (names === undefined) {
+      names = new Set(
+        checker.getPropertiesOfType(pair.target).map((property) => property.escapedName),
+      );
+      required.set(pair.target.id, names);
+    }
+    let answering = members.get(pair.owner.id);
+    if (answering === undefined) {
+      const instance = instanceOf.get(pair.owner.id) ?? pair.source;
+      answering = new Map(
+        checker
+          .getPropertiesOfType(instance)
+          .map((property) => [property.escapedName, chains.declarationsOf(property)]),
+      );
+      members.set(pair.owner.id, answering);
+    }
+    const detail = `satisfies ${pair.name}`;
+    for (const name of names) {
+      for (const id of answering.get(name) ?? []) {
+        for (const site of pair.sites) {
+          found.push({
+            id,
+            detail,
+            site: renderPosition(site.getSourceFile(), targetRoot, site.getStart()),
+          });
+        }
+      }
+    }
+  }
+  return found;
+}

package/src/member-names.ts

@@ -0,0 +1,89 @@
+/**
+ * The members of one project's inventory by the name each is written with, for the
+ * classes whose evidence is a name rather than a type relation: a template and a
+ * string key both hold a name and nothing else, so each holds back every member of
+ * that name its own mechanism can reach.
+ */
+
+import {
+  isIdentifier,
+  isNumericLiteral,
+  isPrivateIdentifier,
+  isStringLiteral,
+  type Node,
+  type SourceFile,
+} from "@typescript/native/unstable/ast";
+import { nodeKey, type Inventory, type InventorySymbol, type SymbolKind } from "./inventory.ts";
+
+/** The kinds of declaration a member name can name. */
+const MEMBER_KINDS: ReadonlySet<SymbolKind> = new Set([
+  "method",
+  "class-member",
+  "interface-method",
+  "type-member",
+  "enum-member",
+]);
+
+/**
+ * The name a member declaration is written with: an identifier's text, a private
+ * name's text without its `#`, a string key's value and a numeric key's text. A
+ * private name is indexed under the name a template or a string would spell, so the
+ * rule that no such evidence holds it back is the framework's alone. A computed key
+ * names nothing a string can be equal to before the program runs.
+ */
+function writtenName(name: Node | undefined): string | undefined {
+  if (name === undefined) {
+    return undefined;
+  }
+  if (isPrivateIdentifier(name)) {
+    return name.text.replace(/^#/u, "");
+  }
+  if (isIdentifier(name)) {
+    return name.text;
+  }
+  if (isStringLiteral(name) || isNumericLiteral(name)) {
+    return name.text;
+  }
+  return undefined;
+}
+
+/**
+ * Every member the inventory holds, keyed by the name it is written with, each
+ * member once and in inventory order. A getter and a setter of one name are one
+ * member.
+ */
+export function memberNames(
+  files: readonly SourceFile[],
+  held: Inventory,
+): ReadonlyMap<string, readonly InventorySymbol[]> {
+  const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
+  const named = new Map<string, string>();
+  for (const file of files) {
+    const visit = (node: Node): void => {
+      const id = held.declarations.get(nodeKey(file, node));
+      const symbol = id === undefined ? undefined : byId.get(id);
+      if (symbol !== undefined && MEMBER_KINDS.has(symbol.kind)) {
+        const name = writtenName((node as { readonly name?: Node }).name);
+        if (name !== undefined) {
+          named.set(symbol.id, name);
+        }
+      }
+      node.forEachChild(visit);
+    };
+    visit(file);
+  }
+  const index = new Map<string, InventorySymbol[]>();
+  for (const symbol of held.symbols) {
+    const name = named.get(symbol.id);
+    if (name === undefined) {
+      continue;
+    }
+    const members = index.get(name);
+    if (members === undefined) {
+      index.set(name, [symbol]);
+    } else {
+      members.push(symbol);
+    }
+  }
+  return index;
+}

package/src/references.ts

@@ -2,6 +2,7 @@ import {
   isArrayLiteralExpression,
   isBinaryExpression,
   isCallExpression,
+  isDecorator,
   isDeleteExpression,
   isElementAccessExpression,
   isExportDeclaration,
@@ -53,9 +54,11 @@ import type { ProjectView } from "./session.ts";
 /**
  * How one reference uses the declaration it names. An `evaluation` names a file: the
  * place it is written imports the module, which runs the module's top level and reads
- * none of what it exports. A `read` of a file reads the module's namespace.
+ * none of what it exports. A `read` of a file reads the module's namespace. A
+ * `decorator` names the declaration a decorator expression is attached to, which the
+ * decorator receives when the class is defined.
  */
-export type Use = "read" | "write" | "evaluation";
+export type Use = "read" | "write" | "evaluation" | "decorator";
 
 /**
  * Which accessor answered for one reference, so that the cost of a run is attributable
@@ -67,8 +70,9 @@ export type Use = "read" | "write" | "evaluation";
  * - `shorthand` is the per-node lookup for `{ a }`, whose name resolves to the property
  *   the literal declares rather than to the declaration that name reads.
  * - `alias` is a step along an import or export chain, from one link to what it names.
+ * - `syntax` is the tree alone, which says what a decorator is attached to.
  */
-export type Resolution = "batch" | "resolved-symbol" | "shorthand" | "alias";
+export type Resolution = "batch" | "resolved-symbol" | "shorthand" | "alias" | "syntax";
 
 /** One use of one declaration by one declaration. */
 export interface Reference {
@@ -318,11 +322,18 @@ interface Evaluation {
   readonly from: string;
 }
 
-/** Everything one file's walk found to resolve. */
+/** One decorator expression, and the declaration it is attached to. */
+interface Decorated {
+  readonly decorator: Node;
+  readonly declaration: string;
+}
+
+/** Everything one file's walk found to resolve, and the decorators it needs no resolution for. */
 interface FileSites {
   readonly uses: readonly Site[];
   readonly links: readonly Link[];
   readonly evaluations: readonly Evaluation[];
+  readonly decorated: readonly Decorated[];
 }
 
 /** Whether one node is a string literal or a template literal with no substitution. */
@@ -418,6 +429,7 @@ function sitesOf(
   const found: Site[] = [];
   const links: Link[] = [];
   const evaluations: Evaluation[] = [];
+  const decorated: Decorated[] = [];
   const writes = new Set<number>();
   const declared = new Set<number>();
   const shorthands = new Map<number, Node>();
@@ -464,13 +476,18 @@ function sitesOf(
     const outer = enclosing;
     if (held !== undefined) {
       enclosing = held;
+      for (const modifier of (node as { readonly modifiers?: readonly Node[] }).modifiers ?? []) {
+        if (isDecorator(modifier)) {
+          decorated.push({ decorator: modifier, declaration: held });
+        }
+      }
     }
     node.forEachChild(visit);
     enclosing = outer;
   };
 
   file.forEachChild(visit);
-  return { uses: found, links, evaluations };
+  return { uses: found, links, evaluations, decorated };
 }
 
 /**
@@ -567,7 +584,25 @@ export function references<Brand>(
     if (test) {
       tests.push(path);
     }
-    const { uses, links, evaluations } = sitesOf(file, declarations, declaredAt(file) ?? "");
+    const { uses, links, evaluations, decorated } = sitesOf(
+      file,
+      declarations,
+      declaredAt(file) ?? "",
+    );
+
+    // A decorator is written inside the declaration it is attached to and receives it,
+    // so the declaration is used where the decorator is written, whatever the
+    // decorator does with it.
+    for (const { decorator, declaration } of decorated) {
+      found.push({
+        from: declaration,
+        to: declaration,
+        position: renderPosition(file, targetRoot, decorator.getStart()),
+        use: "decorator",
+        resolution: "syntax",
+        test,
+      });
+    }
 
     // One batch per capped run of the file's name nodes, the re-exports' nodes after
     // the uses and the evaluated modules' specifiers last, each node once: a bare star