tsrx-typegen 0.2.1 → 0.3.0

package/README.md

@@ -1,45 +1,21 @@
 # tsrx-typegen
 
-Generate declaration files for packages that export `.tsrx` modules. The
-command uses the consuming package's TypeScript and tsrx compiler, then maps
-source-extension imports in the emitted declarations to JavaScript module
-specifiers.
+Generate `.d.ts` declaration files for packages that export `.tsrx` modules.
+Use it when publishing an Octane/tsrx component package: it runs the consuming
+package's own TypeScript and tsrx compiler, then rewrites source-extension
+imports in the emitted declarations to JavaScript module specifiers.
 
 Install `tsrx-typegen` as a development tool alongside `typescript` and
-`@tsrx/typescript-plugin`. Each target in `tsrx-typegen.json` names its
-renderer, project config, declaration output directory, and public subpaths.
-The project config selects source variants and enables `declaration`,
-`emitDeclarationOnly`, and `noEmit: false`. The target's `renderer` is checked
-against `compilerOptions.jsxImportSource` when TypeScript sets it; the project
-config continues to select the actual tsrx compiler and platform.
+`@tsrx/typescript-plugin`, then run it against a named target:
 
 ```sh
-pnpm exec tsrx-typegen --target octane
-pnpm exec tsrx-typegen --project tsconfig.types.json --check
-pnpm exec tsrx-typegen --pack-check
+pnpm exec tsrx-typegen --target octane          # generate declarations
+pnpm exec tsrx-typegen --target octane --check  # verify output is fresh
+pnpm exec tsrx-typegen --pack-check             # validate the packed tarball
 ```
 
-Generation writes only TypeScript declaration files under the config's `outDir` and records
-which files it owns in `.tsrx-typegen-manifest.json`. Check mode emits to a
-temporary directory and compares the result with those owned files. It reports
-missing or stale output, unresolved `.tsrx` references, and code export paths
-without declaration targets. It refuses to overwrite an unmanaged declaration
-and removes stale files only when the manifest says it owns them. Same-name
-sources such as `Button.ts` and `Button.tsrx` need separate target configs or an
-explicit declaration override.
-
-Treat the output directory, including its ownership manifest, as generated
-build artifacts: ignore it in Git, formatting, and linting. Keep handwritten
-declarations and override sources outside that directory. Include the output
-directory in the package's `files` list so ignored declarations still ship in
-the tarball. Generate before local consumer typechecks, and regenerate in
-`prepack` before validating the package. Workspaces that resolve generated
-types directly also need generation during setup and refreshes during
-development; this repository's workflow is documented in
-[Develop against generated declarations](../../docs/toolchain-notes.md#develop-against-generated-declarations).
-
-`--project` selects the target whose project path matches. Use `--target` to
-select a named target directly. A target can look like this:
+Each target in `tsrx-typegen.json` names its renderer, project config,
+declaration output directory, and public subpaths:
 
 ```json
 {
@@ -51,7 +27,7 @@ select a named target directly. A target can look like this:
 			"entrypoints": {
 				".": {
 					"source": "src/index.ts",
-					"runtime": "./dist/index.js",
+					"runtime": "./src/index.ts",
 					"types": "./types/generated/index.d.ts"
 				}
 			}
@@ -60,6 +36,41 @@ select a named target directly. A target can look like this:
 }
 ```
 
+The project config selects source variants and enables `declaration`,
+`emitDeclarationOnly`, and `noEmit: false`. The target's `renderer` is checked
+against `compilerOptions.jsxImportSource` when TypeScript sets it; the project
+config continues to select the actual tsrx compiler and platform. `--project`
+selects the target whose project path matches; `--target` selects a named
+target directly.
+
+## What generation writes and checks
+
+Generation writes only TypeScript declaration files under the config's
+`outDir` and records which files it owns in `.tsrx-typegen-manifest.json`.
+Declaration inputs included by the project under `rootDir` are copied beside
+emitted declarations, with the same import rewriting and freshness checks.
+Check mode emits to a temporary directory and compares the result with those
+owned files. It reports missing or stale output, unresolved `.tsrx`
+references, and code export paths without declaration targets. It refuses to
+overwrite an unmanaged declaration and removes stale files only when the
+manifest says it owns them. Same-name sources such as `Button.ts` and
+`Button.tsrx` need separate target configs or an explicit declaration
+override. Case-only source renames replace the prior manifest-owned
+declaration, including on case-insensitive filesystems; manual declarations
+remain protected.
+
+Treat the output directory, including its ownership manifest, as generated
+build artifacts: ignore it in Git, formatting, and linting. Keep handwritten
+declarations and override sources outside that directory. Include the output
+directory in the package's `files` list so ignored declarations still ship in
+the tarball. Generate before local consumer typechecks, and regenerate in
+`prepack` before validating the package. Workspaces that resolve generated
+types directly also need generation during setup and refreshes during
+development; this repository's workflow is documented in
+[Develop against generated declarations](../../.agents/docs/notes/toolchain-notes.md#develop-against-generated-declarations).
+
+## Overrides and import rewriting
+
 Keep exceptional signatures in handwritten declaration sources outside the
 generated directory, then map their generated output path explicitly:
 
@@ -78,16 +89,54 @@ reference `.tsrx` files.
 
 Relative imports between generated declarations receive runtime extensions
 from the source map, including extensionless imports. This supports NodeNext
-consumers as well as bundler resolution without requiring `allowArbitraryExtensions`.
+consumers as well as bundler resolution without requiring
+`allowArbitraryExtensions`. A plain TypeScript consumer then imports the
+package normally:
+
+```ts
+import { Button } from 'my-component-library'
+```
+
+The `.js` specifiers inside declarations resolve to sibling `.d.ts` files
+through TypeScript's extension substitution. They do not require a JavaScript
+package build. Keep runtime exports pointed at authored source and type exports
+pointed at declarations:
+
+```json
+{
+	"exports": {
+		".": {
+			"types": "./types/generated/index.d.ts",
+			"default": "./src/index.ts"
+		},
+		"./*": {
+			"types": "./types/generated/*.d.ts",
+			"default": "./src/*"
+		}
+	},
+	"files": ["src", "types"]
+}
+```
+
+Keep wildcard runtime targets extensionless so the app bundler can select
+`.web.ts`, `.ios.ts`, or `.web.tsrx` siblings. The declaration wildcard uses
+the same module stem, and the pack check verifies each source variant has its
+matching declaration.
 
 Use separate target records and project configs when public signatures differ.
-Each config must select the same source variants as its runtime build.
+Each config must select the source variants exposed by its runtime exports.
 `runtime` records the published runtime path or condition map, while `types`
-records the declaration path. The CLI does not edit `package.json`; export maps
-remain package-owned. The default source-extension mapping is `.tsrx`, `.tsx`,
-and `.ts` to `.js`, with `.mts` to `.mjs` and `.cts` to `.cjs`. Packages with
-another runtime layout can override these mappings in `sourceExtensions` at
-the target or root level.
+records the declaration path. The CLI does not edit `package.json`; export
+maps remain package-owned. The default source-extension mapping is `.tsrx`,
+`.tsx`, and `.ts` to `.js`, with `.mts` to `.mjs` and `.cts` to `.cjs`.
+Packages with another runtime layout can override these mappings in
+`sourceExtensions` at the target or root level:
+
+```json
+{
+	"sourceExtensions": { ".tsrx": ".js", ".mts": ".mjs", ".cts": ".cjs" }
+}
+```
 
 ## Publish checks
 
@@ -95,8 +144,8 @@ Use `--pack-check` before publishing. It checks every configured target unless
 `--target` narrows the selection, packs a temporary tarball with lifecycle
 scripts disabled, and verifies that package and `publishConfig` export paths
 exist in the tarball. It also compares runtime and declaration value exports
-and checks that relative declaration references resolve inside the package and
-bare package imports are declared dependencies or peers. The command needs
+and checks that relative declaration references resolve to declarations inside
+the package and bare package imports are declared dependencies or peers. The command needs
 `pnpm` and the system `tar` utility. It checks package structure; keep a plain
 TypeScript consumer test for the module-resolution modes and public prop
 contracts your package supports.
@@ -109,14 +158,33 @@ selected for generation; a plain `--target` run against them fails. Every code
 export path still needs a `types` condition — pointing at a `.d.ts` file or,
 for source-published packages, the `.ts` source itself.
 
+```json
+{
+	"targets": {
+		"manual": {
+			"emit": false,
+			"renderer": "octane",
+			"project": "tsconfig.types.json",
+			"outDir": "types/generated",
+			"entrypoints": {
+				".": {
+					"source": "src/index.ts",
+					"runtime": "./src/index.ts",
+					"types": "./types/index.d.ts"
+				}
+			}
+		}
+	}
+}
+```
+
 Run the same gate from `prepack` so `pnpm pack` and publication share it:
 
 ```json
 {
 	"scripts": {
 		"typegen": "tsrx-typegen --target octane",
-		"build": "vite build && pnpm typegen",
-		"prepack": "pnpm build && tsrx-typegen --pack-check"
+		"prepack": "pnpm typegen && tsrx-typegen --pack-check"
 	}
 }
 ```
@@ -125,9 +193,15 @@ When run from a package root that has `tsrx-typegen.json`, `xplat doctor`
 delegates to `tsrx-typegen --pack-check` and returns a failing exit status if
 that declaration gate fails.
 
+```sh
+pnpm exec xplat doctor
+```
+
+## Backend and inference
+
 The first supported backend is the classic `tsrx-tsc` path with TypeScript
-5.9.x. TypeScript 7 content-mapper output needs upstream declaration naming and
-specifier support before it can replace this backend. Generation rejects
+5.9.x. TypeScript 7 content-mapper output needs upstream declaration naming
+and specifier support before it can replace this backend. Generation rejects
 compiler errors; editor-only partial transforms are not used.
 
 This tool preserves TypeScript's declaration inference. Keep exported helpers,
@@ -137,3 +211,10 @@ packed package with a plain TypeScript consumer; generated declarations may
 still express a different contract even when their paths and exports are
 valid. Use explicit overrides for exceptional signatures and keep those
 overrides outside the generated output directory.
+
+```ts
+// Source of your component package; use an explicit return type for helpers.
+export function formatCount(count: number): string {
+	return `${count} packed`
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tsrx-typegen",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Generate consumer-ready TypeScript declarations for TSRX libraries",
   "keywords": [
     "build-tool",

package/src/cli.mjs

@@ -529,7 +529,7 @@ function rewriteDeclaration(ts, path, outputDir, extensions, generatedFiles, run
 
 			const declaration = relative(outputDir, target)
 			const runtimeExtension = runtimeByDeclaration.get(declaration) ?? '.js'
-			const isIndex = /[\\/]index\.d\.[cm]?ts$/.test(target)
+			const isIndex = dirname(target) === targetStem
 			const baseSpecifier = specifier.endsWith('/') ? specifier.slice(0, -1) : specifier
 			replacement = isIndex
 				? `${baseSpecifier}/index${runtimeExtension}`
@@ -608,19 +608,42 @@ function pathInside(root, file) {
 	)
 }
 
-function writeOutput(outputDir, generated, oldFiles, overrideFiles) {
-	for (const file of generated.keys()) {
-		if (oldFiles?.has(file) || overrideFiles.has(file)) {
-			continue
-		}
+function existingOutputPath(outputDir, file) {
+	let current = outputDir
+	const actualParts = []
 
+	for (const part of normalize(file).split(sep)) {
+		let entries
 		try {
-			statSync(join(outputDir, file))
-			throw new Error(`refusing to overwrite unmanaged declaration: ${file}`)
+			entries = readdirSync(current)
 		} catch (error) {
-			if (error.code !== 'ENOENT') {
-				throw error
+			if (error.code === 'ENOENT') {
+				return null
 			}
+
+			throw error
+		}
+
+		const actual = entries.includes(part)
+			? part
+			: entries.find((entry) => entry.toLowerCase() === part.toLowerCase())
+
+		if (!actual) {
+			return null
+		}
+
+		actualParts.push(actual)
+		current = join(current, actual)
+	}
+
+	return actualParts.join(sep)
+}
+
+function writeOutput(outputDir, generated, oldFiles, overrideFiles) {
+	for (const file of generated.keys()) {
+		const existing = existingOutputPath(outputDir, file)
+		if (existing && !oldFiles?.has(existing) && !overrideFiles.has(existing)) {
+			throw new Error(`refusing to overwrite unmanaged declaration: ${file}`)
 		}
 	}
 
@@ -723,8 +746,8 @@ function verifyPublicTypes(projectRoot, generated, outDir, target, sourceOutputs
 	if (target && exportsMap && typeof exportsMap === 'object') {
 		const configuredSubpaths = new Set(Object.keys(target.entrypoints))
 		for (const [subpath, mapping] of Object.entries(exportsMap)) {
-			const runtimeTargets = stringsIn(mapping).filter((entry) =>
-				/\.(?:[cm]?[jt]sx?|tsrx)$/.test(entry),
+			const runtimeTargets = stringsIn(mapping).filter(
+				(entry) => !extname(entry) || /\.(?:[cm]?[jt]sx?|tsrx)$/.test(entry),
 			)
 
 			if (runtimeTargets.length && !configuredSubpaths.has(subpath)) {
@@ -743,7 +766,9 @@ function verifyPublicTypes(projectRoot, generated, outDir, target, sourceOutputs
 			}
 
 			const source = resolve(projectRoot, entry.source)
-			if (![...sourceOutputs.values()].includes(source)) {
+			// TypeScript emits forward-slash paths even on Windows; resolve both
+			// sides before comparing them with the platform-native entry path.
+			if (![...sourceOutputs.values()].some((included) => resolve(included) === source)) {
 				failures.push(
 					`${subpath} source is not included by its TypeScript project: ${entry.source}`,
 				)
@@ -769,8 +794,8 @@ function verifyPublicTypes(projectRoot, generated, outDir, target, sourceOutputs
 
 	if (exportsMap && typeof exportsMap === 'object') {
 		for (const [subpath, mapping] of Object.entries(exportsMap)) {
-			const runtimeTargets = stringsIn(mapping).filter((target) =>
-				/\.(?:[cm]?[jt]sx?|tsrx)$/.test(target),
+			const runtimeTargets = stringsIn(mapping).filter(
+				(target) => !extname(target) || /\.(?:[cm]?[jt]sx?|tsrx)$/.test(target),
 			)
 
 			if (!runtimeTargets.length) {
@@ -900,6 +925,23 @@ function runTarget(projectRoot, args) {
 			return false
 		}
 
+		// TypeScript does not emit declaration inputs. Preserve included, local
+		// declarations beside emitted modules so their references remain closed.
+		for (const source of fileNames) {
+			if (!/\.d\.[cm]?ts$/.test(source) || !pathInside(rootDir, source)) {
+				continue
+			}
+
+			const declaration = relative(rootDir, source)
+			if (sourceOutputs.has(declaration)) {
+				continue
+			}
+
+			const output = join(outputDir, declaration)
+			mkdirSync(dirname(output), { recursive: true })
+			writeFileSync(output, readFileSync(source))
+		}
+
 		const generated = normalizeOutput(ts, outputDir, sourceExtensions, runtimeByDeclaration)
 		const managedOverrides = applyOverrides(ts, projectRoot, outDir, generated, overrides)
 		verifySourceDeclarations(generated, sourceOutputs)

package/src/pack-check.mjs

@@ -50,7 +50,7 @@ const stringsIn = (value) => {
 }
 
 const codeTarget = (target) =>
-	/\.(?:[cm]?[jt]sx?|tsrx)$/.test(target) && !/\.d\.[cm]?ts$/.test(target)
+	(!extname(target) || /\.(?:[cm]?[jt]sx?|tsrx)$/.test(target)) && !/\.d\.[cm]?ts$/.test(target)
 
 function exportBranches(exportsMap, fallbackTypes = []) {
 	const branches = []
@@ -58,7 +58,11 @@ function exportBranches(exportsMap, fallbackTypes = []) {
 		const visit = (value, inheritedTypes) => {
 			if (typeof value === 'string') {
 				if (codeTarget(value)) {
-					branches.push({ subpath, runtime: value, types: inheritedTypes })
+					branches.push({
+						subpath,
+						runtime: value,
+						types: inheritedTypes.length ? inheritedTypes : fallbackTypes,
+					})
 				}
 
 				return
@@ -68,15 +72,20 @@ function exportBranches(exportsMap, fallbackTypes = []) {
 				return
 			}
 
-			const types = Object.hasOwn(value, 'types') ? stringsIn(value.types) : inheritedTypes
+			// An earlier condition cannot use a later sibling's type fallback.
+			let types = inheritedTypes
 			for (const [condition, child] of Object.entries(value)) {
-				if (condition !== 'types') {
+				if (condition === 'types') {
+					if (!types.length) {
+						types = stringsIn(child)
+					}
+				} else {
 					visit(child, types)
 				}
 			}
 		}
 
-		visit(mapping, fallbackTypes)
+		visit(mapping, [])
 	}
 
 	return branches
@@ -104,11 +113,12 @@ function packageFiles(root) {
 }
 
 function expandTarget(target, files, packageRoot) {
-	if (!target.includes('*')) {
+	const extensionless = !extname(target)
+	if (!target.includes('*') && !extensionless) {
 		return [{ path: target, capture: undefined }]
 	}
 
-	if ((target.match(/\*/g) ?? []).length !== 1) {
+	if ((target.match(/\*/g) ?? []).length > 1) {
 		throw new Error(`packed export target uses more than one wildcard: ${target}`)
 	}
 
@@ -118,19 +128,31 @@ function expandTarget(target, files, packageRoot) {
 
 	const pattern = target.slice(2)
 	const marker = pattern.indexOf('*')
-	const prefix = pattern.slice(0, marker)
-	const suffix = pattern.slice(marker + 1)
+	const prefix = marker === -1 ? pattern : pattern.slice(0, marker)
+	const suffix = marker === -1 ? '' : pattern.slice(marker + 1)
 	const matches = files.flatMap((file) => {
 		const path = relative(packageRoot, file).replaceAll('\\', '/')
+		// Extensionless source exports let the app choose platform siblings.
+		// Their wildcard captures are module stems, not source extensions.
+		if (!codeTarget(path) || (extensionless && !extname(path))) {
+			return []
+		}
+
+		const matchedPath = extensionless ? path.slice(0, -extname(path).length) : path
 		if (
-			!path.startsWith(prefix) ||
-			!path.endsWith(suffix) ||
-			path.length < prefix.length + suffix.length
+			!matchedPath.startsWith(prefix) ||
+			!matchedPath.endsWith(suffix) ||
+			matchedPath.length < prefix.length + suffix.length ||
+			(marker === -1 && matchedPath !== pattern)
 		) {
 			return []
 		}
 
-		const capture = path.slice(prefix.length, path.length - suffix.length)
+		const capture =
+			marker === -1
+				? undefined
+				: matchedPath.slice(prefix.length, matchedPath.length - suffix.length)
+
 		return [{ path: `./${path}`, capture }]
 	})
 
@@ -163,13 +185,11 @@ function packedPath(packageRoot, target) {
 function sourceFile(ts, file) {
 	const extension = extname(file).toLowerCase()
 	const scriptKind =
-		extension === '.tsx'
+		extension === '.tsx' || extension === '.tsrx'
 			? ts.ScriptKind.TSX
 			: extension === '.jsx'
 				? ts.ScriptKind.JSX
-				: extension === '.tsrx'
-					? ts.ScriptKind.Deferred
-					: ts.ScriptKind.TS
+				: ts.ScriptKind.TS
 
 	return ts.createSourceFile(
 		file,
@@ -337,7 +357,21 @@ function compilerExports(ts, program, file, cache = new Map(), pending = new Set
 	// Subtract names whose only export edges are type-only.
 	const typeOnly = new Set()
 	for (const statement of source.statements) {
-		if (!ts.isExportDeclaration(statement) || !statement.isTypeOnly) {
+		if (!ts.isExportDeclaration(statement)) {
+			continue
+		}
+
+		if (statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+			for (const element of statement.exportClause.elements) {
+				if (statement.isTypeOnly || element.isTypeOnly) {
+					typeOnly.add(element.name.text)
+				}
+			}
+
+			continue
+		}
+
+		if (!statement.isTypeOnly) {
 			continue
 		}
 
@@ -392,6 +426,20 @@ function moduleResolutionOptions(ts) {
 		allowImportingTsExtensions: true,
 		module: ts.ModuleKind.NodeNext,
 		moduleResolution: ts.ModuleResolutionKind.NodeNext,
+		// Same precedence as repository typecheck/typegen programs
+		// (packages/cli tsconfig-envs.mjs PLATFORM_MODULE_SUFFIXES):
+		// extensionless first, then every platform suffix.
+		moduleSuffixes: [
+			'',
+			'.web',
+			'.ios',
+			'.android',
+			'.mobile',
+			'.native',
+			'.macos',
+			'.linux',
+			'.windows',
+		],
 		noEmit: true,
 		skipLibCheck: true,
 		target: ts.ScriptTarget.Latest,
@@ -421,6 +469,10 @@ function verifyDeclarationClosure(ts, packageRoot, files, manifest, failures) {
 					)
 				} else if (!pathInside(packageRoot, resolve(resolved.resolvedFileName))) {
 					failures.push(`${relative(packageRoot, file)} resolves ${specifier} outside the package`)
+				} else if (!/\.d\.[cm]?ts$/.test(resolved.resolvedFileName)) {
+					failures.push(
+						`${relative(packageRoot, file)} resolves ${specifier} to implementation source; publish its declaration`,
+					)
 				}
 
 				continue
@@ -599,8 +651,6 @@ export function checkPackedPackage(projectRoot, ts) {
 	mkdirSync(packOutput)
 	mkdirSync(extractedRoot)
 	try {
-		verifyPackedPackage(ts, projectRoot)
-		console.log('tsrx-typegen: workspace exports and declaration graph are valid')
 		const packed = spawnSync(
 			'pnpm',
 			['--config.ignore-scripts=true', 'pack', '--pack-destination', packOutput],
@@ -654,7 +704,7 @@ export function checkPackedPackage(projectRoot, ts) {
 		}
 
 		verifyPackedPackage(ts, join(extractedRoot, 'package'))
-		console.log('tsrx-typegen: packed runtime exports and declaration graph are valid')
+		console.log('tsrx-typegen: packed exports and declaration graph are valid')
 	} finally {
 		rmSync(temporary, { recursive: true, force: true })
 	}