Typist - Go Type Consistency Analysis

[github-actions[bot]]

Analysis of repository: github/gh-aw | Run: §22303802656 | Date: 2026-02-23

Executive Summary

Analysis of 558 non-test Go files across 18 packages in pkg/ reveals a codebase that has already invested significantly in type safety — pkg/constants uses 12 custom semantic types covering versions, URLs, job names, engine names, and more. The main refactoring opportunities are 35 untyped string constants and 6 untyped numeric constants in constants.go that could benefit from the same treatment applied to their neighbors, plus targeted any/map[string]any usages that could be progressively strengthened. No true type duplication was found; the three apparent duplicate type names are all intentional build-tag-separated (wasm vs non-wasm) implementations.

Total findings: 0 type duplicates, 1 interface{} usage (wasm compatibility stub), 297 files using any (mostly justified YAML parsing), 41 untyped constants with clear typing opportunities.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total type definitions analyzed: ~350 across 558 files
• Duplicate clusters found: 3 apparent duplicates
• True duplicates: 0
• Build-tag variants (intentional): 3

Cluster 1: SpinnerWrapper — Build-Tag Variant

Classification: Intentional platform split — NOT a duplicate
Files:

1. pkg/console/spinner.go — //go:build !js && !wasm — Full implementation using charmbracelet
2. pkg/console/spinner_wasm.go — //go:build js || wasm — Stub for WASM environments

Assessment: Correct Go pattern for platform-specific implementations. No action required.

---

Cluster 2: ProgressBar — Build-Tag Variant

Classification: Intentional platform split — NOT a duplicate
Files:

1. pkg/console/progress.go — //go:build !js && !wasm
2. pkg/console/progress_wasm.go — //go:build js || wasm

Assessment: Same pattern as SpinnerWrapper. No action required.

---

Cluster 3: RepositoryFeatures — Build-Tag Variant

Classification: Intentional platform split — NOT a duplicate
Files:

1. pkg/workflow/repository_features_validation.go — //go:build !js && !wasm — Full implementation
2. pkg/workflow/repository_features_validation_wasm.go — //go:build js || wasm — Stub with ClearRepositoryFeaturesCache() {}

Assessment: Expected pattern. No action required.

---

Notable Non-Duplicate: MCPServerConfig

Both pkg/parser and pkg/workflow define MCPServerConfig, but this is architecturally sound:

• Both embed types.BaseMCPServerConfig from the shared pkg/types package
• parser.MCPServerConfig adds: Name, Registry, ProxyArgs, Allowed (JSON tags, parsing context)
• workflow.MCPServerConfig adds: Mode, Toolsets, CustomFields (YAML tags, compilation context)

The pkg/types.BaseMCPServerConfig shared base is itself evidence of proactive type consolidation already done.

---

Untyped Usages

Summary Statistics

• interface{} usages: 1
• any usages (files): 297 (predominantly justified YAML parsing)
• Untyped string constants: 35
• Untyped numeric constants: 6
• Total actionable locations: ~41 constant declarations

---

Category 1: The Single interface{} Usage

Location: pkg/console/layout_wasm.go:16
Impact: Low — WASM stub only; signature inconsistency with non-wasm version

// layout_wasm.go (//go:build js || wasm)
func LayoutEmphasisBox(content string, color interface{}) string {
    // WASM stub — color parameter is ignored
    marker := strings.Repeat("!", len(content)+4)
    return marker + "\n  " + content + "\n" + marker
}

// layout.go (//go:build !js && !wasm)
func LayoutEmphasisBox(content string, color lipgloss.AdaptiveColor) string {
    // Full implementation using lipgloss
}

Issue: The WASM stub uses interface{} (old style) instead of any (Go 1.18+). The parameter is intentionally ignored since lipgloss isn't available in WASM.

Suggested fix:

func LayoutEmphasisBox(content string, color any) string {

Benefits: Consistent with modern Go style (any vs interface{}); no functional change needed.
Effort: 1 line change.

---

Category 2: Justified map[string]any Usages (YAML/JSON Parsing)

The widespread use of map[string]any in the workflow and parser packages is largely justified by the nature of YAML frontmatter — it is inherently dynamic. The codebase already demonstrates awareness of this tradeoff:

Already well-typed (these are NOT issues):

• pkg/workflow/tools_types.go — ToolsConfig wraps map[string]any with a structured typed API and explicit // ToMap() for backward compatibility. Comments explain the reasoning at lines 13–20.
• pkg/workflow/frontmatter_types.go:92 — Comment explicitly notes: "This provides compile-time type safety and clearer error messages compared to map[string]any", with inline explanations on each remaining map[string]any field (e.g., // Legacy field, // too dynamic to type, // Deprecated).
• pkg/workflow/tools_types.go:343 — CustomFields map[string]any has an explicit comment: // For truly dynamic configuration (server-specific fields not covered above).

Partially addressable:

Example: SafeInputParam.Default any — pkg/workflow/safe_inputs_parser.go:46

// Current
type SafeInputParam struct {
    Type        string
    Description string
    Required    bool
    Default     any    // Default value — could be string, number, bool, null
}

The Default field represents a JSON schema default value, which by the JSON Schema spec can be any type. Using any is correct here, though a json.RawMessage alternative could provide better serialization control:

Default json.RawMessage `json:"default,omitempty"` // JSON-typed default

Effort: Medium — requires updating all callers that set/read Default.

Example: DevcontainerVSCode.Settings map[string]any — pkg/cli/devcontainer.go:27

type DevcontainerVSCode struct {
    Settings   map[string]any `json:"settings,omitempty"` // VSCode settings are arbitrary JSON
    Extensions []string       `json:"extensions,omitempty"`
}

VSCode settings are extensible and arbitrary — this is a justified use case. No action needed.

Example: DevcontainerFeatures map[string]any — pkg/cli/devcontainer.go:39

type DevcontainerFeatures map[string]any

The DevContainer Features specification defines feature options as arbitrary JSON — the any value is spec-mandated. No action needed.

---

Category 3: Untyped Constants — High Value Opportunity

The pkg/constants/constants.go file shows a clear evolution toward typed constants: 39 constants already use typed declarations (e.g., Version, URL, JobName, ModelName). However, 35 untyped string constants and 6 untyped numeric constants remain that follow similar patterns to already-typed neighbors.

Group A: Output Name Constants (10 untyped strings, lines 682–691)

// Current — untyped
const IsTeamMemberOutput = "is_team_member"
const StopTimeOkOutput = "stop_time_ok"
const SkipCheckOkOutput = "skip_check_ok"
const SkipNoMatchCheckOkOutput = "skip_no_match_check_ok"
const CommandPositionOkOutput = "command_position_ok"
const MatchedCommandOutput = "matched_command"
const RateLimitOkOutput = "rate_limit_ok"
const SkipRolesOkOutput = "skip_roles_ok"
const SkipBotsOkOutput = "skip_bots_ok"
const ActivatedOutput = "activated"

// Suggested — typed (consistent with JobName, StepID pattern)
type OutputName string

const IsTeamMemberOutput OutputName = "is_team_member"
const StopTimeOkOutput OutputName = "stop_time_ok"
// ... etc

Benefits: Prevents accidentally mixing output names with arbitrary strings at call sites. Consistent with the existing StepID and JobName typed constants pattern.
Used in: 19 locations across pkg/workflow and pkg/cli.

---

Group B: MCP Server ID Constants (3 untyped strings, lines 648–657)

// Current — untyped
const SafeOutputsMCPServerID = "safeoutputs"
const SafeInputsMCPServerID = "safeinputs"
const AgenticWorkflowsMCPServerID = "agenticworkflows"

// Suggested — typed
type MCPServerID string

const SafeOutputsMCPServerID MCPServerID = "safeoutputs"
const SafeInputsMCPServerID MCPServerID = "safeinputs"
const AgenticWorkflowsMCPServerID MCPServerID = "agenticworkflows"

Benefits: Prevents passing arbitrary strings where an MCP server ID is expected. These are used in 15+ locations in string concatenation for YAML generation — typing them would make the intent clear.

---

Group C: Artifact Name Constants (3 untyped strings, lines 641–645)

// Current — untyped
const SafeOutputArtifactName = "safe-output"
const AgentOutputArtifactName = "agent-output"
const AgentOutputFilename = "agent_output.json"

// Suggested — typed
type ArtifactName string

const SafeOutputArtifactName ArtifactName = "safe-output"
const AgentOutputArtifactName ArtifactName = "agent-output"
// AgentOutputFilename could remain string (it's a filename, not an artifact name)

---

Group D: Version Constant Missing Type (1 untyped string, line 654)

// Current — untyped (all neighboring Version constants ARE typed)
const SafeInputsMCPVersion = "1.0.0"

// Suggested — uses existing Version type
const SafeInputsMCPVersion Version = "1.0.0"

This is inconsistent with DefaultClaudeCodeVersion Version, DefaultGitHubMCPServerVersion Version, and 20+ other version constants that are correctly typed. Likely an oversight.

---

Group E: Rate Limit Constants (2 untyped ints, lines 694–695)

// Current — untyped, comments explain units
const DefaultRateLimitMax = 5     // Default maximum runs per time window
const DefaultRateLimitWindow = 60 // Default time window in minutes (1 hour)

// Suggested — unit-carrying types prevent confusion
type RunCount int
type Minutes int

const DefaultRateLimitMax RunCount = 5
const DefaultRateLimitWindow Minutes = 60

Benefits: Eliminates ambiguity about units (minutes vs seconds vs hours). The comment currently carries semantic weight that a type could encode.

---

Group F: MaxTimeDeltaX Constants — pkg/workflow/time_delta.go:484–498

// Current — untyped ints in a const block
const (
    MaxTimeDeltaMonths  = 12
    MaxTimeDeltaWeeks   = 52
    MaxTimeDeltaDays    = 365
    MaxTimeDeltaHours   = 8760
    MaxTimeDeltaMinutes = 525600
)

// Suggested — reuse existing numeric field type from TimeDelta struct
// OR introduce a simple semantic type
type TimeDeltaLimit int

const (
    MaxTimeDeltaMonths  TimeDeltaLimit = 12
    MaxTimeDeltaWeeks   TimeDeltaLimit = 52
    MaxTimeDeltaDays    TimeDeltaLimit = 365
    MaxTimeDeltaHours   TimeDeltaLimit = 8760
    MaxTimeDeltaMinutes TimeDeltaLimit = 525600
)

Benefits: Prevents accidentally using time limits as counts or other integer values.

---

Group G: Container Image and Path Constants (14 untyped strings)

// Container images — untyped
const DefaultMCPGatewayContainer = "ghcr.io/github/gh-aw-mcpg"
const DefaultSerenaMCPServerContainer = "ghcr.io/github/serena-mcp-server"
const DefaultNodeAlpineLTSImage = "node:lts-alpine"
// ... etc

// Paths — untyped
const AWFProxyLogsDir = "/tmp/gh-aw/sandbox/firewall/logs"
const DefaultMCPGatewayPayloadDir = "/tmp/gh-aw/mcp-payloads"

Assessment: These are lower priority. Container image references are strings by convention and adding a ContainerImage string type would require updating all Docker-related code. The DocURL type already exists for documentation URLs. Consider a ContainerImage string type for the container constants to match the existing URL type pattern.

---

Refactoring Recommendations

Priority 1: Quick Win — Fix interface{} to any

File: pkg/console/layout_wasm.go:16
Change: color interface{} → color any
Effort: 1 line, 0 functional impact, modernizes to Go 1.18+ idiom

---

Priority 2: High Value — Type the SafeInputsMCPVersion Constant

File: pkg/constants/constants.go:654
Change: const SafeInputsMCPVersion = "1.0.0" → const SafeInputsMCPVersion Version = "1.0.0"
Effort: 1 line — fixes obvious inconsistency with 20+ neighboring typed Version constants

---

Priority 3: Medium — Type Output Name Constants

File: pkg/constants/constants.go:682–691
Change: Add type OutputName string, apply to 10 constants
Effort: ~15 lines in constants.go + verify ~19 usage sites accept string conversion
Benefits: Compile-time protection against string mix-up at output-name-sensitive call sites

---

Priority 4: Medium — Type MCP Server ID Constants

File: pkg/constants/constants.go:648–657
Change: Add type MCPServerID string, apply to 3 constants
Effort: ~10 lines in constants.go + review 15 usage sites (many use string concatenation in YAML builders — may require .String() calls)
Note: Usage in string concatenation ("[mcp_servers." + constants.SafeOutputsMCPServerID + "]") would require string(constants.SafeOutputsMCPServerID) or a .String() method

---

Priority 5: Low — Type Artifact Names and Rate Limit Constants

Files: pkg/constants/constants.go:641–645, 694–695
Effort: Small — add 2 types, update ~5 constants each
Benefits: Semantic clarity; rate limit typing prevents unit confusion

---

Implementation Checklist

• Fix interface{} → any in pkg/console/layout_wasm.go:16
• Add Version type to SafeInputsMCPVersion in pkg/constants/constants.go:654
• Add OutputName string type and apply to 10 output constants (lines 682–691)
• Add MCPServerID string type and apply to 3 MCP server ID constants (lines 648–657)
• Add ArtifactName string type for artifact name constants (lines 641–642)
• Add types to DefaultRateLimitMax and DefaultRateLimitWindow (lines 694–695)
• Evaluate TimeDeltaLimit type for MaxTimeDeltaX constants in pkg/workflow/time_delta.go
• Run full test suite after each change batch

---

Analysis Metadata

Metric	Value
Total Go files analyzed	558 (non-test, in pkg/)
Packages covered	18
True type duplicates	0
Build-tag variants (false positives)	3
interface{} usages	1
Files using any	297
Actionable any usages	~2 (low priority)
Untyped string constants	35
Untyped numeric constants	6
Already-typed constants	39
Detection method	Serena semantic analysis + grep pattern matching

References:

• §22303802656

AI generated by Typist - Go Type Analysis

• expires on Feb 24, 2026, 11:25 AM UTC

[pelikhan]

/plan