From aa5e58bed5817dcf74bbd3b4d9ace238293180e7 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 21 Apr 2026 10:49:48 +0000 Subject: [PATCH] docs: fix README spec inaccuracies in gitutil, logger, stringutil, timeutil - gitutil: add missing IsValidFullSHA documentation; fix IsRateLimitError to include 'secondary rate limit' pattern - logger: document ACTIONS_RUNNER_DEBUG=true enables all loggers - stringutil: fix NormalizeWhitespace description (trims trailing whitespace per-line, not collapse to single space); fix IsPositiveInteger description (must be > 0, no leading zeros); fix NormalizeSafeOutputIdentifier to document period replacement in addition to dash replacement - timeutil: fix FormatDurationNs example (2_500_000_000ns rounds to 3s not 2s due to Go's away-from-zero rounding) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- pkg/gitutil/README.md | 12 +++++++++++- pkg/logger/README.md | 2 +- pkg/stringutil/README.md | 9 +++++---- pkg/timeutil/README.md | 2 +- 4 files changed, 18 insertions(+), 7 deletions(-) diff --git a/pkg/gitutil/README.md b/pkg/gitutil/README.md index 0a40d02a1a4..2d849ea3749 100644 --- a/pkg/gitutil/README.md +++ b/pkg/gitutil/README.md @@ -17,7 +17,7 @@ This package contains helpers for: #### `IsRateLimitError(errMsg string) bool` -Returns `true` when `errMsg` indicates a GitHub API rate-limit error (HTTP 403 "API rate limit exceeded" or HTTP 429). +Returns `true` when `errMsg` indicates a GitHub API rate-limit error. Matches any of: "api rate limit exceeded", "rate limit exceeded", or "secondary rate limit" (case-insensitive). ```go if gitutil.IsRateLimitError(err.Error()) { @@ -47,6 +47,16 @@ if gitutil.IsHexString(sha) { } ``` +#### `IsValidFullSHA(s string) bool` + +Returns `true` if `s` is a valid 40-character lowercase hexadecimal SHA (the standard Git commit SHA format). Use this for strict SHA validation when the full 40-character form is required. + +```go +if gitutil.IsValidFullSHA(commitSHA) { + // Full 40-char commit SHA +} +``` + #### `ExtractBaseRepo(repoPath string) string` Extracts the `owner/repo` portion from an action path that may include a sub-folder. diff --git a/pkg/logger/README.md b/pkg/logger/README.md index acf8c81fec8..13a45b1ca34 100644 --- a/pkg/logger/README.md +++ b/pkg/logger/README.md @@ -61,7 +61,7 @@ log.Printf("Task completed") // Shows +2.5s (or +500ms, +100µs, etc.) ## DEBUG Environment Variable -Control which loggers are enabled using the `DEBUG` environment variable with patterns: +Control which loggers are enabled using the `DEBUG` environment variable with patterns. When `ACTIONS_RUNNER_DEBUG=true` is set (as it is in GitHub Actions debug runs) and `DEBUG` is not explicitly set, all loggers are enabled automatically — equivalent to `DEBUG=*`. ### Examples diff --git a/pkg/stringutil/README.md b/pkg/stringutil/README.md index b1d0870292a..53beb4fbe19 100644 --- a/pkg/stringutil/README.md +++ b/pkg/stringutil/README.md @@ -26,7 +26,7 @@ stringutil.Truncate("hi", 8) // "hi" ### `NormalizeWhitespace(content string) string` -Collapses multiple consecutive whitespace characters (spaces, tabs, newlines) into a single space and trims leading/trailing whitespace. +Normalizes trailing whitespace in multi-line content. Trims trailing spaces and tabs from every line, then ensures the content ends with exactly one newline (or is empty). This reduces spurious diffs caused by trailing-whitespace differences. ### `ParseVersionValue(version any) string` @@ -40,7 +40,7 @@ stringutil.ParseVersionValue(20.0) // "20" ### `IsPositiveInteger(s string) bool` -Returns `true` if `s` is a non-empty string containing only digit characters (`0–9`). +Returns `true` if and only if `s` is a decimal integer that is strictly greater than zero, has no leading zeros, and contains no non-digit characters. Returns `false` for `""`, `"0"`, negative strings (e.g. `"-5"`), strings with leading zeros (e.g. `"007"`), and non-numeric strings. ## ANSI Escape Code Stripping (`ansi.go`) @@ -67,10 +67,11 @@ stringutil.NormalizeWorkflowName("weekly-research") // "weekly-research ### `NormalizeSafeOutputIdentifier(identifier string) string` -Converts dashes to underscores in safe-output identifiers, normalizing the user-facing `dash-separated` format to the internal `underscore_separated` format. +Converts dashes **and periods** to underscores in safe-output identifiers, normalizing user-facing `dash-separated` and dot-separated formats to the internal `underscore_separated` format required by MCP tool names (which must match `^[a-zA-Z0-9_-]+$`). ```go -stringutil.NormalizeSafeOutputIdentifier("create-issue") // "create_issue" +stringutil.NormalizeSafeOutputIdentifier("create-issue") // "create_issue" +stringutil.NormalizeSafeOutputIdentifier("executor-workflow.agent") // "executor_workflow_agent" ``` ### `MarkdownToLockFile(mdPath string) string` diff --git a/pkg/timeutil/README.md b/pkg/timeutil/README.md index 3e21a4e20b3..13deeffbadf 100644 --- a/pkg/timeutil/README.md +++ b/pkg/timeutil/README.md @@ -51,7 +51,7 @@ Formats a duration given in **nanoseconds** as a human-readable string. Returns ```go timeutil.FormatDurationNs(0) // "—" -timeutil.FormatDurationNs(2_500_000_000) // "2s" +timeutil.FormatDurationNs(2_000_000_000) // "2s" timeutil.FormatDurationNs(90_000_000_000) // "1m30s" ```