tsrx-typegen 0.0.0-nightly.g2e22171

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alec Larson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# tsrx-typegen
+
+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`, then run it against a named target:
+
+```sh
+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
+```
+
+Each target in `tsrx-typegen.json` names its renderer, project config,
+declaration output directory, and public subpaths:
+
+```json
+{
+	"targets": {
+		"octane": {
+			"renderer": "octane",
+			"project": "tsconfig.types.json",
+			"outDir": "types/generated",
+			"entrypoints": {
+				".": {
+					"source": "src/index.ts",
+					"runtime": "./src/index.ts",
+					"types": "./types/generated/index.d.ts"
+				}
+			}
+		}
+	}
+}
+```
+
+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:
+
+```json
+{
+	"overrides": {
+		"Button.d.ts": "types/overrides/Button.d.ts"
+	}
+}
+```
+
+The override source is copied to the generated output and tracked by the
+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.
+
+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`. 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 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:
+
+```json
+{
+	"sourceExtensions": { ".tsrx": ".js", ".mts": ".mjs", ".cts": ".cjs" }
+}
+```
+
+## Publish checks
+
+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 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.
+
+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
+checks for it and only validates the packed package. Such targets cannot be
+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",
+		"prepack": "pnpm typegen && tsrx-typegen --pack-check"
+	}
+}
+```
+
+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
+compiler errors; editor-only partial transforms are not used.
+
+This tool preserves TypeScript's declaration inference. Keep exported helpers,
+generic signatures, overloads, and compound members explicit in source when
+inference does not preserve the intended package contract. Always check the
+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

@@ -0,0 +1,35 @@
+{
+  "name": "tsrx-typegen",
+  "version": "0.0.0-nightly.g2e22171",
+  "description": "Generate consumer-ready TypeScript declarations for TSRX libraries",
+  "keywords": [
+    "build-tool",
+    "codegen",
+    "declarations",
+    "dts",
+    "tsrx",
+    "typegen",
+    "typescript"
+  ],
+  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/tsrx-typegen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/octane-xplat/octane-xplat",
+    "directory": "packages/tsrx-typegen"
+  },
+  "bin": {
+    "tsrx-typegen": "./src/cli.mjs"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "peerDependencies": {
+    "@tsrx/typescript-plugin": ">=0.4.11 <1",
+    "typescript": ">=5.9.3 <6"
+  },
+  "scripts": {
+    "test": "node tests/pack-check.mjs && node tests/packed-consumer.mjs"
+  }
+}