@cplieger/deadset-ts 4.0.1 → 5.0.0

package/src/discover.ts

@@ -4,6 +4,7 @@ import type { BuildConfiguration, ProjectConfiguration } from "./config.ts";
 import type { Host } from "./host.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";
 
 /** Directory names discovery does not descend into. */
@@ -323,13 +324,16 @@ function derivedFrom(
  */
 export function consumerProjects(engine: Engine, host: Host, root: string): readonly string[] {
   const kind = host.kindOf(root);
+  if (kind === "absent") {
+    throw new SetupError([
+      {
+        setupClass: "missing-consumer",
+        detail: `the scope declares the consumer ${root}, and nothing is at that path: check the consumer out at ${root} and install its dependencies`,
+      },
+    ]);
+  }
   if (kind !== "directory") {
-    throw new DiscoveryError(
-      kind === "absent"
-        ? `the consumer ${root} does not exist`
-        : `the consumer ${root} is not a directory`,
-      [],
-    );
+    throw new DiscoveryError(`the consumer ${root} is not a directory`, []);
   }
   const found = derivedFrom(engine, host, configFilesUnder(host, root));
   if (found.length === 0) {

package/src/emit-map.ts

@@ -0,0 +1,93 @@
+/**
+ * Where the compiler writes what it compiles: the output extension each source
+ * extension becomes, and the output path one source path is written to. A path a
+ * manifest or a document names is read back to its source through this one rule,
+ * whether the path is the target's own or a workspace package's.
+ */
+
+import { dirnamePath, joinPath, relativePath } from "./paths.ts";
+
+/** The source extensions the compiler emits each output extension from. */
+const EMITTED: readonly { readonly emitted: string; readonly sources: readonly string[] }[] = [
+  { emitted: ".d.ts", sources: [".ts", ".tsx"] },
+  { emitted: ".d.mts", sources: [".mts"] },
+  { emitted: ".d.cts", sources: [".cts"] },
+  { emitted: ".js", sources: [".ts", ".tsx"] },
+  { emitted: ".jsx", sources: [".tsx"] },
+  { emitted: ".mjs", sources: [".mts"] },
+  { emitted: ".cjs", sources: [".cts"] },
+];
+
+/** Where one compiler configuration writes its output, and the directories it writes it from. */
+export interface EmitLayout {
+  /** The directory every output is written below, absolute. */
+  readonly outDir?: string | undefined;
+  /** The directory declaration outputs are written below where it differs, absolute. */
+  readonly declarationDir?: string | undefined;
+  /**
+   * The directories an output path below the output directory is read below, in the
+   * order they are tried: the one the configuration declares, or the ones the
+   * compiler's default may be.
+   */
+  readonly sourceDirs: readonly string[];
+}
+
+/** One path with its extension replaced, where it carries the one named. */
+function reExtended(path: string, emitted: string, source: string): string | undefined {
+  return path.endsWith(emitted) ? path.slice(0, path.length - emitted.length) + source : undefined;
+}
+
+/**
+ * The longest directory every path shares, which is where the compiler roots its
+ * output when the configuration declares no root directory and its directory is not
+ * the root.
+ */
+export function commonDirectory(paths: readonly string[]): string {
+  const first = paths[0];
+  if (first === undefined) {
+    return "";
+  }
+  let common = dirnamePath(first).split("/");
+  for (const path of paths.slice(1)) {
+    const segments = dirnamePath(path).split("/");
+    let shared = 0;
+    while (
+      shared < common.length &&
+      shared < segments.length &&
+      common[shared] === segments[shared]
+    ) {
+      shared += 1;
+    }
+    common = common.slice(0, shared);
+  }
+  return common.join("/");
+}
+
+/**
+ * The source paths one written path may be compiled from, in the order they are
+ * tried: for each output extension the path carries, the path re-extended where it
+ * stands, then read below each source directory where it is below the directory that
+ * output is written to.
+ */
+export function emittedFrom(path: string, layout: EmitLayout): readonly string[] {
+  const found: string[] = [];
+  for (const { emitted, sources } of EMITTED) {
+    if (!path.endsWith(emitted)) {
+      continue;
+    }
+    const emitDir = emitted.startsWith(".d.")
+      ? (layout.declarationDir ?? layout.outDir)
+      : layout.outDir;
+    const below = emitDir === undefined ? undefined : relativePath(emitDir, path);
+    const mapped = below === undefined ? [] : layout.sourceDirs.map((dir) => joinPath(dir, below));
+    for (const source of sources) {
+      for (const from of [path, ...mapped]) {
+        const candidate = reExtended(from, emitted, source);
+        if (candidate !== undefined) {
+          found.push(candidate);
+        }
+      }
+    }
+  }
+  return found;
+}

package/src/entry-point-gaps.ts

@@ -17,18 +17,23 @@ export interface DeclinedConvention {
   readonly reason: string;
 }
 
-/** What is declined for a tool none of whose conventions is entered. */
-const EVERY_CONVENTION = "its configuration and every file it loads by its own convention";
+/** What is declined for a tool whose own conventions are entered only through its configuration files. */
+const EVERY_CONVENTION = "every file it loads by its own convention beyond its configuration files";
 
-/** Why a tool none of whose conventions is entered declines them. */
+/** Why a tool whose own conventions are not read declines them. */
 const UNREAD =
-  "No rule reads it, so a file only it loads is reported as never imported unless " +
-  "ts.entry_files or roots.patterns names it.";
+  "No rule reads it beyond a configuration file the file-name form or a string enters, so a " +
+  "file only it loads is reported as never imported unless ts.entry_files or roots.patterns " +
+  "names it.";
 
-/** The tools none of whose conventions is entered. */
+/** Why a configuration's file names that are not relative literals are declined. */
+const NOT_RELATIVE =
+  "A string of a configuration file names a file only where it is a literal starting with ./ " +
+  "or ../, so a file named otherwise is reported as never imported.";
+
+/** The tools whose own conventions are not read. */
 const UNREAD_TOOLS: readonly string[] = [
   "angular",
-  "astro",
   "astro-db",
   "astro-markdoc",
   "astro-og-canvas",
@@ -61,7 +66,6 @@ const UNREAD_TOOLS: readonly string[] = [
   "esbuild",
   "eve",
   "execa",
-  "expo",
   "expressive-code",
   "fast",
   "fumadocs",
@@ -98,7 +102,6 @@ const UNREAD_TOOLS: readonly string[] = [
   "nano-staged",
   "nest",
   "netlify",
-  "next",
   "next-intl",
   "next-mdx",
   "nitro",
@@ -106,7 +109,6 @@ const UNREAD_TOOLS: readonly string[] = [
   "node-modules-inspector",
   "nodemon",
   "npm-package-json-lint",
-  "nuxt",
   "nuxtjs-i18n",
   "nx",
   "nyc",
@@ -131,17 +133,14 @@ const UNREAD_TOOLS: readonly string[] = [
   "prettier",
   "prisma",
   "quasar",
-  "qwik",
   "railway",
   "raycast",
   "react-cosmos",
   "react-email",
   "react-native",
-  "react-router",
   "relay",
   "release-it",
   "remark",
-  "remix",
   "rolldown",
   "rollup",
   "rsbuild",
@@ -157,11 +156,9 @@ const UNREAD_TOOLS: readonly string[] = [
   "sst",
   "starlight",
   "stencil",
-  "storybook",
   "stylelint",
   "svelte",
   "sveltejs-package",
-  "sveltekit",
   "svgo",
   "svgr",
   "swc",
@@ -184,7 +181,6 @@ const UNREAD_TOOLS: readonly string[] = [
   "typescript-content-mapper",
   "unbuild",
   "unocss",
-  "unplugin-auto-import",
   "unplugin-icons",
   "unplugin-vue-components",
   "unplugin-vue-i18n",
@@ -215,10 +211,17 @@ const UNREAD_TOOLS: readonly string[] = [
 const PARTLY_ENTERED: readonly DeclinedConvention[] = [
   {
     tool: "eslint",
-    convention: "the legacy .eslintrc configuration files",
+    convention: "a legacy configuration written in YAML or in JSON with comments",
+    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.",
+  },
+  {
+    tool: "eslint",
+    convention: "a plugin or shareable configuration named without its package's prefix",
     reason:
-      "Only the flat configuration's file names are entered, so a legacy configuration " +
-      "file the program holds is reported as never imported.",
+      "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.",
   },
   {
     tool: "playwright",
@@ -229,9 +232,8 @@ const PARTLY_ENTERED: readonly DeclinedConvention[] = [
   },
   {
     tool: "playwright",
-    convention: "the globalSetup and globalTeardown files",
-    reason:
-      "No rule enters them, so a setup file only the runner loads is reported as never imported.",
+    convention: "a globalSetup or globalTeardown file named without a leading ./ or ../",
+    reason: NOT_RELATIVE,
   },
   {
     tool: "playwright",
@@ -240,17 +242,73 @@ const PARTLY_ENTERED: readonly DeclinedConvention[] = [
       "Only the configuration object's own testDir and testMatch are read, so a test " +
       "directory a project entry moves is not entered.",
   },
+  {
+    tool: "expo",
+    convention: "an app directory the expo-router entry of an app configuration moves",
+    reason:
+      "The convention row reads the app directory at its default places only, so a route " +
+      "below a moved directory is reported as never imported unless ts.entry_files names it.",
+  },
+  {
+    tool: "next",
+    convention: "a page extension next.config adds through pageExtensions",
+    reason:
+      "The convention row roots the default extensions only, so a route file of another " +
+      "extension is reported as never imported unless ts.entry_files names it.",
+  },
+  {
+    tool: "nuxt",
+    convention: "the files of a layer below layers/ beyond its nuxt.config",
+    reason:
+      "The convention row reads the project's own directories, so a layer's pages, plugins " +
+      "and server routes are reported as never imported unless ts.entry_files names them.",
+  },
+  {
+    tool: "qwik",
+    convention: "the routes of @qwik.dev/router",
+    reason:
+      "No convention row holds for that package, so its route files are reported as " +
+      "never imported unless ts.entry_files names them.",
+  },
+  {
+    tool: "react-router",
+    convention: "a route module app/routes.ts names outside the routes directory",
+    reason:
+      "The convention row roots the routes directory, and a string of routes.ts names no " +
+      "file, so a route module elsewhere is reported as never imported unless " +
+      "ts.entry_files names it.",
+  },
+  {
+    tool: "storybook",
+    convention: "a story the stories member of .storybook/main names outside *.stories.* files",
+    reason:
+      "The convention row roots *.stories.* files, so a story file named otherwise is " +
+      "reported as never imported unless ts.entry_files names it.",
+  },
   {
     tool: "stryker",
-    convention: "a configuration file named on the command line",
-    reason: "Only the file names the tool looks for by default are entered.",
+    convention: "a configuration file named on a command line no package.json script writes",
+    reason:
+      "Only the file names the tool looks for by default and the files a script names are entered.",
+  },
+  {
+    tool: "unplugin-auto-import",
+    convention: "an import its generated declarations add for a component's template alone",
+    reason:
+      "Only a global declared as an alias of an export is read, so an export the generated " +
+      "declarations name only for templates is reported as unused.",
+  },
+  {
+    tool: "vite",
+    convention: "an entry point its configuration names without a leading ./ or ../, or computes",
+    reason: NOT_RELATIVE,
   },
   {
     tool: "vite",
-    convention: "its configuration and every entry point it names",
+    convention: "the module scripts an index.html loads",
     reason:
-      "Only a worker a call addresses by a literal is entered. No rule reads the " +
-      "configuration, so a file only it names is reported as never imported.",
+      "No rule reads an HTML file, so a script only index.html loads is reported as never " +
+      "imported unless ts.entry_files names it.",
   },
   {
     tool: "vitest",
@@ -261,17 +319,15 @@ const PARTLY_ENTERED: readonly DeclinedConvention[] = [
   },
   {
     tool: "vitest",
-    convention: "the mock files below a __mocks__ directory",
+    convention: "the setup files of a configuration that moves its root",
     reason:
-      "No rule enters a file by its directory, so a mock only the runner's module mocking " +
-      "loads is reported as never imported.",
+      "A string is read against the configuration file's directory, so a setup file named " +
+      "against a root the configuration moves is not entered.",
   },
   {
     tool: "vitest",
-    convention: "the setup files of a configuration that moves its root",
-    reason:
-      "A configuration writing root reads its setup files against a directory its text " +
-      "may not state, so none of them is entered.",
+    convention: "a setup file named without a leading ./ or ../",
+    reason: NOT_RELATIVE,
   },
   {
     tool: "vitest",
@@ -282,10 +338,8 @@ const PARTLY_ENTERED: readonly DeclinedConvention[] = [
   },
   {
     tool: "webpack",
-    convention: "its configuration and every entry point it names",
-    reason:
-      "Only a worker a call addresses by a literal is entered. No rule reads the " +
-      "configuration, so a file only it names is reported as never imported.",
+    convention: "an entry point its configuration names without a leading ./ or ../, or computes",
+    reason: NOT_RELATIVE,
   },
 ];
 

package/src/entry-points.ts

@@ -1,8 +1,8 @@
 /**
  * The files a tool or the platform enters without any import naming them: the
- * configuration files the test runner, the linter, the mutation tester and the
- * browser-test runner load by their file name, the test files the runner executes,
- * and a worker a call addresses by a string literal.
+ * configuration files a tool loads by their file name and the files their strings
+ * name, the test files the runner executes, and a worker a call addresses by a string
+ * literal.
  *
  * Each rule is read from the program and nothing else: a file name the tool
  * itself looks for, a literal written in a configuration file, or a literal
@@ -30,7 +30,9 @@ import {
   type SourceFile,
 } from "@typescript/native/unstable/ast";
 import { SymbolFlags } from "@typescript/native/unstable/sync";
+import { configurationFiles, filesNamedBy, moduleStrings } from "./configuration-files.ts";
 import { globExpression } from "./glob.ts";
+import type { Host } from "./host.ts";
 import { dirnamePath, relativePath, resolvePath } from "./paths.ts";
 import { UNANSWERED } from "./query.ts";
 import type { ProjectView } from "./session.ts";
@@ -38,13 +40,15 @@ import type { SourceFiles } from "./source-files.ts";
 
 /** Which rule entered a file. */
 export type EntryRule =
-  /** The test runner: its configuration, its setup files and the test files. */
+  /** A configuration module, by the form of its name. */
+  | "configuration-file"
+  /** A file a relative string of a configuration module or a JSON configuration file names. */
+  | "configuration-string"
+  /** The test runner: its workspace configuration, its setup files and the test files. */
   | "test-runner"
-  /** The linter's flat configuration. */
-  | "lint-configuration"
-  /** The mutation tester's configuration, and the test-runner configuration it names. */
+  /** The mutation tester's configuration under a name the configuration form does not cover. */
   | "mutation-testing"
-  /** The browser-test runner's configuration and the test files below its test directory. */
+  /** The test files below the browser-test runner's test directory. */
   | "browser-tests"
   /** A worker or service worker a call addresses by a string literal. */
   | "worker";
@@ -78,42 +82,28 @@ interface Convention {
 /** The extensions the test runner and the browser-test runner load a configuration from. */
 const MODULE_EXTENSIONS = ["js", "mjs", "cjs", "ts", "mts", "cts"] as const;
 
-/** The extensions the linter's flat configuration and the mutation tester's are loaded from. */
+/** The extensions the mutation tester's configuration is loaded from. */
 const SCRIPT_EXTENSIONS = ["js", "mjs", "cjs"] as const;
 
+/** The tool file names the configuration form does not cover. */
 const CONVENTIONS: readonly Convention[] = [
   {
     rule: "test-runner",
-    stems: ["vitest.config", "vitest.workspace", "vitest.projects"],
+    stems: ["vitest.workspace", "vitest.projects"],
     extensions: MODULE_EXTENSIONS,
     testRunner: true,
   },
-  {
-    rule: "lint-configuration",
-    stems: ["eslint.config"],
-    extensions: MODULE_EXTENSIONS,
-    testRunner: false,
-  },
   {
     rule: "mutation-testing",
-    stems: ["stryker.config", "stryker.conf", ".stryker.config", ".stryker.conf"],
+    stems: ["stryker.conf", ".stryker.config", ".stryker.conf"],
     extensions: SCRIPT_EXTENSIONS,
     testRunner: false,
   },
-  {
-    rule: "mutation-testing",
-    stems: ["vitest.stryker.config"],
-    extensions: MODULE_EXTENSIONS,
-    testRunner: true,
-  },
-  {
-    rule: "browser-tests",
-    stems: ["playwright.config"],
-    extensions: MODULE_EXTENSIONS,
-    testRunner: false,
-  },
 ];
 
+/** The stem of the browser-test runner's configuration, whose test directory is read. */
+const BROWSER_TEST_CONFIG = "playwright.config";
+
 /** The browser-test runner's own test-file pattern, which holds where a configuration names none. */
 const BROWSER_TEST_MATCH = "**/*.{spec,test}.{js,ts,jsx,tsx,cjs,cts,cjsx,ctsx,mjs,mts,mjsx,mtsx}";
 
@@ -256,6 +246,43 @@ function filesNamed(files: SourceFiles, dir: string, text: string): readonly Sou
   return files.named(resolvePath(dir, pathPart(text)));
 }
 
+/** Whether one file name is the browser-test runner's configuration. */
+function isBrowserTestConfig(name: string): boolean {
+  return MODULE_EXTENSIONS.some((ext) => name === `${BROWSER_TEST_CONFIG}.${ext}`);
+}
+
+/**
+ * The files the configuration files of one project enter: each configuration module,
+ * with what it exports, and each own file a relative string of a configuration module
+ * or a JSON configuration file names, read against that file's directory.
+ */
+function configurationEntries(
+  host: Host,
+  targetRoot: string,
+  files: SourceFiles,
+): readonly EntryPoint[] {
+  const { modules, documents } = configurationFiles(host, targetRoot, files);
+  const found: EntryPoint[] = [];
+  const strings = (dir: string, texts: readonly string[]): void => {
+    for (const text of texts) {
+      for (const file of filesNamedBy(files, dir, text)) {
+        found.push({ file, rule: "configuration-string", source: text, exports: true });
+      }
+    }
+  };
+  for (const { file, form } of modules) {
+    found.push({ file, rule: "configuration-file", source: form, exports: true });
+    strings(
+      dirnamePath(file.fileName),
+      moduleStrings(file).map((one) => one.text),
+    );
+  }
+  for (const document of documents) {
+    strings(dirnamePath(document.path), document.strings);
+  }
+  return found;
+}
+
 /**
  * The setup files one test-runner configuration names: every literal under
  * `test.setupFiles` and `test.globalSetup`, read against the configuration's own
@@ -467,8 +494,8 @@ function workersOf<Brand>(
 }
 
 /**
- * Every file of one project the lifted rules enter, in no particular order and
- * possibly more than once: a file two rules enter appears once per rule.
+ * 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.
  *
  * `testFiles` is the configuration's test-file patterns, matched against each
  * file's path below the target root; a file one of them matches is a test file the
@@ -478,19 +505,22 @@ export function entryPoints<Brand>(
   project: ProjectView<Brand>,
   files: SourceFiles,
   testFiles: readonly string[],
+  host: Host,
+  targetRoot: string,
 ): readonly EntryPoint[] {
-  const found: EntryPoint[] = [];
+  const found: EntryPoint[] = [...configurationEntries(host, targetRoot, files)];
   const tests = testFiles.map((pattern) => ({ pattern, expression: globExpression(pattern) }));
   for (const [path, file] of files.byPath) {
-    const named = conventionOf(basename(path));
+    const name = basename(path);
+    const named = conventionOf(name);
     if (named !== undefined) {
       found.push({ file, rule: named.convention.rule, source: named.spelled, exports: true });
       if (named.convention.testRunner) {
         found.push(...setupFilesOf(file, files));
       }
-      if (named.convention.rule === "browser-tests") {
-        found.push(...browserTestsOf(file, files));
-      }
+    }
+    if (isBrowserTestConfig(name)) {
+      found.push(...browserTestsOf(file, files));
     }
     for (const { pattern, expression } of tests) {
       if (expression.test(path)) {

package/src/exempt.ts

@@ -33,6 +33,8 @@ export interface Evidence {
   /** One clause naming the relation, then the thing it relates to. */
   readonly detail: string;
   readonly site: Position;
+  /** The component file, below the target root, whose markup holds the evidence. */
+  readonly whileLive?: string;
 }
 
 /** What a detector reads of one project, while the project's view is open. */
@@ -180,6 +182,7 @@ export function computeExemptions<Brand>(
         class: exemptionClass,
         detail: evidence.detail,
         site: evidence.site,
+        ...(evidence.whileLive === undefined ? {} : { whileLive: evidence.whileLive }),
       });
     }
   }
@@ -196,8 +199,8 @@ function compare(a: string, b: string): number {
 
 /**
  * Records as a run holds them: ordered by site, then class, then declaration, and one
- * per declaration, class and detail, the one at the first site. A fact found at many
- * sites, or by several projects, is one record.
+ * per declaration, class, detail and file it holds while live, the one at the first
+ * site. A fact found at many sites, or by several projects, is one record.
  */
 export function exemptionsOf(found: readonly Exemption[]): readonly Exemption[] {
   const ordered = [...found].sort(
@@ -205,7 +208,7 @@ export function exemptionsOf(found: readonly Exemption[]): readonly Exemption[]
   );
   const seen = new Set<string>();
   return ordered.filter((record) => {
-    const fact = [record.id, record.class, record.detail].join("\u0000");
+    const fact = [record.id, record.class, record.detail, record.whileLive ?? ""].join("\u0000");
     if (seen.has(fact)) {
       return false;
     }
@@ -214,6 +217,21 @@ export function exemptionsOf(found: readonly Exemption[]): readonly Exemption[]
   });
 }
 
+/**
+ * The records that hold while the component files at `live` are live: every record that
+ * holds whatever is live, and each one a live file's markup holds, as a record of the run.
+ */
+export function holdingWhile(
+  records: readonly Exemption[],
+  live: ReadonlySet<string>,
+): readonly Exemption[] {
+  return exemptionsOf(
+    records.flatMap(({ whileLive, ...record }) =>
+      whileLive === undefined || live.has(whileLive) ? [record] : [],
+    ),
+  );
+}
+
 /** The records per declaration, each declaration's in the order given. */
 function byDeclaration(records: readonly Exemption[]): ReadonlyMap<string, readonly Exemption[]> {
   const grouped = new Map<string, Exemption[]>();