Repository navigation
Description
📚 Package Specification Audit Report
Date: 2026-04-16
Total Packages: 22
Packages with Specs: 22
Coverage: 100% ✅
⚠️ Note: This repository uses a shallow clone (1 commit), so timestamp-based staleness analysis was not possible. All findings are based on content analysis.
Summary
| Status | Count | Category |
|---|---|---|
| ✅ Healthy | 18 | Complete, accurate, consistent |
| 4 | API drift, missing examples, inconsistencies | |
| ❌ Critical | 0 | — |
🚨 API Drift — workflow Package
The following exported functions exist in source but are not documented in pkg/workflow/README.md:
| Function | File | Description |
|---|---|---|
ParseTagRefTSV |
action_resolver.go |
Parses TSV lines from git for-each-ref output |
ExtractActionsFromLockFile |
action_sha_checker.go |
Extracts action usages from a lock file |
CheckActionSHAUpdates |
action_sha_checker.go |
Checks for SHA updates across action usages |
GetGeminiAPITarget |
awf_helpers.go |
Returns the Gemini API target URL for a workflow |
ComputeAWFExcludeEnvVarNames |
awf_helpers.go |
Computes env var names to exclude from AWF |
GetGeminiAllowedDomainsWithToolsAndRuntimes |
domains.go |
Returns Gemini allowed domains string |
Recommendation: Add these to the ## Public API table in pkg/workflow/README.md.
⚠️ Missing Dependencies — workflow README
pkg/workflow/README.md lists its internal dependencies but omits 4 packages that are actively imported:
| Missing Package | Files That Import It |
|---|---|
pkg/actionpins |
action_pins.go |
pkg/semverutil |
awf_helpers.go, copilot_engine_execution.go, features_validation.go, mcp_github_config.go, runtime_detection.go |
pkg/typeutil |
claude_logs.go, config_helpers.go, engine.go, metrics.go, publish_artifacts.go, publish_assets.go, safe_outputs_config.go |
pkg/tty |
git_helpers.go, github_cli.go |
Current documented deps: pkg/parser, pkg/constants, pkg/console, pkg/logger, pkg/stringutil, pkg/fileutil, pkg/gitutil, pkg/sliceutil, pkg/types
Recommendation: Add the 4 missing packages to the **Internal**: section.
⚠️ No Code Examples
The following packages document their API in tables but include zero code examples (no ``` blocks):
Packages without code examples (2)
actionpins — pkg/actionpins/README.md
- Has complete type and function tables (9 exported functions documented)
- No usage examples showing how to call
ResolveActionPin,GetCachedActionPin, etc. - Recommendation: Add a small "Usage Example" section with
ResolveActionPinorGetCachedActionPin
stats — pkg/stats/README.md
- Has complete
StatVarmethod table (11 methods documented) - No usage examples showing how to create a
StatVarand add observations - Recommendation: Add a short "Usage Example" section with
Add,Mean,StdDev, etc.
🔄 Cross-Package Inconsistencies
Title format inconsistency (2 packages)
All packages use lowercase package names in their title except two:
| Package | Current Title | Expected Title |
|---|---|---|
console |
# Console Package |
# console Package |
logger |
# Logger Package |
# logger Package |
Recommendation: Lowercase the package name in the title to match the 20 other packages.
Missing spec-extractor footer (12 packages)
10 of 22 packages have the footer *This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*
The following 12 packages are missing the footer:
console, logger, envutil, repoutil, sliceutil, semverutil, stringutil, testutil, timeutil, types, typeutil, styles
Recommendation: Add the footer to these specs or run spec-extractor to regenerate them.
📊 Quality Scores
| Package | Lines | Sections | Code Blocks | Completeness | Consistency | Overall |
|---|---|---|---|---|---|---|
actionpins |
55 | 4 | 0 | 85% | 100% | |
agentdrain |
223 | 5 | 22 | 80% | 100% | ✅ 85% |
cli |
204 | 7 | 8 | 90% | 100% | ✅ 90% |
console |
785 | 14 | 106 | 95% | 90% | ✅ 92% |
constants |
427 | 15 | 40 | 90% | 100% | ✅ 90% |
envutil |
46 | 3 | 2 | 85% | 90% | ✅ 82% |
fileutil |
94 | 3 | 8 | 85% | 100% | ✅ 85% |
gitutil |
89 | 3 | 12 | 85% | 100% | ✅ 85% |
logger |
214 | 8 | 22 | 90% | 90% | ✅ 87% |
parser |
257 | 6 | 10 | 90% | 100% | ✅ 90% |
repoutil |
42 | 3 | 4 | 85% | 90% | ✅ 83% |
semverutil |
103 | 4 | 14 | 85% | 90% | ✅ 83% |
sliceutil |
79 | 3 | 12 | 85% | 90% | ✅ 83% |
stats |
45 | 4 | 0 | 75% | 100% | |
stringutil |
179 | 8 | 22 | 88% | 90% | ✅ 85% |
styles |
101 | 7 | 4 | 80% | 90% | ✅ 82% |
testutil |
62 | 3 | 8 | 80% | 90% | ✅ 82% |
timeutil |
62 | 3 | 6 | 80% | 90% | ✅ 82% |
tty |
44 | 3 | 4 | 90% | 100% | ✅ 88% |
types |
109 | 3 | 6 | 85% | 90% | ✅ 83% |
typeutil |
77 | 4 | 8 | 85% | 90% | ✅ 83% |
workflow |
460 | 7 | 10 | 75% | 100% |
Action Items
-
pkg/workflow/README.md: Add 6 undocumented exported functions to the Public API section -
pkg/workflow/README.md: Add 4 missing internal dependencies (actionpins,semverutil,typeutil,tty) to the Dependencies section -
pkg/actionpins/README.md: Add a Usage Example section with code blocks -
pkg/stats/README.md: Add a Usage Example section with code blocks -
pkg/console/README.md: Normalize title to# console Package -
pkg/logger/README.md: Normalize title to# logger Package - Add spec-extractor footer to the 12 packages that are missing it (run spec-extractor)
📚 Next review scheduled for tomorrow. Close this issue once all items are resolved.
References:
📚 Specification review by Package Specification Librarian · ● 5.3M · ◷
Activity