@tsrx/content-mapper 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Dominic Gannaway
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,287 @@
1
+ # @tsrx/content-mapper
2
+
3
+ TypeScript 7 content mapper for `.tsrx` files. It lets native TypeScript (the
4
+ `typescript@7` line's `tsc` and its language server) type-check `.tsrx` modules
5
+ through the upstream content-mapper protocol, reusing the target-specific
6
+ type-only transform that also powers `@tsrx/typescript-plugin` and the classic
7
+ Volar path.
8
+
9
+ Implementation issue: https://github.com/tsrx-org/tsrx/issues/41. Gaps in
10
+ TypeScript 7 support and the upstream issues behind them:
11
+ https://github.com/tsrx-org/tsrx/issues/136.
12
+
13
+ ## Requirements
14
+
15
+ - **TypeScript `7.1.0-dev.20260822.1` or newer.** The content-mapper protocol is
16
+ not in the stable 7.0 line: `typescript@7.0.2` rejects `--runExternalCode`
17
+ (TS5023) and ignores `contentMappers`. `7.1.0-dev.20260822.1` is the oldest
18
+ nightly that passes this package's test suite (`7.1.0-dev.20260821.1` fails it);
19
+ the repository pins `7.1.0-dev.20260918.1`. Run the suite against another build
20
+ with `TSRX_NATIVE_TSC=<path to tsc>`.
21
+ - **`--runExternalCode`.** TypeScript only spawns the mapper when the user opts
22
+ in; the mapper never enables it. Without the flag, a `contentMappers` entry is
23
+ an error (TS100024). `tsrx-tsc` passes the flag when it runs TypeScript 7,
24
+ because running it is already the decision to execute the project's TSRX
25
+ compiler.
26
+ - **No other TypeScript.** The mapper reads `tsconfig.json` (comments, trailing
27
+ commas and the `extends` chain, including packages) and resolves compiler
28
+ packages with `@tsrx/typescript-plugin`'s own reader and package walk
29
+ (`src/tsconfig-resolution.js`, `src/package-resolution.js`), never through
30
+ TypeScript's JavaScript API. A project whose only `typescript` is the native
31
+ compiler's launcher package needs nothing else; `tests/mapper.test.js` runs the
32
+ mapper with the `typescript` package forbidden to prove it.
33
+
34
+ ## Usage
35
+
36
+ Install the mapper next to TypeScript 7 and declare it in `tsconfig.json`:
37
+
38
+ ```jsonc
39
+ {
40
+ "tsrx": { "compiler": "@tsrx/react" },
41
+ "contentMappers": [
42
+ { "package": "@tsrx/content-mapper", "extensions": [".tsrx"] },
43
+ ],
44
+ "compilerOptions": {
45
+ "jsx": "react-jsx",
46
+ "jsxImportSource": "react",
47
+ },
48
+ }
49
+ ```
50
+
51
+ Then run native `tsc` with external code enabled. The flag is a user decision; the
52
+ mapper never turns it on for you:
53
+
54
+ ```sh
55
+ tsc --runExternalCode --noEmit
56
+ ```
57
+
58
+ `tsrx-tsc` (from `@tsrx/typescript-plugin`) keeps working unchanged for TypeScript
59
+ 5.9 and 6, and on a TypeScript 7.1 nightly it runs this same command for you: it
60
+ finds the native binary through the `typescript` launcher package's platform
61
+ package, adds `--runExternalCode`, and refuses to run a tsconfig without a `.tsrx`
62
+ content mapper rather than let TypeScript skip those files. One `package.json`
63
+ script therefore serves every supported TypeScript
64
+ (`tests/tsrx-tsc-native.test.js`).
65
+
66
+ ### Options
67
+
68
+ The mapper entry accepts an `options` object:
69
+
70
+ | Option | Type | Meaning |
71
+ | ------------------ | ----------------------------- | -------------------------------------------------------------------------------------- |
72
+ | `compiler` | bare package specifier | The TSRX target compiler to use, for example `@tsrx/react` or a third-party compiler. |
73
+ | `platform` | `"web"`, `"ios"`, `"android"` | Platform for `import.meta.env.platform` flags. |
74
+ | `languageFeatures` | boolean, default `true` | `false` keeps spans for diagnostics but drops editor feature bits (CLI-only projects). |
75
+
76
+ Invalid options are reported by TypeScript as option diagnostics on the mapper
77
+ entry.
78
+
79
+ ### Compiler selection
80
+
81
+ One precedence rule, highest first:
82
+
83
+ 1. `contentMappers[].options.compiler` on the mapper entry.
84
+ 2. `tsrx.compiler` in the project's tsconfig, following the `extends` chain (the
85
+ same rule the classic plugin uses).
86
+ 3. Auto-detection of an installed target compiler (`@tsrx/react`, `@tsrx/preact`,
87
+ `@tsrx/solid`, `@tsrx/vue`, `@tsrx/hono`, `@tsrx/ripple`, `octane`) from the
88
+ file's directory upwards.
89
+
90
+ `platform` follows the same rule with `tsrx.platform`.
91
+
92
+ ### What TypeScript sees
93
+
94
+ - The generated TSX of the type-only transform, with a span map. Spans whose text
95
+ is unchanged are `Verbatim` (edit-safe: rename, code actions and formatting
96
+ write back through them); renamed identifiers are `Alias`, so a diagnostic that
97
+ covers one shows the authored name; everything else is `Atom`. Neighbouring
98
+ `Verbatim` spans with the same feature bits whose gap is identical text in both
99
+ files are coalesced into one span, so a statement such as
100
+ `import { a } from './x';` is one edit-safe span and TypeScript can place an
101
+ auto-import edit inside it. Fragments of identifiers (the transform's
102
+ one-character file-start anchor) are dropped.
103
+ - Each embedded `<script>` body as a block statement appended to the generated
104
+ TSX, with a verbatim span back to the source (the shared transform does this on
105
+ every path). A block keeps one body's declarations from colliding with another's
106
+ or with the component's, and contributes nothing to declaration output. `import`
107
+ declarations of a `<script type="module">` body are hoisted to module level in
108
+ front of the block, where TypeScript resolves them like any other import.
109
+ - TSRX compile errors as mapper diagnostics in the original file, printed as
110
+ `error tsrx<code>`. Code `1000` is a fatal compile error, `1001` a usage error
111
+ without a string code, `1002` no compiler found, `1003` invalid configuration;
112
+ string-coded diagnostics such as `tsrx-unclosed-tag` get a stable numeric code
113
+ in the `10000` to `99999` range and keep the string code in brackets in the
114
+ message.
115
+ - While a file cannot be compiled, a stub that re-declares its exports as `any`
116
+ (values and types), so importers keep resolving and the author sees exactly one
117
+ error at the failing construct. `<style>` bodies are never TypeScript's concern
118
+ and stay in the TSRX language server.
119
+
120
+ ### Declarations
121
+
122
+ Under `--declaration`, native TypeScript emits `Component.d.tsrx.ts` (plus `.map`)
123
+ next to `main.d.ts` and keeps `./Component.tsrx` in import specifiers. `<script>`
124
+ bodies add no declaration files.
125
+
126
+ - A project that references a `.tsrx` library through `references` (`tsc --build`)
127
+ must declare the content mapper as well, so that TypeScript knows `.tsrx` inputs
128
+ and redirects `lib/Component.tsrx` to `lib/dist/Component.d.tsrx.ts`. Without
129
+ it, the `./Component.tsrx` specifier inside the library's `index.d.ts` fails to
130
+ resolve and, under `skipLibCheck`, the export silently becomes `any`.
131
+ - A project that consumes published declarations without the mapper needs
132
+ `allowArbitraryExtensions: true`, which makes TypeScript resolve
133
+ `./Component.tsrx` to `Component.d.tsrx.ts`. Emitted declarations are plain
134
+ TypeScript and re-check with TypeScript 5 or 7 this way.
135
+ - microsoft/TypeScript#64120 (`outputExtension`) will let a build that compiles
136
+ `.tsrx` to `.js` emit `Component.d.ts` instead; do not design around the current
137
+ naming.
138
+
139
+ ### Editors
140
+
141
+ TypeScript 7's language server (`tsc --lsp --stdio`, what the VS Code TypeScript 7
142
+ extension and other LSP clients run) serves `.tsrx` files through the mapper once
143
+ the client sends `initializationOptions.runExternalCode: true` and the project
144
+ declares `contentMappers`. `tests/native-lsp.test.js` drives that server and pins
145
+ what editors get:
146
+
147
+ - `.tsrx` document filters are registered dynamically for diagnostics, hover,
148
+ definition, references, document highlights, completion, rename and code
149
+ actions.
150
+ - Pull diagnostics report TypeScript errors and TSRX compile errors (source
151
+ `tsrx`) at authored spans; while a file fails to compile, importers keep
152
+ resolving through the export stub.
153
+ - Hover, definition, references, document highlights and rename work through
154
+ `Verbatim` spans, across `.tsrx` and `.ts` files and across several configured
155
+ projects in one session, and again after a server restart.
156
+ - Auto-import that extends an existing import statement works. Auto-import that
157
+ needs a new import statement is dropped by the server because the insertion
158
+ point falls into synthesized code (the hoisted static JSX at the top of the
159
+ generated file); tracked as microsoft/TypeScript#64119.
160
+ - Rename on an `Atom` span (for example `/>`, which becomes `/>;`) returns
161
+ nothing; whole-symbol projection for `Atom` spans is microsoft/TypeScript#63879.
162
+ - Requests on synthesized spans (`@{`) return nothing. VS Code takes the first
163
+ non-empty document-highlight result in provider order, so the TSRX language
164
+ server's keyword highlights are consulted exactly there; with several `.tsrx`
165
+ editors visible VS Code only asks multi-document providers, which the TSRX
166
+ server does not register.
167
+ - Without `runExternalCode` the mapper process is never spawned, `.tsrx` is never
168
+ registered and `.ts` importers report TS2307 for `.tsrx` modules: that is the
169
+ untrusted-workspace behaviour.
170
+ - `custom/setContentMapperContributions` (the inferred-project contribution of the
171
+ protocol, which the TypeScript 7 VS Code extension exposes to other extensions
172
+ as `registerContentMappers`) maps `.tsrx` files that belong to no configured
173
+ project, and clearing it unregisters them. The TSRX VS Code extension does not
174
+ use it: `.tsrx` files are mapped through the `contentMappers` entry of the
175
+ `tsconfig.json` that covers them, in every editor alike.
176
+
177
+ The TSRX language server runs beside it with `--typescript-backend=native`; see
178
+ [`@tsrx/language-server`](../language-server/README.md) and the VS Code
179
+ extension's README for the per-editor setup.
180
+
181
+ ### Known limitations (TypeScript 7.1.0-dev.20260918.1)
182
+
183
+ - `--watch` compiles once and never recompiles after an edit on macOS
184
+ (microsoft/TypeScript#64351, a nightly regression since `7.1.0-dev.20260811.1`
185
+ that reproduces without a content mapper and with every `--watchFile` strategy).
186
+ The watch test only asserts the initial pass.
187
+ - `--runExternalCode` is required and is never enabled by the mapper; `tsrx-tsc`
188
+ passes it.
189
+ - Editors: no auto-import when a new import statement is needed
190
+ (microsoft/TypeScript#64119), no rename on `Atom` spans
191
+ (microsoft/TypeScript#63879), and an unused variable in a `<script>` body is
192
+ reported as a hint (TS6133) because the body is checked as a module.
193
+
194
+ ### Compatibility and performance
195
+
196
+ [`COMPATIBILITY.md`](./COMPATIBILITY.md) classifies every observed difference
197
+ between this path and classic `tsrx-tsc` (compiler-version difference, previously
198
+ hidden diagnostic, adapter bug, adapter design, upstream limitation) with the test
199
+ or probe behind each row, and lists what is not exercised yet.
200
+ [`BENCHMARKS.md`](./BENCHMARKS.md) reports cold and warm checks, single-edit
201
+ latency, peak memory and process counts for both paths on the same projects and
202
+ hardware (`bench/bench.js`). [`ROLLOUT.md`](./ROLLOUT.md) is the release note with
203
+ migration, rollback and the default-backend decision.
204
+
205
+ ### Cache invalidation
206
+
207
+ The mapper uses `dynamicConfig`. `openProject` returns a `configIdentity` hashed
208
+ from the mapper options, every tsconfig in the `extends` chain and the resolved
209
+ compiler's `package.json`, and lists those files as `watchedFiles`.
210
+
211
+ ## Development
212
+
213
+ ### Dependencies
214
+
215
+ The mapper bundles `@tsrx/typescript-plugin`'s compiler resolution and transform
216
+ (`src/transform.js`, `consumer-compiler.js`, `tsconfig-resolution.js`) and keeps
217
+ classic `typescript` as a peer dependency: the tsconfig readers use
218
+ `readJsonConfigFile`, `convertToObject`, `parseJsonSourceFileConfigFileContent`
219
+ and `resolveModuleName` from the TypeScript 5 API for `extends` and JSONC
220
+ handling. The native compiler never loads the mapper's copy of TypeScript, so this
221
+ is an explicit, versioned dependency rather than a claim of independence.
222
+
223
+ ### Native TypeScript binary
224
+
225
+ The mapper is tested against an exact TypeScript 7 nightly. The `typescript@7.x`
226
+ package is only a thin launcher: its `bin/tsc` calls `lib/getExePath.js`, which
227
+ resolves the platform package `@typescript/typescript-<os>-<arch>` and runs
228
+ `lib/tsc` (or `lib/tsc.exe`) from it. That platform package is self-contained (the
229
+ Go binary plus the `lib.*.d.ts` library files), so this repository pins the
230
+ platform packages directly instead of the launcher:
231
+
232
+ - `package.json` at the repository root lists every
233
+ `@typescript/typescript-<os>-<arch>` package under `optionalDependencies` at the
234
+ exact nightly version. pnpm installs only the one matching the current
235
+ `process.platform` and `process.arch`.
236
+ - Pinning the platform packages avoids a `tsc` bin conflict with the classic
237
+ `typescript` catalog entry, which stays on the 5.x line for the Volar path.
238
+ - The pinned nightly is also listed under `minimumReleaseAgeExclude` in
239
+ `pnpm-workspace.yaml` because it is newer than the workspace's release-age
240
+ policy.
241
+ - `pnpm typecheck` runs the same pinned platform packages through
242
+ `scripts/native-tsc.js`, since the root `typescript` must stay on the 5.x line
243
+ for the tooling's JavaScript API.
244
+
245
+ Tests locate the binary as
246
+ `node_modules/@typescript/typescript-${process.platform}-${process.arch}/lib/tsc`
247
+ resolved from the repository root. A missing binary fails the test instead of
248
+ skipping it.
249
+
250
+ To move to a newer nightly, update the version in the root `package.json`
251
+ (`optionalDependencies`) and in `pnpm-workspace.yaml`
252
+ (`minimumReleaseAgeExclude`), then run `pnpm install`.
253
+
254
+ ### Tests
255
+
256
+ ```sh
257
+ pnpm test --project content-mapper
258
+ ```
259
+
260
+ - `tests/fixtures/consumer/` is the React reference project: two `.tsrx` modules
261
+ that import each other, a `.ts` importer, one intentional cross-file prop-type
262
+ error, one embedded `<script>` block and one `<style>` block with a scoped
263
+ class. `expected-diagnostics.json` records the classic `tsrx-tsc` output and is
264
+ the parity target for `native-tsc.test.js`.
265
+ - `tests/fixtures/targets/` holds one fixture per target (Preact, Solid, Vue,
266
+ Ripple); `targets.test.js` runs both `tsrx-tsc` and native `tsc` on each and
267
+ requires identical diagnostics.
268
+ - `third-party-compiler.test.js` selects a stub compiler through the mapper
269
+ options and through `tsrx.compiler`, and checks that `Alias` spans show authored
270
+ identifiers in diagnostics.
271
+ - `native-lsp.test.js` drives the native language server (`tsc --lsp --stdio`)
272
+ through `tests/lsp-client.js`, a minimal JSON-RPC client, and pins the editor
273
+ features listed under _Editors_ above.
274
+ - Integration tests spawn the mapper from `src/server.js` through a generated
275
+ manifest in a temporary workspace, so they never depend on a stale `dist/`.
276
+
277
+ ### Package layout
278
+
279
+ - `src/server.js` is the executable entry named by the manifest.
280
+ - `src/rpc.js` (`run_mapper_server`, `redirect_console_to_stderr`) is the stdio
281
+ transport and `src/mapper.js` (`create_tsrx_content_mapper`) the protocol
282
+ implementation. Both are exported (`@tsrx/content-mapper/rpc`,
283
+ `@tsrx/content-mapper/mapper`) so a host that ships its own copy of the mapper
284
+ can start it from its own bundled entry file.
285
+
286
+ `MAPPING.md` is the inventory of every mapping site in the shared transform and
287
+ the span kind and feature bits each one becomes.