pkgdx 0.5.0rc1__py3-none-any.whl

pkgdx/__init__.py

@@ -0,0 +1,17 @@
+"""__init__ for pkgdx."""
+
+import contextlib
+from importlib import metadata
+from pathlib import Path
+
+from pkgdx import exceptions, standards
+from pkgdx.logging import configure_pkg_logging
+
+__all__: list[str] = ["exceptions", "standards"]
+
+PKGDX_ROOT: Path = Path(__file__).parent
+
+configure_pkg_logging()
+
+with contextlib.suppress(metadata.PackageNotFoundError):
+    __version__: str = metadata.version("pkgdx")

pkgdx/__main__.py

@@ -0,0 +1,207 @@
+"""Main entry point for pkgdx pre-commit hooks and CLI."""
+
+import argparse
+import logging
+import sys
+import textwrap
+from collections.abc import Callable
+from typing import NoReturn
+
+from pkgdx import __version__, _core, exceptions
+from pkgdx.logging import CLI_CONSOLE, configure_cli_logging
+from pkgdx.standards import _hooks
+from pkgdx.standards._cli import add_subparser as add_standards_subparser
+
+logger = logging.getLogger(__package__)
+
+
+__all__: list[str] = [
+    "detect_secrets",
+    "main",
+    "mypy_typing",
+    "pymarkdown_lint",
+    "ruff_format",
+    "ruff_lint",
+]
+
+
+# PRE-COMMIT ENTRYPOINTS [project.scripts]
+
+
+def _run_hook(func: Callable[[list[str]], int]) -> NoReturn:
+    """Run a config hook, reporting `pkgdx` errors without a traceback.
+
+    Args:
+        func: The core hook logic, called with `sys.argv[1:]`.
+    """
+    try:
+        code = func(sys.argv[1:])
+    except exceptions.Error as err:
+        sys.stderr.write(f"pkgdx: {err}\n")
+        sys.exit(_core.ExitCode.EX_FAILURE)
+    sys.exit(code)
+
+
+def ruff_format() -> NoReturn:
+    """Run ruff formatting with the configured settings.
+
+    NOTE: Relates to pre-commit hook ID `pkgdx-format`, with
+    entry point `pkgdx-format-hook`.
+    """
+    _run_hook(_hooks.core_ruff_format)
+
+
+def ruff_lint() -> NoReturn:
+    """Run ruff linting with the configured settings.
+
+    NOTE: Relates to pre-commit hook ID `pkgdx-lint`, with
+    entry point `pkgdx-lint-hook`.
+    """
+    _run_hook(_hooks.core_ruff_lint)
+
+
+def mypy_typing() -> NoReturn:
+    """Run mypy type checking with the configured settings.
+
+    NOTE: Relates to pre-commit hook ID `pkgdx-typing`, with
+    entry point `pkgdx-typing-hook`.
+    """
+    _run_hook(_hooks.core_mypy_typing)
+
+
+def detect_secrets() -> NoReturn:
+    """Run detect-secrets with the provided arguments.
+
+    NOTE: Relates to pre-commit hook ID `pkgdx-secrets`, with
+    entry point `pkgdx-secrets-hook`.
+    """
+    sys.exit(_hooks.core_detect_secrets(sys.argv[1:]))
+
+
+def pymarkdown_lint() -> NoReturn:
+    """Run pymarkdown linting with the configured settings.
+
+    NOTE: Relates to pre-commit hook ID `pkgdx-markdown`, with
+    entry point `pkgdx-markdown-hook`.
+    """
+    _run_hook(_hooks.core_pymarkdown_lint)
+
+
+# MAIN CLI COMMANDS
+
+
+class CLIArgumentParser(argparse.ArgumentParser):
+    """Custom CLI ArgumentParser."""
+
+    def error(self, message: str) -> NoReturn:
+        """Handle CLI errors by printing a formatted message and exiting.
+
+        Args:
+            message: The error message to display.
+        """
+
+        CLI_CONSOLE.print(f"[red]ERROR:[/red] [b]{message}[/b]", end="\n\n")
+        self.print_usage(sys.stderr)
+        CLI_CONSOLE.print(
+            f"\n[dim]Try [cyan]{self.prog} --help[/cyan].[/dim]",
+        )
+
+        sys.exit(_core.ExitCode.EX_USAGE)
+
+
+def main() -> NoReturn:
+    """Provide a unified `pkgdx` CLI entrypoint - init."""
+
+    # Provides a base parser for shared arguments across subcommands
+    base_parser = CLIArgumentParser(add_help=False)
+    base_parser.add_argument(
+        "-h",
+        "--help",
+        action="help",
+        help="Show this help message and exit",
+    )
+
+    description = textwrap.dedent(
+        """pkgdx centralises creation and implementation of coding standards
+        across projects, providing a single source of truth for toolchain
+        configuration."""
+    )
+
+    epilog = textwrap.fill(
+        "For more information see https://gitlab.com/andyrids/pkgdx.",
+        width=79,
+        initial_indent="",
+    )
+
+    # Main parser for the CLI
+    parser = CLIArgumentParser(
+        prog=__package__,
+        description=textwrap.fill(description, width=79),
+        usage="USAGE:\n %(prog)s [options] <command>",
+        epilog=epilog,
+        add_help=False,
+        parents=[base_parser],
+        formatter_class=_core.CLIGFormatter,
+    )
+
+    parser._optionals.title = "OPTIONS"
+
+    parser.add_argument(
+        "-d",
+        "--debug",
+        action="store_true",
+        help="Show debug logging output",
+    )
+
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"v{__version__}",
+        help="Show program's version number and exit",
+    )
+
+    subparsers = parser.add_subparsers(
+        title="COMMANDS",
+        # Mitigate subparser usage display issue by explicitly setting prog
+        # https://github.com/python/cpython/issues/86463
+        prog=parser.prog,
+        dest="command",
+        required=False,
+        metavar="<command>",
+    )
+
+    add_standards_subparser(subparsers, base_parser)
+
+    args = parser.parse_args()
+
+    # Empty command (`pkgdx`) shows header and help
+    if args.command is None:
+        sys.stdout.write(
+            f"Package Developer Experience (DX) Toolkit [v{__version__}]\n\n"
+        )
+
+        # Prints; USAGE, description, OPTIONS, COMMANDS & epilog
+        parser.print_help()
+
+        sys.exit(_core.ExitCode.EX_OK)
+
+    # Configure logging based on debug flag
+    is_debug = args.debug
+    configure_cli_logging(logging.DEBUG if is_debug else logging.WARNING)
+
+    ctx = _core.CLIContext(args=args, console=CLI_CONSOLE, is_debug=is_debug)
+
+    try:
+        exit_code = int(args.func(ctx))
+    except exceptions.Error as err:
+        logger.error(str(err))
+        exit_code = _core.ExitCode.EX_FAILURE
+    except Exception:
+        logger.exception("Unexpected error")
+        exit_code = _core.ExitCode.EX_SYNTAX
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()

pkgdx/_core.py

@@ -0,0 +1,370 @@
+"""Core logic and file-system operations for the `pkgdx init` command."""
+
+import argparse
+import dataclasses
+import logging
+import os
+import re
+import subprocess
+import sys
+from collections.abc import Iterable
+from enum import IntEnum
+from itertools import chain
+from pathlib import Path
+from typing import Any
+
+import tomlkit
+from rich.console import Console
+from tomlkit import TOMLDocument
+from tomlkit.items import Table
+
+from pkgdx import exceptions, standards
+from pkgdx._types import HookBuiltin, HookLocal, HookRemote
+
+logger = logging.getLogger(__package__)
+
+
+class ExitCode(IntEnum):
+    """Exit codes for the CLI commands.
+
+    NOTE: Members can be passed to `sys.exit` as `int` type checks pass
+    due to `IntEnum` inheritance.
+    """
+
+    EX_OK = 0
+    EX_FAILURE = 1
+    EX_SYNTAX = 2
+    EX_USAGE = 64
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class CLIContext:
+    """Centralized state for the CLI commands.
+
+    Attributes:
+        args: The parsed command-line arguments from argparse.
+        console: The Rich console instance used for terminal output.
+        is_debug: Flag indicating if the CLI is running in debug mode.
+    """
+
+    args: argparse.Namespace
+    console: Console
+    is_debug: bool = False
+
+
+class CLIGFormatter(argparse.RawDescriptionHelpFormatter):
+    """Custom formatter for the CLI help output.
+
+    NOTE: Based on CLI guidance from https://clig.dev/.
+    """
+
+    def add_usage(
+        self,
+        usage: str | None,
+        actions: Iterable[argparse.Action],
+        groups: Iterable[argparse._MutuallyExclusiveGroup],
+        prefix: str | None = None,
+    ) -> None:
+        """Add a custom usage message to the CLI help output.
+
+        Args:
+            usage: The usage string to display.
+            actions: The list of actions for the parser.
+            groups: The list of mutually exclusive groups for the parser.
+            prefix: The prefix for the usage message.
+        """
+
+        super().add_usage(usage, actions, groups, prefix=prefix or "")
+
+
+def get_git_toplevel() -> Path:
+    """Get the root path of the consuming Git repository.
+
+    Returns:
+        The Git top-level directory path.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            check=True,
+            text=True,
+            capture_output=True,
+        )
+    except subprocess.CalledProcessError as e:
+        msg = "Failed `git rev-parse --show-toplevel`"
+        raise exceptions.GitTopLevelError(msg) from e
+    else:
+        return Path(result.stdout.strip())
+
+
+def get_project_root() -> Path:
+    """Get the root path of the consuming repo.
+
+    Returns:
+        The root path of the consuming repo.
+    """
+    cwd = Path.cwd().resolve()
+    for directory in chain([cwd], cwd.parents):
+        if (directory / "pyproject.toml").exists():
+            return directory
+
+    venv_parent = Path(sys.prefix).parent
+    if (venv_parent / "pyproject.toml").exists():
+        return venv_parent
+
+    msg = f"Cannot identify project root:- `{sys.prefix=}` | `{cwd=}`."
+    raise exceptions.ProjectRootNotFoundError(msg)
+
+
+def install_prek_hooks(root: Path) -> None:
+    """Install pre-commit hooks if not installed.
+
+    Args:
+        root: The root path of the consuming repo.
+    """
+    precommit_config = root / ".git" / "hooks" / "pre-commit"
+    if precommit_config.exists():
+        logger.debug("Git shims already installed at `.git/hooks/pre-commit`")
+        return
+    try:
+        subprocess.run(
+            [sys.executable, "-m", "prek", "install"],
+            cwd=root,
+            capture_output=True,
+            check=True,
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        logger.exception("Failed to install Git shims")
+    else:
+        logger.debug("Git shims installed at `.git/hooks/pre-commit`")
+
+
+def update_prek_hooks(root: Path) -> None:
+    """Check for pre-commit hook updates.
+
+    NOTE: Updates the pre-commit hooks based on available tagged versions in
+    the remote `pkgdx` repo.
+
+    Args:
+        root: The root path of the consuming repo.
+    """
+    try:
+        subprocess.run(
+            [sys.executable, "-m", "prek", "update", "--check", "-v"],
+            cwd=root,
+            capture_output=True,
+            check=True,
+            text=True,
+        )
+    except subprocess.CalledProcessError as e:
+        msg = re.sub(r"\n\s|\n", "", e.stdout or e.stderr or "Unknown error")
+        match e.returncode:
+            case 1:
+                logger.warning(msg)
+                logger.warning("Update remote hook revisions - `prek update`")
+            case 2:
+                logger.error(msg)
+            case _:
+                logger.exception(msg)
+    except FileNotFoundError:
+        logger.exception("Check `prek.toml` config exists")
+    else:
+        logger.debug("Remote hook revisions are up-to-date")
+
+
+def _create_repo_table(
+    doc: TOMLDocument, name: str, revision: str | None = None
+) -> Table:
+    """Create a new repository table in the pre-commit configuration.
+
+    Args:
+        doc: The TOMLDocument to parse.
+        name: The name of the repository.
+        revision: The revision of the repository.
+    """
+    new_repo = tomlkit.table()
+    new_repo["repo"] = name
+    if revision:
+        new_repo["rev"] = revision
+
+    new_repo.add(tomlkit.nl())
+
+    new_repo["hooks"] = tomlkit.aot()
+    doc["repos"].append(new_repo)
+
+    logger.debug("Created `[repo]` - %s | %s", name, revision)
+    return new_repo
+
+
+def _get_repo_table(
+    doc: TOMLDocument, name: str, revision: str | None = None
+) -> tuple[Table, bool]:
+    """Get an existing or create a new repository table.
+
+    Args:
+        doc: The TOMLDocument to parse.
+        name: The name of the repository.
+        revision: The revision of the repository.
+
+    Returns:
+        A tuple containing the table and a boolean indicating any changes.
+    """
+    for repo in doc["repos"]:
+        if repo.get("repo") == name:
+            if "hooks" not in repo:
+                repo["hooks"] = tomlkit.aot()
+                return repo, True
+            return repo, False
+    return _create_repo_table(doc, name, revision), True
+
+
+def _inject_missing_hooks(
+    table: dict[str, Any],
+    expected_hooks: list[HookBuiltin | HookLocal | HookRemote],
+) -> bool:
+    """Inject missing hooks into the repository table.
+
+    Args:
+        table: The repository table.
+        expected_hooks: The expected hooks to be present in the table.
+
+    Returns:
+        A boolean indicating if the table was modified.
+    """
+    changed = False
+    existing_id_set = {hook.get("id") for hook in table.get("hooks", [])}
+
+    for expected in expected_hooks:
+        if expected["id"] not in existing_id_set:
+            logger.debug("Detected missing hook `%s`", expected["id"])
+            hook_table = tomlkit.table()
+            for key, value in expected.items():
+                if isinstance(value, list):
+                    array = tomlkit.array()
+                    for item in value:
+                        array.append(item)
+                    hook_table[key] = array
+                else:
+                    hook_table[key] = value
+
+            hook_table.add(tomlkit.nl())
+            table["hooks"].append(hook_table)
+            changed = True
+    return changed
+
+
+def _validate_prek_repos(doc: TOMLDocument) -> None:
+    """Validate the consumer `prek.toml` `[[repos]]` shape.
+
+    NOTE: A missing or empty `repos` key stays valid - the template
+    injection path in `setup_prek_config` creates it.
+
+    Args:
+        doc: The parsed consumer `prek.toml` document.
+
+    Raises:
+        exceptions.PrekConfigError: On a malformed repo/hook entry.
+    """
+    repos = doc.get("repos")
+    if repos is None:
+        return
+    if not isinstance(repos, list):
+        msg = "`repos` must be an array of tables"
+        raise exceptions.PrekConfigError(msg)
+
+    for index, repo in enumerate(repos):
+        is_table = isinstance(repo, dict)
+        if not is_table or not isinstance(repo.get("repo"), str):
+            msg = f"`repos[{index}]` missing string `repo` key"
+            raise exceptions.PrekConfigError(msg)
+
+        hooks = repo.get("hooks", [])
+        if not isinstance(hooks, list):
+            msg = f"`repos[{index}].hooks` must be an array of tables"
+            raise exceptions.PrekConfigError(msg)
+
+        for hook_index, hook in enumerate(hooks):
+            is_table = isinstance(hook, dict)
+            if not is_table or not isinstance(hook.get("id"), str):
+                msg = (
+                    f"`repos[{index}].hooks[{hook_index}]`"
+                    " missing string `id` key"
+                )
+                raise exceptions.PrekConfigError(msg)
+
+
+def setup_prek_config(root: Path, reset: bool = False) -> None:
+    """Configure pre-commit hooks in the consuming repo.
+
+    Args:
+        root: The root path of the consuming repo.
+        reset: Clean installation flag. Defaults to False.
+    """
+    changed = False
+    config_existing = root / "prek.toml"
+    config_template = standards.resolve_config(standards.PREK_CONFIG)
+
+    if reset or not config_existing.exists():
+        logger.debug("Creating `prek.toml` from template")
+        config_existing.write_text(config_template.read_text())
+        return
+
+    # Consuming project `prek.toml`
+    doc_consumer: TOMLDocument = tomlkit.parse(config_existing.read_text())
+    _validate_prek_repos(doc_consumer)
+
+    if "repos" not in doc_consumer or not doc_consumer.get("repos", []):
+        logger.debug("Existing `prek.toml` missing or has empty `[repos]`")
+        doc_consumer["repos"] = tomlkit.aot()
+        changed = True
+
+    # `pkgdx` template `prek.toml`
+    doc_pkgdx: TOMLDocument = tomlkit.parse(config_template.read_text())
+    for table in doc_pkgdx.get("repos", []):
+        name, rev = table.get("repo"), table.get("rev")
+        table_consumer, tchanged = _get_repo_table(doc_consumer, name, rev)
+
+        table_pkgdx = table.get("hooks", [])
+        hchanged = _inject_missing_hooks(table_consumer, table_pkgdx)
+
+        changed = changed or tchanged or hchanged
+
+    if changed:
+        config_text = tomlkit.dumps(doc_consumer)
+        # Normalise spacing between tables
+        config_text = re.sub(r"\n+\[\[repos", "\n\n[[repos", config_text)
+
+        config_existing.write_text(config_text)
+        logger.debug("Added missing pre-commit hooks to `prek.toml`")
+    else:
+        logger.debug("Existing `prek.toml` is correct & unchanged")
+
+
+def create_secrets_baseline(root: Path) -> None:
+    """Run detect-secrets to create a `.secrets.baseline` file."""
+    secrets_baseline = root / ".secrets.baseline"
+    if secrets_baseline.exists():
+        logger.debug("Using existing `.secrets.baseline`")
+        return
+
+    logger.debug("Creating `.secrets.baseline` at %s", root)
+    try:
+        with open(secrets_baseline, "w") as f:
+            subprocess.run(
+                [
+                    sys.executable,
+                    "-m",
+                    "detect_secrets",
+                    "scan",
+                    "--exclude-files",
+                    r"(.*\.lock)",
+                ],
+                cwd=root,
+                env=os.environ | {"PYTHONUTF8": "1"},
+                stdout=f,
+                check=True,
+            )
+    except (subprocess.CalledProcessError, FileNotFoundError) as e:
+        secrets_baseline.unlink(missing_ok=True)
+        msg = "Error creating `.secrets.baseline`"
+        raise exceptions.Error(msg) from e

pkgdx/_types.py

@@ -0,0 +1,111 @@
+"""Type definitions for Pre-commit hooks and repositories in the TOML config.
+
+This module defines `TypedDict` classes for representing remote, local and
+builtin hooks and repositories as they appear in the Pre-commit configuration.
+"""
+
+from typing import Literal, NotRequired, TypedDict
+
+
+class HookRemote(TypedDict):
+    """Represents a Pre-commit remote hook entry in the TOML config.
+
+    Attributes:
+        id: The unique identifier for the remote hook.
+        name: The name of the remote hook.
+        entry: The entry point for the remote hook.
+        args: The list of arguments for the remote hook.
+        language: The programming language of the remote hook.
+        types_or: The list of file types the hook applies to.
+        exclude: The pattern for files to exclude from the hook.
+        require_serial: Flag indicating if the hook requires serial execution.
+        pass_filenames: Flag indicating if filenames should be passed to the
+            hook.
+    """
+
+    id: str
+    name: NotRequired[str]
+    entry: NotRequired[str]
+    args: NotRequired[list[str]]
+    language: NotRequired[str]
+    types_or: NotRequired[list[str]]
+    exclude: NotRequired[str]
+    require_serial: NotRequired[bool]
+    pass_filenames: NotRequired[bool]
+
+
+class RepoRemote(TypedDict):
+    """Represents a Pre-commit remote repo entry in the TOML config.
+
+    Attributes:
+        repo: The URL of the remote repository.
+        rev: The revision of the remote repository.
+        hooks: A list of remote hooks associated with the repository.
+    """
+
+    repo: str
+    rev: NotRequired[str]
+    hooks: list[HookRemote]
+
+
+class HookLocal(TypedDict):
+    """Represents a Pre-commit local hook entry in the TOML config.
+
+    Attributes:
+        id: The unique identifier for the local hook.
+        name: The name of the local hook.
+        entry: The entry point for the local hook.
+        args: The list of arguments for the local hook.
+        language: The programming language of the local hook.
+        types_or: The list of file types the hook applies to.
+        exclude: The pattern for files to exclude from the hook.
+        require_serial: Flag indicating if the hook requires serial execution.
+        pass_filenames: Flag indicating if filenames should be passed to the
+            hook.
+    """
+
+    id: str
+    name: str
+    entry: str
+    args: NotRequired[list[str]]
+    language: str
+    types_or: NotRequired[list[str]]
+    exclude: NotRequired[str]
+    require_serial: NotRequired[bool]
+    pass_filenames: NotRequired[bool]
+
+
+class RepoLocal(TypedDict):
+    """Represents a Pre-commit local repo entry in the TOML config.
+
+    Attributes:
+        repo: The literal string "local" indicating a local repository.
+        rev: The revision of the local repository.
+        hooks: A list of local hooks associated with the repository.
+    """
+
+    repo: Literal["local"]
+    rev: NotRequired[str]
+    hooks: list[HookLocal]
+
+
+class HookBuiltin(TypedDict):
+    """Represents a Pre-commit builtin hook entry in the TOML config.
+
+    Attributes:
+        id: The unique identifier for the builtin hook.
+    """
+
+    id: str
+
+
+class RepoBuiltin(TypedDict):
+    """Represents a Pre-commit builtin repo entry in the TOML config.
+
+    Attributes:
+        repo: The literal string "builtin" indicating a builtin repository.
+        hooks: A list of builtin hooks associated with the repository.
+    """
+
+    repo: Literal["builtin"]
+    hooks: list[HookBuiltin]