@cplieger/deadset-ts 2.2.1 → 2.3.0

package/src/analysis.ts

@@ -0,0 +1,169 @@
+/**
+ * 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 type { Diagnostic } from "@typescript/native/unstable/sync";
+import type { Config, Provenance } from "./config.ts";
+import { diagnosticErrors, discoverProjects, DiscoveryError } from "./discover.ts";
+import type { Finding } from "./finding.ts";
+import type { Host } from "./host.ts";
+import { inventory } from "./inventory.ts";
+import { readManifest } from "./manifest.ts";
+import { relativePath, resolvePath } from "./paths.ts";
+import { byPosition, type Position } from "./position.ts";
+import { roots, unmatchedEverywhere, unmatchedRoots, type RootKind } from "./roots.ts";
+import type { Scope } from "./scope.ts";
+import { diagnosticsOf, runSession, type Engine } from "./session.ts";
+
+/** The setting whose source decides where a finding about a configured root sits. */
+const ROOTS_SETTING = "roots.patterns";
+
+/** One root of the run, merged across the projects that hold it. */
+export interface RunRoot {
+  /** The stable reference of the declaration the root names. */
+  readonly ref: string;
+  /** Where that declaration is written. */
+  readonly position: Position;
+  readonly kind: RootKind;
+  readonly source: string;
+  /** The configurations whose project holds this root, in the run's order. */
+  readonly configurations: readonly string[];
+}
+
+/** The root set of one run, and the findings about the roots the configuration names. */
+export interface RunRoots {
+  /**
+   * The configurations the run analyzed: each compiler configuration file, by its
+   * path below the target root, in discovery order.
+   */
+  readonly configurations: readonly string[];
+  /**
+   * Every root of the run, ordered by the site of its declaration, then by kind, then
+   * by the string that named it. A root several projects hold is one entry naming each.
+   */
+  readonly roots: readonly RunRoot[];
+  /** One finding per configured root or pattern that named nothing in any project. */
+  readonly findings: readonly Finding[];
+}
+
+/**
+ * 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: Host,
+  provenance: Provenance,
+  setting: string,
+  targetRoot: string,
+): string {
+  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: string, b: string): number {
+  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: Engine,
+  host: Host,
+  scope: Scope,
+  config: Config,
+  provenance: Provenance,
+): RunRoots {
+  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: Diagnostic[] = [];
+  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: string[] = [];
+  const merged = new Map<string, Omit<RunRoot, "configurations"> & { configurations: string[] }>();
+  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/src/config.ts

@@ -1,5 +1,12 @@
 import { CONTRACT_VERSION } from "./version.ts";
 
+/**
+ * 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";
+
 /**
  * Whether the target is an application, whose every caller is in the analyzed
  * graph, or a library, whose published API has callers outside it.

package/src/entry-point-gaps.ts

@@ -0,0 +1,304 @@
+/**
+ * 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.
+ */
+
+/** One declined entry-point convention. */
+export interface DeclinedConvention {
+  /** The tool the convention belongs to, by the name of the package or service. */
+  readonly tool: string;
+  /** What is declined: one convention of a tool whose others are entered, or all of them. */
+  readonly convention: string;
+  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";
+
+/** 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: readonly string[] = [
+  "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: readonly DeclinedConvention[] = [
+  {
+    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: string, b: string): number {
+  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: readonly DeclinedConvention[] = [
+  ...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));