[typist] Go Type Consistency Analysis

[github-actions[bot]]

Executive Summary

Analyzed 812 non-test Go files under pkg/ covering ~722 type definitions. The codebase has clearly been migrating from untyped maps to strongly-typed structs (semantic types like EngineName, JobName, StepID, MCPServerID are in place, and ParsedTools *Tools is being introduced alongside the legacy Tools map[string]any), so the remaining issues are concentrated in specific in-flight transitions rather than scattered widely.

Two high-impact themes emerge: (1) the GitHub MCP accessor family in pkg/workflow/mcp_github_config.go still takes githubTool any and re-asserts to map[string]any even though *GitHubToolConfig is already populated on WorkflowData.ParsedTools.GitHub; (2) a cluster of three structs in pkg/cli/logs_models.go (ProcessedRun, RunSummary, DownloadResult) duplicates ~15 fields each describing an analyzed workflow run. Lower-priority opportunities include grouping 11 *Output and 11 Artifact* string constants under semantic types (OutputName, ArtifactName) to match the existing convention.

Metric	Count
Go files analyzed (pkg/, non-test)	812
Type definitions found	~722
Duplicate clusters reported	12
any occurrences (raw)	1,437
Untyped const declarations	309
High-impact recommendations	4

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total types analyzed: ~722
• Duplicate clusters reported: 12
• Exact duplicates: 3 (incl. one false-positive cluster gated by build tags)
• Near duplicates: 7
• Semantic duplicates: 1
• Build-tag pairs (intentional): 1 cluster

Cluster 1 — ProcessedRun / RunSummary / DownloadResult (near, high)

Locations:

1. pkg/cli/logs_models.go:90 — type ProcessedRun struct {
2. pkg/cli/logs_models.go:203 — type RunSummary struct {
3. pkg/cli/logs_models.go:229 — type DownloadResult struct {

All three carry the same 15+ analysis fields (WorkflowRun, AwContext, TaskDomain, BehaviorFingerprint, AccessAnalysis, FirewallAnalysis, RedactedDomainsAnalysis, MissingTools, MissingData, Noops, MCPFailures, MCPToolUsage, TokenUsage, GitHubRateLimitUsage, JobDetails). Each adds 1–3 variant-specific extras: RunSummary adds CLIVersion/RunID/ProcessedAt/Metrics/ArtifactsList; DownloadResult adds Error/Skipped/Cached/LogsPath/Metrics; ProcessedRun adds PolicyAnalysis.

Recommendation: Extract a shared RunAnalysis carrying the common fields and have RunSummary/DownloadResult embed it plus their distinguishing fields. Eliminates ~40 lines of duplicated field declarations and locks the JSON shape in one place.

Cluster 2 — TokenClassWeights vs tokenClassWeights (exact, high)

Locations:

1. pkg/types/token_weights.go:7 — type TokenClassWeights struct {
2. pkg/cli/effective_tokens.go:46 — type tokenClassWeights struct {

Both define identical 5 float64 fields (Input, CachedInput, Output, Reasoning, CacheWrite). The only delta is JSON tag style (hyphens vs underscores). The cli copy is package-private and used only to deserialize the embedded model_multipliers.json.

Recommendation: Drop the private tokenClassWeights and reuse pkg/types.TokenClassWeights. If the on-disk underscore form must stay, add a small wrapper or alternate UnmarshalJSON.

Cluster 3 — experimentStateJSON / ExperimentState & experimentRunRecord / ExperimentRunRecord (near, high)

Locations:

1. pkg/cli/audit_report_experiments.go:35 — type experimentStateJSON struct {
2. pkg/cli/audit_report_experiments.go:42 — type experimentRunRecord struct {
3. pkg/cli/experiments_command.go:31 — type ExperimentState struct {
4. pkg/cli/experiments_command.go:37 — type ExperimentRunRecord struct {

Both files deserialize the same state.json written by pick_experiment.cjs. ExperimentState ↔ experimentStateJSON have the same 2 fields (Counts, Runs); ExperimentRunRecord ↔ experimentRunRecord have the same 3 fields (RunID, Timestamp, Assignments). One pair is exported; the other is package-private in a sibling file.

Recommendation: Delete the private duplicates in audit_report_experiments.go and import the exported types — or hoist both to a new pkg/cli/experiments_types.go.

View remaining duplicate clusters (9)

Cluster 4 — CacheMemoryToolConfig / RepoMemoryToolConfig / CommentMemoryToolConfig (exact, medium)

• pkg/workflow/tools_types.go:400 — type CacheMemoryToolConfig struct { Raw any }
• pkg/workflow/repo_memory.go:62 — type RepoMemoryToolConfig struct { Raw any }
• pkg/workflow/tools_types.go:407 — type CommentMemoryToolConfig struct { Raw any }

Identical single-field wrappers (Raw any "yaml:-") used as parse-time placeholders that defer to dedicated parsers. Differ only by name.

Recommendation: Define a single RawToolConfig struct{ Raw any } and either alias each name or just reuse the one type.

Cluster 5 — AccessLogSummary vs FirewallLogSummary (near, medium)

• pkg/cli/logs_report_firewall.go:12 — type AccessLogSummary struct {
• pkg/cli/logs_report_firewall.go:22 — type FirewallLogSummary struct {

Both summarize aggregated log requests across runs. Same shape (TotalRequests, Allowed*, Blocked*, AllowedDomains, BlockedDomains, ByWorkflow), but field names differ (AllowedCount vs AllowedRequests) and FirewallLogSummary adds RequestsByDomain. The aggregateDomainStats helper already abstracts the difference via a callback.

Recommendation: Unify into one LogSummary with an optional RequestsByDomain and consistent count field names.

Cluster 6 — DomainAnalysis vs FirewallAnalysis (near, medium)

• pkg/cli/access_log.go:33 — type DomainAnalysis struct {
• pkg/cli/firewall_log.go:131 — type FirewallAnalysis struct {

Both embed DomainBuckets and add TotalRequests + allowed/blocked counters. Field names differ (AllowedCount/BlockedCount vs AllowedRequests/BlockedRequests); FirewallAnalysis adds RequestsByDomain. Both implement the same LogAnalysis interface with near-identical AddMetrics methods.

Recommendation: Promote a shared DomainCounters (TotalRequests, Allowed, Blocked) into DomainBuckets, then make FirewallAnalysis its strict superset.

Cluster 7 — ResolutionFailure vs GHAWManifestResolutionFailure (exact, medium)

• pkg/actionpins/actionpins.go:74 — type ResolutionFailure struct { Repo, Ref, ErrorType }
• pkg/workflow/safe_update_manifest.go:39 — type GHAWManifestResolutionFailure struct { Repo, Ref, ErrorType }

Same 3 fields representing an action-ref pinning failure. The workflow variant adds JSON tags for lock-file serialization; they are populated from each other across package boundaries.

Recommendation: Add JSON tags to pkg/actionpins.ResolutionFailure and delete GHAWManifestResolutionFailure.

Cluster 8 — WorkflowStatus vs WorkflowListItem (near, low)

• pkg/cli/list_workflows_command.go:20 — type WorkflowListItem struct {
• pkg/cli/status_command.go:24 — type WorkflowStatus struct {

WorkflowStatus is a strict superset of WorkflowListItem (same Workflow/EngineID/Compiled/Labels/On with identical console tags, plus Status/TimeRemaining/RunStatus/RunConclusion).

Recommendation: Embed WorkflowListItem into WorkflowStatus so the JSON shape stays a strict extension and the list/status commands share the same row marshaller.

Cluster 9 — FirewallDiffSummary / MCPToolsDiffSummary / ToolCallsDiffSummary (near, low)

• pkg/cli/audit_diff.go:50 — type FirewallDiffSummary struct {
• pkg/cli/audit_diff.go:240 — type MCPToolsDiffSummary struct {
• pkg/cli/audit_diff.go:299 — type ToolCallsDiffSummary struct {

All three are small summary structs with parallel New/Removed/Changed counters plus a couple of variant-specific extras (e.g., HasAnomalies, VolumeChangeCount).

Recommendation: Introduce a shared DiffCounts (NewCount, RemovedCount, ChangedCount) embedded inside each summary, keeping variant-specific extras as separate fields.

Cluster 10 — PullRequest vs PRInfo (semantic, low)

• pkg/cli/pr_automerge.go:21 — type PullRequest struct {
• pkg/cli/pr_command.go:27 — type PRInfo struct {

Both model a GitHub PR decoded from gh pr output. PRInfo carries more metadata (Body, branches, repos, author); PullRequest carries Mergeable/CreatedAt/UpdatedAt. Both live in the same package, hinting at parallel evolution.

Recommendation: Define one PullRequest superset in a shared pr_types.go with omitempty on all optional fields.

Cluster 11 — WorkflowRunInfo / ListWorkflowRunsOptions / WorkflowRunResult (near, low)

• pkg/cli/run_workflow_tracking.go:19 — type WorkflowRunInfo struct {
• pkg/cli/logs_github_api.go:168 — type ListWorkflowRunsOptions struct {
• pkg/cli/run_workflow_execution.go:46 — type WorkflowRunResult struct {

Three workflow-run-centric structs scattered across run_*.go and logs_*.go with overlapping run-identity fields (run id, workflow name, status). The codebase already has the heavier WorkflowRun in logs_models.go.

Recommendation: Audit which fields are actually consumed by each caller, then either reuse WorkflowRun or compose around it. At minimum group these under a single run_types.go so the duplication is visible.

Cluster 12 — Build-tag pairs (false positive, low)

• pkg/workflow/repository_features_validation.go:58 ↔ repository_features_validation_wasm.go:5 (RepositoryFeatures)
• pkg/console/spinner.go:96 ↔ spinner_wasm.go:10 (SpinnerWrapper)
• pkg/console/progress.go:31 ↔ progress_wasm.go:7 (ProgressBar)

Intentional native-vs-WASM build-tag variants. Listed here only to prevent confusion. Keep as-is.

Untyped Usages

Summary Statistics

• Raw interface{} occurrences (literal text): 0 — the codebase consistently uses any
• any occurrences: 1,437 — most are legitimate YAML/JSON polymorphic boundaries
• Untyped const declarations: 309 — many are already typed via semantic aliases; ~22 in one file are the main remaining opportunity

Category 1 — func_param for GitHub MCP accessors (high)

GitHub MCP accessor functions take githubTool any and immediately assert to map[string]any, despite a parsed *GitHubToolConfig existing in parallel on WorkflowData.ParsedTools.GitHub. All call sites pass the same data.Tools["github"]. Migrating eliminates ~11 redundant assertions in one file plus ~7 call-site asserts.

Examples:

• pkg/workflow/mcp_github_config.go:138 — func getGitHubType(githubTool any) string
  • Actual: *GitHubToolConfig
  • Suggested: func getGitHubType(cfg *GitHubToolConfig) string
  • Rationale: body asserts toolConfig.(map[string]any) then reads toolConfig["type"] / toolConfig["mode"] — both already exist as cfg.Type / cfg.Mode.
• pkg/workflow/mcp_github_config.go:163 — func getGitHubToken(githubTool any) string → func getGitHubToken(cfg *GitHubToolConfig) string. Reads only toolConfig["github-token"].(string).
• pkg/workflow/mcp_github_config.go:182 — func getGitHubLockdown(githubTool any) bool → func getGitHubLockdown(cfg *GitHubToolConfig) bool.
• pkg/workflow/mcp_github_config.go:264 — func getGitHubAllowedTools(githubTool any) []string → func getGitHubAllowedTools(cfg *GitHubToolConfig) []string. Walks toolConfig["allowed"] as []any of strings.
• pkg/workflow/mcp_renderer_github.go:17 — RenderGitHubMCP(yaml, githubTool any, ...) → RenderGitHubMCP(yaml, cfg *GitHubToolConfig, ...). Delegates entirely to the getGitHub* accessors above; tightening cascades.

Category 2 — struct_field for dual Tools storage (high)

WorkflowData.Tools map[string]any is the legacy untyped tools map; a strongly-typed ParsedTools *Tools already exists alongside it as part of an in-progress migration (see the comment (NEW: parsed from Tools map)). Many consumers still read the untyped map.

• pkg/workflow/compiler_types.go:482 — Tools map[string]any
  • Actual: same content as ParsedTools *Tools on the next line
  • Suggested: remove the raw Tools map and route all readers through ParsedTools (or expose accessors on *Tools).
  • Rationale: dual storage forces every consumer that wants typed access to first do data.Tools["github"].(map[string]any).

Category 3 — type_assertion_pattern on data.Tools[<name>] (high)

map[string]any assertions on data.Tools[<name>] recur across compiler_difc_proxy.go, workflow_github_app.go, compiler_github_mcp_steps.go, compiler_yaml.go, and mcp_github_config.go — each call walks the same legacy map for the GitHub tool config.

• pkg/workflow/compiler_difc_proxy.go:85 — githubTool, hasGitHub := data.Tools["github"]; ... return len(getGitHubGuardPolicies(githubTool)) > 0 → use data.ParsedTools.GitHub directly.
• pkg/workflow/mcp_github_config.go:85 — if toolConfig, ok := githubTool.(map[string]any); ok { _, hasGitHubApp := toolConfig["github-app"]; ... } → return cfg != nil && cfg.GitHubApp != nil. The same assert-then-lookup-by-key pattern repeats 11 times in this file with hard-coded YAML key strings.

Category 4 — untyped_const for step-output names (medium)

11 step-output name constants in pkg/constants/job_constants.go:207-217 are declared as plain untyped strings, despite the file defining semantic types JobName, StepID, and MCPServerID for the analogous identifiers a few lines above.

• pkg/constants/job_constants.go:207 — const IsTeamMemberOutput = "is_team_member"
  • Suggested: type OutputName string; const IsTeamMemberOutput OutputName = "is_team_member"
  • Rationale: these appear in ${{ steps.<id>.outputs.<output> }} expressions next to StepID constants; an OutputName alias matches the existing convention and prevents mixing with JobName/StepID.
• pkg/constants/job_constants.go:217 — const ActivatedOutput = "activated" → const ActivatedOutput OutputName = "activated". Group-migrate all 11 *Output constants in this range.

Category 5 — untyped_const for artifact names and filenames (medium)

11 artifact-name and filename constants in pkg/constants/job_constants.go:90-170 are plain untyped strings, even though the file already defines analogous semantic types for other identifier classes.

• pkg/constants/job_constants.go:95 — const AgentArtifactName = "agent" → type ArtifactName string; const AgentArtifactName ArtifactName = "agent". Covers SafeOutputArtifactName, AgentArtifactName, DetectionArtifactName, ActivationArtifactName, ExperimentArtifactName, SafeOutputItemsArtifactName, SarifArtifactName — same domain, same APIs.
• pkg/constants/job_constants.go:105 — const AgentOutputFilename = "agent_output.json" → type ArtifactFilename string; const AgentOutputFilename ArtifactFilename = "agent_output.json". Covers AgentOutputFilename, SafeOutputsFilename, TokenUsageFilename, GithubRateLimitsFilename, OtelJsonlFilename, OtlpExportErrorsFilename, TemporaryIdMapFilename, SarifFileName.

Deliberately not flagged

• frontmatter map[string]any and tools map[string]any parameters (~1,400 occurrences) — YAML pass-through boundaries serving multiple polymorphic schemas.
• containsTrigger(any), normalizeOTLPHeadersForEndpoint(any), marshalImportInputValue(any), containsExpression(any), validateImportInputType(any) — legitimate sum-type / recursive-traversal patterns over heterogeneous YAML nodes.
• CacheMemoryToolConfig.Raw any, CommentMemoryToolConfig.Raw any — explicitly documented as polymorphic (bool/object/array) with dedicated parsers.
• Constants in url_constants.go, engine_constants.go, version_constants.go, top of constants.go — already typed (URL, DocURL, EngineName, Version, JobName, StepID, MCPServerID, CommandPrefix, LineLength, WorkflowID, FileMode).

Refactoring Recommendations

Priority 1 — Tighten GitHub MCP accessor signatures (high, ~half day)

Steps:

1. Change every func getGitHub*(githubTool any, ...) in pkg/workflow/mcp_github_config.go to take cfg *GitHubToolConfig.
2. Replace toolConfig.(map[string]any) + toolConfig["<key>"] lookups with struct field reads (cfg.Type, cfg.Mode, cfg.GitHubToken, cfg.Allowed.ToStringSlice(), ...).
3. Update call sites in compiler_difc_proxy.go, workflow_github_app.go, compiler_github_mcp_steps.go, compiler_yaml.go, mcp_renderer_github.go to pass data.ParsedTools.GitHub instead of data.Tools["github"].
4. Run go test ./... and verify generated YAML is byte-identical.

Benefit: removes ~11 redundant type assertions and ~16 hard-coded YAML key strings in one file; pulls the GitHub tool config fully onto the typed ParsedTools rail.

Priority 2 — Consolidate run-analysis structs in logs_models.go (high, half to one day)

Steps:

1. Extract the 15 shared fields between ProcessedRun, RunSummary, DownloadResult into a RunAnalysis struct.
2. Embed RunAnalysis in each of the three and keep only the distinguishing fields.
3. Validate the JSON shape is unchanged with go test and a diff over a sample report.

Benefit: removes ~40 lines of duplicated declarations; one place to add new analysis dimensions.

Priority 3 — Delete cross-file private duplicates (high, < 1 hour each)

• pkg/cli/effective_tokens.go:tokenClassWeights → reuse pkg/types.TokenClassWeights (add an alternate UnmarshalJSON if the underscore tag form must stay on disk).
• pkg/cli/audit_report_experiments.go:experimentStateJSON / experimentRunRecord → import ExperimentState/ExperimentRunRecord from experiments_command.go.
• pkg/workflow/safe_update_manifest.go:GHAWManifestResolutionFailure → add JSON tags to pkg/actionpins.ResolutionFailure and reuse.

Priority 4 — Migrate untyped constants to semantic types (medium, half a day)

Steps:

1. Add type OutputName string and re-type all *Output constants in pkg/constants/job_constants.go:207-217.
2. Add type ArtifactName string and type ArtifactFilename string and re-type the corresponding constants in pkg/constants/job_constants.go:90-170.
3. Update consumers (most are string-concat or ${{ steps.... }} template builders — they accept the underlying string).

Benefit: matches the existing semantic-alias convention (JobName, StepID, MCPServerID); prevents mixing constant kinds at call sites.

Implementation Checklist

• Priority 1: tighten GitHub MCP accessors to *GitHubToolConfig
• Priority 2: extract shared RunAnalysis in pkg/cli/logs_models.go
• Priority 3a: delete tokenClassWeights duplicate in pkg/cli/effective_tokens.go
• Priority 3b: delete experimentStateJSON / experimentRunRecord duplicates in pkg/cli/audit_report_experiments.go
• Priority 3c: merge GHAWManifestResolutionFailure into pkg/actionpins.ResolutionFailure
• Priority 4: add OutputName, ArtifactName, ArtifactFilename semantic types
• Lower priority: shared RawToolConfig, unify *LogSummary, embed WorkflowListItem in WorkflowStatus, shared DiffCounts in audit_diff.go
• Investigate the parallel WorkflowRun / WorkflowRunInfo / WorkflowRunResult family for consolidation
• Run go test ./... and full generation diff after each priority

Analysis Metadata

• Total Go files analyzed: 812 (under pkg/, excluding _test.go)
• Total type definitions: ~722
• Duplicate clusters: 12 (3 exact incl. 1 false-positive build-tag pair, 7 near, 1 semantic)
• Untyped usage categories: 5 actionable
• Detection method: Serena semantic analysis + ripgrep pattern matching, cross-referenced by reading each candidate file
• Analysis date: 2026-05-19

References:

• §26096758192

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

• expires on May 20, 2026, 12:37 PM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #33529.