[dinoconstantinou87]

Summary

There was no way to see which of FreeAgent's documented endpoints the spec covers. This adds a coverage command to
FreeAgentTools and a make coverage target that prints its report.

$ make coverage
# FreeAgent API Coverage

The spec covers 119 of the 203 endpoints documented at https://dev.freeagent.com/docs (59%).

| Page | Documented | Covered | Missing |
| --- | ---: | ---: | ---: |
| [Account Locks](https://dev.freeagent.com/docs/account_locks) | 3 | 0 | 3 |
| [Attachments](https://dev.freeagent.com/docs/attachments) | 2 | 2 | 0 |
...

• FreeAgentTools coverage --output <path> writes a Markdown report. --root (default openapi/openapi.yaml)
  and --docs (default https://dev.freeagent.com/docs) can be changed.
• make coverage writes it to .build/coverage.md (COVERAGE_REPORT_PATH overrides) and prints it.

How It Works

• The docs: every page in the sidebar of dev.freeagent.com/docs is downloaded. Each endpoint is the
  METHOD https://api.freeagent.com/v2/... line that starts a code block, with any query string dropped.
• The spec: every operation under paths in openapi.yaml, following each path file's $ref.
• Matching: a method plus a path, where the docs' :id, the spec's {id} and a numeric example ID (the Notes
  page's /v2/notes/1) are the same placeholder.
• Grouping: an endpoint shown on several pages is listed under the page documenting the most endpoints, so the
  Introduction and How To Guides pages, which repeat other pages' examples, drop out.

The report has a summary line, a table of pages, the missing endpoints by page, and the spec endpoints no page
documents.

Known Trade-Off

The docs' own path errors show on both sides rather than being matched. The documented
DELETE /v2/price_list_item/:id is a 404, so it is listed as missing, and the working
DELETE /v2/price_list_items/{id} is listed as not in the docs. The task delete, which the docs give as
/v2/users/:id, appears the same way. Marking these as known errors would need a hand-kept list.

Code

• CoverageCommand fetches the index and every page concurrently and writes the report.
• Models: Endpoint (method, path and the matching key), DocsPage (reads the index links and a page's
  endpoints), SpecPaths (reads the spec's operations) and CoverageReport (the comparison and its Markdown).
• FreeAgentTools is now an AsyncParsableCommand, and SpecGraph.node(at:in:) is no longer private, so
  SpecPaths can follow a $ref pointer.
• URLSession comes from FoundationNetworking on Linux.

Tests

• 10 new tools tests: placeholder matching, reading the index links and a page's endpoints, reading the spec's
  operations through a $ref and inline, and the report's sections, grouping, undocumented list and Markdown.
• 21 tools, 148 CLI and 90 API unit tests pass, and format and lint are clean.
• Run against the live docs on macOS and in swift:6.4.0-noble: the same report, and the tools tests pass on Linux.
• No openapi/ change, so no integration suite runs.

🤖 Generated with Claude Code

https://claude.ai/code/session_01F3kiLMJnzAVUr7s39h94MK