Add loader context to control the sourcemap loading

Author: jridgewell

README.md

@@ -21,9 +21,19 @@ npm install @ampproject/remapping
 ```typescript
 function remapping(
   map: SourceMap | SourceMap[],
-  loader: (file: string) => (SourceMap | null | undefined),
+  loader: (file: string, ctx: LoaderContext) => (SourceMap | null | undefined),
   options?: { excludeContent: boolean, decodedMappings: boolean }
 ): SourceMap;
+
+// LoaderContext gives the loader the importing sourcemap, and the ability to override the "source"
+// location (where nested sources are resolved relative to, and where an original source exists),
+// and the ability to override the "content" of an original sourcemap for inclusion in the output
+// sourcemap.
+type LoaderContext = {
+ readonly importer: string;
+ source: string;
+ content: string | null | undefined;
+}
 ```
 
 `remapping` takes the final output sourcemap, and a `loader` function. For every source file pointer
@@ -55,15 +65,20 @@ const minifiedTransformedMap = JSON.stringify({
 
 const remapped = remapping(
   minifiedTransformedMap,
-  (file) => {
+  (file, ctx) => {
 
     // The "transformed.js" file is an transformed file.
     if (file === 'transformed.js') {
+      // The root importer is empty.
+      console.assert(ctx.importer === '');
+
       return transformedMap;
     }
 
     // Loader will be called to load transformedMap's source file pointers as well.
     console.assert(file === 'helloworld.js');
+    // `transformed.js`'s sourcemap points into `helloworld.js`.
+    console.assert(ctx.importer === 'transformed.js');
     return null;
   }
 );
@@ -110,6 +125,76 @@ console.log(remapped);
 // };
 ```
 
+### Advanced control of the loading graph
+
+#### `source`
+
+The `source` property can overridden to any value to change the location of the current load. Eg,
+for an original source file, it allows us to change the filepath to the original source regardless
+of what the sourcemap source entry says. And for transformed files, it allows us to change the
+resolving location for nested sources files of the loaded sourcemap.
+
+```js
+const remapped = remapping(
+  minifiedTransformedMap,
+  (file, ctx) => {
+
+    if (file === 'transformed.js') {
+      // We pretend the transformed.js file actually exists in the 'src/' directory. When the nested
+      // source files are loaded, they will now be relative to `src/`.
+      ctx.source = 'src/transformed.js';
+      return transformedMap;
+    }
+
+    console.assert(file === 'src/helloworld.js');
+    // We could futher change the source of this original file, eg, to be inside a nested directory
+    // itself. This will be reflected in the remapped sourcemap.
+    ctx.source = 'src/nested/transformed.js';
+    return null;
+  }
+);
+
+console.log(remapped);
+// {
+//   …,
+//   sources: ['src/nested/helloworld.js'],
+// };
+```
+
+
+#### `content`
+
+The `content` property can be overridden when we encounter an original source file. Eg, this allows
+you to manually provide the source content of the file regardless of whether the `sourcesContent`
+field is present in the parent sourcemap. Or, it can be set to `null` to remove the source content.
+
+```js
+const remapped = remapping(
+  minifiedTransformedMap,
+  (file, ctx) => {
+
+    if (file === 'transformed.js') {
+      // transformedMap does not include a `sourcesContent` field, so usually the remapped sourcemap
+      // would not include any `sourcesContent` values.
+      return transformedMap;
+    }
+
+    console.assert(file === 'helloworld.js');
+    // We can read the file to provide the source content.
+    ctx.content = fs.readFileSync(file, 'utf8');
+    return null;
+  }
+);
+
+console.log(remapped);
+// {
+//   …,
+//   sourcesContent: [
+//     'console.log("Hello world!")',
+//   ],
+// };
+```
+
 ### Options
 
 #### excludeContent

src/build-source-map-tree.ts

@@ -3,7 +3,7 @@ import { TraceMap } from '@jridgewell/trace-mapping';
 import OriginalSource from './original-source';
 import { SourceMapTree } from './source-map-tree';
 
-import type { SourceMapInput, SourceMapLoader } from './types';
+import type { SourceMapInput, SourceMapLoader, LoaderContext } from './types';
 
 function asArray<T>(value: T | T[]): T[] {
   if (Array.isArray(value)) return value;
@@ -25,7 +25,7 @@ export default function buildSourceMapTree(
   input: SourceMapInput | SourceMapInput[],
   loader: SourceMapLoader
 ): SourceMapTree {
-  const maps = asArray(input).map((m) => new TraceMap(m));
+  const maps = asArray(input).map((m) => new TraceMap(m, ''));
   const map = maps.pop()!;
 
   for (let i = 0; i < maps.length; i++) {
@@ -37,35 +37,47 @@ export default function buildSourceMapTree(
     }
   }
 
-  let tree = build(map, loader);
+  let tree = build(map, '', loader);
   for (let i = maps.length - 1; i >= 0; i--) {
     tree = new SourceMapTree(maps[i], [tree]);
   }
   return tree;
 }
 
-function build(map: TraceMap, loader: SourceMapLoader): SourceMapTree {
+function build(map: TraceMap, importer: string, loader: SourceMapLoader): SourceMapTree {
   const { resolvedSources, sourcesContent } = map;
 
   const children = resolvedSources.map(
     (sourceFile: string | null, i: number): SourceMapTree | OriginalSource => {
-      const source = sourceFile || '';
+      // The loading context gives the loader more information about why this file is being loaded
+      // (eg, from which importer). It also allows the loader to override the location of the loaded
+      // sourcemap/original source, or to override the content in the sourcesContent field if it's
+      // an unmodified source file.
+      const ctx: LoaderContext = {
+        importer,
+        source: sourceFile || '',
+        content: undefined,
+      };
+
       // Use the provided loader callback to retrieve the file's sourcemap.
       // TODO: We should eventually support async loading of sourcemap files.
-      const sourceMap = loader(source);
+      const sourceMap = loader(ctx.source, ctx);
+
+      const { source, content } = ctx;
 
       // If there is no sourcemap, then it is an unmodified source file.
       if (!sourceMap) {
-        // The source file's actual contents must be included in the sourcemap
-        // (done when generating the sourcemap) for it to be included as a
-        // sourceContent in the output sourcemap.
-        const sourceContent = sourcesContent ? sourcesContent[i] : null;
+        // The contents of this unmodified source file can be overridden via the loader context,
+        // allowing it to be explicitly null or a string. If it remains undefined, we fall back to
+        // the importing sourcemap's `sourcesContent` field.
+        const sourceContent =
+          content !== undefined ? content : sourcesContent ? sourcesContent[i] : null;
         return new OriginalSource(source, sourceContent);
       }
 
       // Else, it's a real sourcemap, and we need to recurse into it to load its
       // source files.
-      return build(new TraceMap(sourceMap, source), loader);
+      return build(new TraceMap(sourceMap, source), source, loader);
     }
   );
 

src/types.ts

@@ -36,7 +36,16 @@ export interface SourceMapSegmentObject {
 
 export type SourceMapInput = string | RawSourceMap | DecodedSourceMap;
 
-export type SourceMapLoader = (file: string) => SourceMapInput | null | undefined;
+export type LoaderContext = {
+  readonly importer: string;
+  source: string;
+  content: string | null | undefined;
+};
+
+export type SourceMapLoader = (
+  file: string,
+  ctx: LoaderContext
+) => SourceMapInput | null | undefined;
 
 export type Options = {
   excludeContent?: boolean;

test/samples/sourceless-transform/test.ts

@@ -30,7 +30,7 @@ describe('source-less transform', () => {
     const remapped = remapping([minified, original], loader);
 
     expect(loader).toHaveBeenCalledTimes(1);
-    expect(loader).toHaveBeenCalledWith('source.ts');
+    expect(loader).toHaveBeenCalledWith('source.ts', expect.anything());
     expect(remapped.sources).toHaveLength(0);
     expect(remapped.mappings).toBe('');
   });