archdoc

TypeScriptソースコードからDDDレイヤードアーキテクチャのAPI仕様書を自動生成するCLIツール。

ts-morphによるAST静的解析でクラス・インターフェース・関数のメタデータを抽出し、レイヤー別のMarkdownドキュメントを生成します。

特徴

• レイヤー別API仕様書の自動生成 — Entity, Value Object, Use Case等のカテゴリ別にMarkdownを出力
• JSDocカスタムタグ対応 — @businessRule, @throws, @param, @returnsを自動抽出
• 設計ドリフト検出 — ベースライン保存→実装変更の差分を検出（CI gate対応）
• Mermaid C4ダイアグラム生成 — レイヤー間依存関係をC4 Componentダイアグラムで可視化
• auto-discoverモード — 既存プロジェクトのディレクトリ構造からlayers.yamlを自動生成
• fumadocs + Vivliostyle互換 — Pure Markdown出力でWeb/PDF両方に対応

インストール

pnpm add -D archdoc

クイックスタート

# 1. layers.yaml を自動生成
npx archdoc init --discover

# 2. layers.yaml を確認・編集

# 3. API仕様書を生成
npx archdoc generate

CLIコマンド

archdoc init

layers.yaml設定ファイルを生成します。

npx archdoc init              # 最小テンプレートを生成
npx archdoc init --discover   # ディレクトリ構造から自動検出

オプション	説明	デフォルト
--discover	ディレクトリ構造から自動検出	false
-s, --source <dir>	ソースルートディレクトリ	src
-o, --output <path>	出力パス	layers.yaml

archdoc generate

レイヤー別API仕様Markdownファイルを生成します。

npx archdoc generate
npx archdoc generate --layer Domain   # 特定レイヤーのみ

オプション	説明	デフォルト
-c, --config <path>	layers.yamlのパス	layers.yaml
-o, --output <dir>	出力ディレクトリ	docs/architecture
--layer <name>	特定レイヤーのみ生成	全レイヤー

archdoc drift

設計仕様と実装の差分を検出します。

npx archdoc drift --baseline  # ベースラインを保存
npx archdoc drift             # 差分を検出

オプション	説明	デフォルト
-c, --config <path>	layers.yamlのパス	layers.yaml
--baseline	現在の実装をベースラインとして保存	false
--layer <name>	特定レイヤーのみチェック	全レイヤー

archdoc diagram

Mermaid C4 Componentダイアグラムを生成します。

npx archdoc diagram
npx archdoc diagram --raw     # .mmdファイルとして出力

オプション	説明	デフォルト
-c, --config <path>	layers.yamlのパス	layers.yaml
-o, --output <dir>	出力ディレクトリ	docs/architecture
--raw	Markdownではなく.mmdファイルとして出力	false

layers.yaml

レイヤー定義はlayers.yamlで管理します。

project:
  name: ECオーダーシステム
  description: 注文管理を行うECシステム
  sourceRoot: src

layers:
  - name: Domain
    nameJa: ドメイン層
    path: src/domain
    type: domain
    description: ビジネスルールとドメインモデルの定義
    responsibility: ビジネスルール・ドメインモデルの定義
    forbiddenImports:
      - src/infrastructure
      - src/presentation
    categories:
      entities: Entity
      valueObjects: Value Object
      repositories: Repository Interface
      services: Domain Service

レイヤータイプ

type	デフォルトカテゴリ
domain	Entity, Value Object, Repository Interface, Domain Service
application	Use Case, Application Service, DTO
presentation	Controller, Handler, Middleware
infrastructure	Repository Implementation, Adapter, External Client
custom	（なし — categories必須）

JSDocタグ規約

archdocが抽出するJSDocタグ:

/**
 * 注文を表すドメインオブジェクト。
 *
 * @businessRule 注文明細は必ず1件以上必要
 * @businessRule キャンセル済み注文への明細追加は不可
 */
export class Order {
  /**
   * 注文明細を追加する。
   *
   * @param item - 追加する注文明細
   * @throws {OrderNotEditableError} 注文が編集不可ステータスの場合
   * @returns 更新後の合計金額
   * @businessRule 同一productIdの明細が存在する場合、数量を合算する
   */
  addItem(item: OrderItem): Money { ... }
}

出力例

生成されるMarkdownの構成:

docs/architecture/
├── index.md           # システム概要（レイヤー一覧・コンポーネント表）
├── domain.md          # ドメイン層 API仕様
├── application.md     # アプリケーション層 API仕様
├── presentation.md    # プレゼンテーション層 API仕様
└── infrastructure.md  # インフラストラクチャ層 API仕様

ライセンス

MIT