🥮 mooncakes.io

moon_sourcemap

A pure MoonBit ECMA-426 Source Map library and command-line toolkit.

source-map
ecma-426
debugging
symbolization
vlq
moon add shop1111/moon_sourcemap@0.1.1
Download zip
Author
Version
0.1.1
License
Apache-2.0
Repository
Last updated
5 hours ago
Downloads
6

Dependencies

README

#MoonSourceMap

English · 中文

MoonSourceMap 是一个纯 MoonBit 的 ECMA-426 Source Map 工具链： 解析、生成、校验、双向查询、Index Map 展平、两级映射组合和栈帧符号化， 并提供适合 CI 使用的命令行程序。

它不依赖 JavaScript Source Map 运行库，核心库可在 wasm、wasm-gc、 JavaScript 和 native 四个稳定后端构建。

#中文

#五分钟上手

安装依赖并验证：

moon update
moon test --target all --deny-warn
moon run --target native cmd/main -- validate examples/demo.min.js.map

查询生成位置（行列均为零基）：

moon run --target native cmd/main -- \
  lookup examples/demo.min.js.map --line 0 --column 4 --format json

输出会恢复到 ../src/demo.ts:0:0 greet。再用同一张 map 符号化栈帧：

moon run --target native cmd/main -- \
  symbolize examples/demo.min.js.map examples/frames.txt

#库 API

下面的片段由 moon test 检查：

///|
test "parse, validate and query" {
  let json =
    #|{"version":3,"sources":["src/main.ts"],"names":["main"],"mappings":"AAAAA"}
  let document = @moon_sourcemap.parse_document(json)
  assert_false(
    @moon_sourcemap.diagnostics_have_errors(@moon_sourcemap.validate(document)),
  )
  let decoded = @moon_sourcemap.decode_document(document)
  let mapping = @moon_sourcemap.original_position_for(
    decoded,
    generated=@moon_sourcemap.Position::new(line=0, column=0),
  )
  assert_true(mapping is Some(_))
}

Builder 会在生产映射时检查生成位置顺序，并自动维护 sources 与 names 表：

///|
test "build a map" {
  let builder = @moon_sourcemap.SourceMapBuilder::new(file="bundle.js")
  let source = builder.add_source(
    url="src/main.ts",
    content="export const answer = 42",
  )
  builder.add_mapping(
    generated=@moon_sourcemap.Position::new(line=0, column=0),
    source_index=source,
    original_line=0,
    original_column=0,
    name="answer",
  )
  let document = builder.build()
  assert_eq(document.version, 3)
}

主要公开接口：

能力API
JSON 双向转换parse_document, encode_document
mappings 编解码decode_mappings, encode_mappings
严格校验validate, validate_json, Diagnostic
位置查询original_position_for, get_original_positions, generated_positions_for
批量索引SourceMapConsumer
Index Mapdecode_document, flatten
生成SourceMapBuilder, encode_decoded
两级构建compose, compose_with_options
栈帧恢复parse_stack_frame, symbolize, symbolize_frame
规范化变换canonicalize, slice_generated, concatenate

#CLI

moon-sourcemap validate <map> [--format text|json]
moon-sourcemap inspect <map> [--format text|json]
moon-sourcemap lookup <map> --line N --column N [--bias glb|lub | --all] [--strict]
moon-sourcemap flatten <map> -o <output>
moon-sourcemap compose <outer> <inner> -o <output>
moon-sourcemap symbolize <map> <frames> [--context N] [--strict] [--format text|json]

退出码固定为：

  • 0：成功；
  • 1：用法或 I/O 错误；
  • 2：Source Map JSON、结构或 mappings 非法；
  • 3：--strict 模式下没有找到映射。

#与通用 VLQ 包的区别

VLQ 只是 Source Map mappings 字段的整数编码。MoonSourceMap 在此之上提供：

  • ECMA-426 文档与 Index Map 数据模型；
  • source/name 增量状态、索引边界和映射顺序校验；
  • GLB/LUB 与反向查询；
  • section 偏移、展平和多级构建组合；
  • sourcesContent、ignore list、符号名和栈帧恢复；
  • 结构化诊断、确定性序列化及 CI 退出码。

因此相邻的通用 VLQ 包可以作为底层编码器，但不能替代本项目。

#合规与范围

本项目依据公开 ECMA-426 标准原创实现，没有移植其他 Source Map 运行库。third_party/tc39-source-map-tests 记录了所选官方数据用例的 来源、固定 revision 和 BSD 许可；产品代码使用 Apache-2.0。

v0.1 不实现仍在演进的 Scopes、Range Mappings、Debug ID 与 Env 提案。坐标在库和 CLI 中统一为零基，避免隐式换算。

#当前里程碑

当前 0.1.1 已完成核心库、六命令 CLI、源码上下文、多文件 map registry、 结构质量报告、TC39 选例、四后端 CI、示例和发布元数据。生产 MoonBit 有效代码由 CI 强制保持在 4000–4499 行，不把测试、空行、纯注释、示例 或第三方数据计入。

#English

MoonSourceMap is an original, pure-MoonBit implementation of ECMA-426. It parses and emits regular and index source maps, validates mapping state, supports GLB/LUB and reverse queries, composes build stages, and symbolizes generated stack frames. ECMA-426 GetOriginalPositions is available through get_original_positions and lookup --all, including generated-only entries at duplicate generated positions.

Run the complete verification matrix:

moon fmt --check
moon check --target all --deny-warn
moon build --target all --deny-warn
moon test --target all --deny-warn
moon info
git diff --exit-code
moon package

The CLI uses stable JSON output and deterministic exit codes, so validate, inspect, lookup, flatten, compose, and symbolize can be used directly in CI.

#License

MoonSourceMap is licensed under Apache-2.0. Selected test data attribution is documented separately under third_party/tc39-source-map-tests.

#
SourceMapError

source
pub(all) suberror SourceMapError {
  InvalidJson(message~ : String)
  InvalidField(path~ : String, message~ : String)
  InvalidVlq(offset~ : Int, message~ : String)
  InvalidMappings(line~ : Int, segment~ : Int, offset~ : Int, message~ : String)
  InvalidDocument(message~ : String)
  Io(message~ : String)
} derive(Eq, 
Debug)

Checked errors raised while parsing or transforming source maps.

#
SourceMapError::code

source
fn SourceMapError::code(self : SourceMapError) -> String

Return a stable error category.

#
SourceMapError::message

source
fn SourceMapError::message(self : SourceMapError) -> String

Return a human-readable message.

#
SourceMapError::path

source
fn SourceMapError::path(self : SourceMapError) -> String

Return the most specific available document path.

#
SourceMapError::to_diagnostic

source
fn SourceMapError::to_diagnostic(self : SourceMapError) -> Diagnostic

Convert a checked error into a validation diagnostic.

#
ComposeOptions

source
pub(all) struct ComposeOptions {
  bias : LookupBias
  missing : MissingMappingPolicy
  preserve_outer_names : Bool
}

Options controlling two-stage map composition.

#
ComposeOptions::default

source

Default composition options.

#
ComposeResult

source
pub(all) struct ComposeResult {
  map : DecodedSourceMap
  stats : ComposeStats
}

A composed map together with coverage statistics.

#
ComposeStats

source
pub(all) struct ComposeStats {
  outer_mappings : Int
  composed_mappings : Int
  generated_only : Int
  dropped : Int
}

Statistics returned by detailed composition.

#
ContextualSymbolizationReport

source
pub(all) struct ContextualSymbolizationReport {
  frames : Array[ContextualSymbolizedFrame]
  matched : Int
  unmatched : Int
  with_context : Int
} derive(Eq, 
Debug)

Aggregate single-map symbolization outcome.

#
ContextualSymbolizationReport::has_complete_context

source
fn ContextualSymbolizationReport::has_complete_context(self : ContextualSymbolizationReport) -> Bool

Return true when every mapped frame has embedded source context.

#
ContextualSymbolizationReport::is_complete

source

Return true when all frames were mapped.

#
ContextualSymbolizationReport::render

source

Render every contextual result.

#
ContextualSymbolizationReport::to_json

source

Convert a contextual report to stable JSON.

#
ContextualSymbolizationReport::unmatched_frames

source

Return only unmatched generated frames.

#
ContextualSymbolizedFrame

source
pub(all) struct ContextualSymbolizedFrame {
  result : SymbolizedFrame
  context : SourceContext?
} derive(Eq, 
Debug)

One symbolized frame with optional embedded source context.

#
ContextualSymbolizedFrame::render

source

Render one contextual result.

#
ContextualSymbolizedFrame::to_json

source

Convert one contextual result to JSON.

#
DecodedSourceMap

source
pub(all) struct DecodedSourceMap {
  file : String?
  sources : Array[SourceEntry]
  mappings : Array[Mapping]
} derive(Eq, 
Debug)

A flattened, decoded source map optimized for lookup.

#
DecodedSourceMap::new

source
fn DecodedSourceMap::new(file? : String, sources? : Array[SourceEntry], mappings? : Array[Mapping]) -> DecodedSourceMap

Construct a decoded map.

#
Diagnostic

source
pub(all) struct Diagnostic {
  severity : DiagnosticSeverity
  code : String
  message : String
  path : String
  mapping_line : Int?
  segment : Int?
  offset : Int?
} derive(Eq, 
Debug)

A stable, machine-readable validation diagnostic.

#
Diagnostic::error

source
fn Diagnostic::error(code~ : String, message~ : String, path? : String, mapping_line? : Int, segment? : Int, offset? : Int) -> Diagnostic

Construct an error diagnostic.

#
Diagnostic::is_error

source
fn Diagnostic::is_error(self : Diagnostic) -> Bool

Whether the diagnostic blocks conformance.

#
Diagnostic::render

source
fn Diagnostic::render(self : Diagnostic) -> String

Render one diagnostic in a stable single-line text format.

#
Diagnostic::to_json

source
fn Diagnostic::to_json(self : Diagnostic) -> Json

Convert a diagnostic to JSON.

#
Diagnostic::warning

source
fn Diagnostic::warning(code~ : String, message~ : String, path? : String, mapping_line? : Int, segment? : Int, offset? : Int) -> Diagnostic

Construct a warning diagnostic.

#
DiagnosticSeverity

source
pub(all) enum DiagnosticSeverity {
  Error
  Warning
} derive(Eq, 
Debug)

Severity for validation diagnostics.

#
DiagnosticSeverity::label

source
fn DiagnosticSeverity::label(self : DiagnosticSeverity) -> String

Stable text label for a diagnostic severity.

#
DuplicateMappingPolicy

source
pub(all) enum DuplicateMappingPolicy {
  KeepFirst
  KeepLast
  KeepAll
} derive(Eq, 
Debug)

Policy used when canonicalizing duplicate generated positions.

#
GeneratedLineUsage

source
pub(all) struct GeneratedLineUsage {
  line : Int
  segments : Int
  mapped_segments : Int
  generated_only_segments : Int
  named_segments : Int
  duplicate_positions : Int
  first_column : Int
  last_column : Int
} derive(Eq, 
Debug)

Mapping distribution for one generated line.

#
GeneratedLineUsage::mapping_coverage_percent

source
fn GeneratedLineUsage::mapping_coverage_percent(self : GeneratedLineUsage) -> Int

Percentage of segments on this line that carry original positions.

#
GeneratedLineUsage::to_json

source

Convert generated-line usage to JSON.

#
GeneratedSpan

source
pub(all) struct GeneratedSpan {
  mapping : Mapping
  end : Position?
} derive(Eq, 
Debug)

A half-open generated interval owned by one mapping.

end=None means the segment remains active to the end of its generated line. A next mapping on another line does not close the previous line.

#
GeneratedSpan::column_width

source
fn GeneratedSpan::column_width(self : GeneratedSpan) -> Int?

Return the finite column width, or None for an open span.

#
GeneratedSpan::contains

source
fn GeneratedSpan::contains(self : GeneratedSpan, position : Position) -> Bool

Return whether a generated position is covered by this span.

#
IndexSection

source
pub(all) struct IndexSection {
  offset : Position
  map : SourceMapDocument
} derive(Eq, 
Debug)

An embedded source map and its generated offset.

#
IndexSection::new

source
fn IndexSection::new(offset~ : Position, map~ : SourceMapDocument) -> IndexSection

Construct an index section.

#
IndexSourceMap

source
pub(all) struct IndexSourceMap {
  version : Int
  file : String?
  sections : Array[IndexSection]
} derive(Eq, 
Debug)

An ECMA-426 index source map.

#
IndexSourceMap::new

source
fn IndexSourceMap::new(file? : String, sections? : Array[IndexSection]) -> IndexSourceMap

Construct an empty version-3 index map.

#
LookupBias

source
pub(all) enum LookupBias {
  GreatestLowerBound
  LeastUpperBound
} derive(Eq, 
Debug)

Bias used when a position has no exact mapping.

#
Mapping

source
pub(all) struct Mapping {
  generated : Position
  original : OriginalPosition?
  name : String?
} derive(Eq, 
Debug)

One decoded Source Map mapping.

Generated-only segments have original=None and name=None.

#
Mapping::generated_only

source
fn Mapping::generated_only(generated~ : Position) -> Mapping

Construct a generated-only mapping.

#
Mapping::mapped

source
fn Mapping::mapped(generated~ : Position, original~ : OriginalPosition, name? : String) -> Mapping

Construct a mapping to an original location.

#
MissingMappingPolicy

source
pub(all) enum MissingMappingPolicy {
  KeepGenerated
  Drop
} derive(Eq, 
Debug)

Policy for outer mappings that cannot be resolved through the inner map.

#
OriginalPosition

source
pub(all) struct OriginalPosition {
  source_index : Int
  line : Int
  column : Int
} derive(Eq, 
Debug)

A location in an original source.

source_index indexes the decoded source table.

#
OriginalPosition::is_valid

source
fn OriginalPosition::is_valid(self : OriginalPosition) -> Bool

Return whether the source index and coordinates are non-negative.

#
OriginalPosition::new

source
fn OriginalPosition::new(source_index~ : Int, line~ : Int, column~ : Int) -> OriginalPosition

Construct an original position.

#
Position

source
pub(all) struct Position {
  line : Int
  column : Int
} derive(Eq, 
Debug)

A zero-based line and UTF-16 column pair.

ECMA-426 uses zero-based positions internally. CLI inputs are also zero based so there is no hidden conversion at the library boundary.

#
Position::compare

source
fn Position::compare(self : Position, other : Position) -> Int

Compare two positions in generated order.

#
Position::is_valid

source
fn Position::is_valid(self : Position) -> Bool

Return whether both coordinates are non-negative.

#
Position::new

source
fn Position::new(line~ : Int, column~ : Int) -> Position

Construct a generated position.

#
RegisteredSourceMap

source
pub(all) struct RegisteredSourceMap {
  name : String
  generated_file : String
  aliases : Array[String]
  map : DecodedSourceMap
}

One named source map and its generated-file aliases.

#
RegistryMissReason

source
pub(all) enum RegistryMissReason {
  MapNotFound
  MappingNotFound
  GeneratedOnly
} derive(Eq, 
Debug)

Reason a registry symbolization did not produce an original location.

#
RegistrySymbolizationReport

source
pub(all) struct RegistrySymbolizationReport {
  frames : Array[RegistrySymbolizedFrame]
  matched : Int
  map_missing : Int
  mapping_missing : Int
  generated_only : Int
} derive(Eq, 
Debug)

Aggregate outcome for newline-separated multi-file stack frames.

#
RegistrySymbolizationReport::is_complete

source

Return true when every frame was symbolized.

#
RegistrySymbolizationReport::render

source

Render all registry frame results.

#
RegistrySymbolizationReport::to_json

source

Convert a registry report to stable JSON.

#
RegistrySymbolizedFrame

source
pub(all) struct RegistrySymbolizedFrame {
  frame : StackFrame
  map_name : String?
  result : SymbolizedFrame?
  context : SourceContext?
  miss_reason : RegistryMissReason?
} derive(Eq, 
Debug)

Result of symbolizing one frame through a source-map registry.

#
RegistrySymbolizedFrame::render

source

Render one registry symbolization result.

#
RegistrySymbolizedFrame::to_json

source

Convert a registry frame result to JSON.

#
RegularSourceMap

source
pub(all) struct RegularSourceMap {
  version : Int
  file : String?
  source_root : String?
  sources : Array[String?]
  sources_content : Array[String?]?
  names : Array[String]
  mappings : String
  ignore_list : Array[Int]
} derive(Eq, 
Debug)

A regular ECMA-426 source map document.

#
RegularSourceMap::new

source
fn RegularSourceMap::new(file? : String, source_root? : String, sources? : Array[String?], sources_content? : Array[String?], names? : Array[String], mappings? : String, ignore_list? : Array[Int]) -> RegularSourceMap

Construct an empty version-3 regular map.

#
SourceContext

source
pub(all) struct SourceContext {
  source : String?
  focus_line : Int
  focus_column : Int
  start_line : Int
  end_line : Int
  lines : Array[String]
} derive(Eq, 
Debug)

Source lines surrounding an original position.

#
SourceContext::render

source
fn SourceContext::render(self : SourceContext) -> String

Render source context with line numbers and a caret.

#
SourceContext::to_json

source
fn SourceContext::to_json(self : SourceContext) -> Json

Convert source context to stable JSON.

#
SourceEntry

source
pub(all) struct SourceEntry {
  url : String?
  content : String?
  ignored : Bool
} derive(Eq, 
Debug)

A raw source entry after source table decoding.

#
SourceEntry::new

source
fn SourceEntry::new(url? : String, content? : String, ignored? : Bool) -> SourceEntry

Construct a decoded source entry.

#
SourceLine

source
pub(all) struct SourceLine {
  number : Int
  start : Int
  end : Int
  text : String
} derive(Eq, 
Debug)

One indexed line of embedded source content.

#
SourceMapBuilder

source
pub(all) struct SourceMapBuilder {
  file : String?
  sources : Array[SourceEntry]
  names : Array[String]
  mappings : Array[Mapping]
}

Incremental builder for normalized regular source maps.

Sources and names are interned in first-seen order. Mappings must be added in generated order, which catches a common source-map producer bug at the point where it is introduced.

#
SourceMapBuilder::add_generated

source
fn SourceMapBuilder::add_generated(self : SourceMapBuilder, generated~ : Position) -> Unit raise SourceMapError

Add a generated-only segment.

#
SourceMapBuilder::add_mapping

source
fn SourceMapBuilder::add_mapping(self : SourceMapBuilder, generated~ : Position, source_index~ : Int, original_line~ : Int, original_column~ : Int, name? : String) -> Unit raise SourceMapError

Add a segment mapped to an interned source.

#
SourceMapBuilder::add_name

source
fn SourceMapBuilder::add_name(self : SourceMapBuilder, name : String) -> Int

Intern a symbol name and return its stable index.

#
SourceMapBuilder::add_source

source
fn SourceMapBuilder::add_source(self : SourceMapBuilder, url? : String, content? : String, ignored? : Bool) -> Int

Intern a source entry and return its stable index.

#
SourceMapBuilder::build

source

Build a normalized version-3 regular source map.

#
SourceMapBuilder::build_decoded

source

Return an independent decoded snapshot.

#
SourceMapBuilder::clear_mappings

source
fn SourceMapBuilder::clear_mappings(self : SourceMapBuilder) -> Unit

Remove every mapping while retaining source and name tables.

#
SourceMapBuilder::mapping_count

source
fn SourceMapBuilder::mapping_count(self : SourceMapBuilder) -> Int

Number of emitted mappings.

#
SourceMapBuilder::new

source
fn SourceMapBuilder::new(file? : String) -> SourceMapBuilder

Create an empty source map builder.

#
SourceMapBuilder::source_count

source
fn SourceMapBuilder::source_count(self : SourceMapBuilder) -> Int

Number of interned sources.

#
SourceMapConsumer

source
pub(all) struct SourceMapConsumer {
  map : DecodedSourceMap
  line_starts : Array[Int]
  reverse : Map[Int, Array[Int]]
}

Precomputed indexes for repeated source-map queries.

#
SourceMapConsumer::from_document

source
fn SourceMapConsumer::from_document(document : SourceMapDocument, map_url? : String) -> SourceMapConsumer raise SourceMapError

Parse and flatten a document directly into a consumer.

#
SourceMapConsumer::generated_positions_for

source
fn SourceMapConsumer::generated_positions_for(self : SourceMapConsumer, source_index~ : Int, line? : Int, column? : Int) -> Array[Mapping]

Return mappings for one source, optionally filtered by original line.

#
SourceMapConsumer::get_original_positions

source
fn SourceMapConsumer::get_original_positions(self : SourceMapConsumer, generated~ : Position) -> Array[OriginalPosition?]

Run ECMA-426 GetOriginalPositions against the consumer's sorted mapping copy.

#
SourceMapConsumer::new

source

Construct a consumer, sorting a private mapping copy when necessary.

#
SourceMapConsumer::original_position_for

source
fn SourceMapConsumer::original_position_for(self : SourceMapConsumer, generated~ : Position, bias? : LookupBias) -> Mapping?

Query a generated position using the precomputed line index.

#
SourceMapConsumer::original_positions_for

source
fn SourceMapConsumer::original_positions_for(self : SourceMapConsumer, positions : ArrayView[Position], bias? : LookupBias) -> Array[Mapping?]

Query multiple positions without rebuilding indexes.

#
SourceMapConsumer::source_index_for_url

source
fn SourceMapConsumer::source_index_for_url(self : SourceMapConsumer, url : String) -> Int?

Find the first source index with an exact URL.

#
SourceMapConsumer::source_indices_for_url

source
fn SourceMapConsumer::source_indices_for_url(self : SourceMapConsumer, url : String) -> Array[Int]

Return every source index sharing a URL.

#
SourceMapConsumer::stats

source

Return aggregate map statistics.

#
SourceMapDocument

source
pub(all) enum SourceMapDocument {
  Regular(RegularSourceMap)
  Indexed(IndexSourceMap)
} derive(Eq, 
Debug)

The raw JSON document shape accepted by MoonSourceMap.

#
SourceMapDocument::file

source
fn SourceMapDocument::file(self : SourceMapDocument) -> String?

Return the optional generated file name.

#
SourceMapDocument::version

source
fn SourceMapDocument::version(self : SourceMapDocument) -> Int

Return the document version.

#
SourceMapRegistry

source
pub(all) struct SourceMapRegistry {
  entries : Array[RegisteredSourceMap]
}

Registry for symbolizing frames from multiple generated artifacts.

#
SourceMapRegistry::find

source
fn SourceMapRegistry::find(self : SourceMapRegistry, generated_file : String) -> RegisteredSourceMap?

Resolve an entry by exact key first, then normalized key.

#
SourceMapRegistry::is_empty

source
fn SourceMapRegistry::is_empty(self : SourceMapRegistry) -> Bool

Return whether the registry is empty.

#
SourceMapRegistry::length

source
fn SourceMapRegistry::length(self : SourceMapRegistry) -> Int

Number of registered source maps.

#
SourceMapRegistry::new

source

Construct an empty registry.

#
SourceMapRegistry::register

source
fn SourceMapRegistry::register(self : SourceMapRegistry, name~ : String, generated_file~ : String, map~ : DecodedSourceMap, aliases? : Array[String]) -> Unit raise SourceMapError

Register a decoded source map.

Exact and normalized keys must remain unique across entries. Re-registering the same logical generated file is rejected instead of silently replacing a map and making symbolization order-dependent.

#
SourceMapRegistry::symbolize

source
fn SourceMapRegistry::symbolize(self : SourceMapRegistry, frames : String, bias? : LookupBias, context_radius? : Int) -> RegistrySymbolizationReport raise SourceMapError

Parse and symbolize newline-separated frames from multiple generated files.

#
SourceMapRegistry::symbolize_frame

source
fn SourceMapRegistry::symbolize_frame(self : SourceMapRegistry, frame : StackFrame, bias? : LookupBias, context_radius? : Int) -> RegistrySymbolizedFrame

Symbolize one frame using the matching generated-file map.

#
SourceMapReport

source
pub(all) struct SourceMapReport {
  file : String?
  sources : Int
  mappings : Int
  mapped_segments : Int
  generated_only_segments : Int
  named_segments : Int
  ignored_sources : Int
  embedded_sources : Int
  referenced_sources : Int
  unreferenced_sources : Int
  generated_lines : Int
  original_lines : Int
  duplicate_positions : Int
  open_spans : Int
  source_usage : Array[SourceUsage]
  generated_line_usage : Array[GeneratedLineUsage]
} derive(Eq, 
Debug)

Structural quality report for one decoded source map.

#
SourceMapReport::busiest_generated_line

source
fn SourceMapReport::busiest_generated_line(self : SourceMapReport) -> GeneratedLineUsage?

Return the generated line with the most mapping segments.

#
SourceMapReport::content_coverage_percent

source
fn SourceMapReport::content_coverage_percent(self : SourceMapReport) -> Int

Percentage of sources with embedded content.

#
SourceMapReport::diagnostics

source
fn SourceMapReport::diagnostics(self : SourceMapReport) -> Array[Diagnostic]

Produce reviewer-facing quality diagnostics from report metrics.

#
SourceMapReport::empty_generated_lines

source
fn SourceMapReport::empty_generated_lines(self : SourceMapReport) -> Int

Count generated lines that contain no mapping segments.

#
SourceMapReport::generated_line

source
fn SourceMapReport::generated_line(self : SourceMapReport, line : Int) -> GeneratedLineUsage?

Return generated-line metrics for an exact line number.

#
SourceMapReport::generated_only_lines

source
fn SourceMapReport::generated_only_lines(self : SourceMapReport) -> Array[Int]

Return generated lines containing at least one generated-only segment.

#
SourceMapReport::has_complete_mappings

source
fn SourceMapReport::has_complete_mappings(self : SourceMapReport) -> Bool

Return whether every segment maps to an original position.

#
SourceMapReport::has_complete_source_usage

source
fn SourceMapReport::has_complete_source_usage(self : SourceMapReport) -> Bool

Return whether every declared source is referenced.

#
SourceMapReport::has_complete_sources_content

source
fn SourceMapReport::has_complete_sources_content(self : SourceMapReport) -> Bool

Return whether every source carries embedded content.

#
SourceMapReport::has_quality_warnings

source
fn SourceMapReport::has_quality_warnings(self : SourceMapReport) -> Bool

Return whether the report contains a mapping or source-quality warning.

#
SourceMapReport::ignored_source_indices

source
fn SourceMapReport::ignored_source_indices(self : SourceMapReport) -> Array[Int]

Return source indexes marked as ignored.

#
SourceMapReport::ignored_source_percent

source
fn SourceMapReport::ignored_source_percent(self : SourceMapReport) -> Int

Percentage of source entries marked as ignored.

#
SourceMapReport::lines_with_duplicates

source
fn SourceMapReport::lines_with_duplicates(self : SourceMapReport) -> Array[Int]

Return generated line numbers containing duplicate positions.

#
SourceMapReport::mapping_coverage_percent

source
fn SourceMapReport::mapping_coverage_percent(self : SourceMapReport) -> Int

Percentage of segments carrying original positions.

#
SourceMapReport::named_mapping_percent

source
fn SourceMapReport::named_mapping_percent(self : SourceMapReport) -> Int

Percentage of mapped segments that preserve a symbol name.

#
SourceMapReport::render

source
fn SourceMapReport::render(self : SourceMapReport) -> String

Render a compact report for terminals and CI logs.

#
SourceMapReport::source

source
fn SourceMapReport::source(self : SourceMapReport, source_index : Int) -> SourceUsage?

Find the usage summary for a source index.

#
SourceMapReport::source_coverage_percent

source
fn SourceMapReport::source_coverage_percent(self : SourceMapReport) -> Int

Percentage of sources referenced by at least one mapping.

#
SourceMapReport::sources_without_content

source
fn SourceMapReport::sources_without_content(self : SourceMapReport) -> Array[Int]

Return source indexes without embedded source content.

#
SourceMapReport::summary

source
fn SourceMapReport::summary(self : SourceMapReport) -> String

Return a concise CI summary line.

#
SourceMapReport::to_json

source
fn SourceMapReport::to_json(self : SourceMapReport) -> Json

Convert the complete report to stable JSON.

#
SourceMapReport::unreferenced_source_indices

source
fn SourceMapReport::unreferenced_source_indices(self : SourceMapReport) -> Array[Int]

Return source indexes that are never referenced by mappings.

#
SourceMapReport::usable_embedded_sources

source
fn SourceMapReport::usable_embedded_sources(self : SourceMapReport) -> Int

Count source entries that are both referenced and backed by embedded text.

#
SourceMapStats

source
pub(all) struct SourceMapStats {
  sources : Int
  mappings : Int
  mapped : Int
  generated_only : Int
  named : Int
  ignored_sources : Int
  generated_lines : Int
  original_lines : Int
}

Summary metrics useful for CI reports and producer diagnostics.

#
SourceMapStats::to_json

source
fn SourceMapStats::to_json(self : SourceMapStats) -> Json

Convert statistics to stable JSON.

#
SourcePathKind

source
pub(all) enum SourcePathKind {
  Anonymous
  DataUri
  AbsoluteUri
  ProtocolRelative
  WindowsAbsolute
  PosixAbsolute
  Relative
} derive(Eq, 
Debug)

Classification used while resolving source entries.

#
SourceResolverOptions

source
pub(all) struct SourceResolverOptions {
  map_url : String?
  source_root : String?
  normalize_windows : Bool
}

Options for resolving sourceRoot and source entries.

#
SourceResolverOptions::new

source
fn SourceResolverOptions::new(map_url? : String, source_root? : String, normalize_windows? : Bool) -> SourceResolverOptions

Construct source resolver options.

#
SourceTextIndex

source
pub(all) struct SourceTextIndex {
  content : String
  starts : Array[Int]
  ends : Array[Int]
}

A line index over one sourcesContent entry.

#
SourceTextIndex::contains

source
fn SourceTextIndex::contains(self : SourceTextIndex, line~ : Int, column~ : Int) -> Bool

Check whether a zero-based original position exists in the source.

#
SourceTextIndex::context

source
fn SourceTextIndex::context(self : SourceTextIndex, source? : String, line~ : Int, column~ : Int, radius? : Int) -> SourceContext?

Extract source context around a zero-based position.

#
SourceTextIndex::line

source
fn SourceTextIndex::line(self : SourceTextIndex, number : Int) -> SourceLine?

Return one indexed line.

#
SourceTextIndex::line_count

source
fn SourceTextIndex::line_count(self : SourceTextIndex) -> Int

Return the number of logical source lines.

#
SourceTextIndex::new

source
fn SourceTextIndex::new(content : String) -> SourceTextIndex

Build a CRLF-aware source text index.

#
SourceUsage

source
pub(all) struct SourceUsage {
  source_index : Int
  url : String?
  mapped_segments : Int
  named_segments : Int
  original_lines : Int
  ignored : Bool
  has_content : Bool
} derive(Eq, 
Debug)

Per-source mapping usage metrics.

#
SourceUsage::is_referenced

source
fn SourceUsage::is_referenced(self : SourceUsage) -> Bool

Return whether a source is referenced by at least one segment.

#
SourceUsage::to_json

source
fn SourceUsage::to_json(self : SourceUsage) -> Json

Convert source usage metrics to JSON.

#
StackFrame

source
pub(all) struct StackFrame {
  file : String
  line : Int
  column : Int
  function_name : String?
  raw : String
} derive(Eq, 
Debug)

A generated stack frame accepted by the symbolizer.

#
SymbolizedFrame

source
pub(all) struct SymbolizedFrame {
  generated : StackFrame
  source : String?
  line : Int?
  column : Int?
  name : String?
  ignored : Bool
  matched : Bool
} derive(Eq, 
Debug)

A generated frame and its optional original location.

#
SymbolizedFrame::render

source
fn SymbolizedFrame::render(self : SymbolizedFrame) -> String

Render a concise human-readable symbolized frame.

#
SymbolizedFrame::to_json

source
fn SymbolizedFrame::to_json(self : SymbolizedFrame) -> Json

Convert a symbolized frame to stable machine-readable JSON.

#
TransformReport

source
pub(all) struct TransformReport {
  mappings_before : Int
  mappings_after : Int
  sources_before : Int
  sources_after : Int
  duplicates_removed : Int
  sources_removed : Int
}

Result metadata for map normalization.

#
TransformReport::to_json

source
fn TransformReport::to_json(self : TransformReport) -> Json

Convert a transform report to JSON.

#
TransformResult

source
pub(all) struct TransformResult {
  map : DecodedSourceMap
  report : TransformReport
}

A transformed map together with auditable change counts.

#
VlqValue

source
pub(all) struct VlqValue {
  value : Int
  next_offset : Int
} derive(Eq, 
Debug)

One decoded signed Base64-VLQ value and the first unread UTF-16 offset.

#
analyze_source_map

source
fn analyze_source_map(map : DecodedSourceMap) -> SourceMapReport

Analyze decoded map structure without requiring generated source text.

Counts refer to mapping segments rather than bytes or characters, because a source map does not carry the length of the generated artifact.

#
analyze_source_map_json

source
fn analyze_source_map_json(input : StringView, map_url? : String) -> SourceMapReport raise SourceMapError

Parse, flatten and analyze a source-map JSON document.

#
canonicalize

source
fn canonicalize(map : DecodedSourceMap, duplicate_policy? : DuplicateMappingPolicy, remove_unused_sources? : Bool) -> TransformResult

Sort mappings, resolve duplicates and optionally remove unused sources.

#
classify_source_path

source
fn classify_source_path(source : String?) -> SourcePathKind

Classify a raw source entry before resolution.

#
compose

source
fn compose(generated_to_intermediate : DecodedSourceMap, intermediate_to_original : DecodedSourceMap) -> DecodedSourceMap

Compose final-to-intermediate and intermediate-to-original decoded maps.

#
compose_json

source
fn compose_json(outer_json : StringView, inner_json : StringView, indent? : Int) -> String raise SourceMapError

Parse, flatten and compose two source-map JSON documents.

#
compose_with_options

source
fn compose_with_options(outer : DecodedSourceMap, inner : DecodedSourceMap, options? : ComposeOptions) -> ComposeResult

Compose two decoded source maps and return coverage statistics.

outer maps final generated code to an intermediate artifact. inner maps that artifact to original sources. The composed source table is copied from inner, and the generated file is copied from outer.

#
concatenate

source
fn concatenate(parts : ArrayView[(Position, DecodedSourceMap)], file? : String) -> DecodedSourceMap raise SourceMapError

Concatenate decoded maps at explicit generated offsets.

This is the programmatic counterpart of constructing an index map and then flattening it, useful for bundlers that already have decoded child maps.

#
decode_document

source
fn decode_document(document : SourceMapDocument, map_url? : String) -> DecodedSourceMap raise SourceMapError

Decode either a regular or index source map for querying.

Index maps are recursively expanded. Source entries are intentionally kept section-local, even when URLs repeat, so that distinct embedded contents and ignore-list flags cannot be conflated.

#
decode_mappings

source
fn decode_mappings(input : String, sources_count~ : Int, names~ : ArrayView[String]) -> Array[Mapping] raise SourceMapError

Decode the ECMA-426 mappings field.

The decoder is strict: segments must contain exactly one, four, or five fields; all accumulated coordinates and indices must remain non-negative; and source/name indices must remain inside the caller-provided tables.

#
decode_regular_source_map

source
fn decode_regular_source_map(map : RegularSourceMap, map_url? : String) -> DecodedSourceMap raise SourceMapError

Decode a regular document into a lookup-oriented representation.

This resolves sourceRoot, associates embedded source content and applies both standard and legacy ignore-list metadata parsed from the document.

#
decode_vlq

source
fn decode_vlq(input : String) -> Int raise SourceMapError

Decode a string containing exactly one Base64-VLQ value.

#
decode_vlq_at

source
fn decode_vlq_at(input : String, offset~ : Int) -> VlqValue raise SourceMapError

Decode one signed Base64-VLQ value at offset.

The returned next_offset can be passed into another call when decoding a Source Map segment.

#
diagnostics_have_errors

source
fn diagnostics_have_errors(diagnostics : ArrayView[Diagnostic]) -> Bool

Return true when at least one conformance error is present.

#
diagnostics_to_json

source
fn diagnostics_to_json(diagnostics : ArrayView[Diagnostic]) -> Json

Convert diagnostics to a JSON array.

#
document_to_json

source
fn document_to_json(document : SourceMapDocument) -> Json

Convert a source map document to its JSON value.

#
encode_decoded

source
fn encode_decoded(decoded : DecodedSourceMap) -> RegularSourceMap raise SourceMapError

Encode a decoded source map as a normalized regular document.

#
encode_document

source
fn encode_document(document : SourceMapDocument, indent? : Int) -> String

Serialize a source map document.

#
encode_mappings

source
fn encode_mappings(mappings : ArrayView[Mapping], names~ : ArrayView[String]) -> String raise SourceMapError

Encode decoded mappings into the canonical ECMA-426 delta representation.

Mappings must be sorted by generated line and column. Original coordinates and source indices must be non-negative. Named mappings must refer to an entry in names.

#
encode_vlq

source
fn encode_vlq(value : Int) -> String

Encode one signed integer using the Base64-VLQ alphabet required by ECMA-426.

#
flatten

source
fn flatten(document : SourceMapDocument) -> RegularSourceMap raise SourceMapError

Flatten a regular or index source map into a normalized regular document.

#
generated_positions_for

source
fn generated_positions_for(map : DecodedSourceMap, source_index~ : Int, line~ : Int, column? : Int) -> Array[Mapping]

Find every generated segment that maps to an original source position.

When column is omitted, all mappings on the requested original line are returned. Results remain in generated order.

#
get_original_positions

source
fn get_original_positions(map : DecodedSourceMap, generated~ : Position) -> Array[OriginalPosition?]

Return all original positions associated with the globally greatest generated position that is not later than generated.

This implements ECMA-426 GetOriginalPositions: duplicate mappings are retained in source-map order, generated-only mappings appear as None, and an empty array means no generated mapping precedes the query.

#
mapping_spans

source
fn mapping_spans(map : DecodedSourceMap) -> Array[GeneratedSpan]

Convert ordered mappings to generated spans.

Duplicate positions produce zero-width spans except for the last duplicate, matching GLB lookup behavior.

#
mapping_spans_for_line

source
fn mapping_spans_for_line(map : DecodedSourceMap, line : Int) -> Array[GeneratedSpan]

Return spans beginning on one generated line.

#
mappings_are_sorted

source
fn mappings_are_sorted(mappings : ArrayView[Mapping]) -> Bool

Return true when mappings are in generated order.

#
mappings_line_count

source
fn mappings_line_count(input : String) -> Int

Count generated lines represented by a mappings string.

#
normalize_generated_file

source
fn normalize_generated_file(value : String) -> String

Normalize a generated-file key for registry matching.

#
original_position_for

source
fn original_position_for(map : DecodedSourceMap, generated~ : Position, bias? : LookupBias) -> Mapping?

Find a decoded segment for a generated position.

GreatestLowerBound returns the last segment at or before the query. LeastUpperBound returns the first segment at or after the query. Bias is applied within a generated line: mappings on another line are not used. When duplicate generated positions exist, GLB selects the last duplicate and LUB selects the first.

#
parse_document

source
fn parse_document(input : StringView) -> SourceMapDocument raise SourceMapError

Parse a regular or index source map JSON document.

#
parse_stack_frame

source
fn parse_stack_frame(input : String) -> StackFrame raise SourceMapError

Parse file:line:column and common at name (file:line:column) frames.

Coordinates are zero-based, matching the library API and ECMA-426. Splitting from the right preserves Windows drive letters and URI schemes.

#
resolve_source_url

source
fn resolve_source_url(source : String?, options? : SourceResolverOptions) -> String?

Resolve one source entry using ECMA-426 sourceRoot and a map URL.

Absolute URIs, data URIs, protocol-relative URLs and absolute filesystem paths do not inherit either base. A relative sourceRoot is first resolved against the directory containing the map.

#
shift_generated

source
fn shift_generated(map : DecodedSourceMap, line_delta? : Int, first_line_column_delta? : Int) -> DecodedSourceMap raise SourceMapError

Shift generated positions using the ECMA-426 section-offset rule.

#
slice_generated

source
fn slice_generated(map : DecodedSourceMap, start~ : Position, end~ : Position) -> DecodedSourceMap raise SourceMapError

Keep mappings in a half-open generated range.

#
sort_mappings

source
fn sort_mappings(mappings : ArrayView[Mapping]) -> Array[Mapping]

Return a copy sorted by generated position.

Sorting is stable for entries that share the same generated position.

#
source_context_for_frame

source
fn source_context_for_frame(map : DecodedSourceMap, frame : SymbolizedFrame, radius? : Int) -> SourceContext?

Resolve embedded source context for a symbolized frame.

#
source_context_for_mapping

source
fn source_context_for_mapping(map : DecodedSourceMap, mapping : Mapping, radius? : Int) -> SourceContext?

Resolve embedded source context for a mapped segment.

#
source_for_mapping

source
fn source_for_mapping(map : DecodedSourceMap, mapping : Mapping) -> SourceEntry?

Resolve the source entry referenced by a mapping.

#
symbolize

source
fn symbolize(map : DecodedSourceMap, frames : String, bias? : LookupBias) -> Array[SymbolizedFrame] raise SourceMapError

Parse and symbolize newline-separated stack frames.

Empty lines are ignored. A malformed non-empty line is reported as an error, preventing CI from silently accepting partially processed input.

#
symbolize_frame

source
fn symbolize_frame(map : DecodedSourceMap, frame : StackFrame, bias? : LookupBias) -> SymbolizedFrame

Symbolize one generated frame.

#
symbolize_frame_with_context

source
fn symbolize_frame_with_context(map : DecodedSourceMap, frame : StackFrame, bias? : LookupBias, context_radius? : Int) -> ContextualSymbolizedFrame

Symbolize one frame and attach embedded source context when available.

#
symbolize_with_context

source
fn symbolize_with_context(map : DecodedSourceMap, frames : String, bias? : LookupBias, context_radius? : Int) -> ContextualSymbolizationReport raise SourceMapError

Parse and symbolize newline-separated frames with source context.

#
symbolized_frames_to_json

source
fn symbolized_frames_to_json(frames : ArrayView[SymbolizedFrame]) -> Json

Convert a list of symbolized frames to JSON.

#
validate

source
fn validate(document : SourceMapDocument) -> Array[Diagnostic]

Validate a parsed source map without aborting after the first problem.

#
validate_json

source
fn validate_json(input : StringView) -> Array[Diagnostic]

Parse and validate a source map in one operation.

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io