[typist] Typist - Go Type Consistency Analysis

[github-actions[bot]]

Executive Summary

Analyzed 786 non-test Go files across pkg/ containing roughly 550 struct/interface definitions and ~470 function signatures touching map[string]any. The codebase is generally well-typed: shared base types (pkg/types/BaseMCPServerConfig, pkg/workflow/SafeOutputTargetConfig, pkg/workflow/BaseSafeOutputConfig), semantic aliases in pkg/constants (LineLength, CommandPrefix, WorkflowID), and a dedicated pkg/typeutil for safe any-conversions are all in place. The findings below are mostly inconsistencies — duplicate field declarations where an existing embed type already exists — plus one exact-duplicate interface and a deprecated empty struct.

There is no widespread interface{}/any abuse: the ~2,839 map[string]any occurrences are concentrated in YAML/JSON parsing entry points (frontmatter map[string]any, configMap map[string]any) where dynamic typing is intentional and documented.

Critical Findings

#	Finding	Priority	Effort
1	11 safe-output config structs inline TargetRepoSlug/AllowedRepos instead of embedding existing SafeOutputTargetConfig	High	Low
2	Exact-duplicate interface: actionpins.SHAResolver and workflow.ActionSHAResolver	Medium	Low
3	workflow.AddCommentConfig is an empty deprecated struct with no remaining references	Low	Trivial
4	Footer *string, TitlePrefix string, Labels []string, CloseOlderKey string are re-declared across 5–11 safe-output configs	Medium	Medium
5	Three FrontmatterConfig fields are explicitly marked deprecated but still kept: MCPServers, Runtimes, Permissions (all map[string]any)	Low	Medium

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Files analyzed: 786 non-test .go files under pkg/
• Struct/interface definitions found: ~550 (excluding test files)
• Exact duplicates: 1 (interface)
• Near duplicates (field-level): ~50 occurrences across 11 named fields
• Semantic duplicates worth consolidating: 1 cluster (safe-output target/repo fields)
• Intentional build-tag duplicates (do NOT consolidate): 3 pairs

Cluster 1: SHAResolver / ActionSHAResolver (exact duplicate interface)

Type: Exact duplicate (different name, identical method set)
Impact: Medium — two interfaces with identical contracts force callers to choose; test doubles must be written twice.

Locations:

1. pkg/actionpins/actionpins.go:59 — type SHAResolver interface { ResolveSHA(ctx context.Context, repo, version string) (string, error) }
2. pkg/workflow/action_resolver.go:16 — type ActionSHAResolver interface { ResolveSHA(ctx context.Context, repo, version string) (string, error) }

Both interfaces are satisfied by the same concrete resolver, and pkg/workflow/maintenance_workflow.go:22,67,143 plus pkg/cli/copilot_setup.go:22,47,178,265,336 use the workflow.ActionSHAResolver form while pkg/cli/copilot_setup_test.go defines a mockSHAResolver that satisfies both.

Recommendation: Promote the interface to pkg/actionpins (or a neutral pkg/types/resolver.go) and have pkg/workflow import/use it directly. Go interface satisfaction is structural — only one definition is needed.

Cluster 2: AddCommentConfig (dead empty struct)

Type: Deprecated empty placeholder
Impact: Low — code smell, no runtime impact.

Location: pkg/workflow/add_comment.go:9-12

// AddCommentConfig holds configuration for creating GitHub issue/PR comments from agent output (deprecated, use AddCommentsConfig)
type AddCommentConfig struct {
    // Empty struct for now, as per requirements, but structured for future expansion
}

A grep across pkg/ returns only this declaration — no other code (production or test) references the type.

Recommendation: Delete the type. The replacement AddCommentsConfig is already used everywhere.

Cluster 3: Safe-output target/repo fields (near-duplicate field declarations)

Type: Near duplicate — same field, same tag, same comment, declared inline in 11 types when an embeddable base already exists.

Existing base (pkg/workflow/safe_outputs_parser.go:9-13):

type SafeOutputTargetConfig struct {
    Target         string   `yaml:"target,omitempty"`
    TargetRepoSlug string   `yaml:"target-repo,omitempty"`
    AllowedRepos   []string `yaml:"allowed-repos,omitempty"`
}

Already adopted in 18 types (good): AssignMilestoneConfig, UpdateEntityConfig, HideCommentConfig, ReplyToPullRequestReviewCommentConfig, AssignToAgentConfig, LinkSubIssueConfig, ResolvePullRequestReviewThreadConfig, AddLabelsConfig, RemoveLabelsConfig, SetIssueFieldConfig, MarkPullRequestAsReadyForReviewConfig, SetIssueTypeConfig, UnassignFromUserConfig, CloseEntityConfig, SubmitPullRequestReviewConfig, AssignToUserConfig, CloseJobConfig, ListJobConfig, AddReviewerConfig.

Still inlining the fields manually (11 places — should embed instead):

File:Line	Type	Fields inlined
pkg/workflow/create_issue.go:19-20	CreateIssuesConfig	TargetRepoSlug, AllowedRepos
pkg/workflow/create_discussion.go:21-22	CreateDiscussionsConfig	TargetRepoSlug, AllowedRepos
pkg/workflow/create_pull_request.go:30-31	CreatePullRequestsConfig	TargetRepoSlug, AllowedRepos
pkg/workflow/create_pr_review_comment.go:14-15	CreatePullRequestReviewCommentsConfig	TargetRepoSlug, AllowedRepos
pkg/workflow/create_code_scanning_alert.go:18-19	CreateCodeScanningAlertsConfig	TargetRepoSlug, AllowedRepos
pkg/workflow/create_agent_session.go:13-14	CreateAgentSessionConfig	TargetRepoSlug, AllowedRepos
pkg/workflow/add_comment.go:17-19	AddCommentsConfig	Target, TargetRepoSlug, AllowedRepos
pkg/workflow/push_to_pull_request_branch.go:22-23	PushToPullRequestBranchConfig	TargetRepoSlug, AllowedRepos
pkg/workflow/comment_memory.go:11-12	CommentMemoryConfig	TargetRepoSlug, AllowedRepos
pkg/workflow/update_project.go:29-30	UpdateProjectConfig	TargetRepoSlug, AllowedRepos
pkg/workflow/dispatch_workflow.go:15	DispatchWorkflowConfig	TargetRepoSlug

Recommendation:

// Before (in each of the 11 types above):
type CreateIssuesConfig struct {
    BaseSafeOutputConfig `yaml:",inline"`
    TitlePrefix          string   `yaml:"title-prefix,omitempty"`
    Labels               []string `yaml:"labels,omitempty"`
    // ...
    TargetRepoSlug       string   `yaml:"target-repo,omitempty"`
    AllowedRepos         []string `yaml:"allowed-repos,omitempty"`
}

// After:
type CreateIssuesConfig struct {
    BaseSafeOutputConfig    `yaml:",inline"`
    SafeOutputTargetConfig  `yaml:",inline"`
    TitlePrefix             string   `yaml:"title-prefix,omitempty"`
    Labels                  []string `yaml:"labels,omitempty"`
    // ...
}

YAML serialization is preserved (same tag names). Callsites that read cfg.TargetRepoSlug continue to work via field promotion. Effort: ~30 min per type plus testing. Impact: Removes ~25 lines of duplicated field declarations and ensures future changes to target semantics apply uniformly.

Cluster 4: Other recurring safe-output fields

These fields are declared verbatim across 5+ types. They are not yet captured in SafeOutputTargetConfig/SafeOutputFilterConfig and could form a new shared embed if duplication grows:

Field	Occurrences	Files
Footer *string \yaml:"footer,omitempty"``	11	create_issue, create_discussion, create_pull_request, add_comment, reply_to_pr_review_comment, submit_pr_review, update_discussion_helpers, update_issue_helpers, update_pull_request_helpers, update_release, comment_memory
TitlePrefix string \yaml:"title-prefix,omitempty"``	7	create_issue, create_discussion, create_pull_request, push_to_pull_request_branch, update_issue_helpers, missing_issue_reporting, create_project
Labels []string \yaml:"labels,omitempty"``	5	create_issue, create_discussion, create_pull_request, push_to_pull_request_branch, missing_issue_reporting
CloseOlderKey string \yaml:"close-older-key,omitempty"``	2	create_issue, create_discussion

Recommendation: Defer until Cluster 3 lands. More embeds add cognitive overhead; only worth it if these field sets continue to grow.

Cluster 5: Intentional build-tag pairs (do NOT consolidate)

These show up as same-name duplicates but are governed by //go:build !js && !wasm vs //go:build js || wasm and represent platform-specific implementations:

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

These are correct — listed here only so future scanners don't churn on them.

Untyped Usages

Summary Statistics

• Bare interface{} literals in non-test files: ~2 (one test fixture)
• any keyword occurrences: ~2,665 across 300 files (concentrated in YAML/JSON parsing — mostly idiomatic)
• map[string]any occurrences: ~2,839 (predominantly intentional)
• Untyped numeric/string constants: hundreds, but most are scope-local file or function constants where typing adds no value

The codebase has clearly invested in dynamic-typing safely: pkg/typeutil provides ParseIntValue, ConvertToInt, ConvertToFloat, ParseBool for moving from any to concrete types, and pkg/constants defines semantic aliases (LineLength, CommandPrefix, WorkflowID) plus typed fs.FileMode constants for file permissions.

Category 1: Deprecated map[string]any fields kept for compatibility

Location: pkg/workflow/frontmatter_types.go:258-269

MCPServers       map[string]any     `json:"mcp-servers,omitempty"` // Legacy field, use Tools instead
Runtimes         map[string]any     `json:"runtimes,omitempty"`    // Deprecated: use RuntimesTyped
Permissions      map[string]any     `json:"permissions,omitempty"` // Deprecated: use PermissionsTyped

Each has a typed replacement (Tools *ToolsConfig, RuntimesTyped *RuntimesConfig, PermissionsTyped *PermissionsConfig) already in the struct.

Recommendation: Plan a strict-mode migration that

1. reads the legacy map[string]any field if present,
2. logs a deprecation warning and emits an error under strict mode,
3. mechanically converts to the typed form, and
4. after one or two releases, removes the legacy field.

Category 2: GitHub Actions YAML model uses any for polymorphism

Location: pkg/cli/copilot_setup.go:139-159

type CopilotWorkflowStep struct {
    With map[string]any `yaml:"with,omitempty"`
    Env  map[string]any `yaml:"env,omitempty"`
}
type WorkflowJob struct {
    RunsOn      any                   `yaml:"runs-on,omitempty"`
    Permissions map[string]any        `yaml:"permissions,omitempty"`
    Steps       []CopilotWorkflowStep `yaml:"steps,omitempty"`
}
type Workflow struct {
    Name string                 `yaml:"name,omitempty"`
    On   any                    `yaml:"on,omitempty"`
    Jobs map[string]WorkflowJob `yaml:"jobs,omitempty"`
}

Env is plausibly always map[string]string. Permissions could be a typed enum (read-all, write-all, or a map). RunsOn is genuinely polymorphic (string or list) — keep as any with a custom unmarshaler or document why.

Recommendation: Narrow CopilotWorkflowStep.Env to map[string]string. Leave RunsOn/On polymorphic but add doc comments explaining the variance.

Category 3: Function parameters typed as frontmatter map[string]any

Roughly 470 functions in pkg/workflow accept map[string]any parameters. The vast majority sit at the YAML-parse boundary and are correct. A handful of internal helpers (e.g. inner pass-through functions that never read the map directly) could accept a typed wrapper, but no bulk refactor is justified.

Recommendation: Address opportunistically when editing nearby code.

Category 4: Untyped constants — mostly OK

Sampled untyped constants like const maxTagPeelDepth = 10, const maxFuzzyMatchSuggestions = 7, const defaultArtifactMaxUploads = 1 are function-local or file-local and used in arithmetic where Go's untyped-constant rules give the right type automatically. No refactor needed.

Where semantic types already exist (pkg/constants/constants.go: LineLength, CommandPrefix, WorkflowID, file-permission fs.FileMode constants), they are a good template if new domain types arise.

Refactoring Recommendations (prioritized)

Priority 1 — Adopt SafeOutputTargetConfig embed in remaining 11 types

Steps:

1. For each type in Cluster 3 above, replace the inline Target/TargetRepoSlug/AllowedRepos declarations with SafeOutputTargetConfig \yaml:",inline"``.
2. Run go build ./... && go test ./pkg/workflow/... to confirm field-promotion access still resolves.
3. Snapshot YAML serialization tests should pass unchanged (same tag names).

Estimated effort: 3–4 hours total. Impact: Removes ~25 lines of duplicated declarations; single source of truth for safe-output target semantics.

Priority 2 — Consolidate the duplicate SHAResolver interface

Steps:

1. Decide canonical home: either keep pkg/actionpins.SHAResolver and have pkg/workflow import it directly, or move to a neutral pkg/types.
2. Delete the duplicate.
3. Update pkg/workflow/maintenance_workflow.go, pkg/cli/copilot_setup*.go, and test doubles.

Estimated effort: 1–2 hours. Impact: One less concept for new contributors; test doubles satisfy a single interface.

Priority 3 — Delete dead AddCommentConfig

Steps: Remove pkg/workflow/add_comment.go:9-12. Build to confirm no references.

Estimated effort: 5 minutes.

Priority 4 — Drop deprecated map[string]any legacy fields

Only do this once strict-mode rollout for typed replacements is complete:

• FrontmatterConfig.MCPServers → Tools
• FrontmatterConfig.Runtimes → RuntimesTyped
• FrontmatterConfig.Permissions → PermissionsTyped

Estimated effort: ~1 day including warning-period migration. Impact: Smaller parser surface, fewer code paths to keep in sync.

Priority 5 (optional) — Extract a second safe-output content embed

Only worthwhile if more fields beyond Cluster 4's (Footer/TitlePrefix/Labels) start being added to multiple types. Premature otherwise.

Implementation Checklist

• Embed SafeOutputTargetConfig in 11 named types (Priority 1)
• Consolidate SHAResolver / ActionSHAResolver into one interface (Priority 2)
• Delete empty AddCommentConfig (Priority 3)
• Plan strict-mode migration for the three deprecated map[string]any frontmatter fields (Priority 4)
• Narrow CopilotWorkflowStep.Env from map[string]any to map[string]string
• Re-run analysis after changes land to verify cluster sizes drop

Analysis Metadata

• Total Go Files Analyzed: 786 (non-test)
• Total Type Definitions Surveyed: ~550
• Duplicate Clusters Reported: 5 (1 exact-interface, 1 dead struct, 1 large near-duplicate, 1 secondary near-duplicate group, 1 build-tag group)
• Untyped Usage Categories: 4
• Detection Method: ripgrep pattern surveys + targeted file reads
• Analysis Date: 2026-05-13

References: §25797721831

Generated by Typist - Go Type Analysis · ● 24.1M · ◷

• expires on May 14, 2026, 12:11 PM UTC