@cplieger/deadset-ts 2.2.0 → 2.3.0

package/README.md

@@ -8,7 +8,7 @@ deadset-ts is a command-line analyzer for TypeScript and JavaScript projects. It
 
 deadset-ts is report-only. It never edits source, and it refuses any `--fix` flag.
 
-**Status: pre-release.** This version implements contract 2.1.0 and ships the analyzer's foundation: one compiler session per run over every `tsconfig` project discovered under the target (the explicit scope, every `tsconfig*.json`, each project's `references`), a fail-closed read of every project's diagnostics, configuration decoding against the contract's closed key list with `print-config` and its provenance, `print-projects`, the report-only guard, the symbol inventory of every declaration a project's own files hold down to its class and type members, and the one-pass reference resolution over that inventory. The inventory and the reference pass are library functions the package exports; no verb reports findings yet, so `analyze`, `explain`, `print-roots`, `print-retained` and `describe` exit with a usage message. The one runtime dependency is the `typescript` package at exactly 7.0.2, installed under the `@typescript/native` name until TypeScript 7.1 ships a compiler API the tooling can share.
+**Status: pre-release.** This version implements contract 2.1.0 and ships the analyzer's foundation: one compiler session per run over every `tsconfig` project discovered under the target (the explicit scope, every `tsconfig*.json`, each project's `references`), a fail-closed read of every project's diagnostics, configuration decoding against the contract's closed key list with `print-config` and its provenance, `print-projects`, the report-only guard, the symbol inventory of every declaration a project's own files hold down to its class and type members, the one-pass reference resolution over that inventory, and the root set `print-roots` prints. A root is a declaration the analysis keeps live without a reference: what a file exports when the manifest names it through `main`, `module`, `types`, `bin` or `exports`, or when `ts.entry_files` matches it; a library target's published API; the configuration, setup and test files of Vitest, Stryker and Playwright, the flat configuration of ESLint, and a worker or service worker a call addresses by a string literal; and every declaration a `roots.patterns` entry names. An entry that names nothing is reported as `DS1704` and fails the run. The entry-point conventions of other tools are not read, and `DECLINED_CONVENTIONS` lists each one with the reason. The inventory and the reference pass are library functions the package exports; no other verb reports findings yet, so `analyze`, `explain`, `print-retained` and `describe` exit with a usage message. The one runtime dependency is the `typescript` package at exactly 7.0.2, installed under the `@typescript/native` name until TypeScript 7.1 ships a compiler API the tooling can share.
 
 ## Install
 
@@ -28,14 +28,15 @@ The npm package carries the command and the library as JavaScript that the compi
 npx deadset-ts version
 ```
 
-`version` prints the analyzer version and the Contract version it implements, and exits 0. Any other invocation, including no arguments, prints the usage line and exits 2.
+`version` prints the analyzer version and the Contract version it implements, and exits 0. `print-config`, `print-projects` and `print-roots` print what their row of the table says and exit 0, or 1 when `print-roots` reports a `DS1704`. `analyze`, `explain`, `print-retained`, `describe`, any other invocation and no arguments print the usage line and exit 2.
 
 | Verb             | Job                                                                             |
 | ---------------- | ------------------------------------------------------------------------------- |
 | `analyze`        | Analyze a project and print the findings                                        |
 | `explain`        | Explain one finding: the relation, the roots and the references that decided it |
 | `print-config`   | Print the resolved configuration and where each setting came from               |
-| `print-roots`    | Print the resolved set of entry points                                          |
+| `print-projects` | Print the compiler configuration of every project a run analyzes                |
+| `print-roots`    | Print every declaration the analysis keeps live without a reference, and why    |
 | `print-retained` | Print every symbol an exemption class held back, with the class                 |
 | `describe`       | Describe the analyzer: version, Contract version, supported issue kinds         |
 | `version`        | Print the analyzer and Contract versions                                        |
@@ -90,6 +91,7 @@ Stable symbol references:
 
 Versions:
 
+- `DECLINED_CONVENTIONS`, `DeclinedConvention`: the entry-point conventions of other tools the analysis does not read, one row per tool or convention with the reason.
 - `CONTRACT_VERSION`: the contract version this analyzer implements.
 
 ## Contributing

package/dist/src/analysis.js

@@ -0,0 +1,109 @@
+/**
+ * One run's passes, composed: the projects discovery names, opened in one snapshot
+ * of one client, each read through the stages in the order they depend on each
+ * other, and the per-project answers merged into the answer for the run.
+ *
+ * The stages take a project's view, which only this composition makes: a view
+ * carries a project's identity in its type so a handle cannot cross to another
+ * project's checker, and that holds only for views the session itself hands out.
+ */
+import { diagnosticErrors, discoverProjects, DiscoveryError } from "./discover.js";
+import { inventory } from "./inventory.js";
+import { readManifest } from "./manifest.js";
+import { relativePath, resolvePath } from "./paths.js";
+import { byPosition } from "./position.js";
+import { roots, unmatchedEverywhere, unmatchedRoots } from "./roots.js";
+import { diagnosticsOf, runSession } from "./session.js";
+/** The setting whose source decides where a finding about a configured root sits. */
+const ROOTS_SETTING = "roots.patterns";
+/**
+ * The document that supplied one setting, below the target root, or the empty
+ * string where the setting came from no document of the target. Both paths are
+ * resolved against the working directory before one is read below the other, so a
+ * relative target and a relative document name the same place.
+ */
+function documentOf(host, provenance, setting, targetRoot) {
+    const origin = provenance.get(setting);
+    if (origin === undefined || origin.source === "default" || origin.source === "flag") {
+        return "";
+    }
+    const document = resolvePath(host.workingDirectory(), origin.label);
+    return relativePath(resolvePath(host.workingDirectory(), targetRoot), document) ?? "";
+}
+/** Two strings ordered bytewise. */
+function compare(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    return a < b ? -1 : 1;
+}
+/**
+ * The root set of the run the scope and the configuration describe.
+ *
+ * Every project is read for errors before anything else, and a project carrying one
+ * fails the run with no root set, as every verb that reads declarations does. A
+ * configured string is a finding when it names nothing in every project, and the
+ * finding sits in the document that declared the roots.
+ */
+export function runRoots(engine, host, scope, config, provenance) {
+    const targetRoot = scope.target.path;
+    const discovered = discoverProjects(engine, host, scope);
+    const manifest = readManifest(host, targetRoot);
+    const options = {
+        manifest,
+        patterns: config.rootPatterns,
+        entryFiles: config.ts.entryFiles,
+        testFiles: config.ts.testFiles,
+        publishedAPI: config.targetKind === "library",
+    };
+    const failures = [];
+    const { projects } = runSession(engine, discovered.configFiles, (project) => {
+        const errors = diagnosticErrors(diagnosticsOf(project));
+        if (errors.length > 0) {
+            failures.push(...errors);
+            return undefined;
+        }
+        const held = inventory(project, host, targetRoot);
+        return { held, rooted: roots(project, held, targetRoot, options) };
+    });
+    if (failures.length > 0) {
+        throw new DiscoveryError(`${String(failures.length)} error(s); no answer was produced`, failures);
+    }
+    const configurations = [];
+    const merged = new Map();
+    for (const answer of projects) {
+        if (answer === undefined) {
+            continue;
+        }
+        const configuration = relativePath(targetRoot, answer.rooted.configFile) ?? answer.rooted.configFile;
+        configurations.push(configuration);
+        const symbols = new Map(answer.held.symbols.map((symbol) => [symbol.id, symbol]));
+        for (const root of answer.rooted.liveUnderReachability) {
+            const symbol = symbols.get(root.id);
+            if (symbol === undefined) {
+                continue;
+            }
+            const key = [root.id, root.kind, root.source].join("\u0000");
+            const held = merged.get(key);
+            if (held === undefined) {
+                merged.set(key, {
+                    ref: symbol.ref,
+                    position: symbol.position,
+                    kind: root.kind,
+                    source: root.source,
+                    configurations: [configuration],
+                });
+            }
+            else if (!held.configurations.includes(configuration)) {
+                held.configurations.push(configuration);
+            }
+        }
+    }
+    const ordered = [...merged.values()].sort((a, b) => byPosition(a.position, b.position) || compare(a.kind, b.kind) || compare(a.source, b.source));
+    const unmatched = unmatchedEverywhere(config.rootPatterns, projects.flatMap((answer) => (answer === undefined ? [] : [answer.rooted])));
+    return {
+        configurations,
+        roots: ordered,
+        findings: unmatchedRoots(unmatched, documentOf(host, provenance, ROOTS_SETTING, targetRoot)),
+    };
+}

package/dist/src/config.js

@@ -1,4 +1,10 @@
 import { CONTRACT_VERSION } from "./version.js";
+/**
+ * The name of the repository configuration at the target root, which is also the
+ * document a finding about the configuration names where no document of the
+ * target supplied the setting it is about.
+ */
+export const REPOSITORY_DOCUMENT = "deadset.json";
 /**
  * The configuration every documented default states. `targetKind` is empty: the
  * field has no default and is never inferred.

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