@cplieger/deadset-ts 8.0.0-dev.2 → 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,14 +12,17 @@
  * type, because nothing ties the name to a type.
  */
 
-import { readComponent } from "./component-files.ts";
-import { ConfigError, type Analysis, type 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 { 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 {
@@ -50,14 +53,6 @@ const READ_BY_MARKUP: ReadonlySet<SymbolKind> = new Set([...READ_BY_A_TEMPLATE,
 /** One identifier, as the grammar of the analyzed language spells one. */
 const IDENTIFIER = /[\p{ID_Start}$_][\p{ID_Continue}$\u200C\u200D]*/uy;
 
-/** Two strings ordered bytewise. */
-function compare(a: string, b: string): number {
-  if (a === b) {
-    return 0;
-  }
-  return a < b ? -1 : 1;
-}
-
 /**
  * Every template under the configured directories, read once for the run, in path
  * order and each file once. A directory is named relative to the target root, and
@@ -66,25 +61,22 @@ function compare(a: string, b: string): number {
  * exemption it was configured for off. A symbolic link to a directory is not
  * followed.
  */
-export function readTemplates(host: Host, targetRoot: string, analysis: Analysis): Templates {
+export function readTemplates(
+  host: Host,
+  targetRoot: string,
+  analysis: ResolvedConfig["analysis"],
+): Templates {
   const files = new Map<string, string>();
   const read = (dir: string): void => {
-    const entries = [...host.readDirectory(joinPath(targetRoot, dir))].sort((a, b) =>
-      compare(a.name, b.name),
-    );
-    for (const entry of entries) {
-      const path = joinPath(dir, entry.name);
-      if (entry.directory) {
-        read(path);
-        continue;
-      }
+    for (const below of filesBelow(host, joinPath(targetRoot, dir), () => true)) {
+      const path = joinPath(dir, below);
       const absolute = joinPath(targetRoot, path);
       if (!files.has(path) && host.kindOf(absolute) === "file") {
         files.set(path, host.readFile(absolute));
       }
     }
   };
-  for (const configured of analysis.templateDirs) {
+  for (const configured of analysis.template_dirs) {
     const dir = normalizePath(configured);
     if (
       isAbsolutePath(dir) ||
@@ -92,19 +84,17 @@ export function readTemplates(host: Host, targetRoot: string, analysis: Analysis
       dir.startsWith("../") ||
       host.kindOf(joinPath(targetRoot, dir)) !== "directory"
     ) {
-      throw new ConfigError(
-        "malformed",
-        "analysis.template_dirs",
+      throw new UsageError(
         `analysis.template_dirs: ${JSON.stringify(configured)} is not a directory below the target root`,
       );
     }
     read(dir);
   }
   return {
-    delimiters: analysis.templateDelimiters,
+    delimiters: analysis.template_delimiters,
     files: [...files]
       .map(([path, text]) => ({ path, text }))
-      .sort((a, b) => compare(a.path, b.path)),
+      .sort((a, b) => bytewise(a.path, b.path)),
   };
 }
 

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 =