Metadata-Version: 2.5
Name: cleanarch
Version: 0.1.0
Summary: モジュラモノリス + DDD のアーキテクチャ契約を「設定ファイルではなく CLI」として配る検査ツール
Project-URL: Homepage, https://github.com/theindiehacker/clean-architecture
Project-URL: Repository, https://github.com/theindiehacker/clean-architecture
Author-email: taiyo tamura <gtaiyou24@gmail.com>
License-Expression: MIT
Keywords: architecture,ddd,import-linter,lint,modular-monolith
Requires-Python: >=3.14
Requires-Dist: import-linter==2.13
Description-Content-Type: text/markdown

# 🏗️ Clean Architecture

モジュラモノリス + DDD のアーキテクチャ契約を、**設定ファイルではなく CLI として配る**検査ツール。

## 何が違うか

通常 [import-linter](https://import-linter.readthedocs.io/) の契約は各リポジトリの `.importlinter` に書く。
モジュールが増えれば契約ファイルも増え、プロジェクトが増えれば同じ文面がコピーで増殖する。
そして中央で契約を 1 本足しても、どのリポジトリにも届かない。

`cleanarch` は契約を**このパッケージの中**に持つ。利用側が書くのは宣言 1 ブロックだけで、
生成された契約はテンポラリファイルに書かれてそのまま捨てられる（リポジトリにコミットさせない
= 手で編集される余地を残さない）。契約を足したいときはこのパッケージのバージョンを上げる。

## 生成される契約

| 契約 | 内容 |
|:--|:--|
| `{module}-layers` | ヘキサゴナルの依存方向（`port → application → domain`）を exhaustive で強制 |
| `{module}-inbound-adapters` | 入力アダプタから domain への直接依存を禁止（ユースケース境界の空洞化を防ぐ） |
| `{module}-encapsulation` | 他モジュールから内部層への参照を禁止。**source は「自分以外の全モジュール」から自動生成** |
| `{shared}-purity` | 共有カーネルから業務モジュールへの依存を禁止（逆流防止） |

`{module}-encapsulation` の source を自動生成しているのが効く。手書きの契約ファイルでは、
モジュールを 1 つ足したときに既存モジュール全部の `source_modules` へ追記する必要があり、
**漏れがそのまま境界の穴になる**（fastship.jp の `.importlinter` にもこの注意書きがある）。
生成ならこの事故が起こらない。

## 導入

```bash
uv add --dev cleanarch
```

## 設定

```toml
[tool.cleanarch]
src = "src"
modules = ["authority", "tenant", "notify"]   # 省略時は src/* を自動検出
shared = ["common"]

# 既定値を上書きしたいとき
layers = ["port", "application", "domain"]
layer_ignores = ["core", "middleware", "exception", "settings"]
internal_layers = ["application", "domain", "port.adapter.persistence", "port.adapter.service"]
inbound_adapters = ["port.adapter.resource", "port.adapter.messaging"]

# 既存違反は負債として明示する。新規違反だけが CI を落とす。
debt = ["authority.port.adapter.resource.oauth.scopes_resource -> authority.domain.model.scope"]

# プロジェクト固有の契約
[[tool.cleanarch.forbidden]]
name = "redis-direct-access"
description = "RedisRegistry 以外からの redis 直接 import を禁止"
source_modules = ["authority", "tenant"]
forbidden_modules = ["redis"]

# フレームワーク実装の上書き（期限付きの負債）
[[tool.cleanarch.overrides]]
target   = "authority.application.identity.IdentityApplicationService"
reason   = "Identity Platform への資格情報移管。CredentialService ポートが未提供"
upstream = "https://github.com/theindiehacker/clean-architecture/issues/128"
sunset   = 2026-12-31
```

## コマンド

```bash
cleanarch check       # 契約 + 上書き宣言を検査する（CI で使う。違反 or 期限切れで非 0 終了）
cleanarch contracts   # 生成される import-linter 契約を表示する（デバッグ用）
cleanarch overrides   # 上書き宣言の一覧と期限を表示する
```

## 負債と上書きを 1 箇所に集める

`debt` と `overrides` をプロジェクト全体で 1 箇所に集約しているのは、**総量を中央から観測する**ため。
契約ファイルが 9 個に散っていると数えられない。

とくに `overrides` の一覧は、そのまま「フレームワークに足りない拡張点のバックログ」になる。
同じ上書きが 2 案件で現れたら、拡張点の不足が確定した合図。

## 開発

```bash
task init          # 依存インストール
task test          # テスト
task style:check   # ruff / mypy
```

## ライセンス

MIT
