[typist] Typist Report: Type Duplication and Untyped Usage Audit (pkg/)

[github-actions[bot]]

Executive Summary

This report is an automated type-consistency sweep of the gh-aw Go codebase (primary focus: pkg/, excluding _test.go files and pkg/linters/ testdata/internals). It looked for two classes of issue: duplicated type definitions (same or near-identical struct/interface shapes defined in more than one place) and untyped usages (interface{}/any or bare untyped constants standing in for a type that already exists, or should).

Headline findings:

• A real, previously-established DRY convention already exists for safe-output config structs (SafeOutputTargetConfig, SafeOutputFilterConfig, BaseSafeOutputConfig), but roughly a third of the ~34 *Config structs in pkg/workflow don't use it — including three structs with an actual field-shadowing bug (GitHubToken parsed twice, dead field left unread).
• One clean structural duplication in pkg/cli/logs_models.go: ProcessedRun, DownloadResult, and RunSummary share ~13-17 fields with no shared base type.
• One clean Go-generics opportunity in pkg/cli/audit_comparison.go: AuditComparisonIntDelta / AuditComparisonStringDelta differ only in value type.
• A GitHubIntegrityLevel enum (pkg/workflow/tools_types.go) is correctly used in one file but re-expressed as raw string literals in two others, and as a string-typed constant in a third.
• Three suspected duplicate pairs (ProgressBar, SpinnerWrapper, RepositoryFeatures) were investigated and confirmed legitimate (go/redacted):build wasm/native platform splits — no action needed. Flagging them here to show they were checked, not missed.
• The codebase is otherwise fairly disciplined about any/interface{} — the vast majority of hits are idiomatic YAML/JSON parsing (map[string]any) or genuine type-switch handling of heterogeneous values. Only one clear "should be concretely typed" function signature was found.

No files were modified — this is read-only analysis.

Summary Statistics

Metric	Count
Non-test .go files scanned (pkg/)	~1,213
Type definitions discovered (struct/interface)	1,090
Duplicate/near-duplicate type clusters found	3 structural + 1 multi-cluster (config structs)
False-positive pairs investigated and confirmed legitimate	3 (platform-split types)
Untyped-usage findings (genuine)	4
Files flagged for refactor	~20

---

Full Analysis Report

1. Duplicated Type Definitions

1.1 ProcessedRun / DownloadResult / RunSummary — near-duplicate result structs

Location: pkg/cli/logs_models.go:97, :252, :225

Three structs carry the same ~13-17 field "processed workflow run" shape, hand-duplicated instead of sharing a base:

// ProcessedRun (line 97)
type ProcessedRun struct {
    Run                     WorkflowRun
    AwContext               *AwContext
    TaskDomain              *TaskDomainInfo
    BehaviorFingerprint     *BehaviorFingerprint
    AgenticAssessments      []AgenticAssessment
    AccessAnalysis          *DomainAnalysis
    FirewallAnalysis        *FirewallAnalysis
    PolicyAnalysis          *PolicyAnalysis
    RedactedDomainsAnalysis *RedactedDomainsAnalysis
    MissingTools            []MissingToolReport
    MissingData             []MissingDataReport
    Noops                   []NoopReport
    MCPFailures             []MCPFailureReport
    SkillActivations        []SkillActivation
    MCPToolUsage            *MCPToolUsageData
    TokenUsage              *TokenUsageSummary
    GitHubRateLimitUsage    *GitHubRateLimitUsage
    JobDetails              []JobInfoWithDuration
}

// DownloadResult (line 252) — same fields minus PolicyAnalysis, plus:
    Metrics   LogMetrics
    Error     error
    Skipped   bool
    Cached    bool
    LogsPath  string

// RunSummary (line 225) — same core fields, plus:
    CLIVersion    string
    RunID         int64
    ProcessedAt   time.Time
    Metrics       LogMetrics
    ArtifactsList []string

For contrast, this same file already contains two correctly-factored examples of the pattern this cluster is missing:

• ReportProvenance (line 119) is embedded by MissingToolReport, NoopReport, MissingDataReport, MCPFailureReport, SkillActivation.
• AggregatedSummaryBase (line 171) is embedded by MissingToolSummary, MissingDataSummary.

Recommendation: extract a ProcessedRunBase (or similar) struct carrying the ~13 shared fields, and have ProcessedRun, DownloadResult, RunSummary embed it plus their own extras. This mirrors the ReportProvenance/AggregatedSummaryBase pattern already proven out in the same file.

---

1.2 AuditComparisonIntDelta / AuditComparisonStringDelta — generics candidate

Location: pkg/cli/audit_comparison.go:45, :51

type AuditComparisonIntDelta struct {
    Before  int
    After   int
    Changed bool
}

type AuditComparisonStringDelta struct {
    Before  string
    After   string
    Changed bool
}

Structurally identical except the value type. Both are composed into AuditComparisonDelta alongside AuditComparisonMCPFailureDelta.

Recommendation:

type AuditComparisonDelta[T comparable] struct {
    Before  T
    After   T
    Changed bool
}

then use AuditComparisonDelta[int] and AuditComparisonDelta[string] at call sites. Low risk — no external serialization concerns apparent beyond straightforward field access.

---

1.3 Confirmed not duplicates — platform-split types (no action needed)

Three pairs were flagged by initial name-collision scanning and then verified structurally distinct-but-related via (go/redacted):build tags:

Native file	Wasm file	Type	Verdict
pkg/console/progress.go ((go/redacted):build !js && !wasm)	pkg/console/progress_wasm.go ((go/redacted):build js || wasm)	ProgressBar	Legitimate — native has progress progress.Model, ttyCheck; wasm has a reduced field set (total, current, indeterminate, updateCount).
pkg/console/spinner.go	pkg/console/spinner_wasm.go	SpinnerWrapper	Legitimate — native has program *tea.Program, mu sync.Mutex, wg sync.WaitGroup; wasm has only enabled bool with no-op methods.
pkg/workflow/repository_features_validation.go	pkg/workflow/repository_features_validation_wasm.go	RepositoryFeatures	Legitimate — fields (HasDiscussions, HasIssues) are deliberately kept byte-identical per the wasm file's own comment, for cross-platform API compatibility; only method bodies diverge.

These are called out explicitly so it's clear they were checked, not overlooked.

---

1.4 Safe-output *Config structs — inconsistent use of an existing DRY layer

pkg/workflow already defines shared sub-structs for common config fields — BaseSafeOutputConfig, SafeOutputTargetConfig (Target, TargetRepoSlug, AllowedRepos), SafeOutputFilterConfig (RequiredLabels, RequiredTitlePrefix, TitlePrefix), SafeOutputAllowBlockConfig, UpdateEntityConfig — and roughly two-thirds of the ~34 top-level safe-output config structs embed them correctly. The remaining third hand-redeclares the same fields instead.

Cluster A — actual bug, not just duplication. GitHubToken string (yaml:"github-token,omitempty") is redeclared alongside an embedded BaseSafeOutputConfig that already has this field, in:

• pkg/workflow/create_project.go:10
• pkg/workflow/update_project.go:27
• pkg/workflow/create_project_status_update.go:12

Because Go field-shadowing makes the outer field win, and each parser (create_project.go:24-34, update_project.go:42-52, create_project_status_update.go:23-32) calls parseBaseSafeOutputConfig (which fills the embedded copy) and then re-parses "github-token" into the outer field, BaseSafeOutputConfig.GitHubToken is set but never read in these three structs. Currently harmless (both copies get the same value), but it's dead code masking a latent divergence risk if either parse path is edited independently in the future.

Cluster B — SafeOutputTargetConfig not used where it should be. TargetRepoSlug/AllowedRepos (and often Target) are hand-declared instead of embedding SafeOutputTargetConfig, in 8 structs:
create_issue.go:21-22, create_discussion.go:21-22, create_pull_request.go:47,51, add_comment.go:18-20, create_code_scanning_alert.go:18-19, push_to_pull_request_branch.go:16,24,29, dispatch_workflow.go:16,18, update_project.go:29-30.

Cluster C — RequiredLabels not consolidated into SafeOutputFilterConfig. 3 structs hand-declare RequiredLabels []string (yaml required-labels) with identical semantics to the ~14 structs that already embed SafeOutputFilterConfig for this field:
merge_pull_request.go:12 (also RequiredTitlePrefix at line 14), push_to_pull_request_branch.go:18, update_issue.go:21.

Cluster D — mixed bag, needs judgment, not a pure merge. TitlePrefix/Labels appear in two different senses across 6-8 structs: "prefix/labels to apply when creating" (create_issue.go, create_pull_request.go, create_discussion.go, create_project.go) vs. "prefix/labels used to filter/require" (push_to_pull_request_branch.go, update_issue.go — these two should fold into Cluster C/SafeOutputFilterConfig instead). Recommend a new, separately-named shared struct (e.g. SafeOutputCreateLabelingConfig{TitlePrefix, Labels}) for the "creation" group rather than merging both senses into one field.

Minor — DispatchRepositoryToolConfig (dispatch_repository.go:18-21) hand-copies 4 BaseSafeOutputConfig fields (Max, GitHubToken, GitHubApp, Staged) inside a map-value struct rather than embedding. Lowest priority since it's an isolated one-off, not a 3+ cluster.

2. Untyped Usages

2.1 any parameter that should be concretely typed

pkg/workflow/args.go:39

func getGitHubCustomArgs(githubTool any) []string {
    // type-asserts to map[string]any internally, no other case handled
}

Both call sites (pkg/workflow/mcp_renderer_github.go:84, :174) already hold githubTool as map[string]any before calling this — every sibling accessor in pkg/workflow/mcp_github_config.go (getGitHubType, getGitHubLockdown, getGitHubToolsets, getGitHubAllowedTools, getGitHubDockerImageVersion) already takes map[string]any directly. This one function is the outlier still doing a needless runtime type assertion.

// Recommended
func getGitHubCustomArgs(githubTool map[string]any) []string

2.2 GitHubIntegrityLevel enum re-expressed as raw strings

Enum definition: pkg/workflow/tools_types.go:287-297 (GitHubIntegrityNone, Unapproved, Approved, Merged).

Used correctly in pkg/workflow/tools_validation_github.go:165-169:

validIntegrityLevels := map[GitHubIntegrityLevel]bool{GitHubIntegrityNone: true, ...}

Duplicated as plain strings in the same package, pkg/workflow/tools_validation_github_integrity_reactions.go:23-35:

var validDisapprovalIntegrityLevels = map[string]bool{"none": true, "unapproved": true, "approved": true, "merged": true}
var validEndorserMinIntegrityLevels = map[string]bool{ /* same 4 literals */ }

Recommendation: retype both maps to map[GitHubIntegrityLevel]bool using the existing named constants — removes the risk of the string literals and the enum drifting apart silently.

2.3 defaultCacheIntegrityLevel typed as plain string instead of GitHubIntegrityLevel

pkg/workflow/cache_integrity.go:17

const defaultCacheIntegrityLevel = "none"

cacheIntegrityLevel() (line 166) also returns plain string, forcing an explicit string(github.MinIntegrity) conversion at line 170 that wouldn't be needed if the return type were GitHubIntegrityLevel to begin with.

2.4 Minor/weaker candidates (lower priority, listed for completeness)

• pkg/constants/constants.go:332 — DefaultMaxDailyAICredits = "5000" is a string while DefaultMaxAICredits/DefaultDetectionMaxAICredits (lines 325, 329) are int64. May be intentional (templated/env-var string) — verify before changing.
• pkg/constants/job_constants.go:260-261 and pkg/constants/constants.go:618 — untyped numeric constants (DefaultRateLimitMax, DefaultRateLimitWindow, MaxSymlinkDepth) with no shared enum family; single-use magnitudes, not worth a named type.

2.5 Explicitly excluded from findings — idiomatic, not a problem

The pervasive use of map[string]any (300+ occurrences across ~958 files) for YAML/JSON config parsing was reviewed and excluded — this is the idiomatic Go pattern for decoding heterogeneous, schema-flexible data (workflow frontmatter, MCP tool configs) and converting it to strong types would require either a large schema/validation library or hand-written unmarshalers with no clear benefit here. Likewise, console.FormField.Value any (pkg/console/console_types.go:50) is a deliberate generic-form-library field (holds a pointer to whatever the caller wants filled in) and type-switch-based accessors handling int/float64/string/bool/map/[]any from decoded YAML are correct, idiomatic uses of any.

---

Refactoring Recommendations

#	Recommendation	Files affected	Effort	Impact
1	Remove shadowed GitHubToken field re-declarations, rely on embedded BaseSafeOutputConfig	create_project.go, update_project.go, create_project_status_update.go	Low	Medium — removes a latent divergence bug
2	Embed SafeOutputTargetConfig instead of hand-declaring Target/TargetRepoSlug/AllowedRepos	create_issue.go, create_discussion.go, create_pull_request.go, add_comment.go, create_code_scanning_alert.go, push_to_pull_request_branch.go, dispatch_workflow.go, update_project.go	Low–Medium (mechanical, verify YAML tags match)	Medium — consistency, less code to maintain
3	Embed SafeOutputFilterConfig instead of hand-declaring RequiredLabels/RequiredTitlePrefix	merge_pull_request.go, push_to_pull_request_branch.go, update_issue.go	Low	Medium
4	Extract shared base struct for ProcessedRun/DownloadResult/RunSummary	pkg/cli/logs_models.go	Medium	Medium — matches existing ReportProvenance/AggregatedSummaryBase pattern in same file
5	Generic AuditComparisonDelta[T] to replace Int/StringDelta pair	pkg/cli/audit_comparison.go	Low	Low–Medium
6	Retype GitHubIntegrityLevel-shaped maps/constants from string to the named enum	tools_validation_github_integrity_reactions.go, cache_integrity.go	Low	Low–Medium — prevents enum/string drift
7	Narrow getGitHubCustomArgs parameter from any to map[string]any	pkg/workflow/args.go	Low	Low
8	New SafeOutputCreateLabelingConfig for "labels/prefix to apply on create" (distinct from filter semantics)	create_issue.go, create_pull_request.go, create_discussion.go, create_project.go	Medium (needs a rename, not a pure merge)	Low–Medium
9	Embed BaseSafeOutputConfig in DispatchRepositoryToolConfig instead of hand-copying 4 fields	dispatch_repository.go	Low	Low

---

Implementation Checklist

• Fix GitHubToken field-shadowing bug in 3 project-related configs (rejig docs #1)
• Migrate 8 structs to embed SafeOutputTargetConfig (Add workflow: githubnext/agentics/weekly-research #2)
• Migrate 3 structs to embed SafeOutputFilterConfig (Add workflow: githubnext/agentics/weekly-research #3)
• Extract ProcessedRunBase for pkg/cli/logs_models.go (Add workflow: githubnext/agentics/weekly-research #4)
• Introduce AuditComparisonDelta[T] generic, update call sites (Add workflow: githubnext/agentics/weekly-research #5)
• Retype integrity-level maps/constants to GitHubIntegrityLevel (add cli flag to guard dropping a agentic workflow instructinos file #6)
• Narrow getGitHubCustomArgs signature (Weekly Research Report: AI Workflow Automation Landscape and Market Opportunities - August 2025 #7)
• Design and introduce SafeOutputCreateLabelingConfig (Add workflow: githubnext/agentics/weekly-research #8, needs design discussion first)
• Embed BaseSafeOutputConfig in DispatchRepositoryToolConfig (Weekly Research Report: AI Workflow Automation Landscape and Strategic Opportunities - August 2025 #9)
• No action needed: ProgressBar, SpinnerWrapper, RepositoryFeatures wasm/native pairs (confirmed legitimate)

---

Analysis Metadata

• Scope: pkg/ Go source files, excluding _test.go and pkg/linters/ internals/testdata
• Files scanned: ~1,213 non-test .go files
• Type definitions catalogued: 1,090 struct/interface declarations
• Method: bulk pattern discovery (struct/interface declaration grep across pkg/) followed by targeted structural review of name-collision candidates, plus dedicated passes for safe-output config duplication and untyped-usage audit
• Analysis type: read-only; no files modified

Generated by ✍️ Typist - Go Type Analysis · agent · 341.4 AIC · ⌖ 45.5 AIC · ⊞ 8.7K · ◷

• expires on Aug 13, 2026, 3:50 AM UTC-08:00

[github-actions[bot]]

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

A newer discussion is available at Discussion #52484.