Skip to content

coding review lint: quote the body's trigger paragraph in label findings (and don't auto-promote it) #331

Description

@shadowbrush

Follow-up to #325 / #328, prompted by hadron-memory/hadron-server#845 — where 3 of 11 checks had a bare Applies when stem and --fix could repair none of them.

This issue supersedes the suggestion I left at the bottom of hadron-server#845. There I speculated that --fix should learn to read the > **Scope.** body line. I then measured it, and that idea is wrong — the data is below.

What I measured

Every review:* check across the four memories that have one (90 checks):

Memory checks > **Scope.** line-initial **Applies when** neither
hadronmemory.com::hadron-server 11 11 0 0
micromentor.org::mmdata 49 38 0 11
hadronmemory.com::hadron-portal 24 0 2 22
hadronmemory.com::hadron-cli 6 6 0 0
Total 90 55 2 33

So a body-derived trigger is findable for ~63% of checks, and the convention is far from universal — hadron-portal uses neither shape in 22 of 24.

Why auto-promotion is the wrong feature

The body text is a scope paragraph, not a label. Compared against the 84 healthy edge labels in the same corpus:

min median p90 max
healthy edge labels 32 84 142 179
> **Scope.** paragraphs 61 238 567
**Applies when** paragraphs 179 389 389

Promoting a Scope paragraph verbatim would produce labels 3× the median healthy length, up to 567 characters — and since the edge loc is slugified from the name, it would also mint enormous derived locs. --fix's current conservatism (only promote a description that already reads as a trigger) is correct and should stay.

What would actually help

Make the finding carry the raw material, so whoever fixes it doesn't have to open each node:

review:entity-ref-args  error  label-is-condition
  edge label is the bare stem "Applies when" with no condition after it
  the node's body states its scope — condense this into the label:
    "Adding or renaming a GraphQL argument (query OR mutation) that identifies an
     existing entity, or widening an existing arg to accept a URN. Skip for …"

Concretely:

  1. When label-present or label-is-condition fires, look for a trigger paragraph in the node body (> **Scope.** … or a line-initial **Applies when** …) and quote it, truncated, in the finding message.
  2. Say nothing extra when neither shape is present — that's a third of checks, and a "couldn't find one" line on every finding is noise.
  3. Leave --fix exactly as it is. Condensing a paragraph into a trigger is a judgement call; the linter should hand over the source text, not guess.

Optionally, a --suggest flag could print the full paragraph rather than a truncation, for someone working through a batch.

Scope note

This is presentation only — no new rule, no severity change, no writes. The --json contract gains nothing new either, since the text goes in the existing message field.

Worth doing because the failure mode it serves is real and recurring: hadron-server#845 is three instances in one memory, and in every one of them the trigger text already existed a few lines away in the node body.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions