@cplieger/deadset-ts 1.2.0 → 2.0.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 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.
+**Status: pre-release.** This version implements contract 1.7.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.
 
 ## Install
 
@@ -20,7 +20,7 @@ npx jsr add -D @cplieger/deadset-ts
 npx @cplieger/deadset-ts version
 ```
 
-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.
+The npm package carries the command and the library as JavaScript that the compiler emits at publish, so `npx deadset-ts` and `import("@cplieger/deadset-ts")` both run on plain Node.js 24 or later, with no loader and no flag. It carries the TypeScript source as well, which is what a TypeScript consumer's own compiler resolves. That consumer sets `allowImportingTsExtensions`, because the source names each import with its `.ts` extension. The JSR package ships source only, and Deno compiles it.
 
 ## Usage
 
@@ -42,17 +42,56 @@ npx deadset-ts version
 
 ## Requirements
 
-- Node.js 24 or later, for the type stripping that runs the shipped source.
+- Node.js 24 or later. The npm command is JavaScript the compiler emits at publish, so it runs with no loader and no flag; a clone of this repository runs the same command from its TypeScript sources through Node's own type stripping, which is what needs the version.
 - TypeScript 7. The analyzer is written against the `typescript` package at exactly version 7.0.2 and its `unstable/*` API. It does not run on TypeScript 6, whose compiler API TypeScript 7 removed, and it does not fall back to it.
 - Linux. Other platforms are untested.
 
 ## API
 
-The package also exports the command line as a function, for callers that embed it:
+The package exports the command line and the analyzer's own stages, for callers that embed them. Every one of them reads the platform through a `Host`: the filesystem, the directory relative paths resolve against, and the version of the package the analyzer was installed from. `bin/node-host.ts` is the Node one the command line binds; a caller embedding the analyzer, or running it on another platform, supplies its own and supplies its own version with it.
 
-- `run(args, out, err)`: runs the command line over `args` (the arguments after the program name), writing to the two `Writer` streams, and returns the exit code. It never exits the process.
+The command line:
+
+- `run(args, out, err, host, openClient?)`: runs the command line over `args` (the arguments after the program name), writing to the two `Writer` streams, and returns the exit code. It never exits the process.
+- `SETTING_OPTIONS`: the configuration setting each command-line option supplies, by option name.
 - `Writer`: `{ write(text: string): void }`. `process.stdout` and `process.stderr` satisfy it.
 
+The platform:
+
+- `Host`: the filesystem a run reads, the directory it reads relative paths against, and the analyzer's own version.
+- `DirectoryEntry`, `PathKind`: one entry of a directory read, and what one path names.
+
+The symbol inventory:
+
+- `inventory(project, host, targetRoot)`: every declaration one project's own files hold, in position order, down to class and type members.
+- `nodeKey(file, node)`: the key one declaration is recorded under.
+- `Inventory`, `InventorySymbol`, `InventoryCost`, `SymbolKind`, `Visibility`: one project's inventory, one declaration of it, what reading it cost, and the two vocabularies a declaration is described by.
+
+The reference pass:
+
+- `references(project, held, targetRoot, options)`: every reference from one project's own files to a declaration of its inventory, in position order, with the rules that classified files as test files.
+- `DEFAULT_BATCH_CAP`: the batch size a run takes when the configuration names none.
+- `Reference`, `References`, `ReferenceOptions`, `ReferenceCost`, `TestFileRule`, `Resolution`, `Use`: one reference, one project's set of them, how a run resolves them, what that cost, one test-file rule, which accessor answered a reference, and whether it reads or writes.
+
+Positions:
+
+- `renderPosition(file, root, offset)`: one compiler offset as a path, a line and a column, the column counting UTF-16 code units.
+- `positionKey(position)`, `byPosition(a, b)`: the string one position is keyed by, and the order positions are reported in.
+- `PositionError`: the refusal for a position that cannot be rendered against the target root.
+- `Position`: one rendered position.
+
+Stable symbol references:
+
+- `renderRef(module, fragment)`: one symbol's stable reference, in the canonical spelling the contract's grammar fixes.
+- `nameComponent(name)`, `computedComponent(text)`: the canonical spelling of one component of that reference, from a declared name or from a computed key.
+- `isRef(value)`: whether one string is a reference of this language's grammar.
+- `REF_EXPRESSIONS`: one regular expression per form the grammar defines.
+- `Module`, `Component`, `Fragment`, `DependencySection`: the module half of a reference, one component of its fragment, what the fragment names, and the manifest section a dependency was declared in.
+
+Versions:
+
+- `CONTRACT_VERSION`: the contract version this analyzer implements.
+
 ## Contributing
 
 See [CONTRIBUTING.md](https://github.com/cplieger/.github/blob/main/CONTRIBUTING.md).

package/{bin/deadset-ts.ts → dist/bin/deadset-ts.js}

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

package/dist/bin/node-host.js

@@ -0,0 +1,74 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** The name the manifest of this package declares. */
+const PACKAGE_NAME = "@cplieger/deadset-ts";
+/** The version the walk found, read once per process. */
+let found;
+/**
+ * One manifest, or undefined where nothing readable is at that path: a file that
+ * cannot be read or parsed is not one that declares this package, so the walk
+ * passes it and the failure is the search's.
+ */
+function manifestAt(path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    return typeof parsed === "object" && parsed !== null ? parsed : undefined;
+}
+/**
+ * The version of the package this file is part of, from the nearest manifest at
+ * or above it that declares this package: a checkout resolves this file to the
+ * manifest beside it, the emitted tree resolves the emitted copy to the same
+ * file two directories up, and neither depth is written down. A manifest
+ * declaring something else is not this package's, so the walk continues past it
+ * rather than reporting the version of whatever the command was installed into.
+ */
+function readVersion() {
+    const from = dirname(fileURLToPath(import.meta.url));
+    let at = from;
+    for (;;) {
+        const manifest = manifestAt(join(at, "package.json"));
+        if (manifest?.name === PACKAGE_NAME && typeof manifest.version === "string") {
+            return manifest.version;
+        }
+        const up = dirname(at);
+        if (up === at) {
+            throw new Error(`no package.json declaring ${PACKAGE_NAME} with a version, from ${from} up to ${at}`);
+        }
+        at = up;
+    }
+}
+/**
+ * The filesystem of the platform the command runs on, and the version of the
+ * package it was installed from.
+ *
+ * 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() {
+    return {
+        workingDirectory: () => process.cwd(),
+        readFile: (path) => readFileSync(path, "utf8"),
+        readDirectory: (path) => readdirSync(path, { withFileTypes: true }).map((entry) => ({
+            name: entry.name,
+            directory: entry.isDirectory(),
+        })),
+        kindOf: (path) => {
+            const stat = statSync(path, { throwIfNoEntry: false });
+            if (stat === undefined) {
+                return "absent";
+            }
+            return stat.isDirectory() ? "directory" : "file";
+        },
+        analyzerVersion: () => {
+            found ??= readVersion();
+            return found;
+        },
+    };
+}

package/dist/src/config.js

@@ -0,0 +1,63 @@
+import { CONTRACT_VERSION } from "./version.js";
+/**
+ * The configuration every documented default states. `targetKind` is empty: the
+ * field has no default and is never inferred.
+ */
+export function defaultConfig() {
+    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: [],
+        },
+    };
+}
+/**
+ * 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) {
+    return origin.source === "default" ? "default" : `${origin.source}: ${origin.label}`;
+}
+/**
+ * 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. */
+    kind;
+    /**
+     * The key or field the message names, spelled as the document spells it. It is
+     * empty when the refusal names none.
+     */
+    key;
+    constructor(kind, key, message) {
+        super(message);
+        this.name = "ConfigError";
+        this.kind = kind;
+        this.key = key;
+    }
+}

package/dist/src/discover.js

@@ -0,0 +1,171 @@
+import { DiagnosticCategory } from "@typescript/native/unstable/sync";
+import { dirnamePath, isAbsolutePath, joinPath, resolvePath } from "./paths.js";
+/** Directory names discovery does not descend into. */
+const IGNORED_DIRECTORIES = 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. */
+    diagnostics;
+    constructor(message, diagnostics) {
+        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) {
+    return diagnostic.category === DiagnosticCategory.Error;
+}
+/** One diagnostic as a line naming its position, its code and its message. */
+export function renderDiagnostic(diagnostic) {
+    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) {
+    return [...sets.configParsing, ...sets.syntactic, ...sets.semantic].filter(isError);
+}
+function isRecord(value) {
+    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, root) {
+    const found = [];
+    const pending = [root];
+    while (pending.length > 0) {
+        const dir = pending.pop();
+        if (dir === undefined) {
+            break;
+        }
+        let entries;
+        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, configFile) {
+    let text;
+    try {
+        text = host.readFile(configFile);
+    }
+    catch {
+        return [];
+    }
+    let value;
+    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 = [];
+    for (const entry of value["references"]) {
+        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, scope) {
+    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, host, scope) {
+    const fromScope = scopeConfigFiles(host, scope);
+    const seen = new Set();
+    const configFiles = [];
+    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) {
+            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/dist/src/host.js

@@ -0,0 +1 @@
+export {};

package/dist/src/index.js

@@ -0,0 +1,6 @@
+export { run, SETTING_OPTIONS } from "./run.js";
+export { inventory, nodeKey, } from "./inventory.js";
+export { DEFAULT_BATCH_CAP, references, } from "./references.js";
+export { byPosition, positionKey, PositionError, renderPosition, } from "./position.js";
+export { computedComponent, isRef, nameComponent, REF_EXPRESSIONS, renderRef, } from "./ref.js";
+export { CONTRACT_VERSION } from "./version.js";