Add uniqueness lint for duplicate :dp: paragraph IDs
Nobody has claimed this yet.
- Dominant language
- reStructuredText
- Stars
- 497
- Forks
- 41
- Avg merge
- 3h 52m
- Merged PRs (30d)
- 4
Description
Problem
The docs build currently does not fail when the same paragraph ID (:dp: / fls_*) is used more than once across src/.
Current behavior
./make.pysucceeds even with duplicate paragraph IDs.- Existing linting checks enforce paragraph-ID presence/placement, but not global uniqueness.
- Definition collection stores paragraph entries keyed by ID, so collisions can silently overwrite (
storage[item.id] = item), which can make ID-keyed tooling nondeterministic.
Why this matters
Paragraph IDs are used as stable references in spec prose and tooling artifacts. Duplicate IDs can silently break traceability and produce inconsistent downstream behavior.
Concrete evidence
A recent fix PR had to deduplicate two inherited collisions (see #661):
fls_t4yeovFm83Woreused insrc/types-and-traits.rstandsrc/glossary.rstfls_I9JaKZelMibyreused insrc/types-and-traits.rstandsrc/glossary.rst
Proposed fix
Add a dedicated lint/check that fails the build when a :dp: paragraph ID appears more than once under src/, with diagnostics that include all file/line locations for each duplicate ID.
Potential implementation options:
- Add a new lint in
exts/ferrocene_spec_lints/for global paragraph-ID uniqueness. - Or enforce uniqueness in paragraph/definition collection and emit explicit errors on collisions.
Acceptance criteria
- Build fails on duplicate
:dp:IDs. - Error message includes duplicate ID plus all file/line occurrences.
- CI covers the regression with a fixture/test case.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in ext/ferrocene_spec_lints/ and inspect make.py to trace the existing paragraph-ID linting and definition collection. Run the current build and lint checks, then locate the fixture or test structure used for regression coverage. Done means duplicate :dp: IDs under src/ fail the build with the ID and every file/line occurrence reported.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- build-system, testing-qa
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100