@cplieger/deadset-ts 5.0.0 → 5.1.0

package/src/dependencies.ts

@@ -27,6 +27,7 @@ import {
   declaredIn as declaredBeside,
   dependenciesNamed,
   moduleStrings,
+  type ParseFile,
 } from "./configuration-files.ts";
 import type { FindingPosition } from "./finding.ts";
 import type { Host } from "./host.ts";
@@ -284,6 +285,7 @@ export function projectNeeds<Brand>(
   held: Inventory,
   host: Host,
   targetRoot: string,
+  parse?: ParseFile,
 ): ProjectNeeds {
   const programPackages = new Set<string>();
   for (const name of project.program.getSourceFileNames()) {
@@ -329,7 +331,12 @@ export function projectNeeds<Brand>(
     }
     return names;
   };
-  const configuration = configurationFiles(host, targetRoot, sourceFilesOf(project, targetRoot));
+  const configuration = configurationFiles(
+    host,
+    targetRoot,
+    sourceFilesOf(project, targetRoot),
+    parse,
+  );
   for (const { file } of configuration.modules) {
     const names = declaredAt(file.fileName);
     for (const { node, text } of moduleStrings(file)) {
@@ -342,6 +349,12 @@ export function projectNeeds<Brand>(
       use([PROJECT_OWNER], dependenciesNamed(text, names));
     }
   }
+  for (const { file, manifestDir } of configuration.outside) {
+    const names = declaredAt(joinPath(manifestDir, "package.json"));
+    for (const { text } of moduleStrings(file)) {
+      use([PROJECT_OWNER], dependenciesNamed(text, names));
+    }
+  }
   return { packages, uses, unanswered };
 }
 

package/src/destructuring.ts

@@ -25,7 +25,13 @@ import {
   type Node,
 } from "@typescript/native/unstable/ast";
 import { TypeFlags, type Symbol as TSSymbol, type Type } from "@typescript/native/unstable/sync";
-import { isAnswered, UNANSWERED, type Answer } from "./query.ts";
+import {
+  isAnswered,
+  propertyTables,
+  UNANSWERED,
+  type Answer,
+  type PropertyTables,
+} from "./query.ts";
 import type { ProjectView } from "./session.ts";
 
 /** One property one object pattern reads. */
@@ -228,7 +234,11 @@ type Found = Answer<Type | undefined>;
  * read once per type for the whole project, since one type is destructured in many
  * places and a table answers every name of it.
  */
-export function destructuring<Brand>(project: ProjectView<Brand>, cap: number): Destructuring {
+export function destructuring<Brand>(
+  project: ProjectView<Brand>,
+  cap: number,
+  properties: PropertyTables = propertyTables(project.queries),
+): Destructuring {
   const queries = project.queries;
   const tables = new Map<number, Answer<ReadonlyMap<string, TSSymbol>>>();
   let patternBatches = 0;
@@ -241,10 +251,10 @@ export function destructuring<Brand>(project: ProjectView<Brand>, cap: number):
     }
     let table: Answer<ReadonlyMap<string, TSSymbol>> = new Map<string, TSSymbol>();
     if ((type.flags & TypeFlags.AnyOrUnknown) === 0) {
-      patternLookups += 1;
-      const properties = queries.propertiesOf(type);
-      table = isAnswered(properties)
-        ? new Map(properties.map((property) => [property.name, property]))
+      const read = properties.of(type);
+      patternLookups += read.asked ? 1 : 0;
+      table = isAnswered(read.properties)
+        ? new Map(read.properties.map((property) => [property.name, property]))
         : UNANSWERED;
     }
     tables.set(type.id, table);

package/src/entry-points.ts

@@ -30,7 +30,12 @@ import {
   type SourceFile,
 } from "@typescript/native/unstable/ast";
 import { SymbolFlags } from "@typescript/native/unstable/sync";
-import { configurationFiles, filesNamedBy, moduleStrings } from "./configuration-files.ts";
+import {
+  configurationFiles,
+  filesNamedBy,
+  moduleStrings,
+  type ParseFile,
+} from "./configuration-files.ts";
 import { globExpression } from "./glob.ts";
 import type { Host } from "./host.ts";
 import { dirnamePath, relativePath, resolvePath } from "./paths.ts";
@@ -260,8 +265,9 @@ function configurationEntries(
   host: Host,
   targetRoot: string,
   files: SourceFiles,
+  parse: ParseFile | undefined,
 ): readonly EntryPoint[] {
-  const { modules, documents } = configurationFiles(host, targetRoot, files);
+  const { modules, documents, outside } = configurationFiles(host, targetRoot, files, parse);
   const found: EntryPoint[] = [];
   const strings = (dir: string, texts: readonly string[]): void => {
     for (const text of texts) {
@@ -280,6 +286,12 @@ function configurationEntries(
   for (const document of documents) {
     strings(dirnamePath(document.path), document.strings);
   }
+  for (const { file } of outside) {
+    strings(
+      dirnamePath(file.fileName),
+      moduleStrings(file).map((one) => one.text),
+    );
+  }
   return found;
 }
 
@@ -507,8 +519,9 @@ export function entryPoints<Brand>(
   testFiles: readonly string[],
   host: Host,
   targetRoot: string,
+  parse?: ParseFile,
 ): readonly EntryPoint[] {
-  const found: EntryPoint[] = [...configurationEntries(host, targetRoot, files)];
+  const found: EntryPoint[] = [...configurationEntries(host, targetRoot, files, parse)];
   const tests = testFiles.map((pattern) => ({ pattern, expression: globExpression(pattern) }));
   for (const [path, file] of files.byPath) {
     const name = basename(path);

package/src/exempt-classes.ts

@@ -49,7 +49,12 @@ export const EXEMPTION_CLASSES = [
     confidence: "certain",
     typescriptVisibility: { private: false, privateName: false },
   },
-  { class: "generated-file", languages: ["go"], confidence: "certain" },
+  {
+    class: "generated-file",
+    languages: ["go", "ts"],
+    confidence: "certain",
+    typescriptVisibility: { private: true, privateName: false },
+  },
   { class: "linkname-cgo-asm-plugin", languages: ["go"], confidence: "certain" },
   {
     class: "template-field",

package/src/exempt.ts

@@ -48,6 +48,11 @@ export interface DetectorInput<Brand> {
   readonly ts: TSSection;
   /** The absolute path of each declared consumer, whose modules are part of the analysis. */
   readonly consumers: readonly string[];
+  /**
+   * The project's generated files, by path below the target root, each with the
+   * convention row that names its directory as generated.
+   */
+  readonly generated?: ReadonlyMap<string, string>;
 }
 
 /**
@@ -162,8 +167,29 @@ export function computeExemptions<Brand>(
   detectors: Detectors,
   holding: Holding,
 ): readonly Exemption[] {
+  return detectExemptions(input, detectors, holding).records;
+}
+
+/** One project's records, and the evidence a production mode found in a test file. */
+export interface Detected {
+  readonly records: readonly Exemption[];
+  /**
+   * Under a production mode, each record whose evidence is written in a test file. It
+   * holds nothing, and it is a test reference to its declaration, as a reference the
+   * test file wrote would be.
+   */
+  readonly inTestFiles: readonly Exemption[];
+}
+
+/** The records of {@link computeExemptions}, beside the test-file evidence it set aside. */
+export function detectExemptions<Brand>(
+  input: DetectorInput<Brand>,
+  detectors: Detectors,
+  holding: Holding,
+): Detected {
   const visibility = new Map(input.held.symbols.map((symbol) => [symbol.id, symbol.visibility]));
   const found: Exemption[] = [];
+  const inTestFiles: Exemption[] = [];
   for (const exemptionClass of TS_EXEMPTION_CLASSES) {
     const detect = detectors.get(exemptionClass);
     if (detect === undefined || holding.disabled.has(exemptionClass)) {
@@ -174,19 +200,21 @@ export function computeExemptions<Brand>(
       if (!retainable(allowed, visibility.get(evidence.id))) {
         continue;
       }
-      if (holding.mode.production && holding.testFiles.has(evidence.site.path)) {
-        continue;
-      }
-      found.push({
+      const record = {
         id: evidence.id,
         class: exemptionClass,
         detail: evidence.detail,
         site: evidence.site,
         ...(evidence.whileLive === undefined ? {} : { whileLive: evidence.whileLive }),
-      });
+      };
+      if (holding.mode.production && holding.testFiles.has(evidence.site.path)) {
+        inTestFiles.push(record);
+        continue;
+      }
+      found.push(record);
     }
   }
-  return exemptionsOf(found);
+  return { records: exemptionsOf(found), inTestFiles };
 }
 
 /** Two strings ordered bytewise. */
@@ -247,17 +275,18 @@ function byDeclaration(records: readonly Exemption[]): ReadonlyMap<string, reado
 }
 
 /**
- * The records that held back a declaration some configuration of the run would
- * otherwise judge dead: each configuration's graph is swept once more with no
- * exemption and the marks it was given, and a record is retained when one of those
- * sweeps judged its declaration a candidate. A record that holds a declaration back in
- * one configuration is retained whatever another configuration answers about it, as a
- * run of that configuration alone would report the declaration without it. A record
- * on a declaration that a relation or a mark holds live in every configuration held
- * nothing back. The order is the declarations' site order, and for one declaration
- * the input's.
+ * The records that held back a declaration: one some configuration's graph, swept
+ * again with no exemption and its marks, judges a candidate, whatever another
+ * configuration answers, or one in `writeOnly`, which the run would report as written
+ * and never read without the record's read. A declaration a relation or a mark holds
+ * live in every configuration is held back by no record. The order is the
+ * declarations' site order, and for one declaration the input's.
  */
-export function retainedIn(matrix: Matrix, input: SweepInput): readonly Exemption[] {
+export function retainedIn(
+  matrix: Matrix,
+  input: SweepInput,
+  writeOnly: ReadonlySet<string> = new Set(),
+): readonly Exemption[] {
   const exempt = input.exempt ?? [];
   if (exempt.length === 0) {
     return [];
@@ -268,7 +297,9 @@ export function retainedIn(matrix: Matrix, input: SweepInput): readonly Exemptio
       sweep(graph, bare).candidates.map((candidate) => candidate.id),
     ),
   );
-  const held = byDeclaration(exempt.filter((record) => dead.has(record.id)));
+  const held = byDeclaration(
+    exempt.filter((record) => dead.has(record.id) || writeOnly.has(record.id)),
+  );
   return matrix.union.symbols.flatMap((symbol) => held.get(symbol.id) ?? []);
 }
 

package/src/file-facts.ts

@@ -47,6 +47,8 @@ export interface FileFacts {
    * reference names is included by the file that names it.
    */
   readonly heldByInclusion: ReadonlySet<string>;
+  /** The paths below the target root of the files below a directory an applied row names as generated. */
+  readonly generated?: ReadonlySet<string>;
 }
 
 /** The line of the last character of one text, counted from one; an empty text is one line. */

package/src/findings/completion.ts

@@ -146,8 +146,9 @@ export function completed(
   const classOf = reachabilityClasses(input);
   const componentOf = findingComponents(swept, input.config.reporters.cascade);
   let minted = swept.sweep.components.length;
+  const dead = new Set(swept.sweep.components.map((component) => component.id));
 
-  return findings.map((finding): CompletedFinding => {
+  const done = findings.map((finding): CompletedFinding => {
     const row = kinds.get(finding.code);
     if (row === undefined) {
       throw new Error(`${finding.code} names no live row of the issue-kind vocabulary`);
@@ -183,6 +184,7 @@ export function completed(
         ? union.made[at]
         : { production: candidate.productionRefs, test: candidate.testRefs };
     const reachabilityClass = judged === undefined ? "certain" : classOf(judged.id);
+    const generated = input.files.generated?.has(finding.position.path) === true;
     return {
       code: finding.code,
       kind: row.name,
@@ -193,7 +195,7 @@ export function completed(
       confidence: capped(reachabilityClass, row.maxClass),
       ...(candidate === undefined ? {} : { livenessRelation: candidate.relation }),
       testOnly: judged !== undefined && counts?.production === 0 && counts.test > 0,
-      generated: false,
+      generated,
       component,
       retainedBy: [],
       configurations:
@@ -202,12 +204,38 @@ export function completed(
           ? swept.matrix.configurations
           : (swept.matrix.heldIn[at] ?? swept.matrix.configurations)),
       consumersLoaded: input.boundary.consumers.loaded,
-      fixability: row.fixability,
+      fixability: generated ? "none" : row.fixability,
       severity: severityOf(input, finding.code, row.defaultSeverity),
       message: finding.message,
       details: finding.details ?? {},
     };
   });
+  return componentCapped(done, dead);
+}
+
+/**
+ * The findings with every finding of a dead component capped by the lowest confidence
+ * among the component's root members, so the minimum confidence reports or withholds a
+ * component whole.
+ */
+function componentCapped(
+  findings: readonly CompletedFinding[],
+  dead: ReadonlySet<string>,
+): readonly CompletedFinding[] {
+  const lowest = new Map<string, Confidence>();
+  for (const finding of findings) {
+    const { id, root } = finding.component;
+    if (root && dead.has(id)) {
+      const held = lowest.get(id);
+      lowest.set(id, held === undefined ? finding.confidence : capped(held, finding.confidence));
+    }
+  }
+  return findings.map((finding) => {
+    const cap = lowest.get(finding.component.id);
+    return cap === undefined || RANK[cap] >= RANK[finding.confidence]
+      ? finding
+      : { ...finding, confidence: cap };
+  });
 }
 
 /** Whether the dials withhold a finding by its own severity or confidence. */

package/src/findings/interfaces.ts

@@ -31,6 +31,7 @@ function compare(a: string, b: string): number {
 function indexed(input: EmitterInput): {
   readonly symbolOf: (id: string) => InventorySymbol | undefined;
   readonly inTest: (id: string) => boolean;
+  readonly inSupport: (id: string) => boolean;
   readonly candidateOf: (id: string) => Candidate | undefined;
   readonly implementationsOf: (id: string) => readonly PositionedSymbol[];
 } {
@@ -43,6 +44,7 @@ function indexed(input: EmitterInput): {
   return {
     symbolOf,
     inTest: (id) => union.test[union.at(id)] === true,
+    inSupport: (id) => union.support[union.at(id)] === true,
     candidateOf: (id) => candidates.get(id),
     implementationsOf: (id) =>
       [...(input.implementations.classes.get(id) ?? [])]
@@ -80,14 +82,19 @@ function findingOf(
  * interface, whose members fall with it unreported; and `DS1203`, a method of a live
  * interface no reference names, unless it is a marker, a method whose every
  * implementation has an empty body. A test file's declaration is neither kind's
- * subject, because a production sweep counts none of the references it can have.
+ * subject, because a production sweep counts none of the references it can have, and
+ * neither is a test-support declaration test code references, which that code keeps live.
  */
 export const interfaces: Emitter = (input) => {
   const run = indexed(input);
   const found: Finding[] = [];
   for (const candidate of input.swept.sweep.candidates) {
     const symbol = run.symbolOf(candidate.id);
-    if (symbol === undefined || run.inTest(candidate.id)) {
+    if (
+      symbol === undefined ||
+      run.inTest(candidate.id) ||
+      (run.inSupport(candidate.id) && candidate.testRefs > 0)
+    ) {
       continue;
     }
     if (symbol.kind === "interface") {

package/src/findings/reads-and-writes.ts

@@ -62,23 +62,76 @@ function findingAbout(
 interface Uses {
   readonly writes: FindingPosition[];
   reads: number;
+  /** The import bindings only the writes use. */
+  readonly alone: Set<string>;
 }
 
 /**
  * Whether one declaration is a subject of the write-only kind: a module-level variable,
- * or a class member that is state rather than code. A getter or a setter is code, so a
- * store into one runs it.
+ * a member of an object type, or a class member that is state rather than code. A getter
+ * or a setter is code, so a store into one runs it.
  */
 function writable(run: Run, symbol: InventorySymbol): boolean {
-  if (symbol.kind === "variable") {
+  if (symbol.kind === "variable" || symbol.kind === "type-member") {
     return true;
   }
   return symbol.kind === "class-member" && !run.input.stores.accessors.has(symbol.id);
 }
 
+/** The reader's word for each kind of the write-only kind's subject. */
+const SUBJECT_WORDS: Readonly<Partial<Record<InventorySymbol["kind"], string>>> = {
+  variable: "variable",
+  "class-member": "member",
+  "type-member": "type member",
+};
+
+/**
+ * The type parameters of one member's declaring type that only the member names, which
+ * deleting the member leaves unused.
+ */
+function parametersOnlyNamedBy(
+  run: Run,
+  namedBy: ReadonlyMap<string, ReadonlySet<string>>,
+  member: InventorySymbol,
+): readonly string[] {
+  return [...run.symbols.values()]
+    .filter((symbol) => {
+      const from = namedBy.get(symbol.id);
+      return (
+        symbol.kind === "type-parameter" &&
+        symbol.parent === member.parent &&
+        from?.size === 1 &&
+        from.has(member.id)
+      );
+    })
+    .map((symbol) => symbol.name);
+}
+
+/** What one write-only finding says, the declarations its deletion takes with it included. */
+function writeOnlyMessage(
+  run: Run,
+  namedBy: ReadonlyMap<string, ReadonlySet<string>>,
+  symbol: InventorySymbol,
+  held: Uses,
+): string {
+  const writes = held.writes.length === 1 ? "once" : `at ${String(held.writes.length)} positions`;
+  const read = run.input.stores.readInTests.has(symbol.id)
+    ? "read only from test files"
+    : "never read";
+  const cascade = [
+    ...parametersOnlyNamedBy(run, namedBy, symbol).map((name) => `type parameter ${name}`),
+    ...[...held.alone].sort().map((name) => `import ${name}`),
+  ];
+  const word = SUBJECT_WORDS[symbol.kind] ?? "member";
+  const message = `${word} ${symbol.name} is written ${writes} and ${read}`;
+  return cascade.length === 0
+    ? message
+    : `${message}, and deleting it with its writes deletes ${cascade.join(" and ")} too`;
+}
+
 /**
- * `DS1301`: a module-level variable or a class member the counted references store into
- * and never read, named with every position written.
+ * `DS1301`: a module-level variable, a type member or a class member the counted
+ * references store into and never read, named with every position written.
  *
  * The subject is a live declaration: a store is a reference, so the sweep holds a
  * written one live and its candidates are never this kind's. Every reference that is
@@ -91,7 +144,7 @@ function writeOnlySymbols(run: Run): readonly Finding[] {
   for (const reference of stores.references) {
     let held = uses.get(reference.to);
     if (held === undefined) {
-      held = { writes: [], reads: 0 };
+      held = { writes: [], reads: 0, alone: new Set() };
       uses.set(reference.to, held);
     }
     // A consumer's store is written at a position no report of the target can name, so
@@ -100,6 +153,9 @@ function writeOnlySymbols(run: Run): readonly Finding[] {
       held.reads += 1;
       continue;
     }
+    for (const name of reference.alone ?? []) {
+      held.alone.add(name);
+    }
     const at = reference.position;
     const key = positionKey(at);
     if (!held.writes.some((written) => positionKey(written) === key)) {
@@ -107,6 +163,13 @@ function writeOnlySymbols(run: Run): readonly Finding[] {
     }
   }
 
+  const namedBy = new Map<string, Set<string>>();
+  for (const reference of stores.references) {
+    if (run.symbols.get(reference.to)?.kind === "type-parameter") {
+      namedBy.set(reference.to, (namedBy.get(reference.to) ?? new Set()).add(reference.from));
+    }
+  }
+
   const found: Finding[] = [];
   for (const symbol of matrix.union.symbols) {
     const held = uses.get(symbol.id);
@@ -120,10 +183,8 @@ function writeOnlySymbols(run: Run): readonly Finding[] {
     ) {
       continue;
     }
-    const writes = held.writes.length === 1 ? "once" : `at ${String(held.writes.length)} positions`;
-    const word = symbol.kind === "variable" ? "variable" : "member";
     found.push(
-      findingAbout(symbol, "DS1301", `${word} ${symbol.name} is written ${writes} and never read`, {
+      findingAbout(symbol, "DS1301", writeOnlyMessage(run, namedBy, symbol, held), {
         writePositions: held.writes,
       }),
     );

package/src/findings/unused-declarations.ts

@@ -142,6 +142,52 @@ function messageOf(code: string, judged: Judged): string {
   return `${subject} has no reference in the target`;
 }
 
+/**
+ * The members nothing writes or reads that are brands: each names a type parameter of
+ * its declaring type that no other part of the declaration names, other than another
+ * such member. They are what make two instantiations of the type distinct types, so
+ * deleting them would let one instantiation stand for another.
+ */
+function brandMembers(input: EmitterInput): ReadonlySet<string> {
+  const union = input.swept.matrix.union;
+  const unreferenced = new Map(
+    input.swept.sweep.candidates
+      .filter((candidate) => candidate.productionRefs + candidate.testRefs === 0)
+      .map((candidate) => [candidate.id, candidate]),
+  );
+  const namedBy = new Map<string, Set<string>>();
+  for (const reference of input.stores.references) {
+    const to = union.symbols[union.at(reference.to)];
+    if (to?.kind === "type-parameter") {
+      namedBy.set(to.id, (namedBy.get(to.id) ?? new Set()).add(reference.from));
+    }
+  }
+  const brands = new Set<string>();
+  for (const [parameter, from] of namedBy) {
+    const owner = union.symbols[union.at(parameter)]?.parent;
+    const members = [...from].map((id) => union.symbols[union.at(id)]);
+    if (
+      members.every(
+        (member) =>
+          member !== undefined &&
+          member.parent === owner &&
+          BRANDS.has(member.kind) &&
+          unreferenced.has(member.id),
+      )
+    ) {
+      for (const member of members) {
+        if (member !== undefined) {
+          brands.add(member.id);
+        }
+      }
+    }
+  }
+  return brands;
+}
+
+/** The kinds of member a brand is: a data member of a type or of a class. */
+const BRANDS: ReadonlySet<SymbolKind> = new Set(["type-member", "class-member"]);
+
 /** The findings of the unused-declarations family, `DS1000` to `DS1099`. */
 export const unusedDeclarations: Emitter = (input) => familyFindings(input, false);
 
@@ -157,6 +203,7 @@ function familyFindings(input: EmitterInput, fallen: boolean): Finding[] {
   const union = input.swept.matrix.union;
   const dead = new Set(input.swept.sweep.candidates.map((candidate) => candidate.id));
   const unreachable = unreachableExports(input);
+  let brands: ReadonlySet<string> | undefined;
 
   const found: Finding[] = [];
   for (const candidate of input.swept.sweep.candidates) {
@@ -179,7 +226,10 @@ function familyFindings(input: EmitterInput, fallen: boolean): Finding[] {
       unreachable: unreachable.has(symbol.id),
     };
     const code = codeOf(judged);
-    if (code === undefined) {
+    if (
+      code === undefined ||
+      (code === "DS1003" && (brands ??= brandMembers(input)).has(symbol.id))
+    ) {
       continue;
     }
     const endLine = Math.max(symbol.position.line, symbol.endLine);

package/src/generated-file.ts

@@ -0,0 +1,27 @@
+/**
+ * The generated-file class on TypeScript: every declaration in a file below a directory
+ * an applied convention row names as generated is retained, because the framework owns
+ * the file and a deletion there is undone at the next generation.
+ */
+
+import type { DetectorInput, Evidence } from "./exempt.ts";
+
+/** The generated-file detector, recording each file's first line. */
+export function generatedFile<Brand>(input: DetectorInput<Brand>): readonly Evidence[] {
+  const generated = input.generated;
+  if (generated === undefined || generated.size === 0) {
+    return [];
+  }
+  return input.held.symbols.flatMap((symbol): Evidence[] => {
+    const row = generated.get(symbol.position.path);
+    return symbol.kind === "file" || row === undefined
+      ? []
+      : [
+          {
+            id: symbol.id,
+            detail: `generated below a directory the convention row ${row} names`,
+            site: { path: symbol.position.path, line: 1, column: 1 },
+          },
+        ];
+  });
+}