@cplieger/deadset-ts 2.1.0 → 2.2.1

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 2.0.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
 
@@ -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/references.js

@@ -1,4 +1,5 @@
 import { isArrayLiteralExpression, isBinaryExpression, isDeleteExpression, isElementAccessExpression, isForInStatement, isForOfStatement, isObjectLiteralExpression, isParenthesizedExpression, isPostfixUnaryExpression, isPrefixUnaryExpression, isPropertyAccessExpression, isPropertyAssignment, isShorthandPropertyAssignment, isSpreadAssignment, isSpreadElement, SyntaxKind, } from "@typescript/native/unstable/ast";
+import { SymbolFlags } from "@typescript/native/unstable/sync";
 import { nodeKey } from "./inventory.js";
 import { byPosition, renderPosition } from "./position.js";
 /**
@@ -31,21 +32,6 @@ const ASSIGNMENTS = new Set([
     SyntaxKind.QuestionQuestionEqualsToken,
     SyntaxKind.CaretEqualsToken,
 ]);
-/**
- * The declaration forms that name something declared elsewhere. Each is a link rather
- * than a declaration of what it names, so a reference through one names the next link
- * and, at the end of the chain, the declaration itself: a re-export something imports
- * is used, and so is the declaration behind it.
- */
-const ALIASES = new Set([
-    SyntaxKind.ImportClause,
-    SyntaxKind.ImportEqualsDeclaration,
-    SyntaxKind.ImportSpecifier,
-    SyntaxKind.NamespaceImport,
-    SyntaxKind.ExportAssignment,
-    SyntaxKind.ExportSpecifier,
-    SyntaxKind.NamespaceExport,
-]);
 /** Whether one node is an identifier or a private name, the two forms a name takes. */
 function isName(node) {
     return node.kind === SyntaxKind.Identifier || node.kind === SyntaxKind.PrivateIdentifier;
@@ -303,11 +289,17 @@ export function references(project, held, targetRoot, options) {
      * is the declaration behind it, so both are named; a link this project does not
      * declare is stepped over rather than recorded.
      *
-     * A declaration handle carries the file it is in and the syntax it is written as, so
-     * both questions the walk asks of a declaration are answered before it is resolved: a
-     * declaration outside the project's own files belongs to another program and is never
-     * read, which is what keeps the pass from fetching a library file to discover that the
-     * inventory does not hold what is in it.
+     * A symbol is asked to step only where the binder flagged it an alias, which is the
+     * same condition the step itself asserts on. The declaration's syntax is not that
+     * condition and does not stand in for it: a default export of an expression is
+     * written as one of the alias forms and names nothing declared elsewhere, so it is
+     * recorded as the declaration it is and the chain ends there.
+     *
+     * A declaration handle carries the file it is in, so the question the walk asks of a
+     * declaration is answered before it is resolved: a declaration outside the project's
+     * own files belongs to another program and is never read, which is what keeps the
+     * pass from fetching a library file to discover that the inventory does not hold what
+     * is in it.
      */
     const targetsOf = (symbol) => {
         const cached = reached.get(symbol.id);
@@ -320,9 +312,8 @@ export function references(project, held, targetRoot, options) {
         let stepped = false;
         while (at !== undefined && !walked.has(at.id)) {
             walked.add(at.id);
-            let alias = false;
+            const alias = (at.flags & SymbolFlags.Alias) !== 0;
             for (const handle of at.declarations) {
-                alias = alias || ALIASES.has(handle.kind);
                 if (!ownFiles.has(handle.path)) {
                     continue;
                 }

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 = "2.0.0";
+export const CONTRACT_VERSION = "2.1.0";

package/jsr.json

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

package/package.json

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

package/src/references.ts

@@ -18,7 +18,7 @@ import {
   type Node,
   type SourceFile,
 } from "@typescript/native/unstable/ast";
-import type { Symbol as TSSymbol } from "@typescript/native/unstable/sync";
+import { SymbolFlags, type Symbol as TSSymbol } from "@typescript/native/unstable/sync";
 import { nodeKey, type Inventory } from "./inventory.ts";
 import { byPosition, renderPosition, type Position } from "./position.ts";
 import type { ProjectView } from "./session.ts";
@@ -159,22 +159,6 @@ const ASSIGNMENTS: ReadonlySet<SyntaxKind> = new Set([
   SyntaxKind.CaretEqualsToken,
 ]);
 
-/**
- * The declaration forms that name something declared elsewhere. Each is a link rather
- * than a declaration of what it names, so a reference through one names the next link
- * and, at the end of the chain, the declaration itself: a re-export something imports
- * is used, and so is the declaration behind it.
- */
-const ALIASES: ReadonlySet<SyntaxKind> = new Set([
-  SyntaxKind.ImportClause,
-  SyntaxKind.ImportEqualsDeclaration,
-  SyntaxKind.ImportSpecifier,
-  SyntaxKind.NamespaceImport,
-  SyntaxKind.ExportAssignment,
-  SyntaxKind.ExportSpecifier,
-  SyntaxKind.NamespaceExport,
-]);
-
 /** Whether one node is an identifier or a private name, the two forms a name takes. */
 function isName(node: Node): boolean {
   return node.kind === SyntaxKind.Identifier || node.kind === SyntaxKind.PrivateIdentifier;
@@ -479,11 +463,17 @@ export function references<Brand>(
    * is the declaration behind it, so both are named; a link this project does not
    * declare is stepped over rather than recorded.
    *
-   * A declaration handle carries the file it is in and the syntax it is written as, so
-   * both questions the walk asks of a declaration are answered before it is resolved: a
-   * declaration outside the project's own files belongs to another program and is never
-   * read, which is what keeps the pass from fetching a library file to discover that the
-   * inventory does not hold what is in it.
+   * A symbol is asked to step only where the binder flagged it an alias, which is the
+   * same condition the step itself asserts on. The declaration's syntax is not that
+   * condition and does not stand in for it: a default export of an expression is
+   * written as one of the alias forms and names nothing declared elsewhere, so it is
+   * recorded as the declaration it is and the chain ends there.
+   *
+   * A declaration handle carries the file it is in, so the question the walk asks of a
+   * declaration is answered before it is resolved: a declaration outside the project's
+   * own files belongs to another program and is never read, which is what keeps the
+   * pass from fetching a library file to discover that the inventory does not hold what
+   * is in it.
    */
   const targetsOf = (symbol: TSSymbol): readonly Target[] => {
     const cached = reached.get(symbol.id);
@@ -496,9 +486,8 @@ export function references<Brand>(
     let stepped = false;
     while (at !== undefined && !walked.has(at.id)) {
       walked.add(at.id);
-      let alias = false;
+      const alias = (at.flags & SymbolFlags.Alias) !== 0;
       for (const handle of at.declarations) {
-        alias = alias || ALIASES.has(handle.kind);
         if (!ownFiles.has(handle.path)) {
           continue;
         }

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 = "2.0.0";
+export const CONTRACT_VERSION = "2.1.0";