[typist] Typist - Go Type Consistency Analysis

[github-actions[bot]]

Analysis of the github/gh-aw repository across 211 non-test Go files in pkg/ (717 total across the repo). The codebase has zero legacy interface{} usages — it has fully adopted the any alias — but has 1,929 any occurrences, 4 critical naming conflicts, and several opportunities for stronger typing.

Executive Summary

• Total any usages: 1,929 lines (1,503 map[string]any, 326 []any, remainder in function signatures)
• Critical duplicate type names: 4 pairs with conflicting definitions across packages
• Platform-specific duplicates: 3 pairs (acceptable, build-tag separated)
• Type aliases: 3 (acceptable re-exports)
• Untyped constants: None critical — all constants have properly inferred types

The any usage is heavily concentrated in YAML/JSON unmarshaling, JSON schema validation, and dynamic tool configuration — areas where dynamic types are architecturally justified. However, the naming conflicts create real maintainability risk.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

Metric	Count
Total types analyzed	~340 struct/interface types across pkg/
Duplicate name clusters found	7
Critical conflicts (different fields, different purposes)	4
Platform-specific splits (build-tag separated)	3
Intentional type aliases	3

---

Cluster 1: MCPServerConfig — Critical Conflict

Type: Naming conflict — both embed types.BaseMCPServerConfig but have incompatible extension fields
Occurrences: 2
Impact: High — different serialization tags (json vs yaml), different field sets

Locations:

1. pkg/parser/mcp.go:33 — Parser-facing definition
2. pkg/workflow/tools_types.go:395 — Workflow-facing definition

Definition Comparison:

// pkg/parser/mcp.go:33 — JSON tags for registry parsing
type MCPServerConfig struct {
    types.BaseMCPServerConfig
    Name      string   `json:"name"`
    Registry  string   `json:"registry"`
    ProxyArgs []string `json:"proxy-args"`
    Allowed   []string `json:"allowed"`
}

// pkg/workflow/tools_types.go:395 — YAML tags for workflow compilation
type MCPServerConfig struct {
    types.BaseMCPServerConfig
    Mode          string         `yaml:"mode,omitempty"`
    Toolsets      []string       `yaml:"toolsets,omitempty"`
    GuardPolicies map[string]any `yaml:"guard-policies,omitempty"`
    CustomFields  map[string]any `yaml:",inline"`
}

Recommendation: Rename to distinguish roles.

• pkg/parser/mcp.go → RegistryMCPServerConfig (or ParsedMCPServerConfig)
• pkg/workflow/tools_types.go → CompiledMCPServerConfig (or WorkflowMCPServerConfig)
• Estimated effort: 2–3 hours (rename + update call sites)
• Benefit: Eliminates ambiguity when both packages are imported

---

Cluster 2: EngineConfig — Critical Conflict

Type: Completely different structures sharing a name
Occurrences: 2
Impact: High — runtime config (30+ fields, no JSON tags) vs audit report struct (9 JSON-tagged fields)

Locations:

1. pkg/workflow/engine.go:17 — Runtime engine configuration
2. pkg/cli/audit_expanded.go:19 — Audit log serialization

Definition Comparison:

// pkg/workflow/engine.go:17 — Runtime config (30+ fields, no JSON tags)
type EngineConfig struct {
    ID                   string
    Version              string
    Model                string
    MaxTurns             string
    MaxContinuations     int
    Concurrency          string
    // ... 25+ more fields
}

// pkg/cli/audit_expanded.go:19 — Audit report (9 JSON-tagged fields)
type EngineConfig struct {
    EngineID        string   `json:"engine_id"`
    EngineName      string   `json:"engine_name,omitempty"`
    Model           string   `json:"model,omitempty"`
    Version         string   `json:"version,omitempty"`
    CLIVersion      string   `json:"cli_version,omitempty"`
    FirewallVersion string   `json:"firewall_version,omitempty"`
    MCPServers      []string `json:"mcp_servers,omitempty"`
    TriggerEvent    string   `json:"trigger_event,omitempty"`
    Repository      string   `json:"repository,omitempty"`
}

Recommendation: Rename the CLI audit type to reflect its actual purpose.

• pkg/cli/audit_expanded.go → AuditEngineConfig or EngineAuditRecord
• Estimated effort: 1 hour
• Benefit: Clear distinction between runtime config and serialized audit data

---

Cluster 3: RepoConfig — Critical Conflict

Type: Completely different structures sharing a name
Occurrences: 2
Impact: Medium — maintenance config vs trial run repository context

Locations:

1. pkg/workflow/repo_config.go:78 — Workflow maintenance config
2. pkg/cli/trial_types.go:24 — Trial run repo context

Definition Comparison:

// pkg/workflow/repo_config.go:78 — Maintenance window configuration
type RepoConfig struct {
    MaintenanceDisabled bool
    Maintenance         *MaintenanceConfig
}

// pkg/cli/trial_types.go:24 — Trial run repository triplet
type RepoConfig struct {
    LogicalRepo string // Repo to simulate against
    CloneRepo   string // Clone source
    HostRepo    string // Host repository
}

Recommendation: Rename the trial types to be unambiguous.

• pkg/cli/trial_types.go → TrialRepoContext or TrialRepoConfig
• Estimated effort: 1 hour
• Benefit: Eliminates confusion when both packages are used in the same file

---

Cluster 4: FileTracker — Interface/Struct Conflict

Type: Interface defined in workflow, concrete struct defined in CLI — same name
Occurrences: 2
Impact: Medium — naming confusion between abstraction and implementation

Locations:

1. pkg/workflow/compiler_types.go:52 — Minimal interface
2. pkg/cli/file_tracker.go:19 — Full struct implementation

Definition Comparison:

// pkg/workflow/compiler_types.go:52 — Interface (1 method)
type FileTracker interface {
    TrackCreated(filePath string)
}

// pkg/cli/file_tracker.go:19 — Concrete struct
type FileTracker struct {
    CreatedFiles    []string
    ModifiedFiles   []string
    OriginalContent map[string][]byte
    gitRoot         string
}

Recommendation: Follow Go conventions for interface/implementation naming.

• Rename interface to FileCreationTracker (focused on its single method), OR
• Rename struct to FileTrackerImpl or CLIFileTracker
• Estimated effort: 1–2 hours
• Benefit: Follows Go idiom where interface and implementing struct have distinct names

---

Clusters 5–7: Platform-Specific Splits (Acceptable)

These type name pairs are separated by //go:build js || wasm build tags — intentional and correct:

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

No action needed — this is the standard Go build constraint pattern.

---

Untyped any Usages

Summary Statistics

Category	Count
map[string]any usages	1,503
[]any usages	326
any in function parameters	~25 functions
any struct fields	~8 structs
Total locations	~1,929

---

Category 1: YAML Unmarshaling (Architecturally Justified)

Impact: Low risk — standard Go pattern for YAML/JSON
Files: pkg/parser/frontmatter_content.go, pkg/workflow/compiler_jobs.go, and ~30 others

The root cause is yaml.Unmarshal producing map[string]any:

// Current (necessary for initial unmarshaling)
var frontmatter map[string]any
if err := yaml.Unmarshal([]byte(content), &frontmatter); err != nil { ... }

Existing mitigation: The codebase already introduced ToolsConfig as a typed wrapper:

// pkg/workflow/tools_types.go — Good pattern already in use
type ToolsConfig struct {
    GitHub  *GitHubToolConfig          // Strongly typed
    Bash    *BashToolConfig            // Strongly typed
    Custom  map[string]MCPServerConfig // Flexible but bounded
    raw     map[string]any             // For round-trip fidelity
}
func ParseToolsConfig(toolsMap map[string]any) (*ToolsConfig, error)

Recommendation: Extend this pattern to other repeated map[string]any patterns (e.g., FrontmatterResult.Frontmatter, TriggerData.Filters).

---

Category 2: Schema Navigation (Justified but Improvable)

Impact: Medium risk — deep type assertion chains, runtime panic risk if ok check missed
Top files: pkg/parser/schema_suggestions.go (34 usages), pkg/parser/import_field_extractor.go (33 usages)

Current pattern requires chained type assertions:

// pkg/parser/schema_suggestions.go — Repeated pattern
if properties, ok := current["properties"].(map[string]any); ok {
    if keySchema, ok := properties[segment].(map[string]any); ok {
        // navigate deeper
    }
}

Recommendation: Extract a SchemaNode helper type:

type SchemaNode map[string]any

func (s SchemaNode) Properties() SchemaNode {
    if v, ok := s["properties"].(map[string]any); ok {
        return SchemaNode(v)
    }
    return nil
}

func (s SchemaNode) StringField(key string) (string, bool) {
    v, ok := s[key].(string)
    return v, ok
}

• Estimated effort: 4–6 hours
• Benefit: Centralized type assertion logic, easier to audit for panic risk

---

Category 3: Function Parameters with any (Improvable)

Impact: Medium — reduces IDE autocomplete and call-site type checking
Count: ~25 functions across the codebase

Key examples:

Function	File	Current Signature	Suggested Fix
processBuiltinMCPTool	pkg/parser/mcp.go:253	toolValue any	toolValue map[string]any
ParseMCPConfig	pkg/parser/mcp.go:482	mcpSection any	mcpSection map[string]any
validateStringProperty	pkg/parser/mcp_property_validation.go:25	value any	value string or value map[string]any
generateExampleFromSchema	pkg/parser/schema_suggestions.go	returns any	returns json.RawMessage
normalizeForJSONSchema	pkg/workflow/tools_parser.go	v any returns any	Could use json.RawMessage

Recommendation: Replace any parameters with map[string]any where that is always the actual type — this is a safe narrowing with zero behavior change.

---

Category 4: Struct Fields with any (Improvable)

Impact: Medium — fields typed as any lose compile-time safety

Type	Field	Current Type	Suggested Type
FrontmatterResult (parser/)	Frontmatter	map[string]any	FrontmatterData (typed struct)
Compiler	Tools	map[string]any	*ToolsConfig (already exists)
MCPServerConfig (workflow)	GuardPolicies	map[string]any	GuardPolicyConfig struct
service_ports.go	Ports	any	PortSpec (string | int | []int union via interface)

---

Refactoring Recommendations

Priority 1 — High Impact, Low Effort: Rename Conflicting Types

Actions:

1. pkg/cli/audit_expanded.go: Rename EngineConfig → AuditEngineConfig
2. pkg/cli/trial_types.go: Rename RepoConfig → TrialRepoContext
3. pkg/parser/mcp.go: Rename MCPServerConfig → RegistryMCPServerConfig
4. pkg/workflow/compiler_types.go or pkg/cli/file_tracker.go: Resolve FileTracker naming

Estimated effort: 4–6 hours total
Risk: Low — purely mechanical rename with no semantic change

---

Priority 2 — Medium Impact: Narrow any Parameters to map[string]any

Where function parameters typed any always receive map[string]any, change the signature. This is a no-op at runtime but improves IDE tooling and prevents misuse.

Estimated effort: 2–3 hours
Risk: Very low — narrowing a parameter type is backward compatible within a package

---

Priority 3 — Higher Effort: Introduce Typed Wrappers

Extend the existing ToolsConfig pattern:

1. FrontmatterData typed struct to replace map[string]any in frontmatter results
2. SchemaNode helper type for schema navigation
3. GuardPolicyConfig struct for MCP guard policies

Estimated effort: 8–16 hours (requires updating callers)
Risk: Medium — requires coordinated changes across multiple files

---

Implementation Checklist

• Rename EngineConfig in pkg/cli/audit_expanded.go → AuditEngineConfig
• Rename RepoConfig in pkg/cli/trial_types.go → TrialRepoContext
• Rename MCPServerConfig in pkg/parser/mcp.go → RegistryMCPServerConfig
• Resolve FileTracker naming conflict (interface vs struct)
• Narrow any parameters to map[string]any in pkg/parser/mcp.go
• Introduce SchemaNode helper type for schema navigation
• Extend ToolsConfig pattern to cover FrontmatterResult.Frontmatter
• Run full test suite after each refactoring step

Analysis Metadata

Field	Value
Go files analyzed (pkg/, non-test)	211
Total type definitions	~340 struct/interface types
Critical duplicate clusters	4
Platform-specific splits (acceptable)	3
any usage locations	1,929
map[string]any count	1,503
interface{} count	0
Detection method	Serena semantic analysis + pattern matching
Analysis date	2026-04-17

References: Workflow Run §24563067306

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

• expires on Apr 18, 2026, 11:43 AM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-04-18T11:43:11.441Z.

Closed by Workflow