reference

extract-from-md v6 仕様書 / エージェント指示 / マニュアル

extract-from-md v6

0. v5 → v6 変更点

項目v5v6
Markdown 解析手書き正規表現 + フェンス走査unified + remark-parse による MDAST 解析
コードブロック検出FENCE_OPEN_RE で1行ずつ走査unist-util-visit で AST の type:'code' ノードを走査
境界ケース4連バッククォート、リスト内インデント、コード内 ``` などで誤動作の可能性CommonMark 準拠で全ケースを正確に処理
フェンス情報の解釈parseFenceInfo() が info 文字列を自前でトークン化node.lang + node.meta を MDAST から受け取り parseFenceInfoFromMDAST() で解釈
依存関係Node.js stdlib のみunified, remark-parse, unist-util-visit を追加
Node.js14+16+ (ESM only)

0.1 なぜ AST ベースにしたか

v5 までの手書き正規表現パーサは、以下の境界ケースで誤動作するリスクがあった:

  • 4連バッククォート: ````js で開いたブロックを ``` で閉じてしまう
  • リスト内インデント: リスト項目内のコードブロックが正しく認識されない
  • **コード内の 文字列**: コードブロックの本文中に `` “ が含まれる場合、フェンスの終端と誤認
  • 未終端フェンス: メッセージが途中で切れた場合の挙動が不安定
  • チルダフェンス: ~~~ と ``` の混在

remark-parse は CommonMark 準拠のステートマシン で解析するため、これらのケースを全て正しく処理する。

0.2 MDAST の code ノード構造

remark-parse が生成する code ノードは以下の構造を持つ:

{
"type": "code",
"lang": "js",
"meta": "title=\"js/a.js\"",
"value": "const a = 1;\n",
"position": {
"start": { "line": 5, "column": 1, "offset": 42 },
"end": { "line": 7, "column": 4, "offset": 68 }
}
}
  • lang: info string の最初の単語(js)
  • meta: 残りの部分(title="js/a.js" / [js/a.js] / js/a.js など)
  • value: コード本文
  • position: 行・列の位置情報

parseFenceInfoFromMDAST() が lang + meta からパスを抽出する。


Part 1. 仕様書

1.1 依存関係

Terminal window
npm install unified remark-parse unist-util-visit
パッケージバージョン用途
unified11.x処理パイプライン
remark-parse11.xMarkdown → MDAST
unist-util-visit5.xAST 走査

ESM only。Node.js 16+ が必要。

1.2 パス解決の 5 ソース(変更なし)

#ソース例既定
1marker// === @file: js/x.js ===✅
2fence ```js title="js/x.js" / ```js [js/x.js]✅
3heading直前見出し ## `js/x.js`opt-in
4paragraph直前段落opt-in
5bare// js/x.js--mode all のみ

1.3 マーカー文法(変更なし)

v5 と同じ。=== は推奨だが必須ではない。@file: path / @file path / @file:path / @ 省略 / 各言語のコメント記法を全て受理。

1.4 --out 既定値(変更なし)

入力種別既定 --out
ディレクトリ<input>/out
ファイル<parent>/<basename(拡張子抜き)>/out

1.5 その他(v5 から継承)

  • モード: strict-marker(既定) / marker / heading / all
  • lang↔拡張子ハード検査(heading/paragraph/bare のみ)
  • 継続結合: parts(既定) / auto / same-target / off
  • 競合: 後勝ち + _superseded/ 退避
  • 会計: 全ブロック disposition 分類、合計不一致 exit 3
  • exit: 0 成功 / 1 CLI エラー / 2 未抽出あり / 3 会計バグ

1.6 v5 との互換性

CLI オプションは完全互換。v5 と同じコマンドがそのまま動作する。

唯一の違いは 未終端フェンスの扱い:

  • v5: 未終端フェンスもブロックとして抽出(unclosed: true フラグ付き)
  • v6: remark-parse は閉じたコードブロックのみ code ノードとして返す。未終端フェンスは MDAST の code ノードにならない ため、v5 のような unclosed フラグ付きブロックは生成されない。

注意: 未終端フェンスの内容を救出したい場合は、v5 の --no-unclosed フラグに相当する機能が v6 では動作しない。代わりに、LLM プロンプトで「必ずフェンスを閉じる」ことを強制する運用を推奨。


Part 2. エージェント指示(LLM プロンプト)

## 出力フォーマット(厳守)
1 ファイル = 1 見出し + 1 コードブロック。説明文はコードブロックの外。
### 形式
## `relative/path/to/file.ext`
```<lang>
// === @file: relative/path/to/file.ext ===
<ファイルの完全な内容>
```
### ルール
1. 見出しは H2 (`##`)。パスはバッククォートで囲む。
2. フェンスは三連バッククォート。言語タグ必須。
3. コード本体の 1 行目に @file マーカー。推奨形式は `===` 装飾付き:
JS/TS : // === @file: js/00-main.js ===
CSS : /* === @file: styles/00-base.css === */
HTML/XML : <!-- === @file: index.html === -->
Python/Sh : # === @file: setup.py ===
SQL : -- === @file: db/schema.sql ===
装飾なし (`// @file: js/00-main.js`) や空白区切り (`// @file js/00-main.js`)
も受理されるが、`===` 装飾付きを推奨(HTML bundle 規約と一致)。
1 行目厳守。先頭に空行を入れない。BOM を付けない。
4. パスは相対のみ。`./` 不要、`..` 禁止、絶対パス禁止。
5. 1 ファイルは 1 コードブロック。省略記号 (`...`) 禁止。
6. 途中で切れる場合、必ず `// @part: n/m` を 2 行目に。最終パートに `// @end`。
7. 末尾に「確認コマンド」「実行方法」等を書く場合、必ず ```bash 等の
非ファイル言語タグを付ける。
8. コードブロック内に説明・diff・チェックリストを書かない。
### 自己検証
生成後、以下が exit 0 になること:
node scripts/extract-from-md.mjs <output.md> --dry --verbose
(--out 未指定なら <output>/out/ に書かれる)

--emit-prompt で取得可能。


Part 3. マニュアル

3.1 インストール(v6 新規)

Terminal window
# 依存関係のインストール
npm install unified remark-parse unist-util-visit

package.json がない場合は npm init -y で作成してからインストール。

3.2 基本コマンド(v5 と同じ)

Terminal window
# ディレクトリ入力 → messages/out/ に出力
node scripts/extract-from-md.mjs messages/
# ファイル入力 → prompts/foo/out/ に出力
node scripts/extract-from-md.mjs prompts/foo.md
# 明示的に out を指定
node scripts/extract-from-md.mjs messages/ --out ./out
# 事前確認
node scripts/extract-from-md.mjs messages/ --dry --verbose
# 上書き
node scripts/extract-from-md.mjs messages/ --force
# LLM 用プロンプト取得
node scripts/extract-from-md.mjs --emit-prompt
# モード一覧
node scripts/extract-from-md.mjs --list-modes

3.3 v6 で改善された境界ケース

以下のケースで v5 よりも正確に動作する:

4連バッククォート:

````js
// === @file: js/a.js ===
const s = "```";
v5: 内部の `` ``` `` をフェンス終端と誤認する可能性
v6: `remark-parse` が正しく処理
**リスト内コードブロック**:
```markdown
- 項目1
```js
// === @file: js/b.js ===
const b = 2;
```
```
v5: インデントの dedent が不正確な場合あり
v6: CommonMark 準拠で正確に処理
**チルダフェンス**:
```markdown
~~~python
# === @file: setup.py ===
print("hi")
~~~
```
v5: 処理可能だったが、チルダとバッククォートの混在で問題が起きる可能性
v6: 全ケースを正確に処理
### 3.4 トラブルシューティング(v6 追加分)
#### `Cannot find module 'unified'`
依存関係がインストールされていない。`npm install unified remark-parse unist-util-visit` を実行。
#### `ERR_REQUIRE_ESM`
Node.js 14 以下を使用している。Node.js 16+ にアップグレードするか、`package.json` に `"type": "module"` を追加。
#### 未終端フェンスの内容が抽出されない
v6 では `remark-parse` の仕様上、閉じられていないフェンスは `code` ノードにならない。これは **意図した動作**。未終端フェンスの内容を救出したい場合は、v5 を使用するか、LLM プロンプトでフェンスを必ず閉じることを強制する。
---
## Part 4. HTML bundle 連携(変更なし)
```bash
node scripts/extract-from-md.mjs llm-output.md \
--out public/tools/snake \
--mode strict-marker \
--marker-line 1 \
--join parts \
--force \
--manifest ./public/tools/snake/_report/manifest.json
node scripts/html-build/audit-imports.mjs --project snake
node scripts/html-build/verify.mjs --project snake
```
---
## 付録. v5 → v6 移行ガイド
| 手順 | コマンド |
|---|---|
| 1. 依存関係のインストール | `npm install unified remark-parse unist-util-visit` |
| 2. スクリプトの置き換え | v6 を `scripts/extract-from-md.mjs` に配置 |
| 3. 動作確認 | `node scripts/extract-from-md.mjs messages/ --dry --verbose` |
| 4. 既存の運用を確認 | CLI オプションは互換。未終端フェンスのみ挙動が異なる |
**CLI オプションは互換**のため、既存のバッチスクリプトや CI 設定の変更は不要。