@cplieger/deadset-ts 5.0.0 → 5.1.1

package/src/conventions.ts

@@ -22,6 +22,8 @@ import {
   isNamespaceImport,
   isNoSubstitutionTemplateLiteral,
   isNonNullExpression,
+  isNumericLiteral,
+  isObjectBindingPattern,
   isObjectLiteralExpression,
   isParenthesizedExpression,
   isPropertyAccessExpression,
@@ -33,7 +35,9 @@ import {
   isVariableStatement,
   SyntaxKind,
   type AsExpression,
+  type Identifier,
   type Node,
+  type ObjectBindingPattern,
   type NonNullExpression,
   type ObjectLiteralExpression,
   type ParenthesizedExpression,
@@ -81,6 +85,14 @@ interface ConventionGlob {
   readonly excludes: readonly RegExp[];
 }
 
+/** One directory an applied row names as generated, read against its manifest's directory. */
+interface GeneratedDirectory {
+  readonly dir: string;
+  readonly row: string;
+  /** The directory below the manifest's directory, `/`-separated. */
+  readonly below: string;
+}
+
 /** A setup failure a row met, at the directory of the manifest that declared it. */
 interface ConventionFailure {
   readonly dir: string;
@@ -92,6 +104,7 @@ export interface Conventions {
   /** The rows applied, ordered by name, then manifest, then their compact encoding. */
   readonly applied: readonly AppliedConvention[];
   readonly globs: readonly ConventionGlob[];
+  readonly generated: readonly GeneratedDirectory[];
   readonly failures: readonly ConventionFailure[];
 }
 
@@ -105,9 +118,11 @@ interface ConventionEntry {
 /** Parses one file's text with no program. */
 type ParseSource = (fileName: string, text: string) => SourceFile;
 
+/** The sections an installed package is required by, so its absence fails the run. */
+const REQUIRED_SECTIONS = ["dependencies", "devDependencies"] as const;
+
 const DEPENDENCY_SECTIONS = [
-  "dependencies",
-  "devDependencies",
+  ...REQUIRED_SECTIONS,
   "peerDependencies",
   "optionalDependencies",
 ] as const;
@@ -124,11 +139,15 @@ function readJSON(host: Host, path: string): unknown {
   }
 }
 
-function declares(manifest: unknown, name: string): boolean {
+function declares(
+  manifest: unknown,
+  name: string,
+  sections: readonly string[] = DEPENDENCY_SECTIONS,
+): boolean {
   if (!isRecord(manifest)) {
     return false;
   }
-  return DEPENDENCY_SECTIONS.some((section) => {
+  return sections.some((section) => {
     const held = manifest[section];
     return isRecord(held) && Object.hasOwn(held, name);
   });
@@ -174,21 +193,33 @@ function unwrapped(node: Node): Node {
   return at;
 }
 
-/** The key one property is written with, where it is written as a name or a literal. */
+/** The key one property is written with, where it is written as a name or as literal text. */
 function keyOf(property: Node): string | undefined {
   if (!isPropertyAssignment(property) && !isShorthandPropertyAssignment(property)) {
     return undefined;
   }
   const { name } = property;
-  if (isComputedPropertyName(name)) {
-    return undefined;
-  }
-  if (isIdentifier(name) || isStringLiteral(name) || isNoSubstitutionTemplateLiteral(name)) {
-    return name.text;
+  const key = isComputedPropertyName(name) ? name.expression : name;
+  if (
+    (isIdentifier(key) && key === name) ||
+    isStringLiteral(key) ||
+    isNoSubstitutionTemplateLiteral(key)
+  ) {
+    return key.text;
   }
   return undefined;
 }
 
+/** Whether one member's computed name is no literal, so it may set any key. */
+function computesKey(member: Node): boolean {
+  const name = (member as { readonly name?: Node }).name;
+  if (name === undefined || !isComputedPropertyName(name)) {
+    return false;
+  }
+  const key = name.expression;
+  return !(isStringLiteral(key) || isNumericLiteral(key) || isNoSubstitutionTemplateLiteral(key));
+}
+
 /** The values one file's top-level variable declarations bind, by name. */
 function declaredValues(file: SourceFile): ReadonlyMap<string, Node> {
   const values = new Map<string, Node>();
@@ -247,6 +278,79 @@ function defaultExports(file: SourceFile): readonly Node[] {
   return found;
 }
 
+/** The declarations whose name is a binding of the scope they are written in. */
+const BINDING_KINDS: ReadonlySet<SyntaxKind> = new Set([
+  SyntaxKind.VariableDeclaration,
+  SyntaxKind.Parameter,
+  SyntaxKind.BindingElement,
+  SyntaxKind.FunctionDeclaration,
+  SyntaxKind.ClassDeclaration,
+  SyntaxKind.ImportClause,
+  SyntaxKind.ImportSpecifier,
+  SyntaxKind.NamespaceImport,
+  SyntaxKind.ImportEqualsDeclaration,
+]);
+
+/** Whether one file declares a binding named `require` at any depth, which shadows the global. */
+function declaresRequire(file: SourceFile): boolean {
+  let found = false;
+  const visit = (node: Node): void => {
+    const name = (node as { readonly name?: Node }).name;
+    if (
+      name !== undefined &&
+      isIdentifier(name) &&
+      name.text === "require" &&
+      BINDING_KINDS.has(node.kind)
+    ) {
+      found = true;
+    }
+    if (!found) {
+      node.forEachChild(visit);
+    }
+  };
+  file.forEachChild(visit);
+  return found;
+}
+
+/**
+ * The top-level `const`, `let` and `var` declarations that bind a `require` of one module,
+ * written with the module's name as its one string-literal argument, in a file that
+ * declares no binding named `require`: each binds as an import of the module does.
+ */
+function requireBindings(
+  file: SourceFile,
+  module: string,
+): readonly (Identifier | ObjectBindingPattern)[] {
+  const found: (Identifier | ObjectBindingPattern)[] = [];
+  for (const statement of file.statements) {
+    if (!isVariableStatement(statement)) {
+      continue;
+    }
+    for (const declaration of statement.declarationList.declarations) {
+      const value =
+        declaration.initializer === undefined ? undefined : unwrapped(declaration.initializer);
+      const [argument, ...rest] =
+        value !== undefined && isCallExpression(value) ? value.arguments : [];
+      if (
+        value === undefined ||
+        !isCallExpression(value) ||
+        !isIdentifier(value.expression) ||
+        value.expression.text !== "require" ||
+        argument === undefined ||
+        rest.length > 0 ||
+        !isStringLiteral(argument) ||
+        argument.text !== module
+      ) {
+        continue;
+      }
+      if (isIdentifier(declaration.name) || isObjectBindingPattern(declaration.name)) {
+        found.push(declaration.name);
+      }
+    }
+  }
+  return found.length > 0 && declaresRequire(file) ? [] : found;
+}
+
 /**
  * The first argument of every call one file makes to one module's export, through a
  * named or a namespace import; `undefined` for a call with no argument.
@@ -254,6 +358,26 @@ function defaultExports(file: SourceFile): readonly Node[] {
 function optionsArguments(file: SourceFile, call: OptionsCall): readonly (Node | undefined)[] {
   const names = new Set<string>();
   const namespaces = new Set<string>();
+  for (const name of requireBindings(file, call.module)) {
+    if (isIdentifier(name)) {
+      namespaces.add(name.text);
+      continue;
+    }
+    for (const element of name.elements) {
+      const local = element.name;
+      const exported = element.propertyName ?? local;
+      if (
+        element.dotDotDotToken === undefined &&
+        local !== undefined &&
+        isIdentifier(local) &&
+        exported !== undefined &&
+        (isIdentifier(exported) || isStringLiteral(exported)) &&
+        exported.text === call.export
+      ) {
+        names.add(local.text);
+      }
+    }
+  }
   for (const statement of file.statements) {
     const bindings = isImportDeclaration(statement)
       ? statement.importClause?.namedBindings
@@ -333,7 +457,7 @@ function readPath(
 ): Node | undefined {
   const [key, ...rest] = keys;
   for (const member of object.properties) {
-    if (isSpreadAssignment(member)) {
+    if (isSpreadAssignment(member) || computesKey(member)) {
       return member;
     }
     if (keyOf(member) !== key) {
@@ -518,6 +642,7 @@ export function readConventions(
 ): Conventions {
   const applied: AppliedConvention[] = [];
   const globs: ConventionGlob[] = [];
+  const generated: GeneratedDirectory[] = [];
   const failures: ConventionFailure[] = [];
   for (const manifest of manifests) {
     const declared = readJSON(host, joinPath(manifest.dir, "package.json"));
@@ -532,7 +657,7 @@ export function readConventions(
       }
       const version = versions.get(row.package);
       if (version === undefined) {
-        if (missing.has(row.package)) {
+        if (missing.has(row.package) || !declares(declared, row.package, REQUIRED_SECTIONS)) {
           continue;
         }
         missing.add(row.package);
@@ -580,6 +705,9 @@ export function readConventions(
       const excludes = [
         ...new Set((row.excludes ?? []).flatMap((one) => expand(one, resolved))),
       ].map(globExpression);
+      for (const below of new Set((row.generated ?? []).flatMap((one) => expand(one, resolved)))) {
+        generated.push({ dir: manifest.dir, row: row.name, below });
+      }
       for (const glob of new Set(row.entries.flatMap((entry) => expand(entry, resolved)))) {
         globs.push({
           dir: manifest.dir,
@@ -597,7 +725,27 @@ export function readConventions(
       compare(a.manifest, b.manifest) ||
       compare(JSON.stringify(a), JSON.stringify(b)),
   );
-  return { applied: unique, globs, failures };
+  return { applied: unique, globs, generated, failures };
+}
+
+/**
+ * Every own file of one project below a directory an applied row names as generated, by
+ * its path below the target root, with the name of the first such row.
+ */
+export function generatedFiles(
+  conventions: Conventions,
+  files: SourceFiles,
+): ReadonlyMap<string, string> {
+  const found = new Map<string, string>();
+  for (const { dir, row, below } of conventions.generated) {
+    const root = joinPath(dir, below);
+    for (const [path, file] of files.byPath) {
+      if (!found.has(path) && relativePath(root, file.fileName) !== undefined) {
+        found.set(path, row);
+      }
+    }
+  }
+  return found;
 }
 
 /** Every own file of one project an applied row's globs match, once per row. */

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>;
 }
 
 /**
@@ -161,12 +166,44 @@ export function computeExemptions<Brand>(
   input: DetectorInput<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 {
+  return heldRecords(evidenceRecords(input, detectors, holding.disabled), holding);
+}
+
+/**
+ * Every record one project's detectors found, one per piece of evidence, before the
+ * mode decides which of them hold: what {@link heldRecords} reads.
+ */
+export function evidenceRecords<Brand>(
+  input: DetectorInput<Brand>,
+  detectors: Detectors,
+  disabled: ReadonlySet<ExemptionClass>,
 ): readonly Exemption[] {
   const visibility = new Map(input.held.symbols.map((symbol) => [symbol.id, symbol.visibility]));
   const found: Exemption[] = [];
   for (const exemptionClass of TS_EXEMPTION_CLASSES) {
     const detect = detectors.get(exemptionClass);
-    if (detect === undefined || holding.disabled.has(exemptionClass)) {
+    if (detect === undefined || disabled.has(exemptionClass)) {
       continue;
     }
     const allowed = typescriptVisibilityOf(exemptionClass);
@@ -174,9 +211,6 @@ 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({
         id: evidence.id,
         class: exemptionClass,
@@ -186,7 +220,21 @@ export function computeExemptions<Brand>(
       });
     }
   }
-  return exemptionsOf(found);
+  return found;
+}
+
+/** The records that hold under one mode, beside the evidence a production mode found in a test file. */
+export function heldRecords(records: readonly Exemption[], holding: Holding): Detected {
+  const found: Exemption[] = [];
+  const inTestFiles: Exemption[] = [];
+  for (const record of records) {
+    if (holding.mode.production && holding.testFiles.has(record.site.path)) {
+      inTestFiles.push(record);
+    } else {
+      found.push(record);
+    }
+  }
+  return { records: exemptionsOf(found), inTestFiles };
 }
 
 /** Two strings ordered bytewise. */
@@ -247,17 +295,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 +317,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. */
@@ -63,13 +65,11 @@ function lastLine(text: string): number {
 }
 
 /**
- * Every source file below the target root, in path order. A directory that cannot be
- * read is skipped, as discovery skips it, and a file that cannot be read is skipped
- * with it: a tree the analysis may not enter holds no file it can report.
+ * The path below the target root of every source file there, in path order. A directory
+ * that cannot be read is skipped, as discovery skips it.
  */
-export function sourceTree(host: Host, targetRoot: string): readonly TreeFile[] {
-  const scopeOf = packageScope(host, targetRoot);
-  const found: TreeFile[] = [];
+export function sourcePaths(host: Host, targetRoot: string): readonly string[] {
+  const found: string[] = [];
   const pending = [""];
   for (let dir = pending.pop(); dir !== undefined; dir = pending.pop()) {
     let entries: readonly { readonly name: string; readonly directory: boolean }[];
@@ -86,23 +86,29 @@ export function sourceTree(host: Host, targetRoot: string): readonly TreeFile[]
         }
         continue;
       }
-      if (!SOURCE_FILE.test(entry.name) || DECLARATION_FILE.test(entry.name)) {
-        continue;
+      if (SOURCE_FILE.test(entry.name) && !DECLARATION_FILE.test(entry.name)) {
+        found.push(path);
       }
-      let text: string;
-      try {
-        text = host.readFile(joinPath(targetRoot, path));
-      } catch {
-        continue;
-      }
-      found.push({
-        path,
-        ref: renderRef(scopeOf(path), { of: "module" }),
-        endLine: lastLine(text),
-      });
     }
   }
-  return found.sort((a, b) => (a.path < b.path ? -1 : 1));
+  return found.sort((a, b) => (a < b ? -1 : 1));
+}
+
+/**
+ * Every source file below the target root, in path order. A file that cannot be read is
+ * skipped: a tree the analysis may not enter holds no file it can report.
+ */
+export function sourceTree(host: Host, targetRoot: string): readonly TreeFile[] {
+  const scopeOf = packageScope(host, targetRoot);
+  return sourcePaths(host, targetRoot).flatMap((path) => {
+    let text: string;
+    try {
+      text = host.readFile(joinPath(targetRoot, path));
+    } catch {
+      return [];
+    }
+    return [{ path, ref: renderRef(scopeOf(path), { of: "module" }), endLine: lastLine(text) }];
+  });
 }
 
 /** Whether one file changes what the program sees by being included in it. */