pylint-clean-architecture 1.5.2

Excelsior: High-fidelity clean architecture linter for Python.

Captain's Log: High-authority Pylint module for enforcing Prime Directives (Clean Architecture) and preventing Hull Integrity Breaches (Technical Debt) in Python projects.

Enforcing architectural boundaries, dependency rules, and design patterns to ensure the fleet remains operational and modular.

Features

• Layer Boundary Enforcement: Ensures Prime Directives are maintained between Domain, UseCase, and Infrastructure.
• The Silent Core Rule (W9013): Guarantees that Domain/UseCase layers remain free of print, logging, and console I/O, forcing delegation to Interfaces/Adapters.
• Dependency Injection Checks: Forbids unauthorized instantiation of infrastructure modules within UseCases.
• Design Pattern Enforcement: Detects "naked returns" and other architectural anomalies.
• Law of Demeter: Prevents tight coupling through deep method chains.
• Contract Integrity: Verifies that Infrastructure implements Domain Protocols correctly.
• Anti-Bypass Guard: Prevents "lazy" disabling of Prime Directives without high-level authorization (Justification).

Docking Procedures

pip install pylint-clean-architecture

Flight Manual

Add the plugin to your pyproject.toml or Pylint configuration:

[tool.pylint.main]
load-plugins = ["clean_architecture_linter"]

Run Pylint as usual:

pylint src/

AI Coding Assistant Support

The clean-arch-init command generates architectural instructions for AI agents (like Cursor or GitHub Copilot) to prevent "Split Brain" issues by teaching the AI your project's rules before it writes code.

Usage:

clean-arch-init

Outcome: This creates a customized .agent/instructions.md file based on the layer names defined in the project's Console Calibration.

Console Calibration

The module is calibrated via [tool.clean-arch] in pyproject.toml.

[tool.clean-arch]
# 1. Project Type Presets (generic, cli_app, fastapi_sqlalchemy)
project_type = "generic"

# 2. Strict Visibility Enforcement
visibility_enforcement = true

# 3. Silent Core Calibration
silent_layers = ["Domain", "UseCase"]
allowed_io_interfaces = ["TelemetryPort", "LoggerPort"]

# 4. Shared Kernel (Allow cross-cutting concerns anywhere)
shared_kernel_modules = ["logging_utils", "clean_architecture_linter.interface.telemetry"]

# 5. Custom Layer Mapping (Map directory regex patterns to layers)
[tool.clean-arch.layer_map]
"services" = "UseCase"
"infrastructure/clients" = "Infrastructure"
"domain/models" = "Domain"

Prime Directives

See RULES.md for a complete catalog of enforced Prime Directives and "Clean Fix" examples.

Mission Log

• CHANGELOG.md - Mission history and architectural updates

Contributing

1. Fork the repo.
2. Install dependencies: make install.
3. Run tests: make test.
4. Submit a PR.