@cplieger/deadset-ts 8.0.0-dev.15 → 8.0.0-dev.17

package/src/platform-calls.ts

@@ -0,0 +1,119 @@
+/**
+ * Which calls are the platform's `require` or AMD's `define` and which constructions its `URL`
+ * (roots.23, references-ts.37, references-ts.1), decided once over the bindings of the names a callee is written with: the
+ * checker's in a program, the file's own scopes in a module read outside every program.
+ */
+
+import {
+  isBindingElement,
+  isCallExpression,
+  isExportSpecifier,
+  isIdentifier,
+  isImportSpecifier,
+  isPropertyAccessExpression,
+  isStringLiteral,
+  isVariableDeclaration,
+  type Identifier,
+  type Node,
+} from "@typescript/native/ast";
+import { parenthesesRemoved, unwrapped } from "./unwrap.ts";
+
+/** A name of the platform the analysis reads calls of. */
+type PlatformName = "require" | "createRequire" | "define" | "URL";
+
+/** What one written name is bound to, as far as its reader can tell. */
+export interface Bound {
+  /** Its own name, and each one an import, a re-export or a destructuring carries it by. */
+  readonly names: ReadonlySet<string>;
+  /** The declarations of the target it resolves to, a variable's initializer read through. */
+  readonly own: readonly Node[];
+  /** Whether the type checker proves it the target's own, a function or a class it writes with a body. */
+  readonly provenOwn: boolean;
+}
+
+/** The binding of each written name, `undefined` where nothing answers which declaration it names. */
+export type BindingOf = (written: Identifier) => Bound | undefined;
+
+/** The name one declaration carries a binding by beside its own: the export an import or a re-export names, or the property a destructuring reads. */
+export function carriedNames(node: Node): readonly string[] {
+  if (isImportSpecifier(node) || isExportSpecifier(node)) {
+    return [(node.propertyName ?? node.name).text];
+  }
+  const property = isBindingElement(node) ? node.propertyName : undefined;
+  return property !== undefined && (isIdentifier(property) || isStringLiteral(property))
+    ? [property.text]
+    : [];
+}
+
+/**
+ * A written name's binding as a file states it, with no checker to ask, so nothing is
+ * proven the target's own (conventions.3): `declarationOf` names the declaration a name
+ * resolves to, and a property is read by how it is written alone.
+ */
+export function lexicalBinding(
+  declarationOf: (written: Identifier) => Node | undefined,
+): BindingOf {
+  return (written) => {
+    const parent = written.parent;
+    if (isPropertyAccessExpression(parent) && parent.name === written) {
+      return undefined;
+    }
+    const declaration = declarationOf(written);
+    return {
+      names: new Set([
+        written.text,
+        ...(declaration === undefined ? [] : carriedNames(declaration)),
+      ]),
+      own: declaration === undefined ? [] : [declaration],
+      provenOwn: false,
+    };
+  };
+}
+
+/** The name a callee or a constructor is written with, parentheses removed: an identifier or a property name. */
+export function writtenName(expression: Node): Identifier | undefined {
+  const at = parenthesesRemoved(expression);
+  if (isIdentifier(at)) {
+    return at;
+  }
+  return isPropertyAccessExpression(at) && isIdentifier(at.name) ? at.name : undefined;
+}
+
+/**
+ * Whether a call or construction through `callee` is one of the platform's `name`: never
+ * where its binding is proven the target's own; otherwise where it is written or carried
+ * by that name, or resolves to a variable of the target whose initializer is such a
+ * callee or, for `require`, a call of a `createRequire`. A callee nothing binds is read by
+ * how it is written.
+ */
+export function callsPlatformBy(
+  name: PlatformName,
+  callee: Identifier,
+  bindingOf: BindingOf,
+  seen = new Set<Node>(),
+): boolean {
+  const bound = bindingOf(callee);
+  if (bound?.provenOwn === true) {
+    return false;
+  }
+  if (callee.text === name || bound?.names.has(name) === true) {
+    return true;
+  }
+  return (bound?.own ?? []).some((node) => {
+    if (seen.has(node) || !isVariableDeclaration(node) || node.initializer === undefined) {
+      return false;
+    }
+    seen.add(node);
+    const value = unwrapped(node.initializer);
+    if (isCallExpression(value)) {
+      const called = writtenName(value.expression);
+      return (
+        name === "require" &&
+        called !== undefined &&
+        callsPlatformBy("createRequire", called, bindingOf, seen)
+      );
+    }
+    const written = writtenName(value);
+    return written !== undefined && callsPlatformBy(name, written, bindingOf, seen);
+  });
+}

package/src/platform-symbols.ts

@@ -0,0 +1,189 @@
+/**
+ * The platform's names read through a program's checker: its `require` and `URL`, as
+ * `platform-calls.ts` decides them, its worker constructors and `navigator`, and Node's
+ * `Worker`.
+ */
+
+import {
+  isArrowFunction,
+  isClassDeclaration,
+  isClassExpression,
+  isFunctionDeclaration,
+  isFunctionExpression,
+  isMethodDeclaration,
+  isModuleDeclaration,
+  isPropertyAssignment,
+  isPropertyDeclaration,
+  isSourceFile,
+  isStringLiteralLikeNode,
+  isVariableDeclaration,
+  type Identifier,
+  type Node,
+} from "@typescript/native/ast";
+import { SymbolFlags, type Symbol as TSSymbol } from "@typescript/native/sync";
+import { UNANSWERED, type Answer } from "./query.ts";
+import type { ProjectView } from "./session.ts";
+import { boundExports, NAMESPACE } from "./entries/static-module.ts";
+import { isAmbient } from "./inventory.ts";
+import { callsPlatformBy, carriedNames, type BindingOf, type Bound } from "./platform-calls.ts";
+import { unwrapped } from "./unwrap.ts";
+
+/** The symbol one symbol names through its aliases, or the symbol itself where it is none. */
+function dealiased<Brand>(project: ProjectView<Brand>, symbol: TSSymbol): Answer<TSSymbol> {
+  if ((symbol.flags & SymbolFlags.Alias) === 0) {
+    return symbol;
+  }
+  return project.queries.aliased(symbol);
+}
+
+/** Each declaration of `symbol` in a file of the target, read in this project's program. */
+function ownDeclarations<Brand>(project: ProjectView<Brand>, symbol: TSSymbol): readonly Node[] {
+  const own = project.ownPaths();
+  return symbol.declarations.flatMap((handle) => {
+    const node = own.has(handle.path) ? project.declarationAt(handle)?.node : undefined;
+    return node === undefined ? [] : [node];
+  });
+}
+
+/**
+ * Whether one declaration writes a function or a class with a body (roots.23): a function
+ * or method declaration with a body, a class declaration, or a variable, a property or a
+ * class field whose initializer is a function, an arrow function or a class expression,
+ * under no `declare` modifier and in no declaration file.
+ */
+function writesBody(node: Node): boolean {
+  const value =
+    (isVariableDeclaration(node) || isPropertyAssignment(node) || isPropertyDeclaration(node)) &&
+    node.initializer !== undefined
+      ? unwrapped(node.initializer)
+      : node;
+  return (
+    (isFunctionDeclaration(value) || isMethodDeclaration(value)
+      ? value.body !== undefined
+      : isFunctionExpression(value) ||
+        isArrowFunction(value) ||
+        isClassDeclaration(value) ||
+        isClassExpression(value)) && !isAmbient(value.getSourceFile(), value)
+  );
+}
+
+/**
+ * What the checker binds `symbol` to, one alias step at a time: every name a step of the
+ * chain carries it by, and the declarations of the target its last step reaches, which
+ * prove it the target's own where one {@link writesBody}. A chain that ends at no
+ * declaration, or that the checker leaves unanswered, reaches none.
+ */
+function boundBy<Brand>(
+  project: ProjectView<Brand>,
+  symbol: Answer<TSSymbol> | undefined,
+): Bound | undefined {
+  if (typeof symbol !== "object") {
+    return undefined;
+  }
+  const names = new Set<string>();
+  const stepped = new Set<number>();
+  for (let at: TSSymbol | undefined = symbol; at !== undefined && !stepped.has(at.id);) {
+    stepped.add(at.id);
+    names.add(at.name);
+    const own = ownDeclarations(project, at);
+    for (const node of own) {
+      carriedNames(node).forEach((one) => names.add(one));
+    }
+    if ((at.flags & SymbolFlags.Alias) === 0) {
+      return { names, own, provenOwn: own.some(writesBody) };
+    }
+    const next = project.aliasStepOf(at);
+    at = typeof next === "object" ? next : undefined;
+  }
+  return { names, own: [], provenOwn: false };
+}
+
+/** Each written name's binding, as this project's checker answers it. */
+function checkerBinding<Brand>(project: ProjectView<Brand>): BindingOf {
+  return (written) => boundBy(project, project.symbolsAt([project.handle(written)])[0]);
+}
+
+/**
+ * Whether a call or construction through `callee`, the batch's answer for which is `symbol`,
+ * is one of the platform's `require`, AMD's `define` or `URL` (roots.23, references-ts.37,
+ * references-ts.1), as {@link callsPlatformBy} decides it over this project's checker.
+ */
+export function callsPlatform<Brand>(
+  project: ProjectView<Brand>,
+  name: "require" | "define" | "URL",
+  callee: Identifier,
+  symbol: Answer<TSSymbol> | undefined,
+): boolean {
+  const others = checkerBinding(project);
+  return callsPlatformBy(name, callee, (written) =>
+    written === callee ? boundBy(project, symbol) : others(written),
+  );
+}
+
+/**
+ * Whether a worker's constructor or `navigator`, the batch's answer for which is `symbol`, is
+ * the platform's (references-ts.2): a name the checker leaves unanswered, or one whose symbol
+ * is no alias and has a declaration outside the target's files.
+ */
+export function isPlatformGlobal<Brand>(
+  project: ProjectView<Brand>,
+  symbol: Answer<TSSymbol> | undefined,
+): boolean {
+  if (symbol === UNANSWERED) {
+    return true;
+  }
+  const own = project.ownPaths();
+  return (
+    symbol !== undefined &&
+    (symbol.flags & SymbolFlags.Alias) === 0 &&
+    symbol.declarations.some((handle) => !own.has(handle.path))
+  );
+}
+
+/** The module names Node's worker threads are imported by. */
+const THREADS: ReadonlySet<string> = new Set(["worker_threads", "node:worker_threads"]);
+
+function namesThreads(node: Node | undefined): boolean {
+  return node !== undefined && isStringLiteralLikeNode(node) && THREADS.has(node.text);
+}
+
+/** Whether one declaration is written in the body of `declare module "worker_threads"`. */
+function inThreadsModule(node: Node): boolean {
+  for (let at = node; !isSourceFile(at); at = at.parent) {
+    if (isModuleDeclaration(at) && namesThreads(at.name)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether a `Worker` constructor, the batch's answer for which is `symbol`, is Node's
+ * (references-ts.2): its symbol resolves to a declaration of `worker_threads`, or one of its
+ * own declarations binds the module's `Worker`, or `holder`, the namespace it is read
+ * through, binds the module, each binding read as {@link boundExports} reads one, which
+ * decides where the module has no declaration.
+ */
+export function startsThread<Brand>(
+  project: ProjectView<Brand>,
+  symbol: Answer<TSSymbol> | undefined,
+  holder: Answer<TSSymbol> | undefined,
+): boolean {
+  const bindingOf = checkerBinding(project);
+  const declared = (one: Answer<TSSymbol> | undefined, member: string): boolean =>
+    typeof one === "object" &&
+    ownDeclarations(project, one).some((node) =>
+      boundExports(node, (specifier) => THREADS.has(specifier), bindingOf).includes(member),
+    );
+  if (declared(symbol, "Worker") || declared(holder, NAMESPACE)) {
+    return true;
+  }
+  const named = typeof symbol === "object" ? dealiased(project, symbol) : undefined;
+  return (
+    typeof named === "object" &&
+    named.declarations.some((handle) => {
+      const node = project.declarationAt(handle)?.node;
+      return node !== undefined && inThreadsModule(node);
+    })
+  );
+}

package/src/references/read-rule.ts

@@ -0,0 +1,60 @@
+import type { Node, SourceFile } from "@typescript/native/ast";
+import type { Type } from "@typescript/native/sync";
+import type { AliasChains } from "../alias-chain.ts";
+import type { Inventory } from "../inventory.ts";
+import type { Position } from "../position.ts";
+import type { Resolution } from "../references.ts";
+import type { ProjectView } from "../session.ts";
+
+/** Where the walk offered a read rule one node: the file, and the declaration enclosing the node. */
+interface ReadSite {
+  readonly file: SourceFile;
+  readonly from: string;
+}
+
+/** What a read rule reads its answers through, after the walk of every file of the side. */
+export interface ReadContext<Brand> {
+  readonly project: ProjectView<Brand>;
+  readonly held: Inventory;
+  readonly chains: AliasChains;
+}
+
+/**
+ * One read a rule makes: a use of the declaration `to` by `from` at a node of a walked file,
+ * or, where a question the read needed went unanswered, a hold. A hold names what the answer
+ * could have made live (program.33): the declarations `ids`, each declaration bearing one of
+ * `names`, each member of one of `types`, or with `members` every member the inventory holds;
+ * the declaration making the read is held as well. A named read sits at a node of `file`, or
+ * at a declaration's own position in it.
+ */
+export type Read =
+  | {
+      readonly kind: "named";
+      readonly from: string;
+      readonly to: string;
+      readonly file: SourceFile;
+      readonly at: Node | Position;
+      readonly use: "read" | "write";
+      readonly via: Resolution;
+      /** A read a rule counts as production code's whoever writes it. */
+      readonly production?: true;
+    }
+  | {
+      readonly kind: "held";
+      readonly from: string;
+      readonly ids?: readonly string[];
+      readonly names?: readonly string[];
+      readonly types?: readonly Type[];
+      readonly members?: true;
+    };
+
+/** One pass of one read rule over the files of one side: it collects while the walk offers nodes, then reads. */
+interface ReadRuleRun {
+  visit(node: Node, site: ReadSite): void;
+  reads<Brand>(context: ReadContext<Brand>): readonly Read[];
+}
+
+/** One rule of the references pages that reads declarations no name node names. */
+export interface ReadRule {
+  start(): ReadRuleRun;
+}

package/src/references/read-rules.ts

@@ -0,0 +1,55 @@
+import { elementAccess } from "../element-access.ts";
+import { indexedAccess } from "../indexed-access.ts";
+import { keyofComparisons } from "../keyof-comparisons.ts";
+import { moduleDeclarations } from "../module-declarations.ts";
+import { overrides } from "../overrides.ts";
+import { isAnswered } from "../query.ts";
+import { iteration } from "../symbol-keys.ts";
+import { typeParameterReads } from "../type-parameter-reads.ts";
+import { unimplementedCallees } from "../unimplemented-callees.ts";
+import type { Read, ReadContext, ReadRule } from "./read-rule.ts";
+
+/** The member kinds a hold of every member names. */
+const MEMBER_KINDS: ReadonlySet<string> = new Set([
+  "method",
+  "class-member",
+  "interface-method",
+  "type-member",
+  "enum-member",
+]);
+
+/**
+ * Every read rule, each run over every side's walked files with the reference sources:
+ * a consumer's read of a target member is a reference as the target's own is.
+ */
+export const READ_RULES: readonly ReadRule[] = [
+  overrides,
+  indexedAccess,
+  elementAccess,
+  keyofComparisons,
+  iteration,
+  typeParameterReads,
+  unimplementedCallees,
+  moduleDeclarations,
+];
+
+/** The declarations one hold names, with the declaration whose read it is. */
+export function heldBy<Brand>(
+  read: Extract<Read, { kind: "held" }>,
+  { project, held, chains }: ReadContext<Brand>,
+): readonly string[] {
+  const ids = [...(read.from === "" ? [] : [read.from]), ...(read.ids ?? [])];
+  for (const name of read.names ?? []) {
+    ids.push(...(held.byName.get(name) ?? []));
+  }
+  for (const type of read.types ?? []) {
+    const properties = project.queries.propertiesOf(type);
+    for (const property of isAnswered(properties) ? properties : []) {
+      ids.push(...chains.declarationsOf(property));
+    }
+  }
+  if (read.members === true) {
+    ids.push(...held.symbols.filter((one) => MEMBER_KINDS.has(one.kind)).map((one) => one.id));
+  }
+  return ids;
+}

package/src/references/sink.ts

@@ -0,0 +1,213 @@
+import {
+  isBinaryExpression,
+  isParenthesizedExpression,
+  isPropertyAccessExpression,
+  SyntaxKind,
+  type Node,
+  type SourceFile,
+} from "@typescript/native/ast";
+import { bindingsOf } from "../import-bindings.ts";
+import type { Site } from "../index/sites.ts";
+import { byPosition, renderPosition, type Position } from "../position.ts";
+import type { ConsumerSide, Reference, Resolution, Use } from "../references.ts";
+import { bytewise } from "../text/compare.ts";
+
+/** One declaration a use names: `guessed` where only its name answered, `stepped` where an alias chain led to it. */
+export interface Target {
+  readonly id: string;
+  readonly guessed?: boolean;
+  readonly stepped?: boolean;
+}
+
+/** One write's index among the records, by its file, with the value it stores. */
+interface Valued {
+  readonly index: number;
+  readonly value: Node;
+}
+
+/**
+ * Where every reference of one pass is made: it renders the position against the side's
+ * root, takes the writing file's test class from the file classes, marks a use only a
+ * declaration's name answered `guessed` and an alias step's `alias`, tags a consumer's
+ * reference with the consumer, and orders the records.
+ */
+export class Sink {
+  readonly #root: string;
+  readonly #testFile: (file: SourceFile) => boolean;
+  readonly #consumer: ConsumerSide | undefined;
+  readonly #found: Reference[] = [];
+  readonly #valued = new Map<SourceFile, Valued[]>();
+  readonly #held = new Set<string>();
+
+  constructor(
+    root: string,
+    testFile: (file: SourceFile) => boolean,
+    consumer: ConsumerSide | undefined,
+  ) {
+    this.#root = root;
+    this.#testFile = testFile;
+    this.#consumer = consumer;
+  }
+
+  /** Whether a test file wrote one walked file's uses. */
+  isTest(file: SourceFile): boolean {
+    return this.#testFile(file);
+  }
+
+  /** The position one node of a walked file renders at. */
+  position(file: SourceFile, at: Node): Position {
+    return renderPosition(file, this.#root, at.getStart());
+  }
+
+  /**
+   * Records one use of each target, made by `from` at `at` in `file`. A write that stores
+   * `value` is remembered for the import bindings only its values use. A `production` use is
+   * production code's whoever writes it.
+   */
+  add(
+    file: SourceFile,
+    at: Node | Position,
+    from: string,
+    targets: Iterable<Target | string>,
+    use: Use,
+    via: Resolution,
+    value?: Node,
+    production = false,
+  ): void {
+    const position = "column" in at ? at : this.position(file, at);
+    const test = !production && this.#testFile(file);
+    for (const one of targets) {
+      const target = typeof one === "string" ? { id: one } : one;
+      this.#found.push({
+        from,
+        to: target.id,
+        position,
+        use,
+        resolution: target.guessed === true ? "by-name" : target.stepped === true ? "alias" : via,
+        test,
+        ...(target.guessed === true ? { guessed: true as const } : {}),
+      });
+      if (use === "write" && value !== undefined) {
+        const valued = this.#valued.get(file) ?? [];
+        valued.push({ index: this.#found.length - 1, value });
+        this.#valued.set(file, valued);
+      }
+    }
+  }
+
+  /** Holds declarations an unanswered question could have made live, and the one whose read asked it. */
+  hold(ids: Iterable<string>): void {
+    for (const id of ids) {
+      this.#held.add(id);
+    }
+  }
+
+  /** The records made so far, before {@link finish} orders them. */
+  get made(): readonly Reference[] {
+    return this.#found;
+  }
+
+  /** Appends records another stage derived from these, rendered already. */
+  extend(references: readonly Reference[]): void {
+    this.#found.push(...references);
+  }
+
+  /**
+   * The records in position order, then the declaration named, the referencing declaration
+   * and the use, each write marked with the import bindings only its values use, and the
+   * held declarations. `usesOf` gives each walked file's name sites.
+   */
+  finish(usesOf: ReadonlyMap<SourceFile, readonly Site[]>): {
+    readonly references: readonly Reference[];
+    readonly held: readonly string[];
+  } {
+    const found = this.#found;
+    for (const [file, writes] of this.#valued) {
+      for (const { index, names } of aloneIn(file, usesOf.get(file) ?? [], writes, found)) {
+        const reference = found[index];
+        if (reference !== undefined) {
+          found[index] = { ...reference, alone: names };
+        }
+      }
+    }
+    found.sort(
+      (a, b) =>
+        byPosition(a.position, b.position) ||
+        bytewise(a.to, b.to) ||
+        bytewise(a.from, b.from) ||
+        bytewise(a.use, b.use),
+    );
+    const consumer = this.#consumer;
+    return {
+      references:
+        consumer === undefined
+          ? found
+          : found.map((reference) => ({ ...reference, consumer: consumer.id })),
+      held: [...this.#held].sort(bytewise),
+    };
+  }
+}
+
+/** The value one assignment stores through the name it writes, where it is a plain assignment. */
+export function storedValue(name: Node): Node | undefined {
+  let target: Node = name;
+  if (isPropertyAccessExpression(name.parent) && name.parent.name === name) {
+    target = name.parent;
+  }
+  while (isParenthesizedExpression(target.parent)) {
+    target = target.parent;
+  }
+  const parent = target.parent;
+  return isBinaryExpression(parent) &&
+    parent.operatorToken.kind === SyntaxKind.EqualsToken &&
+    parent.left === target
+    ? parent.right
+    : undefined;
+}
+
+/**
+ * The import bindings of one file that only the values written into one declaration
+ * use, for each write into it. A binding is named by an identifier that spells its
+ * local name and is not the member a property access names.
+ */
+function aloneIn(
+  file: SourceFile,
+  uses: readonly Site[],
+  writes: readonly Valued[],
+  found: readonly Reference[],
+): readonly { index: number; names: readonly string[] }[] {
+  const bindings = new Set(bindingsOf(file).map((binding) => binding.name.text));
+  if (bindings.size === 0) {
+    return [];
+  }
+  const occurrences = new Map<string, Node[]>();
+  for (const site of uses) {
+    const text = site.node.getText();
+    const parent = site.node.parent;
+    if (!bindings.has(text) || (isPropertyAccessExpression(parent) && parent.name === site.node)) {
+      continue;
+    }
+    if (!occurrences.get(text)?.includes(site.node)) {
+      occurrences.set(text, [...(occurrences.get(text) ?? []), site.node]);
+    }
+  }
+  const inside = (node: Node, value: Node): boolean =>
+    node.pos >= value.pos && node.end <= value.end;
+  const result: { index: number; names: readonly string[] }[] = [];
+  for (const write of writes) {
+    const to = found[write.index]?.to;
+    const sameTarget = writes.filter((one) => found[one.index]?.to === to);
+    const names = [...occurrences]
+      .filter(
+        ([, nodes]) =>
+          nodes.some((node) => inside(node, write.value)) &&
+          nodes.every((node) => sameTarget.some((one) => inside(node, one.value))),
+      )
+      .map(([name]) => name)
+      .sort(bytewise);
+    if (names.length > 0) {
+      result.push({ index: write.index, names });
+    }
+  }
+  return result;
+}