repoguard-tool 0.1.0__py3-none-any.whl

repoguard/__init__.py

@@ -0,0 +1,11 @@
+"""RepoGuard - Open-Source Repository Health Analyzer.
+
+Analyze. Detect. Improve.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__app_name__ = "repoguard"
+
+__all__ = ["__app_name__", "__version__"]

repoguard/analyzers/__init__.py

@@ -0,0 +1,28 @@
+"""Built-in analyzers for RepoGuard."""
+
+from __future__ import annotations
+
+from repoguard.analyzers.cicd import CiCdAnalyzer
+from repoguard.analyzers.code_quality import CodeQualityAnalyzer
+from repoguard.analyzers.dependencies import DependencyAnalyzer
+from repoguard.analyzers.documentation import DocumentationAnalyzer
+from repoguard.analyzers.security import SecurityAnalyzer
+from repoguard.analyzers.testing import TestingAnalyzer
+from repoguard.core.registry import registry
+
+# Automatically register built-in analyzers
+registry.register(DocumentationAnalyzer, overwrite=True)
+registry.register(DependencyAnalyzer, overwrite=True)
+registry.register(TestingAnalyzer, overwrite=True)
+registry.register(SecurityAnalyzer, overwrite=True)
+registry.register(CodeQualityAnalyzer, overwrite=True)
+registry.register(CiCdAnalyzer, overwrite=True)
+
+__all__ = [
+    "CiCdAnalyzer",
+    "CodeQualityAnalyzer",
+    "DependencyAnalyzer",
+    "DocumentationAnalyzer",
+    "SecurityAnalyzer",
+    "TestingAnalyzer",
+]

repoguard/analyzers/cicd.py

@@ -0,0 +1,154 @@
+"""CI/CD analyzer inspecting GitHub workflows, triggers, permissions, and action pinning."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import yaml
+
+from repoguard.core.context import ScanContext
+from repoguard.core.findings import Category, Confidence, Finding, Severity
+from repoguard.plugins.base import BaseAnalyzer
+
+
+class CiCdAnalyzer(BaseAnalyzer):
+    """Analyzes GitHub Actions workflows for best practices, permissions, and security."""
+
+    name = "cicd"
+    description = "Inspects GitHub Actions workflows for permissions, branch pinning, and CI health"
+    category = Category.CICD
+    version = "1.0.0"
+
+    MUTABLE_BRANCHES = {"main", "master", "dev", "develop", "latest"}
+
+    def analyze(self, context: ScanContext) -> list[Finding]:
+        findings: list[Finding] = []
+
+        workflow_files = [
+            f
+            for f in context.files
+            if context.get_relative_path(f).startswith(".github/workflows/")
+            and f.suffix in [".yml", ".yaml"]
+        ]
+
+        # 1. Detect missing workflows
+        if not workflow_files:
+            findings.append(
+                Finding(
+                    id="CICD001",
+                    analyzer=self.name,
+                    category=self.category,
+                    severity=Severity.MEDIUM,
+                    description="No GitHub Actions workflows found in .github/workflows/.",
+                    remediation="Add a CI workflow to automatically build, test, and validate code changes.",
+                    confidence=Confidence.HIGH,
+                )
+            )
+            return findings
+
+        # 2. Inspect each workflow file
+        for wf_file in workflow_files:
+            rel_path = context.get_relative_path(wf_file)
+            content = context.read_file(wf_file)
+            if not content:
+                continue
+
+            # Parse YAML safely
+            try:
+                data = yaml.safe_load(content) or {}
+            except yaml.YAMLError as exc:
+                findings.append(
+                    Finding(
+                        id="CICD005",
+                        analyzer=self.name,
+                        category=self.category,
+                        severity=Severity.HIGH,
+                        description=f"Malformed YAML in workflow '{rel_path}': {exc}",
+                        file_path=rel_path,
+                        remediation="Fix YAML syntax error in workflow file.",
+                        confidence=Confidence.HIGH,
+                    )
+                )
+                continue
+
+            self._check_workflow_permissions(data, rel_path, findings)
+            self._check_action_pinning(content, rel_path, findings)
+
+        return findings
+
+    def _check_workflow_permissions(
+        self,
+        data: dict[str, Any],
+        rel_path: str,
+        findings: list[Finding],
+    ) -> None:
+        """Inspect workflow permissions for principle of least privilege."""
+        permissions = data.get("permissions")
+
+        if permissions == "write-all":
+            findings.append(
+                Finding(
+                    id="CICD002",
+                    analyzer=self.name,
+                    category=self.category,
+                    severity=Severity.HIGH,
+                    description="Workflow configures 'permissions: write-all', granting broad write access to GITHUB_TOKEN.",
+                    file_path=rel_path,
+                    remediation="Define fine-grained, read-only default permissions (e.g. `permissions: contents: read`).",
+                    confidence=Confidence.HIGH,
+                )
+            )
+        elif permissions is None:
+            # Check if jobs define permissions
+            jobs = data.get("jobs", {})
+            has_job_permissions = any(
+                "permissions" in job for job in jobs.values() if isinstance(job, dict)
+            )
+            if not has_job_permissions:
+                findings.append(
+                    Finding(
+                        id="CICD003",
+                        analyzer=self.name,
+                        category=self.category,
+                        severity=Severity.LOW,
+                        description="Workflow lacks explicit least-privilege 'permissions' configuration.",
+                        file_path=rel_path,
+                        remediation="Explicitly specify top-level 'permissions: contents: read' to follow the principle of least privilege.",
+                        confidence=Confidence.MEDIUM,
+                    )
+                )
+
+    def _check_action_pinning(
+        self,
+        content: str,
+        rel_path: str,
+        findings: list[Finding],
+    ) -> None:
+        """Inspect action references for mutable branch tags."""
+        lines = content.splitlines()
+        for idx, line in enumerate(lines, start=1):
+            match = re.search(r"uses:\s*([a-zA-Z0-9_\-\./]+)@([a-zA-Z0-9_\-\.]+)", line)
+            if match:
+                action_name = match.group(1)
+                ref = match.group(2)
+
+                # Skip local actions (./) or docker actions
+                if action_name.startswith((".", "docker://")):
+                    continue
+
+                if ref.lower() in self.MUTABLE_BRANCHES:
+                    findings.append(
+                        Finding(
+                            id="CICD004",
+                            analyzer=self.name,
+                            category=self.category,
+                            severity=Severity.MEDIUM,
+                            description=f"Action '{action_name}' is pinned to mutable branch '@{ref}'.",
+                            file_path=rel_path,
+                            line_number=idx,
+                            evidence=line.strip(),
+                            remediation="Pin third-party GitHub Actions to a full commit SHA or tagged release (e.g. @v4.0.0).",
+                            confidence=Confidence.HIGH,
+                        )
+                    )

repoguard/analyzers/code_quality.py

@@ -0,0 +1,198 @@
+"""Code quality analyzer inspecting file sizes, function complexity, and maintainability."""
+
+from __future__ import annotations
+
+import ast
+
+from repoguard.core.context import ScanContext
+from repoguard.core.findings import Category, Confidence, Finding, Severity
+from repoguard.plugins.base import BaseAnalyzer
+
+
+class CyclomaticComplexityVisitor(ast.NodeVisitor):
+    """Calculates McCabe cyclomatic complexity for an AST function node."""
+
+    def __init__(self) -> None:
+        self.complexity = 1
+
+    def visit_If(self, node: ast.If) -> None:
+        self.complexity += 1
+        self.generic_visit(node)
+
+    def visit_For(self, node: ast.For) -> None:
+        self.complexity += 1
+        self.generic_visit(node)
+
+    def visit_AsyncFor(self, node: ast.AsyncFor) -> None:
+        self.complexity += 1
+        self.generic_visit(node)
+
+    def visit_While(self, node: ast.While) -> None:
+        self.complexity += 1
+        self.generic_visit(node)
+
+    def visit_ExceptHandler(self, node: ast.ExceptHandler) -> None:
+        self.complexity += 1
+        self.generic_visit(node)
+
+    def visit_With(self, node: ast.With) -> None:
+        self.complexity += 1
+        self.generic_visit(node)
+
+    def visit_AsyncWith(self, node: ast.AsyncWith) -> None:
+        self.complexity += 1
+        self.generic_visit(node)
+
+    def visit_Assert(self, node: ast.Assert) -> None:
+        self.complexity += 1
+        self.generic_visit(node)
+
+    def visit_BoolOp(self, node: ast.BoolOp) -> None:
+        self.complexity += len(node.values) - 1
+        self.generic_visit(node)
+
+
+class CodeQualityAnalyzer(BaseAnalyzer):
+    """Inspects code maintainability: large files, complex functions, and poor patterns."""
+
+    name = "code_quality"
+    description = (
+        "Checks for oversized files, high cyclomatic complexity, and maintainability antipatterns"
+    )
+    category = Category.CODE_QUALITY
+    version = "1.0.0"
+
+    def analyze(self, context: ScanContext) -> list[Finding]:
+        findings: list[Finding] = []
+        limits = context.config.code_quality
+
+        python_files = context.list_files(extension=".py")
+        for file_path in python_files:
+            rel_path = context.get_relative_path(file_path)
+            content = context.read_file(file_path)
+            if content is None:
+                continue
+
+            lines = content.splitlines()
+
+            # 1. Check file size
+            if len(lines) > limits.max_file_lines:
+                findings.append(
+                    Finding(
+                        id="QUAL001",
+                        analyzer=self.name,
+                        category=self.category,
+                        severity=Severity.LOW,
+                        description=f"File exceeds maximum recommended length ({len(lines)} > {limits.max_file_lines} lines).",
+                        file_path=rel_path,
+                        remediation="Decompose this module into smaller, focused single-responsibility files.",
+                        confidence=Confidence.HIGH,
+                        metadata={"lines": len(lines), "max": limits.max_file_lines},
+                    )
+                )
+
+            # 2. Parse Python AST for modular quality checks
+            try:
+                tree = ast.parse(content, filename=rel_path)
+            except SyntaxError:
+                # Syntax errors will be reported or skipped safely
+                continue
+
+            self._analyze_python_ast(tree, rel_path, limits, findings)
+
+        return findings
+
+    def _analyze_python_ast(
+        self,
+        tree: ast.AST,
+        rel_path: str,
+        limits,
+        findings: list[Finding],
+    ) -> None:
+        for node in ast.walk(tree):
+            # Check wildcard imports
+            if isinstance(node, ast.ImportFrom):
+                for alias in node.names:
+                    if alias.name == "*":
+                        findings.append(
+                            Finding(
+                                id="QUAL002",
+                                analyzer=self.name,
+                                category=self.category,
+                                severity=Severity.LOW,
+                                description=f"Wildcard import 'from {node.module} import *' pollutes namespace.",
+                                file_path=rel_path,
+                                line_number=node.lineno,
+                                remediation="Explicitly import required functions and classes instead of '*'.",
+                                confidence=Confidence.HIGH,
+                            )
+                        )
+
+            # Check function definitions
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                func_name = node.name
+                func_line = node.lineno
+                func_length = (node.end_lineno - node.lineno + 1) if node.end_lineno else 1
+
+                # Check function length
+                if func_length > limits.max_function_lines:
+                    findings.append(
+                        Finding(
+                            id="QUAL003",
+                            analyzer=self.name,
+                            category=self.category,
+                            severity=Severity.LOW,
+                            description=f"Function '{func_name}' is too long ({func_length} > {limits.max_function_lines} lines).",
+                            file_path=rel_path,
+                            line_number=func_line,
+                            remediation="Refactor the function into smaller helper functions.",
+                            confidence=Confidence.HIGH,
+                            metadata={"length": func_length, "max": limits.max_function_lines},
+                        )
+                    )
+
+                # Check argument count
+                total_args = (
+                    len(node.args.args) + len(node.args.posonlyargs) + len(node.args.kwonlyargs)
+                )
+                if total_args > limits.max_function_arguments:
+                    findings.append(
+                        Finding(
+                            id="QUAL004",
+                            analyzer=self.name,
+                            category=self.category,
+                            severity=Severity.LOW,
+                            description=f"Function '{func_name}' has excessive parameters ({total_args} > {limits.max_function_arguments}).",
+                            file_path=rel_path,
+                            line_number=func_line,
+                            remediation="Group related parameters into a configuration model, dataclass, or object.",
+                            confidence=Confidence.MEDIUM,
+                            metadata={"args": total_args, "max": limits.max_function_arguments},
+                        )
+                    )
+
+                # Calculate cyclomatic complexity
+                visitor = CyclomaticComplexityVisitor()
+                # Visit function body directly
+                for stmt in node.body:
+                    visitor.visit(stmt)
+                complexity = visitor.complexity
+
+                if complexity > limits.max_cyclomatic_complexity:
+                    findings.append(
+                        Finding(
+                            id="QUAL005",
+                            analyzer=self.name,
+                            category=self.category,
+                            severity=Severity.MEDIUM,
+                            description=f"Function '{func_name}' has high cyclomatic complexity ({complexity} > {limits.max_cyclomatic_complexity}).",
+                            file_path=rel_path,
+                            line_number=func_line,
+                            remediation="Simplify conditionals and extract branching logic into separate functions.",
+                            confidence=Confidence.HIGH,
+                            metadata={
+                                "complexity": complexity,
+                                "max": limits.max_cyclomatic_complexity,
+                            },
+                        )
+                    )

repoguard/analyzers/dependencies.py

@@ -0,0 +1,286 @@
+"""Dependency analyzer checking pinned versions, outdated packages, and OSV vulnerabilities."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+
+import requests
+
+from repoguard.core.context import ScanContext
+from repoguard.core.findings import Category, Confidence, Finding, Severity
+from repoguard.plugins.base import BaseAnalyzer
+
+OSV_API_URL = "https://api.osv.dev/v1/query"
+PYPI_API_URL = "https://pypi.org/pypi/{package}/json"
+NPM_REGISTRY_URL = "https://registry.npmjs.org/{package}"
+
+
+@dataclass
+class ParsedDependency:
+    name: str
+    specifier: str
+    pinned_version: str | None
+    ecosystem: str  # "PyPI" or "npm"
+    file_path: str
+    line_number: int | None = None
+
+
+class DependencyAnalyzer(BaseAnalyzer):
+    """Analyzes repository dependencies for security vulnerabilities and update status."""
+
+    name = "dependencies"
+    description = "Inspects dependencies for unpinned versions, outdated releases, and CVEs via OSV"
+    category = Category.DEPENDENCIES
+    version = "1.0.0"
+
+    def __init__(self, config: dict[str, Any] | None = None) -> None:
+        super().__init__(config)
+        self._vuln_cache: dict[str, list[dict[str, Any]]] = {}
+        self._latest_version_cache: dict[str, str | None] = {}
+
+    def analyze(self, context: ScanContext) -> list[Finding]:
+        findings: list[Finding] = []
+        dependencies = self._discover_dependencies(context)
+
+        if not dependencies and not self._has_manifests(context):
+            # No dependencies found and no manifests
+            return findings
+
+        for dep in dependencies:
+            # 1. Check for unpinned dependencies
+            if not dep.pinned_version:
+                findings.append(
+                    Finding(
+                        id="DEP001",
+                        analyzer=self.name,
+                        category=self.category,
+                        severity=Severity.LOW,
+                        description=f"Dependency '{dep.name}' is unpinned in {dep.file_path}",
+                        file_path=dep.file_path,
+                        line_number=dep.line_number,
+                        evidence=f"Specification: {dep.name}{dep.specifier}",
+                        remediation=f"Pin '{dep.name}' to a tested, exact version (e.g. {dep.name}==x.y.z)",
+                        confidence=Confidence.HIGH,
+                    )
+                )
+
+            # 2. Check network-dependent lookups if enabled
+            if context.network_enabled and dep.pinned_version:
+                timeout = context.config.network.timeout_seconds
+
+                # A. Known vulnerabilities via OSV API
+                vulns = self._check_osv_vulnerabilities(dep, timeout=timeout)
+                for vuln in vulns:
+                    vuln_id = vuln.get("id", "UNKNOWN-VULN")
+                    summary = (
+                        vuln.get("summary") or vuln.get("details") or "Known security vulnerability"
+                    )
+                    # Truncate summary for neatness
+                    short_summary = (summary[:150] + "...") if len(summary) > 150 else summary
+
+                    findings.append(
+                        Finding(
+                            id="DEP002",
+                            analyzer=self.name,
+                            category=self.category,
+                            severity=Severity.HIGH,
+                            description=f"Vulnerability {vuln_id} detected in {dep.name}@{dep.pinned_version}: {short_summary}",
+                            file_path=dep.file_path,
+                            line_number=dep.line_number,
+                            evidence=f"Package: {dep.name}=={dep.pinned_version} (Advisory: {vuln_id})",
+                            remediation=f"Upgrade '{dep.name}' to a patched version resolving advisory {vuln_id}",
+                            confidence=Confidence.HIGH,
+                            metadata={"advisory_id": vuln_id, "ecosystem": dep.ecosystem},
+                        )
+                    )
+
+                # B. Outdated dependency check via package registries
+                latest = self._fetch_latest_version(dep, timeout=timeout)
+                if latest and latest != dep.pinned_version:
+                    findings.append(
+                        Finding(
+                            id="DEP003",
+                            analyzer=self.name,
+                            category=self.category,
+                            severity=Severity.LOW,
+                            description=f"Dependency '{dep.name}' is outdated ({dep.pinned_version} -> {latest})",
+                            file_path=dep.file_path,
+                            line_number=dep.line_number,
+                            evidence=f"Current: {dep.pinned_version}, Latest: {latest}",
+                            remediation=f"Consider testing and updating '{dep.name}' to release {latest}",
+                            confidence=Confidence.MEDIUM,
+                            metadata={"latest_version": latest},
+                        )
+                    )
+
+        return findings
+
+    def _has_manifests(self, context: ScanContext) -> bool:
+        return any(
+            context.has_file(f)
+            for f in ["requirements.txt", "pyproject.toml", "Pipfile", "package.json"]
+        )
+
+    def _discover_dependencies(self, context: ScanContext) -> list[ParsedDependency]:
+        """Parse dependencies from requirements.txt, pyproject.toml, and package.json."""
+        deps: list[ParsedDependency] = []
+
+        # Python: requirements.txt
+        for req_file in context.find_files_by_name(["requirements.txt", "requirements-dev.txt"]):
+            rel_path = context.get_relative_path(req_file)
+            lines = context.read_file_lines(req_file) or []
+            for idx, line in enumerate(lines, start=1):
+                clean = line.strip()
+                if not clean or clean.startswith(("#", "-", "--")):
+                    continue
+                match = re.match(r"^([a-zA-Z0-9_\-\.]+)\s*([=><~^!]+.*)?$", clean)
+                if match:
+                    name = match.group(1).lower()
+                    spec = match.group(2) or ""
+                    pinned = None
+                    pin_match = re.search(r"==\s*([0-9a-zA-Z\.\-]+)", spec)
+                    if pin_match:
+                        pinned = pin_match.group(1)
+                    deps.append(
+                        ParsedDependency(
+                            name=name,
+                            specifier=spec,
+                            pinned_version=pinned,
+                            ecosystem="PyPI",
+                            file_path=rel_path,
+                            line_number=idx,
+                        )
+                    )
+
+        # Python: pyproject.toml
+        pyproject_files = context.find_files_by_name(["pyproject.toml"])
+        for pyproject in pyproject_files:
+            rel_path = context.get_relative_path(pyproject)
+            content = context.read_file(pyproject)
+            if content:
+                try:
+                    import tomllib
+
+                    data = tomllib.loads(content)
+                    raw_deps = data.get("project", {}).get("dependencies", [])
+                    for item in raw_deps:
+                        if isinstance(item, str):
+                            match = re.match(
+                                r"^([a-zA-Z0-9_\-\.]+)\s*([=><~^!]+.*)?$", item.strip()
+                            )
+                            if match:
+                                name = match.group(1).lower()
+                                spec = match.group(2) or ""
+                                pinned = None
+                                pin_match = re.search(r"==\s*([0-9a-zA-Z\.\-]+)", spec)
+                                if pin_match:
+                                    pinned = pin_match.group(1)
+                                deps.append(
+                                    ParsedDependency(
+                                        name=name,
+                                        specifier=spec,
+                                        pinned_version=pinned,
+                                        ecosystem="PyPI",
+                                        file_path=rel_path,
+                                    )
+                                )
+                except Exception:
+                    pass
+
+        # JavaScript/Node: package.json
+        pkg_json_files = context.find_files_by_name(["package.json"])
+        for pkg_file in pkg_json_files:
+            rel_path = context.get_relative_path(pkg_file)
+            content = context.read_file(pkg_file)
+            if content:
+                try:
+                    data = json.loads(content)
+                    all_deps: dict[str, str] = {}
+                    all_deps.update(data.get("dependencies", {}))
+                    all_deps.update(data.get("devDependencies", {}))
+
+                    for name, spec in all_deps.items():
+                        clean_spec = str(spec).strip()
+                        # Strict pin e.g. "1.2.3" without ^ or ~
+                        pinned = None
+                        if re.match(r"^[0-9]+\.[0-9]+\.[0-9]+[0-9a-zA-Z\.\-]*$", clean_spec):
+                            pinned = clean_spec
+                        deps.append(
+                            ParsedDependency(
+                                name=name,
+                                specifier=clean_spec,
+                                pinned_version=pinned,
+                                ecosystem="npm",
+                                file_path=rel_path,
+                            )
+                        )
+                except Exception:
+                    pass
+
+        return deps
+
+    def _check_osv_vulnerabilities(
+        self,
+        dep: ParsedDependency,
+        timeout: float = 10.0,
+    ) -> list[dict[str, Any]]:
+        """Query the open-source OSV vulnerability database for known CVEs/GHSAs."""
+        if not dep.pinned_version:
+            return []
+
+        cache_key = f"{dep.ecosystem}:{dep.name}:{dep.pinned_version}"
+        if cache_key in self._vuln_cache:
+            return self._vuln_cache[cache_key]
+
+        payload = {
+            "package": {"name": dep.name, "ecosystem": dep.ecosystem},
+            "version": dep.pinned_version,
+        }
+
+        try:
+            resp = requests.post(OSV_API_URL, json=payload, timeout=timeout)
+            if resp.status_code == 200:
+                data = resp.json()
+                vulns = data.get("vulns", [])
+                self._vuln_cache[cache_key] = vulns
+                return vulns
+        except requests.RequestException:
+            # Network failure or API unavailable handled gracefully
+            pass
+
+        self._vuln_cache[cache_key] = []
+        return []
+
+    def _fetch_latest_version(
+        self,
+        dep: ParsedDependency,
+        timeout: float = 10.0,
+    ) -> str | None:
+        """Fetch latest version from PyPI or npm registry."""
+        cache_key = f"{dep.ecosystem}:{dep.name}"
+        if cache_key in self._latest_version_cache:
+            return self._latest_version_cache[cache_key]
+
+        try:
+            if dep.ecosystem == "PyPI":
+                url = PYPI_API_URL.format(package=dep.name)
+                resp = requests.get(url, timeout=timeout)
+                if resp.status_code == 200:
+                    latest = resp.json().get("info", {}).get("version")
+                    self._latest_version_cache[cache_key] = latest
+                    return latest
+            elif dep.ecosystem == "npm":
+                url = NPM_REGISTRY_URL.format(package=dep.name)
+                resp = requests.get(url, timeout=timeout)
+                if resp.status_code == 200:
+                    latest = resp.json().get("dist-tags", {}).get("latest")
+                    self._latest_version_cache[cache_key] = latest
+                    return latest
+        except requests.RequestException:
+            pass
+
+        self._latest_version_cache[cache_key] = None
+        return None