durable-map

Analyze Azure Durable Functions projects and auto-generate documentation with Mermaid flow diagrams.

Azure Durable Functions の構成を静的解析し、トリガー → オーケストレーター → アクティビティ → インフラ層の呼び出し関係をドキュメントと Mermaid フローチャートで自動生成する CLI ツール。

Features

• C# isolated worker model の自動解析
• Mermaid フローチャートの自動生成
• Markdown / JSON / HTML ドキュメントの自動生成
• トリガー → オーケストレーター → アクティビティの呼び出し関係を可視化
• インフラ層の自動検出 + .durable-map.yml による設定管理
• @durable-map:infra アノテーションによる手動補完

Output Example

graph LR
    A(["HTTP POST /api/order"]) --> B[["Orchestrator: ProcessOrder"]]
    B -->|activity| C["ValidateOrder"]
    B -->|activity| D["ChargePayment"]
    B -->|activity| E["SendConfirmation"]
    C -.->|SQL| F[("SQL:orders-db")]
    D -.->|HTTP| G["HTTP:stripe-api"]
    E -.->|Email| H["Email:sendgrid"]

Azure Resource Info (Planned)

graph TB
    subgraph Azure["☁️ Azure - Japan East"]
        subgraph Plan["App Service Plan: asp-order-prod (P1v3 - $138.70/mo)"]
            App["⚡ func-order-prod\nRuntime: .NET 8 isolated\nOS: Windows"]
        end
        subgraph Infra["Connected Resources"]
            Storage[("📦 Storage: storderprod\nTaskHub: OrderHub")]
            SQL[("🗄️ SQL: orders-db")]
            AppInsights["📊 AppInsights: ai-order-prod"]
        end
    end
    App --- Storage
    App --- SQL
    App --- AppInsights

Quick Start

npx durable-map ./path/to/azure-functions-project

2-Step Workflow

Step 1: 初回実行 — 解析 + .durable-map.yml の自動生成

npx durable-map ./path/to/project -o docs/durable-map.md

初回実行時に解析対象ディレクトリに .durable-map.yml が生成されます。 自動検出された Azure SDK パターンは自動で埋まり、検出できなかったアクティビティは空欄になります。

🔍 Scanning .cs files...
📦 Found 36 functions (12 Client, 6 Orchestrator, 18 Activities)
✅ Generated: .durable-map.yml
⚠️  以下のアクティビティのインフラ層が未設定です:
   - ChargePayment
   - SendConfirmation
→ .durable-map.yml を編集して再実行してください

Step 2: .durable-map.yml を編集して再実行

# .durable-map.yml
infrastructure:
  ValidateOrder:
    - type: SQL
      resource: orders-db
      description: Validate order data
  ChargePayment:
    - type: HTTP
      resource: stripe-api
      description: Process payment via Stripe
  SendConfirmation:
    - type: Email
      resource: sendgrid
      description: Send confirmation email

npx durable-map ./path/to/project -o docs/durable-map.md

設定済みのインフラ情報が Mermaid 図とドキュメントに反映されます。

Options

durable-map ./path/to/project -o ./docs/durable-map.md

durable-map ./path/to/project --format json

durable-map ./path/to/project --format html -o output.html

durable-map ./path/to/project --depth shallow

| Option | Description | |---|---| | -f, --format <format> | Output format (markdown | json | html) Default: markdown | | -o, --output <file> | Output file (default: stdout) | | -d, --depth <mode> | Display depth (shallow | deep) Default: deep | | --exclude <patterns...> | Exclude patterns | | --no-mermaid | Disable Mermaid diagram generation | | -v, --verbose | Verbose logging |

Infrastructure Detection

Auto-Detection

Activities are scanned for Azure SDK client usage:

| Pattern | Type | |---|---| | CosmosClient, CosmosContainer | CosmosDB | | BlobServiceClient, BlobContainerClient | BlobStorage | | QueueClient, QueueServiceClient | Queue | | TableClient, TableServiceClient | TableStorage | | ServiceBusClient, ServiceBusSender | ServiceBus | | EventHubProducerClient, EventHubConsumerClient | EventHub | | HttpClient, IHttpClientFactory | HTTP | | SqlConnection, SqlCommand | SQL | | IConnectionMultiplexer, ConnectionMultiplexer | Redis | | SendGridClient, SmtpClient | Email |

.durable-map.yml Config

自動検出できないインフラ依存関係は .durable-map.yml で設定できます。 type には任意の文字列が使えます（上記のビルトインパターンに限定されません）。

infrastructure:
  MyActivity:
    - type: LogAnalytics
      resource: workspace-name
      description: Query security logs
    - type: SQL
      resource: my-db
      description: Store analysis results

@durable-map:infra Annotation

コード内にアノテーションを直接記述することもできます:

// @durable-map:infra SQL:orders "Order database"
// @durable-map:infra HTTP:stripe-api
public class SaveOrder : TaskActivity<OrderData, bool> { ... }

Priority

config (.durable-map.yml) > annotation (@durable-map:infra) > auto-detection

Supported Languages

| Language | Model | Status | |----------|-------|--------| | C# | isolated worker | Supported | | Python | V2 | Planned | | TypeScript | V4 | Planned |

Roadmap

| Milestone | Description | Issues | |-----------|-------------|--------| | v0.2.0 — Pipeline / CLI 連携 | Pipeline YAML パーサーと Azure CLI 連携でインフラ情報を取得 | #13, #12 | | v0.2.1 — IaC 解析 | Bicep / ARM テンプレートから Azure リソース関係を読み取る | #11 | | v0.3.0 — 出力品質・UX 改善 | Mermaid 図のレイアウト・テーマ改善、インフラ層解析の強化 | #6, #3, #10 | | v0.4.0 — マルチ言語対応 | TypeScript V4 / Python V2 の Durable Functions 解析対応 | #5, #2 | | v0.5.0 — 高度な解析 | 静的解析からボトルネック・アンチパターンを検出し警告出力 | #4 | | v1.0.0 — OSS 公開 | テストカバレッジ・リポジトリ移行・OSS 公開準備 | #8, #9, #7 |

How It Works

1. Recursively scans .cs files in the target directory
2. Detects [Function], [HttpTrigger], [OrchestrationTrigger], [ActivityTrigger] attributes
3. Analyzes CallActivityAsync, CallSubOrchestratorAsync call patterns
4. Auto-detects Azure SDK usage in activity bodies
5. Loads .durable-map.yml config for manual infrastructure mapping
6. Builds a call graph and outputs Markdown + Mermaid / JSON / HTML

Feedback / Contact

Contact Form

License

MIT