Guidedog / ドキュメント 0.2.0

エラーメッセージ¶

診断は問題の名前、場所、役立つ次の操作を示すべきです。Guidedog はその情報を構造化データとして保持します。端末では色とソースの印を付けます。JSON は装飾なしでデータを保持します。

診断の読み方¶

UNDEFINED SUBSTITUTION                              rst.substitution.undefined

  guide/page.rst:4: See |logo| here.
                        ^^^^^^

The substitution "|logo|" is not defined.
No output was written.

Add a definition, e.g. ".. |name| replace:: text".

診断は常に次の順序で、4 つの部分からなります。

タイトル行。問題の種類を大文字で示します。警告と注記は WARNING: と NOTE: で始まります。右端の rst.substitution.undefined などは、検索に使える安定した診断コードです。
場所。ファイル、行番号、ソースの行と問題箇所の下の印を示します。ディレクトリ不足やオプションなど、特定の行に関係しない問題ではパスだけ、または場所なしで表示します。
何が起きたか。問題を説明し、必要なら出力への影響も示します。この例では何も書き出していないことです。
何をすべきか。カラー端末では緑で示す、具体的な修正方法です。複数ある場合は、最も可能性の高い方法から列挙します。

色は文章で伝えた内容を強調するだけです。--color=never で色を無効にし、--color=always で端末以外の出力にも色を残せます。

次の操作を示すヒント¶

Guidedog 自身のメッセージにもこの規則を課す。ヒントは操作（「Add」「Pass」「Set」「Rename」「Run」）と、その対象を示す。例えば --budget=MIB、conf.toml の root_doc、ディレクティブのオプションだ。tests/hints_test.odin は全メッセージを読み、空のヒント、本文の繰り返し、報告内容を示さない「report this」を拒否する。修正を直接示す提案（「Did you mean numfig?」）と、操作不要の注記「Nothing to do:」に理由を添える形式も認める。

Guidedog 自身の不具合なら、そのことを明示します。実行したコマンド、原因となった入力、guidedog --version の出力を添えて報告するよう案内します。

プログラム向けの診断¶

--diagnostics=json は標準エラーに一行一個の JSON オブジェクトとして報告を書く。エディターや継続的インテグレーションから読める。

{"schema":1,"code":"rst.substitution.undefined","severity":"error",
 "title":"UNDEFINED SUBSTITUTION","message":"The substitution \"|logo|\" is not defined.",
 "hint":"Add a definition, e.g. \".. |name| replace:: text\".","path":"guide/page.rst",
 "line":4,"column":5,"end_line":4,"end_column":11,"source":"See |logo| here.",
 "category":""}

ここでは折り返して示すが、実際は一オブジェクト一行。schema はフィールドが変わったときだけ更新する形式の版で、他を読む前に確認する。列は1から始まる Unicode スカラー数で、バイト数や端末の桁数ではない。source は元の行全体。端末はエラー周辺だけを表示し、制御文字のエスケープと全角文字の幅を考慮して印を合わせる。category は suppress_warnings で使う警告分類、または空。

メモリが足りないとき¶

メモリ不足も診断として報告し、クラッシュしません。2 種類あります。

host.budget（メモリ予算の上限）

ビルドが保持可能なメモリ予算（--budget=MIB、既定 1 GiB）に達した。報告は該当の工程を、テンプレートなら要求元の行も示す。端末では一度だけ、予算を増やすか、作業メモリをディスクに置いて続けるか、停止するかを尋ねる。端末以外では停止する。--budget または --memory=disk で事前に選べる。ヒントも予算を数値で示す。

Build again with --budget=256, or with --memory=disk to keep working memory on
disk (slower); or split the work into smaller files.

提案値は、現在の保持量に拒否された工程の要求量を4倍して加えた量（工程は出力と書き込み用コピーも保持する）と旧予算の2倍の大きい方を、64 MiB 単位で切り上げる。工程が空きメモリに収まる場合はその空き量を超えない。収まらない場合はその旨を示し、まず --memory=disk を提案する。

Build again with --memory=disk to keep working memory on disk (slower): the step
needs a budget of about 1408 MiB, more than the 900 MiB this machine has free. Or
free that memory and build with --budget=1408, or split the document.

host.memory（メモリ不足）

予算内の要求をシステムが拒否した。命令はそのメモリを使わず停止する。ビルドは公開せず、GDS の変更は全部か無変更、convert は一ページ全部か無出力となる。メモリを解放するかスレッドを減らして（-j 1）再実行する。公開を決定した後の切り替えはメモリを必要とせず、拒否で半公開にはならない。以前の未完了の公開を見つけても復旧計画のメモリがなければ、そのまま次のビルドに残す。

どちらもステータス 3 で終了します。

終了ステータス¶

各コマンドは次のいずれかのステータスで終了するため、スクリプトで失敗の種類を区別できます。

状態	意味
0	成功です。出力を書き込み、ビルドの場合は公開しました。
1	入力に問題があります。文書のエラー、方針による拒否（`--raw` なしの raw コンテンツ）、読み取れない文書、または `-W`・`--strict` でエラー扱いになった警告です。
2	コマンドの使い方が不正です。不明なオプションやコマンド、値の不足・不正、`conf.toml` や `-D` の不正な設定です。
3	制限に達しました。メモリ予算（`--budget`）、入れ子の深さ（`--max-depth`）、ノード数（`--max-nodes`）、スタック（`--stack-kib`）、大きすぎるソース、またはシステムが供給できないメモリです。
4	ファイルまたは外部プログラムの失敗です。読み書きできないパス、読み取り中に変わったファイル、Typst の起動・完了の失敗などです。
5	Guidedog 内部の失敗です。診断は不具合の報告を依頼します。
70	Guidedog がクラッシュすると、`GUIDEDOG CRASHED (internal error)` と実行した命令、障害、`guidedog --version` の結果を表示する。報告先はビルドが指定する課題管理、なければ提供者。ビルドは最後に公開するので、以前の出力は残る。
130	Ctrl+C で中断されました。公開済みのファイルは変わりません。

理由にかかわらずビルドが失敗すると、前の出力とビルド記録はそのまま残ります。問題を修正して再ビルドしてください。