macos-package-review/QA_SETUP.md

Quality Assurance Setup Complete

We've added comprehensive testing and static analysis tooling to the project.

What's Been Added

1. Test Suite (750+ lines)

File	Coverage	Tests
internal/inventory/inventory_test.go	9 tests + 2 benchmarks	LoadInventory, AllPackages, CountPackages, CountBySource, JSON marshaling
internal/security/audit_test.go	10 tests + 2 benchmarks	NewAudit, FilterByMinSeverity, CountVulnerable, CVSS severity mapping
internal/security/osv_test.go	6 tests + 1 benchmark	OSV response parsing, ecosystem mapping, CVSS handling
internal/report/report_test.go	9 tests + 2 benchmarks	JSON generation, HTML generation, summary calculations

Total: 34+ tests, 7 benchmarks

2. Static Analysis Configuration

Tool	Purpose	Config
golangci-lint	Meta-linter (11 linters)	.golangci.yml
govulncheck	Vulnerability scanning	Built-in, no config needed
go fmt	Code formatting	Built-in
go vet	Basic type checking	Built-in
pre-commit	Git hooks for local checks	.pre-commit-config.yaml

3. CI/CD Pipeline

GitHub Actions workflow (.github/workflows/ci.yml):

• ✅ Tests on Go 1.22 & 1.23
• ✅ golangci-lint with 11 configured linters
• ✅ govulncheck for known vulnerabilities
• ✅ Format checking (go fmt + go vet)
• ✅ Code coverage reporting (Codecov)

4. Build Automation

Enhanced Makefile targets:

• make test — Run all tests with race detector
• make coverage — Generate HTML coverage report
• make lint — Run all linters
• make fmt — Format code
• make vulnerability — Check for CVEs
• make ci — Run all checks (full CI pipeline)
• make install-tools — Install analysis tools

5. Documentation

• TESTING.md — Complete testing guide
• QA_SETUP.md — This file

---

Getting Started

Step 1: Install Analysis Tools

make install-tools

This installs:

• golangci-lint — All-in-one linter
• govulncheck — Vulnerability scanner

Step 2: Run Full Test Suite

make test
# Output: ✓ Tests pass on race detector

Step 3: Check Code Quality

make lint
# Output: ✓ Linting passed

Step 4: Run Full CI Pipeline

make ci
# Runs: fmt → lint → test → vulnerability

Step 5: Set Up Pre-commit Hooks (Optional)

pip install pre-commit
pre-commit install

# Now automatic checks run before each commit
git commit -m "Your change"

---

Test Coverage

Current Test Files

internal/
├── inventory/
│   └── inventory_test.go        (9 tests)
├── security/
│   ├── audit_test.go            (10 tests)
│   └── osv_test.go              (6 tests)
└── report/
    └── report_test.go           (9 tests)

Running Tests

# All tests
make test

# Specific package
go test -v ./internal/security

# Specific test
go test -v -run TestFilterByMinSeverity ./internal/security

# With coverage
make coverage

# Benchmarks
go test -bench=. -benchmem ./...

Coverage Report

make coverage
open coverage.html

Shows:

• Line coverage by file
• Coverage percentage
• Uncovered lines highlighted

---

Linting & Analysis

Configured Linters (11 total)

├─ staticcheck      (Go vet on steroids)
├─ gosec            (Security issues)
├─ revive           (Style consistency)
├─ errcheck         (Unchecked errors)
├─ ineffassign      (Unused assignments)
├─ unused           (Dead code)
├─ typecheck        (Type errors)
├─ gocritic         (Advanced issues)
├─ cyclop           (Complexity)
├─ dupl             (Code duplication)
└─ misspell         (Typos)

Running Linters

# All linters
make lint

# Specific linter
golangci-lint run --enable gosec ./...

# With autofix (where available)
golangci-lint run --fix ./...

---

Vulnerability Scanning

Check for Known Vulnerabilities

make vulnerability

This queries the official Go vulnerability database: https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck

Manual Query

govulncheck ./...

---

CI/CD Pipeline

GitHub Actions

Every push/PR runs automatically:

✓ Test (Go 1.22, 1.23)
✓ Lint (golangci-lint)
✓ Vulnerability (govulncheck)
✓ Format (go fmt + go vet)
✓ Coverage (Codecov)

View results: GitHub > Actions tab

Local CI Check

make ci

Runs locally before pushing.

---

Code Quality Standards

1. Error Handling

✅ All errors must be handled:

if err != nil {
    return fmt.Errorf("context: %w", err)
}

2. Naming

✅ Clear, descriptive names:

func LoadInventory(path string) (*Inventory, error)
type AuditFinding struct
const MaxRetries = 3

3. Complexity

✅ Keep functions simple:

• Max cyclomatic complexity: 10
• Avoid deep nesting (max 3 levels)

4. Comments

✅ Explain the "why":

// LoadInventory reads the system inventory JSON file
// and parses it into structured data.
func LoadInventory(path string) (*Inventory, error) {

---

Testing Patterns Used

Table-Driven Tests

tests := []struct {
    name   string
    input  float64
    want   string
}{
    {"critical", 9.5, "CRITICAL"},
    {"high", 7.5, "HIGH"},
}

for _, tt := range tests {
    t.Run(tt.name, func(t *testing.T) {
        got := cvssToSeverity(tt.input)
        if got != tt.want {
            t.Errorf("got %s, want %s", got, tt.want)
        }
    })
}

Benchmarking

func BenchmarkCountPackages(b *testing.B) {
    for i := 0; i < b.N; i++ {
        inv.CountPackages()
    }
}

Error Cases

func TestLoadInventoryFileNotFound(t *testing.T) {
    _, err := LoadInventory("/nonexistent/file")
    if err == nil {
        t.Error("should error for nonexistent file")
    }
}

---

Common Commands

# Development
make build              # Build binary
make run                # Run audit
make audit-full         # Full workflow

# Testing
make test               # Run tests
make coverage           # Coverage report
go test -bench=. ./... # Benchmarks

# Quality
make lint               # All linters
make fmt                # Format code
make vulnerability      # Vulnerability scan
make ci                 # Full pipeline

# Maintenance
make install-tools      # Install analysis tools
make install-deps       # Download Go deps
make clean              # Clean artifacts

---

Next Steps

1. Run the full test suite:

   make install-tools && make ci
   

2. Review coverage:

   make coverage
   

3. Set up pre-commit hooks (optional):

   pip install pre-commit && pre-commit install
   

4. Push to GitHub — CI will run automatically

---

Performance

Typical CI times:

• Test suite: ~10s
• Linting: ~15s
• Full pipeline: ~45s

---

Resources

• Testing guide: TESTING.md
• Go testing: https://golang.org/pkg/testing/
• Golangci-lint: https://golangci-lint.run/
• Govulncheck: https://pkg.go.dev/golang.org/x/vuln
• Go best practices: https://golang.org/doc/effective_go

---

Summary: 34+ tests, 11 linters, 2 vulnerability scanners, full CI/CD pipeline ✅