[spec-enforcer] Enforce specifications for stringutil, styles, testutil

[github-actions]

Caution

Security scanning requires review for Package Specification Enforcer

Details

Potential security threats were detected in the agent output. The workflow output should be reviewed before merging.

Review the workflow run logs for details.

Specification Test Enforcement

This PR adds/updates specification-driven tests for the following packages:

Package	Tests Added	Tests Passing	Spec Sections Covered
stringutil	9 new functions	all (2 skipped, SPEC_MISMATCH)	NormalizeWhitespace, IsPositiveInteger (edge cases), NormalizeSafeOutputIdentifier (period→underscore), SanitizeIdentifierName, SanitizeParameterName, SanitizePythonVariableName, SanitizeToolID, SanitizeForFilename, GetPATTypeDescription
styles	1	1	Exact hex values for all 11 adaptive color variables
testutil	0	6 (existing)	GetTestRunDir, TempDir, CaptureStderr, StripYAMLCommentHeader

Test Derivation

All tests are derived from README.md specifications, not from implementation source code. Minimal source reads were limited to verifying function signatures and confirming SPEC_MISMATCHes.

pkg/stringutil

Updated 2 existing test functions:

• TestSpec_PublicAPI_IsPositiveInteger — added "0" → false and "007" → false cases documented in the README ("Returns false for "", "0", negative strings, strings with leading zeros").
• TestSpec_PublicAPI_NormalizeSafeOutputIdentifier — converted to table-driven and added period→underscore test case from the documented example: "executor-workflow.agent" → "executor_workflow_agent".

Added 9 new TestSpec_ functions:

• TestSpec_PublicAPI_NormalizeWhitespace — validates documented behavior: trims trailing spaces/tabs from every line, ensures exactly one trailing newline (or empty for empty input), collapses multiple trailing newlines to one.
• TestSpec_PublicAPI_GetPATTypeDescription — validates that the function returns a non-empty human-readable description, and that a fine-grained PAT returns a description containing "fine-grained" as documented.
• TestSpec_PublicAPI_SanitizeIdentifierName — validates: invalid chars replaced with _, digit-starting identifiers prefixed with _, valid identifiers unchanged, extraAllowed function permits specified runes.
• TestSpec_PublicAPI_SanitizeParameterName — validates: hyphens replaced with _, $ preserved, _ preserved, spaces replaced with _, letters+digits preserved.
• TestSpec_PublicAPI_SanitizePythonVariableName — validates basic identifier sanitization (hyphens → underscores, valid chars preserved).
• TestSpec_PublicAPI_SanitizeToolID — skipped (see SPEC_MISMATCH below).
• TestSpec_PublicAPI_SanitizeForFilename — 2 passing cases (space→hyphen for lowercase input; already-safe string unchanged) + 1 skip for lowercasing mismatch.

pkg/styles

Added 1 new TestSpec_ function:

• TestSpec_Constants_RemainingAdaptiveColorHexValues — validates exact hex values for the 7 remaining documented adaptive color variables: ColorPurple, ColorYellow, ColorComment, ColorForeground, ColorBackground, ColorBorder, ColorTableAltRow. The README explicitly documents all 11 hex values and the design notes state "Colors are defined with both light and dark hex constants so tests can assert exact color values." The previous spec_test.go only asserted exact values for 4 of the 11.

pkg/testutil

No changes needed. All 6 existing TestSpec_ functions comprehensively cover the 4 documented public functions (GetTestRunDir, TempDir, CaptureStderr, StripYAMLCommentHeader), including cleanup behavior and idempotency guarantees.

Spec-Implementation Mismatches

Package	Function	Mismatch
stringutil	SanitizeToolID	README.md documents SanitizeToolID as "Replaces characters that are not valid in identifiers with underscores" (identifier sanitization), but the implementation removes "mcp-" prefixes and "-mcp" suffixes from tool IDs — entirely different behavior.
stringutil	SanitizeForFilename	README.md documents SanitizeForFilename as "lowercasing and replacing non-alphanumeric characters with hyphens," but the implementation does not lowercase the output and also preserves _, ., and - characters (which are non-alphanumeric).

Round-Robin State

• Packages processed this run: stringutil, styles, testutil
• Next packages in rotation: timeutil, tty, types
• Total eligible packages: 22 (with README.md)

References:

• §25161738569

---

Auto-generated by Package Specification Enforcer workflow

Generated by Package Specification Enforcer · ● 764.2K · ◷

• expires on May 3, 2026, 11:13 AM UTC

[pelikhan]

@davidslater interresting