Typist - Go Type Consistency Analysis

[github-actions[bot]]

Analysis of 622 non-test Go files across 18 packages in pkg/. The codebase already demonstrates strong typing discipline — pkg/constants uses semantic type aliases extensively, and a pkg/types shared package exists to prevent cross-package duplication. The findings below focus on the remaining opportunities.

Summary

Category	Count	Priority
Duplicate type name clusters	2 meaningful	Medium
WASM stub duplicates (expected pattern)	3	Low / N/A
map[string]any usages	1,423	Low–Medium
[]any usages	292	Low
any struct fields	2	Low
Untyped file-scope constants	5	Low

Full Analysis Report

Duplicated Type Definitions

Cluster 1: EngineConfig — Naming Collision ⚠️

Type: Same name, completely different semantics across packages
Impact: Medium — reading code that imports both cli and workflow packages requires context-switching; the name EngineConfig carries conflicting meaning.

Locations:

1. pkg/cli/audit_expanded.go:19 — Audit-display struct (JSON-tagged, read-only view)
2. pkg/workflow/engine.go:15 — Runtime engine configuration struct (mutable, operational)

Definition Comparison:

// pkg/cli/audit_expanded.go:19  — DISPLAY / REPORTING
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:15  — RUNTIME CONFIGURATION
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
    Firewall         *FirewallConfig
    Agent            string
    APITarget        string
    IsInlineDefinition bool
    InlineProviderID   string
    // ...
}

Recommendation: Rename pkg/cli/audit_expanded.go's EngineConfig to EngineAuditSnapshot or EngineAuditInfo. The cli package type represents a point-in-time audit view, not the operational configuration. This removes the ambiguity without any functional change.

• Estimated effort: 1 hour (rename + update callers in pkg/cli)
• Risk: Low — these are in separate packages with no shared interface

---

Cluster 2: MCPServerConfig — Intentionally Split (Already Addressed) ✅

Locations:

1. pkg/workflow/tools_types.go:493 — Workflow-specific (Mode, Toolsets, GuardPolicies, CustomFields)
2. pkg/parser/mcp.go:35 — Parser-specific (Name, Registry, ProxyArgs, Allowed)

Both embed types.BaseMCPServerConfig from pkg/types/mcp.go. The pkg/types package documentation explicitly explains this design: the shared fields live in BaseMCPServerConfig; each package extends with its own domain-specific fields. This is the correct pattern — no action needed.

---

Cluster 3: WASM Platform Stubs — Expected Pattern ✅

Three type pairs exist because Go build constraints require separate files for WASM targets:

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

The WASM stubs contain only the fields accessible without native OS dependencies. This is idiomatic Go and requires no change.

---

Cluster 4: FileTracker — Interface vs. Struct (Not a Duplicate) ✅

• pkg/workflow/compiler_types.go:51 — type FileTracker interface { TrackCreated(filePath string) }
• pkg/cli/file_tracker.go:18 — type FileTracker struct { ... } (implements the interface)

This is the correct Go interface/implementation pattern. The struct in pkg/cli satisfies the interface in pkg/workflow. No action needed.

---

Cluster 5: LogMetrics — Type Alias (Correct Pattern) ✅

• pkg/workflow/metrics.go:24 — Canonical definition
• pkg/cli/logs_models.go:68 — type LogMetrics = workflow.LogMetrics (type alias for re-export)

Type aliases are the idiomatic Go approach for re-exporting types without introducing a new type. No action needed.

---

Untyped Usages

Category 1: map[string]any — YAML/JSON Parsing (1,423 occurrences)

Impact: Low — largely intentional for dynamic YAML/JSON documents

The vast majority of map[string]any usages appear in:

• YAML frontmatter parsing (pkg/parser/) — YAML documents are structurally variable; map[string]any is the standard Go approach for generic unmarshaling.
• Codemod functions (pkg/cli/codemod_*.go) — These traverse arbitrary YAML structures.
• MCP configuration merging (pkg/parser/tools_merger.go) — The MergeTools function must handle arbitrary tool-config shapes.

Select opportunities for stronger typing:

1a. DevcontainerFeatures

• Location: pkg/cli/devcontainer.go:39
• Current: type DevcontainerFeatures map[string]any
• Context: Devcontainer feature values are always map[string]any{} (empty option maps) or maps of string settings. The feature keys are well-known URIs but values vary per feature.
• Assessment: map[string]any is appropriate here because devcontainer features have a heterogeneous, externally-defined schema. No change recommended.

1b. PostTransformFunc in codemod factory

• Location: pkg/cli/codemod_factory.go:8
• Current: type PostTransformFunc func(lines []string, frontmatter map[string]any, fieldValue any) []string
• Assessment: The fieldValue any parameter represents a YAML field value that could be a string, number, bool, map, or slice — any is appropriate. No change recommended.

1c. WorkflowMCPMetadata.Frontmatter

• Location: pkg/cli/mcp_workflow_scanner.go:21
• Current: Frontmatter map[string]any
• Assessment: Frontmatter is a free-form YAML document. No change recommended.

1d. JSON log parsing in logs_metrics.go

• Location: pkg/cli/logs_metrics.go:651,698
• Current: var logEntries []map[string]any
• Context: Parsing unstructured JSON log lines
• Opportunity: A typed LogEntry struct with the known fields (mcp_servers, etc.) could replace the map, making the code safer and more readable.
• Suggested fix:

  type LogEntry struct {
      MCPServers []MCPServerEntry `json:"mcp_servers,omitempty"`
      // ... other known fields
  }
  type MCPServerEntry struct {
      Name string `json:"name"`
      // ... other known fields
  }

• Estimated effort: 2–3 hours
• Benefit: Eliminates 4 type assertions; compile-time field validation

---

Category 2: []any — YAML Array Parsing (292 occurrences)

Most []any usages are in YAML array traversal where element types are heterogeneous (mixed strings, maps, etc.). These are appropriate for the YAML parsing context.

Notable exception: pkg/parser/yaml_import.go:203

stepsSlice, ok := stepsValue.([]any)

GitHub Actions steps are always []map[string]any — tightening to []map[string]any would eliminate the inner type assertion. Low-effort, low-risk improvement.

---

Category 3: any Struct Fields — JSON-RPC IDs

Location: pkg/cli/gateway_logs.go:194,205

type rpcRequestPayload struct {
    ID any `json:"id"`  // line 194
}
type rpcResponsePayload struct {
    ID any `json:"id"`  // line 205
}

Assessment: The JSON-RPC 2.0 specification requires that id be a string, number, or null. Using any is correct here because json.Unmarshal needs to handle all three. Alternatives like json.RawMessage would add complexity without meaningful benefit. No change recommended.

---

Category 4: Untyped File-Scope Constants

The pkg/constants package already uses semantic type aliases extensively (e.g., Version, CommandPrefix, URL, LineLength). A small number of file-scope constants outside that package lack types:

Location	Constant	Current	Suggested Type
pkg/cli/gateway_logs.go:35	maxScannerBufferSize = 1024 * 1024	int (implicit)	Consider constants.ByteSize if that type exists, or keep as-is (local clarity)
pkg/cli/secret_set_command.go:34	publicKeySize = 32	int (implicit)	Could be int or a named PublicKeySize const — low priority
pkg/cli/audit_cross_run.go:13	maxAuditReportRuns = 50	int (implicit)	Low priority — local file scope
pkg/cli/audit_comparison.go:84	maxAuditComparisonCandidates = 10	int (implicit)	Low priority — local file scope
pkg/cli/audit_diff.go:17	volumeChangeThresholdPercent = 100.0	float64 (implicit)	constants.Percent type could apply; moderate clarity improvement

These constants are all unexported (lowercase) and file-scoped, so their lack of explicit types has low blast radius. The existing typed constant pattern in pkg/constants already handles the high-value cases.

---

Refactoring Recommendations

Priority 1 (Medium): Rename EngineConfig in pkg/cli

Action: Rename EngineConfig in pkg/cli/audit_expanded.go to EngineAuditSnapshot (or EngineAuditInfo) to eliminate the naming collision with pkg/workflow.EngineConfig.

Steps:

1. Rename the type in pkg/cli/audit_expanded.go
2. Update all references within pkg/cli/ (likely audit-related files only)
3. Run tests

Estimated effort: 1 hour
Impact: Eliminates reader confusion; no behavioral change

---

Priority 2 (Low): Type JSON log entry structs in logs_metrics.go

Action: Replace var logEntries []map[string]any with typed LogEntry structs.

Steps:

1. Define LogEntry and MCPServerEntry structs with known fields
2. Replace map-based access with field access
3. Eliminate type assertions for mcp_servers

Estimated effort: 2–3 hours
Impact: 4 fewer type assertions; compile-time field validation

---

Priority 3 (Low): Tighten YAML step arrays in yaml_import.go

Action: Change []any to []map[string]any for step slices in pkg/parser/yaml_import.go.

Estimated effort: 30 minutes
Impact: Minor — removes one level of type assertion

---

Implementation Checklist

• Rename EngineConfig in pkg/cli/audit_expanded.go → EngineAuditSnapshot
• Define typed LogEntry struct for JSON log parsing in logs_metrics.go
• Tighten []any to []map[string]any for YAML step arrays in yaml_import.go
• (Optional) Add explicit types to volumeChangeThresholdPercent and maxScannerBufferSize constants
• Run full test suite after each change

---

Analysis Metadata

Metric	Value
Total Go files analyzed	622
Packages analyzed	18
Total exported type definitions	524
Duplicate name clusters	5 total (2 actionable, 3 expected patterns)
map[string]any occurrences	1,423
[]any occurrences	292
any struct fields	2
Untyped file-scope constants	5
Analysis method	Serena semantic analysis + pattern matching
Analysis date	2026-03-27

References: §23643710895

AI generated by Typist - Go Type Analysis · history

• expires on Mar 28, 2026, 11:23 AM UTC