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:
- 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.
- 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.
- 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.
Follow-up to #325 / #328, prompted by hadron-memory/hadron-server#845 — where 3 of 11 checks had a bare
Applies whenstem and--fixcould repair none of them.This issue supersedes the suggestion I left at the bottom of hadron-server#845. There I speculated that
--fixshould 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):> **Scope.****Applies when**hadronmemory.com::hadron-servermicromentor.org::mmdatahadronmemory.com::hadron-portalhadronmemory.com::hadron-cliSo 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:
> **Scope.**paragraphs**Applies when**paragraphsPromoting 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:
Concretely:
label-presentorlabel-is-conditionfires, look for a trigger paragraph in the node body (> **Scope.** …or a line-initial**Applies when** …) and quote it, truncated, in the finding message.--fixexactly 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
--suggestflag 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
--jsoncontract gains nothing new either, since the text goes in the existingmessagefield.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.