[typist] Typist - Go Type Consistency Analysis

[github-actions[bot]]

Analysis of 668 non-test Go files across 19 packages in pkg/. The codebase is in generally good shape: only 8 type name collisions were found, most expected (WASM variants), and the project already applies a strong semantic-typing pattern for critical constants. The main opportunities are a naming conflict, two consolidation candidates, and extension of the existing typed-constant pattern to cover artifact names, output names, and filenames.

Summary

Category	Count	Status
Total Go files analyzed	668	—
Type name duplicates found	8	3 actionable
any usages (was interface{})	1,862 in 118 files	Mostly justified
Untyped constants	~117	Partially addressable
Existing semantic types	6 (JobName, StepID, MCPServerID, LineLength, CommandPrefix, WorkflowID)	Good foundation

Full Analysis Report

Duplicated Type Definitions

Expected Duplicates (WASM build variants — no action needed)

These exist in both a native and a _wasm.go file. The Go build tag system handles this correctly.

Type	Files
SpinnerWrapper	pkg/console/spinner.go, pkg/console/spinner_wasm.go
ProgressBar	pkg/console/progress.go, pkg/console/progress_wasm.go
RepositoryFeatures	pkg/workflow/repository_features_validation.go, pkg/workflow/repository_features_validation_wasm.go

Correct Pattern (type alias to avoid circular imports — no action needed)

LogMetrics in pkg/cli/logs_models.go is a type alias pointing to the canonical definition in pkg/workflow/metrics.go. This is intentional.

---

Priority 1 — Naming Conflict: FileTracker

Impact: High confusion risk — same name, different kinds, different packages.

Location	Kind
pkg/workflow/compiler_types.go:46	Interface
pkg/cli/file_tracker.go:19	Struct

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

// pkg/cli/file_tracker.go:19 — struct (concrete implementation)
type FileTracker struct { ... }

Go allows a struct and interface to share the same name across packages, but having two types named FileTracker — one an interface, one a struct — in sibling packages creates reader confusion and could break if one package ever imports the other.

Recommendation: Rename the interface to FileTrackerInterface (or simply FileTracking) following Go idiom (interfaces named by behavior). Alternatively, rename the struct to DefaultFileTracker.

Estimated effort: 30 min (rename + update callers with find_referencing_symbols).

---

Priority 2 — Same Name, Different Purpose: RepoConfig

Location	Purpose
pkg/cli/trial_types.go:24	Trial execution repos (LogicalRepo, CloneRepo, HostRepo)
pkg/workflow/repo_config.go:69	Workflow maintenance settings (MaintenanceDisabled, Maintenance)

These serve completely different purposes and should not share a name. A developer importing both packages would need to qualify every usage.

Recommendation: Rename to clarify purpose:

• pkg/cli/trial_types.go: rename to TrialRepoConfig
• pkg/workflow/repo_config.go: rename to WorkflowRepoConfig (or MaintenanceConfig if MaintenanceConfig is not already taken)

Estimated effort: 1 hour.

---

Priority 3 — Same Name, Different Purpose: EngineConfig

Location	Purpose
pkg/cli/audit_expanded.go:19	Audit report data model (IDs, versions, metadata for display)
pkg/workflow/engine.go:16	Runtime configuration (MaxTurns, Concurrency, Command, Args, Env...)

// audit_expanded.go — reporting/display model
type EngineConfig struct {
    EngineID        string
    EngineName      string
    Model           string
    Version         string
    CLIVersion      string
    FirewallVersion string
    MCPServers      []string
    TriggerEvent    string
    Repository      string
}

// workflow/engine.go — runtime config
type EngineConfig struct {
    ID          string
    Version     string
    Model       string
    MaxTurns    string
    Concurrency string
    Command     string
    Env         map[string]string
    Args        []string
    ...
}

Recommendation: Rename to reflect their distinct roles:

• pkg/cli/audit_expanded.go: rename to AuditEngineInfo or EngineRunInfo
• pkg/workflow/engine.go: keep as EngineConfig (it is the authoritative runtime config)

Estimated effort: 1–2 hours.

---

Priority 4 — Consolidation Candidate: MCPServerConfig

Both extend the same base type (types.BaseMCPServerConfig) but add phase-specific fields. They are not true duplicates, but the shared name creates confusion about which "MCPServerConfig" a given function expects.

Location	Phase	Extra fields
pkg/parser/mcp.go:35	Parse-time	Name, Registry, ProxyArgs, Allowed
pkg/workflow/tools_types.go:366	Runtime	Mode, Toolsets, GuardPolicies, CustomFields

Recommendation: Rename to distinguish phases:

• pkg/parser/mcp.go: ParsedMCPServerConfig or MCPServerSpec
• pkg/workflow/tools_types.go: keep as MCPServerConfig (it is the runtime canonical form) or rename to RuntimeMCPServerConfig

Estimated effort: 1–2 hours.

---

Untyped any Usage

The codebase correctly uses any (Go 1.18+ alias for interface{}) and no raw interface{} was found. Of 1,862 usages across 118 files, the vast majority are justified:

• YAML/JSON parsing from frontmatter and workflow files requires map[string]any / []any because schema types are determined at runtime.
• Logger variadic args (Printf(format string, args ...any)) follow stdlib convention.
• Schema navigation functions (navigateToSchemaPath(schema map[string]any, ...)) deal with heterogeneous JSON Schema documents.
• MCP config GuardPolicies map[string]any and CustomFields map[string]any are intentionally open extension points.

The top contributors are in workflow compilation and tool parsing code that directly handles YAML unmarshalling. No immediate action is recommended for these — they represent legitimate use of dynamic typing at serialization boundaries.

The one case to review is compiler_safe_outputs_config.go (53 usages), which uses type handlerBuilder func(*SafeOutputsConfig) map[string]any. If the return values have known structure, a typed struct could replace map[string]any here.

---

Untyped Constants

The codebase already has a strong foundation with semantic type aliases in pkg/constants/:

type JobName      string   // e.g., AgentJobName, DetectionJobName
type StepID       string   // e.g., CheckMembershipStepID
type MCPServerID  string   // e.g., SafeOutputsMCPServerID
type LineLength   int
type CommandPrefix string
type WorkflowID   string

However, several groups of related constants lack types. The pattern is established — these are straightforward extensions.

Group 1 — Artifact Names (high value)

File: pkg/constants/job_constants.go:70–132

// Current (untyped)
const SafeOutputArtifactName    = "safe-output"
const AgentOutputArtifactName   = "agent-output"
const AgentArtifactName         = "agent"
const DetectionArtifactName     = "detection"
const ActivationArtifactName    = "activation"
const SarifArtifactName         = "code-scanning-sarif"
const SafeOutputItemsArtifactName = "safe-outputs-items"

// Suggested
type ArtifactName string

const SafeOutputArtifactName    ArtifactName = "safe-output"
const AgentOutputArtifactName   ArtifactName = "agent-output"
// ...

Benefit: Functions that upload or download artifacts can accept ArtifactName instead of string, preventing accidental use of a filename or step ID where an artifact name is expected.

---

Group 2 — Step Output Names (medium value)

File: pkg/constants/job_constants.go:178–191

// Current (untyped)
const IsTeamMemberOutput      = "is_team_member"
const StopTimeOkOutput        = "stop_time_ok"
const CommandPositionOkOutput = "command_position_ok"
const MatchedCommandOutput    = "matched_command"
const RateLimitOkOutput       = "rate_limit_ok"
const ActivatedOutput         = "activated"

// Suggested
type OutputName string

const IsTeamMemberOutput      OutputName = "is_team_member"
// ...

The StepID type already exists — a companion OutputName type would complete the job/step output contract.

---

Group 3 — System Filenames (low–medium value)

File: pkg/constants/job_constants.go:85–141

// Current (untyped)
const AgentOutputFilename      = "agent_output.json"
const SafeOutputsFilename      = "safeoutputs.jsonl"
const TokenUsageFilename       = "agent_usage.json"
const GithubRateLimitsFilename = "github_rate_limits.jsonl"
const OtelJsonlFilename        = "otel.jsonl"
const SarifFileName            = "code-scanning-alert.sarif"

// Suggested
type ArtifactFilename string

const AgentOutputFilename      ArtifactFilename = "agent_output.json"
// ...

---

Group 4 — Numeric Rate Limit Defaults (low value)

File: pkg/constants/job_constants.go:191–192

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

The comment indicates the unit is minutes, but nothing enforces it. A Minutes or RateLimitWindow type would encode the unit in the type system. Low priority given there are only two constants.

---

Implementation Checklist

• Rename FileTracker interface to avoid struct/interface name collision (pkg/workflow/compiler_types.go:46)
• Rename RepoConfig in pkg/cli/trial_types.go to TrialRepoConfig
• Rename EngineConfig in pkg/cli/audit_expanded.go to AuditEngineInfo
• Rename MCPServerConfig in pkg/parser/mcp.go to MCPServerSpec (or similar)
• Add ArtifactName type and apply to artifact name constants in pkg/constants/job_constants.go
• Add OutputName type and apply to step output name constants in pkg/constants/job_constants.go
• Add ArtifactFilename type and apply to filename constants in pkg/constants/job_constants.go
• Review compiler_safe_outputs_config.go handler builders for potential typed return values

Analysis Metadata

• Total Go files analyzed: 668 (non-test, pkg/ only)
• Packages scanned: 19
• Duplicate type clusters: 8 (3 actionable, 3 WASM-expected, 1 alias, 1 borderline)
• any usage locations: 1,862 across 118 files
• Untyped constant groups identified: 4
• Analysis date: 2026-04-13
• Workflow run: §24341651557

References:

• §24341651557

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

• expires on Apr 14, 2026, 11:53 AM UTC