Skip to content
Back to search

cctools-plugins

SkillWorks with Claude CodeGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pchalasani--claude-code-tools/badge.svg)](/listings/pchalasani--claude-code-tools)

HTML

<a href="/listings/pchalasani--claude-code-tools"><img src="/api/listings/pchalasani--claude-code-tools/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 69 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "cctools-plugins",
  3. "version": "1.0.0",
  4. "owner": {
  5. "name": "Prasad Chalasani"
  6. },
  7. "plugins": [
  8. {
  9. "name": "visual-brief",
  10. "source": "./plugins/visual-brief",
  11. "description": "Quiet milestone reminders for Visual Brief publishers"
  12. },
  13. {
  14. "name": "safety-hooks",
  15. "source": "./plugins/safety-hooks",
  16. "description": "Provides safety guards to block or require confirmation for risky CLI operations (e.g., rm, destructive git actions, .env access, large file operations)"
  17. },
  18. {
  19. "name": "aichat",
  20. "source": "./plugins/aichat",
  21. "description": "Adds `aichat`-related capabilities (agent support, reusable skills, hooks, and a slash command) for continuing work in CLI agent sessions without compaction, and for searching sessions"
  22. },
  23. {
  24. "name": "tmux-cli",
  25. "source": "./plugins/tmux-cli",
  26. "description": "Introduces tmux-cli skill for interacting with CLI scripts and other code agents inside tmux panes using the `tmux-cli` command"
  27. },
  28. {
  29. "name": "workflow",
  30. "source": "./plugins/workflow",
  31. "description": "Workflow utilities and agents including code walkthrough tools, work logging, issue specification helpers, and a UI testing agent for browser-based validation"
  32. },
  33. {
  34. "name": "langroid",
  35. "source": "./plugins/langroid",
  36. "description": "Design patterns for the Langroid multi-agent LLM framework, with a skill to add new patterns as you learn them"
  37. },
  38. {
  39. "name": "voice",
  40. "source": "./plugins/voice",
  41. "description": "Audio feedback when Claude Code agent completes tasks using pocket-tts"
  42. },
  43. {
  44. "name": "voxtype",
  45. "source": "./plugins/voxtype",
  46. "description": "Install and set up voxtype \u2014 local on-device voice dictation for macOS"
  47. },
  48. {
  49. "name": "msg",
  50. "source": "./plugins/msg",
  51. "description": "Inter-agent communication for Claude Code and Codex CLI sessions via threads and messages"
  52. },
  53. {
  54. "name": "agent-tunnel",
  55. "source": "./plugins/agent-tunnel",
  56. "description": "Publish the current Claude session via >share so teammates can ask it questions through the agent-tunnel Discord bot (read-only forks)"
  57. },
  58. {
  59. "name": "writing",
  60. "source": "./plugins/writing",
  61. "description": "Prose-quality skills: agent-style (21 literature-backed rules for formal technical prose) and remove-ai-patterns (de-AI text using the avoid-ai-writing catalog plus a deterministic detector)"
  62. },
  63. {
  64. "name": "dynamic-workflow",
  65. "source": "./plugins/dynamic-workflow",
  66. "description": "Durable JavaScript orchestration for headless Codex agents, plus the github-wake skill"
  67. }
  68. ]
  69. }
README.md · README · 187 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <a href="https://pchalasani.github.io/claude-code-tools/">
  3. <img src="assets/title-blade-runner-theme.png" alt="CLAUDE CODE TOOLS"
  4. width="500"/>
  5. </a>
  6. CLI tools, skills, agents, hooks, and plugins for enhancing productivity with Claude Code and other coding agents.
  7. [![Documentation](https://img.shields.io/badge/%F0%9F%93%96-documentation-blue)](https://pchalasani.github.io/claude-code-tools/)
  8. [![claude-code-tools on PyPI](https://img.shields.io/pypi/v/claude-code-tools?label=claude-code-tools&color=blue)](https://pypi.org/project/claude-code-tools/)
  9. [![claude-code-tools installs/week](https://img.shields.io/pypi/dw/claude-code-tools?label=installs&color=2563eb)](https://pypistats.org/packages/claude-code-tools)
  10. [![aichat-search](https://img.shields.io/crates/v/aichat-search?label=aichat-search&color=orange)](https://crates.io/crates/aichat-search)
  11. [![Mentioned in Awesome Codex CLI](https://awesome.re/mentioned-badge.svg)](https://github.com/RoggeOhta/awesome-codex-cli)
  12. </div>
  13. ## [Full Documentation →](https://pchalasani.github.io/claude-code-tools/)
  14. Everything — installation, every tool, plugins, and guides — lives in the
  15. docs. Click a card below to jump to a feature, or
  16. **[read the full docs](https://pchalasani.github.io/claude-code-tools/)**.
  17. Skills install with one command (`-s` picks one skill, `-g` installs for
  18. every project). Most work in any agent; a few are Claude Code and Codex
  19. only (see the [Plugins page](https://pchalasani.github.io/claude-code-tools/getting-started/plugins/)).
  20. Needs Node.js 22.20 or newer for `npx`:
  21. ```bash
  22. npx skills add pchalasani/claude-code-tools -s voxtype-install
  23. ```
  24. <div align="center">
  25. <table>
  26. <tr>
  27. <td align="center">
  28. <a href="https://pchalasani.github.io/claude-code-tools/getting-started/">
  29. <img src="assets/card-quickstart.svg" alt="quick start" width="300"/>
  30. </a>
  31. </td>
  32. <td align="center">
  33. <a href="https://pchalasani.github.io/claude-code-tools/getting-started/plugins/">
  34. <img src="assets/card-plugins.svg" alt="plugins" width="300"/>
  35. </a>
  36. </td>
  37. </tr>
  38. </table>
  39. <table>
  40. <tr>
  41. <td align="center">
  42. <a href="https://pchalasani.github.io/claude-code-tools/tools/aichat/">
  43. <img src="assets/card-aichat.svg" alt="aichat" width="200"/>
  44. </a>
  45. </td>
  46. <td align="center">
  47. <a href="https://pchalasani.github.io/claude-code-tools/tools/voxtype/">
  48. <img src="assets/card-voxtype.svg" alt="voxtype" width="200"/>
  49. </a>
  50. </td>
  51. <td align="center">
  52. <a href="https://pchalasani.github.io/claude-code-tools/tools/tmux-cli/">
  53. <img src="assets/card-tmux.svg" alt="tmux-cli" width="200"/>
  54. </a>
  55. </td>
  56. <td align="center">
  57. <a href="https://pchalasani.github.io/claude-code-tools/tools/amux/">
  58. <img src="assets/card-amux.svg" alt="amux" width="200"/>
  59. </a>
  60. </td>
  61. </tr>
  62. <tr>
  63. <td align="center">
  64. <a href="https://pchalasani.github.io/claude-code-tools/tools/agent-tunnel/">
  65. <img src="assets/card-agent-tunnel.svg" alt="agent-tunnel" width="200"/>
  66. </a>
  67. </td>
  68. <td align="center">
  69. <a href="https://pchalasani.github.io/claude-code-tools/tools/lmsh/">
  70. <img src="assets/card-lmsh.svg" alt="lmsh" width="200"/>
  71. </a>
  72. </td>
  73. <td align="center">
  74. <a href="https://pchalasani.github.io/claude-code-tools/tools/vault/">
  75. <img src="assets/card-vault.svg" alt="vault" width="200"/>
  76. </a>
  77. </td>
  78. <td align="center">
  79. <a href="https://pchalasani.github.io/claude-code-tools/tools/env-safe/">
  80. <img src="assets/card-env-safe.svg" alt="env-safe" width="200"/>
  81. </a>
  82. </td>
  83. </tr>
  84. <tr>
  85. <td align="center">
  86. <a href="https://pchalasani.github.io/claude-code-tools/plugins-detail/safety-hooks/">
  87. <img src="assets/card-safety.svg" alt="safety" width="200"/>
  88. </a>
  89. </td>
  90. <td align="center">
  91. <a href="https://pchalasani.github.io/claude-code-tools/tools/sasy-guard/">
  92. <img src="assets/card-sasy-guard.svg" alt="sasy-guard" width="200"/>
  93. </a>
  94. </td>
  95. <td align="center">
  96. <a href="https://pchalasani.github.io/claude-code-tools/tools/statusline/">
  97. <img src="assets/card-statusline.svg" alt="statusline" width="200"/>
  98. </a>
  99. </td>
  100. <td align="center">
  101. <a href="https://pchalasani.github.io/claude-code-tools/tools/fix-session/">
  102. <img src="assets/card-session-repair.svg" alt="session repair" width="200"/>
  103. </a>
  104. </td>
  105. </tr>
  106. <tr>
  107. <td align="center">
  108. <a href="https://pchalasani.github.io/claude-code-tools/integrations/google-docs/">
  109. <img src="assets/card-gdocs.svg" alt="gdocs" width="200"/>
  110. </a>
  111. </td>
  112. <td align="center">
  113. <a href="https://pchalasani.github.io/claude-code-tools/integrations/google-sheets/">
  114. <img src="assets/card-gsheets.svg" alt="gsheets" width="200"/>
  115. </a>
  116. </td>
  117. <td align="center">
  118. <a href="https://pchalasani.github.io/claude-code-tools/integrations/alt-llm-providers/">
  119. <img src="assets/card-alt.svg" alt="alt" width="200"/>
  120. </a>
  121. </td>
  122. <td align="center">
  123. <a href="https://pchalasani.github.io/claude-code-tools/plugins-detail/voice/">
  124. <img src="assets/card-voice.svg" alt="voice" width="200"/>
  125. </a>
  126. </td>
  127. </tr>
  128. <tr>
  129. <td align="center">
  130. <a href="https://pchalasani.github.io/claude-code-tools/tools/aichat/port/">
  131. <img src="assets/card-session-port.svg" alt="Claude &lt;-&gt; Codex session porting" width="200"/>
  132. </a>
  133. </td>
  134. <td align="center">
  135. <a href="https://pchalasani.github.io/claude-code-tools/tools/github-wake/">
  136. <img src="assets/card-github-watch.svg"
  137. alt="github-watch: wake on a GitHub comment" width="200"/>
  138. </a>
  139. </td>
  140. <td align="center">
  141. <a href="https://pchalasani.github.io/claude-code-tools/tools/msg/">
  142. <img src="assets/card-msg.svg" alt="msg: inter-agent comms" width="200"/>
  143. </a>
  144. </td>
  145. <td align="center">
  146. <a href="https://pchalasani.github.io/claude-code-tools/plugins-detail/visual-brief/">
  147. <img src="assets/card-visual-brief.svg" alt="Visual Brief" width="200"/>
  148. </a>
  149. </td>
  150. </tr>
  151. <tr>
  152. <td align="center" colspan="4">
  153. <a href="https://pchalasani.github.io/claude-code-tools/guides/claude-to-codex/">
  154. <img src="assets/card-codex-dynamic-workflows.svg"
  155. alt="Codex Dynamic Workflows" width="416"/>
  156. </a>
  157. </td>
  158. </tr>
  159. </table>
  160. <table>
  161. <tr>
  162. <td align="center">
  163. <a href="https://pchalasani.github.io/claude-code-tools/development/">
  164. <img src="assets/card-dev.svg" alt="development" width="300"/>
  165. </a>
  166. </td>
  167. <td align="center">
  168. <a href="LICENSE">
  169. <img src="assets/card-license.svg" alt="license" width="300"/>
  170. </a>
  171. </td>
  172. </tr>
  173. </table>
  174. </div>
plugins/safety-hooks/hooks/command_utils.py · Bundled script · 910 lines · 3 findings marked
  1. """Shared utilities for bash command parsing."""
  2. from __future__ import annotations
  3. import os
  4. import re
  5. import subprocess
  6. from shell_scan import (
  7. _end_of_balanced,
  8. _end_of_single_quote,
  9. _split_command_lines,
  10. _split_line_on_operators,
  11. _split_pipeline_groups,
  12. )
  13. from shell_payloads import literal_shell_payloads, needs_conservative_shell_scan
  14. # Cache for alias expansions (populated on first use)
  15. _alias_cache: dict[str, str] | None = None
  16. def _load_alias_cache() -> dict[str, str]:
  17. """
  18. Load all shell aliases into a cache dict.
  19. Sources the shell rc file and runs 'alias' to get all aliases.
  20. Avoids -i (interactive) flag to prevent TTY issues when run as
  21. a background process by Claude Code.
  22. Returns empty dict on failure.
  23. """
  24. global _alias_cache
  25. if _alias_cache is not None:
  26. return _alias_cache
  27. _alias_cache = {}
  28. shell = os.environ.get('SHELL', '/bin/bash')
  29. try:
  30. # Avoid -i (interactive) flag which can cause TTY issues
  31. # Source rc file explicitly to get aliases without interactive mode
  32. if 'zsh' in shell:
  33. cmd = [shell, '-c', 'source ~/.zshrc 2>/dev/null; alias']
  34. else:
  35. cmd = [shell, '-c', 'source ~/.bashrc 2>/dev/null; alias']
  36. result = subprocess.run(
  37. cmd,
  38. capture_output=True,
  39. text=True,
  40. timeout=5,
  41. stdin=subprocess.DEVNULL, # Explicitly close stdin
  42. start_new_session=True, # Isolate from terminal control
  43. env={**os.environ, 'PS1': '', 'TERM': 'dumb'},
  44. )
  45. output = result.stdout
  46. # Strip ANSI escape sequences
  47. output = re.sub(r'\x1b\][^\x07]*\x07', '', output)
  48. output = re.sub(r'\x1b\[[0-9;]*[a-zA-Z]', '', output)
  49. # Parse alias output - handles both bash and zsh formats:
  50. # bash: alias gcam='git commit -am'
  51. # zsh: gcam='git commit -a -m' or gcam="git commit -a -m"
  52. for line in output.strip().split('\n'):
  53. line = line.strip()
  54. if not line:
  55. continue
  56. # Remove leading 'alias ' if present (bash format)
  57. if line.startswith('alias '):
  58. line = line[6:]
  59. # Parse name=value
  60. if '=' in line:
  61. name, _, value = line.partition('=')
  62. name = name.strip()
  63. value = value.strip()
  64. # Remove surrounding quotes
  65. if (value.startswith("'") and value.endswith("'")) or \
  66. (value.startswith('"') and value.endswith('"')):
  67. value = value[1:-1]
  68. if name:
  69. _alias_cache[name] = value
  70. except Exception:
  71. pass # Fail silently, return empty cache
  72. return _alias_cache
  73. def expand_alias(command: str) -> str:
  74. """
  75. Expand shell alias in the first token of a command.
  76. Uses cached alias lookups for performance. The cache is populated
  77. once per hook invocation by sourcing the shell rc file.
  78. Args:
  79. command: A single bash command (not compound).
  80. Returns:
  81. Command with first token expanded if it's an alias,
  82. otherwise the original command unchanged.
  83. Example:
  84. >>> # With alias gco='git checkout'
  85. >>> expand_alias("gco -f")
  86. 'git checkout -f'
  87. """
  88. parts = command.split(None, 1) # Split into [first_token, rest]
  89. if not parts:
  90. return command
  91. first_token = parts[0]
  92. rest = parts[1] if len(parts) > 1 else ""
  93. # Skip if already a known command or path
  94. if first_token in ('git', 'rm', 'cat', 'less', 'nano', 'vim') or '/' in first_token:
  95. return command
  96. # Look up in alias cache
  97. alias_cache = _load_alias_cache()
  98. if first_token in alias_cache:
  99. expansion = alias_cache[first_token]
  100. return f"{expansion} {rest}".strip()
  101. return command
  102. def expand_command_aliases(command: str) -> str:
  103. """
  104. Expand aliases in a possibly compound bash command.
  105. Splits compound command on shell operators, expands each subcommand's
  106. alias, and reconstructs the command.
  107. Recognized operators:
  108. - && (AND)
  109. - || (OR)
  110. - ; (sequential)
  111. - | (pipe)
  112. - & (background)
  113. Args:
  114. command: A bash command string, possibly compound.
  115. Returns:
  116. Command with aliases expanded in each subcommand.
  117. Example:
  118. >>> # With alias gco='git checkout', gcam='git commit -am'
  119. >>> expand_command_aliases("gco -f && gcam 'msg'")
  120. "git checkout -f && git commit -am 'msg'"
  121. """
  122. if not command:
  123. return command
  124. # Find the operators and their positions to preserve them.
  125. # This regex captures the operators as well as the commands.
  126. # Multi-character operators (&&, ||) must come before single-character
  127. # variants ([;&|]) to prevent partial matching.
  128. parts = re.split(r'(\s*(?:&&|\|\||[;&|])\s*)', command)
  129. result = []
  130. for part in parts:
  131. # Check if this part is an operator
  132. if re.match(r'\s*(?:&&|\|\||[;&|])\s*', part):
  133. result.append(part)
  134. elif part.strip():
  135. # It's a command, expand its alias
  136. result.append(expand_alias(part.strip()))
  137. else:
  138. result.append(part)
  139. return ''.join(result)
  140. def extract_subcommands(command: str) -> list[str]:
  141. """
  142. Split compound bash command into individual subcommands.
  143. Splits on shell chaining operators:
  144. - && (AND)
  145. - || (OR)
  146. - ; (sequential)
  147. - | (pipe)
  148. - & (background)
  149. - a newline outside quotes, which ends a command just as ';' does
  150. Multi-character operators (&&, ||) are matched before single-character
  151. variants to prevent partial matching (e.g., '&&' won't be split as '&' + '&').
  152. Args:
  153. command: A bash command string, possibly compound.
  154. Returns:
  155. List of individual subcommands with whitespace stripped.
  156. Example:
  157. >>> extract_subcommands("cd /tmp && git add . && git commit -m 'msg'")
  158. ['cd /tmp', 'git add .', "git commit -m 'msg'"]
  159. >>> extract_subcommands("echo ok | rm foo")
  160. ['echo ok', 'rm foo']
  161. >>> extract_subcommands("sleep 1 & rm bar")
  162. ['sleep 1', 'rm bar']
  163. >>> extract_subcommands("echo ok\\nrm foo")
  164. ['echo ok', 'rm foo']
  165. """
  166. if not command:
  167. return []
  168. subcommands = []
  169. for line in _split_command_lines(command):
  170. subcommands.extend(_split_line_on_operators(line))
  171. return [cmd.strip() for cmd in subcommands if cmd.strip()]
  172. def _extract_balanced_paren_content(command: str, start_idx: int) -> str | None:
  173. """
  174. Extract content from balanced parentheses starting at given index.
  175. Given a string and the index of an opening '(', finds the matching
  176. closing ')' accounting for nested parentheses. A ')' inside quotes is
  177. text, not the closing one: stopping at it would cut the substitution
  178. short and hide the commands after it, as in "$(printf ')'; rm foo)".
  179. Args:
  180. command: The full command string.
  181. start_idx: Index of the opening '(' character.
  182. Returns:
  183. The content between the balanced parentheses (excluding the parens
  184. themselves), or None if no balanced closing paren is found.
  185. Example:
  186. >>> _extract_balanced_paren_content("$(echo $(rm foo))", 1)
  187. 'echo $(rm foo)'
  188. """
  189. if start_idx >= len(command) or command[start_idx] != '(':
  190. return None
  191. end = _end_of_balanced(command, start_idx, '(')
  192. if end is None:
  193. return None
  194. return command[start_idx + 1:end - 1]
  195. def extract_subshell_commands(command: str) -> list[str]:
  196. """
  197. Extract commands embedded in subshells from a bash command string.
  198. Detects and extracts commands from:
  199. - $(...) command substitution (modern syntax, handles nesting)
  200. - `...` backtick command substitution (legacy syntax)
  201. This is a security measure to detect dangerous commands hidden inside
  202. subshells, e.g., `echo $(rm -rf /)` or `echo \`rm foo\``.
    • Dismissed after review: Runs `rm -rf` against a root or home-directory path
    • Line 252 on GitHub
  203. Uses balanced parenthesis scanning to correctly handle nested $()
  204. subshells like `$(echo $(rm foo))`.
  205. Args:
  206. command: A bash command string that may contain subshells.
  207. Returns:
  208. List of commands found inside subshells. Returns empty list if
  209. no subshells are found.
  210. Example:
  211. >>> extract_subshell_commands("echo $(whoami)")
  212. ['whoami']
  213. >>> extract_subshell_commands("echo `rm foo` bar")
  214. ['rm foo']
  215. >>> extract_subshell_commands("$(cat file) | $(rm -rf /)")
    • Dismissed after review: Runs `rm -rf` against a root or home-directory path
    • Line 269 on GitHub
  216. ['cat file', 'rm -rf /']
    • Dismissed after review: Runs `rm -rf` against a root or home-directory path
    • Line 270 on GitHub
  217. >>> extract_subshell_commands("echo $(echo $(rm foo))")
  218. ['echo $(rm foo)']
  219. """
  220. if not command:
  221. return []
  222. subshell_commands = []
  223. # Extract from $(...) - modern command substitution
  224. # Use balanced parenthesis scanning to handle nested subshells
  225. i = 0
  226. while i < len(command) - 1:
  227. if command[i:i+2] == '$(':
  228. # Found start of $(), extract balanced content
  229. inner_cmd = _extract_balanced_paren_content(command, i + 1)
  230. if inner_cmd is not None:
  231. inner_cmd = inner_cmd.strip()
  232. if inner_cmd:
  233. subshell_commands.append(inner_cmd)
  234. # Skip past this subshell to avoid re-matching nested ones
  235. # at the top level (they'll be found via recursion)
  236. i += 2 + len(inner_cmd) + 1 # $( + content + )
  237. continue
  238. i += 1
  239. # Extract from `...` - backtick command substitution (legacy syntax)
  240. # Backticks cannot be nested, so a simple pattern works
  241. backtick_pattern = r'`([^`]+)`'
  242. for match in re.finditer(backtick_pattern, command):
  243. inner_cmd = match.group(1).strip()
  244. if inner_cmd:
  245. subshell_commands.append(inner_cmd)
  246. return subshell_commands
  247. # Returned for a delimiter whose quoting the shell would unescape, which
  248. # this parser does not replicate. It cannot be treated as "no heredoc":
  249. # the body would then be scanned as commands, and a '<<' inside that body
  250. # would be read as a real heredoc, blanking the commands after the body.
  251. # Scanning stops instead, so nothing further is blanked.
  252. _UNDECODABLE_DELIMITER = object()
  253. def _heredoc_delimiter(command: str, start: int):
  254. # Return type is tuple[str, bool, bool, int], None, or the sentinel
  255. # above; annotating that adds nothing a reader wants here.
  256. """
  257. Parse the delimiter word of the '<<' operator at the given index.
  258. Args:
  259. command: The full command string.
  260. start: Index of the '<' that starts the '<<' operator.
  261. Returns:
  262. Tuple (delimiter, quoted, strip_tabs, end) where delimiter is the
  263. word after quote removal, quoted says whether any part of it was
  264. quoted (so the shell performs no expansion in the body),
  265. strip_tabs reflects the '<<-' form, and end is the index just past
  266. the delimiter word. Returns None when no delimiter word is there.
  267. """
  268. index = start + 2
  269. strip_tabs = index < len(command) and command[index] == '-'
  270. if strip_tabs:
  271. index += 1
  272. while index < len(command) and command[index] in ' \t':
  273. index += 1
  274. delimiter_parts = []
  275. quoted = False
  276. while index < len(command) and command[index] not in ' \t\r\n;&|<>()':
  277. character = command[index]
  278. if (character == '$' and index + 1 < len(command)
  279. and command[index + 1] in "'\""):
  280. # $'EOF' and $"EOF" quote the delimiter; the '$' is not part
  281. # of it, so bash ends the body at EOF, not at $EOF.
  282. ansi_c = command[index + 1] == "'"
  283. end = _end_of_single_quote(command, index + 1, escapes=ansi_c)
  284. if end is None:
  285. return None
  286. content = command[index + 2:end]
  287. if '\\' in content:
  288. # Both forms unescape: $'...' decodes ANSI-C escapes and
  289. # $"..." removes double-quote ones.
  290. return _UNDECODABLE_DELIMITER
  291. quoted = True
  292. delimiter_parts.append(content)
  293. index = end + 1
  294. elif (command.startswith('$(', index)
  295. or command.startswith('${', index)):
  296. # No expansion happens on a delimiter word, so "$(echo EOF)" is
  297. # the delimiter, literally, parentheses and all.
  298. opener = '(' if command[index + 1] == '(' else '{'
  299. end = _end_of_balanced(command, index + 1, opener)
  300. if end is None:
  301. return None
  302. delimiter_parts.append(command[index:end])
  303. index = end
  304. elif character == '`':
  305. # A backtick span is part of the word, and just as literal.
  306. end = command.find('`', index + 1)
  307. if end == -1:
  308. return None
  309. delimiter_parts.append(command[index:end + 1])
  310. index = end + 1
  311. elif character in "'\"":
  312. quoted = True
  313. end = _end_of_single_quote(command, index, escapes=False)
  314. if end is None:
  315. return None
  316. content = command[index + 1:end]
  317. if character == '"' and '\\' in content:
  318. # Quote removal would drop backslashes here.
  319. return _UNDECODABLE_DELIMITER
  320. delimiter_parts.append(content)
  321. index = end + 1
  322. elif character == '\\':
  323. if index + 1 >= len(command):
  324. return None
  325. if command[index + 1] == '\n':
  326. # A continuation inside the word: the shell removes both
  327. # characters before reading the delimiter, so "E\" + "OF"
  328. # is the delimiter EOF, and is not quoted by it.
  329. index += 2
  330. continue
  331. quoted = True
  332. delimiter_parts.append(command[index + 1])
  333. index += 2
  334. else:
  335. delimiter_parts.append(character)
  336. index += 1
  337. delimiter = ''.join(delimiter_parts)
  338. if not delimiter:
  339. return None
  340. return delimiter, quoted, strip_tabs, index
  341. def _ends_with_continuation(line: str) -> bool:
  342. """
  343. Report whether a physical line ends in a backslash-newline pair.
  344. Args:
  345. line: One physical line, without its newline.
  346. Returns:
  347. True when the line ends with an odd number of backslashes, so the
  348. last one escapes the newline instead of itself.
  349. """
  350. return (len(line) - len(line.rstrip('\\'))) % 2 == 1
  351. def _end_of_heredoc_body(
  352. command: str, start: int, delimiter: str, strip_tabs: bool,
  353. join_continuations: bool) -> tuple[int, int] | None:
  354. """
  355. Find the closing delimiter line of one heredoc body.
  356. Args:
  357. command: The full command string.
  358. start: Index where the body begins (just past a newline).
  359. delimiter: The delimiter word that ends the body.
  360. strip_tabs: Whether the '<<-' form allows leading tabs on it.
  361. join_continuations: Whether backslash-newline pairs are removed
  362. while reading the body, as they are for an unquoted delimiter.
  363. A delimiter can then be split over two lines ("EO\\" + "F").
  364. Returns:
  365. Tuple (delimiter_line_start, body_end): the index where the line
  366. holding the delimiter begins -- which is where the body ends, and
  367. with '<<-' may be a leading tab rather than the delimiter itself
  368. -- and the index just past that line. None when the body is never
  369. closed.
  370. """
  371. line_start = start
  372. while line_start <= len(command):
  373. # Read one logical line, which may span several physical ones.
  374. parts = []
  375. scan = line_start
  376. while True:
  377. line_end = command.find('\n', scan)
  378. if line_end == -1:
  379. line_end = len(command)
  380. part = command[scan:line_end].removesuffix('\r')
  381. if (join_continuations and line_end < len(command)
  382. and _ends_with_continuation(part)):
  383. parts.append(part[:-1])
  384. scan = line_end + 1
  385. continue
  386. parts.append(part)
  387. break
  388. line = ''.join(parts)
  389. if strip_tabs:
  390. line = line.lstrip('\t')
  391. if line == delimiter:
  392. return line_start, min(line_end + 1, len(command))
  393. if line_end == len(command):
  394. return None
  395. line_start = line_end + 1
  396. return None
  397. def _heredoc_bodies(
  398. command: str, start: int,
  399. pending: list[tuple[str, bool, bool, int]]) -> tuple[int, list[str]] | None:
  400. """
  401. Consume the bodies of every heredoc declared on one command line.
  402. A command line may open several heredocs ("cat <<A <<'B'"); their
  403. bodies follow the line in declaration order, one after another. Taking
  404. them one at a time would read the second body as shell syntax.
  405. Args:
  406. command: The full command string.
  407. start: Index where the first body begins (just past the newline
  408. that ends the command line).
  409. pending: The (delimiter, quoted, strip_tabs, depth) tuples in the
  410. order the heredocs were declared; depth is unused here.
  411. Returns:
  412. Tuple (end, expanded_bodies): the index just past the last body's
  413. delimiter line, and the bodies whose expansions the shell runs
  414. (those with an unquoted delimiter). None when any body is
  415. unterminated, in which case no body is treated as data.
  416. """
  417. cursor = start
  418. expanded_bodies = []
  419. for delimiter, quoted, strip_tabs, _ in pending:
  420. bounds = _end_of_heredoc_body(
  421. command, cursor, delimiter, strip_tabs,
  422. join_continuations=not quoted)
  423. if bounds is None:
  424. return None
  425. delimiter_line_start, body_end = bounds
  426. if not quoted:
  427. expanded_bodies.append(command[cursor:delimiter_line_start])
  428. cursor = body_end
  429. return cursor, expanded_bodies
  430. # A '#' only opens a comment at the start of a word, so it must follow
  431. # whitespace or an operator (or start the command). ')' is included because
  432. # '(echo x)# comment' is a comment; the cost is that the rarer '$(date)#tag',
  433. # where '#' is mid-word, is misread as one -- which only ever makes this
  434. # function blank less, i.e. hand MORE text to the guards.
  435. _COMMENT_PRECEDERS = ' \t\n;&|(<>)'
  436. # A reserved word is only reserved in command position: at the start of
  437. # the command, or right after an operator that begins a new one. Spaces
  438. # may sit in between, but not another word -- 'echo case' is an argument.
  439. _COMMAND_STARTERS = '\n;&|({'
  440. def _keyword_at(command: str, index: int, keyword: str) -> bool:
  441. """
  442. Report whether a reserved word in command position starts at index.
  443. Args:
  444. command: The full command string.
  445. index: Index to test.
  446. keyword: The word to look for, e.g. 'case'.
  447. Returns:
  448. True when the keyword is there as a whole word and bash would
  449. read it as the reserved word rather than an ordinary argument.
  450. """
  451. if not command.startswith(keyword, index):
  452. return False
  453. before = index
  454. while before and command[before - 1] in ' \t':
  455. before -= 1
  456. if before and command[before - 1] not in _COMMAND_STARTERS:
  457. return False
  458. after = index + len(keyword)
  459. return after == len(command) or command[after] in ' \t\n;&|)'
  460. # The delimiter word as written: a plain name, optionally quoted one of
  461. # the three ways bash allows. Anything else ($'..', $"..", escapes inside
  462. # quotes, substitutions) is left to the shell.
  463. _SIMPLE_DELIMITER = re.compile(
  464. r"""^(?:\\?[A-Za-z0-9_]+|'[A-Za-z0-9_]+'|"[A-Za-z0-9_]+")$""")
  465. # Header-line text that makes bash's tokenization non-trivial. Every
  466. # known way to blank a real command (a body boundary the scanner places
  467. # differently from bash) has needed one of these on the heredoc's own
  468. # line; refusing to blank when any is present makes the failure direction
  469. # over-blocking, which the guards tolerate. The list is deliberately
  470. # blunt: a '(' is enough, whether or not it opens a substitution.
  471. _COMPLEX_HEADER_MARKS = ('`', '$', '(', ')', '{', '}', '[', ']', '\\')
  472. _PLAIN_VARIABLE = re.compile(r'\$(?:[A-Za-z_][A-Za-z0-9_]*|\{[A-Za-z_][A-Za-z0-9_]*\})')
  473. def _simple_heredoc_header(command: str, operator: int, end: int) -> bool:
  474. """
  475. Report whether a heredoc's header line is simple enough to trust.
  476. The scanner approximates bash's tokenizer, and every divergence found
  477. so far (parameter expansions, ANSI-C quoting, substitutions closing
  478. before a newline, 'case' patterns, subscripts, escaped delimiters)
  479. lets an attacker place a body boundary where bash does not, so that
  480. a real command is blanked as data. Rather than chase each one, blank
  481. bodies only when the header line -- the physical line holding the
  482. '<<' -- carries none of the constructs those divergences need, and
  483. the delimiter is a plain word with at most simple quoting.
  484. Args:
  485. command: The full command string.
  486. operator: Index of the '<<' operator.
  487. end: Index just past its delimiter word.
  488. The same principle covers the spans the scanner steps over as
  489. non-command text ($((...)), ${...}, $[...], name[...]=): a '<<' inside
  490. one of those is a place where bash and this scanner could disagree
  491. about whether a heredoc opened, so the caller blanks nothing then too.
  492. Returns:
  493. True when the header line has no complex construct and the
  494. delimiter is plain, so the body boundaries are unambiguous.
  495. """
  496. line_start = command.rfind('\n', 0, operator) + 1
  497. line_end = command.find('\n', operator)
  498. if line_end == -1:
  499. line_end = len(command)
  500. raw = command[operator + 2:end].lstrip('-').strip(' \t')
  501. if not _SIMPLE_DELIMITER.match(raw):
  502. return False
  503. header = command[line_start:operator + 2] + command[end:line_end]
  504. # A plain variable reference ("$HOME", "${name}") cannot move a token
  505. # boundary, and "cat > $HOME/notes.md <<'EOF'" is the common case.
  506. header = _PLAIN_VARIABLE.sub('', header)
  507. return not any(mark in header for mark in _COMPLEX_HEADER_MARKS)
  508. def strip_heredoc_bodies(command: str) -> tuple[str, list[str]]:
  509. """
  510. Blank heredoc bodies and return the bodies the shell still expands.
  511. A heredoc body is data, not code: the shell never runs its lines as
  512. commands. When the delimiter is quoted (<<'EOF', <<"EOF", <<\\EOF) the
  513. shell performs no expansion at all, so nothing in the body executes.
  514. With an unquoted delimiter (<<EOF) only the body's expansions -- $(...)
  515. and backticks -- execute.
  516. Bodies begin after the command line that opens them, which is not the
  517. same as the next newline: a backslash-newline continues that line, and
  518. a newline inside quotes or inside an unfinished command substitution
  519. does not end it. Every heredoc opened on one line is consumed, in
  520. order, and a command substitution is its own parsing unit with its own
  521. bodies.
  522. Args:
  523. command: A bash command string, possibly containing heredocs.
  524. Returns:
  525. Tuple (command_without_bodies, expanded_bodies). The first element
  526. is the command with every heredoc body (and its closing delimiter
  527. line) replaced by whitespace, preserving offsets and line breaks.
  528. The second is the list of bodies whose expansions do execute.
  529. Example:
  530. >>> strip_heredoc_bodies("cat <<'EOF'\\n`rm x`\\nEOF")[1]
  531. []
  532. >>> strip_heredoc_bodies("cat <<EOF\\n`rm x`\\nEOF")[1]
  533. ['`rm x`\\n']
  534. """
  535. expanded_bodies = []
  536. pieces = []
  537. copied_to = 0
  538. index = 0
  539. quote = None
  540. # A command substitution is parsed as its own unit, so it has its own
  541. # command lines and its own heredoc bodies. Track how deep we are in
  542. # one, and remember the depth each heredoc was opened at. Grouping
  543. # parentheses are tracked too, so that the ')' of a nested group is not
  544. # mistaken for the one closing the substitution.
  545. open_parens: list[str] = []
  546. depth = 0
  547. case_depth = 0
  548. in_backtick = False
  549. # Heredocs opened on the command line now being scanned. Their bodies
  550. # all follow that line, in the order the operators appeared.
  551. pending: list[tuple[str, bool, bool, int]] = []
  552. while index < len(command):
  553. character = command[index]
  554. if character == '\\' and quote != "'":
  555. # A backslash-newline continues the command line, so the body
  556. # does not start here; skipping the pair keeps that newline
  557. # out of the body-start decision below.
  558. index += 2
  559. continue
  560. if quote is None and command.startswith("$'", index):
  561. # ANSI-C quoting: a backslash escapes the closing quote.
  562. end = _end_of_single_quote(command, index + 1, escapes=True)
  563. index = len(command) if end is None else end + 1
  564. continue
  565. if character in "'\"":
  566. if quote == character:
  567. quote = None
  568. elif quote is None:
  569. quote = character
  570. index += 1
  571. continue
  572. if quote is None and (
  573. (command.startswith('$(', index)
  574. and not command.startswith('$((', index))
  575. or command.startswith('<(', index)
  576. or command.startswith('>(', index)):
  577. # A command substitution $( ), or a process substitution <( )
  578. # or >( ): each is parsed as its own unit, so a newline inside
  579. # one does not end the command line that contains it.
  580. open_parens.append('$(')
  581. depth += 1
  582. index += 2
  583. continue
  584. if quote is None and character == '`':
  585. # Backticks cannot nest, so one toggles the substitution.
  586. depth += -1 if in_backtick else 1
  587. in_backtick = not in_backtick
  588. if not in_backtick:
  589. # Closing: a heredoc opened inside that never reached a
  590. # newline gets no body, exactly as with ')' below. Left
  591. # pending, it would swallow the first lines of a later
  592. # substitution at the same depth as data.
  593. pending = [item for item in pending if item[3] <= depth]
  594. index += 1
  595. continue
  596. if quote is None and (_keyword_at(command, index, 'case')
  597. or _keyword_at(command, index, 'esac')):
  598. # Inside a case statement a ')' ends a pattern, so it must not
  599. # be taken for the one closing a substitution.
  600. if command[index] == 'c':
  601. case_depth += 1
  602. index += 4
  603. else:
  604. case_depth = max(0, case_depth - 1)
  605. index += 4
  606. continue
  607. if quote is None and character == ')' and open_parens:
  608. if open_parens[-1] == '$(' and case_depth:
  609. # A case pattern's ')', not the end of the substitution.
  610. index += 1
  611. continue
  612. if open_parens.pop() == '$(':
  613. depth -= 1
  614. # A heredoc whose substitution closed before any newline
  615. # never gets a body: bash reads it from inside there.
  616. pending = [item for item in pending if item[3] <= depth]
  617. index += 1
  618. continue
  619. if quote is None and character == '\n' and pending:
  620. # Only the heredocs opened at this depth end here; ones opened
  621. # further out belong to a command line this newline is nested
  622. # inside, and wait for their own.
  623. ready = [item for item in pending if item[3] == depth]
  624. if not ready:
  625. index += 1
  626. continue
  627. bodies = _heredoc_bodies(command, index + 1, ready)
  628. pending = [item for item in pending if item[3] != depth]
  629. if bodies is None:
  630. index += 1
  631. continue
  632. body_end, expanded = bodies
  633. if any('$' in body or '`' in body for body in expanded):
  634. # An unquoted body's expansions do run, and finding the
  635. # commands among them needs a second parser with the same
  636. # divergences: a case pattern's ')' closes '$(' early, and
  637. # "${x@P}" runs a substitution held in x with no '$(' in
  638. # the body at all. Leave such a body unblanked so the
  639. # guards see it whole; quote the delimiter to document
  640. # commands.
  641. return command, []
  642. pieces.append(command[copied_to:index + 1])
  643. pieces.append(''.join(
  644. '\n' if char == '\n' else ' '
  645. for char in command[index + 1:body_end]
  646. ))
  647. expanded_bodies.extend(expanded)
  648. copied_to = body_end
  649. index = body_end
  650. continue
  651. if quote is None and character == '#' and (
  652. index == 0 or command[index - 1] in _COMMENT_PRECEDERS):
  653. # A comment runs to end of line, so any '<<' in it is text.
  654. newline = command.find('\n', index)
  655. if newline == -1:
  656. break
  657. # Stop on the newline itself: it may still end a command line
  658. # whose heredoc bodies start right after the comment.
  659. index = newline
  660. continue
  661. if quote is None and command.startswith('((', index):
  662. # '<<' inside $((1 << 2)) is a left shift, not a heredoc.
  663. arithmetic_end = _end_of_balanced(command, index, '(')
  664. if arithmetic_end is not None:
  665. if '<<' in command[index:arithmetic_end]:
  666. return command, [] # see _simple_heredoc_header
  667. index = arithmetic_end
  668. continue
  669. if quote is None and command.startswith('${', index):
  670. # '<<' inside ${x:-<<EOF} is expansion text, not a heredoc.
  671. expansion_end = _end_of_balanced(command, index + 1, '{')
  672. if expansion_end is not None:
  673. if '<<' in command[index:expansion_end]:
  674. return command, [] # see _simple_heredoc_header
  675. index = expansion_end
  676. continue
  677. if quote is None and command.startswith('$[', index):
  678. # $[1 << 2] is the deprecated arithmetic form, still a shift.
  679. legacy_end = _end_of_balanced(command, index + 1, '[')
  680. if legacy_end is not None:
  681. if '<<' in command[index:legacy_end]:
  682. return command, [] # see _simple_heredoc_header
  683. index = legacy_end
  684. continue
  685. if quote is None and character == '(':
  686. # A grouping or subshell paren. It is not a parsing unit of its
  687. # own, but it has to be balanced so that its ')' is not taken
  688. # for the one closing a substitution. Checked after the
  689. # arithmetic and expansion skips above, which own their parens.
  690. open_parens.append('(')
  691. index += 1
  692. continue
  693. if (quote is None and character == '[' and index > 0
  694. and (command[index - 1].isalnum()
  695. or command[index - 1] == '_')):
  696. # An array subscript is an arithmetic context, so the '<<' in
  697. # "a[1<<2]=foo" is a shift. But only an assignment word gets
  698. # that reading: in "echo a[<<EOF]" bash sees the argument "a["
  699. # followed by a heredoc delimited by "EOF]". So the bracket is
  700. # skipped only when the balanced span is followed by '=' or
  701. # '+=', i.e. it really is "name[subscript]=value".
  702. subscript_end = _end_of_balanced(command, index, '[')
  703. if subscript_end is not None and (
  704. command.startswith('=', subscript_end)
  705. or command.startswith('+=', subscript_end)):
  706. if '<<' in command[index:subscript_end]:
  707. return command, [] # see _simple_heredoc_header
  708. index = subscript_end
  709. continue
  710. if quote is None and command.startswith('<<<', index):
  711. # A here-string, whose expansions do run. Step over the whole
  712. # operator: leaving the scan on its second '<' would read the
  713. # remaining '<<' as a heredoc and blank the lines after it.
  714. index += 3
  715. continue
  716. if quote is None and command.startswith('<<', index):
  717. delimiter = _heredoc_delimiter(command, index)
  718. if delimiter is _UNDECODABLE_DELIMITER:
  719. # The body of this one cannot be located. Stop rather than
  720. # scan on: text inside that body could otherwise be read as
  721. # another heredoc header and blank real commands.
  722. break
  723. if isinstance(delimiter, tuple):
  724. word, quoted, strip_tabs, end = delimiter
  725. if depth or in_backtick or not _simple_heredoc_header(
  726. command, index, end):
  727. # Not provably simple: blank NOTHING in this command.
  728. # See _simple_heredoc_header for why.
  729. return command, []
  730. pending.append((word, quoted, strip_tabs, depth))
  731. index = end
  732. continue
  733. index += 1
  734. pieces.append(command[copied_to:])
  735. return ''.join(pieces), expanded_bodies
  736. def extract_all_commands(command: str) -> list[str]:
  737. """
  738. Recursively extract all commands from a bash command string.
  739. This combines subcommand extraction (splitting on shell operators)
  740. with subshell extraction (commands inside $() or backticks) to
  741. provide a comprehensive list of all commands that will be executed.
  742. This is the recommended function for security hooks that need to
  743. inspect all commands, including those hidden in subshells.
  744. Heredoc bodies are treated as the data they are: a quoted delimiter
  745. (<<'EOF') means nothing in the body executes, and an unquoted one
  746. (<<EOF) means only the body's $() and backtick expansions execute.
  747. Args:
  748. command: A bash command string, possibly compound with subshells.
  749. Returns:
  750. List of all individual commands, including those from subshells.
  751. Example:
  752. >>> extract_all_commands("echo $(rm foo) && ls")
  753. ['echo $(rm foo)', 'ls', 'rm foo']
  754. >>> extract_all_commands("cat `echo secret` | grep pass")
  755. ['cat `echo secret`', 'grep pass', 'echo secret']
  756. >>> extract_all_commands("cat > f <<'EOF'\\n`rm x` is blocked\\nEOF")
  757. ["cat > f <<'EOF'"]
  758. """
  759. if not command:
  760. return []
  761. # Heredoc bodies are data, so their lines are not commands. Blank them
  762. # out first; expanded_bodies holds the bodies (unquoted delimiters only)
  763. # whose substitutions the shell does run.
  764. stripped, expanded_bodies = strip_heredoc_bodies(command)
  765. all_commands = []
  766. # First, extract top-level subcommands (split on operators)
  767. subcommands = extract_subcommands(stripped)
  768. all_commands.extend(subcommands)
  769. # Extract from normalized lines before operator splitting can break spans.
  770. # A continuation can join "$" and "(" into a substitution marker.
  771. subshell_cmds = []
  772. lines = _split_command_lines(stripped)
  773. for line in lines:
  774. subshell_cmds.extend(extract_subshell_commands(line))
  775. for group in _split_pipeline_groups(stripped):
  776. if any(needs_conservative_shell_scan(part)
  777. for part in extract_subcommands(group)):
  778. # Stdin consumers share a pipeline, not an unrelated command list.
  779. for fragment in re.split(r'&&|\|\||[;&|\n]', group):
  780. fragment = fragment.strip()
  781. if fragment and fragment not in all_commands:
  782. all_commands.append(fragment)
  783. # Quoted strings passed to evaluators are code, unlike search patterns.
  784. for subcommand in subcommands:
  785. subshell_cmds.extend(literal_shell_payloads(subcommand))
  786. # Only the substitutions inside an unquoted heredoc body execute; the
  787. # surrounding text is literal, so it is not split into subcommands.
  788. for body in expanded_bodies:
  789. subshell_cmds.extend(extract_subshell_commands(body))
  790. # Recursively process subshell commands (they may contain nested subshells
  791. # or chained operators)
  792. for subcmd in subshell_cmds:
  793. all_commands.extend(extract_all_commands(subcmd))
  794. return all_commands
plugins/safety-hooks/hooks/test_command_utils.py · Bundled script · 639 lines · 2 findings marked
  1. #!/usr/bin/env python3
  2. """
  3. Unit tests for command_utils.py
  4. Tests cover:
  5. - Shell operator splitting (&&, ||, ;, |, &)
  6. - Subshell extraction ($() and backticks)
  7. - Combined extraction via extract_all_commands()
  8. - Edge cases and regression tests for security bypasses
  9. """
  10. import unittest
  11. import sys
  12. import os
  13. # Add the hooks directory to path for imports
  14. sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
  15. from command_utils import (
  16. extract_subcommands,
  17. extract_subshell_commands,
  18. extract_all_commands,
  19. expand_command_aliases,
  20. strip_heredoc_bodies,
  21. )
  22. class TestExtractSubcommands(unittest.TestCase):
  23. """Tests for extract_subcommands() shell operator splitting."""
  24. def test_empty_command(self):
  25. """Empty string returns empty list."""
  26. self.assertEqual(extract_subcommands(""), [])
  27. self.assertEqual(extract_subcommands(" "), [])
  28. def test_single_command(self):
  29. """Single command without operators."""
  30. self.assertEqual(extract_subcommands("ls -la"), ["ls -la"])
  31. self.assertEqual(extract_subcommands("git status"), ["git status"])
  32. def test_and_operator(self):
  33. """Split on && (AND) operator."""
  34. result = extract_subcommands("cd /tmp && ls")
  35. self.assertEqual(result, ["cd /tmp", "ls"])
  36. def test_or_operator(self):
  37. """Split on || (OR) operator."""
  38. result = extract_subcommands("test -f file || echo missing")
  39. self.assertEqual(result, ["test -f file", "echo missing"])
  40. def test_semicolon_operator(self):
  41. """Split on ; (sequential) operator."""
  42. result = extract_subcommands("echo hello; echo world")
  43. self.assertEqual(result, ["echo hello", "echo world"])
  44. def test_newline_operator(self):
  45. """A newline ends a command just as ';' does - security regression."""
  46. result = extract_subcommands("echo ok\nrm foo")
  47. self.assertEqual(result, ["echo ok", "rm foo"])
  48. def test_newline_inside_quotes_is_not_a_separator(self):
  49. """A newline in a quoted word is part of that word, not an operator."""
  50. result = extract_subcommands("echo 'first\nrm foo'")
  51. self.assertEqual(result, ["echo 'first\nrm foo'"])
  52. def test_line_continuation_is_joined(self):
  53. """A backslash-newline continues the line, so the shell removes it."""
  54. result = extract_subcommands("echo ok ; \\\nrm foo")
  55. self.assertEqual(result, ["echo ok", "rm foo"])
  56. def test_pipe_operator(self):
  57. """Split on | (pipe) operator - security regression test."""
  58. result = extract_subcommands("echo ok | rm foo")
  59. self.assertEqual(result, ["echo ok", "rm foo"])
  60. result = extract_subcommands("cat file | grep pattern | wc -l")
  61. self.assertEqual(result, ["cat file", "grep pattern", "wc -l"])
  62. def test_background_operator(self):
  63. """Split on & (background) operator - security regression test."""
  64. result = extract_subcommands("sleep 1 & rm bar")
  65. self.assertEqual(result, ["sleep 1", "rm bar"])
  66. def test_mixed_operators(self):
  67. """Multiple different operators in one command."""
  68. result = extract_subcommands("cmd1 && cmd2 | cmd3; cmd4 || cmd5 & cmd6")
  69. self.assertEqual(result, ["cmd1", "cmd2", "cmd3", "cmd4", "cmd5", "cmd6"])
  70. def test_preserves_command_arguments(self):
  71. """Arguments within commands are preserved."""
  72. result = extract_subcommands("git add . && git commit -m 'msg with spaces'")
  73. self.assertEqual(result, ["git add .", "git commit -m 'msg with spaces'"])
  74. def test_double_operators_not_split_incorrectly(self):
  75. """&& should not become two & splits."""
  76. result = extract_subcommands("cmd1 && cmd2")
  77. # Should be 2 commands, not 3 (which would happen if && was split as & twice)
  78. self.assertEqual(len(result), 2)
  79. self.assertEqual(result, ["cmd1", "cmd2"])
  80. class TestExtractSubshellCommands(unittest.TestCase):
  81. """Tests for extract_subshell_commands() subshell detection."""
  82. def test_empty_command(self):
  83. """Empty string returns empty list."""
  84. self.assertEqual(extract_subshell_commands(""), [])
  85. def test_no_subshells(self):
  86. """Command without subshells returns empty list."""
  87. self.assertEqual(extract_subshell_commands("ls -la"), [])
  88. self.assertEqual(extract_subshell_commands("echo hello"), [])
  89. def test_dollar_paren_subshell(self):
  90. """Extract command from $() syntax."""
  91. result = extract_subshell_commands("echo $(whoami)")
  92. self.assertEqual(result, ["whoami"])
  93. def test_ansi_c_quoted_argument_inside_a_substitution(self):
  94. """$'don\\'t' is one word: its escaped quote must not end quoting.
  95. Regression: the quote-aware bracket balancing read the escaped
  96. quote as the closing one, then took the real closing quote as an
  97. opening one, and never saw the ')' -- hiding the rm.
  98. """
  99. command = "echo $(rm $'don\\'t')"
  100. self.assertEqual(extract_subshell_commands(command), ["rm $'don\\'t'"])
  101. def test_backtick_subshell(self):
  102. """Extract command from backtick syntax."""
  103. result = extract_subshell_commands("echo `whoami`")
  104. self.assertEqual(result, ["whoami"])
  105. def test_multiple_subshells(self):
  106. """Multiple subshells in one command."""
  107. result = extract_subshell_commands("$(cmd1) foo $(cmd2)")
  108. self.assertEqual(result, ["cmd1", "cmd2"])
  109. def test_mixed_subshell_syntax(self):
  110. """Both $() and backticks in same command."""
  111. result = extract_subshell_commands("$(cmd1) and `cmd2`")
  112. self.assertIn("cmd1", result)
  113. self.assertIn("cmd2", result)
  114. def test_subshell_with_arguments(self):
  115. """Subshell containing command with arguments."""
  116. result = extract_subshell_commands("echo $(cat /etc/passwd)")
  117. self.assertEqual(result, ["cat /etc/passwd"])
  118. def test_security_bypass_rm_in_subshell(self):
  119. """Detect rm hidden in subshell - security test."""
  120. result = extract_subshell_commands("echo $(rm -rf /)")
    • Note: Quoted as data in code: Runs `rm -rf` against a root or home-directory path
    • Line 151 on GitHub
  121. self.assertEqual(result, ["rm -rf /"])
    • Note: Quoted as data in code: Runs `rm -rf` against a root or home-directory path
    • Line 152 on GitHub
  122. result = extract_subshell_commands("cat `rm foo`")
  123. self.assertEqual(result, ["rm foo"])
  124. def test_nested_subshell_extraction(self):
  125. """Nested $() subshells are properly extracted - P1 security fix."""
  126. # This was a bypass: $(echo $(rm foo)) would only extract "echo $(rm foo"
  127. # truncated at first ), missing the inner rm command
  128. result = extract_subshell_commands("echo $(echo $(rm foo))")
  129. self.assertEqual(result, ["echo $(rm foo)"])
  130. def test_deeply_nested_subshells(self):
  131. """Multiple levels of nesting are handled."""
  132. result = extract_subshell_commands("$(a $(b $(c)))")
  133. self.assertEqual(result, ["a $(b $(c))"])
  134. def test_multiple_nested_subshells(self):
  135. """Multiple nested subshells at same level."""
  136. result = extract_subshell_commands("$(cmd1 $(inner1)) $(cmd2 $(inner2))")
  137. self.assertIn("cmd1 $(inner1)", result)
  138. self.assertIn("cmd2 $(inner2)", result)
  139. class TestExtractAllCommands(unittest.TestCase):
  140. """Tests for extract_all_commands() comprehensive extraction."""
  141. def test_empty_command(self):
  142. """Empty string returns empty list."""
  143. self.assertEqual(extract_all_commands(""), [])
  144. def test_simple_command(self):
  145. """Simple command without operators or subshells."""
  146. result = extract_all_commands("ls -la")
  147. self.assertEqual(result, ["ls -la"])
  148. def test_chained_commands(self):
  149. """Commands chained with operators."""
  150. result = extract_all_commands("cmd1 && cmd2 | cmd3")
  151. self.assertIn("cmd1", result)
  152. self.assertIn("cmd2", result)
  153. self.assertIn("cmd3", result)
  154. def test_subshell_commands(self):
  155. """Commands inside subshells are extracted."""
  156. result = extract_all_commands("echo $(rm foo)")
  157. self.assertIn("echo $(rm foo)", result) # Top-level command
  158. self.assertIn("rm foo", result) # Subshell command
  159. def test_combined_operators_and_subshells(self):
  160. """Both operators and subshells in same command."""
  161. result = extract_all_commands("echo $(rm foo) && ls")
  162. self.assertIn("echo $(rm foo)", result)
  163. self.assertIn("ls", result)
  164. self.assertIn("rm foo", result)
  165. def test_nested_operators_in_subshell(self):
  166. """Operators inside subshell are also split."""
  167. result = extract_all_commands("$(cmd1 && cmd2)")
  168. self.assertIn("cmd1", result)
  169. self.assertIn("cmd2", result)
  170. def test_security_pipe_bypass(self):
  171. """Detect rm after pipe - security regression test."""
  172. result = extract_all_commands("echo ok | rm -rf /tmp/x")
  173. self.assertIn("rm -rf /tmp/x", result)
  174. def test_security_background_bypass(self):
  175. """Detect rm after background operator - security regression test."""
  176. result = extract_all_commands("sleep 1 & rm foo")
  177. self.assertIn("rm foo", result)
  178. def test_security_subshell_bypass(self):
  179. """Detect rm hidden in subshell - security regression test."""
  180. result = extract_all_commands("echo $(rm secret)")
  181. self.assertIn("rm secret", result)
  182. def test_quoted_paren_does_not_cut_a_subshell_short(self):
  183. """A ')' inside quotes is text, so the rm after it is still found."""
  184. result = extract_all_commands("echo $(printf ')'; rm foo)")
  185. self.assertIn("rm foo", result)
  186. def test_quoted_paren_in_a_heredoc_body_substitution(self):
  187. """Same, for the substitution inside an unquoted heredoc body."""
  188. result = extract_all_commands("cat <<EOF\n$(printf ')'; rm foo)\nEOF")
  189. self.assertIn("rm foo", result)
  190. def test_quoted_heredoc_backticks_are_literal(self):
  191. """A quoted delimiter means the shell expands nothing in the body."""
  192. command = "cat > notes.md <<'MD'\nThe `rm -rf x` guard.\nMD"
  193. result = extract_all_commands(command)
  194. self.assertNotIn("rm -rf x", result)
  195. self.assertIn("cat > notes.md <<'MD'", result)
  196. def test_double_quoted_heredoc_backticks_are_literal(self):
  197. """A double-quoted delimiter is just as literal as a single-quoted one."""
  198. command = 'cat > notes.md <<"MD"\nThe `rm -rf x` guard.\nMD'
  199. self.assertNotIn("rm -rf x", extract_all_commands(command))
  200. def test_backslash_quoted_heredoc_backticks_are_literal(self):
  201. """A backslash-escaped delimiter also disables expansion."""
  202. command = "cat > notes.md <<\\MD\nThe `rm -rf x` guard.\nMD"
  203. self.assertNotIn("rm -rf x", extract_all_commands(command))
  204. def test_unquoted_heredoc_substitutions_are_extracted(self):
  205. """An unquoted delimiter still expands $() and backticks - regression."""
  206. backticks = "cat > notes.md <<MD\nThe `rm -rf x` guard.\nMD"
  207. self.assertIn("rm -rf x", extract_all_commands(backticks))
  208. dollar = "cat > notes.md <<MD\nThe $(rm -rf y) guard.\nMD"
  209. self.assertIn("rm -rf y", extract_all_commands(dollar))
  210. def test_unquoted_heredoc_body_text_is_not_a_command(self):
  211. """Body lines are data even when the delimiter is unquoted."""
  212. command = "cat > notes.md <<MD\nrm -rf /tmp/x\nMD"
  213. self.assertNotIn("rm -rf /tmp/x", extract_all_commands(command))
  214. def test_command_chained_after_heredoc_is_extracted(self):
  215. """Only the body is blanked, never the line introducing it."""
  216. command = "cat <<'MD' && rm foo\nliteral text\nMD"
  217. self.assertIn("rm foo", extract_all_commands(command))
  218. def test_heredoc_tab_stripped_delimiter(self):
  219. """<<- indents the closing delimiter with tabs."""
  220. command = "cat > notes.md <<-'MD'\n\tThe `rm -rf x` guard.\n\tMD"
  221. self.assertNotIn("rm -rf x", extract_all_commands(command))
  222. def test_unterminated_heredoc_keeps_current_behavior(self):
  223. """Without a closing delimiter nothing is treated as a heredoc body."""
  224. command = "cat > notes.md <<'MD'\nThe `rm -rf x` guard."
  225. self.assertIn("rm -rf x", extract_all_commands(command))
  226. def test_herestring_is_not_a_heredoc(self):
  227. """<<< is a here-string, whose expansions do execute."""
  228. command = "cat <<< `rm -rf x`"
  229. self.assertIn("rm -rf x", extract_all_commands(command))
  230. class TestStripHeredocBodies(unittest.TestCase):
  231. """Tests for strip_heredoc_bodies() heredoc detection."""
  232. def test_no_heredoc_is_unchanged(self):
  233. """Commands without heredocs pass through untouched."""
  234. self.assertEqual(strip_heredoc_bodies("ls -la"), ("ls -la", []))
  235. def test_quoted_body_is_blanked_and_not_returned(self):
  236. """A quoted body is removed from the command and never expanded."""
  237. command = "cat <<'MD'\nrm -rf x\nMD"
  238. stripped, bodies = strip_heredoc_bodies(command)
  239. self.assertEqual(bodies, [])
  240. self.assertNotIn("rm", stripped)
  241. self.assertEqual(len(stripped), len(command))
  242. def test_unquoted_body_is_returned(self):
  243. """An unquoted body is blanked but returned for expansion scanning."""
  244. command = "cat <<MD\nrm -rf x\nMD"
  245. stripped, bodies = strip_heredoc_bodies(command)
  246. self.assertEqual(bodies, ["rm -rf x\n"])
  247. self.assertNotIn("rm", stripped)
  248. def test_heredoc_operator_inside_quotes_is_ignored(self):
  249. """A '<<' inside a quoted word does not start a heredoc."""
  250. command = "echo 'a << b'\nrm foo"
  251. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  252. def test_heredoc_operator_inside_comment_is_ignored(self):
  253. """A '<<' in a comment must not swallow the lines that follow."""
  254. command = "# <<END\nrm -rf /tmp/x\nEND"
  255. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  256. def test_comment_after_subshell_close_is_ignored(self):
  257. """'(echo x)# <<END' is a comment, so the next lines are commands."""
  258. command = "(echo x)# <<END\nrm -rf /tmp/x\nEND"
  259. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  260. def test_hash_inside_word_is_not_a_comment(self):
  261. """A '#' that is not word-initial does not start a comment."""
  262. command = "echo a#b <<'MD'\nrm -rf x\nMD"
  263. stripped, bodies = strip_heredoc_bodies(command)
  264. self.assertEqual(bodies, [])
  265. self.assertNotIn("rm", stripped)
  266. def test_left_shift_in_arithmetic_is_not_a_heredoc(self):
  267. """'<<' inside $(( )) is a shift operator, not a heredoc."""
  268. command = "echo $((1 << 2))\nrm -rf /tmp/x\n2"
  269. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  270. def test_parameter_expansion_is_not_a_heredoc(self):
  271. """'<<' inside ${...} is expansion text, so it opens no heredoc."""
  272. command = "echo ${x:-<<EOF}\nrm -rf /tmp/x\nEOF}"
  273. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  274. def test_nested_parameter_expansion_is_skipped_whole(self):
  275. """Nested braces inside a parameter expansion are handled."""
  276. command = "echo ${x:-${y:-<<EOF}}\nrm -rf /tmp/x\nEOF}}"
  277. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  278. def test_nested_arithmetic_is_skipped_whole(self):
  279. """Nested parentheses inside arithmetic are handled."""
  280. command = "echo $(( (1 << 2) + 3 ))\nrm -rf /tmp/x\n3 ))"
  281. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  282. def test_ansi_c_escape_in_delimiter_is_not_a_heredoc(self):
  283. """An undecodable ANSI-C delimiter blanks nothing, so guards see all."""
  284. command = "cat <<$'E\\tOF'\nrm -rf /tmp/x\nE\tOF"
  285. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  286. def test_escaped_brace_does_not_close_a_parameter_expansion(self):
  287. """'\\}' is expansion text, so '<<EOF' after it opens no heredoc."""
  288. command = "echo ${x:-\\}<<EOF}\nrm -rf /tmp/x\nEOF}"
  289. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  290. def test_quoted_brace_does_not_close_a_parameter_expansion(self):
  291. """A '}' inside quotes does not end the expansion either."""
  292. command = "echo ${x:-'}'<<EOF}\nrm -rf /tmp/x\nEOF}"
  293. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  294. def test_every_heredoc_on_the_line_is_consumed(self):
  295. """Two heredocs on one header have two bodies, one after the other."""
  296. command = "cat <<A <<'B'\nfirst\nA\necho <<X\nB\nrm -rf /tmp/x\nX"
  297. stripped, bodies = strip_heredoc_bodies(command)
  298. self.assertEqual(bodies, ["first\n"])
  299. self.assertNotIn("echo <<X", stripped)
  300. self.assertIn("rm -rf /tmp/x", stripped)
  301. def test_second_body_of_a_multi_heredoc_line_is_data(self):
  302. """The second body is data too, so its literal text is not a command."""
  303. command = "cat <<A <<'B'\nliteral a\nA\nThe `rm -rf x` guard\nB"
  304. stripped, bodies = strip_heredoc_bodies(command)
  305. self.assertEqual(bodies, ["literal a\n"])
  306. self.assertNotIn("rm -rf x", stripped)
  307. def test_heredoc_after_a_comment_still_has_a_body(self):
  308. """A trailing comment does not stop the body from starting."""
  309. command = "cat <<'MD' # note\nrm -rf x\nMD"
  310. stripped, bodies = strip_heredoc_bodies(command)
  311. self.assertEqual(bodies, [])
  312. self.assertNotIn("rm -rf x", stripped)
  313. def test_escape_in_a_double_quoted_delimiter_is_not_a_heredoc(self):
  314. """Quote removal would drop a backslash, so decline to blank."""
  315. command = 'cat <<"A\\\\B"\ndata\nA\\B\nrm -rf /tmp/x\nA\\\\B'
  316. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  317. def test_escape_in_a_localized_delimiter_is_not_a_heredoc(self):
  318. """$"..." unescapes just like "..." does, so decline there too."""
  319. command = 'cat <<$"A\\\\B"\ndata\nA\\B\nrm -rf /tmp/x\nA\\\\B'
  320. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  321. def test_undecodable_delimiter_stops_the_scan(self):
  322. """Declining one heredoc must not turn its body into a new header.
  323. Bash ends the <<$'E\\x4fF' body at EOF and runs the rm after it. The
  324. body holds "echo <<X", so scanning on would read that as a heredoc
  325. and blank the rm. Nothing after an undecodable delimiter is blanked.
  326. """
  327. command = "cat <<$'E\\x4fF'\necho <<X\nEOF\nrm -rf /tmp/x\nX"
  328. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  329. def test_case_outside_a_substitution_still_allows_a_heredoc(self):
  330. """'esac' closes the case, so a later heredoc is found normally."""
  331. command = "case x in x) echo yes;; esac\ncat <<'EOF'\nrm -rf /tmp/x\nEOF"
  332. stripped, bodies = strip_heredoc_bodies(command)
  333. self.assertEqual(bodies, [])
  334. self.assertNotIn("rm -rf /tmp/x", stripped)
  335. def test_herestring_operator_is_stepped_over_whole(self):
  336. """The trailing '<<' of '<<<' must not be read as a heredoc."""
  337. command = "cat <<<input\nrm -rf /tmp/x\ninput"
  338. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  339. def test_legacy_arithmetic_shift_is_not_a_heredoc(self):
  340. """$[1 << 2] is the deprecated arithmetic form, so '<<' is a shift."""
  341. command = "echo $[1 << 2]\nrm -rf /tmp/x\n2]"
  342. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  343. def test_array_subscript_shift_is_not_a_heredoc(self):
  344. """'<<' in "a[1<<2]=foo" is a shift: the subscript is arithmetic."""
  345. command = "a[1<<2]=foo\nrm -rf /tmp/x\n2]=foo"
  346. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  347. def test_output_process_substitution_delays_the_body(self):
  348. """>( ) is a parsing unit of its own just as <( ) is."""
  349. command = "cat <<EOF >(cat\nrm -rf /tmp/x\n)\nliteral\nEOF"
  350. stripped, _ = strip_heredoc_bodies(command)
  351. self.assertIn("rm -rf /tmp/x", stripped)
  352. def test_delimiter_split_over_a_continued_line(self):
  353. """An unquoted body loses backslash-newline, so 'EO\\'+'F' ends it."""
  354. command = "cat <<EOF\ndata\nEO\\\nF\nrm -rf /tmp/x\nEOF"
  355. stripped, bodies = strip_heredoc_bodies(command)
  356. self.assertEqual(bodies, ["data\n"])
  357. self.assertIn("rm -rf /tmp/x", stripped)
  358. def test_quoted_body_keeps_a_continued_delimiter_literal(self):
  359. """With a quoted delimiter nothing is unescaped, so it does not end."""
  360. command = "cat <<'EOF'\ndata\nEO\\\nF\nrm -rf /tmp/x\nEOF"
  361. stripped, bodies = strip_heredoc_bodies(command)
  362. self.assertEqual(bodies, [])
  363. self.assertNotIn("rm -rf /tmp/x", stripped)
  364. def test_substitution_closing_first_leaves_the_heredoc_bodyless(self):
  365. """Bash reads that body inside the substitution, so there is none."""
  366. command = "echo $(cat <<'EOF') tail\nrm -rf /tmp/x\nEOF"
  367. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  368. def test_backticks_closing_first_leave_the_heredoc_bodyless(self):
  369. """A closed backtick span drops its heredoc, like ')' does.
  370. Bash runs the rm here: the first span closes before any newline,
  371. so its heredoc has no body, and the second span is code.
  372. """
  373. command = "echo `cat <<IN ` ; echo `\nrm -rf /tmp/x\nIN\n`"
  374. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  375. self.assertIn("rm -rf /tmp/x", extract_all_commands(command))
  376. def test_case_as_an_argument_is_not_the_keyword(self):
  377. """Only a 'case' in command position opens a case statement.
  378. Bash runs the rm: 'echo case' is an argument, so both ')' close
  379. their substitutions and the OUT body's '<<X' is literal.
  380. """
  381. command = ("cat <<OUT $(echo case; echo $(echo hi)\n)\n"
  382. "echo <<X\nOUT\nrm -rf /tmp/x\nX")
  383. self.assertIn("rm -rf /tmp/x", extract_all_commands(command))
  384. def test_bracket_after_an_argument_is_not_a_subscript(self):
  385. """'echo a[<<EOF]' is the argument 'a[' plus a heredoc to 'EOF]'.
  386. Bash runs the rm: the body ends at 'EOF]', and the '<<X' inside
  387. it is literal, not a second heredoc.
  388. """
  389. command = "echo a[<<EOF]\necho <<X\nEOF]\nrm -rf /tmp/x\nX"
  390. self.assertIn("rm -rf /tmp/x", extract_all_commands(command))
  391. def test_assignment_subscript_shift_is_still_not_a_heredoc(self):
  392. """The subscript rule still covers the real assignment form."""
  393. command = "a[1<<2]=foo\nrm -rf /tmp/x"
  394. self.assertIn("rm -rf /tmp/x", extract_all_commands(command))
  395. def test_unterminated_second_body_blanks_nothing(self):
  396. """If any body is unclosed, no body is treated as data."""
  397. command = "cat <<A <<B\nfirst\nA\nrm -rf /tmp/x"
  398. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  399. # Every construct below has, at some point, let the scanner place a
  400. # body boundary where bash does not, so that a real command was
  401. # blanked as data. The policy is therefore to blank nothing when the
  402. # header line carries any of them: the guards then see the whole
  403. # command, which can only over-block.
  404. COMPLEX_HEADERS = {
  405. "ansi-c delimiter": "cat <<$'EOF'\nliteral\nEOF\nrm -rf /tmp/x\n$EOF",
  406. "ansi-c string on the line": "echo $'don\\'t' <<'MD'\nrm -rf x\nMD",
  407. "backticks in the delimiter": "cat <<`echo EOF`\npayload\n`echo EOF`",
  408. "glob bracket on the line": "ls [ab]* ; cat <<EOF\nrm -rf /tmp/x\nEOF",
  409. "case pattern in a substitution": (
  410. "cat <<EOF $(case x in x) echo yes;; esac\nrm -rf /tmp/x\n)\n"
  411. "literal\nEOF"),
  412. "delimiter split by a continuation": (
  413. "cat <<E\\\nOF\necho <<X\nEOF\nrm -rf /tmp/x\nX"),
  414. "nested heredocs": (
  415. "cat <<OUT $(cat <<IN\n)\nIN\nrm -rf /tmp/x\n)\nouter\nOUT"),
  416. "heredoc inside a substitution": (
  417. "echo $(cat <<'EOF'\nrm -rf /tmp/x\nEOF\n)"),
  418. "continuation after the header": (
  419. "cat <<EOF ; \\\nrm -rf /tmp/x\nliteral\nEOF"),
  420. "group inside a substitution": (
  421. "cat <<EOF $( (echo x)\nrm -rf /tmp/x\n)\nliteral\nEOF"),
  422. "newline inside a substitution": (
  423. "cat <<'EOF' $(echo start\nrm -rf /tmp/x)\nliteral\nEOF"),
  424. "newline inside backticks": (
  425. "cat <<'EOF' `echo start\nrm -rf /tmp/x`\nliteral\nEOF"),
  426. "expansion as the delimiter": "cat <<${x}\npayload\n${x}\nrm -rf /tmp/x",
  427. "paren case pattern": (
  428. "cat <<EOF $(case x in (x) echo yes;; esac\nrm -rf /tmp/x\n)\n"
  429. "literal\nEOF"),
  430. "process substitution": (
  431. "cat <<EOF <(echo x\nrm -rf /tmp/x\n)\nliteral\nEOF"),
  432. "subshell group": "(cat <<'EOF'\nrm -rf /tmp/x\nEOF\n)",
  433. "substitution as the delimiter": (
  434. "cat <<$(echo EOF)\npayload\n$(echo EOF)\nrm -rf /tmp/x"),
  435. "parameter expansion with default": (
  436. "echo ${x:-<<EOF}\nrm -rf /tmp/x\nEOF}"),
  437. "array assignment on the line": "a[1<<2]=foo\nrm -rf /tmp/x",
  438. "substitution in an unquoted body": (
  439. "cat <<EOF\n$(case x in x) echo yes;; esac; rm -rf /tmp/x)\nEOF"),
  440. "backticks in an unquoted body": "cat <<EOF\n`rm -rf /tmp/x`\nEOF",
  441. "prompt expansion in an unquoted body": (
  442. "x='$''(rm -rf /tmp/x)'; cat <<EOF\n${x@P}\nEOF"),
  443. }
  444. def test_complex_headers_are_never_blanked(self):
  445. """A header line with any complex construct disables blanking."""
  446. for name, command in self.COMPLEX_HEADERS.items():
  447. with self.subTest(name):
  448. self.assertEqual(strip_heredoc_bodies(command), (command, []))
  449. # Strings reviewers used to blank a real rm. Each is accepted by bash
  450. # and runs the rm; each must reach the guards.
  451. KNOWN_BYPASSES = [
  452. "echo ${x:-<<EOF}\nrm -rf /tmp/x\nEOF}",
  453. "echo ${x:-\\}<<EOF}\nrm -rf /tmp/x\nEOF}",
  454. "cat <<A <<'B'\nfirst\nA\necho <<X\nB\nrm -rf /tmp/x\nX",
  455. "cat <<$'EOF'\nliteral\nEOF\nrm -rf /tmp/x\n$EOF",
  456. "cat <<EOF ; \\\nrm -rf /tmp/x\nliteral\nEOF",
  457. "cat <<E\\\nOF\necho <<X\nEOF\nrm -rf /tmp/x\nX",
  458. "cat <<EOF $( (echo x)\nrm -rf /tmp/x\n)\nliteral\nEOF",
  459. "cat <<EOF <(echo x\nrm -rf /tmp/x\n)\nliteral\nEOF",
  460. "cat <<OUT $(cat <<IN\n)\nIN\nrm -rf /tmp/x\n)\nouter\nOUT",
  461. "echo `cat <<IN ` ; echo `\nrm -rf /tmp/x\nIN\n`",
  462. "cat <<OUT $(echo case; echo $(echo hi)\n)\necho <<X\nOUT\n"
  463. "rm -rf /tmp/x\nX",
  464. "echo a[<<EOF]\necho <<X\nEOF]\nrm -rf /tmp/x\nX",
  465. "cat <<OUT $(if true; then case x in x) :;; esac; fi\n"
  466. "rm -rf /tmp/x\n)\npayload\nOUT",
  467. "echo a[<<EOF]=x\necho <<X\nEOF]=x\nrm -rf /tmp/x\nX",
  468. "cat <<EOF\n$(case x in x) echo yes;; esac; rm -rf /tmp/x)\nEOF",
  469. "cat <<\"A\\\\B\"\nA\\B\nrm -rf /tmp/x\nA\\\\B",
  470. ]
  471. # Not listed above: "x='$''(rm -rf /tmp/x)'; cat <<EOF\n${x@P}\nEOF".
  472. # The scanner leaves that body unblanked (see COMPLEX_HEADERS), but
  473. # the rm is then inside a quoted assignment, which no guard inspects:
  474. # commands built at run time ("eval", "${x@P}") are outside what the
  475. # guards claim to catch, with or without a heredoc.
  476. def test_known_bypasses_reach_the_guards(self):
  477. """No reviewer-found bypass hides the rm from extract_all_commands."""
  478. for command in self.KNOWN_BYPASSES:
  479. with self.subTest(command):
  480. found = [c for c in extract_all_commands(command)
  481. if c.strip().startswith("rm ")]
  482. self.assertTrue(found, command)
  483. def test_plain_variable_on_the_header_still_blanks(self):
  484. """'cat > $HOME/x.md <<EOF' is the common case and must work."""
  485. command = "cat > $HOME/notes.md <<'EOF'\nrm -rf x is bad\nEOF"
  486. stripped, bodies = strip_heredoc_bodies(command)
  487. self.assertEqual(bodies, [])
  488. self.assertNotIn("rm -rf", stripped)
  489. command = "cat > ${DIR}/notes.md <<EOF\nrm -rf x is bad\nEOF"
  490. stripped, bodies = strip_heredoc_bodies(command)
  491. self.assertEqual(bodies, ["rm -rf x is bad\n"])
  492. self.assertNotIn("rm -rf", stripped)
  493. def test_backslash_quoted_plain_delimiter_still_blanks(self):
  494. """<<\\EOF is one of the three simple quotings and stays supported."""
  495. command = "cat <<\\EOF\n`rm x`\nEOF"
  496. stripped, bodies = strip_heredoc_bodies(command)
  497. self.assertEqual(bodies, [])
  498. self.assertNotIn("rm x", stripped)
  499. class TestExpandCommandAliases(unittest.TestCase):
  500. """Tests for expand_command_aliases() with updated operator support."""
  501. def test_empty_command(self):
  502. """Empty command returns empty string."""
  503. self.assertEqual(expand_command_aliases(""), "")
  504. def test_single_command_no_alias(self):
  505. """Single command without alias passes through."""
  506. # Commands like 'git' are skipped for alias expansion
  507. result = expand_command_aliases("git status")
  508. self.assertEqual(result, "git status")
  509. def test_preserves_pipe_operator(self):
  510. """Pipe operator is preserved in output."""
  511. result = expand_command_aliases("git log | grep fix")
  512. self.assertIn("|", result)
  513. def test_preserves_background_operator(self):
  514. """Background operator is preserved in output."""
  515. result = expand_command_aliases("git fetch & git status")
  516. self.assertIn("&", result)
  517. def test_preserves_all_operators(self):
  518. """All operators are preserved."""
  519. cmd = "cmd1 && cmd2 || cmd3; cmd4 | cmd5 & cmd6"
  520. result = expand_command_aliases(cmd)
  521. self.assertIn("&&", result)
  522. self.assertIn("||", result)
  523. self.assertIn(";", result)
  524. self.assertIn("|", result)
  525. self.assertIn("&", result)
  526. if __name__ == "__main__":
  527. unittest.main()
plugins/safety-hooks/hooks/test_rm_block_hook.py · Bundled script · 371 lines · 3 findings marked
  1. #!/usr/bin/env python3
  2. """
  3. Unit tests for rm_block_hook.py
  4. Tests cover:
  5. - Direct rm command blocking
  6. - rm with absolute paths (/bin/rm, /usr/bin/rm)
  7. - rm chained with shell operators (&&, ||, ;, |, &)
  8. - rm hidden in subshells ($() and backticks)
  9. - Safe commands that should pass through
  10. """
  11. import unittest
  12. import sys
  13. import os
  14. # Add the hooks directory to path for imports
  15. sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
  16. from rm_block_hook import check_rm_command, _is_rm_command
  17. class TestIsRmCommand(unittest.TestCase):
  18. """Tests for _is_rm_command() single command detection."""
  19. def test_bare_rm(self):
  20. """Bare 'rm' command is detected."""
  21. self.assertTrue(_is_rm_command("rm"))
  22. def test_rm_with_args(self):
  23. """rm with arguments is detected."""
  24. self.assertTrue(_is_rm_command("rm foo.txt"))
  25. self.assertTrue(_is_rm_command("rm -rf /tmp/test"))
  26. self.assertTrue(_is_rm_command("rm -f file1 file2"))
  27. def test_rm_with_path(self):
  28. """rm with absolute path is detected."""
  29. self.assertTrue(_is_rm_command("/bin/rm foo"))
  30. self.assertTrue(_is_rm_command("/usr/bin/rm -rf /"))
    • Note: Quoted as data in code: Runs `rm -rf` against a root or home-directory path
    • Line 38 on GitHub
  31. def test_not_rm_commands(self):
  32. """Commands that are not rm should not be detected."""
  33. self.assertFalse(_is_rm_command("ls"))
  34. self.assertFalse(_is_rm_command("echo rm"))
  35. self.assertFalse(_is_rm_command("grep rm file"))
  36. self.assertFalse(_is_rm_command("firmware")) # Contains 'rm' but not rm command
  37. self.assertFalse(_is_rm_command(""))
  38. def test_whitespace_handling(self):
  39. """Whitespace is normalized."""
  40. self.assertTrue(_is_rm_command(" rm foo "))
  41. self.assertTrue(_is_rm_command("\trm\t-rf\t/"))
  42. class TestCheckRmCommand(unittest.TestCase):
  43. """Tests for check_rm_command() comprehensive detection."""
  44. def test_direct_rm_blocked(self):
  45. """Direct rm commands are blocked."""
  46. blocked, reason = check_rm_command("rm foo.txt")
  47. self.assertTrue(blocked)
  48. self.assertIsNotNone(reason)
  49. def test_rm_with_path_blocked(self):
  50. """rm with absolute path is blocked."""
  51. blocked, _ = check_rm_command("/bin/rm foo")
  52. self.assertTrue(blocked)
  53. blocked, _ = check_rm_command("/usr/bin/rm -rf /")
    • Note: Quoted as data in code: Runs `rm -rf` against a root or home-directory path
    • Line 68 on GitHub
  54. self.assertTrue(blocked)
  55. def test_safe_commands_pass(self):
  56. """Safe commands are not blocked."""
  57. blocked, reason = check_rm_command("ls -la")
  58. self.assertFalse(blocked)
  59. self.assertIsNone(reason)
  60. blocked, _ = check_rm_command("git status")
  61. self.assertFalse(blocked)
  62. blocked, _ = check_rm_command("echo hello")
  63. self.assertFalse(blocked)
  64. # Security bypass tests - these are the key regression tests
  65. def test_pipe_bypass_blocked(self):
  66. """rm after pipe operator is blocked - security regression test."""
  67. blocked, _ = check_rm_command("echo ok | rm foo")
  68. self.assertTrue(blocked, "rm after pipe should be blocked")
  69. blocked, _ = check_rm_command("cat file | rm -rf /tmp")
  70. self.assertTrue(blocked, "rm in pipe chain should be blocked")
  71. def test_background_bypass_blocked(self):
  72. """rm after background operator is blocked - security regression test."""
  73. blocked, _ = check_rm_command("sleep 1 & rm foo")
  74. self.assertTrue(blocked, "rm after background operator should be blocked")
  75. blocked, _ = check_rm_command("cmd & /bin/rm bar")
  76. self.assertTrue(blocked, "rm with path after & should be blocked")
  77. def test_and_operator_blocked(self):
  78. """rm after && operator is blocked."""
  79. blocked, _ = check_rm_command("cd /tmp && rm foo")
  80. self.assertTrue(blocked)
  81. def test_or_operator_blocked(self):
  82. """rm after || operator is blocked."""
  83. blocked, _ = check_rm_command("test -f x || rm y")
  84. self.assertTrue(blocked)
  85. def test_semicolon_operator_blocked(self):
  86. """rm after ; operator is blocked."""
  87. blocked, _ = check_rm_command("echo done; rm foo")
  88. self.assertTrue(blocked)
  89. def test_subshell_dollar_paren_blocked(self):
  90. """rm inside $() subshell is blocked - security regression test."""
  91. blocked, _ = check_rm_command("echo $(rm foo)")
  92. self.assertTrue(blocked, "rm in $() subshell should be blocked")
  93. blocked, _ = check_rm_command("$(rm -rf /)")
    • Note: Quoted as data in code: Runs `rm -rf` against a root or home-directory path
    • Line 121 on GitHub
  94. self.assertTrue(blocked, "bare $() with rm should be blocked")
  95. def test_subshell_backtick_blocked(self):
  96. """rm inside backtick subshell is blocked - security regression test."""
  97. blocked, _ = check_rm_command("echo `rm foo`")
  98. self.assertTrue(blocked, "rm in backticks should be blocked")
  99. blocked, _ = check_rm_command("cat `rm bar`")
  100. self.assertTrue(blocked, "rm in backticks should be blocked")
  101. def test_quoted_heredoc_documenting_rm_is_allowed(self):
  102. """Writing a doc that mentions rm in a code span is not deletion.
  103. Regression test for issue #187: a single-quoted heredoc delimiter
  104. disables every expansion, so the backticks in the body are literal.
  105. """
  106. command = "cat > notes.md <<'MD'\nThe `rm` guard blocks deletions.\nMD"
  107. blocked, _ = check_rm_command(command)
  108. self.assertFalse(blocked, "literal rm in a quoted heredoc is data")
  109. def test_unquoted_heredoc_substitution_still_blocked(self):
  110. """An unquoted delimiter really does run the substitution."""
  111. command = "cat > notes.md <<MD\nThe `rm -rf x` guard.\nMD"
  112. blocked, _ = check_rm_command(command)
  113. self.assertTrue(blocked, "rm in an unquoted heredoc should be blocked")
  114. def test_rm_chained_after_heredoc_still_blocked(self):
  115. """Blanking the body must not hide the command that opens it."""
  116. blocked, _ = check_rm_command("cat <<'MD' && rm foo\nliteral\nMD")
  117. self.assertTrue(blocked, "rm after a heredoc redirect should be blocked")
  118. def test_comment_cannot_fake_a_heredoc(self):
  119. """A '<<' in a comment must not blank out a following rm."""
  120. blocked, _ = check_rm_command("# <<END\ntrue; rm -rf /tmp/x\nEND")
  121. self.assertTrue(blocked, "rm after a commented '<<' should be blocked")
  122. def test_comment_after_subshell_cannot_fake_a_heredoc(self):
  123. """A comment right after ')' must not blank out a following rm."""
  124. blocked, _ = check_rm_command("(echo x)# <<END\ntrue; rm -rf /tmp/x\nEND")
  125. self.assertTrue(blocked, "rm after '(...)# <<' should be blocked")
  126. def test_parameter_expansion_cannot_fake_a_heredoc(self):
  127. """'<<' in ${x:-<<EOF} must not blank out a following rm."""
  128. blocked, _ = check_rm_command("echo ${x:-<<EOF}\ntrue; rm -rf /tmp/x\nEOF}")
  129. self.assertTrue(blocked, "rm after '${x:-<<EOF}' should be blocked")
  130. def test_arithmetic_shift_cannot_fake_a_heredoc(self):
  131. """A left shift in $(( )) must not blank out a following rm."""
  132. blocked, _ = check_rm_command("echo $((1 << 2))\ntrue; rm -rf /tmp/x\n2")
  133. self.assertTrue(blocked, "rm after an arithmetic shift should be blocked")
  134. def test_newline_separated_rm_is_blocked(self):
  135. """A newline ends a command, so the next line is a command too."""
  136. blocked, _ = check_rm_command("echo hi\nrm -rf /tmp/x")
  137. self.assertTrue(blocked, "rm on its own line should be blocked")
  138. def test_ansi_c_delimiter_cannot_fake_a_heredoc(self):
  139. """<<$'EOF' ends at EOF, so a later rm is not inside the body."""
  140. command = "cat <<$'EOF'\nliteral\nEOF\nrm -rf /tmp/x\n$EOF"
  141. blocked, _ = check_rm_command(command)
  142. self.assertTrue(blocked, "rm after a $'EOF' heredoc should be blocked")
  143. def test_escaped_brace_cannot_fake_a_heredoc(self):
  144. """'\\}' does not close ${...}, so '<<EOF' in it opens no heredoc."""
  145. blocked, _ = check_rm_command(
  146. "echo ${x:-\\}<<EOF}\nrm -rf /tmp/x\nEOF}")
  147. self.assertTrue(blocked, "rm after '${x:-\\}<<EOF}' should be blocked")
  148. def test_line_continuation_cannot_hide_rm_in_a_body(self):
  149. """A continued header means the rm runs before the body starts."""
  150. command = "cat <<EOF ; \\\nrm -rf /tmp/x\nliteral\nEOF"
  151. blocked, _ = check_rm_command(command)
  152. self.assertTrue(blocked, "rm on a continued header should be blocked")
  153. def test_second_heredoc_body_cannot_hide_rm(self):
  154. """Both bodies on a two-heredoc header are data, so the rm is not."""
  155. command = "cat <<A <<'B'\nfirst\nA\necho <<X\nB\nrm -rf /tmp/x\nX"
  156. blocked, _ = check_rm_command(command)
  157. self.assertTrue(blocked, "rm after two heredoc bodies should be blocked")
  158. def test_documenting_rm_in_a_second_heredoc_body_is_allowed(self):
  159. """The second body is data, so documenting rm in it is not deletion."""
  160. command = "cat <<A <<'B'\nliteral a\nA\nThe `rm -rf x` guard\nB"
  161. blocked, _ = check_rm_command(command)
  162. self.assertFalse(blocked, "literal rm in the second body is data")
  163. def test_continued_delimiter_word_cannot_hide_rm(self):
  164. """"E\\"+"OF" is the delimiter EOF, so the rm after that body runs."""
  165. command = "cat <<E\\\nOF\necho <<X\nEOF\nrm -rf /tmp/x\nX"
  166. blocked, _ = check_rm_command(command)
  167. self.assertTrue(blocked, "rm after a continued delimiter word blocks")
  168. def test_nested_heredoc_in_a_substitution_cannot_hide_rm(self):
  169. """The inner heredoc ends inside $( ), leaving the rm a command."""
  170. command = "cat <<OUT $(cat <<IN\n)\nIN\nrm -rf /tmp/x\n)\nouter\nOUT"
  171. blocked, _ = check_rm_command(command)
  172. self.assertTrue(blocked, "rm inside the substitution should be blocked")
  173. def test_undecodable_delimiter_cannot_hide_rm(self):
  174. """Bash ends that body at EOF, so the rm after it is a command."""
  175. command = "cat <<$'E\\x4fF'\necho <<X\nEOF\nrm -rf /tmp/x\nX"
  176. blocked, _ = check_rm_command(command)
  177. self.assertTrue(blocked, "rm after an escaped delimiter's body blocks")
  178. def test_case_pattern_paren_cannot_hide_rm(self):
  179. """The substitution stays open past a case pattern's ')'."""
  180. command = ("cat <<EOF $(case x in x) echo yes;; esac\n"
  181. "rm -rf /tmp/x\n)\nliteral\nEOF")
  182. blocked, _ = check_rm_command(command)
  183. self.assertTrue(blocked, "rm inside a still-open $( ) should be blocked")
  184. def test_herestring_cannot_fake_a_heredoc(self):
  185. """'cat <<<input' opens no heredoc, so the next line is a command."""
  186. blocked, _ = check_rm_command("cat <<<input\nrm -rf /tmp/x\ninput")
  187. self.assertTrue(blocked, "rm after a here-string should be blocked")
  188. def test_legacy_arithmetic_shift_cannot_fake_a_heredoc(self):
  189. """A shift in the deprecated $[ ] form must not blank a following rm."""
  190. blocked, _ = check_rm_command("echo $[1 << 2]\nrm -rf /tmp/x\n2]")
  191. self.assertTrue(blocked, "rm after 'echo $[1 << 2]' should be blocked")
  192. def test_array_subscript_shift_cannot_fake_a_heredoc(self):
  193. """A shift inside an array subscript must not blank a following rm."""
  194. blocked, _ = check_rm_command("a[1<<2]=foo\nrm -rf /tmp/x\n2]=foo")
  195. self.assertTrue(blocked, "rm after 'a[1<<2]=foo' should be blocked")
  196. def test_process_substitution_cannot_hide_rm(self):
  197. """The rm runs inside <( ), before the heredoc body starts."""
  198. command = "cat <<EOF <(echo x\nrm -rf /tmp/x\n)\nliteral\nEOF"
  199. blocked, _ = check_rm_command(command)
  200. self.assertTrue(blocked, "rm inside <( ) on the header is a command")
  201. def test_localized_quote_delimiter_cannot_hide_rm(self):
  202. """$\"A\\\\B\" unescapes, so bash ends that body before the rm."""
  203. command = 'cat <<$"A\\\\B"\ndata\nA\\B\nrm -rf /tmp/x\nA\\\\B'
  204. blocked, _ = check_rm_command(command)
  205. self.assertTrue(blocked, "rm after a '$\"A\\\\B\"' body should be blocked")
  206. def test_double_quoted_escape_delimiter_cannot_hide_rm(self):
  207. """Bash ends that body at 'A\\B', so the next line is a command."""
  208. command = 'cat <<"A\\\\B"\ndata\nA\\B\nrm -rf /tmp/x\nA\\\\B'
  209. blocked, _ = check_rm_command(command)
  210. self.assertTrue(blocked, "rm after a '\"A\\\\B\"' body should be blocked")
  211. def test_continued_delimiter_line_cannot_hide_rm(self):
  212. """An unquoted body ends at a delimiter split across two lines."""
  213. command = "cat <<EOF\ndata\nEO\\\nF\nrm -rf /tmp/x\nEOF"
  214. blocked, _ = check_rm_command(command)
  215. self.assertTrue(blocked, "rm after a continued delimiter is a command")
  216. def test_nested_group_paren_cannot_hide_rm(self):
  217. """The substitution is still open, so the rm inside it is a command."""
  218. command = "cat <<EOF $( (echo x)\nrm -rf /tmp/x\n)\nliteral\nEOF"
  219. blocked, _ = check_rm_command(command)
  220. self.assertTrue(blocked, "rm inside a still-open $( ) should be blocked")
  221. def test_substitution_delimiter_cannot_fake_a_heredoc(self):
  222. """'<<$(echo EOF)' ends at that literal line, so the rm is a command."""
  223. command = "cat <<$(echo EOF)\npayload\n$(echo EOF)\nrm -rf /tmp/x\n$"
  224. blocked, _ = check_rm_command(command)
  225. self.assertTrue(blocked, "rm after a '$(echo EOF)' body should be blocked")
  226. def test_rm_in_a_substitution_before_the_body_is_blocked(self):
  227. """An unfinished $( ) means the rm runs before the body starts."""
  228. command = "cat <<'EOF' $(echo start\nrm -rf /tmp/x)\nliteral\nEOF"
  229. blocked, _ = check_rm_command(command)
  230. self.assertTrue(blocked, "rm inside $( ) on the header is a command")
  231. def test_rm_in_backticks_before_the_body_is_blocked(self):
  232. """Backticks hold the header open just as $( ) does."""
  233. command = "cat <<'EOF' `echo start\nrm -rf /tmp/x`\nliteral\nEOF"
  234. blocked, _ = check_rm_command(command)
  235. self.assertTrue(blocked, "rm inside backticks on the header is a command")
  236. def test_bodyless_heredoc_in_a_substitution_cannot_hide_rm(self):
  237. """The substitution closes first, so the next line is a command."""
  238. command = "echo $(cat <<'EOF') tail\nrm -rf /tmp/x\nEOF"
  239. blocked, _ = check_rm_command(command)
  240. self.assertTrue(blocked, "rm is not a body when the body never starts")
  241. def test_documenting_rm_inside_a_substitution_heredoc_over_blocks(self):
  242. """A heredoc inside $( ) is not blanked, so this over-blocks.
  243. That is the chosen failure direction: substitutions on the header
  244. line are where every known bypass lived.
  245. """
  246. command = "echo $(cat <<'EOF'\nThe `rm -rf x` guard.\nEOF\n)"
  247. blocked, _ = check_rm_command(command)
  248. self.assertTrue(blocked, "complex header: body is not blanked")
  249. def test_complex_bypass_attempts(self):
  250. """Complex commands attempting to hide rm are blocked."""
  251. # Multiple levels of indirection
  252. blocked, _ = check_rm_command("echo safe | cat | rm evil")
  253. self.assertTrue(blocked, "rm at end of pipe chain should be blocked")
  254. # Subshell inside chained command
  255. blocked, _ = check_rm_command("echo $(rm foo) && ls")
  256. self.assertTrue(blocked, "rm in subshell with && should be blocked")
  257. # Background with subshell
  258. blocked, _ = check_rm_command("$(rm x) & echo done")
  259. self.assertTrue(blocked, "rm in subshell with & should be blocked")
  260. def test_nested_subshell_bypass_blocked(self):
  261. """rm hidden in nested $() subshells is blocked - P1 security fix."""
  262. # This was a bypass: the regex stopped at first ), missing inner rm
  263. blocked, _ = check_rm_command("echo $(echo $(rm foo))")
  264. self.assertTrue(blocked, "rm in nested subshell should be blocked")
  265. # Deeper nesting
  266. blocked, _ = check_rm_command("$(cat $(ls $(rm secret)))")
  267. self.assertTrue(blocked, "rm in deeply nested subshell should be blocked")
  268. def test_reason_message_content(self):
  269. """Blocked commands include helpful guidance in reason."""
  270. blocked, reason = check_rm_command("rm foo")
  271. self.assertTrue(blocked)
  272. self.assertIn("TRASH", reason)
  273. self.assertIn("mv", reason)
  274. self.assertIn("TRASH-FILES.md", reason)
  275. class TestEdgeCases(unittest.TestCase):
  276. """Edge case tests for robustness."""
  277. def test_empty_command(self):
  278. """Empty command is not blocked."""
  279. blocked, _ = check_rm_command("")
  280. self.assertFalse(blocked)
  281. def test_whitespace_only(self):
  282. """Whitespace-only command is not blocked."""
  283. blocked, _ = check_rm_command(" ")
  284. self.assertFalse(blocked)
  285. def test_rm_in_string_not_blocked(self):
  286. """String containing 'rm' but not as command passes."""
  287. # 'rm' as part of echo string
  288. blocked, _ = check_rm_command("echo 'do not rm this'")
  289. self.assertFalse(blocked, "rm in quoted string should not be blocked")
  290. def test_command_starting_with_rm_prefix(self):
  291. """Commands starting with 'rm' prefix but not rm command."""
  292. blocked, _ = check_rm_command("rmdir empty_dir")
  293. self.assertFalse(blocked, "rmdir should not be blocked")
  294. if __name__ == "__main__":
  295. unittest.main()
plugins/writing/skills/remove-ai-patterns/upstream/detector/patterns.js · Bundled script · 1,892 lines
  1. /**
  2. * Avoid AI Writing — detection engine (canonical source of truth)
  3. * Implements 45-category pattern detection. This repo's SKILL.md
  4. * catalogs the human-editable pattern rules; this engine is the executable
  5. * expression of the regex-detectable subset and extends it with stylometric and
  6. * AI-tool-fingerprint detectors that don't make sense as skill prose
  7. * (cross-paragraph burstiness, smart-punct signatures, function-word
  8. * trigram entropy, low type-token ratio, AI-tool URL parameters,
  9. * chatbot citation markup leaks, unfilled placeholders).
  10. *
  11. * Scoring model:
  12. * Each category has a weight in the ISSUE_WEIGHTS table. Detection runs
  13. * produce raw (possibly duplicate) issues which are then deduplicated by
  14. * (type, text) pair. rawScore is the sum of category weights across the
  15. * deduped list — so the number reflects the same distinct signals the
  16. * user sees in the issue list.
  17. *
  18. * Weights are deliberately non-flat across severity tags. Cutoff
  19. * disclaimers (10) and chatbot artifacts (8) weigh more than vague
  20. * attributions (5), even though all three are tagged `critical`, because
  21. * the skill treats them as stronger or weaker AI-origin signals.
  22. *
  23. * rawScore is then normalized to 0-100 via `log2(wordCount/50)` so longer
  24. * texts don't accumulate unboundedly on the same density of patterns.
  25. */
  26. const AIDetector = (() => {
  27. // ═══ Tier 1 pre-pass: normalize bypass tricks ══════════════════════
  28. //
  29. // Humanizer tools and prompt-injection bypass techniques insert
  30. // invisible / lookalike chars to defeat exact-string detectors. Strip
  31. // them BEFORE pattern matching so "delve" with a Cyrillic 'е' still
  32. // hits the Tier 1 list. Unicode ranges sourced from
  33. // It-s-AI/llm-detection/detection/attacks/.
  34. //
  35. // Tracks what was stripped so the trinary classifier can use
  36. // "normalization triggered" as a corroborating AI signal — humans don't
  37. // paste ZWSPs into their own writing.
  38. const CYRILLIC_LOOKALIKES = {
  39. 'а': 'a', 'е': 'e', 'о': 'o', 'р': 'p', 'с': 'c', 'х': 'x',
  40. 'у': 'y', 'к': 'k', 'м': 'm', 'н': 'h', 'в': 'b', 'т': 't',
  41. 'А': 'A', 'Е': 'E', 'О': 'O', 'Р': 'P', 'С': 'C', 'Х': 'X',
  42. 'У': 'Y', 'К': 'K', 'М': 'M', 'Н': 'H', 'В': 'B', 'Т': 'T',
  43. };
  44. const GREEK_LOOKALIKES = { 'ο': 'o', 'Ο': 'O', 'α': 'a', 'Α': 'A', 'ρ': 'p', 'Ρ': 'P' };
  45. function normalizeText(text) {
  46. const flags = { zeroWidth: 0, homoglyph: 0, roleplay: 0 };
  47. let out = text;
  48. // 1. Strip zero-width chars (ZWSP U+200B, ZWNJ U+200C, ZWJ U+200D,
  49. // BOM U+FEFF, word joiner U+2060).
  50. out = out.replace(/[​-‍⁠]/g, () => { flags.zeroWidth++; return ''; });
  51. // 2. Swap Cyrillic / Greek Latin-lookalike chars back to Latin so
  52. // pattern matching catches obfuscated tokens.
  53. out = out.replace(/[Ѐ-ӿͰ-Ͽ]/g, (m) => {
  54. const swap = CYRILLIC_LOOKALIKES[m] ?? GREEK_LOOKALIKES[m];
  55. if (swap) { flags.homoglyph++; return swap; }
  56. return m;
  57. });
  58. // 3. Strip *roleplay-action* markers — paired *...* containing an
  59. // action verb (nods, sighs, laughs, smiles, etc.) anchored to
  60. // the start of the inner phrase. This is the actual chat-model
  61. // artifact shape. Markdown `**bold**` is rejected by the
  62. // lookbehind/lookahead; legitimate multi-word `*italic*` is
  63. // preserved because the verb whitelist is narrow.
  64. const ROLEPLAY_VERBS = /^(?:nods|sighs|laughs|smiles|frowns|shrugs|grins|winks|chuckles|gasps|pauses|thinks|wonders|whispers|shouts|gestures|raises|leans|turns|looks|glances|smirks|blinks|nodding|sighing|laughing|smiling|thinking|gesturing)\b/i;
  65. out = out.replace(/(?<!\*)\*([^*\n]{1,80}?)\*(?!\*)/gu, (m, inner) => {
  66. if (ROLEPLAY_VERBS.test(inner)) { flags.roleplay++; return ''; }
  67. return m;
  68. });
  69. return { text: out, flags };
  70. }
  71. // ─── Tier 1: Always flag ───────────────────────────────────────────
  72. const TIER1 = {
  73. 'delve': 'explore, dig into, look at',
  74. 'tapestry': 'describe the actual complexity',
  75. 'paradigm': 'model, approach, framework',
  76. 'beacon': 'rewrite entirely',
  77. 'robust': 'strong, reliable, solid',
  78. 'comprehensive': 'thorough, complete, full',
  79. 'cutting-edge': 'latest, newest, advanced',
  80. 'pivotal': 'important, key, critical',
  81. 'meticulous': 'careful, detailed, precise',
  82. 'meticulously': 'carefully, precisely',
  83. 'seamless': 'smooth, easy, without friction',
  84. 'seamlessly': 'smoothly, easily',
  85. 'game-changer': 'describe what changed',
  86. 'game-changing': 'describe what changed',
  87. 'nestled': 'is located, sits',
  88. 'vibrant': 'describe what makes it active',
  89. 'thriving': 'growing, active',
  90. 'bustling': 'busy, active',
  91. 'intricate': 'complex, detailed',
  92. 'intricacies': 'complexities, details',
  93. 'ever-evolving': 'changing, growing',
  94. 'enduring': 'lasting, long-running',
  95. 'daunting': 'hard, difficult',
  96. 'holistic': 'complete, full, whole',
  97. 'holistically': 'completely, fully',
  98. 'actionable': 'practical, useful, concrete',
  99. 'impactful': 'effective, significant',
  100. 'learnings': 'lessons, findings, takeaways',
  101. 'synergy': 'describe the combined effect',
  102. 'synergies': 'describe the combined effect',
  103. 'interplay': 'relationship, connection',
  104. 'symphony': 'describe the coordination',
  105. 'embrace': 'adopt, accept, use',
  106. };
  107. // Multi-word tier 1 phrases
  108. const TIER1_PHRASES = [
  109. { pattern: /\bdelve\s+into\b/gi, replace: 'explore, dig into' },
  110. { pattern: /\blandscape\b/gi, replace: 'field, space, industry', filter: true },
  111. { pattern: /\brealm\b/gi, replace: 'area, field, domain' },
  112. { pattern: /\btestament\s+to\b/gi, replace: 'shows, proves' },
  113. { pattern: /\bleverag(?:e|es|ing|ed)\b/gi, replace: 'use' },
  114. { pattern: /\bwatershed\s+moment\b/gi, replace: 'turning point, shift' },
  115. { pattern: /\bmarking\s+a\s+pivotal\s+moment\b/gi, replace: 'state what happened' },
  116. { pattern: /\bthe\s+future\s+looks\s+bright\b/gi, replace: 'cut or say something specific' },
  117. { pattern: /\bonly\s+time\s+will\s+tell\b/gi, replace: 'cut or say something specific' },
  118. { pattern: /\bdespite\s+challenges[^.]*continues?\s+to\s+thrive\b/gi, replace: 'name the challenge and response' },
  119. { pattern: /\bdeep\s+dive\b/gi, replace: 'look at, examine' },
  120. { pattern: /\bdive\s+into\b/gi, replace: 'look at, examine' },
  121. { pattern: /\bunpack(?:ing)?\b/gi, replace: 'explain, break down' },
  122. { pattern: /\bcomplexities\b/gi, replace: 'name the actual problems' },
  123. { pattern: /\bthought\s+leader(?:ship)?\b/gi, replace: 'expert, authority' },
  124. { pattern: /\bbest\s+practices\b/gi, replace: 'what works, proven methods' },
  125. { pattern: /\bat\s+its\s+core\b/gi, replace: 'cut, just state it' },
  126. { pattern: /\bin\s+order\s+to\b/gi, replace: 'to', clarity: true },
  127. { pattern: /\bdue\s+to\s+the\s+fact\s+that\b/gi, replace: 'because', clarity: true },
  128. { pattern: /\bserves\s+as\b/gi, replace: 'is', clarity: true },
  129. { pattern: /\bfeatures\b/gi, replace: 'has, includes', filter: true, clarity: true },
  130. { pattern: /\bboasts\b/gi, replace: 'has', clarity: true },
  131. { pattern: /\butiliz(?:e|es|ing|ed)\b/gi, replace: 'use', clarity: true },
  132. { pattern: /\bshowcas(?:e|es|ing|ed)\b/gi, replace: 'show, demonstrate' },
  133. { pattern: /\bembark(?:s|ing|ed)?\b/gi, replace: 'start, begin' },
  134. { pattern: /\bcommenc(?:e|es|ing|ed)\b/gi, replace: 'start, begin', clarity: true },
  135. { pattern: /\bascertain(?:s|ing|ed)?\b/gi, replace: 'find out, determine', clarity: true },
  136. { pattern: /\bendeavou?r(?:s|ing|ed)?\b/gi, replace: 'effort, attempt, try', clarity: true },
  137. { pattern: /\bunderscor(?:es|ing|ed)\b/gi, replace: 'highlights, shows' },
  138. // Hyphen required. The unhyphenated "load bearing" is ordinary English —
  139. // "the load bearing down on the bridge" — where `bearing` is a participle,
  140. // not part of a compound modifier. The tell is always hyphenated.
  141. //
  142. // Construction carve-out: exempt attributive `load-bearing` before a literal
  143. // structural noun, with one optional material/position adjective in between
  144. // ("load-bearing structural wall"). The noun list is limited to commonly
  145. // physical nouns; the abstract-capable ones most likely to carry the
  146. // metaphor (structure, element, frame, foundation) are omitted so "the
  147. // load-bearing structure of the argument" still fires. Some listed nouns
  148. // (member, column, partition) can still be used metaphorically and are
  149. // silently exempt — a recall loss in the safe direction, tracked in #56.
  150. // Predicative use ("the wall is load-bearing") is NOT exempt: the tell
  151. // lives in the subject, which a lookahead cannot reach. Also #56.
  152. { pattern: /\bload-bearing\b(?!\s+(?:(?:structural|exterior|interior|internal|external|concrete|steel|timber|wooden|brick|masonry|perimeter|basement|main|primary|existing|original)\s+)?(?:walls?|beams?|columns?|joists?|truss(?:es)?|members?|footings?|slabs?|studs?|partitions?|masonry|lintels?|piers?|rafters?|girders?|capacity|capacities)\b)/gi, replace: 'essential, critical, or say what breaks if you remove it' },
  153. ];
  154. // ─── Tier 2: Flag in clusters (2+ per paragraph) ──────────────────
  155. const TIER2 = {
  156. 'harness': 'use, take advantage of',
  157. 'navigate': 'work through, handle',
  158. 'navigating': 'working through, handling',
  159. 'foster': 'encourage, support, build',
  160. 'elevate': 'improve, raise, strengthen',
  161. 'unleash': 'release, enable, unlock',
  162. 'streamline': 'simplify, speed up',
  163. 'empower': 'enable, let, allow',
  164. 'bolster': 'support, strengthen',
  165. 'spearhead': 'lead, drive, run',
  166. 'resonate': 'connect with, appeal to',
  167. 'resonates': 'connects with, appeals to',
  168. 'revolutionize': 'change, transform',
  169. 'facilitate': 'enable, help, allow',
  170. 'facilitates': 'enables, helps, allows',
  171. 'underpin': 'support, form the basis of',
  172. 'nuanced': 'specific, subtle, detailed',
  173. 'crucial': 'important, key, necessary',
  174. 'multifaceted': 'describe the actual facets',
  175. 'ecosystem': 'system, community, network',
  176. 'myriad': 'many, numerous',
  177. 'plethora': 'many, a lot of',
  178. 'encompass': 'include, cover, span',
  179. 'catalyze': 'start, trigger, accelerate',
  180. 'reimagine': 'rethink, redesign, rebuild',
  181. 'galvanize': 'motivate, rally, push',
  182. 'augment': 'add to, expand, supplement',
  183. 'cultivate': 'build, develop, grow',
  184. 'illuminate': 'clarify, explain, show',
  185. 'elucidate': 'explain, clarify',
  186. 'juxtapose': 'compare, contrast',
  187. 'transformative': 'describe what changed',
  188. 'transformation': 'describe what changed',
  189. 'cornerstone': 'foundation, basis, key part',
  190. 'paramount': 'most important, top priority',
  191. 'poised': 'ready, set, about to',
  192. 'burgeoning': 'growing, emerging',
  193. 'nascent': 'new, early-stage',
  194. 'quintessential': 'typical, classic, defining',
  195. 'overarching': 'main, central, broad',
  196. 'quietly': 'cut, or name the concrete contrast',
  197. 'underpinning': 'basis, foundation',
  198. 'underpinnings': 'basis, foundations',
  199. 'paradigm-shifting': 'describe what shifted',
  200. };
  201. // Conditional Tier 2 entries: everyday words whose AI tell is a specific
  202. // significance collocation, not the word itself. They join a paragraph's
  203. // Tier 2 cluster only when the collocation matches — bare uses ("deeply
  204. // nested JSON", "cares deeply") never count, because the base rate of
  205. // these words in innocent prose is far higher than the rest of the table
  206. // and an unconditional entry measurably flags clean human writing.
  207. const TIER2_CONDITIONAL = [
  208. {
  209. word: 'deeply',
  210. pattern: /\bdeeply\s+(?:integrated|committed|rooted|personal|human|flawed|resonant|transformative|interconnected|ingrained|embedded|meaningful)\b/i,
  211. suggestion: 'cut, or name what specifically runs deep',
  212. },
  213. ];
  214. // ─── Tier 3: Flag by density ───────────────────────────────────────
  215. const TIER3 = [
  216. 'significant', 'significantly', 'innovative', 'innovation',
  217. 'effective', 'effectively', 'dynamic', 'dynamics',
  218. 'scalable', 'scalability', 'compelling', 'unprecedented',
  219. 'exceptional', 'exceptionally', 'remarkable', 'remarkably',
  220. 'sophisticated', 'instrumental',
  221. 'world-class', 'state-of-the-art', 'best-in-class',
  222. // `verbatim` is usually redundant with the verb it modifies ("copies X
  223. // verbatim" = "copies X"). It has a genuine term-of-art sense in legal,
  224. // research, and QA registers ("verbatim transcript"), so it lives at Tier 3:
  225. // density-gated, it only fires on overuse, not on a single legitimate use.
  226. 'verbatim',
  227. ];
  228. // Multi-word Tier 3 phrases. Density-gated like single Tier 3 words because
  229. // these legitimately show up in human crypto/web3/dev writing. Threshold is
  230. // intentionally lower than single-word Tier 3 (≥2 occurrences of the same
  231. // phrase) — repeating the same multi-word boilerplate is a stronger AI tell
  232. // than re-using "significant."
  233. const TIER3_PHRASES = [
  234. /\bemerging\s+(?:sector|space|category|industry)\b/gi,
  235. /\bthe\s+integration\s+of\b/gi,
  236. /\bthe\s+intersection\s+of\b/gi,
  237. /\bcommunity-?driven\b/gi,
  238. /\blong-?term\s+sustainability\b/gi,
  239. /\buser\s+engagement\b/gi,
  240. /\bdecentralized\s+compute\b/gi,
  241. /\b(?:sustainable\s+)?reward\s+emissions?\b/gi,
  242. /\btokenized\s+incentive\s+structures?\b/gi,
  243. /\bdesigned\s+for\s+long-?term\b/gi,
  244. ];
  245. // O(1) lookup from any token form (hyphenated or dashless) to its canonical
  246. // Tier 3 word. Counting originally did nested-loop word matching which was
  247. // O(tokens × TIER3) — slow on long pastes.
  248. const TIER3_LOOKUP = new Map();
  249. for (const word of TIER3) {
  250. TIER3_LOOKUP.set(word, word);
  251. const dashless = word.replace(/-/g, '');
  252. if (dashless !== word) TIER3_LOOKUP.set(dashless, word);
  253. }
  254. // Per-category score weights. Applied to distinct (deduplicated) issues so
  255. // the score reflects the same signals the user sees in the issue list.
  256. // Non-uniform on purpose: critical rules like cutoff disclaimers (×10) and
  257. // chatbot artifacts (×8) weigh more than vague attributions (×5), even
  258. // though all three are tagged `critical`.
  259. const ISSUE_WEIGHTS = {
  260. tier1: 5,
  261. // Wordiness, not an AI-frequency marker. Weighted like tier2 so a
  262. // clarity fix cannot push a document toward an AI classification.
  263. 'tier1-clarity': 3,
  264. tier2: 3,
  265. tier3: 2,
  266. transition: 2,
  267. chatbot: 8,
  268. sycophantic: 8,
  269. filler: 2,
  270. 'generic-conclusion': 3,
  271. 'lets-construction': 2,
  272. 'reasoning-artifact': 6,
  273. 'acknowledgment-loop': 3,
  274. 'significance-inflation': 4,
  275. 'vague-attribution': 5,
  276. 'hollow-intensifier': 2,
  277. 'emotional-flatline': 2,
  278. 'lingering-attention': 3,
  279. 'novelty-inflation': 3,
  280. 'cutoff-disclaimer': 10,
  281. 'template-phrase': 3,
  282. 'false-concession': 2,
  283. 'rhetorical-question': 2,
  284. 'confidence-calibration': 2,
  285. 'em-dash': 4,
  286. uniformity: 5,
  287. formatting: 3,
  288. 'tier3-phrase': 3,
  289. // Structural / cluster signals are deliberately weighted high. Unlike
  290. // single-vocabulary hits they're near-dispositive on social-length
  291. // posts (a 15-hashtag block, a 6-item bullet-NP list, three distinct
  292. // crypto-shill phrases stacked) and would otherwise be suppressed by
  293. // the log2(words/50) length divisor on short pastes.
  294. 'tier3-phrase-cluster': 12,
  295. 'hashtag-stuff': 12,
  296. 'bullet-np-list': 10,
  297. 'hedge-stack': 6,
  298. 'future-narrative': 12,
  299. 'real-actual-inflation': 5,
  300. // Social endorsement / CTA closer. Weighted like formulaic-opener: a
  301. // strong single-hit social tell that the length divisor would
  302. // otherwise wash out on a short LinkedIn-length post.
  303. 'social-cta-closer': 8,
  304. 'formulaic-opener': 8,
  305. // Speculative scenario opener ("Imagine a world where…"). Weighted like
  306. // formulaic-opener: a single strong opener tell the length divisor would
  307. // otherwise wash out on a short post.
  308. 'speculative-opener': 8,
  309. 'title-case-header': 4,
  310. 'parenthetical-hedge': 3,
  311. 'smart-punct-signature': 6,
  312. 'punct-distribution': 6,
  313. 'fnword-trigram-entropy': 5,
  314. 'cross-para-burstiness': 5,
  315. 'normalization-flag': 9,
  316. // Vocabulary-diversity signal (type-token ratio). Weighted modestly
  317. // because the threshold (>=200 tokens AND TTR<0.4) is conservative;
  318. // it stacks with structural signals to push borderline scores up.
  319. 'low-ttr': 3,
  320. // AI-tool fingerprints. Weighted higher than statistical patterns
  321. // because each is a near-definitive single-hit signal — the AI tool
  322. // literally left its mark in the text. citation-markup ranks highest
  323. // (smoking gun: the literal internal markup of ChatGPT/Grok/etc.),
  324. // UTM tracking second (auto-appended by the tool to URLs it writes),
  325. // placeholders third (strong but humans use bracketed slots in
  326. // templates legitimately and forget them — still a publishing bug
  327. // but slightly less definitive AI evidence).
  328. 'ai-placeholder': 10,
  329. 'ai-citation-markup': 15,
  330. 'ai-utm-source': 12,
  331. };
  332. // ─── Transition phrases ────────────────────────────────────────────
  333. const TRANSITIONS = [
  334. /\bmoreover\b/gi,
  335. /\bfurthermore\b/gi,
  336. /\badditionally\b/gi,
  337. /\bin\s+today'?s\b/gi,
  338. /\bin\s+an\s+era\s+where\b/gi,
  339. /\bit'?s\s+worth\s+noting\s+that\b/gi,
  340. /\bnotably\b/gi,
  341. /\bin\s+conclusion\b/gi,
  342. /\bin\s+summary\b/gi,
  343. /\bto\s+summarize\b/gi,
  344. /\bwhen\s+it\s+comes\s+to\b/gi,
  345. /\bat\s+the\s+end\s+of\s+the\s+day\b/gi,
  346. /\bthat\s+(?:being\s+)?said\b/gi,
  347. ];
  348. // ─── Chatbot artifacts ─────────────────────────────────────────────
  349. const CHATBOT_ARTIFACTS = [
  350. /\bi\s+hope\s+this\s+helps\b/gi,
  351. /\bcertainly!\b/gi,
  352. /\babsolutely!\b/gi,
  353. /\bgreat\s+question!\b/gi,
  354. /\bexcellent\s+point!\b/gi,
  355. /\bfeel\s+free\s+to\s+reach\s+out\b/gi,
  356. /\blet\s+me\s+know\s+if\s+you\s+need\s+anything\b/gi,
  357. /\bin\s+this\s+article,?\s+we\s+will\s+explore\b/gi,
  358. /\blet'?s\s+dive\s+in!?\b/gi,
  359. ];
  360. // ─── Sycophantic tone ──────────────────────────────────────────────
  361. const SYCOPHANTIC = [
  362. /\byou'?re\s+absolutely\s+right\b/gi,
  363. /\bthat'?s\s+a\s+really\s+insightful\b/gi,
  364. /\bthat'?s\s+a\s+great\s+question\b/gi,
  365. /\bexcellent\s+question\b/gi,
  366. ];
  367. // ─── Filler phrases ────────────────────────────────────────────────
  368. const FILLERS = [
  369. /\bit\s+is\s+important\s+to\s+note\s+that\b/gi,
  370. /\bin\s+terms\s+of\b/gi,
  371. /\bthe\s+reality\s+is\s+that\b/gi,
  372. /\bit'?s\s+important\s+to\s+note\s+that\b/gi,
  373. ];
  374. // ─── Generic conclusions ───────────────────────────────────────────
  375. const GENERIC_CONCLUSIONS = [
  376. /\bthe\s+future\s+looks\s+bright\b/gi,
  377. /\bonly\s+time\s+will\s+tell\b/gi,
  378. /\bone\s+thing\s+is\s+certain\b/gi,
  379. /\bas\s+we\s+move\s+forward\b/gi,
  380. ];
  381. // ─── "Let's" constructions ─────────────────────────────────────────
  382. const LETS_PATTERNS = [
  383. /\blet'?s\s+explore\b/gi,
  384. /\blet'?s\s+take\s+a\s+look\b/gi,
  385. /\blet'?s\s+break\s+this\s+down\b/gi,
  386. /\blet'?s\s+examine\b/gi,
  387. /\blet'?s\s+(?:consider|discuss|delve|unpack|walk\s+through)\b/gi,
  388. ];
  389. // ─── Reasoning chain artifacts ─────────────────────────────────────
  390. const REASONING_ARTIFACTS = [
  391. /\blet\s+me\s+think\s+step\s+by\s+step\b/gi,
  392. /\bbreaking\s+this\s+down\b/gi,
  393. /\bto\s+approach\s+this\s+systematically\b/gi,
  394. /\bhere'?s\s+my\s+thought\s+process\b/gi,
  395. /\bfirst,?\s+let'?s\s+consider\b/gi,
  396. /\bworking\s+through\s+this\s+logically\b/gi,
  397. ];
  398. // ─── Acknowledgment loops ──────────────────────────────────────────
  399. const ACKNOWLEDGMENT_LOOPS = [
  400. /\byou'?re\s+asking\s+about\b/gi,
  401. /\bthe\s+question\s+of\s+whether\b/gi,
  402. /\bto\s+answer\s+your\s+question\b/gi,
  403. ];
  404. // ─── Significance inflation ────────────────────────────────────────
  405. const SIGNIFICANCE_INFLATION = [
  406. /\bmarking\s+a\s+(?:pivotal|significant|important)\s+moment\b/gi,
  407. /\ba\s+watershed\s+moment\s+for\b/gi,
  408. /\bin\s+the\s+evolution\s+of\b/gi,
  409. /\ba\s+(?:pivotal|defining)\s+moment\s+in\b/gi,
  410. ];
  411. // ─── Vague attributions ────────────────────────────────────────────
  412. const VAGUE_ATTRIBUTIONS = [
  413. /\bexperts\s+(?:believe|say|suggest|agree)\b/gi,
  414. /\bstudies\s+(?:show|suggest|indicate)\b/gi,
  415. /\bresearch\s+(?:shows|suggests|indicates)\b/gi,
  416. /\bindustry\s+leaders\s+(?:agree|believe|say)\b/gi,
  417. ];
  418. // ─── Hollow intensifiers ──────────────────────────────────────────
  419. const HOLLOW_INTENSIFIERS = [
  420. /\bgenuine(?:ly)?\b/gi,
  421. /\btruly\b/gi,
  422. /\bquite\s+frankly\b/gi,
  423. /\bto\s+be\s+honest\b/gi,
  424. /\blet'?s\s+be\s+clear\b/gi,
  425. ];
  426. // ─── Emotional flatline ────────────────────────────────────────────
  427. // The "interesting (part|thing|aspect|piece)" family is matched in two
  428. // shapes: (1) "the most interesting X" inline (the canonical AI list
  429. // intro), and (2) bare "Interesting X:" used as a section-header opener,
  430. // which is the section-break variant that slipped past v3.3.x.
  431. const EMOTIONAL_FLATLINE = [
  432. /\bwhat\s+surprised\s+me\s+most\b/gi,
  433. /\bi\s+was\s+fascinated\s+to\b/gi,
  434. /\bwhat\s+struck\s+me\s+was\b/gi,
  435. /\bi\s+was\s+excited\s+to\s+learn\b/gi,
  436. /\bthe\s+most\s+interesting\s+(?:part|thing|aspect|piece)\b/gi,
  437. // Multiline flag (/m) so `^` matches at every line start, including
  438. // position 0 of a pasted text that has no leading newline. The earlier
  439. // `(?:^|\n)` form silently missed bare openers at the very start of
  440. // input — caught by silent-failure audit 2026-05-16.
  441. /^\s*interesting\s+(?:part|thing|aspect|piece)(?:\s+of\s+(?:the\s+)?\w+)?\s*:/gim,
  442. ];
  443. // ─── Lingering-attention claims ────────────────────────────────────
  444. // The share-post opener that claims duration of attention instead of
  445. // saying anything about the thing ("the line I keep coming back to").
  446. //
  447. // Precision note: the bare verb phrase "I keep coming back to X" is NOT
  448. // matched on its own, because it is legitimate whenever a reason follows
  449. // ("I keep coming back to Hirschman because it predicts who quits"), and
  450. // the reason clause is not reliably detectable by regex. Only the
  451. // noun-anchored frame ("the line/quote/bit ... I keep coming back to")
  452. // fires, which is the shape that introduces a subject rather than
  453. // asserting something about it. The bare form stays a skill-prose
  454. // judgment call. See SKILL.md §Lingering-attention claims carve-out.
  455. const LINGERING_ATTENTION = [
  456. // "the line I keep coming back to", "the one quote that I keep coming back to"
  457. // Noun-anchored frame only. "can't stop thinking about" is deliberately
  458. // left to its own pattern below rather than folded into this alternation,
  459. // so "the line I can't stop thinking about" scores once, not twice.
  460. /\b(?:the|that|this)\s+(?:one\s+)?(?:line|quote|bit|part|idea|point|framing|comment|thing)\s+(?:that\s+)?i\s+keep\s+(?:coming\s+back\s+to|thinking\s+about)\b/gi,
  461. /\bi\s+can'?t\s+stop\s+thinking\s+about\b/gi,
  462. /\bstill\s+thinking\s+about\s+(?:this|that)\s+one\b/gi,
  463. /\b(?:been|be)\s+rattling\s+around\s+(?:in\s+)?my\s+(?:head|brain)\b/gi,
  464. /\bi'?ve\s+been\s+chewing\s+on\s+(?:this|that)\b/gi,
  465. ];
  466. // ─── Novelty inflation ─────────────────────────────────────────────
  467. const NOVELTY_INFLATION = [
  468. /\bthe\s+failure\s+mode\s+nobody'?s?\s+naming\b/gi,
  469. /\ba\s+problem\s+nobody\s+talks\s+about\b/gi,
  470. /\bthe\s+insight\s+everyone'?s?\s+missing\b/gi,
  471. /\bwhat\s+nobody\s+tells\s+you\b/gi,
  472. ];
  473. // ─── Cutoff disclaimers ────────────────────────────────────────────
  474. // Includes the canonical LLM self-identification phrases — these are
  475. // near-dispositive on their own (real humans don't write "as an AI
  476. // language model" in first person). Patterns cover the major model
  477. // families' default disclaimer language.
  478. const CUTOFF_DISCLAIMERS = [
  479. /\bas\s+of\s+my\s+last\s+update\b/gi,
  480. /\bas\s+of\s+my\s+(?:knowledge\s+)?(?:cut-?off|last\s+training)\b/gi,
  481. /\bi\s+don'?t\s+have\s+access\s+to\s+real-?time\s+(?:data|information)\b/gi,
  482. /\bbased\s+on\s+available\s+information\b/gi,
  483. /\bas\s+an?\s+(?:ai|artificial\s+intelligence|large\s+language|ai\s+language)\s+(?:language\s+)?model\b/gi,
  484. /\bi\s+(?:am|'m)\s+an?\s+(?:ai|artificial\s+intelligence|large\s+language)\s+(?:assistant|model)?\b/gi,
  485. /\bi\s+cannot\s+(?:provide|give|offer)\s+(?:legal|medical|financial|professional)\s+advice\b/gi,
  486. /\bmy\s+training\s+data\s+(?:only\s+)?(?:goes\s+up\s+to|extends\s+to|ends\s+(?:in|at))\b/gi,
  487. ];
  488. // ─── AI-tool fingerprints ──────────────────────────────────────────
  489. // Three near-definitive AI-origin signals adapted from
  490. // Aboudjem/humanizer-skill P33-P35 (see docs/competitive/audits/
  491. // 2026-05-17-aboudjem-humanizer-skill.md). Unlike the statistical
  492. // patterns above, single hit on any of these is strong evidence —
  493. // the AI tool literally left its fingerprint in the text.
  494. // Unfilled slot-fill placeholders. Catches the canonical "[Your Name]"
  495. // family plus dated stubs and HTML/MD comments with placeholder verbs.
  496. const AI_PLACEHOLDERS = [
  497. // Directive stubs ("[Your Name]", "[INSERT SOURCE URL]",
  498. // "[Describe the specific section]") — verb-led, the user was
  499. // told to fill in.
  500. /\[(?:Your|Insert|Add|Enter|Describe|Specify|Choose|Pick)[^\]\n]{1,80}\]/gi,
  501. // Noun-only template variables common in AI-generated email or
  502. // letter boilerplate. Match the bare noun OR noun + qualifier.
  503. // Conservative list: only nouns that almost never appear as
  504. // bracketed real content (citation refs, code identifiers, etc.
  505. // are excluded because they typically contain dots, slashes,
  506. // hyphens, or version numbers).
  507. /\[(?:Recipient|Sender|Topic|Subject|Salutation|Closing|Position|Department|Project Name|Company Name|Date)(?:\s+[^\]\n]{0,60})?\]/gi,
  508. // All-caps directive forms ("[INSERT X]", "[FILL IN]") — the
  509. // uppercase tells you it's a slot, not real content.
  510. /\[(?:INSERT|FILL\s+IN|ADD|TODO|TBD|PLACEHOLDER)[^\]\n]{0,80}\]/g,
  511. // Date stubs.
  512. /\b(?:19|20)\d{2}-XX-XX\b/g,
  513. /\bXX\/XX\/(?:19|20)\d{2}\b/g,
  514. // HTML/Markdown comment placeholders with placeholder verbs.
  515. /<!--\s*(?:add|fill\s+in|insert|todo|placeholder)[^>]{0,120}-->/gi,
  516. ];
  517. // Chatbot citation/markup tokens that leak through copy-paste.
  518. // `citeturn0search0` / `citeturn0news5` from ChatGPT, contentReference
  519. // tokens, oai_citation, attached_file references, grok_card markers.
  520. // Each is a near-definitive signature of a specific tool.
  521. const AI_CITATION_MARKUP = [
  522. /\bcite(?:turn|news|search|navigation)\d+(?:search|turn|news|navigation)\d+/gi,
  523. /contentReference\s*\[oaicite:[^\]]+\]\s*\{[^}]*\}/gi,
  524. /\boai_citation\b/gi,
  525. /\[attached_file:\d+\]/gi,
  526. /\bgrok_card\b/gi,
  527. ];
  528. // UTM/tracking parameters auto-appended by AI tools to URLs they
  529. // generate. Survives copy-paste even when nothing else does.
  530. const AI_UTM_SOURCE = [
  531. /[?&]utm_source=(?:chatgpt|openai|copilot|claude|grok|gemini|perplexity)(?:\.com|\.ai)?\b/gi,
  532. /[?&]referrer=(?:chatgpt|copilot|grok|claude|gemini|perplexity)\.(?:com|ai)\b/gi,
  533. ];
  534. // ─── Template phrases ──────────────────────────────────────────────
  535. const TEMPLATE_PHRASES = [
  536. /\ba\s+\w+\s+step\s+(?:towards?|forward\s+for)\b/gi,
  537. /\bwhether\s+you'?re\s+\w+\s+or\s+\w+/gi,
  538. /\bi\s+recently\s+had\s+the\s+pleasure\s+of\b/gi,
  539. ];
  540. // ─── False concession ──────────────────────────────────────────────
  541. const FALSE_CONCESSION = [
  542. /\bwhile\s+\w+\s+is\s+impressive\b/gi,
  543. /\balthough\s+\w+\s+has\s+made\s+strides\b/gi,
  544. /\bdespite\s+\w+\s+challenges?\b/gi,
  545. ];
  546. // ─── Rhetorical question openers ───────────────────────────────────
  547. const RHETORICAL_QUESTIONS = [
  548. /\bbut\s+what\s+does\s+this\s+mean\s+for\b/gi,
  549. /\bso\s+why\s+should\s+you\s+care\b/gi,
  550. /\bwhat'?s\s+next\?\s*/gi,
  551. ];
  552. // ─── Hedge-stacked predictions ─────────────────────────────────────
  553. // Stacks a modal with a hedge adverb: "could potentially create new
  554. // opportunities", "may eventually unlock value." Either word alone is
  555. // fine; the stack is the tell.
  556. const HEDGE_STACK = [
  557. // At most one intervening word, and never a negator. The old {0,2} gap
  558. // matched ordinary English: "could not possibly" (plain emphatic
  559. // negation) and inverted questions like "could a savage possibly" both
  560. // fired. Measured on the human-control corpus, 3 of 4 hedge-stack flags
  561. // were this over-match. See issue #69.
  562. /\b(?:could|may|might)\s+(?:(?!not\b|never\b|hardly\b|scarcely\b|barely\b)\w+\s+)?(?:potentially|eventually|ultimately|possibly|conceivably)\b/gi,
  563. /\b(?:potentially|eventually|ultimately)\s+(?:could|may|might)\b/gi,
  564. ];
  565. // ─── Generic future-narrative closers ──────────────────────────────
  566. // The "may become one of the most important narratives" template — vague
  567. // future significance with no falsifiable claim. Covers narratives /
  568. // stories / trends / themes / chapters / movements.
  569. const FUTURE_NARRATIVE = [
  570. /\b(?:may|could|will|is\s+(?:poised|set)\s+to)\s+become\s+(?:one\s+of\s+)?(?:the\s+)?(?:most\s+)?\w+\s+(?:narratives?|stories|developments?|trends?|movements?|chapters?|themes?|forces?)\b/gi,
  571. /\bone\s+of\s+the\s+most\s+important\s+(?:narratives?|stories|trends?|themes?)\s+of\s+the\s+(?:next|coming)\s+\w+\b/gi,
  572. ];
  573. // ─── "Real/actual" adjective inflation ─────────────────────────────
  574. // "Real on-chain tokenomics", "actual reward sustainability" — using
  575. // real/actual/genuine/true as an empty intensifier on an abstract noun
  576. // to imply the rest of the field is fake/superficial.
  577. const REAL_ACTUAL_INFLATION = [
  578. /\b(?:real|actual|genuine|true)\s+(?:on-?chain\s+)?(?:tokenomics|economics|utility|adoption|sustainability|impact|revenue|fundamentals|demand|value|innovation|traction)\b/gi,
  579. ];
  580. // ─── Formulaic openers ─────────────────────────────────────────────
  581. // The "In the rapidly evolving world of X, Y has emerged as..." family
  582. // — LLM-default essay openers.
  583. const FORMULAIC_OPENERS = [
  584. /\bin\s+the\s+(?:rapidly\s+|ever-?\s*)?(?:evolving|changing|expanding|growing|shifting)\s+(?:world|landscape|realm|space|field|domain|era)\s+of\b/gi,
  585. /\bin\s+(?:an?|the)\s+(?:digital\s+)?age\s+(?:where|of)\b/gi,
  586. /\bas\s+(?:we|the\s+world|society|industries?)\s+(?:continue|move|navigate|enter)\s+(?:to\s+)?(?:evolve|forward|into|through)\b/gi,
  587. // "has emerged as a leader/force/category" — gated to the inflated
  588. // nouns that signal pseudo-significance, since bare "has emerged as
  589. // a" matches normal English ("Rust has emerged as a serious systems
  590. // language"). Same gating for "has become increasingly".
  591. /\bhas\s+emerged\s+as\s+(?:a|the|one\s+of)\s+(?:leading|key|major|critical|essential|fundamental|pivotal|prominent|dominant|important)\s+\w+/gi,
  592. /\bhas\s+become\s+increasingly\s+(?:important|critical|popular|relevant|prominent|essential)\b/gi,
  593. ];
  594. // ─── Speculative scenario openers ──────────────────────────────────
  595. // "Imagine a world where...", "Picture a future in which...", "Envision
  596. // a world where..." — the LLM habit of opening an argument with a
  597. // hypothetical that lists desirable outcomes instead of making a claim.
  598. // Gated to the world/future/reality object plus where/in-which so it
  599. // stays off instructional "imagine you have an array" (a teaching device
  600. // pointing at a concrete example, not a speculative world) and bare
  601. // "imagine that" asides. "consider a scenario where…" is deliberately
  602. // excluded: that is analytical framing common in technical reasoning,
  603. // not the marketing-opener tell. An optional short comma interrupter
  604. // catches the equally common "Imagine, for a moment, a world where…"
  605. // cadence. Known accepted false positive: fiction openings and staged
  606. // thought experiments match too — the engine has no fiction context
  607. // mode, so that call is left to the skill's carve-out (highlight-only;
  608. // a lone hit cannot flip a document's classification).
  609. const SPECULATIVE_OPENERS = [
  610. /\b(?:imagine|picture|envision)(?:\s*,[^,\n]{1,30},)?\s+a\s+(?:world|future|reality)\s+(?:where|in\s+which)\b/gi,
  611. ];
  612. // Function words whose presence MID-title marks the AI section-header shape.
  613. // Word-anchored: without \b the "A" alternative matches inside any word and
  614. // the guard silently degrades to "four tokens".
  615. const FUNCTION_WORD = /\b(?:And|Or|Of|The|In|For|To|A|An)\b/;
  616. // Must accept exactly what TITLE_CASE_HEADER accepts, or the prefix survives
  617. // into the token count and reintroduces the ##-as-token bug.
  618. const MD_HEADING_PREFIX = /^#{1,6}[ \t]+/;
  619. /** Byte ranges covered by fenced code blocks, computed once per scan.
  620. *
  621. * A document that documents Markdown is the normal case for this rule -- a
  622. * fenced `## Heading` example is illustration, not the author's own section
  623. * header, and flagging it makes every docs page flag itself.
  624. *
  625. * This tracks the opening delimiter instead of counting them, because a
  626. * parity count is wrong on the very case the rule exists for. CommonMark
  627. * closes a fence only on the same character at the same length or longer, so
  628. * a four-backtick fence wrapping a three-backtick example -- exactly how you
  629. * document fences -- nests in practice, and counting delimiters inverts on
  630. * it. Up to three spaces of indent are legal. An unclosed fence runs to end
  631. * of document, matching how renderers treat it.
  632. *
  633. * Computed once per scan rather than rescanned per hit: the previous version
  634. * sliced the whole document for every candidate, which is quadratic on a
  635. * heading-dense file. */
  636. function fenceRanges(text) {
  637. const re = /^[ \t]{0,3}(`{3,}|~{3,})[^\n]*$/gm;
  638. const ranges = [];
  639. let open = null;
  640. let m;
  641. while ((m = re.exec(text)) !== null) {
  642. const marker = m[1];
  643. if (!open) {
  644. open = { char: marker[0], len: marker.length, start: m.index };
  645. } else if (marker[0] === open.char && marker.length >= open.len) {
  646. ranges.push([open.start, m.index + m[0].length]);
  647. open = null;
  648. }
  649. }
  650. if (open) ranges.push([open.start, text.length]);
  651. return ranges;
  652. }
  653. function inFenceRange(ranges, index) {
  654. return typeof index === 'number' && ranges.some(([a, b]) => index >= a && index < b);
  655. }
  656. // ─── Title Case Section Headers in non-technical prose ─────────────
  657. // "Strategic Negotiations And Key Partnerships" — every content word
  658. // capitalized. Acceptable in API docs, ML papers, news headlines. Tell
  659. // in marketing/personal/blog prose. Gated to "personal" / "marketing"
  660. // context modes (technical mode skips this check).
  661. //
  662. // The optional `#{1,6}` prefix is load-bearing (#62): without it the `^[A-Z]`
  663. // anchor required the line to START with a capital, so `## Benefits And
  664. // Strategic Considerations` never matched — the first character is `#`. The
  665. // rule missed the single most common way a heading is actually written, while
  666. // catching the bare-line form it is usually converted from. Reported by a
  667. // downstream vendoring the detector.
  668. //
  669. // Setext headings (`Title`/`=====`) need no prefix: their text line is bare
  670. // and already matched by this same pattern.
  671. const TITLE_CASE_HEADER = /^(?:#{1,6}[ \t]+)?([A-Z][a-z]+(?:\s+(?:[A-Z][a-z]+|and|or|of|the|in|for|to|a|an))+\s+[A-Z][a-z]+)\s*$/gm;
  672. // ─── Parenthetical hedging asides ──────────────────────────────────
  673. // "(and increasingly, X)", "(or more precisely, Y)", "(though to be
  674. // fair, Z)" — pseudo-aside that adds no information but performs
  675. // thoughtfulness. Different from genuine human parentheticals which
  676. // tend to be tangents or clarifications, not hedges.
  677. const PARENTHETICAL_HEDGE = [
  678. /\(\s*(?:and\s+)?(?:increasingly|notably|importantly|crucially|interestingly|perhaps)[,]?\s+[^)]{3,60}\)/gi,
  679. /\(\s*or\s+more\s+(?:precisely|accurately|specifically)[,]?\s+[^)]{3,60}\)/gi,
  680. /\(\s*though\s+to\s+be\s+fair[,]?\s+[^)]{3,60}\)/gi,
  681. /\(\s*at\s+least\s+(?:in\s+)?(?:theory|principle|part)[,]?\s+[^)]{0,60}\)/gi,
  682. ];
  683. // ─── Confidence calibration ────────────────────────────────────────
  684. const CONFIDENCE_CALIBRATION = [
  685. /\binterestingly\b/gi,
  686. /\bsurprisingly\b/gi,
  687. /\bimportantly\b/gi,
  688. /\bsignificantly\b/gi,
  689. /\bcertainly\b/gi,
  690. /\bundoubtedly\b/gi,
  691. /\bwithout\s+a\s+doubt\b/gi,
  692. ];
  693. // ─── Social endorsement / CTA closers ──────────────────────────────
  694. // The curatorial sign-off LLMs append to LinkedIn / X posts that share
  695. // or recommend something — usually a colon teeing up a link. Distinct
  696. // from the bare "worth reading" word-table entry (a single weak word)
  697. // and from infomercial hooks (mid-flow teasers): this is the
  698. // demonstrative-anchored endorsement — "THIS one is worth your time:",
  699. // "do yourself a favor and read this", "thank me later" — that performs
  700. // a recommendation without giving the reader a reason to click.
  701. //
  702. // Precision-first: each pattern carries an anchor so it stays off the
  703. // literal-verb prose a human writes. The demonstrative object ("read
  704. // THIS", not "read the runbook"), the trailing-terminal lookahead on
  705. // "miss this" / "bookmark this" (the closing-line shape, not "miss this
  706. // meeting" / "bookmark this page"), and the sentence-initial lookbehind
  707. // on "thank me later" / "save this for later" (the imperative CTA, not
  708. // "she will thank me later") all exist to suppress false positives on
  709. // ordinary instructional/conversational text. Apostrophe classes admit
  710. // the curly ' (U+2019) because LinkedIn / Word / macOS auto-curl it —
  711. // the straight-only form would miss the canonical "you won't" closer.
  712. const SOCIAL_CTA_CLOSER = [
  713. /\bthis\s+one['’]?s?\s+(?:is\s+)?(?:well\s+|totally\s+|absolutely\s+|definitely\s+|really\s+|truly\s+|easily\s+|more\s+than\s+)?worth\s+(?:your\s+time|the\s+read|a\s+read|every\s+(?:minute|second)|reading|watching|a\s+listen|a\s+watch|a\s+look|it)\b/gi,
  714. /\bthis\s+one['’]?s?\s+(?:is\s+)?a\s+must[-\s]?(?:read|watch|listen|see)\b/gi,
  715. /\b(?:highly|strongly|can['’]?t|cannot)\s+recommend\w*\s+(?:giving\s+)?(?:this|it)\s+(?:one\s+)?a\s+(?:read|listen|watch|look|go)\b/gi,
  716. /\bdo\s+yourself\s+a\s+favou?r\s+and\s+(?:read|watch|check\s+out)\s+(?:this|it)\b/gi,
  717. /\byou\s+(?:really\s+)?(?:won['’]?t|do\s*n['’]?t|will\s+not|do\s+not)\s+want\s+to\s+miss\s+this(?:\s+one)?(?=\s*(?:[:.!\n]|$))/gi,
  718. /(?<=^|[,.!?:\n]\s{0,4})(?:you\s+can\s+)?thank\s+me\s+later\b/gim,
  719. /(?<=^|[.!?:\n]\s{0,4})save\s+this\s+(?:one\s+)?for\s+later\b/gim,
  720. /\bbookmark\s+this(?:\s+(?:one|post|thread))?(?=\s*(?:[:.!\n]|$))/gi,
  721. /\bdo\s*n['’]?t\s+sleep\s+on\s+this\b/gi,
  722. /\btrust\s+me,?\s+(?:on\s+this|you['’]?ll)\b/gi,
  723. ];
  724. // ═══ Helpers ═══════════════════════════════════════════════════════
  725. function tokenize(text) {
  726. return text.toLowerCase().match(/[\w'-]+/g) || [];
  727. }
  728. function countWords(text) {
  729. return (text.match(/\S+/g) || []).length;
  730. }
  731. function getParagraphs(text) {
  732. return text.split(/\n\s*\n/).filter(p => p.trim().length > 0);
  733. }
  734. function getSentences(text) {
  735. return text.split(/[.!?]+/).filter(s => s.trim().length > 5);
  736. }
  737. function matchPatterns(text, patterns, category, severity) {
  738. const issues = [];
  739. for (const pat of patterns) {
  740. const regex = new RegExp(pat.source, pat.flags);
  741. let match;
  742. while ((match = regex.exec(text)) !== null) {
  743. issues.push({
  744. type: category,
  745. text: match[0],
  746. index: match.index,
  747. severity,
  748. suggestion: null,
  749. });
  750. }
  751. }
  752. return issues;
  753. }
  754. // ═══ Main analysis ═════════════════════════════════════════════════
  755. // Upper bound for one scan. Above this we bail rather than running all
  756. // regex passes over a huge buffer — protects page perf on pasted novels.
  757. const MAX_WORDS = 10000;
  758. // V2 contract defaults so early-exit paths (Empty/tooShort/tooLong)
  759. // still return the same field shape a v2 consumer expects. Without
  760. // this, `result.document_classification === 'AI_ONLY'` is `undefined`
  761. // on edge inputs and fails open.
  762. // UNSCORED is returned on empty / too-short / too-long inputs where
  763. // we declined to score. Distinct from HUMAN_ONLY (which is a positive
  764. // classification) so a caller can't mistake a refused scan for a
  765. // confident human verdict — a 50k-word LLM-generated document is
  766. // not "human", it's just outside our scoring window.
  767. function buildV2Defaults(classification, confidence) {
  768. const probs = classification === 'HUMAN_ONLY'
  769. ? { human: 1, mixed: 0, ai: 0 }
  770. : classification === 'AI_ONLY'
  771. ? { human: 0, mixed: 0, ai: 1 }
  772. : { human: 0.333, mixed: 0.334, ai: 0.333 };
  773. return {
  774. document_classification: classification,
  775. class_probabilities: probs,
  776. confidence_category: confidence,
  777. highlight_sentence_for_ai: [],
  778. };
  779. }
  780. function analyzeText(text, options = {}) {
  781. if (!text || text.trim().length === 0) {
  782. return { ...buildV2Defaults('UNSCORED', 'low'), score: 0, label: 'Empty', issues: [], stats: {}, tooShort: true };
  783. }
  784. // Context mode gates rules that are noisy in technical writing. Modes:
  785. // 'general' (default) — full ruleset
  786. // 'technical' — skip title-case headers, formulaic openers gated to
  787. // prose-only structures; lower em-dash + formatting weights
  788. // 'marketing' — full ruleset + boost on formulaic-opener / future-narrative
  789. // 'personal' — full ruleset, normal weights
  790. // Mode is purely a soft gate; nothing is silently suppressed without
  791. // being reflected in stats.contextMode for transparency.
  792. // Mode validation: an unknown string (e.g. typo "tecnical") would
  793. // otherwise silently downgrade to general-mode behavior. Coerce to
  794. // 'general' and surface the original value in stats for traceability.
  795. const VALID_CONTEXT_MODES = new Set(['general', 'technical', 'marketing', 'personal']);
  796. const requestedMode = options.contextMode || 'general';
  797. const contextMode = VALID_CONTEXT_MODES.has(requestedMode) ? requestedMode : 'general';
  798. const contextModeFallback = requestedMode !== contextMode ? requestedMode : null;
  799. // Pre-pass: strip Markdown blockquotes before scoring. A human
  800. // reacting to AI text by quoting it shouldn't have the quoted block
  801. // counted against their own writing. Requires ≥2 consecutive `> `
  802. // lines to count as a blockquote — single-line `> ls -la` shell
  803. // prompts in technical docs stay in the text.
  804. let quotedLines = 0;
  805. const rawLines = text.split(/\r?\n/);
  806. const isQuote = rawLines.map((l) => /^\s*>\s/.test(l));
  807. const stripIdx = new Set();
  808. for (let i = 0; i < rawLines.length; i++) {
  809. if (isQuote[i] && ((isQuote[i - 1] && i > 0) || isQuote[i + 1])) {
  810. stripIdx.add(i);
  811. quotedLines++;
  812. }
  813. }
  814. text = rawLines.filter((_, i) => !stripIdx.has(i)).join('\n');
  815. // Pre-pass: strip bypass-trick chars before pattern matching so
  816. // "delve" with a Cyrillic 'е' still hits Tier 1. Original text is
  817. // preserved so reported `match.index` values remain visually accurate.
  818. const norm = normalizeText(text);
  819. text = norm.text;
  820. const wordCount = countWords(text);
  821. if (wordCount < 10) {
  822. return { ...buildV2Defaults('UNSCORED', 'low'), score: 0, label: 'Too short', issues: [], stats: { wordCount, contextMode, contextModeFallback }, tooShort: true };
  823. }
  824. if (wordCount > MAX_WORDS) {
  825. return {
  826. ...buildV2Defaults('UNSCORED', 'low'),
  827. score: 0,
  828. label: 'Text too long',
  829. issues: [],
  830. stats: { wordCount, contextMode, contextModeFallback },
  831. tooLong: true,
  832. };
  833. }
  834. const tokens = tokenize(text);
  835. const paragraphs = getParagraphs(text);
  836. const sentences = getSentences(text);
  837. const issues = [];
  838. let rawScore = 0;
  839. // ── 1. Tier 1 words ──────────────────────────────────────────
  840. const tier1Found = new Set();
  841. for (const token of tokens) {
  842. if (TIER1[token] && !tier1Found.has(token)) {
  843. tier1Found.add(token);
  844. issues.push({
  845. type: 'tier1',
  846. text: token,
  847. severity: 'high',
  848. suggestion: TIER1[token],
  849. });
  850. }
  851. }
  852. // Tier 1 multi-word phrases. Adds each distinct phrase (lowercased) to
  853. // `tier1Found` so the same phrase hit multiple times only produces one
  854. // issue — matches the downstream dedup behavior.
  855. for (const phrase of TIER1_PHRASES) {
  856. const regex = new RegExp(phrase.pattern.source, phrase.pattern.flags);
  857. let match;
  858. while ((match = regex.exec(text)) !== null) {
  859. const lower = match[0].toLowerCase();
  860. if (tier1Found.has(lower)) continue;
  861. tier1Found.add(lower);
  862. issues.push({
  863. // Clarity-band entries are wordiness edits, not frequency evidence.
  864. // Same fix, weaker claim — see the Tier 1A/1B split in SKILL.md.
  865. type: phrase.clarity ? 'tier1-clarity' : 'tier1',
  866. text: match[0],
  867. severity: phrase.clarity ? 'medium' : 'high',
  868. suggestion: phrase.replace,
  869. });
  870. }
  871. }
  872. // ── 2. Tier 2 clusters ───────────────────────────────────────
  873. let tier2Clusters = 0;
  874. for (const para of paragraphs) {
  875. const paraTokens = tokenize(para);
  876. const found = [];
  877. const suggestions = {};
  878. for (const token of paraTokens) {
  879. if (TIER2[token] && !found.includes(token)) {
  880. found.push(token);
  881. suggestions[token] = TIER2[token];
  882. }
  883. }
  884. for (const cond of TIER2_CONDITIONAL) {
  885. if (!found.includes(cond.word) && cond.pattern.test(para)) {
  886. found.push(cond.word);
  887. suggestions[cond.word] = cond.suggestion;
  888. }
  889. }
  890. if (found.length >= 2) {
  891. tier2Clusters++;
  892. for (const word of found) {
  893. issues.push({
  894. type: 'tier2',
  895. text: word,
  896. severity: 'medium',
  897. suggestion: suggestions[word],
  898. });
  899. }
  900. }
  901. }
  902. // ── 3. Tier 3 density ────────────────────────────────────────
  903. const tier3Counts = {};
  904. for (const token of tokens) {
  905. const canonical = TIER3_LOOKUP.get(token);
  906. if (canonical) tier3Counts[canonical] = (tier3Counts[canonical] || 0) + 1;
  907. }
  908. // Flag at 3% of word count, but never below 3 occurrences. Previous
  909. // floor of 1 meant a 50-word text with one "significant" got flagged
  910. // as Tier 3 overuse, which was noise.
  911. const densityThreshold = Math.max(3, Math.floor(wordCount * 0.03));
  912. let tier3Flags = 0;
  913. for (const [word, count] of Object.entries(tier3Counts)) {
  914. if (count >= densityThreshold) {
  915. tier3Flags++;
  916. issues.push({
  917. type: 'tier3',
  918. text: `"${word}" x${count}`,
  919. severity: 'low',
  920. suggestion: `Overused (${count} times in ${wordCount} words)`,
  921. });
  922. }
  923. }
  924. // ── 4–21. Pattern categories ─────────────────────────────────
  925. issues.push(...matchPatterns(text, TRANSITIONS, 'transition', 'medium'));
  926. issues.push(...matchPatterns(text, CHATBOT_ARTIFACTS, 'chatbot', 'critical'));
  927. issues.push(...matchPatterns(text, SYCOPHANTIC, 'sycophantic', 'critical'));
  928. issues.push(...matchPatterns(text, FILLERS, 'filler', 'medium'));
  929. issues.push(...matchPatterns(text, GENERIC_CONCLUSIONS, 'generic-conclusion', 'medium'));
  930. issues.push(...matchPatterns(text, LETS_PATTERNS, 'lets-construction', 'medium'));
  931. issues.push(...matchPatterns(text, REASONING_ARTIFACTS, 'reasoning-artifact', 'critical'));
  932. issues.push(...matchPatterns(text, ACKNOWLEDGMENT_LOOPS, 'acknowledgment-loop', 'medium'));
  933. issues.push(...matchPatterns(text, SIGNIFICANCE_INFLATION, 'significance-inflation', 'high'));
  934. issues.push(...matchPatterns(text, VAGUE_ATTRIBUTIONS, 'vague-attribution', 'critical'));
  935. issues.push(...matchPatterns(text, HOLLOW_INTENSIFIERS, 'hollow-intensifier', 'medium'));
  936. issues.push(...matchPatterns(text, EMOTIONAL_FLATLINE, 'emotional-flatline', 'low'));
  937. issues.push(...matchPatterns(text, LINGERING_ATTENTION, 'lingering-attention', 'medium'));
  938. issues.push(...matchPatterns(text, NOVELTY_INFLATION, 'novelty-inflation', 'medium'));
  939. issues.push(...matchPatterns(text, CUTOFF_DISCLAIMERS, 'cutoff-disclaimer', 'critical'));
  940. issues.push(...matchPatterns(text, AI_PLACEHOLDERS, 'ai-placeholder', 'critical'));
  941. issues.push(...matchPatterns(text, AI_CITATION_MARKUP, 'ai-citation-markup', 'critical'));
  942. issues.push(...matchPatterns(text, AI_UTM_SOURCE, 'ai-utm-source', 'critical'));
  943. issues.push(...matchPatterns(text, TEMPLATE_PHRASES, 'template-phrase', 'high'));
  944. issues.push(...matchPatterns(text, FALSE_CONCESSION, 'false-concession', 'medium'));
  945. issues.push(...matchPatterns(text, RHETORICAL_QUESTIONS, 'rhetorical-question', 'medium'));
  946. issues.push(...matchPatterns(text, HEDGE_STACK, 'hedge-stack', 'high'));
  947. issues.push(...matchPatterns(text, FUTURE_NARRATIVE, 'future-narrative', 'high'));
  948. issues.push(...matchPatterns(text, REAL_ACTUAL_INFLATION, 'real-actual-inflation', 'medium'));
  949. issues.push(...matchPatterns(text, SOCIAL_CTA_CLOSER, 'social-cta-closer', 'high'));
  950. // ── Tier 1 v2: formulaic openers + parenthetical hedges ──────────
  951. issues.push(...matchPatterns(text, FORMULAIC_OPENERS, 'formulaic-opener', 'high'));
  952. issues.push(...matchPatterns(text, SPECULATIVE_OPENERS, 'speculative-opener', 'high'));
  953. issues.push(...matchPatterns(text, PARENTHETICAL_HEDGE, 'parenthetical-hedge', 'medium'));
  954. // Title-case headers — gated to marketing/personal/general modes
  955. // (technical mode legitimately uses Title Case section headers).
  956. if (contextMode !== 'technical') {
  957. const titleHits = matchPatterns(text, [TITLE_CASE_HEADER], 'title-case-header', 'medium');
  958. // Drop matches that look like proper-noun titles (single line, all
  959. // tokens capitalized incl. function words) — that's headline style,
  960. // not the AI-section-header tell which has mid-sentence "And".
  961. //
  962. // The prefix strip is load-bearing. matchPatterns reports match[0], so a
  963. // Markdown hit arrives as "## Terms Of Service" and `##` counts as a
  964. // token — silently lowering this guard from four content words to three
  965. // for headings only, which is exactly the class it exists to protect.
  966. // "## Terms Of Service", "## Bank Of America" and "## Table Of Contents"
  967. // all flagged as a result: ordinary human headings, on a detector whose
  968. // stated first priority is not firing on human writing.
  969. const filtered = titleHits.filter((h) => {
  970. const title = h.text.replace(MD_HEADING_PREFIX, '');
  971. const tokens = title.trim().split(/\s+/);
  972. if (tokens.length < 4) return false;
  973. // The function word must be MID-title, which is what the comment above
  974. // has always said and what the test never enforced. A leading "The"
  975. // satisfied a bare /\bThe\b/, so ordinary human headings flagged:
  976. // "## The New Security Landscape", "## The Microsoft Approach to
  977. // Identity", "### The Four Keys to a Successful and Secure Modern
  978. // Workplace". Measured across 81 files that provably predate LLMs
  979. // (2018-19 eBooks, 2020 posts): 13 false positives, every one opening
  980. // with "The", against zero on main.
  981. //
  982. // "## Benefits And Strategic Considerations" -- the actual tell, and
  983. // this rule's own fixture -- is untouched: its "And" is interior.
  984. return FUNCTION_WORD.test(tokens.slice(1).join(' '));
  985. });
  986. const fences = filtered.length ? fenceRanges(text) : [];
  987. issues.push(...filtered.filter((h) => !inFenceRange(fences, h.index)));
  988. }
  989. // ── Normalization-trigger flag ───────────────────────────────────
  990. // ZWSPs or homoglyphs in pasted prose are near-dispositive: humans
  991. // don't insert these into their own writing. Single roleplay marker
  992. // can be a false positive on Markdown emphasis (filtered to multi-
  993. // word inner already), so requires ≥2.
  994. if (norm.flags.zeroWidth > 0 || norm.flags.homoglyph >= 2) {
  995. issues.push({
  996. type: 'normalization-flag',
  997. text: `${norm.flags.zeroWidth} zero-width + ${norm.flags.homoglyph} homoglyph swap${norm.flags.homoglyph === 1 ? '' : 's'}`,
  998. severity: 'critical',
  999. suggestion: 'Text contains invisible/lookalike chars typical of AI-humanizer bypass tools. Re-type from your own keyboard.',
  1000. });
  1001. }
  1002. if (norm.flags.roleplay >= 2) {
  1003. issues.push({
  1004. type: 'normalization-flag',
  1005. text: `${norm.flags.roleplay} *roleplay-action* markers stripped`,
  1006. severity: 'high',
  1007. suggestion: 'Paired *action* markers are a chat-model artifact.',
  1008. });
  1009. }
  1010. // Em dashes in list-item separator position — a bulleted or numbered
  1011. // list item opening with a bolded lead term or markdown link, then the
  1012. // dash ("- **Term** — desc", "- [label](url) — desc") — are
  1013. // definition-list typography, not prose punctuation. Shared by the
  1014. // smart-punct signature below and the em-dash frequency check (§22).
  1015. // An optional parenthetical or inline-code span may sit between the bold
  1016. // lead term and the dash — "- **Lingering-attention claims**
  1017. // (`lingering-attention`) — the share-post frame…" is the same definition
  1018. // typography as the bare form. Found by the self-scan (see PROOF.md, #67).
  1019. const SEPARATOR_DASH_RE = /^\s*(?:[-*+]|\d+[.)])\s+(?:\*\*[^*\n]+\*\*|\[[^\]\n]+\]\([^)\n]*\))(?:[ \t]*(?:\([^)\n]*\)|`[^`\n]+`))?[ \t]*—/gm;
  1020. // Keep-a-Changelog version headings (`## [3.21.0] — 2026-07-30`) join a
  1021. // label to a value exactly as a list separator does. Deliberately narrow:
  1022. // a bracketed or bare semver token, then a dash, then an ISO date, and
  1023. // nothing else on the line. Ordinary prose dashes in headings still count,
  1024. // because SKILL.md applies the em-dash rule to headings too.
  1025. const VERSION_HEADING_DASH_RE = /^#{1,6}[ \t]+\[?v?\d+\.\d+\.\d+[^\]\n]*\]?[ \t]*—[ \t]*\d{4}-\d{2}-\d{2}[ \t]*$/gm;
  1026. // ── Smart-punctuation co-occurrence signature ────────────────────
  1027. // Curly quotes + em-dash + Oxford comma all present + zero typos
  1028. // (no double-spaces, no missing apostrophes in common contractions)
  1029. // is a near-dispositive paste-from-LLM signature: humans typing
  1030. // directly into a textarea don't produce all four. Standalone any of
  1031. // these is meaningless — co-occurrence is the signal. Separator-position
  1032. // dashes are typography and don't corroborate it.
  1033. {
  1034. const hasCurly = /[“”‘’]/.test(text);
  1035. const totalEmDashes = (text.match(/—/g) || []).length;
  1036. const separatorEmDashes = (text.match(SEPARATOR_DASH_RE) || []).length
  1037. + (text.match(VERSION_HEADING_DASH_RE) || []).length;
  1038. const hasEmDash = totalEmDashes > separatorEmDashes;
  1039. const oxfordHit = text.match(/\b\w+,\s+\w+,\s+and\s+\w+/g);
  1040. const hasOxford = (oxfordHit?.length || 0) >= 1;
  1041. const doubleSpaces = (text.match(/[^.!?] +/g) || []).length;
  1042. const missingApos = /\b(?:dont|wont|cant|isnt|wasnt|shouldnt|wouldnt|couldnt|youre|theyre|its\s+a\s+\w+ing)\b/i.test(text);
  1043. const clean = doubleSpaces === 0 && !missingApos;
  1044. const signals = [hasCurly, hasEmDash, hasOxford, clean].filter(Boolean).length;
  1045. if (signals >= 4 && wordCount >= 80) {
  1046. issues.push({
  1047. type: 'smart-punct-signature',
  1048. text: 'curly-quotes + em-dash + Oxford comma + zero typos',
  1049. severity: 'high',
  1050. suggestion: 'Smart-punctuation signature consistent with LLM output. Humans typing into textareas rarely produce all four.',
  1051. });
  1052. }
  1053. }
  1054. // ── Punctuation distribution mode ────────────────────────────────
  1055. // Humans cluster trimodal across paragraphs (some paras heavy, some
  1056. // light, some none). AI converges on a normal distribution. We can't
  1057. // run a real modality test client-side, but we can flag the AI
  1058. // signature: low variance of per-paragraph punctuation density.
  1059. // Requires ≥4 paragraphs to be meaningful.
  1060. if (paragraphs.length >= 4) {
  1061. const densities = paragraphs.map((p) => {
  1062. const words = (p.match(/\S+/g) || []).length;
  1063. if (words < 5) return null;
  1064. const puncts = (p.match(/[,;:—()]/g) || []).length;
  1065. return puncts / words;
  1066. }).filter((d) => d !== null);
  1067. if (densities.length >= 4) {
  1068. const mean = densities.reduce((a, b) => a + b, 0) / densities.length;
  1069. const variance = densities.reduce((s, d) => s + (d - mean) ** 2, 0) / densities.length;
  1070. const cv = mean > 0 ? Math.sqrt(variance) / mean : 0;
  1071. // CV < 0.25 across paragraphs means each paragraph has the same
  1072. // punctuation density — the AI signature. Humans usually swing
  1073. // wider. Threshold derived from stylometry papers (arxiv 2507.00838).
  1074. if (cv < 0.25 && mean >= 0.04) {
  1075. issues.push({
  1076. type: 'punct-distribution',
  1077. text: `Punctuation density uniform across paragraphs (CV=${cv.toFixed(2)})`,
  1078. severity: 'medium',
  1079. suggestion: 'AI text holds punctuation density steady; human writers swing between dense and sparse paragraphs.',
  1080. });
  1081. }
  1082. }
  1083. }
  1084. // ── Function-word trigram entropy ────────────────────────────────
  1085. // POS-trigram entropy is the academic signal; function-word trigram
  1086. // entropy approximates it without a tagger (function words ARE the
  1087. // closed-class POS classes). AI text has lower entropy because LLM
  1088. // sampling collapses onto a narrower set of grammatical templates.
  1089. //
  1090. // Method: extract function-word indicators per sentence, build
  1091. // trigrams over the sequence, compute Shannon entropy. Bins below
  1092. // threshold flag.
  1093. if (wordCount >= 150) {
  1094. const FUNC_WORDS = new Set([
  1095. 'the','a','an','and','or','but','of','to','in','on','at','by','for','with',
  1096. 'from','as','is','was','are','were','be','been','being','have','has','had',
  1097. 'do','does','did','will','would','should','could','may','might','must','can',
  1098. 'this','that','these','those','it','its','they','them','their','there','here',
  1099. 'we','our','us','i','you','your','he','she','his','her','him','not','no','so',
  1100. 'if','then','than','when','where','which','who','what','how','why','because',
  1101. ]);
  1102. const seq = tokens.map((t) => FUNC_WORDS.has(t) ? t : '_').filter((_, i, arr) => arr[i] !== '_' || (i > 0 && arr[i - 1] !== '_'));
  1103. if (seq.length >= 50) {
  1104. const trigrams = {};
  1105. for (let i = 0; i < seq.length - 2; i++) {
  1106. const tg = `${seq[i]}|${seq[i + 1]}|${seq[i + 2]}`;
  1107. trigrams[tg] = (trigrams[tg] || 0) + 1;
  1108. }
  1109. const total = seq.length - 2;
  1110. let entropy = 0;
  1111. for (const c of Object.values(trigrams)) {
  1112. const p = c / total;
  1113. entropy -= p * Math.log2(p);
  1114. }
  1115. // Normalize by log2(distinct trigrams) so entropy ranges roughly
  1116. // 0..1 and threshold is interpretable. Empirical threshold: human
  1117. // prose ~0.85-0.95 normalized, AI prose ~0.70-0.82.
  1118. const distinctCount = Object.keys(trigrams).length;
  1119. const normalized = distinctCount > 1 ? entropy / Math.log2(distinctCount) : 1;
  1120. if (normalized < 0.82 && total >= 50) {
  1121. issues.push({
  1122. type: 'fnword-trigram-entropy',
  1123. text: `Function-word trigram entropy ${normalized.toFixed(2)} (low)`,
  1124. severity: 'medium',
  1125. suggestion: 'Grammatical structure is unusually repetitive. AI sampling collapses onto narrower templates than human writing.',
  1126. });
  1127. }
  1128. // Degenerate case: single distinct trigram repeated across the
  1129. // whole document is the strongest possible AI signal but the
  1130. // normalized fallback returns 1.0 (= "fully human"), inverting
  1131. // the signal. Catch it explicitly.
  1132. if (distinctCount === 1 && total >= 50) {
  1133. issues.push({
  1134. type: 'fnword-trigram-entropy',
  1135. text: 'Single function-word trigram repeated across document',
  1136. severity: 'high',
  1137. suggestion: 'Grammatical structure is fully degenerate — every clause uses the same function-word skeleton.',
  1138. });
  1139. }
  1140. }
  1141. }
  1142. // ── Cross-paragraph burstiness ───────────────────────────────────
  1143. // We already check within-paragraph sentence-length uniformity. AI
  1144. // is also flat ACROSS paragraphs — every paragraph has roughly the
  1145. // same sentence-length variance. Humans vary: terse paras next to
  1146. // discursive paras. Measure variance of CV across paragraphs.
  1147. if (paragraphs.length >= 4) {
  1148. const cvs = paragraphs.map((p) => {
  1149. const sents = getSentences(p);
  1150. if (sents.length < 3) return null;
  1151. const lens = sents.map(countWords);
  1152. const m = lens.reduce((a, b) => a + b, 0) / lens.length;
  1153. if (m === 0) return null;
  1154. const v = lens.reduce((s, l) => s + (l - m) ** 2, 0) / lens.length;
  1155. return Math.sqrt(v) / m;
  1156. }).filter((c) => c !== null);
  1157. if (cvs.length >= 4) {
  1158. const cvMean = cvs.reduce((a, b) => a + b, 0) / cvs.length;
  1159. const cvVar = cvs.reduce((s, c) => s + (c - cvMean) ** 2, 0) / cvs.length;
  1160. const cvStd = Math.sqrt(cvVar);
  1161. // Std-of-CV below 0.08 means every paragraph has roughly the same
  1162. // internal rhythm — AI signature. Human prose typically swings
  1163. // 0.15-0.40 across paragraphs of mixed purpose.
  1164. if (cvStd < 0.08 && cvMean < 0.45) {
  1165. issues.push({
  1166. type: 'cross-para-burstiness',
  1167. text: `Sentence-rhythm uniform across paragraphs (σCV=${cvStd.toFixed(2)})`,
  1168. severity: 'medium',
  1169. suggestion: 'Every paragraph has the same internal rhythm. Humans vary cadence between terse and discursive paragraphs.',
  1170. });
  1171. }
  1172. }
  1173. }
  1174. // ── Tier 3 multi-word phrase density ─────────────────────────
  1175. // Two complementary rules:
  1176. // (a) Per-phrase density — same gating as single-word Tier 3: each
  1177. // phrase fine alone, repetition is the tell. Threshold = 2.
  1178. // (b) Cross-phrase clustering — ≥3 *distinct* boilerplate phrases
  1179. // in one piece. LLMs varying their own boilerplate often use
  1180. // each phrase only once but stack 5-10 across the text. The
  1181. // per-phrase rule misses this; the cluster rule catches it.
  1182. // Track non-overlapping match spans so a longer phrase swallowing a
  1183. // shorter one (e.g., "designed for long-term sustainability" matches
  1184. // both "designed for long-term" AND "long-term sustainability") only
  1185. // contributes one distinct hit. Without dedup the cluster threshold
  1186. // can be reached by a single sentence stacking overlapping regexes.
  1187. const claimedSpans = [];
  1188. function spanOverlaps(start, end) {
  1189. for (const [s, e] of claimedSpans) {
  1190. if (start < e && end > s) return true;
  1191. }
  1192. return false;
  1193. }
  1194. let distinctPhrasesHit = 0;
  1195. for (const phrase of TIER3_PHRASES) {
  1196. const regex = new RegExp(phrase.source, phrase.flags);
  1197. const phraseSpans = [];
  1198. let phraseMatch;
  1199. while ((phraseMatch = regex.exec(text)) !== null) {
  1200. const start = phraseMatch.index;
  1201. const end = start + phraseMatch[0].length;
  1202. if (!spanOverlaps(start, end)) {
  1203. phraseSpans.push([start, end, phraseMatch[0]]);
  1204. }
  1205. }
  1206. if (phraseSpans.length === 0) continue;
  1207. for (const [s, e] of phraseSpans) claimedSpans.push([s, e]);
  1208. distinctPhrasesHit++;
  1209. if (phraseSpans.length >= 2) {
  1210. issues.push({
  1211. type: 'tier3-phrase',
  1212. text: `"${phraseSpans[0][2].toLowerCase()}" x${phraseSpans.length}`,
  1213. severity: 'medium',
  1214. suggestion: `Boilerplate phrase repeated ${phraseSpans.length}× — replace at least one with specifics`,
  1215. });
  1216. }
  1217. }
  1218. if (distinctPhrasesHit >= 3) {
  1219. issues.push({
  1220. type: 'tier3-phrase-cluster',
  1221. text: `${distinctPhrasesHit} distinct boilerplate phrases`,
  1222. severity: 'high',
  1223. suggestion: 'Several stock crypto/web3 phrases stacked in one piece. Rewrite around one specific claim or observation.',
  1224. });
  1225. }
  1226. // ── Hashtag stuffing ─────────────────────────────────────────
  1227. // 6+ hashtags in a single post is rare for thoughtful humans and
  1228. // near-universal for LLM-generated social posts. Counted globally,
  1229. // not per-paragraph, since the trailing hashtag block is the shape
  1230. // we care about.
  1231. // Match #tag at start of text or after any non-word char (whitespace,
  1232. // punctuation, line breaks). URL fragments are already excluded
  1233. // because the char immediately before `#` in a URL path is always
  1234. // a word char (e.g. `example.com/page#section` — `e` before `#`).
  1235. // Earlier char class `[\s\\]` had a literal backslash and silently
  1236. // missed hashtags after sentence punctuation; an interim `[\s]` fix
  1237. // on origin only caught whitespace-preceded tags.
  1238. const hashtagMatches = text.match(/(?:^|\W)#\w[\w-]*/g) || [];
  1239. if (hashtagMatches.length >= 6) {
  1240. issues.push({
  1241. type: 'hashtag-stuff',
  1242. text: `${hashtagMatches.length} hashtags`,
  1243. severity: 'medium',
  1244. suggestion: 'Cut to 2-3 specific tags or none. Long hashtag blocks read as bot output.',
  1245. });
  1246. }
  1247. // ── Bullet list of bare noun phrases ─────────────────────────
  1248. // ≥5 consecutive bullet items that are short (≤6 words) and contain
  1249. // no finite-verb / modal token. Catches the "Stable mining efficiency
  1250. // / Reliable pool connectivity / Optimized RandomX performance ..."
  1251. // shape LLMs default to. Markdown bullets, escaped Markdown bullets,
  1252. // unicode bullets, and dashes are all matched. Numbered lists are
  1253. // excluded — those have a separate "numbered list inflation" rule.
  1254. //
  1255. // Note: verbRe covers auxiliaries and modals ("was", "will", "can",
  1256. // etc.). Regular past-tense verbs ("fixed", "removed") are not
  1257. // matched here; instead, the ≤6-word length gate excludes most
  1258. // real-world changelog lines, which tend to read "fixed the X that
  1259. // was doing Y" (>6 words). Short two-word action items ("* fixed
  1260. // bug") would pass both gates — an acceptable trade-off to avoid
  1261. // false-negative risk from adjectives ending in -ed ("skilled",
  1262. // "advanced") that share the same surface form.
  1263. const lines = text.split(/\r?\n/);
  1264. const bulletRe = /^\s*(?:\*|-|•|\+)\s+(.+)$/;
  1265. const verbRe = /\b(?:is|are|was|were|has|have|had|will|would|should|must|do|does|did|can|could|may|might|am|been|being)\b/i;
  1266. const fenceRe = /^\s*(?:```|~~~)/;
  1267. let run = [];
  1268. let blankStreak = 0;
  1269. let inFence = false;
  1270. function flushRun() {
  1271. if (run.length >= 5) {
  1272. const bareNP = run.filter((it) => {
  1273. const wc = (it.match(/\S+/g) || []).length;
  1274. return wc > 0 && wc <= 6 && !verbRe.test(it);
  1275. });
  1276. if (bareNP.length >= 5 && bareNP.length / run.length >= 0.75) {
  1277. issues.push({
  1278. type: 'bullet-np-list',
  1279. text: `${run.length}-item bullet list of bare noun phrases`,
  1280. severity: 'high',
  1281. suggestion: 'Convert to a prose paragraph or merge items. Long lists of bare adj+noun pairs read as AI scaffolding.',
  1282. });
  1283. }
  1284. }
  1285. run = [];
  1286. blankStreak = 0;
  1287. }
  1288. for (const line of lines) {
  1289. if (fenceRe.test(line)) {
  1290. // Code-fence toggle. Bullets inside fences are CLI flag docs or
  1291. // option dumps, not prose AI scaffolding — flush any prose run
  1292. // we were tracking and skip until the fence closes.
  1293. flushRun();
  1294. inFence = !inFence;
  1295. continue;
  1296. }
  1297. if (inFence) continue;
  1298. const m = line.match(bulletRe);
  1299. if (m) {
  1300. run.push(m[1].trim());
  1301. blankStreak = 0;
  1302. } else if (line.trim() === '') {
  1303. // A single blank line inside a list is normal Markdown spacing;
  1304. // two or more blank lines break the run, since visually-disjoint
  1305. // bullet sections shouldn't merge into one logical list.
  1306. blankStreak++;
  1307. if (blankStreak >= 2) flushRun();
  1308. } else {
  1309. flushRun();
  1310. }
  1311. }
  1312. flushRun();
  1313. // NOTE: "Wall-of-text replies" (SKILL.md) is deliberately NOT a
  1314. // detector rule here. A first pass tried "reply-length text, >=4
  1315. // sentences, zero newlines" as a structural gate — it broke the
  1316. // "repeated Tier 1 phrase does not inflate score linearly" fixture
  1317. // and, on reflection, would fire on any ordinary short paragraph
  1318. // (a blog intro, a single-paragraph email) since "one paragraph with
  1319. // no internal line break" is simply what continuous prose looks
  1320. // like, not an AI-specific shape. The tell in SKILL.md depends on
  1321. // knowing the text is conversational-reply register in the first
  1322. // place, which the engine can't reliably infer from the bytes alone
  1323. // (CONTRIBUTING.md: "a signal that fires on most normal prose is not
  1324. // worth adding"). Left as an LLM-judgment rule; see CATEGORIES.md §C.
  1325. // Confidence calibration is only flagged when it stacks (3+ instances).
  1326. // Gating happens pre-dedup on raw match count, since that signals actual
  1327. // stacking, not just vocabulary use.
  1328. const confIssues = matchPatterns(text, CONFIDENCE_CALIBRATION, 'confidence-calibration', 'low');
  1329. if (confIssues.length >= 3) issues.push(...confIssues);
  1330. // ── 22. Em dash frequency ────────────────────────────────────
  1331. // Match real em dashes, plus `--` only when surrounded by whitespace on at
  1332. // least one side (skips CLI flags like --save-dev and YAML `---` blocks).
  1333. // Separator-position em dashes (SEPARATOR_DASH_RE above) are excluded
  1334. // from the rate. The list marker is required on purpose: a line-initial
  1335. // "**Bold lead** — full sentence" outside a list is itself an AI tell
  1336. // and still counts, as does a mid-sentence "**bold** — like this"
  1337. // splice. Em dash only — the `--` substitute is never carved out.
  1338. const rawEmDashCount = (text.match(/—|(?<=\s)--(?=\s|$)|(?<=^|\s)--(?=\s)/gm) || []).length;
  1339. const separatorDashCount = (text.match(SEPARATOR_DASH_RE) || []).length
  1340. + (text.match(VERSION_HEADING_DASH_RE) || []).length;
  1341. const emDashCount = rawEmDashCount - separatorDashCount;
  1342. const emDashRate = emDashCount / (wordCount / 1000);
  1343. if (emDashRate > 1) {
  1344. issues.push({
  1345. type: 'em-dash',
  1346. text: `${emDashCount} em dashes in ${wordCount} words`,
  1347. severity: 'medium',
  1348. suggestion: 'Replace with commas, periods, or rewrite',
  1349. });
  1350. }
  1351. // ── 23. Sentence length uniformity ───────────────────────────
  1352. if (sentences.length >= 5) {
  1353. const lengths = sentences.map(s => countWords(s));
  1354. const avg = lengths.reduce((a, b) => a + b, 0) / lengths.length;
  1355. const variance = lengths.reduce((sum, l) => sum + Math.pow(l - avg, 2), 0) / lengths.length;
  1356. const stdDev = Math.sqrt(variance);
  1357. const cv = avg > 0 ? stdDev / avg : 0;
  1358. if (cv < 0.25 && avg > 10) {
  1359. issues.push({
  1360. type: 'uniformity',
  1361. text: `Sentence lengths cluster around ${Math.round(avg)} words (low variation)`,
  1362. severity: 'medium',
  1363. suggestion: 'Mix short punchy sentences with longer flowing ones',
  1364. });
  1365. }
  1366. }
  1367. // ── Type-token ratio (stylometric — vocabulary diversity) ────
  1368. // TTR = distinct word types / total tokens. Human prose at 200+
  1369. // words typically sits around 0.50–0.65 for English; AI prose
  1370. // tends flatter (0.55–0.75 looks normal, but the lower end of the
  1371. // *too-flat* tail at >=200 words is where the signal lives — too
  1372. // FEW unique words for the length). This is the simplest of the
  1373. // four stylometric signals identified in the May 2026 detection-
  1374. // research review (docs/competitive/detection-research.md): no
  1375. // POS tagger required, no model, pure JS.
  1376. //
  1377. // Threshold tuning: flag only when the sample is large enough
  1378. // that low TTR is meaningfully suspicious (>=200 tokens) AND TTR
  1379. // is below 0.40 (very vocabulary-poor). Conservative on purpose;
  1380. // false positives on short or topic-narrow human prose are easy
  1381. // to trigger and would drown out other signals. The detector-
  1382. // research lens flagged TTR as one of four stylometric add-ons;
  1383. // POS-bigram log-odds, function-word z-scores, and sentence-
  1384. // length burstiness are still TODO.
  1385. if (tokens.length >= 200) {
  1386. const unique = new Set(tokens).size;
  1387. const ttr = unique / tokens.length;
  1388. if (ttr < 0.4) {
  1389. issues.push({
  1390. type: 'low-ttr',
  1391. text: `Vocabulary diversity ${(ttr * 100).toFixed(1)}% (${unique} unique / ${tokens.length} tokens)`,
  1392. severity: 'low',
  1393. suggestion: 'Text reuses a narrow word set. Vary nouns and verbs deliberately, or check if the topic genuinely warrants the repetition.',
  1394. });
  1395. }
  1396. }
  1397. // ── 24. Paragraph length uniformity ──────────────────────────
  1398. if (paragraphs.length >= 4) {
  1399. const paraLengths = paragraphs.map(p => getSentences(p).length);
  1400. const avg = paraLengths.reduce((a, b) => a + b, 0) / paraLengths.length;
  1401. const allSimilar = paraLengths.every(l => Math.abs(l - avg) <= 1);
  1402. if (allSimilar && avg >= 3) {
  1403. issues.push({
  1404. type: 'uniformity',
  1405. text: `All paragraphs are ~${Math.round(avg)} sentences`,
  1406. severity: 'low',
  1407. suggestion: 'Vary paragraph length deliberately',
  1408. });
  1409. }
  1410. }
  1411. // ── 25. Bold overuse ─────────────────────────────────────────
  1412. const boldMatches = text.match(/\*\*[^*]+\*\*/g) || [];
  1413. if (boldMatches.length > 3) {
  1414. issues.push({
  1415. type: 'formatting',
  1416. text: `${boldMatches.length} bold phrases`,
  1417. severity: 'medium',
  1418. suggestion: 'Strip bold from most; restructure to lead with key info',
  1419. });
  1420. }
  1421. // ── Score from the deduped issue list ───────────────────────
  1422. // Previously rawScore was accumulated inline per pattern hit, so
  1423. // repeated hits of the same phrase (or overlapping matches) inflated
  1424. // the score while the displayed issue list was deduplicated. That
  1425. // produced the UX regression where a "heavy AI patterns" label sat
  1426. // above a list of two items. Now the dedup runs first, then each
  1427. // distinct issue contributes its category weight — so the number
  1428. // reflects the same signals the user actually sees.
  1429. const deduped = deduplicateIssues(issues);
  1430. for (const issue of deduped) {
  1431. rawScore += ISSUE_WEIGHTS[issue.type] ?? 2;
  1432. }
  1433. // Scale by text length: longer text gets more chances to trigger.
  1434. const lengthFactor = Math.max(1, Math.log2(wordCount / 50));
  1435. const normalizedScore = Math.min(100, Math.round(rawScore / lengthFactor));
  1436. const label = getLabel(normalizedScore);
  1437. // ── Sentence-region smoothing (HMM-style without an HMM) ─────────
  1438. // Map each text-bearing issue back to its sentence indexes, then
  1439. // merge adjacent flagged sentences into contiguous regions for UI
  1440. // highlighting. Borrowed from GPTZero's sentence-highlighting model
  1441. // — gives users "this paragraph is AI" rather than scattered hits.
  1442. const regions = buildSentenceRegions(text, deduped);
  1443. // Stats derived from the same deduped list so tier counts + patternCount
  1444. // sum to `deduped.length`. Previously patternCount subtracted
  1445. // `tier2Clusters` (a paragraph count) which produced inconsistent totals.
  1446. const tier1Count = deduped.filter((i) => i.type === 'tier1').length;
  1447. const tier2Count = deduped.filter((i) => i.type === 'tier2').length;
  1448. const tier3Count = deduped.filter((i) => i.type === 'tier3').length;
  1449. // ── Trinary classification (GPTZero-shaped) ──────────────────────
  1450. // Decouples confidence from AI-proportion. Maps the 0-100 score plus
  1451. // structural signals into HUMAN_ONLY / MIXED / AI_ONLY with a
  1452. // confidence band. Thresholds are FN-biased: ambiguity routes to
  1453. // MIXED, never AI_ONLY. Quote from GPTZero's design principle:
  1454. // "biases the detector to prefer making less-harmful false-negative
  1455. // errors over false-positive errors."
  1456. // Dense-AI-vocab trifecta: ≥5 distinct tier1 hits + ≥2 tier2 cluster
  1457. // paragraphs + ≥1 transition phrase, AND ≥150 words. Catches
  1458. // saturated ChatGPT prose without firing on dense-jargon human
  1459. // technical writing where the tier1 vocabulary (robust,
  1460. // comprehensive, leverage, ecosystem) legitimately overlaps with
  1461. // systems-programming idiom. Word-count gate prevents short ESL or
  1462. // contrived adversarial sentences from tripping the corroborator.
  1463. const tier1Distinct = new Set(deduped.filter((i) => i.type === 'tier1').map((i) => (i.text || '').toLowerCase())).size;
  1464. const hasTier2Cluster = tier2Clusters >= 2;
  1465. const hasTransition = deduped.some((i) => i.type === 'transition');
  1466. const denseAIVocab = wordCount >= 150 && tier1Distinct >= 5 && hasTier2Cluster && hasTransition;
  1467. const trinary = classifyTrinary({
  1468. score: normalizedScore,
  1469. issues: deduped,
  1470. regions,
  1471. normFlags: norm.flags,
  1472. wordCount,
  1473. denseAIVocab,
  1474. });
  1475. return {
  1476. // Legacy fields preserved for existing callers.
  1477. score: normalizedScore,
  1478. label,
  1479. issues: deduped,
  1480. stats: {
  1481. wordCount,
  1482. tier1Count,
  1483. tier2Count,
  1484. tier2Clusters,
  1485. tier3Count,
  1486. tier3Flags,
  1487. patternCount: deduped.length - tier1Count - tier2Count - tier3Count,
  1488. contextMode,
  1489. contextModeFallback,
  1490. normalization: norm.flags,
  1491. quotedLines,
  1492. unmappedHighlights: regions._unmapped ?? 0,
  1493. denseAIVocab,
  1494. tier1Distinct,
  1495. },
  1496. // Trinary API — shape mirrors GPTZero so integrators can swap.
  1497. document_classification: trinary.classification,
  1498. class_probabilities: trinary.probabilities,
  1499. confidence_category: trinary.confidence,
  1500. highlight_sentence_for_ai: regions,
  1501. };
  1502. }
  1503. // ═══ Sentence regions + trinary classifier ═════════════════════════
  1504. function buildSentenceRegions(text, issues) {
  1505. // Split text into sentences with byte offsets preserved so the UI
  1506. // can highlight spans accurately. Sentence boundaries are coarse
  1507. // (.!?) — fine for highlighting, not for linguistic correctness.
  1508. const sentences = [];
  1509. const sentenceRe = /[^.!?]+[.!?]+|\S[^.!?]*$/g;
  1510. let m;
  1511. while ((m = sentenceRe.exec(text)) !== null) {
  1512. const trimmed = m[0].trim();
  1513. if (trimmed.length < 4) continue;
  1514. sentences.push({ start: m.index, end: m.index + m[0].length, text: trimmed });
  1515. }
  1516. if (sentences.length === 0) return [];
  1517. // Map issue.text back to sentence indexes via substring search. Issues
  1518. // without a meaningful text (e.g. summary signals like "Punctuation
  1519. // density uniform across paragraphs") have no sentence anchor — they
  1520. // contribute to the document-level signal but not to highlights.
  1521. // Filter by issue TYPE not text-regex: text-based filtering used to
  1522. // drop legitimate phrase issues containing "across" / "density".
  1523. const SUMMARY_ONLY_TYPES = new Set([
  1524. 'punct-distribution',
  1525. 'cross-para-burstiness',
  1526. 'fnword-trigram-entropy',
  1527. 'smart-punct-signature',
  1528. 'normalization-flag',
  1529. 'uniformity',
  1530. 'em-dash',
  1531. 'formatting',
  1532. 'tier3',
  1533. 'tier3-phrase',
  1534. 'tier3-phrase-cluster',
  1535. 'hashtag-stuff',
  1536. 'bullet-np-list',
  1537. ]);
  1538. const hits = sentences.map(() => ({ count: 0, weight: 0 }));
  1539. const lowerText = text.toLowerCase();
  1540. let unmappedHighlights = 0;
  1541. for (const issue of issues) {
  1542. if (!issue.text || issue.text.length > 200) continue;
  1543. if (SUMMARY_ONLY_TYPES.has(issue.type)) continue;
  1544. const needle = issue.text.toLowerCase();
  1545. let idx = 0;
  1546. let matched = false;
  1547. while ((idx = lowerText.indexOf(needle, idx)) !== -1) {
  1548. matched = true;
  1549. for (let i = 0; i < sentences.length; i++) {
  1550. if (idx >= sentences[i].start && idx < sentences[i].end) {
  1551. hits[i].count++;
  1552. hits[i].weight += ISSUE_WEIGHTS[issue.type] ?? 2;
  1553. break;
  1554. }
  1555. }
  1556. idx += needle.length;
  1557. }
  1558. if (!matched) unmappedHighlights++;
  1559. }
  1560. // Window-merge contiguous flagged sentences. Allow 1 unflagged
  1561. // sentence gap between two flagged ones (the "smoothing" — keeps
  1562. // a single boring sentence from breaking what's clearly an AI
  1563. // passage). A sentence is "flagged" if it has ≥1 hit.
  1564. const regions = [];
  1565. let cur = null;
  1566. for (let i = 0; i < sentences.length; i++) {
  1567. if (hits[i].count > 0) {
  1568. if (cur === null) {
  1569. cur = { startSentence: i, endSentence: i, start: sentences[i].start, end: sentences[i].end, hitCount: hits[i].count, weight: hits[i].weight };
  1570. } else {
  1571. cur.endSentence = i;
  1572. cur.end = sentences[i].end;
  1573. cur.hitCount += hits[i].count;
  1574. cur.weight += hits[i].weight;
  1575. }
  1576. } else if (cur !== null) {
  1577. // Allow one-sentence gap.
  1578. const next = hits[i + 1];
  1579. if (next && next.count > 0) {
  1580. cur.endSentence = i;
  1581. cur.end = sentences[i].end;
  1582. continue;
  1583. }
  1584. regions.push(finalizeRegion(cur));
  1585. cur = null;
  1586. }
  1587. }
  1588. if (cur !== null) regions.push(finalizeRegion(cur));
  1589. // Expose the unmapped-highlight count via a non-enumerable property
  1590. // so the array length still reads naturally for consumers; the
  1591. // analyzer pulls it into stats.unmappedHighlights for diagnostics.
  1592. Object.defineProperty(regions, '_unmapped', { value: unmappedHighlights, enumerable: false });
  1593. return regions;
  1594. }
  1595. function finalizeRegion(r) {
  1596. // Map cumulative weight inside the region to a 0-1 score. Cap at 20
  1597. // weight = 1.0 (matches Heavy threshold density).
  1598. const score = Math.min(1, r.weight / 20);
  1599. return {
  1600. startSentence: r.startSentence,
  1601. endSentence: r.endSentence,
  1602. start: r.start,
  1603. end: r.end,
  1604. hitCount: r.hitCount,
  1605. score: Math.round(score * 100) / 100,
  1606. };
  1607. }
  1608. // FN-biased: false positives damage trust more than false negatives,
  1609. // so MIXED is wide and AI_ONLY requires multiple signals. Quote from
  1610. // GPTZero: "biases the detector to prefer making less-harmful
  1611. // false-negative errors over false-positive errors."
  1612. function classifyTrinary({ score, issues, regions, normFlags, wordCount, denseAIVocab }) {
  1613. // Strong corroborators — each is near-dispositive on its own:
  1614. // - cutoff-disclaimer (LLM self-identifies as an AI)
  1615. // - reasoning-artifact + chatbot-artifact co-occurrence
  1616. // - normalization-flag at threshold (≥2 ZWSP or homoglyphs).
  1617. // Threshold parity prevents a single stray ZWSP in copy-paste
  1618. // from Word/Notion from flipping to AI_ONLY at score 0.
  1619. // - denseAIVocab: ≥4 distinct tier1 hits AND ≥1 tier2 cluster AND
  1620. // ≥1 transition phrase — the trifecta that saturated ChatGPT
  1621. // prose triggers without needing whitelisted stylometric hits.
  1622. const hasCutoff = issues.some((i) => i.type === 'cutoff-disclaimer');
  1623. const hasNormFlag = normFlags.zeroWidth >= 2 || normFlags.homoglyph >= 2;
  1624. const hasReasoning = issues.some((i) => i.type === 'reasoning-artifact');
  1625. const hasChatbot = issues.some((i) => i.type === 'chatbot');
  1626. const strongCorrob =
  1627. (hasCutoff ? 1 : 0) +
  1628. (hasNormFlag ? 1 : 0) +
  1629. (hasReasoning && hasChatbot ? 1 : 0) +
  1630. (denseAIVocab ? 1 : 0);
  1631. // Weak (stylometric) corroborators — suggestive on their own,
  1632. // dispositive in combination. Smart-punct-signature matches
  1633. // Word-edited human prose so doesn't count without other support.
  1634. const stylometricHits = ['punct-distribution', 'cross-para-burstiness', 'fnword-trigram-entropy']
  1635. .filter((t) => issues.some((i) => i.type === t)).length;
  1636. const hasSmartPunct = issues.some((i) => i.type === 'smart-punct-signature');
  1637. const weakCorrob = (stylometricHits >= 2 ? 1 : 0) + (hasSmartPunct ? 1 : 0);
  1638. // Thresholds:
  1639. // score < 15 with no strong → HUMAN_ONLY
  1640. // strong ≥ 1 OR score ≥ 70 → AI_ONLY (lowered from 80; high
  1641. // density of AI vocab is sufficient evidence)
  1642. // score ≥ 40 with any corroborator → AI_ONLY
  1643. // everything else with score ≥ 15 → MIXED
  1644. const totalCorrob = strongCorrob + weakCorrob;
  1645. let classification;
  1646. if (score < 15 && strongCorrob === 0) classification = 'HUMAN_ONLY';
  1647. else if (strongCorrob >= 1 || score >= 70) classification = 'AI_ONLY';
  1648. else if (score >= 40 && totalCorrob >= 1) classification = 'AI_ONLY';
  1649. else classification = 'MIXED';
  1650. // Humanizer-flag escalation: presence of bypass-trick chars is
  1651. // adversarial signal. If a normalization-flag fired we already
  1652. // counted it in strongCorrob → AI_ONLY. Confidence also gets a
  1653. // floor of 'medium' in that case (an adversary actively evading
  1654. // detection should never read as low-confidence noise).
  1655. // Soft probability distribution. Not calibrated against a labeled
  1656. // corpus yet (TODO when corpus exists — see roadmap.md). Largest
  1657. // class is computed as `1 - others` after rounding to guarantee
  1658. // sum=1 exactly. Sub-1% drift would otherwise hide in toFixed.
  1659. const aiSoft = Math.min(0.97, score / 100 + totalCorrob * 0.06 + strongCorrob * 0.08);
  1660. let p;
  1661. if (classification === 'HUMAN_ONLY') p = { human: Math.max(0.6, 1 - aiSoft), mixed: Math.min(0.35, aiSoft * 0.8), ai: Math.min(0.1, aiSoft * 0.3) };
  1662. else if (classification === 'AI_ONLY') p = { human: Math.max(0.02, 1 - aiSoft - 0.05), mixed: 0.1, ai: aiSoft };
  1663. else p = { human: Math.max(0.15, 0.6 - aiSoft * 0.5), mixed: 0.5, ai: aiSoft * 0.7 };
  1664. const rawSum = p.human + p.mixed + p.ai;
  1665. p.human = +(p.human / rawSum).toFixed(3);
  1666. p.mixed = +(p.mixed / rawSum).toFixed(3);
  1667. // Assign ai as the remainder so the three values sum to exactly 1.
  1668. // Clamp to >= 0 in case rounding pushes human+mixed above 1 (the
  1669. // remainder would otherwise show as -0 or -0.001 — surfaces as a
  1670. // negative percentage in any UI doing Math.round(p.ai * 100)).
  1671. p.ai = Math.max(0, +(1 - p.human - p.mixed).toFixed(3));
  1672. const probabilities = p;
  1673. // Confidence band:
  1674. // high — strongCorrob ≥ 2, OR cutoff-disclaimer, OR score < 8 (clean long doc)
  1675. // medium — strongCorrob ≥ 1, OR score ≥ 45 with weak corroborator, OR score < 20
  1676. // low — everything else
  1677. let confidence;
  1678. if (strongCorrob >= 2 || hasCutoff || (score < 8 && wordCount >= 100)) confidence = 'high';
  1679. else if (strongCorrob >= 1 || (score >= 45 && weakCorrob >= 1) || score < 20) confidence = 'medium';
  1680. else confidence = 'low';
  1681. return { classification, probabilities, confidence };
  1682. }
  1683. function getLabel(score) {
  1684. if (score === 0) return 'Clean';
  1685. if (score <= 15) return 'Minimal AI signals';
  1686. if (score <= 35) return 'Some AI patterns';
  1687. if (score <= 60) return 'Moderate AI signals';
  1688. if (score <= 80) return 'Strong AI signals';
  1689. return 'Heavy AI patterns';
  1690. }
  1691. function getColor(score) {
  1692. if (score <= 15) return '#44bb66';
  1693. if (score <= 35) return '#88bb44';
  1694. if (score <= 60) return '#ddaa00';
  1695. if (score <= 80) return '#ff8833';
  1696. return '#ff4444';
  1697. }
  1698. function deduplicateIssues(issues) {
  1699. const seen = new Set();
  1700. return issues.filter(issue => {
  1701. const key = `${issue.type}:${issue.text.toLowerCase()}`;
  1702. if (seen.has(key)) return false;
  1703. seen.add(key);
  1704. return true;
  1705. });
  1706. }
  1707. // ─── Severity labels ──────────────────────────────────────────
  1708. const SEVERITY_LABELS = {
  1709. critical: 'P0',
  1710. high: 'P1',
  1711. medium: 'P2',
  1712. low: 'P3',
  1713. };
  1714. const TYPE_LABELS = {
  1715. 'tier1': 'AI vocabulary',
  1716. 'tier1-clarity': 'Wordiness',
  1717. 'tier2': 'Word cluster',
  1718. 'tier3': 'Overused word',
  1719. 'transition': 'AI transition',
  1720. 'chatbot': 'Chatbot artifact',
  1721. 'sycophantic': 'Sycophantic tone',
  1722. 'filler': 'Filler phrase',
  1723. 'generic-conclusion': 'Generic conclusion',
  1724. 'lets-construction': '"Let\'s" opener',
  1725. 'reasoning-artifact': 'Reasoning artifact',
  1726. 'acknowledgment-loop': 'Acknowledgment loop',
  1727. 'significance-inflation': 'Significance inflation',
  1728. 'vague-attribution': 'Vague attribution',
  1729. 'hollow-intensifier': 'Hollow intensifier',
  1730. 'emotional-flatline': 'Emotional flatline',
  1731. 'lingering-attention': 'Lingering-attention claim',
  1732. 'novelty-inflation': 'Novelty inflation',
  1733. 'cutoff-disclaimer': 'Cutoff disclaimer',
  1734. 'template-phrase': 'Template phrase',
  1735. 'false-concession': 'False concession',
  1736. 'rhetorical-question': 'Rhetorical question',
  1737. 'confidence-calibration': 'Confidence stacking',
  1738. 'em-dash': 'Em dash overuse',
  1739. 'uniformity': 'Rhythm uniformity',
  1740. 'formatting': 'Formatting',
  1741. 'tier3-phrase': 'Boilerplate phrase',
  1742. 'tier3-phrase-cluster': 'Boilerplate cluster',
  1743. 'hashtag-stuff': 'Hashtag stuffing',
  1744. 'bullet-np-list': 'Bullet-NP list',
  1745. 'hedge-stack': 'Hedge-stacked prediction',
  1746. 'future-narrative': 'Generic future narrative',
  1747. 'real-actual-inflation': '"Real/actual" inflation',
  1748. 'social-cta-closer': 'Engagement-bait closer',
  1749. 'formulaic-opener': 'Formulaic opener',
  1750. 'speculative-opener': 'Speculative scenario opener',
  1751. 'title-case-header': 'Title Case header',
  1752. 'parenthetical-hedge': 'Parenthetical hedge',
  1753. 'smart-punct-signature': 'Smart-punct signature',
  1754. 'punct-distribution': 'Punctuation distribution',
  1755. 'fnword-trigram-entropy': 'Grammar repetition',
  1756. 'cross-para-burstiness': 'Cross-paragraph rhythm',
  1757. 'normalization-flag': 'Bypass-trick chars',
  1758. 'low-ttr': 'Low vocabulary diversity',
  1759. 'ai-placeholder': 'Unfilled placeholder',
  1760. 'ai-citation-markup': 'Chatbot citation markup leak',
  1761. 'ai-utm-source': 'AI-tool URL parameter',
  1762. };
  1763. return {
  1764. analyzeText,
  1765. normalizeText,
  1766. getLabel,
  1767. getColor,
  1768. SEVERITY_LABELS,
  1769. TYPE_LABELS,
  1770. };
  1771. })();
  1772. if (typeof module !== 'undefined' && module.exports) {
  1773. module.exports = AIDetector;
  1774. }

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.