Skip to content

doc-check: referenced=/early-exit short-circuit silently skips link-rot gates #465

Description

@trilamsr

Background

scripts/doc-check.sh (line ~161) has an early-exit guard:

referenced=$(grep -hoE '\b(Test|Fuzz|Benchmark)[A-Z_][A-Za-z0-9_]*[A-Za-z0-9]\b' "${scan_paths[@]}" 2>/dev/null | sort -u || true)
if [ -z "$referenced" ]; then
  echo "doc-check: no test identifiers referenced — nothing to verify"
  exit 0
fi

This is intended to skip the test-identifier-resolution block when no doc references a Go test symbol. But the script's later blocks — markdown link-rot, etc. — all sit BELOW this guard, so when $referenced happens to be empty (the current state on main, since the scanned scan_paths don't currently mention any Test*/Fuzz*/Benchmark* identifiers), every gate below the guard is silently skipped.

Concrete impact

  • The markdown link-rot gate (added in a prior PR) never runs on main.
  • Running the script with the early-exit temporarily disabled surfaces real dead links (e.g. in docs/FOLLOWUPS.md).
  • The YAML link-rot gate added in PR ci(doc-check): scan YAML cross-links for repo-relative rot (#455) #459 had to be placed above this early-exit as a workaround — explicitly noted in the gate's comment block.

Fix

Move the [ -z \$referenced ] && exit 0 short-circuit so it only skips the test-identifier-resolution block that needs it (the one that consumes \$referenced), not the unrelated link-rot gates below. Pattern: scope the guard to wrap only the comm-orphans check, not the rest of the file.

Why separate

PR #459 (YAML link-rot gate) deliberately did not roll this in because (a) the markdown gate's dead-link surface needs its own fix sweep, and (b) reshaping the script's control flow is a separate review concern from "add a new gate." Placement workaround in #459 is documented in scripts/doc-check.sh comment block.

Verification once fixed

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions