04. 開発ワークフロー

開発環境のセットアップ

1. リポジトリのクローン

git clone <repository-url>
cd niro-mcp-servers

2. 依存関係のインストール

# Bun のインストール（未インストールの場合）
curl -fsSL https://bun.sh/install | bash

# 依存関係のインストール
bun install

3. Docker 環境の起動

# 開発環境の起動
docker-compose -f docker-compose.dev.yml up -d

# ログの確認
docker-compose -f docker-compose.dev.yml logs -f confluence-md-dev

4. 環境変数の設定

# .env.example をコピー
cp .env.example .env

# 必要な環境変数を設定
# - CONFLUENCE_BASE_URL: Confluence のベース URL
# - CONFLUENCE_PAT: Personal Access Token（開発用）

Git ブランチ戦略

ブランチ命名規則

main                    # 本番環境のコード
├── develop            # 開発の統合ブランチ
├── feature/*          # 新機能開発
│   ├── feature/clean-html-tool
│   ├── feature/macro-expander
│   └── feature/docker-setup
├── fix/*              # バグ修正
│   └── fix/markdown-conversion-bug
└── docs/*             # ドキュメント更新
    └── docs/api-documentation

ブランチ作成の流れ

# develop から feature ブランチを作成
git checkout develop
git pull origin develop
git checkout -b feature/clean-html-tool

# 作業後、develop にマージ
git checkout develop
git merge feature/clean-html-tool

# main にマージ（リリース時）
git checkout main
git merge develop
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin main --tags

コミットメッセージ規約

Conventional Commits 形式

<type>(<scope>): <subject>

<body>

<footer>

Type の種類

Type	説明	例
`feat`	新機能	`feat(cleaner): add info macro expansion`
`fix`	バグ修正	`fix(parser): handle nested macros correctly`
`docs`	ドキュメント	`docs(readme): update setup instructions`
`style`	コードスタイル	`style(cleaner): format with prettier`
`refactor`	リファクタリング	`refactor(converter): extract markdown utils`
`test`	テスト追加・修正	`test(cleaner): add macro expansion tests`
`chore`	ビルド・設定	`chore(docker): update compose config`
`perf`	パフォーマンス改善	`perf(parser): optimize DOM traversal`

Scope の例

cleaner: 共有ロジック（ConfluenceCleaner）
parser: HTML パーサー
converter: Markdown 変換
mcp: MCP サーバー
docker: Docker 環境
docs: ドキュメント

コミットメッセージの例

# 良い例
git commit -m "feat(cleaner): add code macro expansion support"
git commit -m "fix(parser): handle empty macro body"
git commit -m "docs(specs): add Docker configuration"

# 悪い例（避ける）
git commit -m "update"
git commit -m "fix bug"
git commit -m "WIP"

プルリクエスト（PR）の流れ

1. PR の作成

# feature ブランチで作業完了後
git push origin feature/clean-html-tool

# GitHub で PR を作成
# Base: develop ← Compare: feature/clean-html-tool

2. PR テンプレート

## 概要
この PR の目的を簡潔に説明

## 変更内容
- [ ] 〇〇機能を追加
- [ ] △△のバグを修正
- [ ] ××のテストを追加

## 関連 Issue
Closes #123

## テスト方法
1. Docker 環境を起動
2. `bun test` を実行
3. 〇〇を確認

## スクリーンショット（必要に応じて）

## チェックリスト
- [ ] テストが通る
- [ ] ドキュメントを更新した
- [ ] コミットメッセージが規約に従っている

3. レビュー基準

コードの品質: TypeScript の型安全性、エラーハンドリング
テストカバレッジ: 新機能には必ずテストを追加
ドキュメント: API の変更はドキュメントも更新
パフォーマンス: 大量データでの動作確認
セキュリティ: 外部入力のバリデーション

コーディング規約

TypeScript スタイルガイド

// ✅ 良い例: 明示的な型定義
interface CleanOptions {
  format?: 'markdown' | 'plaintext';
  removeUnwanted?: boolean;
  expandMacros?: boolean;
  maxLength?: number;
}

export class ConfluenceCleaner {
  clean(html: string, options: CleanOptions = {}): CleanedContent {
    // 実装
  }
}

// ❌ 悪い例: any 型の乱用
function process(data: any): any {
  return data;
}

命名規則

// クラス: PascalCase
class ConfluenceCleaner {}

// 関数・変数: camelCase
function convertToMarkdown() {}
const pageContent = '';

// 定数: UPPER_SNAKE_CASE
const MAX_PAGE_SIZE = 1000;

// インターフェース: PascalCase（I プレフィックスなし）
interface CleanedContent {}

// 型エイリアス: PascalCase
type MacroType = 'info' | 'warning' | 'code';

ファイル構成

// 1. Import 文
import { JSDOM } from "jsdom";
import TurndownService from "turndown";

// 2. 型定義
export interface CleanOptions {
  // ...
}

// 3. 定数
const SELECTORS_TO_REMOVE = [
  'script',
  'style',
];

// 4. クラス実装
export class ConfluenceCleaner {
  // コンストラクタ
  constructor() {}

  // パブリックメソッド
  clean() {}

  // プライベートメソッド
  private removeUnwanted() {}
}

テスト戦略

テストフレームワーク

テストランナー: Bun のビルトインテストランナー
ユニットテスト: Bun test
統合テスト: Bun test + Docker
E2E テスト: 実際の Confluence ページを使用

Bun には Jest 互換のテストランナーが組み込まれているため、追加のテストライブラリは不要です。

テストの書き方

import { describe, it, expect } from 'bun:test';
import { ConfluenceCleaner } from './cleaner';

describe('ConfluenceCleaner', () => {
  describe('clean', () => {
    it('should convert info macro to blockquote', () => {
      const cleaner = new ConfluenceCleaner();
      const html = `
        <ac:structured-macro ac:name="info">
          <ac:rich-text-body><p>Test info</p></ac:rich-text-body>
        </ac:structured-macro>
      `;

      const result = cleaner.clean(html);

      expect(result.markdown).toContain('> ℹ️ Info: Test info');
      expect(result.metadata.macrosExpanded).toBe(1);
    });

    it('should handle empty HTML', () => {
      const cleaner = new ConfluenceCleaner();
      const result = cleaner.clean('');

      expect(result.markdown).toBe('');
      expect(result.plaintext).toBe('');
    });

    it('should remove unwanted elements', () => {
      const cleaner = new ConfluenceCleaner();
      const html = '<script>alert("xss")</script><p>Content</p>';

      const result = cleaner.clean(html);

      expect(result.markdown).not.toContain('script');
      expect(result.markdown).toContain('Content');
    });
  });
});

テストの実行

# すべてのテストを実行
bun test

# 特定のファイルのテストを実行
bun test cleaner.test.ts

# カバレッジを確認
bun test --coverage

# Watch モードで実行
bun test --watch

テストカバレッジの目標

共有ロジック: 80% 以上
MCP サーバー: 70% 以上
重要な機能: 90% 以上

デバッグ方法

ローカルでのデバッグ

# TypeScript の型チェック
bun run typecheck

# ビルドエラーの確認
bun run build

# MCP サーバーをローカルで起動してログ確認
bun run --filter @niro/mcp-confluence-md dev

Docker 内でのデバッグ

# コンテナのログを確認
docker-compose -f docker-compose.dev.yml logs -f

# コンテナ内に入ってデバッグ
docker-compose -f docker-compose.dev.yml exec confluence-md-dev sh

# コンテナ内でテストを実行
docker-compose -f docker-compose.dev.yml exec confluence-md-dev bun test

MCP サーバーのデバッグ

// ログ出力の例
console.error('Debug:', { html, options }); // stderr に出力

// MCP サーバーは stdio を使うため、console.log は避ける
// デバッグ用のログは console.error を使用

リリースフロー

1. バージョンアップ

# パッチバージョン (1.0.0 → 1.0.1)
bun version patch

# マイナーバージョン (1.0.0 → 1.1.0)
bun version minor

# メジャーバージョン (1.0.0 → 2.0.0)
bun version major

2. CHANGELOG の更新

## [1.1.0] - 2025-11-26

### Added
- info/warning/code マクロのサポート
- Docker 環境の構築

### Fixed
- 空の HTML を処理する際のバグ修正

### Changed
- パフォーマンス改善（処理速度 20% 向上）

3. リリースタグの作成

# タグを作成
git tag -a v1.1.0 -m "Release v1.1.0"

# タグをプッシュ
git push origin v1.1.0

トラブルシューティング

よくある問題と解決方法

問題 1: Bun のインストールエラー

# 解決策: 最新版を再インストール
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc  # または ~/.zshrc

問題 2: Docker コンテナが起動しない

# ログを確認
docker-compose -f docker-compose.dev.yml logs

# コンテナを再ビルド
docker-compose -f docker-compose.dev.yml build --no-cache
docker-compose -f docker-compose.dev.yml up -d

問題 3: 型エラーが解決しない

# node_modules を削除して再インストール
rm -rf node_modules bun.lockb
bun install

# TypeScript の型キャッシュをクリア
rm -rf packages/*/dist
bun run build

04. 開発ワークフロー

開発環境のセットアップ

1. リポジトリのクローン

2. 依存関係のインストール

3. Docker 環境の起動

4. 環境変数の設定

Git ブランチ戦略

ブランチ命名規則

ブランチ作成の流れ

コミットメッセージ規約

Conventional Commits 形式

Type の種類

Scope の例

コミットメッセージの例

プルリクエスト（PR）の流れ

1. PR の作成

2. PR テンプレート

3. レビュー基準

コーディング規約

TypeScript スタイルガイド

命名規則

ファイル構成

テスト戦略

テストフレームワーク

テストの書き方

テストの実行

テストカバレッジの目標

デバッグ方法

ローカルでのデバッグ

Docker 内でのデバッグ

MCP サーバーのデバッグ

リリースフロー

1. バージョンアップ

2. CHANGELOG の更新

3. リリースタグの作成

トラブルシューティング

よくある問題と解決方法

問題 1: Bun のインストールエラー

問題 2: Docker コンテナが起動しない

問題 3: 型エラーが解決しない

参考リンク