tsrx-typegen 0.2.1 → 0.2.2

package/README.md

@@ -5,6 +5,10 @@ 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
+```
+
 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.
@@ -26,7 +30,13 @@ 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.
+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
@@ -36,7 +46,7 @@ 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).
+[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:
@@ -76,10 +86,22 @@ 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`.
 
+```ts
+// Plain TypeScript consumer of the package whose exports are configured above.
+import { Button } from 'my-component-library'
+
+// Button is a component exported by your library's src/index.ts.
+export { Button }
+```
+
 Use separate target records and project configs when public signatures differ.
 Each config must select the same source variants as its runtime build.
 `runtime` records the published runtime path or condition map, while `types`
@@ -89,6 +111,12 @@ 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
@@ -101,6 +129,11 @@ bare package imports are declared dependencies or peers. The command needs
 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
@@ -109,6 +142,26 @@ 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": "./dist/index.js",
+					"types": "./types/index.d.ts"
+				}
+			}
+		}
+	}
+}
+```
+
 Run the same gate from `prepack` so `pnpm pack` and publication share it:
 
 ```json
@@ -125,6 +178,10 @@ 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
+```
+
 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
@@ -137,3 +194,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.2.2",
   "description": "Generate consumer-ready TypeScript declarations for TSRX libraries",
   "keywords": [
     "build-tool",

package/src/cli.mjs

@@ -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}`)
 		}
 	}
 
@@ -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}`,
 				)

package/src/pack-check.mjs

@@ -599,8 +599,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 +652,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 })
 	}