Skip to content

ADR 0016 follow-ups: repeated references, whole-file links, an opt-in depth lint #110

Description

@aslakhellesoy

Follow-up to #104 (ADR 0016). Smaller open questions, collected — each is a decision rather than a defect, and none blocks anything.

  • The same section referenced twice in one example. Works today: the steps run twice. Is that a legitimate "do it again", or an authoring mistake worth a diagnostic? (ADR open question 5.)

  • Fragment-less whole-file references ([Setup](./shared/setup.md)). Supported, and the one form whose meaning silently changes when the target file grows a second example. Keep, or require an anchor? (ADR open question 6.)

  • An opt-in depth lint. Nesting depth is deliberately a style question the parser doesn't enforce (see explanation/reuse.md), but reference/lint.md is where checkable house style already lives. A rule that is off by default and warns past a configured depth would let a team set its own ceiling without Varar picking one — or it's the same prohibition wearing a hat. (ADR open question 9.)

  • A referenced section's own scopeStack is discarded in favour of the referring example's; the heading serves only as the anchor and the link text. This is what ships, and the 21-reference-consumed bundle pins it — confirm it is intended, and say so in the reference. (ADR open question 4, effectively answered by implementation.)

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    questionFurther information is requested

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions