fix(docs_check): make audit_paths' brace-glob handling actually work
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.
This commit is contained in:
parent
4c7cbe66b9
commit
bfbaae6f01
|
|
@ -38,15 +38,23 @@ What it does NOT prove
|
||||||
(this check is defined by string patterns, after all); those are not
|
(this check is defined by string patterns, after all); those are not
|
||||||
documentation claims.
|
documentation claims.
|
||||||
|
|
||||||
Non-path shapes that look like paths are excluded by is_noise(), and a
|
Non-path shapes that look like paths are excluded by two structural rules
|
||||||
`seg/` token only counts as a directory reference when it is the whole
|
rather than a denylist:
|
||||||
inline-code span. Both rules are structural rather than denylisted: is_noise
|
|
||||||
recognises the shapes that cannot be repo-relative paths (absolute paths and
|
- A `seg/` token only counts as a directory reference when it IS the whole
|
||||||
URIs, dot-prefixed URL parts, dotted hosts, media types, JMAP method names,
|
inline-code span. TOKEN happily returns the `Email/` prefix of
|
||||||
all-numeric pairs, shell and glob fragments), and the whole-span rule means
|
`Email/changes`, the `application/` of `application/json` and the
|
||||||
`Email/changes`, `application/json` and `method/path/origin/失败类别` are never
|
`api.telegram.org/` of `api.telegram.org/bot`; none of those are the whole
|
||||||
mistaken for a directory. Adding a special case to either should make you
|
span, so they are dropped here. This is what keeps JMAP methods, media
|
||||||
suspect the document instead.
|
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
|
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"
|
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 '/').
|
# 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(
|
TOKEN = re.compile(
|
||||||
r"(?<![\w./:-])(?:"
|
r"(?<![\w./:-])(?:"
|
||||||
r"(?:[A-Za-z0-9_.{}\-]+/)*[A-Za-z0-9_.{}\-]+\.(?:" + EXTS + r")"
|
r"(?:[A-Za-z0-9_.{},\-]+/)*[A-Za-z0-9_.{},\-]+\.(?:" + EXTS + r")"
|
||||||
r"|(?:[A-Za-z0-9_.{}\-]+/){1,}"
|
r"|(?:[A-Za-z0-9_.{},\-]+/){1,}"
|
||||||
r")"
|
r")"
|
||||||
)
|
)
|
||||||
INLINE_CODE = re.compile(r"`([^`\n]+)`")
|
INLINE_CODE = re.compile(r"`([^`\n]+)`")
|
||||||
|
|
@ -114,8 +125,9 @@ JMAP_METHOD = re.compile(r"^[A-Z][A-Za-z]*\/[a-z][A-Za-z]*$")
|
||||||
# Dotted domains (api.telegram.org, crates.io) and numeric code pairs
|
# Dotted domains (api.telegram.org, crates.io) and numeric code pairs
|
||||||
# (200/503) are classified structurally inside is_noise.
|
# (200/503) are classified structurally inside is_noise.
|
||||||
#
|
#
|
||||||
# Shell or glob placeholders that are not real paths.
|
# Shell or glob placeholders that are not real paths. No ',' here: brace globs
|
||||||
PLACEHOLDER = re.compile(r"[\s()*,?]")
|
# legitimately contain commas (see TOKEN) and must reach resolve(), not noise.
|
||||||
|
PLACEHOLDER = re.compile(r"[\s()*?]")
|
||||||
|
|
||||||
|
|
||||||
def is_noise(tok):
|
def is_noise(tok):
|
||||||
|
|
@ -213,7 +225,11 @@ def main():
|
||||||
or ("conventional name" if v in CONVENTIONAL else None)
|
or ("conventional name" if v in CONVENTIONAL else None)
|
||||||
)
|
)
|
||||||
if not verdict:
|
if not verdict:
|
||||||
errors.append(f"{rel}:{i} `{v}` does not resolve "
|
# Show the expansion too, or a brace glob would
|
||||||
|
# report only its first alternative and hide the
|
||||||
|
# rest.
|
||||||
|
shown = v if v == tok else f"{tok} -> {v}"
|
||||||
|
errors.append(f"{rel}:{i} `{shown}` does not resolve "
|
||||||
f"(ROOT_DIRS, git history, or CONVENTIONAL)")
|
f"(ROOT_DIRS, git history, or CONVENTIONAL)")
|
||||||
break
|
break
|
||||||
print(f"=== PATH AUDIT ({len(errors)} errors, "
|
print(f"=== PATH AUDIT ({len(errors)} errors, "
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue