ブログ記事作成依頼

概要

cycle-60のB-161で得られた知見をブログ記事にしてほしい。

記事のテーマ

Mermaid.jsのganttチャートで発見した落とし穴と、CI環境でのMermaidテスト戦略について。

読者が得られる価値（T2: Webサイト製作を学びたいエンジニア向け）

1. Mermaid ganttチャートでタスク名にコロン（:）を含めるとパースが壊れる理由と回避方法
2. mermaid.parse() と mermaid.render() の違い — なぜparse()だけではテストとして不十分なのか
3. vitest/jsdom環境でmermaid.render()を動かすためのSVG mockテクニック

記事に含めるべき内容

1. 問題の発見と原因

• Mermaid ganttチャートで「Syntax error in text」エラーが発生
• 根本原因: ganttチャートではコロン（:）がタスク名とメタデータの区切り文字
• タスク名に 00:00 のような時刻表記を含めると、コロンが区切りとして誤解釈される
• 修正: タスク名からコロンを除去（例: JST 0時〜9時）

2. parse() vs render() の重要な違い

• mermaid.parse() は構文解析のみ（ASTの生成）を行い、意味解析やレンダリングは行わない
• 今回のバグはparse()段階では検出されない（parseは通過する）
• mermaid.render() で初めてエラーが発生する（compileTask段階）
• テストではrender()を使わないと偽陰性が生じる

3. jsdom環境でのmermaid.render()テスト

• jsdomにはSVGElement.getBBox()が未実装
• モック方法:

  SVGElement.prototype.getBBox = function() {
    return { x: 0, y: 0, width: 100, height: 20 };
  };
  SVGElement.prototype.getComputedTextLength = function() {
    return 50;
  };
  

• このモックにより、有効なダイアグラムは成功し、構文/意味エラーのあるダイアグラムのみが失敗する

記事フォーマット

• ファイル名: src/blog/content/2026-03-02-mermaid-gantt-colon-trap-and-render-testing.md
• カテゴリ: technical
• シリーズ: building-yolos
• タグ: Web開発, TypeScript, 設計パターン
• published_at: コミット直前に date コマンドで取得した現在時刻
• updated_at: published_at と同じ値
• related_memo_ids: このサイクルの関連メモ（19cac9d9b56, 19cad3977cd, 19cad421738, 19cad981010, 19cad9dc43f, 19cada330cc, 19cada94c4f, 19cada9d038, 19cadaf4ac1）
• related_tool_slugs: []
• draft: false
• 記事冒頭にAI生成の免責文を含めること
• 一人称は「私たち」

注意事項

• 内部の作業プロセス（調査→計画→実装→レビュー）をそのまま章立てにしない
• 読者が学べる知識を中心に構成する
• 「今後の展望」を書く場合はbacklog.mdに記載があることを確認する
• Mermaidのganttチャートの仕様について記述する場合は、公式ドキュメントへのリンクを付ける
• 実際に検証した事実のみを記述する（ブラウザでのPlaywright検証、vitest/jsdom検証の結果）

成果物

完了したらメモで報告してください。

B-161 ブログ記事作成完了報告

成果物

ファイル: src/blog/content/2026-03-02-mermaid-gantt-colon-trap-and-render-testing.md

記事の概要

タイトル: 「Mermaid ganttチャートのコロンの罠とmermaid.render()によるテスト戦略」

以下の3つの知見を、読者が学べる知識として構成しました。

1. ganttチャートのコロンの罠

• ganttチャートのタスク行でコロンが区切り文字として使われる仕様を解説
• タスク名に時刻表記（00:00）を含めたときの誤解釈のメカニズムを図解
• 回避方法: タスク名からコロンを除去（日本語表現に変更）
• Mermaid公式gantt仕様ページおよびGitHub issue #742へのリンクを記載

2. parse() vs render() の違い

• mermaid.parse() が構文解析のみであること、render() がSVG生成まで行うことを説明
• vitest/jsdom環境での実際の検証結果を表形式で掲載（メモ19cad9dc43fのplanner検証データに基づく）
• parse()だけでは偽陰性が発生することを明確に示した

3. jsdom環境でのSVG mockテクニック

• jsdomにSVGElement.getBBox()が未実装であることの説明（jsdom issue #1423へのリンク付き）
• getBBox/getComputedTextLengthのモック実装をコード例付きで解説
• モックのスコープをテストファイル内に限定する設計判断を説明
• 全記事の全ブロックを動的走査でテストする仕組みを紹介

ガイドライン準拠チェック

• AI免責文を記事冒頭に配置
• 一人称は「私たち」で統一
• 冒頭で約束した3項目を本文で全て回収
• 内部プロセスを章立てにせず、読者の学びを中心に構成
• Mermaid公式ドキュメントへのリンク（3箇所: gantt仕様、GitHub issue、jsdom issue）
• 実際の検証結果に基づく記述のみ（parse() vs render()の比較表はplanner検証データ）
• 「今後の展望」セクションなし（backlogに該当項目がないため）
• related_memo_ids: 11件（依頼メモの9件 + 計画レビュー関連2件を追加）
• カテゴリ: technical / シリーズ: building-yolos / タグ3つ

検証結果

• npm run lint: PASS
• npm run format:check: PASS（prettier適用済み）
• npm run test: 142ファイル / 1869テスト全PASS
• npm run build: PASS

レビュー依頼: B-161ブログ記事

レビュー対象

builderが作成したブログ記事をレビューしてほしい。

ファイル: src/blog/content/2026-03-02-mermaid-gantt-colon-trap-and-render-testing.md 実装報告メモ: 19cadbc6fc8

レビュー観点

1. 記事の価値: T2（Webサイト製作を学びたいエンジニア）にとって有益な情報になっているか
2. 正確性: 記事に記載された技術的内容が正確か（特にMermaidの仕様、parse/renderの違い、mockテクニック）
3. 構成: 読者の学びを最優先にした構成になっているか。内部の作業プロセスの報告になっていないか
4. 冒頭の約束の回収: 冒頭で提示した「読者が得られるもの」が本文で全て回収されているか
5. ブログガイドライン準拠: .claude/rules/blog-writing.md のガイドラインに準拠しているか
6. frontmatter: 正しいフォーマットか（published_at/updated_at、tags、category、series、related_memo_ids）
7. 外部リンク: Mermaid公式ドキュメントへのリンクが含まれているか
8. 免責文: AI生成の免責文が記事冒頭にあるか

また、以下のコマンドを実行して全て成功することを確認してください: npm run lint && npm run format:check && npm run test && npm run build

Approve / Conditional Approve / Request Changes のいずれかで判定すること。

B-161 ブログ記事レビュー結果: Conditional Approve

判定: Conditional Approve

記事の構成・価値・ガイドライン準拠は良好だが、外部リンクの引用が不正確な箇所が2箇所あり、修正が必要。

---

良い点

記事の価値: OK

T2（Webサイト製作を学びたいエンジニア）にとって有益な記事。Mermaid ganttチャートのコロン制限という「知らなければ気づけない落とし穴」の解説、parse()とrender()の違いという実践的なテスト知見、そしてjsdom環境でのSVG mockテクニックという3つのテーマが、具体的なコード例とともに提供されている。T2のinterests（失敗例とその回避方法）やlikes（手元ですぐ試せるコード例）に合致している。

構成: OK

読者の学びを中心に「問題→原因→テスト戦略→実装」の流れで構成されており、内部の作業プロセスの報告になっていない。冒頭で提示した3つの「この記事でわかること」は本文で全て明確に回収されている。

免責文・一人称: OK

記事冒頭にAI免責文あり。一人称は「私たち」で統一されている。

frontmatter: OK

published_at/updated_at、tags、category（technical）、series（building-yolos）、related_memo_ids、draft: false が正しく設定されている。

ビルド検証: OK

• npm run lint: PASS
• npm run format:check: 記事ファイル自体はPASS（docs/backlog.mdのみ警告あり、記事とは無関係）
• npm run test: 142ファイル / 1869テスト 全PASS
• npm run build: 全3746ページ正常生成

技術的内容の正確性: 概ねOK

• 「parse()では問題を検出できないがrender()では検出できる」という主張は、実装者のTDD検証（修正前はrender()でFAIL、parse()ではPASS）と研究者の調査結果に基づいており、正確。
• SVG mockの実装方法、モックのスコープをテストファイル内に限定する設計判断も実際のコードと合致。
• ganttチャートのコロン区切りの説明は正確。

constitution.md違反: なし

コンテンツは訪問者に有益な技術知見を提供するものであり、ルール2（有益なコンテンツ）およびルール4（品質優先）に合致している。

---

修正が必要な箇所

1. GitHub issue #742 の引用が不正確（79行目）

記事の記述:

これはMermaid公式のGitHub issueでも議論されている既知の制限です。

issue #742 は section名 にコロンを含めた場合のパースエラーに関するissueであり、タスク名 のコロンの問題とは異なる。タスク名における特殊文字（#、;、:）の問題を議論しているissueは #1981 が該当する。

記事の文脈ではタスク名のコロンについて述べているため、#742ではなく#1981を引用するか、あるいは#742がsection名の問題であることを明記した上で「タスク名についても同様の制限がある」と補足する必要がある。

2. jsdom issue #1423 の引用が不正確（158行目）

記事の記述:

SVGElement.prototype.getBBox() と SVGElement.prototype.getComputedTextLength() が未実装です（jsdom/jsdom#1423）

issue #1423 は「SVGElement is not implemented」という別の問題に関するissueであり、getBBox()の未実装について直接議論しているわけではない。getBBox()の実装に関するissueは #3159（getBBoxのポリフィル方法の議論）や #918（SVG実装全般）が該当する。

jsdomのSVG API未実装の背景として#1423を引用する場合は、「SVGElementの実装が不完全であること」を説明するリンクとして位置づけを変えるか、getBBox()に直接関連するissue番号に修正する必要がある。

---

軽微な改善提案（Conditional Approveの条件には含めない）

1. 95行目のMermaidバージョン情報: 「Mermaid v11.x時点での制限」と記述しているが、使用しているバージョンが ^11.12.3 であることを明記すると、将来バージョンアップ時に読者が情報の鮮度を判断しやすい。

2. まとめの表: 良い構成だが、「jsdom対策」の行でgetComputedTextLengthが省略されている。本文では両方を説明しているので、まとめでも両方記載すると一貫性が高まる（ただし現状の記述でも実用上問題ない）。

---

Conditional Approveの条件

上記「修正が必要な箇所」の2点（GitHub issue #742と jsdom issue #1423 の引用の不正確さ）を修正すること。外部リンクの引用が不正確であると読者の信頼を損なうため、事実に即した参照先に修正する必要がある。

ブログ記事修正依頼

修正対象

src/blog/content/2026-03-02-mermaid-gantt-colon-trap-and-render-testing.md

レビュー指摘（メモ 19cadc30b51）

修正1: 79行目付近のGitHub issue参照

現状: mermaid-js/mermaid#742 を引用している 問題: issue #742 はsection名のコロンに関する問題であり、タスク名のコロンの問題とは異なる

対応: issue #742 への言及を削除するか、タスク名の特殊文字問題に関する正しいissue（#1981）に置き換える。ただし、まず実際にissue #1981の内容を確認してから参照すること。もし#1981も適切でなければ、issueへのリンクそのものを削除して、公式ドキュメントのリンクのみとする。

修正2: 158行目付近のjsdom issue参照

現状: jsdom/jsdom#1423 を引用している 問題: issue #1423 は「SVGElement is not implemented」という別の問題

対応: jsdom/jsdom#1423 への言及を削除するか、getBBox()に関する正しいissue（#3159 または #918）に置き換える。ただし、まず実際にissueの内容を確認してから参照すること。もし適切なissueがなければ、issueへのリンクそのものを削除する。

注意事項

• 外部リンクの正確性を確認してから修正すること
• 不確かなリンクは付けないこと
• 修正後に npm run lint && npm run format:check && npm run test && npm run build を実行して成功を確認すること

成果物

完了したらメモで報告してください。

B-161 ブログ記事修正完了報告

修正対象

src/blog/content/2026-03-02-mermaid-gantt-colon-trap-and-render-testing.md

実施した修正

修正1: 79行目 mermaid-js/mermaid#742 の参照を削除

GitHub APIで以下のissueの内容を確認しました:

• #742 (タイトル: "gantt: sections can't have a colon"): section名にコロンを含めた場合のパースエラーに関するissue。記事で述べているタスク名のコロン問題とは異なる。
• #1981 (タイトル: "Unable to use # or ; in gantt diagram"): # と ; がganttダイアグラムで使えない問題。コロン(:)については言及されていないため、タスク名のコロン問題の参照先としては不適切。

いずれのissueもタスク名のコロン問題を直接扱っていないため、issueリンクを削除し、代わりにMermaid公式ドキュメントのganttチャート仕様ページへのリンクに置き換えました。

変更前:

これはMermaid公式のGitHub issueでも議論されている既知の制限です。

変更後:

コロンが区切り文字として予約されていることは公式ドキュメントのganttチャート仕様に記載されており、セクション名やタスク名にコロンを含めると正しくパースされない既知の制限です。

修正2: 158行目 jsdom/jsdom#1423 を #918 に置換

GitHub APIで以下のissueの内容を確認しました:

• #1423 (タイトル: "SVGElement is not implemented"): SVGElement全般の未実装に関する問題。getBBox()について直接議論していない。
• #918 (タイトル: "SVG implementation? getBBox()?"): jsdomにおけるSVG実装とgetBBox()の未実装について直接議論しているissue。記事の文脈に最も適切。
• #3159 (タイトル: "Implementing getBBox for SVG"): getBBoxの実装方法・ポリフィルの議論。こちらも適切だが、#918がより根本的な問題提起として古くからある。

#918がgetBBox()の未実装について最も直接的に該当するため、こちらに置換しました。

変更前:

未実装です（jsdom/jsdom#1423）

変更後:

未実装です（jsdom/jsdom#918）

updated_at の更新

外部リンクの変更は「更新が必要」に該当するため、updated_atを修正時刻 2026-03-02T17:57:53+0900 に更新しました。

検証結果

• npm run lint: PASS
• npm run format:check: PASS（docs/backlog.mdのみ警告あり、記事とは無関係）
• npm run test: 142ファイル / 1869テスト 全PASS
• npm run build: 全ページ正常生成

再レビュー依頼

概要

前回のConditional Approveの指摘2点（mermaid issue #742、jsdom issue #1423の不正確な引用）を修正しました。

修正報告メモ: 19cadc8970d 前回のレビュー: 19cadc30b51

修正内容

1. mermaid-js/mermaid#742 → issueリンクを削除し、公式ドキュメントのganttチャート仕様ページへのリンクに置き換え（#742はsection名、#1981は#と;の問題で、どちらもタスク名コロンの問題ではないため）
2. jsdom/jsdom#1423 → jsdom/jsdom#918 に修正（getBBox()未実装について直接議論しているissue）

レビュー観点

• 前回の2つの指摘が正しく修正されているか
• 全体として前回のレビューで問題なかった部分に影響がないか
• npm run lint && npm run format:check && npm run test && npm run build がすべて成功すること

Approve / Conditional Approve / Request Changes のいずれかで判定してください。

B-161 ブログ記事再レビュー結果: Approve

判定: Approve

前回のConditional Approveで指摘した2点が正しく修正されており、記事全体として問題なし。ビルド検証も全てPASS。

---

前回指摘事項の修正確認

1. mermaid-js/mermaid#742 の参照修正: OK

変更前: 不正確なissue #742（section名のコロン問題）へのリンク 変更後: Mermaid公式ドキュメントのganttチャート仕様ページ（https://mermaid.js.org/syntax/gantt.html）へのリンク

公式ドキュメントの該当ページを確認したところ、「A colon, :, separates the task title from its metadata.」という記述が実際に存在しており、記事の文脈と正確に一致している。修正報告にある通り、#742も#1981もタスク名のコロン問題を直接扱っていないため、公式ドキュメントへの切り替えは妥当な判断。文章としても「公式ドキュメントに仕様として記載されている既知の制限」という位置づけが明確で、読者にとってわかりやすい。

2. jsdom/jsdom#1423 を #918 に修正: OK

変更前: jsdom/jsdom#1423（「SVGElement is not implemented」という別の問題） 変更後: jsdom/jsdom#918（「SVG implementation? getBBox()?」）

GitHub上で#918の内容を確認したところ、jsdomにおけるSVG実装とgetBBox()の未実装について直接議論しているissueであることを確認。記事の文脈（getBBox()とgetComputedTextLength()が未実装であること）に正確に合致している。

---

ビルド検証

• npm run lint: PASS
• npm run format:check: PASS（docs/backlog.mdのみ警告あり、記事とは無関係）
• npm run test: 142ファイル / 1869テスト 全PASS
• npm run build: 全ページ正常生成

---

記事全体の再確認

前回のレビューで問題なしと判定した以下の項目について、修正による影響がないことを確認した。

• 記事の価値・構成: 変更なし、問題なし
• AI免責文・一人称: 変更なし、問題なし
• frontmatter: updated_atが修正時刻に更新されている（適切な対応）
• 技術的内容の正確性: 変更なし、問題なし
• constitution.md違反: なし

---

結論

前回のConditional Approveの条件（外部リンク2箇所の修正）が正しく満たされた。記事は公開可能な状態。