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

package/src/test-support.ts

@@ -1,10 +1,13 @@
 /**
- * Test-support code: the files only tests reach. A test reaches each one through a chain
- * of references, and every reference to a declaration of one, an import for its effects
- * included, is written in a test file or in another such file, so it is judged with the
- * tests: what it references is referenced by test code.
+ * Test-support code: the files only tests reach that carry test evidence of their own. A
+ * test reaches each one through a chain of references, and every reference to a
+ * declaration of one, an import for its effects included, is written in a test file or in
+ * another such file, so it is judged with the tests: what it references is referenced by
+ * test code.
  */
 
+import { CONVENTION_ROWS } from "./convention-rows.ts";
+import { packageOfSpecifier } from "./dependencies.ts";
 import type { InventorySymbol } from "./inventory.ts";
 import type { Reference } from "./references.ts";
 import type { Root } from "./roots.ts";
@@ -12,18 +15,139 @@ import type { Root } from "./roots.ts";
 /** The root kind that never takes a file out of test-support code: the skip only withholds. */
 const SKIP_ROOT = "type-error";
 
+/**
+ * The test runners and test libraries an import of which is test evidence: each runner a
+ * convention row reads test files for, the platform's own runner, and the libraries below.
+ */
+const TEST_PACKAGES: ReadonlySet<string> = new Set([
+  ...CONVENTION_ROWS.filter((row) => row.testFiles !== undefined).map((row) => row.package),
+  "node:test",
+  "@playwright/test",
+]);
+
+/** The scopes every package of which is a test library. */
+const TEST_SCOPES = ["@testing-library/"] as const;
+
+/**
+ * The Node.js built-in modules a bare specifier names, which are no package. The set is
+ * closed: Node.js adds a new built-in under the `node:` scheme alone
+ * (https://nodejs.org/api/modules.html#built-in-modules-with-mandatory-node-prefix).
+ */
+const NODE_BUILTINS: ReadonlySet<string> = new Set([
+  "assert",
+  "async_hooks",
+  "buffer",
+  "child_process",
+  "cluster",
+  "console",
+  "constants",
+  "crypto",
+  "dgram",
+  "diagnostics_channel",
+  "dns",
+  "domain",
+  "events",
+  "fs",
+  "http",
+  "http2",
+  "https",
+  "inspector",
+  "module",
+  "net",
+  "os",
+  "path",
+  "perf_hooks",
+  "process",
+  "punycode",
+  "querystring",
+  "readline",
+  "repl",
+  "stream",
+  "string_decoder",
+  "sys",
+  "timers",
+  "tls",
+  "trace_events",
+  "tty",
+  "url",
+  "util",
+  "v8",
+  "vm",
+  "wasi",
+  "worker_threads",
+  "zlib",
+]);
+
+/** What a file imports, read for test evidence. */
+export interface TestEvidence {
+  /** Per file below the target root, the module specifiers its imports write. */
+  readonly imports: ReadonlyMap<string, readonly string[]>;
+  /**
+   * Whether the manifest nearest the file, below the target root, that declares the
+   * package declares it under `devDependencies`.
+   */
+  readonly devDependency: (path: string, name: string) => boolean;
+}
+
+/** Whether a specifier names a test runner or a test library. */
+function namesTestPackage(specifier: string): boolean {
+  const name = specifier.startsWith("node:") ? specifier : packageOfSpecifier(specifier);
+  return (
+    name !== undefined &&
+    (TEST_PACKAGES.has(name) || TEST_SCOPES.some((scope) => name.startsWith(scope)))
+  );
+}
+
+/**
+ * Whether a file carries test evidence: an import of a test runner or a test library, or
+ * package imports, Node built-ins aside, that are all devDependencies no file imports
+ * outside the test files and `onlyTests`, the files only tests reach.
+ */
+function evidenceReader(
+  tests: ReadonlySet<string>,
+  evidence: TestEvidence,
+): (onlyTests: ReadonlySet<string>, path: string) => boolean {
+  const importers = new Map<string, string[]>();
+  for (const [path, specifiers] of evidence.imports) {
+    for (const specifier of specifiers) {
+      const name = packageOfSpecifier(specifier);
+      if (name !== undefined) {
+        importers.set(name, [...(importers.get(name) ?? []), path]);
+      }
+    }
+  }
+  return (onlyTests, path) => {
+    const specifiers = evidence.imports.get(path) ?? [];
+    if (specifiers.some(namesTestPackage)) {
+      return true;
+    }
+    const names = specifiers.flatMap((one) => packageOfSpecifier(one) ?? []);
+    const packages = names.filter((name) => !NODE_BUILTINS.has(name));
+    return (
+      packages.length > 0 &&
+      packages.every(
+        (name) =>
+          evidence.devDependency(path, name) &&
+          (importers.get(name) ?? []).every((one) => tests.has(one) || onlyTests.has(one)),
+      )
+    );
+  };
+}
+
 /**
  * The files of one project that are test-support code, below the target root: the
  * largest set of files a test file reaches, none of them a test file or holding a root,
- * whose every user outside the set is a test file. A root has a caller outside the
- * reference graph: a runtime, a tool, a configuration, or a consumer of a library's
- * published API. `testFiles` are the files the test-file rules classified.
+ * each carrying test evidence of its own, whose every user outside the set is a test
+ * file. A root has a caller outside the reference graph: a runtime, a tool, a
+ * configuration, or a consumer of a library's published API. `testFiles` are the files
+ * the test-file rules classified.
  */
 export function testSupportFiles(
   symbols: readonly InventorySymbol[],
   references: readonly Reference[],
   roots: readonly Root[],
   testFiles: readonly string[],
+  evidence: TestEvidence,
 ): ReadonlySet<string> {
   const fileOf = new Map(symbols.map((symbol) => [symbol.id, symbol.position.path]));
   const users = new Map<string, Set<string>>();
@@ -59,17 +183,26 @@ export function testSupportFiles(
       }
     }
   }
-  const support = new Set([...reached].filter((path) => !rooted.has(path)));
-  for (let changed = true; changed;) {
-    changed = false;
-    for (const path of support) {
-      const from = users.get(path) ?? new Set<string>();
-      if (![...from].every((one) => tests.has(one) || support.has(one))) {
-        support.delete(path);
-        changed = true;
+  const withoutOutsideUsers = (files: Set<string>): Set<string> => {
+    for (let changed = true; changed;) {
+      changed = false;
+      for (const path of files) {
+        const from = users.get(path) ?? new Set<string>();
+        if (![...from].every((one) => tests.has(one) || files.has(one))) {
+          files.delete(path);
+          changed = true;
+        }
       }
     }
-  }
+    return files;
+  };
+  // Evidence reads the files only tests reach, evidence or none, so it is fixed before the
+  // files without evidence leave the set.
+  const onlyTests = withoutOutsideUsers(new Set([...reached].filter((path) => !rooted.has(path))));
+  const carries = evidenceReader(tests, evidence);
+  const support = withoutOutsideUsers(
+    new Set([...onlyTests].filter((path) => carries(onlyTests, path))),
+  );
   return support;
 }
 

package/src/type-errors.ts

@@ -8,6 +8,7 @@
 
 import {
   isClassDeclaration,
+  isFunctionLikeDeclaration,
   isNoSubstitutionTemplateLiteral,
   isPropertyAccessExpression,
   isStringLiteral,
@@ -25,6 +26,7 @@ import { isAnswered } from "./query.ts";
 import type { TypeErrorSkip } from "./report.ts";
 import type { Engine, ProjectView } from "./session.ts";
 import type { SetupFailure } from "./setup-failure.ts";
+import { findWorkspace, type Workspace } from "./workspace.ts";
 
 /** The compiler's codes for an import whose module it cannot find. */
 const MODULE_NOT_FOUND: ReadonlySet<number> = new Set([2307, 2792]);
@@ -78,6 +80,8 @@ interface ErrorContext {
   readonly targetRoot: string;
   /** The project configuration's `paths` mapping. */
   readonly paths: PathsMapping;
+  /** Whether one manifest is a workspace member's, whose dependencies the workspace installs. */
+  readonly member: (manifest: string) => boolean;
 }
 
 /** One configuration's `paths` mapping, its targets read against `base`. */
@@ -241,7 +245,11 @@ function expectedModule(
     name === undefined
       ? undefined
       : declaringManifest(host, dirnamePath(importer), targetRoot, name);
-  if (manifest === undefined) {
+  // No run requires a nested package that is no workspace member to be installed.
+  if (
+    manifest === undefined ||
+    (dirnamePath(manifest) !== targetRoot && !context.member(manifest))
+  ) {
     return undefined;
   }
   const where = relativePath(targetRoot, manifest) ?? manifest;
@@ -249,13 +257,27 @@ function expectedModule(
 }
 
 /**
- * The unit a type error at one offset skips: the class member holding it where a
- * top-level class does, else the top-level statement.
+ * The unit a type error at one offset skips: the innermost function holding it, else the
+ * class member holding it where a top-level class does, else the top-level statement.
  */
 function unitAt(file: SourceFile, offset: number): Node | undefined {
   const statement = file.statements.find((one) => one.pos <= offset && offset < one.end);
-  if (statement === undefined || !isClassDeclaration(statement)) {
-    return statement;
+  if (statement === undefined) {
+    return undefined;
+  }
+  let innermost: Node | undefined;
+  const visit = (node: Node): void => {
+    if (offset < node.getStart() || offset >= node.end) {
+      return;
+    }
+    if (isFunctionLikeDeclaration(node)) {
+      innermost = node;
+    }
+    node.forEachChild(visit);
+  };
+  visit(statement);
+  if (innermost !== undefined || !isClassDeclaration(statement)) {
+    return innermost ?? statement;
   }
   return statement.members.find((one) => one.pos <= offset && offset < one.end) ?? statement;
 }
@@ -274,8 +296,18 @@ function messageOf(text: string, targetRoot: string): string {
 export function readErrors<Brand>(
   project: ProjectView<Brand>,
   errors: readonly LocatedDiagnostic[],
-  context: ErrorContext,
+  where: Omit<ErrorContext, "member">,
 ): ProjectErrorReading {
+  let workspace: Workspace | undefined | null = null;
+  const context: ErrorContext = {
+    ...where,
+    member: (manifest) => {
+      if (workspace === null) {
+        workspace = findWorkspace(where.host, where.targetRoot, () => undefined);
+      }
+      return workspace?.memberOf(manifest) !== undefined;
+    },
+  };
   const files = new Map(project.ownSourceFiles().map((file) => [file.fileName, file]));
   const missing: SetupFailure[] = [];
   const skips: Skip[] = [];

package/src/type-parameter-reads.ts

@@ -0,0 +1,227 @@
+/**
+ * The members a read through a value typed by a type parameter reaches: `value.kind`,
+ * where `value` is of a type parameter `T` of a generic function, reads `kind` on each
+ * object type no class declares that a call of the function passes for `T`, because the
+ * call's value is what the read reads, whatever member of the constraint the name resolves
+ * to. A class's members a constraint requires are interface satisfaction's.
+ */
+
+import {
+  isBinaryExpression,
+  isCallExpression,
+  isIdentifier,
+  isNewExpression,
+  isPropertyAccessExpression,
+  isTypeParameterDeclaration,
+  SyntaxKind,
+  type CallExpression,
+  type NewExpression,
+  type Node,
+  type PropertyAccessExpression,
+  type SourceFile,
+} 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 { isAnswered } from "./query.ts";
+import type { Reference } from "./references.ts";
+import type { ProjectView } from "./session.ts";
+
+/** How deep a parameter's type is matched against the type a call passes: `readonly T[]` is one level. */
+const MATCH_DEPTH = 3;
+
+/** One read of a member through a value whose type is a type parameter. */
+interface Read {
+  readonly file: SourceFile;
+  readonly from: string;
+  readonly access: PropertyAccessExpression;
+}
+
+/** A node that declares parameters, as a generic function does. */
+type Generic = Node & {
+  readonly parameters?: readonly Node[];
+};
+
+/** The name a call reaches one generic by: its own, or that of what holds it. */
+function nameOf(generic: Generic): string | undefined {
+  const own = (generic as { readonly name?: Node }).name;
+  const holder = (generic.parent as { readonly name?: Node } | undefined)?.name;
+  const name = own ?? holder;
+  return name !== undefined && isIdentifier(name) ? name.text : undefined;
+}
+
+/** Whether a property access is the target of a plain assignment, which writes the member. */
+function assignedTo(access: PropertyAccessExpression): boolean {
+  const parent = access.parent;
+  return (
+    isBinaryExpression(parent) &&
+    parent.operatorToken.kind === SyntaxKind.EqualsToken &&
+    parent.left === access
+  );
+}
+
+/**
+ * The references the reads through type-parameter-typed values of one project's own files
+ * make to the members of the types its calls pass, each made by the declaration holding
+ * the read.
+ */
+export function typeParameterReads<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+  chains: AliasChains,
+  root: string,
+  testFiles: ReadonlySet<string>,
+): readonly Reference[] {
+  const queries = project.queries;
+  const reads: Read[] = [];
+  const calls: (CallExpression | NewExpression)[] = [];
+  for (const file of project.ownSourceFiles()) {
+    const fileId = held.declarations.get(nodeKey(file, file));
+    if (fileId === undefined) {
+      continue;
+    }
+    const visit = (node: Node, from: string, generic: boolean): void => {
+      const holder = held.declarations.get(nodeKey(file, node)) ?? from;
+      const inside =
+        generic ||
+        (node as { readonly typeParameters?: readonly Node[] }).typeParameters !== undefined;
+      if (
+        inside &&
+        isPropertyAccessExpression(node) &&
+        isIdentifier(node.name) &&
+        !assignedTo(node)
+      ) {
+        reads.push({ file, from: holder, access: node });
+      }
+      if (isCallExpression(node) || isNewExpression(node)) {
+        calls.push(node);
+      }
+      node.forEachChild((child) => {
+        visit(child, holder, inside);
+      });
+    };
+    file.forEachChild((child) => {
+      visit(child, fileId, false);
+    });
+  }
+  if (reads.length === 0) {
+    return [];
+  }
+
+  // The reads whose receiver the checker types as a type parameter, by the generic declaring it.
+  const receivers = queries.typesAt(reads.map((read) => read.access.expression));
+  const byGeneric = new Map<Generic, { read: Read; parameter: Type }[]>();
+  reads.forEach((read, at) => {
+    const type = receivers[at];
+    if (type === undefined || !isAnswered(type) || !type.isTypeParameter()) {
+      return;
+    }
+    const symbol = queries.symbolOfType(type);
+    const declaration =
+      symbol === undefined || !isAnswered(symbol)
+        ? undefined
+        : symbol.declarations
+            .map((handle) => project.declarationAt(handle)?.node)
+            .find((node) => node !== undefined && isTypeParameterDeclaration(node));
+    const generic = declaration?.parent as Generic | undefined;
+    if (generic !== undefined) {
+      byGeneric.set(generic, [...(byGeneric.get(generic) ?? []), { read, parameter: type }]);
+    }
+  });
+  if (byGeneric.size === 0) {
+    return [];
+  }
+
+  /** The types `instantiated` holds where `declared` holds `parameter`, matched part for part. */
+  const passedFor = (
+    parameter: Type,
+    declared: Type,
+    instantiated: Type,
+    depth: number,
+  ): readonly Type[] => {
+    if (declared.id === parameter.id) {
+      return [instantiated];
+    }
+    if (depth >= MATCH_DEPTH) {
+      return [];
+    }
+    const a = queries.typeArguments(declared);
+    const b = queries.typeArguments(instantiated);
+    if (!isAnswered(a) || !isAnswered(b) || a.length !== b.length) {
+      return [];
+    }
+    return a.flatMap((one, at) => {
+      const other = b[at];
+      return other === undefined ? [] : passedFor(parameter, one, other, depth + 1);
+    });
+  };
+
+  // Only a call spelling a generic's name is resolved: one request each.
+  const spelled = new Set([...byGeneric.keys()].flatMap((generic) => nameOf(generic) ?? []));
+  const found = new Map<string, Reference>();
+  for (const call of calls) {
+    const callee = call.expression;
+    const written = isIdentifier(callee)
+      ? callee.text
+      : isPropertyAccessExpression(callee) && isIdentifier(callee.name)
+        ? callee.name.text
+        : undefined;
+    if (written === undefined || !spelled.has(written)) {
+      continue;
+    }
+    const resolved = queries.resolvedSignature(call);
+    if (resolved === undefined || !isAnswered(resolved) || resolved.declaration === undefined) {
+      continue;
+    }
+    const generic = project.declarationAt(resolved.declaration)?.node as Generic | undefined;
+    const pending = generic === undefined ? undefined : byGeneric.get(generic);
+    const declared = pending === undefined ? undefined : queries.genericOf(resolved);
+    if (pending === undefined || declared === undefined || !isAnswered(declared)) {
+      continue;
+    }
+    const count = (generic?.parameters ?? []).length;
+    for (const { read, parameter } of pending) {
+      const passed: Type[] = [];
+      for (let at = 0; at < count; at += 1) {
+        const own = queries.parameterType(declared, at);
+        const given = queries.typeAtPosition(resolved, at);
+        if (own !== undefined && isAnswered(own) && isAnswered(given)) {
+          passed.push(...passedFor(parameter, own, given, 0));
+        }
+      }
+      const name = read.access.name.text;
+      const position = renderPosition(read.file, root, read.access.name.getStart());
+      for (const type of passed) {
+        const parts = type.isUnionType() ? queries.constituents(type) : [type];
+        for (const part of isAnswered(parts) ? parts : []) {
+          const owner = queries.symbolOfType(part);
+          if (
+            !isAnswered(owner) ||
+            owner === undefined ||
+            (owner.flags & SymbolFlags.Class) !== 0
+          ) {
+            continue;
+          }
+          const properties = queries.propertiesOf(part);
+          for (const property of isAnswered(properties) ? properties : []) {
+            if (property.name !== name) {
+              continue;
+            }
+            for (const to of chains.declarationsOf(property)) {
+              found.set(`${read.from}\u0000${to}\u0000${String(read.access.name.pos)}`, {
+                from: read.from,
+                to,
+                position,
+                use: "read",
+                resolution: "batch",
+                test: testFiles.has(position.path),
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+  return [...found.values()];
+}

package/src/verbs/analyze.ts

@@ -12,6 +12,7 @@ import { moduleIdentity } from "../consumers.ts";
 import { analyzerProvenance, verdictOf } from "../findings-pass.ts";
 import { joinPath, normalizePath, relativePath, resolvePath } from "../paths.ts";
 import type { Host } from "../host.ts";
+import type { ManifestEntry } from "../manifest.ts";
 import type { NotBuilt } from "../discover.ts";
 import { partialNotes } from "../partial.ts";
 import {
@@ -22,6 +23,7 @@ import {
   type Report,
   type ReportConfiguration,
   type ReportNotBuilt,
+  type ReportNote,
 } from "../report.ts";
 import { json } from "../reporters/json.ts";
 import { RENDERINGS } from "../reporters/reporters.ts";
@@ -92,6 +94,25 @@ function runRelative(invoked: string, path: string): string {
   return below;
 }
 
+/**
+ * One note per manifest entry the run reads back to no source file: what the entry names
+ * reaches nothing, so the findings its file would have rooted are reported.
+ */
+function unmappedNotes(
+  entries: readonly ManifestEntry[],
+  targetRoot: string,
+): readonly ReportNote[] {
+  return entries.map((entry) => {
+    const named = relativePath(targetRoot, entry.path) ?? entry.path;
+    return {
+      kind: "unmapped-entry",
+      path: relativePath(targetRoot, entry.dir) ?? ".",
+      key: "ts.entry_files",
+      message: `the manifest's ${entry.member} names ${named}, which reads back to no source file of the target: name the file it is built from in ts.entry_files`,
+    };
+  });
+}
+
 /** Each project the run dropped as a report names it, by its configuration file below the target. */
 function notBuiltOf(dropped: readonly NotBuilt[], targetRoot: string): readonly ReportNotBuilt[] {
   return dropped.map((one) => {
@@ -288,6 +309,7 @@ export const analyzeVerb: Verb = ({ err, host, inputs, scope, openClient, option
       typeErrorSkips: run.typeErrorSkips,
       unanswered: unansweredCounts(analysis),
       conventionsApplied: run.conventionsApplied,
+      notes: unmappedNotes(run.unmappedEntries, resolvePath(invoked, targetRoot)),
     });
     report = capFindings(sortFindings(built, config.reporters.sort), config.reporters.maxFindings);
     verdict = verdictOf(result, config);

package/src/verbs/explain.ts

@@ -315,12 +315,15 @@ function reported(found: CompletedFinding): string {
 /**
  * Every finding of the run that names the declaration by its reference and reports at
  * another position: a part of it, or a suppression record naming it. Each is published under
- * the reference asked about, so an explanation leaving it out would disagree with the report.
+ * the reference asked about, or a parameter's under one it starts, so an explanation leaving
+ * it out would disagree with the report.
  */
 function namedElsewhere(findings: readonly CompletedFinding[], subject: InventorySymbol): string {
   return findings
     .filter(
-      (found) => found.symbol.ref === subject.ref && positionKey(found.position) !== subject.id,
+      (found) =>
+        (found.symbol.holder ?? found.symbol.ref) === subject.ref &&
+        positionKey(found.position) !== subject.id,
     )
     .map(
       (found) =>

package/src/version.ts

@@ -4,4 +4,4 @@
  * independently of the analyzer's own version, which is the one the host answers
  * from the package the analyzer was installed from.
  */
-export const CONTRACT_VERSION = "7.2.0";
+export const CONTRACT_VERSION = "8.0.0";