HYPERFLEET-878 - feat: pre-commit hooks registry with commitlint with Go binary

[yasun1]

Achieve commit validation with a Go implementation for better performance and simplified cross-component deployment.

• Implement commit message validator in Go with comprehensive test coverage
• Add GitHub SDK integration for PR title validation (replaces gh CLI dependency)
• Support both local pre-commit hooks and Prow CI environments
• Build container image for reuse across all HyperFleet components
• Add commit range detection with PULL_REFS priority for Prow accuracy
• Create unified CLI with --pr flag for CI mode
• Include comprehensive documentation for local and CI usage
• Add Makefile with build, test, lint, and validation targets

Summary

• HYPERFLEET-878

Test Plan

• Unit tests added/updated
• make test-all passes
• make lint passes
• Helm chart changes validated with make test-helm (if applicable)
• Deployed to a development cluster and verified (if Helm/config changes)
• E2E tests passed (if cross-component or major changes)

[rafabene]

Category: Bug

validateSHA() accepts SHAs with 7+ characters ({7,40}), but baseSHA[:8] here panics if the SHA is exactly 7 chars. Same issue at lines 176, 177, 181, 195.

Two options:

1. Raise the minimum in validateSHA to 8 (since [:8] is used everywhere):

shaPattern = regexp.MustCompile(`^[0-9a-f]{8,40}$`)

2. Use a helper that truncates safely:

func shortSHA(sha string) string {
    if len(sha) <= 8 {
        return sha
    }
    return sha[:8]
}

Option 2 is more defensive since git itself can produce 7-char short SHAs.

[rafabene]

Category: Bug

os.Setenv/os.Unsetenv and os.Chdir are used without proper test isolation. If a subtest panics, env vars leak into the next subtest. Also, os.Getwd() error is silently ignored on line 170.

Use t.Setenv() and t.Chdir() instead — they restore state automatically, even on panic:

// Replace os.Chdir pattern (lines 170-174)
t.Chdir(tempDir)  // Go 1.24+ — auto-restores on cleanup

// Replace os.Setenv/Unsetenv pattern (lines 215-222)
for k, v := range tt.env {
    t.Setenv(k, v)  // auto-restores when subtest ends
}
// Remove manual os.Unsetenv calls — no longer needed

This also removes the need for the final cleanup block at lines 241-244.

[rafabene]

Category: Bug

fmt.Sscanf returns a parse error but it's discarded — the error message only includes the raw string, losing the reason parsing failed.

// Before
return "", fmt.Errorf("invalid PULL_NUMBER: %s", prNumberStr)

// After — wrap the actual error
return "", fmt.Errorf("invalid PULL_NUMBER %q: %w", prNumberStr, err)

Using %q also quotes the value, which helps debug whitespace or encoding issues in the env var.

[rafabene]

Category: Pattern

This file has zero test coverage. GetPRTitleFromEnv() has several testable code paths that don't require a real GitHub API call:

• Missing env vars (REPO_OWNER, REPO_NAME, PULL_NUMBER)
• Invalid PULL_NUMBER (non-numeric)
• Invalid repo format in GetPRTitle() (missing /)

func TestGetPRTitleFromEnv_MissingEnvVars(t *testing.T) {
    client := &Client{client: github.NewClient(nil)}
    ctx := context.Background()

    // All missing
    _, err := client.GetPRTitleFromEnv(ctx)
    if err == nil {
        t.Error("expected error for missing env vars")
    }
}

func TestGetPRTitle_InvalidRepoFormat(t *testing.T) {
    client := &Client{client: github.NewClient(nil)}
    ctx := context.Background()

    _, err := client.GetPRTitle(ctx, "no-slash", 1)
    if err == nil {
        t.Error("expected error for invalid repo format")
    }
}

[rafabene]

Category: Improvement

validatePR() is ~130 lines mixing 5+ concerns (git setup, commit range, SHA validation, commit validation loop, PR title fetch, summary output). Consider extracting:

1. The commit validation loop (lines 168-197) into validateCommits(validator, repo, commits) []string
2. The PR title validation block (lines 199-231) into validatePRTitle(validator, client) (bool, error)
3. The summary output (lines 233-262) into printSummary(failedCommits, prTitleFailed, commits, title)

This also makes each piece independently testable — right now validatePR is essentially untestable because it requires a real git repo with remote, env vars, and GitHub API access all at once.

[rafabene]

Category: Improvement

context.Background() is used here but cmd.Context() is available from cobra — it carries cancellation signals (e.g., SIGINT). Pass the cobra context into validatePR:

// In run():
return validatePR(cmd.Context(), validator)

// In validatePR():
func validatePR(ctx context.Context, validator *commitlint.Validator) error {
    // ...
    ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
    defer cancel()
    // ...
}

This way the GitHub API call respects process cancellation.

[rafabene]

Category: Standards

Several fenced code blocks in this file use bare ``` without a language identifier (MD040 violation). Add language tags:

• Line 142: ASCII diagram → use ```text
• Line 204: commit format → use ```text
• Line 237: valid examples → use ```text
• Line 245: invalid examples → use ```text

[rafabene]

Superseded by new PR with review feedback addressed.