Source Map Validator

Build a utility that validates and processes source maps in various formats to ensure they meet the Source Map v3 specification requirements.

Overview

You need to create a source map validator that can:

1. Accept source maps as both JSON strings and JavaScript objects
2. Validate that source maps conform to the Source Map v3 specification
3. Parse and extract key information from source maps
4. Handle different source map bias modes when looking up positions

Requirements

Source Map Validation

The validator should check that a source map:

• Has a version property set to 3
• Contains required properties: sources (array), mappings (string)
• Has optional properties that are correctly typed if present: sourcesContent (array), names (array), file (string)

Source Map Parsing

The validator should:

• Accept source maps as either JSON strings or plain JavaScript objects
• Parse JSON strings into objects when needed
• Return a normalized object representation

Position Lookup

The validator should provide position lookup functionality with:

• Support for GREATEST_LOWER_BOUND bias (finds the closest mapping at or before the target)
• Support for LEAST_UPPER_BOUND bias (finds the closest mapping at or after the target)
• Ability to map generated code positions to original source positions

Test Cases

• Validates a source map object with version 3, sources array, and mappings string @test
• Rejects a source map with version 2 or missing version @test
• Rejects a source map missing required sources array @test
• Rejects a source map missing required mappings string @test
• Parses a source map from a JSON string successfully @test
• Parses a source map from an object successfully @test

Implementation

@generates

API

/**
 * Validates a source map against the Source Map v3 specification.
 *
 * @param {Object|string} sourceMap - The source map to validate (object or JSON string)
 * @returns {Object} Validation result with { valid: boolean, errors: string[] }
 */
function validateSourceMap(sourceMap) {
  // IMPLEMENTATION HERE
}

/**
 * Parses a source map from string or object format into a normalized object.
 *
 * @param {Object|string} sourceMap - The source map to parse
 * @returns {Object} The parsed source map object
 * @throws {Error} If the source map cannot be parsed
 */
function parseSourceMap(sourceMap) {
  // IMPLEMENTATION HERE
}

/**
 * Creates a source map consumer that can look up positions with different bias modes.
 *
 * @param {Object} sourceMap - The parsed source map object
 * @returns {Object} Consumer with lookup methods
 */
function createSourceMapConsumer(sourceMap) {
  // IMPLEMENTATION HERE
}

module.exports = {
  validateSourceMap,
  parseSourceMap,
  createSourceMapConsumer,
};

Dependencies { .dependencies }

@jridgewell/trace-mapping { .dependency }

Provides modern source map parsing and position lookup with support for GREATEST_LOWER_BOUND and LEAST_UPPER_BOUND bias modes.

istanbul-lib-source-maps { .dependency }

Provides source map support for code coverage, including validation and format handling capabilities.