Multipage preference

Draft ECMA-426 / September 28, 2026

ソースマップ形式仕様

この仕様について

https://tc39.es/ecma426/ にある文書は、最も正確かつ最新のソースマップ仕様である。直近に公開されたスナップショットの内容に、次のスナップショットに含まれる変更を加えたものを収録している。

この仕様への貢献

この仕様は GitHub で開発されている。この仕様の開発には、次の方法で貢献できる。

この文書の作成方法の詳細については、奥付を参照。

はじめに

この Ecma 標準は、トランスパイルされたソースコードを元のソースに対応付けるために使用するソースマップ形式を定義する。

ソースマップ形式には、次の目標がある。

当初のソースマップ形式 (v1) は、最適化された JavaScript コードのソースレベルのデバッグを可能にするため、Closure Inspector で使用するものとして Joseph Schorr が作成した。ただし、形式自体は言語に依存しない。しかし、ソースマップを使用するプロジェクトの規模が拡大するにつれて、形式の冗長さが問題になり始めた。v2 形式（ソースマップ改訂第2版の提案）は、単純さと柔軟性をある程度犠牲にして、ソースマップ全体のサイズを削減することで作成された。v2 形式で変更を加えた後も、ソースマップのファイルサイズがその有用性を制限していた。v3 形式は、Pavel Podivilov (Google) による提案に基づいている。

ソースマップ形式には、現在ではバージョン番号による区別はなく、常に「3」に固定されている。

2023～2024年には、多くの人々の多大な貢献により、ソースマップ形式がより厳密な Ecma 標準として整備された。ソースマップ形式の今後の改訂は、TC39-TG4 によって進められることが期待される。

Asumu Takikawa, Nicolò Ribaudo, Jon Kuperman
ECMA-426, 第1版, プロジェクト編集者

1 適用範囲

この標準は、JavaScript、WebAssembly、および CSS にコンパイルされたコードのデバッグを改善するために、さまざまな種類の開発者ツールが使用するソースマップ形式を定義する。

2 適合性

適合するソースマップ文書とは、この仕様で詳述する構造に適合する JSON 文書である。

適合するソースマップ生成器は、適合するソースマップ文書であり、この仕様のアルゴリズムによって、任意と指定されたものも含めてエラーを一切報告せずに復号できる文書を生成することが望ましい。

適合するソースマップ利用器は、ソースマップ文書の取得（該当する場合）および復号について、この仕様で規定するアルゴリズムを実装することが望ましい。アルゴリズムが任意でエラーを報告してよいと仕様に示されている場合、適合する利用器は、エラーを無視しても、処理を終了せずに報告してもよい。

3 参照文献

次の文書は、その内容の一部または全部がこの文書の要件を構成する形で、本文中から参照されている。日付のある参照文献については、引用された版だけが適用される。日付のない参照文献については、追補を含む、その文書の最新版が適用される。

3.1 規範的参照文献

ECMA-262, ECMAScript® 言語仕様。
https://tc39.es/ecma262/

ECMA-404, JSON データ交換形式。
https://www.ecma-international.org/publications-and-standards/standards/ecma-404/

3.2 参考文献

IETF RFC 4648, Base16、Base32、および Base64 のデータ符号化。
https://datatracker.ietf.org/doc/html/rfc4648

WebAssembly コア仕様。
https://www.w3.org/TR/wasm-core-2/

WHATWG Encoding。
https://encoding.spec.whatwg.org/

WHATWG Fetch。
https://fetch.spec.whatwg.org/

WHATWG Infra。
https://infra.spec.whatwg.org/

WHATWG URL。
https://url.spec.whatwg.org/

4 表記規約

この仕様は、ECMA-262（表記規約）で定義された表記規約に、この節で定義する拡張を加えたものに従う。

4.1 アルゴリズムの規約

4.1.1 暗黙の完了

この仕様で宣言するすべての抽象操作は、そのアルゴリズムで宣言された返却型の値を含む正常完了、またはスロー完了を返すものと暗黙に見なす。例えば、次のように宣言された抽象操作は、

4.1.1.1 GetTheAnswer ( input )

The abstract operation GetTheAnswer takes argument input (an integer) and returns an integer.

次と同等である。

4.1.1.2 GetTheAnswer2 ( input )

The abstract operation GetTheAnswer2 takes argument input (an integer) and returns either a normal completion containing an integer or a throw completion.

完了レコードを返す抽象操作の呼び出しは、明示的な Completion 呼び出しで包まれていない限り、ECMA-262 の完了レコードを展開する略記 ? で包まれているものと暗黙に見なす。例えば、

  1. result を GetTheAnswer(value) とする.
  2. second を Completion(GetTheAnswer(value)) とする.

は、次と同等である。

  1. result を ? GetTheAnswer(value) とする.
  2. second を Completion(GetTheAnswer(value)) とする.

4.1.2 任意のエラー報告

アルゴリズムが任意でエラーを報告することになっている場合、実装は次のいずれかの動作を選択してよい。

  • アルゴリズムの残りの部分の実行を続ける。
  • 例えばブラウザーのコンソールなどで、利用者にエラーを報告し、アルゴリズムの残りの部分の実行を続ける。
  • ThrowCompletion を返す。

実装は、任意のエラー報告ごとに異なる動作を選択できる。

4.2 文法の表記

この仕様は、ECMA-262（文法の表記）で定義された文法の表記規約に従う。ただし、次の点に注意する。

  • この仕様で定義する文法の終端記号は、個々の符号位置である。これは ECMA-262 の字句文法に類似しており、ECMA-262 の構文文法には類似しない。
  • この仕様では、文法定義の複雑さを抑えるため、文法パラメーターおよび先読み制約を使用しない。

5 用語および定義

この文書では、次の用語および定義を適用する。

生成コード

コンパイラーまたはトランスパイラーによって生成されたコード。

元のソース

コンパイラーまたはトランスパイラーを通していないソースコード。

ソースマップ URL

生成コードからソースマップの所在を参照する URL。

列

生成コードの行内における、0を起点とするオフセット。JavaScript および CSS のソースマップでは UTF-16 符号単位で計算し、WebAssembly のソースマップでは、単一の行として表されるバイナリー内容内のバイト索引で計算する。

Note
つまり、「A」(LATIN CAPITAL LETTER A) は1符号単位、「🔥」(FIRE) は2符号単位として数える。他の内容型のソースマップでは、これと異なってもよい。

6 base64 VLQ

base64 VLQ は、base64 で符号化した可変長数量である。最上位ビット（第6ビット）を継続ビットとして使用し、「桁」は下位の桁から順に文字列へ符号化する。また、最初の桁の最下位ビットを符号ビットとして使用する。

Note 1
base64 VLQ 符号化で表現できる値は、より大きな値の用途が示されるまでは、32ビットの数量に制限される。つまり、32ビットを超える値は無効であり、実装はそれらを拒否してよい。この制限には符号ビットを含めるが、継続ビットは含めない。
 Note 2
文字列 "iB" は、2桁の base64 VLQ を表す。最初の桁 "i" はビットパターン 0b100010 を符号化しており、継続ビットは 1（VLQ が続く）、符号ビットは 0（非負）、値のビットは 0b0001 である。2桁目の B はビットパターン 0b000001 を符号化しており、継続ビットは 0、符号ビットはなく、値のビットは 0b00001 である。この VLQ 文字列を復号すると、数値17になる。
Note 3
文字列 "V" は、1桁の base64 VLQ を表す。桁 "V" はビットパターン 0b010101 を符号化しており、継続ビットは 0（継続しない）、符号ビットは 1（負）、値のビットは 0b1010 である。この VLQ 文字列を復号すると、数値-10になる。

base64 VLQ は、次の字句文法に従う。

Vlq :: VlqDigitList VlqDigitList :: TerminalDigit ContinuationDigit VlqDigitList TerminalDigit :: A B C D E F G H I J K L M N O P Q R S T U V W X Y Z a b c d e f ContinuationDigit :: g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8 9 + /

6.1 VLQSignedValue

The syntax-directed operation VLQSignedValue takes no arguments and returns an integer. It is defined piecewise over the following productions:

Vlq :: VlqDigitList
  1. unsigned を VlqDigitList の VLQUnsignedValue とする.
  2. unsigned modulo 2 = 1 ならば、sign を -1 とする.
  3. そうでなければ、sign を 1 とする.
  4. value を floor(unsigned / 2) とする.
  5. value が 0 であり、sign が -1 ならば、-231 を返す.
  6. value ≥ 231 ならば、エラーをスローする.
  7. sign × value を返す.
 Note
手順 6 の検査が必要なのは、unsigned が Vlq の VLQUnsignedValue ではなく、VlqDigitList の VLQUnsignedValue だからである。

6.2 VLQUnsignedValue

The syntax-directed operation VLQUnsignedValue takes no arguments and returns an non-negative integer. It is defined piecewise over the following productions:

Vlq :: VlqDigitList
  1. value を VlqDigitList の VLQUnsignedValue とする.
  2. value ≥ 232 ならば、エラーをスローする.
  3. value を返す.
 VlqDigitList :: ContinuationDigit VlqDigitList
  1. left を ContinuationDigit の VLQUnsignedValue とする.
  2. right を VlqDigitList の VLQUnsignedValue とする.
  3. left + right × 25 を返す.
 TerminalDigit :: A B C D E F G H I J K L M N O P Q R S T U V W X Y Z a b c d e f
  1. digit を、この生成規則に一致する文字とする.
  2. value を、IETF RFC 4648 で定義された base64 符号化に従って digit に対応する整数とする.
  3. 表明: value < 32.
  4. value を返す.
 ContinuationDigit :: g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8 9 + /
  1. digit を、この生成規則に一致する文字とする.
  2. value を、IETF RFC 4648 で定義された base64 符号化に従って digit に対応する整数とする.
  3. 表明: 32 ≤ value < 64.
  4. value - 32 を返す.

7 JSON 値の補助操作

この仕様のアルゴリズムは ECMA-262 の内部機構に基づいて定義されているが、JavaScript 以外のプラットフォームでも容易に実装できることを意図している。この節には、JSON 値を扱うための補助操作をまとめ、文書の残りの部分から ECMA-262 の詳細を抽象化する。

JSON value は、JSON object、JSON array、String、Number、Boolean、または null のいずれかである。

JSON object は、その各プロパティーが次を満たす Object である。

JSON array は、次を満たす JSON object である。

7.1 ParseJSON ( string )

The abstract operation ParseJSON takes argument string (a String) and returns a JSON value. It performs the following steps when called:

  1. result を Call(%JSON.parse%, null, « string ») とする.
  2. 表明: result は JSON value である.
  3. result を返す.
 Editor's Note
この抽象操作は、tc39/ecma262#3540 において、ECMA-262 自体から利用できるようにする作業が進められている。

7.2 JSONObjectGet ( object, key )

The abstract operation JSONObjectGet takes arguments object (a JSON object) and key (a String) and returns a JSON value or missing. object 内の、指定された key に関連付けられた値を返す。 It performs the following steps when called:

  1. object がキー key を持つ自身のプロパティーを持たないならば、missing を返す.
  2. prop を、キーが key である object の自身のプロパティーとする.
  3. prop の [[Value]] 属性を返す.

7.3 JSONArrayIterate ( array )

The abstract operation JSONArrayIterate takes argument array (a JSON array) and returns a List of JSON values. array のすべての要素を含む List を返す。これにより、アルゴリズムで「各要素について」の反復処理を使用できる。 It performs the following steps when called:

  1. length を JSONObjectGet(array, "length") とする.
  2. 表明: length は非負の整数値を持つ Number である.
  3. list を新しい空の List とする.
  4. i を 0 とする.
  5. i < ℝ(length) である間、次を繰り返す:
    1. value を JSONObjectGet(array, ToString(𝔽(i))) とする.
    2. 表明: value は missing でない.
    3. value を list に追加する.
    4. i を i + 1 に設定する.
  6. list を返す.

7.4 StringSplit ( string, separators )

The abstract operation StringSplit takes arguments string (a String) and separators (a List of non-empty Strings) and returns a List of Strings. separators のいずれかの要素を区切りとして、文字列を部分文字列に分割する。複数の区切り文字列が一致する場合、separators 内で先に現れるものほど優先順位が高い。 It performs the following steps when called:

  1. parts を新しい空の List とする.
  2. strLen を string の長さとする.
  3. lastStart を 0 とする.
  4. i を 0 とする.
  5. i < strLen である間、次を繰り返す:
    1. matched を false とする.
    2. separators の各 String sep について、次を行う:
      1. sepLen を sep の長さとする.
      2. candidate を string の i から min(i + sepLen, strLen) までの部分文字列とする.
      3. candidate = sep であり、matched が false ならば:
        1. chunk を string の lastStart から i までの部分文字列とする.
        2. chunk を parts に追加する.
        3. lastStart を i + sepLen に設定する.
        4. i を i + sepLen に設定する.
        5. matched を true に設定する.
    3. matched が false ならば、i を i + 1 に設定する.
  6. chunk を string の lastStart から strLen までの部分文字列とする.
  7. chunk を parts に追加する.
  8. parts を返す.

8 位置の型

8.1 Position Record

Position Record は、非負の行番号と非負の列番号からなる組である。

Table 1: Position Record のフィールド
フィールド名 値の型
[[Line]] 非負の整数値を持つ Number
[[Column]] 非負の整数値を持つ Number

8.2 Original Position Record

Original Position Record は、Decoded Source Record、非負の行番号、および非負の列番号からなる組である。Position Record に類似するが、具体的な元のソースファイル内のソース位置を記述する。

Table 2: Original Position Record のフィールド
フィールド名 値の型
[[Source]] Decoded Source Record
[[Line]] 非負の整数値を持つ Number
[[Column]] 非負の整数値を持つ Number

8.3 ComparePositions ( first, second )

The abstract operation ComparePositions takes arguments first (a Position Record or a Original Position Record) and second (a Position Record or a Original Position Record) and returns lesser, equal or greater. first が second より前にある場合、等しい場合、後にある場合に、それぞれ lesser、equal、greater を返す。Original Position Record の [[Source]] フィールドは無視する。 It performs the following steps when called:

  1. first.[[Line]] < second.[[Line]] ならば、lesser を返す.
  2. first.[[Line]] > second.[[Line]] ならば、greater を返す.
  3. 表明: first.[[Line]] は second.[[Line]] に等しい.
  4. first.[[Column]] < second.[[Column]] ならば、lesser を返す.
  5. first.[[Column]] > second.[[Column]] ならば、greater を返す.
  6. equal を返す.

9 ソースマップ形式

ソースマップは、次の構造を持つ最上位の JSON オブジェクトを含む JSON 文書である。

{
  "version" : 3,
  "file": "out.js",
  "sourceRoot": "",
  "sources": ["foo.js", "bar.js"],
  "sourcesContent": [null, null],
  "names": ["src", "maps", "are", "fun"],
  "mappings": "A,AAAB;;ABCDE",
  "ignoreList": [0]
}

9.1 ソースマップの復号

Decoded Source Map Record は、次のフィールドを持つ。

Table 3: Decoded Source Map Record のフィールド
フィールド名 値の型
[[File]] String または null
[[Sources]] Decoded Source Record の List
[[Mappings]] Decoded Mapping Record の List

Decoded Source Record は、次のフィールドを持つ。

Table 4: Decoded Source Record のフィールド
フィールド名 値の型
[[URL]] URL または null
[[Content]] String または null
[[Ignored]] Boolean

9.1.1 ParseSourceMap ( string, baseURL )

The abstract operation ParseSourceMap takes arguments string (a String) and baseURL (an URL) and returns a Decoded Source Map Record. It performs the following steps when called:

  1. json を ParseJSON(string) とする.
  2. json が JSON object でないならば、エラーをスローする.
  3. JSONObjectGet(json, "sections") が missing でないならば:
    1. DecodeIndexSourceMap(json, baseURL) を返す.
  4. DecodeSourceMap(json, baseURL) を返す.

9.1.2 DecodeSourceMap ( json, baseURL )

The abstract operation DecodeSourceMap takes arguments json (a JSON object) and baseURL (an URL) and returns a Decoded Source Map Record. It performs the following steps when called:

  1. JSONObjectGet(json, "version") が 3𝔽 でないならば、任意でエラーを報告する.
  2. mappingsField を JSONObjectGet(json, "mappings") とする.
  3. mappingsField が String でないならば、エラーをスローする.
  4. JSONObjectGet(json, "sources") が JSON array でないならば、エラーをスローする.
  5. fileField を GetOptionalString(json, "file") とする.
  6. sourceRootField を GetOptionalString(json, "sourceRoot") とする.
  7. sourcesField を GetOptionalListOfOptionalStrings(json, "sources") とする.
  8. sourcesContentField を GetOptionalListOfOptionalStrings(json, "sourcesContent") とする.
  9. ignoreListField を GetOptionalListOfArrayIndexes(json, "ignoreList") とする.
  10. sources を DecodeSourceMapSources(baseURL, sourceRootField, sourcesField, sourcesContentField, ignoreListField) とする.
  11. namesField を GetOptionalListOfStrings(json, "names") とする.
  12. mappings を DecodeMappings(mappingsField, namesField, sources) とする.
  13. mappings を昇順に並べ替える。このとき、 ComparePositions(a.[[GeneratedPosition]], b.[[GeneratedPosition]]) が lesser である場合、Decoded Mapping Record a は Decoded Mapping Record b より小さいものとする.
  14. Decoded Source Map Record { [[File]]: fileField, [[Sources]]: sources, [[Mappings]]: mappings } を返す.

9.1.2.1 GetOptionalString ( object, key )

The abstract operation GetOptionalString takes arguments object (a JSON object) and key (a String) and returns a String or null. It performs the following steps when called:

  1. value を JSONObjectGet(object, key) とする.
  2. value が String ならば、value を返す.
  3. value が missing でないならば、任意でエラーを報告する.
  4. null を返す.

9.1.2.2 GetOptionalListOfStrings ( object, key )

The abstract operation GetOptionalListOfStrings takes arguments object (a JSON object) and key (a String) and returns a List of Strings. It performs the following steps when called:

  1. list を新しい空の List とする.
  2. values を JSONObjectGet(object, key) とする.
  3. values が missing ならば、list を返す.
  4. values が JSON array でないならば:
    1. 任意でエラーを報告する.
    2. list を返す.
  5. JSONArrayIterate(values) の各要素 item について、次を行う:
    1. item が String ならば:
      1. item を list に追加する.
    2. そうでなければ:
      1. 任意でエラーを報告する.
      2. 空の String を list に追加する.
  6. list を返す.

9.1.2.3 GetOptionalListOfOptionalStrings ( object, key )

The abstract operation GetOptionalListOfOptionalStrings takes arguments object (a JSON object) and key (a String) and returns a List of either Strings or null. It performs the following steps when called:

  1. list を新しい空の List とする.
  2. values を JSONObjectGet(object, key) とする.
  3. values が missing ならば、list を返す.
  4. values が JSON array でないならば:
    1. 任意でエラーを報告する.
    2. list を返す.
  5. JSONArrayIterate(values) の各要素 item について、次を行う:
    1. item が String ならば:
      1. item を list に追加する.
    2. そうでなければ:
      1. item ≠ null ならば、任意でエラーを報告する.
      2. null を list に追加する.
  6. list を返す.

9.1.2.4 GetOptionalListOfArrayIndexes ( object, key )

The abstract operation GetOptionalListOfArrayIndexes takes arguments object (an Object) and key (a String) and returns a List of non-negative integers. It performs the following steps when called:

  1. list を新しい空の List とする.
  2. values を JSONObjectGet(object, key) とする.
  3. values が missing ならば、list を返す.
  4. values が JSON array でないならば:
    1. 任意でエラーを報告する.
    2. list を返す.
  5. JSONArrayIterate(values) の各要素 item について、次を行う:
    1. item が整数値を持つ Number であり、item ≥ +0𝔽 ならば:
      1. ℝ(item) を list に追加する.
    2. そうでなければ:
      1. 任意でエラーを報告する.
  6. list を返す.

9.2 対応付けの構造

mappings フィールドのデータは、次のように分解される。

  • 生成ファイルの1行を表す各グループは、セミコロン (;) で区切る。
  • 各セグメントは、コンマ (,) で区切る。
  • 各セグメントは、1個、4個、または5個の可変長フィールドで構成される。

各セグメントのフィールドは、次のとおりである。

  1. セグメントが表す生成コードの行内における、0を起点とする開始列。最初のセグメントの最初のフィールドである場合、または生成コードの新しい行 (;) に続く最初のセグメントである場合、このフィールドは値全体を base64 VLQ として保持する。それ以外の場合、このフィールドは、このフィールドの直前の出現に対する相対値を base64 VLQ として含む。生成コードの各行の後で前の値がリセットされるため、後述する他のフィールドとは異なることに注意する。
  2. 存在する場合、sources リスト内の、0を起点とする索引。このフィールドは、このフィールドの直前の出現に対する相対値を base64 VLQ として含む。ただし、このフィールドが初めて出現する場合は、値全体を表す。
  3. 存在する場合、元のソース内の、0を起点とする開始行。このフィールドは、このフィールドの直前の出現に対する相対値を base64 VLQ として含む。ただし、このフィールドが初めて出現する場合は、値全体を表す。ソースのフィールドがある場合、存在しなければならない。
  4. 存在する場合、元のソースの行内における、0を起点とする開始列。このフィールドは、このフィールドの直前の出現に対する相対値を base64 VLQ として含む。ただし、このフィールドが初めて出現する場合は、値全体を表す。ソースのフィールドがある場合、存在しなければならない。
  5. 存在する場合、このセグメントに関連付けられた names リスト内の、0を起点とする索引。このフィールドは、このフィールドの直前の出現に対する相対値を base64 VLQ として含む。ただし、このフィールドが初めて出現する場合は、値全体を表す。
Note 1
この符号化の目的は、ソースマップのサイズを削減することである。Google Calendar を使用して実施したテストでは、VLQ 符号化により、ソースマップ改訂第2版の提案と比較してソースマップのサイズが50%削減された。
 Note 2
フィールドが1個のセグメントは、コンパイラーが生成したコードなど、対応する元のソースコードがないために対応付けられていない生成コードを表すことを意図している。フィールドが4個のセグメントは、対応する名前が存在しない、対応付けられたコードを表す。フィールドが5個のセグメントは、対応付けられた名前も持つ、対応付けられたコードを表す。
 Note 3
ファイルオフセットの使用も検討されたが、プラットフォーム固有の行末表現によって元のソースとの位置がずれることを避けるため、行・列のデータを使用する方式が採用された。

Decoded Mapping Record は、次のフィールドを持つ。

Table 5: Decoded Mapping Record のフィールド
フィールド名 値の型
[[GeneratedPosition]] Position Record
[[OriginalPosition]] Original Position Record または null
[[Name]] String または null

9.2.1 対応付けの文法

mappings の String は、次の文法に従わなければならない。

MappingsField : LineList LineList : Line Line ; LineList Line : MappingListopt MappingList : Mapping Mapping , MappingList Mapping : GeneratedColumn GeneratedColumn OriginalSource OriginalLine OriginalColumn Nameopt GeneratedColumn : Vlq OriginalSource : Vlq OriginalLine : Vlq OriginalColumn : Vlq Name : Vlq

Decode Mapping State Record は、次のフィールドを持つ。

Table 6: Decode Mapping State Record のフィールド
フィールド名 値の型
[[GeneratedLine]] 非負の整数
[[GeneratedColumn]] 非負の整数
[[SourceIndex]] 非負の整数
[[OriginalLine]] 非負の整数
[[OriginalColumn]] 非負の整数
[[NameIndex]] 非負の整数

9.2.1.1 DecodeMappingsField

The syntax-directed operation DecodeMappingsField takes arguments state (a Decode Mapping State Record), mappings (a List of Decoded Mapping Records), names (a List of Strings), and sources (a List of Decoded Source Records). It is defined piecewise over the following productions:

LineList : Line ; LineList
  1. Line の DecodeMappingsField を、引数 state, mappings, names および sources で実行する.
  2. state.[[GeneratedLine]] を state.[[GeneratedLine]] + 1 に設定する.
  3. state.[[GeneratedColumn]] を 0 に設定する.
  4. LineList の DecodeMappingsField を、引数 state, mappings, names および sources で実行する.
 Line : [empty]
  1. 戻る.
 MappingList : Mapping , MappingList
  1. Mapping の DecodeMappingsField を、引数 state, mappings, names および sources で実行する.
  2. MappingList の DecodeMappingsField を、引数 state, mappings, names および sources で実行する.
 Mapping : GeneratedColumn
  1. GeneratedColumn の DecodeMappingsField を、引数 state, mappings, names および sources で実行する.
  2. state.[[GeneratedColumn]] < 0 ならば:
    1. 任意でエラーを報告する.
    2. 戻る.
  3. position を新しい Position Record { [[Line]]: state.[[GeneratedLine]], [[Column]]: state.[[GeneratedColumn]] } とする.
  4. decodedMapping を新しい DecodedMappingRecord { [[GeneratedPosition]]: position, [[OriginalPosition]]: null, [[Name]]: null } とする.
  5. decodedMapping を mappings に追加する.
 Mapping : GeneratedColumn OriginalSource OriginalLine OriginalColumn Nameopt
  1. GeneratedColumn の DecodeMappingsField を、引数 state, mappings, names および sources で実行する.
  2. state.[[GeneratedColumn]] < 0 ならば:
    1. 任意でエラーを報告する.
    2. 戻る.
  3. generatedPosition を新しい Position Record { [[Line]]: state.[[GeneratedLine]], [[Column]]: state.[[GeneratedColumn]] } とする.
  4. OriginalSource の DecodeMappingsField を、引数 state, mappings, names および sources で実行する.
  5. OriginalLine の DecodeMappingsField を、引数 state, mappings, names および sources で実行する.
  6. OriginalColumn の DecodeMappingsField を、引数 state, mappings, names および sources で実行する.
  7. state.[[SourceIndex]] < 0 または state.[[SourceIndex]] ≥ sources の要素数 または state.[[OriginalLine]] < 0 または state.[[OriginalColumn]] < 0 ならば:
    1. 任意でエラーを報告する.
    2. originalPosition を null とする.
  8. そうでなければ:
    1. originalPosition を新しい Original Position Record { [[Source]]: sources[state.[[SourceIndex]]], [[Line]]: state.[[OriginalLine]], [[Column]]: state.[[OriginalColumn]] } とする.
  9. name を null とする.
  10. Name が存在するならば:
    1. Name の DecodeMappingsField を、引数 state, mappings, names および sources で実行する.
    2. state.[[NameIndex]] < 0 または state.[[NameIndex]] ≥ names の要素数ならば、任意でエラーを報告する.
    3. そうでなければ、name を names[state.[[NameIndex]]] に設定する.
  11. decodedMapping を新しい DecodedMappingRecord { [[GeneratedPosition]]: generatedPosition, [[OriginalPosition]]: originalPosition, [[Name]]: name } とする.
  12. decodedMapping を mappings に追加する.
 GeneratedColumn : Vlq
  1. relativeColumn を Vlq の VLQSignedValue とする.
  2. state.[[GeneratedColumn]] を state.[[GeneratedColumn]] + relativeColumn に設定する.
 OriginalSource : Vlq
  1. relativeSourceIndex を Vlq の VLQSignedValue とする.
  2. state.[[SourceIndex]] を state.[[SourceIndex]] + relativeSourceIndex に設定する.
 OriginalLine : Vlq
  1. relativeLine を Vlq の VLQSignedValue とする.
  2. state.[[OriginalLine]] を state.[[OriginalLine]] + relativeLine に設定する.
 OriginalColumn : Vlq
  1. relativeColumn を Vlq の VLQSignedValue とする.
  2. state.[[OriginalColumn]] を state.[[OriginalColumn]] + relativeColumn に設定する.
 Name : Vlq
  1. relativeName を Vlq の VLQSignedValue とする.
  2. state.[[NameIndex]] を state.[[NameIndex]] + relativeName に設定する.

9.2.2 DecodeMappings ( rawMappings, names, sources )

The abstract operation DecodeMappings takes arguments rawMappings (a String), names (a List of Strings), and sources (a List of Decoded Source Records) and returns a List of Decoded Mapping Record. It performs the following steps when called:

  1. mappings を新しい空の List とする.
  2. mappingsNode を、MappingsField を開始記号として rawMappings を構文解析したときのルート Parse Node とする.
  3. 構文解析に失敗したならば:
    1. 任意でエラーを報告する.
    2. mappings を返す.
  4. state を、すべてのフィールドを 0 に設定した新しい Decode Mapping State Record とする.
  5. mappingsNode の DecodeMappingsField を、引数 state, mappings, names および sources で実行する.
  6. mappings を返す.

9.2.3 生成された JavaScript コードの対応付け

対応付けのエントリーを持ってよい生成コードの位置は、ECMAScript 字句文法に従い、入力要素を用いて定義する。対応付けのエントリーは、次のいずれかを指さなければならない。

9.2.4 生成された JavaScript コードの名前

ソースマップ生成器は、次の条件を満たす場合、JavaScript トークンに対して [[Name]] フィールドを持つ対応付けのエントリーを作成することが望ましい。

  • 元のソース言語の構成要素が、生成された JavaScript コードと意味的に対応する。
  • 元のソース言語の構成要素が名前を持つ。

この場合、対応付けのエントリーの [[Name]] は、元のソース言語の構成要素の名前であることが望ましい。[[Name]] が null でない対応付けを、名前付き対応付けと呼ぶ。

Note 1
関数や変数の名前を変更したり、即時実行関数式から関数名を除去したりするコード圧縮器が、その例である。

次の列挙では、ECMAScript 構文文法の生成規則と、それぞれについてソースマップ生成器が名前付き対応付けを出力することが望ましい、生成規則の右辺にあるトークンまたは非終端記号を示す。そのようなトークンに対して作成される対応付けのエントリーは、9.2.3節に従わなければならない。

この列挙は「最低限」のものとして理解することが望ましい。一般に、ソースマップ生成器は、追加の名前付き対応付けを自由に出力できる。

Note 2
この列挙には、生成器が名前付き対応付けを出力することが「望ましい」トークンに加えて、出力して「よい」トークンも含まれる。これは、既存のツールが名前付き対応付けを出力したり、その存在を期待したりしている実情を反映している。名前付き対応付けを重複させるコストは比較的小さい。names 内の索引は互いに相対的に符号化されるため、同じ名前への後続の対応付けは 0 (A) として符号化される。

9.3 ソースの解決

sourceRoot を先頭に付加した後の sources が絶対 URL でない場合、sources はソースマップに対する相対 URL として解決される。これは、HTML 文書内のスクリプトの src 属性を解決する場合に類似する。

9.3.1 DecodeSourceMapSources ( baseURL, sourceRoot, sources, sourcesContent, ignoreList )

The abstract operation DecodeSourceMapSources takes arguments baseURL (an URL), sourceRoot (a String or null), sources (a List of either Strings or null), sourcesContent (a List of either Strings or null), and ignoreList (a List of non-negative integers) and returns a List of Decoded Source Record. It performs the following steps when called:

  1. decodedSources を新しい空の List とする.
  2. sourcesContentCount を sourcesContent の要素数とする.
  3. sourceUrlPrefix を空の String とする.
  4. sourceRoot ≠ null ならば:
    1. sourceRoot が符号位置 U+002F (SOLIDUS) で終わるならば:
      1. sourceUrlPrefix を sourceRoot に設定する.
    2. そうでなければ:
      1. sourceUrlPrefix を sourceRoot と "/" の文字列連結に設定する.
  5. index を 0 とする.
  6. index < sources の長さである間、次を繰り返す:
    1. source を sources[index] とする.
    2. decodedSource を Decoded Source Record { [[URL]]: null, [[Content]]: null, [[Ignored]]: false } とする.
    3. source ≠ null ならば:
      1. source を sourceUrlPrefix と source の文字列連結に設定する.
      2. sourceURL を、baseURL を使用して source を URL 構文解析した結果とする.
      3. sourceURL が failure ならば、任意でエラーを報告する.
      4. そうでなければ、decodedSource.[[URL]] を sourceURL に設定する.
    4. ignoreList が index を含むならば、decodedSource.[[Ignored]] を true に設定する.
    5. sourcesContentCount > index ならば、decodedSource.[[Content]] を sourcesContent[index] に設定する.
    6. decodedSource を decodedSources に追加する.
    7. index を index + 1 に設定する.
  7. decodedSources を返す.
 Note
ソース内容の表示に対応しているが、同じ URL で内容の異なる複数のソースの表示には対応していない実装は、指定された URL に対応する複数の内容から、いずれか1つを任意に選択する。

9.4 拡張

既存の利用者との互換性を損なわずにこの形式へ機能を追加できるよう、ソースマップ利用器は、認識できない追加のプロパティーがあってもソースマップを拒否せず、そのプロパティーを無視しなければならない。

10 インデックスソースマップ

生成コードの連結や、その他の一般的な後処理を支援するために、ソースマップの別の表現形式をサポートする。

{
  "version" : 3,
  "file": "app.js",
  "sections": [
    {
      "offset": {"line": 0, "column": 0},
      "map": {
        "version" : 3,
        "file": "section.js",
        "sources": ["foo.js", "bar.js"],
        "names": ["src", "maps", "are", "fun"],
        "mappings": "AAAA,E;;ABCDE"
      }
    },
    {
      "offset": {"line": 100, "column": 10},
      "map": {
        "version" : 3,
        "file": "another_section.js",
        "sources": ["more.js"],
        "names": ["more", "is", "better"],
        "mappings": "AAAA,E;AACA,C;ABCDE"
      }
    }
  ]
}

インデックスマップは、標準のマップの形式に従う。通常のソースマップと同様に、ファイル形式は最上位のオブジェクトを持つ JSON である。通常のソースマップと version および file フィールドを共有するが、新たに sections フィールドを持つ。

sections フィールドは、次のフィールドを持つオブジェクトの配列である。

セクションは開始位置の順に並べなければならず、表されるセクション同士が重なってはならない。

10.1 DecodeIndexSourceMap ( json, baseURL )

The abstract operation DecodeIndexSourceMap takes arguments json (an Object) and baseURL (an URL) and returns a Decoded Source Map Record. It performs the following steps when called:

  1. sectionsField を JSONObjectGet(json, "sections") とする.
  2. 表明: sectionsField は missing でない.
  3. sectionsField が JSON array でないならば、エラーをスローする.
  4. JSONObjectGet(json, "version") が 3𝔽 でないならば、任意でエラーを報告する.
  5. fileField を GetOptionalString(json, "file") とする.
  6. sourceMap を Decoded Source Map Record { [[File]]: fileField, [[Sources]]: « », [[Mappings]]: « » } とする.
  7. previousOffsetPosition を null とする.
  8. previousLastMapping を null とする.
  9. JSONArrayIterate(sectionsField) の各 JSON value section について、次を行う:
    1. section が JSON object でないならば:
      1. 任意でエラーを報告する.
    2. そうでなければ:
      1. offset を JSONObjectGet(section, "offset") とする.
      2. offset が JSON object でないならば、エラーをスローする.
      3. offsetLine を JSONObjectGet(offset, "line") とする.
      4. offsetColumn を JSONObjectGet(offset, "column") とする.
      5. offsetLine が整数値を持つ Number でないならば:
        1. 任意でエラーを報告する.
        2. offsetLine を +0𝔽 に設定する.
      6. offsetColumn が整数値を持つ Number でないならば:
        1. 任意でエラーを報告する.
        2. offsetColumn を +0𝔽 に設定する.
      7. offsetPosition を新しい Position Record { [[Line]]: offsetLine, [[Column]]: offsetColumn } とする.
      8. previousOffsetPosition ≠ null ならば:
        1. ComparePositions(offsetPosition, previousOffsetPosition) が lesser ならば、任意でエラーを報告する.
      9. previousLastMapping ≠ null ならば:
        1. ComparePositions(offsetPosition, previousLastMapping.[[GeneratedPosition]]) が lesser ならば、任意でエラーを報告する.
        2. 注記: 復号アルゴリズムのこの部分は、インデックスソースマップの sections フィールドのエントリーが順序付けられ、重複していないことを検査する。生成器はセクションが重複するインデックスソースマップを生成しないことが期待されるが、ソースマップ利用器は、例えば、セクションのオフセットが順序付けられているという、より単純な条件だけを検査してもよい.
      10. mapField を JSONObjectGet(section, "map") とする.
      11. mapField が JSON object でないならば、エラーをスローする.
      12. decodedSectionCompletion を Completion(DecodeSourceMap(json, baseURL)) とする.
      13. decodedSectionCompletion がスロー完了ならば:
        1. 任意でエラーを報告する.
      14. そうでなければ:
        1. decodedSection を decodedSectionCompletion.[[Value]] とする.
        2. decodedSection.[[Sources]] の各 Decoded Source Record additionalSource について、次を行う:
          1. sourceMap.[[Sources]] が additionalSource を含まないならば:
            1. additionalSource を sourceMap.[[Sources]] に追加する.
        3. offsetMappings を新しい空の List とする.
        4. decodedSection.[[Mappings]] の各 Decoded Mapping Record mapping について、次を行う:
          1. mapping.[[GeneratedPosition]].[[Line]] = 0 ならば:
            1. mapping.[[GeneratedPosition]].[[Column]] を mapping.[[GeneratedPosition]].[[Column]] + offsetColumn に設定する.
          2. mapping.[[GeneratedPosition]].[[Line]] を mapping.[[GeneratedPosition]].[[Line]] + offsetLine に設定する.
          3. mapping を offsetMappings に追加する.
        5. sourceMap.[[Mappings]] を sourceMap.[[Mappings]] と offsetMappings のリスト連結に設定する.
        6. previousOffsetPosition を offsetPosition に設定する.
        7. offsetMappings が空でないならば、previousLastMapping を offsetMappings の最後の要素に設定する.
    3. sourceMap を返す.
 Note
実装は、対応付けを連結せずにインデックスソースマップのセクションを表現することを選択してよい。例えば、各セクションを個別に保存し、二分探索を行う方法がある。

11 ソースマップの取得

11.1 生成コードとソースマップの関連付け

ソースマップ形式は言語やプラットフォームに依存しないことを意図しているが、想定される用途である、ウェブサーバーでホストされる JavaScript について、ソースマップの参照方法を定義しておくことは有用である。

出力にソースマップを関連付ける方法は2つある。1つ目は、HTTP ヘッダーを追加するためのサーバー側の対応を必要とし、2つ目は、ソース内の注釈を必要とする。

ソースマップは、WHATWG URL で定義された URL を通して関連付ける。特に、URI に現れることが許可された集合に属さない文字は、パーセント符号化しなければならない。また、URL はデータ URI であってもよい。データ URI を sourcesContent とともに使用すると、完全に自己完結したソースマップを作成できる。

HTTP の sourcemap ヘッダーはソース内の注釈より優先される。両方が存在する場合、ヘッダーの URL を使用してソースマップファイルを解決することが望ましい。

ソースマップ URL の取得方法にかかわらず、その解決には次の同じ処理を使用する。

ソースマップ URL が絶対 URL でない場合、それは生成コードのソースオリジンに対する相対 URL である。ソースオリジンは、次のいずれかの場合によって決定する。

  • 生成されたソースが src 属性を持つ script 要素に関連付けられておらず、生成コード内に //# sourceURL コメントが存在する場合、そのコメントを使用してソースオリジンを決定することが望ましい。

    Note
    以前は //@ sourceURL が使用されていた。//@ sourceMappingURL と同様に、両方を受け入れることは妥当であるが、//# が推奨される。
  • 生成コードが script 要素に関連付けられており、その script 要素が src 属性を持つ場合、script 要素の src 属性をソースオリジンとする。
  • 生成コードが script 要素に関連付けられており、その script 要素が src 属性を持たない場合、ページのオリジンをソースオリジンとする。
  • 生成コードが eval() 関数または new Function() を通して文字列として評価される場合、ページのオリジンをソースオリジンとする。

11.1.1 HTTP ヘッダーによる関連付け

ファイルが sourcemap ヘッダーとともに HTTP(S) で配信される場合、そのヘッダーの値は、関連付けられたソースマップの URL である。

sourcemap: <url>
Note
この文書の以前の改訂では、ヘッダー名として x-sourcemap を推奨していた。これは現在では非推奨であり、sourcemap の使用が期待される。

11.1.2 インライン注釈による関連付け

生成コードには、sourceMappingURL という名前でソースマップの URL を含むコメント、または言語や形式に応じた同等の構成要素を含めることが望ましい。この仕様は、JavaScript、CSS、および WebAssembly について、そのコメントの形式を定義する。他の言語も、同様の規約に従うことが望ましい。

実装ごとに、より複雑でない方法を選択できるよう、同じ言語について sourceMappingURL コメントを検出する方法が複数あってもよい。すべての抽出方法の結果が同じである場合、生成コードはソースマップに曖昧さなく関連付けられているという。

ソースマップに曖昧さなく関連付けられた1つ以上のソースファイルをツールが入力として受け取り、ソースマップに関連付けられた出力ファイルを生成する場合、その関連付けも曖昧さのないものでなければならない。

Note

次の JavaScript コードはソースマップに関連付けられているが、その関連付けは曖昧さのないものではない。

let a = `
//# sourceMappingURL=foo.js.map
// `

ここからソースマップ URL を構文解析によって抽出すると foo.js.map が得られる一方、構文解析せずに抽出すると null が得られる。

11.1.2.1 JavaScriptExtractSourceMapURL ( source )

The abstract operation JavaScriptExtractSourceMapURL takes argument source (a String) and returns a String or null. JavaScript のソースからソースマップ URL を抽出する。実装方法は2つあり、構文解析による方法と、構文解析しない方法のいずれかを使用できる。

ソースマップ URL を構文解析によって抽出するには、次を行う。

  1. tokens を、入力要素の List とする。これは source を ECMA-262 の字句文法に従って解析して得られる.
  2. tokens の各非終端記号 token について、逆順で次を行う:
    1. token が SingleLineComment、WhiteSpace、LineTerminatorSequence のいずれでもないならば、null を返す.
    2. comment を token の内容とする.
    3. sourceMapURL を MatchSourceMapURL(comment) とする.
    4. sourceMapURL が String ならば、sourceMapURL を返す.
  3. null を返す.

ソースマップ URL を構文解析せずに抽出するには、次を行う。

  1. lines を StringSplit(source, « "\u000D\u000A", "\u000A", "\u000D", "\u2028", "\u2029" ») とする.
  2. 注記: 上記の文字列のリストは、LineTerminatorSequence 生成規則に対応する.
  3. lines の各 String lineStr について、List の逆順で次を行う:
    1. line を StringToCodePoints(lineStr) とする.
    2. position を 0 とする.
    3. lineLength を line の長さとする.
    4. position < lineLength である間、次を繰り返す:
      1. first を line[position] とする.
      2. first が U+002F (SOLIDUS) であり、position + 1 < lineLength ならば:
        1. position を position + 1 に設定する.
        2. second を line[position] とする.
        3. second が U+002F (SOLIDUS) ならば:
          1. position を position + 1 に設定する.
          2. comment を lineStr の position から lineLength までの部分文字列とする.
          3. comment が符号位置 U+0022 (QUOTATION MARK)、U+0027 (APOSTROPHE)、または U+0060 (GRAVE ACCENT) のいずれかを含むならば:
            1. null を返す.
          4. comment が符号位置 U+002A (ASTERISK) の直後に符号位置 U+002F (SOLIDUS) が続く並びを含むならば:
            1. null を返す.
          5. sourceMapURL を MatchSourceMapURL(comment) とする.
          6. sourceMapURL が String ならば、sourceMapURL を返す.
          7. position を lineLength に設定する.
        4. そうでなければ:
          1. null を返す.
      3. そうでなく、first が ECMAScript の WhiteSpace ならば:
        1. position を position + 1 に設定する.
      4. そうでなければ:
        1. null を返す.
  4. null を返す.
 Note

source をエラーなく構文解析でき、そこからソースマップ URL を構文解析せずに抽出した結果が null でない場合、構文解析によって抽出しても同じ結果が得られる。

11.1.2.1.1 MatchSourceMapURL ( comment )

The abstract operation MatchSourceMapURL takes argument comment (a String) and returns either none or a String. It performs the following steps when called:

  1. pattern を RegExpCreate("^[@#]\s*sourceMappingURL=(\S*?)\s*$", "") とする.
  2. match を RegExpExec(pattern, comment) とする.
  3. match が null でないならば、 Get(match, "1") を返す.
  4. none を返す.
 Note
この注釈の接頭辞は当初 //@ であったが、Internet Explorer の条件付きコンパイルと競合するため、//# に変更された。

ソースマップ生成器は //# だけを出力しなければならず、ソースマップ利用器は //@ と //# の両方を受け入れなければならない。

11.1.2.2 CSSExtractSourceMapURL ( source )

The abstract operation CSSExtractSourceMapURL takes argument source (a String) and returns a String or null. CSS のソースからソースマップ URL を抽出する。

CSS からのソースマップ URLの抽出は、CSS が /* ... */ 形式のコメントだけをサポートする点を除き、JavaScript の場合と同様である。

11.1.2.3 WebAssemblyExtractSourceMapURL ( bytes )

The abstract operation WebAssemblyExtractSourceMapURL takes argument bytes (a Data Block) and returns a String or null. WebAssembly のバイナリーソースからソースマップ URL を抽出する。
  1. module を module_decode(bytes) とする.
  2. module が WebAssembly error ならば、null を返す.
  3. module の各カスタムセクション customSection について、次を行う:
    1. name を customSection の name とする.
    2. CodePointsToString(name) が "sourceMappingURL" ならば:
      1. value を customSection の bytes とする.
      2. CodePointsToString(value) を返す.
  4. null を返す.

WebAssembly はテキスト形式ではなく、コメントをサポートしないため、曖昧さのない単一の抽出方法をサポートする。URL は WebAssembly の名前として符号化され、カスタムセクションの内容として配置される。WebAssembly コードを生成するツールが、sourceMappingURL という名前のカスタムセクションを2つ以上生成することは無効である。

11.2 ソースマップのフェッチ

11.2.1 FetchSourceMap ( url )

The abstract operation FetchSourceMap takes argument url (an URL) and returns a Promise. It performs the following steps when called:

  1. promiseCapability を NewPromiseCapability(%Promise%) とする.
  2. request を、リクエスト URL が url である新しいリクエストとする.
  3. processResponseConsumeBody を、仮引数 (response, bodyBytes) を持ち、promiseCapability および url をキャプチャーし、呼び出されたときに次の手順を実行する新しい Abstract Closure とする:
    1. bodyBytes が null または failure ならば:
      1. Call(promiseCapability.[[Reject]], undefined, « 新しい TypeError ») を実行する.
      2. 戻る.
    2. url のスキームが HTTP(S) スキームであり、バイト列 `)]}'` が bodyBytes のバイト列接頭辞ならば:
      1. bodyBytes のバイト列長 ≠ 0 であり、bodyBytes[0] が HTTP 改行バイトでない間、次を繰り返す:
        1. bodyBytes から0番目の要素を除去する.
    3. bodyString を Completion(bodyBytes を UTF-8 decode した結果) とする.
    4. IfAbruptRejectPromise(bodyString, promiseCapability).
    5. jsonValue を Completion(ParseJSON(bodyString)) とする.
    6. IfAbruptRejectPromise(jsonValue, promiseCapability).
    7. Call(promiseCapability.[[Resolve]], undefined, « jsonValue ») を実行する.
  4. processResponseConsumeBody を processResponseConsumeBody に設定して、request のフェッチを実行する.
  5. promiseCapability.[[Promise]] を返す.
 Note

歴史的な理由により、HTTP(S) でソースマップを配信する場合、サーバーは文字列 )]}' で始まる行をソースマップの先頭に付加してよい。

)]}'garbage here
{"version": 3, ...}

は、次のように解釈される。

{"version": 3, ...}

12 ソースマップレコードに対する操作

ソースマップを復号した後、ソースマップ利用器は、得られた Decoded Source Map Record を使用して、デバッグなどの用途のために位置情報を検索できる。この節では、ソースマップ利用器がサポートしてよい代表的な操作の動作を記述する。

GetOriginalPositions 操作は、生成コード内のある位置に対応する、元のソース内の位置を問い合わせるために使用してよい。例えば、デバッガーで利用者のマウスクリックに基づき、生成コードから元のソースへ移動するために使用できる。

12.1 GetOriginalPositions ( sourceMapRecord, generatedPosition )

The abstract operation GetOriginalPositions takes arguments sourceMapRecord (a Decoded Source Map Record) and generatedPosition (a Position Record) and returns a List of Original Position Records. It performs the following steps when called:

  1. mappings を sourceMapRecord.[[Mappings]] とする.
  2. last を null とする.
  3. originalPositions を新しい空の List とする.
  4. mappings の各要素 mapping について、List の逆順で次を行う:
    1. last が null ならば:
      1. ComparePositions(mapping.[[GeneratedPosition]], generatedPosition) の実行結果が lesser または equal ならば:
        1. last を mapping に設定する.
  5. last が null でないならば:
    1. mappings の各要素 mapping について、次を行う:
      1. ComparePositions(last.[[GeneratedPosition]], mapping.[[GeneratedPosition]]) の実行結果が equal ならば:
        1. mapping.[[OriginalPosition]] を originalPositions に追加する.
  6. originalPositions を返す.

Annex A (informative) 慣例

ソースマップを扱う場合、または生成する場合は、次の慣例に従うことが望ましい。

A.1 ソースマップの命名

一般に、ソースマップには、生成ファイルの名前に .map 拡張子を付けた名前を使用する。例えば、page.js に対しては、page.js.map という名前のソースマップを生成する。

A.2 eval で評価されるコードと名前付き生成コードの関連付け

eval で評価されるコードでソースマップを使用するための既存の慣例があり、これをサポートすることが望ましい。その形式は、次のとおりである。

//# sourceURL=foo.js

これは「//@ sourceURL で eval に名前を付ける」で説明されている。

Annex B (informative) 注記

B.1 言語に依存しないスタックの対応付け

ソース言語についての知識を用いないスタックトレースの対応付けは、この文書の対象ではない。

B.2 多段階の対応付け

ツールが何らかの DSL（テンプレート）からソースを生成したり、TypeScript → JavaScript → 圧縮された JavaScript という順にコンパイルしたりして、最終的なソースマップの作成までに複数回の変換を行うことが、ますます一般的になっている。この問題は、2つの方法のいずれかで扱える。容易だが情報が失われる方法は、デバッグのためには処理途中の段階を無視することである。この場合、変換によるソース位置情報を無視する（中間の変換結果を「元のソース」と見なす）か、ソース位置情報を引き継ぐ（中間の変換を隠す）。より完全な方法は、複数段階の対応付けをサポートすることである。元のソースにもソースマップへの参照がある場合、それも使用するかどうかを利用者が選択できるようにする。

ただし、JavaScript 以外で「ソースマップへの参照」がどのような形式になるかは明確でない。より具体的には、JavaScript 形式の単一行コメントをサポートしない言語で、ソースマップへの参照をどのように表すかが明確でない。

Annex C (informative) 他の仕様で定義される用語

この節では、この文書で使用する用語およびアルゴリズムのうち、ECMA-262 以外の外部仕様で定義されるものをすべて列挙する。

WebAssembly コア仕様 <https://www.w3.org/TR/wasm-core-2/>
カスタムセクション, module_decode, WebAssembly error, WebAssembly の名前
WHATWG Encoding <https://encoding.spec.whatwg.org/>
UTF-8 decode
WHATWG Fetch <https://fetch.spec.whatwg.org/>
フェッチ, HTTP 改行バイト, processResponseConsumeBody, リクエスト, リクエスト URL
WHATWG Infra <https://infra.spec.whatwg.org/>
バイト列, バイト列接頭辞, バイト列長,
WHATWG URL <https://url.spec.whatwg.org/>
HTTP(S) スキーム, スキーム, URL, URL 構文解析

Annex D (informative) 文献一覧

  1. IETF RFC 4648, Base16、Base32、および Base64 のデータ符号化、参照先: <https://datatracker.ietf.org/doc/html/rfc4648>
  2. ECMA-262, ECMAScript® 言語仕様、参照先: <https://tc39.es/ecma262/>
  3. ECMA-404, JSON データ交換形式、参照先: <https://www.ecma-international.org/publications-and-standards/standards/ecma-404/>
  4. WebAssembly コア仕様、参照先: <https://www.w3.org/TR/wasm-core-2/>
  5. WHATWG Encoding、参照先: <https://encoding.spec.whatwg.org/>
  6. WHATWG Fetch、参照先: <https://fetch.spec.whatwg.org/>
  7. WHATWG Infra、参照先: <https://infra.spec.whatwg.org/>
  8. WHATWG URL、参照先: <https://url.spec.whatwg.org/>
  9. //@ sourceURL で eval に名前を付ける、Firebug (2009)、参照先: <http://blog.getfirebug.com/2009/08/11/give-your-eval-a-name-with-sourceurl/>
  10. ソースマップ改訂第2版の提案、John Lenz (2010)、参照先: <https://docs.google.com/document/d/1xi12LrcqjqIHTtZzrzZKmQ3lbTv9mKrN076UB-j3UZQ/>
  11. 可変長数量、Wikipedia、参照先: <https://en.wikipedia.org/wiki/Variable-length_quantity>

Annex E (informative) 奥付

この仕様は、Ecmarkup というプレーンテキストのソース形式を使用し、GitHub で執筆されている。Ecmarkup は HTML と Markdown の方言であり、ECMAScript 仕様をプレーンテキストで執筆し、この文書の編集規約に従った、十分な機能を備える HTML 表示へと処理するための枠組みとツール群を提供する。Ecmarkup は、構文定義用の Grammarkdown や、アルゴリズムの手順の記述用の Ecmarkdown など、他の複数の形式や技術を基盤とし、統合している。この仕様の PDF 版は、HTML 表示を PDF に印刷することで作成される。

この仕様の初版は、HTML と Markdown に基づく別のプレーンテキストのソース形式である Bikeshed を使用して執筆された。

この文書の標準化前の版は、Google Docs を使用して執筆された。

Copyright & Software License

Ecma International

Rue du Rhone 114

CH-1204 Geneva

Tel: +41 22 849 6000

Fax: +41 22 849 6001

Web: https://ecma-international.org/

Software License

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.