feat(style): add max-run-lines setting to detect long inline scripts (#11)

Author: reugn

docs/configuration/linters.md

@@ -99,6 +99,7 @@ linters:
       naming-convention: ""     # "title", "sentence", or ""
       checkout-first: false     # Check if checkout is first step
       require-step-names: false # Require all steps to have names
+      max-run-lines: 0          # Max lines in run scripts (0 = disabled)
 ```
 
 | Setting | Default | Description |
@@ -108,6 +109,7 @@ linters:
 | `naming-convention` | `""` | `"title"` (Every Word Uppercase), `"sentence"` (First word only), or `""` (none) |
 | `checkout-first` | `false` | Warn if checkout is not first step |
 | `require-step-names` | `false` | Require all steps to have names |
+| `max-run-lines` | `0` | Max lines in run scripts (0 = disabled) |
 
 ## Examples
 

docs/linters/style.md

@@ -29,6 +29,7 @@ Consistent styling:
 | **Name not first** | `name:` field not first in step definition |
 | **Checkout not first** | `actions/checkout` not the first step (optional) |
 | **Env shadowing** | Job-level env var shadows workflow-level env var |
+| **Run script too long** | Run script exceeds max lines (opt-in via `max-run-lines`) |
 
 ## Example Output
 
@@ -38,6 +39,7 @@ ci.yml:5: (style) Job 'j1' has cryptic ID and is missing a name
 ci.yml:10: (style) Step is missing a name
 ci.yml:15: (style) Step 'name' should come first before other fields
 ci.yml:8: (style) Job env var 'NODE_ENV' shadows workflow-level env var
+ci.yml:20: (style) Run script has 15 lines (max 10); consider extracting to a script file
 ```
 
 ## Auto-fix
@@ -57,6 +59,7 @@ linters:
       naming-convention: ""     # "title", "sentence", or "" (default: none)
       checkout-first: false     # Check checkout is first step (default: false)
       require-step-names: false # Require all steps to have names (default: false)
+      max-run-lines: 0          # Max lines in run scripts (default: 0 = disabled)
 ```
 
 ### min-name-length
@@ -120,6 +123,17 @@ When enabled, requires all steps to have explicit `name:` fields.
 
 Simple steps like `- run: go build` often don't need names. Enable this for stricter naming policies.
 
+### max-run-lines
+
+Maximum allowed lines in a `run:` script before suggesting extraction to a script file.
+
+| Value | Description |
+|-------|-------------|
+| `0` | Disabled (default) - no limit on run script length |
+| `10` | Warn if run script exceeds 10 lines |
+
+Long inline scripts are harder to maintain and test. Consider extracting them to a script file (e.g., `scripts/build.sh`) called from the workflow.
+
 ## Cryptic Job ID Detection
 
 A job ID is considered "cryptic" if it:
@@ -222,8 +236,38 @@ name: build and test
 name: Build And Test
 ```
 
+### Long Run Scripts
+
+```yaml
+# With max-run-lines: 10
+linters:
+  settings:
+    style:
+      max-run-lines: 10
+```
+
+```yaml
+# Bad - inline script is too long
+- name: Build and Deploy
+  run: |
+    npm install
+    npm run build
+    npm run test
+    docker build -t myapp .
+    docker push myapp
+    kubectl apply -f deploy.yaml
+    kubectl rollout status deployment/myapp
+    curl -X POST https://notify.example.com
+    echo "Done deploying"
+    ./cleanup.sh
+    # ... more lines
+
+# Good - extract to script file
+- name: Build and Deploy
+  run: ./scripts/build-and-deploy.sh
+```
+
 ## See Also
 
 - [Linters Configuration](../configuration/linters) - Configure style settings
 - [format](format) - For formatting checks (indentation, line length)
-

docs/usage/init.md

@@ -113,6 +113,7 @@ linters:
       naming-convention: ""
       checkout-first: false
       require-step-names: false
+      max-run-lines: 0
 
 upgrade:
   version: tag

internal/config/style_settings.go

@@ -3,6 +3,7 @@ package config
 const (
 	defaultMinNameLength = 3
 	defaultMaxNameLength = 50
+	defaultMaxRunLines   = 0 // 0 means disabled
 )
 
 // StyleSettings contains settings for the style linter.
@@ -20,13 +21,16 @@ type StyleSettings struct {
 	CheckoutFirst bool `yaml:"checkout-first"`
 	// RequireStepNames requires all steps to have explicit names
 	RequireStepNames bool `yaml:"require-step-names"`
+	// MaxRunLines is the maximum allowed lines in a run script (0 = disabled)
+	MaxRunLines int `yaml:"max-run-lines"`
 }
 
 // DefaultStyleSettings returns the default style linter settings.
 func DefaultStyleSettings() *StyleSettings {
 	return &StyleSettings{
 		MinNameLength: defaultMinNameLength,
 		MaxNameLength: defaultMaxNameLength,
+		MaxRunLines:   defaultMaxRunLines,
 	}
 }
 

internal/linter/style_linter.go

@@ -160,6 +160,11 @@ func (l *StyleLinter) checkSteps(wf *workflow.Workflow, job map[string]any, file
 		if issue := l.checkNameFirst(lines, stepLine, file); issue != nil {
 			issues = append(issues, issue)
 		}
+
+		// Check run script length
+		if issue := l.checkRunLength(step, file, stepLine); issue != nil {
+			issues = append(issues, issue)
+		}
 	}
 
 	return issues
@@ -283,6 +288,27 @@ func (l *StyleLinter) checkNameFirst(lines []string, stepLine int, file string)
 	return nil
 }
 
+// checkRunLength checks if a run script exceeds the maximum line count.
+func (l *StyleLinter) checkRunLength(step map[string]any, file string, line int) *Issue {
+	if l.settings.MaxRunLines <= 0 {
+		return nil
+	}
+
+	runScript, ok := step["run"].(string)
+	if !ok || runScript == "" {
+		return nil
+	}
+
+	lineCount := strings.Count(strings.TrimSpace(runScript), "\n") + 1
+	if lineCount > l.settings.MaxRunLines {
+		msg := fmt.Sprintf("Run script has %d lines (max %d); consider extracting to a script file",
+			lineCount, l.settings.MaxRunLines)
+		return newIssue(file, line, msg)
+	}
+
+	return nil
+}
+
 // extractJobEnv extracts env variable names from a job map.
 func extractJobEnv(job map[string]any) map[string]bool {
 	result := make(map[string]bool)

internal/linter/style_linter_test.go

@@ -1,6 +1,7 @@
 package linter
 
 import (
+	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
@@ -842,3 +843,123 @@ jobs:
 		t.Error("Expected to find 'Job name too short' issue")
 	}
 }
+
+func TestStyleLinter_RunScriptLength(t *testing.T) {
+	tests := []struct {
+		name        string
+		maxLines    int
+		runScript   string
+		wantFlagged bool
+	}{
+		{
+			name:        "too long",
+			maxLines:    5,
+			runScript:   "echo 1\necho 2\necho 3\necho 4\necho 5\necho 6",
+			wantFlagged: true,
+		},
+		{
+			name:        "within limit",
+			maxLines:    5,
+			runScript:   "echo 1\necho 2\necho 3",
+			wantFlagged: false,
+		},
+		{
+			name:        "check disabled",
+			maxLines:    0,
+			runScript:   "echo 1\necho 2\necho 3\necho 4\necho 5\necho 6\necho 7\necho 8\necho 9\necho 10",
+			wantFlagged: false,
+		},
+		{
+			name:        "single line",
+			maxLines:    1,
+			runScript:   "echo hello",
+			wantFlagged: false,
+		},
+		{
+			name:        "exact boundary",
+			maxLines:    5,
+			runScript:   "echo 1\necho 2\necho 3\necho 4\necho 5",
+			wantFlagged: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tmpDir := t.TempDir()
+			workflowPath := filepath.Join(tmpDir, "test.yml")
+
+			content := fmt.Sprintf(`name: Test Workflow
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Test Step
+        run: |
+          %s
+`, strings.ReplaceAll(tt.runScript, "\n", "\n          "))
+
+			if err := os.WriteFile(workflowPath, []byte(content), 0600); err != nil {
+				t.Fatalf("Failed to write test workflow: %v", err)
+			}
+
+			wf, err := workflow.LoadWorkflow(workflowPath)
+			if err != nil {
+				t.Fatalf("LoadWorkflow() error = %v", err)
+			}
+
+			linter := NewStyleLinter(&config.StyleSettings{MaxRunLines: tt.maxLines})
+			issues, err := linter.LintWorkflow(wf)
+			if err != nil {
+				t.Fatalf("LintWorkflow() error = %v", err)
+			}
+
+			found := false
+			for _, issue := range issues {
+				if strings.Contains(issue.Message, "Run script has") {
+					found = true
+					break
+				}
+			}
+
+			if found != tt.wantFlagged {
+				t.Errorf("got flagged=%v, want flagged=%v", found, tt.wantFlagged)
+			}
+		})
+	}
+}
+
+func TestStyleLinter_RunScriptStepWithUsesOnly(t *testing.T) {
+	tmpDir := t.TempDir()
+	workflowPath := filepath.Join(tmpDir, "test.yml")
+
+	content := `name: Test Workflow
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+`
+	if err := os.WriteFile(workflowPath, []byte(content), 0600); err != nil {
+		t.Fatalf("Failed to write test workflow: %v", err)
+	}
+
+	wf, err := workflow.LoadWorkflow(workflowPath)
+	if err != nil {
+		t.Fatalf("LoadWorkflow() error = %v", err)
+	}
+
+	linter := NewStyleLinter(&config.StyleSettings{MaxRunLines: 1})
+	issues, err := linter.LintWorkflow(wf)
+	if err != nil {
+		t.Fatalf("LintWorkflow() error = %v", err)
+	}
+
+	for _, issue := range issues {
+		if strings.Contains(issue.Message, "Run script has") {
+			t.Error("Did not expect 'uses' step to trigger run script check")
+		}
+	}
+}