[spec-enforcer] Enforce specifications for envutil, fileutil, gitutil

[github-actions]

Specification Test Enforcement

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

Package	Tests Added	Tests Passing	Spec Sections Covered
envutil	0	9 (existing)	GetIntFromEnv (all 5 documented behaviors)
fileutil	0	7 (existing)	Path Validation, File/Directory Checks, File Operations, Archive Operations
gitutil	3	3	Repository Operations: IsValidFullSHA, FindGitRoot, ReadFileFromHEADWithRoot

Test Derivation

All tests are derived from README.md specifications, not from implementation source code. Minimal source reads were limited to exact function signatures and import paths.

pkg/envutil

No changes needed. The existing spec_test.go comprehensively covers all documented GetIntFromEnv behaviors: returns defaultValue when unset, when unparseable, when below minValue, when above maxValue; validates inclusive min/max boundaries; validates nil-logger behavior; and exercises the README usage example.

pkg/fileutil

No changes needed. The existing spec_test.go covers all 7 documented functions: ValidateAbsolutePath, MustBeWithin, FileExists, DirExists, IsDirEmpty, CopyFile, and ExtractFileFromTar (including its documented security guarantees for unsafe tar entry names and path traversal).

pkg/gitutil

Added 3 new TestSpec_ functions covering previously untested documented functions:

• TestSpec_PublicAPI_IsValidFullSHA — validates 40-char lowercase hex returns true; uppercase, wrong-length, empty, and non-hex strings return false. Derived from the README's specification of ^[0-9a-f]{40}$ semantics ("lowercase" constraint explicitly documented).
• TestSpec_PublicAPI_FindGitRoot — validates that FindGitRoot returns a non-empty absolute path when executed within a git repository. Reflects the documented contract: "Returns the absolute path of the root directory of the current Git repository."
• TestSpec_PublicAPI_ReadFileFromHEADWithRoot — validates: reads a known file (go.mod) from HEAD without error; returns error for non-existent files; rejects .. path traversal (documented security guarantee); returns error when gitRoot is empty.

Spec-Implementation Mismatches

None found for the packages processed this run.

Round-Robin State

• Packages processed this run: envutil, fileutil, gitutil
• Next packages in rotation: logger, parser, repoutil
• Total eligible packages: 22 (with README.md)

References:

• §24954505910

---

Auto-generated by Package Specification Enforcer workflow

Generated by Package Specification Enforcer · ● 340.4K · ◷

• expires on Apr 29, 2026, 10:40 AM UTC

[pelikhan]

/q tell the agent to run lint go to make sure the tests are lint clean

[github-actions]

🎩 Mission equipment ready! Q has optimized your workflow. Use wisely, 007! 🔫

[github-actions]

Lint Analysis for PR #28571

I reviewed the new test code in pkg/gitutil/spec_test.go for lint compliance. Unfortunately, golangci-lint cannot be executed in this environment because the installed Go version (1.24.13) is below the required minimum (1.25.8 per go.mod).

Manual lint review results — no issues found:

Check	Status
Build tag //go:build !integration present	✅
No unused helper functions defined	✅
All assertions have descriptive messages	✅
assert.Equal used with table-driven variable (not bool literal)	✅
assert.NoError / assert.Error / assert.True / assert.NotEmpty used correctly	✅
No fmt.Println in test code	✅
No interface{} (uses none)	✅

The 3 new test functions (TestSpec_PublicAPI_IsValidFullSHA, TestSpec_PublicAPI_FindGitRoot, TestSpec_PublicAPI_ReadFileFromHEADWithRoot) follow the project's coding conventions and should pass lint once the correct Go toolchain is available in CI.

🎩 Equipped by Q · ● 547.6K · ◷