py-code-quality-guard 0.1.0__tar.gz

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

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install dependencies
+        run: uv sync --dev
+      - name: Run Linting, Formatting Checks, and Type Checking, Testing
+        run: uv run pre-commit run --all-files

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

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    env:
+      PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade build
+
+      - name: Build package distributions
+        run: python -m build
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ env.PYPI_API_TOKEN }}

py_code_quality_guard-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+*.egg-info/

py_code_quality_guard-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: Ruff lint
+        entry: uv run ruff check
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: ruff-format
+        name: Ruff format
+        entry: uv run ruff format --check
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: pytest
+        name: Pytest
+        entry: uv run pytest
+        language: system
+        pass_filenames: false
+        always_run: true

py_code_quality_guard-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,19 @@
+- id: cqg
+  name: Code Quality Guard
+  entry: code-quality-guard
+  language: python
+  language_version: python3.12
+  pass_filenames: false
+  require_serial: true
+  types: [python]
+  description: |
+    Run Ruff linting, Ruff formatting checks, and Mypy over the project.
+  args:
+    - --tool
+    - ruff
+    - --tool
+    - ruff-format
+    - --tool
+    - mypy
+    - --check-only
+    - .

py_code_quality_guard-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

py_code_quality_guard-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: py-code-quality-guard
+Version: 0.1.0
+Summary: Automated Code Quality Guard for Python
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: mypy>=1.11
+Requires-Dist: pydantic>=2.8
+Requires-Dist: rich>=13.7
+Requires-Dist: ruff>=0.6
+Description-Content-Type: text/markdown
+
+# Code Quality Guard
+
+[![CI](https://github.com/karma369-labs/code-quality-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/karma369-labs/code-quality-guard/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/py-code-quality-guard)](https://pypi.org/project/py-code-quality-guard/)
+[![Python](https://img.shields.io/badge/python-3.12%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![Ruff](https://img.shields.io/badge/linter-Ruff-D7FF64?logo=ruff&logoColor=black)](https://docs.astral.sh/ruff/)
+[![Mypy](https://img.shields.io/badge/type%20checker-Mypy-4B8BBE?logo=mypy&logoColor=white)](https://mypy-lang.org/)
+
+`py-code-quality-guard` is a CI-friendly command-line quality gate for Python
+projects. It runs Ruff linting, Ruff formatting, and Mypy through one
+consistent interface, with human-readable or JSON output for local workflows
+and automation.
+
+## Features
+
+- Run Ruff, Ruff format, and Mypy independently or together.
+- Check a project directory or a single file.
+- Apply Ruff fixes when supported.
+- Forward additional arguments to each selected tool.
+- Emit text for developers or JSON for scripts and CI integrations.
+- Return a non-zero exit code when any selected check fails.
+
+## Requirements
+
+- Python 3.12 or newer
+- Ruff and Mypy are installed automatically with the package
+
+## Installation
+
+Install the latest release from PyPI in an active virtual environment:
+
+```bash
+python -m pip install py-code-quality-guard
+```
+
+For local development with `uv`:
+
+```bash
+uv sync --dev
+```
+
+## Pre-commit Hook
+
+Add `py-code-quality-guard` to a project-level `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+	- repo: https://github.com/karma369-labs/code-quality-guard
+		rev: v0.1.0
+		hooks:
+			- id: cqg
+```
+
+Install the hook and run it against the repository:
+
+```bash
+python -m pip install pre-commit
+pre-commit install
+pre-commit run --all-files
+```
+
+The `cqg` hook runs Ruff linting, Ruff formatting checks, and Mypy over the
+project. To use a newer release, update `rev` to the corresponding package
+release tag.
+
+## Usage
+
+Run all checks against the current directory:
+
+```bash
+pyqguard .
+```
+
+Run selected tools:
+
+```bash
+pyqguard --tool ruff --tool mypy src/
+```
+
+Checks report the tools' diagnostics without changing files by default:
+
+```bash
+pyqguard --tool ruff-format .
+```
+
+Apply supported fixes:
+
+```bash
+pyqguard --tool ruff --tool ruff-format --fix .
+```
+
+Produce machine-readable output:
+
+```bash
+pyqguard --output json .
+```
+
+Pass an additional argument to a selected tool. Repeat `--tool-arg` as
+needed:
+
+```bash
+pyqguard \
+	--tool ruff \
+	--tool-arg ruff --select \
+	--tool-arg ruff E,F \
+	.
+```
+
+Run `pyqguard --help` for the complete option reference.
+
+## Development
+
+Install the development dependencies and run the test suite:
+
+```bash
+uv sync --dev
+uv run pytest
+```
+
+The repository uses pre-commit for linting, formatting, type checking, and
+other repository checks:
+
+```bash
+uv run pre-commit install
+uv run pre-commit run --all-files
+```
+
+Pull requests targeting `main` run the same pre-commit checks in GitHub Actions.
+
+
+## License
+
+License information has not yet been published for this repository.

py_code_quality_guard-0.1.0/README.md

@@ -0,0 +1,133 @@
+# Code Quality Guard
+
+[![CI](https://github.com/karma369-labs/code-quality-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/karma369-labs/code-quality-guard/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/py-code-quality-guard)](https://pypi.org/project/py-code-quality-guard/)
+[![Python](https://img.shields.io/badge/python-3.12%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![Ruff](https://img.shields.io/badge/linter-Ruff-D7FF64?logo=ruff&logoColor=black)](https://docs.astral.sh/ruff/)
+[![Mypy](https://img.shields.io/badge/type%20checker-Mypy-4B8BBE?logo=mypy&logoColor=white)](https://mypy-lang.org/)
+
+`py-code-quality-guard` is a CI-friendly command-line quality gate for Python
+projects. It runs Ruff linting, Ruff formatting, and Mypy through one
+consistent interface, with human-readable or JSON output for local workflows
+and automation.
+
+## Features
+
+- Run Ruff, Ruff format, and Mypy independently or together.
+- Check a project directory or a single file.
+- Apply Ruff fixes when supported.
+- Forward additional arguments to each selected tool.
+- Emit text for developers or JSON for scripts and CI integrations.
+- Return a non-zero exit code when any selected check fails.
+
+## Requirements
+
+- Python 3.12 or newer
+- Ruff and Mypy are installed automatically with the package
+
+## Installation
+
+Install the latest release from PyPI in an active virtual environment:
+
+```bash
+python -m pip install py-code-quality-guard
+```
+
+For local development with `uv`:
+
+```bash
+uv sync --dev
+```
+
+## Pre-commit Hook
+
+Add `py-code-quality-guard` to a project-level `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+	- repo: https://github.com/karma369-labs/code-quality-guard
+		rev: v0.1.0
+		hooks:
+			- id: cqg
+```
+
+Install the hook and run it against the repository:
+
+```bash
+python -m pip install pre-commit
+pre-commit install
+pre-commit run --all-files
+```
+
+The `cqg` hook runs Ruff linting, Ruff formatting checks, and Mypy over the
+project. To use a newer release, update `rev` to the corresponding package
+release tag.
+
+## Usage
+
+Run all checks against the current directory:
+
+```bash
+pyqguard .
+```
+
+Run selected tools:
+
+```bash
+pyqguard --tool ruff --tool mypy src/
+```
+
+Checks report the tools' diagnostics without changing files by default:
+
+```bash
+pyqguard --tool ruff-format .
+```
+
+Apply supported fixes:
+
+```bash
+pyqguard --tool ruff --tool ruff-format --fix .
+```
+
+Produce machine-readable output:
+
+```bash
+pyqguard --output json .
+```
+
+Pass an additional argument to a selected tool. Repeat `--tool-arg` as
+needed:
+
+```bash
+pyqguard \
+	--tool ruff \
+	--tool-arg ruff --select \
+	--tool-arg ruff E,F \
+	.
+```
+
+Run `pyqguard --help` for the complete option reference.
+
+## Development
+
+Install the development dependencies and run the test suite:
+
+```bash
+uv sync --dev
+uv run pytest
+```
+
+The repository uses pre-commit for linting, formatting, type checking, and
+other repository checks:
+
+```bash
+uv run pre-commit install
+uv run pre-commit run --all-files
+```
+
+Pull requests targeting `main` run the same pre-commit checks in GitHub Actions.
+
+
+## License
+
+License information has not yet been published for this repository.

py_code_quality_guard-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "py-code-quality-guard"
+version = "0.1.0"
+description = "Automated Code Quality Guard for Python"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+	"click>=8.1",
+	"mypy>=1.11",
+	"pydantic>=2.8",
+	"rich>=13.7",
+	"ruff>=0.6",
+]
+
+[project.scripts]
+pyqguard = "code_quality_guard.cli:main"
+
+[dependency-groups]
+dev = [
+	"pre-commit>=3.8",
+	"pytest>=8.3",
+	"pytest-cov>=5.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/code_quality_guard"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]

py_code_quality_guard-0.1.0/src/code_quality_guard/__init__.py

@@ -0,0 +1,3 @@
+"""Automated quality gates for Python projects."""
+
+__version__ = "0.1.0"

py_code_quality_guard-0.1.0/src/code_quality_guard/__main__.py

@@ -0,0 +1,4 @@
+from code_quality_guard.cli import main
+
+if __name__ == "__main__":
+    main()

py_code_quality_guard-0.1.0/src/code_quality_guard/application/__init__.py

@@ -0,0 +1 @@
+"""Application orchestration for quality checks."""

py_code_quality_guard-0.1.0/src/code_quality_guard/application/service.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from code_quality_guard.config.settings import Settings
+from code_quality_guard.runner import CommandResult
+from code_quality_guard.tools.registry import build_tools
+
+
+def run_quality_checks(settings: Settings) -> dict[str, CommandResult]:
+    return {tool.name: tool.run(settings) for tool in build_tools(settings.tools)}

py_code_quality_guard-0.1.0/src/code_quality_guard/cli.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from code_quality_guard.application.service import run_quality_checks
+from code_quality_guard.config.settings import Settings
+from code_quality_guard.reporter.console import render_console
+from code_quality_guard.reporter.json import render_json
+
+TOOL_NAMES = ["ruff", "ruff-format", "mypy"]
+
+
+@click.command()
+@click.argument("target", type=click.Path(path_type=Path, exists=True), default=Path.cwd())
+@click.option("--tool", "tools", multiple=True, type=click.Choice(TOOL_NAMES))
+@click.option("--fix", is_flag=True, help="Apply supported fixes.")
+@click.option("--check-only", is_flag=True, help="Check formatting without changing files.")
+@click.option("--output", type=click.Choice(["text", "json"]), default="text", show_default=True)
+@click.option(
+    "--tool-arg",
+    "tool_args",
+    nargs=2,
+    multiple=True,
+    metavar="TOOL ARG",
+    help="Pass an additional argument to a tool; repeat as needed.",
+)
+def main(
+    target: Path,
+    tools: tuple[str, ...],
+    fix: bool,
+    check_only: bool,
+    output: str,
+    tool_args: tuple[tuple[str, str], ...],
+) -> None:
+    """Run selected code quality tools against TARGET."""
+    selected_tools = tools or tuple(TOOL_NAMES)
+    args_by_tool: dict[str, tuple[str, ...]] = {}
+    for tool_name, argument in tool_args:
+        if tool_name not in selected_tools:
+            raise click.BadParameter(f"{tool_name!r} is not selected with --tool")
+        args_by_tool[tool_name] = (*args_by_tool.get(tool_name, ()), argument)
+    settings = Settings(
+        target=target.resolve(),
+        tools=selected_tools,
+        fix=fix,
+        check_only=check_only,
+        output=output,
+        tool_args=args_by_tool,
+    )
+    results = run_quality_checks(settings)
+    if settings.output == "json":
+        click.echo(render_json(results))
+    else:
+        render_console(results)
+    if not all(result.passed for result in results.values()):
+        raise click.exceptions.Exit(1)

py_code_quality_guard-0.1.0/src/code_quality_guard/config/__init__.py

@@ -0,0 +1,3 @@
+from .settings import Settings
+
+__all__ = ["Settings"]

py_code_quality_guard-0.1.0/src/code_quality_guard/config/settings.py

@@ -0,0 +1,15 @@
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Settings(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    target: Path = Field(default_factory=Path.cwd)
+    tools: tuple[str, ...] = ("ruff", "mypy")
+    fix: bool = False
+    check_only: bool = False
+    output: Literal["text", "json"] = "text"
+    tool_args: dict[str, tuple[str, ...]] = Field(default_factory=dict)

py_code_quality_guard-0.1.0/src/code_quality_guard/reporter/__init__.py

@@ -0,0 +1 @@
+"""Human and machine-readable reporting."""

py_code_quality_guard-0.1.0/src/code_quality_guard/reporter/console.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from rich.console import Console
+
+from code_quality_guard.runner import CommandResult
+
+
+def render_console(results: dict[str, CommandResult]) -> None:
+    console = Console()
+    for name, result in results.items():
+        status = "PASS" if result.passed else "FAIL"
+        color = "green" if result.passed else "red"
+        console.print(
+            f"[{color}][{status}][/{color}] {name} ({result.duration_seconds:.2f}s)"
+        )
+        diagnostics = "\n".join(
+            output.strip() for output in (result.stdout, result.stderr) if output.strip()
+        )
+        if diagnostics:
+            console.print(diagnostics, markup=False)

py_code_quality_guard-0.1.0/src/code_quality_guard/reporter/json.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from typing import Any
+
+from code_quality_guard.runner import CommandResult
+
+
+def render_json(results: dict[str, CommandResult]) -> str:
+    payload: dict[str, Any] = {
+        "checks": {name: asdict(result) for name, result in results.items()},
+        "passed": all(result.passed for result in results.values()),
+    }
+    return json.dumps(payload, indent=2, sort_keys=True)

py_code_quality_guard-0.1.0/src/code_quality_guard/runner.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class CommandResult:
+    command: list[str]
+    passed: bool
+    exit_code: int
+    stdout: str
+    stderr: str
+    duration_seconds: float
+
+
+class SubprocessRunner:
+    def run(self, command: list[str], cwd: Path | None = None) -> CommandResult:
+        started = time.perf_counter()
+        try:
+            completed = subprocess.run(
+                command, cwd=cwd, capture_output=True, text=True, check=False
+            )
+            stdout, stderr, exit_code = completed.stdout, completed.stderr, completed.returncode
+        except FileNotFoundError as error:
+            stdout, stderr, exit_code = (
+                "",
+                f"Command not found: {error.filename or command[0]}",
+                127,
+            )
+        return CommandResult(
+            command=command,
+            passed=exit_code == 0,
+            exit_code=exit_code,
+            stdout=stdout,
+            stderr=stderr,
+            duration_seconds=time.perf_counter() - started,
+        )

py_code_quality_guard-0.1.0/src/code_quality_guard/tools/__init__.py

@@ -0,0 +1 @@
+"""Adapters for external quality tools."""

py_code_quality_guard-0.1.0/src/code_quality_guard/tools/base.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from code_quality_guard.config.settings import Settings
+from code_quality_guard.runner import CommandResult
+
+
+class Tool(Protocol):
+    name: str
+
+    def run(self, settings: Settings) -> CommandResult:
+        """Run the tool for the configured target."""

py_code_quality_guard-0.1.0/src/code_quality_guard/tools/command.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+
+
+def resolve_executable(name: str) -> str:
+    environment_executable = Path(sys.executable).with_name(name)
+    if environment_executable.exists():
+        return str(environment_executable)
+    return shutil.which(name) or name

py_code_quality_guard-0.1.0/src/code_quality_guard/tools/mypy.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from code_quality_guard.config.settings import Settings
+from code_quality_guard.runner import CommandResult, SubprocessRunner
+from code_quality_guard.tools.command import resolve_executable
+
+
+class MypyTool:
+    name = "mypy"
+
+    def __init__(self, runner: SubprocessRunner | None = None) -> None:
+        self.runner = runner or SubprocessRunner()
+
+    def run(self, settings: Settings) -> CommandResult:
+        command = [resolve_executable("mypy"), str(settings.target)]
+        command.extend(settings.tool_args.get(self.name, ()))
+        cwd = settings.target if settings.target.is_dir() else settings.target.parent
+        return self.runner.run(command, cwd=cwd)