cleanarch 0.1.0__tar.gz

cleanarch-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: Python CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  validation:
+    name: 検査
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: uv のセットアップ
+        # setup-uv は major/minor タグを publish していないため commit hash でピンする
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: 依存の同期
+        # --locked で uv.lock と pyproject.toml のズレも検出する
+        run: uv sync --locked
+
+      - name: Ruff リント
+        run: uv run ruff check .
+
+      - name: 型チェック
+        run: uv run mypy
+
+      - name: テスト
+        run: uv run pytest

cleanarch-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,75 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+# 既定は無権限。必要な job にだけ最小権限を与える。
+permissions: {}
+
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: 配布物のビルド
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: uv のセットアップ
+        # setup-uv は major/minor タグを publish していないため commit hash でピンする
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.14"
+          # リリース成果物のビルドではキャッシュを使わない。
+          # PR 経由で汚染されたキャッシュが配布物に混入する経路を断つ (zizmor: cache-poisoning)。
+          enable-cache: false
+
+      - name: タグと pyproject.toml の version が一致することを検証
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          VERSION="$(python3 -c 'import tomllib, pathlib; print(tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"])')"
+          if [ "${TAG#v}" != "$VERSION" ]; then
+            echo "::error::タグ ${TAG} と pyproject.toml の version ${VERSION} が一致しません"
+            exit 1
+          fi
+
+      - name: sdist と wheel をビルド
+        run: uv build --out-dir dist
+
+      - name: 配布物を artifact として保存
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: PyPI へ公開
+    needs: [ build ]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/cleanarch
+    permissions:
+      # OIDC トークンの発行に必須。workflow 単位ではなく job 単位で付与する (公式の強い推奨)
+      id-token: write
+    steps:
+      - name: 配布物を取得
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: PyPI へアップロード
+        # Trusted Publishing (OIDC) のため認証情報の指定は一切不要。
+        # v1.11.0 以降、Trusted Publishing 時は PEP 740 attestation が自動生成・添付される。
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

cleanarch-0.1.0/.gitignore

@@ -0,0 +1,133 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# JetBrains IDE (IntelliJ IDEA / PyCharm)
+# 各開発者のローカル設定なので git 管理しない
+.idea/

cleanarch-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,93 @@
+# 🏗️ 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/Taskfile.yml

@@ -0,0 +1,34 @@
+version: '3'
+
+tasks:
+  init:
+    desc: 開発環境のセットアップ
+    cmds:
+      - uv sync
+      - echo "✅ done"
+
+  test:
+    desc: テスト実行
+    cmd: uv run pytest {{.CLI_ARGS}}
+
+  style:check:
+    desc: スタイル / 型の検査
+    deps: [style:check:ruff, style:check:mypy]
+    cmds:
+      - echo "✅ clean-architecture"
+
+  style:check:ruff:
+    desc: Ruff リント
+    cmd: uv run ruff check .
+
+  style:check:mypy:
+    desc: 型チェック
+    cmd: uv run mypy
+
+  style:fix:
+    desc: スタイル自動修正
+    cmd: uv run ruff check --fix .
+
+  build:
+    desc: 配布物のビルド
+    cmd: uv build --out-dir dist

cleanarch-0.1.0/mise.toml

@@ -0,0 +1,4 @@
+[tools]
+python = "3.14"
+"github:astral-sh/uv" = "latest"
+task = "latest"

cleanarch-0.1.0/pyproject.toml

@@ -0,0 +1,108 @@
+[project]
+name = "cleanarch"
+version = "0.1.0"
+description = "モジュラモノリス + DDD のアーキテクチャ契約を「設定ファイルではなく CLI」として配る検査ツール"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+authors = [{ name = "taiyo tamura", email = "gtaiyou24@gmail.com" }]
+keywords = ["architecture", "import-linter", "modular-monolith", "ddd", "lint"]
+dependencies = [
+    "import-linter==2.13",
+]
+
+[project.scripts]
+cleanarch = "cleanarchitecture.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/theindiehacker/clean-architecture"
+Repository = "https://github.com/theindiehacker/clean-architecture"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cleanarchitecture"]
+
+[dependency-groups]
+dev = [
+    "mypy==2.1.0",
+    "pytest==9.1.1",
+    "ruff==0.15.21",
+]
+
+# ============ 🪄 Ruff ============
+# 利用側プロジェクトに配る規約と揃える (自分が守れない規約は配れない)。
+[tool.ruff]
+# src レイアウト。cleanarchitecture を第一パーティとして isort に認識させる。
+src = ["src", "."]
+target-version = "py314"
+line-length = 120
+indent-width = 4
+extend-exclude = ["__init__.py"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "B008",
+    "ERA001",
+    "FIX002",
+    "N818",
+    "PLR0913",
+    "RUF012",
+    "TRY003",
+    "FBT001",
+    "FBT002",
+    "PLC0415",
+    "PLW0108",
+    "A003",
+    "D",
+    "TD",
+    "ARG",
+    "EM",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# CLI は標準出力が成果物。
+"src/cleanarchitecture/cli.py" = ["T201"]
+"src/cleanarchitecture/_lint_runner.py" = ["T201"]
+"src/cleanarchitecture/overrides.py" = ["T201"]
+# テストは日本語で仕様を書く (テスト名がそのまま仕様書になる)。
+"test/**/*.py" = ["S101", "SLF001", "PLR2004", "INP001", "N801", "N802", "N803", "N806", "N999", "PLC2401", "RUF001", "RUF002", "RUF003",
+                       # テストは fixture / tmp_path を実行時に受け取るため型限定 import へ移せない
+                       "TC001", "TC002", "TC003",
+                       # 期限判定は「今日」が基準。テストでも同じ基準を使う
+                       "DTZ011"]
+
+[tool.ruff.lint.pycodestyle]
+max-line-length = 160
+
+[tool.ruff.lint.flake8-annotations]
+mypy-init-return = true
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff.lint.isort.sections]
+sections = ["FUTURE", "STDLIB", "THIRDPARTY", "FIRSTPARTY", "LOCALFOLDER"]
+
+# ============ ✔️ mypy ============
+[tool.mypy]
+python_version = 3.14
+files = ["src", "test"]
+mypy_path = ["src"]
+color_output = true
+show_column_numbers = true
+check_untyped_defs = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+ignore_missing_imports = true
+strict_optional = false
+explicit_package_bases = true
+
+# ============ 🧪 pytest ============
+[tool.pytest.ini_options]
+testpaths = ["test"]
+pythonpath = ["src"]

cleanarch-0.1.0/src/cleanarchitecture/__init__.py

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

cleanarch-0.1.0/src/cleanarchitecture/__main__.py

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

cleanarch-0.1.0/src/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())