@atlaspack/source-map 3.0.1-canary.4070

package/src/SourceMap.ts

@@ -0,0 +1,480 @@
+import type {
+  ParsedMap,
+  VLQMap,
+  SourceMapStringifyOptions,
+  IndexedMapping,
+  GenerateEmptyMapOptions,
+} from './types';
+
+import {partialVlqMapToSourceMap} from './utils';
+import {version} from '../package.json';
+
+export const SOURCE_MAP_VERSION = `atlaspack:${version}`;
+
+export default class SourceMap {
+  /**
+   * @private
+   */
+  sourceMapInstance: any;
+
+  /**
+   * @private
+   */
+  projectRoot: string;
+
+  /**
+   * Construct a SourceMap instance
+   *
+   * @param projectRoot root directory of the project, this is to ensure all source paths are relative to this path
+   */
+  constructor(projectRoot: string = '/', buffer?: Buffer) {
+    this.projectRoot = projectRoot;
+  }
+
+  // Use this to invalidate saved buffers, we don't check versioning at all in Rust
+  get libraryVersion(): string {
+    return SOURCE_MAP_VERSION;
+  }
+
+  /**
+   * Generates an empty map from the provided fileName and sourceContent
+   *
+   * @param sourceName path of the source file
+   * @param sourceContent content of the source file
+   * @param lineOffset an offset that gets added to the sourceLine index of each mapping
+   */
+  static generateEmptyMap({
+    projectRoot,
+    sourceName,
+    sourceContent,
+    lineOffset = 0,
+  }: GenerateEmptyMapOptions): SourceMap {
+    throw new Error(
+      'SourceMap.generateEmptyMap() must be implemented when extending SourceMap',
+    );
+  }
+
+  /**
+   * Generates an empty map from the provided fileName and sourceContent
+   *
+   * @param sourceName path of the source file
+   * @param sourceContent content of the source file
+   * @param lineOffset an offset that gets added to the sourceLine index of each mapping
+   */
+  addEmptyMap(
+    sourceName: string,
+    sourceContent: string,
+    lineOffset: number = 0,
+  ): SourceMap {
+    this.sourceMapInstance.addEmptyMap(sourceName, sourceContent, lineOffset);
+    return this;
+  }
+
+  /**
+   * Appends raw VLQ mappings to the sourcemaps
+   */
+  addVLQMap(
+    map: VLQMap,
+    lineOffset: number = 0,
+    columnOffset: number = 0,
+  ): SourceMap {
+    throw new Error(
+      'SourceMap.addVLQMap() must be implemented when extending SourceMap',
+    );
+  }
+
+  /**
+   * Appends another sourcemap instance to this sourcemap
+   *
+   * @param buffer the sourcemap buffer that should get appended to this sourcemap
+   * @param lineOffset an offset that gets added to the sourceLine index of each mapping
+   */
+  addSourceMap(sourcemap: SourceMap, lineOffset: number = 0): SourceMap {
+    throw new Error('Not implemented by child class');
+  }
+
+  /**
+   * Appends a buffer to this sourcemap
+   * Note: The buffer should be generated by this library
+   * @param buffer the sourcemap buffer that should get appended to this sourcemap
+   * @param lineOffset an offset that gets added to the sourceLine index of each mapping
+   */
+  addBuffer(buffer: Buffer, lineOffset: number = 0): SourceMap {
+    throw new Error('Not implemented by child class');
+  }
+
+  /**
+   * Appends a Mapping object to this sourcemap
+   * Note: line numbers start at 1 due to mozilla's source-map library
+   *
+   * @param mapping the mapping that should be appended to this sourcemap
+   * @param lineOffset an offset that gets added to the sourceLine index of each mapping
+   * @param columnOffset  an offset that gets added to the sourceColumn index of each mapping
+   */
+  addIndexedMapping(
+    mapping: IndexedMapping<string>,
+    lineOffset: number = 0,
+    columnOffset: number = 0,
+  ): void {
+    // Not sure if it'll be worth it to add this back to C++, wrapping it in an array probably doesn't do that much harm in JS?
+    // Also we barely use this function anyway...
+    this.addIndexedMappings([mapping], lineOffset, columnOffset);
+  }
+
+  _indexedMappingsToInt32Array(
+    mappings: Array<IndexedMapping<string>>,
+    lineOffset: number = 0,
+    columnOffset: number = 0,
+  ): Int32Array {
+    // Encode all mappings into a single typed array and make one call
+    // to C++ instead of one for each mapping to improve performance.
+    let mappingBuffer = new Int32Array(mappings.length * 6);
+    let sources: Map<string, number> = new Map();
+    let names: Map<string, number> = new Map();
+    let i = 0;
+    for (let mapping of mappings) {
+      let hasValidOriginal =
+        mapping.original !== undefined &&
+        typeof mapping.original.line === 'number' &&
+        !Number.isNaN(mapping.original.line) &&
+        typeof mapping.original.column === 'number' &&
+        !Number.isNaN(mapping.original.column);
+
+      mappingBuffer[i++] = mapping.generated.line + lineOffset - 1;
+      mappingBuffer[i++] = mapping.generated.column + columnOffset;
+      // @ts-expect-error TS18048
+      mappingBuffer[i++] = hasValidOriginal ? mapping.original.line - 1 : -1;
+      // @ts-expect-error TS18048
+      mappingBuffer[i++] = hasValidOriginal ? mapping.original.column : -1;
+
+      let sourceIndex = mapping.source ? sources.get(mapping.source) : -1;
+      if (sourceIndex == null && mapping.source) {
+        sourceIndex = this.addSource(mapping.source);
+        sources.set(mapping.source, sourceIndex);
+      }
+      // @ts-expect-error TS18048
+      mappingBuffer[i++] = sourceIndex;
+
+      let nameIndex = mapping.name ? names.get(mapping.name) : -1;
+      if (nameIndex == null && mapping.name) {
+        nameIndex = this.addName(mapping.name);
+        names.set(mapping.name, nameIndex);
+      }
+      // @ts-expect-error TS18048
+      mappingBuffer[i++] = nameIndex;
+    }
+
+    return mappingBuffer;
+  }
+
+  /**
+   * Appends an array of Mapping objects to this sourcemap
+   * This is useful when improving performance if a library provides the non-serialised mappings
+   *
+   * Note: This is only faster if they generate the serialised map lazily
+   * Note: line numbers start at 1 due to mozilla's source-map library
+   *
+   * @param mappings an array of mapping objects
+   * @param lineOffset an offset that gets added to the sourceLine index of each mapping
+   * @param columnOffset  an offset that gets added to the sourceColumn index of each mapping
+   */
+  addIndexedMappings(
+    mappings: Array<IndexedMapping<string>>,
+    lineOffset: number = 0,
+    columnOffset: number = 0,
+  ): SourceMap {
+    let mappingBuffer = this._indexedMappingsToInt32Array(
+      mappings,
+      lineOffset,
+      columnOffset,
+    );
+    this.sourceMapInstance.addIndexedMappings(mappingBuffer);
+    return this;
+  }
+
+  /**
+   * Appends a name to the sourcemap
+   *
+   * @param name the name that should be appended to the names array
+   * @returns the index of the added name in the names array
+   */
+  addName(name: string): number {
+    return this.sourceMapInstance.addName(name);
+  }
+
+  /**
+   * Appends an array of names to the sourcemap's names array
+   *
+   * @param names an array of names to add to the sourcemap
+   * @returns an array of indexes of the names in the sourcemap's names array, has the same order as the provided names array
+   */
+  addNames(names: Array<string>): Array<number> {
+    return names.map((n) => this.addName(n));
+  }
+
+  /**
+   * Appends a source to the sourcemap's sources array
+   *
+   * @param source a filepath that should be appended to the sources array
+   * @returns the index of the added source filepath in the sources array
+   */
+  addSource(source: string): number {
+    return this.sourceMapInstance.addSource(source);
+  }
+
+  /**
+   * Appends an array of sources to the sourcemap's sources array
+   *
+   * @param sources an array of filepaths which should sbe appended to the sources array
+   * @returns an array of indexes of the sources that have been added to the sourcemap, returned in the same order as provided in the argument
+   */
+  addSources(sources: Array<string>): Array<number> {
+    return sources.map((s) => this.addSource(s));
+  }
+
+  /**
+   * Get the index in the sources array for a certain source file filepath
+   *
+   * @param source the filepath of the source file
+   */
+  getSourceIndex(source: string): number {
+    return this.sourceMapInstance.getSourceIndex(source);
+  }
+
+  /**
+   * Get the source file filepath for a certain index of the sources array
+   *
+   * @param index the index of the source in the sources array
+   */
+  getSource(index: number): string {
+    return this.sourceMapInstance.getSource(index);
+  }
+
+  /**
+   * Get a list of all sources
+   */
+  getSources(): Array<string> {
+    return this.sourceMapInstance.getSources();
+  }
+
+  /**
+   * Set the sourceContent for a certain file
+   * this is optional and is only recommended for files that we cannot read in at the end when we serialise the sourcemap
+   *
+   * @param sourceName the path of the sourceFile
+   * @param sourceContent the content of the sourceFile
+   */
+  setSourceContent(sourceName: string, sourceContent: string): void {
+    return this.sourceMapInstance.setSourceContentBySource(
+      sourceName,
+      sourceContent,
+    );
+  }
+
+  /**
+   * Get the content of a source file if it is inlined as part of the source-map
+   *
+   * @param sourceName filename
+   */
+  getSourceContent(sourceName: string): string | null {
+    return this.sourceMapInstance.getSourceContentBySource(sourceName);
+  }
+
+  /**
+   * Get a list of all sources
+   */
+  getSourcesContent(): Array<string | null> {
+    return this.sourceMapInstance.getSourcesContent();
+  }
+
+  /**
+   * Get a map of the source and it's corresponding source content
+   */
+  getSourcesContentMap(): {[key: string]: string | null} {
+    let sources = this.getSources();
+    let sourcesContent = this.getSourcesContent();
+    let results: {[key: string]: string | null} = {};
+    for (let i = 0; i < sources.length; i++) {
+      results[sources[i]] = sourcesContent[i] || null;
+    }
+    return results;
+  }
+
+  /**
+   * Get the index in the names array for a certain name
+   *
+   * @param name the name you want to find the index of
+   */
+  getNameIndex(name: string): number {
+    return this.sourceMapInstance.getNameIndex(name);
+  }
+
+  /**
+   * Get the name for a certain index of the names array
+   *
+   * @param index the index of the name in the names array
+   */
+  getName(index: number): string {
+    return this.sourceMapInstance.getName(index);
+  }
+
+  /**
+   * Get a list of all names
+   */
+  getNames(): Array<string> {
+    return this.sourceMapInstance.getNames();
+  }
+
+  /**
+   * Get a list of all mappings
+   */
+  getMappings(): Array<IndexedMapping<number>> {
+    return this.sourceMapInstance.getMappings();
+  }
+
+  /**
+   * Convert a Mapping object that uses indexes for name and source to the actual value of name and source
+   *
+   * Note: This is only used internally, should not be used externally and will probably eventually get
+   * handled directly in C++ for improved performance
+   *
+   * @param index the Mapping that should get converted to a string-based Mapping
+   */
+  indexedMappingToStringMapping(
+    mapping: IndexedMapping<number>,
+  ): IndexedMapping<string> | null {
+    if (!mapping) return mapping;
+
+    if (mapping.source != null && mapping.source > -1) {
+      // @ts-expect-error TS2322
+      mapping.source = this.getSource(mapping.source);
+    }
+
+    if (mapping.name != null && mapping.name > -1) {
+      // @ts-expect-error TS2322
+      mapping.name = this.getName(mapping.name);
+    }
+
+    // @ts-expect-error TS2322
+    return mapping;
+  }
+
+  /**
+   * Remaps original positions from this map to the ones in the provided map
+   *
+   * This works by finding the closest generated mapping in the provided map
+   * to original mappings of this map and remapping those to be the original
+   * mapping of the provided map.
+   *
+   * @param buffer exported SourceMap as a buffer
+   */
+  extends(buffer: Buffer | SourceMap): SourceMap {
+    throw new Error('Should be implemented by extending');
+  }
+
+  /**
+   * Returns an object with mappings, sources and names
+   * This should only be used for tests, debugging and visualising sourcemaps
+   *
+   * Note: This is a fairly slow operation
+   */
+  getMap(): ParsedMap {
+    return {
+      mappings: this.getMappings(),
+      sources: this.getSources(),
+      sourcesContent: this.getSourcesContent(),
+      names: this.getNames(),
+    };
+  }
+
+  /**
+   * Searches through the sourcemap and returns a mapping that is close to the provided generated line and column
+   *
+   * @param line the line in the generated code (starts at 1)
+   * @param column the column in the generated code (starts at 0)
+   */
+  findClosestMapping(
+    line: number,
+    column: number,
+  ): IndexedMapping<string> | null {
+    let mapping = this.sourceMapInstance.findClosestMapping(line - 1, column);
+    if (mapping) {
+      let v = this.indexedMappingToStringMapping(mapping);
+      return v;
+    } else {
+      return null;
+    }
+  }
+
+  /**
+   * Offset mapping lines from a certain position
+   *
+   * @param line the line in the generated code (starts at 1)
+   * @param lineOffset the amount of lines to offset mappings by
+   */
+  offsetLines(line: number, lineOffset: number): void {
+    if (line < 1 || line + lineOffset < 1) {
+      throw new Error('Line has to be positive');
+    }
+
+    if (lineOffset === 0) {
+      return;
+    }
+
+    this.sourceMapInstance.offsetLines(line - 1, lineOffset);
+  }
+
+  /**
+   * Offset mapping columns from a certain position
+   *
+   * @param line the line in the generated code (starts at 1)
+   * @param column the column in the generated code (starts at 0)
+   * @param columnOffset the amount of columns to offset mappings by
+   */
+  offsetColumns(line: number, column: number, columnOffset: number): void {
+    if (line < 1 || column < 0 || column + columnOffset < 0) {
+      throw new Error('Line and Column has to be positive');
+    }
+
+    if (columnOffset === 0) {
+      return;
+    }
+
+    this.sourceMapInstance.offsetColumns(line - 1, column, columnOffset);
+  }
+
+  /**
+   * Returns a buffer that represents this sourcemap, used for caching
+   */
+  toBuffer(): Buffer {
+    return this.sourceMapInstance.toBuffer();
+  }
+
+  /**
+   * Returns a serialised map using VLQ Mappings
+   */
+  toVLQ(): VLQMap {
+    return this.sourceMapInstance.toVLQ();
+  }
+
+  /**
+   * A function that has to be called at the end of the SourceMap's lifecycle to ensure all memory and native bindings get de-allocated
+   */
+  delete() {
+    throw new Error(
+      'SourceMap.delete() must be implemented when extending SourceMap',
+    );
+  }
+
+  /**
+   * Returns a serialised map
+   *
+   * @param options options used for formatting the serialised map
+   */
+  stringify(options: SourceMapStringifyOptions): Promise<string | VLQMap> {
+    return partialVlqMapToSourceMap(this.toVLQ(), {
+      ...options,
+      rootDir: this.projectRoot || options.rootDir,
+    });
+  }
+}

package/src/node.ts

@@ -0,0 +1,116 @@
+import type {VLQMap, GenerateEmptyMapOptions} from './types';
+import SourceMap, {SOURCE_MAP_VERSION} from './SourceMap';
+import {SourceMap as AtlaspackSourceMap} from '@atlaspack/rust';
+
+// Re-export types for consumers
+export type * from './types';
+
+export default class NodeSourceMap extends SourceMap {
+  constructor(projectRoot: string = '/', buffer?: Buffer) {
+    super(projectRoot);
+    this.projectRoot = projectRoot;
+    this.sourceMapInstance = new AtlaspackSourceMap(projectRoot, buffer);
+  }
+
+  addVLQMap(
+    map: VLQMap,
+    lineOffset: number = 0,
+    columnOffset: number = 0,
+  ): SourceMap {
+    let {sourcesContent, sources = [], mappings, names = []} = map;
+    if (!sourcesContent) {
+      sourcesContent = sources.map(() => '');
+    } else {
+      sourcesContent = sourcesContent.map((content) =>
+        content ? content : '',
+      );
+    }
+    this.sourceMapInstance.addVLQMap(
+      mappings,
+      sources,
+      sourcesContent.map((content) => (content ? content : '')),
+      names,
+      lineOffset,
+      columnOffset,
+    );
+    return this;
+  }
+
+  addSourceMap(sourcemap: SourceMap, lineOffset: number = 0): SourceMap {
+    if (!(sourcemap.sourceMapInstance instanceof AtlaspackSourceMap)) {
+      throw new Error(
+        'The sourcemap provided to addSourceMap is not a valid sourcemap instance',
+      );
+    }
+
+    this.sourceMapInstance.addSourceMap(
+      sourcemap.sourceMapInstance,
+      lineOffset,
+    );
+    return this;
+  }
+
+  addBuffer(buffer: Buffer, lineOffset: number = 0): SourceMap {
+    let previousMap = new NodeSourceMap(this.projectRoot, buffer);
+    return this.addSourceMap(previousMap, lineOffset);
+  }
+
+  extends(input: Buffer | SourceMap): SourceMap {
+    // $FlowFixMe
+    let inputSourceMap: SourceMap = Buffer.isBuffer(input)
+      ? new NodeSourceMap(this.projectRoot, input)
+      : input;
+    this.sourceMapInstance.extends(inputSourceMap.sourceMapInstance);
+    return this;
+  }
+
+  getNames(): Array<string> {
+    return this.sourceMapInstance.getNames();
+  }
+
+  getSources(): Array<string> {
+    return this.sourceMapInstance.getSources();
+  }
+
+  delete() {}
+
+  static generateEmptyMap({
+    projectRoot,
+    sourceName,
+    sourceContent,
+    lineOffset = 0,
+  }: GenerateEmptyMapOptions): NodeSourceMap {
+    let map = new NodeSourceMap(projectRoot);
+    map.addEmptyMap(sourceName, sourceContent, lineOffset);
+    return map;
+  }
+
+  // This function exists to ensure that source map instances from (for example) @parcel/source-map
+  // are not used in place of @atlaspack/source-map, as from a JS point of view this is fine, but the
+  // underlying buffer may be different, and can cause build time errors.
+  static safeToBuffer<T extends SourceMap>(
+    sourceMap: T | null | undefined,
+  ): Buffer | undefined {
+    if (sourceMap == null || sourceMap == undefined) {
+      return undefined;
+    }
+
+    // We can't use instanceof here because if we're using a resolution for @parcel/source-map,
+    // it will be a different instance as it'll be a "copy" of @atlaspack/source-map
+    if (sourceMap.libraryVersion === SOURCE_MAP_VERSION) {
+      return sourceMap.toBuffer();
+    }
+
+    throw new Error(
+      'Source map is not an Atlaspack SourceMap (Expected version ' +
+        SOURCE_MAP_VERSION +
+        ', got ' +
+        sourceMap.libraryVersion +
+        ')',
+    );
+  }
+}
+
+export const init: Promise<void> = Promise.resolve();
+
+export type {SourceMap};

package/src/types.ts

@@ -0,0 +1,47 @@
+export interface MappingPosition {
+  line: number;
+  column: number;
+}
+
+export interface IndexedMapping<T> {
+  generated: MappingPosition;
+  original?: MappingPosition;
+  source?: T;
+  name?: T;
+}
+
+export interface ParsedMap {
+  sources: Array<string>;
+  names: Array<string>;
+  mappings: Array<IndexedMapping<number>>;
+  sourcesContent: Array<string | null>;
+}
+
+export interface VLQMap {
+  sources: readonly string[];
+  sourcesContent?: readonly (string | null)[];
+  names: readonly string[];
+  mappings: string;
+  version?: number;
+  file?: string;
+  sourceRoot?: string;
+}
+
+export interface SourceMapStringifyOptions {
+  file?: string;
+  sourceRoot?: string;
+  inlineSources?: boolean;
+  fs?: {readFile(path: string, encoding: string): Promise<string>};
+  format?: 'inline' | 'string' | 'object';
+  /**
+   * @private
+   */
+  rootDir?: string;
+}
+
+export interface GenerateEmptyMapOptions {
+  projectRoot: string;
+  sourceName: string;
+  sourceContent: string;
+  lineOffset?: number;
+}

package/src/utils.ts

@@ -0,0 +1,73 @@
+import type {VLQMap, SourceMapStringifyOptions} from './types';
+import path from 'path';
+
+export function generateInlineMap(map: string): string {
+  return `data:application/json;charset=utf-8;base64,${Buffer.from(map).toString('base64')}`;
+}
+
+export async function partialVlqMapToSourceMap(
+  map: VLQMap,
+  opts: SourceMapStringifyOptions,
+): Promise<VLQMap | string> {
+  let {fs, file, sourceRoot, inlineSources, rootDir, format = 'string'} = opts;
+
+  let resultMap = {
+    ...map,
+    sourcesContent: map.sourcesContent
+      ? map.sourcesContent.map((content) => {
+          if (content) {
+            return content;
+          } else {
+            return null;
+          }
+        })
+      : [],
+    version: 3,
+    file,
+    sourceRoot,
+  };
+
+  if (resultMap.sourcesContent.length < resultMap.sources.length) {
+    for (
+      let i = 0;
+      i <= resultMap.sources.length - resultMap.sourcesContent.length;
+      i++
+    ) {
+      resultMap.sourcesContent.push(null);
+    }
+  }
+
+  if (fs) {
+    resultMap.sourcesContent = await Promise.all(
+      resultMap.sourcesContent.map(
+        async (content, index): Promise<string | null> => {
+          let sourceName = map.sources[index];
+          // If sourceName starts with `..` it is outside rootDir, in this case we likely cannot access this file from the browser or packaged node_module
+          // Because of this we have to include the sourceContent to ensure you can always see the sourcecontent for each mapping.
+          if (!content && (inlineSources || sourceName.startsWith('..'))) {
+            try {
+              return await fs.readFile(
+                path.resolve(rootDir || '/', sourceName),
+                'utf-8',
+              );
+            } catch (e) {
+              /* empty */
+            }
+          }
+
+          return content;
+        },
+      ),
+    );
+  }
+
+  if (format === 'inline' || format === 'string') {
+    let stringifiedMap = JSON.stringify(resultMap);
+    if (format === 'inline') {
+      return generateInlineMap(stringifiedMap);
+    }
+    return stringifiedMap;
+  }
+
+  return resultMap;
+}