tsrx-typegen 0.2.2 → 0.3.1

package/README.md

@@ -1,55 +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.
-
-```sh
-pnpm exec tsrx-typegen --target octane
-```
+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. Case-only source renames replace the prior
-manifest-owned declaration, including on case-insensitive filesystems; manual
-declarations remain protected.
-
-```sh
-pnpm exec tsrx-typegen --target octane --check
-```
-
-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/notes/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
 {
@@ -61,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"
 				}
 			}
@@ -70,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:
 
@@ -86,30 +87,50 @@ manifest; check mode detects edits to either the source mapping or generated
 copy. Override declarations must use publishable module specifiers and may not
 reference `.tsrx` files.
 
-```sh
-pnpm exec tsrx-typegen --target octane --check
-```
-
 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
-// Plain TypeScript consumer of the package whose exports are configured above.
 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:
 
-// Button is a component exported by your library's src/index.ts.
-export { Button }
+```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
 {
@@ -123,17 +144,12 @@ 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.
 
-```sh
-pnpm exec tsrx-typegen --pack-check
-pnpm exec tsrx-typegen --pack-check --target octane
-```
-
 A target with `"emit": false` exists only to drive packed-package
 verification. Packages whose declarations are handwritten or produced by
 another tool declare one so `--pack-check` skips generation and freshness
@@ -153,7 +169,7 @@ for source-published packages, the `.ts` source itself.
 			"entrypoints": {
 				".": {
 					"source": "src/index.ts",
-					"runtime": "./dist/index.js",
+					"runtime": "./src/index.ts",
 					"types": "./types/index.d.ts"
 				}
 			}
@@ -168,8 +184,7 @@ Run the same gate from `prepack` so `pnpm pack` and publication share it:
 {
 	"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"
 	}
 }
 ```
@@ -182,9 +197,11 @@ that declaration gate fails.
 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,

package/bin/tsrx-typegen.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// Prefer the emitted dist/ build (published tarballs); fall back to src/ so
+// in-repo typegen needs no build step (Node ≥22.18 strips types).
+import { existsSync } from 'node:fs'
+
+const dist = new URL('../dist/cli.js', import.meta.url)
+if (existsSync(dist)) {
+	await import(dist.href)
+} else {
+	await import(new URL('../src/cli.ts', import.meta.url).href)
+}