[typist] Typist: duplicated job-shape types and untyped WorkflowData fields in pkg/

[github-actions[bot]]

Analysis of repository: github/gh-aw

Executive Summary

Scanned 1,658 non-test .go files under pkg/ (1,739 type definitions). The codebase has essentially finished migrating off interface{} (0 real production usages remain, only comments/testdata). Most same-name type clusters found (Config, Rule, StepID, LogParser, RenderOptions) are unrelated types that share a common Go idiom, not real duplication.

The real finding: the same GitHub Actions job concept (runs-on, permissions, concurrency, environment, container, strategy, services, secrets, on, needs) is independently represented four different ways across pkg/workflow/jobs.go, pkg/workflow/actions/parse.go, pkg/workflow/actions/workflow.go, and pkg/workflow/workflow_file.go, each falling back to any/map[string]any for most fields. The codebase already proves the fix pattern twice over: WorkflowFilePermissions (a scalar-or-map union type) and the actions.Expression AST, but has not extended either to the remaining fields, so parse.go ends up doing manual type switches on secrets and needs.

Full Analysis Report

Duplicated Type Definitions

Stats: 1,658 files, 1,739 types, 18 same-name clusters found, 5 actionable after review, 13 excluded as false positives (linter testdata fixtures: fakeOS, Worker, GenericCloser, myString, myBytes; plus coincidental same-name/different-purpose: state, Config, Rule, StepID, LogParser, RenderOptions).

Cluster 1 (High): workflow-job shape re-typed four times

• pkg/workflow/jobs.go Job: string-based shape for template emission (RunsOn/Permissions/Concurrency/Environment/Strategy/Container/Services all plain string)
• pkg/workflow/actions/workflow.go:19-49 Job (native AST): RunsOn/Permissions/Concurrency/Environment/Container are any; Defaults/Strategy/Services are map[string]any, mixed on the same struct with typed fields (If Expression, Env map[string]Expression, ContinueOnError Expression)
• pkg/workflow/actions/parse.go:14-45 workflowYAML/jobYAML raw decode target: On/Permissions/Concurrency/RunsOn/Needs/If/Environment/Container/Secrets all any
• pkg/workflow/workflow_file.go:8-19 WorkflowFile/WorkflowFileJob: On and RunsOn are any, but Permissions is already *WorkflowFilePermissions, a real custom type with its own UnmarshalYAML accepting a shorthand string or a map of scopes
• Smaller copies in pkg/cli: list_workflows_command.go:29 (On any), jsonworkflow_to_markdown.go:39 (On any), runner_guard_activation_gate.go:19 (Needs any)

Concrete cost today: a manual type switch at pkg/workflow/actions/parse.go:160 on source.Secrets.(type) (cases nil/string/map[string]any/default), plus a sibling parseNeeds(value any) a few lines below doing the same for needs.

Recommendation: generalize the WorkflowFilePermissions scalar-or-map pattern (or extend actions.Expression) to runs-on, needs, concurrency, environment, container; make strategy/services/defaults a named map[string]Expression matching how Env/With/Secrets already work. This removes both manual type switches in parse.go. Effort: 4-6h. Benefit: compiler-checked exhaustiveness, no runtime assertions, less drift risk between the string-based and AST-based Job types.

Cluster 2 (Medium): runtimeImportReference near-duplicate — pkg/parser/frontmatter_hash.go and pkg/workflow/runtime_import_validation.go each define a private runtimeImportReference (path/importPath string, startLine int, endLine int). Move one definition into a shared package. Effort: 1h.

Cluster 3 (Medium, correctness-relevant): graderManifestEntry writer/reader pair — pkg/workflow/compiler_yaml_graders.go (writer, 8 fields) and pkg/cli/audit_report_graders.go (reader, 5-field subset) both declare graderManifestEntry for the same on-disk manifest format. Since this is a serialization contract, letting the reader silently drift from the writer is a real risk. Move the shared 5-field subset into one type and have the writer embed/extend it. Effort: 1-2h.

Cluster 4 (Low, informational): three incompatible Finding types in pkg/scanfindings, pkg/workflow/gradershell, pkg/workflow/taint — different subsystems, probably should stay separate; flagging so a 4th does not appear without considering a shared RuleID/Message base (as already done for types.BaseMCPServerConfig).

Cluster 5 (Low, informational): JobInfo vs JobData in pkg/cli — looks like an intentional API-model vs view-model split; flagging in case a converter between them was meant to exist.

Untyped Usages

Stats: legacy interface{} in production code: 0. map[string]any appears in 542 non-test files (pkg/workflow 351, pkg/cli 150, pkg/parser 22, pkg/workqueue 16). []any appears in 218 non-test files. Untyped numeric constants worth a semantic rename: 2 of roughly 60 surveyed (most others already encode their unit in the name and need no change).

Much of the any/map[string]any volume is legitimate for a YAML compiler handling arbitrary user frontmatter. Two spots look like missed opportunities rather than inherent dynamism:

Category 1 (High): WorkflowData carries a dozen untyped map fields — WorkflowData (pkg/workflow/workflow_data.go:38) is the compiler central struct, threaded through most of the 351 pkg/workflow files touching map[string]any. Notable fields: Features (line 170, bool-or-string flags, could be map[string]FeatureValue), Runtimes (167, could be map[string]RuntimeOverride), Jobs (148, could reuse the actions.Job type instead of a bare map), ModelCosts (224, documented providers structure, could be a ModelPricingConfig struct), Tools (96, could switch to the MapToolConfig named type that already exists at pkg/workflow/mcp_config_types.go:70 instead of a second bare map). Start with Tools/Features/Jobs for best ROI. Effort: 1-2h per field.

Category 2 (Low): two unit-less numeric constants — pkg/constants/constants.go:336 DefaultMCPGatewayPayloadSizeThreshold = 524288 (bytes, unit only in a comment) and pkg/workflow/publish_code_coverage.go:18 defaultCodeCoverageWaitForProcessingTimeout = 160 (seconds, unit only in a comment). Rename to include the unit (...Bytes / ...Seconds) for consistency with the rest of the codebase. Effort: 15min.

Recommendations Priority

1. (High, 4-6h) Unify the GitHub Actions job any-fields (Cluster 1); delete the manual type switches in parse.go.
2. (Medium, 2-3h combined) Consolidate runtimeImportReference and graderManifestEntry.
3. (Low, 1-2h per field) Type WorkflowData.Tools/Features/Jobs incrementally; leave the rest as map[string]any.
4. (Trivial, 15min) Rename the two unit-less constants.

Implementation Checklist

• Extend the scalar-or-map union pattern from permissions to runs-on/needs/concurrency/environment/container
• Remove the manual type switches in pkg/workflow/actions/parse.go (lines 160, 175)
• Consolidate runtimeImportReference into one shared type
• Consolidate graderManifestEntry into one shared type
• Switch WorkflowData.Tools to the existing MapToolConfig named type
• Rename the two unit-less constants to include their unit
• Run make test-unit after each change

Analysis Metadata

Files analyzed: 1,658 (non-test, under pkg/). Types analyzed: 1,739. Actionable duplicate clusters: 5. map[string]any files: 542. []any files: 218. Legacy interface{} in production code: 0. Detection method: grep/pattern-based structural analysis plus direct code reading. Note: Serena Go semantic analysis (gopls) was unavailable in this environment (gopls is not installed), so get_symbols_overview/find_referencing_symbols calls failed; all file/line citations were verified by direct inspection, but call-site reference counts should be treated as indicative, not exhaustive. Analysis date: 2026-10-19.

Generated by ✍️ Typist - Go Type Analysis · claude · agent · 463.1 AIC · ⌖ 0.983 AIC · ⊞ 6.7K · ◷

• expires on Oct 20, 2026, 3:47 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-10-20T11:47:27.274Z.

Closed by Workflow