From ec67370612e8ab2db84a460b1ed0c6ba6029def0 Mon Sep 17 00:00:00 2001 From: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Tue, 27 Oct 2026 21:21:10 -0400 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20docs:=20check-docs-citations=20--fi?= =?UTF-8?q?x=20re-anchors=20drifted=20citations=20by=20Go=20declaration?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- AGENTS.md | 2 +- changelog.d/added-14713.md | 1 + src/scripts/check-docs-citations.py | 215 +++++++++++++++++++---- src/scripts/test-check-docs-citations.sh | 126 ++++++++++++- 4 files changed, 306 insertions(+), 38 deletions(-) create mode 100644 changelog.d/added-14713.md diff --git a/AGENTS.md b/AGENTS.md index 56a83fb627..967cc2d9a8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,4 +15,4 @@ These rules apply to every AI agent (hive agents, Copilot CLI, Claude Code, Code - Keep changes surgical and PR-sized; one concern per PR. - Every PR with a user-visible `src/` code change needs a `changelog.d/-.md` fragment (`added|changed|deprecated|fixed|security`) whose body is a single `- ` bullet. Changes outside `src/` (root-level docs, `changelog.d/`, `.github/`), plus `src/docs/`, `*_test.go` files, and `src/{deploy,scripts}/test[-_]*.sh` scripts, are exempt automatically (`src/scripts/check-changelog-fragment.sh` is the source of truth for the exact set); other test-adjacent changes (e.g., `testdata/` fixtures, non-`_test.go` test helpers) and non-user-visible `src/` code changes (refactors, dependency bumps) need the `no-changelog` label instead. `changelog.d/` is at the repository root, not under `src/` — `src/changelog.d/` is never compiled and the guard rejects it. - Sign commits (`git commit -s`); PR titles start with an emoji (`✨` feature, `🐛` fix, `📖` docs, `📝` proposal, `🌱` chore, `⚠️` breaking) — `📝` is for proposals only; a docs PR is `📖 docs: …`. -- Do not edit `src/docs/api-reference.md` line citations by hand; CI's citation guard reports drift and the fix is `bash src/scripts/check-api-reference-citations.sh --fix` — run it only when CI tells you it drifted. The required `changelog-fragment-guard` check runs it (non-fix) when a PR edits a hub or dashboard `server.go` or their `static/` pages, so the PR that causes drift goes red. +- Do not hand-edit `src/docs` file:line citations (including `src/docs/api-reference.md`); when CI's citation guard reports drift, run `python3 src/scripts/check-docs-citations.py --fix` first — it runs `check-api-reference-citations.sh --fix` for `api-reference.md` and re-anchors other `.go` citations by their backticked Go declaration anchor. Only fall back to a manual edit for citations it still reports as `DRIFT`/`UNRESOLVED`, and run it only when CI tells you citations drifted. The required `changelog-fragment-guard` check runs it (non-fix) when a PR edits a hub or dashboard `server.go` or their `static/` pages, so the PR that causes drift goes red. diff --git a/changelog.d/added-14713.md b/changelog.d/added-14713.md new file mode 100644 index 0000000000..00f610995f --- /dev/null +++ b/changelog.d/added-14713.md @@ -0,0 +1 @@ +- `python3 src/scripts/check-docs-citations.py --fix` now repairs drifted `src/docs` line-range citations into `.go` files instead of only delegating to the `api-reference.md` route fixer: it resolves the first backticked symbol anchor on the citing line to a single top-level Go declaration (`func X(`, `func (recv) X(`, `type X`, `const X`, `var X`) and rewrites the range to start at that declaration and end at the first line that covers every anchor. It fails closed — zero or several matching declarations, an anchor outside the declaration, a non-`.go` target, or a line without anchors leaves the citation untouched and still reported as `DRIFT` with a non-zero exit — and a second `--fix` run is a no-op. This ends the hand-typed docs PRs for moved functions (#14713). diff --git a/src/scripts/check-docs-citations.py b/src/scripts/check-docs-citations.py index 301d633f3e..fcdc65f8b1 100755 --- a/src/scripts/check-docs-citations.py +++ b/src/scripts/check-docs-citations.py @@ -12,10 +12,21 @@ Usage: src/scripts/check-docs-citations.py [--fix] [docs-dir] (default docs-dir: src/docs) ---fix delegates to the older api-reference citation fixer, which has enough -route/path context to rewrite moved route registrations. Generic docs citations -verify existence/range, plus a lightweight content anchor when the citing line -names a backticked symbol near the citation. +Generic docs citations verify existence/range, plus a lightweight content +anchor when the citing line names a backticked symbol near the citation. + +--fix first delegates api-reference.md to check-api-reference-citations.sh +--fix (route-registration aware), then re-anchors drifted generic citations by +Go declaration (#14713). A drifted citation is rewritten only when all of these +hold, otherwise it is left untouched and still reported as DRIFT: + - the cited file is a .go file; + - the citing line carries at least one backticked symbol anchor; + - the FIRST anchor names exactly one top-level declaration in that file + (`func X(`, `func (recv) X(`, `type X`, `const X`, `var X`); + - every anchor appears inside that declaration's span. +The new range starts at the declaration and ends at the first line by which +every anchor has appeared, so it always verifies clean under the checker and a +second --fix run is a no-op. --fix exits non-zero while any drift remains. """ from __future__ import annotations @@ -55,6 +66,7 @@ class Citation: line_spec: str line: str match_end: int + spec_start: int = -1 def parse_line_spec(spec: str) -> list[tuple[int, int]]: @@ -166,10 +178,104 @@ def iter_citations(docs_dir: Path) -> list[Citation]: for match in CITATION_RE.finditer(line): cited_path = match.group(1) if is_probably_repo_local(cited_path): - citations.append(Citation(doc, line_no, cited_path, match.group(2), line, match.end())) + citations.append( + Citation(doc, line_no, cited_path, match.group(2), line, match.end(), match.start(2)) + ) return citations +DECL_OPEN_RE = re.compile(r"[{(\[,]\s*$") +DECL_CLOSE_RE = re.compile(r"^(\}|\)\s*$)") +LEADING_IDENT_RE = re.compile(r"^(?:[A-Za-z_][A-Za-z0-9_]*\.)*([A-Za-z_][A-Za-z0-9_]*)") + + +def anchor_identifier(anchor: str) -> str | None: + # `Foo`, `Foo()`, `Foo(ctx)`, `pkg.Foo` and `Recv.Method` all name Foo/Method. + match = LEADING_IDENT_RE.match(anchor.strip()) + return match.group(1) if match else None + + +def strip_go_line_comment(line: str) -> str: + idx = line.find("//") + return line if idx < 0 else line[:idx] + + +def go_declaration_spans(lines: list[str], name: str) -> list[tuple[int, int]]: + """Return 1-based (start, end) spans of top-level Go declarations of name. + + Relies on gofmt layout: top-level declarations start at column 0 and a + multi-line declaration closes with `}` or a lone `)` at column 0. + """ + ident = re.escape(name) + decl_re = re.compile( + r"^(?:func\s+" + ident + r"\s*[\[(]" + r"|func\s*\([^)]*\)\s*" + ident + r"\s*[\[(]" + r"|(?:type|const|var)\s+" + ident + r"\b)" + ) + spans: list[tuple[int, int]] = [] + for idx, line in enumerate(lines): + if not decl_re.match(line): + continue + start = idx + 1 + end: int | None = start + if DECL_OPEN_RE.search(strip_go_line_comment(line).rstrip()): + end = None + for j in range(idx + 1, len(lines)): + if DECL_CLOSE_RE.match(lines[j]): + end = j + 1 + break + if end is None: + # Unterminated declaration: record an unusable span so the caller + # fails closed instead of guessing an end line. + spans.append((start, 0)) + else: + spans.append((start, end)) + return spans + + +def reanchor_go_citation(target: Path, anchors: list[str]) -> tuple[str | None, str]: + """Compute a replacement line spec for a drifted citation, or explain why not.""" + if target.suffix != ".go": + return None, "not a .go file" + if not anchors: + return None, "no backticked symbol anchor on the citing line" + name = anchor_identifier(anchors[0]) + if not name: + return None, f"first anchor {anchors[0]!r} is not an identifier" + with target.open("r", encoding="utf-8", errors="ignore") as fh: + lines = fh.readlines() + spans = go_declaration_spans(lines, name) + if len(spans) != 1: + return None, f"found {len(spans)} top-level declarations of {name}, need exactly 1" + start, end = spans[0] + if end < start: + return None, f"cannot find the end of the {name} declaration" + new_end = start + for anchor in anchors: + hit = next((n for n in range(start, end + 1) if anchor in lines[n - 1]), None) + if hit is None: + return None, f"anchor {anchor} is not inside the {name} declaration ({start}-{end})" + new_end = max(new_end, hit) + return (f"{start}" if new_end == start else f"{start}-{new_end}"), "" + + +def apply_spec_rewrites(rewrites: list[tuple[Citation, str]]) -> None: + by_doc: dict[Path, list[tuple[Citation, str]]] = {} + for citation, new_spec in rewrites: + by_doc.setdefault(citation.doc, []).append((citation, new_spec)) + for doc, items in by_doc.items(): + lines = doc.read_text(encoding="utf-8").splitlines(keepends=True) + # Rewrite right-to-left so earlier offsets on the same line stay valid. + for citation, new_spec in sorted(items, key=lambda it: (it[0].line_no, it[0].spec_start), reverse=True): + line = lines[citation.line_no - 1] + s0 = citation.spec_start + s1 = s0 + len(citation.line_spec) + if line[s0:s1] != citation.line_spec: + continue + lines[citation.line_no - 1] = line[:s0] + new_spec + line[s1:] + doc.write_text("".join(lines), encoding="utf-8") + + def run_api_reference_fix(script_dir: Path, docs_dir: Path) -> int: api_doc = docs_dir / "api-reference.md" checker = script_dir / "check-api-reference-citations.sh" @@ -178,27 +284,11 @@ def run_api_reference_fix(script_dir: Path, docs_dir: Path) -> int: return subprocess.call(["bash", str(checker), "--fix", str(api_doc)]) -def main(argv: list[str]) -> int: - parser = argparse.ArgumentParser(description="Verify repo-local file:line citations in src/docs Markdown.") - parser.add_argument("docs_dir", nargs="?", default=None) - parser.add_argument("--fix", action="store_true", help="run safe fixers where available (currently api-reference.md)") - args = parser.parse_args(argv) - - script_dir = Path(__file__).resolve().parent - src_root = script_dir.parent - repo_root = src_root.parent - docs_dir = Path(args.docs_dir) if args.docs_dir else src_root / "docs" - if not docs_dir.is_absolute(): - docs_dir = (Path.cwd() / docs_dir).resolve() - - if not docs_dir.is_dir(): - print(f"cannot find docs directory at {docs_dir}", file=sys.stderr) - return 2 - - fix_rc = run_api_reference_fix(script_dir, docs_dir) if args.fix else 0 - - resolver = Resolver(repo_root, src_root) +def verify_citations( + docs_dir: Path, resolver: Resolver, repo_root: Path, report: bool +) -> tuple[int, int, int, list[tuple[Citation, Path]]]: checked = skipped = failed = 0 + drifted: list[tuple[Citation, Path]] = [] for citation in iter_citations(docs_dir): target, error = resolver.resolve(citation.cited_path, citation.doc) display_doc = citation.doc.relative_to(repo_root) if citation.doc.is_relative_to(repo_root) else citation.doc @@ -206,7 +296,8 @@ def main(argv: list[str]) -> int: if error and error.startswith("unresolved basename-only"): skipped += 1 continue - print(f"DRIFT {display_doc}:{citation.line_no} {citation.cited_path}:{citation.line_spec} ({error})", file=sys.stderr) + if report: + print(f"DRIFT {display_doc}:{citation.line_no} {citation.cited_path}:{citation.line_spec} ({error})", file=sys.stderr) failed += 1 continue @@ -219,12 +310,14 @@ def main(argv: list[str]) -> int: if bad_ranges: rel_target = target.relative_to(repo_root) if target.is_relative_to(repo_root) else target ranges = ", ".join(f"{s}" if s == e else f"{s}-{e}" for s, e in bad_ranges) - print( - f"DRIFT {display_doc}:{citation.line_no} {citation.cited_path}:{citation.line_spec} " - f"-> {rel_target} has {total_lines} lines; out of range: {ranges}", - file=sys.stderr, - ) + if report: + print( + f"DRIFT {display_doc}:{citation.line_no} {citation.cited_path}:{citation.line_spec} " + f"-> {rel_target} has {total_lines} lines; out of range: {ranges}", + file=sys.stderr, + ) failed += 1 + drifted.append((citation, target)) continue anchors = citation_anchors(citation.line, citation.match_end) @@ -232,17 +325,65 @@ def main(argv: list[str]) -> int: window = source_line_window(target, ranges) if not any(anchor in window for anchor in anchors): rel_target = target.relative_to(repo_root) if target.is_relative_to(repo_root) else target - print( - f"DRIFT {display_doc}:{citation.line_no} {citation.cited_path}:{citation.line_spec} " - f"-> {rel_target} lacks anchor(s) near cited range: {', '.join(anchors)}", - file=sys.stderr, - ) + if report: + print( + f"DRIFT {display_doc}:{citation.line_no} {citation.cited_path}:{citation.line_spec} " + f"-> {rel_target} lacks anchor(s) near cited range: {', '.join(anchors)}", + file=sys.stderr, + ) failed += 1 + drifted.append((citation, target)) continue checked += 1 else: checked += 1 + return checked, skipped, failed, drifted + + +def main(argv: list[str]) -> int: + parser = argparse.ArgumentParser(description="Verify repo-local file:line citations in src/docs Markdown.") + parser.add_argument("docs_dir", nargs="?", default=None) + parser.add_argument("--fix", action="store_true", help="rewrite drifted citations that can be re-anchored safely (api-reference.md routes, Go declarations)") + args = parser.parse_args(argv) + + script_dir = Path(__file__).resolve().parent + src_root = script_dir.parent + repo_root = src_root.parent + docs_dir = Path(args.docs_dir) if args.docs_dir else src_root / "docs" + if not docs_dir.is_absolute(): + docs_dir = (Path.cwd() / docs_dir).resolve() + + if not docs_dir.is_dir(): + print(f"cannot find docs directory at {docs_dir}", file=sys.stderr) + return 2 + + fix_rc = run_api_reference_fix(script_dir, docs_dir) if args.fix else 0 + + resolver = Resolver(repo_root, src_root) + if args.fix: + _, _, _, drifted = verify_citations(docs_dir, resolver, repo_root, report=False) + rewrites: list[tuple[Citation, str]] = [] + for citation, target in drifted: + display_doc = citation.doc.relative_to(repo_root) if citation.doc.is_relative_to(repo_root) else citation.doc + new_spec, reason = reanchor_go_citation(target, citation_anchors(citation.line, citation.match_end)) + if new_spec is None or new_spec == citation.line_spec: + print( + f"UNRESOLVED {display_doc}:{citation.line_no} {citation.cited_path}:{citation.line_spec} " + f"({reason or 'no better range'})", + file=sys.stderr, + ) + continue + rewrites.append((citation, new_spec)) + print( + f"FIXED {display_doc}:{citation.line_no} " + f"{citation.cited_path}:{citation.line_spec} => {citation.cited_path}:{new_spec}" + ) + if rewrites: + apply_spec_rewrites(rewrites) + + checked, skipped, failed, _ = verify_citations(docs_dir, resolver, repo_root, report=True) + if failed == 0 and fix_rc == 0: msg = f"docs citations: {checked} repo-local file:line reference(s) verified" if skipped: @@ -251,6 +392,8 @@ def main(argv: list[str]) -> int: return 0 print(f"docs citations: {failed} drifted citation(s); {checked} verified; {skipped} skipped.", file=sys.stderr) + if not args.fix: + print("Run: python3 src/scripts/check-docs-citations.py --fix", file=sys.stderr) return 1 diff --git a/src/scripts/test-check-docs-citations.sh b/src/scripts/test-check-docs-citations.sh index 88740deaef..666f10a72e 100755 --- a/src/scripts/test-check-docs-citations.sh +++ b/src/scripts/test-check-docs-citations.sh @@ -1,6 +1,7 @@ #!/usr/bin/env bash # test-check-docs-citations.sh — exercises check-docs-citations.py against -# fixture Markdown trees with valid, missing-file, and out-of-range citations. +# fixture Markdown trees with valid, missing-file, and out-of-range citations, +# plus the --fix Go-declaration re-anchoring and its fail-closed rules (#14713). set -u -o pipefail HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" @@ -119,6 +120,129 @@ if python3 "$CHECKER" "$DOCS" >/dev/null 2>&1; then else bad "fenced examples should be ignored" fi +rm -f "${DOCS}/fenced.md" + +# --fix: re-anchor drifted citations by unique top-level Go declaration. +cat > "${FIXTURE_SRC}/pkg/widget/moved.go" <<'EOF' +package widget + +// padding +// padding +// padding +// padding +// padding +// padding + +func Moved(n int) int { + total := 0 + for i := 0; i < n; i++ { + total += i + } + return total +} + +type Grown struct { + A int + B int + C int + D int + E int + F int + Tail string +} + +func Dup() {} + +type Widget struct{} + +func (w *Widget) Dup() {} +EOF +cat > "${FIXTURE_SRC}/pkg/widget/run.sh" <<'EOF' +#!/bin/sh +# padding +# padding +# padding +# padding +# padding + +helper() { + : +} +EOF + +# run_fix : writes the doc, runs --fix, and leaves +# rc/output in globals for the caller. +run_fix() { + printf '# Fix\n\n%s\n' "$2" > "${DOCS}/$1" + set +e + output="$(python3 "$CHECKER" --fix "$DOCS" 2>&1)" + rc=$? + set -e +} + +# expect_untouched