rust-lang / rust-lang/fls

Add uniqueness lint for duplicate :dp: paragraph IDs

Open
#662 0 comments 0 reactions 0 assignees View on GitHub

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.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:

  1. Add a new lint in exts/ferrocene_spec_lints/ for global paragraph-ID uniqueness.
  2. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.