test: add tests for package level actions doc (#335)

* test: add tests for package level actions doc

Signed-off-by: Felipe Zipitria <felipe.zipitria@owasp.org>

* Update content/docs/seclang/actions.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* fix: remove empty line

Signed-off-by: Felipe Zipitria <felipe.zipitria@owasp.org>

---------

Signed-off-by: Felipe Zipitria <felipe.zipitria@owasp.org>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: fzipi

content/docs/seclang/actions.md

@@ -3,7 +3,7 @@ title: "Actions"
 description: "Actions available in Coraza"
 lead: "The action of a rule defines how to handle HTTP requests that have matched one or more rule conditions."
 date: 2020-10-06T08:48:57+00:00
-lastmod: "2026-01-15T14:26:37-03:00"
+lastmod: "2026-01-15T16:50:59-03:00"
 draft: false
 images: []
 menu:
@@ -28,7 +28,6 @@ Disruptive actions will NOT be executed if the `SecRuleEngine` is set to `Detect
 * **Meta-data actions** - used to provide more information about rules. Examples include id, rev, severity and msg.
 * **Data actions** - Not really actions, these are mere containers that hold data used by other actions. For example, the status action holds the status that will be used for blocking (if it takes place).
 
-
 ## allow
 
 **Description**: Stops rule processing on a successful match and allows a transaction to be proceed.allow will affect the entire transaction.

tools/actionsgen/main.go

@@ -23,6 +23,7 @@ import (
 
 type Page struct {
 	LastModification string
+	PackageDescription string
 	Actions          []Action
 }
 
@@ -78,6 +79,7 @@ func main() {
 
 	page := Page{
 		LastModification: time.Now().Format(time.RFC3339),
+		PackageDescription: getPackageDescription(root),
 	}
 
 	for _, file := range files {
@@ -217,3 +219,56 @@ func parseAction(name string, doc string) Action {
 	}
 	return d
 }
+
+// getPackageDescription extracts package-level documentation from the actions package.
+// It looks for doc.go first, then falls back to actions.go or any other .go file.
+func getPackageDescription(pkgPath string) string {
+	// Try to find doc.go first
+	docFile := filepath.Join(pkgPath, "doc.go")
+	if desc := extractPackageDoc(docFile); desc != "" {
+		return desc
+	}
+
+	// Fall back to actions.go
+	actionsFile := filepath.Join(pkgPath, "actions.go")
+	if desc := extractPackageDoc(actionsFile); desc != "" {
+		return desc
+	}
+
+	// Try any .go file in the package
+	files, err := filepath.Glob(filepath.Join(pkgPath, "*.go"))
+	if err != nil {
+		return ""
+	}
+
+	for _, file := range files {
+		if strings.HasSuffix(file, "_test.go") {
+			continue
+		}
+		if desc := extractPackageDoc(file); desc != "" {
+			return desc
+		}
+	}
+
+	return ""
+}
+
+// extractPackageDoc extracts package documentation from a specific Go file.
+func extractPackageDoc(filePath string) string {
+	src, err := os.ReadFile(filePath)
+	if err != nil {
+		return ""
+	}
+
+	fSet := token.NewFileSet()
+	f, err := parser.ParseFile(fSet, filePath, src, parser.ParseComments)
+	if err != nil {
+		return ""
+	}
+
+	if f.Doc != nil {
+		return strings.TrimSpace(f.Doc.Text())
+	}
+
+	return ""
+}

tools/actionsgen/main_test.go

@@ -270,3 +270,181 @@ type NewActionFn struct{}
 		})
 	}
 }
+
+func TestExtractPackageDoc(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	tests := map[string]struct {
+		fileContent string
+		expected    string
+	}{
+		"package with doc comment": {
+			fileContent: `// Package actions provides implementations for various ModSecurity actions.
+// This is a multi-line package comment.
+package actions`,
+			expected: "Package actions provides implementations for various ModSecurity actions.\nThis is a multi-line package comment.",
+		},
+		"package without doc comment": {
+			fileContent: `package actions
+
+type SomeFn struct{}`,
+			expected: "",
+		},
+		"package with single line doc": {
+			fileContent: `// Package actions provides action implementations.
+package actions`,
+			expected: "Package actions provides action implementations.",
+		},
+		"package with whitespace in doc": {
+			fileContent: `// Package actions provides action implementations.
+//
+// This package contains various actions.
+package actions`,
+			expected: "Package actions provides action implementations.\n\nThis package contains various actions.",
+		},
+	}
+
+	for name, test := range tests {
+		t.Run(name, func(t *testing.T) {
+			testFile := filepath.Join(tmpDir, strings.ReplaceAll(t.Name(), "/", "_")+".go")
+			err := os.WriteFile(testFile, []byte(test.fileContent), 0644)
+			if err != nil {
+				t.Fatalf("Failed to create test file: %v", err)
+			}
+
+			result := extractPackageDoc(testFile)
+			if result != test.expected {
+				t.Errorf("want %q, got %q", test.expected, result)
+			}
+		})
+	}
+}
+
+func TestExtractPackageDocFileNotFound(t *testing.T) {
+	result := extractPackageDoc("/nonexistent/file.go")
+	if result != "" {
+		t.Errorf("Expected empty string for non-existent file, got %q", result)
+	}
+}
+
+func TestGetPackageDescription(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	tests := map[string]struct {
+		setup    func(string) error
+		expected string
+	}{
+		"finds doc.go first": {
+			setup: func(dir string) error {
+				docGo := `// Package actions from doc.go
+package actions`
+				actionsGo := `// Package actions from actions.go
+package actions`
+				otherGo := `// Package actions from other.go
+package actions`
+
+				if err := os.WriteFile(filepath.Join(dir, "doc.go"), []byte(docGo), 0644); err != nil {
+					return err
+				}
+				if err := os.WriteFile(filepath.Join(dir, "actions.go"), []byte(actionsGo), 0644); err != nil {
+					return err
+				}
+				return os.WriteFile(filepath.Join(dir, "other.go"), []byte(otherGo), 0644)
+			},
+			expected: "Package actions from doc.go",
+		},
+		"falls back to actions.go if no doc.go": {
+			setup: func(dir string) error {
+				actionsGo := `// Package actions from actions.go
+package actions`
+				otherGo := `// Package actions from other.go
+package actions`
+
+				if err := os.WriteFile(filepath.Join(dir, "actions.go"), []byte(actionsGo), 0644); err != nil {
+					return err
+				}
+				return os.WriteFile(filepath.Join(dir, "other.go"), []byte(otherGo), 0644)
+			},
+			expected: "Package actions from actions.go",
+		},
+		"finds any go file if no doc.go or actions.go": {
+			setup: func(dir string) error {
+				otherGo := `// Package actions from other.go
+package actions`
+				return os.WriteFile(filepath.Join(dir, "other.go"), []byte(otherGo), 0644)
+			},
+			expected: "Package actions from other.go",
+		},
+		"skips test files": {
+			setup: func(dir string) error {
+				testGo := `// Package actions from test file
+package actions`
+				otherGo := `// Package actions from regular file
+package actions`
+
+				if err := os.WriteFile(filepath.Join(dir, "actions_test.go"), []byte(testGo), 0644); err != nil {
+					return err
+				}
+				return os.WriteFile(filepath.Join(dir, "other.go"), []byte(otherGo), 0644)
+			},
+			expected: "Package actions from regular file",
+		},
+		"returns empty string if no package doc found": {
+			setup: func(dir string) error {
+				noDocGo := `package actions
+
+type SomeFn struct{}`
+				return os.WriteFile(filepath.Join(dir, "nodoc.go"), []byte(noDocGo), 0644)
+			},
+			expected: "",
+		},
+		"returns empty string for empty directory": {
+			setup: func(dir string) error {
+				return nil
+			},
+			expected: "",
+		},
+		"handles files without package doc gracefully": {
+			setup: func(dir string) error {
+				file1 := `package actions
+
+type SomeFn struct{}`
+				file2 := `// Package actions has documentation
+package actions`
+
+				if err := os.WriteFile(filepath.Join(dir, "file1.go"), []byte(file1), 0644); err != nil {
+					return err
+				}
+				return os.WriteFile(filepath.Join(dir, "file2.go"), []byte(file2), 0644)
+			},
+			expected: "Package actions has documentation",
+		},
+	}
+
+	for name, test := range tests {
+		t.Run(name, func(t *testing.T) {
+			testDir := filepath.Join(tmpDir, strings.ReplaceAll(t.Name(), "/", "_"))
+			err := os.MkdirAll(testDir, 0755)
+			if err != nil {
+				t.Fatalf("Failed to create test directory: %v", err)
+			}
+
+			err = test.setup(testDir)
+			if err != nil {
+				t.Fatalf("Setup failed: %v", err)
+			}
+
+			result := getPackageDescription(testDir)
+			if result != test.expected {
+				t.Errorf("want %q, got %q", test.expected, result)
+			}
+		})
+	}
+}
+
+func TestGetPackageDescriptionNonExistentDir(t *testing.T) {
+	result := getPackageDescription("/nonexistent/directory")
+	if result != "" {
+		t.Errorf("Expected empty string for non-existent directory, got %q", result)
+	}
+}

tools/actionsgen/template.md

@@ -15,6 +15,9 @@ toc: true
 
 [//]: <> (This file is generated by tools/actionsgen. DO NOT EDIT.)
 
+{{ if .PackageDescription -}}
+{{ .PackageDescription }}
+{{ else -}}
 Actions are defined as part of a `SecRule` or as parameter for `SecAction` or `SecDefaultAction`. A rule can have no or several actions which need to be separated by a comma.
 
 Actions can be categorized by how they affect overall processing:
@@ -27,6 +30,7 @@ Disruptive actions will NOT be executed if the `SecRuleEngine` is set to `Detect
 * **Flow actions** - These actions affect the rule flow (for example skip or skipAfter).
 * **Meta-data actions** - used to provide more information about rules. Examples include id, rev, severity and msg.
 * **Data actions** - Not really actions, these are mere containers that hold data used by other actions. For example, the status action holds the status that will be used for blocking (if it takes place).
+{{ end -}}
 
 {{ range .Actions }}
 ## {{ .Name }}