[typist] Typist - Go Type Consistency Analysis #25280

2026-04-08T11:45:43Z

github-actions[bot]
bot Apr 8, 2026

This report covers a semantic analysis of 665 non-test Go source files in pkg/. The analysis identified several naming collisions, near-duplicate struct definitions, and intentional but noteworthy any/map[string]any usage patterns.

Key Metrics

Total non-test Go files analyzed: 665
Total type definitions found: ~677 (494 structs, 17 interfaces, 8 type aliases, remainder function/string types)
Duplicate name clusters: 6 (across different packages)
Near-identical struct pair: 1 (high-impact consolidation candidate)
Struct fields using any or map[string]any: ~25 distinct locations
Untyped numeric constants: 4

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

Metric	Count
Type name clusters (same name, different package)	6
Exact/near-identical field duplicates	1
Naming collisions (same name, different kind)	2
Platform-specific stub pairs (build tags)	3

Cluster 1: `WorkflowTrialResult` / `TrialArtifacts` — Near-Duplicate Structs

Type: Near-duplicate (overlapping fields)
Impact: Medium — two structs in the same package carrying the same core fields

Locations:

pkg/cli/trial_types.go:6 — WorkflowTrialResult
pkg/cli/trial_support.go:19 — TrialArtifacts

Definition Comparison:

// pkg/cli/trial_types.go
type WorkflowTrialResult struct {
    WorkflowName        string         `json:"workflow_name"`
    RunID               string         `json:"run_id"`
    SafeOutputs         map[string]any `json:"safe_outputs"`
    AgenticRunInfo      map[string]any `json:"agentic_run_info,omitempty"`
    AdditionalArtifacts map[string]any `json:"additional_artifacts,omitempty"`
    Timestamp           time.Time      `json:"timestamp"`
}

// pkg/cli/trial_support.go
type TrialArtifacts struct {
    SafeOutputs         map[string]any `json:"safe_outputs"`
    AgenticRunInfo      map[string]any `json:"agentic_run_info,omitempty"`
    AdditionalArtifacts map[string]any `json:"additional_artifacts,omitempty"`
}

TrialArtifacts is essentially WorkflowTrialResult minus WorkflowName, RunID, and Timestamp. The three core map[string]any fields are identical in name, type, and JSON tags.

Recommendation:

Embed TrialArtifacts inside WorkflowTrialResult to eliminate the field duplication:

type TrialArtifacts struct {
    SafeOutputs         map[string]any `json:"safe_outputs"`
    AgenticRunInfo      map[string]any `json:"agentic_run_info,omitempty"`
    AdditionalArtifacts map[string]any `json:"additional_artifacts,omitempty"`
}
type WorkflowTrialResult struct {
    WorkflowName string `json:"workflow_name"`
    RunID        string `json:"run_id"`
    Timestamp    time.Time `json:"timestamp"`
    TrialArtifacts
}

Estimated effort: 30 minutes
Benefits: Single definition of the artifact fields; changes propagate automatically

Cluster 2: `MCPServerConfig` — Same Base, Different Extensions

Type: Semantic near-duplicate (shared embedded base)
Impact: Low-Medium — same name in two packages, both embedding types.BaseMCPServerConfig

Locations:

pkg/workflow/tools_types.go:366 — Runtime workflow tool configuration
pkg/parser/mcp.go:35 — Parsed/inspected MCP configuration

// pkg/workflow/tools_types.go
type MCPServerConfig struct {
    types.BaseMCPServerConfig
    Mode          string         `yaml:"mode,omitempty"`
    Toolsets      []string       `yaml:"toolsets,omitempty"`
    GuardPolicies map[string]any `yaml:"guard-policies,omitempty"`
    CustomFields  map[string]any `yaml:",inline"`
}

// pkg/parser/mcp.go
type MCPServerConfig struct {
    types.BaseMCPServerConfig
    Name      string   `json:"name"`
    Registry  string   `json:"registry"`
    ProxyArgs []string `json:"proxy-args"`
    Allowed   []string `json:"allowed"`
}

These serve different serialization formats (YAML vs JSON) and different pipeline stages. The shared BaseMCPServerConfig embedding is correct architecture.

Recommendation: No structural change needed. Consider adding package-level doc comments clarifying the distinction. Risk is low since Go's package qualification prevents ambiguity at usage sites.

Cluster 3: `LogParser` — Function Type vs Interface (Naming Collision)

Type: Naming collision — same name, fundamentally different kinds
Impact: Medium — can cause confusion in code reviews and IDE navigation

Locations:

pkg/cli/log_aggregation.go:29 — Generic function type
pkg/workflow/agentic_engine.go:166 — Interface type

// pkg/cli/log_aggregation.go — function type
type LogParser[T LogAnalysis] func(logPath string, verbose bool) (T, error)

// pkg/workflow/agentic_engine.go — interface
type LogParser interface {
    ParseLogMetrics(logContent string, verbose bool) LogMetrics
    GetLogParserScriptId() string
    GetLogFileForParsing() string
}

Recommendation: Rename the CLI function type to LogParserFunc[T LogAnalysis] to follow the Go convention of suffixing function types with Func and to eliminate the cross-package naming collision.

Estimated effort: 20 minutes (rename + update call sites in pkg/cli)
Benefits: Clarity at usage sites; aligns with Go stdlib conventions (http.HandlerFunc, etc.)

Cluster 4: `FileTracker` — Struct vs Interface (Naming Collision)

Type: Naming collision — same name, struct in one package, interface in another
Impact: Medium — could mislead readers about which they're importing

Locations:

pkg/cli/file_tracker.go:19 — Concrete struct
pkg/workflow/compiler_types.go:65 — Interface

// pkg/cli/file_tracker.go — struct
type FileTracker struct {
    CreatedFiles    []string
    ModifiedFiles   []string
    OriginalContent map[string][]byte
    gitRoot         string
}

// pkg/workflow/compiler_types.go — interface
type FileTracker interface {
    TrackCreated(filePath string)
}

Recommendation: Rename the workflow interface to FileTrackerWriter or FileCreationTracker to clarify its role and avoid the struct/interface naming confusion.

Estimated effort: 20 minutes
Benefits: Clear distinction between the concrete CLI implementation and the compiler-contract interface

Clusters 5-6: `RepoConfig` and `EngineConfig` — Unrelated Types Sharing a Name

Type: Coincidental naming — completely different fields and purposes
Impact: Low — no real risk since they live in separate packages

Type	Location	Purpose
`RepoConfig`	`pkg/cli/trial_types.go:24`	Trial repo strategy (LogicalRepo, CloneRepo, HostRepo)
`RepoConfig`	`pkg/workflow/repo_config.go:68`	Maintenance workflow config (MaintenanceDisabled, Maintenance)
`EngineConfig`	`pkg/cli/audit_expanded.go:19`	Audit metadata (EngineID, TriggerEvent, MCPServers)
`EngineConfig`	`pkg/workflow/engine.go:16`	Compiler engine config (ID, Model, MaxTurns, Agent, etc.)

Recommendation: No structural change needed. Document-level comments are sufficient. Go's package system handles the disambiguation.

Clusters 7-9: Platform-Specific Build Tag Pairs (Expected)

Three type names appear twice with platform-specific implementations — these are intentional and correct:

Type	Files
`SpinnerWrapper`	`pkg/console/spinner.go` (native) / `pkg/console/spinner_wasm.go` (WASM stub)
`ProgressBar`	`pkg/console/progress.go` (native) / `pkg/console/progress_wasm.go` (WASM stub)
`RepositoryFeatures`	`pkg/workflow/repository_features_validation.go` / `_wasm.go`

These use //go:build js || wasm build constraints. No action needed.

Untyped Usages

Summary Statistics

Category	Locations
Struct fields using `any`	~8
Struct fields using `map[string]any`	~17
Function parameters using `map[string]any` (codemod pattern)	28+
Untyped numeric constants	4

Category 1: `map[string]any` as Codemod Frontmatter

Impact: Low — intentional design; YAML is inherently dynamic

The Codemod.Apply function signature (pkg/cli/fix_codemods.go:13) and PostTransformFunc (pkg/cli/codemod_factory.go:13) both use map[string]any for YAML frontmatter. This pattern propagates to 150+ call sites.

// pkg/cli/fix_codemods.go
type Codemod struct {
    Apply func(content string, frontmatter map[string]any) (string, bool, error)
}

// pkg/cli/codemod_factory.go
type PostTransformFunc func(lines []string, frontmatter map[string]any, fieldValue any) []string

Since YAML frontmatter structure is inherently open-ended (keys are user-defined), this pattern is appropriate. However, WorkflowMCPMetadata.Frontmatter map[string]any in pkg/cli/mcp_workflow_scanner.go:21 could potentially be refined if the keys accessed from it are well-known.

Recommendation: No change for the codemod pattern — it represents valid use of map[string]any for dynamic YAML. Consider whether WorkflowMCPMetadata.Frontmatter could expose a typed accessor for its known fields.

Category 2: `any`-typed Struct Fields (Strong Typing Opportunities)

Impact: Medium — runtime type assertions required for these fields

Location	Field	Current Type	Suggested Type	Reasoning
`pkg/cli/logs_models.go:300`	`RunID`	`any`	`int64` or `string`	GitHub run IDs are numeric
`pkg/cli/logs_models.go:301`	`RunNumber`	`any`	`int64`	GitHub run numbers are always integers
`pkg/workflow/mcp_scripts_parser.go:36`	`Default`	`any`	`json.RawMessage` or `string`	JSON Schema default values can be typed via RawMessage
`pkg/cli/gateway_logs.go:194`	`ID`	`any`	`any` (keep)	JSON-RPC 2.0 spec: ID is string, number, or null
`pkg/cli/gateway_logs.go:205`	`ID`	`any`	`any` (keep)	Same JSON-RPC spec reason
`pkg/cli/list_workflows_command.go:25`	`On`	`any`	`any` (keep)	GitHub Actions `on:` is string, array, or object
`pkg/cli/copilot_setup.go:147`	`RunsOn`	`any`	`any` (keep)	GitHub Actions `runs-on:` can be string or array

The RunID any and RunNumber any fields in logs_models.go:300-301 stand out — the comment says "Additional fields that might be present" suggesting backward-compatibility concern. Other RunID fields in the same file (lines 112, 120, 131, 140) are correctly typed as int64.

Recommendation:

// pkg/cli/logs_models.go — change:
RunID      any    `json:"run_id,omitempty"`
RunNumber  any    `json:"run_number,omitempty"`

// to:
RunID      int64  `json:"run_id,omitempty"`
RunNumber  int64  `json:"run_number,omitempty"`

Estimated effort: 15 minutes
Benefits: Consistent with the other 5+ RunID int64 fields in the same file

Category 3: `map[string]any` in Trial Artifact Structs

Impact: Low — these fields represent arbitrary JSON blobs from workflow outputs

Location	Fields
`pkg/cli/trial_types.go:9-12`	`SafeOutputs`, `AgenticRunInfo`, `AdditionalArtifacts`
`pkg/cli/trial_support.go:20-23`	Same 3 fields (see Cluster 1 above)

Since safe outputs are user-defined JSON payloads of arbitrary shape, map[string]any is appropriate here. The issue is duplication (covered in Cluster 1 above), not the type choice.

Category 4: Untyped Numeric Constants

Impact: Low-Medium — unclear units/semantics

Location	Constant	Value	Suggested Type
`pkg/constants/job_constants.go:185`	`DefaultRateLimitMax`	`5`	`int` (or named type `RateLimitCount`)
`pkg/constants/job_constants.go:186`	`DefaultRateLimitWindow`	`60`	Could be `time.Duration` or `int` with comment clarifying units (minutes)
`pkg/constants/constants.go:280`	`MaxSymlinkDepth`	`5`	`int`
`pkg/constants/constants.go:142`	`DefaultMCPGatewayPayloadSizeThreshold`	`524288`	`int64` (bytes)

DefaultRateLimitWindow = 60 is particularly worth typing — the comment says "minutes" but the constant is a bare int. Adding a type (or at minimum using 60 * time.Minute if compatible) would prevent accidental unit confusion.

Recommendation:

// Before
const DefaultRateLimitMax    = 5     // Default maximum runs per time window
const DefaultRateLimitWindow = 60    // Default time window in minutes (1 hour)

// After (minimal change — add int types)
const DefaultRateLimitMax    int = 5
const DefaultRateLimitWindow int = 60 // minutes

Estimated effort: 10 minutes
Benefits: Explicit types prevent accidental misuse in typed contexts

Refactoring Recommendations by Priority

Priority 1: `WorkflowTrialResult` / `TrialArtifacts` Field Deduplication

Files: pkg/cli/trial_types.go, pkg/cli/trial_support.go
Action: Embed TrialArtifacts in WorkflowTrialResult
Effort: ~30 minutes — risk: low (same package, straightforward embedding)

Priority 2: `LogParser` Rename (CLI function type → `LogParserFunc`)

Files: pkg/cli/log_aggregation.go + callers
Action: type LogParserFunc[T LogAnalysis] func(...) to follow Go conventions
Effort: ~20 minutes

Priority 3: `FileTracker` Interface Rename

Files: pkg/workflow/compiler_types.go + callers
Action: Rename to FileCreationTracker or FileTrackerWriter
Effort: ~20 minutes

Priority 4: `RunID any` / `RunNumber any` → `int64`

Files: pkg/cli/logs_models.go:300-301
Action: Change field types to int64 (consistent with other fields)
Effort: ~15 minutes — verify no string run IDs reach this struct

Priority 5: Type numeric constants

Files: pkg/constants/job_constants.go, pkg/constants/constants.go
Action: Add explicit int or int64 types to bare numeric constants
Effort: ~10 minutes

Implementation Checklist

Embed TrialArtifacts in WorkflowTrialResult (Priority 1)
Rename LogParser function type to LogParserFunc in pkg/cli (Priority 2)
Rename FileTracker interface in pkg/workflow/compiler_types.go (Priority 3)
Change RunID any / RunNumber any to int64 in logs_models.go (Priority 4)
Add explicit types to DefaultRateLimitMax, DefaultRateLimitWindow, MaxSymlinkDepth, DefaultMCPGatewayPayloadSizeThreshold (Priority 5)
Run full test suite after each change
Add package-level doc comments distinguishing RepoConfig and EngineConfig in cli vs workflow

Analysis Metadata

Item	Value
Total Go files analyzed	665 non-test files in `pkg/`
Total type definitions	~677
Packages surveyed	agentdrain, cli, console, constants, envutil, fileutil, gitutil, logger, parser, repoutil, semverutil, sliceutil, stringutil, styles, testutil, timeutil, tty, types, typeutil, workflow
Duplicate name clusters	6 (3 intentional WASM pairs, 3 real collisions)
Near-identical struct pair	1 (WorkflowTrialResult / TrialArtifacts)
`any`-typed struct fields	~8 (2 actionable, rest appropriate)
`map[string]any` struct fields	~17 (most appropriate; 1 consolidation via embedding)
Untyped numeric constants	4
Detection method	Serena LSP semantic analysis + ripgrep pattern matching
Analysis date	2026-04-08
Workflow run	§24133342259

References:

§24133342259

Generated by Typist - Go Type Analysis · ● 376.1K · ◷

expires on Apr 9, 2026, 11:45 AM UTC

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[typist] Typist - Go Type Consistency Analysis #25280

Uh oh!

{{title}}

Uh oh!

Duplicated Type Definitions

Summary Statistics

Cluster 1: `WorkflowTrialResult` / `TrialArtifacts` — Near-Duplicate Structs

Cluster 2: `MCPServerConfig` — Same Base, Different Extensions

Cluster 3: `LogParser` — Function Type vs Interface (Naming Collision)

Cluster 4: `FileTracker` — Struct vs Interface (Naming Collision)

Clusters 5-6: `RepoConfig` and `EngineConfig` — Unrelated Types Sharing a Name

Clusters 7-9: Platform-Specific Build Tag Pairs (Expected)

Untyped Usages

Summary Statistics

Category 1: `map[string]any` as Codemod Frontmatter

Category 2: `any`-typed Struct Fields (Strong Typing Opportunities)

Category 3: `map[string]any` in Trial Artifact Structs

Category 4: Untyped Numeric Constants

Refactoring Recommendations by Priority

Priority 1: `WorkflowTrialResult` / `TrialArtifacts` Field Deduplication

Priority 2: `LogParser` Rename (CLI function type → `LogParserFunc`)

Priority 3: `FileTracker` Interface Rename

Priority 4: `RunID any` / `RunNumber any` → `int64`

Priority 5: Type numeric constants

Implementation Checklist

Analysis Metadata

Replies: 0 comments

Select a reply

Uh oh!

[typist] Typist - Go Type Consistency Analysis #25280

Uh oh!

github-actions[bot] bot Apr 8, 2026

Key Metrics

Duplicated Type Definitions

Summary Statistics

Cluster 1: WorkflowTrialResult / TrialArtifacts — Near-Duplicate Structs

Cluster 2: MCPServerConfig — Same Base, Different Extensions

Cluster 3: LogParser — Function Type vs Interface (Naming Collision)

Cluster 4: FileTracker — Struct vs Interface (Naming Collision)

Clusters 5-6: RepoConfig and EngineConfig — Unrelated Types Sharing a Name

Clusters 7-9: Platform-Specific Build Tag Pairs (Expected)

Untyped Usages

Summary Statistics

Category 1: map[string]any as Codemod Frontmatter

Category 2: any-typed Struct Fields (Strong Typing Opportunities)

Category 3: map[string]any in Trial Artifact Structs

Category 4: Untyped Numeric Constants

Refactoring Recommendations by Priority

Priority 1: WorkflowTrialResult / TrialArtifacts Field Deduplication

Priority 2: LogParser Rename (CLI function type → LogParserFunc)

Priority 3: FileTracker Interface Rename

Priority 4: RunID any / RunNumber any → int64

Priority 5: Type numeric constants

Implementation Checklist

Analysis Metadata

Replies: 0 comments

github-actions[bot]
bot Apr 8, 2026

Cluster 1: `WorkflowTrialResult` / `TrialArtifacts` — Near-Duplicate Structs

Cluster 2: `MCPServerConfig` — Same Base, Different Extensions

Cluster 3: `LogParser` — Function Type vs Interface (Naming Collision)

Cluster 4: `FileTracker` — Struct vs Interface (Naming Collision)

Clusters 5-6: `RepoConfig` and `EngineConfig` — Unrelated Types Sharing a Name

Category 1: `map[string]any` as Codemod Frontmatter

Category 2: `any`-typed Struct Fields (Strong Typing Opportunities)

Category 3: `map[string]any` in Trial Artifact Structs

Priority 1: `WorkflowTrialResult` / `TrialArtifacts` Field Deduplication

Priority 2: `LogParser` Rename (CLI function type → `LogParserFunc`)

Priority 3: `FileTracker` Interface Rename

Priority 4: `RunID any` / `RunNumber any` → `int64`