[typist] 🔤 Typist - Go Type Consistency Analysis

[github-actions[bot]]

Analysis of repository: github/gh-aw

Executive Summary

I scanned roughly 1,245 non-test top-level type declarations and ~4,700 interface{}/any usages across the ~1,380 non-test .go files under pkg/. The good news: the codebase is disciplined about idiomatic Go — almost all any usage is either generic type parameters ([T any]) or genuinely dynamic YAML/JSON frontmatter parsing backed by a dedicated pkg/typeutil helper package, and the old interface{} syntax barely exists outside linter test fixtures. The codebase also already knows how to deduplicate well: pkg/types.BaseMCPServerConfig is a clean example of extracting a shared base type.

That said, a handful of real opportunities stand out. Two structs — graderManifestEntry and runtimeImportReference — are copy-pasted verbatim (including one shared regex) across pkg/parser/pkg/cli/pkg/workflow, and the cli copy of graderManifestEntry has silently drifted out of sync with the newer workflow-side fields. Separately, a "string or number from JSON/YAML" type-switch (case float64: ... case string: ...) is hand-rolled in at least 39 files instead of using one shared type. Fixing these two things alone would remove a meaningful amount of near-duplicate boilerplate without touching the parts of the codebase that are intentionally dynamic.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total types analyzed: ~1,245
• Duplicate clusters found: 10 (reported below)
• Exact duplicates: 0
• Near duplicates: 6
• Semantic duplicates: 4 (2 confirmed false positives on inspection, noted for search-hygiene only)

Cluster 1: graderManifestEntry — diverging near-duplicate

Type: Near duplicate
Occurrences: 2 (+1 test file)
Impact: High — same JSON manifest, silently diverging schemas

Locations:

1. pkg/cli/audit_report_graders.go:67 — reader side
2. pkg/workflow/compiler_yaml_graders.go:86 — writer side

// pkg/cli (reader) — only 5 fields
type graderManifestEntry struct {
    ID, Name, Unit, Direction string
    Threshold *float64
}

// pkg/workflow (writer) — 13 fields
type graderManifestEntry struct {
    ID, Name, Description, Source string
    Enabled bool
    Unit, Direction string
    Threshold, Max, Min *float64
    Digest, Run, Inline string
    Config map[string]any
}

Recommendation: Move the canonical struct into a shared package (e.g. pkg/types) so the reader can't silently drop fields (Enabled, Source, Max, Min, Digest, Run, Inline, Config) the writer emits. Estimated effort: 1-2 hours.

---

Cluster 2: runtimeImportReference — struct + regex copy-pasted

Type: Near duplicate
Occurrences: 2 real usage sites (+1 additional consumer file)
Impact: High — parsing logic for the same macro syntax duplicated in two packages

Locations:

1. pkg/parser/frontmatter_hash.go:572
2. pkg/workflow/runtime_import_validation.go:38
3. pkg/workflow/compiler_yaml_prompt.go (consumer)

// Both files, same 3 fields, one renamed:
type runtimeImportReference struct {
    path/importPath string
    startLine        int
    endLine          int
}

Both files also define byte-for-byte identical regexes for the {{#runtime-import ...}} macro. If the macro syntax ever changes, it must be changed in two places by hand.

Recommendation: Extract the regex + struct into a shared helper package. Estimated effort: 1-2 hours.

---

Cluster 3: HostedWebPolicy vs AWFHostedWebPolicy

Type: Near duplicate
Occurrences: 78 references across 12 files
Impact: Medium — recently added feature (commit #63212, "Add hosted web domain policies to workflow frontmatter")

// pkg/workflow/engine.go:209 — frontmatter-facing
type HostedWebPolicy struct {
    Enabled bool
    Allowed, Blocked []string
    MaxUses int
}

// pkg/workflow/awf_config.go:225 — AWF-runtime-facing
type AWFHostedWebPolicy struct {
    Enabled bool
    AllowedDomains, BlockedDomains []string
    MaxUses int
}

Same 4 conceptual fields, different tag/naming conventions. This mirrors the codebase's existing "Definition → Runtime" converter pattern (see EngineCapabilitiesDefinition.ToRuntimeCapabilities()).

Recommendation: Confirm an explicit converter function exists between the two (as with EngineCapabilities); if not, add one so field additions can't drift silently. Estimated effort: 1 hour.

---

Cluster 4: "Wire"/"WireSchema" triple-duplication for custom MarshalJSON types

Type: Near duplicate (systemic pattern)
Occurrences: At least 5 triplets in pkg/cli
Impact: Medium — same field set hand-maintained 3x per type

Examples: domainAnalysisWire / domainAnalysisWireSchema, mcpServerHealthDetailWire, mcpFailureSummaryWire. A comment in pkg/cli/mcp_schema.go already acknowledges this: "These wire types mirror custom MarshalJSON output, which reflection cannot infer."

Recommendation: Generate the schema struct directly from the MarshalJSON anonymous struct via a shared reflection-friendly builder instead of hand-maintaining a third copy per type. Estimated effort: 3-4 hours (affects 5 types).

---

Cluster 5: Definition/Runtime twin structs (systemic, mostly intentional)

EngineCapabilities / EngineCapabilitiesDefinition, EngineNetworkConfig / EngineNetworkDefinition, EngineAuthConfig / AuthDefinition — an intentional declarative-YAML-to-runtime pattern with explicit ToRuntimeX() converters. Not a bug, but ~6 pairs must be kept in sync by hand.

Recommendation: Document the pattern once and add a test that fails if a *Definition struct's field set diverges from its runtime counterpart without updating the converter.

---

Cluster 6: DomainAnalysis / RedactedDomainsAnalysis / WorkflowDomainsSummary / DomainBuckets / DomainBreakdown

Five separate "domain summary" structs across pkg/cli built for different reports (access logs, redaction audit, domain inventory, generic bucketing, outcome breakdown). Not confirmed field-identical, but worth a follow-up pass to see if 2-3 can share a common base struct.

---

Noted false positives (search hygiene, no action needed)

• Cluster (pkg/agentdrain) vs RunCluster (pkg/cli/audit_cross_run_clusters.go) — unrelated domains (log-template mining vs. run-grouping), fields don't overlap.
• PolicyRule/PolicyCondition (pkg/intent) vs FirewallPolicyRule (pkg/cli/firewall_policy.go) — agent-governance policy vs. network-firewall ACL rules, only vocabulary overlaps.
• safeOutputTargetConfig vs SafeOutputTargetConfig (pkg/workflow) — case-only name collision between structurally unrelated types; low-risk but a grep/readability hazard worth a rename.

---

Untyped Usages

Summary Statistics

• Raw interface{}/any hits scanned: ~4,703
• High-signal findings after filtering idiomatic generics/dynamic-YAML use: 7
• interface{} (legacy syntax) in production code: effectively 0 (confined to linter testdata)
• Untyped constants flagged: 2

Category 1: map[string]any with a fully-known schema

Impact: High

Example: pkg/workflow/trigger_parser.go:29

type TriggerIR struct {
    Filters          map[string]any
    AdditionalEvents map[string]any
    // ...
}

Built by hand in ~15 parse*Trigger functions (parsePushTrigger, parsePullRequestTrigger, parseIssueTrigger, parseManualTrigger, ...), always with the same small set of well-known keys (branches, tags, paths, workflow_dispatch, inputs...). The schema is fully known per event type at compile time, so map[string]any hides key typos the compiler could otherwise catch.

Suggested fix: Per-event concrete filter structs (PushFilters{Branches, BranchesIgnore, Tags, TagsIgnore, Paths, PathsIgnore []string}, PullRequestFilters{...}), unified via a small interface with a ToYAMLMap() method.

---

Category 2: Duplicated Target any field across 5 config structs

Impact: High

Location: pkg/workflow/safe_outputs_azure_devops.go (lines 40, 52, 57, 64, 70)

Target any `yaml:"target,omitempty"` // repeated in UpdateWorkItemConfig, CommentOnWorkItemConfig,
                                       // AssignWorkItemConfig, LinkWorkItemsConfig, UploadWorkItemAttachmentConfig

All 5 are consumed by the same helper, addAzureDevOpsTarget (confirmed: 6 references in this file), which just nil-checks and forwards. The value is always a work-item ID (string/int) or a GH Actions expression string — a bounded, knowable domain.

Suggested fix:

type AzureDevOpsWorkItemTarget struct {
    ID           string
    IsExpression bool
}
// with UnmarshalYAML accepting string or int

---

Category 3: Repeated "string or number" type-switch — 39 files

Impact: High (confirmed via grep: case float64: appears in 39 non-test files)

Location (representative): pkg/cli/mcp_tools_privileged.go:458

RunID      any `json:"run_id,omitempty"`
RunIDOrURL any `json:"run_id_or_url,omitempty"`

with a normalizeAuditRunInput(input any, fieldName string) type switch on nil/string/float64/int/int64. The same 4-case pattern recurs nearly verbatim across checkout_config_parser.go, service_ports.go, runtime_overrides.go, step_types.go, role_checks.go, engine.go, mcp_github_config.go, and ~32 other files.

Suggested fix: A single shared StringOrNumber type in pkg/typeutil implementing json.Unmarshaler with a .String() accessor, replacing ~39 ad-hoc copies of the same type switch.

Estimated effort: 4-6 hours (mechanical, high test coverage already exists per call site).

---

Category 4: Discriminated-union fields left as any despite documented shapes

Impact: Medium

Location: pkg/workflow/frontmatter_types.go:252,280,289

Headers  any `json:"headers,omitempty"`  // doc comment: "map form or deprecated comma-separated string"
Endpoint any `json:"endpoint,omitempty"` // doc comment: "string / object / array"

Both fields have doc comments enumerating exactly 2-3 accepted concrete shapes — a closed discriminated union, not truly dynamic data. The sibling field WorkflowFilePermissions in the very same file already demonstrates the intended pattern (custom UnmarshalYAML accepting scalar-or-map).

Suggested fix: OTLPHeaders and OTLPEndpointValue types with custom UnmarshalJSON, following the existing WorkflowFilePermissions pattern for On/RunsOn in pkg/workflow/workflow_file.go too.

---

Category 5: Untyped constants

Impact: Medium

Example 1: pkg/constants/job_constants.go:310

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

Every other timeout-like constant in pkg/constants/constants.go is a typed time.Duration (e.g. DefaultToolTimeout = 60 * time.Second), but DefaultRateLimitWindow's unit ("minutes") is only documented in a comment — a future caller could easily misread it as seconds. Consumed at pkg/workflow/role_checks.go:84.

Suggested fix: const DefaultRateLimitWindow = 60 * time.Minute.

Example 2: pkg/workflow/model_alias_validation.go:53

switch value {
case "low", "medium", "high":

The same closed 3-value enum recurs as bare strings in pkg/cli/audit_report.go:86 (Priority) and pkg/cli/audit_cross_run_clusters.go:45 (Severity), documented only by comments.

Suggested fix:

type EffortLevel string
const (
    EffortLow    EffortLevel = "low"
    EffortMedium EffortLevel = "medium"
    EffortHigh   EffortLevel = "high"
)

---

Verified non-issues (excluded after sampling)

map[string]any in pkg/parser (2,780+ occurrences, concentrated in frontmatter/schema files) backs genuinely dynamic YAML/JSON parsing, already served by a purpose-built pkg/typeutil package (ParseIntValue, ConvertToInt, LookupMap, LookupString). This is idiomatic for the domain and was intentionally excluded.

---

🎯 What Should We Do About This?

Priority 1: High-impact, low-effort — shared "string or number" type

Recommendation: Add pkg/typeutil.StringOrNumber (or similar) and migrate the ~39 files with hand-rolled case float64: type switches.
Estimated effort: 4-6 hours
Impact: High — removes the single most-duplicated pattern found in this scan

---

Priority 2: High — fix drifting graderManifestEntry and shared runtimeImportReference

Recommendation: Extract both into shared types (pkg/types or a new small package) so the cli reader can't silently drop fields the workflow writer emits, and the runtime-import regex/struct isn't hand-copied.
Estimated effort: 2-4 hours combined
Impact: High — closes an active schema-drift bug risk

---

Priority 3: Medium — Azure DevOps Target any and OTLP Headers/Endpoint fields

Recommendation: Replace with small typed unions (AzureDevOpsWorkItemTarget, OTLPHeaders, OTLPEndpointValue) using custom UnmarshalYAML/UnmarshalJSON, following the WorkflowFilePermissions pattern already established in the same file.
Estimated effort: 3-4 hours
Impact: Medium — removes type assertions at well-defined boundaries

---

Priority 4: Low — constant typing and naming hygiene

Recommendation: Type DefaultRateLimitWindow as time.Duration; introduce a shared EffortLevel (or similar) enum type for the low/medium/high pattern; rename safeOutputTargetConfig to avoid the case-only collision with SafeOutputTargetConfig.
Estimated effort: 1-2 hours
Impact: Low-medium — clarity and search-hygiene

---

Implementation Checklist

• Extract shared pkg/typeutil.StringOrNumber type, migrate the highest-traffic call sites first (mcp_tools_privileged.go, checkout_config_parser.go, service_ports.go)
• Move graderManifestEntry to a shared package; add a field-parity test between writer and reader
• Extract shared runtimeImportReference struct + regex used by pkg/parser and pkg/workflow
• Add/verify explicit HostedWebPolicy → AWFHostedWebPolicy converter
• Type the Azure DevOps Target field and OTLP Headers/Endpoint fields as documented unions
• Type DefaultRateLimitWindow as time.Duration; add shared EffortLevel enum
• Rename safeOutputTargetConfig to remove the case-only collision
• Run full test suite after each extraction

Analysis Metadata

• Total Go Files Analyzed: 1,380 (non-test, pkg/ only)
• Total Type Definitions Scanned: ~1,245
• Duplicate Clusters Reported: 6 actionable + 4 noted/false-positive
• Untyped Usage Locations Reported: 7 categories (from ~4,703 raw hits)
• Detection Method: grep/pattern-based extraction (Serena's Go language server was unavailable in this sandbox — no Go toolchain on PATH — so semantic reference tracing fell back to grep-based cross-referencing)
• Analysis Date: 2026-09-25

References:

• §36129422336

Generated by ✍️ Typist - Go Type Analysis · claude · agent · 357.7 AIC · ⌖ 11 AIC · ⊞ 10.2K · ◷

• expires on Sep 26, 2026, 3:38 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-09-26T11:38:29.380Z.

Closed by Workflow