Typist - Go Type Consistency Analysis

[github-actions[bot]]

This report analyzes all 619 non-test Go source files in pkg/ for duplicated type definitions and untyped usages. The codebase is generally well-structured with strong typing, a dedicated pkg/types shared package, and an active migration away from map[string]any via ToolsConfig. The main opportunities for improvement are naming collisions between package-local types and untyped numeric constants, while the heavy map[string]any usage in YAML frontmatter parsing is partially justified but worth continued migration effort.

Stats: 619 files · 594 type definitions · 5 true duplicate name clusters · ~1,423 map[string]any usages · 3 untyped numeric constants

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total type definitions analyzed: 594
• Duplicate name clusters found: 5 (across non-wasm, non-alias files)
• Exact duplicates (same structure): 0
• Build-constraint stubs (intentional): 3 clusters
• Naming collisions (distinct concepts, same name): 2 clusters
• Extension pattern (intentional shared base): 1 cluster

---

Cluster 1: EngineConfig — Naming Collision ⚠️

Type: Naming collision — two unrelated types sharing the same name in different packages
Occurrences: 2
Impact: Medium — developers reading cross-package code may confuse the two

Location	Purpose	Key Fields
pkg/workflow/engine.go:15	Parsed engine config from workflow frontmatter	ID, Version, Model, MaxTurns, Firewall, Args, Env
pkg/cli/audit_expanded.go:19	Audit log representation of runtime engine info	EngineID, EngineName, CLIVersion, MCPServers, TriggerEvent

These are semantically different — the workflow type drives compilation while the CLI type drives audit report rendering. Both are used within their own packages and never imported cross-package (verified by grep), so there is no actual type conflict. However, the shared name creates cognitive friction.

Recommendation:

• Rename cli.EngineConfig → AuditEngineInfo or RunEngineInfo to clarify intent
• Estimated effort: 30 minutes
• Benefits: Eliminates developer confusion, clearer audit domain model

---

Cluster 2: LogParser — Naming Collision ⚠️

Type: Naming collision — fundamentally different type shapes (interface vs generic function type)
Occurrences: 2
Impact: Low — used only within respective packages, no cross-package confusion

Location	Type shape	Semantics
pkg/workflow/agentic_engine.go:169	interface { ParseLogMetrics(...) LogMetrics; GetLogParserScriptId() string }	Engine-agnostic log parsing contract
pkg/cli/log_aggregation.go:30	type LogParser[T LogAnalysis] func(logPath string, verbose bool) (T, error)	Generic file-parsing function type for CLI aggregation

These are entirely unrelated concepts. The function type in CLI could be renamed to LogFileParser or LogAggregatorFn.

Recommendation:

• Rename cli.LogParser[T] → LogFileParser[T] to reduce ambiguity
• Estimated effort: 15 minutes
• Benefits: Clearer intent, no confusion with the workflow interface

---

Cluster 3: MCPServerConfig — Extension Pattern ✅ (Intentional)

Type: Designed extension using shared pkg/types.BaseMCPServerConfig
Occurrences: 2 (plus base in pkg/types)

Location	Extra fields
pkg/parser/mcp.go:35	Name, Registry, ProxyArgs, Allowed (parser-specific)
pkg/workflow/tools_types.go:493	Mode, Toolsets, GuardPolicies, CustomFields (workflow-specific)

Both embed types.BaseMCPServerConfig from the shared pkg/types package. This is the correct architecture. No action needed.

---

Cluster 4: RepositoryFeatures / ProgressBar / SpinnerWrapper — Build Stubs ✅ (Intentional)

These use the standard Go build-constraint pattern where a WASM stub replaces the full implementation at compile time:

pkg/workflow/repository_features_validation.go       // Full implementation
pkg/workflow/repository_features_validation_wasm.go  // //go:build js || wasm stub

pkg/console/progress.go                              // Full implementation  
pkg/console/progress_wasm.go                         // //go:build js || wasm stub

pkg/console/spinner.go                               // Full implementation
pkg/console/spinner_wasm.go                          // //go:build js || wasm stub

No action needed — this is idiomatic Go platform-specific code.

---

Cluster 5: LogMetrics — Proper Type Alias ✅ (Intentional)

// pkg/workflow/metrics.go:24
type LogMetrics struct { TokenUsage int; EstimatedCost float64; Turns int; ... }

// pkg/cli/logs_models.go:68
type LogMetrics = workflow.LogMetrics  // type alias, not a new definition

The CLI package re-exports via alias for ergonomic use. No action needed.

---

Untyped Usages

Summary Statistics

• interface{} usages: 0 (none — codebase uses modern any)
• any usages (total): ~1,824
  • Generic type constraints [T any] (idiomatic, not a concern): majority
  • YAML/JSON parsing variables: ~300 (partially justified)
  • map[string]any for frontmatter: ~1,423 (see below)
• Untyped numeric constants: 3

---

Category 1: map[string]any in YAML Frontmatter Parsing

Impact: Medium — ongoing technical debt, but active migration in progress

The workflow compiler parses GitHub Actions workflow YAML via map[string]any because YAML is inherently dynamic at parse time. This is a known trade-off; the team has already begun the migration with ToolsConfig.

Top files by occurrence:

File	Occurrences
pkg/workflow/compiler_safe_outputs_config.go	49
pkg/workflow/frontmatter_types.go	42
pkg/workflow/safe_outputs_tools_filtering.go	38
pkg/workflow/compiler_orchestrator_workflow.go	37
pkg/workflow/trigger_parser.go	31
pkg/workflow/tools.go	27
pkg/workflow/call_workflow_validation.go	26

Migration in progress: pkg/workflow/tools_types.go documents the pattern explicitly and provides ToolsConfig as the strongly-typed alternative. The file even includes the migration path with backward-compat wrappers. The frontmatter_types.go file shows 9 typed structs have already been extracted (RuntimesConfig, GitHubActionsPermissionsConfig, etc.) alongside the remaining raw map usage.

Recommendation:

• Continue the ToolsConfig migration pattern for additional frontmatter sections (triggers, permissions, concurrency blocks)
• Prioritize trigger_parser.go (31 occurrences) and call_workflow_validation.go (26 occurrences) as the next candidates
• Estimated effort: 2–4 hours per file
• Benefits: Compile-time validation, no runtime type assertions, better IDE support

Example — current pattern:

// pkg/workflow/trigger_parser.go
func parseTriggers(frontmatter map[string]any) ([]string, error) {
    onMap, ok := frontmatter["on"].(map[string]any)  // runtime assertion
    ...
}

Suggested direction:

type TriggersConfig struct {
    Push        *PushTrigger        `yaml:"push,omitempty"`
    PullRequest *PullRequestTrigger `yaml:"pull_request,omitempty"`
    Schedule    []ScheduleEntry     `yaml:"schedule,omitempty"`
    // etc.
}

---

Category 2: Untyped Numeric Constants ⚠️

Impact: Low — reduces semantic clarity and allows accidental mixing of unrelated values

// pkg/constants/constants.go:765-766
const DefaultRateLimitMax = 5     // Default maximum runs per time window
const DefaultRateLimitWindow = 60 // Default time window in minutes (1 hour)

These two constants represent different domains (count vs minutes) but share the same inferred type int. They could be mixed accidentally.

// Also untyped:
const DefaultMCPGatewayPayloadSizeThreshold = 524288  // bytes, but no type

Recommendation:

type RateLimitCount int
type RateLimitWindowMinutes int
type ByteSize int

const DefaultRateLimitMax    RateLimitCount         = 5
const DefaultRateLimitWindow RateLimitWindowMinutes = 60
const DefaultMCPGatewayPayloadSizeThreshold ByteSize = 524288

Note: LineLength type is already defined and used for MaxExpressionLineLength and ExpressionBreakThreshold — the same pattern should apply here.

• Estimated effort: 30 minutes
• Benefits: Prevents accidental cross-assignment, documents units in the type system

---

Category 3: any in Generic Constraints and Variadics ✅ (Idiomatic)

// pkg/sliceutil/sliceutil.go
func Filter[T any](slice []T, predicate func(T) bool) []T { ... }
func Map[T, U any](slice []T, transform func(T) U) []U { ... }

// pkg/logger/logger.go
func (l *Logger) Printf(format string, args ...any) { ... }
func (l *Logger) Print(args ...any) { ... }

Both patterns are idiomatic Go. Generic type constraints and variadic ...any following fmt.Printf conventions are correct usage. No action needed.

---

Refactoring Recommendations

Priority 1: Medium — EngineConfig Naming Collision

Action: Rename cli.EngineConfig to AuditEngineInfo

Steps:

1. Rename type in pkg/cli/audit_expanded.go:19
2. Update all references within pkg/cli/ (verified to not cross into pkg/workflow/)
3. Run tests

Estimated effort: 30 minutes | Impact: Medium (developer clarity)

---

Priority 2: Low — LogParser Naming Collision

Action: Rename cli.LogParser[T] to LogFileParser[T]

Steps:

1. Rename type in pkg/cli/log_aggregation.go:30
2. Update references within pkg/cli/

Estimated effort: 15 minutes | Impact: Low (developer clarity)

---

Priority 3: Medium — Continue map[string]any Migration

Action: Extend ToolsConfig migration pattern to triggers and permissions

Steps:

1. Design TriggersConfig struct following RuntimesConfig pattern in frontmatter_types.go
2. Refactor trigger_parser.go to use the new type
3. Add YAML unmarshal support
4. Update downstream consumers

Estimated effort: 2–4 hours per module | Impact: High long-term

---

Priority 4: Low — Add Types to Numeric Constants

Action: Apply existing LineLength pattern to rate-limit and threshold constants

Estimated effort: 30 minutes | Impact: Low (semantic clarity)

---

Implementation Checklist

• Rename cli.EngineConfig → AuditEngineInfo (Priority 1)
• Rename cli.LogParser[T] → LogFileParser[T] (Priority 2)
• Design TriggersConfig typed struct (Priority 3)
• Refactor trigger_parser.go to use typed config (Priority 3)
• Add typed constants for rate limit and payload size (Priority 4)
• Continue ToolsConfig-pattern migration for remaining frontmatter sections

Analysis Metadata

• Total Go files analyzed: 619 (non-test, in pkg/)
• Total type definitions: 594
• True duplicate name clusters: 2 (EngineConfig, LogParser)
• Intentional patterns correctly identified: 3 (MCPServerConfig extension, build stubs, type alias)
• map[string]any occurrences: ~1,423 (across ~150 files)
• Untyped numeric constants: 3
• Detection method: Serena semantic analysis + pattern matching + Grep
• Analysis date: 2026-03-26

References:

• §23591572074

AI generated by Typist - Go Type Analysis · history

• expires on Mar 27, 2026, 11:26 AM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #23221.