🎯 Repository Quality Improvement Report - Dependencies

[github-actions[bot]]

Analysis Date: 2025-12-22
Focus Area: Dependencies
Strategy Type: Standard
Custom Area: No

Executive Summary

The gh-aw repository demonstrates strong security practices with govulncheck integration, SHA-pinned GitHub Actions (99.9%), and Dependabot automation across 3 ecosystems. However, the dependency landscape reveals 56% unstable v0.x dependencies (32 of 57 total), 7 different versions of actions/checkout across workflows, and missing license compliance tooling. The project has a healthy 2.56:1 indirect-to-direct dependency ratio (41 indirect, 16 direct) with 3 strategic replace directives for stability.

Key opportunities: standardize GitHub Actions versions, reduce v0.x dependency exposure, implement license compliance scanning, and add dependency update automation tooling.

Full Analysis Report

Focus Area: Dependencies

Current State Assessment

gh-aw manages dependencies across multiple ecosystems:

• Go modules: 16 direct + 41 indirect = 57 total dependencies
• GitHub Actions: 4,793 action uses across 122 workflow lock files
• Custom actions: 2 internal actions (setup-safe-inputs, setup-safe-outputs)
• Dependabot: Automated updates for npm, pip, and gomod in .github/workflows

Metrics Collected:

Metric	Value	Status
Total Go Dependencies	57 (16 direct, 41 indirect)	✅
Dependency Maturity (v1.x+)	44% (25 of 57)	⚠️
v0.x Dependencies	56% (32 of 57)	⚠️
go.sum Integrity Entries	160	✅
Replace Directives	3	✅
GitHub Actions Pinning	99.98% (4,792 of 4,793)	✅
Actions Version Consistency	7 versions of checkout	⚠️
Security Scanning	govulncheck + SARIF	✅
Dependabot Coverage	3 ecosystems	✅
License Compliance Tools	None	❌
Dependency Update Automation	Dependabot only	⚠️
tools.go File	Missing	⚠️

Findings

Strengths

• Excellent security posture: govulncheck integration with SARIF upload to GitHub Security
• Strong action pinning: 99.98% SHA-pinned GitHub Actions (industry best practice)
• Automated dependency updates: Dependabot covering npm, pip, and gomod ecosystems
• Strategic replace directives: 3 well-documented replacements for stability (semver v3.4.0, cast v1.10.0, lipgloss v1.1.0)
• Clean dependency graph: No deprecated packages detected, healthy 2.56:1 indirect/direct ratio
• Integrity verification: 160 go.sum entries ensuring reproducible builds

Areas for Improvement

• High v0.x exposure: 56% of dependencies (32 of 57) are on unstable v0.x versions, increasing breaking change risk
• GitHub Actions version sprawl: 7 different versions of actions/checkout across workflows
• Missing license compliance: No go-licenses or similar tooling to track dependency licenses
• No tools.go: Missing pattern for tracking build-time tool dependencies
• Limited update automation: Only Dependabot; no automated version range updates or bulk upgrade tooling
• Pseudo-version usage: 4 indirect pseudo-versions indicate dependencies without stable releases
• No dependency age tracking: Cannot identify outdated dependencies beyond manual inspection
• Workflow lock file dependencies: 122 lock files with embedded dependencies lack centralized management

Detailed Analysis

Go Dependency Ecosystem

Direct Dependencies (16):

• TUI/CLI: 10 charmbracelet packages (huh, lipgloss, bubbles, etc.)
• Core Libraries: cobra (CLI), go-gh (GitHub API), fsnotify (file watching)
• Specialized: goccy/go-yaml (YAML 1.1 support), modelcontextprotocol/go-sdk (MCP integration)
• Testing: stretchr/testify (comprehensive test utilities)

Critical Third-Party Dependencies:

• charmbracelet ecosystem: 10 packages for terminal UI (highest concentration)
• github.com/cli/go-gh: Official GitHub CLI library integration
• modelcontextprotocol/go-sdk: MCP server protocol (pseudo-version v1.1.1-0.20251212184941)

Replace Directives Analysis:

// All 3 replacements are stability-focused with clear rationale:
replace github.com/Masterminds/semver/v3 => v3.4.0  // Bug fixes + new features
replace github.com/spf13/cast => v1.10.0            // Type conversion improvements  
replace github.com/charmbracelet/lipgloss => v1.1.0 // Stable release vs pseudo-version

Dependency Maturity Analysis

Version Distribution:

• v0.x (unstable): 32 dependencies (56%) - high breaking change risk
• v1.x (stable): 22 dependencies (39%) - stable APIs
• v2+ (mature): 9 dependencies (15%) - long-term stability

Risk Assessment:
The 56% v0.x exposure is concerning for a production CLI tool. Many indirect dependencies are TUI/terminal libraries where breaking changes could impact user experience. Consider:

1. Vendor critical v0.x dependencies
2. Pin v0.x dependencies to specific minor versions
3. Monitor charmbracelet package releases closely

GitHub Actions Dependency Management

Strengths:

• SHA-pinned actions: 4,792 of 4,793 (99.98%) use commit SHAs with version comments
• Example: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
• Dependabot monitoring: Weekly scans for npm, pip, and gomod in workflows

Issues:

• Version inconsistency: 7 different versions of actions/checkout across workflows
• Unpinned action: 1 action without SHA pinning (security risk)
• No centralized action management: No composite actions or version constants

Recommendation: Create a centralized action version registry in .github/actions-versions.yml or use Dependabot groups to batch action updates.

License Compliance Gap

Current State:

• Repository has LICENSE file (project license)
• No tooling to track dependency licenses
• No automated license compatibility checks
• No SBOM (Software Bill of Materials) generation

Risk:
Without license tracking, the project could inadvertently include GPL dependencies incompatible with the MIT license, or fail to comply with attribution requirements.

Recommended Tools:

• go-licenses for Go dependency license scanning
• license-checker for npm dependencies
• pip-licenses for Python dependencies
• Integrate with CI to fail on incompatible licenses

Dependabot Configuration Analysis

Coverage:

# .github/dependabot.yml
- npm (weekly, .github/workflows)
- pip (weekly, .github/workflows)  
- gomod (weekly, .github/workflows)

Gaps:

• No GitHub Actions ecosystem (relies on workflow lock file dependabot)
• No grouping rules for related dependencies
• Weekly interval may be too infrequent for security patches
• No auto-merge configuration for minor/patch updates

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: The following tasks are designed for GitHub Copilot agent execution. Please split these into individual work items for Claude to process.

Improvement Tasks

The following code regions and tasks should be processed by the Copilot agent. Each section is marked for easy identification by the planner agent.

Task 1: Implement License Compliance Scanning

Priority: High
Estimated Effort: Medium
Focus Area: Dependencies

Description:
Add automated license compliance scanning for Go dependencies to prevent license conflicts and ensure proper attribution. This should integrate with CI to fail builds when incompatible licenses are detected.

Acceptance Criteria:

• Install and configure go-licenses tool
• Create .github/workflows/license-check.yml workflow
• Fail CI on GPL/AGPL/SSPL licenses (incompatible with MIT)
• Generate SBOM (Software Bill of Materials) artifact
• Document allowed/disallowed licenses in CONTRIBUTING.md
• Add license report to release artifacts

Code Region: .github/workflows/, Makefile, CONTRIBUTING.md

Create a GitHub Actions workflow to scan Go dependency licenses using go-licenses:

1. Add license-check.yml workflow:
   - Install go-licenses tool
   - Scan all dependencies: go-licenses check ./...
   - Disallow: GPL, LGPL, AGPL, SSPL (copyleft licenses)
   - Allow: MIT, Apache-2.0, BSD-3-Clause, ISC
   - Generate CSV report of all licenses
   - Upload SBOM as artifact

2. Add Makefile target:
   - `make license-check`: Run locally
   - `make license-report`: Generate HTML report

3. Update CONTRIBUTING.md:
   - Add "Dependency License Policy" section
   - List allowed/disallowed licenses
   - Explain how to check licenses before adding dependencies

Example go-licenses commands:
- Check: go-licenses check --disallowed_types=GPL,LGPL,AGPL ./...
- Report: go-licenses csv ./... > licenses.csv
- Save: go-licenses save ./... --save_path=third_party/licenses

---

Task 2: Standardize GitHub Actions Versions

Priority: High
Estimated Effort: Small
Focus Area: Dependencies

Description:
Eliminate GitHub Actions version sprawl by standardizing to single versions of commonly-used actions. Currently 7 different versions of actions/checkout exist across workflows, creating maintenance burden and inconsistency.

Acceptance Criteria:

• Audit all action versions in .github/workflows/*.yml
• Create action version constants in shared location
• Standardize to latest stable versions (actions/checkout@v5.0.1, actions/setup-node@v6.1.0, etc.)
• Update all 122 workflow lock files to use consistent versions
• Add validation script to prevent version drift
• Document standard action versions in CONTRIBUTING.md

Code Region: .github/workflows/*.yml, .github/workflows/*.lock.yml

Standardize GitHub Actions versions across all workflows:

1. Create `.github/action-versions.md`:
   ```markdown
   # Standard GitHub Actions Versions
   
   Use these pinned versions for consistency:
   
   - `actions/checkout`: v5.0.1 (SHA: 93cb6efe18208431cddfb8368fd83d5badbf9bfd)
   - `actions/setup-node`: v6.1.0 (SHA: 395ad3262231945c25e8478fd5baf05154b1d79f)
   - `actions/upload-artifact`: v5.0.0 (SHA: 330a01c490aca151604b8cf639adc76d48f6c5d4)
   - `actions/cache`: v4.3.0 (SHA: 0057852bfaa89a56745cba8c7296529d2fc39830)
   - `actions/github-script`: v8 (SHA: ed597411d8f924073f98dfc5c65a23a2325f34cd)

2. Update all .yml and .lock.yml files:

   • Replace all action version references with standard versions
   • Ensure SHA pinning maintained
   • Run make recompile to regenerate lock files

3. Add version validation script:

   • Create scripts/validate-action-versions.sh
   • Check all workflows match standard versions
   • Integrate into make lint

4. Configure Dependabot grouping:

   • Add to .github/dependabot.yml:

     groups:
       github-actions:
         patterns:
           - "actions/*"

---

#### Task 3: Reduce v0.x Dependency Exposure

**Priority**: Medium  
**Estimated Effort**: Large  
**Focus Area**: Dependencies

**Description:**
Reduce the project's exposure to unstable v0.x dependencies from 56% to <30%. This involves evaluating each v0.x dependency, finding stable alternatives, or vendoring critical ones to mitigate breaking change risk.

**Acceptance Criteria:**
- [ ] Audit all 32 v0.x dependencies for maturity/stability
- [ ] Identify dependencies with v1.0+ alternatives
- [ ] Replace or vendor critical v0.x dependencies
- [ ] Add vendor directory for high-risk v0.x dependencies (if vendoring)
- [ ] Document dependency stability policy in `DEVGUIDE.md`
- [ ] Achieve <30% v0.x dependency ratio (target: 17 of 57 max)

**Code Region:** `go.mod`, `go.sum`, `pkg/*`, `cmd/*`

```markdown
Reduce v0.x dependency exposure through systematic evaluation:

1. Audit v0.x dependencies:
   ```bash
   # List all v0.x dependencies
   grep -E "v0\.[0-9]+" go.mod > v0-deps.txt
   
   # For each, research:
   # - Is there a v1.x+ alternative?
   # - How actively maintained?
   # - Breaking change history?
   # - Can we vendor it?

2. Priority action areas:

   • charmbracelet packages: Monitor for v1.0 releases, consider vendoring critical ones
   • indirect dependencies: Check if updating direct deps brings in stable versions
   • development-only: Less critical, but document risk

3. Vendoring strategy for critical v0.x:

   • Add go mod vendor to build process
   • Document vendored packages in DEVGUIDE.md
   • Set up monitoring for upstream stability announcements

4. Document in DEVGUIDE.md:

   ## Dependency Stability Policy
   
   - Prefer v1.0+ dependencies for production code
   - v0.x allowed only when:
     - No stable alternative exists
     - Actively maintained (commits within 3 months)
     - Used by >1000 projects (proven stability)
   - Critical v0.x dependencies must be vendored

5. Track progress:

   • Current: 56% v0.x (32 of 57)
   • Target: <30% v0.x (17 of 57)
   • Add metric to make deps output

---

#### Task 4: Add tools.go for Build Tool Management

**Priority**: Medium  
**Estimated Effort**: Small  
**Focus Area**: Dependencies

**Description:**
Create a `tools.go` file to track build-time tool dependencies (linters, generators, etc.) ensuring consistent tooling across development environments and CI.

**Acceptance Criteria:**
- [ ] Create `tools.go` in repository root
- [ ] Import all build-time tools with blank imports
- [ ] Update `go.mod` to track tool versions
- [ ] Document tool installation in `DEVGUIDE.md`
- [ ] Add `make tools` target to install tracked tools
- [ ] Ensure CI uses same tool versions as local development

**Code Region:** `tools.go` (new file), `Makefile`, `DEVGUIDE.md`

```markdown
Add tools.go for build-time dependency tracking:

1. Create tools.go:
   ```go
   //go:build tools
   // +build tools

   // Package tools tracks build-time tool dependencies.
   // Import tools here to include them in go.mod.
   package tools

   import (
       _ "github.com/golangci/golangci-lint/cmd/golangci-lint"
       _ "github.com/google/go-licenses"
       // Add other tools as discovered
   )

2. Update go.mod:

   go get github.com/golangci/golangci-lint/cmd/golangci-lint@latest
   go get github.com/google/go-licenses@latest
   go mod tidy

3. Add Makefile target:

   .PHONY: tools
   tools: ## Install build-time tools
   	`@echo` "Installing tools from tools.go..."
   	`@cat` tools.go | grep _ | awk -F'"' '{print $$2}' | xargs -tI % go install %

4. Update DEVGUIDE.md:

   ## Build Tools
   
   This project uses `tools.go` to track build-time tool dependencies.
   
   Install all tools:
   ```bash
   make tools

   Tools are versioned in go.mod for consistency across environments.

5. Update CI workflows:

   • Replace manual tool installations with make tools
   • Ensures CI and local dev use identical versions

---

#### Task 5: Implement Dependency Update Dashboard

**Priority**: Low  
**Estimated Effort**: Medium  
**Focus Area**: Dependencies

**Description:**
Create a dependency health dashboard that tracks outdated dependencies, security advisories, and update history. This provides visibility into dependency freshness and helps prioritize updates.

**Acceptance Criteria:**
- [ ] Add `gh aw deps outdated` command to show outdated dependencies
- [ ] Add `gh aw deps security` command to show security advisories
- [ ] Add `gh aw deps report` command to generate comprehensive dependency report
- [ ] Display dependency age, latest version, and update recommendation
- [ ] Integrate with GitHub Security Advisory API
- [ ] Add dependency metrics to `gh aw audit` output

**Code Region:** `pkg/cli/deps_command.go` (new file), `cmd/gh-aw/main.go`

```markdown
Create dependency management commands for visibility and automation:

1. Add `pkg/cli/deps_command.go`:
   ```go
   // NewDepsCommand creates the 'deps' subcommand
   func NewDepsCommand() *cobra.Command {
       cmd := &cobra.Command{
           Use:   "deps",
           Short: "Dependency management and health checks",
       }
       
       cmd.AddCommand(newDepsOutdatedCommand())
       cmd.AddCommand(newDepsSecurityCommand()) 
       cmd.AddCommand(newDepsReportCommand())
       
       return cmd
   }

2. Implement gh aw deps outdated:

   • Parse go.mod for current versions
   • Query proxy.golang.org for latest versions
   • Display table: Module | Current | Latest | Age | Recommendation
   • Use console formatting for output

3. Implement gh aw deps security:

   • Query GitHub Security Advisory API
   • Filter for Go dependencies in go.mod
   • Display CVE/GHSA with severity and fix version
   • Link to GitHub Security tab

4. Implement gh aw deps report:

   • Aggregate outdated + security + license info
   • Generate markdown report
   • Optionally create GitHub discussion with report
   • Include dependency graph visualization (mermaid)

5. Add to main.go:

   rootCmd.AddCommand(cli.NewDepsCommand())

6. Test coverage:

   • Unit tests for version comparison logic
   • Integration tests with test go.mod files
   • Mock API responses for security checks

---

## 📊 Historical Context

<details>
<summary><b>Previous Focus Areas</b></summary>

| Date | Focus Area | Type | Custom | Key Outcomes |
|------|------------|------|--------|--------------|
| 2025-12-05 | Testing | Standard | N | 1,164 test files, 99.5% not parallelized, 28% table-driven |
| 2025-12-06 | Security | Standard | N | 142 go.mod deps, govulncheck enabled, 24 security test files |
| 2025-12-07 | Workflow Input/Output Contract Validation | Custom | Y | 164 workflows, 3 JSON schemas, 5,850 LOC schema definitions |
| 2025-12-08 | CLI Resilience Self-Healing Operations | Custom | Y | 29% uncompiled workflows, 108 defer patterns, zero repair commands |
| 2025-12-09 | Code Organization | Standard | N | 267 Go files, 48 exceed 500 lines, 82.5% oversized API |
| 2025-12-10 | Performance | Standard | N | 85% uncached regex, 694-line bottleneck, zero parallelization |
| 2025-12-11 | Workflow Lifecycle Management | Custom | Y | 46 uncompiled workflows, timestamp-based staleness only |
| 2025-12-12 | Workflow Cost Optimization | Custom | Y | 173 workflows with zero budget config, no cost prediction |
| 2025-12-15 | MCP Server Debugging Observability | Custom | Y | 21K LOC MCP code, 16 debug loggers, zero health checks |
| 2025-12-16 | Error Message Actionability | Custom | Y | 1,311 error points, only 2.1% use console formatting |
| 2025-12-17 | Documentation | Standard | N | 73-line README, 64 docs pages, 0% package-level docs |
| 2025-12-18 | CI/CD | Standard | N | 131 workflows, 99.7% SHA-pinned actions, 15-job critical path |
| 2025-12-19 | Workflow Validation UX | Custom | Y | 19 validation modules, only 30% console formatting |

</details>

---

## 🎯 Recommendations

### Immediate Actions (This Week)
1. **Implement license compliance scanning** - Priority: High - Prevent license conflicts before they become legal issues
2. **Standardize GitHub Actions versions** - Priority: High - Reduce maintenance burden and security exposure

### Short-term Actions (This Month)
1. **Reduce v0.x dependency exposure** - Priority: Medium - Mitigate breaking change risk in production
2. **Add tools.go for build tools** - Priority: Medium - Ensure consistent tooling across environments

### Long-term Actions (This Quarter)
1. **Implement dependency dashboard** - Priority: Low - Improve visibility into dependency health
2. **Set up automated dependency aging alerts** - Priority: Low - Proactive dependency maintenance

---

## 📈 Success Metrics

Track these metrics to measure improvement in the **Dependencies** focus area:

- **v0.x Dependency Ratio**: 56% → <30% (reduce unstable dependencies)
- **GitHub Actions Version Consistency**: 7 checkout versions → 1 version (eliminate sprawl)
- **License Compliance**: No scanning → 100% scanned (prevent license conflicts)
- **Dependency Age**: Unknown → <90 days median (keep dependencies fresh)
- **Security Advisory MTTR**: Unknown → <7 days (rapid security response)
- **Tool Version Consistency**: No tracking → 100% tracked via tools.go

---

## Next Steps

1. Review and prioritize the tasks above
2. Assign tasks to Copilot agent via planner agent
3. Track progress on improvement items
4. Re-evaluate this focus area in 3 months or when metrics improve significantly

---

*Generated by Repository Quality Improvement Agent*  
*Next analysis: 2025-12-23 - Focus area will be selected based on diversity algorithm*


> AI generated by [Repository Quality Improvement Agent](https://github.com/githubnext/gh-aw/actions/runs/20432946442)

[pelikhan]

/plan

[github-actions[bot]]

🎉 Yo ho ho! Plan Command found the treasure and completed successfully! ⚓💰

[github-actions[bot]]

Planning Complete ✅

I've created a comprehensive implementation plan for the dependency management improvements identified in this quality report.

Parent Tracking Issue

Issue #aw_7251dep0a1b2: Improve dependency management and security posture

This parent issue tracks all related work and links back to this discussion.

Implementation Plan (5 Sub-Issues)

1. Add license compliance scanning - Implement go-licenses for automated license compliance checking
2. Standardize GitHub Actions versions - Eliminate version sprawl across 122 workflow files (7→1 checkout versions)
3. Add tools.go for build tools - Track build-time dependencies for consistent dev/CI environments
4. Reduce v0.x dependency exposure - Lower unstable dependency ratio from 56% to <30%
5. Add dependency health CLI - Create gh aw deps commands for visibility and monitoring

Success Metrics

• v0.x dependencies: 56% → <30%
• GitHub Actions consistency: 7 versions → 1 version
• License compliance: 0% → 100% scanned
• Tool tracking: None → 100% via tools.go

Each sub-issue contains detailed implementation guidance, acceptance criteria, and specific file changes needed for GitHub Copilot agents to execute.

The plan prioritizes high-impact, low-effort improvements first (license scanning, action standardization) before tackling larger efforts (v0.x reduction).

AI generated by Plan Command for discussion #7251