Flag `//` comment lines that match AI-narration patterns. These are heuristics, not proof. The aim is to surface the comments most likely to violate CLAUDE.md's "label, don't narrate" rule for a human or LLM to review. The `.code-report` header explains the rules so a follow-up LLM
(
lines: list[str], path: Path, fence_mask: list[bool]
)
| 1198 | |
| 1199 | |
| 1200 | def find_ai_narration_violations( |
| 1201 | lines: list[str], path: Path, fence_mask: list[bool] |
| 1202 | ) -> list[Violation]: |
| 1203 | """Flag `//` comment lines that match AI-narration patterns. |
| 1204 | |
| 1205 | These are heuristics, not proof. The aim is to surface the comments |
| 1206 | most likely to violate CLAUDE.md's "label, don't narrate" rule for a |
| 1207 | human or LLM to review. The `.code-report` header explains the rules |
| 1208 | so a follow-up LLM pass can decide per-line.""" |
| 1209 | violations: list[Violation] = [] |
| 1210 | |
| 1211 | for i, line in enumerate(lines): |
| 1212 | if fence_mask[i]: |
| 1213 | continue |
| 1214 | payload = _comment_payload(line) |
| 1215 | if payload is None: |
| 1216 | continue |
| 1217 | # Skip section-header style "//---" banners — those are intentional |
| 1218 | # per CLAUDE.md "98-dash banners separate concern groups". |
| 1219 | stripped_payload = payload.strip() |
| 1220 | if not stripped_payload or set(stripped_payload) <= {"-", "="}: |
| 1221 | continue |
| 1222 | # Skip `// clang-format off/on` and other tooling pragmas. |
| 1223 | if re.match( |
| 1224 | r"^\s*(?:clang-format|code-(?:verify|format)|NOLINT|cppcheck-suppress)", |
| 1225 | payload, |
| 1226 | re.IGNORECASE, |
| 1227 | ): |
| 1228 | continue |
| 1229 | |
| 1230 | for kind, pattern in _AI_PATTERNS: |
| 1231 | if pattern.search(payload): |
| 1232 | violations.append( |
| 1233 | Violation( |
| 1234 | path, |
| 1235 | i + 1, |
| 1236 | f"ai-{kind}", |
| 1237 | f"AI-narration smell ({kind}): {payload.strip()[:80]}", |
| 1238 | ) |
| 1239 | ) |
| 1240 | # One violation per line is enough — the worst pattern wins |
| 1241 | break |
| 1242 | |
| 1243 | # Dash-substitute is orthogonal to the tone patterns: a comment can |
| 1244 | # restate the code AND lean on a spaced double-hyphen. Report it on |
| 1245 | # its own so the worst-pattern break above doesn't mask it. |
| 1246 | if _DASH_SUBSTITUTE_RE.search(payload): |
| 1247 | violations.append( |
| 1248 | Violation( |
| 1249 | path, |
| 1250 | i + 1, |
| 1251 | "comment-dash-substitute", |
| 1252 | "`--` as a sentence dash; rewrite the sentence (comma / " |
| 1253 | "colon / period / parentheses), don't swap em dash for " |
| 1254 | f"`--`: {payload.strip()[:80]}", |
| 1255 | ) |
| 1256 | ) |
| 1257 |
no test coverage detected