Typist - Go Type Consistency Analysis

[github-actions[bot]]

This report summarizes a full semantic type-consistency analysis of all non-test Go source files in pkg/ (622 files). The analysis identified no critical type duplication or dangerous untyped usages. The codebase demonstrates strong typing discipline overall. A small number of low-priority opportunities for incremental improvement are documented below.

Summary

• Total Go source files analyzed: 622 (non-test, pkg/ only)
• Total type declarations found: ~527
• Duplicate type name clusters: 4 found, all intentional
• any / interface{} usages reviewed: 14 locations — all justified
• Untyped constants reviewed: ~30 locations — all appropriate for their scope
• Critical issues: None
• Refactoring priority: Low

---

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Duplicate clusters found: 4
• Exact duplicates requiring consolidation: 0
• Intentional build-tag variants: 2
• Cross-package types sharing a base: 1 cluster (well-designed)
• Same-name, different-purpose types: 1 cluster (intentional layering)

---

Cluster 1: EngineConfig — Same Name, Different Purpose

Classification: Intentional layering (NOT a consolidation candidate)

Location	Package	Purpose
pkg/cli/audit_expanded.go:19	cli	JSON-serializable audit display struct (all-string, JSON-tagged)
pkg/workflow/engine.go:15	workflow	Internal runtime engine configuration (no JSON tags, rich types)

Comparison:

// pkg/cli/audit_expanded.go — display/audit layer
type EngineConfig struct {
    EngineID        string   `json:"engine_id"`
    EngineName      string   `json:"engine_name,omitempty"`
    Model           string   `json:"model,omitempty"`
    Version         string   `json:"version,omitempty"`
    CLIVersion      string   `json:"cli_version,omitempty"`
    FirewallVersion string   `json:"firewall_version,omitempty"`
    MCPServers      []string `json:"mcp_servers,omitempty"`
    TriggerEvent    string   `json:"trigger_event,omitempty"`
    Repository      string   `json:"repository,omitempty"`
}

// pkg/workflow/engine.go — runtime engine layer
type EngineConfig struct {
    ID               string
    Version          string
    Model            string
    MaxTurns         string
    MaxContinuations int
    Concurrency      string
    Command          string
    Env              map[string]string
    Args             []string
    Agent            string
    IsInlineDefinition   bool
    InlineProviderAuth   *AuthDefinition
    InlineProviderRequest *RequestShape
    // ...
}

Assessment: These serve entirely different purposes at different architectural layers. Merging them would violate separation of concerns. No action needed.

---

Cluster 2: MCPServerConfig — Shared Base Type (Good Architecture)

Classification: Intentional extension pattern using pkg/types bridge

Location	Package	Added Fields
pkg/workflow/tools_types.go:479	workflow	Mode, Toolsets, GuardPolicies, CustomFields
pkg/parser/mcp.go:35	parser	Name, Registry, ProxyArgs, Allowed

Both embed types.BaseMCPServerConfig from pkg/types/mcp.go, which was explicitly created as a bridge to avoid circular imports between pkg/parser and pkg/workflow. This is well-designed: shared fields live in pkg/types, layer-specific extensions live in their respective packages.

Assessment: This is idiomatic Go architecture for avoiding circular imports. No action needed.

---

Cluster 3 & 4: Build-Tag Platform Variants (Intentional)

• ProgressBar — pkg/console/progress.go (full) vs pkg/console/progress_wasm.go (stub)
• SpinnerWrapper — pkg/console/spinner.go (full) vs pkg/console/spinner_wasm.go (stub)
• RepositoryFeatures — pkg/workflow/repository_features_validation.go vs …_wasm.go

Assessment: Standard Go build-tag pattern for platform-specific implementations (native vs WebAssembly). No action needed.

---

any Usage Analysis

Summary Statistics

• Struct fields using any: 11
• Struct fields using map[string]any: ~10
• interface{} usages: 0 (codebase uses modern any consistently)
• Usages requiring stronger typing: 0

---

All any Usages Are Justified

File	Field	Reason
pkg/cli/gateway_logs.go:194,205	rpcRequestPayload.ID, rpcResponsePayload.ID	JSON-RPC 2.0 spec: id MUST accept string, number, or null
pkg/cli/logs_models.go:279–280	RunID, RunNumber	GitHub API returns integers; some paths serialize as string
pkg/cli/trial_command.go:32–35	SafeOutputs, AgenticRunInfo, AdditionalArtifacts	User-defined workflow output blobs — schema varies per workflow
pkg/cli/trial_support.go:20–23	Same three fields	Same reason (parallel struct)
pkg/cli/copilot_setup.go:141–155	With, Env, RunsOn, On, Permissions	GitHub Actions YAML is intrinsically polymorphic per the spec
pkg/cli/list_workflows_command.go:25	On	GHA on: trigger can be string, list, or event-keyed map
pkg/cli/mcp_registry.go:28	Config map[string]any	Per-registry config schema varies by registry type
pkg/cli/devcontainer.go:25	Settings map[string]any	Dev container settings are open-ended per spec
pkg/workflow/tools_types.go:483–484	GuardPolicies, CustomFields	Server-specific policy configs; inline catch-all for unknown YAML

Notable: The codebase has already migrated from interface{} to any (modern Go 1.18+ idiom) everywhere.

---

Untyped Constants Analysis

Summary Statistics

• Package-level constants with named types: ~50 (in pkg/constants/constants.go)
• Package-level constants without named types: ~25 (path strings, domain names, etc.)
• File-local constants without named types: ~20 (implementation details)

---

pkg/constants/constants.go — Strong Typing Already Established

The file defines semantic named types for important domain concepts:

Type	Kind	Has String()	Has IsValid()
Version	string	✅	✅
FeatureFlag	string	❌	❌
URL	string	❌	❌
ModelName	string	❌	❌
JobName	string	✅	✅
StepID	string	✅	✅
CommandPrefix	string	✅	✅
WorkflowID	string	❌	❌
EngineName	string	❌	❌
DocURL	string	✅	✅
MCPServerID	string	✅	❌
LineLength	int	❌	❌

Minor opportunity: Some types (FeatureFlag, URL, ModelName, WorkflowID, EngineName, LineLength) have no methods defined, making them functionally equivalent to their base types. Adding String() and IsValid() where appropriate would improve consistency with the other named types. The file itself notes (lines 25–31) that method body duplication across types is intentional since Go does not allow shared method sets for distinct named types.

---

File-Local Constants (Appropriate as-is)

These are file-scoped implementation constants that do not benefit from named types:

// pkg/cli/audit_cross_run.go — thresholds
const maxAuditReportRuns = 50
const mcpErrorRateThreshold = 0.10
const mcpConnectionRateThreshold = 0.75
const spikeDetectionMultiplier = 2.0

// pkg/cli/gateway_logs.go — buffer sizing
const maxScannerBufferSize = 1024 * 1024

// pkg/cli/run_workflow_tracking.go — retry policy
const maxRetries = 6
const initialDelay = 2 * time.Second
const maxDelay = 10 * time.Second

These are idiomatic Go: file-local numeric constants whose semantics are clear from context. Introducing named types for these would add indirection with no benefit.

---

Minor Refactoring Opportunities

These are low-priority improvements that would improve code consistency, not fix bugs.

Opportunity 1: Complete Method Coverage on Named Types in pkg/constants/constants.go

Priority: Low
Effort: ~1 hour
Impact: Improved API consistency

Types without String() and/or IsValid() methods: FeatureFlag, URL, ModelName, WorkflowID, EngineName, LineLength.

Adding consistent methods would allow these types to satisfy common interfaces and provide validation-at-construction guarantees matching the other named types in the package.

---

Opportunity 2: Structural Overlap Between WorkflowTrialResult and TrialArtifacts

Priority: Low
Effort: ~30 minutes
Impact: Minor reduction in field duplication

// pkg/cli/trial_command.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 structurally a subset of WorkflowTrialResult's artifact fields. If TrialArtifacts is used as a deserialization target for a different data source, embedding it in WorkflowTrialResult would reduce field duplication. This should only be done if both types are populated from the same source.

---

Implementation Checklist

• (Low) Add String() / IsValid() methods to FeatureFlag, URL, ModelName, WorkflowID, EngineName, LineLength in pkg/constants/constants.go
• (Low) Evaluate whether TrialArtifacts can be embedded in WorkflowTrialResult to reduce field duplication

Recommendations

No critical or high-priority refactoring is required. The codebase's type system is well-designed:

1. All any usages are justified by external schema constraints (JSON-RPC spec, GitHub Actions YAML spec, user-defined workflow outputs)
2. Type name conflicts are intentional — they represent different architectural layers or build-tag variants, with the pkg/types bridge package proactively preventing circular import issues
3. Important constants are strongly typed using named types in pkg/constants/constants.go

The two minor opportunities (completing method coverage on named types, and potential struct embedding) are cosmetic improvements that can be addressed as part of routine maintenance.

---

References:

• §23846036229
• Analysis date: 2026-04-01 | Files analyzed: 622 | Detection method: Serena LSP + pattern matching

AI generated by Typist - Go Type Analysis · history

• expires on Apr 2, 2026, 11:28 AM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #24069.