@esportsplus/typescript 0.29.6 → 0.31.1

package/README.md

@@ -18,6 +18,7 @@ Extends the TypeScript compiler with a plugin architecture for custom AST transf
 - Vite plugin for dev/build integration
 - CLI wrapper for `tsc` with automatic plugin detection
 - Language service caching for incremental compilation
+- `analyze` throw-safety analysis on the `tsc` passthrough and over LSP
 
 ## Usage
 
@@ -72,13 +73,90 @@ export default defineConfig({
 tsc
 ```
 
-The CLI detects plugins in `tsconfig.json` `compilerOptions.plugins`, loads them, runs coordinated compilation, and automatically calls `tsc-alias` afterward.
+The CLI detects plugins in `tsconfig.json` `compilerOptions.plugins`, loads them, runs coordinated compilation, and automatically calls `tsc-alias` afterward. The package installs `tsc`/`tsc-alias` bins (also under the unambiguous `esportsplus-tsc`/`esportsplus-tsc-alias` names).
+
+## analyze
+
+`analyze` is a static analyzer for effects TypeScript's types leave implicit. It runs a per-function summary fixpoint over the call graph — so a finding points at the *consumer*, the call site where a caller should be careful — and is organised into **channels**, each checking one class of effect:
+
+- **`exceptions`** — calls that may throw with no `catch` on the path to a handler boundary, `@throws` under-declaration, and `catch` rethrows that drop the caught error's `cause`. Carries the throw origin as related information.
+- **`resources`** — acquired resources (timers, event listeners, file handles, sockets, `Disposable`s, …) that can leak: not released, transferred, or `using`-bound on every path — including throwing paths, which it derives from the `exceptions` channel's summaries.
+- **`async`** — unbounded `Promise.all(…)`-style fan-out, orphaned promises whose rejections go unhandled, and awaited cancellable calls that drop an `AbortSignal` the function holds.
+
+Only `exceptions` is on by default; enable the others per project. It rides the `tsc` passthrough (build/CI), and ships an LSP server so editors can render the same findings.
+
+### Enable
+
+Add an `analyze` entry to `compilerOptions.plugins`. Analysis covers every file the tsconfig includes (ignoring excludes); no config beyond the entry is required.
+
+```jsonc
+{
+    "compilerOptions": {
+        "plugins": [
+            {
+                "name": "ts-probe",
+                // Editor squiggle color; "warn" opts down. CLI/build ignore this.
+                "severity": "error",
+                // Fail the tsc/build run when there are findings.
+                "failOnFindings": true,
+                // Per-channel config. `enabled` and `dispatch` are recognised on
+                // every channel; other keys are that channel's own options.
+                "channels": {
+                    "exceptions": {
+                        "enabled": true,
+                        // "consumers" (default): uncaught calls only.
+                        // "cross-module": only when the throwing callee is in another package.
+                        // "all": throws AND uncaught calls.
+                        "report": "consumers",
+                        // Flag `throw`s inside `catch` that drop the caught error's cause.
+                        "errorCause": true
+                    },
+                    "resources": {
+                        "enabled": true,
+                        // Untrackable handling when a resource escapes local analysis:
+                        // "optimist" assumes transfer (silent), "pessimist" reports it.
+                        "dispatch": "optimist",
+                        // Calls that take ownership of a passed resource argument.
+                        "ownership": [{ "callee": "registerCleanup", "params": [0] }]
+                    },
+                    "async": {
+                        "enabled": true,
+                        "fanOut": "warn",                     // "off" | "warn" | "error"
+                        "fanOutAllowLiteralUpTo": 16,         // inline array/tuple size that is fine
+                        "poolFunctions": ["p-limit", "p-map"] // sanctioned concurrency wrappers
+                    }
+                },
+                // Model third-party throw behavior: "node", "express".
+                "presets": ["node"]
+            }
+        ]
+    }
+}
+```
+
+### CLI / build
+
+The `tsc` passthrough runs analyze after a successful compile and prints findings to stderr. With `failOnFindings: true`, a run with findings exits non-zero — drop it into CI as a gate.
+
+```bash
+tsc   # compiles, resolves aliases, then reports analyze findings
+```
+
+### Editor (LSP)
+
+The package ships a standalone language server (`esportsplus-tsc-lsp` bin, or the `@esportsplus/typescript/lsp` export) that publishes analyze findings over LSP. A client spawns it beside the native TypeScript server and merges both diagnostic streams; `severity` drives the squiggle color. Analysis runs against saved files on open and save. Beyond diagnostics it serves **hovers** (the finding plus its origin→boundary chain) and **quick-fixes** — `void`/`await` an orphaned promise, forward an `AbortSignal`, or fix a leaked handle by converting it to `using` or wrapping the region in `try/finally`.
+
+```typescript
+import { startServer } from '@esportsplus/typescript/lsp';
+
+startServer(); // stdio LSP server
+```
 
 ## API
 
 ### `@esportsplus/typescript`
 
-Re-exports the TypeScript compiler API (`ts`).
+No exports. Import the TypeScript compiler API directly from `typescript/unstable/*` (see [TypeScript 7 migration](#typescript-7-migration)).
 
 ### `@esportsplus/typescript/compiler`
 
@@ -90,7 +168,14 @@ Re-exports the TypeScript compiler API (`ts`).
 | `imports` | Import detection and modification (WeakMap cached) |
 | `plugin` | Built-in plugins (`tsc`, `vite`) |
 | `uid` | Unique identifier generation |
-| `languageService` | Cached TypeScript language service |
+
+### `@esportsplus/typescript/lsp`
+
+| Export | Description |
+|---|---|
+| `startServer` | Start the stdio analyze LSP server |
+| `createServer` | Wire the server onto an existing JSON-RPC connection |
+| `AnalyzeWorkspace` | Long-lived native session that re-runs the analysis |
 
 ### Types
 
@@ -137,6 +222,15 @@ Importable base tsconfig files:
 { "extends": "@esportsplus/typescript/tsconfig.package.json" }
 ```
 
+## TypeScript 7 migration
+
+This package targets `typescript@^7`, shipped as a regular `dependencies` entry. Breaking changes for consumers:
+
+- **Root export removed.** `@esportsplus/typescript` no longer re-exports `ts`. Import the compiler API directly from the `typescript/unstable/*` subpaths you need — `typescript/unstable/ast`, `typescript/unstable/ast/is`, `typescript/unstable/sync`, `typescript/unstable/fs`, etc.
+- **Plugin-facing types.** `TransformContext` and `ReplacementIntent` now carry `typescript/unstable/ast` + `typescript/unstable/sync` identities instead of the classic `ts` namespace types.
+- **`coordinator.transform` signature.** Takes the `{ checker, program }` project pair instead of a single `ts.Program`.
+- **`imports.includes` signature.** Takes the API `Checker` type, and symbol declarations are represented as NodeHandles rather than `ts.Node`.
+
 ## Scripts
 
 ```bash

package/bin/tsc-alias

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
 
-(await import ('@esportsplus/cli-passthrough')).default('tsc-alias');
+(await import ('@esportsplus/cli-passthrough')).default('tsc-alias');

package/bin/tsc-lsp

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../build/lsp/bin.js';

package/build/cli/diagnostics.d.ts

@@ -0,0 +1,8 @@
+import { type Diagnostic } from 'typescript/unstable/sync';
+import type { PositionMapping } from '../compiler/sourcemap.js';
+declare const flatten: (diagnostic: Diagnostic, indent?: number) => string;
+declare const format: (diagnostics: readonly Diagnostic[], root: string, transformed?: Map<string, {
+    code: string;
+    mapping: PositionMapping;
+}>) => string;
+export { flatten, format };

package/build/cli/diagnostics.js

@@ -0,0 +1,95 @@
+import { readFileSync } from 'fs';
+import { computeLineStarts } from 'typescript/unstable/ast/scanner';
+import { DiagnosticCategory } from 'typescript/unstable/sync';
+import path from 'path';
+import { resolveOffset } from '../compiler/sourcemap.js';
+const ANSI_BLUE = '\x1b[94m';
+const ANSI_CYAN = '\x1b[96m';
+const ANSI_GREY = '\x1b[90m';
+const ANSI_RED = '\x1b[91m';
+const ANSI_RESET = '\x1b[0m';
+const ANSI_YELLOW = '\x1b[93m';
+const BACKSLASH_REGEX = /\\/g;
+const TRAILING_NEWLINE_REGEX = /\r?\n$/;
+function categoryColor(category) {
+    switch (category) {
+        case DiagnosticCategory.Error:
+            return ANSI_RED;
+        case DiagnosticCategory.Suggestion:
+            return ANSI_BLUE;
+        case DiagnosticCategory.Warning:
+            return ANSI_YELLOW;
+        default:
+            return ANSI_GREY;
+    }
+}
+function categoryLabel(category) {
+    switch (category) {
+        case DiagnosticCategory.Error:
+            return 'error';
+        case DiagnosticCategory.Suggestion:
+            return 'suggestion';
+        case DiagnosticCategory.Warning:
+            return 'warning';
+        default:
+            return 'message';
+    }
+}
+function formatOne(diagnostic, root, sources, transformed) {
+    let category = categoryLabel(diagnostic.category), code = `${ANSI_GREY}TS${diagnostic.code}${ANSI_RESET}`, color = categoryColor(diagnostic.category), message = flatten(diagnostic);
+    if (diagnostic.fileName === undefined) {
+        return `${color}${category}${ANSI_RESET} ${code}: ${message}`;
+    }
+    let location = `${ANSI_CYAN}${path.relative(root, diagnostic.fileName).replace(BACKSLASH_REGEX, '/')}${ANSI_RESET}`, entry = transformed?.get(diagnostic.fileName.replace(BACKSLASH_REGEX, '/')), end = entry ? resolveOffset(entry.mapping, diagnostic.end) : diagnostic.end, pos = entry ? resolveOffset(entry.mapping, diagnostic.pos) : diagnostic.pos, sourceInfo = sources.get(diagnostic.fileName) ?? readSourceInfo(diagnostic.fileName);
+    sources.set(diagnostic.fileName, sourceInfo);
+    const text = sourceInfo.text;
+    if (text === undefined) {
+        return `${location} - ${color}${category}${ANSI_RESET} ${code}: ${message}`;
+    }
+    let lineStarts = sourceInfo.lineStarts, line = lineOfPosition(lineStarts, pos), character = pos - lineStarts[line], lineEnd = line + 1 < lineStarts.length ? lineStarts[line + 1] : text.length, source = text.slice(lineStarts[line], lineEnd).replace(TRAILING_NEWLINE_REGEX, ''), width = Math.max(1, Math.min(end, lineEnd) - pos), underline = `${' '.repeat(character)}${color}${'~'.repeat(width)}${ANSI_RESET}`, header = `${location}:${ANSI_YELLOW}${line + 1}${ANSI_RESET}:${ANSI_YELLOW}${character + 1}${ANSI_RESET} - ${color}${category}${ANSI_RESET} ${code}: ${message}`;
+    return `${header}\n\n${source}\n${underline}`;
+}
+function lineOfPosition(lineStarts, position) {
+    let high = lineStarts.length - 1, low = 0;
+    while (low <= high) {
+        let middle = (low + high) >> 1;
+        if (lineStarts[middle] <= position) {
+            low = middle + 1;
+        }
+        else {
+            high = middle - 1;
+        }
+    }
+    return high < 0 ? 0 : high;
+}
+function readSourceInfo(fileName) {
+    try {
+        const text = readFileSync(fileName, 'utf8');
+        return { lineStarts: computeLineStarts(text), text };
+    }
+    catch {
+        return { lineStarts: [], text: undefined };
+    }
+}
+const flatten = (diagnostic, indent = 0) => {
+    let result = '';
+    if (indent > 0) {
+        result += `\n${'  '.repeat(indent)}`;
+    }
+    result += diagnostic.text;
+    if (diagnostic.messageChain !== undefined) {
+        for (let i = 0, n = diagnostic.messageChain.length; i < n; i++) {
+            result += flatten(diagnostic.messageChain[i], indent + 1);
+        }
+    }
+    return result;
+};
+const format = (diagnostics, root, transformed) => {
+    let parts = [];
+    const sources = new Map();
+    for (let i = 0, n = diagnostics.length; i < n; i++) {
+        parts.push(formatOne(diagnostics[i], root, sources, transformed));
+    }
+    return parts.join('\n\n');
+};
+export { flatten, format };

package/build/cli/tsc.d.ts

@@ -1,10 +1,20 @@
 import type { Plugin } from '../compiler/types.js';
+import { API } from 'typescript/unstable/sync';
+import { stripJsonc } from '../jsonc.js';
 type PluginConfig = {
     transform: string;
 };
-declare function build(config: object, tsconfig: string, pluginConfigs: PluginConfig[]): Promise<void>;
+declare function build(tsconfig: string, pluginConfigs: PluginConfig[], instance?: API, noEmit?: boolean): Promise<void>;
+declare function classifyFlags(args: string[]): {
+    informational: boolean;
+    noEmit: boolean;
+    watch: boolean;
+};
 declare function isPlugin(value: unknown): value is Plugin;
 declare function loadPlugins(configs: PluginConfig[], root: string): Promise<Plugin[]>;
+declare function main(): void;
 declare function normalizePath(fileName: string): string;
+declare function projectPath(args: string[]): string | null;
+declare function resolvePluginConfigs(tsconfig: string): PluginConfig[];
 declare function runTscAlias(args: string[]): Promise<number>;
-export { build, isPlugin, loadPlugins, normalizePath, runTscAlias };
+export { build, classifyFlags, isPlugin, loadPlugins, main, normalizePath, projectPath, resolvePluginConfigs, runTscAlias, stripJsonc };