From 7eb76da40aa50d0221e5515a6cbba393d1b87bd3 Mon Sep 17 00:00:00 2001 From: Kynan Ware <47394200+BagToad@users.noreply.github.com> Date: Wed, 4 Mar 2026 16:08:03 -0700 Subject: [PATCH] Add godoc comments to exported symbols in pkg/cmd/workflow Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- pkg/cmd/workflow/disable/disable.go | 2 ++ pkg/cmd/workflow/enable/enable.go | 2 ++ pkg/cmd/workflow/list/list.go | 2 ++ pkg/cmd/workflow/run/run.go | 5 +++++ pkg/cmd/workflow/shared/shared.go | 18 ++++++++++++++++-- pkg/cmd/workflow/shared/test.go | 9 +++++++++ pkg/cmd/workflow/view/view.go | 2 ++ pkg/cmd/workflow/workflow.go | 1 + 8 files changed, 39 insertions(+), 2 deletions(-) diff --git a/pkg/cmd/workflow/disable/disable.go b/pkg/cmd/workflow/disable/disable.go index 8b2fb62d3..cd00f6881 100644 --- a/pkg/cmd/workflow/disable/disable.go +++ b/pkg/cmd/workflow/disable/disable.go @@ -13,6 +13,7 @@ import ( "github.com/spf13/cobra" ) +// DisableOptions holds the options for the disable workflow command. type DisableOptions struct { HttpClient func() (*http.Client, error) IO *iostreams.IOStreams @@ -27,6 +28,7 @@ type iprompter interface { Select(string, string, []string) (int, error) } +// NewCmdDisable creates a new cobra command for disabling a workflow. func NewCmdDisable(f *cmdutil.Factory, runF func(*DisableOptions) error) *cobra.Command { opts := &DisableOptions{ IO: f.IOStreams, diff --git a/pkg/cmd/workflow/enable/enable.go b/pkg/cmd/workflow/enable/enable.go index 93e8ac007..f74dd6e46 100644 --- a/pkg/cmd/workflow/enable/enable.go +++ b/pkg/cmd/workflow/enable/enable.go @@ -13,6 +13,7 @@ import ( "github.com/spf13/cobra" ) +// EnableOptions holds the options for the enable workflow command. type EnableOptions struct { HttpClient func() (*http.Client, error) IO *iostreams.IOStreams @@ -27,6 +28,7 @@ type iprompter interface { Select(string, string, []string) (int, error) } +// NewCmdEnable creates a new cobra command for enabling a workflow. func NewCmdEnable(f *cmdutil.Factory, runF func(*EnableOptions) error) *cobra.Command { opts := &EnableOptions{ IO: f.IOStreams, diff --git a/pkg/cmd/workflow/list/list.go b/pkg/cmd/workflow/list/list.go index efedc731e..9360269a5 100644 --- a/pkg/cmd/workflow/list/list.go +++ b/pkg/cmd/workflow/list/list.go @@ -15,6 +15,7 @@ import ( const defaultLimit = 50 +// ListOptions holds the options for the list workflows command. type ListOptions struct { IO *iostreams.IOStreams HttpClient func() (*http.Client, error) @@ -32,6 +33,7 @@ var workflowFields = []string{ "state", } +// NewCmdList creates a new cobra command for listing workflows. func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Command { opts := &ListOptions{ IO: f.IOStreams, diff --git a/pkg/cmd/workflow/run/run.go b/pkg/cmd/workflow/run/run.go index 386227bf1..b4259e2ac 100644 --- a/pkg/cmd/workflow/run/run.go +++ b/pkg/cmd/workflow/run/run.go @@ -24,6 +24,7 @@ import ( "gopkg.in/yaml.v3" ) +// RunOptions holds the options for the run workflow command. type RunOptions struct { HttpClient func() (*http.Client, error) IO *iostreams.IOStreams @@ -47,6 +48,7 @@ type iprompter interface { Select(string, string, []string) (int, error) } +// NewCmdRun creates a new cobra command for running a workflow. func NewCmdRun(f *cmdutil.Factory, runF func(*RunOptions) error) *cobra.Command { opts := &RunOptions{ IO: f.IOStreams, @@ -190,10 +192,12 @@ func parseFields(opts RunOptions) (map[string]string, error) { return params, nil } +// InputAnswer collects user-provided input values for workflow dispatch. type InputAnswer struct { providedInputs map[string]string } +// WriteAnswer stores a single input value by name into the answer map. func (ia *InputAnswer) WriteAnswer(name string, value interface{}) error { if s, ok := value.(string); ok { ia.providedInputs[name] = s @@ -390,6 +394,7 @@ func runRun(opts *RunOptions) error { return nil } +// WorkflowInput describes a single input parameter defined in a workflow file. type WorkflowInput struct { Name string Required bool diff --git a/pkg/cmd/workflow/shared/shared.go b/pkg/cmd/workflow/shared/shared.go index 04b5fa199..4db7b6d64 100644 --- a/pkg/cmd/workflow/shared/shared.go +++ b/pkg/cmd/workflow/shared/shared.go @@ -20,8 +20,11 @@ import ( ) const ( - Active WorkflowState = "active" - DisabledManually WorkflowState = "disabled_manually" + // Active represents an enabled workflow state. + Active WorkflowState = "active" + // DisabledManually represents a workflow disabled by a user. + DisabledManually WorkflowState = "disabled_manually" + // DisabledInactivity represents a workflow disabled due to inactivity. DisabledInactivity WorkflowState = "disabled_inactivity" ) @@ -29,8 +32,10 @@ type iprompter interface { Select(string, string, []string) (int, error) } +// WorkflowState represents the state of a GitHub Actions workflow. type WorkflowState string +// Workflow represents a GitHub Actions workflow. type Workflow struct { Name string ID int64 @@ -38,22 +43,27 @@ type Workflow struct { State WorkflowState } +// WorkflowsPayload is the response payload for listing workflows from the API. type WorkflowsPayload struct { Workflows []Workflow } +// Disabled reports whether the workflow is in a disabled state. func (w *Workflow) Disabled() bool { return w.State != Active } +// Base returns the file name component of the workflow path. func (w *Workflow) Base() string { return path.Base(w.Path) } +// ExportData returns the workflow fields as a map for structured output. func (w *Workflow) ExportData(fields []string) map[string]interface{} { return cmdutil.StructExportData(w, fields) } +// GetWorkflows fetches workflows for a repository, up to the given limit (0 for all). func GetWorkflows(client *api.Client, repo ghrepo.Interface, limit int) ([]Workflow, error) { perPage := limit page := 1 @@ -93,6 +103,7 @@ func GetWorkflows(client *api.Client, repo ghrepo.Interface, limit int) ([]Workf return workflows, nil } +// FilteredAllError indicates that all workflows were filtered out during selection. type FilteredAllError struct { error } @@ -146,6 +157,7 @@ func FindWorkflow(client *api.Client, repo ghrepo.Interface, workflowSelector st return getWorkflowsByName(client, repo, workflowSelector, states) } +// GetWorkflow fetches a single workflow by its database ID. func GetWorkflow(client *api.Client, repo ghrepo.Interface, workflowID int64) (*Workflow, error) { return getWorkflowByID(client, repo, strconv.FormatInt(workflowID, 10)) } @@ -189,6 +201,7 @@ func getWorkflowsByName(client *api.Client, repo ghrepo.Interface, name string, return filtered, nil } +// ResolveWorkflow finds a workflow by selector or prompts the user to choose one. func ResolveWorkflow(p iprompter, io *iostreams.IOStreams, client *api.Client, repo ghrepo.Interface, prompt bool, workflowSelector string, states []WorkflowState) (*Workflow, error) { if prompt { workflows, err := GetWorkflows(client, repo, 0) @@ -232,6 +245,7 @@ func ResolveWorkflow(p iprompter, io *iostreams.IOStreams, client *api.Client, r return selectWorkflow(p, workflows, "Which workflow do you mean?", states) } +// GetWorkflowContent retrieves and decodes the YAML content of a workflow file. func GetWorkflowContent(client *api.Client, repo ghrepo.Interface, workflow Workflow, ref string) ([]byte, error) { path := fmt.Sprintf("repos/%s/contents/%s", ghrepo.FullName(repo), workflow.Path) if ref != "" { diff --git a/pkg/cmd/workflow/shared/test.go b/pkg/cmd/workflow/shared/test.go index dab67394f..18bbd01c6 100644 --- a/pkg/cmd/workflow/shared/test.go +++ b/pkg/cmd/workflow/shared/test.go @@ -1,13 +1,16 @@ package shared +// AWorkflow is a test fixture representing an active workflow. var AWorkflow = Workflow{ Name: "a workflow", ID: 123, Path: ".github/workflows/flow.yml", State: Active, } +// AWorkflowContent is a test fixture with base64-encoded content for AWorkflow. var AWorkflowContent = `{"content":"bmFtZTogYSB3b3JrZmxvdwo="}` +// DisabledWorkflow is a test fixture representing a manually disabled workflow. var DisabledWorkflow = Workflow{ Name: "a disabled workflow", ID: 456, @@ -15,6 +18,7 @@ var DisabledWorkflow = Workflow{ State: DisabledManually, } +// DisabledInactivityWorkflow is a test fixture representing a workflow disabled due to inactivity. var DisabledInactivityWorkflow = Workflow{ Name: "a disabled inactivity workflow", ID: 1206, @@ -22,6 +26,7 @@ var DisabledInactivityWorkflow = Workflow{ State: DisabledInactivity, } +// AnotherDisabledWorkflow is a test fixture representing a second manually disabled workflow. var AnotherDisabledWorkflow = Workflow{ Name: "a disabled workflow", ID: 1213, @@ -29,6 +34,7 @@ var AnotherDisabledWorkflow = Workflow{ State: DisabledManually, } +// UniqueDisabledWorkflow is a test fixture representing a disabled workflow with a unique name. var UniqueDisabledWorkflow = Workflow{ Name: "terrible workflow", ID: 1314, @@ -36,14 +42,17 @@ var UniqueDisabledWorkflow = Workflow{ State: DisabledManually, } +// AnotherWorkflow is a test fixture representing a second active workflow. var AnotherWorkflow = Workflow{ Name: "another workflow", ID: 789, Path: ".github/workflows/another.yml", State: Active, } +// AnotherWorkflowContent is a test fixture with base64-encoded content for AnotherWorkflow. var AnotherWorkflowContent = `{"content":"bmFtZTogYW5vdGhlciB3b3JrZmxvdwo="}` +// YetAnotherWorkflow is a test fixture representing a third active workflow with a duplicate name. var YetAnotherWorkflow = Workflow{ Name: "another workflow", ID: 1011, diff --git a/pkg/cmd/workflow/view/view.go b/pkg/cmd/workflow/view/view.go index 2e550f496..9a0e1a0ce 100644 --- a/pkg/cmd/workflow/view/view.go +++ b/pkg/cmd/workflow/view/view.go @@ -21,6 +21,7 @@ import ( "github.com/spf13/cobra" ) +// ViewOptions holds the options for the view workflow command. type ViewOptions struct { HttpClient func() (*http.Client, error) IO *iostreams.IOStreams @@ -42,6 +43,7 @@ type iprompter interface { Select(string, string, []string) (int, error) } +// NewCmdView creates a new cobra command for viewing a workflow. func NewCmdView(f *cmdutil.Factory, runF func(*ViewOptions) error) *cobra.Command { opts := &ViewOptions{ IO: f.IOStreams, diff --git a/pkg/cmd/workflow/workflow.go b/pkg/cmd/workflow/workflow.go index ccdb7d34a..e6e578b1e 100644 --- a/pkg/cmd/workflow/workflow.go +++ b/pkg/cmd/workflow/workflow.go @@ -10,6 +10,7 @@ import ( "github.com/spf13/cobra" ) +// NewCmdWorkflow creates the top-level workflow command for GitHub Actions. func NewCmdWorkflow(f *cmdutil.Factory) *cobra.Command { cmd := &cobra.Command{ Use: "workflow ",