Skip to content

[finding] The docs-drift PR comment still renders all unreachable bridge rows as one cause — the advisory path passes no ceiling, so causes reads unmeasured there #11867

Description

@os-steve

Observed while implementing #11178 (PR #11865). Filed unassigned and unlabelled for grading. ⛔ Not a claim on anyone's time.

The reading

PR #11865 splits --bridge-coverage's unreachable rows into three derived causes (discovery-gap / no-in-repo-registrar / undecided) so that the auth ledger's 56 of 56 stops reading like the rest ledger's 46 of 87. That split is computed against a ceiling — every path: any packages/** file declares — and bridgeCoverageFrom takes that ceiling as an optional argument.

Only the --bridge-coverage CLI arm passes one. The advisory path does not:

// affected-docs.mjs, the PHASE 2 advisory run
bridgeCoverage = bridgeCoverageFrom(ledgers, registrarByTail.keys());

so on that path every ledger's cause is unmeasured and the three counts are null — honest, by design, but it means the PR-comment renderer never sees the split. .github/workflows/docs-drift-check.yml:262 still says:

the other 177 have no registrar path: tail to select them

That sentence is accurate about the mechanism and does not claim remediability — this is not a wrong number. But it is the surface a human actually reads on a PR, and it presents one population where there are measurably three: on 589758d22, 14 remediable by discovery, 56 with no in-repo registrar anywhere on the surface, 107 undecided.

Why it was left out of PR #11865

Scope: that card's ruled deliverable was what --bridge-coverage reports. Wiring the advisory path is a separate decision with a real cost — the ceiling masks ~1093 files (~1.4s measured), and the advisory run happens per-PR whenever a change carries a bridgeable symbol, whereas --bridge-coverage is a single diff-free gate step.

The shape, if taken

Two hops, both small:

  1. pass a ceiling on the advisory path (or decide the cost is not worth paying and leave unmeasured — a legitimate answer);
  2. give data.bridgeCoverage.causes a render branch in docs-drift-check.yml. [finding] docs-drift's route-bridge exclusions are silent — only the cross-cutting CAP publishes what it withheld, the two KIND rules do not #9433 measured that a JSON key with no render branch is half-wired — published while no reader sees it — and affected-docs.mjs --self-test already pins the bridgeCoverage key at both ends for exactly that reason. A causes render branch would deserve the same pin.

Not claimed

  • No opinion on whether the advisory should pay the ceiling cost. The measurement is offered so the call is made on numbers.
  • Whether the drift comment's readers actually want the breakdown, versus a single "and N of these are structural" clause, was not investigated.

Refs

#11178 · PR #11865 (where the split landed) · #9433 (the half-wired-key rule) · #9747

Activity

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

Metadata

Metadata

Assignees

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions