@cplieger/deadset-ts 4.0.1 → 5.1.0

package/dist/src/emit-map.js

@@ -0,0 +1,72 @@
+/**
+ * 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.js";
+/** The source extensions the compiler emits each output extension from. */
+const EMITTED = [
+    { 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"] },
+];
+/** One path with its extension replaced, where it carries the one named. */
+function reExtended(path, emitted, source) {
+    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) {
+    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, layout) {
+    const found = [];
+    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/dist/src/entry-point-gaps.js

@@ -7,15 +7,18 @@
  * Every row carries a reason, because the list is read where the rows are shown
  * one at a time: beside a finding, or in a report's declared gaps.
  */
-/** 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";
-/** Why a tool none of whose conventions is entered 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.";
-/** The tools none of whose conventions is entered. */
+/** 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 whose own conventions are not read declines them. */
+const UNREAD = "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.";
+/** 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 = [
     "angular",
-    "astro",
     "astro-db",
     "astro-markdoc",
     "astro-og-canvas",
@@ -48,7 +51,6 @@ const UNREAD_TOOLS = [
     "esbuild",
     "eve",
     "execa",
-    "expo",
     "expressive-code",
     "fast",
     "fumadocs",
@@ -85,7 +87,6 @@ const UNREAD_TOOLS = [
     "nano-staged",
     "nest",
     "netlify",
-    "next",
     "next-intl",
     "next-mdx",
     "nitro",
@@ -93,7 +94,6 @@ const UNREAD_TOOLS = [
     "node-modules-inspector",
     "nodemon",
     "npm-package-json-lint",
-    "nuxt",
     "nuxtjs-i18n",
     "nx",
     "nyc",
@@ -118,17 +118,14 @@ const UNREAD_TOOLS = [
     "prettier",
     "prisma",
     "quasar",
-    "qwik",
     "railway",
     "raycast",
     "react-cosmos",
     "react-email",
     "react-native",
-    "react-router",
     "relay",
     "release-it",
     "remark",
-    "remix",
     "rolldown",
     "rollup",
     "rsbuild",
@@ -144,11 +141,9 @@ const UNREAD_TOOLS = [
     "sst",
     "starlight",
     "stencil",
-    "storybook",
     "stylelint",
     "svelte",
     "sveltejs-package",
-    "sveltekit",
     "svgo",
     "svgr",
     "swc",
@@ -171,7 +166,6 @@ const UNREAD_TOOLS = [
     "typescript-content-mapper",
     "unbuild",
     "unocss",
-    "unplugin-auto-import",
     "unplugin-icons",
     "unplugin-vue-components",
     "unplugin-vue-i18n",
@@ -201,9 +195,15 @@ const UNREAD_TOOLS = [
 const PARTLY_ENTERED = [
     {
         tool: "eslint",
-        convention: "the legacy .eslintrc configuration files",
-        reason: "Only the flat configuration's file names are entered, so a legacy configuration " +
-            "file the program holds is reported as never imported.",
+        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: "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",
@@ -213,8 +213,8 @@ const PARTLY_ENTERED = [
     },
     {
         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",
@@ -222,16 +222,64 @@ const PARTLY_ENTERED = [
         reason: "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: "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,
+    },
+    {
+        tool: "vite",
+        convention: "the module scripts an index.html loads",
+        reason: "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",
@@ -241,15 +289,14 @@ const PARTLY_ENTERED = [
     },
     {
         tool: "vitest",
-        convention: "the mock files below a __mocks__ directory",
-        reason: "No rule enters a file by its directory, so a mock only the runner's module mocking " +
-            "loads is reported as never imported.",
+        convention: "the setup files of a configuration that moves its root",
+        reason: "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",
@@ -259,9 +306,8 @@ const PARTLY_ENTERED = [
     },
     {
         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,
     },
 ];
 /** Two strings ordered bytewise. */

package/dist/src/entry-points.js

@@ -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
@@ -12,45 +12,31 @@
  */
 import { isArrayLiteralExpression, isAsExpression, isCallExpression, isExportAssignment, isIdentifier, isMetaProperty, isNewExpression, isNoSubstitutionTemplateLiteral, isObjectLiteralExpression, isParenthesizedExpression, isPropertyAccessExpression, isPropertyAssignment, isSatisfiesExpression, isStringLiteral, } from "@typescript/native/unstable/ast";
 import { SymbolFlags } from "@typescript/native/unstable/sync";
+import { configurationFiles, filesNamedBy, moduleStrings, } from "./configuration-files.js";
 import { globExpression } from "./glob.js";
 import { dirnamePath, relativePath, resolvePath } from "./paths.js";
 import { UNANSWERED } from "./query.js";
 /** The extensions the test runner and the browser-test runner load a configuration from. */
 const MODULE_EXTENSIONS = ["js", "mjs", "cjs", "ts", "mts", "cts"];
-/** 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"];
+/** The tool file names the configuration form does not cover. */
 const CONVENTIONS = [
     {
         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}";
 /** The members of a test-runner configuration's `test` object that name setup files. */
@@ -174,6 +160,37 @@ function filesNamed(files, dir, text) {
     }
     return files.named(resolvePath(dir, pathPart(text)));
 }
+/** Whether one file name is the browser-test runner's configuration. */
+function isBrowserTestConfig(name) {
+    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, targetRoot, files, parse) {
+    const { modules, documents, outside } = configurationFiles(host, targetRoot, files, parse);
+    const found = [];
+    const strings = (dir, texts) => {
+        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);
+    }
+    for (const { file } of outside) {
+        strings(dirnamePath(file.fileName), moduleStrings(file).map((one) => one.text));
+    }
+    return found;
+}
 /**
  * The setup files one test-runner configuration names: every literal under
  * `test.setupFiles` and `test.globalSetup`, read against the configuration's own
@@ -360,26 +377,27 @@ function workersOf(project, file, files) {
     return found;
 }
 /**
- * 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
  * runner executes.
  */
-export function entryPoints(project, files, testFiles) {
-    const found = [];
+export function entryPoints(project, files, testFiles, host, targetRoot, parse) {
+    const found = [...configurationEntries(host, targetRoot, files, parse)];
     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/dist/src/exempt-classes.js

@@ -26,7 +26,12 @@ export const EXEMPTION_CLASSES = [
         confidence: "certain",
         typescriptVisibility: { private: false, privateName: false },
     },
-    { class: "generated-file", languages: ["go"], confidence: "certain" },
+    {
+        class: "generated-file",
+        languages: ["go", "ts"],
+        confidence: "certain",
+        typescriptVisibility: { private: true, privateName: false },
+    },
     { class: "linkname-cgo-asm-plugin", languages: ["go"], confidence: "certain" },
     {
         class: "template-field",

package/dist/src/exempt.js

@@ -88,8 +88,13 @@ function detected(exemptionClass, detect, input) {
  * test file makes is none there.
  */
 export function computeExemptions(input, detectors, holding) {
+    return detectExemptions(input, detectors, holding).records;
+}
+/** The records of {@link computeExemptions}, beside the test-file evidence it set aside. */
+export function detectExemptions(input, detectors, holding) {
     const visibility = new Map(input.held.symbols.map((symbol) => [symbol.id, symbol.visibility]));
     const found = [];
+    const inTestFiles = [];
     for (const exemptionClass of TS_EXEMPTION_CLASSES) {
         const detect = detectors.get(exemptionClass);
         if (detect === undefined || holding.disabled.has(exemptionClass)) {
@@ -100,18 +105,21 @@ export function computeExemptions(input, detectors, holding) {
             if (!retainable(allowed, visibility.get(evidence.id))) {
                 continue;
             }
-            if (holding.mode.production && holding.testFiles.has(evidence.site.path)) {
-                continue;
-            }
-            found.push({
+            const record = {
                 id: evidence.id,
                 class: exemptionClass,
                 detail: evidence.detail,
                 site: evidence.site,
-            });
+                ...(evidence.whileLive === undefined ? {} : { whileLive: evidence.whileLive }),
+            };
+            if (holding.mode.production && holding.testFiles.has(evidence.site.path)) {
+                inTestFiles.push(record);
+                continue;
+            }
+            found.push(record);
         }
     }
-    return exemptionsOf(found);
+    return { records: exemptionsOf(found), inTestFiles };
 }
 /** Two strings ordered bytewise. */
 function compare(a, b) {
@@ -122,14 +130,14 @@ function compare(a, b) {
 }
 /**
  * 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) {
     const ordered = [...found].sort((a, b) => byPosition(a.site, b.site) || compare(a.class, b.class) || compare(a.id, b.id));
     const seen = new Set();
     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;
         }
@@ -137,6 +145,13 @@ export function exemptionsOf(found) {
         return true;
     });
 }
+/**
+ * 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, live) {
+    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) {
     const grouped = new Map();
@@ -152,24 +167,21 @@ function byDeclaration(records) {
     return grouped;
 }
 /**
- * The records that held back a declaration some configuration of the run would
- * otherwise judge dead: each configuration's graph is swept once more with no
- * exemption and the marks it was given, and a record is retained when one of those
- * sweeps judged its declaration a candidate. A record that holds a declaration back in
- * one configuration is retained whatever another configuration answers about it, as a
- * run of that configuration alone would report the declaration without it. A record
- * on a declaration that a relation or a mark holds live in every configuration held
- * nothing back. The order is the declarations' site order, and for one declaration
- * the input's.
+ * The records that held back a declaration: one some configuration's graph, swept
+ * again with no exemption and its marks, judges a candidate, whatever another
+ * configuration answers, or one in `writeOnly`, which the run would report as written
+ * and never read without the record's read. A declaration a relation or a mark holds
+ * live in every configuration is held back by no record. The order is the
+ * declarations' site order, and for one declaration the input's.
  */
-export function retainedIn(matrix, input) {
+export function retainedIn(matrix, input, writeOnly = new Set()) {
     const exempt = input.exempt ?? [];
     if (exempt.length === 0) {
         return [];
     }
     const bare = { marked: input.marked, mode: input.mode };
     const dead = new Set(matrix.graphs.flatMap((graph) => sweep(graph, bare).candidates.map((candidate) => candidate.id)));
-    const held = byDeclaration(exempt.filter((record) => dead.has(record.id)));
+    const held = byDeclaration(exempt.filter((record) => dead.has(record.id) || writeOnly.has(record.id)));
     return matrix.union.symbols.flatMap((symbol) => held.get(symbol.id) ?? []);
 }
 /**