Report a Retired Badge Written Inline, Not Only One Defined

[ptr727]

Raised by Copilot as a suppressed finding on promotion pull request #635, against develop code rather than anything that promotion introduces. It is the same shape as #636: a comment claiming more coverage than the code delivers.

The gap

readme_shield_findings scanned reference definitions alone for a retired badge service:

for ref, url in sorted(defs.items()):
    if dep["match"] in url:

So a repo writing the badge as an inline image renders the dead badge and reports nothing. Measured against the pre-fix function:

inline badge           pre=0 post=1
reference badge        pre=1 post=1
fenced inline badge    pre=0 post=0

What made it hard to see

The comment above the loop said the service is "scanned across the whole document rather than per section, since a dead badge is wrong wherever it sits", and the selftest case was named "a retired badge service is reported wherever it sits" while constructing only the reference form. The claim, the case name and the case body all agreed with each other, and none of them agreed with the code. That is the pattern worth naming: the evidence was shaped to the claim rather than to the behavior.

The sweep, not the instance

shield_endpoints already resolves ![alt][ref] and ![alt](url) alike, and its docstring records this exact lesson: "Reading references alone made an inline shield invisible rather than wrong." So the fix is to take the reading that already existed rather than to write a second one.

Every sibling site was enumerated before fixing, and this was the only one that had not taken it:

Site	Reads	Correct?
readme_link_findings naming and grouping loops (4)	definitions	Yes, the rule is about reference definitions
shield presence, shield exclusivity (2)	shield_endpoints	Yes, already both forms
deprecatedShields (1)	definitions	No, fixed here

A definition is still reported where nothing renders it, since a retired service left in the reference block is removed with the badge rather than after it, and a definition that is rendered produces one finding rather than two.

Measured

All 22 cataloged READMEs, pre against post, in both directions: shield findings stay at 7 and no verdict moves, so no false positive. All three repos carrying the badge (ESPHome-NonRoot, KiCadLibrary, MediaTools) write it as a reference definition, so this closes a blind spot rather than catching a live miss. The TODO.md entry for deleting those three badges is unaffected and its count is unchanged.

Verification

Four selftest cases: the inline badge reported, a definition-plus-render counted once, a fenced sample still markup, and the original reference case unchanged. Each was A/B tested against the pre-fix function rather than reasoned about, which is what showed the inline case going 0 -> 1 and the fenced one correctly staying 0. spec/audit.py --selftest, spec/validate.py, prose_lint.py --diff develop and editorconfig-checker all clean. spec/audit.py stays LF.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Updates the README shield auditing logic so deprecated/retired badge services are detected when written as inline images, not only when present as reference-style link definitions. This closes a blind spot in readme_shield_findings and expands the selftest suite to cover the newly supported cases.

Changes:

• Use shield_endpoints() to scan the unfenced document for inline image URLs that match deprecatedShields.
• Keep reporting deprecated reference definitions while avoiding double-reporting when the same URL is also rendered.
• Add selftest cases covering inline deprecated badges, definition+render deduping, and fenced samples remaining ignored.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (2)

spec/audit.py:1754

• The new wording logic has an important third shape: a deprecated badge URL can be rendered in the README, but not via the specific [ref] definition being reported (e.g., the same URL is rendered inline while the reference definition is unused). Add a selftest case that covers this branch and asserts the updated wording (for example, "rendered elsewhere").

        ("a retired badge written inline is reported", conformant.replace("[![Last Commit][b]][x]", "[![Last Commit][b]][x]\\\n![Last Build](https://byob.yarr.is/o/r/lastbuild)"), {}, 1),
        ("a retired badge defined and rendered is one finding, not two", conformant.replace("[![Last Commit][b]][x]", "[![Last Commit][b]][x]\\\n![Last Build][last-build-shield]").replace("[license-shield]: https://img.shields.io/github/license/o/r\n", "[license-shield]: https://img.shields.io/github/license/o/r\n[last-build-shield]: https://byob.yarr.is/o/r/lastbuild\n"), {}, 1),
        ("a retired badge shown as a fenced sample is markup", conformant.replace("## Overview", "```md\n![Last Build](https://byob.yarr.is/o/r/lastbuild)\n```\n\n## Overview"), {}, 0),

spec/audit.py:805

• The deprecated-shield finding decides between "renders" vs "defines" by checking whether the definition URL appears anywhere in rendered. If the badge is rendered via an inline image (or via a different reference name) but this particular [ref] definition is unused, the message will incorrectly claim that [ref] "renders" the badge. It should only say [ref] renders when that reference name is actually used as an image reference; otherwise prefer wording like "rendered elsewhere" to avoid attributing the render to the unused definition.

This issue also appears on line 1752 of the same file.

        for ref, url in sorted(defs.items()):
            if dep["match"] in url:
                defined.add(url)
                verb = f"renders {dep['label']}" if url in rendered else f"defines {dep['label']} and nothing renders it"
                findings.append(("LETTER", f"readme: `[{ref}]` {verb}, which is retired - {dep['reason']} (spec/readme-structure.md)"))

[ptr727]

Answering both suppressed comments from round 2. They are one finding stated at two altitudes, and the code-level one is the sharper of the two, so it is quoted first.

The deprecated-shield finding decides between "renders" vs "defines" by checking whether the definition URL appears anywhere in rendered. If the badge is rendered via an inline image (or via a different reference name) but this particular [ref] definition is unused, the message will incorrectly claim that [ref] "renders" the badge.

The new wording logic has an important third shape: a deprecated badge URL can be rendered in the README, but not via the specific [ref] definition being reported [...] Add a selftest case that covers this branch and asserts the updated wording (for example, "rendered elsewhere").

Both accepted, fixed in 0d81120, and the framing is worth correcting: this was a mis-attribution, not a missing wording branch. Round 1's fix keyed on the URL, and a URL is not an attribution — the same endpoint rendered inline leaves the reference definition unused, so url in rendered credited that render to a reference nothing uses. The message then told a maintainer [ref] renders the badge when deleting [ref] would leave the badge on the page.

Attribution is now by reference name, taken from the image-reference uses, and the URL decides only between the two unused cases. Four shapes, and the suggested wording is adopted:

Shape	Wording
[ref] used as an image reference	`[ref]` renders <label>
[ref] unused, endpoint rendered elsewhere	`[ref]` defines <label> and it is rendered elsewhere
[ref] unused, nothing renders it	`[ref]` defines <label> and nothing renders it
inline image, no definition	an inline image renders <label>

The selftest case you asked for is there and asserts the wording rather than the count, since a count cannot tell these four apart. A/B on that fixture: the round-1 code says "renders" and is wrong to, where this says "defines it and it is rendered elsewhere".

Measured across all 22 cataloged READMEs: shield findings stay at 7, and no verdict and no wording moves, because no repo carries the shape. So this, like both pipe fixes in #636, closes a blind spot rather than correcting a live report.

Worth noting for the record: this is the third round in a row where the defect was a claim wider than the code behind it — the comment that said "wherever it sits" over a definitions-only scan, the message that said "renders" over an unrendered definition, and now an attribution that said [ref] over a render [ref] had no part in.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (1)

spec/audit.py:804

• shield_endpoints() returns a list, but this code uses it for repeated membership checks (url in rendered) and set operations. Converting it once to a set improves clarity and avoids repeated O(n) scans. While changing that, consider naming the URL sets explicitly (rendered_urls, defined_urls) to avoid confusion with reference names.

    rendered = shield_endpoints(unfenced, defs)
    used_refs = {m.group(1) for m in _MD_IMAGE_REF.finditer(unfenced)}
    for dep in model.get("deprecatedShields", []):
        defined = set()
        for ref, url in sorted(defs.items()):
            if dep["match"] in url:

[ptr727]

Answering the round-3 suppressed comment on spec/audit.py:804:

shield_endpoints() returns a list, but this code uses it for repeated membership checks (url in rendered) and set operations. Converting it once to a set improves clarity and avoids repeated O(n) scans. While changing that, consider naming the URL sets explicitly (rendered_urls, defined_urls) to avoid confusion with reference names.

Accepted in full, fixed in 5877b9e. Both halves, and the naming half is the one that earns its place here rather than the cost: this block reasons about reference names and URLs a line apart, and the defect round 2 fixed was precisely a URL standing in for a reference name. rendered_urls and defined_urls against used_refs makes that confusion visible in the identifier rather than only in the comment.

No behavior change, which is asserted rather than assumed: the selftest passes unchanged, and the corpus run reports the same 7 shield findings across all 22 READMEs with no repo's finding set moving.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.