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

package/src/exemptions/sites.ts

@@ -0,0 +1,293 @@
+/**
+ * The one walk of a project's own files every detector shares: its calls and the class
+ * `this` stands for at each, its classes, the values it hands to positions typed by
+ * their context, its functions' parameters, its decorated declarations and its
+ * assignments to properties. The walk reads syntax only; what a call invokes through a
+ * method of `Function.prototype` asks the checker, once per project, at the first
+ * detector that needs it.
+ */
+
+import {
+  isArrowFunction,
+  isBinaryExpression,
+  isClassDeclaration,
+  isClassExpression,
+  isClassStaticBlockDeclaration,
+  isElementAccessExpression,
+  isFunctionDeclaration,
+  isFunctionExpression,
+  isGetAccessorDeclaration,
+  isIdentifier,
+  isMethodDeclaration,
+  isNoSubstitutionTemplateLiteral,
+  isObjectLiteralExpression,
+  isPropertyAccessExpression,
+  isPropertyDeclaration,
+  isSetAccessorDeclaration,
+  isStringLiteral,
+  isVariableDeclaration,
+  ModifierFlags,
+  SyntaxKind,
+  type CallExpression,
+  type ClassLikeDeclaration,
+  type Expression,
+  type Node,
+  type ParameterDeclaration,
+} from "@typescript/native/ast";
+import { handedOn, valuesOf } from "../index/values.ts";
+import { isParameterProperty, nodeKey, type Inventory } from "../inventory.ts";
+import type { ProjectView } from "../session.ts";
+import { parenthesesRemoved } from "../unwrap.ts";
+import { decoratorsOf, invocations, type Invocations } from "./calls.ts";
+
+/** One call of the project's own files, and the class `this` is a value of where it is written. */
+export interface CallSite {
+  readonly call: CallExpression;
+  /** The inventory's identifier of the class, where `this` is an instance of one. */
+  readonly self: string | undefined;
+}
+
+/** One class the inventory holds, declared or written as an expression. */
+interface ClassSite {
+  readonly id: string;
+  readonly node: ClassLikeDeclaration;
+}
+
+/** One value the project hands to a position the checker types from its context. */
+interface FlowSite {
+  readonly value: Expression;
+  /** The class `this` stands for, where the value is `this` inside an instance member. */
+  readonly self: string | undefined;
+}
+
+/** One identifier-named parameter of a function, method or function-valued variable of the project. */
+export interface ParameterSite {
+  /** The inventory's identifier of the function's declaration. */
+  readonly fn: string;
+  /** Its place among the arguments a call binds, a `this` parameter taking none. */
+  readonly index: number;
+  readonly rest: boolean;
+  readonly name: Node;
+}
+
+/** One assignment of a value to a property a key written as a name or a string names. */
+interface StoreSite {
+  readonly store: Expression;
+  readonly receiver: Expression;
+  readonly key: string;
+  readonly value: Expression;
+}
+
+/** The property one assignment's left side names on its receiver, where a written key names it. */
+function storeOf(node: Node): StoreSite | undefined {
+  if (!isBinaryExpression(node) || node.operatorToken.kind !== SyntaxKind.EqualsToken) {
+    return undefined;
+  }
+  const left = parenthesesRemoved(node.left);
+  if (isPropertyAccessExpression(left) && isIdentifier(left.name)) {
+    return { store: node, receiver: left.expression, key: left.name.text, value: node.right };
+  }
+  if (
+    isElementAccessExpression(left) &&
+    (isStringLiteral(left.argumentExpression) ||
+      isNoSubstitutionTemplateLiteral(left.argumentExpression))
+  ) {
+    return {
+      store: node,
+      receiver: left.expression,
+      key: left.argumentExpression.text,
+      value: node.right,
+    };
+  }
+  return undefined;
+}
+
+/** One declaration the inventory holds that carries a decorator. */
+interface DecoratedSite {
+  readonly id: string;
+  readonly node: Node;
+}
+
+/** What one walk of a project's own files found. */
+interface Walked {
+  readonly calls: readonly CallSite[];
+  readonly classes: readonly ClassSite[];
+  readonly flows: readonly FlowSite[];
+  readonly parameters: readonly ParameterSite[];
+  readonly decorated: readonly DecoratedSite[];
+  /** The assignments to a property a written key names. */
+  readonly stores: readonly StoreSite[];
+  /** The parameter properties the inventory holds, by identifier. */
+  readonly parameterProperties: ReadonlySet<string>;
+  /** The class properties whose declaration writes an initializer, by identifier. */
+  readonly initialized: ReadonlySet<string>;
+}
+
+/** 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 opens a body whose `this` is no instance of the enclosing class: a
+ * function that is not an arrow, a static block, a static member, and a method or an
+ * accessor of an object literal, whose `this` is the literal.
+ */
+function resetsThis(node: Node): boolean {
+  return (
+    isFunctionDeclaration(node) ||
+    isFunctionExpression(node) ||
+    isClassStaticBlockDeclaration(node) ||
+    isStatic(node) ||
+    ((isMethodDeclaration(node) ||
+      isGetAccessorDeclaration(node) ||
+      isSetAccessorDeclaration(node)) &&
+      isObjectLiteralExpression(node.parent))
+  );
+}
+
+/** The parameters and declaring node of one function-like declaration of the project. */
+function functionOf(
+  node: Node,
+): { readonly declared: Node; readonly parameters: readonly ParameterDeclaration[] } | undefined {
+  if (
+    isFunctionDeclaration(node) ||
+    (isMethodDeclaration(node) && !isObjectLiteralExpression(node.parent))
+  ) {
+    return { declared: node, parameters: node.parameters };
+  }
+  if (
+    isVariableDeclaration(node) &&
+    node.initializer !== undefined &&
+    (isArrowFunction(node.initializer) || isFunctionExpression(node.initializer))
+  ) {
+    return { declared: node, parameters: node.initializer.parameters };
+  }
+  return undefined;
+}
+
+function walk<Brand>(project: ProjectView<Brand>, held: Inventory): Walked {
+  const calls: CallSite[] = [];
+  const classes: ClassSite[] = [];
+  const flows: FlowSite[] = [];
+  const parameters: ParameterSite[] = [];
+  const decorated: DecoratedSite[] = [];
+  const stores: StoreSite[] = [];
+  const parameterProperties = new Set<string>();
+  const initialized = new Set<string>();
+  for (const file of project.ownSourceFiles()) {
+    const visit = (node: Node, self: string | undefined): void => {
+      const id = held.declarations.get(nodeKey(file, node));
+      let inner = self;
+      if (isClassDeclaration(node) || isClassExpression(node)) {
+        inner = id;
+        if (id !== undefined) {
+          classes.push({ id, node });
+        }
+      } else if (resetsThis(node)) {
+        inner = undefined;
+      }
+      if (id !== undefined) {
+        if (isParameterProperty(node)) {
+          parameterProperties.add(id);
+        }
+        if (decoratorsOf(node).length > 0) {
+          decorated.push({ id, node });
+        }
+        if (isPropertyDeclaration(node) && node.initializer !== undefined) {
+          initialized.add(id);
+        }
+      }
+      if (node.kind === SyntaxKind.CallExpression) {
+        calls.push({ call: node as CallExpression, self: inner });
+      }
+      const store = storeOf(node);
+      if (store !== undefined) {
+        stores.push(store);
+      }
+      for (const written of handedOn(node)) {
+        for (const value of valuesOf(written)) {
+          flows.push({ value, self: value.kind === SyntaxKind.ThisKeyword ? inner : undefined });
+        }
+      }
+      const fn = functionOf(node);
+      const fnId = fn === undefined ? undefined : held.declarations.get(nodeKey(file, fn.declared));
+      if (fn !== undefined && fnId !== undefined) {
+        fn.parameters
+          .filter((parameter) => !(isIdentifier(parameter.name) && parameter.name.text === "this"))
+          .forEach((parameter, index) => {
+            if (isIdentifier(parameter.name)) {
+              parameters.push({
+                fn: fnId,
+                index,
+                rest: parameter.dotDotDotToken !== undefined,
+                name: parameter.name,
+              });
+            }
+          });
+      }
+      node.forEachChild((child) => {
+        visit(child, inner);
+      });
+    };
+    file.forEachChild((child) => {
+      visit(child, undefined);
+    });
+  }
+  return {
+    calls,
+    classes,
+    flows,
+    parameters,
+    decorated,
+    stores,
+    parameterProperties,
+    initialized,
+  };
+}
+
+/** One project's sites, walked at the first detector that reads them. */
+export interface ProjectSites extends Walked {
+  /** What each call invokes, a call through `call`, `apply` or `bind` included. */
+  readonly invocations: Invocations;
+}
+
+/** The sites of one project's own files, each walk and each checker question made once. */
+export function projectSites<Brand>(project: ProjectView<Brand>, held: Inventory): ProjectSites {
+  let walked: Walked | undefined;
+  let invoked: Invocations | undefined;
+  const sites = (): Walked => (walked ??= walk(project, held));
+  return {
+    get calls() {
+      return sites().calls;
+    },
+    get classes() {
+      return sites().classes;
+    },
+    get flows() {
+      return sites().flows;
+    },
+    get parameters() {
+      return sites().parameters;
+    },
+    get decorated() {
+      return sites().decorated;
+    },
+    get stores() {
+      return sites().stores;
+    },
+    get parameterProperties() {
+      return sites().parameterProperties;
+    },
+    get initialized() {
+      return sites().initialized;
+    },
+    get invocations() {
+      return (invoked ??= invocations(
+        project,
+        sites().calls.map((one) => one.call),
+      ));
+    },
+  };
+}

package/src/{template-field.ts → exemptions/template-field.ts}

@@ -12,17 +12,17 @@
  * type, because nothing ties the name to a type.
  */
 
-import { readComponent } from "./component-files.ts";
-import type { ResolvedConfig, TemplateDelimiters } from "./config.ts";
-import type { DetectorInput, Evidence } from "./exempt.ts";
-import type { Host } from "./host.ts";
-import type { SymbolKind } from "./inventory.ts";
-import { memberNames } from "./member-names.ts";
-import { extensionOf, isAbsolutePath, joinPath, normalizePath, relativePath } from "./paths.ts";
-import { isComponentFile, type Position } from "./position.ts";
-import { bytewise } from "./text/compare.ts";
-import { filesBelow } from "./fs/tree.ts";
-import { UsageError } from "./usage.ts";
+import { readComponent } from "../component-files.ts";
+import type { ResolvedConfig, TemplateDelimiters } from "../config.ts";
+import type { DetectorInput, Evidence } from "./lifecycle.ts";
+import type { Host } from "../host.ts";
+import type { SymbolKind } from "../inventory.ts";
+import { memberNames } from "../member-names.ts";
+import { extensionOf, isAbsolutePath, joinPath, normalizePath, relativePath } from "../paths.ts";
+import { isComponentFile, type Position } from "../position.ts";
+import { bytewise } from "../text/compare.ts";
+import { filesBelow } from "../fs/tree.ts";
+import { UsageError } from "../usage.ts";
 
 /** One template, by its path below the target root. */
 interface TemplateFile {

package/src/{value-reach.ts → exemptions/value-reach.ts}

@@ -2,9 +2,10 @@
  * The classes of the target a value of one type carries, and the members of the other
  * object types the target writes that it carries, as a serializer walking the value reaches
  * them: through constituents, array and tuple elements, the data members and index
- * signatures of the types the target writes, and the values `stored` gives for a type where
- * it erases them. The walk stops at `any`, `unknown`, a type parameter, a function and an
- * interface or class of another program, so an instance held only there is missed.
+ * signatures of the types the target writes, a class's polymorphic `this` type, and the values
+ * `stored` gives for a type where it erases them. The walk stops at `any`, `unknown`, any
+ * other type parameter, a function and an interface or class of another program, so an
+ * instance held only there is missed.
  */
 
 import {
@@ -17,14 +18,15 @@ import {
 import {
   ObjectFlags,
   SymbolFlags,
+  TypeFlags,
   type ObjectType,
   type Symbol as TSSymbol,
   type Type,
 } from "@typescript/native/sync";
-import { classNames, typesAt } from "./class-members.ts";
-import type { Inventory } from "./inventory.ts";
-import { must } from "./query.ts";
-import type { ProjectView } from "./session.ts";
+import { classNames, typesAt } from "../class-members.ts";
+import type { Inventory } from "../inventory.ts";
+import { must } from "../query.ts";
+import type { ProjectView } from "../session.ts";
 
 /**
  * The object types whose members the walk reads whatever declares them. A reverse-mapped
@@ -53,7 +55,10 @@ interface ValueReach {
 }
 
 /** The two conversion methods a serializer or a formatter resolves on a value's own shape. */
-const CONVERSION_NAMES: ReadonlySet<string> = new Set(["toJSON", "toString"]);
+export const CONVERSION_NAMES: ReadonlySet<string> = new Set(["toJSON", "toString"]);
+
+/** The types that keep nothing of a value they are given, or that a decode gives a value. */
+export const ERASED = TypeFlags.Any | TypeFlags.Unknown;
 
 /**
  * The members that can answer a conversion: a serializer reads the name with `[[Get]]`
@@ -208,6 +213,9 @@ export function valueReach<Brand>(
     let found: readonly Type[] = [];
     if (type.isUnionType() || type.isIntersectionType()) {
       found = must(queries.constituents(type));
+    } else if (type.isTypeParameter() && type.isThisType === true) {
+      // A value of a class's polymorphic `this` type is an instance of the class.
+      found = [must(queries.constraintOf(type))].filter((one) => one !== undefined);
     } else if (type.isObjectType()) {
       const target = targetOf(type);
       const isList =

package/src/facts.ts

@@ -6,7 +6,7 @@
 
 import { FACTS_VERSION } from "./contract/contract.generated.ts";
 import type { BindingRecord } from "./bindings.ts";
-import type { GeneratedFact } from "./generated-file.ts";
+import type { GeneratedFact } from "./exemptions/generated-file.ts";
 import { LANGUAGE, PRODUCT } from "./product.ts";
 import { bytewise } from "./text/compare.ts";
 

package/src/index/sites.ts

@@ -56,7 +56,7 @@ import type { Use } from "../references.ts";
 import { isLoadCall, type LoadCall } from "../roots/unseen-loads.ts";
 import { keyNameOf, type KeyedAccess } from "../symbol-keys.ts";
 import { parenthesesRemoved } from "../unwrap.ts";
-import { handedOn, valuesOf } from "../value-flow.ts";
+import { handedOn, valuesOf } from "./values.ts";
 
 /**
  * The operators whose left side one assignment stores into. A compound assignment is

package/src/index/values.ts

@@ -0,0 +1,170 @@
+/**
+ * What a written expression evaluates to, the one definition every pass shares: the
+ * values it can be, the values a call's argument carries inside the literals it writes,
+ * and the positions a program hands a value to that the checker types from their context.
+ */
+
+import {
+  isArrayLiteralExpression,
+  isArrowFunction,
+  isAsExpression,
+  isBinaryExpression,
+  isCallExpression,
+  isConditionalExpression,
+  isIdentifier,
+  isNewExpression,
+  isNonNullExpression,
+  isObjectLiteralExpression,
+  isOmittedExpression,
+  isParameterDeclaration,
+  isParenthesizedExpression,
+  isPropertyAccessExpression,
+  isPropertyAssignment,
+  isPropertyDeclaration,
+  isReturnStatement,
+  isSatisfiesExpression,
+  isShorthandPropertyAssignment,
+  isSpreadAssignment,
+  isSpreadElement,
+  isVariableDeclaration,
+  SyntaxKind,
+  type Expression,
+  type Node,
+} from "@typescript/native/ast";
+
+/** 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 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 expressions one written value can evaluate to, each read alone because the checker
+ * reduces a union by subtype, so the type at the whole drops a class another branch's
+ * extends: the operand of a spread, of parentheses and of `!`, each branch of a
+ * conditional, each operand of `??` and `||`, and the right operand of `&&` and of a
+ * comma. The left operand of `&&` is its value only where it is falsy, which no object
+ * is. An assertion is a value of its own, whose type its reader decides.
+ */
+export function valuesOf(expression: Expression): readonly Expression[] {
+  if (isSpreadElement(expression) || isParenthesizedExpression(expression)) {
+    return valuesOf(expression.expression);
+  }
+  if (isNonNullExpression(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 name node a callee, a decorator expression or a value resolves through, where it has one. */
+export function nameOf(expression: Expression): Node | undefined {
+  if (isParenthesizedExpression(expression)) {
+    return nameOf(expression.expression);
+  }
+  if (isPropertyAccessExpression(expression)) {
+    return expression.name;
+  }
+  return isIdentifier(expression) ? expression : undefined;
+}
+
+/** One value an argument carries, and the node its declaration is resolved from. */
+export interface CarriedValue {
+  /** Where the value is written, which is where a record of it sits. */
+  readonly site: Node;
+  /** The name the value is resolved through, the shorthand assignment that holds it, or none. */
+  readonly name: Node | undefined;
+  readonly shorthand: boolean;
+}
+
+/**
+ * The values one argument carries: each value it can be ({@link valuesOf}), or what an
+ * array or object literal it can be holds, at any depth, through spreads and shorthand
+ * properties. Each value is read inside every assertion around it.
+ */
+export function carriedValues(argument: Expression): readonly CarriedValue[] {
+  return valuesOf(argument).flatMap((value): readonly CarriedValue[] => {
+    let at = value;
+    while (isAsExpression(at) || isSatisfiesExpression(at)) {
+      at = at.expression;
+    }
+    if (at !== value) {
+      return carriedValues(at);
+    }
+    if (isArrayLiteralExpression(value)) {
+      return value.elements.flatMap(carriedValues);
+    }
+    if (isObjectLiteralExpression(value)) {
+      return value.properties.flatMap((property): readonly CarriedValue[] => {
+        if (isPropertyAssignment(property)) {
+          return carriedValues(property.initializer);
+        }
+        if (isSpreadAssignment(property)) {
+          return carriedValues(property.expression);
+        }
+        return isShorthandPropertyAssignment(property)
+          ? [{ site: property.name, name: property, shorthand: true }]
+          : [];
+      });
+    }
+    return isOmittedExpression(value)
+      ? []
+      : [{ site: value, name: nameOf(value), shorthand: false }];
+  });
+}
+
+/** The expressions one node hands to a position typed by its context. */
+export 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 [];
+}

package/src/liveness/sweep.ts

@@ -7,7 +7,7 @@
  * unanswered checker question; each Contract rule "live only through" one is a view up to it.
  */
 
-import { exemptionsOf, isUnansweredRecord, type Exemption } from "../exempt.ts";
+import { exemptionsOf, type Exemption } from "../exemptions/lifecycle.ts";
 import type { InventorySymbol } from "../inventory.ts";
 import { edgeWithheldBy, type Mode } from "../tests/file-class.ts";
 import { componentsOf, type Component, type Positional } from "./components.ts";
@@ -644,7 +644,7 @@ function seedsOf(
     const seed = { at, origin: { k: "exemption", record } as const };
     if (record.whileLive !== undefined) {
       gate(record.whileLive, seed);
-    } else if (isUnansweredRecord(record)) {
+    } else if (record.unanswered === true) {
       unanswered.push(seed);
     } else {
       records.push(seed);