[typist] Type Consistency Analysis — Duplicates & Untyped Usages in pkg/

[github-actions[bot]]

Analysis of repository: github/gh-aw

Good news first: this is a healthily typed codebase. I swept every non-test .go file under pkg/ (891 files, ~609 struct/interface definitions plus 38+ named string types) hunting for duplicated type definitions and weak typing — and the headline is that the team is already doing the right things. There are zero interface{} usages left (everything is on modern any), zero problematic cross-package duplicate types (the few repeated names are deliberate alias re-exports or //go:build wasm variants), and a dedicated pkg/typeutil package already centralizes safe conversion out of dynamic map[string]any data.

So this is more a consolidation review than a fix-these-duplicates list. The one genuinely actionable theme: a handful of polymorphic YAML/JSON fields typed any (RunsOn, On, Headers, RunID/RunNumber/ID) recur across packages and each re-implements its own runtime type juggling. Shared union types with custom unmarshalers would remove that repetition and shrink the ~1,395 raw type assertions in the parsing layer.

Full Analysis Report

Summary Statistics

Metric	Count
Non-test Go files analyzed (pkg/)	891
Struct / interface definitions	609
Named string enum-style types already defined	38+
interface{} usages	0 ✅
Cross-package duplicate type definitions	0 ✅
type X = pkg.Y alias re-exports (good pattern)	11
map[string]any usages (non-test)	2,113
[]any usages (non-test)	395
Struct fields typed any	31
Raw .(map[string]any) / .(string) / .([]any) assertions	573 / 650 / 172

---

Duplicated Type Definitions — none to consolidate ✅

Every repeated type name falls into one of two intentional patterns, not duplication.

1. Alias re-exports (single source of truth, re-surfaced for a package API):

// pkg/actionpins/actionpins.go — the real definitions
type ActionPin struct { ... }
type SHAResolver interface { ... }

// pkg/workflow/action_pins.go — re-exports, NOT copies
type ActionPin    = actionpins.ActionPin
type SHAResolver  = actionpins.SHAResolver

Same for InputDefinition (pkg/types→pkg/workflow), SanitizeOptions (pkg/stringutil→pkg/workflow), and LogMetrics/ToolCallInfo (pkg/workflow→pkg/cli). This is exactly the pattern a duplicate-finder would recommend — already in place.

2. Build-tag variants — ProgressBar, SpinnerWrapper (pkg/console) and RepositoryFeatures (pkg/workflow) each have a *_wasm.go twin guarded by //go:build. Compiled mutually-exclusively; correct by design.

---

Untyped Usages

Category 1 — Polymorphic any struct fields (the actionable one)

31 struct fields are typed any. Most are legitimately polymorphic — comments say so (e.g. continue-on-error can be bool or string expression; runs-on is string, array, or object). The opportunity is that several recur across files, each re-deriving the type by hand:

Recurring polymorphic fields (with locations)

• RunsOn any (string | array | object): pkg/workflow/safe_jobs.go:20, pkg/cli/copilot_setup.go:149
• On any (string | array | map): pkg/cli/status_command.go:35, pkg/cli/list_workflows_command.go:25, pkg/cli/jsonworkflow_to_markdown.go:38, pkg/cli/copilot_setup.go:157
• Headers any (almost always string→string map): pkg/parser/import_field_extractor.go:752, pkg/workflow/frontmatter_types.go:208,238
• RunID/RunNumber/ID any (JSON string-or-number): pkg/cli/logs_models.go:304-305, pkg/cli/gateway_logs_types.go:148,159, pkg/cli/mcp_tools_privileged.go:254-255
• Imports/Include any (string | array): pkg/workflow/frontmatter_types.go:342,344

Suggested fix — shared union types with custom unmarshalers:

// pkg/types/yamlunion.go (new)

// StringOrSlice accepts a scalar or sequence and normalizes to []string.
type StringOrSlice []string
func (s *StringOrSlice) UnmarshalYAML(unmarshal func(any) error) error { ... }

// FlexibleID accepts a JSON string or number, exposes a canonical string.
type FlexibleID string
func (f *FlexibleID) UnmarshalJSON(b []byte) error { ... }

Then Imports/Include (and the []string half of RunsOn) become StringOrSlice; RunID/RunNumber/ID become FlexibleID; Headers any becomes map[string]string where confirmed. Benefit: the type juggling lives in one tested place, and consumers get a concrete type instead of an assertion.

⚠️ RunsOn/On also accept object forms, so they cannot collapse all the way to []string — a small RunsOnSpec/TriggerSpec with its own unmarshaler fits those two.

Category 2 — map[string]any in the parsing layer (mostly idiomatic)

2,113 map[string]any usages sound alarming but are concentrated in YAML/JSON frontmatter handling, where input is schema-dynamic (hotspots: pkg/parser/import_field_extractor.go = 78, tools_merger.go = 19). Forcing concrete structs here fights the job of the parser.

The real signal is the 573 raw .(map[string]any) and 650 raw .(string) assertions. The team already built pkg/typeutil for this (LookupMap, LookupString, LookupStringPath, ParseBool, ConvertToInt, ...) — so the recommendation is not add types, it is route ad-hoc assertions through the existing helpers for nil-safety and consistency.

Category 3 — Untyped constants — no findings

The codebase already defines 38+ semantic string types (JobName, StepID, EngineName, PermissionLevel, SandboxType, ActionMode, OutcomeStatus, ...). Remaining bare numeric constants are idiomatic Go untyped constants — typing them would be noise, not safety.

---

Refactoring Recommendations

Priority 1 — Shared union types for recurring polymorphic fields. Add pkg/types/yamlunion.go (StringOrSlice, FlexibleID, plus RunsOnSpec/TriggerSpec for object-accepting cases); migrate Imports, Include, RunID, RunNumber, ID, Headers. Effort ~4–6h · Impact High.

Priority 2 — Funnel raw assertions through pkg/typeutil. Audit the 573 .(map[string]any) + 650 .(string) sites; replace hand-rolled assertions with LookupMap/LookupString/LookupStringPath; consider a lint flagging new raw assertions on parsed config. Effort ~3–5h · Impact Medium.

Priority 3 — Tighten confirmed-shape any fields. Narrow each Headers any to map[string]string where always headers; review any any field whose comment does not describe a real union. Effort ~2h · Impact Medium.

Implementation Checklist

• Add pkg/types/yamlunion.go (StringOrSlice, FlexibleID, RunsOnSpec, TriggerSpec) + tests
• Migrate Imports/Include/RunID/RunNumber/ID to the new union types
• Narrow Headers any → map[string]string where confirmed
• Audit 573 .(map[string]any) assertions → typeutil.LookupMap
• Run go test ./...

Analysis Metadata

• Files analyzed: 891 non-test .go files in pkg/
• Types: 609 structs/interfaces + 38+ named string types
• Duplicate clusters: 0 problematic (11 intentional alias re-exports, 3 build-tag variant pairs)
• Detection method: ripgrep pattern extraction + manual cluster verification by reading source. (go run/python/awk/sed execution was blocked by the run security policy, so extraction used the dedicated search tools instead.)

References: §27138497703

Generated by ✍️ Typist - Go Type Analysis · 345 AIC · ⌖ 15.1 AIC · ⊞ 9.3K · ◷

• expires on Jun 9, 2026, 5:00 AM UTC-08:00

[github-actions[bot]]

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

A newer discussion is available at Discussion #38107.