@cplieger/deadset-ts 1.2.0 → 2.1.0

package/dist/src/session.js

@@ -0,0 +1,101 @@
+import { API } from "@typescript/native/unstable/sync";
+import { isIdentifier } from "@typescript/native/unstable/ast";
+/**
+ * Opens the compiler client the analysis reads through.
+ *
+ * Closing twice releases once: a run that fails before its snapshot opens closes
+ * the client where it failed, and the outer release runs whatever happened, so the
+ * second call has nothing left to do.
+ */
+export function openEngine(options) {
+    const api = new API({ collectTiming: options.collectTiming });
+    let closed = false;
+    return {
+        parseConfigFile: (file) => api.parseConfigFile(file),
+        updateSnapshot: (openProjects) => api.updateSnapshot({ openProjects: [...openProjects] }),
+        getTimingInfo: () => api.getTimingInfo(),
+        close: () => {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            api.close();
+        },
+    };
+}
+function viewOf(project) {
+    // The snapshot is never updated, so a project's own file set is the same answer
+    // every time it is asked for. It is read once because the question is not free:
+    // deciding it consults the metadata of every file the program holds, the compiler's
+    // own library files included, and a run asks for the set once per pass.
+    let ownFiles;
+    return {
+        configFile: project.configFileName,
+        program: project.program,
+        checker: project.checker,
+        ownSourceFiles: () => {
+            ownFiles ??= project.program
+                .getSourceFileNames()
+                // The metadata decides which files belong to the target, and it is read by
+                // name. Fetching each file first and filtering afterwards costs one round
+                // trip per library file the answer then discards, and a program holds far
+                // more library files than target files.
+                .filter((name) => {
+                const metadata = project.program.getSourceFileMetadata(name);
+                return (metadata !== undefined && !metadata.isDefaultLibrary && !metadata.isFromExternalLibrary);
+            })
+                .map((name) => project.program.getSourceFile(name))
+                .filter((file) => file !== undefined);
+            return ownFiles;
+        },
+        handle: (node) => ({ node }),
+        symbolsAt: (handles) => project.checker.getSymbolAtLocation(handles.map(({ node }) => node)),
+        resolvedSymbolAt: ({ node }) => isIdentifier(node) ? project.checker.getResolvedSymbol(node) : undefined,
+        shorthandValueAt: ({ node }) => project.checker.getShorthandAssignmentValueSymbol(node),
+        aliasStepOf: (symbol) => {
+            const held = project.checker.getImmediateAliasedSymbol(symbol);
+            // An alias that resolves to nothing answers with the checker's own unknown
+            // symbol, which declares nothing; a symbol that is no alias answers with
+            // nothing at all.
+            return held === undefined || held.declarations.length === 0 ? undefined : held;
+        },
+        declarationAt: (handle) => {
+            const node = handle.resolve(project);
+            return node === undefined ? undefined : { node };
+        },
+    };
+}
+/** The three diagnostic sets one project carries, read before any analysis. */
+export function diagnosticsOf(project) {
+    return {
+        configFile: project.configFile,
+        syntactic: project.program.getSyntacticDiagnostics(),
+        semantic: project.program.getSemanticDiagnostics(),
+        configParsing: project.program.getConfigFileParsingDiagnostics(),
+    };
+}
+/**
+ * Runs `visit` over every project the compiler configurations name, inside one
+ * snapshot of one client.
+ *
+ * The snapshot is opened once with every configuration, so each becomes a project
+ * with its own program and checker; it is never updated, because the analysis
+ * reads and the tree does not change under it. It is disposed once when the last
+ * project has been visited, and the client is released after it, whether the visit
+ * completed or threw.
+ */
+export function runSession(engine, configFiles, visit) {
+    try {
+        const snapshot = engine.updateSnapshot(configFiles);
+        try {
+            const projects = snapshot.getProjects().map((project) => visit(viewOf(project)));
+            return { projects, timing: engine.getTimingInfo() };
+        }
+        finally {
+            snapshot.dispose();
+        }
+    }
+    finally {
+        engine.close();
+    }
+}

package/dist/src/version.js

@@ -0,0 +1,7 @@
+/**
+ * The Contract version this analyzer implements. It is the resolved value of
+ * `contract_version` when no configuration source supplies one, and it moves
+ * independently of the analyzer's own version, which is the one the host answers
+ * from the package the analyzer was installed from.
+ */
+export const CONTRACT_VERSION = "2.0.0";

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "1.2.0",
+  "version": "2.1.0",
   "license": "GPL-3.0-or-later",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,20 +1,25 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "1.2.0",
+  "version": "2.1.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.mjs"
+    "deadset-ts": "./dist/bin/deadset-ts.js"
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/src/index.js"
+    }
   },
   "engines": {
     "node": ">=24"
   },
   "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
     "typecheck": "tsc -p tsconfig.json",
     "typecheck:tests": "tsc -p tsconfig.test.json",
     "test": "vitest --run",
@@ -58,7 +63,7 @@
   "files": [
     "LICENSE",
     "NOTICE",
-    "bin/",
+    "dist/",
     "src/",
     "!src/**/*.test.ts",
     "jsr.json"

package/src/host.ts

@@ -8,8 +8,9 @@ export interface DirectoryEntry {
 }
 
 /**
- * The filesystem the analysis reads, and the directory it reads relative paths
- * against.
+ * The platform one run reads: the filesystem, the directory relative paths
+ * resolve against, and the version of the package this analyzer was installed
+ * from.
  *
  * 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
@@ -26,4 +27,11 @@ export interface Host {
   readDirectory(path: string): readonly DirectoryEntry[];
   /** What one path names, `"absent"` where nothing is there. */
   kindOf(path: string): PathKind;
+  /**
+   * The version of the package this analyzer was installed from, or a throw
+   * naming why it cannot be known. It is a method rather than a value because
+   * locating that package is a filesystem walk, and a host that cannot do it
+   * says so at the one moment the value is asked for.
+   */
+  analyzerVersion(): string;
 }

package/src/index.ts

@@ -2,12 +2,24 @@ export { run, SETTING_OPTIONS, type Writer } from "./run.ts";
 export type { DirectoryEntry, Host, PathKind } from "./host.ts";
 export {
   inventory,
+  nodeKey,
   type Inventory,
   type InventoryCost,
   type InventorySymbol,
   type SymbolKind,
   type Visibility,
 } from "./inventory.ts";
+export {
+  DEFAULT_BATCH_CAP,
+  references,
+  type Reference,
+  type ReferenceCost,
+  type ReferenceOptions,
+  type References,
+  type Resolution,
+  type TestFileRule,
+  type Use,
+} from "./references.ts";
 export {
   byPosition,
   positionKey,
@@ -26,4 +38,4 @@ export {
   type Fragment,
   type Module,
 } from "./ref.ts";
-export { CONTRACT_VERSION, version } from "./version.ts";
+export { CONTRACT_VERSION } from "./version.ts";

package/src/inventory.ts

@@ -15,6 +15,7 @@ import {
   isModuleBlock,
   isModuleDeclaration,
   isNamespaceExport,
+  isParenthesizedTypeNode,
   isPrivateIdentifier,
   isPropertyDeclaration,
   isPropertySignatureDeclaration,
@@ -133,6 +134,17 @@ export interface Inventory {
   /** The compiler configuration the project was opened from. */
   readonly configFile: string;
   readonly symbols: readonly InventorySymbol[];
+  /**
+   * Each declaring node's {@link nodeKey} mapped to the identifier of the declaration
+   * enumerated there. A reading that starts from a node of the same program, rather
+   * than from a position, resolves the declaration through this map instead of
+   * rendering the position a second time, so the rule that decides a declaration's
+   * identifier has one owner.
+   *
+   * A getter and a setter of one name are one declaration and two nodes, so both nodes
+   * name it.
+   */
+  readonly declarations: ReadonlyMap<string, string>;
   readonly cost: InventoryCost;
   /**
    * The module specifiers of the bare star re-exports the project's files carry, in
@@ -316,6 +328,31 @@ function memberKey(component: Component, isStatic: boolean): string {
   return `${component.computed ? "[" : ""}${component.text}${isStatic ? ":static" : ""}`;
 }
 
+/** The type one node is, through however many parentheses are written around it. */
+function unparenthesizedType(type: Node): Node {
+  let held = type;
+  while (isParenthesizedTypeNode(held)) {
+    held = held.type;
+  }
+  return held;
+}
+
+/**
+ * The direct constituents of one type. Parentheses are syntax and are not a
+ * constituent, so a parenthesized type contributes the constituents it holds: the
+ * constituents of `(A | B) & C` are `A`, `B` and `C`. A union or an intersection
+ * written without them stays one constituent.
+ */
+function constituentsOf(type: Node): readonly Node[] {
+  const held = unparenthesizedType(type);
+  if (!isUnionTypeNode(held) && !isIntersectionTypeNode(held)) {
+    return [held];
+  }
+  return held.types.flatMap((member) =>
+    isParenthesizedTypeNode(member) ? constituentsOf(member) : [member],
+  );
+}
+
 /**
  * The members one type alias declares: the members of the object type it writes, and
  * of every object type that is a direct constituent of a union or an intersection it
@@ -327,11 +364,7 @@ function memberKey(component: Component, isStatic: boolean): string {
  * neither of them is the one a reference to it would name.
  */
 function aliasMembers(type: Node): readonly Node[] {
-  const literals = isTypeLiteralNode(type)
-    ? [type]
-    : isUnionTypeNode(type) || isIntersectionTypeNode(type)
-      ? type.types.filter(isTypeLiteralNode)
-      : [];
+  const literals = constituentsOf(type).filter(isTypeLiteralNode);
   if (literals.length < 2) {
     return literals[0]?.members ?? [];
   }
@@ -407,8 +440,15 @@ function nameNodeOf(node: Node): Node | undefined {
   return (node as { readonly name?: Node }).name;
 }
 
-/** One node's identity across the two mechanisms, which resolve it separately. */
-function nodeKey(file: SourceFile, node: Node): string {
+/**
+ * One node's identity inside one program, which is how two readings of that program
+ * name one declaration.
+ *
+ * The two mechanisms behind the member set resolve a member separately and meet here;
+ * so does the reference pass, which starts from a resolved symbol's declaration and
+ * needs the declaration this enumeration made for it.
+ */
+export function nodeKey(file: SourceFile, node: Node): string {
   return `${file.fileName}:${String(node.pos)}:${String(node.end)}`;
 }
 
@@ -828,8 +868,10 @@ export function inventory<Brand>(
     const endLine = renderPosition(file, targetRoot, Math.max(node.end - 1, 0)).line;
     if (held !== undefined) {
       // A getter and a setter of one name are one symbol and one reference, so the
-      // second declaration widens the first record rather than making a second.
+      // second declaration widens the first record rather than making a second. Both
+      // nodes name that record, so a reading that starts from either one finds it.
       held.endLine = Math.max(held.endLine, endLine);
+      byNode.set(nodeKey(file, node), held);
       return;
     }
     const at = name ?? node;
@@ -884,6 +926,9 @@ export function inventory<Brand>(
   return {
     configFile: project.configFile,
     symbols,
+    declarations: new Map(
+      [...byNode].map(([key, record]) => [key, positionKey(record.position)] as const),
+    ),
     cost: { batches: 1, exportTables, memberTables },
     starReExports,
     outsideOwnFiles,