docs: add note about line discrepancies and returning source maps in …

…code transformers (#12566)

docs/CodeTransformation.md

@@ -123,6 +123,12 @@ Instead of having your custom transformer implement the `Transformer` interface
 
 Note that [ECMAScript module](ECMAScriptModules.md) support is indicated by the passed in `supports*` options. Specifically `supportsDynamicImport: true` means the transformer can return `import()` expressions, which is supported by both ESM and CJS. If `supportsStaticESM: true` it means top level `import` statements are supported and the code will be interpreted as ESM and not CJS. See [Node's docs](https://nodejs.org/api/esm.html#esm_differences_between_es_modules_and_commonjs) for details on the differences.
 
+:::tip
+
+Make sure `TransformedSource` contains a source map, so it is possible to report line information accurately in code coverage and test errors. Inline source maps also work but are slower.
+
+:::
+
 ### Examples
 
 ### TypeScript with type checking

website/versioned_docs/version-27.0/CodeTransformation.md

@@ -128,6 +128,12 @@ As can be seen, only `process` or `processAsync` is mandatory to implement, alth
 
 Note that [ECMAScript module](ECMAScriptModules.md) support is indicated by the passed in `supports*` options. Specifically `supportsDynamicImport: true` means the transformer can return `import()` expressions, which is supported by both ESM and CJS. If `supportsStaticESM: true` it means top level `import` statements are supported and the code will be interpreted as ESM and not CJS. See [Node's docs](https://nodejs.org/api/esm.html#esm_differences_between_es_modules_and_commonjs) for details on the differences.
 
+:::tip
+
+Make sure `TransformedSource` contains a source map, so it is possible to report line information accurately in code coverage and test errors. Inline source maps also work but are slower.
+
+:::
+
 ### Examples
 
 ### TypeScript with type checking

website/versioned_docs/version-27.1/CodeTransformation.md

@@ -128,6 +128,12 @@ As can be seen, only `process` or `processAsync` is mandatory to implement, alth
 
 Note that [ECMAScript module](ECMAScriptModules.md) support is indicated by the passed in `supports*` options. Specifically `supportsDynamicImport: true` means the transformer can return `import()` expressions, which is supported by both ESM and CJS. If `supportsStaticESM: true` it means top level `import` statements are supported and the code will be interpreted as ESM and not CJS. See [Node's docs](https://nodejs.org/api/esm.html#esm_differences_between_es_modules_and_commonjs) for details on the differences.
 
+:::tip
+
+Make sure `TransformedSource` contains a source map, so it is possible to report line information accurately in code coverage and test errors. Inline source maps also work but are slower.
+
+:::
+
 ### Examples
 
 ### TypeScript with type checking

website/versioned_docs/version-27.2/CodeTransformation.md

@@ -128,6 +128,12 @@ As can be seen, only `process` or `processAsync` is mandatory to implement, alth
 
 Note that [ECMAScript module](ECMAScriptModules.md) support is indicated by the passed in `supports*` options. Specifically `supportsDynamicImport: true` means the transformer can return `import()` expressions, which is supported by both ESM and CJS. If `supportsStaticESM: true` it means top level `import` statements are supported and the code will be interpreted as ESM and not CJS. See [Node's docs](https://nodejs.org/api/esm.html#esm_differences_between_es_modules_and_commonjs) for details on the differences.
 
+:::tip
+
+Make sure `TransformedSource` contains a source map, so it is possible to report line information accurately in code coverage and test errors. Inline source maps also work but are slower.
+
+:::
+
 ### Examples
 
 ### TypeScript with type checking

website/versioned_docs/version-27.4/CodeTransformation.md

@@ -128,6 +128,12 @@ As can be seen, only `process` or `processAsync` is mandatory to implement, alth
 
 Note that [ECMAScript module](ECMAScriptModules.md) support is indicated by the passed in `supports*` options. Specifically `supportsDynamicImport: true` means the transformer can return `import()` expressions, which is supported by both ESM and CJS. If `supportsStaticESM: true` it means top level `import` statements are supported and the code will be interpreted as ESM and not CJS. See [Node's docs](https://nodejs.org/api/esm.html#esm_differences_between_es_modules_and_commonjs) for details on the differences.
 
+:::tip
+
+Make sure `TransformedSource` contains a source map, so it is possible to report line information accurately in code coverage and test errors. Inline source maps also work but are slower.
+
+:::
+
 ### Examples
 
 ### TypeScript with type checking

website/versioned_docs/version-27.5/CodeTransformation.md

@@ -128,6 +128,12 @@ As can be seen, only `process` or `processAsync` is mandatory to implement, alth
 
 Note that [ECMAScript module](ECMAScriptModules.md) support is indicated by the passed in `supports*` options. Specifically `supportsDynamicImport: true` means the transformer can return `import()` expressions, which is supported by both ESM and CJS. If `supportsStaticESM: true` it means top level `import` statements are supported and the code will be interpreted as ESM and not CJS. See [Node's docs](https://nodejs.org/api/esm.html#esm_differences_between_es_modules_and_commonjs) for details on the differences.
 
+:::tip
+
+Make sure `TransformedSource` contains a source map, so it is possible to report line information accurately in code coverage and test errors. Inline source maps also work but are slower.
+
+:::
+
 ### Examples
 
 ### TypeScript with type checking