notque/vexjoy-agent / skills/programming/programming
programming
FlaggedLanguage-specific patterns and tooling: Go, Kotlin, PHP, Swift, TypeScript.
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())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |