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

package/src/module-declarations.ts

@@ -15,20 +15,18 @@ import {
   isImportTypeNode,
   isLiteralTypeNode,
   isModuleDeclaration,
-  isNamespaceExport,
-  isNamespaceImport,
   isNoSubstitutionTemplateLiteral,
   isStringLiteral,
   SyntaxKind,
   type Node,
   type SourceFile,
 } from "@typescript/native/ast";
+import { namesImported } from "./import-bindings.ts";
 import { nodeKey, type Inventory, type InventorySymbol } from "./inventory.ts";
-import { renderPosition } from "./position.ts";
 import { UNANSWERED } from "./query.ts";
 import { aliasFragment, nameComponent } from "./ref.ts";
-import type { Reference } from "./references.ts";
-import type { ProjectView } from "./session.ts";
+import type { Read, ReadRule } from "./references/read-rule.ts";
+import { isPathSpecifier } from "./paths.ts";
 
 /** Whether a node is a specifier's text: a string literal or a template with no substitution. */
 function literalText(node: Node | undefined): node is Node & { readonly text: string } {
@@ -58,33 +56,12 @@ function specifierOf(node: Node): (Node & { readonly text: string }) | undefined
   return undefined;
 }
 
-/**
- * The export names an import or a re-export reads from the module it names: none for a
- * namespace, a star or a bare form.
- */
-export function namesImported(node: Node): readonly string[] {
-  if (isImportDeclaration(node)) {
-    const clause = node.importClause;
-    const bindings = clause?.namedBindings;
-    return [
-      ...(clause?.name === undefined ? [] : ["default"]),
-      ...(bindings === undefined || isNamespaceImport(bindings)
-        ? []
-        : bindings.elements.map((one) => (one.propertyName ?? one.name).text)),
-    ];
-  }
-  const clause = isExportDeclaration(node) ? node.exportClause : undefined;
-  return clause === undefined || isNamespaceExport(clause)
-    ? []
-    : clause.elements.map((one) => (one.propertyName ?? one.name).text);
-}
-
 /**
  * Whether a specifier matches a declaration's name, the name's one `*` standing for any run.
  * A relative name is resolved against its own file, so no specifier names it by its text.
  */
 function namesModule(specifier: string, name: string): boolean {
-  if (/^(?:\.{1,2}(?:\/|$)|\/)/u.test(name)) {
+  if (isPathSpecifier(name)) {
     return false;
   }
   const star = name.indexOf("*");
@@ -161,76 +138,75 @@ interface Declared {
 }
 
 /**
- * The references the imports of one project's own files make to the module declarations
- * they name, each at the import's specifier.
+ * The reads the imports of a side's files make of the module declarations of the target they
+ * name, each at the import's specifier. A specifier the checker leaves unanswered still names
+ * a declaration by its name or pattern.
  */
-export function moduleDeclarationReferences<Brand>(
-  project: ProjectView<Brand>,
-  held: Inventory,
-  root: string,
-  testFiles: ReadonlySet<string>,
-): readonly Reference[] {
-  const imports: Import[] = [];
-  const declared: Declared[] = [];
-  for (const file of project.ownSourceFiles()) {
-    const fileId = held.declarations.get(nodeKey(file, file));
-    if (fileId === undefined) {
-      continue;
-    }
-    const visit = (node: Node, from: string): void => {
-      const own = held.declarations.get(nodeKey(file, node));
-      if (isModuleDeclaration(node) && literalText(node.name) && own !== undefined) {
-        declared.push({ id: own, name: node.name });
-      }
-      const specifier = specifierOf(node);
-      if (specifier !== undefined) {
-        imports.push({ file, from, specifier, names: namesImported(node) });
-      }
-      node.forEachChild((child) => {
-        visit(child, own ?? from);
-      });
-    };
-    file.forEachChild((child) => {
-      visit(child, fileId);
-    });
-  }
-  if (declared.length === 0 || imports.length === 0) {
-    return [];
-  }
-
-  const asked = [...declared.map((one) => one.name), ...imports.map((one) => one.specifier)];
-  const answers = project.symbolsAt(asked.map((node) => project.handle(node)));
-  const moduleOf = (at: number): number | undefined => {
-    const symbol = answers[at];
-    return symbol === undefined || symbol === UNANSWERED ? undefined : symbol.id;
-  };
-
-  const named = namedBy(held);
-  const found: Reference[] = [];
-  imports.forEach((one, index) => {
-    const resolved = moduleOf(declared.length + index);
-    const position = renderPosition(one.file, root, one.specifier.getStart());
-    const read = (to: string, resolution: Reference["resolution"], test: boolean): void => {
-      found.push({ from: one.from, to, position, use: "read", resolution, test });
-    };
-    const test = testFiles.has(position.path);
-    const same = new Set(
-      declared
-        .filter((_, at) => resolved !== undefined && resolved === moduleOf(at))
-        .map((declaration) => declaration.id),
-    );
-    for (const id of same) {
-      read(id, "batch", test);
-    }
-    for (const declaration of named(one.specifier.text, one.names)) {
-      // A wildcard declaration is how the compiler types the file a matching specifier
-      // names, so the import uses it whoever writes it, a test included.
-      if (declaration.wildcard || !same.has(declaration.id)) {
-        for (const to of [declaration.id, ...declaration.members]) {
-          read(to, "syntax", test && !declaration.wildcard);
+export const moduleDeclarations: ReadRule = {
+  start() {
+    const imports: Import[] = [];
+    return {
+      visit(node, { file, from }) {
+        const specifier = specifierOf(node);
+        if (specifier !== undefined) {
+          imports.push({ file, from, specifier, names: namesImported(node) });
         }
-      }
-    }
-  });
-  return found;
-}
+      },
+      reads({ project, held }) {
+        const found: Read[] = [];
+        // A module declaration whose name is a string is written at a file's top level.
+        const declared: Declared[] = project.ownSourceFiles().flatMap((file) =>
+          file.statements.flatMap((statement) => {
+            const id = held.declarations.get(nodeKey(file, statement));
+            return isModuleDeclaration(statement) && literalText(statement.name) && id !== undefined
+              ? [{ id, name: statement.name }]
+              : [];
+          }),
+        );
+        if (declared.length === 0 || imports.length === 0) {
+          return found;
+        }
+        const asked = [...declared.map((one) => one.name), ...imports.map((one) => one.specifier)];
+        const answers = project.symbolsAt(asked.map((node) => project.handle(node)));
+        const moduleOf = (at: number): number | undefined => {
+          const symbol = answers[at];
+          return symbol === undefined || symbol === UNANSWERED ? undefined : symbol.id;
+        };
+        const named = namedBy(held);
+        imports.forEach((one, index) => {
+          const resolved = moduleOf(declared.length + index);
+          const read = (to: string, via: "batch" | "syntax", production: boolean): void => {
+            found.push({
+              kind: "named",
+              from: one.from,
+              to,
+              file: one.file,
+              at: one.specifier,
+              use: "read",
+              via,
+              ...(production ? { production: true as const } : {}),
+            });
+          };
+          const same = new Set(
+            declared
+              .filter((_, at) => resolved !== undefined && resolved === moduleOf(at))
+              .map((declaration) => declaration.id),
+          );
+          for (const id of same) {
+            read(id, "batch", false);
+          }
+          for (const declaration of named(one.specifier.text, one.names)) {
+            // A wildcard declaration is how the compiler types the file a matching specifier
+            // names, so the import uses it whoever writes it, a test included.
+            if (declaration.wildcard || !same.has(declaration.id)) {
+              for (const to of [declaration.id, ...declaration.members]) {
+                read(to, "syntax", declaration.wildcard);
+              }
+            }
+          }
+        });
+        return found;
+      },
+    };
+  },
+};

package/src/overrides.ts

@@ -15,14 +15,14 @@ import {
   SyntaxKind,
   type HeritageClauseElement,
   type Node,
+  type SourceFile,
 } from "@typescript/native/ast";
-import type { AliasChains } from "./alias-chain.ts";
 import { memberComponent } from "./class-members.ts";
-import { nodeKey, type Inventory, type InventorySymbol } from "./inventory.ts";
+import { nodeKey, type InventorySymbol } from "./inventory.ts";
 import { SymbolFlags, type Symbol as TSSymbol, type Type } from "@typescript/native/sync";
 import { UNANSWERED } from "./query.ts";
 import { nameComponent } from "./ref.ts";
-import type { Reference } from "./references.ts";
+import type { Read, ReadRule } from "./references/read-rule.ts";
 import type { ProjectView } from "./session.ts";
 
 const CLASS_DECLARATIONS: ReadonlySet<SyntaxKind> = new Set([
@@ -41,141 +41,157 @@ function nameOf(entry: HeritageClauseElement): Node {
   return isQualifiedName(entry.typeName) ? entry.typeName.right : entry.typeName;
 }
 
-/** Each class of the target whose `extends` clause names a class, with the name node. */
-function extending<Brand>(
-  project: ProjectView<Brand>,
-  held: Inventory,
-): readonly { readonly id: string; readonly base: Node }[] {
-  const found: { id: string; base: Node }[] = [];
-  for (const file of project.ownSourceFiles()) {
-    const visit = (node: Node): void => {
-      if (isClassDeclaration(node) || isClassExpression(node)) {
-        const id = held.declarations.get(nodeKey(file, node));
-        const clause = node.heritageClauses?.find((one) => one.token === SyntaxKind.ExtendsKeyword);
-        const base = clause?.types[0];
-        if (id !== undefined && base !== undefined) {
-          found.push({ id, base: nameOf(base) });
-        }
-      }
-      node.forEachChild(visit);
-    };
-    file.forEachChild(visit);
-  }
-  return found;
+/** One class whose `extends` clause names a class, with the name node and its file. */
+interface Extending {
+  readonly node: Node;
+  readonly file: SourceFile;
+  readonly base: Node;
 }
 
 /**
- * The references each base class member makes to its overrides, for the classes of one
- * project that extend another class of the target, and each class makes to its members
- * that override a member of a class declared outside the target. A member a nearer base
- * already overrides is reached through that override. A private member is not
- * overridden. Each reference is placed at the override and made by its file.
+ * The reads each base class member makes of its overrides, for the classes of the target that
+ * extend another class of the target, and each class makes of its members that override a
+ * member of a class declared outside the target. A member a nearer base already overrides is
+ * reached through that override. A private member is not overridden. Each read is placed at
+ * the override. A class whose base the checker leaves unanswered holds every member it could
+ * override.
  */
-export function overrideReferences<Brand>(
-  project: ProjectView<Brand>,
-  held: Inventory,
-  chains: AliasChains,
-  testFiles: ReadonlySet<string>,
-): readonly Reference[] {
-  const classes = extending(project, held);
-  if (classes.length === 0) {
-    return [];
-  }
-  const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
-  const members = new Map<string, Map<string, InventorySymbol>>();
-  for (const symbol of held.symbols) {
-    const component = memberComponent(symbol, byId);
-    if (
-      component === undefined ||
-      !OVERRIDABLE.has(symbol.kind) ||
-      symbol.visibility === "private" ||
-      symbol.visibility === "private-name"
-    ) {
-      continue;
-    }
-    const own = members.get(symbol.parent) ?? new Map<string, InventorySymbol>();
-    own.set(component, symbol);
-    members.set(symbol.parent, own);
-  }
-  const bases = new Map<string, readonly string[]>();
-  const outsideBases = new Map<string, TSSymbol>();
-  const own = project.ownPaths();
-  const symbols = project.symbolsAt(classes.map((one) => project.handle(one.base)));
-  classes.forEach(({ id }, index) => {
-    const symbol = symbols[index];
-    if (symbol !== undefined && symbol !== UNANSWERED) {
-      const inTarget = chains
-        .chainOf(symbol)
-        .map((target) => target.id)
-        .filter((target) => byId.get(target)?.kind === "class" && target !== id);
-      bases.set(id, inTarget);
-      const declared =
-        (symbol.flags & SymbolFlags.Alias) === 0 ? symbol : project.queries.aliased(symbol);
-      if (
-        inTarget.length === 0 &&
-        declared !== UNANSWERED &&
-        (((declared.flags & SymbolFlags.Class) !== 0 &&
-          // The target's augmentation of an outside class merges an interface into it,
-          // so only a class declaration says where the class is.
-          declared.declarations.some(
-            (handle) => CLASS_DECLARATIONS.has(handle.kind) && !own.has(handle.path),
-          )) ||
-          ((declared.flags & SymbolFlags.Interface) !== 0 &&
-            declared.declarations.some(
-              (handle) => handle.kind === SyntaxKind.VariableDeclaration && !own.has(handle.path),
-            )))
-      ) {
-        outsideBases.set(id, declared);
-      }
-    }
-  });
-
-  /** The nearest member of one component the class or a class it extends declares. */
-  const declaredAbove = (classId: string, component: string, seen: Set<string>): string[] => {
-    if (seen.has(classId)) {
-      return [];
-    }
-    seen.add(classId);
-    const own = members.get(classId)?.get(component);
-    if (own !== undefined) {
-      return [own.id];
-    }
-    return (bases.get(classId) ?? []).flatMap((base) => declaredAbove(base, component, seen));
-  };
-
-  const found: Reference[] = [];
-  const outsideNames = outsideMemberNames(project, bases, outsideBases);
-  for (const [classId, names] of outsideNames) {
-    for (const [component, member] of members.get(classId) ?? []) {
-      if (names.has(component)) {
-        found.push({
-          from: classId,
-          to: member.id,
-          position: member.position,
-          use: "read",
-          resolution: "override",
-          test: testFiles.has(member.position.path),
+export const overrides: ReadRule = {
+  start() {
+    const extending: Extending[] = [];
+    return {
+      visit(node, { file }) {
+        if (isClassDeclaration(node) || isClassExpression(node)) {
+          const clause = node.heritageClauses?.find(
+            (one) => one.token === SyntaxKind.ExtendsKeyword,
+          );
+          const base = clause?.types[0];
+          if (base !== undefined) {
+            extending.push({ node, file, base: nameOf(base) });
+          }
+        }
+      },
+      reads({ project, held, chains }) {
+        const found: Read[] = [];
+        const classes = extending.flatMap((one) => {
+          const id = held.declarations.get(nodeKey(one.file, one.node));
+          return id === undefined ? [] : [{ ...one, id }];
         });
-      }
-    }
-  }
-  for (const [classId, baseIds] of bases) {
-    for (const [component, member] of members.get(classId) ?? []) {
-      const seen = new Set([classId]);
-      for (const base of baseIds.flatMap((one) => declaredAbove(one, component, seen))) {
-        found.push({
-          from: base,
-          to: member.id,
-          position: member.position,
-          use: "read",
-          resolution: "override",
-          test: testFiles.has(member.position.path),
+        if (classes.length === 0) {
+          return found;
+        }
+        const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
+        const members = new Map<string, Map<string, InventorySymbol>>();
+        for (const symbol of held.symbols) {
+          const component = memberComponent(symbol, byId);
+          if (
+            component === undefined ||
+            !OVERRIDABLE.has(symbol.kind) ||
+            symbol.visibility === "private" ||
+            symbol.visibility === "private-name"
+          ) {
+            continue;
+          }
+          const own = members.get(symbol.parent) ?? new Map<string, InventorySymbol>();
+          own.set(component, symbol);
+          members.set(symbol.parent, own);
+        }
+        const bases = new Map<string, readonly string[]>();
+        const outsideBases = new Map<string, TSSymbol>();
+        const fileOf = new Map(classes.map((one) => [one.id, one.file]));
+        const own = project.ownPaths();
+        const unanswered = new Set<string>();
+        const symbols = project.symbolsAt(classes.map((one) => project.handle(one.base)));
+        classes.forEach(({ id }, index) => {
+          const symbol = symbols[index];
+          if (symbol === UNANSWERED) {
+            unanswered.add(id);
+            return;
+          }
+          if (symbol === undefined) {
+            return;
+          }
+          const inTarget = chains
+            .chainOf(symbol)
+            .map((target) => target.id)
+            .filter((target) => byId.get(target)?.kind === "class" && target !== id);
+          bases.set(id, inTarget);
+          const declared =
+            (symbol.flags & SymbolFlags.Alias) === 0 ? symbol : project.queries.aliased(symbol);
+          if (declared === UNANSWERED) {
+            unanswered.add(id);
+            return;
+          }
+          if (
+            inTarget.length === 0 &&
+            (((declared.flags & SymbolFlags.Class) !== 0 &&
+              // The target's augmentation of an outside class merges an interface into it,
+              // so only a class declaration says where the class is.
+              declared.declarations.some(
+                (handle) => CLASS_DECLARATIONS.has(handle.kind) && !own.has(handle.path),
+              )) ||
+              ((declared.flags & SymbolFlags.Interface) !== 0 &&
+                declared.declarations.some(
+                  (handle) =>
+                    handle.kind === SyntaxKind.VariableDeclaration && !own.has(handle.path),
+                )))
+          ) {
+            outsideBases.set(id, declared);
+          }
         });
-      }
-    }
-  }
-  return found;
-}
+
+        /** The nearest member of one component the class or a class it extends declares. */
+        const declaredAbove = (classId: string, component: string, seen: Set<string>): string[] => {
+          if (seen.has(classId)) {
+            return [];
+          }
+          seen.add(classId);
+          const member = members.get(classId)?.get(component);
+          if (member !== undefined) {
+            return [member.id];
+          }
+          return (bases.get(classId) ?? []).flatMap((base) => declaredAbove(base, component, seen));
+        };
+
+        const read = (classId: string, from: string, member: InventorySymbol): void => {
+          const file = fileOf.get(classId);
+          if (file !== undefined) {
+            found.push({
+              kind: "named",
+              from,
+              to: member.id,
+              file,
+              at: member.position,
+              use: "read",
+              via: "override",
+            });
+          }
+        };
+        const outside = outsideMemberNames(project, bases, outsideBases);
+        for (const classId of [...unanswered, ...outside.unanswered]) {
+          const ids = [...(members.get(classId)?.values() ?? [])].map((member) => member.id);
+          found.push({ kind: "held", from: classId, ids });
+        }
+        for (const [classId, names] of outside.names) {
+          for (const [component, member] of members.get(classId) ?? []) {
+            if (names.has(component)) {
+              read(classId, classId, member);
+            }
+          }
+        }
+        for (const [classId, baseIds] of bases) {
+          for (const [component, member] of members.get(classId) ?? []) {
+            const seen = new Set([classId]);
+            for (const base of baseIds.flatMap((one) => declaredAbove(one, component, seen))) {
+              read(classId, base, member);
+            }
+          }
+        }
+        return found;
+      },
+    };
+  },
+};
 
 /**
  * Per class of the target with a class declared outside the target in its `extends`
@@ -186,12 +202,24 @@ function outsideMemberNames<Brand>(
   project: ProjectView<Brand>,
   bases: ReadonlyMap<string, readonly string[]>,
   outsideBases: ReadonlyMap<string, TSSymbol>,
-): ReadonlyMap<string, ReadonlySet<string>> {
+): {
+  readonly names: ReadonlyMap<string, ReadonlySet<string>>;
+  readonly unanswered: readonly string[];
+} {
   const direct = new Map<string, ReadonlySet<string>>();
+  const unanswered: string[] = [];
   const error = errorType(project);
   for (const [classId, base] of outsideBases) {
     const instance = project.queries.declaredTypeOf(base);
     const statics = project.queries.typeOfSymbol(base);
+    if (
+      instance === UNANSWERED ||
+      statics === UNANSWERED ||
+      project.queries.propertiesOf(instance) === UNANSWERED ||
+      (statics !== undefined && project.queries.propertiesOf(statics) === UNANSWERED)
+    ) {
+      unanswered.push(classId);
+    }
     const components = [
       ...namesOf(project, instance === UNANSWERED ? undefined : instance).map(nameComponent),
       ...(instance !== UNANSWERED && reaches(project, instance, error) ? ["toString"] : []),
@@ -220,7 +248,7 @@ function outsideMemberNames<Brand>(
       names.set(classId, found);
     }
   }
-  return names;
+  return { names, unanswered };
 }
 
 /** The global `Error` instance type's identifier, where the program's library declares one. */

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,6 +149,18 @@ export function resolvePath(against: string, path: string): string {
   return isAbsolutePath(path) ? normalizePath(path) : joinPath(against, path);
 }
 
+/**
+ * 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 (!isPathRelativeURL(reference)) {
+    return undefined;
+  }
+  const cut = reference.search(/[?#]/u);
+  return resolvePath(dir, cut < 0 ? reference : reference.slice(0, cut));
+}
+
 /**
  * The relative path before the query of a relative module specifier such as
  * `./worker.ts?worker`, the module a bundler loads; undefined for a specifier with no
@@ -105,7 +169,7 @@ export function resolvePath(against: string, path: string): string {
  */
 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