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.py succeeds 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_t4yeovFm83Wo reused in src/types-and-traits.rst and src/glossary.rst
fls_I9JaKZelMiby reused in src/types-and-traits.rst and src/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.
Problem
The docs build currently does not fail when the same paragraph ID (
:dp:/fls_*) is used more than once acrosssrc/.Current behavior
./make.pysucceeds even with duplicate paragraph IDs.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.rstProposed fix
Add a dedicated lint/check that fails the build when a
:dp:paragraph ID appears more than once undersrc/, with diagnostics that include all file/line locations for each duplicate ID.Potential implementation options:
exts/ferrocene_spec_lints/for global paragraph-ID uniqueness.Acceptance criteria
:dp:IDs.