Why
Runtime coverage pipelines often start with V8 byte offsets, not line/column pairs.
Fallow Runtime currently has to normalize V8 offsets into line/column positions before source-map lookup. That logic belongs close to the source-map SDK because correctness depends on the same details srcmap already owns:
- generated byte offsets vs generated line/column positions
- UTF-8 byte offsets vs UTF-16 JavaScript columns
- missing/generated-only positions
- bundled/minified output with sparse mappings
- line/column APIs that are already 0-based internally
The existing public APIs are strong for original_position_for(line, column) and generated_position_for(source, line, column), but runtime coverage callers need a first-class path from generated byte offsets to original source locations.
Scope
Add helper APIs for generated byte-offset lookup.
Possible API direction:
pub struct GeneratedOffsetLookup<'a> { ... }
impl GeneratedOffsetLookup<'_> {
pub fn new(generated_source: &str) -> Self;
pub fn byte_offset_to_position(&self, byte_offset: u32) -> Option<GeneratedPosition>;
pub fn original_position_for_offset(&self, sm: &SourceMap, byte_offset: u32) -> Option<OriginalLocation>;
}
Alternative shapes are fine; the important bit is that runtime coverage consumers do not each reimplement offset normalization.
Acceptance criteria
- Supports UTF-8 source text and documents what column unit is passed into source-map lookup.
- Tests cover ASCII, multi-byte UTF-8, surrogate-pair JavaScript columns if relevant, CRLF, and offsets at line boundaries.
- Works with both eager
SourceMap and, if feasible, LazySourceMap.
- Example shows V8 function range start offset -> original TypeScript file/line/column.
- README documents the runtime coverage use case.
Non-goals
- Do not build a full V8-to-Istanbul converter in
srcmap.
- Do not take a dependency on Fallow-specific protocol types.
- Do not change existing line/column lookup semantics.
Why
Runtime coverage pipelines often start with V8 byte offsets, not line/column pairs.
Fallow Runtime currently has to normalize V8 offsets into line/column positions before source-map lookup. That logic belongs close to the source-map SDK because correctness depends on the same details
srcmapalready owns:The existing public APIs are strong for
original_position_for(line, column)andgenerated_position_for(source, line, column), but runtime coverage callers need a first-class path from generated byte offsets to original source locations.Scope
Add helper APIs for generated byte-offset lookup.
Possible API direction:
Alternative shapes are fine; the important bit is that runtime coverage consumers do not each reimplement offset normalization.
Acceptance criteria
SourceMapand, if feasible,LazySourceMap.Non-goals
srcmap.