[typist] Go Type Consistency Analysis

[github-actions[bot]]

Analysis of repository: github/gh-aw | Run: §25107280023 | Date: 2026-04-29

Executive Summary

729 non-test Go files were analyzed across the pkg/ directory. The codebase demonstrates strong typing discipline overall — named semantic types (JobName, StepID, EngineName, PermissionLevel, etc.) are used consistently in pkg/constants/. One cross-package struct duplication was found (ContainerPin), three platform-split structs are intentional and not actionable, 1,540+ map[string]any usages are legitimate YAML frontmatter handling, and two untyped numeric constants could benefit from explicit types. No interface{} usages were found in the production code.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total exported struct types: 508
• Duplicate name clusters found: 4
• True cross-package duplicate: 1 (ContainerPin)
• Intentional platform splits (WASM vs non-WASM): 3 (RepositoryFeatures, ProgressBar, SpinnerWrapper)

---

Cluster 1: ContainerPin — Cross-Package Duplicate

Type: Exact duplicate
Occurrences: 2
Impact: Medium — identical struct defined in two packages; type conversion required between them

Locations:

1. pkg/actionpins/actionpins.go:45
2. pkg/workflow/action_cache.go:33

Definition Comparison (identical fields and JSON tags):

// pkg/actionpins/actionpins.go:45
type ContainerPin struct {
    Image       string `json:"image"`
    Digest      string `json:"digest"`
    PinnedImage string `json:"pinned_image"`
}

// pkg/workflow/action_cache.go:33
type ContainerPin struct {
    Image       string `json:"image"`
    Digest      string `json:"digest"`
    PinnedImage string `json:"pinned_image"`
}

Evidence of the problem — pkg/workflow/action_pins.go:94 performs an explicit type conversion because they are distinct types:

return ContainerPin(pin), true  // converting actionpins.ContainerPin → workflow.ContainerPin

The workflow package already re-exports three other actionpins types as aliases in pkg/workflow/action_pins.go:

type ActionYAMLInput = actionpins.ActionYAMLInput
type ActionPin        = actionpins.ActionPin
type ActionPinsData   = actionpins.ActionPinsData

ContainerPin was simply omitted from this list.

Recommendation:

• Add type ContainerPin = actionpins.ContainerPin to pkg/workflow/action_pins.go
• Remove the ContainerPin definition from pkg/workflow/action_cache.go
• The type conversion ContainerPin(pin) in action_pins.go:94 becomes a no-op and can be removed
• Estimated effort: 15 minutes
• Benefits: Eliminates silent type conversion; single source of truth; consistent with existing alias pattern

---

Clusters 2–4: Intentional Platform Splits (Not Actionable)

The following duplicate names are build-tag-separated implementations (//go:build !js && !wasm vs //go:build js || wasm) and are intentional:

Type	Non-WASM file	WASM file
RepositoryFeatures	pkg/workflow/repository_features_validation.go:57	pkg/workflow/repository_features_validation_wasm.go:5
ProgressBar	pkg/console/progress.go:31	pkg/console/progress_wasm.go:7
SpinnerWrapper	pkg/console/spinner.go:96	pkg/console/spinner_wasm.go:10

These are correct Go patterns for platform-specific implementations and require no action.

---

Untyped Usages

Summary Statistics

• interface{} usages: 0 (none found in production code)
• any usages (type positions): ~2,049 (almost entirely in YAML/JSON processing)
• Untyped numeric constants: 2 candidates
• Untyped boolean constant: 1 candidate

---

Category 1: map[string]any — YAML Frontmatter (Appropriate but Improvable)

Impact: Low — current usage is correct; naming could improve readability

The codebase uses map[string]any pervasively (~1,540 occurrences) for YAML frontmatter processing. This is correct: YAML unmarshaling into map[string]any is the standard Go idiom when schema is dynamic. The primary type is FrontmatterResult.Frontmatter:

// pkg/parser/frontmatter_content.go:17
type FrontmatterResult struct {
    Frontmatter map[string]any
    Markdown    string
    ...
}

The map[string]any flows from here through ~40+ functions in pkg/parser/ and pkg/workflow/ (e.g., func ConvertStepToYAML(stepMap map[string]any), func extractJobsFromFrontmatter(frontmatter map[string]any) map[string]any).

Potential improvement (optional, low priority):

// In pkg/parser or pkg/workflow, a named alias would clarify intent:
type Frontmatter = map[string]any

This would make 1,540+ function signatures self-documenting, but carries substantial churn.

---

Category 2: Untyped Rate Limit Constants

Impact: Medium — ambiguous units; inconsistent with codebase's strong-typing conventions

Location: pkg/constants/job_constants.go:211-212

// Current (ambiguous — what are the units?)
const DefaultRateLimitMax    = 5   // Default maximum runs per time window
const DefaultRateLimitWindow = 60  // Default time window in minutes (1 hour)

The codebase already defines LineLength int for semantically-typed integers and uses time.Duration for timeouts in constants.go. The window value's unit (minutes) is only communicated via comment.

Suggested fix:

// Option A: explicit primitive types
const DefaultRateLimitMax    int = 5
const DefaultRateLimitWindow int = 60 // minutes

// Option B: semantic type (consistent with LineLength, JobName patterns)
type RateLimitCount int
type RateLimitWindowMinutes int

const DefaultRateLimitMax    RateLimitCount         = 5
const DefaultRateLimitWindow RateLimitWindowMinutes = 60

Benefits: Prevents silent unit mismatch; consistent with codebase conventions
Estimated effort: 30 minutes (type + update callers)

---

Category 3: Untyped Boolean Constant

Impact: Low

Location: pkg/constants/constants.go:111

// Current
const DefaultGitHubLockdown = false

// Suggested
const DefaultGitHubLockdown bool = false

A minor improvement — explicit bool type makes the constant's type visible without hovering.

---

Category 4: Untyped Output Name Constants

Impact: Low

Location: pkg/constants/job_constants.go:198-208

const IsTeamMemberOutput         = "is_team_member"
const StopTimeOkOutput           = "stop_time_ok"
const SkipCheckOkOutput          = "skip_check_ok"
// ... 8 more

The codebase has StepID string, JobName string, MCPServerID string as typed string identifiers. A parallel type OutputName string could make these type-safe, but the scope of changes to call sites is significant.

Recommendation: Skip unless output names are being misused in practice. The existing pattern of untyped string constants for output names is common in Go and does not create runtime risk here.

---

Refactoring Recommendations

Priority 1: High — Fix ContainerPin Duplicate

Action: Add alias in pkg/workflow/action_pins.go, remove from pkg/workflow/action_cache.go

// Add to pkg/workflow/action_pins.go (alongside existing aliases)
type ContainerPin = actionpins.ContainerPin

// Remove from pkg/workflow/action_cache.go (lines 30-37)
// type ContainerPin struct { ... }

Also remove the now-redundant type conversion in pkg/workflow/action_pins.go:94:

// Before
return ContainerPin(pin), true
// After
return pin, true

Estimated effort: 15 minutes
Risk: Very low — pure alias; callers are unaffected

---

Priority 2: Medium — Type Rate Limit Constants

Action: Add explicit types to DefaultRateLimitMax and DefaultRateLimitWindow

Estimated effort: 30 minutes
Risk: Low — may require minor caller updates if they assign to typed variables

---

Priority 3: Low — Minor Constant Improvements

Apply at your discretion alongside other changes:

• DefaultGitHubLockdown bool = false
• DefaultMCPGatewayPayloadSizeThreshold int64 = 524288

---

Implementation Checklist

• Add type ContainerPin = actionpins.ContainerPin alias to pkg/workflow/action_pins.go
• Remove ContainerPin struct from pkg/workflow/action_cache.go
• Remove type conversion ContainerPin(pin) in pkg/workflow/action_pins.go:94
• Add explicit integer types to DefaultRateLimitMax and DefaultRateLimitWindow
• (Optional) Add bool type to DefaultGitHubLockdown
• Run go build ./... to verify

Analysis Metadata

• Total Go Files Analyzed: 729 non-test files in pkg/
• Total Exported Struct Types: 508
• Duplicate Clusters: 4 (1 actionable, 3 intentional platform splits)
• interface{} usages: 0
• any usages: ~2,049 (appropriate for YAML/JSON processing)
• Untyped Constant Candidates: 3 (2 medium-priority, 1 low-priority)
• Detection Method: Pattern matching (grep) + file analysis
• Analysis Date: 2026-04-29

References:

• §25107280023

Generated by Typist - Go Type Analysis · ● 370.8K · ◷

• expires on Apr 30, 2026, 12:00 PM UTC