@cplieger/deadset-ts 2.0.0 → 2.2.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.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.
+**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.
 
 ## Install
 
@@ -20,7 +20,7 @@ npx jsr add -D @cplieger/deadset-ts
 npx @cplieger/deadset-ts version
 ```
 
-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.
+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: a Deno program imports and type-checks the library, but the compiler's synchronous session does not open under Deno, so running an analysis needs Node.
 
 ## Usage
 
@@ -70,7 +70,7 @@ The symbol inventory:
 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.
+- `DEFAULT_BATCH_CAP`: the batch size the reference pass takes when its caller passes none; it is an option of the pass, not a configuration key. [Batch-cap calibration](docs/batch-cap-calibration.md) is the measurement that set it.
 - `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:

package/dist/src/inventory.js

@@ -1,4 +1,4 @@
-import { isClassDeclaration, isComputedPropertyName, isEnumDeclaration, isEnumMember, isExportAssignment, isExportDeclaration, isFunctionDeclaration, isGetAccessorDeclaration, isIdentifier, isInterfaceDeclaration, isIntersectionTypeNode, isMethodDeclaration, isMethodSignatureDeclaration, isModuleBlock, isModuleDeclaration, isNamespaceExport, isPrivateIdentifier, isPropertyDeclaration, isPropertySignatureDeclaration, isSetAccessorDeclaration, isTypeAliasDeclaration, isTypeLiteralNode, isUnionTypeNode, isVariableStatement, ModifierFlags, } from "@typescript/native/unstable/ast";
+import { isClassDeclaration, isComputedPropertyName, isEnumDeclaration, isEnumMember, isExportAssignment, isExportDeclaration, isFunctionDeclaration, isGetAccessorDeclaration, isIdentifier, isInterfaceDeclaration, isIntersectionTypeNode, isMethodDeclaration, isMethodSignatureDeclaration, isModuleBlock, isModuleDeclaration, isNamespaceExport, isParenthesizedTypeNode, isPrivateIdentifier, isPropertyDeclaration, isPropertySignatureDeclaration, isSetAccessorDeclaration, isTypeAliasDeclaration, isTypeLiteralNode, isUnionTypeNode, isVariableStatement, ModifierFlags, } from "@typescript/native/unstable/ast";
 import { dirnamePath, joinPath, relativePath } from "./paths.js";
 import { byPosition, positionKey, renderPosition } from "./position.js";
 import { computedComponent, nameComponent, renderRef } from "./ref.js";
@@ -104,6 +104,27 @@ function isStringOrNumericName(name) {
 function memberKey(component, isStatic) {
     return `${component.computed ? "[" : ""}${component.text}${isStatic ? ":static" : ""}`;
 }
+/** The type one node is, through however many parentheses are written around it. */
+function unparenthesizedType(type) {
+    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) {
+    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
@@ -115,11 +136,7 @@ function memberKey(component, isStatic) {
  * neither of them is the one a reference to it would name.
  */
 function aliasMembers(type) {
-    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 ?? [];
     }

package/dist/src/version.js

@@ -4,4 +4,4 @@
  * 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 = "1.7.0";
+export const CONTRACT_VERSION = "2.1.0";

package/jsr.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "type": "module",
   "sideEffects": false,
   "description": "Deterministic dead-code analysis for TypeScript, class and type members included",

package/src/inventory.ts

@@ -15,6 +15,7 @@ import {
   isModuleBlock,
   isModuleDeclaration,
   isNamespaceExport,
+  isParenthesizedTypeNode,
   isPrivateIdentifier,
   isPropertyDeclaration,
   isPropertySignatureDeclaration,
@@ -327,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
@@ -338,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 ?? [];
   }

package/src/version.ts

@@ -4,4 +4,4 @@
  * 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 = "1.7.0";
+export const CONTRACT_VERSION = "2.1.0";