From bfbaae6f0162dd4adb0ce8bfe1f0bfef612f2ad4 Mon Sep 17 00:00:00 2001 From: anonsaber Date: Tue, 29 Sep 2026 09:35:08 +0800 Subject: [PATCH] fix(docs_check): make audit_paths' brace-glob handling actually work MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two advertised mechanisms were dead code, found by self-testing the checker rather than trusting its 0-error output: 1. variants() could never see a brace glob. Its segment class excluded ',', so `channel/telegram/{mod,commands}.rs` tokenised as two bogus fragments, `channel/telegram/` and `commands}.rs`. The glob was still caught as an error, but only the first alternative was ever reported and it was reported under the wrong filename — a reader chasing that error would not find `commands}.rs` in the document. ',' is now in the segment class and removed from PLACEHOLDER, so the glob stays whole, expands per variant, and the message shows the glob alongside the failing alternative: `channel/telegram/{mod,commands}.rs -> channel/telegram/mod.rs`. 2. The docstring attributed the non-path exclusions to is_noise(). They are not: JMAP methods (Email/changes), media types (application/json), dotted hosts and template URLs are dropped by the whole-span rule, and absolute paths never arrive at all because TOKEN's lookbehind refuses to start a match after a '/'. is_noise() is reachable fallback for dot-prefixed URL parts and whole-span seg/ tokens. The docstring now says which rule does which, so the next reader is not pointed at the wrong function. Verified, not assumed. A scratch doc with src/util/, src/domain/llm/client.rs, tests/telegram_dispatch.rs, run_mode.rs and one brace glob yields exactly 5 errors and exit 1. src/ai.rs, src/domain/jmap/client.rs, docs/todo.md (git-deleted), a stalwartlabs/ citation and docker-compose.yml all pass, as do Email/changes, application/json, api.telegram.org/bot, 200/503, .well-known/jmap, {jmap_origin}/.well-known/jmap and a log-format string. GATE-DOCS still PASS (6/6), 362 path-refs checked, 0 errors. --- scripts/docs_check/audit_paths.py | 44 +++++++++++++++++++++---------- 1 file changed, 30 insertions(+), 14 deletions(-) diff --git a/scripts/docs_check/audit_paths.py b/scripts/docs_check/audit_paths.py index 6cbcab4..8ab787f 100644 --- a/scripts/docs_check/audit_paths.py +++ b/scripts/docs_check/audit_paths.py @@ -38,15 +38,23 @@ What it does NOT prove (this check is defined by string patterns, after all); those are not documentation claims. -Non-path shapes that look like paths are excluded by is_noise(), and a -`seg/` token only counts as a directory reference when it is the whole -inline-code span. Both rules are structural rather than denylisted: is_noise -recognises the shapes that cannot be repo-relative paths (absolute paths and -URIs, dot-prefixed URL parts, dotted hosts, media types, JMAP method names, -all-numeric pairs, shell and glob fragments), and the whole-span rule means -`Email/changes`, `application/json` and `method/path/origin/失败类别` are never -mistaken for a directory. Adding a special case to either should make you -suspect the document instead. +Non-path shapes that look like paths are excluded by two structural rules +rather than a denylist: + +- A `seg/` token only counts as a directory reference when it IS the whole + inline-code span. TOKEN happily returns the `Email/` prefix of + `Email/changes`, the `application/` of `application/json` and the + `api.telegram.org/` of `api.telegram.org/bot`; none of those are the whole + span, so they are dropped here. This is what keeps JMAP methods, media + types, dotted hosts, `{jmap_origin}/.well-known/jmap` templates and + `method/path/origin/失败类别` log formats out. Absolute paths are excluded + one step earlier by TOKEN's lookbehind, which refuses to start a match after + a '/', so `/api/status` never reaches the scanner at all. +- is_noise() then catches the remainder that survives that test: dot-prefixed + URL parts (`.well-known/jmap`), and, for whole-span `seg/` tokens, media + types, dotted hosts, all-numeric pairs and shell/glob fragments. That last + list is fallback, not the main defence — if you find yourself wanting to add + a case there, suspect the document instead. """ import os @@ -81,10 +89,13 @@ ROOT_DIRS = [ EXTS = "rs|js|mjs|ts|tsx|json|toml|ya?ml|md|sh|sql|cfg|lock|html|css|proto|txt" # A file token (ends in a known extension) or a directory token (ends in '/'). +# ',' is in the segment class so a brace glob like `{mod,commands}.rs` is kept +# whole and expanded by variants(); drop it and the glob is mangled into two +# bogus tokens, one of which does not resolve and reports the wrong filename. TOKEN = re.compile( r"(? {v}" + errors.append(f"{rel}:{i} `{shown}` does not resolve " f"(ROOT_DIRS, git history, or CONVENTIONAL)") break print(f"=== PATH AUDIT ({len(errors)} errors, "