Typist - Go Type Consistency Analysis

[github-actions[bot]]

This report analyzes all 607 non-test Go source files in pkg/ for duplicated type definitions and untyped usages. The codebase demonstrates clear architectural awareness of typing concerns — a shared pkg/types base package exists and FrontmatterConfig already comments on specific map[string]any fields explaining their necessity. The primary opportunities are consistency improvements (untyped constants in groups where peers are already typed) and targeted reduction of map[string]any in areas where structure is known.

The 4 duplicate struct name pairs are all intentional build-tag separated implementations (wasm vs native), not true duplicates. The largest refactoring surface is in map[string]any usage across 249 files, most of which reflects genuinely dynamic YAML parsing — but a notable subset can be improved.

Summary

Metric	Value
Total non-test Go files analyzed	607
Exported type definitions	479
map[string]any occurrences	1,438 (in 249 files)
[]any occurrences	274
Duplicate struct name clusters	4 (all wasm/native split)
Untyped output-name string constants	11
Untyped container/image string constants	9
Refactoring priority items identified	3

Full Analysis Report

Duplicated Type Definitions

Cluster 1: MCPServerConfig — Intentional Domain Split ✅

Type: Near-duplicate with shared base
Occurrences: 2
Verdict: Architecture is correct — not a refactoring target

Location	Purpose
pkg/parser/mcp.go:35	Parser-specific: adds Name, Registry, ProxyArgs, Allowed
pkg/workflow/tools_types.go:489	Workflow-specific: adds Mode, Toolsets, GuardPolicies, CustomFields

Both embed types.BaseMCPServerConfig from pkg/types, which is already the correct pattern for shared fields. No action needed.

---

Cluster 2: ProgressBar — Platform Build-Tag Split ✅

Type: Wasm vs native implementation
Verdict: Intentional, not a refactoring target

Location	Build Constraint
pkg/console/progress.go:31	//go:build !js && !wasm
pkg/console/progress_wasm.go:7	//go:build js || wasm

Same pattern applies to SpinnerWrapper in pkg/console/spinner.go and pkg/console/spinner_wasm.go.

---

Cluster 3: RepositoryFeatures — Identical Struct in Build-Tag Split ⚠️

Type: Identical struct in two files
Occurrences: 2

Location	Build Constraint
pkg/workflow/repository_features_validation.go:57	(no constraint — native)
pkg/workflow/repository_features_validation_wasm.go:5	//go:build js || wasm

// Both files define the exact same struct:
type RepositoryFeatures struct {
    HasDiscussions bool
    HasIssues      bool
}

Unlike ProgressBar/SpinnerWrapper, the struct body is 100% identical between wasm and native. The difference is only the validateRepositoryFeatures function — wasm returns nil immediately.

Recommendation: Extract the RepositoryFeatures struct to a shared file without build constraints, keeping only validateRepositoryFeatures in the build-tag-separated files.

• Estimated effort: 30 minutes
• Impact: Low — eliminates one definition, minor maintenance improvement

---

Untyped Usages

Category 1: Output Name Constants — Missing Semantic Type (High Value)

The pkg/constants/constants.go file defines strongly typed constants for StepID, JobName, WorkflowID, EngineName, MCPServerID, etc. However, 11 output name constants are bare untyped strings:

// Current — untyped, can be mixed with arbitrary strings
const IsTeamMemberOutput = "is_team_member"       // line 746
const StopTimeOkOutput = "stop_time_ok"            // line 747
const SkipCheckOkOutput = "skip_check_ok"          // line 748
const SkipNoMatchCheckOkOutput = "skip_no_match_check_ok" // line 749
const CommandPositionOkOutput = "command_position_ok"     // line 750
const MatchedCommandOutput = "matched_command"     // line 751
const RateLimitOkOutput = "rate_limit_ok"          // line 752
const SkipRolesOkOutput = "skip_roles_ok"          // line 753
const SkipBotsOkOutput = "skip_bots_ok"            // line 754
const SkipIfCheckFailingOkOutput = "skip_if_check_failing_ok" // line 755
const ActivatedOutput = "activated"                // line 756

// Also untyped:
const ArtifactPrefixOutputName = "artifact_prefix" // line 672

Suggested fix (following the existing pattern in the same file):

// OutputName represents a GitHub Actions step output variable name.
// This semantic type distinguishes output names from arbitrary strings,
// preventing accidental misuse of step IDs or other string constants as output names.
type OutputName string

func (o OutputName) String() string { return string(o) }

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

• Estimated effort: 1–2 hours (including updating all usage sites)
• Benefits: Consistent with the existing StepID, JobName pattern; compile-time prevention of misuse

---

Category 2: Container/Image Constants — Inconsistent Typing

Version constants consistently use the Version type, but container image constants are untyped despite being the same "registry path" concept:

// Typed (correct pattern):
const DefaultMCPGatewayVersion Version = "v0.2.3"         // line 388
const DefaultClaudeCodeVersion  Version = "latest"         // line 277
const DefaultFirewallVersion    Version = "v0.25.0"        // line 370

// Untyped (inconsistent with peers):
const DefaultMCPGatewayContainer  = "ghcr.io/github/gh-aw-mcpg"         // line 391
const DefaultSerenaMCPServerContainer = "ghcr.io/github/serena-mcp-server" // line 408
const OraiosSerenaContainer       = "ghcr.io/oraios/serena"              // line 411
const DefaultQmdIndexingRunnerImage = "ubuntu-latest"                    // line 442
const DefaultNodeAlpineLTSImage   = "node:lts-alpine"                    // line 461
const DefaultPythonAlpineLTSImage = "python:alpine"                      // line 465
const DefaultAlpineImage          = "alpine:latest"                      // line 469
const DefaultActivationJobRunnerImage = "ubuntu-slim"                    // line 543
const DevModeGhAwImage            = "localhost/gh-aw:dev"                // line 473

A ContainerImage string type would make the distinction between container registry references and other strings explicit.

• Estimated effort: 1–2 hours
• Impact: Medium — improves API clarity; prevents accidental misuse

---

Category 3: Numeric Untyped Constants

const DefaultRateLimitMax    = 5     // line — should be int or a RateLimitCount type
const DefaultRateLimitWindow = 60    // line — should be int (minutes) or time.Duration
const DefaultMCPGatewayPayloadSizeThreshold = 524288 // line 402 — should be int64 or explicit size type

DefaultMCPGatewayPort = 80 is defined inside a const block without an explicit type.

These are lower priority since Go's type system infers numeric types correctly for arithmetic, but explicit types would add semantic clarity.

---

Category 4: map[string]any Usage — Large Surface, Largely Justified

1,438 occurrences across 249 files. The codebase already documents why many of these must remain dynamic:

// From pkg/workflow/frontmatter_types.go (with existing comments):
MCPServers map[string]any // Legacy field, use Tools instead
Runtimes   map[string]any // Deprecated: use RuntimesTyped
Jobs       map[string]any // Custom workflow jobs (too dynamic to type)
On         map[string]any // Complex trigger config with many variants (too dynamic to type)

The existing FrontmatterConfig struct is itself a migration from raw map[string]any — several fields already have typed alternatives (Tools *ToolsConfig, SafeOutputs *SafeOutputsConfig, RuntimesTyped *RuntimesConfig).

Most actionable opportunities (not yet typed):

Field	File	Lines	Current Type	Why Typeable
GuardPolicies	pkg/workflow/mcp_renderer_types.go:21,87,114	3 structs	map[string]any	Same field on 3 different config structs; could use a shared GuardPoliciesConfig type
InputSchema	pkg/workflow/mcp_scripts_generator.go:20	1 struct	map[string]any	JSON Schema structure is known
ExtraFields	pkg/workflow/runtime_definitions.go:27	1 struct	map[string]any	"Additional with fields from user's setup step" — could use map[string]string

DevcontainerFeatures (pkg/cli/devcontainer.go:39) already demonstrates the pattern:

// Named type alias for map[string]any — improves documentation at usage sites
type DevcontainerFeatures map[string]any

MapToolConfig (pkg/workflow/mcp_config_types.go:66) is another good example:

type MapToolConfig map[string]any
// with typed accessor methods: GetString, GetStringArray, GetStringMap

These named-alias patterns reduce the raw map[string]any surface while maintaining flexibility.

GitHubReposScope (pkg/workflow/tools_types.go:285) shows a typed alias for any:

type GitHubReposScope any // string or []any (YAML-parsed arrays are []any)

---

Refactoring Recommendations

Priority 1: Add OutputName Type to Constants (High impact, low effort)

• Where: pkg/constants/constants.go:746–756
• What: Add type OutputName string following the existing StepID/JobName pattern; retype the 11 output name constants
• Steps:
  1. Define OutputName string type with String() method
  2. Update constant declarations
  3. Update usage sites to accept OutputName (search for each constant usage)
  4. Run tests

---

Priority 2: Extract RepositoryFeatures from Build-Tag Files (Low effort)

• Where: pkg/workflow/repository_features_validation.go and _wasm.go
• What: Move the identical struct to a shared repository_features_types.go without build constraints
• Steps:
  1. Create pkg/workflow/repository_features_types.go with the struct
  2. Remove struct from both build-tag files
  3. Verify compilation for both wasm and native targets

---

Priority 3: Type Container/Image Constants (Medium effort)

• Where: pkg/constants/constants.go
• What: Add ContainerImage string type for the 9 container/image string constants
• Steps:
  1. Define ContainerImage string type following existing patterns
  2. Update constant declarations
  3. Update usage sites

---

Implementation Checklist

• Add OutputName type and retype 11 output-name constants in pkg/constants/constants.go
• Extract RepositoryFeatures struct to a build-tag-free shared file
• Add ContainerImage type for container/image reference constants
• Consider GuardPoliciesConfig struct to replace map[string]any on the 3 renderer config structs
• Continue migrating remaining FrontmatterConfig map[string]any fields toward typed structs (ongoing)

---

Analysis Metadata

• Total Go Files Analyzed: 607 (non-test, in pkg/)
• Total Exported Type Definitions: 479
• Duplicate Struct Name Clusters: 4 (all are wasm/native build-tag splits)
• Untyped Constant Groups: 2 actionable groups (output names: 11; container/image: 9)
• map[string]any Occurrences: 1,438 in 249 files (majority justified by YAML dynamism)
• Detection Method: Serena semantic analysis + pattern matching
• Analysis Date: 2026-03-24
• Workflow Run: §23486695834

References:

• §23486695834

AI generated by Typist - Go Type Analysis · history

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

[github-actions[bot]]

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

A newer discussion is available at Discussion #22871.