@tsrx/content-mapper 0.1.0 → 0.1.2
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/README.md +106 -60
- package/dist/mapper-B4f--1ac.js +3366 -0
- package/dist/mapper-B4f--1ac.js.map +1 -0
- package/dist/mapper.js +3 -0
- package/dist/protocol.js +126 -0
- package/dist/protocol.js.map +1 -0
- package/dist/rpc.js +137 -0
- package/dist/rpc.js.map +1 -0
- package/dist/server.js +2 -3315
- package/dist/server.js.map +1 -1
- package/package.json +10 -10
- package/src/diagnostic-directives.js +199 -0
- package/src/export-stub.js +112 -9
- package/src/mapper.js +43 -40
- package/src/protocol.js +23 -13
- package/src/rpc.js +11 -2
package/README.md
CHANGED
|
@@ -12,11 +12,13 @@ https://github.com/tsrx-org/tsrx/issues/136.
|
|
|
12
12
|
|
|
13
13
|
## Requirements
|
|
14
14
|
|
|
15
|
-
- **TypeScript `7.1.0-dev.
|
|
15
|
+
- **TypeScript `7.1.0-dev.20260923.1` or newer.** The content-mapper protocol is
|
|
16
16
|
not in the stable 7.0 line: `typescript@7.0.2` rejects `--runExternalCode`
|
|
17
|
-
(TS5023) and ignores `contentMappers`.
|
|
18
|
-
|
|
19
|
-
|
|
17
|
+
(TS5023) and ignores `contentMappers`. The protocol arrived in
|
|
18
|
+
`7.1.0-dev.20260822.1` (`7.1.0-dev.20260821.1` fails this package's test suite),
|
|
19
|
+
but `tsc --watch` never recompiled on macOS until `7.1.0-dev.20260923.1`
|
|
20
|
+
(microsoft/TypeScript#64351), the oldest nightly that passes the whole suite.
|
|
21
|
+
The repository runs `7.1.0-dev.20260930.4`. Run the suite against another build
|
|
20
22
|
with `TSRX_NATIVE_TSC=<path to tsc>`.
|
|
21
23
|
- **`--runExternalCode`.** TypeScript only spawns the mapper when the user opts
|
|
22
24
|
in; the mapper never enables it. Without the flag, a `contentMappers` entry is
|
|
@@ -89,6 +91,29 @@ One precedence rule, highest first:
|
|
|
89
91
|
|
|
90
92
|
`platform` follows the same rule with `tsrx.platform`.
|
|
91
93
|
|
|
94
|
+
### What a compiler returns
|
|
95
|
+
|
|
96
|
+
The mapper runs any TSRX compiler, this repository's targets, Ripple, Octane or a
|
|
97
|
+
third-party one, through
|
|
98
|
+
`compile_to_volar_mappings(source, filename, { loose: true, platform })`, and
|
|
99
|
+
relies on what it returns:
|
|
100
|
+
|
|
101
|
+
- `code`: the generated TSX. Keep it valid TSX: a directive hides only
|
|
102
|
+
TypeScript's checker errors, so a syntax error TypeScript finds in the generated
|
|
103
|
+
code shows as it is, next to the compiler's own error.
|
|
104
|
+
- `mappings`: Volar mappings from the source to `code`. Map every token of a
|
|
105
|
+
statement, keywords and punctuation too, so that TypeScript's errors land on the
|
|
106
|
+
source and a directive covers the statement's whole generated code.
|
|
107
|
+
- `errors`: the collected errors, each with `pos` and `end` offsets into the
|
|
108
|
+
source and a `code`, TSRX's (`TSRX2002`) or TypeScript's (`TS1186`). An error
|
|
109
|
+
without a code is sent as `771001`.
|
|
110
|
+
- `sourceAst`: the source tree, with `start` and `end` on its nodes. The mapper
|
|
111
|
+
finds the statement, class or type member, or element that holds an error in it.
|
|
112
|
+
Without a tree, a directive covers only the error's own span.
|
|
113
|
+
|
|
114
|
+
A mistake the compiler cannot recover from is thrown, with `pos` and `code`: the
|
|
115
|
+
mapper then sends that error alone, and a stub of the file's exports.
|
|
116
|
+
|
|
92
117
|
### What TypeScript sees
|
|
93
118
|
|
|
94
119
|
- The generated TSX of the type-only transform, with a span map. Spans whose text
|
|
@@ -106,12 +131,23 @@ One precedence rule, highest first:
|
|
|
106
131
|
or with the component's, and contributes nothing to declaration output. `import`
|
|
107
132
|
declarations of a `<script type="module">` body are hoisted to module level in
|
|
108
133
|
front of the block, where TypeScript resolves them like any other import.
|
|
109
|
-
- TSRX compile
|
|
110
|
-
`error
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
134
|
+
- Every TSRX compile error as a mapper diagnostic in the original file, printed as
|
|
135
|
+
`error TSRX<number>`, in capitals like TypeScript's `TS2322`, so a TSRX error
|
|
136
|
+
shows with its own code (`TSRX2002`). An error with a TypeScript code is `11`
|
|
137
|
+
and its number (`TS1005` → `TSRX111005`), with the code in brackets in the
|
|
138
|
+
message. The mapper's own errors are `771000` (a file that doesn't compile, with
|
|
139
|
+
an error without a code), `771001` (an error without a TSRX or TypeScript code),
|
|
140
|
+
`771002` (no compiler found) and `771003` (invalid configuration). The source,
|
|
141
|
+
codes and prefixes are in `@tsrx/core/diagnostics`.
|
|
142
|
+
- For each of those errors, an `ignore` diagnostic directive over the generated
|
|
143
|
+
code of the statement, class or type member, or element that holds it, so a
|
|
144
|
+
mistake shows once: TypeScript's own report of it there (TS1186 for a rest
|
|
145
|
+
element's default, a follow-on error of a TSRX mistake) is hidden until the
|
|
146
|
+
mapper's error is fixed. TypeScript's other errors in that code come back then
|
|
147
|
+
too. `tests/error-examples.js` has an example of every error in
|
|
148
|
+
`@tsrx/core/diagnostics`, and `tests/error-examples.test.js` checks that each
|
|
149
|
+
shows exactly once on TypeScript 7, or that its known problem (with the issue
|
|
150
|
+
that tracks it) still stands.
|
|
115
151
|
- While a file cannot be compiled, a stub that re-declares its exports as `any`
|
|
116
152
|
(values and types), so importers keep resolving and the author sees exactly one
|
|
117
153
|
error at the failing construct. `<style>` bodies are never TypeScript's concern
|
|
@@ -167,23 +203,20 @@ what editors get:
|
|
|
167
203
|
- Without `runExternalCode` the mapper process is never spawned, `.tsrx` is never
|
|
168
204
|
registered and `.ts` importers report TS2307 for `.tsrx` modules: that is the
|
|
169
205
|
untrusted-workspace behaviour.
|
|
170
|
-
- `custom/setContentMapperContributions
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
206
|
+
- `custom/setContentMapperContributions`, exposed by the TypeScript 7 VS Code
|
|
207
|
+
extension as `registerContentMappers`, discovers configured projects for
|
|
208
|
+
contributed file extensions. TSRX registers only `.tsrx`, so opening a `.tsrx`
|
|
209
|
+
file starts TypeScript features without opening a `.ts` or `.js` file. The
|
|
210
|
+
mapper comes from the project's `contentMappers` entry. The API also supports an
|
|
211
|
+
optional inferred-project mapper for files outside configured projects; the TSRX
|
|
212
|
+
extension does not provide one.
|
|
176
213
|
|
|
177
214
|
The TSRX language server runs beside it with `--typescript-backend=native`; see
|
|
178
|
-
[`@tsrx/language-server`](
|
|
179
|
-
extension's README for the per-editor setup.
|
|
215
|
+
[`@tsrx/language-server`](https://github.com/tsrx-org/tsrx/tree/main/packages/language-server)
|
|
216
|
+
and the VS Code extension's README for the per-editor setup.
|
|
180
217
|
|
|
181
|
-
### Known limitations (TypeScript 7.1.0-dev.
|
|
218
|
+
### Known limitations (TypeScript 7.1.0-dev.20260930.4)
|
|
182
219
|
|
|
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
220
|
- `--runExternalCode` is required and is never enabled by the mapper; `tsrx-tsc`
|
|
188
221
|
passes it.
|
|
189
222
|
- Editors: no auto-import when a new import statement is needed
|
|
@@ -212,44 +245,53 @@ compiler's `package.json`, and lists those files as `watchedFiles`.
|
|
|
212
245
|
|
|
213
246
|
### Dependencies
|
|
214
247
|
|
|
215
|
-
The mapper
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
248
|
+
The mapper has no dependency on `typescript`, classic or native: it reads tsconfig
|
|
249
|
+
files and resolves compiler packages with its own code, and `tests/mapper.test.js`
|
|
250
|
+
and `tests/package.test.js` run the shipped bundles with the `typescript` package
|
|
251
|
+
forbidden to keep it that way.
|
|
252
|
+
|
|
253
|
+
`@tsrx/typescript-plugin` is a devDependency only. The bundles inline its compiler
|
|
254
|
+
resolution and transform (`src/transform.js`, `language.js`,
|
|
255
|
+
`consumer-compiler.js`, `package-resolution.js`, `tsconfig-resolution.js`,
|
|
256
|
+
`config-host.js`, `jsonc.js`) together with the third-party modules those pull in
|
|
257
|
+
(`@volar/language-core`, `resolve-pkg-maps`), because the plugin publishes only
|
|
258
|
+
its `dist` and pulls the classic Volar stack into anything that depends on it.
|
|
259
|
+
`@tsrx/core` appears in JSDoc types only; the TSRX target compiler itself is
|
|
260
|
+
resolved from the project at run time.
|
|
261
|
+
|
|
262
|
+
`jsonc-parser` is the one runtime dependency: its UMD entry requires its
|
|
263
|
+
`./impl/*` files at run time, which a bundle cannot follow, so it stays external
|
|
264
|
+
and installs next to the package.
|
|
222
265
|
|
|
223
266
|
### Native TypeScript binary
|
|
224
267
|
|
|
225
|
-
The
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
`lib/
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
-
|
|
237
|
-
`typescript`
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
Tests locate the binary
|
|
246
|
-
`
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
(`minimumReleaseAgeExclude`), then run `pnpm install`.
|
|
268
|
+
The repository's root `typescript` is the exact TypeScript 7.1 nightly the mapper
|
|
269
|
+
is tested against: the `native` catalog in `pnpm-workspace.yaml` (`ts_native`).
|
|
270
|
+
The `typescript@7.x` package is only a thin launcher: its `bin/tsc` calls
|
|
271
|
+
`lib/getExePath.js`, which resolves the platform package
|
|
272
|
+
`@typescript/typescript-<os>-<arch>` (an optional dependency of the launcher, so
|
|
273
|
+
pnpm installs only the one matching the current platform) and runs `lib/tsc` (or
|
|
274
|
+
`lib/tsc.exe`) from it.
|
|
275
|
+
|
|
276
|
+
- `pnpm typecheck` runs that `tsc` directly, with `--runExternalCode` for the
|
|
277
|
+
projects that declare the mapper in `contentMappers`.
|
|
278
|
+
- The packages whose code or tests use TypeScript's JavaScript API
|
|
279
|
+
(`@tsrx/typescript-plugin`, `@tsrx/language-server`, `@tsrx/core`'s tests and
|
|
280
|
+
the others that list it) keep `typescript` from the `default` catalog, the 5.x
|
|
281
|
+
line.
|
|
282
|
+
- Packages whose declaration files import `typescript` without declaring it get it
|
|
283
|
+
as an optional peer through `packageExtensions`, so they take the `typescript`
|
|
284
|
+
of the package that uses them rather than the root launcher.
|
|
285
|
+
- The nightly is also listed under `minimumReleaseAgeExclude` because it is newer
|
|
286
|
+
than the workspace's release-age policy.
|
|
287
|
+
|
|
288
|
+
Tests locate the binary the way the launcher does, through the platform package of
|
|
289
|
+
the `typescript` resolved from the repository root. A missing binary fails the
|
|
290
|
+
test instead of skipping it.
|
|
291
|
+
|
|
292
|
+
To move to a newer nightly, update `ts_native` and the matching
|
|
293
|
+
`minimumReleaseAgeExclude` entries in `pnpm-workspace.yaml`, then run
|
|
294
|
+
`pnpm install`.
|
|
253
295
|
|
|
254
296
|
### Tests
|
|
255
297
|
|
|
@@ -280,8 +322,12 @@ pnpm test --project content-mapper
|
|
|
280
322
|
- `src/rpc.js` (`run_mapper_server`, `redirect_console_to_stderr`) is the stdio
|
|
281
323
|
transport and `src/mapper.js` (`create_tsrx_content_mapper`) the protocol
|
|
282
324
|
implementation. Both are exported (`@tsrx/content-mapper/rpc`,
|
|
283
|
-
`@tsrx/content-mapper/mapper`)
|
|
284
|
-
|
|
325
|
+
`@tsrx/content-mapper/mapper`), with `src/protocol.js`
|
|
326
|
+
(`@tsrx/content-mapper/protocol`), so a host that ships its own copy of the
|
|
327
|
+
mapper can start it from its own bundled entry file. The exports resolve to the
|
|
328
|
+
bundles in `dist/` (built with `dist/server.js`), never to `src/`: the source
|
|
329
|
+
imports `@tsrx/typescript-plugin/src/*`, which that package does not publish and
|
|
330
|
+
which is not a dependency of this one.
|
|
285
331
|
|
|
286
332
|
`MAPPING.md` is the inventory of every mapping site in the shared transform and
|
|
287
333
|
the span kind and feature bits each one becomes.
|