@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 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.20260822.1` or newer.** The content-mapper protocol is
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`. `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
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 | 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). |
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. Fragments of identifiers (the transform's
102
- one-character file-start anchor) are dropped.
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
- - 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.
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` (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.
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`](../language-server/README.md) and the VS Code
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.20260918.1)
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 mapper is tested against an exact TypeScript 7 nightly. The `typescript@7.x`
236
- package is only a thin launcher: its `bin/tsc` calls `lib/getExePath.js`, which
237
- resolves the platform package `@typescript/typescript-<os>-<arch>` and runs
238
- `lib/tsc` (or `lib/tsc.exe`) from it. That platform package is self-contained (the
239
- Go binary plus the `lib.*.d.ts` library files), so this repository pins the
240
- platform packages directly instead of the launcher:
241
-
242
- - `package.json` at the repository root lists every
243
- `@typescript/typescript-<os>-<arch>` package under `optionalDependencies` at the
244
- exact nightly version. pnpm installs only the one matching the current
245
- `process.platform` and `process.arch`.
246
- - Pinning the platform packages avoids a `tsc` bin conflict with the classic
247
- `typescript` catalog entry, which stays on the 5.x line for the Volar path.
248
- - The pinned nightly is also listed under `minimumReleaseAgeExclude` in
249
- `pnpm-workspace.yaml` because it is newer than the workspace's release-age
250
- policy.
251
- - `pnpm typecheck` runs the same pinned platform packages through
252
- `scripts/native-tsc.js`, since the root `typescript` must stay on the 5.x line
253
- for the tooling's JavaScript API.
254
-
255
- Tests locate the binary as
256
- `node_modules/@typescript/typescript-${process.platform}-${process.arch}/lib/tsc`
257
- resolved from the repository root. A missing binary fails the test instead of
258
- skipping it.
259
-
260
- To move to a newer nightly, update the version in the root `package.json`
261
- (`optionalDependencies`) and in `pnpm-workspace.yaml`
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