@cplieger/deadset-ts 7.0.0-dev.2 → 7.0.0-dev.4

package/src/interface-satisfaction.ts

@@ -25,8 +25,8 @@ import {
   type Expression,
   type Node,
   type SourceFile,
-} from "@typescript/native/unstable/ast";
-import { SymbolFlags, type Type } from "@typescript/native/unstable/sync";
+} from "@typescript/native/ast";
+import { SymbolFlags, type Type } from "@typescript/native/sync";
 import { aliasChains } from "./alias-chain.ts";
 import { emptyImplementation } from "./implementations.ts";
 import type { DetectorInput, Evidence } from "./exempt.ts";

package/src/intra-function-parts.ts

@@ -66,7 +66,7 @@ import {
   type Node,
   type SourceFile,
   type Statement,
-} from "@typescript/native/unstable/ast";
+} from "@typescript/native/ast";
 import type { FindingPosition } from "./finding.ts";
 import { nodeKey, type Inventory } from "./inventory.ts";
 import { positionKey, renderPosition } from "./position.ts";
@@ -93,8 +93,17 @@ export interface PartFact {
   readonly used: boolean;
   /** Where the part is a parameter's name, what a function used as a value decides it by. */
   readonly parameter?: ParameterPlace;
+  /** Where the part is a result, whether its type has a `then` member, as a promise does. */
+  readonly thenable?: boolean;
 }
 
+/**
+ * What a call does with its value: uses it, discards it as a statement of its own or the
+ * operand of `void`, or awaits it as a statement, which sequences on a thenable value and
+ * discards any other.
+ */
+type CallUse = "used" | "discarded" | "awaited";
+
 /** What decides a parameter of a function used as a value: a caller may pass it more arguments. */
 interface ParameterPlace {
   /** Whether a parameter after this one, which is no binding-pattern name, is read. */
@@ -116,8 +125,8 @@ interface SignatureFact {
 export interface ProjectParts {
   readonly parts: readonly PartFact[];
   readonly signatures: readonly SignatureFact[];
-  /** Each name written as the callee of a call, by position, and whether the call's value is discarded. */
-  readonly calls: ReadonlyMap<string, boolean>;
+  /** Each name written as the callee of a call, by position, and what the call does with its value. */
+  readonly calls: ReadonlyMap<string, CallUse>;
   /** Each name an import or an export specifier writes, by position, which uses no value. */
   readonly specifiers: ReadonlySet<string>;
 }
@@ -165,16 +174,15 @@ function calleeName(call: CallExpression): Identifier | undefined {
   return isPropertyAccessExpression(callee) && isIdentifier(callee.name) ? callee.name : undefined;
 }
 
-/**
- * Whether a call's value is discarded: the call is a statement of its own, awaited as a
- * statement, or the operand of `void`.
- */
-function discarded(call: CallExpression): boolean {
+/** What a call does with its value. */
+function callUse(call: CallExpression): CallUse {
   const parent = outerParent(call);
   if (isExpressionStatement(parent) || isVoidExpression(parent)) {
-    return true;
+    return "discarded";
   }
-  return isAwaitExpression(parent) && isExpressionStatement(outerParent(parent));
+  return isAwaitExpression(parent) && isExpressionStatement(outerParent(parent))
+    ? "awaited"
+    : "used";
 }
 
 /** Whether one statement leaves its statement list on every path: the rest of the list never runs. */
@@ -473,7 +481,7 @@ export function projectParts<Brand>(
   const kinds = new Map(held.symbols.map((symbol) => [symbol.id, symbol.kind]));
   const parts: PartFact[] = [];
   const signatures: SignatureFact[] = [];
-  const calls = new Map<string, boolean>();
+  const calls = new Map<string, CallUse>();
   const specifiers = new Set<string>();
   const sites: { readonly file: SourceFile; readonly declared: Declared }[] = [];
   const contextual: ContextualParameter[] = [];
@@ -550,7 +558,7 @@ export function projectParts<Brand>(
       if (isCallExpression(node)) {
         const name = calleeName(node);
         if (name !== undefined) {
-          calls.set(position(name), discarded(node));
+          calls.set(position(name), callUse(node));
         }
       }
       if (isImportSpecifier(node) || isExportSpecifier(node)) {
@@ -1004,10 +1012,12 @@ function resultParts<Brand>(
   root: string,
   sites: readonly { readonly file: SourceFile; readonly declared: Declared }[],
   references: readonly Reference[],
-  calls: ReadonlyMap<string, boolean>,
+  calls: ReadonlyMap<string, CallUse>,
 ): PartFact[] {
   const discardedAt = new Set(
-    references.filter((one) => calls.get(positionKey(one.position)) === true).map((one) => one.to),
+    references
+      .filter((one) => (calls.get(positionKey(one.position)) ?? "used") !== "used")
+      .map((one) => one.to),
   );
   const found: PartFact[] = [];
   for (const { file, declared } of sites) {
@@ -1030,6 +1040,8 @@ function resultParts<Brand>(
       continue;
     }
     const at = signature.type ?? (node as { readonly name?: Node }).name ?? node;
+    const valued = project.queries.nonNullable(result);
+    const members = isAnswered(valued) ? project.queries.propertiesOf(valued) : UNANSWERED;
     found.push({
       code: UNUSED_RESULT,
       declaration: id,
@@ -1038,6 +1050,7 @@ function resultParts<Brand>(
       position: spanOf(file, root, at),
       message: "result is discarded at every call site",
       used: false,
+      thenable: !isAnswered(members) || members.some((member) => member.name === "then"),
     });
   }
   return found;
@@ -1077,7 +1090,7 @@ export function intraFunctionFacts(
     const known = parts.get(key);
     parts.set(key, known === undefined ? part : { ...known, used: known.used || part.used });
   }
-  const calls = new Map<string, boolean>();
+  const calls = new Map<string, CallUse>();
   const specifiers = new Set<string>();
   for (const one of projects) {
     for (const [at, value] of one.calls) {
@@ -1089,6 +1102,7 @@ export function intraFunctionFacts(
   }
   const valued = new Set<string>();
   const called = new Map<string, boolean>();
+  const awaited = new Set<string>();
   for (const reference of references) {
     if (reference.use === "decorator" || reference.use === "evaluation") {
       continue;
@@ -1096,7 +1110,10 @@ export function intraFunctionFacts(
     const at = positionKey(reference.position);
     const call = reference.consumer === undefined ? calls.get(at) : undefined;
     if (call !== undefined) {
-      called.set(reference.to, (called.get(reference.to) ?? true) && call);
+      called.set(reference.to, (called.get(reference.to) ?? true) && call !== "used");
+      if (call === "awaited") {
+        awaited.add(reference.to);
+      }
     } else if (reference.consumer !== undefined || !specifiers.has(at)) {
       valued.add(reference.to);
     }
@@ -1115,8 +1132,16 @@ export function intraFunctionFacts(
       .map((one) => one.declaration)
       .filter((id) => !fixed.has(id) && !exempted.has(id) && valued.has(id)),
   );
+  // Awaiting a thenable result sequences on it, so a call that awaits one uses it.
+  const sequenced = new Set(
+    [...parts.values()]
+      .filter((part) => part.thenable === true && awaited.has(part.declaration))
+      .map((part) => part.declaration),
+  );
   const discardedEverywhere = new Set(
-    [...called].filter(([id, all]) => all && !valued.has(id)).map(([id]) => id),
+    [...called]
+      .filter(([id, all]) => all && !valued.has(id) && !sequenced.has(id))
+      .map(([id]) => id),
   );
   return { parts: [...parts.values()], free, freeButValued, discardedEverywhere };
 }

package/src/inventory.ts

@@ -28,8 +28,8 @@ import {
   ModifierFlags,
   type Node,
   type SourceFile,
-} from "@typescript/native/unstable/ast";
-import type { Symbol as TSSymbol } from "@typescript/native/unstable/sync";
+} from "@typescript/native/ast";
+import type { Symbol as TSSymbol } from "@typescript/native/sync";
 import type { Host } from "./host.ts";
 import { dirnamePath, joinPath, relativePath } from "./paths.ts";
 import {
@@ -165,6 +165,12 @@ export interface Inventory {
   readonly byName: ReadonlyMap<string, readonly string[]>;
   /** Each `declare module` declaration whose name is a string literal, by id, to that name. */
   readonly modules: ReadonlyMap<string, string>;
+  /**
+   * Each enum member's dependents, by id: the later members of its declaration with no
+   * initializer, up to the first one with an initializer, whose values its deletion moves.
+   * A member with none has no entry.
+   */
+  readonly dependents: ReadonlyMap<string, readonly string[]>;
 }
 
 /** A declaration under construction, before its reference is rendered. */
@@ -986,6 +992,31 @@ export function inventory<Brand>(
     return undefined;
   }
 
+  const dependents = new Map<string, readonly string[]>();
+  for (const container of containers.filter((one) => one.memberKind === "enum-member")) {
+    const ids = container.members.map((member) => {
+      const record = byNode.get(nodeKey(member.getSourceFile(), member));
+      return record === undefined ? undefined : positionKey(record.position);
+    });
+    container.members.forEach((_member, index) => {
+      const after: string[] = [];
+      for (let next = index + 1; next < container.members.length; next += 1) {
+        const member = container.members[next];
+        if (member === undefined || !isEnumMember(member) || member.initializer !== undefined) {
+          break;
+        }
+        const id = ids[next];
+        if (id !== undefined) {
+          after.push(id);
+        }
+      }
+      const id = ids[index];
+      if (id !== undefined && after.length > 0) {
+        dependents.set(id, after);
+      }
+    });
+  }
+
   const byId = new Map(building.map((record) => [positionKey(record.position), record]));
   const symbols = building
     .map(render)
@@ -1002,6 +1033,7 @@ export function inventory<Brand>(
       .map((symbol) => symbol.id),
     byName: namesOf(building),
     modules: new Map(modules.map(([record, name]) => [positionKey(record.position), name])),
+    dependents,
   };
 }
 

package/src/keyof-comparisons.ts

@@ -0,0 +1,211 @@
+/**
+ * The members a comparison with a key reads: where one operand of `===`, `!==`, `==` or
+ * `!=`, or a `switch` expression a `case` label is compared with, is declared with a type
+ * that holds `keyof X`, the literal the other side has names the member of `X` under that
+ * key, because deleting the member makes the comparison a type error.
+ */
+
+import {
+  isBinaryExpression,
+  isCaseClause,
+  isElementAccessExpression,
+  isIdentifier,
+  isParenthesizedExpression,
+  isPropertyAccessExpression,
+  isSwitchStatement,
+  isTypeOperatorNode,
+  SyntaxKind,
+  type Expression,
+  type Node,
+  type SourceFile,
+  type TypeNode,
+} from "@typescript/native/ast";
+import { SymbolFlags, type Type } from "@typescript/native/sync";
+import type { AliasChains } from "./alias-chain.ts";
+import { nodeKey, type Inventory } from "./inventory.ts";
+import { renderPosition } from "./position.ts";
+import { UNANSWERED } from "./query.ts";
+import type { Reference } from "./references.ts";
+import type { ProjectView } from "./session.ts";
+
+/** The operators that compare their operands for equality. */
+const EQUALITIES: ReadonlySet<SyntaxKind> = new Set([
+  SyntaxKind.EqualsEqualsEqualsToken,
+  SyntaxKind.ExclamationEqualsEqualsToken,
+  SyntaxKind.EqualsEqualsToken,
+  SyntaxKind.ExclamationEqualsToken,
+]);
+
+/** One comparison of a keyed operand with another, and the declaration that writes it. */
+interface Comparison {
+  readonly file: SourceFile;
+  readonly from: string;
+  readonly keyed: Expression;
+  readonly other: Expression;
+}
+
+function unwrapped(node: Expression): Expression {
+  return isParenthesizedExpression(node) ? unwrapped(node.expression) : node;
+}
+
+/** The name node an operand's symbol is read at: an identifier, or a property access's name. */
+function nameOf(node: Expression): Node | undefined {
+  const at = unwrapped(node);
+  if (isIdentifier(at)) {
+    return at;
+  }
+  return isPropertyAccessExpression(at) ? at.name : undefined;
+}
+
+/** The operand of each `keyof` one type node holds, through every type node it is built of. */
+function keyofOperands(node: TypeNode): readonly TypeNode[] {
+  const found: TypeNode[] = [];
+  const visit = (at: Node): void => {
+    if (isTypeOperatorNode(at) && at.operator === SyntaxKind.KeyOfKeyword) {
+      found.push(at.type);
+      return;
+    }
+    at.forEachChild(visit);
+  };
+  visit(node);
+  return found;
+}
+
+/** The names a literal type or a union of them spells, or none. */
+function literalNames(parts: readonly Type[]): readonly string[] {
+  const names: string[] = [];
+  for (const part of parts) {
+    if (part.isStringLiteralType()) {
+      names.push(part.value);
+    } else if (part.isNumberLiteralType()) {
+      names.push(String(part.value));
+    } else {
+      return [];
+    }
+  }
+  return names;
+}
+
+/**
+ * The references the key comparisons of one project's own files make to the members their
+ * literal side names, each made by the declaration holding the comparison.
+ */
+export function keyofComparisonReferences<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+  chains: AliasChains,
+  root: string,
+  testFiles: ReadonlySet<string>,
+): readonly Reference[] {
+  const queries = project.queries;
+  const comparisons: Comparison[] = [];
+  for (const file of project.ownSourceFiles()) {
+    const fileId = held.declarations.get(nodeKey(file, file));
+    if (fileId === undefined) {
+      continue;
+    }
+    const visit = (node: Node, from: string): void => {
+      const holder = held.declarations.get(nodeKey(file, node)) ?? from;
+      if (isBinaryExpression(node) && EQUALITIES.has(node.operatorToken.kind)) {
+        comparisons.push({ file, from: holder, keyed: node.left, other: node.right });
+        comparisons.push({ file, from: holder, keyed: node.right, other: node.left });
+      }
+      if (isSwitchStatement(node)) {
+        for (const clause of node.caseBlock.clauses) {
+          if (isCaseClause(clause)) {
+            comparisons.push({
+              file,
+              from: holder,
+              keyed: node.expression,
+              other: clause.expression,
+            });
+          }
+        }
+      }
+      node.forEachChild((child) => {
+        visit(child, holder);
+      });
+    };
+    file.forEachChild((child) => {
+      visit(child, fileId);
+    });
+  }
+  const named = comparisons.flatMap((one) => {
+    const name = nameOf(one.keyed);
+    return name === undefined || isElementAccessExpression(unwrapped(one.other))
+      ? []
+      : [{ ...one, name }];
+  });
+  if (named.length === 0) {
+    return [];
+  }
+
+  // The operand's own declaration states the key type, which the checker resolves to
+  // the literals it admits and so no longer names the type the key indexes.
+  const symbols = queries.symbolsAt(named.map((one) => one.name));
+  const keyed = named.flatMap((one, at) => {
+    const asked = symbols[at];
+    const symbol =
+      asked === UNANSWERED || asked === undefined || (asked.flags & SymbolFlags.Alias) === 0
+        ? asked
+        : queries.aliased(asked);
+    if (symbol === UNANSWERED || symbol === undefined) {
+      return [];
+    }
+    const operands = symbol.declarations.flatMap((handle) => {
+      const declared = (
+        project.declarationAt(handle)?.node as { readonly type?: TypeNode } | undefined
+      )?.type;
+      return declared === undefined ? [] : keyofOperands(declared);
+    });
+    return operands.length === 0 ? [] : [{ ...one, operands }];
+  });
+  if (keyed.length === 0) {
+    return [];
+  }
+  const nodes = keyed.flatMap((one) => [one.other, ...one.operands]);
+  const types = queries.typesAt(nodes);
+  const typeOf = new Map<Node, Type>();
+  nodes.forEach((node, at) => {
+    const type = types[at];
+    if (type !== UNANSWERED && type !== undefined) {
+      typeOf.set(node, type);
+    }
+  });
+  const partsOf = (type: Type): readonly Type[] => {
+    const parts = queries.constituents(type);
+    return parts === UNANSWERED ? [type] : parts;
+  };
+
+  const found: Reference[] = [];
+  for (const one of keyed) {
+    const literal = typeOf.get(one.other);
+    const names = literal === undefined ? [] : literalNames(partsOf(literal));
+    if (names.length === 0) {
+      continue;
+    }
+    const position = renderPosition(one.file, root, one.other.getStart());
+    for (const operand of one.operands) {
+      const object = typeOf.get(operand);
+      for (const part of object === undefined ? [] : partsOf(object)) {
+        const properties = queries.propertiesOf(part);
+        for (const property of properties === UNANSWERED ? [] : properties) {
+          if (!names.includes(property.name)) {
+            continue;
+          }
+          for (const to of chains.declarationsOf(property)) {
+            found.push({
+              from: one.from,
+              to,
+              position,
+              use: "read",
+              resolution: "keyed",
+              test: testFiles.has(position.path),
+            });
+          }
+        }
+      }
+    }
+  }
+  return found;
+}

package/src/kinds.ts

@@ -19,6 +19,8 @@ export interface KindRow {
   /** The highest confidence a finding of the kind carries. */
   readonly maxClass: Confidence;
   readonly fixability: Fixability;
+  /** Each fixability a finding of the kind may carry in place of `fixability`. */
+  readonly findingFixabilities?: readonly Fixability[];
   /**
    * Whether the Contract fixes the kind on at its default severity, so a severity key
    * naming the code, or a family prefix whose range holds it, is an unimplemented key.
@@ -43,6 +45,7 @@ const ROWS: readonly KindRow[] = [
     defaultSeverity: "deny",
     maxClass: "certain",
     fixability: "deletable",
+    findingFixabilities: ["manual"],
     fixed: false,
   },
   {
@@ -53,6 +56,7 @@ const ROWS: readonly KindRow[] = [
     defaultSeverity: "deny",
     maxClass: "certain",
     fixability: "deletable",
+    findingFixabilities: ["manual"],
     fixed: false,
   },
   {
@@ -65,6 +69,7 @@ const ROWS: readonly KindRow[] = [
     defaultSeverity: "deny",
     maxClass: "certain",
     fixability: "deletable",
+    findingFixabilities: ["manual"],
     fixed: false,
   },
   {
@@ -75,6 +80,7 @@ const ROWS: readonly KindRow[] = [
     defaultSeverity: "deny",
     maxClass: "certain",
     fixability: "deletable",
+    findingFixabilities: ["manual"],
     fixed: false,
   },
   {
@@ -85,6 +91,7 @@ const ROWS: readonly KindRow[] = [
     defaultSeverity: "deny",
     maxClass: "certain",
     fixability: "deletable",
+    findingFixabilities: ["manual"],
     fixed: false,
   },
   {
@@ -95,6 +102,7 @@ const ROWS: readonly KindRow[] = [
     defaultSeverity: "deny",
     maxClass: "certain",
     fixability: "deletable",
+    findingFixabilities: ["manual"],
     fixed: false,
   },
   {
@@ -103,7 +111,7 @@ const ROWS: readonly KindRow[] = [
     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, 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.",
+      "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. A package-level declaration whose name a string literal spells carries the class grammar/analysis.md gives it.",
     defaultSeverity: "warn",
     maxClass: "certain",
     fixability: "narrowable",
@@ -125,10 +133,11 @@ const ROWS: readonly KindRow[] = [
     code: "DS1103",
     name: "unreachable-export",
     languages: ["go", "ts"],
-    rule: "An unused exported symbol in a package or file no external code can import: an unused-exported candidate whose enclosing package or file is unimportable from outside, reported once under this code at the certain class, because unimportability is a property of the package graph rather than of the consumer set.",
+    rule: "An unused exported symbol in a package or file no external code can import: an unused-exported candidate whose enclosing package or file is unimportable from outside, reported once under this code at the certain class, because unimportability is a property of the package graph rather than of the consumer set, except where the confidence rule of grammar/analysis.md gives a declaration a string literal spells the class possible.",
     defaultSeverity: "deny",
     maxClass: "certain",
     fixability: "deletable",
+    findingFixabilities: ["manual"],
     fixed: false,
   },
   {
@@ -151,6 +160,7 @@ const ROWS: readonly KindRow[] = [
     defaultSeverity: "deny",
     maxClass: "certain",
     fixability: "deletable",
+    findingFixabilities: ["manual"],
     fixed: false,
   },
   {
@@ -170,6 +180,8 @@ const ROWS: readonly KindRow[] = [
     name: "unused-satisfaction-assertion",
     languages: ["go"],
     rule: "A compile-time satisfaction assertion whose interface no symbol uses as a type.",
+    precondition:
+      "In a library, an assertion whose interface is published API, an exported interface of a package outside programs can import, has the reachability class possible, whatever consumers the run declares and loads. The assertion checks a promise the published API makes, that the type satisfies the published interface, and that promise is made to every program that imports the package, not only to the consumers the run declares. A loaded consumer that names the interface as a type uses it, and the assertion is not reported.",
     defaultSeverity: "deny",
     maxClass: "certain",
     fixability: "deletable",
@@ -179,7 +191,7 @@ const ROWS: readonly KindRow[] = [
     code: "DS1301",
     name: "write-only-symbol",
     languages: ["go", "ts"],
-    rule: "A package-level or module-level variable, struct field, class member, type member or collection that production code writes and never reads. In production mode a read from a test file counts as no read. A write from a loaded consumer's code counts as a read, because the deletion the finding names would break a consumer the target does not own. A write in a consumer's test file counts as a read in the run that counts test references. It counts in a production sweep only where the configuration counts consumer tests as production. A comparison of struct values reads every field of the type: in Go, a value of a struct type used as an operand of `==` or `!=`, as a map key, or as a `switch` tag or `case` expression is a read of every field of that type, transitively through the fields of every struct type it holds, recorded at the comparison, because equality reads every field and a field that decides equality carries information. In Go a type argument the program instantiates a type parameter with, where the parameter's constraint is `comparable` or embeds it, is compared as an operand of `==` of that type is, recorded at the instantiation, so the struct values `slices.Equal`, `slices.Index` or `maps.Equal` compares have every field read. `reflect.DeepEqual` is not a comparison under this rule. In TypeScript a comparison of two object references reads no member, because `===` compares identity and never a member. In TypeScript a property of an object literal writes the member of the same name that the literal's contextual type declares, whether or not the compiler checks the literal for excess properties. Where that contextual type is a union or an intersection, the property writes the member of that name on each constituent that declares one. So a literal that a declaration annotates, a function returns, a call passes or a `satisfies` expression checks writes the members of the type it is given. A store through the value a field or a member holds reads that field or member rather than writing it, because the store lands in storage every other holder of the value reads. In Go that store is an assignment, an increment, a compound assignment or a `delete` whose target is reached through a struct field holding a map, a slice or a pointer. Examples are `s.f[k] = v`, `s.f.x = v` and `delete(s.f, k)`. The same store through a field holding an array or a struct is a store into the field itself. TypeScript holds every object by reference, so an element or property store through a member's value reads the member. The finding names each write position, so the deletion set is visible. Deleting the subject and its writes also deletes every declaration whose only uses they hold. Such a declaration is a type parameter of the subject's declaring type that the subject's type alone names, an import binding the writes alone use, or a declaration whose every use is in the type annotation of the subject or of another subject this rule reports, or in the writes those findings name. The finding's message names each such declaration, and no finding is reported about the declaration itself.",
+    rule: "A package-level or module-level variable, struct field, class member, type member or collection that production code writes and never reads. In production mode a read from a test file counts as no read. A write from a loaded consumer's code counts as a read, because the deletion the finding names would break a consumer the target does not own. A write in a consumer's test file counts as a read in the run that counts test references. It counts in a production sweep only where the configuration counts consumer tests as production. A comparison of struct values reads every field of the type: in Go, a value of a struct type used as an operand of `==` or `!=`, as a map key, or as a `switch` tag or `case` expression is a read of every field of that type, transitively through the fields of every struct type it holds, recorded at the comparison, because equality reads every field and a field that decides equality carries information. In Go a type argument the program instantiates a type parameter with, where the parameter's constraint is `comparable` or embeds it, is compared as an operand of `==` of that type is, recorded at the instantiation, so the struct values `slices.Equal`, `slices.Index` or `maps.Equal` compares have every field read. `reflect.DeepEqual` is not a comparison under this rule. In Go, a conversion the compiler accepts between two struct types, or between two pointer types that are not named types and whose base types are struct types, reads every field of the two struct types where their struct type literals are distinct, recorded at the conversion, because the conversion is legal only while their fields are identical, ignoring tags, and so no field of either can be deleted alone. It reads in the same way every field of each pair of distinct struct type literals the identity of the two types compares in turn: through each field's type, and from there through the element, key, base, parameter and result types of the type literals it reaches, through the method signatures of an interface type literal, and through the type arguments of an instantiated generic type. A field reached there has no reference of its own, as grammar/symbol-ref.md states, so it is never a subject and those reads hold no finding back. It stops at a defined type, whose fields the conversion does not read, because a defined type is identical to itself whatever fields it declares. A pair whose two sides are one struct type literal, the two struct types themselves included, as where one type is declared from the other or the conversion is to the operand's own type, reads nothing, because a field deleted from that literal leaves both sides identical. Where the operand's type or the conversion's type is a type parameter, the struct type its constraint's core type is takes that side's place, and a type parameter operand reads in the same way the fields of each struct type argument an instantiation the program holds gives it, an instantiation made through another generic declaration's own type parameters included. A conversion to any other type, an interface type among them, reads no field under this rule. In TypeScript a comparison of two object references reads no member, because `===` compares identity and never a member. In TypeScript a property of an object literal writes the member of the same name that the literal's contextual type declares, whether or not the compiler checks the literal for excess properties. Where that contextual type is a union or an intersection, the property writes the member of that name on each constituent that declares one. So a literal that a declaration annotates, a function returns, a call passes or a `satisfies` expression checks writes the members of the type it is given. An object literal handed to a callee the target does not implement has its members read, as grammar/analysis.md states. A store through the value a field or a member holds reads that field or member rather than writing it, because the store lands in storage every other holder of the value reads. In Go that store is an assignment, an increment, a compound assignment or a `delete` whose target is reached through a struct field holding a map, a slice or a pointer. Examples are `s.f[k] = v`, `s.f.x = v` and `delete(s.f, k)`. The same store through a field holding an array or a struct is a store into the field itself. TypeScript holds every object by reference, so an element or property store through a member's value reads the member. The finding names each write position, so the deletion set is visible. Deleting the subject and its writes also deletes every declaration whose only uses they hold. Such a declaration is a type parameter of the subject's declaring type that the subject's type alone names, an import binding the writes alone use, or a declaration whose every use is in the type annotation of the subject or of another subject this rule reports, or in the writes those findings name. The finding's message names each such declaration, and no finding is reported about the declaration itself.",
     defaultSeverity: "deny",
     maxClass: "certain",
     fixability: "deletable",
@@ -193,6 +205,7 @@ const ROWS: readonly KindRow[] = [
     defaultSeverity: "deny",
     maxClass: "certain",
     fixability: "deletable",
+    findingFixabilities: ["manual"],
     fixed: false,
   },
   {
@@ -211,7 +224,7 @@ const ROWS: readonly KindRow[] = [
     code: "DS1501",
     name: "file-never-built",
     languages: ["go", "ts"],
-    rule: "A source file no configuration in the build matrix builds. On the Go side the finding names the build constraint that excluded the file. A file whose build constraint is the ignore tag is never reported: the toolchain applies no build constraint to a file named on its own command line, so that tag is the toolchain's convention for a file built by hand. A file any other custom tag excludes is reported under a matrix the configuration declares complete, because completeness is the maintainer's assertion that the listed configurations are every one the target builds, and a configuration the maintainer builds by hand belongs in that list.",
+    rule: "A source file no configuration in the build matrix builds. On the Go side the finding names the build constraint that excluded the file. A file whose build constraint holds only when the ignore tag is set is never reported, because grammar/analysis.md keeps such a file outside the analysis wherever no configuration builds it: the tag is the toolchain's convention for a file kept out of ordinary package builds unless a configuration explicitly satisfies the tag, and built by hand, the toolchain applying no build constraint to a file named on its own command line. A file any other custom tag excludes is reported under a matrix the configuration declares complete, because completeness is the maintainer's assertion that the listed configurations are every one the target builds, and a configuration the maintainer builds by hand belongs in that list.",
     precondition:
       'Reported only when the configuration declares the build matrix complete, and never for a file the toolchain ignored solely because it imports "C" under a build with cgo disabled. Such a file is recorded as excluded by cgo rather than as never built.',
     defaultSeverity: "deny",
@@ -235,7 +248,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 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.",
+      "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. Four 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, and one that a needed dependency names as a peer, as stated below. A command no script entry and no workflow step runs needs nothing. A declared dependency that the installed manifest of a needed declared dependency names in its peerDependencies is needed, and so on until no further dependency joins. A peer dependency is a package the needed dependency expects beside it at a version its manifest states, whether or not it imports the package, and the project's declaration is what keeps that package present at a version the project chooses, so removing the declaration can break the needed dependency where nothing the analysis reads imports the peer. A peer that peerDependenciesMeta marks optional is needed in the same way, because the needed dependency's manifest still names it as a package it works with, and a package manager may leave an optional peer out where the project does not declare it, so the project's declaration is what keeps it present for the needed dependency. A declared dependency that only dependencies nothing needs name as a peer is needed by nothing. 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 directory of the manifest that declares the dependency, and a dependency with none is decided by the import closure alone. On the TypeScript side, the dependencies judged are those of every manifest grammar/analysis.md says the analysis reads, a nested package's among them, each read against its own directory: a dependency is needed by a use written in a file at or below the directory of the manifest that declares it, by a use no one file holds, and as a peer of a needed dependency of the same manifest or of a manifest below it. A dependency a nested package's manifest declares whose installed manifest the analysis cannot find is not judged, because no run requires a nested package to be installed and its commands and peers cannot be read, while a workspace member's and the target's own are judged as above.",
     defaultSeverity: "deny",
     maxClass: "certain",
     fixability: "manual",
@@ -277,7 +290,7 @@ const ROWS: readonly KindRow[] = [
     code: "DS1703",
     name: "stale-suppression",
     languages: ["go", "ts"],
-    rule: "A suppression that matches no current finding, at either mechanism and in the baseline alike. The run exits with the findings code when at least one is reported. The kind is fixed on at deny: no flag, no severity setting and no per-mechanism exception reduces it below a finding, and a configuration naming this code under a severity key is an unimplemented key.",
+    rule: "A suppression record that is stale, as grammar/suppression.md defines it, at either mechanism and in the baseline alike. The run exits with the findings code when at least one is reported. The kind is fixed on at deny: no flag, no severity setting and no per-mechanism exception reduces it below a finding, and a configuration naming this code under a severity key is an unimplemented key.",
     defaultSeverity: "deny",
     maxClass: "certain",
     fixability: "none",
@@ -345,7 +358,7 @@ const ROWS: readonly KindRow[] = [
     languages: ["go", "ts"],
     rule: "A result value that no call site of the function uses, on a function whose signature is free to change.",
     precondition:
-      "The same free-signature rule as unused-parameter, plus a closed-world condition: every call site of the function must be in the loaded graph, because an unknown caller may consume the result, so the kind reports only for a function whose callers are all visible.",
+      "The same free-signature rule as unused-parameter, plus a closed-world condition: every call site of the function must be in the loaded graph, because an unknown caller may consume the result, so the kind reports only for a function whose callers are all visible. A call that is the operand of an await expression written as a statement of its own uses a result whose type has a member named then, a promise or another thenable, because the caller sequences on it, and discards any other result. A call written as a statement of its own, or as the operand of void, discards its result whatever its type.",
     defaultSeverity: "warn",
     maxClass: "certain",
     fixability: "manual",

package/src/manifest.ts

@@ -6,7 +6,7 @@
  */
 
 import type { Host } from "./host.ts";
-import { dirnamePath, isAbsolutePath, joinPath, relativePath, resolvePath } from "./paths.ts";
+import { isAbsolutePath, joinPath, relativePath, resolvePath } from "./paths.ts";
 
 /** The manifest's own name. */
 const MANIFEST = "package.json";
@@ -212,31 +212,16 @@ export function readManifest(host: Host, targetRoot: string): Manifest {
 }
 
 /**
- * The entry points every package manifest between the target root and each compiler
- * configuration names: each directory holding a `package.json` that a configuration sits
- * in or below, the target root and `known` excluded, whose manifests the run reads
- * otherwise. Each entry is spelled under its manifest's path below the target root, and
- * is published by its own manifest's rule, as the target's own entries are.
+ * The entry points the manifests of the nested packages in `dirs` name. Each entry is
+ * spelled under its manifest's path below the target root, and is published by its own
+ * manifest's rule, as the target's own entries are.
  */
 export function packageEntries(
   host: Host,
   targetRoot: string,
-  configFiles: readonly string[],
-  known: ReadonlySet<string>,
+  dirs: readonly string[],
 ): readonly ManifestEntry[] {
-  const dirs = new Set<string>();
-  for (const configFile of configFiles) {
-    for (
-      let dir = dirnamePath(resolvePath(targetRoot, configFile));
-      dir !== targetRoot && relativePath(targetRoot, dir) !== undefined;
-      dir = dirnamePath(dir)
-    ) {
-      if (!known.has(dir) && host.kindOf(joinPath(dir, MANIFEST)) === "file") {
-        dirs.add(dir);
-      }
-    }
-  }
-  return [...dirs].sort().flatMap((dir) => {
+  return dirs.flatMap((dir) => {
     const manifest = readManifest(host, dir);
     const where = `${relativePath(targetRoot, dir) ?? dir}/${MANIFEST}`;
     return manifest.entries.map((entry) => ({