# export_cycles_high_level_report

Lattix Python APIを使用して、サブシステム間の循環依存（High Level Cycles）を一括検出・可視化するスクリプトです。

## 用語について

| 用語 | 意味 |
|------|------|
| High Level Cycles（高レベル循環依存） | サブシステム間の循環依存。個々のファイルや関数レベルではなく、DSM上のサブシステム（フォルダやモジュールに相当する単位）同士が互いに依存し合っている状態 |
| Componentアルゴリズム | Lattixが提供するDSM上のサブシステム並び替えアルゴリズム。依存の方向が上から下（左上→右下）に揃うよう最適化し、逆依存（右上セルの依存）を最小化する。並び替え後のIndex順が「本来あるべき依存方向」の基準となる |
| プリセット | フィルター設定（方向・Kind等）に名前を付けて保存したもの。プリセット定義ファイル（JSON）を作業フォルダに配置し、config.jsonの `presets_file` で参照することで、HTMLレポートやExcel出力時に共通のフィルター条件を適用できる |

## 必要な環境

| 項目 | 要件 |
|------|------|
| Lattix | 2025.1.7以降（Python API対応版） |
| Python | 3.12（Lattixが要求するバージョン） |
| pyliblattix | Lattixインストールディレクトリ内 `python_api/pyliblattix.pyd` |
| .ldzファイル | レポート出力対象のLattixプロジェクトファイル |

### 追加のPythonパッケージ／ツール

| 項目 | 種別 | 用途 |
|------|------|------|
| openpyxl | Python (pip) | Excelファイル生成 |
| Pillow | Python (pip) | Excel内グラフ画像埋め込み |
| mermaid-cli (mmdc) | npm | Mermaidグラフ→PNG変換 |

## セットアップ

### 1. pyliblattixのパスを通す

Pythonのライブラリパスに `pyliblattix` を追加する必要があります。Pythonの `site-packages` ディレクトリに `lattix.pth` ファイルを作成し、以下を記載してください。

```
C:\Program Files\Lattix2025.1.7\python_api
```

### 2. 追加パッケージをインストールする

```
pip install -r scripts/requirements_export_cycles_high_level_report.txt
```

### 3. ディレクトリ構成

以下のようなディレクトリ構成で配置してください。

```
lattix-api-work/
├── scripts/
│   └── export_cycles_high_level_report.py  # 本スクリプト
├── ldz/
│   └── httpd-2.0.55/
│       └── httpd-2.ldz   # Lattixプロジェクトファイル
└── work/                  # 作業フォルダ
    ├── config.json        # 設定ファイル
    └── httpd-2_cycles_high_level/   # 出力ディレクトリ（自動生成）
```

## 設定ファイル（config.json）を用意する

作業フォルダ（`work/`）に `config.json` を作成します。以下のパスは例ですので、`ldz_path` / `source_root_map` は環境に合わせて変更してください。

```json
{
    "ldz_path": "c:\\work\\ldz\\httpd-2.0.55\\httpd-2.ldz",
    "source_root_map": {
        "C:/work/src/httpd-2.0.55": "C:/work/ldz/httpd-2.0.55"
    },
    "sort_by_component": true,
    "presets_file": [
        "presets_cpp_understand.json",
        "presets_cpp_clang.json",
        "presets_dotnet.json",
        "presets_java.json"
    ]
}
```

| キー | 説明 | デフォルト |
|------|------|-----------|
| `ldz_path` | レポート出力対象のLattixプロジェクトファイルの絶対パス | （必須） |
| `source_root_map` | Lattix解析時のソースパスと、現在ソースが存在するパスの対応（後述） | `{}`（空） |
| `sort_by_component` | `true`にすると、Componentアルゴリズムで深い階層まで再帰的にサブシステムの並び順を並び替えてからレポートを生成する | `true` |
| `presets_file` | 読み込むプリセット定義ファイル（JSON）のリスト。作業フォルダに配置したファイル名を指定する | なし（プリセットなし） |

### source_root_map について

レポート内のファイルリンクを正しく機能させるための設定です。

Lattixの.ldzファイルには、**解析時のソースコードのパス**がパーティション名として記録されています。その後ソースコードを別の場所に移動した場合、パーティション名から推定されるパスと実際のファイル位置がずれてしまいます。

`source_root_map` は「パーティション名から推定される旧パス」→「実際にファイルがある現在のパス」を対応付けます。

```json
"source_root_map": {
    "C:/work/src/httpd-2.0.55": "C:/work/ldz/httpd-2.0.55"
}
```

この例では:
- Lattix解析時のソースは `C:/work/src/httpd-2.0.55/` にあった
- 現在は `C:/work/ldz/httpd-2.0.55/` に配置されている

これにより、レポート内の `vscode://file/...` リンクが現在のファイル位置を正しく指すようになります。

> **Lattixプロジェクト（.ldz）解析時と本スクリプト実行時で、ソースコードの場所が変わっていない場合**は、`"source_root_map": {}` のまま（空）で問題ありません。.ldzファイルを別のフォルダや別のマシンに移動して使用している場合は、この設定を行わないとレポート内のソースコードへのリンクが正しいパスを指しません。

## スクリプトを実行する

作業フォルダをカレントディレクトリにして、スクリプトを実行します。

```powershell
cd lattix-api-work\work
python ..\scripts\export_cycles_high_level_report.py
```

実行結果:
```
Component並び替え実施済み
出力ディレクトリ: httpd-2_cycles_high_level/
  - 個別PlantUML: depth*_cycle_*.puml
  - 個別Mermaid:  depth*_cycle_*.md
  - HTMLインデックス: index.html
循環コンポーネント数: 31
```

出力ディレクトリに `index.html` が生成されるので、外部ブラウザ（Chrome, Edge等）で開いてください（※Mermaid/Excel機能はCDNからライブラリを読み込むため、インターネット接続が必要です）。

> **注意**: VS Code内蔵ブラウザでは `vscode://` リンクが動作しません。必ず外部ブラウザで開いてください。

## コマンドラインオプション

| オプション | 説明 |
|-----------|------|
| `--excel` | Excel(.xlsx)レポートを同時に出力する |
| `--no-graph` | Excelにグラフ画像を含めない（高速化） |
| `--preset PRESET` | 特定のプリセットでフィルタリングしてExcel出力 |
| `--depth DEPTH` | 出力対象の深さを制限する（`shallowest`, `shallowest+1` 等） |

`--depth` オプションは、まず影響の大きい浅い循環から着手する場合に有用です。

```powershell
# 最も浅い階層の循環のみ出力
python ..\scripts\export_cycles_high_level_report.py --depth shallowest

# 浅い順に2階層分出力
python ..\scripts\export_cycles_high_level_report.py --depth shallowest+1
```

## プリセット定義ファイル

config.jsonの `presets_file` に外部プリセットファイルを指定すると、HTMLレポートのフィルタードロップダウンやExcel出力時に共通のフィルター条件を適用できます。複数ファイルを指定でき、すべてのプリセットがドロップダウンに表示されます。

```json
{
    "ldz_path": "...",
    "presets_file": [
        "presets_cpp_understand.json",
        "presets_cpp_clang.json",
        "presets_dotnet.json",
        "presets_java.json"
    ]
}
```

プリセット定義ファイルはJSON配列で、各プリセットに以下のキーを持ちます。

```json
[
    {
        "name": "Include_Reverse",
        "reverse_only": true,
        "kinds": ["Include"],
        "tag": "C++_Understand"
    }
]
```

| キー | 説明 |
|------|------|
| `name` | プリセット名。ドロップダウンや `--preset` オプションで指定する名前 |
| `reverse_only` | `true` で逆依存のみ、`false` で全方向を表示 |
| `kinds` | フィルター対象のKindリスト（配列）。`"all"` で全Kind |
| `tag` | グルーピング用タグ。言語やモジュール種別ごとに分類できる |

各プリセットファイルでは、カテゴリごとに `{カテゴリ}_Reverse`（逆依存のみ）と `{カテゴリ}_All`（全方向）のペアが定義されています。

### 提供済みプリセットファイル

| ファイル | タグ | プリセット数 | 主なカテゴリ |
|---------|------|------------|-------------|
| `presets_cpp_understand.json` | C++_Understand | 12 | Include, Data, Class, Method, Declaration, Macro |
| `presets_cpp_clang.json` | C++_Clang | 28 | Override, Invoke, Inherit, Type Reference, Macro, Read Field, Read Global, Include, Modify Global, Modify Field 等 |
| `presets_dotnet.json` | DotNET | 14 | Property, Class Reference, Invokes, Constructs, Data Member Reference, Event, Inherits |
| `presets_java.json` | Java | 12 | Class Reference, Invokes, Inherits, Data Member Reference, Constructs, Annotation |

使用するLattixプロジェクトの解析モジュール（Understand / Clang / .NET / Java）に応じたプリセットファイルを `presets_file` に指定してください。

## 同梱ファイル

| ファイル | 内容 |
|---------|------|
| `scripts/export_cycles_high_level_report.py` | スクリプト本体 |
| `scripts/requirements_export_cycles_high_level_report.txt` | Pythonパッケージ一覧 |
| `work/config.json` | 設定ファイルのサンプル |
| `work/presets_cpp_understand.json` | C++ (Understand解析) 向けプリセット |
| `work/presets_cpp_clang.json` | C++ (Clang解析) 向けプリセット |
| `work/presets_dotnet.json` | .NET 向けプリセット |
| `work/presets_java.json` | Java 向けプリセット |
| `work/httpd-2_cycles_high_level/` | 出力レポートのサンプル（Apache httpd 2.0.55） |

## サンプルレポートの確認

`work/httpd-2_cycles_high_level/index.html` をブラウザで開くと、サンプルレポートの動作を確認できます。

## 注意事項

- 本スクリプトの検証はC++（Understand）のみで実施しています
- C++（Clang）、Java、.NET用のプリセットファイルは参考として同梱していますが、これらの言語での動作検証は行っておりませんのでご了承ください。
