@cplieger/deadset-ts 8.0.0-dev.2 → 8.0.0-dev.20

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/partial.ts

@@ -1,6 +1,7 @@
-import type { NotBuilt } from "./discover.ts";
+import type { NotBuilt } from "./load/discover.ts";
 import { relativePath } from "./paths.ts";
 import type { UnansweredQuestion } from "./query.ts";
+import { bytewise } from "./text/compare.ts";
 
 /** What a run read only in part. */
 interface Partial {
@@ -24,7 +25,7 @@ function counted(n: number, one: string, many: string): string {
  */
 export function partialNotes(partial: Partial): readonly string[] {
   const notes = [...partial.notBuilt]
-    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+    .sort((a, b) => bytewise(a.id, b.id))
     .map(
       (one) =>
         `the derived configuration ${one.id} was not built and is not analyzed: ${one.error}`,

package/src/paths.ts

@@ -1,11 +1,7 @@
 /**
- * Filesystem paths, as the supported platform spells them: a solidus separates
- * segments and a leading solidus makes a path absolute.
- *
- * They are written here rather than taken from the platform's own library because
- * every module below the command line stays free of the platform, and because the
- * supported platform set is one, so a second spelling would be a rule nothing
- * exercises.
+ * Filesystem paths as the supported platform spells them: a solidus between segments, a
+ * leading one for an absolute path. They are written here rather than taken from the
+ * platform's library so every module below the command line stays free of the platform.
  */
 
 const SEPARATOR = "/";
@@ -15,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
@@ -67,6 +115,25 @@ export function dirnamePath(path: string): string {
   return cut === 0 ? SEPARATOR : normalized.slice(0, cut);
 }
 
+/**
+ * `dir` and every directory above it, nearest first, normalized. With `top`, the list ends
+ * at `top` and is empty where `dir` is neither `top` nor below it; without, it ends at the
+ * root of the path.
+ */
+export function ancestors(dir: string, top?: string): readonly string[] {
+  const end = top === undefined ? undefined : normalizePath(top);
+  const found: string[] = [];
+  for (let at = normalizePath(dir); ; at = dirnamePath(at)) {
+    if (end !== undefined && at !== end && relativePath(end, at) === undefined) {
+      return [];
+    }
+    found.push(at);
+    if (at === end || dirnamePath(at) === at) {
+      return found;
+    }
+  }
+}
+
 /**
  * The extension of one path's last segment, from its last full stop, or the empty string
  * where it has none. A segment that only starts with a full stop has none.
@@ -82,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
@@ -90,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
@@ -101,14 +180,11 @@ export function queriedModulePath(specifier: string): string | undefined {
 }
 
 /**
- * One path as it reads below a root, or undefined when it is not below the root.
- * Both are normalized first, so a root written with a trailing separator or a `.`
- * segment reaches the same answer, and the comparison is then lexical, so a root
- * and a path spelled through different symbolic links name nothing in common. The
- * root itself is not below itself.
- *
- * The caller resolves both against the same directory before calling: a relative
- * root and an absolute path are two spellings this cannot reconcile.
+ * One path as it reads below a root, or undefined when it is not strictly below the root:
+ * the root itself is not below itself. Both are normalized, then compared lexically, so a
+ * root and a path spelled through different symbolic links name nothing in common. The
+ * caller resolves both against the same directory first: a relative root and an absolute
+ * path cannot be reconciled.
  */
 export function relativePath(root: string, path: string): string | undefined {
   const at = normalizePath(root);

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