pygenkit 0.2.0__py3-none-any.whl

pygenkit/templates/python-cli/src/{{module_name}}/cli.py.jinja

@@ -0,0 +1,28 @@
+"""CLI entry point for {{ project.name }}."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="{{ module_name }}")
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {{ project.version }}",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    _ = args
+    print("Hello from {{ project.name }}!")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pygenkit/templates/python-cli/tests/test_cli.py.jinja

@@ -0,0 +1,21 @@
+"""Tests for the CLI."""
+
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "src"
+if str(SRC) not in sys.path:
+    sys.path.insert(0, str(SRC))
+
+from {{ module_name }}.cli import main
+
+
+def test_help_returns_zero() -> None:
+    exit_code = main(["--help"])
+    assert exit_code == 0
+
+
+def test_version_output() -> None:
+    exit_code = main(["--version"])
+    assert exit_code == 0

pygenkit/utils/__init__.py

@@ -0,0 +1,4 @@
+from pygenkit.utils.files import FileUtils
+from pygenkit.utils.filters import TemplateFilters
+
+__all__ = ["FileUtils", "TemplateFilters"]

pygenkit/utils/files.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+
+class FileUtils:
+    @staticmethod
+    def ensure_dir(path: str | Path) -> Path:
+        p = Path(path)
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @staticmethod
+    def write_file(path: str | Path, content: str) -> Path:
+        p = Path(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(content, encoding="utf-8")
+        return p
+
+    @staticmethod
+    def remove_tree(path: str | Path) -> None:
+        p = Path(path)
+        if p.exists():
+            shutil.rmtree(p)
+
+    @staticmethod
+    def copy_tree(src: str | Path, dst: str | Path) -> None:
+        shutil.copytree(Path(src), Path(dst), dirs_exist_ok=True)

pygenkit/utils/filters.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import re
+
+
+class TemplateFilters:
+    @staticmethod
+    def snake_case(value: str) -> str:
+        s = re.sub(r"[-\s]+", "_", value)
+        return s.lower().strip("_")
+
+    @staticmethod
+    def kebab_case(value: str) -> str:
+        s = re.sub(r"[_\s]+", "-", value)
+        return s.lower().strip("-")
+
+    @staticmethod
+    def pascal_case(value: str) -> str:
+        return "".join(word.capitalize() for word in re.split(r"[-_\\s]", value))
+
+    @staticmethod
+    def camel_case(value: str) -> str:
+        s = TemplateFilters.pascal_case(value)
+        return s[0].lower() + s[1:] if s else s
+
+    @staticmethod
+    def module_name(value: str) -> str:
+        return TemplateFilters.snake_case(value)
+
+    @staticmethod
+    def capitalise(value: str) -> str:
+        return value.capitalize()
+
+    @staticmethod
+    def get_filters() -> dict[str, object]:
+        return {
+            "snake_case": TemplateFilters.snake_case,
+            "kebab_case": TemplateFilters.kebab_case,
+            "pascal_case": TemplateFilters.pascal_case,
+            "camel_case": TemplateFilters.camel_case,
+            "module_name": TemplateFilters.module_name,
+            "capitalise": TemplateFilters.capitalise,
+        }

pygenkit/validators/__init__.py

@@ -0,0 +1,3 @@
+from pygenkit.validators.api import has_errors, validate_project
+
+__all__ = ["validate_project", "has_errors"]

pygenkit/validators/api.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pygenkit.validators import security as security_validator
+from pygenkit.validators import version as version_validator
+from pygenkit.validators import workflow as workflow_validator
+
+
+def validate_project(root: str | Path = ".") -> list[dict[str, object]]:
+    results: list[dict[str, object]] = []
+
+    _add_results(results, "version", version_validator.validate_version_consistency(root))
+    _add_results(results, "workflow", workflow_validator.validate_workflows(root))
+    _add_results(results, "security", security_validator.validate_security(root))
+
+    return results
+
+
+def _add_results(
+    results: list[dict[str, object]],
+    category: str,
+    issues: list[str],
+) -> None:
+    for issue in issues:
+        results.append({"category": category, "message": issue})
+
+
+def has_errors(results: list[dict[str, object]]) -> bool:
+    return len(results) > 0

pygenkit/validators/security.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def validate_security(root: str | Path = ".") -> list[str]:
+    issues: list[str] = []
+    wf_dir = Path(root) / ".github" / "workflows"
+
+    if not wf_dir.is_dir():
+        return []
+
+    for yml_file in sorted(wf_dir.glob("*.yml")):
+        issues.extend(_check_workflow_security(yml_file))
+
+    secrets_file = Path(root) / ".github" / "secrets"
+    if secrets_file.exists():
+        issues.append(".github/secrets file should not be versioned")
+
+    return issues
+
+
+def _check_workflow_security(path: Path) -> list[str]:
+    issues: list[str] = []
+    name = path.name
+
+    try:
+        raw = path.read_text(encoding="utf-8")
+        data = yaml.safe_load(raw)
+    except yaml.YAMLError:
+        return issues
+
+    if not isinstance(data, dict):
+        return issues
+
+    jobs = data.get("jobs", {})
+    if not isinstance(jobs, dict):
+        return issues
+
+    for job_id, job in jobs.items():
+        if not isinstance(job, dict):
+            continue
+        issues.extend(_check_job_permissions(name, job_id, job))
+        issues.extend(_check_job_secrets(name, job_id, job))
+        issues.extend(_check_job_environment(name, job_id, job))
+
+    return issues
+
+
+def _check_job_permissions(wf_name: str, job_id: str, job: dict[str, Any]) -> list[str]:
+    issues: list[str] = []
+    prefix = f"{wf_name}/{job_id}"
+
+    if "permissions" not in job:
+        issues.append(
+            f"{prefix}: no explicit permissions block"
+        )
+
+    steps = job.get("steps", [])
+    if isinstance(steps, list):
+        for i, step in enumerate(steps):
+            if isinstance(step, dict) and step.get("uses", "").startswith("actions/checkout"):
+                token = step.get("with", {}).get("token", "")
+                if token and "secrets." not in str(token):
+                    issues.append(f"{prefix}/step{i}: hardcoded token in checkout action")
+
+    return issues
+
+
+def _check_job_secrets(wf_name: str, job_id: str, job: dict[str, Any]) -> list[str]:
+    issues: list[str] = []
+    raw_yml = yaml.dump(job)
+
+    hardcoded_patterns = ["password=", "api_key=", "secret=", "token="]
+    for pattern in hardcoded_patterns:
+        if pattern in raw_yml.lower():
+            prefix = f"{wf_name}/{job_id}"
+            issues.append(f"{prefix}: possible hardcoded secret ('{pattern}') in workflow")
+
+    return issues
+
+
+def _check_job_environment(wf_name: str, job_id: str, job: dict[str, Any]) -> list[str]:
+    issues: list[str] = []
+    env = job.get("environment")
+
+    if env and isinstance(env, str) and env == "pypi":
+        return issues
+
+    steps = job.get("steps", [])
+    if isinstance(steps, list):
+        for step in steps:
+            if isinstance(step, dict):
+                uses = step.get("uses", "")
+                if ("pypi-publish" in uses or "pypa/gh-action-pypi-publish" in uses) and not env:
+                        prefix = f"{wf_name}/{job_id}"
+                        issues.append(f"{prefix}: PyPI publish should use a protected environment")
+
+    return issues

pygenkit/validators/version.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pygenkit.inspector import debian as debian_inspector
+from pygenkit.inspector import detect as detect_inspector
+from pygenkit.inspector import git as git_inspector
+from pygenkit.inspector import pyproject as pyproject_inspector
+
+
+def validate_version_consistency(root: str | Path = ".") -> list[str]:
+    issues: list[str] = []
+    root = Path(root).resolve()
+
+    pyproject_ver = _get_pyproject_version(root)
+    init_ver = _get_init_version(root)
+    changelog_ver = _get_changelog_version(root)
+    latest_tag = _get_latest_tag(root)
+
+    if pyproject_ver and init_ver and pyproject_ver != init_ver:
+        issues.append(
+            f"pyproject.toml: {pyproject_ver} != src/.../__init__.py: {init_ver}"
+        )
+
+    if pyproject_ver and changelog_ver and pyproject_ver != changelog_ver:
+        issues.append(
+            f"pyproject.toml: {pyproject_ver} != debian/changelog: {changelog_ver}"
+        )
+
+    if latest_tag and pyproject_ver and latest_tag != pyproject_ver:
+        issues.append(
+            f"latest git tag v{latest_tag} != pyproject.toml: {pyproject_ver}"
+        )
+
+    return issues
+
+
+def _get_pyproject_version(root: Path) -> str | None:
+    try:
+        data = pyproject_inspector.read_pyproject(root)
+        return pyproject_inspector.detect_project_version(data)
+    except (FileNotFoundError, Exception):
+        return None
+
+
+def _get_init_version(root: Path) -> str | None:
+    try:
+        data = pyproject_inspector.read_pyproject(root)
+        name = pyproject_inspector.detect_project_name(data)
+        if name:
+            module = detect_inspector.detect_module(root, name)
+        else:
+            module = detect_inspector.detect_module(root)
+        if module:
+            return detect_inspector.detect_version_in_init(root, module)
+    except (FileNotFoundError, Exception):
+        pass
+    return None
+
+
+def _get_changelog_version(root: Path) -> str | None:
+    try:
+        info = debian_inspector.inspect_debian(root)
+        return info.version_in_changelog
+    except Exception:
+        return None
+
+
+def _get_latest_tag(root: Path) -> str | None:
+    try:
+        tags = git_inspector.detect_git_tags(root)
+        for t in tags:
+            if t.startswith("v"):
+                return t.lstrip("v")
+        return tags[0] if tags else None
+    except Exception:
+        return None

pygenkit/validators/workflow.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def validate_workflows(root: str | Path = ".") -> list[str]:
+    issues: list[str] = []
+    wf_dir = Path(root) / ".github" / "workflows"
+
+    if not wf_dir.is_dir():
+        return []
+
+    for yml_file in sorted(wf_dir.glob("*.yml")):
+        issues.extend(_validate_single_workflow(yml_file))
+
+    return issues
+
+
+def _validate_single_workflow(path: Path) -> list[str]:
+    issues: list[str] = []
+    name = path.name
+
+    try:
+        raw = path.read_text(encoding="utf-8")
+        data = yaml.safe_load(raw)
+    except yaml.YAMLError as exc:
+        issues.append(f"{name}: invalid YAML — {exc}")
+        return issues
+
+    if not isinstance(data, dict):
+        issues.append(f"{name}: not a mapping")
+        return issues
+
+    if "name" not in data:
+        issues.append(f"{name}: missing 'name' field")
+
+    triggers = _collect_triggers(data)
+    if not triggers:
+        issues.append(f"{name}: no triggers defined (on:)")
+
+    jobs = data.get("jobs", {})
+    if not jobs:
+        issues.append(f"{name}: no jobs defined")
+        return issues
+
+    for job_id, job in jobs.items():
+        if not isinstance(job, dict):
+            continue
+        issues.extend(_validate_job(name, job_id, job))
+
+    return issues
+
+
+def _collect_triggers(data: dict[str, Any]) -> list[str]:
+    triggers: list[str] = []
+    on = data.get("on", {})
+    if isinstance(on, str):
+        triggers.append(on)
+    elif isinstance(on, dict):
+        triggers.extend(on.keys())
+    elif isinstance(on, list):
+        triggers.extend(str(t) for t in on)
+    return triggers
+
+
+def _validate_job(wf_name: str, job_id: str, job: dict[str, Any]) -> list[str]:
+    issues: list[str] = []
+    prefix = f"{wf_name}/{job_id}"
+
+    if "runs-on" not in job:
+        issues.append(f"{prefix}: missing runs-on")
+
+    steps = job.get("steps", [])
+    if not steps:
+        issues.append(f"{prefix}: no steps")
+        return issues
+
+    for i, step in enumerate(steps):
+        if not isinstance(step, dict):
+            continue
+        if "uses" in step:
+            issues.extend(_check_action_version(prefix, i, step["uses"]))
+        if "run" in step:
+            issues.extend(_check_shell_injection(prefix, i, step["run"]))
+
+    return issues
+
+
+def _check_action_version(prefix: str, step_idx: int, uses: str) -> list[str]:
+    issues: list[str] = []
+    if not isinstance(uses, str):
+        return issues
+
+    if "@" not in uses:
+        issues.append(f"{prefix}/step{step_idx}: action '{uses}' has no version pin")
+        return issues
+
+    action, version = uses.rsplit("@", 1)
+    known_outdated = {
+        "actions/checkout@v4": "use actions/checkout@v6 or newer",
+        "actions/checkout@v3": "use actions/checkout@v6 or newer",
+        "actions/checkout@v2": "use actions/checkout@v6 or newer",
+        "actions/setup-python@v5": "use actions/setup-python@v6 or newer",
+        "actions/setup-python@v4": "use actions/setup-python@v6 or newer",
+        "actions/setup-python@v3": "use actions/setup-python@v6 or newer",
+        "actions/upload-artifact@v3": "use actions/upload-artifact@v4 or newer",
+        "actions/download-artifact@v3": "use actions/download-artifact@v4 or newer",
+    }
+
+    full = f"{action}@{version}"
+    if full in known_outdated:
+        issues.append(f"{prefix}/step{step_idx}: {full} is outdated — {known_outdated[full]}")
+
+    if not _is_sha_pin(version):
+        issues.append(
+            f"{prefix}/step{step_idx}: '{full}' uses tag '{version}' instead of SHA pin"
+        )
+
+    return issues
+
+
+def _is_sha_pin(version: str) -> bool:
+    return len(version) == 40 and all(c in "0123456789abcdef" for c in version)
+
+
+def _check_shell_injection(prefix: str, step_idx: int, run: str) -> list[str]:
+    issues: list[str] = []
+    if not isinstance(run, str):
+        return issues
+
+    dangerous = ["${{ github.event.issue.title }}", "${{ github.event.pull_request.title }}"]
+    for pattern in dangerous:
+        if pattern in run:
+            issues.append(
+                f"{prefix}/step{step_idx}: possible script injection via {pattern}"
+            )
+
+    return issues