Typist: Go Type Consistency Analysis

[github-actions[bot]]

Analysis of Go type consistency across the pkg/ directory of github/gh-aw.

The codebase is overall well-typed — most previously problematic patterns (like MCPServerConfig) have already been addressed via a shared pkg/types base. The main opportunities center on pervasive map[string]any for frontmatter and a cluster of untyped string/numeric constants that would benefit from typed grouping.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total non-test Go files analyzed: 621
• Total type definitions: 610
• True duplicate clusters found: 0 (all apparent duplicates are intentional)
• Name-collision clusters (different semantics): 1 (EngineConfig)
• Platform-conditional duplicates (build tags): 2 (SpinnerWrapper, ProgressBar, RepositoryFeatures — WASM vs non-WASM)

Cluster 1: EngineConfig — Name Collision (Different Semantics)

Type: Semantic name collision
Impact: Medium — same name in the same cli package scope (different file) vs workflow package

Locations:

1. pkg/workflow/engine.go:15 — runtime engine configuration (ID, Model, MaxTurns, Args, Env, etc.)
2. pkg/cli/audit_expanded.go:19 — audit-report DTO (EngineID, EngineName, CLIVersion, MCPServers, etc.)

Definition comparison:

// pkg/workflow/engine.go — runtime/compilation config
type EngineConfig struct {
    ID, Version, Model, MaxTurns, Concurrency, UserAgent, Command string
    MaxContinuations int
    Env              map[string]string
    Args             []string
    IsInlineDefinition bool
    // ...
}

// pkg/cli/audit_expanded.go — audit-report data transfer object
type EngineConfig struct {
    EngineID, EngineName, Model, Version, CLIVersion, FirewallVersion string
    MCPServers   []string
    TriggerEvent string
    Repository   string
}
```

**Recommendation**: Rename the audit DTO to avoid confusion.

- Rename `pkg/cli/audit_expanded.go:EngineConfig` → `AuditEngineSnapshot` or `EngineAuditConfig`
- Improves searchability — currently two `EngineConfig` types with different field sets cause cognitive overhead
- **Estimated effort**: < 1 hour (single file, no cross-package import)

---

#### Cluster 2: `MCPServerConfig` — Already Properly Handled ✅

**Locations**:
- `pkg/workflow/tools_types.go:479` — embeds `types.BaseMCPServerConfig`, adds `Mode`, `Toolsets`, `GuardPolicies`, `CustomFields`
- `pkg/parser/mcp.go:35` — embeds `types.BaseMCPServerConfig`, adds `Name`, `Registry`, `ProxyArgs`, `Allowed`

**Status**: This is a well-designed split. The `pkg/types` package intentionally provides `BaseMCPServerConfig` as a shared base, with each package extending it for its domain. No action needed.

---

#### Cluster 3: `RepositoryFeatures`, `SpinnerWrapper`, `ProgressBar` — Build-Tag Conditionals ✅

**Pattern**: `//go:build !js && !wasm` / `//go:build js || wasm` pairs providing platform-specific stub implementations.

- `pkg/workflow/repository_features_validation.go` vs `pkg/workflow/repository_features_validation_wasm.go`
- `pkg/console/spinner.go` vs `pkg/console/spinner_wasm.go`
- `pkg/console/progress.go` vs `pkg/console/progress_wasm.go`

**Status**: Intentional and correct Go idiom. No action needed.

---

#### Cluster 4: `FileTracker` — Not a Duplicate ✅

- `pkg/cli/file_tracker.go:18` — concrete `struct` implementation
- `pkg/workflow/compiler_types.go:51` — `interface` definition

**Status**: Standard Go pattern (interface + implementation in different packages). Not a duplicate.

---

### Untyped Usages

#### Summary Statistics

- **`interface{}` usages**: 0 (none found — the codebase has fully migrated to `any`)
- **`any` type usages**: 1,443 (all via `map[string]any` or `[]any`)
- **`map[string]any` usages**: 1,443 total, **1,048 in `pkg/workflow/`** alone
- **Functions with `frontmatter map[string]any` parameter**: 142
- **Untyped string/numeric constants**: ~25 (in `pkg/constants/constants.go`)

---

#### Category 1: `map[string]any` for Frontmatter (High Volume)

**Impact**: Medium — the pattern is pervasive but reflects genuine YAML dynamism; a type alias would improve readability without requiring behavioral changes

**Locations**: 142 function signatures across `pkg/workflow/` and `pkg/cli/` — examples:

```
pkg/workflow/compiler_orchestrator_workflow.go:246  extractYAMLSections(frontmatter map[string]any, ...)
pkg/workflow/compiler_filters_validation.go:57       ValidateEventFilters(frontmatter map[string]any) error
pkg/workflow/slash_command_parser.go:34             expandSlashCommandShorthand(...) map[string]any
pkg/cli/codemod_factory.go:8                        PostTransformFunc func(lines []string, frontmatter map[string]any, fieldValue any) []string
pkg/cli/imports.go:142                              reconstructWorkflowFileFromMap(frontmatter map[string]any, ...) (string, error)

Current state:

func ValidateEventFilters(frontmatter map[string]any) error { ... }
func (c *Compiler) extractYAMLSections(frontmatter map[string]any, workflowData *WorkflowData) { ... }

Suggested fix: Introduce a type alias in pkg/workflow (or pkg/types) to document intent without changing behavior:

// Frontmatter represents the parsed YAML frontmatter from a workflow markdown file.
// Values are untyped because YAML can contain arbitrary nested structures.
type Frontmatter = map[string]any

// Then all 142 signatures become self-documenting:
func ValidateEventFilters(frontmatter Frontmatter) error { ... }

Benefits: Grep-ability, self-documentation, easier future migration to a typed struct, no behavioral change required
Estimated effort: 2–3 hours (mechanical rename)

---

Category 2: Untyped Artifact Name Constants

Impact: Medium — artifact names mixed with other string constants, no compile-time check prevents wrong string being used as an artifact name

Location: pkg/constants/constants.go:635–670

Current state:

const SafeOutputArtifactName      = "safe-output"       // untyped string
const AgentOutputArtifactName     = "agent-output"       // untyped string
const AgentArtifactName           = "agent"              // untyped string
const DetectionArtifactName       = "detection"          // untyped string
const LegacyDetectionArtifactName = "threat-detection.log"
const ActivationArtifactName      = "activation"
const SafeOutputItemsArtifactName = "safe-output-items"
const FirewallAuditArtifactName   = "firewall-audit-logs"

Suggested fix:

type ArtifactName string

const (
    SafeOutputArtifactName      ArtifactName = "safe-output"
    AgentOutputArtifactName     ArtifactName = "agent-output"
    AgentArtifactName           ArtifactName = "agent"
    DetectionArtifactName       ArtifactName = "detection"
    LegacyDetectionArtifactName ArtifactName = "threat-detection.log"
    ActivationArtifactName      ArtifactName = "activation"
    SafeOutputItemsArtifactName ArtifactName = "safe-output-items"
    FirewallAuditArtifactName   ArtifactName = "firewall-audit-logs"
)

Benefits: Prevents accidentally passing a filepath or other string where an artifact name is expected; all 8 constants self-document as artifact names
Estimated effort: 1–2 hours (update usage sites to cast when passing to string-accepting APIs)

---

Category 3: Untyped Job Output Name Constants

Impact: Medium — output names interchangeable with arbitrary strings

Location: pkg/constants/constants.go:736–746

Current state:

const IsTeamMemberOutput        = "is_team_member"       // untyped string
const StopTimeOkOutput          = "stop_time_ok"
const SkipCheckOkOutput         = "skip_check_ok"
const SkipNoMatchCheckOkOutput  = "skip_no_match_check_ok"
const CommandPositionOkOutput   = "command_position_ok"
const MatchedCommandOutput      = "matched_command"
const RateLimitOkOutput         = "rate_limit_ok"
const SkipRolesOkOutput         = "skip_roles_ok"
const SkipBotsOkOutput          = "skip_bots_ok"
const SkipIfCheckFailingOkOutput = "skip_if_check_failing_ok"
const ActivatedOutput           = "activated"

Suggested fix: Introduce type OutputName string (similar to the existing JobName, StepID patterns already in the file):

type OutputName string

const (
    IsTeamMemberOutput         OutputName = "is_team_member"
    StopTimeOkOutput           OutputName = "stop_time_ok"
    // ... etc.
)

Benefits: Consistent with existing JobName / StepID typed constant patterns already in the file
Estimated effort: 1–2 hours

---

Category 4: Untyped Numeric/Bool Constants

Impact: Low — numeric constants without units or type constraints

Location: pkg/constants/constants.go

Current state:

const DefaultMCPGatewayPayloadSizeThreshold = 524288  // bytes? unspecified
const DefaultRateLimitMax    = 5                        // untyped int
const DefaultRateLimitWindow = 60                       // untyped int (minutes? seconds?)
const DefaultGitHubLockdown  = false                    // untyped bool

Suggested fixes:

// Make units explicit
const DefaultMCPGatewayPayloadSizeThreshold int = 524288  // 512 KB in bytes

type RateLimit struct {
    Max    int
    Window int // minutes
}

// Or at minimum add comments documenting units (already partially done):
const DefaultRateLimitMax    = 5  // Maximum runs per time window
const DefaultRateLimitWindow = 60 // Time window in minutes

Benefits: Avoids unit confusion (already bit the project once based on comment style), prevents accidental type mismatches
Estimated effort: 30 minutes

---

Category 5: DevcontainerFeatures map[string]any — Partially Addressed ✅

Location: pkg/cli/devcontainer.go:39

Current state:

type DevcontainerFeatures map[string]any

Status: The type alias already exists and is a good pattern — it documents intent. The mergeFeatures helper still takes map[string]any for the second argument rather than DevcontainerFeatures, which is a minor inconsistency.

Suggested fix:

// pkg/cli/devcontainer.go:305
func mergeFeatures(existing DevcontainerFeatures, toAdd DevcontainerFeatures) {

Estimated effort: 15 minutes

---

Refactoring Recommendations

Priority 1: Medium — Rename EngineConfig Audit DTO

Recommendation: Rename pkg/cli/audit_expanded.go:EngineConfig to AuditEngineSnapshot

Steps:

1. Rename type in pkg/cli/audit_expanded.go
2. Update the single usage at line 127 in the same file
3. Run go build ./... to verify

Estimated effort: < 1 hour
Impact: Eliminates name collision, improves searchability

---

Priority 2: Medium — Introduce Frontmatter Type Alias

Recommendation: Add type Frontmatter = map[string]any to pkg/workflow (or pkg/types)

Steps:

1. Add type alias definition in pkg/workflow/compiler_types.go or pkg/types/frontmatter.go
2. Update 142 function signatures across pkg/workflow/ and pkg/cli/
3. Run go build ./...

Estimated effort: 2–3 hours
Impact: Improves readability and grep-ability across the largest code surface

---

Priority 3: Medium — Type Artifact Name & Output Name Constants

Recommendation: Introduce ArtifactName and OutputName types — consistent with existing JobName, StepID, MCPServerID patterns

Steps:

1. Add type ArtifactName string and type OutputName string to pkg/constants/constants.go
2. Update the 19 affected constant declarations
3. Update call sites to cast as needed (.String() or string(...))

Estimated effort: 1–2 hours
Impact: Compile-time safety for artifact and output name usage

---

Priority 4: Low — Fix mergeFeatures Signature

Recommendation: Align mergeFeatures second argument to DevcontainerFeatures

Estimated effort: 15 minutes

---

Implementation Checklist

• Rename cli.EngineConfig (audit DTO) → AuditEngineSnapshot
• Add type Frontmatter = map[string]any alias
• Update 142 frontmatter function signatures
• Add type ArtifactName string and group artifact constants
• Add type OutputName string and group output name constants
• Fix mergeFeatures signature to use DevcontainerFeatures
• Run go build ./... after each change

Analysis Metadata

Metric	Value
Total non-test Go files analyzed	621
Total type definitions	610
True duplicate type clusters	0
Name-collision type clusters	1 (EngineConfig)
Build-tag conditional pairs	3 (intentional)
any / map[string]any usages	1,443
Functions with untyped frontmatter param	142
Untyped string constants (candidates)	~19
Detection method	Serena LSP + pattern search + grep
Analysis date	2026-03-31

References:

• §23794594978

AI generated by Typist - Go Type Analysis · history

• expires on Apr 1, 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 #23860.