feat(docs): report catalog coverage with docs.mjs --list

[amondnet]

What

SKILL.md described the skill's coverage in prose — Spring Boot 3.3.0-3.x and 4.0.8+, with "Other Spring projects (framework, security, data) are not published yet". pleaseai/spring-docs has since published 52 Spring Framework versions. Because the stale range lived in the description field — the one that decides whether the skill is reached at all — an entire published project was invisible to the agent, not merely undocumented.

Prose cannot track a repository that releases on its own schedule. This stops writing versions down and reads them instead.

Changes

• summarizeCatalog (Library Layer, no I/O) — the counterpart to lookupTag: that one answers "can I have this version", this one answers "which versions exist". Same catalog, so a coverage report and a resolution can never disagree. Keeps published and unpublished separate, so a reserved tag with no archive is not counted as shipped.
• docs.mjs --list [project] — exposes it. --refresh / --no-fetch are rejected there: the catalog is never cached, and accepting them would promise behaviour that does not exist.
• Shared fetchCatalog — resolveDocs and listDocs parse and validate the catalog in one place. Existing failure wording is unchanged.
• Natural version ordering — 3.5.10 after 3.5.9. The catalog arrives sorted today, but that is a property of a generator in another repository.
• SKILL.md / README.md — version lists removed, pointed at the command. Only the two gaps that belong to upstream remain: Boot 3.2 and older predate the Antora component, and 3.x trees ship no generated appendix.
• Detection stays Boot-only and now says so — Framework arrives as a transitive dependency and is declared in no build file, so its version has to be asked for rather than guessed.

Verification

lint          eslint --max-warnings 0
typecheck     tsc --noEmit
build:skill   bundles regenerated + --check clean
coverage gate scripts/lib/docs-cache.ts 97.96% (threshold 90%)
tests         230 pass / 5 fail

Against the live catalog:

$ node skills/spring-docs/scripts/docs.mjs --list
→ boot 46 published + 4.1.1 unpublished, framework 52 published, exit 0
$ node skills/spring-docs/scripts/docs.mjs --list security
→ {"kind":"unavailable","suggestion":"known projects: boot, framework"}, exit 1

The 5 failing tests are all in scripts/lib/__tests__/library-layer-guard.test.ts and are pre-existing — each spawns eslint against a 5s test timeout, which this machine exceeds. Confirmed failing on a clean main (5 failures there too). Untouched; out of scope for this change.

Follow-up (not in this PR)

Extending detection to Spring Framework is a design decision, not a doc fix: Framework is a transitive dependency of Boot, so the gap closes through BOM-based resolution of one declared Boot version into the component matrix, not through another build-file parser. Worth its own issue.

---

Summary by cubic

Replaces the stale hand-written version list in the skill description—which only named Spring Boot 3.3.0-3.x and 4.0.8+, hiding the 52 published Framework versions—with docs.mjs --list, which reads the catalog live so the agent sees everything the docs repo publishes.

Changes

• Adds summarizeCatalog to the library layer to list published and unpublished versions from the same catalog used for resolution.
• Exposes --list [project]; --refresh and --no-fetch are rejected because the catalog is never cached.
• resolveDocs and listDocs share fetchCatalog for parsing and validation.
• Versions sort naturally (3.5.10 after 3.5.9).
• SKILL.md and README.md point at the command and keep only upstream gaps: pre-Antora Boot 3.2 and missing 3.x appendix.
• Detection stays Boot-only and now says why: Framework is transitive, so its version must be asked for.

^{Written for commit 8420c3a. Summary will update on new commits.}

[sonarqubecloud]

Quality Gate failed

Failed conditions
D Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[codacy-production]

Not up to standards ⛔

🔴 Issues 3 high

Alerts:
⚠ 3 issues (≤ 0 issues of at least minor severity)

Results:
3 new issues

Category	Results
ErrorProne	1 high
Security	2 high

View in Codacy

🟢 Metrics 35 complexity · 0 duplication

Metric	Results
Complexity	35
Duplication	0

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[gemini-code-assist]

Code Review

This pull request introduces a new --list option to the docs.ts script, allowing users to query and display the published projects and versions directly from the live catalog.json instead of relying on static documentation. It adds the listDocs and summarizeCatalog functions, implements natural version sorting so that versions like 3.5.10 correctly follow 3.5.9, and refactors the existing catalog fetching logic into a shared fetchCatalog helper. Comprehensive unit tests have been added to verify the new listing, argument parsing, and sorting behavior, and the user-facing documentation in README.md and SKILL.md has been updated accordingly. There are no review comments to assess, and I have no additional feedback to provide on these changes.

[greptile-apps]

Confidence Score: 4/5

The PR appears safe to merge after correcting the non-blocking but misleading skill instruction about failed-resolution suggestions.

Findings

1.  Misleading Resolution Guidance ▶

Fix with agent prompt

### Issue 1
skills/spring-docs/SKILL.md:81-83
This says a failed resolution provides the same coverage information as `--list`, but unknown-version failures only suggest opening an issue, while network, cache, and checksum failures provide unrelated suggestions or none. An agent following this guidance may skip `--list` and fail to discover the versions that are actually available.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

This PR replaces static Spring documentation coverage claims with a live catalog report.

• Adds --list [project] and structured published/unpublished coverage output.
• Shares catalog fetching and validation between listing and documentation resolution.
• Adds natural version ordering and tests for listing, argument parsing, and catalog summarization.
• Updates the installed skill bundle and documentation, with one misleading instruction about failed-resolution suggestions.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  CLI[docs CLI arguments] --> Parse[parseArgs]
  Parse -->|resolve mode| Resolve[resolveDocs]
  Parse -->|list mode| List[listDocs]
  Resolve --> Fetch[fetchCatalog]
  List --> Fetch
  Fetch --> Validate{Valid catalog?}
  Validate -->|No| Unavailable[unavailable result]
  Validate -->|Yes, resolve| Lookup[lookupTag]
  Validate -->|Yes, list| Summarize[summarizeCatalog]
  Lookup --> Ready[ready or unavailable]
  Summarize --> Coverage[published and unpublished versions]

Loading

_{Reviews (1) · Last reviewed commit: "feat(docs): report catalog coverage with..."}

[greptile-apps]

Misleading resolution guidance

This says a failed resolution provides the same coverage information as --list, but unknown-version failures only suggest opening an issue, while network, cache, and checksum failures provide unrelated suggestions or none. An agent following this guidance may skip --list and fail to discover the versions that are actually available.

Prompt To Fix With AI

This is a comment left during a code review.
Path: skills/spring-docs/SKILL.md
Line: 81-83

Comment:
**Misleading resolution guidance**

This says a failed resolution provides the same coverage information as `--list`, but unknown-version failures only suggest opening an issue, while network, cache, and checksum failures provide unrelated suggestions or none. An agent following this guidance may skip `--list` and fail to discover the versions that are actually available.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!