@lovrozagar/honey 0.6.8 → 0.7.1

package/src/type-extractor.ts

@@ -1,6 +1,8 @@
-import { existsSync } from "node:fs"
-import { dirname, relative, resolve } from "node:path"
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, join, relative, resolve, sep } from "node:path"
 import type { ts } from "ts-morph"
+import { canonical, expandOptional, joinPatterns, parsePattern } from "./pattern.ts"
+import { quoteKey } from "./type-emitter.ts"
 
 export type ExtractedBaseCtx = {
 	envType: string
@@ -8,85 +10,105 @@ export type ExtractedBaseCtx = {
 	tapsType: string | null
 }
 
+/**
+ * The tsconfig that governs the entry: the nearest one walking up, but never past the
+ * project root (the nearest directory with a package.json) — a stray tsconfig in a parent
+ * directory or the home folder is not this project's.
+ */
 function findTsConfig(fromPath: string): string | undefined {
 	let dir = dirname(resolve(fromPath))
 	let prev = ""
 	while (dir !== prev) {
 		const p = resolve(dir, "tsconfig.json")
 		if (existsSync(p)) return p
+		if (existsSync(resolve(dir, "package.json"))) return undefined
 		prev = dir
 		dir = dirname(dir)
 	}
 	return undefined
 }
 
+/* ts-morph bundles a different TS version — structurally identical at runtime */
+function bridge<T>(value: unknown): T {
+	return value as T
+}
+
+type LoadedEntry = {
+	/** The app's type */
+	appType: ts.Type
+	checker: ts.TypeChecker
+	compiler: typeof ts
+	/** A node inside the entry, for type lookups that need a location */
+	node: ts.Node
+	project: import("ts-morph").Project
+	sourceFile: import("ts-morph").SourceFile
+}
+
 /**
- * Uses ts-morph to extract the middleware context type from a Honey app export.
- * Returns inline type strings so the gen file has zero imports from user code.
+ * Load the entry and find the app export: `export const app = …`, any other exported
+ * declaration of that name, or `export default honey()` for `exportName: "default"`.
  */
-export async function extractBaseCtx(options: {
+async function loadEntry(options: {
 	entryPath: string
 	exportName: string
-	outputDir?: string
 	tsconfigPath?: string
-}): Promise<ExtractedBaseCtx> {
-	const { Project, ts } = await import("ts-morph")
-
+}): Promise<LoadedEntry> {
+	const { Project, ts: tsLib } = await import("ts-morph")
 	const tsConfigFilePath = options.tsconfigPath ?? findTsConfig(options.entryPath)
-
-	const project = new Project({
-		skipAddingFilesFromTsConfig: true,
-		tsConfigFilePath,
-	})
-
+	const project = new Project({ skipAddingFilesFromTsConfig: true, tsConfigFilePath })
 	project.addSourceFilesAtPaths(options.entryPath)
 	project.resolveSourceFileDependencies()
 
 	const sourceFile = project.getSourceFileOrThrow(options.entryPath)
-	const varDecl = sourceFile.getVariableDeclaration(options.exportName)
-	if (!varDecl) {
+	const declarations = sourceFile.getExportedDeclarations().get(options.exportName)
+	const decl = declarations?.[0] ?? sourceFile.getVariableDeclaration(options.exportName)
+	if (!decl) {
 		throw new Error(`Export "${options.exportName}" not found in ${options.entryPath}`)
 	}
-
-	const type = varDecl.getType()
-	/* ts-morph bundles different TS version — structurally identical at runtime */
-	function bridge<T>(value: unknown): T {
-		return value as T
-	}
 	const checker: ts.TypeChecker = bridge(project.getTypeChecker().compilerObject)
-	const node: ts.Node = bridge(varDecl.compilerNode)
-	const tsLib: typeof ts = bridge(ts)
+	const node: ts.Node = bridge(decl.compilerNode)
+	const compiler: typeof ts = bridge(tsLib)
+	/* `export default <expr>` declares an ExportAssignment; its type is the expression's */
+	const target = compiler.isExportAssignment(node) ? node.expression : node
+	const appType = checker.getTypeAtLocation(target)
+	return { appType, checker, compiler, node: target, project, sourceFile }
+}
+
+/**
+ * Uses ts-morph to extract the middleware context type from a Honey app export.
+ * Returns inline type strings so the gen file has zero imports from user code.
+ */
+export async function extractBaseCtx(options: {
+	entryPath: string
+	exportName: string
+	outputDir?: string
+	tsconfigPath?: string
+}): Promise<ExtractedBaseCtx> {
+	const { appType, checker, compiler, node } = await loadEntry(options)
+	const ser = new Serializer(checker, node, compiler)
 
-	function getType(sym: ReturnType<typeof type.getProperty>): ts.Type {
-		const s: ts.Symbol = bridge(sym?.compilerSymbol)
-		return checker.getTypeOfSymbolAtLocation(s, node)
+	const typeOfProp = (name: string): ts.Type | null => {
+		const sym = appType.getProperty(name)
+		return sym ? checker.getTypeOfSymbolAtLocation(sym, node) : null
 	}
 
 	/* extract $env */
-	let envType = "Record<string, unknown>"
-	const envProp = type.getProperty("$env")
-	if (envProp) {
-		envType = serialize(getType(envProp), checker, node, tsLib)
-	}
+	const envT = typeOfProp("$env")
+	const envType = envT ? ser.serialize(envT) : "Record<string, unknown>"
 
 	/* extract $ctx and isolate middleware additions */
-	const ctxProp = type.getProperty("$ctx")
-	if (!ctxProp) {
+	const ctxType = typeOfProp("$ctx")
+	if (!ctxType) {
 		throw new Error(`Export "${options.exportName}" has no $ctx — not a Honey instance`)
 	}
-
-	const ctxType = getType(ctxProp)
-	const middlewareType = extractMiddleware(ctxType, checker, node, tsLib)
+	const middlewareType = propsType(extractMiddlewareProps(ctxType, ser))
 
 	/* extract $taps — typed tap payloads declared via .taps<T>() */
 	let tapsType: string | null = null
-	const tapsProp = type.getProperty("$taps")
-	if (tapsProp) {
-		const tapsT = getType(tapsProp)
-		const tapsStr = serialize(tapsT, checker, node, tsLib)
-		if (tapsStr !== "{}" && tapsStr !== "Record<string, unknown>") {
-			tapsType = tapsStr
-		}
+	const tapsT = typeOfProp("$taps")
+	if (tapsT) {
+		const tapsStr = ser.serialize(tapsT)
+		if (tapsStr !== "{}" && tapsStr !== "Record<string, unknown>") tapsType = tapsStr
 	}
 
 	const sanitize = (s: string) => sanitizeImportPaths(s, options.outputDir)
@@ -116,47 +138,27 @@ const HONEY_CTX_PROPS = new Set([
 	"tap",
 ])
 
-/** Resolve an import() reference from a declaration's type annotation */
-function resolveTypeRefFromDecl(
-	decl: ts.Declaration | undefined,
-	checker: ts.TypeChecker,
-	compiler: typeof ts,
-): string | undefined {
-	if (!decl) return undefined
-	const typeRef = (decl as { type?: ts.TypeNode }).type
-	if (!typeRef || !compiler.isTypeReferenceNode(typeRef)) return undefined
-	const typeName = (typeRef as ts.TypeReferenceNode).typeName
-
-	let refSym = checker.getSymbolAtLocation(typeName)
-	while (refSym && refSym.flags & compiler.SymbolFlags.Alias) {
-		refSym = checker.getAliasedSymbol(refSym)
-	}
-	if (!refSym) return undefined
-
-	const refDecls = refSym.declarations
-	if (!refDecls?.length) return undefined
-
-	const srcFile = refDecls[0].getSourceFile()
-	if (!isExportedFromFile(refSym, srcFile, checker)) return undefined
+type MwPropEntry = { name: string; opt: boolean; type: string }
 
-	return `import("${srcFile.fileName}").${refSym.getName()}`
+function propsType(props: readonly MwPropEntry[]): string | null {
+	if (props.length === 0) return null
+	return `{ ${props.map((p) => `${quoteKey(p.name)}${p.opt ? "?" : ""}: ${p.type}`).join("; ")} }`
 }
 
-type MwPropEntry = { name: string; opt: boolean; type: string }
+/** Is a property name something a type literal can spell and a consumer can see? */
+function isPublicName(name: string): boolean {
+	/* `#secret` private fields surface as `__#123@#secret` — never part of a type */
+	return !name.startsWith("#") && !name.startsWith("__#")
+}
 
-function extractMiddlewareProps(
-	ctxType: ts.Type,
-	checker: ts.TypeChecker,
-	node: ts.Node,
-	compiler: typeof ts,
-): MwPropEntry[] {
-	const allProps = ctxType.getProperties()
-	const mwProps = allProps.filter((p) => {
+function extractMiddlewareProps(ctxType: ts.Type, ser: Serializer): MwPropEntry[] {
+	const { checker, compiler, node } = ser
+	const mwProps = ctxType.getProperties().filter((p) => {
 		const name = p.getName()
 		if (HONEY_CTX_PROPS.has(name)) return false
 		/* skip internal/private properties (underscore-prefixed) */
 		if (name.startsWith("_")) return false
-		return true
+		return isPublicName(name)
 	})
 
 	return mwProps.map((p) => {
@@ -166,14 +168,14 @@ function extractMiddlewareProps(
 		/* 1. try declaration-site TypeReference (explicit annotation on property or variable) */
 		let typeStr: string | undefined
 		const mwDecl = p.valueDeclaration ?? p.declarations?.[0]
-		typeStr = resolveTypeRefFromDecl(mwDecl, checker, compiler)
+		typeStr = ser.refFromDeclaration(mwDecl)
 
 		/* 1b. shorthand property — trace to the underlying variable's type annotation */
 		if (!typeStr && mwDecl && compiler.isShorthandPropertyAssignment(mwDecl)) {
 			const varSym = checker.getShorthandAssignmentValueSymbol(mwDecl)
 			if (varSym) {
 				const varDecl = varSym.valueDeclaration ?? varSym.declarations?.[0]
-				typeStr = resolveTypeRefFromDecl(varDecl, checker, compiler)
+				typeStr = ser.refFromDeclaration(varDecl)
 
 				/* 1c. destructured binding (e.g. const { shardDb } = openShardSession(...))
 				 * — trace through the function return type to find the original type annotation */
@@ -189,7 +191,7 @@ function extractMiddlewareProps(
 								const innerSym = checker.getShorthandAssignmentValueSymbol(retProp.valueDeclaration)
 								if (innerSym) {
 									const innerDecl = innerSym.valueDeclaration ?? innerSym.declarations?.[0]
-									typeStr = resolveTypeRefFromDecl(innerDecl, checker, compiler)
+									typeStr = ser.refFromDeclaration(innerDecl)
 								}
 							}
 						}
@@ -198,32 +200,13 @@ function extractMiddlewareProps(
 			}
 		}
 
-		/* 2. try resolved type as named import reference */
-		if (!typeStr) {
-			typeStr = serializeAsRef(t, checker, node, compiler) ?? undefined
-		}
-
-		/* 3. structural fallback */
-		if (!typeStr) {
-			typeStr = serialize(t, checker, node, compiler)
-		}
+		/* 2. a named type as an import() reference; 3. structural */
+		typeStr ??= ser.asRef(t) ?? ser.serialize(t)
 
 		return { name: p.getName(), opt, type: typeStr }
 	})
 }
 
-function extractMiddleware(
-	ctxType: ts.Type,
-	checker: ts.TypeChecker,
-	node: ts.Node,
-	compiler: typeof ts,
-): string | null {
-	const props = extractMiddlewareProps(ctxType, checker, node, compiler)
-	if (props.length === 0) return null
-	const entries = props.map((p) => `${p.name}${p.opt ? "?" : ""}: ${p.type}`)
-	return `{ ${entries.join("; ")} }`
-}
-
 /** Check if a symbol is exported from its source file */
 function isExportedFromFile(sym: ts.Symbol, sf: ts.SourceFile, checker: ts.TypeChecker): boolean {
 	/* .d.ts module types are always accessible */
@@ -234,216 +217,257 @@ function isExportedFromFile(sym: ts.Symbol, sf: ts.SourceFile, checker: ts.TypeC
 	return exports.some((e) => e.getName() === sym.getName())
 }
 
+/** Lib types every program has in scope; their names are written as is, never imported. */
+function isLibFile(fileName: string): boolean {
+	return /(?:^|[\\/])lib\.[\w.-]*\.d\.ts$/.test(fileName) || /[\\/]typescript[\\/]lib[\\/]/.test(fileName)
+}
+
 /**
- * Attempts to build an `import("path").TypeName` reference for a type.
- * Returns null if the type has no usable named symbol.
+ * TypeScript types → type source text.
  *
- * Prefers compact references over structural expansion:
- * - .d.ts types: import("drizzle-orm/d1").DrizzleD1Database
- * - .ts type aliases: import("./db.orm.gen").CoreDb
- * - globals (Promise, Map, etc.) are skipped — handled by serialize()
+ * Named types become `import("…").Name<Args>` references when the declaring module exports
+ * them; everything else is written structurally. The structural writer is precise about the
+ * things a reader relies on: optional and rest parameters, generic signatures, tuple rest and
+ * optional elements, literal types (quoted), boolean literals, quoted keys, and precedence
+ * (`(() => void)[]`, `(A | B) & C`). A type it is still expanding when it meets itself again
+ * is written as `unknown` there, never expanded without end.
  */
-function serializeAsRef(
-	type: ts.Type,
-	checker: ts.TypeChecker,
-	node: ts.Node,
-	compiler: typeof ts,
-	depth = 0,
-): string | null {
-	if (depth > 6) return null
-
-	/* union with never members (from intersection narrowing) — simplify first */
-	if (type.isUnion()) {
-		const nonNever = (type as ts.UnionType).types.filter((t) => !(t.flags & compiler.TypeFlags.Never))
-		if (nonNever.length === 1) {
-			return serializeAsRef(nonNever[0], checker, node, compiler, depth)
-		}
+class Serializer {
+	readonly checker: ts.TypeChecker
+	readonly compiler: typeof ts
+	readonly node: ts.Node
+	readonly #active = new Set<ts.Type>()
+	/* type parameters of the signatures being written: inside them a parameter keeps its name */
+	readonly #bound = new Set<ts.Symbol>()
+
+	constructor(checker: ts.TypeChecker, node: ts.Node, compiler: typeof ts) {
+		this.checker = checker
+		this.node = node
+		this.compiler = compiler
 	}
 
-	const sym = type.getSymbol() ?? type.aliasSymbol
-	if (!sym) return null
-
-	const name = sym.getName()
-	if (!name || name.startsWith("__") || name === "Object") return null
-
-	const decls = sym.declarations
-	if (!decls?.length) return null
-
-	const sf = decls[0].getSourceFile()
-	const fileName = sf.fileName
-
-	/* skip global/lib types — serialize() handles these with its globals set */
-	if (fileName.includes("/lib.") || fileName.includes("/lib/")) return null
+	/** An `import()` reference with type arguments for an annotation like `x: Foo<Bar>`. */
+	refFromDeclaration(decl: ts.Declaration | undefined): string | undefined {
+		const { checker, compiler } = this
+		if (!decl) return undefined
+		const typeRef = (decl as { type?: ts.TypeNode }).type
+		if (!typeRef || !compiler.isTypeReferenceNode(typeRef)) return undefined
+		let refSym = checker.getSymbolAtLocation(typeRef.typeName)
+		while (refSym && refSym.flags & compiler.SymbolFlags.Alias) refSym = checker.getAliasedSymbol(refSym)
+		if (!refSym?.declarations?.length) return undefined
+		const srcFile = refSym.declarations[0].getSourceFile()
+		if (isLibFile(srcFile.fileName)) return undefined
+		if (!isExportedFromFile(refSym, srcFile, checker)) return undefined
+		const args = typeRef.typeArguments?.map((a) => {
+			const t = checker.getTypeFromTypeNode(a)
+			return this.asRef(t) ?? this.serialize(t)
+		})
+		const argText = args && args.length > 0 ? `<${args.join(", ")}>` : ""
+		return `import("${srcFile.fileName}").${refSym.getName()}${argText}`
+	}
 
-	const isDts = sf.isDeclarationFile
-	const isTypeAlias =
-		(sym.flags & compiler.SymbolFlags.TypeAlias) !== 0 || decls.some((d) => compiler.isTypeAliasDeclaration(d))
+	/**
+	 * `import("path").TypeName<Args>` for a named type whose module exports it, else null.
+	 * Globals (Promise, Map, …) are left to `serialize`.
+	 */
+	asRef(type: ts.Type, depth = 0): string | null {
+		const { checker, compiler } = this
+		if (depth > 6) return null
+
+		/* union with never members (from intersection narrowing) — simplify first */
+		if (type.isUnion()) {
+			const nonNever = type.types.filter((t) => !(t.flags & compiler.TypeFlags.Never))
+			if (nonNever.length === 1) return this.asRef(nonNever[0], depth)
+		}
 
-	/* only reference .d.ts symbols or explicit type aliases from .ts files */
-	if (!isDts && !isTypeAlias) return null
+		const sym = type.aliasSymbol ?? type.getSymbol()
+		if (!sym) return null
+		const name = sym.getName()
+		if (!name || name.startsWith("__") || name === "Object") return null
+		const decls = sym.declarations
+		if (!decls?.length) return null
+		const sf = decls[0].getSourceFile()
+		if (isLibFile(sf.fileName)) return null
+
+		const named =
+			(sym.flags &
+				(compiler.SymbolFlags.TypeAlias |
+					compiler.SymbolFlags.Interface |
+					compiler.SymbolFlags.Class |
+					compiler.SymbolFlags.Enum)) !==
+			0
+		/* only reference .d.ts symbols or explicitly declared named types from .ts files */
+		if (!sf.isDeclarationFile && !named) return null
+
+		const typeArgs = type.aliasSymbol ? type.aliasTypeArguments : (type as ts.TypeReference).typeArguments
+		/* a class or interface reference carries its `this` type as a trailing argument */
+		const declared = sym.declarations?.[0]
+		const paramCount =
+			declared && "typeParameters" in declared
+				? ((declared as { typeParameters?: unknown[] }).typeParameters?.length ?? 0)
+				: (typeArgs?.length ?? 0)
+		const args = (typeArgs ?? []).slice(0, paramCount)
+		const withArgs = (ref: string): string =>
+			args.length > 0
+				? `${ref}<${args.map((arg) => this.asRef(arg, depth + 1) ?? this.serialize(arg)).join(", ")}>`
+				: ref
+
+		/* a global type (an ambient script such as wrangler's worker-configuration.d.ts, or
+		 * `declare global`) is in scope wherever the app compiles: write its name. Expanding it
+		 * loses overloads and generics, and the copy is not assignable back to the original. */
+		if (named) {
+			const globalName = this.#globalName(sym, decls[0])
+			if (globalName !== null) return withArgs(globalName)
+		}
+		/* any other ambient script declaration has no import() path */
+		if (sf.isDeclarationFile && !(sf as unknown as { externalModuleIndicator?: unknown }).externalModuleIndicator) {
+			return null
+		}
+		/* skip non-exported symbols — import() on them resolves to `any` */
+		if (!isExportedFromFile(sym, sf, checker)) return null
 
-	/* skip ambient .d.ts scripts (no exports) — import() can't resolve them */
-	if (isDts) {
-		const tsSf = sf as unknown as { externalModuleIndicator?: unknown }
-		if (!tsSf.externalModuleIndicator) return null
+		return withArgs(`import("${sf.fileName}").${name}`)
 	}
 
-	/* skip non-exported symbols — import() on them resolves to `any` */
-	if (!isExportedFromFile(sym, sf, checker)) return null
-
-	/* build type arguments if present */
-	const ref = type as ts.TypeReference
-	const typeArgs = ref.typeArguments ?? type.aliasTypeArguments
-	if (typeArgs?.length) {
-		const args = typeArgs.map((arg) => {
-			const argRef = serializeAsRef(arg, checker, node, compiler, depth + 1)
-			return argRef ?? serialize(arg, checker, node, compiler)
-		})
-		return `import("${fileName}").${name}<${args.join(", ")}>`
+	/** The name a global declaration is reachable by (`Cloudflare.Env`), or null if it is module-scoped. */
+	#globalName(sym: ts.Symbol, decl: ts.Declaration): string | null {
+		const { compiler } = this
+		let global = false
+		for (let n: ts.Node | undefined = decl.parent; n; n = n.parent) {
+			if (compiler.isModuleDeclaration(n) && n.flags & compiler.NodeFlags.GlobalAugmentation) {
+				global = true
+				break
+			}
+			if (compiler.isSourceFile(n)) {
+				global = !(n as unknown as { externalModuleIndicator?: unknown }).externalModuleIndicator
+				break
+			}
+		}
+		if (!global) return null
+		/* a `declare global` member is qualified as `global.Name`; in scope it is `Name` */
+		const name = this.checker.getFullyQualifiedName(sym).replace(/^global\./, "")
+		return /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(name) ? name : null
 	}
 
-	return `import("${fileName}").${name}`
-}
-
-function serialize(type: ts.Type, checker: ts.TypeChecker, node: ts.Node, compiler: typeof ts, depth = 0): string {
-	if (depth > 8) return "unknown"
-
-	const next = (t: ts.Type) => serialize(t, checker, node, compiler, depth + 1)
-
-	/* primitives */
-	if (type.flags & compiler.TypeFlags.String) return "string"
-	if (type.flags & compiler.TypeFlags.Number) return "number"
-	if (type.flags & compiler.TypeFlags.Boolean) return "boolean"
-	if (type.flags & compiler.TypeFlags.BigInt) return "bigint"
-	if (type.flags & compiler.TypeFlags.ESSymbol) return "symbol"
-	if (type.flags & compiler.TypeFlags.Void) return "void"
-	if (type.flags & compiler.TypeFlags.Undefined) return "undefined"
-	if (type.flags & compiler.TypeFlags.Null) return "null"
-	if (type.flags & compiler.TypeFlags.Never) return "never"
-	if (type.flags & compiler.TypeFlags.Unknown) return "unknown"
-	if (type.flags & compiler.TypeFlags.Any) return "unknown"
-
-	/* literals */
-	if (type.isStringLiteral()) return `"${(type as ts.StringLiteralType).value}"`
-	if (type.isNumberLiteral()) return `${(type as ts.NumberLiteralType).value}`
-
-	/* union */
-	if (type.isUnion()) {
-		return type.types
-			.map((t) => {
-				const s = next(t)
-				/* parenthesize function types inside unions — TS syntax requires it */
-				return s.includes("=>") ? `(${s})` : s
-			})
-			.join(" | ")
+	serialize(type: ts.Type): string {
+		if (this.#active.has(type)) return "unknown"
+		this.#active.add(type)
+		try {
+			return this.#serialize(type)
+		} finally {
+			this.#active.delete(type)
+		}
 	}
 
-	/* intersection */
-	if (type.isIntersection()) return type.types.map(next).join(" & ")
+	#serialize(type: ts.Type): string {
+		const { checker, compiler, node } = this
+		const F = compiler.TypeFlags
+		const next = (t: ts.Type) => this.serialize(t)
 
-	/* array */
-	if (checker.isArrayType(type)) {
-		const args = checker.getTypeArguments(type as ts.TypeReference)
-		if (args.length > 0) {
-			const el = next(args[0])
-			return el.includes("|") || el.includes("&") ? `(${el})[]` : `${el}[]`
+		/* an enum is nominal: keep its name when it can be referenced */
+		const enumSym = type.getSymbol()
+		if (enumSym && enumSym.flags & compiler.SymbolFlags.Enum) {
+			const ref = this.asRef(type)
+			if (ref) return ref
 		}
-		return "unknown[]"
-	}
 
-	/* tuple */
-	if (checker.isTupleType(type)) {
-		const args = checker.getTypeArguments(type as ts.TypeReference)
-		return `[${args.map(next).join(", ")}]`
-	}
+		/* primitives */
+		if (type.flags & F.String) return "string"
+		if (type.flags & F.Number) return "number"
+		if (type.flags & F.Boolean) return "boolean"
+		if (type.flags & F.BigInt) return "bigint"
+		if (type.flags & F.ESSymbol) return "symbol"
+		if (type.flags & F.UniqueESSymbol) return "symbol"
+		if (type.flags & F.Void) return "void"
+		if (type.flags & F.Undefined) return "undefined"
+		if (type.flags & F.Null) return "null"
+		if (type.flags & F.Never) return "never"
+		if (type.flags & F.Unknown) return "unknown"
+		if (type.flags & F.Any) return "unknown"
+		if (type.flags & F.NonPrimitive) return "object"
+
+		/* literals */
+		if (type.isStringLiteral()) return JSON.stringify(type.value)
+		if (type.isNumberLiteral()) return `${type.value}`
+		if (type.flags & F.BigIntLiteral) {
+			const v = (type as ts.BigIntLiteralType).value
+			return `${v.negative ? "-" : ""}${v.base10Value}n`
+		}
+		if (type.flags & F.BooleanLiteral) return checker.typeToString(type)
+		if (type.flags & F.TemplateLiteral) return "string"
+
+		/* a type parameter: by name inside the signature that declares it, else its constraint or unknown */
+		if (type.flags & F.TypeParameter) {
+			if (type.symbol && this.#bound.has(type.symbol)) return type.symbol.getName()
+			const constraint = checker.getBaseConstraintOfType(type)
+			return constraint && constraint !== type ? next(constraint) : "unknown"
+		}
 
-	/* function (pure callable, no data properties) */
-	const sigs = type.getCallSignatures()
-	if (sigs.length > 0 && type.getProperties().length === 0) {
-		const sig = sigs[0]
-		const params = sig.getParameters().map((p) => {
-			const pt = checker.getTypeOfSymbolAtLocation(p, p.valueDeclaration ?? node)
-			const decl = p.valueDeclaration
-			const isRest =
-				decl !== undefined &&
-				compiler.isParameter(decl) &&
-				(decl as ts.ParameterDeclaration).dotDotDotToken !== undefined
-			return `${isRest ? "..." : ""}${p.getName()}: ${next(pt)}`
-		})
-		const ret = checker.getReturnTypeOfSignature(sig)
-		return `(${params.join(", ")}) => ${next(ret)}`
-	}
+		/* union */
+		if (type.isUnion()) return unionText(type.types.map(next))
 
-	/* well-known globals — keep name, serialize type args */
-	const sym = type.getSymbol()
-	if (sym) {
-		const name = sym.getName()
-		const globals = new Set([
-			"AbortController",
-			"AbortSignal",
-			"ArrayBuffer",
-			"Blob",
-			"DataView",
-			"Date",
-			"Error",
-			"File",
-			"FormData",
-			"Headers",
-			"Map",
-			"Promise",
-			"ReadableStream",
-			"RegExp",
-			"Request",
-			"Response",
-			"Set",
-			"SharedArrayBuffer",
-			"TransformStream",
-			"URL",
-			"URLSearchParams",
-			"WeakMap",
-			"WeakSet",
-			"WritableStream",
-		])
-		if (globals.has(name)) {
+		/* intersection */
+		if (type.isIntersection()) return intersectionText(type.types.map(next))
+
+		/* array */
+		if (checker.isArrayType(type)) {
+			const args = checker.getTypeArguments(type as ts.TypeReference)
+			const readonlyArray = type.getSymbol()?.getName() === "ReadonlyArray"
+			const el = args.length > 0 ? arrayText(next(args[0])) : "unknown[]"
+			return readonlyArray ? `readonly ${el}` : el
+		}
+
+		/* tuple — rest and optional elements kept */
+		if (checker.isTupleType(type)) {
 			const ref = type as ts.TypeReference
-			if (ref.typeArguments?.length) {
-				return `${name}<${ref.typeArguments.map(next).join(", ")}>`
-			}
-			return name
+			const args = checker.getTypeArguments(ref)
+			const target = ref.target as ts.TupleType
+			const parts = args.map((arg, i) => {
+				const flags = target.elementFlags?.[i] ?? compiler.ElementFlags.Required
+				if (flags & compiler.ElementFlags.Rest) return `...${arrayText(next(arg))}`
+				if (flags & compiler.ElementFlags.Variadic) return `...${next(arg)}`
+				if (flags & compiler.ElementFlags.Optional) return `${next(arg)}?`
+				return next(arg)
+			})
+			return `${target.readonly ? "readonly " : ""}[${parts.join(", ")}]`
 		}
 
-		/* named types — prefer import() reference over structural expansion */
-		if (name && !name.startsWith("__") && name !== "Object") {
-			const ref = serializeAsRef(type, checker, node, compiler, 0)
-			if (ref) return ref
+		/* function (pure callable, no data properties) */
+		const sigs = type.getCallSignatures()
+		if (sigs.length > 0 && type.getProperties().length === 0) {
+			const parts = sigs.map((sig) => this.#signature(sig))
+			return parts.length === 1 ? parts[0] : parts.map((p) => `(${p})`).join(" & ")
+		}
 
-			/* fallback: typeToString for .d.ts types without clean ref */
-			const decls = sym.declarations
-			if (decls?.length) {
-				const sf = decls[0].getSourceFile()
-				if (sf.isDeclarationFile) {
-					return checker.typeToString(
-						type,
-						node,
-						compiler.TypeFormatFlags.UseFullyQualifiedType | compiler.TypeFormatFlags.NoTruncation,
-					)
-				}
+		/* well-known globals — keep name, serialize type args */
+		const sym = type.getSymbol()
+		if (sym) {
+			const name = sym.getName()
+			const decl = sym.declarations?.[0]
+			if (decl && isLibFile(decl.getSourceFile().fileName) && name !== "Object" && !name.startsWith("__")) {
+				const args = (type as ts.TypeReference).typeArguments ?? []
+				const declaredParams = (decl as { typeParameters?: unknown[] }).typeParameters?.length ?? args.length
+				const kept = args.slice(0, declaredParams)
+				return kept.length > 0 ? `${name}<${kept.map(next).join(", ")}>` : name
+			}
+
+			/* named types — prefer import() reference over structural expansion */
+			if (name && !name.startsWith("__") && name !== "Object") {
+				const ref = this.asRef(type)
+				if (ref) return ref
 			}
 		}
-	}
+		const aliasRef = type.aliasSymbol ? this.asRef(type) : null
+		if (aliasRef) return aliasRef
 
-	/* Record<string, V> — index signature only */
-	const stringIdx = type.getStringIndexType()
-	if (stringIdx && type.getProperties().length === 0) {
-		return `Record<string, ${next(stringIdx)}>`
-	}
+		/* Record<string, V> — index signature only */
+		const stringIdx = type.getStringIndexType()
+		if (stringIdx && type.getProperties().length === 0) {
+			return `Record<string, ${next(stringIdx)}>`
+		}
 
-	/* object — expand to structural form */
-	const props = type.getProperties()
-	if (props.length > 50) {
-		return checker.typeToString(type, node, compiler.TypeFormatFlags.NoTruncation)
-	}
-	if (props.length > 0) {
+		/* object — expand to structural form */
+		const props = type.getProperties().filter((p) => isPublicName(p.getName()))
 		const entries: string[] = []
 		for (const p of props) {
 			const decls = p.getDeclarations()
@@ -455,37 +479,220 @@ function serialize(type: ts.Type, checker: ts.TypeChecker, node: ts.Node, compil
 			const opt = (p.flags & compiler.SymbolFlags.Optional) !== 0
 			const ro =
 				decls?.some((d) => (compiler.getCombinedModifierFlags(d) & compiler.ModifierFlags.Readonly) !== 0) ?? false
-			entries.push(`${ro ? "readonly " : ""}${p.getName()}${opt ? "?" : ""}: ${next(pt)}`)
+			entries.push(`${ro ? "readonly " : ""}${quoteKey(p.getName())}${opt ? "?" : ""}: ${next(pt)}`)
 		}
+		if (stringIdx) entries.push(`[key: string]: ${next(stringIdx)}`)
+		for (const sig of sigs) entries.push(this.#signature(sig, true))
 		if (entries.length > 0) return `{ ${entries.join("; ")} }`
+		if (props.length === 0) return "{}"
+		return "unknown"
+	}
+
+	/** `<T extends X>(a: A, b?: B, ...rest: C[]) => R`, or the call-signature member form */
+	#signature(sig: ts.Signature, member = false): string {
+		const typeParams = sig.getTypeParameters() ?? []
+		const added = typeParams.map((t) => t.symbol).filter((s) => s !== undefined && !this.#bound.has(s))
+		for (const s of added) this.#bound.add(s)
+		try {
+			return this.#signatureText(sig, typeParams, member)
+		} finally {
+			for (const s of added) this.#bound.delete(s)
+		}
+	}
+
+	#signatureText(sig: ts.Signature, typeParams: readonly ts.TypeParameter[], member: boolean): string {
+		const { checker, compiler, node } = this
+		const tp =
+			typeParams.length > 0
+				? `<${typeParams
+						.map((t) => {
+							const c = t.getConstraint()
+							return `${t.symbol.getName()}${c ? ` extends ${this.#typeParamText(c)}` : ""}`
+						})
+						.join(", ")}>`
+				: ""
+		const params = sig.getParameters().map((p) => {
+			const pt = checker.getTypeOfSymbolAtLocation(p, p.valueDeclaration ?? node)
+			const decl = p.valueDeclaration
+			const param = decl && compiler.isParameter(decl) ? (decl as ts.ParameterDeclaration) : undefined
+			const isRest = param?.dotDotDotToken !== undefined
+			const optional = !isRest && param !== undefined && checker.isOptionalParameter(param)
+			/* an optional parameter's type carries `| undefined`; `?` already says so */
+			const text = optional ? this.#typeParamText(checker.getNonNullableType(pt)) : this.#typeParamText(pt)
+			return `${isRest ? "..." : ""}${p.getName()}${optional ? "?" : ""}: ${text}`
+		})
+		const ret = this.#typeParamText(checker.getReturnTypeOfSignature(sig))
+		return member ? `${tp}(${params.join(", ")}): ${ret}` : `${tp}(${params.join(", ")}) => ${ret}`
 	}
 
-	/* fallback */
-	return checker.typeToString(type, undefined, compiler.TypeFormatFlags.NoTruncation)
+	/** A type inside a signature: a bare type parameter stays by name, bound by the signature. */
+	#typeParamText(t: ts.Type): string {
+		if (t.flags & this.compiler.TypeFlags.TypeParameter) return t.symbol.getName()
+		return this.asRef(t) ?? this.serialize(t)
+	}
 }
 
 /**
- * Converts absolute `import()` paths emitted by `typeToString` into
- * resolvable module specifiers:
- * - node_modules paths → bare package specifiers
- * - project-internal paths → relative from outputDir
+ * Does `type` contain `token` outside every bracket and string? Used to parenthesize only
+ * where precedence needs it.
  */
-function sanitizeImportPaths(str: string, outputDir?: string): string {
-	return str.replace(/import\("([^"]+)"\)/g, (_match, filePath: string) => {
-		const nmIdx = filePath.lastIndexOf("/node_modules/")
-		if (nmIdx !== -1) {
-			return `import("${filePath.slice(nmIdx + "/node_modules/".length)}")`
+function hasTopLevel(type: string, token: "|" | "&" | "=>"): boolean {
+	let depth = 0
+	let quote: string | null = null
+	for (let i = 0; i < type.length; i++) {
+		const c = type[i]
+		if (quote !== null) {
+			if (c === "\\") i++
+			else if (c === quote) quote = null
+			continue
+		}
+		if (c === '"' || c === "'" || c === "`") quote = c
+		else if (c === "(" || c === "{" || c === "[" || c === "<") depth++
+		else if (c === ")" || c === "}" || c === "]" || (c === ">" && type[i - 1] !== "=")) depth--
+		else if (depth === 0 && type.startsWith(token, i)) return true
+	}
+	return false
+}
+
+function arrayText(el: string): string {
+	return hasTopLevel(el, "|") || hasTopLevel(el, "&") || hasTopLevel(el, "=>") || el.startsWith("readonly ")
+		? `(${el})[]`
+		: `${el}[]`
+}
+
+function unionText(parts: string[]): string {
+	return [...new Set(parts)].map((p) => (hasTopLevel(p, "=>") ? `(${p})` : p)).join(" | ")
+}
+
+function intersectionText(parts: string[]): string {
+	return parts.map((p) => (hasTopLevel(p, "|") || hasTopLevel(p, "=>") ? `(${p})` : p)).join(" & ")
+}
+
+/* ---- module specifiers ---- */
+
+type PackageInfo = { dir: string; json: Record<string, unknown> }
+
+const packageCache = new Map<string, PackageInfo | null>()
+
+function nearestPackage(fromFile: string): PackageInfo | null {
+	let dir = dirname(fromFile)
+	const visited: string[] = []
+	let found: PackageInfo | null = null
+	let prev = ""
+	while (dir !== prev) {
+		const cached = packageCache.get(dir)
+		if (cached !== undefined) {
+			found = cached
+			break
+		}
+		visited.push(dir)
+		const file = join(dir, "package.json")
+		if (existsSync(file)) {
+			try {
+				const json = JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>
+				/* a package.json without a name (a "type": "module" marker) is not a package boundary */
+				if (typeof json.name === "string") {
+					found = { dir, json }
+					break
+				}
+			} catch {
+				/* unreadable — keep walking */
+			}
+		}
+		prev = dir
+		dir = dirname(dir)
+	}
+	for (const d of visited) packageCache.set(d, found)
+	return found
+}
+
+/** Every file an `exports` value can point at, with the subpath that names it. */
+function exportTargets(exports: unknown): Array<{ subpath: string; target: string }> {
+	const out: Array<{ subpath: string; target: string }> = []
+	const collect = (subpath: string, value: unknown): void => {
+		if (typeof value === "string") out.push({ subpath, target: value })
+		else if (Array.isArray(value)) for (const v of value) collect(subpath, v)
+		else if (value !== null && typeof value === "object") {
+			for (const v of Object.values(value as Record<string, unknown>)) collect(subpath, v)
 		}
-		if (!outputDir) return `import("${filePath}")`
-		let rel = relative(outputDir, filePath)
+	}
+	if (typeof exports === "string" || Array.isArray(exports)) collect(".", exports)
+	else if (exports !== null && typeof exports === "object") {
+		const entries = Object.entries(exports as Record<string, unknown>)
+		if (entries.length > 0 && entries.every(([k]) => !k.startsWith("."))) collect(".", exports)
+		else for (const [k, v] of entries) collect(k, v)
+	}
+	return out
+}
+
+function stripTypeExtension(path: string): string {
+	return path
+		.replace(/\.d\.[mc]?ts$/, "")
+		.replace(/\.[mc]?tsx?$/, "")
+		.replace(/\.[mc]?js$/, "")
+}
+
+/** `@types/foo` types the `foo` package; `@types/scope__name` types `@scope/name`. */
+function typedPackageName(name: string): string {
+	if (!name.startsWith("@types/")) return name
+	const bare = name.slice("@types/".length)
+	return bare.includes("__") ? `@${bare.replace("__", "/")}` : bare
+}
+
+/**
+ * The specifier a generated file should use to import `filePath`.
+ *
+ * A file of another package is named through that package — its `exports` subpath when one
+ * points at the file (any condition: `types`, `default`, or a source condition), its `types`
+ * entry, or (no `exports` map) its path without extension; an `@types` package by the package it
+ * types. A file of the output's own package is a relative path. Lib files never get here.
+ */
+function moduleSpecifier(filePath: string, outputDir: string | undefined): string {
+	const pkg = nearestPackage(filePath)
+	const ownPkg = outputDir ? nearestPackage(join(outputDir, "_")) : null
+	const relativeSpecifier = (): string => {
+		if (!outputDir) return filePath
+		let rel = relative(outputDir, filePath).split(sep).join("/")
 		if (!rel.startsWith(".")) rel = `./${rel}`
-		return `import("${rel}")`
+		return rel
+	}
+	if (!pkg || (ownPkg && pkg.dir === ownPkg.dir)) return relativeSpecifier()
+	const name = typedPackageName(String(pkg.json.name))
+	const rel = `./${relative(pkg.dir, filePath).split(sep).join("/")}`
+
+	if (pkg.json.exports !== undefined) {
+		const match = exportTargets(pkg.json.exports).find(
+			(e) => e.target === rel || stripTypeExtension(e.target) === stripTypeExtension(rel),
+		)
+		if (match) return match.subpath === "." ? name : `${name}/${match.subpath.replace(/^\.\//, "")}`
+		/* the package does not export this file — a path into it would not resolve */
+		return relativeSpecifier()
+	}
+	const typesEntry = pkg.json.types ?? pkg.json.typings
+	if (
+		typeof typesEntry === "string" &&
+		stripTypeExtension(`./${typesEntry.replace(/^\.\//, "")}`) === stripTypeExtension(rel)
+	) {
+		return name
+	}
+	const sub = stripTypeExtension(rel.slice(2)).replace(/\/index$/, "")
+	return sub === "index" || sub === "" ? name : `${name}/${sub}`
+}
+
+/**
+ * Rewrite absolute `import("…")` paths into resolvable module specifiers, and drop the
+ * `import()` around lib types (`Date`, `Promise`), which are global.
+ */
+function sanitizeImportPaths(str: string, outputDir?: string): string {
+	return str.replace(/import\("([^"]+)"\)\./g, (_match, filePath: string) => {
+		if (isLibFile(filePath)) return ""
+		return `import("${moduleSpecifier(filePath, outputDir)}").`
 	})
 }
 
 export type ExtractedChainTypes = {
 	base: ExtractedBaseCtx
-	/** per-route middleware additions keyed by "method /path" */
+	/** per-route middleware additions keyed by "method /full/path" (basePath included) */
 	routeMiddleware: Record<string, string>
 	/** structured per-property middleware data for sub-type dedup */
 	routeMiddlewareProps: Record<string, Array<{ name: string; opt: boolean; type: string }>>
@@ -495,9 +702,13 @@ const HTTP_METHODS = new Set(["all", "delete", "get", "head", "options", "patch"
 
 /**
  * Extracts base ctx and per-route middleware additions from sub-chains.
- * Traces HTTP method calls (`.get()`, `.post()`, etc.) back to their
- * Honey instance receiver, computes the ctx diff vs the base export,
- * and returns per-route additions keyed by "method /path".
+ *
+ * Every source file of the program is scanned for HTTP method calls (`.get()`, `.post()`, …)
+ * on a Honey instance. A route is keyed by its full path — the receiver's `$basePath` type
+ * joined with the literal path, exactly as the router registers it — so `v1.get("/items")`
+ * and `pub.get("/items")` never share an entry. A receiver whose base path is not a literal
+ * type cannot be keyed and is skipped: a route without an entry gets the base ctx, never
+ * another route's.
  */
 export async function extractChainTypes(options: {
 	entryPath: string
@@ -505,30 +716,8 @@ export async function extractChainTypes(options: {
 	outputDir?: string
 	tsconfigPath?: string
 }): Promise<ExtractedChainTypes> {
-	const { Project, ts } = await import("ts-morph")
-
-	const tsConfigFilePath = options.tsconfigPath ?? findTsConfig(options.entryPath)
-
-	const project = new Project({
-		skipAddingFilesFromTsConfig: true,
-		tsConfigFilePath,
-	})
-
-	project.addSourceFilesAtPaths(options.entryPath)
-	project.resolveSourceFileDependencies()
-
-	const sourceFile = project.getSourceFileOrThrow(options.entryPath)
-	const baseVarDecl = sourceFile.getVariableDeclaration(options.exportName)
-	if (!baseVarDecl) {
-		throw new Error(`Export "${options.exportName}" not found in ${options.entryPath}`)
-	}
-
-	function bridge<T>(value: unknown): T {
-		return value as T
-	}
-	const checker: ts.TypeChecker = bridge(project.getTypeChecker().compilerObject)
-	const baseNode: ts.Node = bridge(baseVarDecl.compilerNode)
-	const tsLib: typeof ts = bridge(ts)
+	const { appType, checker, compiler, node: baseNode, project } = await loadEntry(options)
+	const ser = new Serializer(checker, baseNode, compiler)
 
 	function getCtxType(tsType: ts.Type, locationNode?: ts.Node): ts.Type | null {
 		const sym = tsType.getProperty("$ctx")
@@ -536,131 +725,122 @@ export async function extractChainTypes(options: {
 		return checker.getTypeOfSymbolAtLocation(sym, locationNode ?? sym.valueDeclaration ?? baseNode)
 	}
 
+	function basePathOf(tsType: ts.Type, locationNode: ts.Node): string | null {
+		const sym = tsType.getProperty("$basePath")
+		if (!sym) return null
+		const t = checker.getTypeOfSymbolAtLocation(sym, locationNode)
+		return t.isStringLiteral() ? t.value : null
+	}
+
 	/* extract base ctx */
-	const baseType = bridge<ts.Type>(baseVarDecl.getType().compilerType)
 	let envType = "Record<string, unknown>"
-	const envSym = baseType.getProperty("$env")
-	if (envSym) {
-		envType = serialize(checker.getTypeOfSymbolAtLocation(envSym, baseNode), checker, baseNode, tsLib)
-	}
+	const envSym = appType.getProperty("$env")
+	if (envSym) envType = ser.serialize(checker.getTypeOfSymbolAtLocation(envSym, baseNode))
 
-	const baseCtxType = getCtxType(baseType)
+	const baseCtxType = getCtxType(appType, baseNode)
 	if (!baseCtxType) {
 		throw new Error(`Export "${options.exportName}" has no $ctx — not a Honey instance`)
 	}
-	const baseMwProps = extractMiddlewareProps(baseCtxType, checker, baseNode, tsLib)
-	const baseMiddlewareType =
-		baseMwProps.length === 0
-			? null
-			: `{ ${baseMwProps.map((p) => `${p.name}${p.opt ? "?" : ""}: ${p.type}`).join("; ")} }`
+	const baseMwProps = extractMiddlewareProps(baseCtxType, ser)
+	const baseMiddlewareType = propsType(baseMwProps)
 
 	/* build name→type map for reusing base type references in route middleware */
 	const basePropTypeByName = new Map<string, string>()
-	for (const p of baseMwProps) {
-		basePropTypeByName.set(p.name, p.type)
-	}
+	for (const p of baseMwProps) basePropTypeByName.set(p.name, p.type)
 
 	/* collect base middleware property names for diffing */
 	const baseMwPropNames = new Set<string>()
 	for (const p of baseCtxType.getProperties()) {
 		const name = p.getName()
-		if (!HONEY_CTX_PROPS.has(name) && !name.startsWith("_")) {
-			baseMwPropNames.add(name)
-		}
+		if (!HONEY_CTX_PROPS.has(name) && !name.startsWith("_")) baseMwPropNames.add(name)
 	}
 
 	const sanitize = (s: string) => sanitizeImportPaths(s, options.outputDir)
 
-	/* scan for route-defining calls: <expr>.<httpMethod>(<pathLiteral>) */
-	const routeMiddleware: Record<string, string> = {}
-	const routeMiddlewareProps: Record<string, Array<{ name: string; opt: boolean; type: string }>> = {}
-	const compilerSourceFile: ts.SourceFile = bridge(sourceFile.compilerNode)
+	const routeMiddleware: Record<string, string> = Object.create(null)
+	const routeMiddlewareProps: Record<string, Array<{ name: string; opt: boolean; type: string }>> = Object.create(null)
 
 	function visitNode(node: ts.Node): void {
-		if (tsLib.isCallExpression(node) && tsLib.isPropertyAccessExpression(node.expression)) {
+		if (compiler.isCallExpression(node) && compiler.isPropertyAccessExpression(node.expression)) {
 			const methodName = node.expression.name.text
-			if (HTTP_METHODS.has(methodName) && node.arguments.length > 0) {
-				const pathArg = node.arguments[0]
-				if (tsLib.isStringLiteral(pathArg)) {
-					const path = pathArg.text
-					/* get the type of the receiver (the expression before .get/.post/etc.) */
-					const receiverExpr = node.expression.expression
-					const receiverType = checker.getTypeAtLocation(receiverExpr)
-					const ctxType = getCtxType(receiverType, receiverExpr)
-
-					if (ctxType) {
-						/* extract extra middleware props by iterating intersection MEMBERS individually.
-						 * This preserves source-level declarations (e.g. ShorthandPropertyAssignment)
-						 * that get lost when extracting from the flattened intersection. */
-						const extraEntries: MwPropEntry[] = []
-						const dupeNames = new Set<string>()
-						const members = ctxType.isIntersection() ? (ctxType as ts.IntersectionType).types : [ctxType]
-						for (const member of members) {
-							const memberProps = extractMiddlewareProps(member, checker, baseNode, tsLib)
-							for (const rp of memberProps) {
-								if (baseMwPropNames.has(rp.name)) continue
-								if (extraEntries.some((e) => e.name === rp.name)) {
-									dupeNames.add(rp.name)
-									continue
-								}
-								extraEntries.push(rp)
-							}
-						}
-						/* for properties that appeared in multiple intersection members
-						 * (e.g. auth narrowed by a later middleware), resolve from the
-						 * flattened intersection so TypeScript computes the correct
-						 * intersected type instead of using the first member's type */
-						for (const dupeName of dupeNames) {
-							const sym = ctxType.getProperty(dupeName)
-							if (!sym) continue
-							const t = checker.getTypeOfSymbolAtLocation(sym, sym.valueDeclaration ?? baseNode)
-							const typeStr = serializeAsRef(t, checker, baseNode, tsLib) ?? serialize(t, checker, baseNode, tsLib)
-							const idx = extraEntries.findIndex((e) => e.name === dupeName)
-							if (idx !== -1) {
-								extraEntries[idx] = { ...extraEntries[idx], type: typeStr }
-							}
-						}
+			const pathArg = node.arguments[0]
+			if (HTTP_METHODS.has(methodName) && pathArg && compiler.isStringLiteralLike(pathArg)) {
+				const receiverExpr = node.expression.expression
+				const receiverType = checker.getTypeAtLocation(receiverExpr)
+				const ctxType = getCtxType(receiverType, receiverExpr)
+				const basePath = ctxType ? basePathOf(receiverType, receiverExpr) : null
+				if (ctxType && basePath !== null) {
+					for (const variant of fullPaths(basePath, pathArg.text)) recordRoute(`${methodName} ${variant}`, ctxType)
+				}
+			}
+		}
+		compiler.forEachChild(node, visitNode)
+	}
 
-						if (extraEntries.length > 0) {
-							/* reuse compact base type references when the route has the same property
-							 * (e.g. shardDb: ShardDb from base → reuse import ref instead of structural expansion) */
-							const entries = extraEntries.map((e) => {
-								const baseRef = basePropTypeByName.get(e.name)
-								if (baseRef && baseRef.length < e.type.length) {
-									return { ...e, type: baseRef }
-								}
-								return e
-							})
-
-							const key = `${methodName} ${path}`
-							routeMiddleware[key] = sanitize(
-								`{ ${entries.map((e) => `${e.name}${e.opt ? "?" : ""}: ${e.type}`).join("; ")} }`,
-							)
-							routeMiddlewareProps[key] = entries.map((e) => ({
-								name: e.name,
-								opt: e.opt,
-								type: sanitize(e.type),
-							}))
-						}
-					}
+	/** The paths the router serves for this registration — an optional last param yields two. */
+	function fullPaths(basePath: string, path: string): string[] {
+		try {
+			return expandOptional(parsePattern(joinPatterns(basePath, path))).map((segments) => canonical(segments))
+		} catch {
+			/* a pattern the router would refuse registers nothing */
+			return []
+		}
+	}
+
+	function recordRoute(key: string, ctxType: ts.Type): void {
+		/* extract extra middleware props by iterating intersection MEMBERS individually.
+		 * This preserves source-level declarations (e.g. ShorthandPropertyAssignment)
+		 * that get lost when extracting from the flattened intersection. */
+		const extraEntries: MwPropEntry[] = []
+		const dupeNames = new Set<string>()
+		const members = ctxType.isIntersection() ? (ctxType as ts.IntersectionType).types : [ctxType]
+		for (const member of members) {
+			for (const rp of extractMiddlewareProps(member, ser)) {
+				if (baseMwPropNames.has(rp.name)) continue
+				if (extraEntries.some((e) => e.name === rp.name)) {
+					dupeNames.add(rp.name)
+					continue
 				}
+				extraEntries.push(rp)
 			}
 		}
+		/* a property in several intersection members (e.g. auth narrowed by a later middleware)
+		 * is read from the flattened intersection, so TypeScript computes the intersected type */
+		for (const dupeName of dupeNames) {
+			const sym = ctxType.getProperty(dupeName)
+			if (!sym) continue
+			const t = checker.getTypeOfSymbolAtLocation(sym, sym.valueDeclaration ?? baseNode)
+			const typeStr = ser.asRef(t) ?? ser.serialize(t)
+			const idx = extraEntries.findIndex((e) => e.name === dupeName)
+			if (idx !== -1) extraEntries[idx] = { ...extraEntries[idx], type: typeStr }
+		}
+		if (extraEntries.length === 0) return
 
-		tsLib.forEachChild(node, visitNode)
+		/* reuse compact base type references when the route has the same property
+		 * (e.g. shardDb: ShardDb from base → reuse import ref instead of structural expansion) */
+		const entries = extraEntries.map((e) => {
+			const baseRef = basePropTypeByName.get(e.name)
+			return baseRef && baseRef.length < e.type.length ? { ...e, type: baseRef } : e
+		})
+		routeMiddleware[key] = sanitize(propsType(entries) ?? "{}")
+		routeMiddlewareProps[key] = entries.map((e) => ({ name: e.name, opt: e.opt, type: sanitize(e.type) }))
 	}
 
-	visitNode(compilerSourceFile)
+	/* every source file of the program, not only the entry: routes are often registered in
+	   modules the entry imports */
+	for (const sf of project.getSourceFiles()) {
+		const compilerSf: ts.SourceFile = bridge(sf.compilerNode)
+		if (compilerSf.isDeclarationFile) continue
+		if (/[\\/]node_modules[\\/]/.test(compilerSf.fileName)) continue
+		visitNode(compilerSf)
+	}
 
 	/* extract $taps */
 	let tapsType: string | null = null
-	const tapsSym = baseType.getProperty("$taps")
+	const tapsSym = appType.getProperty("$taps")
 	if (tapsSym) {
-		const tapsT = checker.getTypeOfSymbolAtLocation(tapsSym, baseNode)
-		const tapsStr = serialize(tapsT, checker, baseNode, tsLib)
-		if (tapsStr !== "{}" && tapsStr !== "Record<string, unknown>") {
-			tapsType = tapsStr
-		}
+		const tapsStr = ser.serialize(checker.getTypeOfSymbolAtLocation(tapsSym, baseNode))
+		if (tapsStr !== "{}" && tapsStr !== "Record<string, unknown>") tapsType = tapsStr
 	}
 
 	return {
@@ -669,7 +849,7 @@ export async function extractChainTypes(options: {
 			middlewareType: baseMiddlewareType ? sanitize(baseMiddlewareType) : null,
 			tapsType: tapsType ? sanitize(tapsType) : null,
 		},
-		routeMiddleware,
-		routeMiddlewareProps,
+		routeMiddleware: { ...routeMiddleware },
+		routeMiddlewareProps: { ...routeMiddlewareProps },
 	}
 }