@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 +21 -0
- package/README.md +287 -0
- package/dist/server.js +3328 -0
- package/dist/server.js.map +1 -0
- package/package.json +65 -0
- package/src/export-stub.js +150 -0
- package/src/mapper.js +473 -0
- package/src/protocol.js +122 -0
- package/src/rpc.js +126 -0
- package/src/server.js +11 -0
- package/src/span-mappings.js +370 -0
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.
|