@cplieger/deadset-ts 1.0.0 → 1.2.0

package/NOTICE

@@ -0,0 +1,3 @@
+deadset-ts
+Copyright 2026 cplieger
+https://github.com/cplieger/deadset-ts

package/README.md

@@ -1,9 +1,6 @@
 # deadset-ts
 
-[![npm](https://img.shields.io/npm/v/@cplieger/deadset-ts)](https://www.npmjs.com/package/@cplieger/deadset-ts)
-[![JSR](https://jsr.io/badges/@cplieger/deadset-ts)](https://jsr.io/@cplieger/deadset-ts)
-[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/PROJECT_ID/badge)](https://www.bestpractices.dev/projects/PROJECT_ID)
-[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/cplieger/deadset-ts/badge)](https://scorecard.dev/viewer/?uri=github.com/cplieger/deadset-ts)
+[![npm](https://img.shields.io/npm/v/@cplieger/deadset-ts)](https://www.npmjs.com/package/@cplieger/deadset-ts) [![JSR](https://jsr.io/badges/@cplieger/deadset-ts)](https://jsr.io/@cplieger/deadset-ts)
 
 > Deterministic dead-code analysis for TypeScript, class and type members included.
 
@@ -11,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 0.1.0 and ships the command-line skeleton only: `version` runs, the other verbs are reserved and exit with a usage message. One runtime dependency is planned, the `typescript` package at one exact version; the skeleton has none.
+**Status: pre-release.** This version implements contract 1.5.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`, and the report-only guard. `analyze` and `explain` are not implemented yet and 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
 
@@ -19,9 +16,11 @@ deadset-ts is report-only. It never edits source, and it refuses any `--fix` fla
 npm i -D @cplieger/deadset-ts
 # or
 npx jsr add -D @cplieger/deadset-ts
+# or run the command without installing it
+npx @cplieger/deadset-ts version
 ```
 
-The package ships TypeScript source, not compiled JavaScript: the `deadset-ts` command is a `.ts` file that Node.js 24 or later runs directly through its built-in type stripping, and the exported API is imported as source by the consumer's own compiler. There is no build step on either side.
+The package ships TypeScript source, not compiled JavaScript, and there is no build step on either side. The `deadset-ts` command runs on plain Node.js 24 or later; its entry strips the types of the package's own source itself, because Node refuses to do that for a file under `node_modules`. The exported API is source too, so a consumer compiles it with its own TypeScript, or imports it under Deno from the JSR package; plain Node cannot import it.
 
 ## Usage
 

package/bin/deadset-ts.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// Node refuses to strip types from a .ts file under node_modules, so the
+// TypeScript entry cannot start from an install. A load hook scoped to this
+// package's own files supplies the stripped source instead.
+// https://nodejs.org/api/typescript.html#type-stripping-in-dependencies
+import { readFileSync } from "node:fs";
+import { registerHooks, stripTypeScriptTypes } from "node:module";
+
+const packageRoot = new URL("../", import.meta.url).href;
+
+registerHooks({
+  load(url, context, nextLoad) {
+    if (!url.startsWith(packageRoot) || !url.endsWith(".ts")) {
+      return nextLoad(url, context);
+    }
+    return {
+      format: "module",
+      source: stripTypeScriptTypes(readFileSync(new URL(url), "utf8")),
+      shortCircuit: true,
+    };
+  },
+});
+
+await import("./deadset-ts.ts");

package/bin/deadset-ts.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
 import { run } from "../src/run.ts";
+import { nodeHost } from "./node-host.ts";
 
-process.exitCode = run(process.argv.slice(2), process.stdout, process.stderr);
+process.exitCode = run(process.argv.slice(2), process.stdout, process.stderr, nodeHost());

package/bin/node-host.ts

@@ -0,0 +1,28 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import type { DirectoryEntry, Host, PathKind } from "../src/host.ts";
+
+/**
+ * The filesystem of the platform the command runs on.
+ *
+ * It is the one module that names the platform: everything the analysis is made of
+ * takes the filesystem as a parameter, so a consumer compiling the published
+ * sources needs the compiler's types and nothing else.
+ */
+export function nodeHost(): Host {
+  return {
+    workingDirectory: () => process.cwd(),
+    readFile: (path) => readFileSync(path, "utf8"),
+    readDirectory: (path): readonly DirectoryEntry[] =>
+      readdirSync(path, { withFileTypes: true }).map((entry) => ({
+        name: entry.name,
+        directory: entry.isDirectory(),
+      })),
+    kindOf: (path): PathKind => {
+      const stat = statSync(path, { throwIfNoEntry: false });
+      if (stat === undefined) {
+        return "absent";
+      }
+      return stat.isDirectory() ? "directory" : "file";
+    },
+  };
+}

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "license": "GPL-3.0-or-later",
   "exports": {
     ".": "./src/index.ts"
@@ -8,10 +8,12 @@
   "publish": {
     "include": [
       "LICENSE",
+      "NOTICE",
       "README.md",
       "bin/**",
       "src/**",
-      "jsr.json"
+      "jsr.json",
+      "package.json"
     ],
     "exclude": [
       "src/**/*.test.ts"

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "type": "module",
   "sideEffects": false,
   "description": "Deterministic dead-code analysis for TypeScript, class and type members included",
   "license": "GPL-3.0-or-later",
   "bin": {
-    "deadset-ts": "./bin/deadset-ts.ts"
+    "deadset-ts": "./bin/deadset-ts.mjs"
   },
   "exports": {
     ".": "./src/index.ts"
@@ -22,15 +22,18 @@
     "lint:prettier": "prettier --check .",
     "lint:fix": "eslint . --fix && prettier --write ."
   },
+  "dependencies": {
+    "@typescript/native": "npm:typescript@7.0.2"
+  },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@types/node": "24.13.4",
-    "@typescript/native": "npm:typescript@7.0.2",
+    "@types/node": "24.13.5",
     "eslint": "10.10.0",
-    "prettier": "3.9.6",
+    "fast-check": "4.10.1",
+    "prettier": "3.9.7",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "typescript-eslint": "8.70.0",
-    "vitest": "5.0.0"
+    "vitest": "5.0.1"
   },
   "publishConfig": {
     "access": "public"
@@ -53,6 +56,8 @@
     "cli"
   ],
   "files": [
+    "LICENSE",
+    "NOTICE",
     "bin/",
     "src/",
     "!src/**/*.test.ts",

package/src/config.ts

@@ -0,0 +1,218 @@
+import { CONTRACT_VERSION } from "./version.ts";
+
+/**
+ * Whether the target is an application, whose every caller is in the analyzed
+ * graph, or a library, whose published API has callers outside it.
+ */
+export type TargetKind = "application" | "library";
+
+/** The lowest reachability class a finding must reach to be reported. */
+export type Confidence = "certain" | "probable" | "possible";
+
+/** Whether declarations in generated files are analyzed. */
+export type GeneratedFiles = "exclude" | "include";
+
+/** How a reference from a consumer's test file counts. */
+export type ConsumerTests = "test" | "production";
+
+/** One language an analysis covers. */
+export type Language = "go" | "ts";
+
+/** What a finding of one issue kind does to a run. */
+export type Severity = "allow" | "warn" | "deny";
+
+/** One rendering of the finding list. */
+export type Format = "text" | "json" | "github" | "sarif" | "template";
+
+/** The order findings are rendered in. */
+export type Sort = "position" | "size";
+
+/** How much of a dead component a rendering names. */
+export type Cascade = "roots" | "full";
+
+/** One entry of the build matrix: a configuration the target builds under. */
+export interface BuildConfiguration {
+  readonly id: string;
+  readonly os: string;
+  readonly arch: string;
+  readonly tags: readonly string[];
+}
+
+/**
+ * The pair of action delimiters a template is parsed with. Both members are
+ * required once a document names the object, so the pair is one setting rather
+ * than two.
+ */
+export interface TemplateDelimiters {
+  readonly left: string;
+  readonly right: string;
+}
+
+/** How the analysis is scoped and filtered. */
+export interface Analysis {
+  readonly languages: readonly Language[];
+  readonly minConfidence: Confidence;
+  readonly generatedFiles: GeneratedFiles;
+  readonly consumerTests: ConsumerTests;
+  readonly configurations: readonly BuildConfiguration[];
+  readonly matrixComplete: boolean;
+  readonly templateDirs: readonly string[];
+  readonly templateDelimiters: TemplateDelimiters;
+}
+
+/** How findings are rendered. */
+export interface Reporters {
+  readonly formats: readonly Format[];
+  readonly sort: Sort;
+  readonly cascade: Cascade;
+  readonly maxFindings: number;
+  readonly failOn: Severity;
+}
+
+/** The section the TypeScript analyzer owns. */
+export interface TSSection {
+  readonly testFiles: readonly string[];
+  readonly entryFiles: readonly string[];
+}
+
+/**
+ * The resolved configuration: the closed key list of the Contract's
+ * configuration schema, decoded, with every default applied.
+ *
+ * `targetKind` is empty exactly in the configuration every default states, which
+ * is not a configuration a run may use: the field has no default and resolution
+ * refuses a result that carries none.
+ *
+ * `severity` is a map rather than an object because its keys come from a
+ * document, and an object keyed by document text answers for names it never
+ * held. The order it is written in is the emitter's, not the map's.
+ */
+export interface Config {
+  readonly contractVersion: string;
+  readonly targetKind: TargetKind | "";
+  readonly analysis: Analysis;
+  readonly consumersComplete: boolean;
+  readonly rootPatterns: readonly string[];
+  readonly severity: ReadonlyMap<string, Severity>;
+  readonly exemptionsDisabled: readonly string[];
+  readonly reporters: Reporters;
+  readonly ts: TSSection;
+}
+
+/**
+ * The configuration every documented default states. `targetKind` is empty: the
+ * field has no default and is never inferred.
+ */
+export function defaultConfig(): Config {
+  return {
+    contractVersion: CONTRACT_VERSION,
+    targetKind: "",
+    analysis: {
+      languages: [],
+      minConfidence: "possible",
+      generatedFiles: "exclude",
+      consumerTests: "test",
+      configurations: [],
+      matrixComplete: false,
+      templateDirs: [],
+      templateDelimiters: { left: "{{", right: "}}" },
+    },
+    consumersComplete: false,
+    rootPatterns: [],
+    severity: new Map(),
+    exemptionsDisabled: [],
+    reporters: {
+      formats: ["text"],
+      sort: "position",
+      cascade: "roots",
+      maxFindings: 0,
+      failOn: "deny",
+    },
+    ts: {
+      testFiles: ["**/*.test.{ts,tsx,mts,cts}"],
+      entryFiles: [],
+    },
+  };
+}
+
+/** Where a resolved setting came from, in the order the sources outrank each other. */
+export type Source = "flag" | "repository" | "central" | "default";
+
+/**
+ * One setting's source together with the file or flag that supplied it. `label`
+ * is empty exactly when `source` is `"default"`.
+ */
+export interface Origin {
+  readonly source: Source;
+  readonly label: string;
+}
+
+/**
+ * Renders the origin as the provenance value the Contract declares: `default`,
+ * or the source, a colon, a space and the file or flag.
+ */
+export function renderOrigin(origin: Origin): string {
+  return origin.source === "default" ? "default" : `${origin.source}: ${origin.label}`;
+}
+
+/**
+ * The origin of each resolved setting, keyed by the setting's dotted path. A
+ * section holds no value of its own and has no entry; the severity object
+ * carries one entry per code it names, or the entry `severity` alone when it is
+ * empty.
+ */
+export type Provenance = ReadonlyMap<string, Origin>;
+
+/**
+ * The configuration documents one invocation reads, each the document's text or
+ * absent. `repositoryLabel` names the document `repository` holds and
+ * `centralLabel` the one `central` holds; `flagLabels` names the flag that
+ * supplied each setting `flags` names, keyed by dotted setting path.
+ */
+export interface Inputs {
+  readonly flags?: string;
+  readonly repository?: string;
+  readonly central?: string;
+  readonly repositoryLabel?: string;
+  readonly centralLabel?: string;
+  readonly flagLabels?: ReadonlyMap<string, string>;
+}
+
+/** Which refusal a {@link ConfigError} carries. */
+export type ErrorKind =
+  /**
+   * A document that is not one JSON instance of the closed key list: a syntax
+   * error, a value of the wrong type, a value outside the closed set a key
+   * declares, or a member written twice at one level.
+   */
+  | "malformed"
+  /**
+   * A key the closed key list does not declare, or a severity key naming a kind
+   * whose severity the Contract fixes.
+   */
+  | "unimplemented-key"
+  /** A resolved configuration no source supplied a target kind for. */
+  | "missing-target-kind";
+
+/**
+ * Every refusal configuration resolution makes. Each maps to the usage exit
+ * code, and each is thrown rather than returned: a refusal ends the run, and the
+ * one caller that turns it into an exit code is the command line.
+ */
+export class ConfigError extends Error {
+  /** Which refusal this is. */
+  readonly kind: ErrorKind;
+
+  /**
+   * The key or field the message names, spelled as the document spells it. It is
+   * empty when the refusal names none.
+   */
+  readonly key: string;
+
+  constructor(kind: ErrorKind, key: string, message: string) {
+    super(message);
+    this.name = "ConfigError";
+    this.kind = kind;
+    this.key = key;
+  }
+}

package/src/discover.ts

@@ -0,0 +1,198 @@
+import { DiagnosticCategory } from "@typescript/native/unstable/sync";
+import type { Diagnostic } from "@typescript/native/unstable/sync";
+import type { Host } from "./host.ts";
+import { dirnamePath, isAbsolutePath, joinPath, resolvePath } from "./paths.ts";
+import type { Scope } from "./scope.ts";
+import type { Engine } from "./session.ts";
+
+/** Directory names discovery does not descend into. */
+const IGNORED_DIRECTORIES: ReadonlySet<string> = new Set(["node_modules", ".git"]);
+
+/** A compiler configuration file discovery recognises under a root. */
+const CONFIG_FILE = /^tsconfig.*\.json$/u;
+
+/**
+ * A run that cannot read what it was asked to analyze. It ends the run with the
+ * failure code and no finding list: a configuration file the compiler cannot read,
+ * or a project carrying an error, leaves the analysis without the type information
+ * every answer rests on, and a partial answer is never printed as a complete one.
+ */
+export class DiscoveryError extends Error {
+  /** The diagnostics the compiler reported, in the order it reported them. */
+  readonly diagnostics: readonly Diagnostic[];
+
+  constructor(message: string, diagnostics: readonly Diagnostic[]) {
+    super(message);
+    this.name = "DiscoveryError";
+    this.diagnostics = diagnostics;
+  }
+}
+
+/** Whether one diagnostic is an error, which is what fails a run closed. */
+export function isError(diagnostic: Diagnostic): boolean {
+  return diagnostic.category === DiagnosticCategory.Error;
+}
+
+/** One diagnostic as a line naming its position, its code and its message. */
+export function renderDiagnostic(diagnostic: Diagnostic): string {
+  const where = diagnostic.fileName ?? "<no file>";
+  return `${where}:${String(diagnostic.pos)}: TS${String(diagnostic.code)}: ${diagnostic.text}`;
+}
+
+/**
+ * Every error a project's three diagnostic sets carry, in the order the compiler
+ * reported them: a configuration whose options do not parse, a file whose syntax
+ * does not, and a program that does not type-check. A resolved configuration
+ * carries no diagnostics of its own, so a configuration written with an unreadable
+ * option resolves and is refused here, once its project is open.
+ */
+export function diagnosticErrors(sets: {
+  readonly syntactic: readonly Diagnostic[];
+  readonly semantic: readonly Diagnostic[];
+  readonly configParsing: readonly Diagnostic[];
+}): readonly Diagnostic[] {
+  return [...sets.configParsing, ...sets.syntactic, ...sets.semantic].filter(isError);
+}
+
+/** Every compiler configuration file discovery found, and where each came from. */
+export interface Discovery {
+  /** The configuration files, in discovery order, each once. */
+  readonly configFiles: readonly string[];
+  /** The files the scope named, which are the ones discovery read first. */
+  readonly fromScope: readonly string[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * The configuration files below `root`, in ascending path order, skipping an
+ * ignored directory. A directory that cannot be read is skipped: a tree the
+ * analysis may not enter names no project.
+ */
+function configFilesUnder(host: Host, root: string): string[] {
+  const found: string[] = [];
+  const pending = [root];
+  while (pending.length > 0) {
+    const dir = pending.pop();
+    if (dir === undefined) {
+      break;
+    }
+    let entries: readonly { readonly name: string; readonly directory: boolean }[];
+    try {
+      entries = host.readDirectory(dir);
+    } catch {
+      continue;
+    }
+    for (const entry of [...entries].sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      const path = joinPath(dir, entry.name);
+      if (entry.directory) {
+        if (!IGNORED_DIRECTORIES.has(entry.name)) {
+          pending.push(path);
+        }
+        continue;
+      }
+      if (CONFIG_FILE.test(entry.name)) {
+        found.push(path);
+      }
+    }
+  }
+  return found.sort();
+}
+
+/**
+ * The configuration files one configuration's `references` name, resolved against
+ * that configuration's own directory. A reference naming a directory names the
+ * `tsconfig.json` in it, which is the compiler's own rule.
+ */
+function referencesOf(host: Host, configFile: string): string[] {
+  let text: string;
+  try {
+    text = host.readFile(configFile);
+  } catch {
+    return [];
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    // What a configuration's contents say is refused by the compiler's own
+    // diagnostics, which name the position; nothing is inferred from it here.
+    return [];
+  }
+  if (!isRecord(value) || !Array.isArray(value["references"])) {
+    return [];
+  }
+  const dir = dirnamePath(configFile);
+  const found: string[] = [];
+  for (const entry of value["references"] as unknown[]) {
+    if (!isRecord(entry)) {
+      continue;
+    }
+    const path = entry["path"];
+    if (typeof path !== "string" || path === "") {
+      continue;
+    }
+    const resolved = isAbsolutePath(path) ? path : joinPath(dir, path);
+    found.push(resolved.endsWith(".json") ? resolved : joinPath(resolved, "tsconfig.json"));
+  }
+  return found;
+}
+
+/**
+ * The configuration files the scope names directly: one per module the scope
+ * declares whose path names a configuration file rather than a directory. A module
+ * naming a directory is reached by the walk over that directory instead.
+ */
+function scopeConfigFiles(host: Host, scope: Scope): string[] {
+  return [scope.target, ...scope.consumers]
+    .map((module) => module.path)
+    .filter((path) => path.endsWith(".json"))
+    .map((path) => resolvePath(host.workingDirectory(), path));
+}
+
+/**
+ * Every project one run analyzes, in the order discovery reads them: the paths the
+ * scope names, then every compiler configuration under the target root that is not
+ * inside an ignored directory, then the configurations each of those references,
+ * transitively. Each configuration appears once.
+ *
+ * A configuration file the compiler cannot read ends the run with the failure code,
+ * so a project that would have been analyzed with no type information is never
+ * analyzed at all. What a configuration's own contents say is refused once its
+ * project is open, by {@link diagnosticErrors} over the three sets a program
+ * reports, because a resolution carries no diagnostics.
+ *
+ * Nothing reads a build output: a project is the files its configuration names, so a
+ * package whose sources ship as TypeScript is analyzed as it stands.
+ */
+export function discoverProjects(engine: Engine, host: Host, scope: Scope): Discovery {
+  const fromScope = scopeConfigFiles(host, scope);
+  const seen = new Set<string>();
+  const configFiles: string[] = [];
+  const pending = [...fromScope, ...configFilesUnder(host, scope.target.path)];
+  while (pending.length > 0) {
+    const configFile = pending.shift();
+    if (configFile === undefined) {
+      break;
+    }
+    const path = resolvePath(host.workingDirectory(), configFile);
+    if (seen.has(path)) {
+      continue;
+    }
+    seen.add(path);
+    try {
+      engine.parseConfigFile(path);
+    } catch (error: unknown) {
+      throw new DiscoveryError(
+        `${path} cannot be read as a compiler configuration: ` +
+          (error instanceof Error ? error.message : String(error)),
+        [],
+      );
+    }
+    configFiles.push(path);
+    pending.push(...referencesOf(host, path));
+  }
+  return { configFiles, fromScope };
+}

package/src/host.ts

@@ -0,0 +1,29 @@
+/** What one path names. */
+export type PathKind = "file" | "directory" | "absent";
+
+/** One entry of a directory. */
+export interface DirectoryEntry {
+  readonly name: string;
+  readonly directory: boolean;
+}
+
+/**
+ * The filesystem the analysis reads, and the directory it reads relative paths
+ * against.
+ *
+ * It is a parameter rather than an import because a published module that reads
+ * the filesystem directly carries the whole platform's type surface into every
+ * consumer's compile, and because the run's own reads are then the one thing a
+ * caller can watch. The command line binds it to the platform it runs on; nothing
+ * under this module does.
+ */
+export interface Host {
+  /** The directory a relative path resolves against. */
+  workingDirectory(): string;
+  /** The text of one file, or a throw naming why it cannot be read. */
+  readFile(path: string): string;
+  /** The entries of one directory, or a throw naming why it cannot be read. */
+  readDirectory(path: string): readonly DirectoryEntry[];
+  /** What one path names, `"absent"` where nothing is there. */
+  kindOf(path: string): PathKind;
+}

package/src/index.ts

@@ -1 +1,29 @@
-export { run, type Writer } from "./run.ts";
+export { run, SETTING_OPTIONS, type Writer } from "./run.ts";
+export type { DirectoryEntry, Host, PathKind } from "./host.ts";
+export {
+  inventory,
+  type Inventory,
+  type InventoryCost,
+  type InventorySymbol,
+  type SymbolKind,
+  type Visibility,
+} from "./inventory.ts";
+export {
+  byPosition,
+  positionKey,
+  PositionError,
+  renderPosition,
+  type Position,
+} from "./position.ts";
+export {
+  computedComponent,
+  isRef,
+  nameComponent,
+  REF_EXPRESSIONS,
+  renderRef,
+  type Component,
+  type DependencySection,
+  type Fragment,
+  type Module,
+} from "./ref.ts";
+export { CONTRACT_VERSION, version } from "./version.ts";