@cplieger/deadset-ts 7.2.0-dev.3 → 8.0.0-dev.1

package/src/import-bindings.ts

@@ -0,0 +1,128 @@
+/**
+ * The import bindings of one file: the names its import declarations bind, which only
+ * the file itself can read.
+ */
+
+import {
+  isExportSpecifier,
+  isExternalModuleReference,
+  isIdentifier,
+  isImportDeclaration,
+  isImportEqualsDeclaration,
+  isJsxElement,
+  isJsxFragment,
+  isJsxSelfClosingElement,
+  isNamespaceImport,
+  SyntaxKind,
+  type Identifier,
+  type Node,
+  type SourceFile,
+} from "@typescript/native/ast";
+
+/** The extensions of the files whose import bindings are judged: no markup can read them. */
+const JUDGED = /\.(?:[mc]?ts|tsx|[mc]?js|jsx)$/u;
+
+/** The compiler's `jsx` settings whose emit calls no factory the file must hold. */
+const AUTOMATIC_RUNTIME: ReadonlySet<unknown> = new Set([4, 5, "react-jsx", "react-jsxdev"]);
+
+/** A doc comment, where a JavaScript file names the types it imports. */
+const DOC_COMMENT = /\/\*\*[\s\S]*?\*\//gu;
+
+/** The parts of a doc comment the compiler resolves names in: a `{…}` type or link, a `@see` target. */
+const DOC_REFERENCE = /\{[^{}]*\}|@see\s+[A-Za-z_$][\w$.]*/gu;
+
+/** The factory a pragma comment names: `@jsx h` or `@jsxFrag Fragment`. */
+const PRAGMA = /@jsx(?:Frag)?\s+([A-Za-z_$][\w$]*)/gu;
+
+/** The compiler options the JSX rule reads. */
+export interface JsxOptions {
+  readonly jsx?: unknown;
+  readonly jsxFactory?: unknown;
+  readonly jsxFragmentFactory?: unknown;
+}
+
+/**
+ * The names one file's import declarations bind: the default, named and namespace names of
+ * an `import` declaration, and the name of an `import x = require()` declaration that is
+ * not exported. None is judged in a declaration file or a component file.
+ */
+export function importBindings(file: SourceFile): readonly Identifier[] {
+  if (file.isDeclarationFile || !JUDGED.test(file.fileName)) {
+    return [];
+  }
+  const found: Identifier[] = [];
+  for (const statement of file.statements) {
+    if (isImportDeclaration(statement)) {
+      const clause = statement.importClause;
+      if (clause?.name !== undefined) {
+        found.push(clause.name);
+      }
+      const named = clause?.namedBindings;
+      if (named !== undefined && isNamespaceImport(named)) {
+        found.push(named.name);
+      } else if (named !== undefined) {
+        for (const element of named.elements) {
+          found.push(element.name);
+        }
+      }
+    } else if (
+      isImportEqualsDeclaration(statement) &&
+      isExternalModuleReference(statement.moduleReference) &&
+      isIdentifier(statement.name) &&
+      !(statement.modifiers ?? []).some((modifier) => modifier.kind === SyntaxKind.ExportKeyword)
+    ) {
+      found.push(statement.name);
+    }
+  }
+  return found;
+}
+
+/** Whether one identifier names a binding in a local export, which reads it whatever it resolves to. */
+export function exportsLocally(use: Identifier): boolean {
+  return isExportSpecifier(use.parent);
+}
+
+/**
+ * The names a file reads without an identifier the program resolves: each name a type, a
+ * link or a `@see` tag of its doc comments spells, and, where it writes JSX the compiler
+ * turns into factory calls, the factories the configuration or a pragma names.
+ */
+export function implicitReads(file: SourceFile, options: JsxOptions): ReadonlySet<string> {
+  const names = new Set<string>();
+  for (const comment of file.text.match(DOC_COMMENT) ?? []) {
+    for (const reference of comment.match(DOC_REFERENCE) ?? []) {
+      for (const word of reference.match(/[A-Za-z_$][\w$]*/gu) ?? []) {
+        names.add(word);
+      }
+    }
+  }
+  if (AUTOMATIC_RUNTIME.has(options.jsx) || !writesJsx(file)) {
+    return names;
+  }
+  for (const factory of [options.jsxFactory, options.jsxFragmentFactory]) {
+    names.add(typeof factory === "string" ? (factory.split(".")[0] ?? factory) : "React");
+  }
+  for (const match of file.text.matchAll(PRAGMA)) {
+    if (match[1] !== undefined) {
+      names.add(match[1]);
+    }
+  }
+  return names;
+}
+
+/** Whether a file holds a JSX element or fragment. */
+function writesJsx(file: SourceFile): boolean {
+  let found = false;
+  const visit = (node: Node): void => {
+    if (found) {
+      return;
+    }
+    if (isJsxElement(node) || isJsxSelfClosingElement(node) || isJsxFragment(node)) {
+      found = true;
+      return;
+    }
+    node.forEachChild(visit);
+  };
+  file.forEachChild(visit);
+  return found;
+}

package/src/indexed-access.ts

@@ -11,6 +11,8 @@ import {
   isCallExpression,
   isClassDeclaration,
   isClassExpression,
+  isConstructorDeclaration,
+  isConstructorTypeNode,
   isFunctionDeclaration,
   isFunctionExpression,
   isFunctionTypeNode,
@@ -27,6 +29,7 @@ import {
   isObjectBindingPattern,
   isParenthesizedTypeNode,
   isPropertyAccessExpression,
+  isPropertyAssignment,
   isPropertySignatureDeclaration,
   isStringLiteral,
   isTypeAliasDeclaration,
@@ -71,6 +74,7 @@ function isGeneric(node: Node): node is Generic {
       isArrowFunction(node) ||
       isFunctionExpression(node) ||
       isFunctionTypeNode(node) ||
+      isConstructorTypeNode(node) ||
       isTypeAliasDeclaration(node) ||
       isInterfaceDeclaration(node) ||
       isClassDeclaration(node) ||
@@ -79,6 +83,25 @@ function isGeneric(node: Node): node is Generic {
   );
 }
 
+/** Whether a function declares no type parameter and a parameter whose type holds `keyof`. */
+function takesKeyof(node: Node): node is Generic {
+  if (
+    !(
+      isFunctionDeclaration(node) ||
+      isMethodDeclaration(node) ||
+      isMethodSignatureDeclaration(node) ||
+      isArrowFunction(node) ||
+      isFunctionExpression(node)
+    ) ||
+    node.typeParameters !== undefined
+  ) {
+    return false;
+  }
+  return node.parameters.some(
+    (parameter) => parameter.type !== undefined && keyofOperands(parameter.type).length > 0,
+  );
+}
+
 /** Whether one generic is a receiver's: a class or an interface whose methods it parameterizes. */
 function isReceiver(node: Node): boolean {
   return isInterfaceDeclaration(node) || isClassDeclaration(node) || isClassExpression(node);
@@ -121,8 +144,8 @@ function unwrappedType(node: TypeNode): TypeNode {
 function literalNames(index: TypeNode): readonly string[] | undefined {
   const node = unwrappedType(index);
   if (isUnionTypeNode(node)) {
-    const names = node.types.map(literalNames);
-    return names.every((one) => one !== undefined) ? names.flat() : undefined;
+    const names = node.types.flatMap((one) => literalNames(one) ?? []);
+    return names.length > 0 ? names : undefined;
   }
   if (!isLiteralTypeNode(node)) {
     return undefined;
@@ -134,19 +157,14 @@ function literalNames(index: TypeNode): readonly string[] | undefined {
   return isNumericLiteral(literal) ? [String(Number(literal.text))] : undefined;
 }
 
-/** The name a literal type carries, a union's each, or none where a constituent is no literal. */
-function literalTypeNames(
-  type: Type,
-  parts: (type: Type) => readonly Type[],
-): string[] | undefined {
+/** The names the literal constituents of a type carry: a key the type names is one the access requires. */
+function literalTypeNames(type: Type, parts: (type: Type) => readonly Type[]): string[] {
   const names: string[] = [];
   for (const part of parts(type)) {
     if (part.isStringLiteralType()) {
       names.push(part.value);
     } else if (part.isNumberLiteralType()) {
       names.push(String(part.value));
-    } else {
-      return undefined;
     }
   }
   return names;
@@ -266,7 +284,9 @@ function calledName(generic: Generic): string | undefined {
   }
   const parent = generic.parent as Node | undefined;
   return parent !== undefined &&
-    (isVariableDeclaration(parent) || isPropertySignatureDeclaration(parent)) &&
+    (isVariableDeclaration(parent) ||
+      isPropertySignatureDeclaration(parent) ||
+      isPropertyAssignment(parent)) &&
     isIdentifier(parent.name)
     ? parent.name.text
     : undefined;
@@ -274,9 +294,12 @@ function calledName(generic: Generic): string | undefined {
 
 /** The generic a declaration a symbol names is: the function a variable is initialized with included. */
 function genericOf(node: Node): Generic | undefined {
-  if (isGeneric(node) || isReceiverMember(node)) {
+  if (isGeneric(node) || isReceiverMember(node) || takesKeyof(node)) {
     return node;
   }
+  if (isConstructorDeclaration(node) && isGeneric(node.parent)) {
+    return node.parent;
+  }
   if (isPropertySignatureDeclaration(node)) {
     // The typings mark the annotation present; a signature written without one has none.
     const declared = (node as { readonly type?: TypeNode }).type;
@@ -378,6 +401,8 @@ export function indexedAccessReferences<Brand>(
   const carried = new Map<Generic, Carried[]>();
   const names = new Set<string>();
   const sites: Site[] = [];
+  /** Accesses indexed by a type parameter whose constraint is no `keyof`: it requires each key it names. */
+  const constrained: (Omit<Access, "index"> & { readonly constraint: TypeNode })[] = [];
   /** Calls passing an argument, which a generic declared outside the own files may fix. */
   const argumentCalls: Site[] = [];
 
@@ -407,13 +432,28 @@ export function indexedAccessReferences<Brand>(
       const own = held.declarations.get(nodeKey(file, node));
       const holder = own ?? from;
       const inside = isGeneric(node) ? [...enclosing, node] : enclosing;
-      if (isGeneric(node)) {
+      if (isGeneric(node) || takesKeyof(node)) {
         carriedIn(node).forEach((one) => carry(node, one));
       }
       if (isIndexedAccessTypeNode(node) && !aliasTypes.has(node)) {
         const literal = literalNames(node.indexType);
+        const parameter =
+          literal === undefined ? namedParameter(node.indexType, inside) : undefined;
+        const constraint =
+          parameter === undefined
+            ? undefined
+            : (
+                parameter.generic.typeParameters?.[parameter.index] as
+                  { readonly constraint?: TypeNode } | undefined
+              )?.constraint;
         if (literal !== undefined) {
           accesses.push({ file, from: holder, at: node, object: node.objectType, index: literal });
+        } else if (
+          constraint !== undefined &&
+          keyofOperands(constraint).length === 0 &&
+          namedParameter(node.objectType, inside) === undefined
+        ) {
+          constrained.push({ file, from: holder, at: node, object: node.objectType, constraint });
         }
       }
       if (
@@ -433,7 +473,7 @@ export function indexedAccessReferences<Brand>(
         if (name !== undefined) {
           const site = { file, from: holder, node, name, enclosing: inside };
           sites.push(site);
-          if (isCallExpression(node) && node.arguments.length > 0) {
+          if (argumentsOf(node).length > 0) {
             argumentCalls.push(site);
           }
         }
@@ -447,6 +487,36 @@ export function indexedAccessReferences<Brand>(
     });
   }
 
+  /** The literal keys one constraint names, through the type aliases it references. */
+  const requiredNames = (node: TypeNode, seen: ReadonlySet<Node>): readonly string[] => {
+    const type = unwrappedType(node);
+    if (isUnionTypeNode(type)) {
+      return type.types.flatMap((one) => requiredNames(one, seen));
+    }
+    if (!isTypeReferenceNode(type) || type.typeArguments !== undefined) {
+      return literalNames(type) ?? [];
+    }
+    const [symbol] = queries.symbolsAt([type.typeName]);
+    if (symbol === UNANSWERED || symbol === undefined) {
+      return [];
+    }
+    return symbol.declarations.flatMap((handle) => {
+      const declared = project.declarationAt(handle)?.node;
+      return declared !== undefined &&
+        isTypeAliasDeclaration(declared) &&
+        declared.typeParameters === undefined &&
+        !seen.has(declared)
+        ? requiredNames(declared.type, new Set([...seen, declared]))
+        : [];
+    });
+  };
+  for (const { constraint, ...access } of constrained) {
+    const index = requiredNames(constraint, new Set());
+    if (index.length > 0) {
+      accesses.push({ ...access, index });
+    }
+  }
+
   function partsOf(type: Type): readonly Type[] {
     const parts = queries.constituents(type);
     return parts === UNANSWERED ? [type] : parts;
@@ -471,11 +541,13 @@ export function indexedAccessReferences<Brand>(
    * variable holding the callee is initialized with.
    */
   const receiverTypeOf = (callee: Expression): Type | undefined => {
+    let operand: Type | undefined;
     if (isPropertyAccessExpression(callee)) {
       const type = queries.typeAt(callee.expression);
-      const args = type === UNANSWERED || type === undefined ? [] : queries.typeArguments(type);
-      if (type !== UNANSWERED && type !== undefined && args !== UNANSWERED && args.length > 0) {
-        return type;
+      operand = type === UNANSWERED ? undefined : type;
+      const args = operand === undefined ? [] : queries.typeArguments(operand);
+      if (operand !== undefined && args !== UNANSWERED && args.length > 0) {
+        return operand;
       }
     }
     const name = isPropertyAccessExpression(callee) ? callee.name : callee;
@@ -485,7 +557,7 @@ export function indexedAccessReferences<Brand>(
         ? named
         : queries.aliased(named);
     if (symbol === UNANSWERED || symbol === undefined) {
-      return undefined;
+      return operand;
     }
     for (const handle of symbol.declarations) {
       const node = project.declarationAt(handle)?.node;
@@ -506,7 +578,42 @@ export function indexedAccessReferences<Brand>(
         return type;
       }
     }
-    return undefined;
+    return operand;
+  };
+
+  /**
+   * The instantiation of `owner` a receiver's type is, or the first one among the base
+   * types it extends, breadth first: a subclass fixes its base's type parameters, and
+   * `this` stands for its class.
+   */
+  const instantiationOf = (type: Type, owner: Node): Type | undefined => {
+    const seen = new Set<number>();
+    for (let queue = [type]; queue.length > 0;) {
+      const next: Type[] = [];
+      for (const at of queue) {
+        if (seen.has(at.id)) {
+          continue;
+        }
+        seen.add(at.id);
+        const target = at.isTypeReference() ? queries.targetOf(at) : at;
+        const symbol = target === UNANSWERED ? undefined : queries.symbolOfType(target);
+        const declares =
+          symbol !== undefined &&
+          symbol !== UNANSWERED &&
+          symbol.declarations.some((handle) => project.declarationAt(handle)?.node === owner);
+        if (declares) {
+          return at;
+        }
+        const constraint = at.isTypeParameter() ? queries.constraintOf(at) : undefined;
+        const bases = at.isTypeParameter() ? [] : queries.baseTypes(at);
+        next.push(...(bases === UNANSWERED ? [] : bases));
+        if (constraint !== undefined && constraint !== UNANSWERED) {
+          next.push(constraint);
+        }
+      }
+      queue = next;
+    }
+    return type;
   };
 
   /** What one site fixes for one side of a carried access. */
@@ -517,7 +624,10 @@ export function indexedAccessReferences<Brand>(
     const { node } = site;
     if (side.kind === "receiver") {
       const callee = isCallExpression(node) ? node.expression : undefined;
-      const receiver = callee === undefined ? undefined : receiverTypeOf(callee);
+      const owner = receiverOf(generic);
+      const typed = callee === undefined ? undefined : receiverTypeOf(callee);
+      const receiver =
+        typed === undefined || owner === undefined ? typed : instantiationOf(typed, owner);
       if (receiver === undefined) {
         return undefined;
       }
@@ -541,7 +651,7 @@ export function indexedAccessReferences<Brand>(
     if (isTypeReferenceNode(node)) {
       return undefined;
     }
-    const at = (generic.parameters ?? []).findIndex((parameter) => {
+    const at = parametersOf(generic).findIndex((parameter) => {
       const type = parameter.type === undefined ? undefined : unwrappedType(parameter.type);
       return (
         type !== undefined &&
@@ -645,9 +755,7 @@ export function indexedAccessReferences<Brand>(
   // by its type parameters and its receiver's. Only a call passing an argument the compiler
   // types as a literal can fix an index, so only such a call's signature is resolved.
   const outside = argumentCalls.filter((site) => !resolvedGenerics.has(site));
-  const argumentNodes = argumentCalls.flatMap((site) => [
-    ...(site.node as CallExpression).arguments,
-  ]);
+  const argumentNodes = argumentCalls.flatMap((site) => argumentsOf(site.node));
   const argumentTypes = queries.typesAt(argumentNodes);
   const literalArgument = new Set<Node>();
   argumentTypes.forEach((type, at) => {
@@ -656,14 +764,14 @@ export function indexedAccessReferences<Brand>(
       node !== undefined &&
       type !== UNANSWERED &&
       type !== undefined &&
-      (literalTypeNames(type, partsOf)?.length ?? 0) > 0
+      literalTypeNames(type, partsOf).length > 0
     ) {
       literalArgument.add(node);
     }
   });
   const own = project.ownPaths();
   for (const site of outside) {
-    if (!(site.node as CallExpression).arguments.some((one) => literalArgument.has(one))) {
+    if (!argumentsOf(site.node).some((one) => literalArgument.has(one))) {
       continue;
     }
     const resolved = queries.resolvedSignature(site.node);
@@ -682,7 +790,7 @@ export function indexedAccessReferences<Brand>(
     }
   }
   for (const site of argumentCalls) {
-    if ((site.node as CallExpression).arguments.some((one) => literalArgument.has(one))) {
+    if (argumentsOf(site.node).some((one) => literalArgument.has(one))) {
       accesses.push(...instantiatedAccesses(site));
     }
   }
@@ -706,7 +814,7 @@ export function indexedAccessReferences<Brand>(
     ) {
       return [];
     }
-    const count = (site.node as CallExpression).arguments.length;
+    const count = argumentsOf(site.node).length;
     const parameters: Type[] = [];
     for (let at = 0; at < count; at += 1) {
       const type = queries.parameterType(generic, at);
@@ -745,13 +853,13 @@ export function indexedAccessReferences<Brand>(
       }
       const names = access.index.isTypeParameter()
         ? parameters.flatMap((parameter, at) => {
-            if (parameter.id !== access.index.id) {
+            if (!partsOf(parameter).some((part) => part.id === access.index.id)) {
               return [];
             }
             const passed = queries.typeAtPosition(resolved, at);
-            return passed === UNANSWERED ? [] : (literalTypeNames(passed, partsOf) ?? []);
+            return passed === UNANSWERED ? [] : literalTypeNames(passed, partsOf);
           })
-        : (literalTypeNames(access.index, partsOf) ?? []);
+        : literalTypeNames(access.index, partsOf);
       if (names.length > 0) {
         found.push({
           file: site.file,
@@ -819,6 +927,20 @@ export function indexedAccessReferences<Brand>(
   return found;
 }
 
+/** The arguments a call or a `new` expression passes, none for a type reference. */
+function argumentsOf(node: Site["node"]): readonly Expression[] {
+  return isTypeReferenceNode(node) ? [] : (node.arguments ?? []);
+}
+
+/** The parameters a site's arguments bind: a class's are its constructor's. */
+function parametersOf(generic: Generic): NonNullable<Generic["parameters"]> {
+  if (isClassDeclaration(generic) || isClassExpression(generic)) {
+    const constructor = generic.members.find(isConstructorDeclaration);
+    return constructor?.parameters ?? [];
+  }
+  return generic.parameters ?? [];
+}
+
 /** What makes two carried accesses one: the kind and position of each side, or its written node. */
 function sideKey(one: Carried): readonly unknown[] {
   const key = (side: Side): unknown =>

package/src/interface-satisfaction.ts

@@ -1,10 +1,10 @@
 /**
  * The interface-satisfaction class: a member is held back when a value of its class
- * reaches a position the checker types as an interface requiring that member, through 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, and a position typed by a type parameter reaches its constraint. The contextual
- * lookup has no batch form, so it is asked only of a value typed as a target class.
+ * 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
+ * contextual lookup has no batch form, so it is asked only of a value of a target class.
  */
 
 import {
@@ -20,6 +20,7 @@ import {
   isNewExpression,
   isObjectLiteralExpression,
   isSetAccessorDeclaration,
+  isTypeLiteralNode,
   ModifierFlags,
   SyntaxKind,
   type Expression,
@@ -74,6 +75,11 @@ interface Pair {
   readonly sites: Node[];
 }
 
+/** Whether a type alias names one type: the client's type object carries the alias it was written through. */
+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;
@@ -225,24 +231,38 @@ export function interfaceSatisfaction<Brand>(input: DetectorInput<Brand>): reado
       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 interfaceNames = new Map<string, string | undefined>();
+  /**
+   * The interface types one position's type is or holds, each with the interface's name:
+   * an interface, or an object type literal a type alias names, directly or as a
+   * constituent of an intersection the alias names.
+   */
   const interfacesOf = (type: Type): readonly { type: Type; name: string }[] =>
     partsOf(type).flatMap((part): readonly { type: Type; name: string }[] => {
       if (part.isTypeParameter()) {
         const constraint = must(queries.constraintOf(part));
         return constraint === undefined ? [] : interfacesOf(constraint);
       }
-      if (!interfaceNames.has(part.id)) {
+      const named = aliased(part) ? part : aliased(type) ? type : undefined;
+      const key = `${String(part.id)}:${String(named?.id ?? "")}`;
+      if (!interfaceNames.has(key)) {
         const symbol = part.isObjectType() ? must(queries.symbolOfType(part)) : undefined;
+        const flags = symbol?.flags ?? 0;
         interfaceNames.set(
-          part.id,
-          symbol !== undefined && (symbol.flags & SymbolFlags.Interface) !== 0
-            ? symbol.name
-            : undefined,
+          key,
+          (flags & SymbolFlags.Interface) !== 0
+            ? symbol?.name
+            : (flags & SymbolFlags.TypeLiteral) !== 0 &&
+                named !== undefined &&
+                symbol?.declarations.some((handle) => {
+                  const node = project.declarationAt(handle)?.node;
+                  return node !== undefined && isTypeLiteralNode(node);
+                }) === true
+              ? must(queries.typeToString(named))
+              : undefined,
         );
       }
-      const name = interfaceNames.get(part.id);
+      const name = interfaceNames.get(key);
       return name === undefined ? [] : [{ type: part, name }];
     });