fastmcp(fix[ids]): avoid duplicate IDs on same-slug headings

[tony]

Summary

• Fix: a page heading whose slug matches a tool's bare cross-reference alias no longer produces docutils Duplicate ID diagnostics or an ambiguous HTML fragment (sphinx-autodoc-fastmcp: avoid duplicate IDs when tool alias matches page heading slug #48)
• Decouple: tool cards keep a single canonical physical anchor (fastmcp-tool-<slug>); the bare slug survives purely as a Sphinx label alias pointing at the canonical anchor
• Resolve: {tool}, {toolref}, {toolicon*}, and bare {ref} targets keep working and now resolve to the canonical fragment; fastmcp-tool-summary table links target it too
• Test: a heading-collision integration scenario locks in the contract — no duplicate-ID diagnostics, sole heading ownership of the bare anchor, canonical-fragment link resolution

Before/After

Delete buffer
=============

.. fastmcp-tool:: buffer_tools.delete_buffer

Before: the build emitted CRITICAL: Duplicate ID: "delete-buffer". [docutils], the rendered page carried two delete-buffer anchors, and tool links resolved to the ambiguous bare fragment.

After: the heading owns #delete-buffer exclusively; the card is reachable at #fastmcp-tool-delete-buffer; label-based references ({ref}, tool roles) resolve there.

Design decisions

• Alias as pure label, not conditional physical ID: dropping the bare id only on collision would make card anchors unstable — adding a heading to a page would silently move the tool's anchor. The canonical anchor is deterministic; the bare alias always points at it.
• Incremental rebuilds: accepted aliases ride the pickled doctree as a node attribute, so the doctree-read hook restores alias labels from cache without re-running the directive.
• Trade-off: raw-URL fragments #<slug> no longer land on the card. Label-based references are unaffected; the bare fragment was ambiguous in exactly the colliding case this fixes.

Test plan

• test_heading_collision_emits_no_duplicate_id_diagnostic — same-slug heading + tool card builds without duplicate-ID diagnostics
• test_heading_collision_anchor_counts — heading owns the sole bare anchor; {toolref} and fastmcp-tool-summary links target #fastmcp-tool-<slug>
• test_heading_collision_card_renders — card classes and badges render under the collision
• Full suite, lint, and types green: uv run pytest, uv run ruff check ., uv run mypy
• just build-docs — shipped docs build cleanly; tool-role links resolve to canonical anchors

[codecov-commenter]

Codecov Report

❌ Patch coverage is 97.50000% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 91.90%. Comparing base (707dc0c) to head (6551238).

Files with missing lines	Patch %	Lines
...-fastmcp/src/sphinx_autodoc_fastmcp/_directives.py	80.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #49      +/-   ##
==========================================
+ Coverage   91.88%   91.90%   +0.01%     
==========================================
  Files         233      233              
  Lines       18191    18223      +32     
==========================================
+ Hits        16714    16747      +33     
+ Misses       1477     1476       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tony]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}