調査依頼: Mermaidシンタックスエラーの原因特定とテスト方法のベストプラクティス

背景

ownerからJavaScript Date API記事(src/blog/content/2026-03-02-javascript-date-pitfalls-and-fixes.md)のMermaidシンタックスエラーの報告があった。 また、再発防止策として全記事の全Mermaid記法を npm test 内でバリデーションするテストの構築が依頼されている。

調査項目

1. Mermaidシンタックスエラーの原因特定

JS Date API記事（226-238行目）のMermaid ganttチャートのシンタックスエラーの原因を特定してほしい。

当該Mermaidブロック:

考えられる問題点:

• dateFormat HH:mm で 24:00 が使えるか
• ganttチャートのタスク定義の構文（<id>, <start>, <duration or end> 形式の使い方）
• タスク名の日本語や括弧
• titleの -- がMermaidの構文と干渉していないか

以下を調査してほしい:

• Mermaid v11.xのganttチャートの正確な構文仕様
• dateFormatのHH:mmでの制約
• 各タスク行のフォーマット仕様
• 上記Mermaidブロックの具体的なエラー原因

2. Mermaidバリデーションテストのベストプラクティス

npm test内でMermaidの構文をバリデーションするテストを構築するためのベストプラクティスや事例を調査してほしい。

調査観点:

• Mermaid公式がテスト/バリデーション用に提供しているAPI（例: mermaid.parse() など）
• Node.js/Vitest環境でMermaidの構文をバリデーションする方法
• ブラウザ環境なしでMermaidの構文チェックだけを行う方法
• 他のプロジェクトでのMermaidテストの事例やベストプラクティス

なお、このサイトではMermaid ^11.12.3 を使用している。

3. サイト内全Mermaidブロックの現状

以下の7記事にMermaidブロック（計16箇所）がある。全ブロックの構文をリストアップし、明らかな問題がないか確認してほしい。

• src/blog/content/2026-02-19-workflow-simplification-stopping-rule-violations.md (6箇所)
• src/blog/content/2026-03-02-javascript-date-pitfalls-and-fixes.md (1箇所)
• src/blog/content/2026-02-28-url-structure-reorganization.md (1箇所)
• src/blog/content/2026-02-13-how-we-built-this-site.md (2箇所)
• src/blog/content/2026-02-23-workflow-skill-based-autonomous-operation.md (2箇所)
• src/blog/content/2026-02-18-workflow-evolution-direct-agent-collaboration.md (3箇所)
• src/blog/content/2026-02-18-spawner-experiment.md (1箇所)

成果物

調査結果をメモで返答してほしい。

Mermaidシンタックスエラー調査レポート

概要

JS Date API記事のMermaid ganttチャートのシンタックスエラーの原因特定と、全記事のMermaidブロック検証、およびMermaidバリデーションテストのベストプラクティスについて調査した。

1. Mermaidシンタックスエラーの原因特定

問題のganttブロック（再掲）

mermaid.parse()での検証結果

mermaid ^11.12.3 のNode.js環境（jsdom提供なし）での mermaid.parse() の結果：

• タイトルなしの場合: 全ての要素（24:00、日本語、括弧）は正常にパースされる
• タイトルありの場合: purify.addHook is not a function というTypeErrorが発生する

vitest/jsdom環境での mermaid.parse() の結果：

• 問題のganttブロック全体（titleを含む）を正常にパースできる（テスト確認済み）

結論：エラーの根本原因

シンタックスエラーの実体は「DOMPurify依存問題」である。

Mermaid v11.xは、title 行や subgraph のラベル、ノードの ["..."] ラベルなどのテキストコンテンツをXSS防止のためにDOMPurifyでサニタイズする。DOMPurifyはブラウザDOM（またはjsdom）に依存するため：

1. ブラウザ環境: 正常にレンダリングされる
2. vitest/jsdom環境: jsdomがDOM APIを提供するため mermaid.parse() が正常に動作する
3. 純粋なNode.js環境: DOMが存在しないため purify.addHook is not a function エラーになる

各問題点の評価

純粋なNode.js（jsdomなし）環境でエラー報告されている場合、問題はMermaid構文の誤りではなく、DOMPurifyが動作しない実行環境に起因する。ブラウザやvitest環境では正常に動作する可能性が高い。

Mermaid ganttチャートの正式な構文仕様（v11.x）

タスク行のフォーマット仕様（3種類）:

タスク名 :[tags,] <taskId>, <startDate>, <endDate or duration>
タスク名 :[tags,] <startDate>, <endDate or duration>
タスク名 :[tags,] after <taskId>, <duration>

• tags: active, done, crit, milestone のいずれか（任意、複数可、先頭に指定）
• taskId: タスクの識別子（任意）
• startDate: dateFormatで指定した形式の日付/時刻
• endDate: dateFormatで指定した形式の終了日時（または1d, 2hなどの期間）

crit, c1, 00:00, 09:00 は「critタグ付き、ID: c1、開始: 00:00、終了: 09:00」として正しい。

2. Mermaidバリデーションテストのベストプラクティス

調査結果

方法A: mermaid.parse() + vitest/jsdom（推奨）

mermaid パッケージ（v11.12.3）はすでにプロジェクトに導入済みで、mermaid.parse() は vitest/jsdom 環境（既存の設定）で動作することを確認済み。

実際にすべてのブロックをテストし、16個すべてが通過した。

実装例：

// src/blog/__tests__/mermaid-syntax.test.ts
import { describe, test, expect, beforeAll } from 'vitest';
import mermaid from 'mermaid';
import { readdirSync, readFileSync } from 'fs';

// Markdownファイルからmermaidブロックを抽出するユーティリティ
function extractMermaidBlocks(markdown: string): string[] {
  const blocks: string[] = [];
  const regex = /```mermaid\n([\s\S]*?)```/g;
  let match;
  while ((match = regex.exec(markdown)) !== null) {
    blocks.push(match[1].trim());
  }
  return blocks;
}

describe('Mermaid syntax validation for all blog articles', () => {
  beforeAll(() => {
    mermaid.initialize({ startOnLoad: false });
  });

  const blogDir = new URL('../../content', import.meta.url).pathname;
  const files = readdirSync(blogDir).filter(f => f.endsWith('.md'));

  for (const file of files) {
    const content = readFileSync(`${blogDir}/${file}`, 'utf-8');
    const blocks = extractMermaidBlocks(content);

    if (blocks.length === 0) continue;

    describe(file, () => {
      blocks.forEach((block, i) => {
        test(`block ${i + 1}`, async () => {
          const result = await mermaid.parse(block, { suppressErrors: true });
          expect(result, `Mermaid block ${i + 1} has invalid syntax`).not.toBe(false);
        });
      });
    });
  }
});

メリット:

• 追加パッケージ不要（mermaidはすでに導入済み）
• vitestのjsdom環境がそのまま使える（vitest.config.mts でjsdom設定済み）
• flowchart、sequenceDiagram、ganttなど全ダイアグラムタイプに対応
• npm test で自動実行される

デメリット:

• DOMPurifyが必要なコンテンツ（ラベル付きノード等）はjsdomに依存
• jsdom環境でも一部の複雑なレンダリングは検証できない

方法B: @mermaid-js/parser（限定的）

すでにインストール済みの @mermaid-js/parser v1.0.0 は、サポートするダイアグラムタイプが限られている。

• サポート: pie, gitGraph, info, packet, architecture, radar, treemap
• 非サポート: gantt, flowchart, sequenceDiagram（このサイトで使用されているもの）

このサイトでの用途には不適切。

方法C: @mermaid-js/mermaid-cli (mmdc)

Puppeteerを必要とするCLIツール。CI環境ではChrome/Chromiumが必要で、インストールと実行コストが高い。

デメリット:

• 別途インストールが必要（依存関係が大きい）
• Puppeteer/Chromiumが必要で CI環境での設定が複雑
• npm test に統合しにくい

このサイトには不適切。

方法D: @a24z/mermaid-parser（軽量だが外部依存）

軽量（~50KB）のバリデーション専用パッケージで、ganttを含む全ダイアグラムタイプに対応している。ただし追加の依存関係が必要で、mermaidパッケージ自体とのバージョン整合性が不明。

結論: 方法Aを推奨

3. サイト内全Mermaidブロックの現状

検証結果

mermaid.parse() を vitest/jsdom 環境で全16ブロックを実際に実行した結果：

全16ブロックが正常にパース（PASS）

特記事項

• 2026-03-02-javascript-date-pitfalls の ganttブロック（title あり、24:00 あり、日本語タスク名あり）も vitest/jsdom 環境では正常にパースされる
• もしブラウザでのレンダリングエラーが報告された場合、それはMermaidのレンダリングエンジン側の問題（日付計算、axisFormat等）であり、構文エラーではない可能性が高い
• 純粋なNode.js環境（jsdomなし）では DOMPurify 依存のためにラベル付きノードやタイトルのパースが失敗するが、これはテスト環境の問題であり、ブラウザでは影響しない

4. Mermaidバリデーションテスト実装の推奨事項

実装すべきテスト

// src/blog/__tests__/mermaid-syntax.test.ts
import { describe, test, expect, beforeAll } from 'vitest';
import mermaid from 'mermaid';
import { readdirSync, readFileSync } from 'node:fs';
import { join } from 'node:path';

/** Markdownファイルからmermaidコードブロックを抽出する */
function extractMermaidBlocks(markdown: string): string[] {
  const blocks: string[] = [];
  const regex = /^```mermaid\n([\s\S]*?)^```/gm;
  let match;
  while ((match = regex.exec(markdown)) !== null) {
    blocks.push(match[1].trim());
  }
  return blocks;
}

describe('ブログ記事のMermaid構文バリデーション', () => {
  beforeAll(() => {
    mermaid.initialize({ startOnLoad: false });
  });

  const blogContentDir = join(process.cwd(), 'src/blog/content');
  const files = readdirSync(blogContentDir).filter(f => f.endsWith('.md'));

  for (const file of files) {
    const content = readFileSync(join(blogContentDir, file), 'utf-8');
    const blocks = extractMermaidBlocks(content);

    if (blocks.length === 0) continue;

    describe(file, () => {
      blocks.forEach((block, i) => {
        test(`mermaidブロック ${i + 1}`, async () => {
          const result = await mermaid.parse(block, { suppressErrors: true });
          expect(
            result,
            `${file} の mermaidブロック${i + 1}に構文エラーがあります:\n${block}`
          ).not.toBe(false);
        });
      });
    });
  }
});

実装上の注意点

1. import.meta.url ではなく process.cwd() を使う: vitestのjsdom環境ではimport.meta.urlによるパス解決が不安定なケースがある
2. 正規表現は行頭マッチング（^）を使う: インデントされたコードブロックを誤検出しないよう gm フラグと ^ を組み合わせる
3. suppressErrors: true を必ず指定する: エラー時に例外を投げず false を返すようにする
4. エラーメッセージにブロック内容を含める: 失敗時にどのブロックが問題か分かるようにする

まとめ

1. シンタックスエラーの原因: ganttブロック自体の構文は正しい。問題は純粋なNode.js環境でのDOMPurify依存だが、ブラウザ/vitest環境では正常に動作する。

2. バリデーションテストの推奨方法: 既存の mermaid パッケージと vitest/jsdom 環境を使った mermaid.parse() による自動テストが最適。追加依存なしで実現可能。

3. 全ブロックの現状: 全16ブロックが vitest/jsdom 環境で正常にパースされることを確認済み。

計画依頼: B-161 Mermaidシンタックスエラー修正＋全数バリデーションテスト整備

背景・目的

ownerからJavaScript Date API記事のMermaidシンタックスエラーの修正と、再発防止のための全数バリデーションテスト構築が依頼された。

ターゲットユーザーへの影響

• サイトのブログ記事を読む全てのターゲットユーザー（T1〜T5）に影響
• 壊れた図表はコンテンツの信頼性を損ない、constitution Rule 4「品質の優先」に反する

調査結果（確定事項）

エラーの根本原因

Playwright + 実サイトでの検証により確定:

1. mermaid.parse() は成功するが、mermaid.render() で失敗する

   • エラー: TypeError: Cannot read properties of undefined (reading 'type') at compileTask

2. 根本原因: ganttチャートのタスク行で : が区切り文字として使われるため、タスク名内のコロンが誤解釈される

   • 問題の行: JST 00:00 - 09:00（テスト失敗）:crit, c1, 00:00, 09:00
   • 00:00 の : がタスク名とパラメータの区切りとして解釈される

3. 修正方法: タスク名からコロンを除去

   • 例: JST 0時〜9時（テスト失敗） :crit, c1, 00:00, 09:00 → 描画成功を確認済み

テスト戦略

1. mermaid.parse() だけでは不十分 — 今回のエラーはparse段階では検出できない
2. mermaid.render() を使う必要がある — render段階で初めてエラーが発生する
3. サイトのMermaid環境: mermaid ^11.12.3 (package.json)
4. vitest/jsdom環境: parse()は動くが、render()にはDOMが必要。jsdom環境でrender()が動くかの検証が必要
5. 全7記事・16ブロックをテスト対象とする

Mermaid使用状況

7記事に計16箇所のMermaidブロック:

• 2026-02-19-workflow-simplification-stopping-rule-violations.md (6箇所)
• 2026-03-02-javascript-date-pitfalls-and-fixes.md (1箇所)
• 2026-02-28-url-structure-reorganization.md (1箇所)
• 2026-02-13-how-we-built-this-site.md (2箇所)
• 2026-02-23-workflow-skill-based-autonomous-operation.md (2箇所)
• 2026-02-18-workflow-evolution-direct-agent-collaboration.md (3箇所)
• 2026-02-18-spawner-experiment.md (1箇所)

計画策定の要件

以下の2つのタスクについて、具体的な実装計画を立ててほしい。

タスク1: Mermaidシンタックスエラーの修正

• 対象ファイル: src/blog/content/2026-03-02-javascript-date-pitfalls-and-fixes.md の226-238行目
• 修正内容: タスク名 JST 00:00 - 09:00（テスト失敗） → コロンを含まない表現に変更
• 記事のupdated_atの更新

タスク2: Mermaid全数バリデーションテストの構築

• npm test 内で全記事の全Mermaidブロックを検証するテストを構築する
• テスト方式: mermaid.render() を使った実レンダリング検証（parse()だけでは不十分なため）
• テスト環境: vitest + jsdom（ただしrender()がjsdomで動作するか要検証。動作しない場合の代替案も検討すること）
• テストファイルの配置場所の検討
• エラーメッセージはどのファイルのどのブロックが問題かを特定できるようにする
• 全16ブロックが通過すること

計画に含めるべき内容

• 具体的な変更ファイルと変更内容
• テストの実装方針（render()がjsdomで動かない場合のフォールバック案を含む）
• テストファイルの配置場所
• 完了条件

成果物

計画をメモで返答してほしい。

B-161 実装計画: Mermaidシンタックスエラー修正 + 全数バリデーションテスト整備

計画の概要

本計画は2つのタスクから構成される。

• タスク1: 問題のganttチャートのMermaid記法を修正する
• タスク2: 全記事のMermaidブロックを mermaid.render() で検証するテストを構築する

重要な調査結果（plannerによる追加検証）

PMの依頼メモに記載された通り、researcherの調査では mermaid.parse() による検証のみが行われたが、これは不十分である。plannerにて以下の追加検証を vitest/jsdom 環境で実施し、確定事項として報告する。

mermaid.parse() vs mermaid.render() の検証結果

確定した方針: mermaid.render() + getBBox mock

jsdomには SVGElement.getBBox() が実装されていないため、mermaid.render() は素のjsdomでは全てのダイアグラムでエラーになる。しかし以下のモックを追加することで、有効なダイアグラムはレンダリング成功し、構文/意味エラーのあるダイアグラムのみが正しくエラーとなることを確認済み。

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

mermaid.parse() だけでは今回のganttチャートの問題を検出できない（parse段階では通過してしまう）ため、mermaid.render() + getBBox mock が唯一の適切なテスト方式である。

タスク1: Mermaidシンタックスエラーの修正

対象ファイル

/mnt/data/yolo-web/src/blog/content/2026-03-02-javascript-date-pitfalls-and-fixes.md

変更内容

1-1. ganttチャート本体の修正（226-238行目）

問題の根本原因: ganttチャートのタスク行では : がタスク名とメタデータの区切り文字として使われるため、タスク名中の 00:00 や 09:00 のコロンが誤解釈される。

修正前:

JST 00:00 - 09:00（テスト失敗）:crit, c1, 00:00, 09:00

修正後（コロンを含まない日本語表現に変更）:

JST 0時〜9時（テスト失敗） :crit, c1, 00:00, 09:00

注意: タスク名のみ変更し、メタデータ部分 (:crit, c1, 00:00, 09:00) は変更しない。メタデータ中のコロンは dateFormat HH:mm の正しい値である。

また、titleも同様にコロンを含むため修正する。

修正前:

title JST 00:00 -- 09:00 のタイムゾーンギャップ

修正後:

title JST 0時〜9時のタイムゾーンギャップ

1-2. updated_at の更新

コミット直前に date +"%Y-%m-%dT%H:%M:%S%z" を実行し、得られた実際の現在時刻で frontmatter の updated_at を更新する。

完了条件

• ganttチャートが mermaid.render() (getBBox mock付きjsdom環境) でエラーなくレンダリングされること
• 記事の他の部分に影響がないこと

タスク2: Mermaid全数バリデーションテストの構築

テストファイルの配置場所

/mnt/data/yolo-web/src/blog/__tests__/mermaid-validation.test.ts

理由:

• 既存のブログテスト (blog-series.test.ts) と同じディレクトリに配置
• ブログコンテンツに対するバリデーションテストとして意味的に適切
• __tests__ ディレクトリのパターンは既存プロジェクトの慣習に従う

テスト実装方針

2-1. Mermaidブロック抽出ユーティリティ

ブログ記事のMarkdownファイルからMermaidコードブロックを抽出する関数を実装する。

• 正規表現: /^```mermaid\n([\s\S]*?)^```/gm (行頭マッチで誤検出を防止)
• 戻り値: { code: string; blockIndex: number; startLine: number }[] (エラー時にどのブロックかを特定するため行番号を含む)

2-2. SVG mock のセットアップ

テストの beforeAll で以下のモックを設定する。これにより jsdom 環境でも mermaid.render() が動作する。

• SVGElement.prototype.getBBox のモック
• SVGElement.prototype.getComputedTextLength のモック

モックはテストファイル内の beforeAll で設定し、グローバルな setup.ts は変更しない。理由: このモックはMermaidバリデーションテスト専用であり、他のテストに影響を与えるべきではない。

2-3. テスト構造

describe("ブログ記事のMermaid全数バリデーション")
  - src/blog/content ディレクトリの全 .md ファイルを走査
  - Mermaidブロックを含むファイルごとに describe を生成
  - 各ブロックごとに test を生成
  - mermaid.render() を呼び出し、成功することを検証
  - render ID はファイル名とブロックインデックスから一意に生成（例: `mermaid-validation-{sanitized-filename}-{index}`）

2-4. テストの実装手順

1. src/blog/content/ 配下の全 .md ファイルを fs.readdirSync で取得する
2. 各ファイルの内容を読み込み、Mermaidブロック抽出ユーティリティで全ブロックを抽出する
3. Mermaidブロックが0個のファイルはスキップする
4. 各ブロックについて mermaid.render() を呼び出す
5. render が成功した場合（SVGが返された場合）はPASS
6. render がエラーを投げた場合は FAIL とし、エラーメッセージに以下を含める:
   • ファイル名
   • ブロックのインデックスと開始行番号
   • Mermaidコードの先頭数行（問題箇所の特定用）
   • render() が投げたエラーメッセージ

2-5. mermaid の初期化

beforeAll で以下を実行:

const mermaid = (await import("mermaid")).default;
mermaid.initialize({ startOnLoad: false });

動的 import を使う理由: mermaid は ESM パッケージであり、vitest/jsdom 環境での互換性を確保するため。

テストの期待結果

全7記事・16ブロックが mermaid.render() で正常にレンダリングされること（タスク1の修正後）。

完了条件

• npm test で全テストがPASSすること（既存の141ファイル + 新規1ファイル = 142ファイル）
• エラー時のメッセージが「どのファイルの何番目のブロックか」を特定できること
• タスク1の修正が含まれた状態で全16ブロックがPASSすること

実装順序

1. タスク2のテストファイルを先に作成する（この時点では問題のganttブロックのテストが1件FAILする想定）
2. タスク1のMermaid記法を修正する
3. テストを再実行し、全件PASSすることを確認する
4. updated_at を更新する

この順序にする理由: テストが先に存在することで、修正が正しく行われたことを即座に検証できる（TDD的アプローチ）。

変更ファイルの一覧

リスクと注意事項

1. getBBox mock の安定性: mermaid のバージョンアップにより、他のSVG APIへの依存が追加される可能性がある。その場合はモックの追加が必要になるが、テストが失敗するため検出は容易。

2. render IDの重複: mermaid.render() の第1引数はドキュメント内で一意である必要がある。ファイル名+インデックスから生成することで重複を防ぐ。

3. テスト実行時間: mermaid の初回 import にやや時間がかかる（約400ms）が、それ以降の render は各50-70ms程度。16ブロック全体で2秒以内に収まる見込み。

4. mermaid.parse() は使用しない: 本計画の核心的な判断として、mermaid.parse() のみによるテストは採用しない。理由: 今回のバグ（ganttチャートのタスク名にコロンが含まれる問題）は parse 段階では検出されず、render 段階で初めてエラーとなるため。researcherの調査レポートでは parse() を推奨していたが、PMが指摘した通り parse() では不十分であることを planner の追加検証で確認済み。

レビュー依頼: B-161計画

レビュー対象

plannerが作成した実装計画（メモ 19cad9dc43f）をレビューしてほしい。

背景

ownerからの依頼:

1. JavaScript Date API記事のMermaidシンタックスエラーを修正
2. 再発防止として、npm test内で全記事の全Mermaid記法を描画可能か検証するテストを構築

PMの調査で確定した事実

• 根本原因: ganttチャートのタスク名に含まれるコロン（00:00の:）がMermaidの区切り文字として誤解釈される
• mermaid.parse()では検出不可: ブラウザでmermaid.render()を実行して初めてエラーが発生（Playwright検証済み）
• 修正方法: タスク名のコロンを除去（日本語時間表現に変更）→ 描画成功をブラウザで確認済み

レビュー観点

1. エラー修正の妥当性: ganttチャートの修正内容は適切か。修正後の表現は記事の内容として自然か。
2. テスト戦略の妥当性: mermaid.render() + getBBox mockのアプローチは適切か。parse()だけでは不十分なことは確認済み。
3. テストの完全性: 全16ブロックをカバーしているか。今後新しい記事が追加されたときも自動的にテストされるか。
4. テストのメンテナンス性: getBBox mockなどの脆弱性はないか。mermaidバージョンアップ時のリスクは許容範囲か。
5. 実装順序の妥当性: TDDアプローチ（テスト先行）は適切か。
6. 見落としがないか: 他に考慮すべき点はないか。

成果物

レビュー結果をメモで返答してほしい。Approve / Conditional Approve / Request Changes のいずれかで判定すること。

B-161計画レビュー結果: Approve

判定: Approve

計画全体として適切に設計されており、そのまま実装に進んで問題ありません。以下に各観点の詳細を記載します。

1. エラー修正の妥当性 -- OK

ganttチャートの修正内容

修正前: JST 00:00 - 09:00（テスト失敗） / title JST 00:00 -- 09:00 のタイムゾーンギャップ 修正後: JST 0時〜9時（テスト失敗） / title JST 0時〜9時のタイムゾーンギャップ

Mermaid公式ドキュメント（https://mermaid.ai/open-source/syntax/gantt.html）およびGitHubのissue（mermaid-js/mermaid#742）で確認した通り、ganttチャートではコロンがタスク名とメタデータの区切り文字として使われるため、タスク名中のコロンはエスケープできない既知の制限です。タスク名からコロンを除去する以外に信頼できる回避策はありません。

修正後の「0時〜9時」という表現は日本語として自然であり、記事の文脈（日本語の技術ブログ記事でJSTの時間帯を説明するセクション）にも合致しています。メタデータ部分（:crit, c1, 00:00, 09:00）は変更しないという判断も正しく、ganttチャートのdateFormat HH:mmに対して有効な値です。

1つ注意点

記事本文の200行目に「JST 00:00 -- 09:00の9時間帯でテストが失敗する」という見出しがありますが、ここはMermaidブロック内ではないため修正不要です。ただしbuilderが混同しないよう留意してください。

2. テスト戦略の妥当性 -- OK

mermaid.render() + getBBox mockのアプローチ

plannerの追加検証結果の表は説得力があり、mermaid.parse()では今回のganttチャートのバグを検出できないことが明確に示されています。

jsdomはSVGElement.getBBox()を実装していないため（jsdom/jsdom#1423で確認）、getBBoxとgetComputedTextLengthのモックは必須です。計画に記載されたモック実装は適切です。

モックをbeforeAll内に限定し、グローバルなsetup.tsを変更しない判断は正しいです。確認した通り、src/test/setup.tsは現在localStorageのモックのみを扱っており、SVGモックを混入させるべきではありません。

3. テストの完全性 -- OK

カバレッジ

• 7記事・16ブロックという数は、Grepで \``mermaid` を検索した結果と一致しています。
• src/blog/content/配下の全.mdファイルを動的に走査する設計のため、新しい記事が追加されても自動的にテスト対象になります。
• Mermaidブロックが0個のファイルはスキップするという処理も適切です（49記事中42記事はMermaidを含まないため）。

抽出の正規表現

計画では /^\``mermaid\n([\s\S]*?)^```/gmを使用するとしています。行頭マッチの^とmultilineフラグのm を組み合わせることで、コードブロック内にネストされた \`` を誤検出することを防いでいます。ブログ記事のMermaidブロックは全て行頭にあるため、この正規表現で十分です。

4. テストのメンテナンス性 -- OK（軽微なリスクあり）

getBBox mockの安定性

mermaidのバージョン（現在^11.12.3）がアップデートされた際に、新たなSVG APIへの依存が追加される可能性はあります。しかし計画に記載の通り、その場合はテストが失敗するため検出は容易です。

render IDの一意性

ファイル名+ブロックインデックスから生成する方式は適切です。ファイル名のサニタイズ（英数字以外の文字の処理）について計画では「sanitized-filename」と記述していますが、具体的なサニタイズルールは明示されていません。builderに対して「mermaid.render()の第1引数に使える文字列にサニタイズすること」を注記しておくと良いでしょう。ただしこれはApproveを妨げる問題ではありません。

5. 実装順序の妥当性 -- OK

TDDアプローチ（テスト先行 -> 修正 -> 全件PASS確認）は適切です。具体的には:

1. テストファイル作成（この時点で問題のganttブロック1件がFAIL）
2. Mermaid記法の修正
3. 全件PASS確認
4. updated_at更新

この順序により、修正が正しく行われたことを即座に検証でき、テストの有効性（本当にエラーを検出できること）も確認できます。

6. 見落とし確認

markdown.tsのHTMLエスケープとの関係

markdown.tsのmermaid拡張（22-33行目）では、Mermaidコードを &, <, >, " にHTMLエスケープして <div class="mermaid"> に格納しています。これはXSS防止のためであり、クライアントサイドでMermaidRenderer.tsx（el.textContent経由）がブラウザのDOM APIでデコードされた生テキストを受け取る設計です。

計画のテストではMarkdownファイルから直接Mermaidブロックを正規表現で抽出してmermaid.render()に渡すため、このHTMLエスケープの処理パスは関係しません。テストは「Mermaidの記法として有効か」を検証するものであり、「HTMLレンダリングパイプラインが正しく動作するか」を検証するものではないため、この設計で問題ありません。

sanitize.tsのMermaid div扱い

sanitize.tsはdivタグのclass属性を許可しており（78行目: div: ["class"]）、sanitizeテスト（50-55行目）でmermaid divが保持されることが確認されています。計画のテストはsanitize処理とは独立しているため、影響はありません。

vitest.config.mtsのjsdom設定

vitest.config.mtsで environment: "jsdom" が設定されていることを確認しました。mermaid.render()はDOM環境を必要とするため、jsdom環境での実行は必須です。既存の設定で問題なく動作します。

テスト実行時間

計画では全16ブロックで2秒以内と見積もっていますが、mermaidの初回importが400msとされています。既存テスト（141ファイル）への影響は軽微です。ただし、mermaid.render()がjsdom環境で各ダイアグラムタイプについてDOM操作を行うため、実際のテスト時間が予想を超える可能性があります。万が一テストが遅い場合は、vitestのtimeout設定を個別に調整する選択肢がありますが、現時点では問題視しません。

総括

計画は以下の点で優れています:

• parse()では不十分であるという調査結果を踏まえ、render() + getBBox mockという適切な代替策を選択
• 全記事を動的に走査する設計で、将来の記事追加にも自動対応
• TDDアプローチにより修正の検証が確実
• モックのスコープをテストファイル内に限定し、他テストへの副作用を回避

Approveとします。そのまま実装に進んでください。

実装依頼: B-161 Mermaid全数バリデーションテスト構築＋シンタックスエラー修正

概要

計画メモ 19cad9dc43f に基づいて、以下の実装を行ってください。

実装手順（この順序で実施すること）

ステップ1: Mermaid全数バリデーションテストの構築

新規ファイル: src/blog/__tests__/mermaid-validation.test.ts

以下の仕様でテストファイルを新規作成する:

1. SVG mockのセットアップ (beforeAll):

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

2. mermaidの初期化 (beforeAll):

   const mermaid = (await import("mermaid")).default;
   mermaid.initialize({ startOnLoad: false });
   

3. Mermaidブロック抽出ユーティリティ:

   • 正規表現: /^```mermaid\n([\s\S]*?)^```/gm で行頭マッチ
   • 戻り値: { code: string; blockIndex: number; startLine: number }[]

4. テスト構造:

   • src/blog/content/ 配下の全 .md ファイルを fs.readdirSync で走査
   • Mermaidブロックを含むファイルごとに describe を生成
   • 各ブロックごとに mermaid.render() を呼び出し、成功を検証
   • render ID: mermaid-validation-{sanitized-filename}-{index} で一意に
   • エラー時にファイル名・ブロック番号・開始行番号・コードの先頭数行・エラーメッセージを含める

ステップ2: Mermaid記法の修正

対象ファイル: src/blog/content/2026-03-02-javascript-date-pitfalls-and-fixes.md

226-238行目のganttチャートを修正:

修正前:

    title JST 00:00 -- 09:00 のタイムゾーンギャップ

修正後:

    title JST 0時〜9時のタイムゾーンギャップ

修正前:

    JST 00:00 - 09:00（テスト失敗）:crit, c1, 00:00, 09:00

修正後:

    JST 0時〜9時（テスト失敗） :crit, c1, 00:00, 09:00

根本原因: Mermaidのganttチャートでは : がタスク名とメタデータの区切り文字。タスク名内の 00:00 のコロンが区切りとして誤解釈されていた。

ステップ3: updated_atの更新

src/blog/content/2026-03-02-javascript-date-pitfalls-and-fixes.md のfrontmatterの updated_at を現在時刻で更新する。 date +"%Y-%m-%dT%H:%M:%S%:z" コマンドで現在時刻を取得すること。

ステップ4: 検証

以下のコマンドを実行して全て成功することを確認:

npm run lint && npm run format:check && npm run test && npm run build

注意事項

• テストでは mermaid.parse() ではなく mermaid.render() を使うこと（parse()では今回のバグを検出できない）
• getBBox mockはテストファイル内のbeforeAllで設定し、グローバルなsetup.tsは変更しないこと
• 全7記事・16ブロックがPASSすること

成果物

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

B-161 実装完了報告: Mermaid全数バリデーションテスト構築＋シンタックスエラー修正

実施内容

計画メモ 19cad9dc43f に基づき、以下の4ステップを実施しました。

ステップ1: Mermaid全数バリデーションテストの構築

新規ファイル: src/blog/__tests__/mermaid-validation.test.ts

• SVGElement.prototype.getBBox / getComputedTextLength のモックを beforeAll で設定
• mermaid を動的 import し、startOnLoad: false で初期化
• 正規表現 /^\``mermaid\n([\s\S]*?)^```/gm` でMermaidブロックを抽出
• 各ブロックに対して mermaid.render() を実行し、SVG生成成功を検証
• エラー時にはファイル名・ブロック番号・開始行番号・コード先頭5行・エラーメッセージを含む詳細メッセージを出力
• render ID は mermaid-validation-{sanitized-filename}-{index} 形式で一意性を確保

ステップ2: Mermaid記法の修正

対象: src/blog/content/2026-03-02-javascript-date-pitfalls-and-fixes.md 226-238行目

• title: JST 00:00 -- 09:00 のタイムゾーンギャップ -> JST 0時〜9時のタイムゾーンギャップ
• タスク名: JST 00:00 - 09:00（テスト失敗） -> JST 0時〜9時（テスト失敗）
• 根本原因: ganttチャートでは : がタスク名とメタデータの区切り文字であり、タスク名内の時刻表記のコロンが誤解釈されていた

ステップ3: updated_at の更新

updated_at: "2026-03-02T17:23:10+09:00" に更新済み

ステップ4: 検証結果

全て成功:

• npm run lint: PASS
• npm run format:check: PASS
• npm run test: 142ファイル / 1869テスト PASS（新規テスト16件含む）
• npm run build: PASS

TDD的検証

テストを先に作成した段階で、修正前のganttブロックが正しく失敗することを確認:

• 15 passed, 1 failed（2026-03-02-javascript-date-pitfalls-and-fixes.md ブロック#0）
• エラーメッセージ: Cannot read properties of undefined (reading 'type')

修正後に再実行し、全16ブロックがPASSすることを確認。

変更ファイル一覧

レビュー依頼: B-161実装

レビュー対象

builderが実装した以下の成果物をレビューしてほしい。

変更ファイル

1. 新規: src/blog/__tests__/mermaid-validation.test.ts — Mermaid全数バリデーションテスト
2. 修正: src/blog/content/2026-03-02-javascript-date-pitfalls-and-fixes.md — ganttチャート修正 + updated_at更新

背景と計画

• 計画メモ: 19cad9dc43f
• 実装報告メモ: 19cada94c4f

レビュー観点

テストファイル (mermaid-validation.test.ts)

1. テスト方式: mermaid.render() を使っているか（mermaid.parse() だけでは今回のバグを検出できないため不可）
2. SVG mock: getBBox と getComputedTextLength のモックが適切に設定されているか
3. 全数テスト: 全7記事・16ブロックをカバーしているか、新しい記事追加時に自動的にテスト対象になるか
4. エラーメッセージ: 失敗時にどのファイルのどのブロックかを特定できるか
5. コード品質: 既存テストファイルのパターンとの一貫性、不要な依存やハードコードがないか
6. テスト配置: src/blog/__tests__/ に配置されているか

ブログ記事の修正

1. ganttチャート修正: タスク名からコロンが除去されているか（JST 0時〜9時 形式）
2. titleの修正: titleからもコロンが除去されているか
3. updated_at: 適切に更新されているか
4. 記事の自然さ: 修正後の表現が記事の文脈として自然か

全体

1. npm run lint && npm run format:check && npm run test && npm run build がすべて成功すること
2. テストが過不足なく実装されていること（16ブロック全てがテストされ、かつ余計なテストがないこと）

成果物

レビュー結果をメモで返答してほしい。Approve / Conditional Approve / Request Changes のいずれかで判定すること。

B-161 実装レビュー結果: Approve

判定: Approve

全ての観点でレビュー基準を満たしており、計画通りの高品質な実装です。

テストファイル (mermaid-validation.test.ts)

テスト方式: OK

• mermaid.render() を使用しており、mermaid.parse() のみでは検出できないganttチャートのコロン問題を正しく検出可能。計画で明記された核心的要件を満たしている。

SVG mock: OK

• SVGElement.prototype.getBBox と getComputedTextLength が beforeAll で適切に設定されている。グローバルのsetup.tsを変更せず、テストファイル内で完結する設計は適切。

全数テスト: OK

• 7記事 / 16ブロック全てをカバー。fs.readdirSync で content ディレクトリを動的走査するため、新しい記事が追加された場合にも自動的にテスト対象になる。新しいMermaidブロックにシンタックスエラーがあれば即座に検出できる回帰テストとして機能する。

エラーメッセージ: OK

• 失敗時にファイル名、ブロック番号（#N）、開始行番号、コード先頭5行、エラーメッセージを全て含む。問題箇所の特定が容易。

コード品質: OK

• TypeScript型定義（MermaidBlock interface）が適切に定義されている。
• JSDocコメントで extractMermaidBlocks 関数と mermaid.render() を使う理由が説明されている。
• 既存の blog-series.test.ts と同じimportパターン（vitestから直接import）で一貫性がある。
• eslint-disable コメントは mermaid の型定義が無いための any 使用のみで、最小限の例外。
• render IDは mermaid-validation-{sanitized-filename}-{index} 形式で一意性を確保。

テスト配置: OK

• src/blog/__tests__/ に既存テストと並べて配置されている。

ブログ記事の修正

ganttチャート修正: OK

• title: JST 00:00 -- 09:00 のタイムゾーンギャップ → JST 0時〜9時のタイムゾーンギャップ (コロン除去)
• タスク名: JST 00:00 - 09:00（テスト失敗） → JST 0時〜9時（テスト失敗） (コロン除去)
• メタデータ部分 (:crit, c1, 00:00, 09:00) は適切にそのまま維持されている。

記事の自然さ: OK

• 修正後の「0時〜9時」は本文中の「午前0時から午前9時」と整合しており、自然な日本語表現。
• ganttチャートの見た目上の情報量は維持されている。

updated_at: OK

• 2026-03-02T17:23:10+09:00 に更新済み。コンテンツの実質的変更に該当するため、更新は適切。

ビルド検証: 全PASS

• npm run lint: PASS
• npm run format:check: PASS
• npm run test: 142ファイル / 1869テスト全PASS（新規16テスト含む）
• npm run build: PASS

計画との整合性: 完全一致

計画メモ 19cad9dc43f に記載された4ステップ（テスト作成→修正→updated_at更新→検証）が全て実施されている。TDD的アプローチ（テスト先行で1件FAIL→修正後全件PASS）も実装報告で確認されている。

constitution.md違反: なし

今回の変更はコンテンツの品質改善（Mermaid図のレンダリングエラー修正）とテスト追加であり、ルール4（品質優先）に合致している。

軽微な改善提案（Approve判定に影響なし）

• afterAll で SVGElement.prototype.getBBox / getComputedTextLength のモックを delete してクリーンアップする処理があるとなお良い。vitestのワーカー分離前提では実害はないが、将来的なテスト環境変更への安全策として検討の余地あり。これは次回の改善機会として記録するに留める。