@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/src/mapper.js CHANGED
@@ -16,15 +16,11 @@ import {
16
16
  source_uses_platform_flag,
17
17
  } from '@tsrx/typescript-plugin/src/language.js';
18
18
  import { transform_tsrx } from '@tsrx/typescript-plugin/src/transform.js';
19
+ import { DIAGNOSTIC_SOURCE, MAPPER_CODES, TYPESCRIPT_CODE_PREFIX } from '@tsrx/core/diagnostics';
20
+ import { ignore_directives } from './diagnostic-directives.js';
19
21
  import { build_export_stub } from './export-stub.js';
20
- import {
21
- DIAGNOSTIC_CODE_COMPILE_ERROR,
22
- DIAGNOSTIC_CODE_INVALID_CONFIG,
23
- DIAGNOSTIC_CODE_NO_COMPILER,
24
- DIAGNOSTIC_CODE_USAGE_ERROR,
25
- DIAGNOSTIC_SOURCE,
26
- } from './protocol.js';
27
- import { to_span_mappings } from './span-mappings.js';
22
+ import { share_platform_globals } from './platform-globals.js';
23
+ import { to_span_mappings, to_verification_mappings } from './span-mappings.js';
28
24
 
29
25
  const require = createRequire(import.meta.url);
30
26
  const bare_package_specifier_pattern =
@@ -37,6 +33,7 @@ const bare_package_specifier_pattern =
37
33
  * @property {string} [compiler] Bare package specifier of the TSRX compiler. Takes precedence over `tsrx.compiler` in the tsconfig chain.
38
34
  * @property {'web' | 'ios' | 'android'} [platform] Platform for `import.meta.env.platform` flags. Takes precedence over `tsrx.platform`.
39
35
  * @property {boolean} [languageFeatures] `false` clears every editor feature bit while keeping spans for diagnostics (CLI-only projects).
36
+ * @property {boolean} [verificationMappings] `true` adds `verificationMappings` to each transform result: the transform's own diagnostics mappings, in Volar's shape and order, for command-line checkers. Off by default; TypeScript ignores the field.
40
37
  */
41
38
 
42
39
  /**
@@ -136,7 +133,7 @@ export function create_tsrx_content_mapper(context = {}) {
136
133
  return failure(state, file_name, content, {
137
134
  start: 0,
138
135
  length: 0,
139
- code: DIAGNOSTIC_CODE_INVALID_CONFIG,
136
+ code: MAPPER_CODES.INVALID_CONFIG,
140
137
  messageText: error_message(error),
141
138
  });
142
139
  }
@@ -144,7 +141,7 @@ export function create_tsrx_content_mapper(context = {}) {
144
141
  return failure(state, file_name, content, {
145
142
  start: 0,
146
143
  length: 0,
147
- code: DIAGNOSTIC_CODE_NO_COMPILER,
144
+ code: MAPPER_CODES.NO_COMPILER,
148
145
  messageText:
149
146
  `No TSRX compiler found for ${file_name}. Install a target compiler ` +
150
147
  '(for example @tsrx/react) next to the project, or select one with ' +
@@ -168,36 +165,62 @@ export function create_tsrx_content_mapper(context = {}) {
168
165
  return failure(state, file_name, content, {
169
166
  start: 0,
170
167
  length: 0,
171
- code: DIAGNOSTIC_CODE_INVALID_CONFIG,
168
+ code: MAPPER_CODES.INVALID_CONFIG,
172
169
  messageText: error_message(error),
173
170
  });
174
171
  }
175
172
 
176
173
  const result = transform_tsrx(compiler, file_name, content, { platform });
177
174
  if (result.fatalError) {
175
+ // The file has no generated code for TypeScript to check, so the error
176
+ // goes to TypeScript whatever its code.
178
177
  return failure(
179
178
  state,
180
179
  file_name,
181
180
  content,
182
- to_diagnostic(result.fatalError, content.length, DIAGNOSTIC_CODE_COMPILE_ERROR),
181
+ to_diagnostic(result.fatalError, content.length, MAPPER_CODES.COMPILE_ERROR),
183
182
  );
184
183
  }
185
184
  if (result.sourceAst) {
186
185
  state.lastGood.set(file_name, result.sourceAst);
187
186
  }
188
187
 
188
+ // The one generated output every consumer below reads, so that a rewrite of
189
+ // the text and its mappings reaches the spans, the directives and the
190
+ // verification mappings alike.
191
+ const generated = share_platform_globals(result.text, result.mappings);
189
192
  const language_features = state.options.languageFeatures !== false;
190
- const mappings = to_span_mappings(result.mappings, result.text, content, {
193
+ const mappings = to_span_mappings(generated.mappings, generated.text, content, {
191
194
  languageFeatures: language_features,
192
195
  });
193
- const diagnostics = result.errors.map((error) =>
194
- to_diagnostic(error, content.length, DIAGNOSTIC_CODE_USAGE_ERROR),
196
+ // Every error goes to TypeScript, even one with a TypeScript code: the
197
+ // generated code can lose the mistake (a repeated modifier, a rest
198
+ // parameter's `?`), and then TypeScript never reports it. Where TypeScript
199
+ // does, the directives hide its copy until the mapper's error is fixed.
200
+ // A warning doesn't go: TypeScript shows each of the mapper's diagnostics
201
+ // as an error, as the protocol has no severity, so `tsc` would fail on
202
+ // code that compiles, and its directive would hide TypeScript's own
203
+ // errors in the statement that holds it.
204
+ const errors = result.errors.filter((error) => error.severity !== 'warning');
205
+ const diagnostics = errors.map((error) =>
206
+ to_diagnostic(error, content.length, MAPPER_CODES.USAGE_ERROR),
207
+ );
208
+ const diagnosticDirectives = ignore_directives(
209
+ errors,
210
+ result.sourceAst,
211
+ generated.mappings,
212
+ content.length,
213
+ generated.text.length,
195
214
  );
196
215
  return {
197
- text: result.text,
216
+ text: generated.text,
198
217
  extension: '.tsx',
199
218
  mappings,
200
219
  ...(diagnostics.length > 0 ? { diagnostics } : null),
220
+ ...(diagnosticDirectives ? { diagnosticDirectives } : null),
221
+ ...(state.options.verificationMappings
222
+ ? { verificationMappings: to_verification_mappings(generated.mappings) }
223
+ : null),
201
224
  };
202
225
  }
203
226
 
@@ -315,6 +338,7 @@ export function create_tsrx_content_mapper(context = {}) {
315
338
  extension: '.ts',
316
339
  mappings: [],
317
340
  diagnostics: [clamp_diagnostic(diagnostic, content.length)],
341
+ ...(state.options.verificationMappings ? { verificationMappings: [] } : null),
318
342
  };
319
343
  }
320
344
 
@@ -337,7 +361,7 @@ export function validate_options(raw) {
337
361
  optionDiagnostics.push({
338
362
  path: [],
339
363
  messageText: 'Content mapper options must be an object.',
340
- code: DIAGNOSTIC_CODE_INVALID_CONFIG,
364
+ code: MAPPER_CODES.INVALID_CONFIG,
341
365
  });
342
366
  return { options, optionDiagnostics };
343
367
  }
@@ -352,7 +376,7 @@ export function validate_options(raw) {
352
376
  optionDiagnostics.push({
353
377
  path: [key],
354
378
  messageText: '"compiler" must be a bare package specifier such as "@tsrx/react".',
355
- code: DIAGNOSTIC_CODE_INVALID_CONFIG,
379
+ code: MAPPER_CODES.INVALID_CONFIG,
356
380
  });
357
381
  }
358
382
  break;
@@ -363,18 +387,19 @@ export function validate_options(raw) {
363
387
  optionDiagnostics.push({
364
388
  path: [key],
365
389
  messageText: '"platform" must be "web", "ios", or "android".',
366
- code: DIAGNOSTIC_CODE_INVALID_CONFIG,
390
+ code: MAPPER_CODES.INVALID_CONFIG,
367
391
  });
368
392
  }
369
393
  break;
370
394
  case 'languageFeatures':
395
+ case 'verificationMappings':
371
396
  if (typeof value === 'boolean') {
372
- options.languageFeatures = value;
397
+ options[key] = value;
373
398
  } else {
374
399
  optionDiagnostics.push({
375
400
  path: [key],
376
- messageText: '"languageFeatures" must be a boolean.',
377
- code: DIAGNOSTIC_CODE_INVALID_CONFIG,
401
+ messageText: `"${key}" must be a boolean.`,
402
+ code: MAPPER_CODES.INVALID_CONFIG,
378
403
  });
379
404
  }
380
405
  break;
@@ -382,17 +407,23 @@ export function validate_options(raw) {
382
407
  optionDiagnostics.push({
383
408
  path: [key],
384
409
  messageText: `Unknown content mapper option "${key}".`,
385
- code: DIAGNOSTIC_CODE_INVALID_CONFIG,
410
+ code: MAPPER_CODES.INVALID_CONFIG,
386
411
  });
387
412
  }
388
413
  }
389
414
  return { options, optionDiagnostics };
390
415
  }
391
416
 
417
+ const TSRX_CODE = /^TSRX(\d+)$/;
418
+ const TYPESCRIPT_CODE = /^TS(\d+)$/;
419
+
392
420
  /**
393
421
  * Translate a compiler `CompileError` into a mapper diagnostic in original
394
- * offsets. Coded errors keep their string code in the message and derive a
395
- * stable numeric code from it; uncoded ones use `fallback_code`.
422
+ * offsets. TypeScript shows the mapper's diagnostics as `TSRX<number>`, so a
423
+ * TSRX code goes as its number (`TSRX2002` → `2002`) and a TypeScript code as
424
+ * `TYPESCRIPT_CODE_PREFIX` then its number (`TS1005` → `111005`), which keeps
425
+ * the code in the message too. An error without either uses `fallback_code`
426
+ * and keeps any other code in the message.
396
427
  * @param {CompileError} error
397
428
  * @param {number} content_length
398
429
  * @param {number} fallback_code
@@ -401,37 +432,25 @@ export function validate_options(raw) {
401
432
  export function to_diagnostic(error, content_length, fallback_code) {
402
433
  const start = typeof error.pos === 'number' ? error.pos : 0;
403
434
  const end = typeof error.end === 'number' && error.end > start ? error.end : start + 1;
404
- const code =
405
- typeof error.code === 'string' && error.code ? numeric_code(error.code) : fallback_code;
435
+ const code = typeof error.code === 'string' ? error.code : '';
436
+ const tsrx = TSRX_CODE.exec(code);
437
+ const typescript = TYPESCRIPT_CODE.exec(code);
406
438
  const message = String(error.message ?? error);
407
439
  return clamp_diagnostic(
408
440
  {
409
441
  start,
410
442
  length: end - start,
411
- code,
412
- messageText:
413
- typeof error.code === 'string' && error.code ? `${message} [${error.code}]` : message,
443
+ code: tsrx
444
+ ? Number(tsrx[1])
445
+ : typescript
446
+ ? Number(`${TYPESCRIPT_CODE_PREFIX}${typescript[1]}`)
447
+ : fallback_code,
448
+ messageText: code && !tsrx ? `${message} [${code}]` : message,
414
449
  },
415
450
  content_length,
416
451
  );
417
452
  }
418
453
 
419
- /**
420
- * Stable numeric code for a TSRX string diagnostic code (FNV-1a 32-bit,
421
- * folded into the 10000..99999 range so it never collides with the fixed
422
- * codes below 10000).
423
- * @param {string} code
424
- * @returns {number}
425
- */
426
- export function numeric_code(code) {
427
- let hash = 0x811c9dc5;
428
- for (let index = 0; index < code.length; index++) {
429
- hash ^= code.charCodeAt(index);
430
- hash = Math.imul(hash, 0x01000193);
431
- }
432
- return 10000 + ((hash >>> 0) % 90000);
433
- }
434
-
435
454
  /**
436
455
  * @param {MapperDiagnostic} diagnostic
437
456
  * @param {number} content_length
@@ -0,0 +1,76 @@
1
+ /** @import {CodeMapping} from '@tsrx/core/types' */
2
+
3
+ import fs from 'node:fs';
4
+ import { fileURLToPath } from 'node:url';
5
+
6
+ /**
7
+ * The editor-only `ImportMetaEnv` / `ImportMeta` globals that `withPlatformTypes`
8
+ * in `@tsrx/core` appends to the generated TSX of a module that keeps a platform
9
+ * flag, exactly as it prints them, with the three flag value types captured.
10
+ */
11
+ const PLATFORM_GLOBALS =
12
+ /\ndeclare global \{\n\tinterface ImportMetaEnv \{\n\t\treadonly platform: string & \{\n\t\t\treadonly web: (true|false|boolean);\n\t\t\treadonly ios: (true|false|boolean);\n\t\t\treadonly android: (true|false|boolean);\n\t\t\};\n\t\}\n\tinterface ImportMeta \{\n\t\treadonly \[key: `env\$\{string\}`\]: ImportMetaEnv;\n\t\}\n\}\n/;
13
+
14
+ /** The `platform-globals/` file that declares each set of flag value types. */
15
+ const PLATFORM_FILES = new Map([
16
+ ['true,false,false', 'web'],
17
+ ['false,true,false', 'ios'],
18
+ ['false,false,true', 'android'],
19
+ ['boolean,boolean,boolean', 'unconfigured'],
20
+ ]);
21
+
22
+ /** @type {Map<string, string | null>} */
23
+ const files = new Map();
24
+
25
+ /**
26
+ * Replace a module's copy of the platform globals in its generated TSX with a
27
+ * reference to the shared file that declares the same globals. Native
28
+ * TypeScript merges every module's copy into one `ImportMeta` and reports the
29
+ * repeated index signature (TS2374), and declaration output keeps every
30
+ * `declare global` block. The shared file is in the program once, and
31
+ * declaration output drops a `/// <reference path>` directive.
32
+ *
33
+ * The copy is blanked in place, and the directive goes at the start of the
34
+ * text, where TypeScript reads it, so every generated offset moves by its
35
+ * length. A directive is not an import: organize imports and auto-import still
36
+ * see only the module's own imports, and TypeScript 7 maps their edits only
37
+ * when the last of them is the module's last import. Text without the exact
38
+ * copy (another TSRX version, a third-party compiler), or that starts with a
39
+ * hashbang, comes back unchanged.
40
+ * @param {string} text
41
+ * @param {readonly CodeMapping[]} mappings
42
+ * @returns {{ text: string, mappings: readonly CodeMapping[] }}
43
+ */
44
+ export function share_platform_globals(text, mappings) {
45
+ const match = PLATFORM_GLOBALS.exec(text);
46
+ const name = match && PLATFORM_FILES.get(match.slice(1).join(','));
47
+ const file = name && !text.startsWith('#!') ? platform_globals_file(name) : null;
48
+ if (!match || !file) return { text, mappings };
49
+ const directive = `/// <reference path="${file}" />\n`;
50
+ const end = match.index + match[0].length;
51
+ return {
52
+ text: `${directive}${text.slice(0, match.index)}${match[0].replace(/[^\n]/g, ' ')}${text.slice(end)}`,
53
+ mappings: mappings.map((mapping) => ({
54
+ ...mapping,
55
+ generatedOffsets: mapping.generatedOffsets.map((offset) => offset + directive.length),
56
+ })),
57
+ };
58
+ }
59
+
60
+ /**
61
+ * The path of a `platform-globals/` file, with forward slashes. The directory
62
+ * sits next to `src/` and `dist/`, so one relative URL serves both. A file
63
+ * missing from the installed package, or a path a directive cannot quote,
64
+ * leaves the copy in place.
65
+ * @param {string} name
66
+ * @returns {string | null}
67
+ */
68
+ function platform_globals_file(name) {
69
+ let file = files.get(name);
70
+ if (file === undefined) {
71
+ const path = fileURLToPath(new URL(`../platform-globals/${name}.d.cts`, import.meta.url));
72
+ file = fs.existsSync(path) && !/["\r\n]/.test(path) ? path.replace(/\\/g, '/') : null;
73
+ files.set(name, file);
74
+ }
75
+ return file;
76
+ }
package/src/protocol.js CHANGED
@@ -39,21 +39,13 @@ export const SpanMapFeature = /** @type {const} */ ({
39
39
  All: (1 << 20) - 1,
40
40
  });
41
41
 
42
- /** Diagnostic-directive policies (unused by TSRX today; kept for completeness). */
42
+ /**
43
+ * Diagnostic-directive policies: `Ignore` hides TypeScript's errors in a
44
+ * generated range; `Expect` also reports a diagnostic of the mapper's when
45
+ * there are none there.
46
+ */
43
47
  export const DiagnosticDirectivePolicy = /** @type {const} */ ({ Ignore: 0, Expect: 1 });
44
48
 
45
- /** Prefix for mapper-authored diagnostics: `error tsrx(1000): ...`. */
46
- export const DIAGNOSTIC_SOURCE = 'tsrx';
47
-
48
- /** Numeric code for a fatal compile error (the file could not be transformed). */
49
- export const DIAGNOSTIC_CODE_COMPILE_ERROR = 1000;
50
- /** Numeric code for a usage error that carries no string code. */
51
- export const DIAGNOSTIC_CODE_USAGE_ERROR = 1001;
52
- /** Numeric code when no TSRX compiler can be resolved for a file. */
53
- export const DIAGNOSTIC_CODE_NO_COMPILER = 1002;
54
- /** Numeric code when the project's TSRX configuration is invalid. */
55
- export const DIAGNOSTIC_CODE_INVALID_CONFIG = 1003;
56
-
57
49
  /**
58
50
  * @typedef {[
59
51
  * generatedStart: number,
@@ -65,6 +57,23 @@ export const DIAGNOSTIC_CODE_INVALID_CONFIG = 1003;
65
57
  * ]} SpanMapping
66
58
  */
67
59
 
60
+ /**
61
+ * Not part of the TypeScript 7 protocol: what the `verificationMappings` mapper
62
+ * option adds to a transform result for command-line checkers. Every compiler
63
+ * mapping marked for diagnostics, in Volar's `CodeMapping` shape and in the
64
+ * transform's order, so `new SourceMap(verificationMappings).toSourceRange(start,
65
+ * end, true)` from `@volar/source-map` maps a diagnostic as `tsrx-tsc` does.
66
+ * Points (offsets with zero length) belong to the mapping they are listed in.
67
+ * Empty when the transform has a mapping whose verification is a `shouldReport`
68
+ * callback, which can't be serialized.
69
+ * @typedef {object} VerificationMapping
70
+ * @property {number[]} sourceOffsets
71
+ * @property {number[]} generatedOffsets
72
+ * @property {number[]} lengths
73
+ * @property {number[]} generatedLengths
74
+ * @property {{ verification: true }} data
75
+ */
76
+
68
77
  /**
69
78
  * @typedef {object} MapperDiagnostic
70
79
  * @property {number} start Offset into the original text (UTF-16 code units).
@@ -80,10 +89,29 @@ export const DIAGNOSTIC_CODE_INVALID_CONFIG = 1003;
80
89
  * @property {SpanMapping[]} mappings
81
90
  */
82
91
 
92
+ /**
93
+ * @typedef {[
94
+ * originalStart: number,
95
+ * originalLength: number,
96
+ * generatedStart: number,
97
+ * generatedEnd: number,
98
+ * policy: 0 | 1,
99
+ * unusedExpectDirectiveIndex?: number,
100
+ * ]} DiagnosticDirective
101
+ */
102
+
103
+ /**
104
+ * @typedef {object} DiagnosticDirectives
105
+ * @property {Array<{ code: number, messageText: string }>} unusedExpectDirectiveDiagnostics What an `Expect` directive reports when TypeScript has no error in its range.
106
+ * @property {DiagnosticDirective[]} directives
107
+ */
108
+
83
109
  /**
84
110
  * @typedef {MappedOutput & {
85
111
  * diagnostics?: MapperDiagnostic[],
112
+ * diagnosticDirectives?: DiagnosticDirectives,
86
113
  * supplemental?: MappedOutput[],
114
+ * verificationMappings?: VerificationMapping[],
87
115
  * }} TransformResult
88
116
  */
89
117
 
package/src/rpc.js CHANGED
@@ -9,6 +9,8 @@
9
9
  * it from their own entry file.
10
10
  */
11
11
 
12
+ import { Console } from 'node:console';
13
+
12
14
  /**
13
15
  * @typedef {{ jsonrpc: '2.0', id?: number | string | null, method: string, params?: unknown }} RequestMessage
14
16
  */
@@ -119,8 +121,15 @@ export function run_mapper_server(mapper, streams = {}) {
119
121
 
120
122
  /**
121
123
  * Route every console method to stderr so stray logging (from a target
122
- * compiler, for example) can never corrupt the protocol stream on stdout.
124
+ * compiler, for example) can never corrupt the protocol stream on stdout: not
125
+ * only `log` but `dir`, `table`, `trace`, `group` and the rest write there, so
126
+ * each takes the method of a console whose stdout is stderr.
123
127
  */
124
128
  export function redirect_console_to_stderr() {
125
- console.log = console.info = console.warn = console.debug = (...args) => console.error(...args);
129
+ const to_stderr = new Console({ stdout: process.stderr, stderr: process.stderr });
130
+ for (const [name, method] of Object.entries(to_stderr)) {
131
+ if (typeof method === 'function') {
132
+ /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (console))[name] = method;
133
+ }
134
+ }
126
135
  }