[typist] Typist type analysis

[github-actions[bot]]

🔤 Typist - Go Type Consistency Analysis

Analysis of repository: github/gh-aw

Executive Summary

I scanned all 1,213 non-test .go files under pkg/ (roughly 1,000+ struct definitions across cli, workflow, parser, linters, and two dozen small utility packages), looking for duplicated type definitions and places where interface{}/any or untyped constants stand in for a concrete type. Good news first: the codebase is already disciplined in the places that matter most — interface{} has been fully retired in favor of any, and the safe-outputs config family in pkg/workflow (BaseSafeOutputConfig + composable mixins like SafeOutputTargetConfig) and the MCP server config embedding in pkg/parser/mcp.go are genuinely good "embed, don't copy" patterns worth pointing to as the house style.

That said, I found 13 duplicate/near-duplicate type clusters and 16 untyped-usage findings worth fixing. The standouts: pkg/cli/logs_models.go has a struct (MCPFailureSummary) that hand-copies fields from AggregatedSummaryBase instead of embedding it — and the source comment right next to it already calls this out as "copy-paste drift risk." pkg/agentdrain maintains two structs (Cluster/SnapshotCluster) that are field-for-field identical except JSON tags, hand-copied on every save/load. And in pkg/intent — the package that encodes autonomy/write-scope security policy — Autonomy and WriteScope are plain string fields ranked against a lookup table of literals, so a typo silently resolves to the least-restrictive rank instead of failing to compile. That one's worth prioritizing given the security-policy context.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Files scanned: 1,213 non-test .go files under pkg/
• Duplicate/near-duplicate clusters flagged: 13
• Patterns verified as intentional (build-tag variants or already well-factored) and excluded: 6
• Exact duplicates: 2
• Near duplicates: 6
• Semantic duplicates: 5

Cluster 1: AggregatedSummaryBase drift — pkg/cli (Near duplicate, High impact)

• pkg/cli/logs_models.go:171 defines AggregatedSummaryBase{Count, Workflows, WorkflowsDisplay, FirstReason, FirstReasonDisplay, RunIDs}.
• MissingToolSummary (:181) and MissingDataSummary (:196) correctly embed it.
• MCPFailureSummary (:187) manually re-declares 4 of the 6 fields instead of embedding — and the comment at :171 already flags this as a "copy-paste drift risk."

Recommendation: embed AggregatedSummaryBase in MCPFailureSummary like its siblings do. Mechanical, low-risk, ~15 minutes.

---

Cluster 2: AnalysisBase vs FirewallSummaryBase — pkg/cli (Exact duplicate, High impact)

• pkg/cli/domain_buckets.go:41 AnalysisBase embeds DomainBuckets{AllowedDomains, BlockedDomains} plus TotalRequests, AllowedRequests, BlockedRequests.
• pkg/cli/logs_report_firewall.go:17 FirewallSummaryBase declares the exact same five fields independently.

Recommendation: have FirewallSummaryBase compose AnalysisBase instead of re-declaring its fields.

---

Cluster 3: Cluster vs SnapshotCluster — pkg/agentdrain (Exact duplicate, High impact)

• pkg/agentdrain/types.go:32 Cluster{ID, Template, Size, Stage}.
• pkg/agentdrain/persist.go:21 SnapshotCluster — identical fields, only difference is JSON tags.
• persist.go:40-45 and :74-79 hand-copy every field between the two on every save/load.

Recommendation: add json tags directly to Cluster (or a MarshalJSON/UnmarshalJSON pair) and delete SnapshotCluster plus the copy loops.

---

Cluster 4: AuditComparisonIntDelta vs AuditComparisonStringDelta — pkg/cli (Near duplicate, generics candidate)

• pkg/cli/audit_comparison.go:45 {Before, After int; Changed bool} and :51 {Before, After string; Changed bool} — identical shape, different value type.

Recommendation: type AuditComparisonDelta[T comparable] struct { Before, After T; Changed bool }.

---

Cluster 5: RunOptions vs RunWorkflowOptions — pkg/cli (Near duplicate)

• pkg/cli/run_workflow_execution.go:31 RunOptions and pkg/cli/run_interactive.go:366 RunWorkflowOptions share 8 of 9 fields (Verbose, EngineOverride, RepoOverride, RefOverride, AutoMergePRs, Push, DryRun, Approve) with identical names/types.

Recommendation: extract a shared WorkflowRunFlags struct and embed it in both.

---

Cluster 6: Scanner Finding/Output boilerplate — pkg/cli (Semantic duplicate)

• Six independent security-scanner wrappers each redeclare a Finding + Output{ Findings []Finding } shape: poutine.go:24,35, grype.go:41,60, runner_guard.go:22,34, plus grant.go:47, zizmor.go:20, actionlint.go:98.

Recommendation: the per-tool Finding shapes genuinely differ (different JSON schemas), but the repeated Output{ Findings []X } wrapper is a good fit for type ScanOutput[F any] struct { Findings []F }.

---

Cluster 7: RepeatOptions vs PollOptions — pkg/cli (Semantic duplicate)

• pkg/cli/retry.go:20 and pkg/cli/signal_aware_poll.go:35 both model "run something repeatedly with signal-aware cancellation and start/progress messaging," implemented twice with parallel signal-handling logic.

Recommendation: evaluate whether ExecuteWithRepeat can be reimplemented on top of PollWithSignalHandling.

---

Cluster 8: GitHubMCPDockerOptions vs GitHubMCPRemoteOptions — pkg/workflow (Near duplicate)

• pkg/workflow/mcp_renderer_types.go:67-98 and :101-128 share 7 fields verbatim (ReadOnly, Lockdown, LockdownFromStep, GuardPoliciesFromStep, Toolsets, Features, AllowedTools, GuardPolicies), diverging only in Docker-specific vs. remote-specific fields.

Recommendation: extract a GitHubMCPCommonOptions struct for the shared fields, mirroring the BaseSafeOutputConfig pattern already used elsewhere in this package.

---

Cluster 9: MCPConfigRenderer vs MCPRendererOptions/MCPConfigRendererUnified — pkg/workflow (Semantic duplicate)

• pkg/workflow/mcp_config_types.go:40 and pkg/workflow/mcp_renderer_types.go:6 are two parallel "renderer options" abstractions carrying the same concepts (copilot-field toggle, format, guard policies, container pin mappings) under different field names, both still actively referenced (17 files use MCPConfigRenderer).

Recommendation: this likely needs an owner's call on whether the legacy path can migrate onto the unified renderer — flagged for a design conversation, not a blind merge.

---

Cluster 10: IntentRecord vs RootReference — pkg/intent (Semantic duplicate)

• pkg/intent/resolver.go:36 IntentRecord's Root*-prefixed fields (RootNodeID, RootType, RootURL, Labels) are a hand-flattened mirror of RootReference (:50). Every constructor (fromRoot, fromLabels, unlinked, ambiguous) manually maps one onto the other.

Recommendation: embed RootReference (or a pointer to it) inside IntentRecord instead of duplicating four fields by hand.

---

Cluster 11: *VarState deferred-cleanup tracking — four linters under pkg/linters/* (Near duplicate)

• manualmutexunlock/manualmutexunlock.go:158 (mutexVarState), httprespbodyclose/httprespbodyclose.go:166 (respVarState), contextcancelnotdeferred/contextcancelnotdeferred.go:129 (cancelVarState), fileclosenotdeferred/fileclosenotdeferred.go:162 (fileVarState) each implement the identical shape/algorithm for "was this resource closed via defer, manually, or not at all," keyed by map[types.Object]*XVarState.

Recommendation: hoist a generic tracker into pkg/linters/internal/ (which already houses astutil, analyzerutil, coverage, filecheck, nolint) parameterized by the "is this a manual cleanup call" predicate.

---

Cluster 12: Untyped-value conversion split — pkg/typeutil vs pkg/stringutil (Semantic duplicate)

• pkg/typeutil/convert.go already hosts ParseIntValue, ConvertToInt, ConvertToFloat (heterogeneous decoded-YAML/JSON value → typed). pkg/stringutil/stringutil.go:54 independently implements ParseVersionValue(any) string, doing the same kind of coercion in a different package.

Recommendation: move (or alias) the string-coercion helper next to typeutil's other converters.

---

Cluster 13: setutil.Contains underuse — pkg/linters/* (style/consistency, not a bug)

• pkg/setutil/setutil.go:6 defines Contains[K comparable](set map[K]struct{}, key K) bool, but most call sites (pkg/linters/internal/nolint/nolint.go:109-117, pkg/linters/globwalkignorederror/globwalkignorederror.go:22, pkg/linters/errormessage/errormessage.go:101-122) re-implement the _, ok := m[key] check inline. Only pkg/linters/ssljson/ssljson.go actually uses it.

Recommendation: low priority; switch inline checks to setutil.Contains for consistency when touching those files anyway.

---

Patterns verified as fine (not findings)

• RepositoryFeatures (repository_features_validation.go vs. _wasm.go), ProgressBar (console/progress.go vs. progress_wasm.go), and SpinnerWrapper (console/spinner.go vs. spinner_wasm.go) are legitimate (go/redacted):build native/WASM variants, not accidental drift.
• The safe-outputs *Config family in pkg/workflow (CreateIssuesConfig, CreatePullRequestsConfig, AddCommentsConfig, etc.) already composes BaseSafeOutputConfig + mixins (SafeOutputTargetConfig, SafeOutputAllowedLabelsConfig, SafeOutputFilterConfig, ...) via yaml:",inline" — a good pattern to hold up as the house style rather than a target for refactoring.
• pkg/parser/mcp.go:39's RegistryMCPServerConfig explicitly embeds types.BaseMCPServerConfig with a comment noting it's intentionally distinct from the workflow-side config — another positive example of doing this right.

---

Untyped Usages

Summary Statistics

• interface{} usages in production code: 0 (fully migrated to any; the only 18 repo-wide hits are in linter testdata/ fixtures used to test the linters that detect this exact anti-pattern)
• any usages flagged as fixable: 10
• any usages confirmed as legitimate (dynamic YAML/JSON, generic containers, required third-party signatures) and excluded: many — see notes below
• Untyped constants flagged: 6

Findings

#	Location	Current	Why it matters	Suggested fix
1	pkg/intent/policy.go:39,48	ExecutionPolicy.Autonomy, .WriteScope are plain string	Ranked against literal tables (autonomyRank, writeScopeRank); a typo silently resolves to the least-restrictive rank in a security-policy engine — fail-open risk	type Autonomy string / type WriteScope string with matching consts, mirroring this package's own AttributionStatus/AttributionSource enums
2	pkg/github/label_objective_mapping.go:27	ObjectiveMapping.MultiLabelLogic string	Constants MultiLabelLogicMax/Sum/First already exist in label_objective_mapping_constants.go:137-139 but are never referenced — the field still compares raw string literals	Change the field to the named type and use the existing constants
3	pkg/intent/resolver.go:41,46	IntentRecord.Rule, .RootType are plain string	Populated from a small closed set of literals ("issue", "artifact", "single_closing_issue", ...) scattered across the file, inconsistent with this package's own enum convention	Typed enums with named constants
4	pkg/workflow/awf_config.go:174	AWFConfigFile.Enclaves []map[string]any	Built field-by-field from a fully-typed source (EnclaveConfig) via addEnclaveString/addEnclaveInt helpers just to skip zero values	Define AWFEnclaveConfig with omitempty tags and drop the manual map-building helpers
5	pkg/workflow/safe_outputs_config_types.go:115, threat_detection_config.go:9-10	Steps/PostSteps []any	A concrete WorkflowStep type and SliceToSteps([]any) converter already exist (step_types.go:19,195), but each consumer re-does the type assertion individually (e.g. compiler_safe_outputs_job.go:242-247)	Convert to []*WorkflowStep at parse time; delete the duplicated per-consumer assertion logic
6	pkg/cli/run_workflow_execution.go:25	const workflowCompletionWaitTimeoutMinutes = 6 * 60 (untyped int "minutes")	Consumed via manual time.Duration(timeoutMinutes) * time.Minute conversion at pr_automerge.go:120-123	const workflowCompletionWaitTimeout = 6 * time.Hour as time.Duration; change the function signature to accept time.Duration directly
7	pkg/cli/update_org.go:27,31,37	orgUpdateCoreBuffer, orgUpdateSearchBuffer, orgUpdateCriticalConsumed — untyped rate-limit budget constants	Could be accidentally compared/added to unrelated int counters	type rateLimitBudget int
8	pkg/errorutil/errors.go:19,32,45	Bare string literals "404", "403", "410"	HTTP status codes expressed as untyped string constants instead of derived from net/http	strconv.Itoa(http.StatusNotFound) or a named constant block
9	pkg/console/console_types.go:50	FormField.Value any	Only construction site is a spec test that never sets it — dead API surface with no call site to confirm intended concrete type	Type concretely or remove
10	pkg/console/layout_wasm.go:16	LayoutEmphasisBox(content string, color any)	color param is unused in the body and has zero callers repo-wide	Remove the dead parameter (and function, if unused)

Lower-confidence / awaiting a design call

• pkg/workflow/safe_outputs_config_types.go:93 — SafeOutputsConfig.Data any is a genuine 4-way sum type (false/omitted, true, inline schema, or an expression string). A discriminated wrapper would remove the any but is a larger refactor — flagged for awareness, not a quick fix.
• pkg/workflow/mcp_config_types.go:54 and three sibling fields — GuardPolicies map[string]any, populated by deriveWriteSinkGuardPolicyFromWorkflow which does nested map navigation including key deletion. Closer to genuine dynamic tree manipulation; worth a conversation about a GuardPolicy/WriteSinkPolicy struct rather than a mechanical fix.
• pkg/cli/experiments_analyze_statistics.go:18,21 — defaultMinSamples, balanceSignificanceThreshold are untyped but low-risk; a SampleCount/PValue named type would make intent explicit rather than fix a real bug.
• pkg/cli/logs_models.go:338-339 — AwInfo.RunID any, .RunNumber any — comment suggests genuinely mixed-type input from varying agent-log JSON producers; no type-switch call sites found, so confidence is low on whether this is currently safe.

Confirmed legitimate (excluded from findings)

• pkg/typeutil — the package's entire purpose is being the typed boundary for decoding heterogeneous YAML/JSON config; its any usage is correct by design.
• pkg/types/input_definition.go:18 — InputDefinition.Default any is genuinely polymorphic (string/number/boolean from YAML), already resolved via a 5-way type switch, and explicitly documented as the sanctioned pattern other pkg/parser code points to.
• func run(pass *analysis.Pass) (any, error) across ~70 files in pkg/linters/* — required by the third-party golang.org/x/tools/go/analysis.Analyzer.Run signature; cannot be changed without forking that API.
• The bulk of map[string]any in pkg/parser (frontmatter/YAML traversal) and pkg/workflow (MCP tool config, model-pricing overlays) is genuine dynamic-document handling, already self-documented in-source as intentional.

---

Refactoring Recommendations

Priority 1 — Mechanical, low-risk consolidations

1. Embed AggregatedSummaryBase in MCPFailureSummary (Cluster 1) — the code already flags this itself.
2. Merge FirewallSummaryBase into AnalysisBase (Cluster 2).
3. Delete SnapshotCluster, add JSON tags to Cluster directly (Cluster 3).
4. Generify AuditComparisonIntDelta/StringDelta (Cluster 4).
5. Wire up the unused MultiLabelLogicMax/Sum/First constants (Untyped Add workflow: githubnext/agentics/weekly-research #2).

Estimated effort: half a day total across all five; each is independently shippable.

Priority 2 — Security-relevant and structural fixes

1. Type ExecutionPolicy.Autonomy/.WriteScope as enums (Untyped rejig docs #1) — this is the one I'd bump to the top given it's a fail-open risk in policy evaluation, not just a style nit.
2. Convert Steps/PostSteps to []*WorkflowStep at parse time (Untyped Add workflow: githubnext/agentics/weekly-research #5) — removes duplicated type-assertion logic at every call site.
3. Extract GitHubMCPCommonOptions (Cluster 8) and consider embedding RootReference in IntentRecord (Cluster 10).
4. Hoist the *VarState pattern into pkg/linters/internal (Cluster 11).

Estimated effort: 1-2 days; touches more call sites, worth a quick design nod from a reviewer before starting.

Priority 3 — Worth a conversation, not a quick PR

• MCPConfigRenderer vs. the unified renderer path (Cluster 9), SafeOutputsConfig.Data any sum type, and the GuardPolicies map[string]any tree manipulation are all real but larger design questions — flagging them here so they're on the radar, not proposing a specific mechanical fix.

---

Analysis Metadata

• Go files analyzed: 1,213 non-test files under pkg/
• Duplicate/near-duplicate clusters flagged: 13 (plus 3 patterns explicitly verified as fine)
• Untyped-usage findings: 10 fixable + 4 lower-confidence
• Detection method: parallel package-scoped greps/reads (pkg/cli, pkg/workflow, pkg/parser + small domain packages, pkg/linters + utilities), cross-checked against call sites before flagging
• Analysis date: 2026-08-13

Generated by ✍️ Typist - Go Type Analysis · agent · 535.4 AIC · ⌖ 46.1 AIC · ⊞ 8.7K · ◷

• expires on Aug 14, 2026, 3:47 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 #52704.