[typist] Typist - Go Type Consistency Analysis

[github-actions[bot]]

Analysis of 659 non-test Go files across pkg/ identified 2 genuine cross-package name collisions, 3 intentional build-constraint duplicates (correctly separated), and approximately 1,825 any-typed locations — the vast majority justified by YAML/JSON dynamism. Below are the actionable findings worth addressing.

Summary

Category	Count	Status
Go files analyzed	659	—
Cross-package name collisions	2	⚠️ Action needed
Build-constraint pairs (wasm/native)	3	✅ Intentional
map[string]any usages	~1,800	⚠️ Some improvable
Plain any struct fields	~12	⚠️ Some improvable
interface{} usages	0	✅ Clean

Full Analysis Report

Duplicated Type Definitions

Cluster 1: EngineConfig — Cross-Package Name Collision (Medium Priority)

Type: Semantic name collision across packages (different purposes)

Locations:

1. pkg/workflow/engine.go:16 — runtime engine configuration
2. pkg/cli/audit_expanded.go:19 — audit display record

Definition Comparison:

// pkg/workflow/engine.go:16 — runtime config, ~20 fields
type EngineConfig struct {
    ID               string
    Version          string
    Model            string
    MaxTurns         string
    MaxContinuations int
    Concurrency      string
    UserAgent        string
    Command          string
    Env              map[string]string
    Config           string
    Args             []string
    Agent            string
    APITarget        string
    TokenWeights     *types.TokenWeights
    IsInlineDefinition bool
    InlineProviderID   string
    // ... more fields
}

// pkg/cli/audit_expanded.go:19 — audit display record, 9 fields
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"`
}

Issue: The two types are in different packages (workflow vs cli) and have distinct purposes: one configures the engine at runtime, the other represents the engine identity for audit reporting. The shared name is misleading — developers browsing or searching for EngineConfig may find the wrong one.

Recommendation: Rename pkg/cli/audit_expanded.go's type to AuditEngineConfig or EngineAuditRecord to reflect its audit-display purpose and eliminate the name ambiguity.

• Estimated effort: ~1 hour (rename + update usages within pkg/cli)
• Impact: Medium — prevents future confusion; no logic change needed

---

Cluster 2: MCPServerConfig — Intentional Design (Already Addressed)

Locations:

1. pkg/workflow/tools_types.go:366 — workflow-specific fields
2. pkg/parser/mcp.go:35 — parser-specific fields

Both embed types.BaseMCPServerConfig from pkg/types/mcp.go, which already consolidates the shared fields. This is correct architecture — no action required.

// pkg/types/mcp.go — shared base (well-structured)
type BaseMCPServerConfig struct {
    Command   string
    Args      []string
    Env       map[string]string
    Type      string
    Version   string
    URL       string
    Headers   map[string]string
    Auth      *MCPAuthConfig
    Container string
    // ...
}

---

Cluster 3: Build-Constraint Pairs (Intentional — No Action Required)

The following type pairs are intentional platform stubs using //go:build !js && !wasm / //go:build js || wasm split:

Type	Native file	Wasm stub
SpinnerWrapper	pkg/console/spinner.go:96	pkg/console/spinner_wasm.go:10
ProgressBar	pkg/console/progress.go:31	pkg/console/progress_wasm.go:7
RepositoryFeatures	pkg/workflow/repository_features_validation.go:57	pkg/workflow/repository_features_validation_wasm.go:5

These follow the standard Go build-tag pattern for platform stubs. ✅

---

Untyped Usages

Category 1: type X any Type Aliases (Low Priority)

Location: pkg/workflow/tools_types.go:275

// Current — comment needed to explain valid values
type GitHubReposScope any // string or []any (YAML-parsed arrays are []any)

This represents a sum type (string | []string) that Go cannot express natively. A custom struct with a json.Unmarshaler would add clarity:

// Suggested — explicit sum type with unmarshaling
type GitHubReposScope struct {
    Single   string
    Multiple []string
}

func (g *GitHubReposScope) UnmarshalYAML(value *yaml.Node) error {
    switch value.Kind {
    case yaml.ScalarNode:
        return value.Decode(&g.Single)
    case yaml.SequenceNode:
        return value.Decode(&g.Multiple)
    }
    return fmt.Errorf("unexpected repos-scope type: %v", value.Kind)
}

• Estimated effort: 2–3 hours
• Impact: Low-medium — improves call-site safety; no behavioral change

---

Category 2: Struct Fields with any for Variable-Type JSON (Acceptable / Documented)

These fields use any for intentional type flexibility, all with comments explaining why:

Location	Field	Reason
pkg/workflow/frontmatter_types.go	Engine any	Can be string or object in YAML
pkg/cli/gateway_logs.go:194,205	ID any	JSON-RPC spec: ID is string | number | null
pkg/cli/logs_models.go:300,301	RunID any, RunNumber any	JSON field can be int or string
pkg/cli/copilot_setup.go:147,155	RunsOn any, On any	GHA: runs-on can be string or array

These are correct usage of any in Go. No change recommended.

---

Category 3: map[string]any in Struct Fields (Medium Priority)

Location: pkg/cli/trial_types.go

// Current — three loose any maps
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"`
}

SafeOutputs, AgenticRunInfo, and AdditionalArtifacts carry dynamic JSON blobs from workflow outputs. If the schemas for these are known, typed structs would improve usability at call sites. However, if the structure is genuinely variable per workflow, the current approach is appropriate.

Recommendation: Investigate whether AgenticRunInfo has a stable schema (it may already mirror AwInfo in pkg/cli/logs_models.go). If so:

// Suggested (if schema is stable)
type WorkflowTrialResult struct {
    WorkflowName        string            `json:"workflow_name"`
    RunID               string            `json:"run_id"`
    SafeOutputs         map[string]string `json:"safe_outputs"`           // values are always strings?
    AgenticRunInfo      *AwInfo           `json:"agentic_run_info,omitempty"`
    AdditionalArtifacts map[string]any    `json:"additional_artifacts,omitempty"` // keep if truly dynamic
    Timestamp           time.Time         `json:"timestamp"`
}

• Estimated effort: 2–4 hours
• Impact: Medium — better IDE support and safer call sites for trial result processing

---

Category 4: map[string]any for JSON Output Building (Low Priority)

Location: pkg/cli/deps_report.go:213

// Current — ad-hoc JSON construction
output := map[string]any{
    "summary": map[string]any{
        "total_dependencies":  report.TotalDeps,
        "outdated_count":      len(report.Outdated),
        "security_advisories": len(report.Advisories),
        // ...
    },
    "maturity": map[string]any{...},
    // ...
}

This nested map is only used for JSON marshaling output. A typed struct would provide better compile-time guarantees:

// Suggested
type DepsReportOutput struct {
    Summary  DepsReportSummary  `json:"summary"`
    Outdated []OutdatedDep      `json:"outdated"`
    Security []Advisory         `json:"security"`
    Maturity DepsMaturityReport `json:"maturity"`
}

• Estimated effort: 1–2 hours
• Impact: Low — the output is write-only; improves maintainability

---

Category 5: map[string]any for YAML Frontmatter (Accepted Pattern)

The pkg/workflow/ and pkg/parser/ packages use map[string]any extensively (~1,600 usages) for YAML frontmatter manipulation. This is the correct Go pattern for working with dynamic YAML structures where the schema is partially known or varies by user configuration. The team has already documented the rationale in comments throughout pkg/workflow/frontmatter_types.go.

Notable well-structured workarounds already in place:

• MapToolConfig (pkg/workflow/mcp_config_types.go:66) — named type alias for map[string]any with helper methods
• DevcontainerFeatures (pkg/cli/devcontainer.go:40) — named type alias for clarity
• Typed parsing functions (parseRuntimesConfig, parsePermissionsConfig) to convert raw maps to strongly-typed structs

---

Refactoring Priority Summary

Priority	Recommendation	Location	Effort
Medium	Rename cli.EngineConfig → AuditEngineConfig	pkg/cli/audit_expanded.go:19	~1 hr
Medium	Investigate typing WorkflowTrialResult fields	pkg/cli/trial_types.go	2–4 hrs
Low	Type GitHubReposScope with custom unmarshaler	pkg/workflow/tools_types.go:275	2–3 hrs
Low	Type DepsReportOutput struct	pkg/cli/deps_report.go:213	1–2 hrs

Implementation Checklist

• Rename cli.EngineConfig to AuditEngineConfig and update all usages within pkg/cli/
• Audit WorkflowTrialResult.AgenticRunInfo schema — determine if it matches AwInfo
• If schema stable: replace map[string]any fields in WorkflowTrialResult with typed structs
• Consider a custom YAML unmarshaler for GitHubReposScope to replace the any alias
• Create typed DepsReportOutput struct in deps_report.go

Analysis Metadata

• Total Go files analyzed: 659 (non-test, in pkg/)
• interface{} usages: 0 (clean — fully migrated to any)
• any type usages: ~1,825 (most intentional YAML/JSON handling)
• Cross-package name collisions: 2 (EngineConfig, MCPServerConfig)
• Actionable MCPServerConfig: 0 (already addressed via BaseMCPServerConfig)
• Detection method: Serena semantic analysis + pattern search + manual verification
• Workflow run: §24079340460

References:

• §24079340460

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

• expires on Apr 8, 2026, 11:45 AM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #25280.