[spec-librarian] Specification Audit — 2026-07-03 — 2 issues found

[github-actions]

📚 Package Specification Audit Report

Date: 2026-07-03
Total Packages: 31
Packages with Specs: 30
Coverage: 96%

---

Coverage Summary

Status	Package	Notes
❌	modelsdev	No README.md — 1 exported function (FindPricing) undocumented
✅	All other 30 packages	README.md present

---

🚨 Missing Specifications

The following package has no README.md:

Package	Source Files	Exported Symbols	Priority
modelsdev	1 (catalog.go)	1 (FindPricing)	Medium

Details: pkg/modelsdev/catalog.go exposes FindPricing(ctx context.Context, provider, model string) (map[string]float64, bool), which looks up per-token pricing from the models.dev catalog. The package also uses internal unexported helpers (ensureCatalog, downloadAndParseCatalog, parseCatalog, parseCostMap, normalizeProvider, normalizeComparableModelID) and a singleton OnceLoader cache.

Recommendation: Run the spec-extractor workflow for pkg/modelsdev to generate a README.md.

---

⚠️ Stale / Incomplete Specifications

View: linters README missing 6 sub-package entries

linters — 6 undocumented analyzer sub-packages

The pkg/linters/README.md documents 34 sub-packages but the following 6 directories exist in source and are not referenced in the README:

Sub-package	Source file
deferinloop	deferinloop.go
errorfwrapv	errorfwrapv.go
httpnoctx	httpnoctx.go
httprespbodyclose	httprespbodyclose.go
sprintfint	sprintfint.go
timesleepnocontext	timesleepnocontext.go

Each sub-package contains a *.go implementation file, a *_test.go, and a testdata/ directory, indicating they are fully implemented analyzers.

Recommendation: Re-run spec-extractor for pkg/linters to add entries for the 6 missing sub-packages.

---

🔄 Cross-Package Consistency

No terminology conflicts or dependency mismatches found. All checked packages:

• Use logger.New("namespace:sub") pattern consistently for debug logging
• Correctly distinguish stdout (structured/data output) from stderr (diagnostic/log output)
• Dependency declarations in README files match actual Go import statements

---

📊 Quality Scores

Package	Completeness	Accuracy	Consistency	Freshness	Overall
modelsdev	❌ 0%	—	—	—	❌ 0%
linters	⚠️ 85%	100%	95%	N/A	⚠️ 70%
All other 29 packages	✅ ≥90%	✅ ≥90%	✅ ≥85%	N/A	✅ ≥88%

Note: File timestamps are identical across the checkout (CI artifact), so freshness cannot be determined from mtime. Quality scoring uses symbol coverage and cross-reference accuracy instead.

---

Action Items

• Generate specification for pkg/modelsdev (use spec-extractor workflow)
• Update pkg/linters/README.md to document 6 undocumented analyzer sub-packages: deferinloop, errorfwrapv, httpnoctx, httprespbodyclose, sprintfint, timesleepnocontext
• 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 · 88.4 AIC · ⌖ 9.18 AIC · ⊞ 6.1K · ◷

• expires on Jul 6, 2026, 5:54 AM UTC-08:00