[spec-librarian] Specification Audit — 2026-07-10 — 1 issue found

[github-actions]

📚 Package Specification Audit Report

Date: 2026-07-10
Total Packages: 32
Packages with Specs: 32
Coverage: 100%

---

Coverage Summary

All 32 packages under pkg/ have a README.md specification. 100% coverage achieved.

---

🚨 Accuracy Issues Found

parser — Phantom Function in Specification

The specification documents a function that does not exist in the source code:

Status	Documented Name	Actual Name in Source
❌ Phantom	LocateJSONPathInYAMLWithAdditionalProperties	Does not exist

The source file pkg/parser/json_path_locator.go exposes only:

• LocateJSONPathInYAML(yamlContent, jsonPath string) JSONPathLocation
• LocateJSONPathForPathInfo(yamlContent string, info JSONPathInfo) JSONPathLocation
• ExtractJSONPathFromValidationError(err error) []JSONPathInfo

The README documents a three-argument variant LocateJSONPathInYAMLWithAdditionalProperties(yamlContent, jsonPath, errorMessage string) that does not exist. This may be a residue from a refactoring where this functionality was merged into LocateJSONPathForPathInfo.

File: pkg/parser/README.md
Recommendation: Remove the phantom entry for LocateJSONPathInYAMLWithAdditionalProperties from the Public API table, or check if this function was recently deleted and the spec not updated.

---

⚠️ Low Documentation-to-Symbol Ratios

The following packages have a low ratio of documented symbols relative to their exported surface area. Note: many "exported" symbols may be constants or variables (not functions/types), which reduces the urgency, but these warrant review:

View low-coverage packages (symbol ratio < 20%)

Package	Exported Symbols	Backtick-Documented Symbols	Approx Ratio	Notes
constants	294	55	~19%	Large number of constants; README may not enumerate all
cli	3,269	372	~11%	Very large package; many cobra commands; README covers structure
workflow	5,541	339	~6%	Largest package; generated types dominate
stringutil	111	14	~13%	Several utility functions may be undocumented
envutil	33	3	~9%	Only 3 top-level funcs but many constants
parser	570	124	~22%	Large generated-type surface area

These ratios reflect all exported identifiers including constants/vars. The constants, cli, workflow, and parser packages have large auto-generated or configuration type surfaces that may not require individual documentation. A targeted review is still recommended.

---

🔄 Cross-Package Consistency Notes

View consistency observations

README Format Consistency

All 32 package READMEs follow a consistent structure:

• # <Package> Package heading
• ## Overview, ## Public API, ## Usage Examples, ## Dependencies, ## Design Notes sections
• Footer: "This specification is automatically maintained by the spec-extractor workflow."

Dependency Accuracy Spot-Check

• actionpins: README lists console, gitutil, logger, semverutil as dependencies — confirmed accurate against source imports
• sliceutil: README claims dependency on logger — confirmed accurate (logger.New("sliceutil:sliceutil") found in source)
• syncutil: README claims dependency on logger — confirmed accurate

No Conflicting Cross-Package Terminology Found

All READMEs use consistent terminology for key concepts (e.g., "formatted output", error return conventions).

---

📊 Quality Scores

Package	Completeness	Accuracy	Consistency	Overall	Status
tty	100%	100%	100%	✅ 100%	Good
setutil	100%	100%	100%	✅ 100%	Good
repoutil	100%	100%	100%	✅ 100%	Good
envutil	100%	100%	100%	✅ 100%	Good
importinpututil	100%	100%	100%	✅ 100%	Good
syncutil	100%	100%	100%	✅ 100%	Good
semverutil	100%	100%	100%	✅ 100%	Good
actionpins	90%	100%	100%	✅ 96%	Good
parser	85%	70%	90%	⚠️ 82%	Needs Attention — phantom function
console	80%	90%	90%	✅ 87%	Good
workflow	60%	85%	90%	⚠️ 78%	Needs Attention — large surface area
cli	55%	85%	90%	⚠️ 77%	Needs Attention — large surface area
stringutil	50%	90%	90%	⚠️ 77%	Needs Attention — several undocumented funcs

---

Action Items

• Fix phantom function in parser README: Remove or correct the LocateJSONPathInYAMLWithAdditionalProperties entry — the actual function is LocateJSONPathInYAML. Re-run spec-extractor for parser package to regenerate the Public API table.
• Review stringutil README for undocumented exported functions (package has 25 exported top-level functions, only ~14 symbolically documented).
• Consider running the spec-extractor against workflow, cli, and parser packages to refresh their large auto-generated type surfaces.
• When opening a fix PR for this issue, include Closes #<this issue number> (or Fixes/Resolves) in the PR description.

---

📚 Next review scheduled for tomorrow. Close this issue once all items are resolved.

📚 Specification review by Package Specification Librarian · 72.8 AIC · ⌖ 4.93 AIC · ⊞ 6K · ◷

• expires on Jul 13, 2026, 5:55 AM UTC-08:00