Skip to content

notque/vexjoy-agent / skills/programming/programming

programming

Flagged

Language-specific patterns and tooling: Go, Kotlin, PHP, Swift, TypeScript.

FileKindSize
SKILL.mdskill md11.6 KB
references/go/code-review.mdmarkdown12.0 KB
references/go/code-review/common-review-comments.mdmarkdown6.6 KB
references/go/concurrency.mdmarkdown11.5 KB
references/go/concurrency/concurrency-patterns.mdmarkdown5.7 KB
references/go/error-handling.mdmarkdown10.8 KB
references/go/error-handling/patterns.mdmarkdown4.2 KB
references/go/google-style-guide/SHA256SUMSother313 B
references/go/google-style-guide/UPSTREAM_REVISIONother41 B
references/go/google-style-guide/best-practices/part-01.mdmarkdown10.0 KB
references/go/google-style-guide/best-practices/part-02.mdmarkdown15.0 KB
references/go/google-style-guide/best-practices/part-03.mdmarkdown14.1 KB
references/go/google-style-guide/best-practices/part-04.mdmarkdown13.5 KB
references/go/google-style-guide/best-practices/part-05.mdmarkdown10.5 KB
references/go/google-style-guide/best-practices/part-06.mdmarkdown14.4 KB
references/go/google-style-guide/best-practices/part-07.mdmarkdown16.1 KB
references/go/google-style-guide/best-practices/part-08.mdmarkdown11.4 KB
references/go/google-style-guide/best-practices/part-09.mdmarkdown13.7 KB
references/go/google-style-guide/best-practices/part-10.mdmarkdown16.9 KB
references/go/google-style-guide/decisions/part-01.mdmarkdown15.0 KB
references/go/google-style-guide/decisions/part-02.mdmarkdown12.5 KB
references/go/google-style-guide/decisions/part-03.mdmarkdown11.5 KB
references/go/google-style-guide/decisions/part-04.mdmarkdown8.4 KB
references/go/google-style-guide/decisions/part-05.mdmarkdown9.8 KB
references/go/google-style-guide/decisions/part-06.mdmarkdown14.7 KB
references/go/google-style-guide/decisions/part-07.mdmarkdown13.3 KB
references/go/google-style-guide/decisions/part-08.mdmarkdown14.3 KB
references/go/google-style-guide/decisions/part-09.mdmarkdown15.3 KB
references/go/google-style-guide/decisions/part-10.mdmarkdown8.3 KB
references/go/google-style-guide/guide/part-01.mdmarkdown16.3 KB
references/go/google-style-guide/guide/part-02.mdmarkdown3.0 KB
references/go/google-style-guide/index.mdmarkdown8.4 KB
references/go/preferred-patterns.mdmarkdown12.5 KB
references/go/preferred-patterns/code-examples.mdmarkdown11.6 KB
references/go/quality-gate.mdmarkdown7.3 KB
references/go/quality-gate/common-lint-errors.jsonconfig7.6 KB
references/go/quality-gate/examples.mdmarkdown11.0 KB
references/go/quality-gate/makefile-targets.jsonconfig5.1 KB
references/go/sapcc-conventions.mdmarkdown34.6 KB
references/go/sapcc-conventions/api-design-detailed.mdmarkdown22.7 KB
references/go/sapcc-conventions/architecture-patterns.mdmarkdown18.6 KB
references/go/sapcc-conventions/build-ci-detailed.mdmarkdown18.7 KB
references/go/sapcc-conventions/error-handling-detailed.mdmarkdown20.1 KB
references/go/sapcc-conventions/extended-patterns.mdmarkdown7.1 KB
references/go/sapcc-conventions/go-bits-philosophy-detailed.mdmarkdown24.5 KB
references/go/sapcc-conventions/library-reference.mdmarkdown14.0 KB
references/go/sapcc-conventions/pr-mining-insights.mdmarkdown17.5 KB
references/go/sapcc-conventions/review-standards.mdmarkdown10.5 KB
references/go/sapcc-conventions/sapcc-code-patterns.mdmarkdown46.2 KB
references/go/testing.mdmarkdown9.7 KB
references/go/testing/go-benchmark-and-concurrency.mdmarkdown5.6 KB
references/go/testing/go-test-patterns.mdmarkdown9.0 KB
references/kotlin/concurrency-patterns.mdmarkdown5.4 KB
references/kotlin/kotlin-testing.mdmarkdown7.9 KB
references/php/modern-php-features.mdmarkdown4.4 KB
references/php/testing-patterns.mdmarkdown7.5 KB
references/swift/preferred-patterns.mdmarkdown2.4 KB
references/swift/swift-testing.mdmarkdown6.6 KB
references/swift/task-patterns.mdmarkdown3.6 KB
scripts/bench-compare.shscript7.1 KB
scripts/check-errors.shscript7.1 KB
scripts/check-interface-compliance.shscript6.4 KB
scripts/check-sapcc-auth-ordering.shscript5.5 KB
scripts/check-sapcc-httptest.shscript4.4 KB
scripts/check-sapcc-identify-endpoint.shscript5.8 KB
scripts/check-sapcc-json-strict.shscript4.9 KB
scripts/check-sapcc-time-now.shscript4.2 KB
scripts/check-sapcc-todo-format.shscript4.1 KB
scripts/gen-table-test.shscript4.2 KB
scripts/quality_checker.pyscript16.2 KB
scripts/sync-google-style-guide.pyscript2.5 KB
scripts/validate.pyscript6.3 KB

scripts/quality_checker.py

View on GitHub
#!/usr/bin/env python3
"""
Go PR Quality Gate - Comprehensive quality checker for Go repositories.
Runs make check and provides intelligent error analysis with actionable feedback.
"""

import argparse
import json
import re
import subprocess
import sys
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple


class QualityCheckError(Exception):
    """Custom exception for quality check errors."""

    pass


def load_reference_data(reference_name: str) -> Dict[str, Any]:
    """Load data from references directory."""
    skill_dir = Path(__file__).parent.parent
    reference_path = skill_dir / "references" / reference_name

    if not reference_path.exists():
        # Return empty dict if reference file doesn't exist (graceful degradation)
        return {}

    with open(reference_path, "r", encoding="utf-8") as f:
        return json.load(f)


def validate_go_repository(verbose: bool = False) -> Dict[str, Any]:
    """
    Validate current directory is a Go repository with Makefile.

    Returns:
        Dict with validation status and repository info
    """
    cwd = Path.cwd()

    # Check for go.mod
    go_mod = cwd / "go.mod"
    if not go_mod.exists():
        raise QualityCheckError(
            f"Not a Go repository: go.mod not found in {cwd}\nNavigate to a Go repository root directory."
        )

    # Check for Makefile
    makefile = cwd / "Makefile"
    if not makefile.exists():
        raise QualityCheckError(
            f"Makefile not found in {cwd}\n"
            f"This repository may not use an auto-generated Makefile.\n"
            f"Expected: Makefile with 'check' target"
        )

    # Check if it's a repository with an auto-generated Makefile
    is_gomakefilemaker = False
    with open(makefile, "r", encoding="utf-8") as f:
        first_line = f.readline()
        if "AUTOGENERATED" in first_line or "go-makefile-maker" in first_line:
            is_gomakefilemaker = True

    # Check for git repository
    is_git_repo = (cwd / ".git").exists()

    result = {
        "status": "valid",
        "repository": str(cwd),
        "repository_name": cwd.name,
        "has_gomod": True,
        "has_makefile": True,
        "is_gomakefilemaker": is_gomakefilemaker,
        "is_git_repo": is_git_repo,
    }

    if verbose:
        print("Repository validation:", file=sys.stderr)
        print(f"  Path: {cwd}", file=sys.stderr)
        print("  Go module: ✓", file=sys.stderr)
        print("  Makefile: ✓", file=sys.stderr)
        print(f"  Auto-generated Makefile: {'✓' if is_gomakefilemaker else '✗'}", file=sys.stderr)
        print(f"  Git repository: {'✓' if is_git_repo else '✗'}", file=sys.stderr)

    return result


def run_make_check(verbose: bool = False) -> Tuple[int, str, str]:
    """
    Run make check via Fish shell.

    Returns:
        Tuple of (exit_code, stdout, stderr)
    """
    if verbose:
        print("\n🔍 Running quality checks...", file=sys.stderr)
        print("  ├─ Static analysis... ⏳", file=sys.stderr)
        print("  ├─ Unit tests... ⏳", file=sys.stderr)
        print("  └─ Coverage report... ⏳", file=sys.stderr)
        print("", file=sys.stderr)

    try:
        # Run make check via Fish shell
        result = subprocess.run(
            ["fish", "-c", "make check"],
            capture_output=True,
            text=True,
            timeout=600,  # 10 minute timeout
        )

        return result.returncode, result.stdout, result.stderr

    except subprocess.TimeoutExpired:
        raise QualityCheckError(
            "Quality checks timed out after 10 minutes.\n"
            "Try running individual targets:\n"
            "  - make static-check\n"
            "  - make test"
        )
    except FileNotFoundError:
        raise QualityCheckError("Fish shell not found.\nEnsure Fish is installed and in PATH.")


def extract_coverage(output: str) -> Optional[str]:
    """
    Extract coverage percentage from make check output.

    Looks for patterns like: "coverage: 87.3% of statements"
    """
    # Pattern: coverage: XX.X% of statements
    coverage_pattern = r"coverage:\s+([\d.]+)%\s+of\s+statements"
    match = re.search(coverage_pattern, output)

    if match:
        return match.group(1)

    return None


def categorize_linting_errors(output: str) -> List[Dict[str, Any]]:
    """
    Parse and categorize linting errors from golangci-lint output.

    Expected format:
    path/to/file.go:123:45: error message (linter-name)
    """
    errors = []

    # Pattern: file.go:line:col: message (linter)
    lint_pattern = r"(.+?):(\d+):(\d+):\s+(.+?)\s+\(([^)]+)\)"

    for match in re.finditer(lint_pattern, output):
        file_path, line, col, message, linter = match.groups()

        # Load linter info from reference data
        lint_errors = load_reference_data("common-lint-errors.json")
        linter_info = lint_errors.get(linter, {})

        errors.append(
            {
                "linter": linter,
                "file": file_path,
                "line": int(line),
                "column": int(col),
                "message": message.strip(),
                "description": linter_info.get("description", "Unknown linter"),
                "fix_suggestion": linter_info.get("fix", "Review error and apply fix"),
                "severity": linter_info.get("severity", "medium"),
            }
        )

    return errors


def categorize_test_failures(output: str) -> List[Dict[str, Any]]:
    """
    Parse and categorize test failures.

    Expected format:
    --- FAIL: TestName (0.00s)
        test_file.go:123: error message
    FAIL    package/path    0.123s
    """
    failures = []

    # Pattern: --- FAIL: TestName
    test_fail_pattern = r"--- FAIL:\s+(\S+)\s+\(([\d.]+)s\)"

    # Pattern: FAIL package/path
    package_fail_pattern = r"FAIL\s+(\S+)\s+([\d.]+)s"

    current_test = None
    current_package = None

    for line in output.split("\n"):
        # Check for test failure
        test_match = re.search(test_fail_pattern, line)
        if test_match:
            current_test = test_match.group(1)
            duration = test_match.group(2)
            continue

        # Check for package failure
        package_match = re.search(package_fail_pattern, line)
        if package_match:
            current_package = package_match.group(1)

            if current_test:
                # Extract error message from previous lines
                error_msg = "Test failed - check output for details"

                failures.append(
                    {"package": current_package, "test": current_test, "error": error_msg, "type": "test_failure"}
                )

                current_test = None

            current_package = None

    return failures


def categorize_build_errors(output: str) -> List[Dict[str, Any]]:
    """
    Parse and categorize build errors.

    Expected format:
    # package/path
    file.go:123:45: error message
    """
    errors = []

    # Pattern: file.go:line:col: error message (no linter in parens)
    build_pattern = r"^([^:]+):(\d+):(\d+):\s+(.+)$"

    for line in output.split("\n"):
        # Skip lines that look like linting errors (have linter in parens)
        if re.search(r"\([^)]+\)$", line):
            continue

        match = re.search(build_pattern, line)
        if match:
            file_path, line_num, col, message = match.groups()

            errors.append(
                {
                    "file": file_path,
                    "line": int(line_num),
                    "column": int(col),
                    "message": message.strip(),
                    "type": "build_error",
                }
            )

    return errors


def suggest_fix_commands(errors: Dict[str, List]) -> List[str]:
    """
    Suggest make targets to fix common error patterns.

    Returns:
        List of make commands to try
    """
    commands = []

    # Check for import-related errors
    lint_errors = errors.get("linting", [])
    for error in lint_errors:
        if error.get("linter") in ["goimports", "gci"]:
            if "make goimports" not in commands:
                commands.append("make goimports")

    # Check for dependency-related errors
    for error in lint_errors:
        if "go.mod" in error.get("message", "") or "go.sum" in error.get("message", ""):
            if "make tidy-deps" not in commands:
                commands.append("make tidy-deps")

    # Check for license header errors
    for error in lint_errors:
        if "license" in error.get("message", "").lower() or "spdx" in error.get("message", "").lower():
            if "make license-headers" not in commands:
                commands.append("make license-headers")

    return commands


def parse_check_output(exit_code: int, stdout: str, stderr: str, verbose: bool = False) -> Dict[str, Any]:
    """
    Parse make check output and categorize results.

    Returns:
        Structured data with results and errors
    """
    combined_output = stdout + "\n" + stderr

    # Success case
    if exit_code == 0:
        coverage = extract_coverage(combined_output)

        result = {
            "status": "success",
            "coverage": f"{coverage}%" if coverage else None,
            "checks_passed": ["static-check", "test", "coverage"],
            "summary": "All quality checks passed",
        }

        if verbose:
            print("\n✅ All quality checks passed", file=sys.stderr)
            if coverage:
                print(f"📊 Coverage: {coverage}%", file=sys.stderr)

        return result

    # Failure case - categorize errors
    errors = {
        "linting": categorize_linting_errors(combined_output),
        "tests": categorize_test_failures(combined_output),
        "build": categorize_build_errors(combined_output),
    }

    # Remove empty categories
    errors = {k: v for k, v in errors.items() if v}

    # Generate fix suggestions
    fix_commands = suggest_fix_commands(errors)

    result = {
        "status": "failed",
        "exit_code": exit_code,
        "errors": errors,
        "fix_commands": fix_commands,
        "error_count": sum(len(v) for v in errors.values()),
        "summary": f"Quality checks failed with {sum(len(v) for v in errors.values())} errors",
    }

    if verbose:
        print(f"\n❌ Quality checks failed (exit code: {exit_code})", file=sys.stderr)
        print(f"📊 Total errors: {result['error_count']}", file=sys.stderr)

        if errors.get("linting"):
            print(f"\n🔍 Linting errors: {len(errors['linting'])}", file=sys.stderr)
            # Group by linter
            by_linter = {}
            for error in errors["linting"]:
                linter = error["linter"]
                by_linter.setdefault(linter, []).append(error)

            for linter, linter_errors in sorted(by_linter.items()):
                print(f"  • {linter}: {len(linter_errors)} issues", file=sys.stderr)

        if errors.get("tests"):
            print(f"\n🧪 Test failures: {len(errors['tests'])}", file=sys.stderr)
            for test_error in errors["tests"]:
                print(f"  • {test_error['test']} in {test_error['package']}", file=sys.stderr)

        if fix_commands:
            print("\n💡 Suggested fixes:", file=sys.stderr)
            for cmd in fix_commands:
                print(f'  • fish -c "{cmd}"', file=sys.stderr)

    return result


def generate_report(results: Dict[str, Any], format_type: str = "json") -> str:
    """
    Generate formatted report from results.

    Args:
        results: Parsed check results
        format_type: 'json' or 'text'

    Returns:
        Formatted report string
    """
    if format_type == "json":
        return json.dumps(results, indent=2, ensure_ascii=False)

    # Text format
    lines = []

    if results["status"] == "success":
        lines.append("✅ All quality checks passed")
        if results.get("coverage"):
            lines.append(f"📊 Coverage: {results['coverage']}")
        lines.append("")
        lines.append("Next steps:")
        lines.append("  • View detailed coverage: fish -c 'open build/cover.html'")
        lines.append("  • Create commit if ready")
    else:
        lines.append(f"❌ Quality checks failed ({results['error_count']} errors)")
        lines.append("")

        errors = results.get("errors", {})

        if errors.get("linting"):
            lines.append(f"🔍 Linting Errors ({len(errors['linting'])}):")
            # Group by linter
            by_linter = {}
            for error in errors["linting"]:
                linter = error["linter"]
                by_linter.setdefault(linter, []).append(error)

            for linter, linter_errors in sorted(by_linter.items()):
                lines.append(f"\n  [{linter}] - {len(linter_errors)} issues")
                for error in linter_errors[:3]:  # Show first 3
                    lines.append(f"    • {error['file']}:{error['line']}: {error['message']}")
                if len(linter_errors) > 3:
                    lines.append(f"    ... and {len(linter_errors) - 3} more")

        if errors.get("tests"):
            lines.append(f"\n🧪 Test Failures ({len(errors['tests'])}):")
            for test_error in errors["tests"]:
                lines.append(f"  • {test_error['test']} in {test_error['package']}")
                lines.append(f"    {test_error['error']}")

        if results.get("fix_commands"):
            lines.append("\n💡 Suggested fixes:")
            for cmd in results["fix_commands"]:
                lines.append(f'  • fish -c "{cmd}"')

    return "\n".join(lines)


def main():
    """Main entry point."""
    parser = argparse.ArgumentParser(
        description="Go PR Quality Gate - Run comprehensive quality checks",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  # Run full quality check
  python3 quality_checker.py

  # Validate repository only
  python3 quality_checker.py --validate-only

  # Check with minimum coverage threshold
  python3 quality_checker.py --min-coverage 80.0

  # Verbose output
  python3 quality_checker.py --verbose
        """,
    )

    parser.add_argument("--validate-only", action="store_true", help="Only validate repository, do not run checks")
    parser.add_argument("--format", choices=["json", "text"], default="json", help="Output format (default: json)")
    parser.add_argument("--min-coverage", type=float, help="Minimum required coverage percentage (e.g., 80.0)")
    parser.add_argument("--verbose", action="store_true", help="Enable verbose output to stderr")

    args = parser.parse_args()

    try:
        # Step 1: Validate repository
        validation = validate_go_repository(verbose=args.verbose)

        if args.validate_only:
            print(json.dumps(validation, indent=2))
            return 0

        # Step 2: Run make check
        exit_code, stdout, stderr = run_make_check(verbose=args.verbose)

        # Step 3: Parse results
        results = parse_check_output(exit_code, stdout, stderr, verbose=args.verbose)

        # Step 4: Check coverage threshold if specified
        if args.min_coverage and results.get("coverage"):
            coverage_str = results["coverage"].rstrip("%")
            try:
                coverage = float(coverage_str)
                if coverage < args.min_coverage:
                    results["status"] = "failed"
                    results["coverage_check"] = {"required": args.min_coverage, "actual": coverage, "passed": False}
                    if args.verbose:
                        print(f"\n⚠️  Coverage {coverage}% below threshold {args.min_coverage}%", file=sys.stderr)
            except ValueError:
                pass

        # Step 5: Generate and print report
        report = generate_report(results, format_type=args.format)
        print(report)

        # Exit with appropriate code
        if results["status"] == "success":
            return 0
        else:
            return 1

    except QualityCheckError as e:
        error_result = {"status": "error", "error_type": "QualityCheckError", "message": str(e)}
        print(json.dumps(error_result, indent=2), file=sys.stderr)
        return 2
    except Exception as e:
        error_result = {"status": "error", "error_type": type(e).__name__, "message": str(e)}
        print(json.dumps(error_result, indent=2), file=sys.stderr)
        return 3


if __name__ == "__main__":
    sys.exit(main())
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall