@esportsplus/typescript 0.29.1 → 0.29.6

package/.github/workflows/bump.yml

@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
       - name: bump version

package/.github/workflows/dependabot.yml

@@ -20,13 +20,13 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
         name: Install pnpm
         with:
           run_install: false
           version: latest
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           cache: 'pnpm'
           node-version: 'latest'
@@ -43,7 +43,7 @@ jobs:
     runs-on: ubuntu-latest
     if: ${{ github.actor == 'dependabot[bot]' && github.event_name == 'pull_request' }}
     steps:
-      - uses: dependabot/fetch-metadata@v2
+      - uses: dependabot/fetch-metadata@v3
         id: metadata
         with:
           alert-lookup: true

package/.github/workflows/publish.yml

@@ -24,18 +24,17 @@ jobs:
       contents: read
       id-token: write
     steps:
-      - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
         name: Install pnpm
         with:
           run_install: false
           version: latest
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           cache: 'pnpm'
           node-version: 'latest'
           registry-url: 'https://registry.npmjs.org'
-      - run: pnpm config delete always-auth
       - run: pnpm i
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,146 @@
+# @esportsplus/typescript
+
+TypeScript compiler plugin framework with coordinated AST transformations, import management, and build tool integration.
+
+## Install
+
+```bash
+pnpm add @esportsplus/typescript
+```
+
+## Overview
+
+Extends the TypeScript compiler with a plugin architecture for custom AST transformations. Plugins receive type-checked AST nodes with accurate positions at every stage, return declarative intents (replacements, imports, prepends), and the coordinator applies them in the correct order.
+
+**Key features:**
+- Multi-plugin coordination with fresh AST positions between stages
+- Declarative import management (add/remove specifiers, namespace imports)
+- Vite plugin for dev/build integration
+- CLI wrapper for `tsc` with automatic plugin detection
+- Language service caching for incremental compilation
+
+## Usage
+
+### Plugin
+
+```typescript
+import type { Plugin } from '@esportsplus/typescript/compiler';
+
+let plugin: Plugin = {
+    // Optional: skip files that don't contain these strings
+    patterns: ['myFunction'],
+
+    transform({ checker, code, sourceFile, shared }) {
+        // Return declarative transformation intents
+        return {
+            imports: [
+                { package: 'my-lib', add: ['helper'], remove: ['deprecated'] }
+            ],
+            prepend: [
+                'let __cache = new Map();'
+            ],
+            replacements: [
+                {
+                    node: someAstNode,
+                    generate: (sf) => `transformedCode()`
+                }
+            ]
+        };
+    }
+};
+```
+
+### Vite
+
+```typescript
+import { plugin } from '@esportsplus/typescript/compiler';
+
+export default defineConfig({
+    plugins: [
+        plugin.vite({
+            name: 'my-transforms',
+            plugins: [myPlugin]
+        })
+    ]
+});
+```
+
+### CLI
+
+```bash
+# Compiles with plugins from tsconfig.json, then resolves path aliases
+tsc
+```
+
+The CLI detects plugins in `tsconfig.json` `compilerOptions.plugins`, loads them, runs coordinated compilation, and automatically calls `tsc-alias` afterward.
+
+## API
+
+### `@esportsplus/typescript`
+
+Re-exports the TypeScript compiler API (`ts`).
+
+### `@esportsplus/typescript/compiler`
+
+| Export | Description |
+|---|---|
+| `ast` | AST utilities — expression names, property paths, node testing |
+| `code` | Template literal code generation with escaping |
+| `coordinator` | Multi-plugin transformation orchestrator |
+| `imports` | Import detection and modification (WeakMap cached) |
+| `plugin` | Built-in plugins (`tsc`, `vite`) |
+| `uid` | Unique identifier generation |
+| `languageService` | Cached TypeScript language service |
+
+### Types
+
+```typescript
+type Plugin = {
+    patterns?: string[];
+    transform: (ctx: TransformContext) => TransformResult;
+};
+
+type TransformContext = {
+    checker: ts.TypeChecker;
+    code: string;
+    program: ts.Program;
+    shared: SharedContext;
+    sourceFile: ts.SourceFile;
+};
+
+type TransformResult = {
+    imports?: ImportIntent[];
+    prepend?: string[];
+    replacements?: ReplacementIntent[];
+};
+
+type ImportIntent = {
+    add?: string[];
+    namespace?: string;
+    package: string;
+    remove?: string[];
+};
+
+type ReplacementIntent = {
+    generate: (sourceFile: ts.SourceFile) => string;
+    node: ts.Node;
+};
+```
+
+## Shared Config
+
+Importable base tsconfig files:
+
+```json
+{ "extends": "@esportsplus/typescript/tsconfig.browser.json" }
+{ "extends": "@esportsplus/typescript/tsconfig.node.json" }
+{ "extends": "@esportsplus/typescript/tsconfig.package.json" }
+```
+
+## Scripts
+
+```bash
+pnpm build       # tsc && tsc-alias
+pnpm test        # vitest run
+pnpm bench:run   # vitest bench --run
+```

package/build/compiler/coordinator.js

@@ -92,7 +92,8 @@ function modify(code, file, pkg, options) {
     for (let i = 0, n = found.length; i < n; i++) {
         for (let [name, alias] of found[i].specifiers) {
             if (!remove || (!remove.has(name) && !remove.has(alias))) {
-                specifiers.add(name === alias ? name : `${name} as ${alias}`);
+                let base = name === alias ? name : `${name} as ${alias}`;
+                specifiers.add(found[i].typeOnly.has(name) ? `type ${base}` : base);
             }
         }
     }

package/build/compiler/imports.d.ts

@@ -2,6 +2,7 @@ import { ts } from '../index.js';
 type ImportInfo = {
     end: number;
     specifiers: Map<string, string>;
+    typeOnly: Set<string>;
     start: number;
 };
 type ModifyOptions = {

package/build/compiler/imports.js

@@ -15,14 +15,17 @@ const all = (file, pkg) => {
         if (!ts.isStringLiteral(moduleSpecifier) || moduleSpecifier.text !== pkg) {
             continue;
         }
-        let bindings = stmt.importClause?.namedBindings, specifiers = new Map();
+        let bindings = stmt.importClause?.namedBindings, declTypeOnly = stmt.importClause?.isTypeOnly ?? false, specifiers = new Map(), typeOnly = new Set();
         if (bindings && ts.isNamedImports(bindings)) {
             for (let j = 0, m = bindings.elements.length; j < m; j++) {
                 let element = bindings.elements[j], name = element.name.text, propertyName = element.propertyName?.text || name;
                 specifiers.set(propertyName, name);
+                if (declTypeOnly || element.isTypeOnly) {
+                    typeOnly.add(propertyName);
+                }
             }
         }
-        imports.push({ end: stmt.end, specifiers, start: stmt.getStart(file) });
+        imports.push({ end: stmt.end, specifiers, start: stmt.getStart(file), typeOnly });
     }
     return imports;
 };

package/package.json

@@ -8,14 +8,14 @@
   },
   "dependencies": {
     "@esportsplus/cli-passthrough": "^0.0.15",
-    "@esportsplus/utilities": "^0.27.3",
-    "@types/node": "^25.6.0",
-    "tsc-alias": "^1.8.16",
-    "typescript": "^6.0.2"
+    "@esportsplus/utilities": "^0.28.0",
+    "@types/node": "^26.0.1",
+    "tsc-alias": "^1.8.17",
+    "typescript": "^6.0.3"
   },
   "devDependencies": {
-    "vite": "^8.0.8",
-    "vitest": "^4.1.4"
+    "vite": "^8.1.0",
+    "vitest": "^4.1.9"
   },
   "exports": {
     "./package.json": "./package.json",
@@ -33,6 +33,9 @@
   },
   "main": "build/index.js",
   "name": "@esportsplus/typescript",
+  "overrides": {
+    "postcss": "8.5.15"
+  },
   "private": false,
   "repository": {
     "type": "git",
@@ -40,7 +43,7 @@
   },
   "type": "module",
   "types": "build/index.d.ts",
-  "version": "0.29.1",
+  "version": "0.29.6",
   "scripts": {
     "bench:run": "vitest bench --run",
     "build": "tsc && tsc-alias",

package/pnpm-workspace.yaml

@@ -0,0 +1,6 @@
+# Approve dependency build scripts (pnpm errors on unapproved ones during install/publish) and trust
+# our own scope so freshly published first-party deps bypass the minimumReleaseAge gate.
+allowBuilds:
+  esbuild: true
+minimumReleaseAgeExclude:
+  - '@esportsplus/*'

package/src/compiler/coordinator.ts

@@ -136,7 +136,12 @@ function modify(code: string, file: ts.SourceFile, pkg: string, options: ModifyO
     for (let i = 0, n = found.length; i < n; i++) {
         for (let [name, alias] of found[i].specifiers) {
             if (!remove || (!remove.has(name) && !remove.has(alias))) {
-                specifiers.add(name === alias ? name : `${name} as ${alias}`);
+                let base = name === alias ? name : `${name} as ${alias}`;
+
+                // Preserve type-only specifiers with an inline `type` modifier so the merged import
+                // stays erasable — otherwise `import type { X }` re-emits as a runtime `import { X }`
+                // and fails at load time when X has no runtime export.
+                specifiers.add(found[i].typeOnly.has(name) ? `type ${base}` : base);
             }
         }
     }

package/src/compiler/imports.ts

@@ -4,6 +4,10 @@ import { ts } from '~/index';
 type ImportInfo = {
     end: number;
     specifiers: Map<string, string>;
+    // propertyName keys that were imported type-only, whether via a type-only clause
+    // (`import type { A }`) or an inline specifier (`import { type A }`). Preserved so a rewrite
+    // re-emits them as type imports instead of runtime imports.
+    typeOnly: Set<string>;
     start: number;
 };
 
@@ -43,7 +47,9 @@ const all = (file: ts.SourceFile, pkg: string): ImportInfo[] => {
         }
 
         let bindings = stmt.importClause?.namedBindings,
-            specifiers = new Map<string, string>();
+            declTypeOnly = stmt.importClause?.isTypeOnly ?? false,
+            specifiers = new Map<string, string>(),
+            typeOnly = new Set<string>();
 
         if (bindings && ts.isNamedImports(bindings)) {
             for (let j = 0, m = bindings.elements.length; j < m; j++) {
@@ -52,10 +58,14 @@ const all = (file: ts.SourceFile, pkg: string): ImportInfo[] => {
                     propertyName = element.propertyName?.text || name;
 
                 specifiers.set(propertyName, name);
+
+                if (declTypeOnly || element.isTypeOnly) {
+                    typeOnly.add(propertyName);
+                }
             }
         }
 
-        imports.push({ end: stmt.end, specifiers, start: stmt.getStart(file) });
+        imports.push({ end: stmt.end, specifiers, start: stmt.getStart(file), typeOnly });
     }
 
     return imports;

package/tests/compiler/coordinator.test.ts

@@ -346,6 +346,23 @@ describe('coordinator.transform', () => {
         expect(result.code).not.toMatch(/import\s*\{[^}]*reactive[^}]*\}\s*from\s*'my-pkg'/);
     });
 
+    it('preserves a type-only import when rewriting a package\'s imports', () => {
+        let code = "import { html } from 'my-pkg';\nimport type { Renderable } from 'my-pkg';\nlet x = 1;",
+            file = parse(code),
+            program = makeProgram(file),
+            plugin = makePlugin(() => ({
+                imports: [{ namespace: 'NS', package: 'my-pkg', remove: ['html'] }]
+            })),
+            result = coordinator.transform([plugin], code, file, program, '/root', new Map());
+
+        expect(result.changed).toBe(true);
+        expect(result.code).toContain("import * as NS from 'my-pkg';");
+        // Renderable must stay type-only (import type { ... } or inline `type Renderable`) so it is
+        // erased at runtime — a runtime `import { Renderable }` fails when it has no runtime export.
+        expect(result.code).toMatch(/import\s+type\s*\{[^}]*Renderable|import\s*\{[^}]*type\s+Renderable/);
+        expect(result.code).not.toMatch(/import\s*\{\s*Renderable\s*\}\s*from\s*'my-pkg'/);
+    });
+
     // F-TEST-003: Import manipulation integration tests
 
     it('adds specifiers to existing import', () => {

package/tsconfig.node.json

@@ -1,3 +1,6 @@
 {
+    "compilerOptions": {
+        "types": ["node"]
+    },
     "extends": "./tsconfig.base.json"
 }