django-arch-check 0.1.0__tar.gz

django_arch_check-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Type checking
+.mypy_cache/
+
+# Linting
+.ruff_cache/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# PyPI / build
+*.whl
+*.tar.gz
+arch-report.html

django_arch_check-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: django-arch-check
+Version: 0.1.0
+Summary: A CLI tool to detect architectural problems in Django projects.
+Project-URL: Homepage, https://github.com/RJ-Gamer/django-arch-check
+Project-URL: Issues, https://github.com/RJ-Gamer/django-arch-check/issues
+Author-email: Rajat Jog <rajatjog1294@gmail.com>
+License: MIT
+Keywords: architecture,cli,django,linting
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# django-arch-check
+
+A CLI tool that analyzes Django projects and detects architectural problems such as fat models, god apps, circular imports, missing service layers, and more.
+
+## Installation
+
+```bash
+pip install django-arch-check
+```
+
+## Usage
+
+```bash
+django-arch-check analyze /path/to/your/django/project
+```
+
+## Development
+
+```bash
+# Create and activate a virtual environment
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+
+# Run the CLI
+django-arch-check analyze /path/to/project
+```
+
+## License
+
+MIT

django_arch_check-0.1.0/README.md

@@ -0,0 +1,33 @@
+# django-arch-check
+
+A CLI tool that analyzes Django projects and detects architectural problems such as fat models, god apps, circular imports, missing service layers, and more.
+
+## Installation
+
+```bash
+pip install django-arch-check
+```
+
+## Usage
+
+```bash
+django-arch-check analyze /path/to/your/django/project
+```
+
+## Development
+
+```bash
+# Create and activate a virtual environment
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+
+# Run the CLI
+django-arch-check analyze /path/to/project
+```
+
+## License
+
+MIT

django_arch_check-0.1.0/django_arch_check/__init__.py

@@ -0,0 +1,3 @@
+"""django-arch-check: Architectural health checker for Django projects."""
+
+__version__ = "0.1.0"

django_arch_check-0.1.0/django_arch_check/analyzer.py

@@ -0,0 +1,68 @@
+"""Main analysis orchestrator.
+
+This module is responsible for running all registered detectors against a
+Django project and returning their aggregated results to the CLI layer.
+
+To add a new detector:
+    1. Implement it in ``detectors/<name>.py`` with a ``detect(project_path)``
+       function that returns a list of finding dataclasses.
+    2. Import the detector module and its Finding type below.
+    3. Add a field to :class:`AnalysisResult` for the new findings list.
+    4. Call the detector inside :func:`run_analysis` and populate the field.
+    5. Add any new threshold parameters to :func:`run_analysis` and pass them
+       through from the CLI layer.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from django_arch_check.detectors import celery_tasks, circular_imports, direct_sql, fat_models, god_apps, missing_service_layer, n_plus_one
+from django_arch_check.detectors.circular_imports import CircularImportFinding
+from django_arch_check.detectors.fat_models import FatModelFinding
+from django_arch_check.detectors.god_apps import GodAppFinding
+from django_arch_check.detectors.celery_tasks import CeleryTaskFinding
+from django_arch_check.detectors.direct_sql import DirectSQLFinding
+from django_arch_check.detectors.n_plus_one import NPlusOneFinding
+from django_arch_check.detectors.missing_service_layer import MissingServiceLayerFinding
+
+
+@dataclass
+class AnalysisResult:
+    """Aggregated output of all detectors for a single project run."""
+
+    fat_models: list[FatModelFinding] = field(default_factory=list)
+    god_apps: list[GodAppFinding] = field(default_factory=list)
+    circular_imports: list[CircularImportFinding] = field(default_factory=list)
+    missing_service_layer: list[MissingServiceLayerFinding] = field(default_factory=list)
+    celery_tasks: list[CeleryTaskFinding] = field(default_factory=list)
+    direct_sql: list[DirectSQLFinding] = field(default_factory=list)
+    n_plus_one: list[NPlusOneFinding] = field(default_factory=list)
+
+
+def run_analysis(
+    project_path: str,
+    fat_model_threshold: int = 10,
+    god_app_threshold: int = 30,
+    service_layer_threshold: int = 10,
+) -> AnalysisResult:
+    """Run all registered detectors against *project_path*.
+
+    Args:
+        project_path:        Root directory of the Django project.
+        fat_model_threshold: Minimum method count to flag a model as fat.
+        god_app_threshold:        Minimum LOC-% share to flag an app as a god app.
+        service_layer_threshold: Function body lines above which an ORM view is critical.
+
+    Returns:
+        An :class:`AnalysisResult` containing findings from every detector.
+    """
+    return AnalysisResult(
+        fat_models=fat_models.detect(project_path, threshold=fat_model_threshold),
+        god_apps=god_apps.detect(project_path, threshold=god_app_threshold),
+        circular_imports=circular_imports.detect(project_path),
+        missing_service_layer=missing_service_layer.detect(project_path, line_threshold=service_layer_threshold),
+        celery_tasks=celery_tasks.detect(project_path),
+        direct_sql=direct_sql.detect(project_path),
+        n_plus_one=n_plus_one.detect(project_path),
+    )

django_arch_check-0.1.0/django_arch_check/cli.py

@@ -0,0 +1,318 @@
+"""CLI entry point for django-arch-check."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from django_arch_check import __version__
+from django_arch_check.analyzer import AnalysisResult, run_analysis
+from django_arch_check.report import generate_html
+
+# ---------------------------------------------------------------------------
+# Severity styling
+# ---------------------------------------------------------------------------
+
+_SEVERITY_STYLE: dict[str, dict[str, object]] = {
+    "critical": {"fg": "red", "bold": True},
+    "warning": {"fg": "yellow", "bold": False},
+}
+
+
+def _severity_label(severity: str) -> str:
+    """Return a fixed-width, coloured severity label."""
+    label = f"[{severity.upper()}]"
+    # Pad to 10 chars so WARNING and CRITICAL columns align.
+    label = f"{label:<10}"
+    return click.style(label, **_SEVERITY_STYLE.get(severity, {}))  # type: ignore[arg-type]
+
+
+# ---------------------------------------------------------------------------
+# Section printers
+# ---------------------------------------------------------------------------
+
+
+def _print_fat_models(result: AnalysisResult) -> None:
+    """Print fat-model findings and their section summary."""
+    findings = result.fat_models
+
+    click.echo()
+    click.echo(click.style("── Fat Models ──────────────────────────────", bold=True))
+
+    if not findings:
+        click.echo(click.style("  No fat models found.", fg="green"))
+        return
+
+    for f in findings:
+        label = _severity_label(f.severity)
+        click.echo(
+            f"  {label} {f.file_path} → "
+            + click.style(f.class_name, bold=True)
+            + f" ({f.method_count} methods)"
+        )
+
+    count = len(findings)
+    click.echo()
+    click.echo(
+        click.style(f"  Found {count} fat model(s).", fg="red" if count else "green")
+    )
+
+
+def _print_god_apps(result: AnalysisResult) -> None:
+    """Print god-app findings and their section summary."""
+    findings = result.god_apps
+
+    click.echo()
+    click.echo(click.style("── God Apps ────────────────────────────────", bold=True))
+
+    if not findings:
+        click.echo(click.style("  No god apps found.", fg="green"))
+        return
+
+    for f in findings:
+        label = _severity_label(f.severity)
+        click.echo(
+            f"  {label} "
+            + click.style(f.app_path, bold=True)
+            + f" owns {f.percentage}% of total project code"
+            + f" ({f.app_loc:,} / {f.total_loc:,} lines)"
+        )
+
+    count = len(findings)
+    click.echo()
+    click.echo(
+        click.style(f"  Found {count} god app(s).", fg="red" if count else "green")
+    )
+
+
+def _print_circular_imports(result: AnalysisResult) -> None:
+    """Print circular-import findings and their section summary."""
+    findings = result.circular_imports
+
+    click.echo()
+    click.echo(click.style("── Circular Imports ────────────────────────", bold=True))
+
+    if not findings:
+        click.echo(click.style("  No circular imports found.", fg="green"))
+        return
+
+    for f in findings:
+        label = _severity_label(f.severity)
+        click.echo(
+            f"  {label} Circular import detected: "
+            + click.style(f.cycle_display, bold=True)
+        )
+
+    count = len(findings)
+    click.echo()
+    click.echo(click.style(f"  Found {count} circular import(s).", fg="red"))
+
+
+def _print_missing_service_layer(result: AnalysisResult) -> None:
+    """Print missing-service-layer findings and their section summary."""
+    findings = result.missing_service_layer
+
+    click.echo()
+    click.echo(click.style("── Missing Service Layer ────────────────────", bold=True))
+
+    if not findings:
+        click.echo(click.style("  No missing service layer issues found.", fg="green"))
+        return
+
+    for f in findings:
+        label = _severity_label(f.severity)
+        if f.severity == "critical":
+            detail = f"contains {f.line_count} lines of business logic"
+        else:
+            detail = "makes direct ORM calls"
+        click.echo(
+            f"  {label} {f.file_path} → "
+            + click.style(f.view_name + "()", bold=True)
+            + f" {detail}"
+        )
+
+    count = len(findings)
+    click.echo()
+    click.echo(
+        click.style(
+            f"  Found {count} missing service layer issue(s).",
+            fg="red" if count else "green",
+        )
+    )
+
+
+def _print_celery_tasks(result: AnalysisResult) -> None:
+    """Print Celery task findings and their section summary."""
+    findings = result.celery_tasks
+
+    click.echo()
+    click.echo(click.style("── Celery Tasks Without Retry ──────────────", bold=True))
+
+    if not findings:
+        click.echo(click.style("  No Celery tasks missing retry config.", fg="green"))
+        return
+
+    for f in findings:
+        label = _severity_label(f.severity)
+        if f.severity == "critical":
+            detail = "high-stakes task, no retry configured"
+        else:
+            detail = "no retry configured"
+        click.echo(
+            f"  {label} {f.file_path} → "
+            + click.style(f.task_name + "()", bold=True)
+            + f" — {detail}"
+        )
+
+    count = len(findings)
+    click.echo()
+    click.echo(
+        click.style(
+            f"  Found {count} Celery task(s) without retry.",
+            fg="red" if count else "green",
+        )
+    )
+
+
+def _print_direct_sql(result: AnalysisResult) -> None:
+    """Print direct-SQL findings and their section summary."""
+    findings = result.direct_sql
+
+    click.echo()
+    click.echo(click.style("── Direct SQL ──────────────────────────────", bold=True))
+
+    if not findings:
+        click.echo(click.style("  No direct SQL usage found.", fg="green"))
+        return
+
+    for f in findings:
+        label = _severity_label(f.severity)
+        click.echo(
+            f"  {label} {f.file_path}:{f.line_number} → raw SQL detected: "
+            + click.style(f.pattern, bold=True)
+        )
+
+    count = len(findings)
+    click.echo()
+    click.echo(click.style(f"  Found {count} direct SQL usage(s).", fg="yellow"))
+
+
+def _print_n_plus_one(result: AnalysisResult) -> None:
+    """Print N+1 query-risk findings and their section summary."""
+    findings = result.n_plus_one
+
+    click.echo()
+    click.echo(click.style("── N+1 Query Risks ─────────────────────────", bold=True))
+
+    if not findings:
+        click.echo(click.style("  No N+1 query risks found.", fg="green"))
+        return
+
+    for f in findings:
+        label = _severity_label(f.severity)
+        click.echo(
+            f"  {label} {f.file_path}:{f.line_number} → "
+            + click.style("ORM call inside loop", bold=True)
+            + " — possible N+1 query risk"
+        )
+
+    count = len(findings)
+    click.echo()
+    click.echo(click.style(f"  Found {count} potential N+1 issue(s).", fg="yellow"))
+
+
+def _write_html_report(result: AnalysisResult, project_path: str) -> None:
+    """Generate arch-report.html and write it to the project root."""
+    import os
+
+    from django_arch_check.report import compute_score
+
+    html_content = generate_html(result, project_path)
+    out_path = os.path.join(project_path, "arch-report.html")
+    with open(out_path, "w", encoding="utf-8") as fh:
+        fh.write(html_content)
+    score = compute_score(result)
+    click.echo(click.style(f"  Health score: {score}/100", bold=True))
+    click.echo(click.style(f"  Report saved: {out_path}", fg="cyan"))
+
+
+# ---------------------------------------------------------------------------
+# CLI definition
+# ---------------------------------------------------------------------------
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="django-arch-check")
+def main() -> None:
+    """Django Architectural Health Checker.
+
+    Analyzes a Django project for structural and architectural issues.
+    """
+
+
+@main.command()
+@click.argument(
+    "project_path",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, readable=True),
+)
+@click.option(
+    "--fat-model-threshold",
+    default=10,
+    show_default=True,
+    metavar="N",
+    help="Flag models with >= N non-dunder methods.",
+)
+@click.option(
+    "--god-app-threshold",
+    default=30,
+    show_default=True,
+    metavar="PCT",
+    help="Flag apps owning >= PCT% of total project LOC.",
+)
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["text", "html"], case_sensitive=False),
+    default="text",
+    show_default=True,
+    help="Output format: text (stdout) or html (arch-report.html).",
+)
+def analyze(
+    project_path: str,
+    fat_model_threshold: int,
+    god_app_threshold: int,
+    output_format: str,
+) -> None:
+    """Analyze a Django project at PROJECT_PATH for architectural issues."""
+    click.echo(click.style(f"Analyzing: {project_path}", bold=True))
+
+    result = run_analysis(
+        project_path,
+        fat_model_threshold=fat_model_threshold,
+        god_app_threshold=god_app_threshold,
+    )
+
+    if output_format == "html":
+        _write_html_report(result, project_path)
+        return
+
+    _print_fat_models(result)
+    _print_god_apps(result)
+    _print_circular_imports(result)
+    _print_missing_service_layer(result)
+    _print_celery_tasks(result)
+    _print_direct_sql(result)
+    _print_n_plus_one(result)
+
+    # Exit non-zero if any critical findings exist across all detectors —
+    # allows the tool to act as a CI gate.
+    has_critical = (
+        any(f.severity == "critical" for f in result.fat_models)
+        or any(f.severity == "critical" for f in result.god_apps)
+        or any(f.severity == "critical" for f in result.circular_imports)
+        or any(f.severity == "critical" for f in result.missing_service_layer)
+        or any(f.severity == "critical" for f in result.celery_tasks)
+    )
+    if has_critical:
+        sys.exit(1)

django_arch_check-0.1.0/django_arch_check/detectors/__init__.py

@@ -0,0 +1,5 @@
+"""Detector plugins for django-arch-check.
+
+Each module in this package implements a specific architectural check.
+All detectors will be discovered and invoked by the analyzer.
+"""

django_arch_check-0.1.0/django_arch_check/detectors/base.py

@@ -0,0 +1,7 @@
+"""Base class for all architectural detectors.
+
+All concrete detectors will inherit from BaseDetector and implement
+the `run()` method.
+"""
+
+# TODO: define BaseDetector protocol / abstract base class