Switch subclass-wrapper to AST-only pipeline

Refactor subclass-wrapper resolution to an AST-only pipeline and remove the TypeChecker-based program cache.

- Move subclass-wrapper logic from typecheck/ to ast/: add ast/file-pipeline.ts and ast/subclass-wrapper.ts, and update codegen/imports accordingly.
- Implement AST-only cross-file extends resolution using import-resolver's fileCache (findImportSourcePath) and a WrapperLookupCache; subclass methods must now have explicit type annotations (no TypeChecker inference).
- Remove TypeChecker-dependent program-cache and typecheck/file-pipeline; plugin no longer preloads a ts.Program or accepts tsconfig option.
- Simplify plugin cache startup and HMR handling in src/index.ts to use the AST pipeline and transform cache only.
- Update tests to use the new AST pipeline entrypoints and adjust expectations.

This eliminates the dependency on a baked ts.Program for wrapper resolution, simplifies startup, and relies on the existing import-resolver for cross-file traversal. Partial wrapper resolutions are still all-or-nothing; explicit annotations are required for AST-only resolution.
This commit is contained in:
手瓜一十雪
2026-05-26 21:48:12 +08:00
parent 0f7aa5a600
commit 0d30ee628e
10 changed files with 248 additions and 437 deletions
+9 -13
View File
@@ -50,24 +50,22 @@ import protobufVitePlugin from '@snowluma/proton/vite';
export default defineConfig({
plugins: [
protobufVitePlugin({
root: 'src', // 可选:限制插件只处理该目录下的 .ts 文件
tsconfig: 'tsconfig.json', // 可选:configResolved 时预加载整个 TS Program
cache: true, // 可选:默认启用,缓存写入 Vite cacheDir/proton
root: 'src', // 可选:限制插件只处理该目录下的 .ts 文件
cache: true, // 可选:默认启用,缓存写入 Vite cacheDir/proton
}),
],
});
```
插件会在 Vite `configResolved` 阶段完成项目级初始化:解析作用目录、解析 `tsconfig`、预构建并缓存 TypeChecker 所需的 `ts.Program`。如果启用缓存(默认),Proton 会在 Vite 的 `cacheDir` 下维护两类缓存:
插件在 Vite `configResolved` 阶段解析作用目录。所有类型分析都基于 AST(不依赖 `tsconfig.json` 或 TypeChecker),跨文件 `extends` 链通过 `import-resolver` 的文件缓存遍历。如果启用缓存(默认),Proton 会在 Vite 的 `cacheDir` 下维护:
```text
node_modules/.vite/proton/
program/ TypeScript 增量 Program 缓存(tsBuildInfoFile)
transform/ 按源码 hash + 配置 hash + 依赖 mtime 命中的 transform 结果
```
这样普通文件的 transform 可以先走作用域过滤与 hash cache;未命中时才执行 AST 分析、跨文件导入解析和必要的 TypeChecker 子类解析。
这样普通文件的 transform 可以先走作用域过滤与 hash cache;未命中时才执行 AST 分析、跨文件导入解析和子类包装器解析。
添加工作区依赖:
@@ -210,7 +208,7 @@ const result = DemoTransformer.decode(undefined, bytes);
抽象体内部的 `protobuf_encode<R>` / `protobuf_decode<B>` 无法进行静态替换 —— 因为 `R` 和 `B` 在运行时会被擦除。Proton 通过以下方式处理此问题:
1. **检测**满足以下条件的类:其静态方法 (a) 接收类型参数,(b) 调用 `protobuf_encode<R>` / `protobuf_decode<R>` 且其中 `R` 是这些参数之一,以及 (c) 使用 `this: T extends { … }` 进行约束,且该参数出现在约束内部。
2. **利用 TypeScript 的 TypeChecker** —— 基于项目的 `tsconfig.json` 延迟构建 —— 遍历文件中每个子类的 `extends` 链(包含跨文件边和路径别名),并将包装器的类型参数与子类的同级方法签名进行解析(在此示例中,`R` 对应 `serialize` 的返回值类型,`B` 对应 `deserialize` 的主体参数类型)。
2. **AST-only 解析**:通过文件级导入解析(与 protobuf 接口共用同一套 `import-resolver` 机制)遍历每个子类的 `extends` 链(含跨文件边和包/路径别名),并把包装器的类型参数和子类的同级方法签名进行匹配(本例中 `R` 对应 `serialize` 的返回值类型,`B` 对应 `deserialize` 的参数类型)。
3. 在类声明后**追加**一个针对每个子类的重写(Override):
```js
DemoTransformer.encode = function (ctx, params) {
@@ -227,9 +225,9 @@ DemoTransformer.encode = function (ctx, params) {
* 包装器方法可以命名为任何名称(`encode`、`enc`、`request` 等)—— Proton 只关注主体和约束的形状。
* 同级方法的名称是从 `this: T extends { … }` 约束中读取的,因此 `serialize`/`deserialize`、`build`/`parse` 或任何其他组合都可以正常工作。
* 多层继承(`Leaf → MidBase → AbstractBase`)会被 TypeChecker 全程追踪。
* 多层继承(`Leaf → MidBase → AbstractBase`)通过逐级 `extends` 解析支持。
如果同级方法缺少显式的返回值/参数类型注解,将使用检查器推导出的类型作为兜底。只有当包装器主体中的每个编解码器调用都成功解析时,才会输出重写代码 —— 部分解析会在运行时产生死标识符引用,因此“全有或全无(all-or-nothing)”的规则是故意为之的。
同级方法**必须**显式声明返回值/参数类型注解:AST-only 路径不进行类型推导,缺少注解的方法会被跳过。只有当包装器主体中的每个编解码器调用都成功解析时,才会输出重写代码 —— 部分解析会在运行时产生死标识符引用,因此“全有或全无(all-or-nothing)”的规则是故意为之的。
## proto3 默认值语义
@@ -300,15 +298,13 @@ src/
ast-helpers.ts 共享 AST 小工具 + 快速预检
wrapper-binding.ts 包装器绑定类型 + 类型模板实例化
static-wrapper.ts 静态方法包装器检测 (AST)
subclass-wrapper.ts AST-only extends 链遍历 + 类型参数解析
file-pipeline.ts 插件 transform() 使用的单文件胶水层
utils.ts 名称解析 + 虚拟 SF 追踪
dependency-graph.ts 拓扑排序 + 可达性
types.ts 共享的 Schema 类型
codegen/ 内联传输格式发射器
subclass-override.ts 每个子类重写的代码生成
typecheck/ 基于 TypeChecker 的管道(用于子类重写)
program-cache.ts 延迟加载的 ts.Program,以 tsconfig 为键
subclass-wrapper.ts extends 链遍历 + 类型参数解析
file-pipeline.ts 插件 transform() 使用的单文件胶水层
transform/ Vite 插件字符串编辑
replacer.ts protobuf 调用替换编辑收集
text-edits.ts 通用倒序文本编辑应用
+97
View File
@@ -0,0 +1,97 @@
import { readFileSync } from 'fs';
import ts from 'typescript';
import { renderSubclassOverride } from '../codegen/subclass-override.js';
import { resolveImports, type ParsedFileEntry } from './import-resolver.js';
import {
resolveSubclassWrappers,
WrapperLookupCache,
type ResolvedSubclassWrapper,
} from './subclass-wrapper.js';
/** One contiguous insertion to splice into the user file, addressing the
* spot immediately after a subclass's closing `}`. Grouped per subclass so
* multiple inherited overrides (encode + decode + …) land together. */
export interface SubclassOverrideInsertion {
/** Source-file offset of the insertion point. Always == subclass.end so
* any user code after the class declaration runs against the override. */
position: number;
/** Pre-rendered TS-flavoured snippet, ready to splice. */
code: string;
}
/** Result returned by `runSubclassWrapperPipeline`. */
export interface SubclassWrapperPipelineResult {
/** All resolved subclass overrides reachable from this file. Empty when
* no class in the file extends a wrapper-bearing base, or when resolution
* fails for every candidate. */
resolvedWrappers: ResolvedSubclassWrapper[];
/** Mangled type names that must be present in the codec registry for the
* generated overrides to compile against. Handed to `selectUsedRegistry`
* as extra roots. */
extraRootTypeNames: string[];
/** Pre-rendered insertions ready to feed into the text-edit applier. */
insertions: SubclassOverrideInsertion[];
}
const EMPTY: SubclassWrapperPipelineResult = {
resolvedWrappers: [],
extraRootTypeNames: [],
insertions: [],
};
/** Resolve inherited wrapper overrides for every class in `sourceFile` using
* the AST-only resolver. `fileCache` is the same map populated by
* `resolveImports`; cross-file extends edges are walked through it. */
export function runSubclassWrapperPipeline(
sourceFile: ts.SourceFile,
fileCache: Map<string, ParsedFileEntry>,
): SubclassWrapperPipelineResult {
const wrapperCache = new WrapperLookupCache();
const allResolved: ResolvedSubclassWrapper[] = [];
const extraRoots = new Set<string>();
// Group per subclass so encode + decode + ... land in one contiguous block.
const perSubclass = new Map<ts.ClassDeclaration, string[]>();
for (const stmt of sourceFile.statements) {
if (!ts.isClassDeclaration(stmt) || !stmt.name) continue;
const resolved = resolveSubclassWrappers(stmt, sourceFile, fileCache, wrapperCache);
for (const r of resolved) {
allResolved.push(r);
for (const c of r.resolvedCodecCalls) extraRoots.add(c.resolvedTypeName);
const rendered = renderSubclassOverride(r);
if (!rendered) continue;
const bucket = perSubclass.get(r.subclass);
if (bucket) bucket.push(rendered.code);
else perSubclass.set(r.subclass, [rendered.code]);
}
}
if (allResolved.length === 0) return EMPTY;
const insertions: SubclassOverrideInsertion[] = [];
for (const [subclass, codes] of perSubclass) {
insertions.push({ position: subclass.end, code: '\n' + codes.join('\n') });
}
return {
resolvedWrappers: allResolved,
extraRootTypeNames: Array.from(extraRoots),
insertions,
};
}
/** Convenience entry that reads `filePath` from disk, builds a fresh file
* cache, and delegates to `runSubclassWrapperPipeline`. Used by tests and
* callers that don't already have a parsed source file + cache on hand. */
export function runSubclassWrapperPipelineFromPath(filePath: string): SubclassWrapperPipelineResult {
let code: string;
try {
code = readFileSync(filePath, 'utf-8');
} catch {
return EMPTY;
}
const fileCache = new Map<string, ParsedFileEntry>();
const imported = resolveImports(code, filePath, fileCache);
return runSubclassWrapperPipeline(imported.sourceFile, fileCache);
}
@@ -149,6 +149,19 @@ function resolveModulePath(specifier: string, importerPath: string): string | nu
return resolved.resolvedFileName;
}
/** Resolve `name` (imported into `sf`) to the absolute path of the `.ts`
* module that declares it. Returns null for local symbols, type-only imports,
* or unresolved specifiers. Used by the AST-only subclass-wrapper resolver to
* walk extends edges across file boundaries. */
export function findImportSourcePath(sf: ts.SourceFile, name: string, fromPath: string): string | null {
for (const imp of collectImportClauses(sf, false)) {
if (imp.importedName === name || imp.localName === name) {
return resolveModulePath(imp.specifier, fromPath);
}
}
return null;
}
function hasExportModifier(node: ts.Node): boolean {
return ts.canHaveModifiers(node) && !!ts.getModifiers(node)?.some(m => m.kind === ts.SyntaxKind.ExportKeyword);
}
@@ -1,21 +1,24 @@
import ts from 'typescript';
import { getPropertyNameText, isBareTypeRef, isStaticMethod } from '../ast/ast-helpers.js';
import type { ClassWrapperInfo, WrapperCodecCall, WrapperMethodInfo } from '../ast/static-wrapper.js';
import { detectClassWrappers } from '../ast/static-wrapper.js';
import { getPropertyNameText, isBareTypeRef, isStaticMethod } from './ast-helpers.js';
import { findImportSourcePath, type ParsedFileEntry } from './import-resolver.js';
import type { ClassWrapperInfo, WrapperCodecCall, WrapperMethodInfo } from './static-wrapper.js';
import { detectClassWrappers } from './static-wrapper.js';
import {
createImportedTypeNameResolver,
resolveSourceFileForTypeNode,
typeNodeToMangledName,
} from '../ast/utils.js';
} from './utils.js';
/**
* Subclass-side resolution of inherited wrapper methods. For every wrapper
* inherited from an abstract base, resolves the wrapper's type parameter to
* the concrete type used by THIS subclass, so the override generator can
* emit a per-subclass `Sub.method = function(...)` stub.
* AST-only subclass-wrapper resolution. For each wrapper inherited from an
* abstract base, resolves the wrapper's type parameter to the concrete type
* used by THIS subclass, so the override generator can emit a per-subclass
* `Sub.method = function(...)` stub.
*
* Uses TypeChecker for cross-file extends-chain walking (with tsconfig path
* aliases) and to infer types from method bodies that lack explicit annotations.
* Cross-file extends edges resolve through the import-resolver's `fileCache`
* (the same cache populated by `resolveImports`), so no TypeChecker is needed.
* Subclass methods MUST carry explicit type annotations — this resolver does
* not infer types from method bodies.
*/
/** Where, in the wrapper's `this: T extends { … }` constraint, the
@@ -25,15 +28,7 @@ export type ResolutionPosition =
| { kind: 'paramType'; index: number };
export interface ResolvedCodecCall extends WrapperCodecCall {
/** Mangled name of the resolved concrete type — same shape used by the
* rest of the analyzer (`UserMsg`, `Wrapper__string`, …). The override
* generator pastes `protobuf_encode_${typeName}` / `protobuf_decode_…`
* into the cloned wrapper body in place of the generic form. */
resolvedTypeName: string;
/** Synthetic TypeNode for the resolved type, suitable for handing to the
* monomorphizer. Lives in its own SourceFile via the existing synthetic-
* SF registry so subsequent `getText()` / import-resolution calls land
* in the right module. */
resolvedTypeNode: ts.TypeNode;
}
@@ -46,20 +41,35 @@ export interface ResolvedSubclassWrapper {
resolvedCodecCalls: ResolvedCodecCall[];
}
/** Walk a subclass's extends chain (via the checker) and return every
* wrapper inherited by it, paired with the per-codec-call type resolution.
* An empty array means the subclass either doesn't extend anything proton
* cares about, or proton couldn't resolve at least one type. */
/** Per-pipeline cache of wrapper detection results, memoised on the
* ClassDeclaration node so the same abstract base is not re-scanned for
* every subclass. */
export class WrapperLookupCache {
private readonly map = new WeakMap<ts.ClassDeclaration, ClassWrapperInfo | null>();
getOrDetect(cls: ts.ClassDeclaration, sf: ts.SourceFile): ClassWrapperInfo | null {
if (this.map.has(cls)) return this.map.get(cls)!;
const info = detectClassWrappers(cls, sf);
this.map.set(cls, info);
return info;
}
}
/** Walk the subclass's extends chain and return every wrapper inherited by it,
* paired with the per-codec-call type resolution. An empty array means the
* subclass either doesn't extend anything proton cares about, or proton
* couldn't resolve at least one type. */
export function resolveSubclassWrappers(
subclass: ts.ClassDeclaration,
checker: ts.TypeChecker,
subclassSf: ts.SourceFile,
fileCache: Map<string, ParsedFileEntry>,
wrapperCache: WrapperLookupCache,
): ResolvedSubclassWrapper[] {
const results: ResolvedSubclassWrapper[] = [];
const wrappers = collectInheritedWrappers(subclass, checker, wrapperCache);
const wrappers = collectInheritedWrappers(subclass, subclassSf, fileCache, wrapperCache);
for (const wrapper of wrappers) {
const resolvedCodecCalls = resolveWrapperCodecCalls(subclass, wrapper, checker);
const resolvedCodecCalls = resolveWrapperCodecCalls(subclass, wrapper);
if (resolvedCodecCalls === null) continue;
results.push({ subclass, wrapper, resolvedCodecCalls });
}
@@ -69,21 +79,70 @@ export function resolveSubclassWrappers(
function collectInheritedWrappers(
cls: ts.ClassDeclaration,
checker: ts.TypeChecker,
sf: ts.SourceFile,
fileCache: Map<string, ParsedFileEntry>,
wrapperCache: WrapperLookupCache,
): WrapperMethodInfo[] {
const result: WrapperMethodInfo[] = [];
// Skip `cls` itself: only override methods inherited from ancestors.
let first = true;
for (const ancestor of walkExtendsChain(cls, checker)) {
for (const node of walkExtendsChain(cls, sf, fileCache)) {
if (first) { first = false; continue; }
const info = wrapperCache.getOrDetect(ancestor);
const info = wrapperCache.getOrDetect(node.cls, node.sf);
if (!info) continue;
for (const wrapper of info.values()) result.push(wrapper);
}
return result;
}
/** Yield each level of the extends chain. Resolves cross-file edges by
* consulting the file's import statements + the shared `fileCache`. */
function* walkExtendsChain(
cls: ts.ClassDeclaration,
sf: ts.SourceFile,
fileCache: Map<string, ParsedFileEntry>,
): IterableIterator<{ cls: ts.ClassDeclaration; sf: ts.SourceFile }> {
let current: { cls: ts.ClassDeclaration; sf: ts.SourceFile } | null = { cls, sf };
const seen = new Set<ts.ClassDeclaration>();
while (current && !seen.has(current.cls)) {
seen.add(current.cls);
yield current;
current = resolveExtendsParent(current.cls, current.sf, fileCache);
}
}
function resolveExtendsParent(
cls: ts.ClassDeclaration,
sf: ts.SourceFile,
fileCache: Map<string, ParsedFileEntry>,
): { cls: ts.ClassDeclaration; sf: ts.SourceFile } | null {
const ext = cls.heritageClauses?.find(h => h.token === ts.SyntaxKind.ExtendsKeyword);
const heritageExpr = ext?.types[0]?.expression;
if (!heritageExpr || !ts.isIdentifier(heritageExpr)) return null;
const baseName = heritageExpr.text;
// Local declaration in the same file.
const local = findClassByName(sf, baseName);
if (local) return { cls: local, sf };
// Imported from another module — look up the import specifier and find
// the cached entry at that path.
const sourcePath = findImportSourcePath(sf, baseName, sf.fileName);
if (!sourcePath) return null;
const entry = fileCache.get(sourcePath);
if (!entry) return null;
const parent = findClassByName(entry.sourceFile, baseName);
if (!parent) return null;
return { cls: parent, sf: entry.sourceFile };
}
function findClassByName(sf: ts.SourceFile, name: string): ts.ClassDeclaration | null {
for (const stmt of sf.statements) {
if (ts.isClassDeclaration(stmt) && stmt.name?.text === name) return stmt;
}
return null;
}
/** Resolve every codec call inside a wrapper body for one specific
* subclass. Returns null if any single codec call fails to resolve — the
* override is all-or-nothing because partially-generated code would
@@ -91,7 +150,6 @@ function collectInheritedWrappers(
function resolveWrapperCodecCalls(
subclass: ts.ClassDeclaration,
wrapper: WrapperMethodInfo,
checker: ts.TypeChecker,
): ResolvedCodecCall[] | null {
if (!wrapper.thisConstraint) return null;
@@ -101,7 +159,7 @@ function resolveWrapperCodecCalls(
const position = findTypeParamInConstraint(wrapper.thisConstraint, codecCall.typeParamName);
if (!position) return null;
const typeNode = extractSubclassMemberTypeNode(subclass, position.memberName, position.position, checker);
const typeNode = extractSubclassMemberTypeNode(subclass, position.memberName, position.position);
if (!typeNode) return null;
const typeName = computeMangledName(typeNode, subclassSf);
@@ -116,14 +174,14 @@ function resolveWrapperCodecCalls(
return resolved;
}
/** Inspect a `{ memberName: (params) => returnType }` literal and locate
* the property whose signature references `typeParamName`. Returns the
* member name plus where on its signature the type appears. */
interface ConstraintHit {
memberName: string;
position: ResolutionPosition;
}
/** Inspect a `{ memberName: (params) => returnType }` literal and locate
* the property whose signature references `typeParamName`. Returns the
* member name plus where on its signature the type appears. */
function findTypeParamInConstraint(constraint: ts.TypeNode, typeParamName: string): ConstraintHit | null {
if (!ts.isTypeLiteralNode(constraint)) return null;
@@ -147,93 +205,27 @@ function findTypeParamInConstraint(constraint: ts.TypeNode, typeParamName: strin
return null;
}
/** Pull a type out of a subclass member's signature at the requested
* position. Prefers the explicit annotation when present; falls back to
* the TypeChecker's inferred type otherwise. */
/** Pull a type out of a subclass member's signature at the requested position.
* AST-only: the annotation must be explicit. Methods without annotations
* cannot be overridden by this pipeline (the wrapper instance is skipped). */
function extractSubclassMemberTypeNode(
subclass: ts.ClassDeclaration,
memberName: string,
position: ResolutionPosition,
checker: ts.TypeChecker,
): ts.TypeNode | null {
for (const member of subclass.members) {
if (!ts.isMethodDeclaration(member)) continue;
if (!isStaticMethod(member)) continue;
if (!ts.isIdentifier(member.name) || member.name.text !== memberName) continue;
if (position.kind === 'returnType') {
if (member.type) return member.type;
const sig = checker.getSignatureFromDeclaration(member);
if (!sig) return null;
const ret = checker.getReturnTypeOfSignature(sig);
return typeToTypeNode(ret, member, checker);
}
const param = member.parameters[position.index];
if (!param) return null;
if (param.type) return param.type;
const type = checker.getTypeAtLocation(param);
return typeToTypeNode(type, member, checker);
if (position.kind === 'returnType') return member.type ?? null;
return member.parameters[position.index]?.type ?? null;
}
return null;
}
function typeToTypeNode(type: ts.Type, enclosing: ts.Node, checker: ts.TypeChecker): ts.TypeNode | null {
return checker.typeToTypeNode(
type,
enclosing,
ts.NodeBuilderFlags.NoTruncation | ts.NodeBuilderFlags.UseFullyQualifiedType,
) ?? null;
}
/** Walk the extends chain in source order, yielding the class declaration
* for each level. Uses the checker so cross-file edges and tsconfig path
* aliases resolve correctly. */
function* walkExtendsChain(
cls: ts.ClassDeclaration,
checker: ts.TypeChecker,
): IterableIterator<ts.ClassDeclaration> {
let current: ts.ClassDeclaration | null = cls;
const seen = new Set<ts.ClassDeclaration>();
while (current && !seen.has(current)) {
seen.add(current);
yield current;
const ext = current.heritageClauses?.find(h => h.token === ts.SyntaxKind.ExtendsKeyword);
const heritageExpr = ext?.types[0]?.expression;
if (!heritageExpr) break;
const symbol = checker.getSymbolAtLocation(heritageExpr);
if (!symbol) break;
// When the parent is imported, `getSymbolAtLocation` lands on the
// import-alias symbol; the class declaration lives on the aliased
// target symbol. Resolve through the alias before reading
// declarations — otherwise cross-file inheritance never finds the
// base class.
const targetSymbol = (symbol.flags & ts.SymbolFlags.Alias)
? checker.getAliasedSymbol(symbol)
: symbol;
const decls = targetSymbol.getDeclarations();
if (!decls) break;
const parentDecl = decls.find((d): d is ts.ClassDeclaration => ts.isClassDeclaration(d));
if (!parentDecl) break;
current = parentDecl;
}
}
/** Map a resolved TypeNode to the mangled name proton's generator expects.
* Routes through `typeNodeToMangledName` so primitives, generics, and
* synthetic-SF-registered nodes all share the same shape used elsewhere
* in the analyzer. */
/** Map a resolved TypeNode to the mangled name proton's generator expects. */
function computeMangledName(node: ts.TypeNode, fallbackSf: ts.SourceFile): string | null {
// If the node was produced by TypeChecker (synthetic), the synthetic-SF
// registry already has the right context; for explicit annotations the
// node is part of the subclass's own SourceFile, which is what we hand
// in as the fallback.
const effectiveSf = resolveSourceFileForTypeNode(node, fallbackSf);
const resolver = createImportedTypeNameResolver(effectiveSf);
try {
@@ -242,20 +234,3 @@ function computeMangledName(node: ts.TypeNode, fallbackSf: ts.SourceFile): strin
return null;
}
}
/**
* Per-program cache of wrapper detection results. The same abstract base
* gets re-discovered for every subclass it has, so memoizing on the class
* declaration node keeps the cost flat as the number of subclasses grows.
*/
export class WrapperLookupCache {
private readonly map = new WeakMap<ts.ClassDeclaration, ClassWrapperInfo | null>();
getOrDetect(cls: ts.ClassDeclaration): ClassWrapperInfo | null {
if (this.map.has(cls)) return this.map.get(cls)!;
const sf = cls.getSourceFile();
const info = detectClassWrappers(cls, sf);
this.map.set(cls, info);
return info;
}
}
@@ -1,5 +1,5 @@
import ts from 'typescript';
import type { ResolvedSubclassWrapper } from '../typecheck/subclass-wrapper.js';
import type { ResolvedSubclassWrapper } from '../ast/subclass-wrapper.js';
/**
* Per-subclass override code generation. Copies the wrapper body verbatim,
+9 -27
View File
@@ -4,19 +4,17 @@ import { dirname, isAbsolute, resolve } from 'path';
import type { Plugin, ResolvedConfig } from 'vite';
import { analyze, analyzeSource, selectUsedRegistry, typeNodeToMangledName } from './ast/analyzer.js';
import { fileHasExtendingClass } from './ast/ast-helpers.js';
import {
runSubclassWrapperPipeline,
type SubclassWrapperPipelineResult,
} from './ast/file-pipeline.js';
import { resolveImports, type ParsedFileEntry } from './ast/import-resolver.js';
import { generateCode } from './codegen/generator.js';
import { applyReplacements, collectReplacementEdits, replaceCallSites } from './transform/replacer.js';
import { applyTextEdits, type TextEdit } from './transform/text-edits.js';
import {
runSubclassWrapperPipeline,
type SubclassWrapperPipelineResult,
} from './typecheck/file-pipeline.js';
import { invalidateProgramCache, prepareProgramForTsconfig } from './typecheck/program-cache.js';
export interface ProtobufVitePluginOptions {
root?: string;
tsconfig?: string;
cache?: boolean | {
dir?: string;
};
@@ -25,10 +23,8 @@ export interface ProtobufVitePluginOptions {
interface ProtonPluginContext {
viteRoot: string;
scopeRoot: string;
tsconfigPath: string;
cacheEnabled: boolean;
transformCacheDir: string;
programCacheDir: string;
}
interface TransformDiskCacheEntry {
@@ -52,13 +48,7 @@ export default function protobufVitePlugin(_options: ProtobufVitePluginOptions =
configResolved(config) {
const nextCtx = createPluginContext(config, _options);
ctx = nextCtx;
if (nextCtx.cacheEnabled) {
mkdirSync(nextCtx.transformCacheDir, { recursive: true });
mkdirSync(nextCtx.programCacheDir, { recursive: true });
}
prepareProgramForTsconfig(nextCtx.tsconfigPath, {
cacheDir: nextCtx.cacheEnabled ? nextCtx.programCacheDir : undefined,
});
if (nextCtx.cacheEnabled) mkdirSync(nextCtx.transformCacheDir, { recursive: true });
},
transform(code, id) {
@@ -70,8 +60,6 @@ export default function protobufVitePlugin(_options: ProtobufVitePluginOptions =
const sourceHash = hashString(code);
const configHash = hashString(JSON.stringify({
scopeRoot: normalizePath(activeCtx.scopeRoot),
tsconfigPath: normalizePath(activeCtx.tsconfigPath),
tsconfigMtime: safeMtime(activeCtx.tsconfigPath),
version: TRANSFORM_CACHE_VERSION,
}));
const cachePath = activeCtx.cacheEnabled
@@ -82,10 +70,10 @@ export default function protobufVitePlugin(_options: ProtobufVitePluginOptions =
const imported = resolveImports(code, cleanId, fileCache);
const { registry, callSites, sourceFile } = analyze(code, cleanId, imported);
// Guard the TypeChecker-based wrapper pipeline behind a cheap scan:
// most files have no extending classes.
// Guard the wrapper pipeline behind a cheap scan: most files have no
// extending classes.
const subclassWrappers: SubclassWrapperPipelineResult = fileHasExtendingClass(sourceFile)
? runSubclassWrapperPipeline(cleanId)
? runSubclassWrapperPipeline(sourceFile, fileCache)
: { resolvedWrappers: [], extraRootTypeNames: [], insertions: [] };
if (
@@ -132,10 +120,7 @@ export default function protobufVitePlugin(_options: ProtobufVitePluginOptions =
},
handleHotUpdate({ file }) {
if (file.endsWith('.ts')) {
fileCache.delete(file);
invalidateProgramCache(file);
}
if (file.endsWith('.ts')) fileCache.delete(file);
},
};
}
@@ -147,15 +132,12 @@ function buildContext(
cacheEnabled: boolean,
): ProtonPluginContext {
const scopeRoot = resolveOptionPath(options.root, viteRoot, viteRoot);
const tsconfigPath = resolveOptionPath(options.tsconfig, viteRoot, resolve(scopeRoot, 'tsconfig.json'));
const cacheBase = resolveCacheBase(options, viteRoot, viteCacheDir);
return {
viteRoot,
scopeRoot,
tsconfigPath,
cacheEnabled,
transformCacheDir: resolve(cacheBase, 'transform'),
programCacheDir: resolve(cacheBase, 'program'),
};
}
@@ -1,86 +0,0 @@
import ts from 'typescript';
import { renderSubclassOverride } from '../codegen/subclass-override.js';
import { getProgramForFile } from './program-cache.js';
import { resolveSubclassWrappers, WrapperLookupCache, type ResolvedSubclassWrapper } from './subclass-wrapper.js';
/** One contiguous insertion to splice into the user file, addressing the
* spot immediately after a subclass's closing `}`. Grouped per subclass so
* multiple inherited overrides (encode + decode + …) land together. */
export interface SubclassOverrideInsertion {
/** Source-file offset of the insertion point. Always == subclass.end so
* any user code after the class declaration runs against the override. */
position: number;
/** Already-rendered override text. */
code: string;
}
/** Result returned by `runSubclassWrapperPipeline`. */
export interface SubclassWrapperPipelineResult {
/** All resolved subclass overrides reachable from this file. Empty when
* TypeChecker is unavailable, when no class in the file extends a
* wrapper-bearing base, or when resolution fails for every candidate. */
resolvedWrappers: ResolvedSubclassWrapper[];
/** Mangled type names that must be present in the codec registry for the
* generated overrides to compile against. Handed to `selectUsedRegistry`
* as extra roots. */
extraRootTypeNames: string[];
/** Per-subclass insertion points + rendered override text. Inserted into
* the user's source immediately after the subclass declaration so any
* subsequent statements (including top-level `Sub.method(...)` calls)
* see the override and dispatch through it, not the inherited body. */
insertions: SubclassOverrideInsertion[];
}
/** Lazily retrieves the TypeChecker (returns empty result when no tsconfig is
* reachable), resolves inherited wrapper overrides for every class in the file,
* and returns resolved wrappers, extra codec roots, and insertion points. */
export function runSubclassWrapperPipeline(filePath: string): SubclassWrapperPipelineResult {
const empty: SubclassWrapperPipelineResult = {
resolvedWrappers: [],
extraRootTypeNames: [],
insertions: [],
};
const programCtx = getProgramForFile(filePath);
if (!programCtx) return empty;
const sf = programCtx.program.getSourceFile(filePath);
if (!sf) return empty;
const cache = new WrapperLookupCache();
const allResolved: ResolvedSubclassWrapper[] = [];
const extraRoots = new Set<string>();
// Group per subclass so encode + decode + ... land in one contiguous block.
const perSubclass = new Map<ts.ClassDeclaration, string[]>();
for (const stmt of sf.statements) {
if (!ts.isClassDeclaration(stmt) || !stmt.name) continue;
const resolved = resolveSubclassWrappers(stmt, programCtx.checker, cache);
for (const r of resolved) {
allResolved.push(r);
for (const c of r.resolvedCodecCalls) extraRoots.add(c.resolvedTypeName);
const rendered = renderSubclassOverride(r);
if (!rendered) continue;
const bucket = perSubclass.get(r.subclass);
if (bucket) bucket.push(rendered.code);
else perSubclass.set(r.subclass, [rendered.code]);
}
}
if (allResolved.length === 0) return empty;
const insertions: SubclassOverrideInsertion[] = [];
for (const [cls, parts] of perSubclass) {
insertions.push({
position: cls.getEnd(),
code: '\n' + parts.join(''),
});
}
return {
resolvedWrappers: allResolved,
extraRootTypeNames: [...extraRoots],
insertions,
};
}
@@ -1,158 +0,0 @@
import { existsSync, mkdirSync } from 'fs';
import { dirname, resolve } from 'path';
import ts from 'typescript';
/**
* Lazy ts.Program cache keyed by tsconfig path. Built once per tsconfig and
* reused across transform calls; HMR drops the cache for the affected program.
* Returns null when no tsconfig is reachable so callers can fall back to the
* AST-only pipeline (used by in-repo test fixtures with synthesized file names).
*/
export interface ProgramContext {
/** Absolute path to the tsconfig this program was built from. */
tsconfigPath: string;
program: ts.Program;
checker: ts.TypeChecker;
}
interface CacheEntry extends ProgramContext {
/** Set of absolute source file paths reachable from this program. */
fileSet: Set<string>;
}
const programCache = new Map<string, CacheEntry>();
const tsconfigLookupCache = new Map<string, string | null>();
/** Cap upward walk; keeps the lookup loop bounded if we end up at a
* monorepo root with no tsconfig (rare in this repo, but possible if a
* caller hands us a path outside the workspace). */
const TSCONFIG_WALK_MAX_DEPTH = 24;
function findTsconfigUpwards(startDir: string): string | null {
let dir = resolve(startDir);
const cached = tsconfigLookupCache.get(dir);
if (cached !== undefined) return cached;
const visited: string[] = [];
for (let i = 0; i < TSCONFIG_WALK_MAX_DEPTH; i++) {
visited.push(dir);
const candidate = resolve(dir, 'tsconfig.json');
if (existsSync(candidate)) {
for (const v of visited) tsconfigLookupCache.set(v, candidate);
return candidate;
}
const parent = resolve(dir, '..');
if (parent === dir) {
for (const v of visited) tsconfigLookupCache.set(v, null);
return null;
}
dir = parent;
}
for (const v of visited) tsconfigLookupCache.set(v, null);
return null;
}
export interface BuildProgramOptions {
cacheDir?: string;
}
function buildProgram(tsconfigPath: string, buildOptions: BuildProgramOptions = {}): CacheEntry | null {
const configFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
if (configFile.error) return null;
const parsedConfig = ts.parseJsonConfigFileContent(
configFile.config,
ts.sys,
dirname(tsconfigPath),
);
if (parsedConfig.fileNames.length === 0) return null;
// `noEmit: true` + `skipLibCheck: true` are the two things that pay back
// hardest here: we never actually emit (proton does its own codegen) and
// the lib check is the single biggest cost factor.
const options: ts.CompilerOptions = {
...parsedConfig.options,
noEmit: true,
skipLibCheck: parsedConfig.options.skipLibCheck ?? true,
};
if (buildOptions.cacheDir) {
mkdirSync(buildOptions.cacheDir, { recursive: true });
options.incremental = true;
options.tsBuildInfoFile = resolve(
buildOptions.cacheDir,
`program-${safeFileName(tsconfigPath)}.tsbuildinfo`,
);
}
const program = ts.createProgram({
rootNames: parsedConfig.fileNames,
options,
});
const checker = program.getTypeChecker();
const fileSet = new Set<string>();
for (const sf of program.getSourceFiles()) {
if (!sf.isDeclarationFile) fileSet.add(normalizePath(sf.fileName));
}
return { tsconfigPath, program, checker, fileSet };
}
export function prepareProgramForTsconfig(tsconfigPath: string, options: BuildProgramOptions = {}): ProgramContext | null {
const abs = resolve(tsconfigPath);
const built = buildProgram(abs, options);
if (!built) return null;
programCache.set(abs, built);
tsconfigLookupCache.set(dirname(abs), abs);
return { tsconfigPath: built.tsconfigPath, program: built.program, checker: built.checker };
}
/** Locate (or build) the program that contains `filePath`. Returns null if
* no tsconfig is reachable, or if the file isn't part of any program — in
* which case the caller MUST fall back to the AST-only pipeline. */
export function getProgramForFile(filePath: string): ProgramContext | null {
const tsconfigPath = findTsconfigUpwards(dirname(filePath));
if (!tsconfigPath) return null;
let entry = programCache.get(tsconfigPath);
if (!entry) {
const built = buildProgram(tsconfigPath);
if (!built) return null;
entry = built;
programCache.set(tsconfigPath, entry);
}
if (!entry.fileSet.has(normalizePath(filePath))) {
// File isn't included in this tsconfig (e.g. excluded fixture). The
// checker would still answer, but using a Program that doesn't actually
// contain the file leads to subtly wrong symbol lookups.
return null;
}
return { tsconfigPath: entry.tsconfigPath, program: entry.program, checker: entry.checker };
}
/** Drop the cached program containing `filePath`, or all programs if no
* argument is given. Called from the plugin's `handleHotUpdate` hook. */
export function invalidateProgramCache(filePath?: string): void {
if (!filePath) {
programCache.clear();
tsconfigLookupCache.clear();
return;
}
const normalized = normalizePath(filePath);
for (const [tsconfigPath, entry] of programCache) {
if (entry.fileSet.has(normalized)) {
programCache.delete(tsconfigPath);
}
}
}
function normalizePath(p: string): string {
return resolve(p).replace(/\\/g, '/');
}
function safeFileName(value: string): string {
return normalizePath(value).replace(/[^a-zA-Z0-9_.-]/g, '_');
}
@@ -231,7 +231,7 @@ const buf = protobuf_encode<UsedMsg>({ inner: { id: 1 } });
}
});
it('uses Vite cacheDir for transform hash cache and startup program cache', () => {
it('uses Vite cacheDir for transform hash cache', () => {
const root = mkdtempSync(resolve(tmpdir(), 'proton-cache-'));
try {
const sourcePath = resolve(root, 'entry.ts');
@@ -244,18 +244,16 @@ const buf = protobuf_encode<UsedMsg>({ inner: { id: 1 } });
files: ['entry.ts'],
}));
const firstPlugin = protobufVitePlugin({ root, tsconfig: tsconfigPath });
const firstPlugin = protobufVitePlugin({ root });
runConfigResolved(firstPlugin, root, cacheDir);
const first = runPluginTransform(firstPlugin, code, sourcePath);
expect(first?.code).toContain('protobuf_encode_Msg');
const transformCacheDir = resolve(cacheDir, 'proton', 'transform');
const programCacheDir = resolve(cacheDir, 'proton', 'program');
expect(existsSync(transformCacheDir)).toBe(true);
expect(existsSync(programCacheDir)).toBe(true);
expect(readdirSync(transformCacheDir).some(name => name.endsWith('.json'))).toBe(true);
const secondPlugin = protobufVitePlugin({ root, tsconfig: tsconfigPath });
const secondPlugin = protobufVitePlugin({ root });
runConfigResolved(secondPlugin, root, cacheDir);
const second = runPluginTransform(secondPlugin, code, sourcePath);
expect(second).toEqual(first);
@@ -3,12 +3,12 @@ import { dirname, resolve } from 'path';
import ts from 'typescript';
import { fileURLToPath } from 'url';
import { describe, expect, it } from 'vitest';
import { runSubclassWrapperPipelineFromPath } from '../../src/ast/file-pipeline';
import { resolveImports, type ParsedFileEntry } from '../../src/ast/import-resolver';
import { detectClassWrappersInFile } from '../../src/ast/static-wrapper';
import { WrapperLookupCache, resolveSubclassWrappers } from '../../src/ast/subclass-wrapper';
import { renderSubclassOverride } from '../../src/codegen/subclass-override';
import protobufVitePlugin from '../../src/index';
import { runSubclassWrapperPipeline } from '../../src/typecheck/file-pipeline';
import { getProgramForFile, invalidateProgramCache } from '../../src/typecheck/program-cache';
import { WrapperLookupCache, resolveSubclassWrappers } from '../../src/typecheck/subclass-wrapper';
const here = dirname(fileURLToPath(import.meta.url));
const fixturePath = resolve(here, 'wrapper-fixtures', 'packet-transformer.ts');
@@ -57,22 +57,23 @@ class NotAWrapper {
});
});
describe('subclass wrapper resolution (TypeChecker)', () => {
function buildAstContext(filePath: string): { sf: ts.SourceFile; fileCache: Map<string, ParsedFileEntry> } {
const code = readFileSync(filePath, 'utf-8');
const fileCache = new Map<string, ParsedFileEntry>();
const imported = resolveImports(code, filePath, fileCache);
return { sf: imported.sourceFile, fileCache };
}
describe('subclass wrapper resolution (AST)', () => {
it('resolves R for DemoTransformer.encode through the serialize return type', () => {
invalidateProgramCache();
const programCtx = getProgramForFile(fixturePath);
if (!programCtx) {
throw new Error('TypeChecker program unavailable for fixture');
}
const sf = programCtx.program.getSourceFile(fixturePath)!;
expect(sf).toBeDefined();
const { sf, fileCache } = buildAstContext(fixturePath);
const subclass = sf.statements.find(
(s): s is ts.ClassDeclaration => ts.isClassDeclaration(s) && s.name?.text === 'DemoTransformer',
)!;
const cache = new WrapperLookupCache();
const resolved = resolveSubclassWrappers(subclass, programCtx.checker, cache);
const resolved = resolveSubclassWrappers(subclass, sf, fileCache, cache);
expect(resolved).toHaveLength(2);
const encode = resolved.find(r => r.wrapper.methodName === 'encode')!;
@@ -91,15 +92,13 @@ describe('subclass wrapper resolution (TypeChecker)', () => {
});
it('renders the per-subclass override as JS-flavoured TS', () => {
invalidateProgramCache();
const programCtx = getProgramForFile(fixturePath)!;
const sf = programCtx.program.getSourceFile(fixturePath)!;
const { sf, fileCache } = buildAstContext(fixturePath);
const subclass = sf.statements.find(
(s): s is ts.ClassDeclaration => ts.isClassDeclaration(s) && s.name?.text === 'DemoTransformer',
)!;
const cache = new WrapperLookupCache();
const resolved = resolveSubclassWrappers(subclass, programCtx.checker, cache);
const resolved = resolveSubclassWrappers(subclass, sf, fileCache, cache);
const encode = resolved.find(r => r.wrapper.methodName === 'encode')!;
const rendered = renderSubclassOverride(encode);
expect(rendered).not.toBeNull();
@@ -115,8 +114,7 @@ describe('file-pipeline (end-to-end)', () => {
}
it('produces extra root names + override code for the demo subclass', () => {
invalidateProgramCache();
const result = runSubclassWrapperPipeline(fixturePath);
const result = runSubclassWrapperPipelineFromPath(fixturePath);
expect(result.extraRootTypeNames).toEqual(
expect.arrayContaining(['rsq_pb', 'rps_pb']),
@@ -132,10 +130,9 @@ describe('file-pipeline (end-to-end)', () => {
});
it('returns an empty result when no class in the file extends a wrapper', () => {
invalidateProgramCache();
// Re-use an existing test file that has no transformer classes.
const otherFile = resolve(here, 'plugin.test.ts');
const result = runSubclassWrapperPipeline(otherFile);
const result = runSubclassWrapperPipelineFromPath(otherFile);
expect(result.resolvedWrappers).toHaveLength(0);
expect(result.extraRootTypeNames).toHaveLength(0);
expect(result.insertions).toHaveLength(0);
@@ -146,8 +143,7 @@ describe('cross-file inheritance', () => {
const subclassFile = resolve(here, 'wrapper-fixtures', 'subclass-transformer.ts');
it('walks the extends edge into a separate module and resolves wrappers', () => {
invalidateProgramCache();
const result = runSubclassWrapperPipeline(subclassFile);
const result = runSubclassWrapperPipelineFromPath(subclassFile);
expect(result.extraRootTypeNames).toEqual(
expect.arrayContaining(['FooRequestPb', 'FooResponsePb']),
);
@@ -159,9 +155,8 @@ describe('cross-file inheritance', () => {
});
it('does not generate overrides on the abstract base file itself', () => {
invalidateProgramCache();
const baseFile = resolve(here, 'wrapper-fixtures', 'base-transformer.ts');
const result = runSubclassWrapperPipeline(baseFile);
const result = runSubclassWrapperPipelineFromPath(baseFile);
// No subclasses defined in the base file → no overrides emitted there.
expect(result.resolvedWrappers).toHaveLength(0);
expect(result.insertions).toHaveLength(0);
@@ -170,7 +165,6 @@ describe('cross-file inheritance', () => {
describe('plugin transform integration', () => {
function runPluginOnFixture(): string {
invalidateProgramCache();
const plugin = protobufVitePlugin();
const code = loadFixture();
const transformHook = plugin.transform!;