[typist] Typist - Go Type Consistency Analysis

[github-actions[bot]]

🔤 Typist - Go Type Consistency Analysis

Analysis of repository: github/gh-aw — scope: all non-test .go files under pkg/

Executive Summary

I scanned roughly 956 type definitions across pkg/workflow (372), pkg/cli (473), and the 30 smaller utility packages (111), skipping every _test.go file and lint-rule testdata/ fixtures. The good news first: the codebase has essentially completed its interface{} → any migration (only 4 stray interface{} hits remain, all in comments or a single test file), and most of the ~3,950 map[string]any/any occurrences are legitimate — they represent raw YAML frontmatter or JSON payloads before schema validation, which genuinely can't be statically typed yet. Several packages (pkg/actionpins, pkg/typeutil) already model this well with named enum types and documented "acceptable any" conventions.

Where it gets interesting: pkg/workflow and pkg/cli each have their own quiet "one struct wearing three names" problem. EngineCapabilities/EngineCapabilitiesDefinition are field-for-field identical (there's even a struct(x) conversion between them that only compiles because they're identical). pkg/cli/audit.go defines the same ~12-field "audit run configuration" three separate times (AuditOptions → auditCommandOptions → auditRunConfig), each one hand-copying the previous. And there are six-plus places using a bare string or int for what's clearly an enum or a duration — RunPhase, GitHub Actions run status/conclusion strings, a defaultSafeOutputsTimeoutMinutes that's really a time.Duration in disguise. None of these are bugs today, but they're exactly the kind of thing that causes a silent typo or an out-of-sync copy six months from now.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total types analyzed: ~956 (372 in pkg/workflow, 473 in pkg/cli, 111 across 30 smaller packages)
• Duplicate clusters found: 8
• Exact structural duplicates: 2 clusters (6 total occurrences)
• Near duplicates: 4 clusters
• Semantic/systemic duplicates: 2 clusters (repeated fields across 25+ structs)

Cluster 1: EngineCapabilities vs EngineCapabilitiesDefinition (near duplicate)

Impact: Medium — same 6 bool fields declared twice, one is the runtime type, one is the YAML-tagged declarative twin.

Locations:

1. pkg/workflow/agentic_engine.go:111 — EngineCapabilities struct { ToolsAllowlist, MaxTurns, WebSearch, MaxContinuations, NativeAgentFile, BareMode bool }
2. pkg/workflow/engine_definition.go:126 — EngineCapabilitiesDefinition — identical 6 fields, with yaml:"..." tags added.

Proof of equivalence: pkg/workflow/engine_definition.go:137 does a direct struct conversion:

func (d EngineCapabilitiesDefinition) ToRuntimeCapabilities() EngineCapabilities {
	return EngineCapabilities(d)
}

This only compiles because the two types have identical field names/order/types.

Recommendation: collapse to one type — either add yaml tags directly onto EngineCapabilities and delete EngineCapabilitiesDefinition, or make it a type alias (type EngineCapabilitiesDefinition = EngineCapabilities).
Estimated effort: <1 hour. Benefits: removes a manually-maintained 1:1 field mirror that will silently drift if one side gains a field.

---

Cluster 2: Safe-output "empty wrapper" configs (exact duplicate, 3-way)

Impact: Low-Medium — three types with zero unique fields.

Locations:

1. pkg/workflow/add_labels.go:10 — AddLabelsConfig
2. pkg/workflow/remove_labels.go — RemoveLabelsConfig
3. pkg/workflow/unassign_from_user.go:10 — UnassignFromUserConfig

All three are byte-for-byte identical compositions of BaseSafeOutputConfig + SafeOutputTargetConfig + SafeOutputFilterConfig + SafeOutputAllowBlockConfig, with no additional fields.

Recommendation: acceptable as-is if each needs a distinct type for the handler registry's func() any factory (see Category 1 below), but if that registry is ever refactored to use generics, these three collapse into one AllowBlockTargetConfig exposed via per-output type aliases.
Estimated effort: 1-2 hours (bundled with the factory registry work). Benefits: one definition instead of three to keep in sync.

---

Cluster 3: Safe-output "Base+Target+Filter" configs (exact duplicate, 3-way)

Impact: Low — same pattern as Cluster 2, one tier simpler.

Locations:

1. pkg/workflow/resolve_pr_review_thread.go:12 — ResolvePullRequestReviewThreadConfig
2. pkg/workflow/mark_pull_request_as_ready_for_review.go:10 — MarkPullRequestAsReadyForReviewConfig
3. pkg/workflow/dismiss_pull_request_review.go:8 — DismissPullRequestReviewConfig

All three = BaseSafeOutputConfig + SafeOutputTargetConfig + SafeOutputFilterConfig, no extra fields.

Recommendation: same as Cluster 2 — low priority, worth revisiting only if the safe-output handler registry moves to generics.

---

Cluster 4: AuditOptions → auditCommandOptions → auditRunConfig cascade (near duplicate)

Impact: High — the same ~12-field concept is manually re-declared three times in one file (verified against source: all three structs live in pkg/cli/audit.go, lines 25, 76, 309).

type AuditOptions struct {          // audit.go:25 — 14 fields (public API / cobra binding)
	Owner, Repo, Hostname, OutputDir string
	Verbose, Parse, JSONOutput       bool
	JobID                            int64
	StepNumber                       int
	Format                           string
	ArtifactSets                     []string
	ExperimentFilter, VariantFilter  string
	EvalsOnly                        bool
}

type auditCommandOptions struct {   // audit.go:76 — 11 fields, 9 map 1:1 to AuditOptions
	outputDir, verbose, jsonOutput, parse, repoFlag, format,
	artifacts, stdin, experimentFilter, variantFilter, evalsOnly ...
}

type auditRunConfig struct {        // audit.go:309 — 14 fields, 12 map 1:1 to AuditOptions
	runID, owner, repo, hostname, outputDir, verbose, parse,
	jsonOutput, jobID, stepNumber, artifactFilter,
	experimentFilter, variantFilter, evalsOnly, evalsArtifactRequested ...
}

Recommendation: have auditCommandOptions and auditRunConfig embed AuditOptions and add only the 1-2 genuinely distinct fields (stdin, evalsArtifactRequested) instead of re-declaring the whole field set at each pipeline stage.
Estimated effort: 2-3 hours (touches cobra flag binding + downstream call sites). Benefits: one field to add/rename instead of three; removes an entire class of "I updated AuditOptions but forgot auditRunConfig" bugs.

---

Cluster 5: Systemic Verbose/JSONOutput repetition across ~25 CLI Options structs (semantic duplicate)

Impact: Medium — not a correctness risk today, but a maintenance smell at scale.

Verbose bool is independently declared in 25+ structs (RunOptions, TrialOptions, AuditOptions, OutcomesConfig, HealthConfig, ChecksConfig, ForecastConfig, CompileConfig, DockerImagesOptions, LogsDownloadOptions, StdinLogsOptions, InitOptions, AddOptions, ViewOptions, PollOptions, UpgradeConfig, and more), and JSONOutput/JSON bool repeats in 19 of them. RunOptions and TrialOptions alone share 5 of ~13 fields (Verbose, DryRun, RepeatCount, AutoMergePRs, EngineOverride).

Recommendation: introduce a small embeddable CommonCLIFlags{ Verbose, JSONOutput bool } that command-specific Options structs embed. The codebase already does this well elsewhere — AggregatedSummaryBase, DiffEntryBase, and FirewallSummaryBase in pkg/cli are good existing templates to copy.
Estimated effort: 4-6 hours (mechanical but touches ~25 files). Benefits: adding a new common flag becomes a one-line change instead of a 25-file find-and-replace.

---

Cluster 6: FlexibleID-shaped any fields, duplicated 4 times (semantic duplicate)

Impact: Low-Medium — same "JSON id may be string or number" pattern reinvented independently.

Locations:

• pkg/cli/gateway_logs_types.go:148,159 — rpcRequestPayload.ID any, rpcResponsePayload.ID any (JSON-RPC 2.0 id — spec-mandated ambiguity)
• pkg/cli/mcp_tools_privileged.go:299-300 — logsArgs.RunID any, RunIDOrURL any
• pkg/cli/logs_models.go:323-324 — WorkflowRunInfo.RunID any, RunNumber any

Recommendation: each occurrence is individually justified (JSON's string/number ambiguity), but four independent ad hoc implementations of the same idea is worth a single shared type, e.g. type FlexibleID any plus one func (FlexibleID) String() string normalizer, instead of four separate type-assertion sites.
Estimated effort: 1-2 hours. Benefits: one normalization helper instead of four copies of the same type-switch.

---

Cluster 7: Position/location tracking, pkg/console vs pkg/parser (near duplicate)

Impact: Low — small structs, but a clean case for pkg/types (which already exists as this repo's shared-type bridge).

Locations:

• pkg/console/console_types.go:4 — ErrorPosition{ File string; Line int; Column int }
• pkg/parser/json_path_locator.go:23 — JSONPathLocation{ Line int; Column int; Found bool }

2 of 3 fields match by name and type (Line, Column).

Recommendation: extract a shared types.LineColumn{ Line, Column int } into pkg/types (which pkg/parser already imports) and embed it in both. Low urgency, cheap fix.
Estimated effort: <1 hour.

---

Cluster 8: pkg/types is (mostly) doing its job — noted as a positive pattern to reinforce

pkg/types.BaseMCPServerConfig is correctly embedded by pkg/parser.RegistryMCPServerConfig rather than re-declared, and pkg/types.InputDefinition is reused via a type alias (ImportInputDefinition = types.InputDefinition) in pkg/parser/import_processor.go:96. No action needed — flagging so future consolidation work (Clusters 1, 4, 5, 7) follows this existing convention rather than inventing a new shared-types location.

One thing to double check when pkg/workflow's own container/action-pin types are touched: pkg/actionpins (ActionPin, ContainerPin, ActionPinsData — pkg/actionpins/actionpins.go:40,48,55) deliberately avoids depending on pkg/workflow, but pkg/workflow has its own pinning-related types for the same concept. This wasn't fully cross-referenced (out of scope for this pass) — worth a follow-up look before assuming no overlap.

---

Untyped Usages

Summary Statistics

• interface{} usages (non-test, non-comment): 0 — fully migrated to any
• any usages: pervasive (~3,950 map[string]any/any occurrences across pkg/workflow ~1,694, pkg/cli ~2,204, other packages ~50-60), but the large majority are justified — see below
• Untyped constants flagged as genuine candidates: ~15
• Total untyped locations reported as actionable: ~25

Category 1: any in function signatures — one clear generics candidate

Impact: Medium

pkg/workflow/safe_output_handlers.go:17 — safeOutputHandlerDescriptor.NewConfig func() any, instantiated ~40 times as func() any { return &XConfig{} } (each closure always returns exactly one concrete pointer type).

• Suggested fix: make the descriptor generic, e.g. Descriptor[T any]{ NewConfig func() *T }, removing the runtime type assertions the consumer side currently needs.
• Benefits: compile-time guarantee that each handler's config type matches its factory; currently a mismatch would only surface as a runtime panic on type assertion.
• Effort: Medium — real gain, but touches ~40 call sites, so worth doing as its own follow-up rather than bundled with the smaller fixes above.

pkg/cli/actions.go:15 — convertToGitHubActionsEnv(env any, envVarMetadata []EnvironmentVariable) map[string]string. All 3 call sites (pkg/cli/mcp_add.go:200,222,271) pass a value pulled from server.Config["env"] where Config map[string]any — always a map[string]any at runtime.

// Suggested
func convertToGitHubActionsEnv(env map[string]any, envVarMetadata []EnvironmentVariable) map[string]string

• Benefits: makes the internal env.(map[string]any) type-assertion branch dead code and removes a silent no-op path.
• Effort: <1 hour, low risk.

Category 2: Struct fields — mostly acceptable, one clear miss

Impact: Low-Medium

• pkg/parser/import_observability.go:18 — Headers any (JSON field). HTTP headers are always key/value — this should be map[string]string or at minimum map[string]any, not bare any. Suggested fix: narrow to a concrete map type.
• pkg/workflow/safe_outputs_config_types.go:109 — ReportFailureAsIssue any (comment: "bool, templatable expression string, or []interface{} categories"). The codebase already has a Templatable* convention (TemplatableBool, TemplatableInt32 in templatables.go) for exactly this "small closed set of YAML shapes" problem — this field predates or missed that convention. Suggested fix: normalize into a TemplatableReportFailureAsIssue-style discriminated type, consistent with the rest of the package.
• Everything else flagged (FormField.Value any in pkg/console, RunsOn any/On any GitHub Actions fields in pkg/cli, JSON-RPC ID any, MCP Default any) mirrors genuine upstream schema ambiguity (GitHub Actions YAML, JSON-RPC spec) and is correctly left as any.

Category 3: map[string]any — overwhelmingly acceptable

Impact: Informational only

Across all three packages, map[string]any is near-universally tied to parsing raw YAML frontmatter or external JSON (GraphQL/REST payloads, MCP registry manifests, JSON-schema documents) before schema validation happens. Several files even carry explicit comments marking this as an intentional, documented pattern (e.g. pkg/parser/import_processor.go: "This is an appropriate use of 'any' for dynamic YAML/JSON data"). This is idiomatic for a YAML-driven compiler and is not a refactoring target as a category — only the two specific misses in Category 2 stood out as exceptions.

Category 4: Untyped constants — the highest-value, lowest-risk findings

Impact: Medium — these are the "6 months from now, someone typos a magic string" risk class.

Enum-shaped strings with no named type (the package already has the right pattern elsewhere — PermissionLevel, ActionMode, pkg/actionpins.ResolutionErrorType — these are just stragglers):

• pkg/workflow/run_phase.go:4-6 — runPhaseAgent = "agent", runPhaseDetection = "detection", runPhaseEvals = "evals", returned as bare string from workflowRunPhase(). → type RunPhase string with 3 named constants.
• pkg/workflow/safe_outputs_validation.go:14-15 — SafeOutputsURLsPolicyAllowedOnly/AllowedOrCodeRegion, consumed by a plain string field. → type SafeOutputsURLsPolicy string.
• pkg/workflow/mcp_scripts_parser.go:65 — MCPScriptsModeHTTP = "http", commented as "the available transport modes" (implying more are coming). → type MCPScriptsMode string now, before a second mode makes this a bigger refactor.
• pkg/workflow/compiler_experiments.go:25,29 — ExperimentsStorageCache/ExperimentsStorageRepo. → type ExperimentsStorageMode string.
• pkg/cli/run_workflow_execution.go:52, pkg/cli/status_command.go:32,36,37, pkg/cli/checks_command.go — WorkflowRunResult.Status, WorkflowStatus.Status/RunStatus/RunConclusion all typed bare string for GitHub Actions status/conclusion values, recurring across 4 files with no compile-time guard against a typo like "succes" or "trigerred". This is the broadest single Category-4 finding — worth a shared named type reused across all 4 sites rather than 4 separate local fixes.
• pkg/console/console_types.go:13,46 — CompilerError.Type string ("error"|"warning"|"info") and FormField.Type string ("input"|"password"|"confirm"|"select") — same untyped-enum pattern, smaller blast radius.

Duration/threshold constants missing their unit type:

• pkg/workflow/compiler_safe_outputs_job.go:539 — const defaultSafeOutputsTimeoutMinutes = 45 (bare int) vs. pkg/workflow/repository_features_validation.go:59's repositoryFeaturesTimeout = 3 * time.Second, which does it correctly. → redefine as 45 * time.Minute (time.Duration).
• pkg/cli/run_workflow_execution.go:26 — workflowCompletionWaitTimeoutMinutes = 6 * 60 (bare int minutes). → 6 * time.Hour.
• pkg/cli/audit_cross_run.go:14,18,22 — mcpErrorRateThreshold = 0.10, mcpConnectionRateThreshold = 0.75, spikeDetectionMultiplier = 2.0 — untyped floats mixing "threshold" and "multiplier" semantics with no type distinguishing them. → a type ratio float64 would self-document intent and block an accidental threshold/multiplier swap at a call site.

🎯 What Should We Do About This?

Prioritized by effort-to-impact ratio — the first four are all under an hour each and directly prevent a future silent-drift bug:

Priority 1 — Quick wins (each < 1 hour, do first)

1. Collapse EngineCapabilities/EngineCapabilitiesDefinition (Cluster 1) — delete the manually-mirrored twin.
2. Fix convertToGitHubActionsEnv(env any, ...) → map[string]any (Category 1) — call sites already only ever pass that type.
3. Fix Headers any → concrete map type in pkg/parser/import_observability.go:18 (Category 2).
4. Add named types for RunPhase and SafeOutputsURLsPolicy (Category 4) — the package already has the convention, these are just stragglers.

Priority 2 — Medium effort, real safety gain

1. Collapse the AuditOptions/auditCommandOptions/auditRunConfig cascade in pkg/cli/audit.go via embedding (Cluster 4).
2. Introduce a shared named type for GitHub Actions run status/conclusion strings, used across run_workflow_execution.go, status_command.go, checks_command.go (Category 4) — the single broadest untyped-enum finding.
3. Redefine defaultSafeOutputsTimeoutMinutes and workflowCompletionWaitTimeoutMinutes as time.Duration (Category 4).

Priority 3 — Larger, opportunistic refactors

1. Generic-ize the safe_output_handlers.go func() any factory registry (Category 1) — worth doing on its own, ~40 call sites.
2. Introduce CommonCLIFlags{ Verbose, JSONOutput bool } and have the ~25 CLI Options structs embed it (Cluster 5).
3. Consolidate the 4-way FlexibleID-style any fields into one shared type (Cluster 6).
4. Extract types.LineColumn for the console/parser position structs (Cluster 7).

Implementation Checklist

• Collapse EngineCapabilities/EngineCapabilitiesDefinition
• Type convertToGitHubActionsEnv's env parameter concretely
• Type import_observability.go's Headers field concretely
• Add RunPhase and SafeOutputsURLsPolicy named types
• Consolidate AuditOptions/auditCommandOptions/auditRunConfig
• Add a shared named type for GitHub Actions run status/conclusion strings
• Convert the two bare-int timeout constants to time.Duration
• (Follow-up) Generics pass on safe_output_handlers.go's config factory registry
• (Follow-up) CommonCLIFlags embed for the ~25 CLI Options structs
• Run full test suite after each change

Analysis Metadata

• Total Go files analyzed: ~1,163 non-test .go files under pkg/ (excluding testdata/)
• Total type definitions found: ~956
• Duplicate clusters: 8
• Untyped usage locations flagged: ~25 (10 any params/fields + ~15 untyped constants)
• Detection method: parallel semantic analysis across pkg/workflow, pkg/cli, and the remaining 30 utility packages, with spot-verification via direct source reads on the highest-priority claims (EngineCapabilities, AuditOptions cascade, run_phase.go)
• Analysis date: 2026-07-29

Generated by ✍️ Typist - Go Type Analysis · age00 · 421.3 AIC · ⌖ 14.1 AIC · ⊞ 8.6K · ◷

• expires on Jul 30, 2026, 4:15 AM UTC-08:00

[github-actions[bot]]

Smoke test bot check-in 🤖 — automated systems report all green. Carry on, humans (and bots)!

Warning

Firewall blocked 6 domains

The following domains were blocked by the firewall during workflow execution:

• accounts.google.com
• android.clients.google.com
• clients2.google.com
• contentautofill.googleapis.com
• safebrowsingohttpgateway.googleapis.com
• www.google.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "accounts.google.com"
    - "android.clients.google.com"
    - "clients2.google.com"
    - "contentautofill.googleapis.com"
    - "safebrowsingohttpgateway.googleapis.com"
    - "www.google.com"

See Network Configuration for more information.

📰 BREAKING: Report filed by Smoke Copilot · aut00 · 54.7 AIC · ⌖ 7.42 AIC · ⊞ 8.3K · ◷
_{Comment /smoke-copilot to run again
Add label smoke to run again}