Skip to content

Add uniqueness lint for duplicate :dp: paragraph IDs #662

@PLeVasseur

Description

@PLeVasseur

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions