Report a Retired Badge Written Inline, Not Only One Defined (#637)

readme_shield_findings scanned reference definitions alone for a retired badge service, so a repo writing it as an inline image rendered the dead badge and reported nothing. The comment above the loop claimed it was scanned wherever it sits, and the selftest case carried that name while testing the reference form only, so the claim and its evidence agreed with each other and not with the code. shield_endpoints already resolves both forms and its docstring records the same lesson; this was the one site that had not taken it.
Three review rounds refined it. The finding text claimed every matching definition renders the badge, which contradicted the comment directly above it, so the wording now follows which of four shapes it is. Attribution moved from the URL to the reference name, because the same endpoint rendered inline leaves a definition unused and reading the URL credited that render to a reference nothing uses. unfenced_text is computed once, so the definitions and the rendered images cannot be read from two views of the document, and the endpoint set is held as a set named by its namespace.
Measured against all 22 cataloged READMEs at every round: shield findings stay at 7 and no verdict or wording moves, since no repo carries either shape. Every new selftest case was A/B tested against the pre-fix function rather than reasoned about.
Raised by Copilot as a suppressed finding on promotion pull request #635.

Author: ptr727

spec/audit.py

@@ -787,13 +787,32 @@ def readme_shield_findings(text, model, entry):
  repo can be measured against.
  """
 findings= []
-defs= {m.group(1): m.group(2) formin_LINK_DEF.finditer(unfenced_text(text))}
+# One unfenced view serves both passes, so the definitions and the rendered images cannot be read from different documents.
+unfenced=unfenced_text(text)
+defs= {m.group(1): m.group(2) formin_LINK_DEF.finditer(unfenced)}
 # A retired badge service is scanned across the whole document rather than per section, since a dead badge is wrong wherever it sits.
 # It renders broken rather than absent, which a visitor reads as a failing build rather than as a stale badge.
+# Both forms are read, since reading definitions alone made an inline badge invisible rather than wrong, which is the reading shield_endpoints already takes for every other shield.
+# A definition is reported even where nothing renders it, because a retired service left in the reference block is removed with the badge rather than after it.
+# Which of the four it is decides the wording, since a definition nothing renders is not rendering anything and saying so sends the reader looking for a badge that is not on the page.
+# Attribution is by reference name and never by URL: the same endpoint rendered inline leaves this definition unused, so reading the URL alone would credit a render to a reference nothing uses.
+# A set rather than the list shield_endpoints returns, since every use here is membership or a difference, and the names say which of the two namespaces each holds.
+rendered_urls=set(shield_endpoints(unfenced, defs))
+used_refs= {m.group(1) formin_MD_IMAGE_REF.finditer(unfenced)}
 fordepinmodel.get("deprecatedShields", []):
+defined_urls=set()
 forref, urlinsorted(defs.items()):
 ifdep["match"] inurl:
-findings.append(("LETTER", f"readme: `[{ref}]` renders {dep['label']}, which is retired - {dep['reason']} (spec/readme-structure.md)"))
+defined_urls.add(url)
+ifrefinused_refs:
+verb=f"renders {dep['label']}"
+elifurlinrendered_urls:
+verb=f"defines {dep['label']} and it is rendered elsewhere"
+else:
+verb=f"defines {dep['label']} and nothing renders it"
+findings.append(("LETTER", f"readme: `[{ref}]` {verb}, which is retired - {dep['reason']} (spec/readme-structure.md)"))
+forurlinsorted({uforuinrendered_urlsifdep["match"] inu} -defined_urls):
+findings.append(("LETTER", f"readme: an inline image renders {dep['label']}, which is retired - {dep['reason']} (spec/readme-structure.md)"))
 targets= {(p.get("target") ifisinstance(p, dict) elsep) forpinentry.get("publish", [])}
 secrets=set(entry.get("requiredSecrets", []))
 want= []
@@ -1736,6 +1755,17 @@ def _selftest():
  ("a fenced badge sample does not satisfy a required shield", conformant.replace("[![GitHub Release][c]][x]\\\n", "```md\n[![GitHub Release][c]][x]\n```\n"), {}, 1),
  ("a fenced license shield does not trip the exclusive rule", conformant.replace("## Overview", "```md\n![License][license-shield]\n```\n\n## Overview"), {}, 0),
  ("a retired badge service is reported wherever it sits", conformant.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),
+# The case above named every placement and read only the reference block, so an inline badge was invisible rather than wrong.
+# That is the reading shield_endpoints already takes for every other shield, and this one had not taken it.
+ ("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),
+# The wording follows which of the three shapes it is, since a definition nothing renders is not rendering anything.
+# Saying it renders sends the reader looking for a badge that is not on the page.
+ ("an unrendered definition says so rather than claiming a render", conformant.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, "nothing renders it"),
+ ("a rendered definition says renders", 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, "renders the byob"),
+# The same endpoint rendered inline leaves this definition unused, so attributing by URL would credit the render to a reference nothing uses.
+ ("an unused definition beside an inline render is not credited with it", conformant.replace("[![Last Commit][b]][x]", "[![Last Commit][b]][x]\\\n![Last Build](https://byob.yarr.is/o/r/lastbuild)").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, "rendered elsewhere"),
  ("the pre-release shield is told from the release shield by its query", conformant.replace("?include_prereleases&label=GitHub%20Pre-Release", "?label=Another%20Release"), {}, 1),
 # The license shield is an ordinary member of the base class, addressed to a different section.
  ("the license shield in the closing License section", conformant, {}, 0),
@@ -1747,12 +1777,18 @@ def _selftest():
  ("inline shields count as present", inline_all.replace("PLACEHOLDER-a", "github/actions/workflow/status/o/r").replace("PLACEHOLDER-b", "github/last-commit/o/r").replace("PLACEHOLDER-c", "github/v/release/o/r").replace("PLACEHOLDER-d", "github/v/release/o/r?include_prereleases").replace("PLACEHOLDER-license-shield", "github/license/o/r"), {}, 0),
  ("an inline shield in the wrong section is still exclusive", conformant.replace("## Overview", "![License](https://img.shields.io/github/license/o/r)\n\n## Overview"), {}, 1),
  ]
-forlabel, text, ent, wantninshield_cases:
+# A case may carry a fifth element, a substring the finding text must contain.
+# A count alone cannot tell one wording from another, and the wording is the whole subject of some of these cases.
+forcaseinshield_cases:
+label, text, ent, wantn=case[:4]
+want_text=case[4] iflen(case) >4elseNone
 got=readme_shield_findings(text, rm, ent)
-iflen(got) !=wantn:
+good=len(got) ==wantnand (want_textisNoneorany(want_textintfor_, tingot))
+ifnotgood:
 ok=False
-print(f" {'ok 'iflen(got) ==wantnelse'FAIL'} want={wantn} got={len(got)} readme shields: {label}")
-iflen(got) !=wantn:
+shown=f"want={wantn}"ifwant_textisNoneelsef"want={wantn}+'{want_text}'"
+print(f" {'ok 'ifgoodelse'FAIL'}{shown} got={len(got)} readme shields: {label}")
+ifnotgood:
 for_, tingot:
 print(f" {t}")