@cplieger/deadset-ts 7.2.0-dev.4 → 8.0.0-dev.1

package/src/discover.ts

@@ -1,11 +1,13 @@
 import { DiagnosticCategory } from "@typescript/native/sync";
 import type { Diagnostic } from "@typescript/native/sync";
+import { baseUrlPaths } from "./base-url.ts";
 import type { BuildConfiguration, ProjectConfiguration } from "./config.ts";
 import type { Host } from "./host.ts";
-import { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.ts";
+import { dirnamePath, isAbsolutePath, joinPath, relativePath, resolvePath } from "./paths.ts";
 import type { Scope } from "./scope.ts";
 import { SetupError } from "./setup-failure.ts";
 import type { Engine, ProjectDiagnostics } from "./session.ts";
+import { writtenPath, type WorkspaceProgram } from "./workspace-programs.ts";
 
 /** Directory names discovery does not descend into. */
 export const IGNORED_DIRECTORIES: ReadonlySet<string> = new Set(["node_modules", ".git"]);
@@ -112,10 +114,18 @@ interface ProjectErrors {
 
 /**
  * The codes of a type library and a lib the configuration names that the compiler
- * cannot find, which it reports while it gathers the program's files:
- * https://github.com/microsoft/typescript-go/blob/89d5d5b2849a0db0957065889ca58536fa6d2e4a/internal/compiler/processingDiagnostic.go
+ * cannot find, which it reports while it gathers the program's files,
+ * https://github.com/microsoft/typescript-go/blob/89d5d5b2849a0db0957065889ca58536fa6d2e4a/internal/compiler/processingDiagnostic.go,
+ * and {@link MISSING_GLOBAL_TYPE}, which the checker reports.
  */
-const UNFOUND_LIBRARY: ReadonlySet<number> = new Set([2688, 2726, 2727]);
+const UNFOUND_LIBRARY: ReadonlySet<number> = new Set([2318, 2688, 2726, 2727]);
+
+/**
+ * The code of a global type the checker finds in no library the program holds. The checker
+ * types every use of one against nothing and places no error in the file, so the analysis
+ * skips each file of such a project whole.
+ */
+export const MISSING_GLOBAL_TYPE = 2318;
 
 /** The errors one open project carries, each located in the file it names. */
 export function projectErrors(sets: ProjectDiagnostics): ProjectErrors {
@@ -337,9 +347,110 @@ function derivedId(targetRoot: string, configFile: string): string {
   return relativePath(targetRoot, configFile) ?? configFile;
 }
 
+/**
+ * The code of a configuration whose `extends` chain returns to a configuration it already
+ * passed. The parse reports it and returns, and a snapshot opened from it never answers:
+ * https://github.com/microsoft/TypeScript/issues/64754
+ */
+const CIRCULAR_EXTENDS = 18000;
+
+type Parsed = ReturnType<Engine["parseConfigFile"]>;
+
+/** The configuration files one parsed configuration's own `extends` names by path. */
+function extendedPaths(parsed: Parsed, configFile: string): readonly string[] {
+  const { raw } = parsed as { readonly raw?: unknown };
+  const named: unknown = typeof raw === "object" && raw !== null ? Reflect.get(raw, "extends") : [];
+  return (Array.isArray(named) ? named : [named])
+    .filter((one): one is string => typeof one === "string")
+    .filter((one) => one.startsWith("./") || one.startsWith("../") || isAbsolutePath(one))
+    .map((one) => resolvePath(dirnamePath(configFile), one));
+}
+
+/**
+ * The `extends` chain from `configFile` to the first configuration it reaches twice, each
+ * link by path, or undefined where no chain written by path returns.
+ */
+function extendsCycle(
+  engine: Engine,
+  configFile: string,
+  parsed: Parsed,
+): readonly string[] | undefined {
+  const walk = (chain: readonly string[], at: Parsed): readonly string[] | undefined => {
+    for (const next of extendedPaths(at, chain.at(-1) ?? configFile)) {
+      if (chain.includes(next)) {
+        return [...chain, next];
+      }
+      let read: Parsed;
+      try {
+        read = engine.parseConfigFile(next);
+      } catch {
+        continue;
+      }
+      const cycle = walk([...chain, next], read);
+      if (cycle !== undefined) {
+        return cycle;
+      }
+    }
+    return undefined;
+  };
+  return walk([configFile], parsed);
+}
+
+/** The configuration files one parsed configuration's `references` name. */
+function referencesOf(parsed: Parsed): readonly string[] {
+  // The parse answers a directory reference as the directory; the compiler reads a
+  // path not ending `.json` as its `tsconfig.json`:
+  // https://github.com/microsoft/typescript-go/blob/89d5d5b2849a0db0957065889ca58536fa6d2e4a/internal/core/projectreference.go#L18
+  return (parsed.projectReferences ?? []).map(({ path }) =>
+    path.endsWith(".json") ? path : joinPath(path, "tsconfig.json"),
+  );
+}
+
+/** Why one parsed configuration's own `extends` chain cannot be opened, where it is circular. */
+function circularity(engine: Engine, configFile: string, parsed: Parsed): string | undefined {
+  const chain = extendsCycle(engine, configFile, parsed);
+  if (chain === undefined && !parsed.errors.some(({ code }) => code === CIRCULAR_EXTENDS)) {
+    return undefined;
+  }
+  return `TS${String(CIRCULAR_EXTENDS)}: Circularity detected while resolving configuration: ${(chain ?? [configFile]).join(" -> ")}`;
+}
+
+/**
+ * Why a configuration the `references` reach, transitively, cannot be opened, where one's
+ * `extends` chain is circular: the compiler opens every referenced project with the one
+ * that references it.
+ */
+function referencedCircularity(
+  engine: Engine,
+  references: readonly string[],
+  visited: Set<string>,
+): string | undefined {
+  for (const reference of references) {
+    if (visited.has(reference)) {
+      continue;
+    }
+    visited.add(reference);
+    let parsed: Parsed;
+    try {
+      parsed = engine.parseConfigFile(reference);
+    } catch {
+      continue;
+    }
+    const reason =
+      circularity(engine, reference, parsed) ??
+      referencedCircularity(engine, referencesOf(parsed), visited);
+    if (reason !== undefined) {
+      return reason;
+    }
+  }
+  return undefined;
+}
+
 /**
  * The configuration files one configuration's `references` name, or why the compiler
- * cannot read the configuration.
+ * cannot read the configuration: it throws, or its `extends` chain or that of a
+ * configuration it references is circular, which the analysis refuses before any
+ * snapshot is asked to open it.
  */
 function readConfiguration(
   engine: Engine,
@@ -347,14 +458,11 @@ function readConfiguration(
 ): { readonly references: readonly string[] } | { readonly reason: string } {
   try {
     const parsed = engine.parseConfigFile(configFile);
-    // The parse answers a directory reference as the directory; the compiler reads a
-    // path not ending `.json` as its `tsconfig.json`:
-    // https://github.com/microsoft/typescript-go/blob/89d5d5b2849a0db0957065889ca58536fa6d2e4a/internal/core/projectreference.go#L18
-    return {
-      references: (parsed.projectReferences ?? []).map(({ path }) =>
-        path.endsWith(".json") ? path : joinPath(path, "tsconfig.json"),
-      ),
-    };
+    const references = referencesOf(parsed);
+    const reason =
+      circularity(engine, configFile, parsed) ??
+      referencedCircularity(engine, references, new Set([configFile]));
+    return reason === undefined ? { references } : { reason };
   } catch (error: unknown) {
     return { reason: error instanceof Error ? error.message : String(error) };
   }
@@ -508,3 +616,38 @@ export function discoverProjects(
   }
   return derivedProjects(engine, host, scope);
 }
+
+/**
+ * How the snapshot reads each configuration of `configFiles` that sets `baseUrl` and
+ * `programs` does not already describe: a configuration only the snapshot holds, which
+ * extends it and states the `paths` {@link baseUrlPaths} gives, so its imports resolve as
+ * the compilers before version 7 resolve them. A configuration the compiler cannot read is
+ * left for its project to refuse.
+ */
+export function withBaseUrlPaths(
+  engine: Engine,
+  host: Host,
+  configFiles: readonly string[],
+  programs: ReadonlyMap<string, WorkspaceProgram>,
+): ReadonlyMap<string, WorkspaceProgram> {
+  const found = new Map(programs);
+  for (const configFile of configFiles) {
+    if (found.has(configFile)) {
+      continue;
+    }
+    let paths: Record<string, string[]> | undefined;
+    try {
+      paths = baseUrlPaths(engine.parseConfigFile(configFile).options);
+    } catch {
+      continue;
+    }
+    if (paths !== undefined) {
+      found.set(configFile, {
+        kind: "configuration",
+        file: writtenPath(host, configFile),
+        text: `${JSON.stringify({ extends: configFile, compilerOptions: { paths } }, null, 2)}\n`,
+      });
+    }
+  }
+  return found;
+}

package/src/entry-point-gaps.ts

@@ -58,7 +58,6 @@ const UNREAD_TOOLS: readonly string[] = [
   "cypress",
   "danger",
   "dependency-cruiser",
-  "docusaurus",
   "dotenv",
   "drizzle",
   "electron-vite",
@@ -112,14 +111,12 @@ const UNREAD_TOOLS: readonly string[] = [
   "nuxtjs-i18n",
   "nx",
   "nyc",
-  "oclif",
   "openapi-ts",
   "openclaw",
   "orval",
   "oxfmt",
   "oxlint",
   "panda-css",
-  "parcel",
   "payload",
   "pino",
   "playwright-ct",
@@ -164,7 +161,6 @@ const UNREAD_TOOLS: readonly string[] = [
   "swc",
   "syncpack",
   "tailwind",
-  "tanstack-router",
   "taskfile",
   "tauri",
   "temporal",
@@ -210,18 +206,19 @@ const UNREAD_TOOLS: readonly string[] = [
 /** The conventions declined for a tool some of whose conventions are entered. */
 const PARTLY_ENTERED: readonly DeclinedConvention[] = [
   {
-    tool: "eslint",
-    convention: "a legacy configuration written in YAML or in JSON with comments",
+    tool: "docusaurus",
+    convention: "a page or theme directory a plugin's configuration moves, and the docs",
     reason:
-      "Only a configuration module and a strict JSON configuration file are read, so a " +
-      "dependency only such a file names is reported as unused.",
+      "The convention row reads src/pages and src/theme only, and a document's imports are " +
+      "read from every Markdown and MDX file, so a module only a moved directory holds is " +
+      "reported as never imported unless ts.entry_files names it.",
   },
   {
     tool: "eslint",
-    convention: "a plugin or shareable configuration named without its package's prefix",
+    convention: "a legacy configuration written in YAML or in JSON with comments",
     reason:
-      "A string uses a dependency only where it spells the dependency's name, so a " +
-      "dependency only a shortened name loads is reported as unused.",
+      "Only a configuration module and a strict JSON configuration file are read, so a " +
+      "dependency only such a file names is reported as unused.",
   },
   {
     tool: "playwright",

package/src/entry-points.ts

@@ -14,6 +14,7 @@
 import {
   isArrayLiteralExpression,
   isAsExpression,
+  isBinaryExpression,
   isCallExpression,
   isExportAssignment,
   isIdentifier,
@@ -26,6 +27,8 @@ import {
   isPropertyAssignment,
   isSatisfiesExpression,
   isStringLiteral,
+  isTemplateExpression,
+  SyntaxKind,
   type Node,
   type SourceFile,
 } from "@typescript/native/ast";
@@ -40,6 +43,7 @@ import type { Selected } from "./conventions.ts";
 import { globExpression } from "./glob.ts";
 import type { Host } from "./host.ts";
 import { htmlEntries } from "./html-entries.ts";
+import { documentEntries } from "./mdx-entries.ts";
 import { dirnamePath, relativePath, resolvePath } from "./paths.ts";
 import { UNANSWERED } from "./query.ts";
 import type { ProjectView } from "./session.ts";
@@ -61,7 +65,15 @@ export type EntryRule =
   /** A file a module script of an HTML file below the target root loads. */
   | "html-entry"
   /** A file a `run:` step of a workflow in the target root's `.github/workflows` names. */
-  | "workflow-step";
+  | "workflow-step"
+  /**
+   * A file a load whose path is computed may name: below the directory the literal
+   * start of an `import()` or `require()` argument names, or matched by the literal
+   * glob of `import.meta.glob`.
+   */
+  | "computed-import"
+  /** A file an import line of a Markdown or MDX document below the target root names. */
+  | "document-import";
 
 /** One file a rule enters. */
 interface EntryPoint {
@@ -78,6 +90,8 @@ interface EntryPoint {
    * level and names none of its exports.
    */
   readonly exports: boolean;
+  /** Where the file is entered for some of its exports only, their export names. */
+  readonly names?: readonly string[];
 }
 
 /** One file-name convention: the stems a tool looks for, under each extension it loads. */
@@ -114,8 +128,11 @@ const SETUP_MEMBERS = ["setupFiles", "globalSetup"] as const;
 /** A member that moves the directory every path of a test-runner configuration is read from. */
 const ROOT_MEMBER = "root";
 
-/** The prefixes a literal is relative with, in a module specifier and a URL reference alike. */
-const RELATIVE_PREFIXES = ["./", "../"] as const;
+/**
+ * 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 constructors whose first argument addresses a worker script. */
 const WORKER_CONSTRUCTORS: ReadonlySet<string> = new Set(["Worker", "SharedWorker"]);
@@ -228,9 +245,17 @@ function literalsOf(value: Node): readonly string[] | undefined {
   return found;
 }
 
-/** Whether a literal is relative in the sense a module specifier and a URL reference share. */
+/**
+ * Whether a literal is a relative URL reference, which is also how the test runner reads a
+ * setup file's path against its root.
+ */
 function isRelative(text: string): boolean {
-  return RELATIVE_PREFIXES.some((prefix) => text.startsWith(prefix));
+  return text !== "" && !text.startsWith("/") && !URL_SCHEME.test(text);
+}
+
+/** Whether a module specifier is relative, which a bare name is not: it names a package. */
+function isModuleRelative(text: string): boolean {
+  return text.startsWith("./") || text.startsWith("../");
 }
 
 /** A URL reference with its query and its fragment removed, which name no part of the file. */
@@ -470,10 +495,10 @@ function workerSitesOf(file: SourceFile): readonly WorkerSite[] {
 }
 
 /**
- * The workers one file addresses. A call's names must resolve to the platform's own
- * declarations, which no file of the target declares and no import brings in; a
- * name the target binds itself is the target's own constructor or object, which
- * addresses no worker this rule knows. One batch per file that writes such a call.
+ * The workers one file addresses. A call's names must resolve to a symbol the platform
+ * declares, which a file of the target may augment and no import brings in; a name only
+ * the target declares is the target's own constructor or object, which addresses no
+ * worker this rule knows. One batch per file that writes such a call.
  */
 function workersOf<Brand>(
   project: ProjectView<Brand>,
@@ -498,8 +523,7 @@ function workersOf<Brand>(
     if (
       symbol !== undefined &&
       (symbol.flags & SymbolFlags.Alias) === 0 &&
-      symbol.declarations.length > 0 &&
-      symbol.declarations.every((handle) => !files.byName.has(handle.path))
+      symbol.declarations.some((handle) => !files.byName.has(handle.path))
     ) {
       platform.add(name);
     }
@@ -517,6 +541,94 @@ function workersOf<Brand>(
   return found;
 }
 
+/** The literal text a computed path starts with: a template's head, or a concatenation's first literal. */
+function leadingLiteral(node: Node): string | undefined {
+  const at = unwrapped(node);
+  if (isTemplateExpression(at)) {
+    return at.head.text;
+  }
+  if (isBinaryExpression(at) && at.operatorToken.kind === SyntaxKind.PlusToken) {
+    return literalOf(unwrapped(at.left)) ?? leadingLiteral(at.left);
+  }
+  return undefined;
+}
+
+/** Whether one call is `import.meta.glob(...)`. */
+function isMetaGlob(node: Node): boolean {
+  if (!isCallExpression(node) || !isPropertyAccessExpression(node.expression)) {
+    return false;
+  }
+  const { expression, name } = node.expression;
+  return (
+    isIdentifier(name) &&
+    name.text === "glob" &&
+    isMetaProperty(expression) &&
+    expression.keywordToken === SyntaxKind.ImportKeyword
+  );
+}
+
+/**
+ * The files one file loads by a computed path, each with what exports: every own file
+ * below the directory a relative literal start of an `import()` or `require()` argument
+ * names, other than the calling file's own directory or one holding it, which would name
+ * every sibling, and
+ * every own file a relative literal glob of `import.meta.glob` matches, both read against
+ * the calling file's directory, as a bundler's context module reads them.
+ */
+function computedImportsOf(file: SourceFile, files: SourceFiles): readonly EntryPoint[] {
+  const dir = dirnamePath(file.fileName);
+  const found: EntryPoint[] = [];
+  const below = (prefix: string): void => {
+    const target = resolvePath(dir, prefix);
+    if (
+      !isModuleRelative(prefix) ||
+      !prefix.endsWith("/") ||
+      target === dir ||
+      relativePath(target, dir) !== undefined
+    ) {
+      return;
+    }
+    for (const candidate of files.byName.values()) {
+      if (candidate !== file && relativePath(target, candidate.fileName) !== undefined) {
+        found.push({ file: candidate, rule: "computed-import", source: prefix, exports: true });
+      }
+    }
+  };
+  const globbed = (pattern: string): void => {
+    if (!isModuleRelative(pattern)) {
+      return;
+    }
+    const expression = globExpression(resolvePath(dir, pattern));
+    for (const candidate of files.byName.values()) {
+      if (candidate !== file && expression.test(candidate.fileName)) {
+        found.push({ file: candidate, rule: "computed-import", source: pattern, exports: true });
+      }
+    }
+  };
+  const visit = (node: Node): void => {
+    if (isCallExpression(node)) {
+      const [first] = node.arguments;
+      const callee = node.expression;
+      const loads =
+        callee.kind === SyntaxKind.ImportKeyword ||
+        (isIdentifier(callee) && callee.text === "require");
+      if (loads && first !== undefined) {
+        const prefix = leadingLiteral(first);
+        if (prefix !== undefined) {
+          below(prefix);
+        }
+      } else if (isMetaGlob(node) && first !== undefined) {
+        for (const pattern of literalsOf(first) ?? []) {
+          globbed(pattern);
+        }
+      }
+    }
+    node.forEachChild(visit);
+  };
+  file.forEachChild(visit);
+  return found;
+}
+
 /**
  * Every file of one project the rules enter, in no particular order and possibly more
  * than once: a file two rules enter appears once per rule.
@@ -554,10 +666,20 @@ export function entryPoints<Brand>(
       }
     }
     found.push(...workersOf(project, file, files));
+    found.push(...computedImportsOf(file, files));
   }
   for (const { file, source } of htmlEntries(host, targetRoot, files, parse)) {
     found.push({ file, rule: "html-entry", source, exports: true });
   }
+  for (const { file, source, names } of documentEntries(host, targetRoot, files)) {
+    found.push({
+      file,
+      rule: "document-import",
+      source,
+      exports: true,
+      ...(names === undefined ? {} : { names }),
+    });
+  }
   for (const { file, source } of workflowEntries(host, targetRoot, files)) {
     found.push({ file, rule: "workflow-step", source, exports: true });
   }

package/src/finding.ts

@@ -34,6 +34,12 @@ interface FindingSubject {
   readonly name: string;
   /** The number of source lines the subject spans. */
   readonly sizeLines: number;
+  /**
+   * Where the subject is a part whose reference is its own, a parameter's, the reference
+   * of the declaration that holds it, which a record binding that declaration matches.
+   * No report carries it.
+   */
+  readonly holder?: string;
 }
 
 /** A declaration a finding names beside the subject, with where it is written. */
@@ -87,6 +93,10 @@ export interface Finding {
   readonly details?: FindingDetails;
   /** The reachability class of a subject that is no declaration, where it is not `certain`. */
   readonly reachabilityClass?: Confidence;
+  /** Whether references to a subject that is no declaration exist, all from dead code. */
+  readonly unreachableOnly?: true;
+  /** The dead declarations and files whose component a subject that is no declaration falls with. */
+  readonly fallsWith?: readonly string[];
 }
 
 /** The dead component a finding names, as the finding schema spells its members. */