docs-validate-code-samples

Elastic ドキュメント用のコードサンプル検証ツールです。1 つ以上の Markdown ファイルにあるすべてのコードブロックを、docs-builder のスタイルルールに照らして確認し、違反をすべて報告してください。

ドキュメントのソースファイルは変更しないでください。分析と報告のみを行ってください。

---

ステップ 1：ファイルを解決する

$ARGUMENTS を解析して、任意の --output <path> フラグを特定します（続行する前に取り除いてください）。対象を解決します。

• 単一の .md ファイル — そのファイルのみを分析します。
• ディレクトリ — find <dir> -name "*.md" -type f | sort ですべての .md ファイルを再帰的に検索します。
• グロブ — bash -O globstar -c 'printf "%s\n" <glob>' で展開します。
• 引数なし — 「ファイルパス、ディレクトリ、またはグロブパターンを指定してください。」と尋ねます。

---

ステップ 2：コードブロックを抽出する

各ファイルで、Grep を使ってパターン ^``` に一致するフェンス行番号を検索し、次に Read でファイルを読み込んでブロックを抽出します。リスト項目内のブロックを検出するため、インデント付きフェンス（^\s+```）も検索します。

• HTML コメント内のブロック（``）はスキップします。
• 情報文字列が {} で始まり、{} で終わる MyST ディレクティブブロック（例：```{note}）はスキップします。

各ブロックについて、開始行番号、フェンスの情報文字列、言語識別子（最初の語）、属性（残りのトークン）、本文を記録します。

---

ステップ 3：チェック A〜H を実行する

チェック A — 言語識別子の欠落または誤り

フェンスの情報文字列が空のブロックをすべて指摘します。また、内容に対して言語識別子が明らかに誤っているブロックも指摘します（例：JSON のみの応答に js を使用している場合、HTTP メソッド行がなく応答データのみなのに console を使用している場合）。

一般的な有効な識別子：bash、sh、console、console-result、json、yaml、python、javascript、js、typescript、java、go、ruby、sql、esql、eql、painless、kql、kuery、txt、text、xml、toml、ini、diff。

内容から適切な識別子を推定します。HTTP メソッド行 → console、{／[ で始まる → json、key: value の行 → yaml、curl／apt-get → bash、import／def／print( → python、public class → java、const／let／=> → javascript。

チェック B — subs=true のない変数置換

対象ファイルから上の階層をたどり、docset.yml を探して、その subs: セクションにある有効な変数名を解析します。.git/ の存在で判定する Git ルート、または 6 階層上のいずれかに達したら探索を止めます。ブロックに {{var}} が含まれており、var が定義済みの置換キーであるにもかかわらず、フェンスの情報文字列に subs=true がない場合は指摘します。逆に、{{...}} パターンがないブロックに subs=true が付いている場合も指摘します。

docset.yml が見つからない場合は、{{word}} パターン（単一の識別子）をすべて、置換変数である可能性があるものとして指摘します。

チェック C — コールアウトにすべきインラインコメント

言語が bash、sh、shell、console、yaml、python、javascript、js、typescript、java、go、ruby のブロックについて、同じ行にコードがある状態で # または // がコードの後に現れ、そのコメントが読者向けの説明である行を指摘します。

例外：シェバン行、単独のコメント行（同じ行にコードがない）、文字列内の #、すでにコールアウトマーカー（<1>）を使用している行。

提案：明示的なコールアウトマーカー（<N>）に置き換え、ブロックの後に番号付きリストを追加します。

チェック D — console ブロックと console-result ブロックの JSON 検証

console ブロックは API リクエスト（顧客がコピーして貼り付けるもの）で、console-result ブロックはレスポンス（表示のみ）です。各 console ブロックには 1 つ以上の API 呼び出しが含まれます。HTTP メソッドとパスの行に続いて、任意で JSON 本文が記述され、複数の呼び出しがある場合はこれが繰り返されます。

console ブロック内の ... は必ず指摘してください — 許容されません。現実的な値に置き換えてください。console-result 内の ... は問題ありません。

JSON 解析の前に、両方のブロックタイプを前処理してください：

1. 行末にあるコールアウトマーカー（<N>）と、その直前の //／# を取り除きます。
2. {{var}}／{{{var}}} テンプレート変数をプレースホルダー文字列に置き換えます。
3. JSON 本文を組み立てる際、単独行の # または // コメントはスキップします。
4. 三重引用符で囲まれた Painless 文字列（"""..."""）を、複数行に対応した perl の置換を使ってプレースホルダーに置き換えます。
5. console-result のみ：... の省略記号を正規化します — [...] を [] に、{...} を {} に、: ... を : null に置き換え、単独行の ... を取り除きます。
6. } または ] の前にある末尾のカンマを検出して指摘します（黙って修正しないでください）。

NDJSON（_bulk）： メソッド行に _bulk が含まれる場合は、空でない各行を個別の JSON オブジェクトとして検証します。それ以外の場合は、本文全体を jq で検証します。

指摘しないもの： Painless スクリプト（解析前に置換済み）、EQL／ES|QL の文字列値、コールアウトマーカーとテンプレート変数（すでに取り除かれています）。

チェック E — 予約されていないドメイン名

コードブロック内の URL またはホスト名で、実在する TLD を持つ架空のプレースホルダードメイン（例：mycompany.com、mycluster.io）が使われている場合は指摘してください。

安全 — 指摘しないでください：example.com/net/org とそのサブドメイン、.example／.test／.localhost／.invalid TLD、localhost、ループバック（127.x.x.x）、RFC 5737 のドキュメント用 IP（192.0.2.x、198.51.100.x、203.0.113.x）、プライベートアドレス範囲、および既知の正規ドメイン：elastic.co、amazonaws.com、azure.com、googleapis.com、docker.com、github.com、pypi.org、npmjs.com、その他のよく知られたレジストリやクラウドプロバイダーなど。

提案：example.com または my-cluster.example.com のようなサブドメインに置き換えてください。

チェック F — console ブロックの API 検証

まず、すべてのファイルから一意な METHOD /path の値を収集します。一意なエンドポイントごとに（今回の実行で以前に検証済みのものはスキップ）、クエリ "request body fields <endpoint> elasticsearch API"（product: elasticsearch、section: api）を指定して mcp__elastic-docs__search_docs を呼び出し、一致する API リファレンスページ（URL が /docs/api/doc/elasticsearch/operation/ で始まるもの）を探します。mcp__elastic-docs__get_document_by_url（include_body: true）でそのページを取得します。

• 一致するページが見つからない場合： エンドポイントが削除または名前変更された可能性があるとして指摘します。
• 非推奨のフィールド： 最上位のリクエスト本文キーがドキュメント内の「deprecated」とともに現れる場合は、置き換え先とともに指摘します。
• 認識されないフィールド（参考情報）： 最上位のキーがドキュメント本文にまったく現れない場合は、確認が必要な項目として記載します。

指摘しないもの： _ で始まるメタデータフィールド、ネストされたオブジェクトキー、標準の Search DSL フィールド（query、aggs、sort、size、from、highlight、knn、retriever、script）。

問題の詳細には必ず API ドキュメントの URL を含めてください。

チェック G — ES|QL 構文の検証

G-1 — ソースコマンド： 空行でもコメント行でもない最初の行は、FROM、PROMQL、ROW、SHOW INFO、または TS でなければなりません。処理コマンドから始まるブロック（ソースの欠落）、または SELECT から始まるブロック（SQL 構文）を報告してください。

G-2 — パイプコマンド名： | で始まる各行では、認識済みのコマンドを使用する必要があります。認識済みコマンドは、CHANGE_POINT、COMPLETION、DEDUP、DISSECT、DROP、ENRICH、EVAL、FORK、FUSE、GROK、HIGHLIGHT、INLINE STATS、IP_LOCATION、KEEP、LIMIT、LOOKUP JOIN、METRICS_INFO、MMR、MV_EXPAND、REGISTERED_DOMAIN、RENAME、RERANK、SAMPLE、SORT、STATS、TS_COLLAPSE、TS_INFO、URI_PARTS、USER_AGENT、WHERE です。認識されない名前を報告してください。

G-2a — 不完全なパイプコマンド： コマンド名が認識されるだけでは不十分です。パイプコマンドが記述されているのに、同じ行に引数が続かない場合は報告してください。必要な引数：

コマンド	必要なもの
KEEP、DROP	1 つ以上のフィールド名
WHERE	条件式
SORT	1 つ以上のフィールド
EVAL、STATS	1 つ以上の式
RENAME	1 つ以上の old AS new ペア
DISSECT、GROK	入力フィールドとパターン
ENRICH	ポリシー名
LOOKUP JOIN	ルックアップインデックス名と ON <field>

G-3 — SQL 構文： 行頭の SELECT、GROUP BY、（LOOKUP を伴わない）JOIN、ORDER BY を報告してください。これらはすべて ES|QL では無効な SQL 構文です。

G-4 — 報告しないもの： // コメント行、パイプの後にある WHERE、文字列内の FROM、コメントまたは空行のみのブロック。

チェック H — Painless スクリプトの検証

Painless は、単独の ```painless ブロックと、console ブロック内の三重引用符 """...""" 文字列の 2 か所に記述されます。チェック D がそれらをプレースホルダーに置き換える前に、Bash 経由で複数行に一致する perl パターンを使用して、console ブロックからインライン Painless を抽出してください。

各 Painless ソースに対して、以下のチェックを実行してください。

H-1 — 区切り文字の対応： {}、[]、() のペアの数を数えます。不均衡があれば報告してください。文字列リテラル内の区切り文字は数えないでください。

H-2 — 非推奨の .getValue() API： doc フィールドに対する .getValue() は非推奨です。使用箇所を報告し、代わりに .value を提案してください（例：doc['field'].value）。

H-3 — 利用できない API： System.out、System.err、System.exit、Thread.sleep、Runtime.getRuntime、または ProcessBuilder の使用を報告してください。これらは Painless サンドボックスでは利用できません。デバッグには、代わりに Painless 実行 API（POST /_scripts/painless/_execute）の使用を提案してください。

H-4 — 報告しないもの： // コメント行、引用符で囲まれた文字列内の区切り文字、区切り文字を含まない単一式のスクリプト、空またはコメントのみのブロック。

---

ステップ 4：レポートを生成する

2 つのセクションを出力してください。問題のあるファイルがない場合は、その表を省略してください。

セクション 1 — 概要表：

## Code Sample Validation Report

**Target:** <path>
**Files checked:** N
**Issues found:** N

### Summary

#### All blocks (Checks A, B, C, E)
| File | Missing/wrong lang | subs=true | Callout | Domain | Total |
|------|--------------------|-----------|---------|--------|-------|

#### Console / console-result blocks (Checks D, F)
| File | Ellipsis | JSON errors | API Validation | Total |
|------|----------|-------------|----------------|-------|

#### ES|QL blocks (Check G)
| File | Source cmd | Pipe cmd | SQL-ism | Total |
|------|------------|----------|---------|-------|

#### Painless blocks (Check H)
| File | Unbalanced delimiters | Deprecated API | Unavailable API | Total |
|------|-----------------------|----------------|-----------------|-------|

セクション 2 — 問題の詳細：ファイルごとにサブセクションを 1 つ作成します。

#### `path/to/file.md` — Line N — Check X — Short title

> **Issue:** description
> **Suggestion:** fix

```
  context lines around the error
      ^
```

JSON エラーについては、jq のエラーメッセージと、問題の行の前後最大 2 行のコンテキストを、該当箇所を指す ^ とともに記載してください。インライン Painless スクリプトについては、問題が単独ブロックと埋め込みの三重引用符文字列のどちらに由来するかを明記してください。

問題が見つからなかった場合は、セクション 2 の代わりに「チェックしたすべてのファイルで問題は見つかりませんでした。」と出力してください。

出力モード： --output <path> が指定されていない限り、コンソールに出力してください。指定されている場合は、レポートを Markdown ファイルとして書き込み、パスを確認してください。

---

ガイドライン

• 報告する各ブロックについて、開始フェンスの行番号を記載してください。
• 誤検出を報告しないでください。曖昧なインラインコメントはスキップし、H-1 は不均衡が明白な場合にのみ適用してください。
• Markdown 以外のファイルは黙ってスキップしてください。読み取れないファイルは記録し、処理を続行してください。