@tsrx/content-mapper 0.1.1 → 0.1.3
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 +139 -58
- package/dist/{mapper-DATqGboo.js → mapper-Gc2yuGNf.js} +843 -55
- package/dist/mapper-Gc2yuGNf.js.map +1 -0
- package/dist/mapper.js +2 -2
- package/dist/protocol.js +39 -12
- package/dist/protocol.js.map +1 -1
- package/dist/rpc.js +11 -2
- package/dist/rpc.js.map +1 -1
- package/dist/server.js +1 -1
- package/package.json +9 -8
- package/platform-globals/android.d.cts +17 -0
- package/platform-globals/ios.d.cts +17 -0
- package/platform-globals/unconfigured.d.cts +17 -0
- package/platform-globals/web.d.cts +17 -0
- package/src/diagnostic-directives.js +239 -0
- package/src/export-stub.js +94 -7
- package/src/mapper.js +65 -46
- package/src/platform-globals.js +76 -0
- package/src/protocol.js +41 -13
- package/src/rpc.js +11 -2
- package/src/span-mappings.js +379 -8
- package/dist/mapper-DATqGboo.js.map +0 -1
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
|
|
@@ -67,15 +69,46 @@ script therefore serves every supported TypeScript
|
|
|
67
69
|
|
|
68
70
|
The mapper entry accepts an `options` object:
|
|
69
71
|
|
|
70
|
-
| Option
|
|
71
|
-
|
|
|
72
|
-
| `compiler`
|
|
73
|
-
| `platform`
|
|
74
|
-
| `languageFeatures`
|
|
72
|
+
| Option | Type | Meaning |
|
|
73
|
+
| ---------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------- |
|
|
74
|
+
| `compiler` | bare package specifier | The TSRX target compiler to use, for example `@tsrx/react` or a third-party compiler. |
|
|
75
|
+
| `platform` | `"web"`, `"ios"`, `"android"` | Platform for `import.meta.env.platform` flags. |
|
|
76
|
+
| `languageFeatures` | boolean, default `true` | `false` keeps spans for diagnostics but drops editor feature bits (CLI-only projects). |
|
|
77
|
+
| `verificationMappings` | boolean, default `false` | `true` adds the transform's own diagnostics mappings to each transform result, for command-line checkers (see below). |
|
|
75
78
|
|
|
76
79
|
Invalid options are reported by TypeScript as option diagnostics on the mapper
|
|
77
80
|
entry.
|
|
78
81
|
|
|
82
|
+
With `verificationMappings: true`, each transform result also has
|
|
83
|
+
`verificationMappings`: every compiler mapping marked for diagnostics, in Volar's
|
|
84
|
+
`CodeMapping` shape (`sourceOffsets`, `generatedOffsets`, `lengths`,
|
|
85
|
+
`generatedLengths`) and in the transform's order. It is for a checker that runs
|
|
86
|
+
TypeScript (or another checker) on the generated text itself, through
|
|
87
|
+
`create_tsrx_content_mapper` from `@tsrx/content-mapper/mapper`. Mapped with
|
|
88
|
+
`@volar/source-map`, each diagnostic lands where `tsrx-tsc` puts it:
|
|
89
|
+
|
|
90
|
+
```js
|
|
91
|
+
import { SourceMap } from '@volar/source-map';
|
|
92
|
+
|
|
93
|
+
const map = new SourceMap(result.verificationMappings);
|
|
94
|
+
const [range] = map.toSourceRange(start, start + length, true);
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
`@tsrx/content-mapper` doesn't depend on `@volar/source-map`; a checker that uses
|
|
98
|
+
it installs it itself (`npm install @volar/source-map`, version 2).
|
|
99
|
+
|
|
100
|
+
Unlike `mappings`, nothing is selected, coalesced or extended over whitespace, and
|
|
101
|
+
each mapping keeps its offsets together: Volar maps a range only through one
|
|
102
|
+
mapping that holds both of its ends, such as the two zero-length points of a
|
|
103
|
+
literal's start and end, and tries mappings in this order. When any mapping of a
|
|
104
|
+
file has a `verification` that is a `shouldReport` callback, the file's
|
|
105
|
+
`verificationMappings` is empty: the callback depends on the diagnostic and can't
|
|
106
|
+
be serialized, and leaving out only that mapping could let an overlapping one move
|
|
107
|
+
a diagnostic. The TSRX compilers in this repository emit none. The field is
|
|
108
|
+
outside the TypeScript 7 protocol (`VerificationMapping` in
|
|
109
|
+
`@tsrx/content-mapper/protocol`); TypeScript ignores it, and `mappings` is the
|
|
110
|
+
same with or without the option.
|
|
111
|
+
|
|
79
112
|
### Compiler selection
|
|
80
113
|
|
|
81
114
|
One precedence rule, highest first:
|
|
@@ -89,6 +122,29 @@ One precedence rule, highest first:
|
|
|
89
122
|
|
|
90
123
|
`platform` follows the same rule with `tsrx.platform`.
|
|
91
124
|
|
|
125
|
+
### What a compiler returns
|
|
126
|
+
|
|
127
|
+
The mapper runs any TSRX compiler, this repository's targets, Ripple, Octane or a
|
|
128
|
+
third-party one, through
|
|
129
|
+
`compile_to_volar_mappings(source, filename, { loose: true, platform })`, and
|
|
130
|
+
relies on what it returns:
|
|
131
|
+
|
|
132
|
+
- `code`: the generated TSX. Keep it valid TSX: a directive hides only
|
|
133
|
+
TypeScript's checker errors, so a syntax error TypeScript finds in the generated
|
|
134
|
+
code shows as it is, next to the compiler's own error.
|
|
135
|
+
- `mappings`: Volar mappings from the source to `code`. Map every token of a
|
|
136
|
+
statement, keywords and punctuation too, so that TypeScript's errors land on the
|
|
137
|
+
source and a directive covers the statement's whole generated code.
|
|
138
|
+
- `errors`: the collected errors, each with `pos` and `end` offsets into the
|
|
139
|
+
source and a `code`, TSRX's (`TSRX2002`) or TypeScript's (`TS1186`). An error
|
|
140
|
+
without a code is sent as `771001`.
|
|
141
|
+
- `sourceAst`: the source tree, with `start` and `end` on its nodes. The mapper
|
|
142
|
+
finds the statement, class or type member, or element that holds an error in it.
|
|
143
|
+
Without a tree, a directive covers only the error's own span.
|
|
144
|
+
|
|
145
|
+
A mistake the compiler cannot recover from is thrown, with `pos` and `code`: the
|
|
146
|
+
mapper then sends that error alone, and a stub of the file's exports.
|
|
147
|
+
|
|
92
148
|
### What TypeScript sees
|
|
93
149
|
|
|
94
150
|
- The generated TSX of the type-only transform, with a span map. Spans whose text
|
|
@@ -98,20 +154,49 @@ One precedence rule, highest first:
|
|
|
98
154
|
`Verbatim` spans with the same feature bits whose gap is identical text in both
|
|
99
155
|
files are coalesced into one span, so a statement such as
|
|
100
156
|
`import { a } from './x';` is one edit-safe span and TypeScript can place an
|
|
101
|
-
auto-import edit inside it.
|
|
102
|
-
|
|
157
|
+
auto-import edit inside it. A span from a mapping with no feature at all joins
|
|
158
|
+
either neighbour. Fragments of identifiers (the transform's one-character
|
|
159
|
+
file-start anchor) are dropped.
|
|
103
160
|
- Each embedded `<script>` body as a block statement appended to the generated
|
|
104
161
|
TSX, with a verbatim span back to the source (the shared transform does this on
|
|
105
162
|
every path). A block keeps one body's declarations from colliding with another's
|
|
106
163
|
or with the component's, and contributes nothing to declaration output. `import`
|
|
107
164
|
declarations of a `<script type="module">` body are hoisted to module level in
|
|
108
165
|
front of the block, where TypeScript resolves them like any other import.
|
|
109
|
-
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
166
|
+
- For a module that keeps an `import.meta.env.platform` flag, a
|
|
167
|
+
`/// <reference path>` directive to the shared file in `platform-globals/` that
|
|
168
|
+
types the flags for the project's platform, in place of the `declare global`
|
|
169
|
+
block the compiler appends to each such module. The file is in the program once,
|
|
170
|
+
so two modules don't repeat the `ImportMeta` index signature (TS2374), and
|
|
171
|
+
declaration output drops the directive, so `Component.d.tsrx.ts` carries no
|
|
172
|
+
generated globals. A directive is not an import, so organize imports and
|
|
173
|
+
auto-import see only the module's own imports. Under `noResolve: true`
|
|
174
|
+
TypeScript doesn't follow the directive, and every flag read reports TS2339
|
|
175
|
+
(`Property 'env' does not exist on type 'ImportMeta'`).
|
|
176
|
+
- Every TSRX compile error as a mapper diagnostic in the original file, printed as
|
|
177
|
+
`error TSRX<number>`, in capitals like TypeScript's `TS2322`, so a TSRX error
|
|
178
|
+
shows with its own code (`TSRX2002`). An error with a TypeScript code is `11`
|
|
179
|
+
and its number (`TS1005` → `TSRX111005`), with the code in brackets in the
|
|
180
|
+
message. The mapper's own errors are `771000` (a file that doesn't compile, with
|
|
181
|
+
an error without a code), `771001` (an error without a TSRX or TypeScript code),
|
|
182
|
+
`771002` (no compiler found) and `771003` (invalid configuration). The source,
|
|
183
|
+
codes and prefixes are in `@tsrx/core/diagnostics`.
|
|
184
|
+
- For each of those errors, an `ignore` diagnostic directive over the generated
|
|
185
|
+
code of the statement, class or type member, or element that holds it, so a
|
|
186
|
+
mistake shows once: TypeScript's own report of it there (TS1186 for a rest
|
|
187
|
+
element's default, a follow-on error of a TSRX mistake) is hidden until the
|
|
188
|
+
mapper's error is fixed. TypeScript's other errors in that code come back then
|
|
189
|
+
too. `tests/error-examples.js` has an example of every error in
|
|
190
|
+
`@tsrx/core/diagnostics`, and `tests/error-examples.test.js` checks that each
|
|
191
|
+
shows exactly once on TypeScript 7, or that its known problem (with the issue
|
|
192
|
+
that tracks it) still stands.
|
|
193
|
+
- No warning (`severity: 'warning'`, such as TSRX2035). TypeScript 7 shows every
|
|
194
|
+
mapper diagnostic as an error, so a warning would fail `tsc` on code that
|
|
195
|
+
compiles, and its directive would hide TypeScript's own errors in the same
|
|
196
|
+
statement. The classic `tsrx-tsc` and the TSRX language server on its classic
|
|
197
|
+
and plugin backends still show warnings, so VS Code shows them on TypeScript 7
|
|
198
|
+
too. With `--typescript-backend=native` the server reports no compile
|
|
199
|
+
diagnostics, so nothing shows a warning there yet.
|
|
115
200
|
- While a file cannot be compiled, a stub that re-declares its exports as `any`
|
|
116
201
|
(values and types), so importers keep resolving and the author sees exactly one
|
|
117
202
|
error at the failing construct. `<style>` bodies are never TypeScript's concern
|
|
@@ -167,23 +252,20 @@ what editors get:
|
|
|
167
252
|
- Without `runExternalCode` the mapper process is never spawned, `.tsrx` is never
|
|
168
253
|
registered and `.ts` importers report TS2307 for `.tsrx` modules: that is the
|
|
169
254
|
untrusted-workspace behaviour.
|
|
170
|
-
- `custom/setContentMapperContributions
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
255
|
+
- `custom/setContentMapperContributions`, exposed by the TypeScript 7 VS Code
|
|
256
|
+
extension as `registerContentMappers`, discovers configured projects for
|
|
257
|
+
contributed file extensions. TSRX registers only `.tsrx`, so opening a `.tsrx`
|
|
258
|
+
file starts TypeScript features without opening a `.ts` or `.js` file. The
|
|
259
|
+
mapper comes from the project's `contentMappers` entry. The API also supports an
|
|
260
|
+
optional inferred-project mapper for files outside configured projects; the TSRX
|
|
261
|
+
extension does not provide one.
|
|
176
262
|
|
|
177
263
|
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.
|
|
264
|
+
[`@tsrx/language-server`](https://github.com/tsrx-org/tsrx/tree/main/packages/language-server)
|
|
265
|
+
and the VS Code extension's README for the per-editor setup.
|
|
180
266
|
|
|
181
|
-
### Known limitations (TypeScript 7.1.0-dev.
|
|
267
|
+
### Known limitations (TypeScript 7.1.0-dev.20260930.4)
|
|
182
268
|
|
|
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
269
|
- `--runExternalCode` is required and is never enabled by the mapper; `tsrx-tsc`
|
|
188
270
|
passes it.
|
|
189
271
|
- Editors: no auto-import when a new import statement is needed
|
|
@@ -232,34 +314,33 @@ and installs next to the package.
|
|
|
232
314
|
|
|
233
315
|
### Native TypeScript binary
|
|
234
316
|
|
|
235
|
-
The
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
`lib/
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
-
|
|
247
|
-
`typescript`
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
Tests locate the binary
|
|
256
|
-
`
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
(`minimumReleaseAgeExclude`), then run `pnpm install`.
|
|
317
|
+
The repository's root `typescript` is the exact TypeScript 7.1 nightly the mapper
|
|
318
|
+
is tested against: the `native` catalog in `pnpm-workspace.yaml` (`ts_native`).
|
|
319
|
+
The `typescript@7.x` package is only a thin launcher: its `bin/tsc` calls
|
|
320
|
+
`lib/getExePath.js`, which resolves the platform package
|
|
321
|
+
`@typescript/typescript-<os>-<arch>` (an optional dependency of the launcher, so
|
|
322
|
+
pnpm installs only the one matching the current platform) and runs `lib/tsc` (or
|
|
323
|
+
`lib/tsc.exe`) from it.
|
|
324
|
+
|
|
325
|
+
- `pnpm typecheck` runs that `tsc` directly, with `--runExternalCode` for the
|
|
326
|
+
projects that declare the mapper in `contentMappers`.
|
|
327
|
+
- The packages whose code or tests use TypeScript's JavaScript API
|
|
328
|
+
(`@tsrx/typescript-plugin`, `@tsrx/language-server`, `@tsrx/core`'s tests and
|
|
329
|
+
the others that list it) keep `typescript` from the `default` catalog, the 5.x
|
|
330
|
+
line.
|
|
331
|
+
- Packages whose declaration files import `typescript` without declaring it get it
|
|
332
|
+
as an optional peer through `packageExtensions`, so they take the `typescript`
|
|
333
|
+
of the package that uses them rather than the root launcher.
|
|
334
|
+
- The nightly is also listed under `minimumReleaseAgeExclude` because it is newer
|
|
335
|
+
than the workspace's release-age policy.
|
|
336
|
+
|
|
337
|
+
Tests locate the binary the way the launcher does, through the platform package of
|
|
338
|
+
the `typescript` resolved from the repository root. A missing binary fails the
|
|
339
|
+
test instead of skipping it.
|
|
340
|
+
|
|
341
|
+
To move to a newer nightly, update `ts_native` and the matching
|
|
342
|
+
`minimumReleaseAgeExclude` entries in `pnpm-workspace.yaml`, then run
|
|
343
|
+
`pnpm install`.
|
|
263
344
|
|
|
264
345
|
### Tests
|
|
265
346
|
|