From 65cd1b9e01e0ad2d6f77b3c80b6450afb93d907d Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Fri, 3 Apr 2026 13:18:36 +0000
Subject: [PATCH] refactor(ansible): clarify CLI helper naming

Co-Authored-By: Virgil <virgil@lethean.io>
---
 cmd/ansible/ansible.go      | 20 +++++++++++---------
 cmd/ansible/ansible_test.go |  4 ++--
 2 files changed, 13 insertions(+), 11 deletions(-)

diff --git a/cmd/ansible/ansible.go b/cmd/ansible/ansible.go
index 2aebe69..2282a17 100644
--- a/cmd/ansible/ansible.go
+++ b/cmd/ansible/ansible.go
@@ -15,7 +15,7 @@ import (
 	"gopkg.in/yaml.v3"
 )
 
-type playbookCommandSettings struct {
+type playbookCommandOptions struct {
 	playbookPath string
 	basePath     string
 	limit        string
@@ -280,18 +280,20 @@ func parseExtraVarsScalar(value string) any {
 	return value
 }
 
-// resolveTestSSHKeyFile resolves the SSH key flag used by the ansible test subcommand.
-func resolveTestSSHKeyFile(opts core.Options) string {
+// Example:
+//
+//	core ansible test server.example.com -i ~/.ssh/id_ed25519
+func resolveSSHTestKeyFile(opts core.Options) string {
 	if key := opts.String("key"); key != "" {
 		return key
 	}
 	return opts.String("i")
 }
 
-func buildPlaybookCommandSettings(opts core.Options, rawArgs []string) (playbookCommandSettings, error) {
+func buildPlaybookCommandSettings(opts core.Options, rawArgs []string) (playbookCommandOptions, error) {
 	positional := positionalArgs(opts)
 	if len(positional) < 1 {
-		return playbookCommandSettings{}, coreerr.E("buildPlaybookCommandSettings", "usage: ansible <playbook>", nil)
+		return playbookCommandOptions{}, coreerr.E("buildPlaybookCommandSettings", "usage: ansible <playbook>", nil)
 	}
 	playbookPath := positional[0]
 
@@ -300,15 +302,15 @@ func buildPlaybookCommandSettings(opts core.Options, rawArgs []string) (playbook
 	}
 
 	if !coreio.Local.Exists(playbookPath) {
-		return playbookCommandSettings{}, coreerr.E("buildPlaybookCommandSettings", sprintf("playbook not found: %s", playbookPath), nil)
+		return playbookCommandOptions{}, coreerr.E("buildPlaybookCommandSettings", sprintf("playbook not found: %s", playbookPath), nil)
 	}
 
 	vars, err := extraVars(opts)
 	if err != nil {
-		return playbookCommandSettings{}, coreerr.E("buildPlaybookCommandSettings", "parse extra vars", err)
+		return playbookCommandOptions{}, coreerr.E("buildPlaybookCommandSettings", "parse extra vars", err)
 	}
 
-	return playbookCommandSettings{
+	return playbookCommandOptions{
 		playbookPath: playbookPath,
 		basePath:     pathDir(playbookPath),
 		limit:        joinedStringOption(opts, "limit", "l"),
@@ -473,7 +475,7 @@ func runSSHTestCommand(opts core.Options) core.Result {
 		Port:     opts.Int("port"),
 		User:     firstStringOption(opts, "user", "u"),
 		Password: opts.String("password"),
-		KeyFile:  resolveTestSSHKeyFile(opts),
+		KeyFile:  resolveSSHTestKeyFile(opts),
 		Timeout:  30 * time.Second,
 	}
 
diff --git a/cmd/ansible/ansible_test.go b/cmd/ansible/ansible_test.go
index 2e43558..34a958c 100644
--- a/cmd/ansible/ansible_test.go
+++ b/cmd/ansible/ansible_test.go
@@ -253,7 +253,7 @@ func TestTestKeyFile_Good_PrefersExplicitKey(t *testing.T) {
 		core.Option{Key: "i", Value: "/tmp/ignored"},
 	)
 
-	assert.Equal(t, "/tmp/id_ed25519", resolveTestSSHKeyFile(opts))
+	assert.Equal(t, "/tmp/id_ed25519", resolveSSHTestKeyFile(opts))
 }
 
 func TestTestKeyFile_Good_FallsBackToShortAlias(t *testing.T) {
@@ -261,7 +261,7 @@ func TestTestKeyFile_Good_FallsBackToShortAlias(t *testing.T) {
 		core.Option{Key: "i", Value: "/tmp/id_ed25519"},
 	)
 
-	assert.Equal(t, "/tmp/id_ed25519", resolveTestSSHKeyFile(opts))
+	assert.Equal(t, "/tmp/id_ed25519", resolveSSHTestKeyFile(opts))
 }
 
 func TestFirstString_Good_ResolvesShortUserAlias(t *testing.T) {