Typist - Go Type Consistency Analysis

[github-actions[bot]]

Analysis of repository: github/gh-aw — §23434646322

Executive Summary

601 non-test Go source files in pkg/ were analyzed. The codebase demonstrates strong awareness of type safety concerns — pkg/workflow/tools_types.go contains explicit in-code comments documenting an in-progress migration away from the pervasive map[string]any pattern toward typed structs. No use of legacy interface{} was found (0 occurrences). The four identified "duplicate" struct names are all intentional build-tag patterns (WASM vs. native), not accidental duplication. The primary refactoring opportunities are the 1,413 map[string]any usages for YAML frontmatter/tools parsing, three untyped numeric constants in pkg/constants/constants.go, and one struct field that could use a richer type.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

Metric	Count
Total non-test Go files analyzed	601
Total struct type definitions	467
Struct names appearing more than once	4
True (accidental) duplicates	0
Build-tag duplicates (intentional)	4
Packages with shared base type already in place	1 (pkg/types)

Cluster 1: ProgressBar and SpinnerWrapper — Build-tag pattern (intentional)

Type: Platform-specific implementation split
Occurrences: 2 each
Verdict: ✅ Intentional — standard Go idiom for WASM compatibility

File	Build tag	Purpose
pkg/console/progress.go:31	(default)	Full implementation using bubbles/progress model
pkg/console/progress_wasm.go:7	//go:build js || wasm	Stub with no-op fields
pkg/console/spinner.go:96	(default)	Full implementation with tea.Program, mutex, waitgroup
pkg/console/spinner_wasm.go:10	//go:build js || wasm	Minimal stub (enabled bool only)

This is a correct idiomatic Go pattern. No action needed.

---

Cluster 2: RepositoryFeatures — Build-tag pattern (intentional)

Type: WASM stub for live feature detection
Occurrences: 2
Verdict: ✅ Intentional

File	Build tag	Fields
pkg/workflow/repository_features_validation.go:57	(default)	HasDiscussions bool, HasIssues bool
pkg/workflow/repository_features_validation_wasm.go:5	//go:build js || wasm	Same fields, but validateRepositoryFeatures is a no-op

Fields are identical and the WASM stub is a compile-time placeholder. No action needed.

---

Cluster 3: MCPServerConfig — Different types with shared base (by design)

Type: Purposeful domain separation, shared base already extracted
Occurrences: 2
Verdict: ✅ Well-structured — pkg/types.BaseMCPServerConfig already consolidates shared fields

File	Package	Purpose	Extra fields
pkg/workflow/tools_types.go:380	workflow	Workflow execution config	Mode, Toolsets, GuardPolicies map[string]any, CustomFields map[string]any
pkg/parser/mcp.go:35	parser	MCP inspection/parsing config	Name, Registry, ProxyArgs, Allowed

Both embed types.BaseMCPServerConfig which lives in pkg/types/mcp.go. The shared base pattern is already implemented correctly. The remaining map[string]any fields (GuardPolicies, CustomFields) are covered below.

---

Untyped Usages

Summary Statistics

Category	Count
interface{} usages	0
map[string]any usages (total)	1,413
Struct fields typed as map[string]any	~5
Untyped numeric constants	6
Type aliases for map[string]any	2

---

Category 1: map[string]any for YAML frontmatter parsing — in-progress migration

Impact: Medium — codebase is already aware and partially migrated
Location: Predominantly pkg/workflow/

The files with the highest concentration:

File	Count
pkg/workflow/compiler_safe_outputs_config.go	49
pkg/workflow/frontmatter_types.go	42
pkg/workflow/safe_outputs_tools_filtering.go	38
pkg/workflow/compiler_orchestrator_workflow.go	37
pkg/workflow/trigger_parser.go	31

The codebase already documents this as an active migration target. pkg/workflow/tools_types.go contains these explicit comments at lines 13 and 20:

// This type provides a structured alternative to the pervasive map[string]any pattern.
// ...
// by replacing map[string]any with strongly-typed configuration structs.

ToolsConfig (introduced in tools_types.go) provides a typed wrapper with ParseToolsConfig(map[string]any) and ToMap() map[string]any converters for backward compatibility. The migration pattern is already established — continuing to push call sites toward *ToolsConfig will progressively reduce map[string]any usage.

Recommendation: Continue the existing migration, focusing on these high-value sites:

1. pkg/workflow/compiler_orchestrator_workflow.go — Functions like extractYAMLSections, processAndMergeSteps, and processAndMergeServices all accept frontmatter map[string]any. A typed FrontmatterData struct (partially represented already by WorkflowData) could replace the raw map.

2. pkg/workflow/compiler_safe_outputs_config.go — handlerBuilder func(*SafeOutputsConfig) map[string]any (line 132) returns a raw map. Returning a dedicated SafeOutputsHandlerResult struct would eliminate downstream type assertions.

3. pkg/workflow/frontmatter_types.go — Already has strongly typed structs like RuntimesConfig and GitHubActionsPermissionsConfig. Remaining map[string]any usages are likely in parsing glue code that could adopt these types.

---

Category 2: Struct fields typed as map[string]any

Impact: Low-Medium — these are in boundary/integration types

Example 1: MCPServerConfig.GuardPolicies and CustomFields

• Location: pkg/workflow/tools_types.go:391-394
• Current:

  GuardPolicies map[string]any `yaml:"guard-policies,omitempty"`
  CustomFields  map[string]any `yaml:",inline"`

• Context: GuardPolicies is explicitly noted as server-specific and extensible. CustomFields is an inline catch-all for unknown YAML keys.
• Verdict: CustomFields (inline catch-all) is acceptable. GuardPolicies could benefit from a typed base interface:

  type GuardPolicy interface{ guardPolicy() }
  GuardPolicies map[string]GuardPolicy `yaml:"guard-policies,omitempty"`

  However, this requires all policy types to implement the marker interface.
• Estimated effort: 3-4 hours
• Priority: Low

Example 2: MCPToolDefinition.InputSchema

• Location: pkg/workflow/mcp_scripts_generator.go:20
• Current:

  type MCPToolDefinition struct {
      InputSchema map[string]any `json:"inputSchema"`
      ...
  }

• Context: InputSchema represents a JSON Schema object, which is inherently dynamic and polymorphic. This is a widely-accepted pattern for JSON Schema embedding in Go.
• Verdict: Acceptable as-is. Could use a json.RawMessage or a dedicated JSONSchema type if validation is needed.
• Priority: Very Low

Example 3: DevcontainerFeatures type alias

• Location: pkg/cli/devcontainer.go:39
• Current:

  type DevcontainerFeatures map[string]any

• Context: Dev container features are key-value configuration objects defined by the devcontainer spec. Values can be booleans, strings, or nested objects.
• Verdict: Acceptable — the map[string]any is hidden behind a named type, which is the right approach.
• Priority: Very Low

---

Category 3: Untyped numeric constants

Impact: Low — clarity and misuse prevention

Location: pkg/constants/constants.go

Line	Constant	Value	Issue	Suggested Fix
392	DefaultMCPGatewayPayloadSizeThreshold	524288	Unitless bytes value	type ByteSize int64; const DefaultMCPGatewayPayloadSizeThreshold ByteSize = 524288
739	DefaultRateLimitMax	5	Unitless count	type RunCount int; const DefaultRateLimitMax RunCount = 5
740	DefaultRateLimitWindow	60	Comment says "minutes" but type is int	Use time.Duration: const DefaultRateLimitWindow = 60 * time.Minute
1069	MaxSymlinkDepth	5	Unitless depth count	Acceptable as int given context; a comment suffices

The highest-value fix is DefaultRateLimitWindow — the comment says "Default time window in minutes (1 hour)" but the raw integer could be accidentally used as seconds elsewhere:

// Current
const DefaultRateLimitMax = 5     // Default maximum runs per time window
const DefaultRateLimitWindow = 60 // Default time window in minutes (1 hour)

// Suggested
const DefaultRateLimitMax = 5
const DefaultRateLimitWindow = 60 * time.Minute

Estimated effort: 30-60 minutes
Priority: Medium (prevents unit confusion bugs)

---

Refactoring Recommendations

Priority 1: Medium — Convert DefaultRateLimitWindow to time.Duration

File: pkg/constants/constants.go:740
Risk: Low — isolated constant
Steps:

1. Change declaration to const DefaultRateLimitWindow = 60 * time.Minute
2. Find all usages and verify they expect a time.Duration
3. Run tests

---

Priority 2: Medium — Continue ToolsConfig migration in compiler_orchestrator_workflow.go

File: pkg/workflow/compiler_orchestrator_workflow.go
Risk: Medium — central orchestration logic
Steps:

1. Update function signatures from frontmatter map[string]any to use structured types where possible
2. Use ToolsConfig wrapper where tools maps are extracted
3. Run the full test suite

---

Priority 3: Low — Type handlerBuilder return value

File: pkg/workflow/compiler_safe_outputs_config.go:132
Current: type handlerBuilder func(*SafeOutputsConfig) map[string]any
Risk: Low — internal type
Steps:

1. Introduce a SafeOutputsHandlerResult struct capturing the fields currently returned as a raw map
2. Update all handler implementations

---

Implementation Checklist

• Change DefaultRateLimitWindow to use time.Duration (quick win)
• Audit usages of DefaultRateLimitWindow across pkg/ for unit mismatches
• Identify next map[string]any frontmatter parameter to migrate using ToolsConfig pattern
• Consider typed GuardPolicy interface for MCPServerConfig.GuardPolicies
• Run full test suite after each incremental change

---

Analysis Metadata

Metric	Value
Total Go files analyzed	601
Total struct definitions	467
Duplicate struct name clusters	4 (all intentional)
interface{} usages	0
map[string]any usages	1,413
Untyped numeric constants	6
Detection method	Serena semantic analysis + pattern matching
Analysis date	2026-03-23

References: §23434646322

AI generated by Typist - Go Type Analysis · history

• expires on Mar 24, 2026, 11:23 AM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Typist - Go Type Analysis.

A newer discussion is available at Discussion #22655.