@cplieger/deadset-ts 6.1.1-dev.1 → 7.0.0-dev.2

package/src/intra-function-parts.ts

@@ -6,6 +6,7 @@
  */
 
 import {
+  isArrayBindingPattern,
   isArrowFunction,
   isAwaitExpression,
   isBigIntLiteral,
@@ -55,10 +56,12 @@ import {
   isVoidExpression,
   NodeFlags,
   SyntaxKind,
+  type ArrowFunction,
   type BindingName,
   type Block,
   type CallExpression,
   type CatchClause,
+  type FunctionExpression,
   type Identifier,
   type Node,
   type SourceFile,
@@ -473,6 +476,7 @@ export function projectParts<Brand>(
   const calls = new Map<string, boolean>();
   const specifiers = new Set<string>();
   const sites: { readonly file: SourceFile; readonly declared: Declared }[] = [];
+  const contextual: ContextualParameter[] = [];
 
   for (const file of files) {
     const declarationAt = (node: Node): string | undefined => {
@@ -624,15 +628,25 @@ export function projectParts<Brand>(
       });
       const reader = readers.get(one.signature);
       if (reader !== undefined) {
-        parts.push(...parameterParts(file, targetRoot, one.id, one.signature, reader, ids, false));
+        const found = parameterParts(file, targetRoot, one.id, one.signature, reader, ids, false);
+        parts.push(...found.parts);
+        contextual.push(...found.contextual);
       }
     }
     for (const one of walk.values) {
       const reader = readers.get(one.signature);
       if (reader !== undefined) {
-        parts.push(
-          ...parameterParts(file, targetRoot, one.holder, one.signature, reader, ids, true),
+        const found = parameterParts(
+          file,
+          targetRoot,
+          one.holder,
+          one.signature,
+          reader,
+          ids,
+          true,
         );
+        parts.push(...found.parts);
+        contextual.push(...found.contextual);
       }
     }
     walk.catches.forEach(({ name, holder }, at) => {
@@ -677,7 +691,7 @@ export function projectParts<Brand>(
   }
 
   parts.push(...resultParts(project, targetRoot, sites, references, calls));
-  return { parts, signatures, calls, specifiers };
+  return { parts: withContextualRead(project, parts, contextual), signatures, calls, specifiers };
 }
 
 /**
@@ -743,9 +757,38 @@ function parameterNames(signature: SignatureNode): ParameterName[] {
   return found;
 }
 
+/** An unread name of a parameter that a contextual type of its function expression keeps. */
+interface ContextualParameter {
+  readonly part: PartFact;
+  readonly signature: ArrowFunction | FunctionExpression;
+}
+
+/**
+ * The parts with each name of `contextual` read where the compiler gives its function a
+ * contextual type: the inference of the call holding the function may read a parameter's
+ * annotation, and the code handing the argument may act on what an object pattern reads.
+ * A question the checker leaves unanswered keeps the name read.
+ */
+function withContextualRead<Brand>(
+  project: ProjectView<Brand>,
+  parts: readonly PartFact[],
+  contextual: readonly ContextualParameter[],
+): readonly PartFact[] {
+  if (contextual.length === 0) {
+    return parts;
+  }
+  const signatures = [...new Set(contextual.map((one) => one.signature))];
+  const answers = project.queries.contextualTypes(signatures);
+  const typed = new Set(signatures.filter((_signature, at) => answers[at] !== undefined));
+  const read = new Set(contextual.filter((one) => typed.has(one.signature)).map((one) => one.part));
+  return parts.map((part) => (read.has(part) ? { ...part, used: true } : part));
+}
+
 /**
- * Each name one function's parameters bind and whether the function reads it. A binding
- * pattern counts as read where its function reads any name it binds.
+ * Each name one function's parameters bind and whether the function reads it, and the
+ * unread names a contextual type of a function expression may keep: those of a parameter
+ * that carries a type annotation or is an object binding pattern. A binding pattern counts
+ * as read where its function reads any name it binds.
  */
 function parameterParts(
   file: SourceFile,
@@ -755,7 +798,7 @@ function parameterParts(
   reader: { readonly names: readonly ParameterName[]; readonly uses: readonly Identifier[] },
   ids: ReadonlyMap<Node, Answer<number>>,
   inValue: boolean,
-): PartFact[] {
+): { readonly parts: PartFact[]; readonly contextual: ContextualParameter[] } {
   // A function that reads `arguments` reads every parameter by position.
   const readsArguments =
     !isArrowFunction(signature) && identifiersNaming(signature, new Set(["arguments"])).length > 0;
@@ -766,11 +809,14 @@ function parameterParts(
   );
   const lastRead = Math.max(-1, ...reader.names.filter((_, at) => read[at]).map((one) => one.at));
   const found: PartFact[] = [];
+  const contextual: ContextualParameter[] = [];
+  const expression =
+    isArrowFunction(signature) || isFunctionExpression(signature) ? signature : undefined;
   reader.names.forEach(({ name, at, pattern, exempt }, index) => {
     if (exempt) {
       return;
     }
-    found.push({
+    const part: PartFact = {
       code: UNUSED_PARAMETER,
       declaration,
       kind: "parameter",
@@ -779,9 +825,19 @@ function parameterParts(
       message: `parameter ${name.text} is never read in the body`,
       used: read[index] === true,
       parameter: { beforeARead: !pattern && at < lastRead, inValue },
-    });
+    };
+    found.push(part);
+    const parameter = signature.parameters[at];
+    if (
+      expression !== undefined &&
+      !part.used &&
+      parameter !== undefined &&
+      (parameter.type !== undefined || isObjectBindingPattern(parameter.name))
+    ) {
+      contextual.push({ part, signature: expression });
+    }
   });
-  return found;
+  return { parts: found, contextual };
 }
 
 /** One local a block declares by name, and every identifier of the block that spells it. */
@@ -792,6 +848,22 @@ interface Local {
   readonly uses: readonly Identifier[];
 }
 
+/**
+ * The names one declaration binds that a write of its initializer stores each on its own:
+ * the declared name, or each element name of an array binding pattern at any depth.
+ */
+function arrayPatternNames(name: BindingName): readonly Identifier[] {
+  if (isIdentifier(name)) {
+    return [name];
+  }
+  if (!isArrayBindingPattern(name)) {
+    return [];
+  }
+  return name.elements.flatMap((element) =>
+    isBindingElement(element) && element.name !== undefined ? arrayPatternNames(element.name) : [],
+  );
+}
+
 /** The locals one block declares with `let` or `const`, each with the names that spell it. */
 function localsOf(block: Block): readonly Local[] {
   const declared: { name: Identifier; statement: number; initialized: boolean }[] = [];
@@ -807,9 +879,9 @@ function localsOf(block: Block): readonly Local[] {
       return;
     }
     for (const declaration of list.declarations) {
-      if (isIdentifier(declaration.name)) {
+      for (const name of arrayPatternNames(declaration.name)) {
         declared.push({
-          name: declaration.name,
+          name,
           statement: at,
           initialized: declaration.initializer !== undefined,
         });

package/src/inventory.ts

@@ -139,8 +139,6 @@ export interface InventoryCost {
 
 /** One project's declarations, in position order, and what reading them cost. */
 export interface Inventory {
-  /** The compiler configuration the project was opened from. */
-  readonly configFile: string;
   readonly symbols: readonly InventorySymbol[];
   /**
    * Each declaring node's {@link nodeKey} mapped to the identifier of the declaration
@@ -154,20 +152,6 @@ export interface Inventory {
    */
   readonly declarations: ReadonlyMap<string, string>;
   readonly cost: InventoryCost;
-  /**
-   * The module specifiers of the bare star re-exports the project's files carry, in
-   * the order they were read. A bare star re-export declares nothing here: the names
-   * it carries forward are the declarations of the module it names, so it is a
-   * reference to that module and not a declaration of this one.
-   */
-  readonly starReExports: readonly string[];
-  /**
-   * The number of member declarations that were left out because the file declaring
-   * them is not one of the target's own files. Such a declaration belongs to another
-   * program, so the target's inventory does not name it, and the count is reported so
-   * that the omission is a number rather than a silence.
-   */
-  readonly outsideOwnFiles: number;
   /**
    * The declarations whose module, namespace or container table the checker did not
    * answer, in position order: whether each is exported, and which members a table
@@ -534,9 +518,7 @@ export function inventory<Brand>(
   const byNode = new Map<string, Building>();
   const exportScopes: ExportScope[] = [];
   const containers: Container[] = [];
-  const starReExports: string[] = [];
   const modules: (readonly [Building, string])[] = [];
-  let outsideOwnFiles = 0;
 
   const keep = (record: Building): Building => {
     building.push(record);
@@ -782,14 +764,10 @@ export function inventory<Brand>(
     }
   }
 
-  function walkExportDeclaration(
-    node: { readonly exportClause?: Node; readonly moduleSpecifier?: Node },
-    owner: Building,
-  ): void {
+  function walkExportDeclaration(node: { readonly exportClause?: Node }, owner: Building): void {
     const clause = node.exportClause;
+    // A bare star re-export declares nothing: the names it carries are the named module's.
     if (clause === undefined) {
-      const specifier = node.moduleSpecifier;
-      starReExports.push(specifier === undefined ? "" : literalTextOf(specifier));
       return;
     }
     if (isNamespaceExport(clause)) {
@@ -876,7 +854,7 @@ export function inventory<Brand>(
         memberTables += 1;
         const table = project.queries.membersOf(symbol);
         if (isAnswered(table)) {
-          outsideOwnFiles += readTable(container, table, seen, false);
+          readTable(container, table, seen, false);
         } else {
           unansweredOwners.add(container.owner);
         }
@@ -885,7 +863,7 @@ export function inventory<Brand>(
         memberTables += 1;
         const table = project.queries.exportsOf(symbol);
         if (isAnswered(table)) {
-          outsideOwnFiles += readTable(container, table, seen, container.isClass);
+          readTable(container, table, seen, container.isClass);
         } else {
           unansweredOwners.add(container.owner);
         }
@@ -905,8 +883,7 @@ export function inventory<Brand>(
     table: ReadonlyMap<string, TSSymbol>,
     seen: Map<string, Building>,
     areStatic: boolean,
-  ): number {
-    let outside = 0;
+  ): void {
     for (const [, member] of table) {
       const declarations = member.declarations
         .map((handle) => project.declarationAt(handle))
@@ -916,7 +893,6 @@ export function inventory<Brand>(
       }
       const own = declarations.filter((held) => ownFiles.has(held.node.getSourceFile().fileName));
       if (own.length === 0) {
-        outside += declarations.length;
         continue;
       }
       // A merged symbol's table holds the members every one of its declarations writes,
@@ -925,7 +901,6 @@ export function inventory<Brand>(
         keepMember(container, held.node, seen, areStatic);
       }
     }
-    return outside;
   }
 
   /**
@@ -1017,14 +992,11 @@ export function inventory<Brand>(
     .sort((a, b) => byPosition(a.position, b.position) || (a.ref < b.ref ? -1 : 1));
 
   return {
-    configFile: project.configFile,
     symbols,
     declarations: new Map(
       [...byNode].map(([key, record]) => [key, positionKey(record.position)] as const),
     ),
     cost: { batches: 1, exportTables, memberTables },
-    starReExports,
-    outsideOwnFiles,
     unanswered: symbols
       .filter((symbol) => underUnanswered(byId.get(symbol.id), unansweredOwners))
       .map((symbol) => symbol.id),

package/src/json-document.ts

@@ -100,7 +100,7 @@ class Walk {
 }
 
 /** What a walk of one document found. */
-export interface DocumentWalk {
+interface DocumentWalk {
   /** The offset of the brace opening each object of the document's array member, in order. */
   readonly opened: readonly number[];
   /** The first member one object writes twice, at any depth, as the offset of its name. */

package/src/kinds.ts

@@ -101,7 +101,7 @@ const ROWS: readonly KindRow[] = [
     code: "DS1101",
     name: "unnecessary-export",
     languages: ["go", "ts"],
-    rule: "An exported symbol whose every reference is inside the symbol's own package or module, reported as a candidate for unexporting. The subject is a package-level declaration or a method. Three subjects are excluded. An interface method is excluded because its exportedness is the contract of the interface that declares it. A struct field is excluded because an encoder reads it by name. A method that satisfies an interface some symbol uses as a type is excluded because it cannot be unexported without its type ceasing to satisfy that interface. The finding names the narrower visibility the references support. A declared cross-language edge counts as an out-of-package reference. Where the edge's other side is unknown to the analyzer, the finding is emitted pending.",
+    rule: "An exported symbol whose every reference is inside the symbol's own package or module, reported as a candidate for unexporting. The subject is a package-level declaration or a method. Three subjects are excluded. An interface method is excluded because its exportedness is the contract of the interface that declares it. A struct field is excluded because an encoder reads it by name. A method that satisfies an interface some symbol uses as a type is excluded because it cannot be unexported without its type ceasing to satisfy that interface, and so is a method whose name and signature are those of a method of an exported interface type declared by a package outside the target that the import closure holds, because that interface fixes them whether or not the program converts the method's type to it. The finding names the narrower visibility the references support. A declared cross-language edge counts as an out-of-package reference. Where the edge's other side is unknown to the analyzer, the finding is emitted pending. A reference from a Go external test package, a test file whose package clause names its directory's package with the suffix _test, is a reference from outside the package, because that test builds as another package and needs the export.",
     precondition:
       "Closed world only. A Go main package, and an internal/ directory tree for importers outside its parent, are closed worlds whatever the configuration declares, because no other program can import them, so this finding is reported there always. A published package is a closed world only when the configuration declares the consumer set complete and every declared consumer loads. A library with no consumer loaded and no complete consumer set declared gets this finding on its internal/ tree and its main packages and never on its published API. A symbol the rule of DS1301 holds for is not reported under this code, whatever severity the configuration gives DS1301, because the write-only finding names the defect to fix first. A type that a parameter or a result of an exported function or method of its own package names is not reported when a reference from outside the package references that function or method, because the caller holds values of the type, and unexporting it would leave an exported signature naming a type its callers cannot name.",
     defaultSeverity: "warn",
@@ -113,7 +113,7 @@ const ROWS: readonly KindRow[] = [
     code: "DS1102",
     name: "unnecessary-exposure",
     languages: ["go"],
-    rule: "An exported symbol of a non-internal package whose every reference is inside the target module, reported as a candidate for relocation behind an internal boundary. The subject is a package-level declaration or a method. Three subjects are excluded. An interface method is excluded because its exportedness is the contract of the interface that declares it. A struct field is excluded because an encoder reads it by name. A method that satisfies an interface some symbol uses as a type is excluded because it cannot be unexported without its type ceasing to satisfy that interface. The finding names the narrower visibility the references support. A declared cross-language edge counts as an out-of-package reference. Where the edge's other side is unknown to the analyzer, the finding is emitted pending.",
+    rule: "An exported symbol of a non-internal package whose every reference is inside the target module, reported as a candidate for relocation behind an internal boundary. The subject is a package-level declaration or a method. Three subjects are excluded. An interface method is excluded because its exportedness is the contract of the interface that declares it. A struct field is excluded because an encoder reads it by name. A method that satisfies an interface some symbol uses as a type is excluded because it cannot be unexported without its type ceasing to satisfy that interface, and so is a method whose name and signature are those of a method of an exported interface type declared by a package outside the target that the import closure holds, because that interface fixes them whether or not the program converts the method's type to it. The finding names the narrower visibility the references support. A declared cross-language edge counts as an out-of-package reference. Where the edge's other side is unknown to the analyzer, the finding is emitted pending. A reference from a Go external test package, a test file whose package clause names its directory's package with the suffix _test, is a reference from outside the package, because that test builds as another package and needs the export.",
     precondition:
       "Closed world only. Reported always for a main package and an internal/ directory tree, and for a published package only when the configuration declares the consumer set complete and every declared consumer loads. A library with no consumer loaded and no complete consumer set declared gets this finding on its internal/ tree and its main packages and never on its published API. A symbol the rule of DS1301 holds for is not reported under this code, whatever severity the configuration gives DS1301, because the write-only finding names the defect to fix first. A type that a parameter or a result of an exported function or method of its own package names is not reported when a reference from outside the target module references that function or method, because the caller holds values of the type, and moving it behind an internal boundary would leave an exported signature naming a type its callers cannot name.",
     defaultSeverity: "warn",
@@ -235,7 +235,7 @@ const ROWS: readonly KindRow[] = [
     languages: ["go", "ts"],
     rule: "A directly declared dependency that no import in the target needs. On the Go side, a direct require whose module provides no package any target package or test variant imports. On the TypeScript side, a manifest dependency, development dependency or peer dependency the project's import closure does not need. A deletion finding whose fix would remove the last use of a dependency names that dependency.",
     precondition:
-      "On the Go side the rule is the semantics of `go mod tidy -diff` exactly: a requirement marked indirect is never reported, because it exists to pin a transitive version and removing it changes the build list. On the TypeScript side the import closure is the files of the run's projects, and four more dependencies are needed. The first is one whose installed manifest declares a command, because a command is run by name rather than imported. The second is one that the installed manifest of a needed dependency declares as a peer and does not mark optional. The third is every required peer of a dependency so held, to a fixpoint. The fourth is one that a string names under a manifest key of an applied convention row, as grammar/analysis.md states. An installed manifest is the package's manifest in the nearest node_modules directory at or above the target, and a dependency with none is decided by the import closure alone.",
+      "On the Go side the rule is the semantics of `go mod tidy -diff` exactly: a requirement marked indirect is never reported, because it exists to pin a transitive version and removing it changes the build list. On the TypeScript side the import closure is the files of the run's projects, and a call of `import.meta.resolve` or of `require.resolve` in them, whatever `require` names, whose first argument is a string literal or a template literal with no substitution needs each dependency an import of that specifier needs. Three more dependencies are needed: one whose command a script entry or a workflow step runs, one that a string of a configuration file names, and one that a string names under a manifest key or a package key of an applied convention row, each as grammar/analysis.md states. A command no script entry and no workflow step runs needs nothing, and a peer the installed manifest of a needed dependency requires is needed only as any other dependency is, because the package manager installs a required peer itself. A dependency of a manifest whose directory holds source only in configurations the run lists in configurations_not_built is reported at the reachability class possible, because the source that may import it was not analyzed. An installed manifest is the package's manifest in the nearest node_modules directory at or above the target, and a dependency with none is decided by the import closure alone.",
     defaultSeverity: "deny",
     maxClass: "certain",
     fixability: "manual",
@@ -319,7 +319,7 @@ const ROWS: readonly KindRow[] = [
     languages: ["go", "ts"],
     rule: "A parameter with no reference inside its function body, on a function whose signature is free to change.",
     precondition:
-      "The signature must be free, defined as follows: the function is not a method retained by interface satisfaction, is not used as a value, is not a go:linkname or cgo target, is not a function the Go test driver runs (a test, benchmark or fuzz test of a test file, or TestMain), and is not a stub whose body is empty or only panics. A parameter its body never names is dead whatever the callers, so a published declaration of a library is reported too, with the fixability the vocabulary gives the kind: the signature change is a breaking change. In TypeScript a caller may pass a function used as a value more arguments than it declares parameters, so in such a function whose signature is free but for that use, a parameter its body never reads is reported when its body reads no parameter after it, and an unread parameter before the last read one is not. A TypeScript parameter that is a binding pattern is judged by the names it binds: each name the body never reads is reported wherever the pattern stands, because removing it from the pattern moves no argument, except a name beside a rest element of the same object pattern, whose removal changes what that element holds, and the pattern counts as a read parameter when the body reads any name it binds. A rest parameter is judged as the last parameter. A TypeScript `this` parameter declares the type of `this` and receives no argument, so it is never reported. No name exempts a parameter. A TypeScript parameter whose name starts with an underscore is judged as any other is, and a Go parameter named by the blank identifier declares no name a body could read and is never reported.",
+      "The signature must be free, defined as follows: the function is not a method retained by interface satisfaction, is not a method whose name and signature are those of a method of an exported interface type declared by a package outside the target that the import closure holds, is not used as a value, is not a go:linkname or cgo target, is not a function the Go test driver runs (a test, benchmark or fuzz test of a test file, or TestMain), and is not a stub whose body is empty or only panics. A function literal or function expression that initializes a variable the program only calls, never passing, storing, returning or assigning it, is called by name and is not used as a value. A parameter its body never names is dead whatever the callers, so a published declaration of a library is reported too, with the fixability the vocabulary gives the kind: the signature change is a breaking change. In TypeScript a caller may pass a function used as a value more arguments than it declares parameters, so in such a function whose signature is free but for that use, a parameter its body never reads is reported when its body reads no parameter after it, and an unread parameter before the last read one is not. A parameter of a TypeScript function expression or arrow function that the compiler gives a contextual type is not reported when it carries a type annotation, because the inference of the call that holds the function may read the annotation, or when it is an object binding pattern, because the pattern reads each property it names from the argument and the code that hands the argument may act on that read. No name such a pattern binds is reported either. Any other TypeScript parameter that is a binding pattern is judged by the names it binds: each name the body never reads is reported wherever the pattern stands, because removing it from the pattern moves no argument, except a name beside a rest element of the same object pattern, whose removal changes what that element holds, and the pattern counts as a read parameter when the body reads any name it binds. A rest parameter is judged as the last parameter. A TypeScript `this` parameter declares the type of `this` and receives no argument, so it is never reported. No name exempts a parameter. A TypeScript parameter whose name starts with an underscore is judged as any other is, and a Go parameter named by the blank identifier declares no name a body could read and is never reported.",
     defaultSeverity: "warn",
     maxClass: "certain",
     fixability: "manual",
@@ -330,8 +330,9 @@ const ROWS: readonly KindRow[] = [
     code: "DS1802",
     name: "unused-receiver",
     languages: ["go"],
-    rule: "A named method receiver with no reference inside the method body, on a method whose signature is free to change. Go permits a method with no receiver name, so the fix deletes an identifier and changes no signature.",
-    precondition: "The same free-signature rule as unused-parameter, applied to the receiver.",
+    rule: "A named method receiver with no reference inside the method body. Go permits a method with no receiver name, so the fix deletes an identifier and changes no signature.",
+    precondition:
+      "None beyond the rule. Deleting a receiver name changes no signature, so a method retained by interface satisfaction, a method used as a value and a stub are reported as any other method is.",
     defaultSeverity: "warn",
     maxClass: "certain",
     fixability: "deletable",

package/src/manifest.ts

@@ -15,7 +15,7 @@ const MANIFEST = "package.json";
 const LEGACY_MEMBERS = ["main", "module", "types"] as const;
 
 /** What reaches one entry point the manifest names. */
-export type EntryRole =
+type EntryRole =
   /** A consumer importing the package, which is a caller the analysis cannot see. */
   | "import"
   /** A shell running the package's command, which is a caller that exists. */

package/src/namespace-objects.ts

@@ -34,7 +34,7 @@ import {
 } from "@typescript/native/unstable/ast";
 
 /** What one use of a namespace object reads beyond the names the checker resolves. */
-export type NamespaceUse =
+type NamespaceUse =
   /** Every export of the module `specifier` names. */
   | { readonly kind: "whole"; readonly specifier: Node }
   /** The export a literal index names, the literal being the node to resolve. */

package/src/pnpm-workspace.ts

@@ -6,7 +6,7 @@
  */
 
 /** What the document says about `packages`. */
-export type PnpmPackages =
+type PnpmPackages =
   | { readonly kind: "listed"; readonly patterns: readonly string[] }
   /** The document declares no `packages` key. */
   | { readonly kind: "absent" }