@tsrx/content-mapper 0.1.2 → 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
@@ -69,15 +69,46 @@ script therefore serves every supported TypeScript
69
69
 
70
70
  The mapper entry accepts an `options` object:
71
71
 
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). |
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). |
77
78
 
78
79
  Invalid options are reported by TypeScript as option diagnostics on the mapper
79
80
  entry.
80
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
+
81
112
  ### Compiler selection
82
113
 
83
114
  One precedence rule, highest first:
@@ -123,14 +154,25 @@ mapper then sends that error alone, and a stub of the file's exports.
123
154
  `Verbatim` spans with the same feature bits whose gap is identical text in both
124
155
  files are coalesced into one span, so a statement such as
125
156
  `import { a } from './x';` is one edit-safe span and TypeScript can place an
126
- auto-import edit inside it. Fragments of identifiers (the transform's
127
- 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.
128
160
  - Each embedded `<script>` body as a block statement appended to the generated
129
161
  TSX, with a verbatim span back to the source (the shared transform does this on
130
162
  every path). A block keeps one body's declarations from colliding with another's
131
163
  or with the component's, and contributes nothing to declaration output. `import`
132
164
  declarations of a `<script type="module">` body are hoisted to module level in
133
165
  front of the block, where TypeScript resolves them like any other import.
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'`).
134
176
  - Every TSRX compile error as a mapper diagnostic in the original file, printed as
135
177
  `error TSRX<number>`, in capitals like TypeScript's `TS2322`, so a TSRX error
136
178
  shows with its own code (`TSRX2002`). An error with a TypeScript code is `11`
@@ -148,6 +190,13 @@ mapper then sends that error alone, and a stub of the file's exports.
148
190
  `@tsrx/core/diagnostics`, and `tests/error-examples.test.js` checks that each
149
191
  shows exactly once on TypeScript 7, or that its known problem (with the issue
150
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.
151
200
  - While a file cannot be compiled, a stub that re-declares its exports as `any`
152
201
  (values and types), so importers keep resolving and the author sees exactly one
153
202
  error at the failing construct. `<style>` bodies are never TypeScript's concern