[typist] Typist: Go Type Consistency Analysis - Duplicate Types & Untyped Usages

[github-actions[bot]]

Typist - Go Type Consistency Analysis

Analysis of repository: github/gh-aw

Executive Summary

A semantic analysis of all non-test Go files under pkg/ (792 source files across 24 sub-packages) identified 3 duplicate type clusters and ~15 high-impact untyped-usage opportunities. The codebase already practices strong typing well for domain constants (e.g., EngineName, JobName, StepID), so the main consolidation wins are: (a) one true duplicate type (RepositoryFeatures) split across WASM/non-WASM build tags, and (b) a recurring pattern of returning raw map[string]any from YAML/JSON schema navigation code, which forces 50+ downstream type assertions in pkg/parser/schema_suggestions.go alone.

Quick stats

• Total types analyzed: 287 struct definitions
• Duplicate clusters: 3 (1 exact, 2 platform-variant near-duplicates)
• any usages: ~3,000 across 478 files (most justified by YAML/JSON unmarshaling)
• map[string]any patterns: ~1,766
• High-impact refactoring opportunities: ~15
• Overall priority: Medium — codebase is well-typed; gains are in schema navigation helpers and a handful of parser entry points.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total struct types analyzed: 287
• Duplicate clusters found: 3
• Exact duplicates: 1
• Near duplicates (platform variants): 2
• Semantic duplicates: 0 worth consolidating

All three clusters arise from _wasm.go build-tagged variants, which is an idiomatic Go pattern. Only one is a clean consolidation candidate.

---

Cluster 1: RepositoryFeatures (exact duplicate)

Classification: Exact duplicate — identical fields
Occurrences: 2
Impact: Medium — trivial to consolidate; no platform-specific reason for duplication.

Locations:

1. pkg/workflow/repository_features_validation.go:57
2. pkg/workflow/repository_features_validation_wasm.go:5

type RepositoryFeatures struct {
    HasDiscussions bool
    HasIssues      bool
}

Recommendation: Move the type to a build-tag-free file (e.g., repository_features_types.go) and keep only the platform-specific functions in the _wasm.go / non-_wasm.go files.

• Estimated effort: 30 minutes
• Benefit: One source of truth; prevents drift if a field is added later.

---

Cluster 2: ProgressBar (near-duplicate; platform variant)

Classification: Near-duplicate — WASM stub omits one runtime-only field
Occurrences: 2
Impact: Low — intentional platform divergence; consolidation risks coupling WASM to a non-WASM dependency.

Locations:

1. pkg/console/progress.go:31
2. pkg/console/progress_wasm.go:7

// progress.go
type ProgressBar struct {
    progress      progress.Model
    total         int64
    current       int64
    indeterminate bool
    updateCount   int64
}

// progress_wasm.go
type ProgressBar struct {
    total         int64
    current       int64
    indeterminate bool
    updateCount   int64
}

Recommendation: Keep as-is, or extract a ProgressBar interface with Update, Increment, etc. and let each build tag implement it. Only worth doing if the API surface grows.

---

Cluster 3: SpinnerWrapper (near-duplicate; platform variant)

Classification: Near-duplicate — WASM stub is intentionally minimal
Occurrences: 2
Impact: Low — same rationale as ProgressBar.

Locations:

1. pkg/console/spinner.go:96
2. pkg/console/spinner_wasm.go:10

// spinner.go
type SpinnerWrapper struct {
    program *tea.Program
    enabled bool
    running bool
    mu      sync.Mutex
    wg      sync.WaitGroup
}

// spinner_wasm.go
type SpinnerWrapper struct {
    enabled bool
}

Recommendation: Same as ProgressBar — introduce an interface only if the consumer surface grows.

---

Untyped Usages

Summary Statistics

• any usages: ~3,000 across 478 files (most are YAML/JSON unmarshaling targets and are appropriate)
• interface{} usages: 0 in production code (codebase uses the modern any alias)
• map[string]any patterns: ~1,766
• High-impact replacement opportunities: ~15
• Untyped domain constants: none material — codebase already uses typed enums (EngineName, JobName, StepID, etc.)

---

Category 1: any in function parameters that always destructure to a known shape

These functions accept any purely so they can be called from a YAML walker, but each one branches over a small, bounded set of input types. Replacing with a typed shim at the call site would eliminate per-call type assertions and document the contract.

Example 1

• Location: pkg/parser/schema_triggers.go:73
• Current: func IsLabelOnlyEvent(eventValue any) bool
• Actual input: always map[string]any with a types []string field.
• Suggested:

  type EventConfig struct { Types []string }
  func IsLabelOnlyEvent(cfg EventConfig) bool

Example 2

• Location: pkg/parser/schema_triggers.go:117
• Current: func IsNonConflictingCommandEvent(eventValue any) bool
• Same pattern as Example 1; same fix.

Example 3

• Location: pkg/workflow/reactions.go:42
• Current: func parseReactionValue(value any) (string, error)
• Actual input: one of string | int | int64 | uint64 | float64, all of which yield a string enum.
• Suggested: take a string or normalize numerics at the YAML boundary before calling.

Example 4

• Location: pkg/workflow/service_ports.go:153
• Current: func parsePortSpec(spec any) ([]int, []string)
• Actual input: int | uint64 | int64 | float64 | string.
• Suggested: normalize numerics to int at the parser boundary, then accept int | string via a small PortSpec interface or two-overload helper.

Example 5

• Location: pkg/workflow/safe_outputs_messages_config.go:53
• Current: func parseMentionsConfig(mentions any) *MentionsConfig
• Actual input: bool | map[string]any with a known field set.
• Suggested: discriminated MentionsInput (struct with IsBool bool; Object *MentionsObject).

Example 6

• Location: pkg/parser/import_field_extractor.go:919
• Current: func validateObjectInput(name string, value any, paramDef map[string]any, importPath string) error
• Suggested: value map[string]any directly — callers can validate before calling.

---

Category 2: map[string]any schema navigation (high-impact)

This is the single biggest opportunity in the codebase. pkg/parser/schema_suggestions.go repeatedly drills into nested map[string]any values, asserting types at each level. There are 15+ assertions in this one file (lines 162, 175, 190, 191, 201, 213, 218, 228, 391, 451, 477, ...).

Suggested refactor

// pkg/parser/jsonschema.go (new)
type JSONSchema struct{ m map[string]any }

func Wrap(v any) (JSONSchema, bool) {
    m, ok := v.(map[string]any)
    return JSONSchema{m: m}, ok
}

func (j JSONSchema) Properties() (map[string]JSONSchema, bool) { /* ... */ }
func (j JSONSchema) Items() (JSONSchema, bool)                 { /* ... */ }
func (j JSONSchema) OneOf() ([]JSONSchema, bool)               { /* ... */ }
func (j JSONSchema) String(key string) (string, bool)          { /* ... */ }

Impact sites:

• pkg/parser/schema_suggestions.go:175 — navigateToSchemaPath
• pkg/parser/schema_suggestions.go:213 — resolveSchemaWithOneOf
• pkg/parser/schema_suggestions.go:391-651 — deep navigation block

Benefit: Eliminates ~50 type assertions; turns runtime errors into compile-time guarantees; clarifies intent.

---

Category 3: MCP/parser entry points with any discriminators

Example 1

• Location: pkg/parser/mcp.go:255
• Current: func processBuiltinMCPTool(toolName string, toolValue any, serverFilter string) (*RegistryMCPServerConfig, error)
• Actual input: map[string]any with mode and github-token keys.
• Suggested:

  type MCPToolConfig struct { Mode, GithubToken string }
  func processBuiltinMCPTool(name string, cfg MCPToolConfig, serverFilter string) (*RegistryMCPServerConfig, error)

Example 2

• Location: pkg/workflow/compiler_jobs.go:112
• Current: func (c *Compiler) getCustomJobsDependencies(customJobs map[string]any) []string
• Suggested: introduce a CustomJob struct and use map[string]CustomJob (or map[JobName]CustomJob).

Example 3

• Location: pkg/workflow/permissions_parser.go:244
• Current: func NewPermissionsParserFromValue(permissionsValue any) *PermissionsParser
• Actual input: string | map[string]any.
• Suggested: split into two constructors — NewPermissionsParserFromString(s string) and NewPermissionsParserFromMap(m map[string]any).

---

Category 4: Untyped constants

No material findings. The codebase already follows the strong-typing idiom for domain enums. Spot-checked exemplars worth preserving:

• pkg/constants/engine_constants.go:11 — type EngineName string with typed constants ✅
• pkg/constants/job_constants.go:3 — type JobName string with typed constants ✅
• pkg/constants/job_constants.go:31 — type StepID string with typed constants ✅

No const Timeout = 30-style untyped numerics with semantic meaning were found in core code paths.

---

Refactoring Recommendations (prioritized)

Priority 1 — Consolidate RepositoryFeatures

Why: Only true exact duplicate in the codebase; no platform-specific reason to keep two copies.

1. Add pkg/workflow/repository_features_types.go (no build tag) with the struct.
2. Remove the duplicate declaration from repository_features_validation_wasm.go.
3. Leave functions in their platform-tagged files.

• Effort: 30 min
• Risk: Low
• Impact: Removes a real source of drift.

---

Priority 2 — Introduce a JSONSchema helper for schema navigation

Why: Single change that eliminates ~50 type assertions and most of the readability friction in pkg/parser/schema_suggestions.go.

1. Add pkg/parser/jsonschema.go with the wrapper type and accessor methods.
2. Migrate navigateToSchemaPath, resolveSchemaWithOneOf, and the deep navigation block to use it.
3. Migrate other parser navigation sites opportunistically.

• Effort: 4-6 hrs
• Risk: Medium (touches schema code; needs good test coverage)
• Impact: High maintainability win.

---

Priority 3 — Type the small parser/workflow entry points

Why: Each call site listed in Category 1 and Category 3 is independently small but together they form a consistent pattern of "accept any, immediately assert".

Apply one at a time; each is a self-contained PR.

• Effort: 1-2 hrs per site
• Risk: Low
• Impact: Per-site clarity; cumulative is meaningful.

---

Implementation Checklist

• Consolidate RepositoryFeatures (P1)
• Add JSONSchema wrapper + migrate schema_suggestions.go (P2)
• Type IsLabelOnlyEvent / IsNonConflictingCommandEvent parameters
• Type parseReactionValue / parseReactionConfig parameters
• Type parsePortSpec parameter (normalize numerics at boundary)
• Type parseMentionsConfig parameter (discriminated union)
• Type validateObjectInput parameter
• Type processBuiltinMCPTool config parameter
• Type getCustomJobsDependencies input map values
• Split NewPermissionsParserFromValue into two typed constructors
• Decide whether to extract ProgressBar/SpinnerWrapper interfaces (skip unless API grows)

---

Caveats

• Most any usage in this codebase is justified by YAML/JSON unmarshaling boundaries. The recommendations above target only sites where the input shape is bounded and predictable.
• The two platform-variant struct clusters (ProgressBar, SpinnerWrapper) are idiomatic Go build-tag patterns and should not be consolidated without a clear API need.
• The JSONSchema wrapper recommendation does not need to land all at once — it can be introduced and migrated incrementally.

---

Analysis Metadata

• Total Go files analyzed: 792 (non-test, under pkg/)
• Total struct types: 287
• Duplicate clusters: 3 (1 exact, 2 platform-variant)
• Untyped usage locations flagged: ~15 high-impact
• Detection method: Serena semantic analysis + ripgrep pattern matching
• Analysis date: 2026-05-15
• Workflow run: §25916573153

References:

• Workflow run §25916573153

Generated by ✍️ Typist - Go Type Analysis · ● 4.9M · ◷

• expires on May 16, 2026, 12:06 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-05-16T12:06:08.861Z.

Closed by Workflow