@cplieger/deadset-ts 3.5.0 → 3.6.0

package/src/deprecation.ts

@@ -0,0 +1,101 @@
+/**
+ * Which declarations of one project carry the deprecation marker, the documentation tag
+ * the TypeScript tools recognize, as the checker reports a symbol's tags: gathered from
+ * every declaration of the symbol, so overloads, an accessor pair and a merged
+ * declaration share them. A declaration list's documentation covers every name it
+ * declares, and the checker attaches it to the first name alone, so the later names read
+ * the list's own tags from the tree.
+ */
+
+import { isVariableStatement, SyntaxKind, type Node } from "@typescript/native/unstable/ast";
+import type { Symbol as TSSymbol } from "@typescript/native/unstable/sync";
+import { nodeKey, type Inventory } from "./inventory.ts";
+import { DEFAULT_BATCH_CAP } from "./references.ts";
+import type { Handle, ProjectView } from "./session.ts";
+
+/** The tag the TypeScript tools recognize as marking a declaration deprecated. */
+const DEPRECATED_TAG = "deprecated";
+
+/** Whether one node's own documentation carries the deprecation tag. */
+function documentedDeprecated(node: Node): boolean {
+  const docs = (node as { readonly jsDoc?: readonly Node[] }).jsDoc ?? [];
+  return docs.some((doc) =>
+    ((doc as { readonly tags?: readonly Node[] }).tags ?? []).some(
+      (tag) => tag.kind === SyntaxKind.JSDocDeprecatedTag,
+    ),
+  );
+}
+
+/** The node a declaration's symbol is resolved at: its name, or itself where it has none. */
+function nameNode(node: Node): Node {
+  return (node as { readonly name?: Node }).name ?? node;
+}
+
+/**
+ * The identifiers of every declaration of one project that carries the deprecation
+ * marker, in the inventory's order.
+ *
+ * The checker is asked only for a symbol with a declaration in a file whose tree holds
+ * the tag, so a project whose files hold none costs no round trip, and one that does
+ * costs one batch per file and one request per symbol that could carry the tag.
+ */
+export function deprecatedDeclarations<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+): readonly string[] {
+  const marked = new Set<string>();
+  const markedPaths = new Set<string>();
+  const declared: { readonly id: string; readonly handle: Handle<Brand> }[][] = [];
+
+  for (const file of project.ownSourceFiles()) {
+    const named: { readonly id: string; readonly handle: Handle<Brand> }[] = [];
+    const visit = (node: Node): void => {
+      if (documentedDeprecated(node)) {
+        markedPaths.add(file.path);
+        if (isVariableStatement(node)) {
+          for (const declaration of node.declarationList.declarations) {
+            const id = held.declarations.get(nodeKey(file, declaration));
+            if (id !== undefined) {
+              marked.add(id);
+            }
+          }
+        }
+      }
+      const id = held.declarations.get(nodeKey(file, node));
+      if (id !== undefined && node !== file) {
+        named.push({ id, handle: project.handle(nameNode(node)) });
+      }
+      node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+    declared.push(named);
+  }
+
+  if (markedPaths.size > 0) {
+    const asked = new Map<number, boolean>();
+    const carriesTag = (symbol: TSSymbol): boolean => {
+      const known = asked.get(symbol.id);
+      if (known !== undefined) {
+        return known;
+      }
+      const carries =
+        symbol.declarations.some((declaration) => markedPaths.has(declaration.path)) &&
+        symbol.getJsDocTags(project.checker).some((tag) => tag.name === DEPRECATED_TAG);
+      asked.set(symbol.id, carries);
+      return carries;
+    };
+    for (const named of declared) {
+      for (let start = 0; start < named.length; start += DEFAULT_BATCH_CAP) {
+        const batch = named.slice(start, start + DEFAULT_BATCH_CAP);
+        project.symbolsAt(batch.map((one) => one.handle)).forEach((symbol, at) => {
+          const one = batch[at];
+          if (symbol !== undefined && one !== undefined && carriesTag(symbol)) {
+            marked.add(one.id);
+          }
+        });
+      }
+    }
+  }
+
+  return held.symbols.filter((symbol) => marked.has(symbol.id)).map((symbol) => symbol.id);
+}

package/src/discover.ts

@@ -7,7 +7,7 @@ import type { Scope } from "./scope.ts";
 import type { Engine } from "./session.ts";
 
 /** Directory names discovery does not descend into. */
-const IGNORED_DIRECTORIES: ReadonlySet<string> = new Set(["node_modules", ".git"]);
+export const IGNORED_DIRECTORIES: ReadonlySet<string> = new Set(["node_modules", ".git"]);
 
 /** A compiler configuration file discovery recognises under a root. */
 const CONFIG_FILE = /^tsconfig.*\.json$/u;

package/src/enum-group.ts

@@ -0,0 +1,265 @@
+/**
+ * The enum-group class: every member of an `enum` declaration is held back when a value
+ * of the enum arrives by conversion rather than by a member's name. The conversions are
+ * a type assertion from a number or a string, an element access on the enum object
+ * keyed by anything but literal text, and a decoded value typed as the enum: an `any`
+ * or `unknown` expression asserted to it, or bound to a variable or returned from a
+ * function it annotates, where a number counts too. An enum's own value converts nothing.
+ */
+
+import {
+  isArrowFunction,
+  isAsExpression,
+  isElementAccessExpression,
+  isEnumDeclaration,
+  isFunctionDeclaration,
+  isFunctionExpression,
+  isGetAccessorDeclaration,
+  isIdentifier,
+  isMethodDeclaration,
+  isNoSubstitutionTemplateLiteral,
+  isParenthesizedExpression,
+  isParenthesizedTypeNode,
+  isPropertyAccessExpression,
+  isReturnStatement,
+  isStringLiteral,
+  isVariableDeclaration,
+  SyntaxKind,
+  type Node,
+  type SourceFile,
+} from "@typescript/native/unstable/ast";
+import { TypeFlags, type Type } from "@typescript/native/unstable/sync";
+import { aliasChains } from "./alias-chain.ts";
+import type { DetectorInput, Evidence } from "./exempt.ts";
+import { nodeKey } from "./inventory.ts";
+import { renderPosition } from "./position.ts";
+import { DEFAULT_BATCH_CAP } from "./references.ts";
+
+/** The operand types a conversion produces an enum value from. */
+const NUMBER = TypeFlags.NumberLike;
+const STRING = TypeFlags.StringLike;
+const DECODED = TypeFlags.Any | TypeFlags.Unknown;
+
+/** How one site produces a value of the type it names. */
+type Form = "assertion" | "lookup" | "annotation";
+
+/** One place that may produce a value of an enum. */
+interface Site {
+  readonly form: Form;
+  /** The name node whose symbol says which declaration the site names. */
+  readonly name: Node;
+  /** The expression whose type decides the conversion, absent for a lookup. */
+  readonly operand: Node | undefined;
+  /** Where the evidence is recorded. */
+  readonly at: Node;
+}
+
+/** The expression one node is, through however many parentheses are written around it. */
+function unparenthesized(node: Node): Node {
+  let held = node;
+  while (isParenthesizedExpression(held)) {
+    held = held.expression;
+  }
+  return held;
+}
+
+/**
+ * The name node a type node names its declaration by: the identifier of a type
+ * reference, the right side of a qualified one, through parentheses. A type that is no
+ * reference names no declaration.
+ */
+function typeName(type: Node | undefined): Node | undefined {
+  let held = type;
+  while (held !== undefined && isParenthesizedTypeNode(held)) {
+    held = held.type;
+  }
+  if (held?.kind !== SyntaxKind.TypeReference) {
+    return undefined;
+  }
+  const name = (held as unknown as { readonly typeName: Node }).typeName;
+  if (name.kind === SyntaxKind.QualifiedName) {
+    return (name as unknown as { readonly right: Node }).right;
+  }
+  return name;
+}
+
+/** The name node an expression names an object by: an identifier, or a property access's name. */
+function objectName(expression: Node): Node | undefined {
+  const held = unparenthesized(expression);
+  if (isIdentifier(held)) {
+    return held;
+  }
+  return isPropertyAccessExpression(held) ? held.name : undefined;
+}
+
+/** The return type annotation of the function a return statement leaves, where it has one. */
+function returnTypeOf(statement: Node): Node | undefined {
+  for (let at = statement.parent; at.kind !== SyntaxKind.SourceFile; at = at.parent) {
+    if (
+      isFunctionDeclaration(at) ||
+      isMethodDeclaration(at) ||
+      isFunctionExpression(at) ||
+      isArrowFunction(at) ||
+      isGetAccessorDeclaration(at)
+    ) {
+      return at.type;
+    }
+  }
+  return undefined;
+}
+
+/** Every site of one file that may produce a value of a type it names, in source order. */
+function sitesOf(file: SourceFile): readonly Site[] {
+  const found: Site[] = [];
+  const annotated = (type: Node | undefined, value: Node | undefined, at: Node): void => {
+    const name = typeName(type);
+    if (name !== undefined && value !== undefined) {
+      found.push({ form: "annotation", name, operand: value, at });
+    }
+  };
+  const visit = (node: Node): void => {
+    if (isAsExpression(node) || node.kind === SyntaxKind.TypeAssertionExpression) {
+      const assertion = node as unknown as { readonly type: Node; readonly expression: Node };
+      const name = typeName(assertion.type);
+      if (name !== undefined) {
+        found.push({ form: "assertion", name, operand: assertion.expression, at: node });
+      }
+    } else if (isElementAccessExpression(node)) {
+      const key = node.argumentExpression;
+      const name = objectName(node.expression);
+      if (name !== undefined && !isStringLiteral(key) && !isNoSubstitutionTemplateLiteral(key)) {
+        found.push({ form: "lookup", name, operand: undefined, at: node });
+      }
+    } else if (isVariableDeclaration(node)) {
+      annotated(node.type, node.initializer, node.initializer ?? node);
+    } else if (isReturnStatement(node) && node.expression !== undefined) {
+      annotated(returnTypeOf(node), node.expression, node.expression);
+    }
+    node.forEachChild(visit);
+  };
+  file.forEachChild(visit);
+  return found;
+}
+
+/**
+ * The parts of one type that are not values of an enum: its constituents where it is a
+ * union, and itself otherwise. An enum's own value, or one of its members, is a value the
+ * source names, whichever number or string it also is.
+ */
+function partsOf(type: Type): readonly Type[] {
+  const parts = type.isUnionType() ? type.getTypes() : [type];
+  return parts.filter((part) => (part.flags & TypeFlags.EnumLike) === 0);
+}
+
+/**
+ * The detail one site records about the enum it produces, or undefined where the
+ * operand's type converts nothing: a number, or a string an assertion converts, is
+ * converted, a value of type `any` or `unknown` is decoded, and a value of an enum is one
+ * the source names.
+ */
+function detailOf(site: Site, enumName: string, operand: Type | undefined): string | undefined {
+  if (site.form === "lookup") {
+    return `looked up by an element access on ${enumName}`;
+  }
+  if (operand === undefined) {
+    return undefined;
+  }
+  const parts = partsOf(operand);
+  if (parts.some((part) => (part.flags & NUMBER) !== 0)) {
+    return "converted from number";
+  }
+  if (parts.some((part) => (part.flags & STRING) !== 0)) {
+    return site.form === "assertion" ? "converted from string" : undefined;
+  }
+  if (parts.some((part) => (part.flags & DECODED) !== 0)) {
+    return `decoded as ${enumName}`;
+  }
+  return undefined;
+}
+
+/**
+ * The enum-group detector: every member of each enum declaration of the target that a
+ * conversion produces a value of, recorded at each conversion.
+ */
+export function enumGroup<Brand>(input: DetectorInput<Brand>): readonly Evidence[] {
+  const { project, held, targetRoot } = input;
+  const files = project.ownSourceFiles();
+
+  // The enums of the target, by the identifier of their declaration, with their names.
+  const enums = new Map<string, string>();
+  for (const file of files) {
+    const visit = (node: Node): void => {
+      if (isEnumDeclaration(node)) {
+        const id = held.declarations.get(nodeKey(file, node));
+        if (id !== undefined) {
+          enums.set(id, node.name.getText());
+        }
+      }
+      node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+  }
+  if (enums.size === 0) {
+    return [];
+  }
+
+  const sites = files.flatMap(sitesOf);
+  const named = new Map<Site, string>();
+  const chains = aliasChains(project, held);
+  for (let from = 0; from < sites.length; from += DEFAULT_BATCH_CAP) {
+    const run = sites.slice(from, from + DEFAULT_BATCH_CAP);
+    project.symbolsAt(run.map((site) => project.handle(site.name))).forEach((symbol, index) => {
+      const site = run[index];
+      if (symbol === undefined || site === undefined) {
+        return;
+      }
+      const target = chains.chainOf(symbol).find((link) => enums.has(link.id));
+      if (target !== undefined) {
+        named.set(site, target.id);
+      }
+    });
+  }
+
+  const typed = sites.filter((site) => named.has(site) && site.operand !== undefined);
+  const operandType = new Map<Site, Type>();
+  for (let from = 0; from < typed.length; from += DEFAULT_BATCH_CAP) {
+    const run = typed.slice(from, from + DEFAULT_BATCH_CAP);
+    project.checker
+      .getTypeAtLocation(run.map((site) => site.operand ?? site.at))
+      .forEach((type, index) => {
+        const site = run[index];
+        if (type !== undefined && site !== undefined) {
+          operandType.set(site, type);
+        }
+      });
+  }
+
+  const members = new Map<string, string[]>();
+  for (const symbol of held.symbols) {
+    if (symbol.kind === "enum-member" && enums.has(symbol.parent)) {
+      const listed = members.get(symbol.parent);
+      if (listed === undefined) {
+        members.set(symbol.parent, [symbol.id]);
+      } else {
+        listed.push(symbol.id);
+      }
+    }
+  }
+
+  const found: Evidence[] = [];
+  for (const site of sites) {
+    const enumId = named.get(site);
+    if (enumId === undefined) {
+      continue;
+    }
+    const detail = detailOf(site, enums.get(enumId) ?? "", operandType.get(site));
+    if (detail === undefined) {
+      continue;
+    }
+    const position = renderPosition(site.at.getSourceFile(), targetRoot, site.at.getStart());
+    for (const id of members.get(enumId) ?? []) {
+      found.push({ id, detail, site: position });
+    }
+  }
+  return found;
+}

package/src/file-facts.ts

@@ -0,0 +1,143 @@
+/**
+ * What the file kinds read about the target's files beside the sweep: every source
+ * file below the target root, whether or not a project includes it, and the files a
+ * program holds by inclusion rather than by an import.
+ */
+
+import type { SourceFile } from "@typescript/native/unstable/ast";
+import { IGNORED_DIRECTORIES } from "./discover.ts";
+import type { Host } from "./host.ts";
+import { packageScope } from "./inventory.ts";
+import { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.ts";
+import { renderRef } from "./ref.ts";
+import type { ProjectView } from "./session.ts";
+
+/** A file name the compiler reads as a source file. */
+const SOURCE_FILE = /\.(?:ts|tsx|mts|cts)$/u;
+
+/** A file name the compiler reads as a declaration file, which no build emits code from. */
+const DECLARATION_FILE = /\.d\.(?:[^./]+\.)?[mc]?ts$/u;
+
+/** A line break as the compiler counts lines. */
+const LINE_BREAK = /\r\n|[\n\r\u2028\u2029]/gu;
+
+/** One source file below the target root. */
+export interface TreeFile {
+  /** The path below the target root, with the solidus as separator. */
+  readonly path: string;
+  /** The stable reference of the file's module. */
+  readonly ref: string;
+  /** The line of the file's last character, counted from one. */
+  readonly endLine: number;
+}
+
+/** The target's files, as the file kinds read them. */
+export interface FileFacts {
+  /**
+   * Every source file below the target root a compiler configuration can include, in
+   * path order: a source extension, not a declaration file, and not below a directory
+   * discovery skips.
+   */
+  readonly tree: readonly TreeFile[];
+  /**
+   * The paths below the target root of the files a program holds by inclusion rather
+   * than by an import. A file that carries a triple-slash directive, augments a module
+   * or the global scope, or declares an ambient module changes what every file of the
+   * program sees for as long as the program includes it, and a file a triple-slash path
+   * reference names is included by the file that names it.
+   */
+  readonly heldByInclusion: ReadonlySet<string>;
+}
+
+/** The line of the last character of one text, counted from one; an empty text is one line. */
+function lastLine(text: string): number {
+  const last = Math.max(text.length - 1, 0);
+  let line = 1;
+  for (const found of text.matchAll(LINE_BREAK)) {
+    if (found.index + found[0].length > last) {
+      break;
+    }
+    line += 1;
+  }
+  return line;
+}
+
+/**
+ * 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.
+ */
+export function sourceTree(host: Host, targetRoot: string): readonly TreeFile[] {
+  const scopeOf = packageScope(host, targetRoot);
+  const found: TreeFile[] = [];
+  const pending = [""];
+  for (let dir = pending.pop(); dir !== undefined; dir = pending.pop()) {
+    let entries: readonly { readonly name: string; readonly directory: boolean }[];
+    try {
+      entries = host.readDirectory(joinPath(targetRoot, dir));
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const path = dir === "" ? entry.name : `${dir}/${entry.name}`;
+      if (entry.directory) {
+        if (!IGNORED_DIRECTORIES.has(entry.name)) {
+          pending.push(path);
+        }
+        continue;
+      }
+      if (!SOURCE_FILE.test(entry.name) || DECLARATION_FILE.test(entry.name)) {
+        continue;
+      }
+      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));
+}
+
+/** Whether one file changes what the program sees by being included in it. */
+function actsByInclusion(file: SourceFile): boolean {
+  return (
+    file.referencedFiles.length > 0 ||
+    file.typeReferenceDirectives.length > 0 ||
+    file.libReferenceDirectives.length > 0 ||
+    file.moduleAugmentations.length > 0 ||
+    file.ambientModuleNames.length > 0
+  );
+}
+
+/**
+ * The paths below the target root of one project's own files the program holds by
+ * inclusion, in the order the program holds them, each once.
+ */
+export function heldByInclusion<Brand>(
+  project: ProjectView<Brand>,
+  targetRoot: string,
+): readonly string[] {
+  const held = new Set<string>();
+  const add = (fileName: string): void => {
+    const path = relativePath(targetRoot, fileName);
+    if (path !== undefined) {
+      held.add(path);
+    }
+  };
+  for (const file of project.ownSourceFiles()) {
+    if (actsByInclusion(file)) {
+      add(file.fileName);
+    }
+    for (const reference of file.referencedFiles) {
+      add(resolvePath(dirnamePath(file.fileName), reference.fileName));
+    }
+  }
+  return [...held];
+}

package/src/findings/boundary.ts

@@ -0,0 +1,39 @@
+import type { Finding } from "../finding.ts";
+
+/** Which side of a declared cross-language edge, as the edges document spells it. */
+export type EdgeSideName = "provides" | "used_by";
+
+/** One side of a declared cross-language edge that names a symbol of this analyzer's language. */
+export interface EdgeSide {
+  /** The edge's identifier, as the edges document spells it. */
+  readonly edge: string;
+  readonly side: EdgeSideName;
+  /** The stable symbol reference the side names. */
+  readonly symbol: string;
+}
+
+/**
+ * One finding a declared edge holds back: the finding the analyzer would report about
+ * the symbol one side of the edge names, which a report carries only inside that side's
+ * evaluation, because the code that may use the symbol is in the other language.
+ */
+export interface PendingFinding extends EdgeSide {
+  readonly finding: Finding;
+}
+
+/** What the run knows about the code outside the target that can reach its declarations. */
+export interface Boundary {
+  readonly consumers: {
+    /** The identifier of every consumer the scope declares. */
+    readonly declared: readonly string[];
+    /** The identifier of every declared consumer the run loaded. */
+    readonly loaded: readonly string[];
+  };
+  /**
+   * Whether the target's manifest declares `exports`, so code outside the target can
+   * import no file the manifest does not name.
+   */
+  readonly encapsulated: boolean;
+  /** Every side of a declared cross-language edge that names a symbol of this language. */
+  readonly edges: readonly EdgeSide[];
+}