cleanarch 0.1.0__py3-none-any.whl

cleanarch-0.1.0.dist-info/METADATA

@@ -0,0 +1,106 @@
+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

cleanarch-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+cleanarchitecture/__init__.py,sha256=kHI_FejyrsJ-dO4j_AEsZYdbn4TGIqNTXEPaZjmdwjg,343
+cleanarchitecture/__main__.py,sha256=qi-CC9AuFW8sHeDQ_dgwVic_h0916UIw8SRBgfYXm8Q,69
+cleanarchitecture/_lint_runner.py,sha256=ICNuOekVvfD2wzvtWPfbuyGKSwyxX1wg83ATjvbBPk0,955
+cleanarchitecture/cli.py,sha256=FtLf38T7rG3xzr8j8QkX5ZY3-1wrlkMAzwMqrkIN_NY,3319
+cleanarchitecture/config.py,sha256=bB4R_4DNCm8cHMqAETvqtlDR4ZTkcRRwItOck4FPHhk,5762
+cleanarchitecture/contracts.py,sha256=Ju_yqW5cbmpptJ7TXcIjaIifTqQCwFOyVTq7gf3wqGE,8798
+cleanarchitecture/overrides.py,sha256=6ZlBhYqXbrIH05iriids0Hyq4cYZkRpL8JQEKyN9TpA,2514
+cleanarch-0.1.0.dist-info/METADATA,sha256=JD0eyGyQjYH894rT42VyGRweelw_-Ov9POAIM__KusQ,4802
+cleanarch-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+cleanarch-0.1.0.dist-info/entry_points.txt,sha256=yi5oO7xWAYYaQxyTg5LyPVuJ_BJ9Bq8odLFwgXrhVWI,57
+cleanarch-0.1.0.dist-info/RECORD,,

cleanarch-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cleanarch-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cleanarch = cleanarchitecture.cli:main

cleanarchitecture/__init__.py

@@ -0,0 +1,11 @@
+"""インストール済みメタデータからバージョンを読む。
+
+バージョンの真実源は pyproject.toml の [project].version 一箇所。
+引数は import 名 (cleanarchitecture) ではなく配布名 (cleanarch)。
+"""
+
+from importlib.metadata import version
+
+__version__ = version("cleanarch")
+
+__all__ = ["__version__"]

cleanarchitecture/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from cleanarchitecture.cli import main
+
+sys.exit(main())

cleanarchitecture/_lint_runner.py

@@ -0,0 +1,24 @@
+"""import-linter を子プロセスとして実行するエントリポイント。
+
+`python -m cleanarchitecture._lint_runner <生成した .ini>` として `cli` から起動される。
+別プロセスに分けるのは、import-linter が検査対象プロジェクトのソースを実際に import するため。
+CLI 自身のプロセスに読み込ませると、利用側の import 副作用と sys.path 汚染を持ち込んでしまう。
+"""
+
+import sys
+
+from importlinter.application.use_cases import lint_imports
+from importlinter.configuration import configure
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    if len(args) != 1:
+        print("usage: python -m cleanarchitecture._lint_runner <config.ini>", file=sys.stderr)
+        return 2
+    configure()
+    return 0 if lint_imports(config_filename=args[0], cache_dir=None) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cleanarchitecture/cli.py

@@ -0,0 +1,91 @@
+"""cleanarch のコマンドライン。
+
+    cleanarch check       アーキテクチャ契約 + 上書き宣言を検査する (CI で使う)
+    cleanarch contracts   生成される import-linter 契約を表示する (デバッグ用)
+    cleanarch overrides   上書き宣言の一覧と期限を表示する
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from cleanarchitecture import contracts, overrides
+from cleanarchitecture.config import ArchConfig, ConfigError, load
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="cleanarch", description="モジュラモノリス + DDD のアーキテクチャ契約検査")
+    parser.add_argument("command", choices=["check", "contracts", "overrides"], help="実行するコマンド")
+    parser.add_argument("-C", "--directory", default=".", help="プロジェクトルート (既定: カレント)")
+    args = parser.parse_args(argv)
+
+    try:
+        config = load(Path(args.directory))
+    except ConfigError as e:
+        print(f"設定エラー: {e}", file=sys.stderr)
+        return 2
+
+    if args.command == "contracts":
+        print(contracts.build(config))
+        return 0
+    if args.command == "overrides":
+        return _overrides(config)
+    return _check(config)
+
+
+def _check(config: ArchConfig) -> int:
+    print(f"モジュール: {', '.join(config.modules)}")
+    if config.shared:
+        print(f"共有カーネル: {', '.join(config.shared)}")
+
+    architecture = _lint_imports(config)
+    print()
+    declarations = _overrides(config)
+    # どちらか一方でも落ちたら CI を失敗させる (個別の終了コードは区別しない)。
+    return 1 if architecture or declarations else 0
+
+
+def _lint_imports(config: ArchConfig) -> int:
+    """生成した契約で import-linter を実行する。
+
+    生成物を利用側リポジトリに書き出さないのは、`.importlinter` をコミットさせないため。
+    ファイルとして存在すると必ず手で編集され、中央の更新を受け取れなくなる。
+    """
+    with tempfile.NamedTemporaryFile("w", suffix=".ini", encoding="utf-8", delete=False) as f:
+        f.write(contracts.build(config))
+        config_path = Path(f.name)
+    env = {**os.environ, "PYTHONPATH": os.pathsep.join(
+        [str(config.source_root), *([os.environ["PYTHONPATH"]] if os.environ.get("PYTHONPATH") else [])],
+    )}
+    try:
+        completed = subprocess.run(  # noqa: S603
+            [sys.executable, "-m", "cleanarchitecture._lint_runner", str(config_path)],
+            cwd=config.source_root,
+            env=env,
+            check=False,
+        )
+    finally:
+        config_path.unlink(missing_ok=True)
+    return completed.returncode
+
+
+def _overrides(config: ArchConfig) -> int:
+    report = overrides.inspect(config.overrides)
+    print(overrides.render(report))
+    if report.has_error:
+        print(
+            "\n期限切れの上書きがあります。upstream に拡張点を足して上書きを畳むか、"
+            "延長理由を添えて sunset を更新してください。",
+            file=sys.stderr,
+        )
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cleanarchitecture/config.py

@@ -0,0 +1,142 @@
+"""`pyproject.toml` の `[tool.cleanarch]` を読み取る。
+
+利用側プロジェクトが書くアーキテクチャ設定はこの 1 ブロックだけ。契約そのもの (どんな依存を
+禁じるか) はこのパッケージが持ち、バージョンを上げれば全プロジェクトに伝播する。
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from datetime import date
+from pathlib import Path  # noqa: TC003  # ArchConfig の実行時フィールド型
+
+# 各モジュールの内部層 = 「外から import されてはいけない層」。
+# 公開面は port.adapter.resource (HTTP / MCP 等の入力アダプタ) と core / __init__ のみ。
+DEFAULT_INTERNAL_LAYERS = (
+    "application",
+    "domain",
+    "port.adapter.messaging",
+    "port.adapter.persistence",
+    "port.adapter.service",
+)
+# ヘキサゴナルの依存方向。左ほど外側。
+DEFAULT_LAYERS = ("port", "application", "domain")
+# layers 契約 (exhaustive) の対象外にするモジュール直下のファイル / パッケージ。
+DEFAULT_LAYER_IGNORES = ("core", "middleware", "exception", "settings", "event", "notification", "doc")
+# 入力アダプタ。ここから domain への直接依存を禁じ、application のユースケース境界を空洞化させない。
+DEFAULT_INBOUND_ADAPTERS = ("port.adapter.resource", "port.adapter.messaging")
+
+
+def _today() -> date:
+    """sunset は暦日での期限。実行環境のローカル暦日で判定する (CI ゲートとして自然な単位)。"""
+    return date.today()  # noqa: DTZ011
+
+
+class ConfigError(Exception):
+    """`[tool.cleanarch]` の記述が不正なときに送出する。"""
+
+
+@dataclass(frozen=True)
+class Override:
+    """フレームワーク実装を案件側で差し替えている宣言 (期限付きの負債)。"""
+
+    target: str
+    reason: str
+    upstream: str
+    sunset: date
+
+    @property
+    def is_expired(self) -> bool:
+        return self.sunset < _today()
+
+    def days_left(self) -> int:
+        return (self.sunset - _today()).days
+
+
+@dataclass(frozen=True)
+class ArchConfig:
+    project_root: Path
+    source_root: Path
+    modules: tuple[str, ...]
+    shared: tuple[str, ...] = ()
+    layers: tuple[str, ...] = DEFAULT_LAYERS
+    layer_ignores: tuple[str, ...] = DEFAULT_LAYER_IGNORES
+    internal_layers: tuple[str, ...] = DEFAULT_INTERNAL_LAYERS
+    inbound_adapters: tuple[str, ...] = DEFAULT_INBOUND_ADAPTERS
+    debt: tuple[str, ...] = ()
+    overrides: tuple[Override, ...] = ()
+    forbidden: tuple[dict, ...] = field(default=())
+
+    @property
+    def root_packages(self) -> tuple[str, ...]:
+        return tuple(sorted({*self.modules, *self.shared}))
+
+
+def load(project_root: Path) -> ArchConfig:
+    """`{project_root}/pyproject.toml` から設定を読む。"""
+    pyproject = project_root / "pyproject.toml"
+    if not pyproject.exists():
+        raise ConfigError(f"pyproject.toml が見つかりません: {pyproject}")
+
+    table = tomllib.loads(pyproject.read_text(encoding="utf-8")).get("tool", {}).get("cleanarch")
+    if table is None:
+        raise ConfigError(
+            f"{pyproject} に [tool.cleanarch] がありません。"
+            " 最低限 src (ソースルート) を設定してください。",
+        )
+
+    source_root = (project_root / table.get("src", "src")).resolve()
+    if not source_root.is_dir():
+        raise ConfigError(f"ソースルートが存在しません: {source_root}")
+
+    shared = tuple(table.get("shared", ()))
+    modules = tuple(table.get("modules") or _discover(source_root, shared))
+    if not modules:
+        raise ConfigError(
+            f"モジュールが 1 つも見つかりません ({source_root})。"
+            " [tool.cleanarch] の modules に明示してください。",
+        )
+
+    unknown = [m for m in (*modules, *shared) if not (source_root / m).is_dir()]
+    if unknown:
+        raise ConfigError(f"存在しないモジュールが指定されています: {', '.join(unknown)}")
+
+    return ArchConfig(
+        project_root=project_root.resolve(),
+        source_root=source_root,
+        modules=modules,
+        shared=shared,
+        layers=tuple(table.get("layers", DEFAULT_LAYERS)),
+        layer_ignores=tuple(table.get("layer_ignores", DEFAULT_LAYER_IGNORES)),
+        internal_layers=tuple(table.get("internal_layers", DEFAULT_INTERNAL_LAYERS)),
+        inbound_adapters=tuple(table.get("inbound_adapters", DEFAULT_INBOUND_ADAPTERS)),
+        debt=tuple(table.get("debt", ())),
+        overrides=tuple(_override(o) for o in table.get("overrides", ())),
+        forbidden=tuple(table.get("forbidden", ())),
+    )
+
+
+def _discover(source_root: Path, shared: tuple[str, ...]) -> tuple[str, ...]:
+    """ソースルート直下の Python パッケージをモジュールとみなす。"""
+    return tuple(sorted(
+        path.name
+        for path in source_root.iterdir()
+        if path.is_dir()
+        and (path / "__init__.py").exists()
+        and not path.name.startswith((".", "_"))
+        and path.name not in shared
+    ))
+
+
+def _override(raw: dict) -> Override:
+    missing = [key for key in ("target", "reason", "upstream", "sunset") if not raw.get(key)]
+    if missing:
+        raise ConfigError(
+            f"[[tool.cleanarch.overrides]] に {', '.join(missing)} がありません: {raw.get('target', raw)}。"
+            " 上書きは理由・upstream Issue・期限をセットで宣言してください。",
+        )
+    sunset = raw["sunset"]
+    if not isinstance(sunset, date):
+        raise ConfigError(f"sunset は日付で指定してください (例: 2026-12-31): {raw['target']}")
+    return Override(raw["target"], raw["reason"], raw["upstream"], sunset)

cleanarchitecture/contracts.py

@@ -0,0 +1,207 @@
+"""`[tool.cleanarch]` から import-linter の契約を組み立てる。
+
+**契約はここにある** — 利用側の `.importlinter` には無い。契約を 1 本足したいときは
+このパッケージを直して version を上げるだけで、全プロジェクトに伝播する。
+利用側がファイルをコピーしないので、プロジェクトが増えても契約はずれない。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from cleanarchitecture.config import ArchConfig
+
+
+@dataclass(frozen=True)
+class Contract:
+    """import-linter の 1 契約。INI のフォーマットはこの型だけが知る。
+
+    値がリストのオプションはインデント付きの複数行に、空のリストは行ごと落とす。
+    各契約ビルダーが文字列連結を書かずに済むため、契約を足す差分が「何を禁じるか」だけになる。
+    """
+
+    id: str
+    name: str
+    type: str
+    options: dict[str, str | list[str]]
+
+    def render(self) -> str:
+        lines = [f"[importlinter:contract:{self.id}]", f"name = {self.name}", f"type = {self.type}"]
+        for key, value in self.options.items():
+            if isinstance(value, str):
+                lines.append(f"{key} = {value}")
+            elif value:
+                lines.append(f"{key} =")
+                lines.extend(f"    {item}" for item in value)
+        return "\n".join(lines) + "\n"
+
+
+@dataclass(frozen=True)
+class Debt:
+    """既存違反 (負債) の 1 エントリ。新規違反だけが CI を落とすようにするための逃がし口。
+
+    `debt` はプロジェクト全体で 1 箇所 (`[tool.cleanarch] debt`) に集約されるため、負債の総量が
+    中央から観測できる。契約ファイルが 9 個に散っていると数えられない。
+    """
+
+    source: str
+    target: str
+    entry: str
+
+    @staticmethod
+    def parse(entry: str) -> Debt:
+        source, _, target = entry.partition("->")
+        return Debt(source.strip(), target.strip(), entry)
+
+
+def build(config: ArchConfig) -> str:
+    """import-linter の設定 (INI) を生成する。"""
+    debt = [Debt.parse(entry) for entry in config.debt]
+    contracts = [
+        *(_layers(config, module) for module in config.modules),
+        *(_inbound_adapters(config, module, debt) for module in config.modules),
+        *(_encapsulation(config, module, debt) for module in config.modules),
+        *(_shared_purity(config, shared, debt) for shared in config.shared),
+        *(_custom(rule) for rule in config.forbidden),
+    ]
+    return "\n".join([_header(config), *(c.render() for c in contracts if c is not None)])
+
+
+def _header(config: ArchConfig) -> str:
+    packages = "\n".join(f"    {name}" for name in config.root_packages)
+    return (
+        "# このファイルは cleanarch が生成しています。手で編集しないでください。\n"
+        "# 契約の追加・変更は cleanarch のバージョンを上げることで受け取ります。\n"
+        "[importlinter]\n"
+        f"root_packages =\n{packages}\n"
+        "# 解消済みの負債エントリで CI を落とさず、可視化だけする\n"
+        "unmatched_ignore_imports_alerting = warn\n"
+    )
+
+
+def _layers(config: ArchConfig, module: str) -> Contract:
+    """ヘキサゴナルアーキテクチャの依存方向 (port → application → domain)。"""
+    return Contract(
+        id=f"{module}-layers",
+        name=f"[{module}] ヘキサゴナルアーキテクチャの依存違反を禁止",
+        type="layers",
+        options={
+            "layers": list(config.layers),
+            "containers": [module],
+            "exhaustive": "true",
+            "exhaustive_ignores": list(config.layer_ignores),
+        },
+    )
+
+
+def _inbound_adapters(config: ArchConfig, module: str, debt: list[Debt]) -> Contract | None:
+    """入力アダプタは application を経由してドメインを操作する。
+
+    domain を直接 import すると application のユースケース境界が空洞化するため禁止する。
+    """
+    adapters = [f"{module}.{name}" for name in config.inbound_adapters if _exists(config, module, name)]
+    if not adapters or not _exists(config, module, "domain"):
+        return None
+    return Contract(
+        id=f"{module}-inbound-adapters",
+        name=f"[{module}] 入力アダプタから domain への直接依存を禁止",
+        type="forbidden",
+        options={
+            "source_modules": adapters,
+            "forbidden_modules": [f"{module}.domain"],
+            "allow_indirect_imports": "true",
+            "ignore_imports": _entries(_into_own_domain(debt, module)),
+        },
+    )
+
+
+def _encapsulation(config: ArchConfig, module: str, debt: list[Debt]) -> Contract | None:
+    """他モジュールから内部層への参照を禁止する (モジュール境界のカプセル化)。
+
+    `source_modules` は「自分以外の全 root package」から自動生成する。モジュールを 1 つ足したとき
+    に既存モジュールの契約へ追記し忘れる (= 境界の穴が開く) 事故を、生成で構造的に塞ぐ。
+    """
+    others = [name for name in config.root_packages if name != module]
+    internals = [f"{module}.{layer}" for layer in config.internal_layers if _exists(config, module, layer)]
+    if not others or not internals:
+        return None
+    return Contract(
+        id=f"{module}-encapsulation",
+        name=f"[{module}] 外部モジュールから内部層への参照を禁止",
+        type="forbidden",
+        options={
+            "source_modules": others,
+            "forbidden_modules": internals,
+            "allow_indirect_imports": "true",
+            "ignore_imports": _entries(_from_outside(debt, module)),
+        },
+    )
+
+
+def _shared_purity(config: ArchConfig, shared: str, debt: list[Debt]) -> Contract:
+    """共有カーネルから業務モジュールへの依存を禁止する (逆流防止)。
+
+    共有カーネルに業務語彙が染み出すと、切り出したときに他プロジェクトで邪魔になる。
+    レビューの目視ではなく機械で落とす。
+    """
+    return Contract(
+        id=f"{shared}-purity",
+        name=f"[{shared}] 共有カーネルから業務モジュールへの依存を禁止",
+        type="forbidden",
+        options={
+            "source_modules": [shared],
+            "forbidden_modules": list(config.modules),
+            "ignore_imports": _entries(_originating_in(debt, shared)),
+        },
+    )
+
+
+def _custom(rule: dict) -> Contract:
+    """利用側が固有に足す forbidden 契約 (`[[tool.cleanarch.forbidden]]`)。"""
+    return Contract(
+        id=f"custom-{rule['name']}",
+        name=f"[custom] {rule.get('description', rule['name'])}",
+        type="forbidden",
+        options={
+            "source_modules": list(rule["source_modules"]),
+            "forbidden_modules": list(rule["forbidden_modules"]),
+            "allow_indirect_imports": "true" if rule.get("allow_indirect_imports", True) else "false",
+            "ignore_imports": list(rule.get("ignore_imports", ())),
+        },
+    )
+
+
+def _exists(config: ArchConfig, module: str, dotted: str) -> bool:
+    """`{module}.{dotted}` が実ファイルとして存在するか。
+
+    契約を生成で組み立てる以上、モジュールごとの構成差 (HTTP を持たない・messaging を持たない)
+    を吸収するのは生成側の責務。存在しないモジュールを契約に書くと import-linter が止まる。
+    """
+    base = config.source_root / module / Path(*dotted.split("."))
+    return base.is_dir() or base.with_suffix(".py").is_file()
+
+
+# 負債をどの契約に効かせるかは「向き」で決まる。全契約に配ると import-linter が未使用の
+# ignore として警告するため、契約ごとに向きの合うものだけを拾う。
+
+
+def _into_own_domain(debt: list[Debt], module: str) -> list[Debt]:
+    """自モジュールの入力アダプタ → 自モジュールの domain"""
+    return [d for d in debt if d.source.startswith(f"{module}.") and d.target.startswith(f"{module}.domain")]
+
+
+def _from_outside(debt: list[Debt], module: str) -> list[Debt]:
+    """他モジュール → 自モジュールの内部層"""
+    return [d for d in debt if d.target.startswith(f"{module}.") and not d.source.startswith(f"{module}.")]
+
+
+def _originating_in(debt: list[Debt], package: str) -> list[Debt]:
+    """共有カーネル → 業務モジュール"""
+    return [d for d in debt if d.source.startswith(f"{package}.")]
+
+
+def _entries(debt: list[Debt]) -> list[str]:
+    return [d.entry for d in debt]

cleanarchitecture/overrides.py

@@ -0,0 +1,64 @@
+"""フレームワーク実装の上書き宣言を検査する。
+
+案件ごとにポート実装やアプリケーションサービスを差し替えることはある。問題は上書きそのもの
+ではなく、**上書きが不可視のまま放置されること**。宣言を必須にし期限を切ることで、上書きの
+一覧がそのまま「フレームワークに足りない拡張点のバックログ」になる。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, NamedTuple
+
+if TYPE_CHECKING:
+    from cleanarchitecture.config import Override
+
+# 期限までこの日数を切ったら警告する (upstream 化に着手する猶予)。
+WARN_THRESHOLD_DAYS = 30
+
+
+class Report(NamedTuple):
+    expired: list[Override]
+    expiring: list[Override]
+    healthy: list[Override]
+
+    @property
+    def has_error(self) -> bool:
+        return bool(self.expired)
+
+    @property
+    def total(self) -> int:
+        return len(self.expired) + len(self.expiring) + len(self.healthy)
+
+
+def inspect(overrides: tuple[Override, ...]) -> Report:
+    expired = [o for o in overrides if o.is_expired]
+    expiring = [o for o in overrides if not o.is_expired and o.days_left() <= WARN_THRESHOLD_DAYS]
+    healthy = [o for o in overrides if not o.is_expired and o.days_left() > WARN_THRESHOLD_DAYS]
+    return Report(expired, expiring, healthy)
+
+
+def render(report: Report) -> str:
+    if report.total == 0:
+        return "上書き宣言はありません。"
+
+    # 重大度ごとに情報量を変える。期限切れは「次に何をすべきか」まで、有効なものは存在だけ。
+    lines: list[str] = []
+    for override in report.expired:
+        lines.extend([
+            f"  ✕ {override.target}",
+            f"      期限切れ {-override.days_left()} 日 (sunset {override.sunset})",
+            f"      理由: {override.reason}",
+            f"      upstream: {override.upstream}",
+        ])
+    for override in report.expiring:
+        lines.extend([
+            f"  ! {override.target}  残り {override.days_left()} 日 (sunset {override.sunset})",
+            f"      upstream: {override.upstream}",
+        ])
+    lines.extend(f"  · {override.target}  残り {override.days_left()} 日" for override in report.healthy)
+
+    summary = (
+        f"上書き {report.total} 件 "
+        f"(期限切れ {len(report.expired)} / 期限間近 {len(report.expiring)} / 有効 {len(report.healthy)})"
+    )
+    return "\n".join([summary, *lines])