@cplieger/deadset-ts 8.0.0-dev.16 → 8.0.0-dev.18

package/src/paths.ts

@@ -11,6 +11,58 @@ export function isAbsolutePath(path: string): boolean {
   return path.startsWith(SEPARATOR);
 }
 
+/** Whether a specifier starts a path relative to the file that writes it: `./` or `../`. */
+export function startsRelativePath(specifier: string): boolean {
+  return specifier.startsWith("./") || specifier.startsWith("../");
+}
+
+/** Whether a specifier names a path relative to the file that writes it: `.`, `..`, `./` or `../` first. */
+export function isRelativeSpecifier(specifier: string): boolean {
+  return specifier === "." || specifier === ".." || startsRelativePath(specifier);
+}
+
+/**
+ * Whether a module specifier names a path rather than a package, as the compiler reads one:
+ * a relative specifier or an absolute path.
+ */
+export function isPathSpecifier(specifier: string): boolean {
+  return isRelativeSpecifier(specifier) || isAbsolutePath(specifier);
+}
+
+/**
+ * Whether a string starts with `./`, `../` or `/`, the specifiers a browser reads as a URL
+ * rather than a bare name, so a bare `.` or `..` stays a request:
+ * https://html.spec.whatwg.org/multipage/webappapis.html#resolve-a-url-like-module-specifier
+ */
+export function isExplicitPath(text: string): boolean {
+  return startsRelativePath(text) || isAbsolutePath(text);
+}
+
+/**
+ * Whether a string starts with `.` or `/`, which no npm package name does, so a reader that
+ * takes any other string as a package's takes it as a path:
+ * https://docs.npmjs.com/cli/v11/configuring-npm/package-json#name
+ */
+export function cannotStartPackageName(text: string): boolean {
+  return text.startsWith(".") || isAbsolutePath(text);
+}
+
+/** A URL scheme, `file:` and `node:` among them: https://url.spec.whatwg.org/#url-scheme-string */
+const URL_SCHEME = /^[a-z][a-z\d+.-]*:/iu;
+
+/** Whether a string starts with a URL scheme. */
+export function hasURLScheme(text: string): boolean {
+  return URL_SCHEME.test(text);
+}
+
+/**
+ * Whether a URL reference is a relative one that does not start with a solidus, the bare
+ * name included: https://url.spec.whatwg.org/#relative-url-string
+ */
+export function isPathRelativeURL(reference: string): boolean {
+  return reference !== "" && !reference.startsWith(SEPARATOR) && !hasURLScheme(reference);
+}
+
 /**
  * One path with `.` removed, `..` applied to the segment before it, and repeated
  * separators collapsed. A `..` that walks past the root of an absolute path is
@@ -97,18 +149,12 @@ export function resolvePath(against: string, path: string): string {
   return isAbsolutePath(path) ? normalizePath(path) : joinPath(against, path);
 }
 
-/**
- * A URL reference's scheme. A reference with none that does not start with a solidus is
- * relative, the bare name included: https://url.spec.whatwg.org/#relative-url-string
- */
-const URL_SCHEME = /^[a-z][a-z\d+.-]*:/iu;
-
 /**
  * The path a relative URL reference names against `dir`, its query and its fragment
  * removed, which name no part of the file; undefined where the reference is not relative.
  */
 export function relativeURLPath(dir: string, reference: string): string | undefined {
-  if (reference === "" || reference.startsWith("/") || URL_SCHEME.test(reference)) {
+  if (!isPathRelativeURL(reference)) {
     return undefined;
   }
   const cut = reference.search(/[?#]/u);
@@ -123,7 +169,7 @@ export function relativeURLPath(dir: string, reference: string): string | undefi
  */
 export function queriedModulePath(specifier: string): string | undefined {
   const query = specifier.indexOf("?");
-  if (query < 0 || !(specifier.startsWith("./") || specifier.startsWith("../"))) {
+  if (query < 0 || !startsRelativePath(specifier)) {
     return undefined;
   }
   const raw = specifier

package/src/platform-calls.ts

@@ -1,6 +1,6 @@
 /**
- * Which calls are the platform's `require` and which constructions its `URL` (roots.23,
- * references-ts.1), decided once over the bindings of the names a callee is written with: the
+ * 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.
  */
 
@@ -19,7 +19,7 @@ import {
 import { parenthesesRemoved, unwrapped } from "./unwrap.ts";
 
 /** A name of the platform the analysis reads calls of. */
-type PlatformName = "require" | "createRequire" | "URL";
+type PlatformName = "require" | "createRequire" | "define" | "URL";
 
 /** What one written name is bound to, as far as its reader can tell. */
 export interface Bound {

package/src/platform-symbols.ts

@@ -28,19 +28,11 @@ import { isAmbient } from "./inventory.ts";
 import { callsPlatformBy, carriedNames, type BindingOf, type Bound } from "./platform-calls.ts";
 import { unwrapped } from "./unwrap.ts";
 
-/** Counts one request a platform decision puts to the checker. */
-type Asked = () => void;
-
 /** The symbol one symbol names through its aliases, or the symbol itself where it is none. */
-function dealiased<Brand>(
-  project: ProjectView<Brand>,
-  symbol: TSSymbol,
-  asked: Asked,
-): Answer<TSSymbol> {
+function dealiased<Brand>(project: ProjectView<Brand>, symbol: TSSymbol): Answer<TSSymbol> {
   if ((symbol.flags & SymbolFlags.Alias) === 0) {
     return symbol;
   }
-  asked();
   return project.queries.aliased(symbol);
 }
 
@@ -84,7 +76,6 @@ function writesBody(node: Node): boolean {
 function boundBy<Brand>(
   project: ProjectView<Brand>,
   symbol: Answer<TSSymbol> | undefined,
-  asked: Asked,
 ): Bound | undefined {
   if (typeof symbol !== "object") {
     return undefined;
@@ -101,7 +92,6 @@ function boundBy<Brand>(
     if ((at.flags & SymbolFlags.Alias) === 0) {
       return { names, own, provenOwn: own.some(writesBody) };
     }
-    asked();
     const next = project.aliasStepOf(at);
     at = typeof next === "object" ? next : undefined;
   }
@@ -109,29 +99,24 @@ function boundBy<Brand>(
 }
 
 /** Each written name's binding, as this project's checker answers it. */
-function checkerBinding<Brand>(project: ProjectView<Brand>, asked: Asked): BindingOf {
-  return (written) => {
-    asked();
-    return boundBy(project, project.symbolsAt([project.handle(written)])[0], asked);
-  };
+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` or `URL` (roots.23, references-ts.1), as
- * {@link callsPlatformBy} decides it over this project's checker, each request it puts
- * counted by `asked`.
+ * 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" | "URL",
+  name: "require" | "define" | "URL",
   callee: Identifier,
   symbol: Answer<TSSymbol> | undefined,
-  asked: Asked,
 ): boolean {
-  const others = checkerBinding(project, asked);
+  const others = checkerBinding(project);
   return callsPlatformBy(name, callee, (written) =>
-    written === callee ? boundBy(project, symbol, asked) : others(written),
+    written === callee ? boundBy(project, symbol) : others(written),
   );
 }
 
@@ -177,15 +162,14 @@ function inThreadsModule(node: Node): boolean {
  * (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. Each request it puts is counted by `asked`.
+ * decides where the module has no declaration.
  */
 export function startsThread<Brand>(
   project: ProjectView<Brand>,
   symbol: Answer<TSSymbol> | undefined,
   holder: Answer<TSSymbol> | undefined,
-  asked: Asked,
 ): boolean {
-  const bindingOf = checkerBinding(project, asked);
+  const bindingOf = checkerBinding(project);
   const declared = (one: Answer<TSSymbol> | undefined, member: string): boolean =>
     typeof one === "object" &&
     ownDeclarations(project, one).some((node) =>
@@ -194,7 +178,7 @@ export function startsThread<Brand>(
   if (declared(symbol, "Worker") || declared(holder, NAMESPACE)) {
     return true;
   }
-  const named = typeof symbol === "object" ? dealiased(project, symbol, asked) : undefined;
+  const named = typeof symbol === "object" ? dealiased(project, symbol) : undefined;
   return (
     typeof named === "object" &&
     named.declarations.some((handle) => {

package/src/query.ts

@@ -207,8 +207,22 @@ export interface Queries {
   constraintOf(type: Type): Answer<Type | undefined>;
   /** The object and the index of an indexed-access type; none for another type. */
   indexedAccessOf(type: Type): Answer<{ readonly object: Type; readonly index: Type } | undefined>;
+  /**
+   * The types one type is spelled from besides its constituents, type arguments and members:
+   * a type parameter's constraint and default, a conditional's check, extends, true
+   * and false types, a mapped type's constraint, name and template, an indexed access's
+   * object and index, the operand of `keyof` or of a string mapping, a template literal's
+   * spans and a substitution's base and constraint. None for another type.
+   */
+  partsOf(type: Type): Answer<readonly Type[]>;
+  /** The type parameters of a signature, its `this` parameter's type and its predicate's type. */
+  signaturePartsOf(signature: Signature): Answer<readonly Type[]>;
   /** The symbol a type is declared by. */
   symbolOfType(type: Type): Answer<TSSymbol | undefined>;
+  /** The type alias a type was instantiated from, where it was. */
+  aliasSymbolOf(type: Type): Answer<TSSymbol | undefined>;
+  /** The type arguments the alias a type was instantiated from was given. */
+  aliasArgumentsOf(type: Type): Answer<readonly Type[]>;
   signaturesOf(type: Type, kind: SignatureKind): Answer<readonly Signature[]>;
   resolvedSignature(node: Node): Answer<Signature | undefined>;
   /** The signature each call-like node resolves to. */
@@ -223,6 +237,37 @@ export interface Queries {
   typeToString(type: Type): Answer<string>;
 }
 
+/** How to read the types one type is spelled from, as {@link Queries.partsOf} names them. */
+function partQuestion(type: Type): (() => readonly (Type | undefined)[]) | undefined {
+  if (type.isTypeParameter()) {
+    return () => [type.getConstraint(), type.getDefault()];
+  }
+  if (type.isConditionalType()) {
+    return () => [
+      type.getCheckType(),
+      type.getExtendsType(),
+      type.getTrueType(),
+      type.getFalseType(),
+    ];
+  }
+  if (type.isMappedType()) {
+    return () => [type.getConstraintType(), type.getNameType(), type.getTemplateType()];
+  }
+  if (type.isIndexedAccessType()) {
+    return () => [type.getObjectType(), type.getIndexType()];
+  }
+  if (type.isIndexType() || type.isStringMappingType()) {
+    return () => [type.getTarget()];
+  }
+  if (type.isTemplateLiteralType()) {
+    return () => type.getTypes();
+  }
+  if (type.isSubstitutionType()) {
+    return () => [type.getBaseType(), type.getConstraint()];
+  }
+  return undefined;
+}
+
 /**
  * The guarded questions over one project's checker. `configFile` names the project
  * in the log, `batch` sends many questions in one round trip, `log` is the run's,
@@ -528,12 +573,48 @@ export function queriesOf(
             () => ({ object: type.getObjectType(), index: type.getIndexType() }),
           )
         : undefined,
+    partsOf: (type) => {
+      const parts = partQuestion(type);
+      return parts === undefined
+        ? []
+        : one(
+            "getParts",
+            () => typeLocation(type),
+            () => parts().filter((part) => part !== undefined),
+          );
+    },
+    signaturePartsOf: (signature) =>
+      one(
+        "getSignatureParts",
+        () => `signature ${String(signature.id)}`,
+        () => {
+          const self =
+            signature.thisParameter === undefined ? undefined : signature.getThisParameter();
+          return [
+            ...((signature.typeParameters ?? []).length === 0 ? [] : signature.getTypeParameters()),
+            self === undefined ? undefined : checker.getTypeOfSymbol(self),
+            checker.getTypePredicateOfSignature(signature)?.type,
+          ].filter((part) => part !== undefined);
+        },
+      ),
     symbolOfType: (type) =>
       one(
         "getSymbol",
         () => typeLocation(type),
         () => type.getSymbol(),
       ),
+    aliasSymbolOf: (type) =>
+      one(
+        "getAliasSymbol",
+        () => typeLocation(type),
+        () => type.getAliasSymbol(),
+      ),
+    aliasArgumentsOf: (type) =>
+      one(
+        "getAliasTypeArguments",
+        () => typeLocation(type),
+        () => type.getAliasTypeArguments(),
+      ),
     signaturesOf: (type, kind) =>
       one(
         "getSignaturesOfType",

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;
+}