@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 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
@@ -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 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.
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` (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.
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`](../language-server/README.md) and the VS Code
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.20260918.1)
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 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.
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 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`.
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`) so a host that ships its own copy of the mapper
284
- can start it from its own bundled entry file.
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.