From 44db4bb4198754d831708a007ff8ade6e8f821a5 Mon Sep 17 00:00:00 2001 From: joshunrau Date: Wed, 18 Nov 2026 13:12:20 -0500 Subject: [PATCH 1/2] refactor(runtime-bundler): rewrite declaration imports with oxc-parser TypeScript 7 no longer exposes the compiler API that dtsPlugin used to parse, transform and reprint each .d.ts. Parse with oxc-parser instead and splice each resolved path into the original text between the specifier's own quotes, so the rest of the declaration, quote style and comments included, is emitted as written. A syntax error in a declaration is now reported as a load error on that file, where the TypeScript parser recovered from it silently. resolveDependency returns a result instead of throwing, which removes the catch and its unreachable 'Unknown Error' branch. Co-Authored-By: Claude Opus 5.5 --- packages/runtime-bundler/package.json | 1 + .../src/__tests__/plugin.test.ts | 85 ++++++++++++----- packages/runtime-bundler/src/plugin.ts | 94 +++++++++---------- pnpm-lock.yaml | 6 ++ pnpm-workspace.yaml | 1 + 5 files changed, 115 insertions(+), 72 deletions(-) diff --git a/packages/runtime-bundler/package.json b/packages/runtime-bundler/package.json index 8e61a4859..38cb20469 100644 --- a/packages/runtime-bundler/package.json +++ b/packages/runtime-bundler/package.json @@ -18,6 +18,7 @@ "dependencies": { "@douglasneuroinformatics/libjs": "catalog:", "esbuild": "catalog:", + "oxc-parser": "catalog:", "zod": "workspace:zod__3.x@*" } } diff --git a/packages/runtime-bundler/src/__tests__/plugin.test.ts b/packages/runtime-bundler/src/__tests__/plugin.test.ts index 7e6a349eb..436cbcdff 100644 --- a/packages/runtime-bundler/src/__tests__/plugin.test.ts +++ b/packages/runtime-bundler/src/__tests__/plugin.test.ts @@ -1,7 +1,6 @@ import * as fs from 'node:fs/promises'; import type { OnLoadArgs, OnResolveArgs, PluginBuild } from 'esbuild'; -import ts from 'typescript'; import { beforeEach, describe, expect, it, vi } from 'vitest'; import { assetPlugin, dtsPlugin } from '../plugin.js'; @@ -23,11 +22,6 @@ vi.mock('module', async (importOriginal) => ({ vi.mock('fs/promises', () => ({ readFile: vi.fn() })); -vi.mock('typescript', async (importOriginal) => { - const actual = (await importOriginal<{ default: typeof import('typescript') }>()).default; - return { default: { ...actual, transform: vi.fn(actual.transform) } }; -}); - /** Maps `'@'` to the resolved package.json path the mocked require would return. */ const packageJsonResolutions = new Map(); @@ -163,10 +157,66 @@ describe('dtsPlugin', () => { const { onLoadCallbacks } = setupPlugin(dtsPlugin({ configFilepath, entryPoints, outdir: '/out', packages })); const result: any = await onLoadCallbacks[0]!({ path: importerFilepath } as OnLoadArgs); expect(result.loader).toBe('copy'); - expect(result.contents).toContain('from "../some-pkg/index.d.ts"'); + expect(result.contents).toContain("from '../some-pkg/index.d.ts'"); expect(result.contents).toContain("from './local.js'"); }); + it('should change nothing but the text inside each bare specifier, so quote style and comments survive', async () => { + packageJsonResolutions.set(`some-pkg/package.json@${importerFilepath}`, '/repo/node_modules/some-pkg/package.json'); + const packages: ResolvedPackage[] = [ + { + exports: { '.': { types: '/repo/node_modules/some-pkg/index.d.ts' } }, + name: 'some-pkg', + packageJsonPath: '/repo/node_modules/some-pkg/package.json', + packageRoot: '/repo/node_modules/some-pkg' + } + ]; + const entryPoints: EntryPoint[] = [ + { in: '/repo/node_modules/some-pkg/index.d.ts', out: 'some-pkg/index.d' }, + { in: importerFilepath, out: 'app/index.d' } + ]; + vi.mocked(fs.readFile).mockResolvedValueOnce( + "import type { X } from \"some-pkg\";\n/** café: import { Y } from 'some-pkg'; */\nimport type { Z } from 'some-pkg';\n" + ); + const { onLoadCallbacks } = setupPlugin(dtsPlugin({ configFilepath, entryPoints, outdir: '/out', packages })); + const result: any = await onLoadCallbacks[0]!({ path: importerFilepath } as OnLoadArgs); + expect(result.contents).toBe( + "import type { X } from \"../some-pkg/index.d.ts\";\n/** café: import { Y } from 'some-pkg'; */\nimport type { Z } from '../some-pkg/index.d.ts';\n" + ); + }); + + it('should rewrite a bare import nested in a declare module block, not only top-level imports', async () => { + packageJsonResolutions.set(`some-pkg/package.json@${importerFilepath}`, '/repo/node_modules/some-pkg/package.json'); + const packages: ResolvedPackage[] = [ + { + exports: { '.': { types: '/repo/node_modules/some-pkg/index.d.ts' } }, + name: 'some-pkg', + packageJsonPath: '/repo/node_modules/some-pkg/package.json', + packageRoot: '/repo/node_modules/some-pkg' + } + ]; + const entryPoints: EntryPoint[] = [ + { in: '/repo/node_modules/some-pkg/index.d.ts', out: 'some-pkg/index.d' }, + { in: importerFilepath, out: 'app/index.d' } + ]; + vi.mocked(fs.readFile).mockResolvedValueOnce( + "declare module 'augmented' {\n import type { X } from 'some-pkg';\n export const x: X;\n}\n" + ); + const { onLoadCallbacks } = setupPlugin(dtsPlugin({ configFilepath, entryPoints, outdir: '/out', packages })); + const result: any = await onLoadCallbacks[0]!({ path: importerFilepath } as OnLoadArgs); + expect(result.contents).toContain("import type { X } from '../some-pkg/index.d.ts';"); + }); + + it('should leave an export-from declaration untouched, so its package need not be included', async () => { + const sourceText = "export type { X } from 'unlisted-pkg';\n"; + vi.mocked(fs.readFile).mockResolvedValueOnce(sourceText); + const { onLoadCallbacks } = setupPlugin( + dtsPlugin({ configFilepath, entryPoints: [], outdir: '/out', packages: [] }) + ); + const result: any = await onLoadCallbacks[0]!({ path: importerFilepath } as OnLoadArgs); + expect(result.contents).toBe(sourceText); + }); + it('should resolve a subpath import of a scoped package against its own export key', async () => { packageJsonResolutions.set( `@scope/pkg/package.json@${importerFilepath}`, @@ -187,7 +237,7 @@ describe('dtsPlugin', () => { vi.mocked(fs.readFile).mockResolvedValueOnce("import type { X } from '@scope/pkg/sub';\nexport type { X };\n"); const { onLoadCallbacks } = setupPlugin(dtsPlugin({ configFilepath, entryPoints, outdir: '/out', packages })); const result: any = await onLoadCallbacks[0]!({ path: importerFilepath } as OnLoadArgs); - expect(result.contents).toContain('from "../@scope/pkg/sub.d.ts"'); + expect(result.contents).toContain("from '../@scope/pkg/sub.d.ts'"); }); it('should error when the matched package does not export the imported subpath', async () => { @@ -223,29 +273,16 @@ describe('dtsPlugin', () => { vi.mocked(fs.readFile).mockResolvedValueOnce("import type { X } from 'some-pkg';\nexport type { X };\n"); const { onLoadCallbacks } = setupPlugin(dtsPlugin({ configFilepath, entryPoints, outdir: '/out', packages })); const result: any = await onLoadCallbacks[0]!({ path: importerFilepath } as OnLoadArgs); - expect(result.contents).toContain('from "../some-pkg/types.ts"'); - }); - - it('should report a non-error thrown during the transform as an unknown error', async () => { - vi.mocked(ts.transform).mockImplementationOnce(() => { - // eslint-disable-next-line @typescript-eslint/only-throw-error -- the plugin must report a thrown value that is not an Error - throw 'not an error'; - }); - vi.mocked(fs.readFile).mockResolvedValueOnce('export type X = string;\n'); - const { onLoadCallbacks } = setupPlugin( - dtsPlugin({ configFilepath, entryPoints: [], outdir: '/out', packages: [] }) - ); - const result: any = await onLoadCallbacks[0]!({ path: importerFilepath } as OnLoadArgs); - expect(result.errors[0]).toEqual({ location: { file: importerFilepath }, text: 'Unknown Error' }); + expect(result.contents).toContain("from '../some-pkg/types.ts'"); }); - it('should report a transform failure as a load error rather than throw', async () => { + it('should report a syntax error as a load error on the file rather than emit the declaration', async () => { vi.mocked(fs.readFile).mockResolvedValueOnce('this is not valid { typescript syntax +++'); const { onLoadCallbacks } = setupPlugin( dtsPlugin({ configFilepath, entryPoints: [], outdir: '/out', packages: [] }) ); const result: any = await onLoadCallbacks[0]!({ path: importerFilepath } as OnLoadArgs); - expect(Array.isArray(result.errors) || result.contents !== undefined).toBe(true); + expect(result).toEqual({ errors: [expect.objectContaining({ location: { file: importerFilepath } })] }); }); }); diff --git a/packages/runtime-bundler/src/plugin.ts b/packages/runtime-bundler/src/plugin.ts index 5ac2d283b..ab720891f 100644 --- a/packages/runtime-bundler/src/plugin.ts +++ b/packages/runtime-bundler/src/plugin.ts @@ -3,7 +3,8 @@ import * as module from 'node:module'; import * as path from 'node:path'; import type { Plugin } from 'esbuild'; -import ts from 'typescript'; +import { parseSync, Visitor } from 'oxc-parser'; +import type { ImportDeclaration } from 'oxc-parser'; import { validatePackageName } from './utils.js'; @@ -16,6 +17,8 @@ type DtsPluginOptions = { packages: ResolvedPackage[]; }; +type DependencyResolution = { issue: string; success: false } | { relativePath: string; success: true }; + function parseImportPath(importPath: string) { const segments = importPath.split('/'); const sliceIndex = importPath.startsWith('@') ? 2 : 1; @@ -28,13 +31,12 @@ function parseImportPath(importPath: string) { export function dtsPlugin(options: DtsPluginOptions): Plugin { const require = module.createRequire(options.configFilepath); - const printer = ts.createPrinter(); - const resolveDependency = (importPath: string, importerFilepath: string) => { + const resolveDependency = (importPath: string, importerFilepath: string): DependencyResolution => { const { exportKey, packageId } = parseImportPath(importPath); const validationResult = validatePackageName(packageId); if (!validationResult.success) { - throw new Error(`Illegal import '${importPath}': ${validationResult.issue}`); + return { issue: `Illegal import '${importPath}': ${validationResult.issue}`, success: false }; } const packageJsonId = `${packageId}/package.json`; @@ -42,7 +44,10 @@ export function dtsPlugin(options: DtsPluginOptions): Plugin { try { packageJsonFilepath = require.resolve(packageJsonId, { paths: [importerFilepath] }); } catch { - throw new Error(`Failed to resolve '${packageId}' from '${importerFilepath}' via '${packageJsonId}'`); + return { + issue: `Failed to resolve '${packageId}' from '${importerFilepath}' via '${packageJsonId}'`, + success: false + }; } for (const pkg of options.packages) { if (pkg.packageJsonPath !== packageJsonFilepath) { @@ -51,47 +56,29 @@ export function dtsPlugin(options: DtsPluginOptions): Plugin { const packageExport = pkg.exports[exportKey]; if (packageExport) { if ('copy' in packageExport) { - throw new Error(`Found dependency '${importPath}' but export '${exportKey}' is a static asset`); + return { + issue: `Found dependency '${importPath}' but export '${exportKey}' is a static asset`, + success: false + }; } const types = packageExport.types; if (types) { const outfile = options.entryPoints.find((item) => item.in === types)?.out; if (!outfile) { - throw new Error(`Could not find dependency with absolute input path '${types}'`); + return { issue: `Could not find dependency with absolute input path '${types}'`, success: false }; } const outpath = path.resolve(options.outdir, outfile + (outfile.endsWith('.d') ? '.ts' : '')); const importerPath = options.entryPoints.find((item) => item.in === importerFilepath)!.out; const importer = path.resolve(options.outdir, importerPath + (importerPath.endsWith('.d') ? '.ts' : '')); - return path.relative(path.dirname(importer), outpath); + return { relativePath: path.relative(path.dirname(importer), outpath), success: true }; } - throw new Error(`Found dependency '${importPath}' but export '${exportKey}' does not specify types`); + return { + issue: `Found dependency '${importPath}' but export '${exportKey}' does not specify types`, + success: false + }; } } - throw new Error(`Could not find dependency '${importPath}' imported by '${importerFilepath}'`); - }; - - const factory = (context: ts.TransformationContext) => { - return (rootNode: T): T => { - const visit = (node: ts.Node) => { - if (ts.isImportDeclaration(node)) { - const importPath = (node.moduleSpecifier as ts.StringLiteral).text; - const isRelativeImport = importPath.startsWith('./'); - if (isRelativeImport) { - return ts.visitEachChild(node, visit, context); - } - const resolvedImportPath = resolveDependency(importPath, rootNode.fileName); - return ts.factory.updateImportDeclaration( - node, - node.modifiers, - node.importClause, - ts.factory.createStringLiteral(resolvedImportPath), - node.attributes - ); - } - return ts.visitEachChild(node, visit, context); - }; - return ts.visitNode(rootNode, visit) as T; - }; + return { issue: `Could not find dependency '${importPath}' imported by '${importerFilepath}'`, success: false }; }; return { @@ -104,23 +91,34 @@ export function dtsPlugin(options: DtsPluginOptions): Plugin { })); build.onLoad({ filter: /.*/, namespace }, async (args) => { const sourceText = await fs.readFile(args.path, 'utf-8'); - const sourceFile = ts.createSourceFile(args.path, sourceText, ts.ScriptTarget.ESNext, true, ts.ScriptKind.TS); - let transformationResult: ts.TransformationResult; - try { - transformationResult = ts.transform(sourceFile, [factory]); - } catch (err) { + const parseResult = parseSync(args.path, sourceText, { lang: 'dts', sourceType: 'module' }); + if (parseResult.errors.length) { return { - errors: [ - { - location: { - file: args.path - }, - text: err instanceof Error ? err.message : 'Unknown Error' - } - ] + errors: parseResult.errors.map((error) => ({ location: { file: args.path }, text: error.message })) }; } - const contents = printer.printFile(transformationResult.transformed[0]!); + // every import declaration, including those nested in `declare module` blocks, in source order + const importDeclarations: ImportDeclaration[] = []; + new Visitor({ + ImportDeclaration(node) { + importDeclarations.push(node); + } + }).visit(parseResult.program); + let contents = ''; + let copiedUpTo = 0; + for (const { source } of importDeclarations) { + if (source.value.startsWith('./')) { + continue; + } + const resolution = resolveDependency(source.value, args.path); + if (!resolution.success) { + return { errors: [{ location: { file: args.path }, text: resolution.issue }] }; + } + // the specifier's span includes its quotes; splicing between them keeps the source's quote style + contents += sourceText.slice(copiedUpTo, source.start + 1) + resolution.relativePath; + copiedUpTo = source.end - 1; + } + contents += sourceText.slice(copiedUpTo); return { contents, loader: 'copy' diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index f218af7f7..ee3cb8a24 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -102,6 +102,9 @@ catalogs: nodemailer: specifier: ^10.0.11 version: 10.0.11 + oxc-parser: + specifier: ^0.150.0 + version: 0.150.0 prisma: specifier: ^6.9.0 version: 6.19.3 @@ -1100,6 +1103,9 @@ importers: esbuild: specifier: 'catalog:' version: 0.28.2 + oxc-parser: + specifier: 'catalog:' + version: 0.150.0 zod: specifier: workspace:zod__3.x@* version: link:../../vendor/zod@3.x diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 863bc18d7..28f4614d4 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -40,6 +40,7 @@ catalog: motion: '13.4.4' neverthrow: ^8.2.0 nodemailer: ^10.0.11 + oxc-parser: '^0.150.0' conventional-commits-parser: '^7.1.2' prisma: '^6.9.0' react-dropzone: ^20.1.2 From c22106d02b3c919851fd4fbffacbe2105f6a594b Mon Sep 17 00:00:00 2001 From: joshunrau Date: Wed, 18 Nov 2026 13:12:41 -0500 Subject: [PATCH 2/2] refactor(testing): read the route union with oxc-parser gen-routes pulled FileRouteTypes['to'] out of apps/web's route tree with the TypeScript compiler API, which TypeScript 7 no longer exposes. Read it from oxc-parser's AST instead; the generated route.d.ts is byte-identical. A route tree that fails to parse, or whose union holds no string literal, now stops the script instead of being ignored or written out as an empty type. Co-Authored-By: Claude Opus 5.5 --- pnpm-lock.yaml | 3 ++ testing/package.json | 1 + testing/scripts/gen-routes.ts | 52 ++++++++++++++++++++++------------- 3 files changed, 37 insertions(+), 19 deletions(-) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index ee3cb8a24..4fce435ba 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1452,6 +1452,9 @@ importers: '@playwright/test': specifier: ^1.63.0 version: 1.63.0 + oxc-parser: + specifier: 'catalog:' + version: 0.150.0 type-fest: specifier: workspace:type-fest__4.x@* version: link:../vendor/type-fest@4.x diff --git a/testing/package.json b/testing/package.json index 10d8d4651..ca9d3202a 100644 --- a/testing/package.json +++ b/testing/package.json @@ -15,6 +15,7 @@ "@opendatacapture/playground-url": "workspace:*", "@opendatacapture/schemas": "workspace:*", "@playwright/test": "^1.63.0", + "oxc-parser": "catalog:", "type-fest": "workspace:type-fest__4.x@*" } } diff --git a/testing/scripts/gen-routes.ts b/testing/scripts/gen-routes.ts index f2ad6e049..429689b50 100644 --- a/testing/scripts/gen-routes.ts +++ b/testing/scripts/gen-routes.ts @@ -16,34 +16,48 @@ import * as fs from 'node:fs'; import * as path from 'node:path'; -import ts from 'typescript'; +import { parseSync } from 'oxc-parser'; +import type { ExportNamedDeclaration, TSInterfaceDeclaration, TSPropertySignature } from 'oxc-parser'; const ROUTE_TREE_PATH = path.resolve(import.meta.dirname, '../../apps/web/src/route-tree.ts'); const OUTPUT_PATH = path.resolve(import.meta.dirname, '../src/generated/route.d.ts'); function extractRouteToMembers(sourceText: string): string[] { - const sourceFile = ts.createSourceFile('route-tree.ts', sourceText, ts.ScriptTarget.Latest, true); + const { errors, program } = parseSync(ROUTE_TREE_PATH, sourceText); + if (errors.length) { + throw new Error( + `Could not parse route-tree.ts:\n${errors.map((error) => error.codeframe ?? error.message).join('\n')}` + ); + } - let members: null | string[] = null; - const visit = (node: ts.Node): void => { - if (ts.isInterfaceDeclaration(node) && node.name.text === 'FileRouteTypes') { - const toProperty = node.members.find((member): member is ts.PropertySignature => { - return ts.isPropertySignature(member) && member.name.getText(sourceFile) === 'to'; - }); - if (toProperty?.type && ts.isUnionTypeNode(toProperty.type)) { - members = toProperty.type.types.flatMap((typeNode) => { - if (ts.isLiteralTypeNode(typeNode) && ts.isStringLiteral(typeNode.literal)) { - return [typeNode.literal.text]; + const fileRouteTypes = program.body.find( + (statement): statement is ExportNamedDeclaration & { declaration: TSInterfaceDeclaration } => { + return ( + statement.type === 'ExportNamedDeclaration' && + statement.declaration?.type === 'TSInterfaceDeclaration' && + statement.declaration.id.name === 'FileRouteTypes' + ); + } + )?.declaration; + const toProperty = fileRouteTypes?.body.body.find((member): member is TSPropertySignature => { + return member.type === 'TSPropertySignature' && member.key.type === 'Identifier' && member.key.name === 'to'; + }); + const toType = toProperty?.typeAnnotation?.typeAnnotation; + const members = + toType?.type === 'TSUnionType' + ? toType.types.flatMap((typeNode) => { + if ( + typeNode.type === 'TSLiteralType' && + typeNode.literal.type === 'Literal' && + typeof typeNode.literal.value === 'string' + ) { + return [typeNode.literal.value]; } return []; - }); - } - } - ts.forEachChild(node, visit); - }; - visit(sourceFile); + }) + : []; - if (!members) { + if (!members.length) { throw new Error("Could not find `FileRouteTypes['to']` string-literal union in route-tree.ts"); } return members;