Skip to content

Commit e0fe9ab

Browse files
tedsluisclaude
andcommitted
fix: stop lint_docs.py false-flagging generic btsnoop/btsnooz filename mentions
lint_docs.py's dead-filename check requires every backtick-quoted filename to resolve to a real path, but the project's own prose frequently discusses the two extraction-path naming conventions generically (e.g. "extracted via the raw `btsnoop_hci.log` path", "not `-btsnooz_hci.log`") without a CAP-NNN- prefix — these were never meant to be file references and have been false-flagging as "dead filename reference" across CAPTURE_BLUETOOTH_HCI_SNOOP.md, DESKRESEARCH_FINDINGS.md, TODO.md, and several CAP-NNN-FINDINGS.md/EVENT-NOTES.md files, failing CI's Lint docs check on every push that touches this topic (predates this session). - scripts/lint_docs.py: added GENERIC_LOG_FILENAME_RE, matching the same design pattern as the existing PLACEHOLDER_FILENAME_RE exemption, to skip bare/dash-only `btsnoop_hci.log`/`btsnooz_hci.log` mentions specifically (a real CAP-NNN-prefixed reference is still checked normally). Added CAP-032-btsnooz_hci.log to KNOWN_HISTORICAL_REFERENCES — CAP-032's own Corrections section quotes it as the pre-fix wrong value, same pattern as the existing CAP-005-recoding.mp4 entry. - DESKRESEARCH_FINDINGS.md: reworded one bare `FINDINGS.md` mention (added in this session's audit-findings entry) to the established `CAP-NNN-FINDINGS.md` convention instead of needing a linter exception. Verified clean: `lint_docs: clean — no dead filenames, no unregistered IDs, no stale project name, no missing footers.` Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Bjo12itgeoZW8rPFPXUZvz
1 parent 9e75573 commit e0fe9ab

2 files changed

Lines changed: 20 additions & 1 deletion

File tree

DESKRESEARCH_FINDINGS.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -180,7 +180,7 @@ Status legend (consistent with `PROTOCOL.md` §0):
180180
| awk '$2!=$3 {c++} END{print "mismatches:", c+0}'
181181
```
182182

183-
- **Captures examined:** every capture whose own `FINDINGS.md` already documented an extraction
183+
- **Captures examined:** every capture whose own `CAP-NNN-FINDINGS.md` already documented an extraction
184184
path or truncation result — `CAP-012`, `CAP-013`, `CAP-017`, `CAP-031` (all `btsnooz`-extracted),
185185
`CAP-032` (raw-extracted). (The 2026-08-28 project-wide audit's own re-verification pass additionally
186186
confirmed all other real captures — `CAP-001``CAP-011` excl. `012`/`013`, `CAP-014``CAP-016`,

scripts/lint_docs.py

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,19 @@
3939
# files or IDs — e.g. `CAP-NNN-FINDINGS.md` used as a doc-writing convention.
4040
PLACEHOLDER_FILENAME_RE = re.compile(r"CAP-(NNN|nnn|00n|CAP-\d+)", re.IGNORECASE)
4141

42+
# Generic, un-prefixed mentions of the two btsnoop-log naming conventions
43+
# themselves (raw `btsnoop_hci.log` vs. the `btsnooz.py`-fallback
44+
# `btsnooz_hci.log`, each with or without a leading dash for the
45+
# `CAP-NNN-` prefix they'd normally carry) — prose *about* the naming
46+
# pattern (e.g. "extracted via the raw `btsnoop_hci.log` path"), not a
47+
# reference to any specific file. A real per-capture reference always
48+
# carries its own `CAP-NNN-` prefix and is checked normally; this only
49+
# exempts the bare/dash-only generic form. Found repeatedly false-flagging
50+
# across `CAPTURE_BLUETOOTH_HCI_SNOOP.md`, `DESKRESEARCH_FINDINGS.md`,
51+
# `TODO.md`, and several `CAP-NNN-FINDINGS.md`/`EVENT-NOTES.md` files
52+
# discussing the `CAP-012`/`013`/`017`/`031`/`032` extraction-path finding.
53+
GENERIC_LOG_FILENAME_RE = re.compile(r"^-?btsnoo[pz]_hci\.log$")
54+
4255
# Deliberate historical references this project keeps on purpose (retired
4356
# docs, a corrected typo kept as a "sic"/before-value in a Corrections note,
4457
# an illustrative example filename, an external repo's path quoted for
@@ -58,6 +71,10 @@
5871
"AUDIT_REPORT_2026-08-22.md", # transient audit-report artifact, never committed (2026-08-23);
5972
# its findings live on in the docs/CHANGELOG.md entries that
6073
# cite it by name, same lifecycle as AUDIT_REPORT_2026-08-20.md
74+
"CAP-032-btsnooz_hci.log", # CAP-032-EVENT-NOTES.md's own "Corrections" section quotes this as
75+
# the pre-fix (wrong) value of its Log Metadata table's Log file
76+
# field, kept as a "sic"/before-value — same pattern as the
77+
# CAP-005-recoding.mp4 entry above, not a live reference.
6178
}
6279

6380
# Only lint cross-references to the project's own capture/doc artifacts —
@@ -200,6 +217,7 @@ def check_filenames(files: list[Path]) -> list[str]:
200217
name = match.group(1)
201218
if (
202219
PLACEHOLDER_FILENAME_RE.search(name)
220+
or GENERIC_LOG_FILENAME_RE.match(name)
203221
or name in KNOWN_HISTORICAL_REFERENCES
204222
or Path(name).name in gitignored
205223
):
@@ -212,6 +230,7 @@ def check_filenames(files: list[Path]) -> list[str]:
212230
continue # remote image, not a repo-relative path
213231
if (
214232
PLACEHOLDER_FILENAME_RE.search(name)
233+
or GENERIC_LOG_FILENAME_RE.match(name)
215234
or name in KNOWN_HISTORICAL_REFERENCES
216235
or Path(name).name in gitignored
217236
):

0 commit comments

Comments
 (0)