@cplieger/deadset-ts 2.2.1 → 3.0.0

package/dist/src/entry-point-gaps.js

@@ -0,0 +1,278 @@
+/**
+ * Every entry-point convention this analyzer declines, each with the tool it belongs
+ * to and why. A file only a declined convention enters is reported as never
+ * imported, so a project that relies on one names the file in `ts.entry_files` or
+ * `roots.patterns`, and this list is what tells it to.
+ *
+ * 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. */
+const UNREAD_TOOLS = [
+    "angular",
+    "astro",
+    "astro-db",
+    "astro-markdoc",
+    "astro-og-canvas",
+    "ava",
+    "babel",
+    "biome",
+    "borp",
+    "bumpp",
+    "bun",
+    "c8",
+    "capacitor",
+    "catalyst",
+    "changelogen",
+    "changelogithub",
+    "changesets",
+    "commitizen",
+    "commitlint",
+    "convex",
+    "create-typescript-app",
+    "cspell",
+    "cucumber",
+    "cypress",
+    "danger",
+    "dependency-cruiser",
+    "docusaurus",
+    "dotenv",
+    "drizzle",
+    "electron-vite",
+    "eleventy",
+    "esbuild",
+    "eve",
+    "execa",
+    "expo",
+    "expressive-code",
+    "fast",
+    "fumadocs",
+    "gatsby",
+    "github-action",
+    "github-actions",
+    "glob",
+    "graphql-codegen",
+    "hardhat",
+    "husky",
+    "i18next-parser",
+    "jest",
+    "karma",
+    "knex",
+    "ladle",
+    "laravel-vite-plugin",
+    "lefthook",
+    "lint-staged",
+    "linthtml",
+    "lit",
+    "lockfile-lint",
+    "lost-pixel",
+    "lunaria",
+    "markdownlint",
+    "marko",
+    "mdx",
+    "mdxlint",
+    "metro",
+    "mise",
+    "mocha",
+    "moonrepo",
+    "msw",
+    "nano-spawn",
+    "nano-staged",
+    "nest",
+    "netlify",
+    "next",
+    "next-intl",
+    "next-mdx",
+    "nitro",
+    "node",
+    "node-modules-inspector",
+    "nodemon",
+    "npm-package-json-lint",
+    "nuxt",
+    "nuxtjs-i18n",
+    "nx",
+    "nyc",
+    "oclif",
+    "openapi-ts",
+    "openclaw",
+    "orval",
+    "oxfmt",
+    "oxlint",
+    "panda-css",
+    "parcel",
+    "payload",
+    "pino",
+    "playwright-ct",
+    "playwright-test",
+    "plop",
+    "pm2",
+    "pnpm",
+    "postcss",
+    "pre-commit",
+    "preconstruct",
+    "prettier",
+    "prisma",
+    "quasar",
+    "qwik",
+    "railway",
+    "raycast",
+    "react-cosmos",
+    "react-email",
+    "react-native",
+    "react-router",
+    "relay",
+    "release-it",
+    "remark",
+    "remix",
+    "rolldown",
+    "rollup",
+    "rsbuild",
+    "rslib",
+    "rspack",
+    "rstest",
+    "sanity",
+    "semantic-release",
+    "sentry",
+    "serverless-framework",
+    "simple-git-hooks",
+    "size-limit",
+    "sst",
+    "starlight",
+    "stencil",
+    "storybook",
+    "stylelint",
+    "svelte",
+    "sveltejs-package",
+    "sveltekit",
+    "svgo",
+    "svgr",
+    "swc",
+    "syncpack",
+    "tailwind",
+    "tanstack-router",
+    "taskfile",
+    "tauri",
+    "temporal",
+    "textlint",
+    "travis",
+    "ts-node",
+    "tsd",
+    "tsdown",
+    "tsup",
+    "tsx",
+    "turbo",
+    "typedoc",
+    "typescript",
+    "typescript-content-mapper",
+    "unbuild",
+    "unocss",
+    "unplugin-auto-import",
+    "unplugin-icons",
+    "unplugin-vue-components",
+    "unplugin-vue-i18n",
+    "unplugin-vue-markdown",
+    "unplugin-vue-router",
+    "varlock",
+    "vercel",
+    "vercel-og",
+    "vike",
+    "vite-plugin-pages",
+    "vite-plugin-pwa",
+    "vite-plugin-vue-layouts-next",
+    "vite-plus",
+    "vite-pwa-assets-generator",
+    "vitepress",
+    "vue",
+    "webdriver-io",
+    "wireit",
+    "wrangler",
+    "wxt",
+    "xo",
+    "yarn",
+    "yorkie",
+    "zx",
+];
+/** The conventions declined for a tool some of whose conventions are entered. */
+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.",
+    },
+    {
+        tool: "playwright",
+        convention: "a testMatch written as a regular expression",
+        reason: "A testMatch that is not a string literal leaves the test-file set unknown, and an " +
+            "unknown set enters nothing.",
+    },
+    {
+        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.",
+    },
+    {
+        tool: "playwright",
+        convention: "the testDir and testMatch of an entry in projects",
+        reason: "Only the configuration object's own testDir and testMatch are read, so a test " +
+            "directory a project entry moves is not entered.",
+    },
+    {
+        tool: "stryker",
+        convention: "a configuration file named on the command line",
+        reason: "Only the file names the tool looks for by default are entered.",
+    },
+    {
+        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.",
+    },
+    {
+        tool: "vitest",
+        convention: "the benchmark and type-test files",
+        reason: "A test file is one ts.test_files classifies, so a *.bench.* or *.test-d.* file is " +
+            "entered only where a configured pattern names it.",
+    },
+    {
+        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.",
+    },
+    {
+        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.",
+    },
+    {
+        tool: "vitest",
+        convention: "the test files a configuration's include member names",
+        reason: "A test file is one ts.test_files classifies rather than one the runner's include " +
+            "reads, so the two are kept equal by configuration.",
+    },
+    {
+        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.",
+    },
+];
+/** Two strings ordered bytewise. */
+function compare(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    return a < b ? -1 : 1;
+}
+/** Every declined entry-point convention, ordered by tool and then by convention. */
+export const DECLINED_CONVENTIONS = [
+    ...UNREAD_TOOLS.map((tool) => ({ tool, convention: EVERY_CONVENTION, reason: UNREAD })),
+    ...PARTLY_ENTERED,
+].sort((a, b) => compare(a.tool, b.tool) || compare(a.convention, b.convention));

package/dist/src/entry-points.js

@@ -0,0 +1,385 @@
+/**
+ * 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.
+ *
+ * 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
+ * argument of a call the checker resolves to the platform's own declaration. A
+ * value that is not a literal is not evaluated and not guessed, so a file it would
+ * have named is entered by nothing here.
+ */
+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 { globExpression } from "./glob.js";
+import { dirnamePath, relativePath, resolvePath } from "./paths.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. */
+const SCRIPT_EXTENSIONS = ["js", "mjs", "cjs"];
+const CONVENTIONS = [
+    {
+        rule: "test-runner",
+        stems: ["vitest.config", "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"],
+        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 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. */
+const SETUP_MEMBERS = ["setupFiles", "globalSetup"];
+/** 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 = ["./", "../"];
+/** The constructors whose first argument addresses a worker script. */
+const WORKER_CONSTRUCTORS = new Set(["Worker", "SharedWorker"]);
+/** The file's name, the last segment of its path. */
+function basename(path) {
+    return path.slice(path.lastIndexOf("/") + 1);
+}
+/** The convention one file name is, with the spelling a root reports it by. */
+function conventionOf(name) {
+    for (const convention of CONVENTIONS) {
+        for (const stem of convention.stems) {
+            if (convention.extensions.some((ext) => name === `${stem}.${ext}`)) {
+                return { convention, spelled: `${stem}.*` };
+            }
+        }
+    }
+    return undefined;
+}
+/** The text a string literal or a template with no substitution denotes. */
+function literalOf(node) {
+    if (node !== undefined && (isStringLiteral(node) || isNoSubstitutionTemplateLiteral(node))) {
+        return node.text;
+    }
+    return undefined;
+}
+/** The expression a wrapper that changes no value holds: parentheses and type assertions. */
+function unwrapped(node) {
+    let at = node;
+    while (isParenthesizedExpression(at) || isAsExpression(at) || isSatisfiesExpression(at)) {
+        at = at.expression;
+    }
+    return at;
+}
+/**
+ * The object literals one configuration file's default export is written as: the
+ * literal itself, or each literal argument of the call it is, at any depth of calls.
+ * A default export written as anything else, a name or a computation, yields none,
+ * because its value is not in the file's text.
+ */
+function configObjects(file) {
+    const found = [];
+    const collect = (node) => {
+        const at = unwrapped(node);
+        if (isObjectLiteralExpression(at)) {
+            found.push(at);
+            return;
+        }
+        if (isCallExpression(at)) {
+            for (const argument of at.arguments) {
+                collect(argument);
+            }
+        }
+    };
+    for (const statement of file.statements) {
+        if (isExportAssignment(statement) && !statement.isExportEquals) {
+            collect(statement.expression);
+        }
+    }
+    return found;
+}
+/**
+ * The value one member of an object literal is written with, when it is written as
+ * `name: value`, and undefined where the literal writes no such member.
+ */
+function memberOf(object, name) {
+    if (!isObjectLiteralExpression(object)) {
+        return undefined;
+    }
+    for (const property of object.properties) {
+        if (isPropertyAssignment(property) &&
+            isIdentifier(property.name) &&
+            property.name.text === name) {
+            return property.initializer;
+        }
+    }
+    return undefined;
+}
+/**
+ * The strings one member holds, when it is written as a literal or an array of
+ * literals. `undefined` is a value the text does not state.
+ */
+function literalsOf(value) {
+    const at = unwrapped(value);
+    const single = literalOf(at);
+    if (single !== undefined) {
+        return [single];
+    }
+    if (!isArrayLiteralExpression(at)) {
+        return undefined;
+    }
+    const found = [];
+    for (const element of at.elements) {
+        const text = literalOf(unwrapped(element));
+        if (text === undefined) {
+            return undefined;
+        }
+        found.push(text);
+    }
+    return found;
+}
+/** Whether a literal is relative in the sense a module specifier and a URL reference share. */
+function isRelative(text) {
+    return RELATIVE_PREFIXES.some((prefix) => text.startsWith(prefix));
+}
+/** A URL reference with its query and its fragment removed, which name no part of the file. */
+function pathPart(text) {
+    const cut = text.search(/[?#]/u);
+    return cut < 0 ? text : text.slice(0, cut);
+}
+/** The own files one relative literal names, read against a directory. */
+function filesNamed(files, dir, text) {
+    if (!isRelative(text)) {
+        return [];
+    }
+    return files.named(resolvePath(dir, pathPart(text)));
+}
+/**
+ * The setup files one test-runner configuration names: every literal under
+ * `test.setupFiles` and `test.globalSetup`, read against the configuration's own
+ * directory. A configuration that moves its root names them against a directory its
+ * text may not state, so none is read from it.
+ */
+function setupFilesOf(file, files) {
+    const objects = configObjects(file);
+    const tests = objects
+        .map((object) => memberOf(object, "test"))
+        .filter((value) => value !== undefined)
+        .map(unwrapped);
+    if ([...objects, ...tests].some((object) => memberOf(object, ROOT_MEMBER) !== undefined)) {
+        return [];
+    }
+    const dir = dirnamePath(file.fileName);
+    const found = [];
+    for (const test of tests) {
+        for (const name of SETUP_MEMBERS) {
+            const value = memberOf(test, name);
+            for (const text of value === undefined ? [] : (literalsOf(value) ?? [])) {
+                for (const named of filesNamed(files, dir, text)) {
+                    found.push({ file: named, rule: "test-runner", source: text, exports: false });
+                }
+            }
+        }
+    }
+    return found;
+}
+/**
+ * The test files one browser-test configuration names: every own file below its
+ * test directory that its test-file pattern matches. The directory is the literal
+ * `testDir` reads against the configuration's directory, or that directory where no
+ * object of the configuration writes one; the pattern is the literal `testMatch`, or
+ * the runner's own where none is written. A member whose value is not a literal
+ * leaves the set unknown, and an unknown set enters nothing.
+ */
+function browserTestsOf(file, files) {
+    const objects = configObjects(file);
+    if (objects.length === 0) {
+        return [];
+    }
+    let testDir = ".";
+    let patterns = [BROWSER_TEST_MATCH];
+    for (const object of objects) {
+        const dir = memberOf(object, "testDir");
+        if (dir !== undefined) {
+            testDir = literalOf(unwrapped(dir));
+        }
+        const match = memberOf(object, "testMatch");
+        if (match !== undefined) {
+            patterns = literalsOf(match);
+        }
+    }
+    if (testDir === undefined || patterns === undefined) {
+        return [];
+    }
+    const under = resolvePath(dirnamePath(file.fileName), testDir);
+    const found = [];
+    for (const pattern of patterns) {
+        const expression = globExpression(pattern);
+        for (const candidate of files.byName.values()) {
+            const below = relativePath(under, candidate.fileName);
+            if (below !== undefined && expression.test(below)) {
+                found.push({ file: candidate, rule: "browser-tests", source: pattern, exports: false });
+            }
+        }
+    }
+    return found;
+}
+/**
+ * The address one worker argument writes: a relative literal, or a `URL` built from
+ * a literal against `import.meta.url`. Any other argument is computed and addresses
+ * nothing the text states.
+ */
+function workerAddress(argument) {
+    if (argument === undefined) {
+        return undefined;
+    }
+    const at = unwrapped(argument);
+    const literal = literalOf(at);
+    if (literal !== undefined) {
+        return { literal, names: [] };
+    }
+    if (!isNewExpression(at) || !isIdentifier(at.expression) || at.expression.text !== "URL") {
+        return undefined;
+    }
+    const [reference, base] = at.arguments ?? [];
+    const text = literalOf(reference === undefined ? undefined : unwrapped(reference));
+    if (text === undefined || base === undefined) {
+        return undefined;
+    }
+    const meta = unwrapped(base);
+    if (!isPropertyAccessExpression(meta) ||
+        !isMetaProperty(meta.expression) ||
+        !isIdentifier(meta.name) ||
+        meta.name.text !== "url") {
+        return undefined;
+    }
+    return { literal: text, names: [at.expression] };
+}
+/**
+ * Every call one file writes that addresses a worker: `new Worker(...)`,
+ * `new SharedWorker(...)` and `navigator.serviceWorker.register(...)`, each with an
+ * address its text states.
+ */
+function workerSitesOf(file) {
+    const found = [];
+    const visit = (node) => {
+        if (isNewExpression(node) &&
+            isIdentifier(node.expression) &&
+            WORKER_CONSTRUCTORS.has(node.expression.text)) {
+            const address = workerAddress(node.arguments?.[0]);
+            if (address !== undefined) {
+                found.push({
+                    literal: address.literal,
+                    platformNames: [node.expression, ...address.names],
+                });
+            }
+        }
+        if (isCallExpression(node)) {
+            const callee = node.expression;
+            if (isPropertyAccessExpression(callee) &&
+                isIdentifier(callee.name) &&
+                callee.name.text === "register" &&
+                isPropertyAccessExpression(callee.expression) &&
+                isIdentifier(callee.expression.name) &&
+                callee.expression.name.text === "serviceWorker" &&
+                isIdentifier(callee.expression.expression) &&
+                callee.expression.expression.text === "navigator") {
+                const address = workerAddress(node.arguments[0]);
+                if (address !== undefined) {
+                    found.push({
+                        literal: address.literal,
+                        platformNames: [callee.expression.expression, ...address.names],
+                    });
+                }
+            }
+        }
+        node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+    return found;
+}
+/**
+ * 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.
+ */
+function workersOf(project, file, files) {
+    const sites = workerSitesOf(file);
+    if (sites.length === 0) {
+        return [];
+    }
+    const names = sites.flatMap((site) => site.platformNames);
+    const symbols = project.symbolsAt(names.map((name) => project.handle(name)));
+    const platform = new Set();
+    names.forEach((name, index) => {
+        const symbol = symbols[index];
+        if (symbol !== undefined &&
+            (symbol.flags & SymbolFlags.Alias) === 0 &&
+            symbol.declarations.length > 0 &&
+            symbol.declarations.every((handle) => !files.byName.has(handle.path))) {
+            platform.add(name);
+        }
+    });
+    const dir = dirnamePath(file.fileName);
+    const found = [];
+    for (const site of sites) {
+        if (!site.platformNames.every((name) => platform.has(name))) {
+            continue;
+        }
+        for (const named of filesNamed(files, dir, site.literal)) {
+            found.push({ file: named, rule: "worker", source: site.literal, exports: false });
+        }
+    }
+    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.
+ *
+ * `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 = [];
+    const tests = testFiles.map((pattern) => ({ pattern, expression: globExpression(pattern) }));
+    for (const [path, file] of files.byPath) {
+        const named = conventionOf(basename(path));
+        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));
+            }
+        }
+        for (const { pattern, expression } of tests) {
+            if (expression.test(path)) {
+                found.push({ file, rule: "test-runner", source: pattern, exports: false });
+            }
+        }
+        found.push(...workersOf(project, file, files));
+    }
+    return found;
+}

package/dist/src/finding.js

@@ -0,0 +1,12 @@
+/**
+ * The members of a finding its emitter decides: the code, where the subject is,
+ * what the subject is, and the sentence the finding reports. They are the
+ * Contract's finding members of the same names, spelled in this language's case.
+ *
+ * Every other member the finding schema requires follows from these and from the
+ * run: the kind's name, its fixability and its ceiling come from the code's row of
+ * the issue-kind vocabulary, the severity and the confidence from the resolved
+ * configuration, the language from the analyzer. A report completes them, so an
+ * emitter cannot state one that disagrees with the vocabulary.
+ */
+export {};