@cplieger/deadset-ts 5.0.0 → 5.1.1

package/src/configuration-files.ts

@@ -8,6 +8,8 @@
  */
 
 import {
+  isExportDeclaration,
+  isImportDeclaration,
   isNoSubstitutionTemplateLiteral,
   isStringLiteral,
   type Node,
@@ -43,8 +45,19 @@ const DEPENDENCY_MEMBERS = [
 /** The prefixes a string names a file with, relative to the file that writes it. */
 const RELATIVE_PREFIXES = ["./", "../"] as const;
 
+/** The JavaScript extensions a relative specifier from a configuration file stands for TypeScript under. */
+const COUNTERPARTS: readonly (readonly [string, readonly string[]])[] = [
+  [".js", [".ts", ".tsx"]],
+  [".jsx", [".tsx", ".ts"]],
+  [".mjs", [".mts"]],
+  [".cjs", [".cts"]],
+];
+
+/** The extensions appended to a relative specifier from a configuration file, in order. */
+const APPENDED = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"] as const;
+
 /** The extensions the program's module resolution appends to a specifier written without one. */
-const RESOLVED_EXTENSIONS = [
+export const RESOLVED_EXTENSIONS = [
   ".ts",
   ".tsx",
   ".d.ts",
@@ -83,10 +96,27 @@ interface ConfigurationDocument {
   readonly strings: readonly string[];
 }
 
+/** Parses one file the program does not hold, with no type information. */
+export type ParseFile = (fileName: string, text: string) => SourceFile;
+
+/** One file no program holds that a configuration module outside the program leads to. */
+export interface OutsideModule {
+  /** The file, parsed alone. */
+  readonly file: SourceFile;
+  /** The directory of the configuration module the file was reached from, which holds its manifest. */
+  readonly manifestDir: string;
+}
+
 /** The configuration files one project holds and sits beside. */
 interface ConfigurationFiles {
   /** Every own file that is a configuration module, with the form its name has. */
   readonly modules: readonly { readonly file: SourceFile; readonly form: string }[];
+  /**
+   * Every configuration module in a directory of the project that the program does not
+   * hold, and every file such a file imports or re-exports by a relative specifier that
+   * the program does not hold either, read where a parser is given.
+   */
+  readonly outside: readonly OutsideModule[];
   /** Every JSON configuration file in a directory of the project's files or above one. */
   readonly documents: readonly ConfigurationDocument[];
 }
@@ -128,6 +158,7 @@ export function configurationFiles(
   host: Host,
   targetRoot: string,
   files: SourceFiles,
+  parse?: ParseFile,
 ): ConfigurationFiles {
   const root = resolvePath(host.workingDirectory(), targetRoot);
   const manifests = new Map<string, boolean>();
@@ -182,7 +213,111 @@ export function configurationFiles(
       documents.push({ path, strings: documentStrings(value) });
     }
   }
-  return { modules, documents };
+  return {
+    modules,
+    documents,
+    outside:
+      parse === undefined ? [] : outsideModules(host, [...dirs], files, holdsManifest, parse),
+  };
+}
+
+/** The relative specifiers one file's imports and re-exports name. */
+function relativeSpecifiers(file: SourceFile): readonly string[] {
+  return file.statements.flatMap((statement) => {
+    const specifier =
+      isImportDeclaration(statement) || isExportDeclaration(statement)
+        ? statement.moduleSpecifier
+        : undefined;
+    return specifier !== undefined &&
+      isStringLiteral(specifier) &&
+      RELATIVE_PREFIXES.some((prefix) => specifier.text.startsWith(prefix))
+      ? [specifier.text]
+      : [];
+  });
+}
+
+/**
+ * The module one relative specifier from a configuration file reaches: the path it names,
+ * that path with its JavaScript extension replaced by the TypeScript counterparts, that
+ * path with an extension appended, and a directory's `index` with one appended.
+ */
+function reachedBy(host: Host, dir: string, specifier: string): string | undefined {
+  const path = resolvePath(dir, specifier);
+  const isFile = (candidate: string): boolean => host.kindOf(candidate) === "file";
+  // A data file such as `./package.json` is no module, so its strings use no dependency.
+  if (isFile(path) && APPENDED.some((extension) => path.endsWith(extension))) {
+    return path;
+  }
+  for (const [extension, counterparts] of COUNTERPARTS) {
+    if (path.endsWith(extension)) {
+      const stem = path.slice(0, -extension.length);
+      const found = counterparts.map((one) => stem + one).find(isFile);
+      if (found !== undefined) {
+        return found;
+      }
+    }
+  }
+  const appended = APPENDED.map((extension) => path + extension).find(isFile);
+  if (appended !== undefined) {
+    return appended;
+  }
+  return host.kindOf(path) === "directory"
+    ? APPENDED.map((extension) => joinPath(path, `index${extension}`)).find(isFile)
+    : undefined;
+}
+
+/**
+ * The configuration modules of the directories that hold a manifest which the program
+ * does not hold, and the files they import by a relative specifier, until no further
+ * file joins. A file that cannot be read is skipped.
+ */
+function outsideModules(
+  host: Host,
+  dirs: readonly string[],
+  files: SourceFiles,
+  holdsManifest: (dir: string) => boolean,
+  parse: ParseFile,
+): readonly OutsideModule[] {
+  const pending: { path: string; manifestDir: string }[] = [];
+  for (const dir of [...dirs].sort()) {
+    if (!holdsManifest(dir)) {
+      continue;
+    }
+    let names: readonly string[];
+    try {
+      names = host
+        .readDirectory(dir)
+        .filter((entry) => !entry.directory && configurationModuleForm(entry.name) !== undefined)
+        .map((entry) => entry.name)
+        .sort();
+    } catch {
+      continue;
+    }
+    pending.push(...names.map((name) => ({ path: joinPath(dir, name), manifestDir: dir })));
+  }
+  const found: OutsideModule[] = [];
+  const seen = new Set<string>();
+  for (let next = pending.shift(); next !== undefined; next = pending.shift()) {
+    if (seen.has(next.path) || files.byName.has(next.path)) {
+      continue;
+    }
+    seen.add(next.path);
+    let text: string;
+    try {
+      text = host.readFile(next.path);
+    } catch {
+      continue;
+    }
+    const file = parse(next.path, text);
+    found.push({ file, manifestDir: next.manifestDir });
+    for (const specifier of relativeSpecifiers(file)) {
+      const reached = reachedBy(host, dirnamePath(next.path), specifier);
+      if (reached !== undefined) {
+        pending.push({ path: reached, manifestDir: next.manifestDir });
+      }
+    }
+  }
+  return found;
 }
 
 /** Every dependency the manifest in one directory declares, or none where it holds none to read. */

package/src/conformance-record.ts

@@ -2,16 +2,9 @@
 // Regenerate it with `UPDATE_GOLDEN=1 npx vitest --run src/conformance.corpus.test.ts`.
 export const RECORD = {
   conformance: {
-    corpusVersion: "2.1.1",
+    corpusVersion: "2.2.0",
     result: "pass",
-    digest: "sha256:e5e456bf3a706f1fa9f906ae71e10ea98a78da52d7d99a5ed59dca8a72bbe927",
+    digest: "sha256:ce7c9087ed7b2baf3de9fa2df436b500706f4f9e94fd9e0fed633054305f06a4",
   },
-  gaps: [
-    {
-      fixture: "private-member-unread",
-      capability: "reflective-lookup",
-      reason:
-        "The reference pass resolves a string-literal element access to the member it names, so the member is live by that reference and the retained listing names no class for it.",
-    },
-  ],
+  gaps: [],
 } as const;

package/src/contextual-uses.ts

@@ -0,0 +1,358 @@
+/**
+ * The uses contextual types make of the target's members, which no name node resolves to.
+ * An object-literal property writes the member of its name on each constituent of the
+ * literal's contextual type that declares one. A value reaching a position typed by another
+ * object type reads each of its members that type declares, through array elements and
+ * function parameters and results too; a class instance there is the
+ * interface-satisfaction class's evidence instead.
+ */
+
+import {
+  isComputedPropertyName,
+  isGetAccessorDeclaration,
+  isIdentifier,
+  isMethodDeclaration,
+  isNoSubstitutionTemplateLiteral,
+  isNumericLiteral,
+  isObjectLiteralExpression,
+  isPropertyAssignment,
+  isSetAccessorDeclaration,
+  isShorthandPropertyAssignment,
+  isStringLiteral,
+  type Expression,
+  type Node,
+  type ObjectLiteralExpression,
+} from "@typescript/native/unstable/ast";
+import { SignatureKind, type Type } from "@typescript/native/unstable/sync";
+import type { AliasChains } from "./alias-chain.ts";
+import type { Inventory, SymbolKind } from "./inventory.ts";
+import { isAnswered, type PropertyTables } from "./query.ts";
+import type { ProjectView } from "./session.ts";
+
+/** The member kinds a contextual type writes and reads: data members and the members of object types. */
+const MEMBER_KINDS: ReadonlySet<SymbolKind> = new Set(["type-member", "class-member"]);
+
+/** One object literal a walk found, and the declaration it is written inside. */
+export interface LiteralAt {
+  readonly literal: ObjectLiteralExpression;
+  readonly from: string;
+}
+
+/** One value handed to a position typed by its context, and the declaration it is written inside. */
+export interface FlowAt {
+  readonly value: Expression;
+  readonly from: string;
+}
+
+/** One use the contextual types make: the node it is written at and the members it names. */
+export interface ContextualUse {
+  readonly at: Node;
+  readonly from: string;
+  readonly ids: readonly string[];
+}
+
+/** What the contextual types of one project's literals and values use, and what asking cost. */
+export interface ContextualUses {
+  /** Each literal property that writes a member, by the property's node. */
+  readonly writes: readonly ContextualUse[];
+  /** Each value whose members a position typed by another object type reads. */
+  readonly reads: readonly ContextualUse[];
+  /** The batched lookups: contextual types and value types, one per capped run. */
+  readonly batches: number;
+  /** The per-type lookups: each distinct type's constituents, properties and declaring symbol. */
+  readonly lookups: number;
+}
+
+/** The name one literal property is written under, where the name is literal text. */
+function propertyName(property: Node): { node: Node; text: string } | undefined {
+  if (
+    !isPropertyAssignment(property) &&
+    !isShorthandPropertyAssignment(property) &&
+    !isMethodDeclaration(property) &&
+    !isGetAccessorDeclaration(property) &&
+    !isSetAccessorDeclaration(property)
+  ) {
+    return undefined;
+  }
+  const name = property.name;
+  if (isIdentifier(name) || isStringLiteral(name) || isNumericLiteral(name)) {
+    return { node: name, text: name.text };
+  }
+  if (isComputedPropertyName(name)) {
+    const key = name.expression;
+    if (isStringLiteral(key) || isNumericLiteral(key) || isNoSubstitutionTemplateLiteral(key)) {
+      return { node: name, text: key.text };
+    }
+  }
+  return undefined;
+}
+
+/** The parameter and result types of one call signature, each where the checker answered. */
+interface Called {
+  readonly parameters: readonly (Type | undefined)[];
+  readonly result: Type | undefined;
+}
+
+/** One object type a value is checked as, and the position's object types it is checked against. */
+interface Checked {
+  readonly source: Type;
+  readonly targets: readonly Type[];
+}
+
+/** One member of an object type, by the inventory's declarations and the checker's declaration handles. */
+interface Member {
+  readonly ids: readonly string[];
+  readonly handles: ReadonlySet<string>;
+}
+
+/**
+ * The contextual uses of one project's literals and values, asked in batches: one
+ * contextual type per literal and per value whose type carries a member of the target,
+ * one type per value, and each distinct type's properties once.
+ */
+export function contextualUses<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+  chains: AliasChains,
+  literals: readonly LiteralAt[],
+  flows: readonly FlowAt[],
+  cap: number,
+  properties: PropertyTables,
+): ContextualUses {
+  const queries = project.queries;
+  const kinds = new Map(held.symbols.map((symbol) => [symbol.id, symbol.kind]));
+  let batches = 0;
+  let lookups = 0;
+  const batchesOf = (count: number): number => Math.ceil(count / cap);
+
+  const parts = new Map<number, readonly Type[]>();
+  /** The object types one type is: itself, or its constituents at any depth. */
+  const partsOf = (type: Type): readonly Type[] => {
+    const known = parts.get(type.id);
+    if (known !== undefined) {
+      return known;
+    }
+    let found: readonly Type[] = [];
+    if (type.isUnionType() || type.isIntersectionType()) {
+      lookups += 1;
+      const constituents = queries.constituents(type);
+      found = isAnswered(constituents) ? constituents.flatMap(partsOf) : [];
+    } else if (type.isObjectType()) {
+      found = [type];
+    }
+    parts.set(type.id, found);
+    return found;
+  };
+
+  const tables = new Map<number, ReadonlyMap<string, Member>>();
+  /** The members one object type has, by name. */
+  const membersOf = (type: Type): ReadonlyMap<string, Member> => {
+    const known = tables.get(type.id);
+    if (known !== undefined) {
+      return known;
+    }
+    const table = new Map<string, Member>();
+    const read = properties.of(type);
+    lookups += read.asked ? 1 : 0;
+    for (const property of isAnswered(read.properties) ? read.properties : []) {
+      table.set(property.name, {
+        ids: chains
+          .declarationsOf(property)
+          .filter((id) => MEMBER_KINDS.has(kinds.get(id) ?? "file")),
+        handles: new Set(
+          property.declarations.map((handle) => `${handle.path}#${String(handle.index)}`),
+        ),
+      });
+    }
+    tables.set(type.id, table);
+    return table;
+  };
+
+  const writes: ContextualUse[] = [];
+  batches += batchesOf(literals.length);
+  const contexts = queries.contextualTypes(
+    literals.map((one) => one.literal),
+    cap,
+  );
+  literals.forEach(({ literal, from }, index) => {
+    const context = contexts[index];
+    if (context === undefined || !isAnswered(context)) {
+      return;
+    }
+    const tablesOf = partsOf(context).map(membersOf);
+    for (const property of literal.properties) {
+      const name = propertyName(property);
+      if (name === undefined) {
+        continue;
+      }
+      const ids = [...new Set(tablesOf.flatMap((table) => table.get(name.text)?.ids ?? []))];
+      if (ids.length > 0) {
+        writes.push({ at: name.node, from, ids });
+      }
+    }
+  });
+
+  const carried = flows.filter((flow) => !isObjectLiteralExpression(flow.value));
+  batches += batchesOf(carried.length);
+  const types = queries.typesAt(
+    carried.map((flow) => flow.value),
+    cap,
+  );
+  /** The members a position may read structurally: those of object types, not of classes. */
+  const readable = (member: Member): readonly string[] =>
+    member.ids.filter((id) => kinds.get(id) === "type-member");
+  const carries = (part: Type): boolean =>
+    [...membersOf(part).values()].some((member) => readable(member).length > 0);
+
+  const elements = new Map<number, Type | undefined>();
+  /** The element type of an array type, read once per type. */
+  const elementOf = (type: Type): Type | undefined => {
+    if (elements.has(type.id)) {
+      return elements.get(type.id);
+    }
+    lookups += 1;
+    const isArray = queries.isArray(type);
+    let element: Type | undefined;
+    if (isAnswered(isArray) && isArray) {
+      lookups += 1;
+      const held = queries.typeArguments(type);
+      element = isAnswered(held) ? held[0] : undefined;
+    }
+    elements.set(type.id, element);
+    return element;
+  };
+
+  const calls = new Map<number, Called | undefined>();
+  /** The parameter and return types of a type's one call signature, read once per type. */
+  const callOf = (type: Type): Called | undefined => {
+    if (calls.has(type.id)) {
+      return calls.get(type.id);
+    }
+    lookups += 1;
+    const signatures = queries.signaturesOf(type, SignatureKind.Call);
+    let called: Called | undefined;
+    const [signature, ...more] = isAnswered(signatures) ? signatures : [];
+    if (signature !== undefined && more.length === 0) {
+      const parameters = signature.parameters.map((_parameter, index) =>
+        queries.parameterType(signature, index),
+      );
+      const result = queries.returnTypeOf(signature);
+      lookups += parameters.length + 1;
+      called = {
+        parameters: parameters.map((one) => (isAnswered(one) ? one : undefined)),
+        result: isAnswered(result) ? result : undefined,
+      };
+    }
+    calls.set(type.id, called);
+    return called;
+  };
+
+  /**
+   * Each object type a value of `source` is checked as against the object types of
+   * `target`: the value's own, and through array elements and through a function's
+   * parameters, checked the other way, and its result. A source that is one of the
+   * target's own object types matches it as it stands. Each pair is compared once, which
+   * ends the walk over a recursive type.
+   */
+  const compared = (
+    source: Type | undefined,
+    target: Type | undefined,
+    into: Checked[],
+    seen: Set<string>,
+  ): void => {
+    const key = `${String(source?.id)}>${String(target?.id)}`;
+    if (source === undefined || target === undefined || source.id === target.id) {
+      return;
+    }
+    if (seen.has(key)) {
+      return;
+    }
+    seen.add(key);
+    const targets = partsOf(target);
+    const sources = partsOf(source).filter((one) => !targets.some((part) => part.id === one.id));
+    for (const one of sources) {
+      if (carries(one)) {
+        into.push({ source: one, targets });
+      }
+      const element = elementOf(one);
+      const called = element === undefined ? callOf(one) : undefined;
+      for (const part of targets) {
+        if (element !== undefined) {
+          compared(element, elementOf(part), into, seen);
+          continue;
+        }
+        const other = called === undefined ? undefined : callOf(part);
+        if (called === undefined || other === undefined) {
+          continue;
+        }
+        other.parameters.forEach((parameter, index) => {
+          compared(parameter, called.parameters[index], into, seen);
+        });
+        compared(called.result, other.result, into, seen);
+      }
+    }
+  };
+
+  /**
+   * Whether a value of one type may carry a member a position reads, at any depth the
+   * walk takes. A type met again on the way adds nothing its first visit did not.
+   */
+  const mayCarry = (type: Type, seen: Set<number> = new Set()): boolean => {
+    if (seen.has(type.id)) {
+      return false;
+    }
+    seen.add(type.id);
+    return partsOf(type).some((part) => {
+      if (carries(part)) {
+        return true;
+      }
+      const element = elementOf(part);
+      if (element !== undefined) {
+        return mayCarry(element, seen);
+      }
+      return callOf(part) !== undefined;
+    });
+  };
+
+  const sourced = carried.flatMap((flow, index) => {
+    const type = types[index];
+    return type === undefined || !isAnswered(type) || !mayCarry(type) ? [] : [{ flow, type }];
+  });
+  batches += batchesOf(sourced.length);
+  const positions = queries.contextualTypes(
+    sourced.map((one) => one.flow.value),
+    cap,
+  );
+  const reads: ContextualUse[] = [];
+  sourced.forEach(({ flow, type }, index) => {
+    const position = positions[index];
+    if (position === undefined || !isAnswered(position)) {
+      return;
+    }
+    const checked: Checked[] = [];
+    compared(type, position, checked, new Set());
+    const ids = new Set<string>();
+    for (const { source, targets } of checked) {
+      const tables = targets.map(membersOf);
+      for (const [name, member] of membersOf(source)) {
+        const read = tables.some((table) => {
+          const declared = table.get(name);
+          return (
+            declared !== undefined &&
+            declared.handles.size > 0 &&
+            ![...declared.handles].some((handle) => member.handles.has(handle))
+          );
+        });
+        if (read) {
+          for (const id of readable(member)) {
+            ids.add(id);
+          }
+        }
+      }
+    }
+    if (ids.size > 0) {
+      reads.push({ at: flow.value, from: flow.from, ids: [...ids] });
+    }
+  });
+  return { writes, reads, batches, lookups };
+}

package/src/convention-rows.ts

@@ -52,6 +52,8 @@ export interface ConventionRow {
   readonly entries: readonly string[];
   /** The globs of the files the row does not root, though an entry glob names them. */
   readonly excludes?: readonly string[];
+  /** The directories the framework generates, each of whose files is a generated file. */
+  readonly generated?: readonly string[];
   /** The directories configuration moves, in the order their placeholders depend on each other. */
   readonly moves: readonly DirectoryMove[];
 }
@@ -102,6 +104,7 @@ export const CONVENTION_ROWS: readonly ConventionRow[] = [
       `<src>/content/config.${MODULE}`,
     ],
     excludes: ["<src>/pages/**/_*", "<src>/pages/**/_*/**"],
+    generated: [".astro"],
     moves: [
       {
         id: "src",
@@ -128,6 +131,7 @@ export const CONVENTION_ROWS: readonly ConventionRow[] = [
     name: "next",
     package: "next",
     range: ">=13.4.0 <17.0.0",
+    generated: [".next"],
     entries: [
       `{,src/}app/**/{layout,page,loading,not-found,error,route,template,default,forbidden,unauthorized}.${SCRIPT}`,
       `{,src/}app/global-{error,not-found}.${SCRIPT}`,
@@ -144,6 +148,7 @@ export const CONVENTION_ROWS: readonly ConventionRow[] = [
     name: "nuxt",
     package: "nuxt",
     range: ">=3.0.0 <5.0.0",
+    generated: [".nuxt"],
     entries: [
       "<srcDir>/{app,error}.{vue,jsx,tsx}",
       `<srcDir>/app.config.${MODULE}`,
@@ -238,6 +243,7 @@ export const CONVENTION_ROWS: readonly ConventionRow[] = [
     package: "@react-router/dev",
     range: ">=7.0.0 <9.0.0",
     entries: APP_DIRECTORY_ENTRIES,
+    generated: [".react-router"],
     moves: [
       {
         id: "app",
@@ -316,6 +322,7 @@ export const CONVENTION_ROWS: readonly ConventionRow[] = [
     package: "@sveltejs/kit",
     range: ">=2.0.0 <3.0.0",
     entries: [...SVELTEKIT_ENTRIES, "<params>/*.{js,ts}"],
+    generated: [".svelte-kit"],
     moves: [
       {
         id: "src",
@@ -380,6 +387,7 @@ export const CONVENTION_ROWS: readonly ConventionRow[] = [
     package: "@sveltejs/kit",
     range: ">=3.0.0 <4.0.0",
     entries: [...SVELTEKIT_ENTRIES, "<params>.{js,ts}"],
+    generated: [".svelte-kit"],
     moves: [
       {
         id: "src",