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
Markdown
[](/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)
- {
- "name": "cctools-plugins",
- "version": "1.0.0",
- "owner": {
- "name": "Prasad Chalasani"
- },
- "plugins": [
- {
- "name": "visual-brief",
- "source": "./plugins/visual-brief",
- "description": "Quiet milestone reminders for Visual Brief publishers"
- },
- {
- "name": "safety-hooks",
- "source": "./plugins/safety-hooks",
- "description": "Provides safety guards to block or require confirmation for risky CLI operations (e.g., rm, destructive git actions, .env access, large file operations)"
- },
- {
- "name": "aichat",
- "source": "./plugins/aichat",
- "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"
- },
- {
- "name": "tmux-cli",
- "source": "./plugins/tmux-cli",
- "description": "Introduces tmux-cli skill for interacting with CLI scripts and other code agents inside tmux panes using the `tmux-cli` command"
- },
- {
- "name": "workflow",
- "source": "./plugins/workflow",
- "description": "Workflow utilities and agents including code walkthrough tools, work logging, issue specification helpers, and a UI testing agent for browser-based validation"
- },
- {
- "name": "langroid",
- "source": "./plugins/langroid",
- "description": "Design patterns for the Langroid multi-agent LLM framework, with a skill to add new patterns as you learn them"
- },
- {
- "name": "voice",
- "source": "./plugins/voice",
- "description": "Audio feedback when Claude Code agent completes tasks using pocket-tts"
- },
- {
- "name": "voxtype",
- "source": "./plugins/voxtype",
- "description": "Install and set up voxtype \u2014 local on-device voice dictation for macOS"
- },
- {
- "name": "msg",
- "source": "./plugins/msg",
- "description": "Inter-agent communication for Claude Code and Codex CLI sessions via threads and messages"
- },
- {
- "name": "agent-tunnel",
- "source": "./plugins/agent-tunnel",
- "description": "Publish the current Claude session via >share so teammates can ask it questions through the agent-tunnel Discord bot (read-only forks)"
- },
- {
- "name": "writing",
- "source": "./plugins/writing",
- "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)"
- },
- {
- "name": "dynamic-workflow",
- "source": "./plugins/dynamic-workflow",
- "description": "Durable JavaScript orchestration for headless Codex agents, plus the github-wake skill"
- }
- ]
- }
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)
- <div align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/">
- <img src="assets/title-blade-runner-theme.png" alt="CLAUDE CODE TOOLS"
- width="500"/>
- </a>
- CLI tools, skills, agents, hooks, and plugins for enhancing productivity with Claude Code and other coding agents.
- [](https://pchalasani.github.io/claude-code-tools/)
- [](https://pypi.org/project/claude-code-tools/)
- [](https://pypistats.org/packages/claude-code-tools)
- [](https://crates.io/crates/aichat-search)
- [](https://github.com/RoggeOhta/awesome-codex-cli)
- </div>
- ## [Full Documentation →](https://pchalasani.github.io/claude-code-tools/)
- Everything — installation, every tool, plugins, and guides — lives in the
- docs. Click a card below to jump to a feature, or
- **[read the full docs](https://pchalasani.github.io/claude-code-tools/)**.
- Skills install with one command (`-s` picks one skill, `-g` installs for
- every project). Most work in any agent; a few are Claude Code and Codex
- only (see the [Plugins page](https://pchalasani.github.io/claude-code-tools/getting-started/plugins/)).
- Needs Node.js 22.20 or newer for `npx`:
- ```bash
- npx skills add pchalasani/claude-code-tools -s voxtype-install
- ```
- <div align="center">
- <table>
- <tr>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/getting-started/">
- <img src="assets/card-quickstart.svg" alt="quick start" width="300"/>
- </a>
- </td>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/getting-started/plugins/">
- <img src="assets/card-plugins.svg" alt="plugins" width="300"/>
- </a>
- </td>
- </tr>
- </table>
- <table>
- <tr>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/tools/aichat/">
- <img src="assets/card-aichat.svg" alt="aichat" width="200"/>
- </a>
- </td>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/tools/voxtype/">
- <img src="assets/card-voxtype.svg" alt="voxtype" width="200"/>
- </a>
- </td>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/tools/tmux-cli/">
- <img src="assets/card-tmux.svg" alt="tmux-cli" width="200"/>
- </a>
- </td>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/tools/amux/">
- <img src="assets/card-amux.svg" alt="amux" width="200"/>
- </a>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/tools/agent-tunnel/">
- <img src="assets/card-agent-tunnel.svg" alt="agent-tunnel" width="200"/>
- </a>
- </td>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/tools/lmsh/">
- <img src="assets/card-lmsh.svg" alt="lmsh" width="200"/>
- </a>
- </td>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/tools/vault/">
- <img src="assets/card-vault.svg" alt="vault" width="200"/>
- </a>
- </td>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/tools/env-safe/">
- <img src="assets/card-env-safe.svg" alt="env-safe" width="200"/>
- </a>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/plugins-detail/safety-hooks/">
- <img src="assets/card-safety.svg" alt="safety" width="200"/>
- </a>
- </td>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/tools/sasy-guard/">
- <img src="assets/card-sasy-guard.svg" alt="sasy-guard" width="200"/>
- </a>
- </td>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/tools/statusline/">
- <img src="assets/card-statusline.svg" alt="statusline" width="200"/>
- </a>
- </td>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/tools/fix-session/">
- <img src="assets/card-session-repair.svg" alt="session repair" width="200"/>
- </a>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/integrations/google-docs/">
- <img src="assets/card-gdocs.svg" alt="gdocs" width="200"/>
- </a>
- </td>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/integrations/google-sheets/">
- <img src="assets/card-gsheets.svg" alt="gsheets" width="200"/>
- </a>
- </td>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/integrations/alt-llm-providers/">
- <img src="assets/card-alt.svg" alt="alt" width="200"/>
- </a>
- </td>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/plugins-detail/voice/">
- <img src="assets/card-voice.svg" alt="voice" width="200"/>
- </a>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/tools/aichat/port/">
- <img src="assets/card-session-port.svg" alt="Claude <-> Codex session porting" width="200"/>
- </a>
- </td>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/tools/github-wake/">
- <img src="assets/card-github-watch.svg"
- alt="github-watch: wake on a GitHub comment" width="200"/>
- </a>
- </td>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/tools/msg/">
- <img src="assets/card-msg.svg" alt="msg: inter-agent comms" width="200"/>
- </a>
- </td>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/plugins-detail/visual-brief/">
- <img src="assets/card-visual-brief.svg" alt="Visual Brief" width="200"/>
- </a>
- </td>
- </tr>
- <tr>
- <td align="center" colspan="4">
- <a href="https://pchalasani.github.io/claude-code-tools/guides/claude-to-codex/">
- <img src="assets/card-codex-dynamic-workflows.svg"
- alt="Codex Dynamic Workflows" width="416"/>
- </a>
- </td>
- </tr>
- </table>
- <table>
- <tr>
- <td align="center">
- <a href="https://pchalasani.github.io/claude-code-tools/development/">
- <img src="assets/card-dev.svg" alt="development" width="300"/>
- </a>
- </td>
- <td align="center">
- <a href="LICENSE">
- <img src="assets/card-license.svg" alt="license" width="300"/>
- </a>
- </td>
- </tr>
- </table>
- </div>
plugins/safety-hooks/hooks/command_utils.py · Bundled script · 910 lines · 3 findings marked
- """Shared utilities for bash command parsing."""
- from __future__ import annotations
- import os
- import re
- import subprocess
- from shell_scan import (
- _end_of_balanced,
- _end_of_single_quote,
- _split_command_lines,
- _split_line_on_operators,
- _split_pipeline_groups,
- )
- from shell_payloads import literal_shell_payloads, needs_conservative_shell_scan
- # Cache for alias expansions (populated on first use)
- _alias_cache: dict[str, str] | None = None
- def _load_alias_cache() -> dict[str, str]:
- """
- Load all shell aliases into a cache dict.
- Sources the shell rc file and runs 'alias' to get all aliases.
- Avoids -i (interactive) flag to prevent TTY issues when run as
- a background process by Claude Code.
- Returns empty dict on failure.
- """
- global _alias_cache
- if _alias_cache is not None:
- return _alias_cache
- _alias_cache = {}
- shell = os.environ.get('SHELL', '/bin/bash')
- try:
- # Avoid -i (interactive) flag which can cause TTY issues
- # Source rc file explicitly to get aliases without interactive mode
- if 'zsh' in shell:
- cmd = [shell, '-c', 'source ~/.zshrc 2>/dev/null; alias']
- else:
- cmd = [shell, '-c', 'source ~/.bashrc 2>/dev/null; alias']
- result = subprocess.run(
- cmd,
- capture_output=True,
- text=True,
- timeout=5,
- stdin=subprocess.DEVNULL, # Explicitly close stdin
- start_new_session=True, # Isolate from terminal control
- env={**os.environ, 'PS1': '', 'TERM': 'dumb'},
- )
- output = result.stdout
- # Strip ANSI escape sequences
- output = re.sub(r'\x1b\][^\x07]*\x07', '', output)
- output = re.sub(r'\x1b\[[0-9;]*[a-zA-Z]', '', output)
- # Parse alias output - handles both bash and zsh formats:
- # bash: alias gcam='git commit -am'
- # zsh: gcam='git commit -a -m' or gcam="git commit -a -m"
- for line in output.strip().split('\n'):
- line = line.strip()
- if not line:
- continue
- # Remove leading 'alias ' if present (bash format)
- if line.startswith('alias '):
- line = line[6:]
- # Parse name=value
- if '=' in line:
- name, _, value = line.partition('=')
- name = name.strip()
- value = value.strip()
- # Remove surrounding quotes
- if (value.startswith("'") and value.endswith("'")) or \
- (value.startswith('"') and value.endswith('"')):
- value = value[1:-1]
- if name:
- _alias_cache[name] = value
- except Exception:
- pass # Fail silently, return empty cache
- return _alias_cache
- def expand_alias(command: str) -> str:
- """
- Expand shell alias in the first token of a command.
- Uses cached alias lookups for performance. The cache is populated
- once per hook invocation by sourcing the shell rc file.
- Args:
- command: A single bash command (not compound).
- Returns:
- Command with first token expanded if it's an alias,
- otherwise the original command unchanged.
- Example:
- >>> # With alias gco='git checkout'
- >>> expand_alias("gco -f")
- 'git checkout -f'
- """
- parts = command.split(None, 1) # Split into [first_token, rest]
- if not parts:
- return command
- first_token = parts[0]
- rest = parts[1] if len(parts) > 1 else ""
- # Skip if already a known command or path
- if first_token in ('git', 'rm', 'cat', 'less', 'nano', 'vim') or '/' in first_token:
- return command
- # Look up in alias cache
- alias_cache = _load_alias_cache()
- if first_token in alias_cache:
- expansion = alias_cache[first_token]
- return f"{expansion} {rest}".strip()
- return command
- def expand_command_aliases(command: str) -> str:
- """
- Expand aliases in a possibly compound bash command.
- Splits compound command on shell operators, expands each subcommand's
- alias, and reconstructs the command.
- Recognized operators:
- - && (AND)
- - || (OR)
- - ; (sequential)
- - | (pipe)
- - & (background)
- Args:
- command: A bash command string, possibly compound.
- Returns:
- Command with aliases expanded in each subcommand.
- Example:
- >>> # With alias gco='git checkout', gcam='git commit -am'
- >>> expand_command_aliases("gco -f && gcam 'msg'")
- "git checkout -f && git commit -am 'msg'"
- """
- if not command:
- return command
- # Find the operators and their positions to preserve them.
- # This regex captures the operators as well as the commands.
- # Multi-character operators (&&, ||) must come before single-character
- # variants ([;&|]) to prevent partial matching.
- parts = re.split(r'(\s*(?:&&|\|\||[;&|])\s*)', command)
- result = []
- for part in parts:
- # Check if this part is an operator
- if re.match(r'\s*(?:&&|\|\||[;&|])\s*', part):
- result.append(part)
- elif part.strip():
- # It's a command, expand its alias
- result.append(expand_alias(part.strip()))
- else:
- result.append(part)
- return ''.join(result)
- def extract_subcommands(command: str) -> list[str]:
- """
- Split compound bash command into individual subcommands.
- Splits on shell chaining operators:
- - && (AND)
- - || (OR)
- - ; (sequential)
- - | (pipe)
- - & (background)
- - a newline outside quotes, which ends a command just as ';' does
- Multi-character operators (&&, ||) are matched before single-character
- variants to prevent partial matching (e.g., '&&' won't be split as '&' + '&').
- Args:
- command: A bash command string, possibly compound.
- Returns:
- List of individual subcommands with whitespace stripped.
- Example:
- >>> extract_subcommands("cd /tmp && git add . && git commit -m 'msg'")
- ['cd /tmp', 'git add .', "git commit -m 'msg'"]
- >>> extract_subcommands("echo ok | rm foo")
- ['echo ok', 'rm foo']
- >>> extract_subcommands("sleep 1 & rm bar")
- ['sleep 1', 'rm bar']
- >>> extract_subcommands("echo ok\\nrm foo")
- ['echo ok', 'rm foo']
- """
- if not command:
- return []
- subcommands = []
- for line in _split_command_lines(command):
- subcommands.extend(_split_line_on_operators(line))
- return [cmd.strip() for cmd in subcommands if cmd.strip()]
- def _extract_balanced_paren_content(command: str, start_idx: int) -> str | None:
- """
- Extract content from balanced parentheses starting at given index.
- Given a string and the index of an opening '(', finds the matching
- closing ')' accounting for nested parentheses. A ')' inside quotes is
- text, not the closing one: stopping at it would cut the substitution
- short and hide the commands after it, as in "$(printf ')'; rm foo)".
- Args:
- command: The full command string.
- start_idx: Index of the opening '(' character.
- Returns:
- The content between the balanced parentheses (excluding the parens
- themselves), or None if no balanced closing paren is found.
- Example:
- >>> _extract_balanced_paren_content("$(echo $(rm foo))", 1)
- 'echo $(rm foo)'
- """
- if start_idx >= len(command) or command[start_idx] != '(':
- return None
- end = _end_of_balanced(command, start_idx, '(')
- if end is None:
- return None
- return command[start_idx + 1:end - 1]
- def extract_subshell_commands(command: str) -> list[str]:
- """
- Extract commands embedded in subshells from a bash command string.
- Detects and extracts commands from:
- - $(...) command substitution (modern syntax, handles nesting)
- - `...` backtick command substitution (legacy syntax)
- This is a security measure to detect dangerous commands hidden inside
- 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
- Uses balanced parenthesis scanning to correctly handle nested $()
- subshells like `$(echo $(rm foo))`.
- Args:
- command: A bash command string that may contain subshells.
- Returns:
- List of commands found inside subshells. Returns empty list if
- no subshells are found.
- Example:
- >>> extract_subshell_commands("echo $(whoami)")
- ['whoami']
- >>> extract_subshell_commands("echo `rm foo` bar")
- ['rm foo']
- >>> extract_subshell_commands("$(cat file) | $(rm -rf /)")
- Dismissed after review: Runs `rm -rf` against a root or home-directory path
- Line 269 on GitHub
- ['cat file', 'rm -rf /']
- Dismissed after review: Runs `rm -rf` against a root or home-directory path
- Line 270 on GitHub
- >>> extract_subshell_commands("echo $(echo $(rm foo))")
- ['echo $(rm foo)']
- """
- if not command:
- return []
- subshell_commands = []
- # Extract from $(...) - modern command substitution
- # Use balanced parenthesis scanning to handle nested subshells
- i = 0
- while i < len(command) - 1:
- if command[i:i+2] == '$(':
- # Found start of $(), extract balanced content
- inner_cmd = _extract_balanced_paren_content(command, i + 1)
- if inner_cmd is not None:
- inner_cmd = inner_cmd.strip()
- if inner_cmd:
- subshell_commands.append(inner_cmd)
- # Skip past this subshell to avoid re-matching nested ones
- # at the top level (they'll be found via recursion)
- i += 2 + len(inner_cmd) + 1 # $( + content + )
- continue
- i += 1
- # Extract from `...` - backtick command substitution (legacy syntax)
- # Backticks cannot be nested, so a simple pattern works
- backtick_pattern = r'`([^`]+)`'
- for match in re.finditer(backtick_pattern, command):
- inner_cmd = match.group(1).strip()
- if inner_cmd:
- subshell_commands.append(inner_cmd)
- return subshell_commands
- # Returned for a delimiter whose quoting the shell would unescape, which
- # this parser does not replicate. It cannot be treated as "no heredoc":
- # the body would then be scanned as commands, and a '<<' inside that body
- # would be read as a real heredoc, blanking the commands after the body.
- # Scanning stops instead, so nothing further is blanked.
- _UNDECODABLE_DELIMITER = object()
- def _heredoc_delimiter(command: str, start: int):
- # Return type is tuple[str, bool, bool, int], None, or the sentinel
- # above; annotating that adds nothing a reader wants here.
- """
- Parse the delimiter word of the '<<' operator at the given index.
- Args:
- command: The full command string.
- start: Index of the '<' that starts the '<<' operator.
- Returns:
- Tuple (delimiter, quoted, strip_tabs, end) where delimiter is the
- word after quote removal, quoted says whether any part of it was
- quoted (so the shell performs no expansion in the body),
- strip_tabs reflects the '<<-' form, and end is the index just past
- the delimiter word. Returns None when no delimiter word is there.
- """
- index = start + 2
- strip_tabs = index < len(command) and command[index] == '-'
- if strip_tabs:
- index += 1
- while index < len(command) and command[index] in ' \t':
- index += 1
- delimiter_parts = []
- quoted = False
- while index < len(command) and command[index] not in ' \t\r\n;&|<>()':
- character = command[index]
- if (character == '$' and index + 1 < len(command)
- and command[index + 1] in "'\""):
- # $'EOF' and $"EOF" quote the delimiter; the '$' is not part
- # of it, so bash ends the body at EOF, not at $EOF.
- ansi_c = command[index + 1] == "'"
- end = _end_of_single_quote(command, index + 1, escapes=ansi_c)
- if end is None:
- return None
- content = command[index + 2:end]
- if '\\' in content:
- # Both forms unescape: $'...' decodes ANSI-C escapes and
- # $"..." removes double-quote ones.
- return _UNDECODABLE_DELIMITER
- quoted = True
- delimiter_parts.append(content)
- index = end + 1
- elif (command.startswith('$(', index)
- or command.startswith('${', index)):
- # No expansion happens on a delimiter word, so "$(echo EOF)" is
- # the delimiter, literally, parentheses and all.
- opener = '(' if command[index + 1] == '(' else '{'
- end = _end_of_balanced(command, index + 1, opener)
- if end is None:
- return None
- delimiter_parts.append(command[index:end])
- index = end
- elif character == '`':
- # A backtick span is part of the word, and just as literal.
- end = command.find('`', index + 1)
- if end == -1:
- return None
- delimiter_parts.append(command[index:end + 1])
- index = end + 1
- elif character in "'\"":
- quoted = True
- end = _end_of_single_quote(command, index, escapes=False)
- if end is None:
- return None
- content = command[index + 1:end]
- if character == '"' and '\\' in content:
- # Quote removal would drop backslashes here.
- return _UNDECODABLE_DELIMITER
- delimiter_parts.append(content)
- index = end + 1
- elif character == '\\':
- if index + 1 >= len(command):
- return None
- if command[index + 1] == '\n':
- # A continuation inside the word: the shell removes both
- # characters before reading the delimiter, so "E\" + "OF"
- # is the delimiter EOF, and is not quoted by it.
- index += 2
- continue
- quoted = True
- delimiter_parts.append(command[index + 1])
- index += 2
- else:
- delimiter_parts.append(character)
- index += 1
- delimiter = ''.join(delimiter_parts)
- if not delimiter:
- return None
- return delimiter, quoted, strip_tabs, index
- def _ends_with_continuation(line: str) -> bool:
- """
- Report whether a physical line ends in a backslash-newline pair.
- Args:
- line: One physical line, without its newline.
- Returns:
- True when the line ends with an odd number of backslashes, so the
- last one escapes the newline instead of itself.
- """
- return (len(line) - len(line.rstrip('\\'))) % 2 == 1
- def _end_of_heredoc_body(
- command: str, start: int, delimiter: str, strip_tabs: bool,
- join_continuations: bool) -> tuple[int, int] | None:
- """
- Find the closing delimiter line of one heredoc body.
- Args:
- command: The full command string.
- start: Index where the body begins (just past a newline).
- delimiter: The delimiter word that ends the body.
- strip_tabs: Whether the '<<-' form allows leading tabs on it.
- join_continuations: Whether backslash-newline pairs are removed
- while reading the body, as they are for an unquoted delimiter.
- A delimiter can then be split over two lines ("EO\\" + "F").
- Returns:
- Tuple (delimiter_line_start, body_end): the index where the line
- holding the delimiter begins -- which is where the body ends, and
- with '<<-' may be a leading tab rather than the delimiter itself
- -- and the index just past that line. None when the body is never
- closed.
- """
- line_start = start
- while line_start <= len(command):
- # Read one logical line, which may span several physical ones.
- parts = []
- scan = line_start
- while True:
- line_end = command.find('\n', scan)
- if line_end == -1:
- line_end = len(command)
- part = command[scan:line_end].removesuffix('\r')
- if (join_continuations and line_end < len(command)
- and _ends_with_continuation(part)):
- parts.append(part[:-1])
- scan = line_end + 1
- continue
- parts.append(part)
- break
- line = ''.join(parts)
- if strip_tabs:
- line = line.lstrip('\t')
- if line == delimiter:
- return line_start, min(line_end + 1, len(command))
- if line_end == len(command):
- return None
- line_start = line_end + 1
- return None
- def _heredoc_bodies(
- command: str, start: int,
- pending: list[tuple[str, bool, bool, int]]) -> tuple[int, list[str]] | None:
- """
- Consume the bodies of every heredoc declared on one command line.
- A command line may open several heredocs ("cat <<A <<'B'"); their
- bodies follow the line in declaration order, one after another. Taking
- them one at a time would read the second body as shell syntax.
- Args:
- command: The full command string.
- start: Index where the first body begins (just past the newline
- that ends the command line).
- pending: The (delimiter, quoted, strip_tabs, depth) tuples in the
- order the heredocs were declared; depth is unused here.
- Returns:
- Tuple (end, expanded_bodies): the index just past the last body's
- delimiter line, and the bodies whose expansions the shell runs
- (those with an unquoted delimiter). None when any body is
- unterminated, in which case no body is treated as data.
- """
- cursor = start
- expanded_bodies = []
- for delimiter, quoted, strip_tabs, _ in pending:
- bounds = _end_of_heredoc_body(
- command, cursor, delimiter, strip_tabs,
- join_continuations=not quoted)
- if bounds is None:
- return None
- delimiter_line_start, body_end = bounds
- if not quoted:
- expanded_bodies.append(command[cursor:delimiter_line_start])
- cursor = body_end
- return cursor, expanded_bodies
- # A '#' only opens a comment at the start of a word, so it must follow
- # whitespace or an operator (or start the command). ')' is included because
- # '(echo x)# comment' is a comment; the cost is that the rarer '$(date)#tag',
- # where '#' is mid-word, is misread as one -- which only ever makes this
- # function blank less, i.e. hand MORE text to the guards.
- _COMMENT_PRECEDERS = ' \t\n;&|(<>)'
- # A reserved word is only reserved in command position: at the start of
- # the command, or right after an operator that begins a new one. Spaces
- # may sit in between, but not another word -- 'echo case' is an argument.
- _COMMAND_STARTERS = '\n;&|({'
- def _keyword_at(command: str, index: int, keyword: str) -> bool:
- """
- Report whether a reserved word in command position starts at index.
- Args:
- command: The full command string.
- index: Index to test.
- keyword: The word to look for, e.g. 'case'.
- Returns:
- True when the keyword is there as a whole word and bash would
- read it as the reserved word rather than an ordinary argument.
- """
- if not command.startswith(keyword, index):
- return False
- before = index
- while before and command[before - 1] in ' \t':
- before -= 1
- if before and command[before - 1] not in _COMMAND_STARTERS:
- return False
- after = index + len(keyword)
- return after == len(command) or command[after] in ' \t\n;&|)'
- # The delimiter word as written: a plain name, optionally quoted one of
- # the three ways bash allows. Anything else ($'..', $"..", escapes inside
- # quotes, substitutions) is left to the shell.
- _SIMPLE_DELIMITER = re.compile(
- r"""^(?:\\?[A-Za-z0-9_]+|'[A-Za-z0-9_]+'|"[A-Za-z0-9_]+")$""")
- # Header-line text that makes bash's tokenization non-trivial. Every
- # known way to blank a real command (a body boundary the scanner places
- # differently from bash) has needed one of these on the heredoc's own
- # line; refusing to blank when any is present makes the failure direction
- # over-blocking, which the guards tolerate. The list is deliberately
- # blunt: a '(' is enough, whether or not it opens a substitution.
- _COMPLEX_HEADER_MARKS = ('`', '$', '(', ')', '{', '}', '[', ']', '\\')
- _PLAIN_VARIABLE = re.compile(r'\$(?:[A-Za-z_][A-Za-z0-9_]*|\{[A-Za-z_][A-Za-z0-9_]*\})')
- def _simple_heredoc_header(command: str, operator: int, end: int) -> bool:
- """
- Report whether a heredoc's header line is simple enough to trust.
- The scanner approximates bash's tokenizer, and every divergence found
- so far (parameter expansions, ANSI-C quoting, substitutions closing
- before a newline, 'case' patterns, subscripts, escaped delimiters)
- lets an attacker place a body boundary where bash does not, so that
- a real command is blanked as data. Rather than chase each one, blank
- bodies only when the header line -- the physical line holding the
- '<<' -- carries none of the constructs those divergences need, and
- the delimiter is a plain word with at most simple quoting.
- Args:
- command: The full command string.
- operator: Index of the '<<' operator.
- end: Index just past its delimiter word.
- The same principle covers the spans the scanner steps over as
- non-command text ($((...)), ${...}, $[...], name[...]=): a '<<' inside
- one of those is a place where bash and this scanner could disagree
- about whether a heredoc opened, so the caller blanks nothing then too.
- Returns:
- True when the header line has no complex construct and the
- delimiter is plain, so the body boundaries are unambiguous.
- """
- line_start = command.rfind('\n', 0, operator) + 1
- line_end = command.find('\n', operator)
- if line_end == -1:
- line_end = len(command)
- raw = command[operator + 2:end].lstrip('-').strip(' \t')
- if not _SIMPLE_DELIMITER.match(raw):
- return False
- header = command[line_start:operator + 2] + command[end:line_end]
- # A plain variable reference ("$HOME", "${name}") cannot move a token
- # boundary, and "cat > $HOME/notes.md <<'EOF'" is the common case.
- header = _PLAIN_VARIABLE.sub('', header)
- return not any(mark in header for mark in _COMPLEX_HEADER_MARKS)
- def strip_heredoc_bodies(command: str) -> tuple[str, list[str]]:
- """
- Blank heredoc bodies and return the bodies the shell still expands.
- A heredoc body is data, not code: the shell never runs its lines as
- commands. When the delimiter is quoted (<<'EOF', <<"EOF", <<\\EOF) the
- shell performs no expansion at all, so nothing in the body executes.
- With an unquoted delimiter (<<EOF) only the body's expansions -- $(...)
- and backticks -- execute.
- Bodies begin after the command line that opens them, which is not the
- same as the next newline: a backslash-newline continues that line, and
- a newline inside quotes or inside an unfinished command substitution
- does not end it. Every heredoc opened on one line is consumed, in
- order, and a command substitution is its own parsing unit with its own
- bodies.
- Args:
- command: A bash command string, possibly containing heredocs.
- Returns:
- Tuple (command_without_bodies, expanded_bodies). The first element
- is the command with every heredoc body (and its closing delimiter
- line) replaced by whitespace, preserving offsets and line breaks.
- The second is the list of bodies whose expansions do execute.
- Example:
- >>> strip_heredoc_bodies("cat <<'EOF'\\n`rm x`\\nEOF")[1]
- []
- >>> strip_heredoc_bodies("cat <<EOF\\n`rm x`\\nEOF")[1]
- ['`rm x`\\n']
- """
- expanded_bodies = []
- pieces = []
- copied_to = 0
- index = 0
- quote = None
- # A command substitution is parsed as its own unit, so it has its own
- # command lines and its own heredoc bodies. Track how deep we are in
- # one, and remember the depth each heredoc was opened at. Grouping
- # parentheses are tracked too, so that the ')' of a nested group is not
- # mistaken for the one closing the substitution.
- open_parens: list[str] = []
- depth = 0
- case_depth = 0
- in_backtick = False
- # Heredocs opened on the command line now being scanned. Their bodies
- # all follow that line, in the order the operators appeared.
- pending: list[tuple[str, bool, bool, int]] = []
- while index < len(command):
- character = command[index]
- if character == '\\' and quote != "'":
- # A backslash-newline continues the command line, so the body
- # does not start here; skipping the pair keeps that newline
- # out of the body-start decision below.
- index += 2
- continue
- if quote is None and command.startswith("$'", index):
- # ANSI-C quoting: a backslash escapes the closing quote.
- end = _end_of_single_quote(command, index + 1, escapes=True)
- index = len(command) if end is None else end + 1
- continue
- if character in "'\"":
- if quote == character:
- quote = None
- elif quote is None:
- quote = character
- index += 1
- continue
- if quote is None and (
- (command.startswith('$(', index)
- and not command.startswith('$((', index))
- or command.startswith('<(', index)
- or command.startswith('>(', index)):
- # A command substitution $( ), or a process substitution <( )
- # or >( ): each is parsed as its own unit, so a newline inside
- # one does not end the command line that contains it.
- open_parens.append('$(')
- depth += 1
- index += 2
- continue
- if quote is None and character == '`':
- # Backticks cannot nest, so one toggles the substitution.
- depth += -1 if in_backtick else 1
- in_backtick = not in_backtick
- if not in_backtick:
- # Closing: a heredoc opened inside that never reached a
- # newline gets no body, exactly as with ')' below. Left
- # pending, it would swallow the first lines of a later
- # substitution at the same depth as data.
- pending = [item for item in pending if item[3] <= depth]
- index += 1
- continue
- if quote is None and (_keyword_at(command, index, 'case')
- or _keyword_at(command, index, 'esac')):
- # Inside a case statement a ')' ends a pattern, so it must not
- # be taken for the one closing a substitution.
- if command[index] == 'c':
- case_depth += 1
- index += 4
- else:
- case_depth = max(0, case_depth - 1)
- index += 4
- continue
- if quote is None and character == ')' and open_parens:
- if open_parens[-1] == '$(' and case_depth:
- # A case pattern's ')', not the end of the substitution.
- index += 1
- continue
- if open_parens.pop() == '$(':
- depth -= 1
- # A heredoc whose substitution closed before any newline
- # never gets a body: bash reads it from inside there.
- pending = [item for item in pending if item[3] <= depth]
- index += 1
- continue
- if quote is None and character == '\n' and pending:
- # Only the heredocs opened at this depth end here; ones opened
- # further out belong to a command line this newline is nested
- # inside, and wait for their own.
- ready = [item for item in pending if item[3] == depth]
- if not ready:
- index += 1
- continue
- bodies = _heredoc_bodies(command, index + 1, ready)
- pending = [item for item in pending if item[3] != depth]
- if bodies is None:
- index += 1
- continue
- body_end, expanded = bodies
- if any('$' in body or '`' in body for body in expanded):
- # An unquoted body's expansions do run, and finding the
- # commands among them needs a second parser with the same
- # divergences: a case pattern's ')' closes '$(' early, and
- # "${x@P}" runs a substitution held in x with no '$(' in
- # the body at all. Leave such a body unblanked so the
- # guards see it whole; quote the delimiter to document
- # commands.
- return command, []
- pieces.append(command[copied_to:index + 1])
- pieces.append(''.join(
- '\n' if char == '\n' else ' '
- for char in command[index + 1:body_end]
- ))
- expanded_bodies.extend(expanded)
- copied_to = body_end
- index = body_end
- continue
- if quote is None and character == '#' and (
- index == 0 or command[index - 1] in _COMMENT_PRECEDERS):
- # A comment runs to end of line, so any '<<' in it is text.
- newline = command.find('\n', index)
- if newline == -1:
- break
- # Stop on the newline itself: it may still end a command line
- # whose heredoc bodies start right after the comment.
- index = newline
- continue
- if quote is None and command.startswith('((', index):
- # '<<' inside $((1 << 2)) is a left shift, not a heredoc.
- arithmetic_end = _end_of_balanced(command, index, '(')
- if arithmetic_end is not None:
- if '<<' in command[index:arithmetic_end]:
- return command, [] # see _simple_heredoc_header
- index = arithmetic_end
- continue
- if quote is None and command.startswith('${', index):
- # '<<' inside ${x:-<<EOF} is expansion text, not a heredoc.
- expansion_end = _end_of_balanced(command, index + 1, '{')
- if expansion_end is not None:
- if '<<' in command[index:expansion_end]:
- return command, [] # see _simple_heredoc_header
- index = expansion_end
- continue
- if quote is None and command.startswith('$[', index):
- # $[1 << 2] is the deprecated arithmetic form, still a shift.
- legacy_end = _end_of_balanced(command, index + 1, '[')
- if legacy_end is not None:
- if '<<' in command[index:legacy_end]:
- return command, [] # see _simple_heredoc_header
- index = legacy_end
- continue
- if quote is None and character == '(':
- # A grouping or subshell paren. It is not a parsing unit of its
- # own, but it has to be balanced so that its ')' is not taken
- # for the one closing a substitution. Checked after the
- # arithmetic and expansion skips above, which own their parens.
- open_parens.append('(')
- index += 1
- continue
- if (quote is None and character == '[' and index > 0
- and (command[index - 1].isalnum()
- or command[index - 1] == '_')):
- # An array subscript is an arithmetic context, so the '<<' in
- # "a[1<<2]=foo" is a shift. But only an assignment word gets
- # that reading: in "echo a[<<EOF]" bash sees the argument "a["
- # followed by a heredoc delimited by "EOF]". So the bracket is
- # skipped only when the balanced span is followed by '=' or
- # '+=', i.e. it really is "name[subscript]=value".
- subscript_end = _end_of_balanced(command, index, '[')
- if subscript_end is not None and (
- command.startswith('=', subscript_end)
- or command.startswith('+=', subscript_end)):
- if '<<' in command[index:subscript_end]:
- return command, [] # see _simple_heredoc_header
- index = subscript_end
- continue
- if quote is None and command.startswith('<<<', index):
- # A here-string, whose expansions do run. Step over the whole
- # operator: leaving the scan on its second '<' would read the
- # remaining '<<' as a heredoc and blank the lines after it.
- index += 3
- continue
- if quote is None and command.startswith('<<', index):
- delimiter = _heredoc_delimiter(command, index)
- if delimiter is _UNDECODABLE_DELIMITER:
- # The body of this one cannot be located. Stop rather than
- # scan on: text inside that body could otherwise be read as
- # another heredoc header and blank real commands.
- break
- if isinstance(delimiter, tuple):
- word, quoted, strip_tabs, end = delimiter
- if depth or in_backtick or not _simple_heredoc_header(
- command, index, end):
- # Not provably simple: blank NOTHING in this command.
- # See _simple_heredoc_header for why.
- return command, []
- pending.append((word, quoted, strip_tabs, depth))
- index = end
- continue
- index += 1
- pieces.append(command[copied_to:])
- return ''.join(pieces), expanded_bodies
- def extract_all_commands(command: str) -> list[str]:
- """
- Recursively extract all commands from a bash command string.
- This combines subcommand extraction (splitting on shell operators)
- with subshell extraction (commands inside $() or backticks) to
- provide a comprehensive list of all commands that will be executed.
- This is the recommended function for security hooks that need to
- inspect all commands, including those hidden in subshells.
- Heredoc bodies are treated as the data they are: a quoted delimiter
- (<<'EOF') means nothing in the body executes, and an unquoted one
- (<<EOF) means only the body's $() and backtick expansions execute.
- Args:
- command: A bash command string, possibly compound with subshells.
- Returns:
- List of all individual commands, including those from subshells.
- Example:
- >>> extract_all_commands("echo $(rm foo) && ls")
- ['echo $(rm foo)', 'ls', 'rm foo']
- >>> extract_all_commands("cat `echo secret` | grep pass")
- ['cat `echo secret`', 'grep pass', 'echo secret']
- >>> extract_all_commands("cat > f <<'EOF'\\n`rm x` is blocked\\nEOF")
- ["cat > f <<'EOF'"]
- """
- if not command:
- return []
- # Heredoc bodies are data, so their lines are not commands. Blank them
- # out first; expanded_bodies holds the bodies (unquoted delimiters only)
- # whose substitutions the shell does run.
- stripped, expanded_bodies = strip_heredoc_bodies(command)
- all_commands = []
- # First, extract top-level subcommands (split on operators)
- subcommands = extract_subcommands(stripped)
- all_commands.extend(subcommands)
- # Extract from normalized lines before operator splitting can break spans.
- # A continuation can join "$" and "(" into a substitution marker.
- subshell_cmds = []
- lines = _split_command_lines(stripped)
- for line in lines:
- subshell_cmds.extend(extract_subshell_commands(line))
- for group in _split_pipeline_groups(stripped):
- if any(needs_conservative_shell_scan(part)
- for part in extract_subcommands(group)):
- # Stdin consumers share a pipeline, not an unrelated command list.
- for fragment in re.split(r'&&|\|\||[;&|\n]', group):
- fragment = fragment.strip()
- if fragment and fragment not in all_commands:
- all_commands.append(fragment)
- # Quoted strings passed to evaluators are code, unlike search patterns.
- for subcommand in subcommands:
- subshell_cmds.extend(literal_shell_payloads(subcommand))
- # Only the substitutions inside an unquoted heredoc body execute; the
- # surrounding text is literal, so it is not split into subcommands.
- for body in expanded_bodies:
- subshell_cmds.extend(extract_subshell_commands(body))
- # Recursively process subshell commands (they may contain nested subshells
- # or chained operators)
- for subcmd in subshell_cmds:
- all_commands.extend(extract_all_commands(subcmd))
- return all_commands
plugins/safety-hooks/hooks/test_command_utils.py · Bundled script · 639 lines · 2 findings marked
- #!/usr/bin/env python3
- """
- Unit tests for command_utils.py
- Tests cover:
- - Shell operator splitting (&&, ||, ;, |, &)
- - Subshell extraction ($() and backticks)
- - Combined extraction via extract_all_commands()
- - Edge cases and regression tests for security bypasses
- """
- import unittest
- import sys
- import os
- # Add the hooks directory to path for imports
- sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
- from command_utils import (
- extract_subcommands,
- extract_subshell_commands,
- extract_all_commands,
- expand_command_aliases,
- strip_heredoc_bodies,
- )
- class TestExtractSubcommands(unittest.TestCase):
- """Tests for extract_subcommands() shell operator splitting."""
- def test_empty_command(self):
- """Empty string returns empty list."""
- self.assertEqual(extract_subcommands(""), [])
- self.assertEqual(extract_subcommands(" "), [])
- def test_single_command(self):
- """Single command without operators."""
- self.assertEqual(extract_subcommands("ls -la"), ["ls -la"])
- self.assertEqual(extract_subcommands("git status"), ["git status"])
- def test_and_operator(self):
- """Split on && (AND) operator."""
- result = extract_subcommands("cd /tmp && ls")
- self.assertEqual(result, ["cd /tmp", "ls"])
- def test_or_operator(self):
- """Split on || (OR) operator."""
- result = extract_subcommands("test -f file || echo missing")
- self.assertEqual(result, ["test -f file", "echo missing"])
- def test_semicolon_operator(self):
- """Split on ; (sequential) operator."""
- result = extract_subcommands("echo hello; echo world")
- self.assertEqual(result, ["echo hello", "echo world"])
- def test_newline_operator(self):
- """A newline ends a command just as ';' does - security regression."""
- result = extract_subcommands("echo ok\nrm foo")
- self.assertEqual(result, ["echo ok", "rm foo"])
- def test_newline_inside_quotes_is_not_a_separator(self):
- """A newline in a quoted word is part of that word, not an operator."""
- result = extract_subcommands("echo 'first\nrm foo'")
- self.assertEqual(result, ["echo 'first\nrm foo'"])
- def test_line_continuation_is_joined(self):
- """A backslash-newline continues the line, so the shell removes it."""
- result = extract_subcommands("echo ok ; \\\nrm foo")
- self.assertEqual(result, ["echo ok", "rm foo"])
- def test_pipe_operator(self):
- """Split on | (pipe) operator - security regression test."""
- result = extract_subcommands("echo ok | rm foo")
- self.assertEqual(result, ["echo ok", "rm foo"])
- result = extract_subcommands("cat file | grep pattern | wc -l")
- self.assertEqual(result, ["cat file", "grep pattern", "wc -l"])
- def test_background_operator(self):
- """Split on & (background) operator - security regression test."""
- result = extract_subcommands("sleep 1 & rm bar")
- self.assertEqual(result, ["sleep 1", "rm bar"])
- def test_mixed_operators(self):
- """Multiple different operators in one command."""
- result = extract_subcommands("cmd1 && cmd2 | cmd3; cmd4 || cmd5 & cmd6")
- self.assertEqual(result, ["cmd1", "cmd2", "cmd3", "cmd4", "cmd5", "cmd6"])
- def test_preserves_command_arguments(self):
- """Arguments within commands are preserved."""
- result = extract_subcommands("git add . && git commit -m 'msg with spaces'")
- self.assertEqual(result, ["git add .", "git commit -m 'msg with spaces'"])
- def test_double_operators_not_split_incorrectly(self):
- """&& should not become two & splits."""
- result = extract_subcommands("cmd1 && cmd2")
- # Should be 2 commands, not 3 (which would happen if && was split as & twice)
- self.assertEqual(len(result), 2)
- self.assertEqual(result, ["cmd1", "cmd2"])
- class TestExtractSubshellCommands(unittest.TestCase):
- """Tests for extract_subshell_commands() subshell detection."""
- def test_empty_command(self):
- """Empty string returns empty list."""
- self.assertEqual(extract_subshell_commands(""), [])
- def test_no_subshells(self):
- """Command without subshells returns empty list."""
- self.assertEqual(extract_subshell_commands("ls -la"), [])
- self.assertEqual(extract_subshell_commands("echo hello"), [])
- def test_dollar_paren_subshell(self):
- """Extract command from $() syntax."""
- result = extract_subshell_commands("echo $(whoami)")
- self.assertEqual(result, ["whoami"])
- def test_ansi_c_quoted_argument_inside_a_substitution(self):
- """$'don\\'t' is one word: its escaped quote must not end quoting.
- Regression: the quote-aware bracket balancing read the escaped
- quote as the closing one, then took the real closing quote as an
- opening one, and never saw the ')' -- hiding the rm.
- """
- command = "echo $(rm $'don\\'t')"
- self.assertEqual(extract_subshell_commands(command), ["rm $'don\\'t'"])
- def test_backtick_subshell(self):
- """Extract command from backtick syntax."""
- result = extract_subshell_commands("echo `whoami`")
- self.assertEqual(result, ["whoami"])
- def test_multiple_subshells(self):
- """Multiple subshells in one command."""
- result = extract_subshell_commands("$(cmd1) foo $(cmd2)")
- self.assertEqual(result, ["cmd1", "cmd2"])
- def test_mixed_subshell_syntax(self):
- """Both $() and backticks in same command."""
- result = extract_subshell_commands("$(cmd1) and `cmd2`")
- self.assertIn("cmd1", result)
- self.assertIn("cmd2", result)
- def test_subshell_with_arguments(self):
- """Subshell containing command with arguments."""
- result = extract_subshell_commands("echo $(cat /etc/passwd)")
- self.assertEqual(result, ["cat /etc/passwd"])
- def test_security_bypass_rm_in_subshell(self):
- """Detect rm hidden in subshell - security test."""
- 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
- 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
- result = extract_subshell_commands("cat `rm foo`")
- self.assertEqual(result, ["rm foo"])
- def test_nested_subshell_extraction(self):
- """Nested $() subshells are properly extracted - P1 security fix."""
- # This was a bypass: $(echo $(rm foo)) would only extract "echo $(rm foo"
- # truncated at first ), missing the inner rm command
- result = extract_subshell_commands("echo $(echo $(rm foo))")
- self.assertEqual(result, ["echo $(rm foo)"])
- def test_deeply_nested_subshells(self):
- """Multiple levels of nesting are handled."""
- result = extract_subshell_commands("$(a $(b $(c)))")
- self.assertEqual(result, ["a $(b $(c))"])
- def test_multiple_nested_subshells(self):
- """Multiple nested subshells at same level."""
- result = extract_subshell_commands("$(cmd1 $(inner1)) $(cmd2 $(inner2))")
- self.assertIn("cmd1 $(inner1)", result)
- self.assertIn("cmd2 $(inner2)", result)
- class TestExtractAllCommands(unittest.TestCase):
- """Tests for extract_all_commands() comprehensive extraction."""
- def test_empty_command(self):
- """Empty string returns empty list."""
- self.assertEqual(extract_all_commands(""), [])
- def test_simple_command(self):
- """Simple command without operators or subshells."""
- result = extract_all_commands("ls -la")
- self.assertEqual(result, ["ls -la"])
- def test_chained_commands(self):
- """Commands chained with operators."""
- result = extract_all_commands("cmd1 && cmd2 | cmd3")
- self.assertIn("cmd1", result)
- self.assertIn("cmd2", result)
- self.assertIn("cmd3", result)
- def test_subshell_commands(self):
- """Commands inside subshells are extracted."""
- result = extract_all_commands("echo $(rm foo)")
- self.assertIn("echo $(rm foo)", result) # Top-level command
- self.assertIn("rm foo", result) # Subshell command
- def test_combined_operators_and_subshells(self):
- """Both operators and subshells in same command."""
- result = extract_all_commands("echo $(rm foo) && ls")
- self.assertIn("echo $(rm foo)", result)
- self.assertIn("ls", result)
- self.assertIn("rm foo", result)
- def test_nested_operators_in_subshell(self):
- """Operators inside subshell are also split."""
- result = extract_all_commands("$(cmd1 && cmd2)")
- self.assertIn("cmd1", result)
- self.assertIn("cmd2", result)
- def test_security_pipe_bypass(self):
- """Detect rm after pipe - security regression test."""
- result = extract_all_commands("echo ok | rm -rf /tmp/x")
- self.assertIn("rm -rf /tmp/x", result)
- def test_security_background_bypass(self):
- """Detect rm after background operator - security regression test."""
- result = extract_all_commands("sleep 1 & rm foo")
- self.assertIn("rm foo", result)
- def test_security_subshell_bypass(self):
- """Detect rm hidden in subshell - security regression test."""
- result = extract_all_commands("echo $(rm secret)")
- self.assertIn("rm secret", result)
- def test_quoted_paren_does_not_cut_a_subshell_short(self):
- """A ')' inside quotes is text, so the rm after it is still found."""
- result = extract_all_commands("echo $(printf ')'; rm foo)")
- self.assertIn("rm foo", result)
- def test_quoted_paren_in_a_heredoc_body_substitution(self):
- """Same, for the substitution inside an unquoted heredoc body."""
- result = extract_all_commands("cat <<EOF\n$(printf ')'; rm foo)\nEOF")
- self.assertIn("rm foo", result)
- def test_quoted_heredoc_backticks_are_literal(self):
- """A quoted delimiter means the shell expands nothing in the body."""
- command = "cat > notes.md <<'MD'\nThe `rm -rf x` guard.\nMD"
- result = extract_all_commands(command)
- self.assertNotIn("rm -rf x", result)
- self.assertIn("cat > notes.md <<'MD'", result)
- def test_double_quoted_heredoc_backticks_are_literal(self):
- """A double-quoted delimiter is just as literal as a single-quoted one."""
- command = 'cat > notes.md <<"MD"\nThe `rm -rf x` guard.\nMD'
- self.assertNotIn("rm -rf x", extract_all_commands(command))
- def test_backslash_quoted_heredoc_backticks_are_literal(self):
- """A backslash-escaped delimiter also disables expansion."""
- command = "cat > notes.md <<\\MD\nThe `rm -rf x` guard.\nMD"
- self.assertNotIn("rm -rf x", extract_all_commands(command))
- def test_unquoted_heredoc_substitutions_are_extracted(self):
- """An unquoted delimiter still expands $() and backticks - regression."""
- backticks = "cat > notes.md <<MD\nThe `rm -rf x` guard.\nMD"
- self.assertIn("rm -rf x", extract_all_commands(backticks))
- dollar = "cat > notes.md <<MD\nThe $(rm -rf y) guard.\nMD"
- self.assertIn("rm -rf y", extract_all_commands(dollar))
- def test_unquoted_heredoc_body_text_is_not_a_command(self):
- """Body lines are data even when the delimiter is unquoted."""
- command = "cat > notes.md <<MD\nrm -rf /tmp/x\nMD"
- self.assertNotIn("rm -rf /tmp/x", extract_all_commands(command))
- def test_command_chained_after_heredoc_is_extracted(self):
- """Only the body is blanked, never the line introducing it."""
- command = "cat <<'MD' && rm foo\nliteral text\nMD"
- self.assertIn("rm foo", extract_all_commands(command))
- def test_heredoc_tab_stripped_delimiter(self):
- """<<- indents the closing delimiter with tabs."""
- command = "cat > notes.md <<-'MD'\n\tThe `rm -rf x` guard.\n\tMD"
- self.assertNotIn("rm -rf x", extract_all_commands(command))
- def test_unterminated_heredoc_keeps_current_behavior(self):
- """Without a closing delimiter nothing is treated as a heredoc body."""
- command = "cat > notes.md <<'MD'\nThe `rm -rf x` guard."
- self.assertIn("rm -rf x", extract_all_commands(command))
- def test_herestring_is_not_a_heredoc(self):
- """<<< is a here-string, whose expansions do execute."""
- command = "cat <<< `rm -rf x`"
- self.assertIn("rm -rf x", extract_all_commands(command))
- class TestStripHeredocBodies(unittest.TestCase):
- """Tests for strip_heredoc_bodies() heredoc detection."""
- def test_no_heredoc_is_unchanged(self):
- """Commands without heredocs pass through untouched."""
- self.assertEqual(strip_heredoc_bodies("ls -la"), ("ls -la", []))
- def test_quoted_body_is_blanked_and_not_returned(self):
- """A quoted body is removed from the command and never expanded."""
- command = "cat <<'MD'\nrm -rf x\nMD"
- stripped, bodies = strip_heredoc_bodies(command)
- self.assertEqual(bodies, [])
- self.assertNotIn("rm", stripped)
- self.assertEqual(len(stripped), len(command))
- def test_unquoted_body_is_returned(self):
- """An unquoted body is blanked but returned for expansion scanning."""
- command = "cat <<MD\nrm -rf x\nMD"
- stripped, bodies = strip_heredoc_bodies(command)
- self.assertEqual(bodies, ["rm -rf x\n"])
- self.assertNotIn("rm", stripped)
- def test_heredoc_operator_inside_quotes_is_ignored(self):
- """A '<<' inside a quoted word does not start a heredoc."""
- command = "echo 'a << b'\nrm foo"
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- def test_heredoc_operator_inside_comment_is_ignored(self):
- """A '<<' in a comment must not swallow the lines that follow."""
- command = "# <<END\nrm -rf /tmp/x\nEND"
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- def test_comment_after_subshell_close_is_ignored(self):
- """'(echo x)# <<END' is a comment, so the next lines are commands."""
- command = "(echo x)# <<END\nrm -rf /tmp/x\nEND"
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- def test_hash_inside_word_is_not_a_comment(self):
- """A '#' that is not word-initial does not start a comment."""
- command = "echo a#b <<'MD'\nrm -rf x\nMD"
- stripped, bodies = strip_heredoc_bodies(command)
- self.assertEqual(bodies, [])
- self.assertNotIn("rm", stripped)
- def test_left_shift_in_arithmetic_is_not_a_heredoc(self):
- """'<<' inside $(( )) is a shift operator, not a heredoc."""
- command = "echo $((1 << 2))\nrm -rf /tmp/x\n2"
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- def test_parameter_expansion_is_not_a_heredoc(self):
- """'<<' inside ${...} is expansion text, so it opens no heredoc."""
- command = "echo ${x:-<<EOF}\nrm -rf /tmp/x\nEOF}"
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- def test_nested_parameter_expansion_is_skipped_whole(self):
- """Nested braces inside a parameter expansion are handled."""
- command = "echo ${x:-${y:-<<EOF}}\nrm -rf /tmp/x\nEOF}}"
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- def test_nested_arithmetic_is_skipped_whole(self):
- """Nested parentheses inside arithmetic are handled."""
- command = "echo $(( (1 << 2) + 3 ))\nrm -rf /tmp/x\n3 ))"
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- def test_ansi_c_escape_in_delimiter_is_not_a_heredoc(self):
- """An undecodable ANSI-C delimiter blanks nothing, so guards see all."""
- command = "cat <<$'E\\tOF'\nrm -rf /tmp/x\nE\tOF"
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- def test_escaped_brace_does_not_close_a_parameter_expansion(self):
- """'\\}' is expansion text, so '<<EOF' after it opens no heredoc."""
- command = "echo ${x:-\\}<<EOF}\nrm -rf /tmp/x\nEOF}"
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- def test_quoted_brace_does_not_close_a_parameter_expansion(self):
- """A '}' inside quotes does not end the expansion either."""
- command = "echo ${x:-'}'<<EOF}\nrm -rf /tmp/x\nEOF}"
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- def test_every_heredoc_on_the_line_is_consumed(self):
- """Two heredocs on one header have two bodies, one after the other."""
- command = "cat <<A <<'B'\nfirst\nA\necho <<X\nB\nrm -rf /tmp/x\nX"
- stripped, bodies = strip_heredoc_bodies(command)
- self.assertEqual(bodies, ["first\n"])
- self.assertNotIn("echo <<X", stripped)
- self.assertIn("rm -rf /tmp/x", stripped)
- def test_second_body_of_a_multi_heredoc_line_is_data(self):
- """The second body is data too, so its literal text is not a command."""
- command = "cat <<A <<'B'\nliteral a\nA\nThe `rm -rf x` guard\nB"
- stripped, bodies = strip_heredoc_bodies(command)
- self.assertEqual(bodies, ["literal a\n"])
- self.assertNotIn("rm -rf x", stripped)
- def test_heredoc_after_a_comment_still_has_a_body(self):
- """A trailing comment does not stop the body from starting."""
- command = "cat <<'MD' # note\nrm -rf x\nMD"
- stripped, bodies = strip_heredoc_bodies(command)
- self.assertEqual(bodies, [])
- self.assertNotIn("rm -rf x", stripped)
- def test_escape_in_a_double_quoted_delimiter_is_not_a_heredoc(self):
- """Quote removal would drop a backslash, so decline to blank."""
- command = 'cat <<"A\\\\B"\ndata\nA\\B\nrm -rf /tmp/x\nA\\\\B'
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- def test_escape_in_a_localized_delimiter_is_not_a_heredoc(self):
- """$"..." unescapes just like "..." does, so decline there too."""
- command = 'cat <<$"A\\\\B"\ndata\nA\\B\nrm -rf /tmp/x\nA\\\\B'
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- def test_undecodable_delimiter_stops_the_scan(self):
- """Declining one heredoc must not turn its body into a new header.
- Bash ends the <<$'E\\x4fF' body at EOF and runs the rm after it. The
- body holds "echo <<X", so scanning on would read that as a heredoc
- and blank the rm. Nothing after an undecodable delimiter is blanked.
- """
- command = "cat <<$'E\\x4fF'\necho <<X\nEOF\nrm -rf /tmp/x\nX"
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- def test_case_outside_a_substitution_still_allows_a_heredoc(self):
- """'esac' closes the case, so a later heredoc is found normally."""
- command = "case x in x) echo yes;; esac\ncat <<'EOF'\nrm -rf /tmp/x\nEOF"
- stripped, bodies = strip_heredoc_bodies(command)
- self.assertEqual(bodies, [])
- self.assertNotIn("rm -rf /tmp/x", stripped)
- def test_herestring_operator_is_stepped_over_whole(self):
- """The trailing '<<' of '<<<' must not be read as a heredoc."""
- command = "cat <<<input\nrm -rf /tmp/x\ninput"
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- def test_legacy_arithmetic_shift_is_not_a_heredoc(self):
- """$[1 << 2] is the deprecated arithmetic form, so '<<' is a shift."""
- command = "echo $[1 << 2]\nrm -rf /tmp/x\n2]"
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- def test_array_subscript_shift_is_not_a_heredoc(self):
- """'<<' in "a[1<<2]=foo" is a shift: the subscript is arithmetic."""
- command = "a[1<<2]=foo\nrm -rf /tmp/x\n2]=foo"
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- def test_output_process_substitution_delays_the_body(self):
- """>( ) is a parsing unit of its own just as <( ) is."""
- command = "cat <<EOF >(cat\nrm -rf /tmp/x\n)\nliteral\nEOF"
- stripped, _ = strip_heredoc_bodies(command)
- self.assertIn("rm -rf /tmp/x", stripped)
- def test_delimiter_split_over_a_continued_line(self):
- """An unquoted body loses backslash-newline, so 'EO\\'+'F' ends it."""
- command = "cat <<EOF\ndata\nEO\\\nF\nrm -rf /tmp/x\nEOF"
- stripped, bodies = strip_heredoc_bodies(command)
- self.assertEqual(bodies, ["data\n"])
- self.assertIn("rm -rf /tmp/x", stripped)
- def test_quoted_body_keeps_a_continued_delimiter_literal(self):
- """With a quoted delimiter nothing is unescaped, so it does not end."""
- command = "cat <<'EOF'\ndata\nEO\\\nF\nrm -rf /tmp/x\nEOF"
- stripped, bodies = strip_heredoc_bodies(command)
- self.assertEqual(bodies, [])
- self.assertNotIn("rm -rf /tmp/x", stripped)
- def test_substitution_closing_first_leaves_the_heredoc_bodyless(self):
- """Bash reads that body inside the substitution, so there is none."""
- command = "echo $(cat <<'EOF') tail\nrm -rf /tmp/x\nEOF"
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- def test_backticks_closing_first_leave_the_heredoc_bodyless(self):
- """A closed backtick span drops its heredoc, like ')' does.
- Bash runs the rm here: the first span closes before any newline,
- so its heredoc has no body, and the second span is code.
- """
- command = "echo `cat <<IN ` ; echo `\nrm -rf /tmp/x\nIN\n`"
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- self.assertIn("rm -rf /tmp/x", extract_all_commands(command))
- def test_case_as_an_argument_is_not_the_keyword(self):
- """Only a 'case' in command position opens a case statement.
- Bash runs the rm: 'echo case' is an argument, so both ')' close
- their substitutions and the OUT body's '<<X' is literal.
- """
- command = ("cat <<OUT $(echo case; echo $(echo hi)\n)\n"
- "echo <<X\nOUT\nrm -rf /tmp/x\nX")
- self.assertIn("rm -rf /tmp/x", extract_all_commands(command))
- def test_bracket_after_an_argument_is_not_a_subscript(self):
- """'echo a[<<EOF]' is the argument 'a[' plus a heredoc to 'EOF]'.
- Bash runs the rm: the body ends at 'EOF]', and the '<<X' inside
- it is literal, not a second heredoc.
- """
- command = "echo a[<<EOF]\necho <<X\nEOF]\nrm -rf /tmp/x\nX"
- self.assertIn("rm -rf /tmp/x", extract_all_commands(command))
- def test_assignment_subscript_shift_is_still_not_a_heredoc(self):
- """The subscript rule still covers the real assignment form."""
- command = "a[1<<2]=foo\nrm -rf /tmp/x"
- self.assertIn("rm -rf /tmp/x", extract_all_commands(command))
- def test_unterminated_second_body_blanks_nothing(self):
- """If any body is unclosed, no body is treated as data."""
- command = "cat <<A <<B\nfirst\nA\nrm -rf /tmp/x"
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- # Every construct below has, at some point, let the scanner place a
- # body boundary where bash does not, so that a real command was
- # blanked as data. The policy is therefore to blank nothing when the
- # header line carries any of them: the guards then see the whole
- # command, which can only over-block.
- COMPLEX_HEADERS = {
- "ansi-c delimiter": "cat <<$'EOF'\nliteral\nEOF\nrm -rf /tmp/x\n$EOF",
- "ansi-c string on the line": "echo $'don\\'t' <<'MD'\nrm -rf x\nMD",
- "backticks in the delimiter": "cat <<`echo EOF`\npayload\n`echo EOF`",
- "glob bracket on the line": "ls [ab]* ; cat <<EOF\nrm -rf /tmp/x\nEOF",
- "case pattern in a substitution": (
- "cat <<EOF $(case x in x) echo yes;; esac\nrm -rf /tmp/x\n)\n"
- "literal\nEOF"),
- "delimiter split by a continuation": (
- "cat <<E\\\nOF\necho <<X\nEOF\nrm -rf /tmp/x\nX"),
- "nested heredocs": (
- "cat <<OUT $(cat <<IN\n)\nIN\nrm -rf /tmp/x\n)\nouter\nOUT"),
- "heredoc inside a substitution": (
- "echo $(cat <<'EOF'\nrm -rf /tmp/x\nEOF\n)"),
- "continuation after the header": (
- "cat <<EOF ; \\\nrm -rf /tmp/x\nliteral\nEOF"),
- "group inside a substitution": (
- "cat <<EOF $( (echo x)\nrm -rf /tmp/x\n)\nliteral\nEOF"),
- "newline inside a substitution": (
- "cat <<'EOF' $(echo start\nrm -rf /tmp/x)\nliteral\nEOF"),
- "newline inside backticks": (
- "cat <<'EOF' `echo start\nrm -rf /tmp/x`\nliteral\nEOF"),
- "expansion as the delimiter": "cat <<${x}\npayload\n${x}\nrm -rf /tmp/x",
- "paren case pattern": (
- "cat <<EOF $(case x in (x) echo yes;; esac\nrm -rf /tmp/x\n)\n"
- "literal\nEOF"),
- "process substitution": (
- "cat <<EOF <(echo x\nrm -rf /tmp/x\n)\nliteral\nEOF"),
- "subshell group": "(cat <<'EOF'\nrm -rf /tmp/x\nEOF\n)",
- "substitution as the delimiter": (
- "cat <<$(echo EOF)\npayload\n$(echo EOF)\nrm -rf /tmp/x"),
- "parameter expansion with default": (
- "echo ${x:-<<EOF}\nrm -rf /tmp/x\nEOF}"),
- "array assignment on the line": "a[1<<2]=foo\nrm -rf /tmp/x",
- "substitution in an unquoted body": (
- "cat <<EOF\n$(case x in x) echo yes;; esac; rm -rf /tmp/x)\nEOF"),
- "backticks in an unquoted body": "cat <<EOF\n`rm -rf /tmp/x`\nEOF",
- "prompt expansion in an unquoted body": (
- "x='$''(rm -rf /tmp/x)'; cat <<EOF\n${x@P}\nEOF"),
- }
- def test_complex_headers_are_never_blanked(self):
- """A header line with any complex construct disables blanking."""
- for name, command in self.COMPLEX_HEADERS.items():
- with self.subTest(name):
- self.assertEqual(strip_heredoc_bodies(command), (command, []))
- # Strings reviewers used to blank a real rm. Each is accepted by bash
- # and runs the rm; each must reach the guards.
- KNOWN_BYPASSES = [
- "echo ${x:-<<EOF}\nrm -rf /tmp/x\nEOF}",
- "echo ${x:-\\}<<EOF}\nrm -rf /tmp/x\nEOF}",
- "cat <<A <<'B'\nfirst\nA\necho <<X\nB\nrm -rf /tmp/x\nX",
- "cat <<$'EOF'\nliteral\nEOF\nrm -rf /tmp/x\n$EOF",
- "cat <<EOF ; \\\nrm -rf /tmp/x\nliteral\nEOF",
- "cat <<E\\\nOF\necho <<X\nEOF\nrm -rf /tmp/x\nX",
- "cat <<EOF $( (echo x)\nrm -rf /tmp/x\n)\nliteral\nEOF",
- "cat <<EOF <(echo x\nrm -rf /tmp/x\n)\nliteral\nEOF",
- "cat <<OUT $(cat <<IN\n)\nIN\nrm -rf /tmp/x\n)\nouter\nOUT",
- "echo `cat <<IN ` ; echo `\nrm -rf /tmp/x\nIN\n`",
- "cat <<OUT $(echo case; echo $(echo hi)\n)\necho <<X\nOUT\n"
- "rm -rf /tmp/x\nX",
- "echo a[<<EOF]\necho <<X\nEOF]\nrm -rf /tmp/x\nX",
- "cat <<OUT $(if true; then case x in x) :;; esac; fi\n"
- "rm -rf /tmp/x\n)\npayload\nOUT",
- "echo a[<<EOF]=x\necho <<X\nEOF]=x\nrm -rf /tmp/x\nX",
- "cat <<EOF\n$(case x in x) echo yes;; esac; rm -rf /tmp/x)\nEOF",
- "cat <<\"A\\\\B\"\nA\\B\nrm -rf /tmp/x\nA\\\\B",
- ]
- # Not listed above: "x='$''(rm -rf /tmp/x)'; cat <<EOF\n${x@P}\nEOF".
- # The scanner leaves that body unblanked (see COMPLEX_HEADERS), but
- # the rm is then inside a quoted assignment, which no guard inspects:
- # commands built at run time ("eval", "${x@P}") are outside what the
- # guards claim to catch, with or without a heredoc.
- def test_known_bypasses_reach_the_guards(self):
- """No reviewer-found bypass hides the rm from extract_all_commands."""
- for command in self.KNOWN_BYPASSES:
- with self.subTest(command):
- found = [c for c in extract_all_commands(command)
- if c.strip().startswith("rm ")]
- self.assertTrue(found, command)
- def test_plain_variable_on_the_header_still_blanks(self):
- """'cat > $HOME/x.md <<EOF' is the common case and must work."""
- command = "cat > $HOME/notes.md <<'EOF'\nrm -rf x is bad\nEOF"
- stripped, bodies = strip_heredoc_bodies(command)
- self.assertEqual(bodies, [])
- self.assertNotIn("rm -rf", stripped)
- command = "cat > ${DIR}/notes.md <<EOF\nrm -rf x is bad\nEOF"
- stripped, bodies = strip_heredoc_bodies(command)
- self.assertEqual(bodies, ["rm -rf x is bad\n"])
- self.assertNotIn("rm -rf", stripped)
- def test_backslash_quoted_plain_delimiter_still_blanks(self):
- """<<\\EOF is one of the three simple quotings and stays supported."""
- command = "cat <<\\EOF\n`rm x`\nEOF"
- stripped, bodies = strip_heredoc_bodies(command)
- self.assertEqual(bodies, [])
- self.assertNotIn("rm x", stripped)
- class TestExpandCommandAliases(unittest.TestCase):
- """Tests for expand_command_aliases() with updated operator support."""
- def test_empty_command(self):
- """Empty command returns empty string."""
- self.assertEqual(expand_command_aliases(""), "")
- def test_single_command_no_alias(self):
- """Single command without alias passes through."""
- # Commands like 'git' are skipped for alias expansion
- result = expand_command_aliases("git status")
- self.assertEqual(result, "git status")
- def test_preserves_pipe_operator(self):
- """Pipe operator is preserved in output."""
- result = expand_command_aliases("git log | grep fix")
- self.assertIn("|", result)
- def test_preserves_background_operator(self):
- """Background operator is preserved in output."""
- result = expand_command_aliases("git fetch & git status")
- self.assertIn("&", result)
- def test_preserves_all_operators(self):
- """All operators are preserved."""
- cmd = "cmd1 && cmd2 || cmd3; cmd4 | cmd5 & cmd6"
- result = expand_command_aliases(cmd)
- self.assertIn("&&", result)
- self.assertIn("||", result)
- self.assertIn(";", result)
- self.assertIn("|", result)
- self.assertIn("&", result)
- if __name__ == "__main__":
- unittest.main()
plugins/safety-hooks/hooks/test_rm_block_hook.py · Bundled script · 371 lines · 3 findings marked
- #!/usr/bin/env python3
- """
- Unit tests for rm_block_hook.py
- Tests cover:
- - Direct rm command blocking
- - rm with absolute paths (/bin/rm, /usr/bin/rm)
- - rm chained with shell operators (&&, ||, ;, |, &)
- - rm hidden in subshells ($() and backticks)
- - Safe commands that should pass through
- """
- import unittest
- import sys
- import os
- # Add the hooks directory to path for imports
- sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
- from rm_block_hook import check_rm_command, _is_rm_command
- class TestIsRmCommand(unittest.TestCase):
- """Tests for _is_rm_command() single command detection."""
- def test_bare_rm(self):
- """Bare 'rm' command is detected."""
- self.assertTrue(_is_rm_command("rm"))
- def test_rm_with_args(self):
- """rm with arguments is detected."""
- self.assertTrue(_is_rm_command("rm foo.txt"))
- self.assertTrue(_is_rm_command("rm -rf /tmp/test"))
- self.assertTrue(_is_rm_command("rm -f file1 file2"))
- def test_rm_with_path(self):
- """rm with absolute path is detected."""
- self.assertTrue(_is_rm_command("/bin/rm foo"))
- 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
- def test_not_rm_commands(self):
- """Commands that are not rm should not be detected."""
- self.assertFalse(_is_rm_command("ls"))
- self.assertFalse(_is_rm_command("echo rm"))
- self.assertFalse(_is_rm_command("grep rm file"))
- self.assertFalse(_is_rm_command("firmware")) # Contains 'rm' but not rm command
- self.assertFalse(_is_rm_command(""))
- def test_whitespace_handling(self):
- """Whitespace is normalized."""
- self.assertTrue(_is_rm_command(" rm foo "))
- self.assertTrue(_is_rm_command("\trm\t-rf\t/"))
- class TestCheckRmCommand(unittest.TestCase):
- """Tests for check_rm_command() comprehensive detection."""
- def test_direct_rm_blocked(self):
- """Direct rm commands are blocked."""
- blocked, reason = check_rm_command("rm foo.txt")
- self.assertTrue(blocked)
- self.assertIsNotNone(reason)
- def test_rm_with_path_blocked(self):
- """rm with absolute path is blocked."""
- blocked, _ = check_rm_command("/bin/rm foo")
- self.assertTrue(blocked)
- 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
- self.assertTrue(blocked)
- def test_safe_commands_pass(self):
- """Safe commands are not blocked."""
- blocked, reason = check_rm_command("ls -la")
- self.assertFalse(blocked)
- self.assertIsNone(reason)
- blocked, _ = check_rm_command("git status")
- self.assertFalse(blocked)
- blocked, _ = check_rm_command("echo hello")
- self.assertFalse(blocked)
- # Security bypass tests - these are the key regression tests
- def test_pipe_bypass_blocked(self):
- """rm after pipe operator is blocked - security regression test."""
- blocked, _ = check_rm_command("echo ok | rm foo")
- self.assertTrue(blocked, "rm after pipe should be blocked")
- blocked, _ = check_rm_command("cat file | rm -rf /tmp")
- self.assertTrue(blocked, "rm in pipe chain should be blocked")
- def test_background_bypass_blocked(self):
- """rm after background operator is blocked - security regression test."""
- blocked, _ = check_rm_command("sleep 1 & rm foo")
- self.assertTrue(blocked, "rm after background operator should be blocked")
- blocked, _ = check_rm_command("cmd & /bin/rm bar")
- self.assertTrue(blocked, "rm with path after & should be blocked")
- def test_and_operator_blocked(self):
- """rm after && operator is blocked."""
- blocked, _ = check_rm_command("cd /tmp && rm foo")
- self.assertTrue(blocked)
- def test_or_operator_blocked(self):
- """rm after || operator is blocked."""
- blocked, _ = check_rm_command("test -f x || rm y")
- self.assertTrue(blocked)
- def test_semicolon_operator_blocked(self):
- """rm after ; operator is blocked."""
- blocked, _ = check_rm_command("echo done; rm foo")
- self.assertTrue(blocked)
- def test_subshell_dollar_paren_blocked(self):
- """rm inside $() subshell is blocked - security regression test."""
- blocked, _ = check_rm_command("echo $(rm foo)")
- self.assertTrue(blocked, "rm in $() subshell should be blocked")
- 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
- self.assertTrue(blocked, "bare $() with rm should be blocked")
- def test_subshell_backtick_blocked(self):
- """rm inside backtick subshell is blocked - security regression test."""
- blocked, _ = check_rm_command("echo `rm foo`")
- self.assertTrue(blocked, "rm in backticks should be blocked")
- blocked, _ = check_rm_command("cat `rm bar`")
- self.assertTrue(blocked, "rm in backticks should be blocked")
- def test_quoted_heredoc_documenting_rm_is_allowed(self):
- """Writing a doc that mentions rm in a code span is not deletion.
- Regression test for issue #187: a single-quoted heredoc delimiter
- disables every expansion, so the backticks in the body are literal.
- """
- command = "cat > notes.md <<'MD'\nThe `rm` guard blocks deletions.\nMD"
- blocked, _ = check_rm_command(command)
- self.assertFalse(blocked, "literal rm in a quoted heredoc is data")
- def test_unquoted_heredoc_substitution_still_blocked(self):
- """An unquoted delimiter really does run the substitution."""
- command = "cat > notes.md <<MD\nThe `rm -rf x` guard.\nMD"
- blocked, _ = check_rm_command(command)
- self.assertTrue(blocked, "rm in an unquoted heredoc should be blocked")
- def test_rm_chained_after_heredoc_still_blocked(self):
- """Blanking the body must not hide the command that opens it."""
- blocked, _ = check_rm_command("cat <<'MD' && rm foo\nliteral\nMD")
- self.assertTrue(blocked, "rm after a heredoc redirect should be blocked")
- def test_comment_cannot_fake_a_heredoc(self):
- """A '<<' in a comment must not blank out a following rm."""
- blocked, _ = check_rm_command("# <<END\ntrue; rm -rf /tmp/x\nEND")
- self.assertTrue(blocked, "rm after a commented '<<' should be blocked")
- def test_comment_after_subshell_cannot_fake_a_heredoc(self):
- """A comment right after ')' must not blank out a following rm."""
- blocked, _ = check_rm_command("(echo x)# <<END\ntrue; rm -rf /tmp/x\nEND")
- self.assertTrue(blocked, "rm after '(...)# <<' should be blocked")
- def test_parameter_expansion_cannot_fake_a_heredoc(self):
- """'<<' in ${x:-<<EOF} must not blank out a following rm."""
- blocked, _ = check_rm_command("echo ${x:-<<EOF}\ntrue; rm -rf /tmp/x\nEOF}")
- self.assertTrue(blocked, "rm after '${x:-<<EOF}' should be blocked")
- def test_arithmetic_shift_cannot_fake_a_heredoc(self):
- """A left shift in $(( )) must not blank out a following rm."""
- blocked, _ = check_rm_command("echo $((1 << 2))\ntrue; rm -rf /tmp/x\n2")
- self.assertTrue(blocked, "rm after an arithmetic shift should be blocked")
- def test_newline_separated_rm_is_blocked(self):
- """A newline ends a command, so the next line is a command too."""
- blocked, _ = check_rm_command("echo hi\nrm -rf /tmp/x")
- self.assertTrue(blocked, "rm on its own line should be blocked")
- def test_ansi_c_delimiter_cannot_fake_a_heredoc(self):
- """<<$'EOF' ends at EOF, so a later rm is not inside the body."""
- command = "cat <<$'EOF'\nliteral\nEOF\nrm -rf /tmp/x\n$EOF"
- blocked, _ = check_rm_command(command)
- self.assertTrue(blocked, "rm after a $'EOF' heredoc should be blocked")
- def test_escaped_brace_cannot_fake_a_heredoc(self):
- """'\\}' does not close ${...}, so '<<EOF' in it opens no heredoc."""
- blocked, _ = check_rm_command(
- "echo ${x:-\\}<<EOF}\nrm -rf /tmp/x\nEOF}")
- self.assertTrue(blocked, "rm after '${x:-\\}<<EOF}' should be blocked")
- def test_line_continuation_cannot_hide_rm_in_a_body(self):
- """A continued header means the rm runs before the body starts."""
- command = "cat <<EOF ; \\\nrm -rf /tmp/x\nliteral\nEOF"
- blocked, _ = check_rm_command(command)
- self.assertTrue(blocked, "rm on a continued header should be blocked")
- def test_second_heredoc_body_cannot_hide_rm(self):
- """Both bodies on a two-heredoc header are data, so the rm is not."""
- command = "cat <<A <<'B'\nfirst\nA\necho <<X\nB\nrm -rf /tmp/x\nX"
- blocked, _ = check_rm_command(command)
- self.assertTrue(blocked, "rm after two heredoc bodies should be blocked")
- def test_documenting_rm_in_a_second_heredoc_body_is_allowed(self):
- """The second body is data, so documenting rm in it is not deletion."""
- command = "cat <<A <<'B'\nliteral a\nA\nThe `rm -rf x` guard\nB"
- blocked, _ = check_rm_command(command)
- self.assertFalse(blocked, "literal rm in the second body is data")
- def test_continued_delimiter_word_cannot_hide_rm(self):
- """"E\\"+"OF" is the delimiter EOF, so the rm after that body runs."""
- command = "cat <<E\\\nOF\necho <<X\nEOF\nrm -rf /tmp/x\nX"
- blocked, _ = check_rm_command(command)
- self.assertTrue(blocked, "rm after a continued delimiter word blocks")
- def test_nested_heredoc_in_a_substitution_cannot_hide_rm(self):
- """The inner heredoc ends inside $( ), leaving the rm a command."""
- command = "cat <<OUT $(cat <<IN\n)\nIN\nrm -rf /tmp/x\n)\nouter\nOUT"
- blocked, _ = check_rm_command(command)
- self.assertTrue(blocked, "rm inside the substitution should be blocked")
- def test_undecodable_delimiter_cannot_hide_rm(self):
- """Bash ends that body at EOF, so the rm after it is a command."""
- command = "cat <<$'E\\x4fF'\necho <<X\nEOF\nrm -rf /tmp/x\nX"
- blocked, _ = check_rm_command(command)
- self.assertTrue(blocked, "rm after an escaped delimiter's body blocks")
- def test_case_pattern_paren_cannot_hide_rm(self):
- """The substitution stays open past a case pattern's ')'."""
- command = ("cat <<EOF $(case x in x) echo yes;; esac\n"
- "rm -rf /tmp/x\n)\nliteral\nEOF")
- blocked, _ = check_rm_command(command)
- self.assertTrue(blocked, "rm inside a still-open $( ) should be blocked")
- def test_herestring_cannot_fake_a_heredoc(self):
- """'cat <<<input' opens no heredoc, so the next line is a command."""
- blocked, _ = check_rm_command("cat <<<input\nrm -rf /tmp/x\ninput")
- self.assertTrue(blocked, "rm after a here-string should be blocked")
- def test_legacy_arithmetic_shift_cannot_fake_a_heredoc(self):
- """A shift in the deprecated $[ ] form must not blank a following rm."""
- blocked, _ = check_rm_command("echo $[1 << 2]\nrm -rf /tmp/x\n2]")
- self.assertTrue(blocked, "rm after 'echo $[1 << 2]' should be blocked")
- def test_array_subscript_shift_cannot_fake_a_heredoc(self):
- """A shift inside an array subscript must not blank a following rm."""
- blocked, _ = check_rm_command("a[1<<2]=foo\nrm -rf /tmp/x\n2]=foo")
- self.assertTrue(blocked, "rm after 'a[1<<2]=foo' should be blocked")
- def test_process_substitution_cannot_hide_rm(self):
- """The rm runs inside <( ), before the heredoc body starts."""
- command = "cat <<EOF <(echo x\nrm -rf /tmp/x\n)\nliteral\nEOF"
- blocked, _ = check_rm_command(command)
- self.assertTrue(blocked, "rm inside <( ) on the header is a command")
- def test_localized_quote_delimiter_cannot_hide_rm(self):
- """$\"A\\\\B\" unescapes, so bash ends that body before the rm."""
- command = 'cat <<$"A\\\\B"\ndata\nA\\B\nrm -rf /tmp/x\nA\\\\B'
- blocked, _ = check_rm_command(command)
- self.assertTrue(blocked, "rm after a '$\"A\\\\B\"' body should be blocked")
- def test_double_quoted_escape_delimiter_cannot_hide_rm(self):
- """Bash ends that body at 'A\\B', so the next line is a command."""
- command = 'cat <<"A\\\\B"\ndata\nA\\B\nrm -rf /tmp/x\nA\\\\B'
- blocked, _ = check_rm_command(command)
- self.assertTrue(blocked, "rm after a '\"A\\\\B\"' body should be blocked")
- def test_continued_delimiter_line_cannot_hide_rm(self):
- """An unquoted body ends at a delimiter split across two lines."""
- command = "cat <<EOF\ndata\nEO\\\nF\nrm -rf /tmp/x\nEOF"
- blocked, _ = check_rm_command(command)
- self.assertTrue(blocked, "rm after a continued delimiter is a command")
- def test_nested_group_paren_cannot_hide_rm(self):
- """The substitution is still open, so the rm inside it is a command."""
- command = "cat <<EOF $( (echo x)\nrm -rf /tmp/x\n)\nliteral\nEOF"
- blocked, _ = check_rm_command(command)
- self.assertTrue(blocked, "rm inside a still-open $( ) should be blocked")
- def test_substitution_delimiter_cannot_fake_a_heredoc(self):
- """'<<$(echo EOF)' ends at that literal line, so the rm is a command."""
- command = "cat <<$(echo EOF)\npayload\n$(echo EOF)\nrm -rf /tmp/x\n$"
- blocked, _ = check_rm_command(command)
- self.assertTrue(blocked, "rm after a '$(echo EOF)' body should be blocked")
- def test_rm_in_a_substitution_before_the_body_is_blocked(self):
- """An unfinished $( ) means the rm runs before the body starts."""
- command = "cat <<'EOF' $(echo start\nrm -rf /tmp/x)\nliteral\nEOF"
- blocked, _ = check_rm_command(command)
- self.assertTrue(blocked, "rm inside $( ) on the header is a command")
- def test_rm_in_backticks_before_the_body_is_blocked(self):
- """Backticks hold the header open just as $( ) does."""
- command = "cat <<'EOF' `echo start\nrm -rf /tmp/x`\nliteral\nEOF"
- blocked, _ = check_rm_command(command)
- self.assertTrue(blocked, "rm inside backticks on the header is a command")
- def test_bodyless_heredoc_in_a_substitution_cannot_hide_rm(self):
- """The substitution closes first, so the next line is a command."""
- command = "echo $(cat <<'EOF') tail\nrm -rf /tmp/x\nEOF"
- blocked, _ = check_rm_command(command)
- self.assertTrue(blocked, "rm is not a body when the body never starts")
- def test_documenting_rm_inside_a_substitution_heredoc_over_blocks(self):
- """A heredoc inside $( ) is not blanked, so this over-blocks.
- That is the chosen failure direction: substitutions on the header
- line are where every known bypass lived.
- """
- command = "echo $(cat <<'EOF'\nThe `rm -rf x` guard.\nEOF\n)"
- blocked, _ = check_rm_command(command)
- self.assertTrue(blocked, "complex header: body is not blanked")
- def test_complex_bypass_attempts(self):
- """Complex commands attempting to hide rm are blocked."""
- # Multiple levels of indirection
- blocked, _ = check_rm_command("echo safe | cat | rm evil")
- self.assertTrue(blocked, "rm at end of pipe chain should be blocked")
- # Subshell inside chained command
- blocked, _ = check_rm_command("echo $(rm foo) && ls")
- self.assertTrue(blocked, "rm in subshell with && should be blocked")
- # Background with subshell
- blocked, _ = check_rm_command("$(rm x) & echo done")
- self.assertTrue(blocked, "rm in subshell with & should be blocked")
- def test_nested_subshell_bypass_blocked(self):
- """rm hidden in nested $() subshells is blocked - P1 security fix."""
- # This was a bypass: the regex stopped at first ), missing inner rm
- blocked, _ = check_rm_command("echo $(echo $(rm foo))")
- self.assertTrue(blocked, "rm in nested subshell should be blocked")
- # Deeper nesting
- blocked, _ = check_rm_command("$(cat $(ls $(rm secret)))")
- self.assertTrue(blocked, "rm in deeply nested subshell should be blocked")
- def test_reason_message_content(self):
- """Blocked commands include helpful guidance in reason."""
- blocked, reason = check_rm_command("rm foo")
- self.assertTrue(blocked)
- self.assertIn("TRASH", reason)
- self.assertIn("mv", reason)
- self.assertIn("TRASH-FILES.md", reason)
- class TestEdgeCases(unittest.TestCase):
- """Edge case tests for robustness."""
- def test_empty_command(self):
- """Empty command is not blocked."""
- blocked, _ = check_rm_command("")
- self.assertFalse(blocked)
- def test_whitespace_only(self):
- """Whitespace-only command is not blocked."""
- blocked, _ = check_rm_command(" ")
- self.assertFalse(blocked)
- def test_rm_in_string_not_blocked(self):
- """String containing 'rm' but not as command passes."""
- # 'rm' as part of echo string
- blocked, _ = check_rm_command("echo 'do not rm this'")
- self.assertFalse(blocked, "rm in quoted string should not be blocked")
- def test_command_starting_with_rm_prefix(self):
- """Commands starting with 'rm' prefix but not rm command."""
- blocked, _ = check_rm_command("rmdir empty_dir")
- self.assertFalse(blocked, "rmdir should not be blocked")
- if __name__ == "__main__":
- unittest.main()
plugins/writing/skills/remove-ai-patterns/upstream/detector/patterns.js · Bundled script · 1,892 lines
- /**
- * Avoid AI Writing — detection engine (canonical source of truth)
- * Implements 45-category pattern detection. This repo's SKILL.md
- * catalogs the human-editable pattern rules; this engine is the executable
- * expression of the regex-detectable subset and extends it with stylometric and
- * AI-tool-fingerprint detectors that don't make sense as skill prose
- * (cross-paragraph burstiness, smart-punct signatures, function-word
- * trigram entropy, low type-token ratio, AI-tool URL parameters,
- * chatbot citation markup leaks, unfilled placeholders).
- *
- * Scoring model:
- * Each category has a weight in the ISSUE_WEIGHTS table. Detection runs
- * produce raw (possibly duplicate) issues which are then deduplicated by
- * (type, text) pair. rawScore is the sum of category weights across the
- * deduped list — so the number reflects the same distinct signals the
- * user sees in the issue list.
- *
- * Weights are deliberately non-flat across severity tags. Cutoff
- * disclaimers (10) and chatbot artifacts (8) weigh more than vague
- * attributions (5), even though all three are tagged `critical`, because
- * the skill treats them as stronger or weaker AI-origin signals.
- *
- * rawScore is then normalized to 0-100 via `log2(wordCount/50)` so longer
- * texts don't accumulate unboundedly on the same density of patterns.
- */
- const AIDetector = (() => {
- // ═══ Tier 1 pre-pass: normalize bypass tricks ══════════════════════
- //
- // Humanizer tools and prompt-injection bypass techniques insert
- // invisible / lookalike chars to defeat exact-string detectors. Strip
- // them BEFORE pattern matching so "delve" with a Cyrillic 'е' still
- // hits the Tier 1 list. Unicode ranges sourced from
- // It-s-AI/llm-detection/detection/attacks/.
- //
- // Tracks what was stripped so the trinary classifier can use
- // "normalization triggered" as a corroborating AI signal — humans don't
- // paste ZWSPs into their own writing.
- const CYRILLIC_LOOKALIKES = {
- 'а': 'a', 'е': 'e', 'о': 'o', 'р': 'p', 'с': 'c', 'х': 'x',
- 'у': 'y', 'к': 'k', 'м': 'm', 'н': 'h', 'в': 'b', 'т': 't',
- 'А': 'A', 'Е': 'E', 'О': 'O', 'Р': 'P', 'С': 'C', 'Х': 'X',
- 'У': 'Y', 'К': 'K', 'М': 'M', 'Н': 'H', 'В': 'B', 'Т': 'T',
- };
- const GREEK_LOOKALIKES = { 'ο': 'o', 'Ο': 'O', 'α': 'a', 'Α': 'A', 'ρ': 'p', 'Ρ': 'P' };
- function normalizeText(text) {
- const flags = { zeroWidth: 0, homoglyph: 0, roleplay: 0 };
- let out = text;
- // 1. Strip zero-width chars (ZWSP U+200B, ZWNJ U+200C, ZWJ U+200D,
- // BOM U+FEFF, word joiner U+2060).
- out = out.replace(/[-]/g, () => { flags.zeroWidth++; return ''; });
- // 2. Swap Cyrillic / Greek Latin-lookalike chars back to Latin so
- // pattern matching catches obfuscated tokens.
- out = out.replace(/[Ѐ-ӿͰ-Ͽ]/g, (m) => {
- const swap = CYRILLIC_LOOKALIKES[m] ?? GREEK_LOOKALIKES[m];
- if (swap) { flags.homoglyph++; return swap; }
- return m;
- });
- // 3. Strip *roleplay-action* markers — paired *...* containing an
- // action verb (nods, sighs, laughs, smiles, etc.) anchored to
- // the start of the inner phrase. This is the actual chat-model
- // artifact shape. Markdown `**bold**` is rejected by the
- // lookbehind/lookahead; legitimate multi-word `*italic*` is
- // preserved because the verb whitelist is narrow.
- 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;
- out = out.replace(/(?<!\*)\*([^*\n]{1,80}?)\*(?!\*)/gu, (m, inner) => {
- if (ROLEPLAY_VERBS.test(inner)) { flags.roleplay++; return ''; }
- return m;
- });
- return { text: out, flags };
- }
- // ─── Tier 1: Always flag ───────────────────────────────────────────
- const TIER1 = {
- 'delve': 'explore, dig into, look at',
- 'tapestry': 'describe the actual complexity',
- 'paradigm': 'model, approach, framework',
- 'beacon': 'rewrite entirely',
- 'robust': 'strong, reliable, solid',
- 'comprehensive': 'thorough, complete, full',
- 'cutting-edge': 'latest, newest, advanced',
- 'pivotal': 'important, key, critical',
- 'meticulous': 'careful, detailed, precise',
- 'meticulously': 'carefully, precisely',
- 'seamless': 'smooth, easy, without friction',
- 'seamlessly': 'smoothly, easily',
- 'game-changer': 'describe what changed',
- 'game-changing': 'describe what changed',
- 'nestled': 'is located, sits',
- 'vibrant': 'describe what makes it active',
- 'thriving': 'growing, active',
- 'bustling': 'busy, active',
- 'intricate': 'complex, detailed',
- 'intricacies': 'complexities, details',
- 'ever-evolving': 'changing, growing',
- 'enduring': 'lasting, long-running',
- 'daunting': 'hard, difficult',
- 'holistic': 'complete, full, whole',
- 'holistically': 'completely, fully',
- 'actionable': 'practical, useful, concrete',
- 'impactful': 'effective, significant',
- 'learnings': 'lessons, findings, takeaways',
- 'synergy': 'describe the combined effect',
- 'synergies': 'describe the combined effect',
- 'interplay': 'relationship, connection',
- 'symphony': 'describe the coordination',
- 'embrace': 'adopt, accept, use',
- };
- // Multi-word tier 1 phrases
- const TIER1_PHRASES = [
- { pattern: /\bdelve\s+into\b/gi, replace: 'explore, dig into' },
- { pattern: /\blandscape\b/gi, replace: 'field, space, industry', filter: true },
- { pattern: /\brealm\b/gi, replace: 'area, field, domain' },
- { pattern: /\btestament\s+to\b/gi, replace: 'shows, proves' },
- { pattern: /\bleverag(?:e|es|ing|ed)\b/gi, replace: 'use' },
- { pattern: /\bwatershed\s+moment\b/gi, replace: 'turning point, shift' },
- { pattern: /\bmarking\s+a\s+pivotal\s+moment\b/gi, replace: 'state what happened' },
- { pattern: /\bthe\s+future\s+looks\s+bright\b/gi, replace: 'cut or say something specific' },
- { pattern: /\bonly\s+time\s+will\s+tell\b/gi, replace: 'cut or say something specific' },
- { pattern: /\bdespite\s+challenges[^.]*continues?\s+to\s+thrive\b/gi, replace: 'name the challenge and response' },
- { pattern: /\bdeep\s+dive\b/gi, replace: 'look at, examine' },
- { pattern: /\bdive\s+into\b/gi, replace: 'look at, examine' },
- { pattern: /\bunpack(?:ing)?\b/gi, replace: 'explain, break down' },
- { pattern: /\bcomplexities\b/gi, replace: 'name the actual problems' },
- { pattern: /\bthought\s+leader(?:ship)?\b/gi, replace: 'expert, authority' },
- { pattern: /\bbest\s+practices\b/gi, replace: 'what works, proven methods' },
- { pattern: /\bat\s+its\s+core\b/gi, replace: 'cut, just state it' },
- { pattern: /\bin\s+order\s+to\b/gi, replace: 'to', clarity: true },
- { pattern: /\bdue\s+to\s+the\s+fact\s+that\b/gi, replace: 'because', clarity: true },
- { pattern: /\bserves\s+as\b/gi, replace: 'is', clarity: true },
- { pattern: /\bfeatures\b/gi, replace: 'has, includes', filter: true, clarity: true },
- { pattern: /\bboasts\b/gi, replace: 'has', clarity: true },
- { pattern: /\butiliz(?:e|es|ing|ed)\b/gi, replace: 'use', clarity: true },
- { pattern: /\bshowcas(?:e|es|ing|ed)\b/gi, replace: 'show, demonstrate' },
- { pattern: /\bembark(?:s|ing|ed)?\b/gi, replace: 'start, begin' },
- { pattern: /\bcommenc(?:e|es|ing|ed)\b/gi, replace: 'start, begin', clarity: true },
- { pattern: /\bascertain(?:s|ing|ed)?\b/gi, replace: 'find out, determine', clarity: true },
- { pattern: /\bendeavou?r(?:s|ing|ed)?\b/gi, replace: 'effort, attempt, try', clarity: true },
- { pattern: /\bunderscor(?:es|ing|ed)\b/gi, replace: 'highlights, shows' },
- // Hyphen required. The unhyphenated "load bearing" is ordinary English —
- // "the load bearing down on the bridge" — where `bearing` is a participle,
- // not part of a compound modifier. The tell is always hyphenated.
- //
- // Construction carve-out: exempt attributive `load-bearing` before a literal
- // structural noun, with one optional material/position adjective in between
- // ("load-bearing structural wall"). The noun list is limited to commonly
- // physical nouns; the abstract-capable ones most likely to carry the
- // metaphor (structure, element, frame, foundation) are omitted so "the
- // load-bearing structure of the argument" still fires. Some listed nouns
- // (member, column, partition) can still be used metaphorically and are
- // silently exempt — a recall loss in the safe direction, tracked in #56.
- // Predicative use ("the wall is load-bearing") is NOT exempt: the tell
- // lives in the subject, which a lookahead cannot reach. Also #56.
- { 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' },
- ];
- // ─── Tier 2: Flag in clusters (2+ per paragraph) ──────────────────
- const TIER2 = {
- 'harness': 'use, take advantage of',
- 'navigate': 'work through, handle',
- 'navigating': 'working through, handling',
- 'foster': 'encourage, support, build',
- 'elevate': 'improve, raise, strengthen',
- 'unleash': 'release, enable, unlock',
- 'streamline': 'simplify, speed up',
- 'empower': 'enable, let, allow',
- 'bolster': 'support, strengthen',
- 'spearhead': 'lead, drive, run',
- 'resonate': 'connect with, appeal to',
- 'resonates': 'connects with, appeals to',
- 'revolutionize': 'change, transform',
- 'facilitate': 'enable, help, allow',
- 'facilitates': 'enables, helps, allows',
- 'underpin': 'support, form the basis of',
- 'nuanced': 'specific, subtle, detailed',
- 'crucial': 'important, key, necessary',
- 'multifaceted': 'describe the actual facets',
- 'ecosystem': 'system, community, network',
- 'myriad': 'many, numerous',
- 'plethora': 'many, a lot of',
- 'encompass': 'include, cover, span',
- 'catalyze': 'start, trigger, accelerate',
- 'reimagine': 'rethink, redesign, rebuild',
- 'galvanize': 'motivate, rally, push',
- 'augment': 'add to, expand, supplement',
- 'cultivate': 'build, develop, grow',
- 'illuminate': 'clarify, explain, show',
- 'elucidate': 'explain, clarify',
- 'juxtapose': 'compare, contrast',
- 'transformative': 'describe what changed',
- 'transformation': 'describe what changed',
- 'cornerstone': 'foundation, basis, key part',
- 'paramount': 'most important, top priority',
- 'poised': 'ready, set, about to',
- 'burgeoning': 'growing, emerging',
- 'nascent': 'new, early-stage',
- 'quintessential': 'typical, classic, defining',
- 'overarching': 'main, central, broad',
- 'quietly': 'cut, or name the concrete contrast',
- 'underpinning': 'basis, foundation',
- 'underpinnings': 'basis, foundations',
- 'paradigm-shifting': 'describe what shifted',
- };
- // Conditional Tier 2 entries: everyday words whose AI tell is a specific
- // significance collocation, not the word itself. They join a paragraph's
- // Tier 2 cluster only when the collocation matches — bare uses ("deeply
- // nested JSON", "cares deeply") never count, because the base rate of
- // these words in innocent prose is far higher than the rest of the table
- // and an unconditional entry measurably flags clean human writing.
- const TIER2_CONDITIONAL = [
- {
- word: 'deeply',
- pattern: /\bdeeply\s+(?:integrated|committed|rooted|personal|human|flawed|resonant|transformative|interconnected|ingrained|embedded|meaningful)\b/i,
- suggestion: 'cut, or name what specifically runs deep',
- },
- ];
- // ─── Tier 3: Flag by density ───────────────────────────────────────
- const TIER3 = [
- 'significant', 'significantly', 'innovative', 'innovation',
- 'effective', 'effectively', 'dynamic', 'dynamics',
- 'scalable', 'scalability', 'compelling', 'unprecedented',
- 'exceptional', 'exceptionally', 'remarkable', 'remarkably',
- 'sophisticated', 'instrumental',
- 'world-class', 'state-of-the-art', 'best-in-class',
- // `verbatim` is usually redundant with the verb it modifies ("copies X
- // verbatim" = "copies X"). It has a genuine term-of-art sense in legal,
- // research, and QA registers ("verbatim transcript"), so it lives at Tier 3:
- // density-gated, it only fires on overuse, not on a single legitimate use.
- 'verbatim',
- ];
- // Multi-word Tier 3 phrases. Density-gated like single Tier 3 words because
- // these legitimately show up in human crypto/web3/dev writing. Threshold is
- // intentionally lower than single-word Tier 3 (≥2 occurrences of the same
- // phrase) — repeating the same multi-word boilerplate is a stronger AI tell
- // than re-using "significant."
- const TIER3_PHRASES = [
- /\bemerging\s+(?:sector|space|category|industry)\b/gi,
- /\bthe\s+integration\s+of\b/gi,
- /\bthe\s+intersection\s+of\b/gi,
- /\bcommunity-?driven\b/gi,
- /\blong-?term\s+sustainability\b/gi,
- /\buser\s+engagement\b/gi,
- /\bdecentralized\s+compute\b/gi,
- /\b(?:sustainable\s+)?reward\s+emissions?\b/gi,
- /\btokenized\s+incentive\s+structures?\b/gi,
- /\bdesigned\s+for\s+long-?term\b/gi,
- ];
- // O(1) lookup from any token form (hyphenated or dashless) to its canonical
- // Tier 3 word. Counting originally did nested-loop word matching which was
- // O(tokens × TIER3) — slow on long pastes.
- const TIER3_LOOKUP = new Map();
- for (const word of TIER3) {
- TIER3_LOOKUP.set(word, word);
- const dashless = word.replace(/-/g, '');
- if (dashless !== word) TIER3_LOOKUP.set(dashless, word);
- }
- // Per-category score weights. Applied to distinct (deduplicated) issues so
- // the score reflects the same signals the user sees in the issue list.
- // Non-uniform on purpose: critical rules like cutoff disclaimers (×10) and
- // chatbot artifacts (×8) weigh more than vague attributions (×5), even
- // though all three are tagged `critical`.
- const ISSUE_WEIGHTS = {
- tier1: 5,
- // Wordiness, not an AI-frequency marker. Weighted like tier2 so a
- // clarity fix cannot push a document toward an AI classification.
- 'tier1-clarity': 3,
- tier2: 3,
- tier3: 2,
- transition: 2,
- chatbot: 8,
- sycophantic: 8,
- filler: 2,
- 'generic-conclusion': 3,
- 'lets-construction': 2,
- 'reasoning-artifact': 6,
- 'acknowledgment-loop': 3,
- 'significance-inflation': 4,
- 'vague-attribution': 5,
- 'hollow-intensifier': 2,
- 'emotional-flatline': 2,
- 'lingering-attention': 3,
- 'novelty-inflation': 3,
- 'cutoff-disclaimer': 10,
- 'template-phrase': 3,
- 'false-concession': 2,
- 'rhetorical-question': 2,
- 'confidence-calibration': 2,
- 'em-dash': 4,
- uniformity: 5,
- formatting: 3,
- 'tier3-phrase': 3,
- // Structural / cluster signals are deliberately weighted high. Unlike
- // single-vocabulary hits they're near-dispositive on social-length
- // posts (a 15-hashtag block, a 6-item bullet-NP list, three distinct
- // crypto-shill phrases stacked) and would otherwise be suppressed by
- // the log2(words/50) length divisor on short pastes.
- 'tier3-phrase-cluster': 12,
- 'hashtag-stuff': 12,
- 'bullet-np-list': 10,
- 'hedge-stack': 6,
- 'future-narrative': 12,
- 'real-actual-inflation': 5,
- // Social endorsement / CTA closer. Weighted like formulaic-opener: a
- // strong single-hit social tell that the length divisor would
- // otherwise wash out on a short LinkedIn-length post.
- 'social-cta-closer': 8,
- 'formulaic-opener': 8,
- // Speculative scenario opener ("Imagine a world where…"). Weighted like
- // formulaic-opener: a single strong opener tell the length divisor would
- // otherwise wash out on a short post.
- 'speculative-opener': 8,
- 'title-case-header': 4,
- 'parenthetical-hedge': 3,
- 'smart-punct-signature': 6,
- 'punct-distribution': 6,
- 'fnword-trigram-entropy': 5,
- 'cross-para-burstiness': 5,
- 'normalization-flag': 9,
- // Vocabulary-diversity signal (type-token ratio). Weighted modestly
- // because the threshold (>=200 tokens AND TTR<0.4) is conservative;
- // it stacks with structural signals to push borderline scores up.
- 'low-ttr': 3,
- // AI-tool fingerprints. Weighted higher than statistical patterns
- // because each is a near-definitive single-hit signal — the AI tool
- // literally left its mark in the text. citation-markup ranks highest
- // (smoking gun: the literal internal markup of ChatGPT/Grok/etc.),
- // UTM tracking second (auto-appended by the tool to URLs it writes),
- // placeholders third (strong but humans use bracketed slots in
- // templates legitimately and forget them — still a publishing bug
- // but slightly less definitive AI evidence).
- 'ai-placeholder': 10,
- 'ai-citation-markup': 15,
- 'ai-utm-source': 12,
- };
- // ─── Transition phrases ────────────────────────────────────────────
- const TRANSITIONS = [
- /\bmoreover\b/gi,
- /\bfurthermore\b/gi,
- /\badditionally\b/gi,
- /\bin\s+today'?s\b/gi,
- /\bin\s+an\s+era\s+where\b/gi,
- /\bit'?s\s+worth\s+noting\s+that\b/gi,
- /\bnotably\b/gi,
- /\bin\s+conclusion\b/gi,
- /\bin\s+summary\b/gi,
- /\bto\s+summarize\b/gi,
- /\bwhen\s+it\s+comes\s+to\b/gi,
- /\bat\s+the\s+end\s+of\s+the\s+day\b/gi,
- /\bthat\s+(?:being\s+)?said\b/gi,
- ];
- // ─── Chatbot artifacts ─────────────────────────────────────────────
- const CHATBOT_ARTIFACTS = [
- /\bi\s+hope\s+this\s+helps\b/gi,
- /\bcertainly!\b/gi,
- /\babsolutely!\b/gi,
- /\bgreat\s+question!\b/gi,
- /\bexcellent\s+point!\b/gi,
- /\bfeel\s+free\s+to\s+reach\s+out\b/gi,
- /\blet\s+me\s+know\s+if\s+you\s+need\s+anything\b/gi,
- /\bin\s+this\s+article,?\s+we\s+will\s+explore\b/gi,
- /\blet'?s\s+dive\s+in!?\b/gi,
- ];
- // ─── Sycophantic tone ──────────────────────────────────────────────
- const SYCOPHANTIC = [
- /\byou'?re\s+absolutely\s+right\b/gi,
- /\bthat'?s\s+a\s+really\s+insightful\b/gi,
- /\bthat'?s\s+a\s+great\s+question\b/gi,
- /\bexcellent\s+question\b/gi,
- ];
- // ─── Filler phrases ────────────────────────────────────────────────
- const FILLERS = [
- /\bit\s+is\s+important\s+to\s+note\s+that\b/gi,
- /\bin\s+terms\s+of\b/gi,
- /\bthe\s+reality\s+is\s+that\b/gi,
- /\bit'?s\s+important\s+to\s+note\s+that\b/gi,
- ];
- // ─── Generic conclusions ───────────────────────────────────────────
- const GENERIC_CONCLUSIONS = [
- /\bthe\s+future\s+looks\s+bright\b/gi,
- /\bonly\s+time\s+will\s+tell\b/gi,
- /\bone\s+thing\s+is\s+certain\b/gi,
- /\bas\s+we\s+move\s+forward\b/gi,
- ];
- // ─── "Let's" constructions ─────────────────────────────────────────
- const LETS_PATTERNS = [
- /\blet'?s\s+explore\b/gi,
- /\blet'?s\s+take\s+a\s+look\b/gi,
- /\blet'?s\s+break\s+this\s+down\b/gi,
- /\blet'?s\s+examine\b/gi,
- /\blet'?s\s+(?:consider|discuss|delve|unpack|walk\s+through)\b/gi,
- ];
- // ─── Reasoning chain artifacts ─────────────────────────────────────
- const REASONING_ARTIFACTS = [
- /\blet\s+me\s+think\s+step\s+by\s+step\b/gi,
- /\bbreaking\s+this\s+down\b/gi,
- /\bto\s+approach\s+this\s+systematically\b/gi,
- /\bhere'?s\s+my\s+thought\s+process\b/gi,
- /\bfirst,?\s+let'?s\s+consider\b/gi,
- /\bworking\s+through\s+this\s+logically\b/gi,
- ];
- // ─── Acknowledgment loops ──────────────────────────────────────────
- const ACKNOWLEDGMENT_LOOPS = [
- /\byou'?re\s+asking\s+about\b/gi,
- /\bthe\s+question\s+of\s+whether\b/gi,
- /\bto\s+answer\s+your\s+question\b/gi,
- ];
- // ─── Significance inflation ────────────────────────────────────────
- const SIGNIFICANCE_INFLATION = [
- /\bmarking\s+a\s+(?:pivotal|significant|important)\s+moment\b/gi,
- /\ba\s+watershed\s+moment\s+for\b/gi,
- /\bin\s+the\s+evolution\s+of\b/gi,
- /\ba\s+(?:pivotal|defining)\s+moment\s+in\b/gi,
- ];
- // ─── Vague attributions ────────────────────────────────────────────
- const VAGUE_ATTRIBUTIONS = [
- /\bexperts\s+(?:believe|say|suggest|agree)\b/gi,
- /\bstudies\s+(?:show|suggest|indicate)\b/gi,
- /\bresearch\s+(?:shows|suggests|indicates)\b/gi,
- /\bindustry\s+leaders\s+(?:agree|believe|say)\b/gi,
- ];
- // ─── Hollow intensifiers ──────────────────────────────────────────
- const HOLLOW_INTENSIFIERS = [
- /\bgenuine(?:ly)?\b/gi,
- /\btruly\b/gi,
- /\bquite\s+frankly\b/gi,
- /\bto\s+be\s+honest\b/gi,
- /\blet'?s\s+be\s+clear\b/gi,
- ];
- // ─── Emotional flatline ────────────────────────────────────────────
- // The "interesting (part|thing|aspect|piece)" family is matched in two
- // shapes: (1) "the most interesting X" inline (the canonical AI list
- // intro), and (2) bare "Interesting X:" used as a section-header opener,
- // which is the section-break variant that slipped past v3.3.x.
- const EMOTIONAL_FLATLINE = [
- /\bwhat\s+surprised\s+me\s+most\b/gi,
- /\bi\s+was\s+fascinated\s+to\b/gi,
- /\bwhat\s+struck\s+me\s+was\b/gi,
- /\bi\s+was\s+excited\s+to\s+learn\b/gi,
- /\bthe\s+most\s+interesting\s+(?:part|thing|aspect|piece)\b/gi,
- // Multiline flag (/m) so `^` matches at every line start, including
- // position 0 of a pasted text that has no leading newline. The earlier
- // `(?:^|\n)` form silently missed bare openers at the very start of
- // input — caught by silent-failure audit 2026-05-16.
- /^\s*interesting\s+(?:part|thing|aspect|piece)(?:\s+of\s+(?:the\s+)?\w+)?\s*:/gim,
- ];
- // ─── Lingering-attention claims ────────────────────────────────────
- // The share-post opener that claims duration of attention instead of
- // saying anything about the thing ("the line I keep coming back to").
- //
- // Precision note: the bare verb phrase "I keep coming back to X" is NOT
- // matched on its own, because it is legitimate whenever a reason follows
- // ("I keep coming back to Hirschman because it predicts who quits"), and
- // the reason clause is not reliably detectable by regex. Only the
- // noun-anchored frame ("the line/quote/bit ... I keep coming back to")
- // fires, which is the shape that introduces a subject rather than
- // asserting something about it. The bare form stays a skill-prose
- // judgment call. See SKILL.md §Lingering-attention claims carve-out.
- const LINGERING_ATTENTION = [
- // "the line I keep coming back to", "the one quote that I keep coming back to"
- // Noun-anchored frame only. "can't stop thinking about" is deliberately
- // left to its own pattern below rather than folded into this alternation,
- // so "the line I can't stop thinking about" scores once, not twice.
- /\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,
- /\bi\s+can'?t\s+stop\s+thinking\s+about\b/gi,
- /\bstill\s+thinking\s+about\s+(?:this|that)\s+one\b/gi,
- /\b(?:been|be)\s+rattling\s+around\s+(?:in\s+)?my\s+(?:head|brain)\b/gi,
- /\bi'?ve\s+been\s+chewing\s+on\s+(?:this|that)\b/gi,
- ];
- // ─── Novelty inflation ─────────────────────────────────────────────
- const NOVELTY_INFLATION = [
- /\bthe\s+failure\s+mode\s+nobody'?s?\s+naming\b/gi,
- /\ba\s+problem\s+nobody\s+talks\s+about\b/gi,
- /\bthe\s+insight\s+everyone'?s?\s+missing\b/gi,
- /\bwhat\s+nobody\s+tells\s+you\b/gi,
- ];
- // ─── Cutoff disclaimers ────────────────────────────────────────────
- // Includes the canonical LLM self-identification phrases — these are
- // near-dispositive on their own (real humans don't write "as an AI
- // language model" in first person). Patterns cover the major model
- // families' default disclaimer language.
- const CUTOFF_DISCLAIMERS = [
- /\bas\s+of\s+my\s+last\s+update\b/gi,
- /\bas\s+of\s+my\s+(?:knowledge\s+)?(?:cut-?off|last\s+training)\b/gi,
- /\bi\s+don'?t\s+have\s+access\s+to\s+real-?time\s+(?:data|information)\b/gi,
- /\bbased\s+on\s+available\s+information\b/gi,
- /\bas\s+an?\s+(?:ai|artificial\s+intelligence|large\s+language|ai\s+language)\s+(?:language\s+)?model\b/gi,
- /\bi\s+(?:am|'m)\s+an?\s+(?:ai|artificial\s+intelligence|large\s+language)\s+(?:assistant|model)?\b/gi,
- /\bi\s+cannot\s+(?:provide|give|offer)\s+(?:legal|medical|financial|professional)\s+advice\b/gi,
- /\bmy\s+training\s+data\s+(?:only\s+)?(?:goes\s+up\s+to|extends\s+to|ends\s+(?:in|at))\b/gi,
- ];
- // ─── AI-tool fingerprints ──────────────────────────────────────────
- // Three near-definitive AI-origin signals adapted from
- // Aboudjem/humanizer-skill P33-P35 (see docs/competitive/audits/
- // 2026-05-17-aboudjem-humanizer-skill.md). Unlike the statistical
- // patterns above, single hit on any of these is strong evidence —
- // the AI tool literally left its fingerprint in the text.
- // Unfilled slot-fill placeholders. Catches the canonical "[Your Name]"
- // family plus dated stubs and HTML/MD comments with placeholder verbs.
- const AI_PLACEHOLDERS = [
- // Directive stubs ("[Your Name]", "[INSERT SOURCE URL]",
- // "[Describe the specific section]") — verb-led, the user was
- // told to fill in.
- /\[(?:Your|Insert|Add|Enter|Describe|Specify|Choose|Pick)[^\]\n]{1,80}\]/gi,
- // Noun-only template variables common in AI-generated email or
- // letter boilerplate. Match the bare noun OR noun + qualifier.
- // Conservative list: only nouns that almost never appear as
- // bracketed real content (citation refs, code identifiers, etc.
- // are excluded because they typically contain dots, slashes,
- // hyphens, or version numbers).
- /\[(?:Recipient|Sender|Topic|Subject|Salutation|Closing|Position|Department|Project Name|Company Name|Date)(?:\s+[^\]\n]{0,60})?\]/gi,
- // All-caps directive forms ("[INSERT X]", "[FILL IN]") — the
- // uppercase tells you it's a slot, not real content.
- /\[(?:INSERT|FILL\s+IN|ADD|TODO|TBD|PLACEHOLDER)[^\]\n]{0,80}\]/g,
- // Date stubs.
- /\b(?:19|20)\d{2}-XX-XX\b/g,
- /\bXX\/XX\/(?:19|20)\d{2}\b/g,
- // HTML/Markdown comment placeholders with placeholder verbs.
- /<!--\s*(?:add|fill\s+in|insert|todo|placeholder)[^>]{0,120}-->/gi,
- ];
- // Chatbot citation/markup tokens that leak through copy-paste.
- // `citeturn0search0` / `citeturn0news5` from ChatGPT, contentReference
- // tokens, oai_citation, attached_file references, grok_card markers.
- // Each is a near-definitive signature of a specific tool.
- const AI_CITATION_MARKUP = [
- /\bcite(?:turn|news|search|navigation)\d+(?:search|turn|news|navigation)\d+/gi,
- /contentReference\s*\[oaicite:[^\]]+\]\s*\{[^}]*\}/gi,
- /\boai_citation\b/gi,
- /\[attached_file:\d+\]/gi,
- /\bgrok_card\b/gi,
- ];
- // UTM/tracking parameters auto-appended by AI tools to URLs they
- // generate. Survives copy-paste even when nothing else does.
- const AI_UTM_SOURCE = [
- /[?&]utm_source=(?:chatgpt|openai|copilot|claude|grok|gemini|perplexity)(?:\.com|\.ai)?\b/gi,
- /[?&]referrer=(?:chatgpt|copilot|grok|claude|gemini|perplexity)\.(?:com|ai)\b/gi,
- ];
- // ─── Template phrases ──────────────────────────────────────────────
- const TEMPLATE_PHRASES = [
- /\ba\s+\w+\s+step\s+(?:towards?|forward\s+for)\b/gi,
- /\bwhether\s+you'?re\s+\w+\s+or\s+\w+/gi,
- /\bi\s+recently\s+had\s+the\s+pleasure\s+of\b/gi,
- ];
- // ─── False concession ──────────────────────────────────────────────
- const FALSE_CONCESSION = [
- /\bwhile\s+\w+\s+is\s+impressive\b/gi,
- /\balthough\s+\w+\s+has\s+made\s+strides\b/gi,
- /\bdespite\s+\w+\s+challenges?\b/gi,
- ];
- // ─── Rhetorical question openers ───────────────────────────────────
- const RHETORICAL_QUESTIONS = [
- /\bbut\s+what\s+does\s+this\s+mean\s+for\b/gi,
- /\bso\s+why\s+should\s+you\s+care\b/gi,
- /\bwhat'?s\s+next\?\s*/gi,
- ];
- // ─── Hedge-stacked predictions ─────────────────────────────────────
- // Stacks a modal with a hedge adverb: "could potentially create new
- // opportunities", "may eventually unlock value." Either word alone is
- // fine; the stack is the tell.
- const HEDGE_STACK = [
- // At most one intervening word, and never a negator. The old {0,2} gap
- // matched ordinary English: "could not possibly" (plain emphatic
- // negation) and inverted questions like "could a savage possibly" both
- // fired. Measured on the human-control corpus, 3 of 4 hedge-stack flags
- // were this over-match. See issue #69.
- /\b(?:could|may|might)\s+(?:(?!not\b|never\b|hardly\b|scarcely\b|barely\b)\w+\s+)?(?:potentially|eventually|ultimately|possibly|conceivably)\b/gi,
- /\b(?:potentially|eventually|ultimately)\s+(?:could|may|might)\b/gi,
- ];
- // ─── Generic future-narrative closers ──────────────────────────────
- // The "may become one of the most important narratives" template — vague
- // future significance with no falsifiable claim. Covers narratives /
- // stories / trends / themes / chapters / movements.
- const FUTURE_NARRATIVE = [
- /\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,
- /\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,
- ];
- // ─── "Real/actual" adjective inflation ─────────────────────────────
- // "Real on-chain tokenomics", "actual reward sustainability" — using
- // real/actual/genuine/true as an empty intensifier on an abstract noun
- // to imply the rest of the field is fake/superficial.
- const REAL_ACTUAL_INFLATION = [
- /\b(?:real|actual|genuine|true)\s+(?:on-?chain\s+)?(?:tokenomics|economics|utility|adoption|sustainability|impact|revenue|fundamentals|demand|value|innovation|traction)\b/gi,
- ];
- // ─── Formulaic openers ─────────────────────────────────────────────
- // The "In the rapidly evolving world of X, Y has emerged as..." family
- // — LLM-default essay openers.
- const FORMULAIC_OPENERS = [
- /\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,
- /\bin\s+(?:an?|the)\s+(?:digital\s+)?age\s+(?:where|of)\b/gi,
- /\bas\s+(?:we|the\s+world|society|industries?)\s+(?:continue|move|navigate|enter)\s+(?:to\s+)?(?:evolve|forward|into|through)\b/gi,
- // "has emerged as a leader/force/category" — gated to the inflated
- // nouns that signal pseudo-significance, since bare "has emerged as
- // a" matches normal English ("Rust has emerged as a serious systems
- // language"). Same gating for "has become increasingly".
- /\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,
- /\bhas\s+become\s+increasingly\s+(?:important|critical|popular|relevant|prominent|essential)\b/gi,
- ];
- // ─── Speculative scenario openers ──────────────────────────────────
- // "Imagine a world where...", "Picture a future in which...", "Envision
- // a world where..." — the LLM habit of opening an argument with a
- // hypothetical that lists desirable outcomes instead of making a claim.
- // Gated to the world/future/reality object plus where/in-which so it
- // stays off instructional "imagine you have an array" (a teaching device
- // pointing at a concrete example, not a speculative world) and bare
- // "imagine that" asides. "consider a scenario where…" is deliberately
- // excluded: that is analytical framing common in technical reasoning,
- // not the marketing-opener tell. An optional short comma interrupter
- // catches the equally common "Imagine, for a moment, a world where…"
- // cadence. Known accepted false positive: fiction openings and staged
- // thought experiments match too — the engine has no fiction context
- // mode, so that call is left to the skill's carve-out (highlight-only;
- // a lone hit cannot flip a document's classification).
- const SPECULATIVE_OPENERS = [
- /\b(?:imagine|picture|envision)(?:\s*,[^,\n]{1,30},)?\s+a\s+(?:world|future|reality)\s+(?:where|in\s+which)\b/gi,
- ];
- // Function words whose presence MID-title marks the AI section-header shape.
- // Word-anchored: without \b the "A" alternative matches inside any word and
- // the guard silently degrades to "four tokens".
- const FUNCTION_WORD = /\b(?:And|Or|Of|The|In|For|To|A|An)\b/;
- // Must accept exactly what TITLE_CASE_HEADER accepts, or the prefix survives
- // into the token count and reintroduces the ##-as-token bug.
- const MD_HEADING_PREFIX = /^#{1,6}[ \t]+/;
- /** Byte ranges covered by fenced code blocks, computed once per scan.
- *
- * A document that documents Markdown is the normal case for this rule -- a
- * fenced `## Heading` example is illustration, not the author's own section
- * header, and flagging it makes every docs page flag itself.
- *
- * This tracks the opening delimiter instead of counting them, because a
- * parity count is wrong on the very case the rule exists for. CommonMark
- * closes a fence only on the same character at the same length or longer, so
- * a four-backtick fence wrapping a three-backtick example -- exactly how you
- * document fences -- nests in practice, and counting delimiters inverts on
- * it. Up to three spaces of indent are legal. An unclosed fence runs to end
- * of document, matching how renderers treat it.
- *
- * Computed once per scan rather than rescanned per hit: the previous version
- * sliced the whole document for every candidate, which is quadratic on a
- * heading-dense file. */
- function fenceRanges(text) {
- const re = /^[ \t]{0,3}(`{3,}|~{3,})[^\n]*$/gm;
- const ranges = [];
- let open = null;
- let m;
- while ((m = re.exec(text)) !== null) {
- const marker = m[1];
- if (!open) {
- open = { char: marker[0], len: marker.length, start: m.index };
- } else if (marker[0] === open.char && marker.length >= open.len) {
- ranges.push([open.start, m.index + m[0].length]);
- open = null;
- }
- }
- if (open) ranges.push([open.start, text.length]);
- return ranges;
- }
- function inFenceRange(ranges, index) {
- return typeof index === 'number' && ranges.some(([a, b]) => index >= a && index < b);
- }
- // ─── Title Case Section Headers in non-technical prose ─────────────
- // "Strategic Negotiations And Key Partnerships" — every content word
- // capitalized. Acceptable in API docs, ML papers, news headlines. Tell
- // in marketing/personal/blog prose. Gated to "personal" / "marketing"
- // context modes (technical mode skips this check).
- //
- // The optional `#{1,6}` prefix is load-bearing (#62): without it the `^[A-Z]`
- // anchor required the line to START with a capital, so `## Benefits And
- // Strategic Considerations` never matched — the first character is `#`. The
- // rule missed the single most common way a heading is actually written, while
- // catching the bare-line form it is usually converted from. Reported by a
- // downstream vendoring the detector.
- //
- // Setext headings (`Title`/`=====`) need no prefix: their text line is bare
- // and already matched by this same pattern.
- 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;
- // ─── Parenthetical hedging asides ──────────────────────────────────
- // "(and increasingly, X)", "(or more precisely, Y)", "(though to be
- // fair, Z)" — pseudo-aside that adds no information but performs
- // thoughtfulness. Different from genuine human parentheticals which
- // tend to be tangents or clarifications, not hedges.
- const PARENTHETICAL_HEDGE = [
- /\(\s*(?:and\s+)?(?:increasingly|notably|importantly|crucially|interestingly|perhaps)[,]?\s+[^)]{3,60}\)/gi,
- /\(\s*or\s+more\s+(?:precisely|accurately|specifically)[,]?\s+[^)]{3,60}\)/gi,
- /\(\s*though\s+to\s+be\s+fair[,]?\s+[^)]{3,60}\)/gi,
- /\(\s*at\s+least\s+(?:in\s+)?(?:theory|principle|part)[,]?\s+[^)]{0,60}\)/gi,
- ];
- // ─── Confidence calibration ────────────────────────────────────────
- const CONFIDENCE_CALIBRATION = [
- /\binterestingly\b/gi,
- /\bsurprisingly\b/gi,
- /\bimportantly\b/gi,
- /\bsignificantly\b/gi,
- /\bcertainly\b/gi,
- /\bundoubtedly\b/gi,
- /\bwithout\s+a\s+doubt\b/gi,
- ];
- // ─── Social endorsement / CTA closers ──────────────────────────────
- // The curatorial sign-off LLMs append to LinkedIn / X posts that share
- // or recommend something — usually a colon teeing up a link. Distinct
- // from the bare "worth reading" word-table entry (a single weak word)
- // and from infomercial hooks (mid-flow teasers): this is the
- // demonstrative-anchored endorsement — "THIS one is worth your time:",
- // "do yourself a favor and read this", "thank me later" — that performs
- // a recommendation without giving the reader a reason to click.
- //
- // Precision-first: each pattern carries an anchor so it stays off the
- // literal-verb prose a human writes. The demonstrative object ("read
- // THIS", not "read the runbook"), the trailing-terminal lookahead on
- // "miss this" / "bookmark this" (the closing-line shape, not "miss this
- // meeting" / "bookmark this page"), and the sentence-initial lookbehind
- // on "thank me later" / "save this for later" (the imperative CTA, not
- // "she will thank me later") all exist to suppress false positives on
- // ordinary instructional/conversational text. Apostrophe classes admit
- // the curly ' (U+2019) because LinkedIn / Word / macOS auto-curl it —
- // the straight-only form would miss the canonical "you won't" closer.
- const SOCIAL_CTA_CLOSER = [
- /\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,
- /\bthis\s+one['’]?s?\s+(?:is\s+)?a\s+must[-\s]?(?:read|watch|listen|see)\b/gi,
- /\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,
- /\bdo\s+yourself\s+a\s+favou?r\s+and\s+(?:read|watch|check\s+out)\s+(?:this|it)\b/gi,
- /\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,
- /(?<=^|[,.!?:\n]\s{0,4})(?:you\s+can\s+)?thank\s+me\s+later\b/gim,
- /(?<=^|[.!?:\n]\s{0,4})save\s+this\s+(?:one\s+)?for\s+later\b/gim,
- /\bbookmark\s+this(?:\s+(?:one|post|thread))?(?=\s*(?:[:.!\n]|$))/gi,
- /\bdo\s*n['’]?t\s+sleep\s+on\s+this\b/gi,
- /\btrust\s+me,?\s+(?:on\s+this|you['’]?ll)\b/gi,
- ];
- // ═══ Helpers ═══════════════════════════════════════════════════════
- function tokenize(text) {
- return text.toLowerCase().match(/[\w'-]+/g) || [];
- }
- function countWords(text) {
- return (text.match(/\S+/g) || []).length;
- }
- function getParagraphs(text) {
- return text.split(/\n\s*\n/).filter(p => p.trim().length > 0);
- }
- function getSentences(text) {
- return text.split(/[.!?]+/).filter(s => s.trim().length > 5);
- }
- function matchPatterns(text, patterns, category, severity) {
- const issues = [];
- for (const pat of patterns) {
- const regex = new RegExp(pat.source, pat.flags);
- let match;
- while ((match = regex.exec(text)) !== null) {
- issues.push({
- type: category,
- text: match[0],
- index: match.index,
- severity,
- suggestion: null,
- });
- }
- }
- return issues;
- }
- // ═══ Main analysis ═════════════════════════════════════════════════
- // Upper bound for one scan. Above this we bail rather than running all
- // regex passes over a huge buffer — protects page perf on pasted novels.
- const MAX_WORDS = 10000;
- // V2 contract defaults so early-exit paths (Empty/tooShort/tooLong)
- // still return the same field shape a v2 consumer expects. Without
- // this, `result.document_classification === 'AI_ONLY'` is `undefined`
- // on edge inputs and fails open.
- // UNSCORED is returned on empty / too-short / too-long inputs where
- // we declined to score. Distinct from HUMAN_ONLY (which is a positive
- // classification) so a caller can't mistake a refused scan for a
- // confident human verdict — a 50k-word LLM-generated document is
- // not "human", it's just outside our scoring window.
- function buildV2Defaults(classification, confidence) {
- const probs = classification === 'HUMAN_ONLY'
- ? { human: 1, mixed: 0, ai: 0 }
- : classification === 'AI_ONLY'
- ? { human: 0, mixed: 0, ai: 1 }
- : { human: 0.333, mixed: 0.334, ai: 0.333 };
- return {
- document_classification: classification,
- class_probabilities: probs,
- confidence_category: confidence,
- highlight_sentence_for_ai: [],
- };
- }
- function analyzeText(text, options = {}) {
- if (!text || text.trim().length === 0) {
- return { ...buildV2Defaults('UNSCORED', 'low'), score: 0, label: 'Empty', issues: [], stats: {}, tooShort: true };
- }
- // Context mode gates rules that are noisy in technical writing. Modes:
- // 'general' (default) — full ruleset
- // 'technical' — skip title-case headers, formulaic openers gated to
- // prose-only structures; lower em-dash + formatting weights
- // 'marketing' — full ruleset + boost on formulaic-opener / future-narrative
- // 'personal' — full ruleset, normal weights
- // Mode is purely a soft gate; nothing is silently suppressed without
- // being reflected in stats.contextMode for transparency.
- // Mode validation: an unknown string (e.g. typo "tecnical") would
- // otherwise silently downgrade to general-mode behavior. Coerce to
- // 'general' and surface the original value in stats for traceability.
- const VALID_CONTEXT_MODES = new Set(['general', 'technical', 'marketing', 'personal']);
- const requestedMode = options.contextMode || 'general';
- const contextMode = VALID_CONTEXT_MODES.has(requestedMode) ? requestedMode : 'general';
- const contextModeFallback = requestedMode !== contextMode ? requestedMode : null;
- // Pre-pass: strip Markdown blockquotes before scoring. A human
- // reacting to AI text by quoting it shouldn't have the quoted block
- // counted against their own writing. Requires ≥2 consecutive `> `
- // lines to count as a blockquote — single-line `> ls -la` shell
- // prompts in technical docs stay in the text.
- let quotedLines = 0;
- const rawLines = text.split(/\r?\n/);
- const isQuote = rawLines.map((l) => /^\s*>\s/.test(l));
- const stripIdx = new Set();
- for (let i = 0; i < rawLines.length; i++) {
- if (isQuote[i] && ((isQuote[i - 1] && i > 0) || isQuote[i + 1])) {
- stripIdx.add(i);
- quotedLines++;
- }
- }
- text = rawLines.filter((_, i) => !stripIdx.has(i)).join('\n');
- // Pre-pass: strip bypass-trick chars before pattern matching so
- // "delve" with a Cyrillic 'е' still hits Tier 1. Original text is
- // preserved so reported `match.index` values remain visually accurate.
- const norm = normalizeText(text);
- text = norm.text;
- const wordCount = countWords(text);
- if (wordCount < 10) {
- return { ...buildV2Defaults('UNSCORED', 'low'), score: 0, label: 'Too short', issues: [], stats: { wordCount, contextMode, contextModeFallback }, tooShort: true };
- }
- if (wordCount > MAX_WORDS) {
- return {
- ...buildV2Defaults('UNSCORED', 'low'),
- score: 0,
- label: 'Text too long',
- issues: [],
- stats: { wordCount, contextMode, contextModeFallback },
- tooLong: true,
- };
- }
- const tokens = tokenize(text);
- const paragraphs = getParagraphs(text);
- const sentences = getSentences(text);
- const issues = [];
- let rawScore = 0;
- // ── 1. Tier 1 words ──────────────────────────────────────────
- const tier1Found = new Set();
- for (const token of tokens) {
- if (TIER1[token] && !tier1Found.has(token)) {
- tier1Found.add(token);
- issues.push({
- type: 'tier1',
- text: token,
- severity: 'high',
- suggestion: TIER1[token],
- });
- }
- }
- // Tier 1 multi-word phrases. Adds each distinct phrase (lowercased) to
- // `tier1Found` so the same phrase hit multiple times only produces one
- // issue — matches the downstream dedup behavior.
- for (const phrase of TIER1_PHRASES) {
- const regex = new RegExp(phrase.pattern.source, phrase.pattern.flags);
- let match;
- while ((match = regex.exec(text)) !== null) {
- const lower = match[0].toLowerCase();
- if (tier1Found.has(lower)) continue;
- tier1Found.add(lower);
- issues.push({
- // Clarity-band entries are wordiness edits, not frequency evidence.
- // Same fix, weaker claim — see the Tier 1A/1B split in SKILL.md.
- type: phrase.clarity ? 'tier1-clarity' : 'tier1',
- text: match[0],
- severity: phrase.clarity ? 'medium' : 'high',
- suggestion: phrase.replace,
- });
- }
- }
- // ── 2. Tier 2 clusters ───────────────────────────────────────
- let tier2Clusters = 0;
- for (const para of paragraphs) {
- const paraTokens = tokenize(para);
- const found = [];
- const suggestions = {};
- for (const token of paraTokens) {
- if (TIER2[token] && !found.includes(token)) {
- found.push(token);
- suggestions[token] = TIER2[token];
- }
- }
- for (const cond of TIER2_CONDITIONAL) {
- if (!found.includes(cond.word) && cond.pattern.test(para)) {
- found.push(cond.word);
- suggestions[cond.word] = cond.suggestion;
- }
- }
- if (found.length >= 2) {
- tier2Clusters++;
- for (const word of found) {
- issues.push({
- type: 'tier2',
- text: word,
- severity: 'medium',
- suggestion: suggestions[word],
- });
- }
- }
- }
- // ── 3. Tier 3 density ────────────────────────────────────────
- const tier3Counts = {};
- for (const token of tokens) {
- const canonical = TIER3_LOOKUP.get(token);
- if (canonical) tier3Counts[canonical] = (tier3Counts[canonical] || 0) + 1;
- }
- // Flag at 3% of word count, but never below 3 occurrences. Previous
- // floor of 1 meant a 50-word text with one "significant" got flagged
- // as Tier 3 overuse, which was noise.
- const densityThreshold = Math.max(3, Math.floor(wordCount * 0.03));
- let tier3Flags = 0;
- for (const [word, count] of Object.entries(tier3Counts)) {
- if (count >= densityThreshold) {
- tier3Flags++;
- issues.push({
- type: 'tier3',
- text: `"${word}" x${count}`,
- severity: 'low',
- suggestion: `Overused (${count} times in ${wordCount} words)`,
- });
- }
- }
- // ── 4–21. Pattern categories ─────────────────────────────────
- issues.push(...matchPatterns(text, TRANSITIONS, 'transition', 'medium'));
- issues.push(...matchPatterns(text, CHATBOT_ARTIFACTS, 'chatbot', 'critical'));
- issues.push(...matchPatterns(text, SYCOPHANTIC, 'sycophantic', 'critical'));
- issues.push(...matchPatterns(text, FILLERS, 'filler', 'medium'));
- issues.push(...matchPatterns(text, GENERIC_CONCLUSIONS, 'generic-conclusion', 'medium'));
- issues.push(...matchPatterns(text, LETS_PATTERNS, 'lets-construction', 'medium'));
- issues.push(...matchPatterns(text, REASONING_ARTIFACTS, 'reasoning-artifact', 'critical'));
- issues.push(...matchPatterns(text, ACKNOWLEDGMENT_LOOPS, 'acknowledgment-loop', 'medium'));
- issues.push(...matchPatterns(text, SIGNIFICANCE_INFLATION, 'significance-inflation', 'high'));
- issues.push(...matchPatterns(text, VAGUE_ATTRIBUTIONS, 'vague-attribution', 'critical'));
- issues.push(...matchPatterns(text, HOLLOW_INTENSIFIERS, 'hollow-intensifier', 'medium'));
- issues.push(...matchPatterns(text, EMOTIONAL_FLATLINE, 'emotional-flatline', 'low'));
- issues.push(...matchPatterns(text, LINGERING_ATTENTION, 'lingering-attention', 'medium'));
- issues.push(...matchPatterns(text, NOVELTY_INFLATION, 'novelty-inflation', 'medium'));
- issues.push(...matchPatterns(text, CUTOFF_DISCLAIMERS, 'cutoff-disclaimer', 'critical'));
- issues.push(...matchPatterns(text, AI_PLACEHOLDERS, 'ai-placeholder', 'critical'));
- issues.push(...matchPatterns(text, AI_CITATION_MARKUP, 'ai-citation-markup', 'critical'));
- issues.push(...matchPatterns(text, AI_UTM_SOURCE, 'ai-utm-source', 'critical'));
- issues.push(...matchPatterns(text, TEMPLATE_PHRASES, 'template-phrase', 'high'));
- issues.push(...matchPatterns(text, FALSE_CONCESSION, 'false-concession', 'medium'));
- issues.push(...matchPatterns(text, RHETORICAL_QUESTIONS, 'rhetorical-question', 'medium'));
- issues.push(...matchPatterns(text, HEDGE_STACK, 'hedge-stack', 'high'));
- issues.push(...matchPatterns(text, FUTURE_NARRATIVE, 'future-narrative', 'high'));
- issues.push(...matchPatterns(text, REAL_ACTUAL_INFLATION, 'real-actual-inflation', 'medium'));
- issues.push(...matchPatterns(text, SOCIAL_CTA_CLOSER, 'social-cta-closer', 'high'));
- // ── Tier 1 v2: formulaic openers + parenthetical hedges ──────────
- issues.push(...matchPatterns(text, FORMULAIC_OPENERS, 'formulaic-opener', 'high'));
- issues.push(...matchPatterns(text, SPECULATIVE_OPENERS, 'speculative-opener', 'high'));
- issues.push(...matchPatterns(text, PARENTHETICAL_HEDGE, 'parenthetical-hedge', 'medium'));
- // Title-case headers — gated to marketing/personal/general modes
- // (technical mode legitimately uses Title Case section headers).
- if (contextMode !== 'technical') {
- const titleHits = matchPatterns(text, [TITLE_CASE_HEADER], 'title-case-header', 'medium');
- // Drop matches that look like proper-noun titles (single line, all
- // tokens capitalized incl. function words) — that's headline style,
- // not the AI-section-header tell which has mid-sentence "And".
- //
- // The prefix strip is load-bearing. matchPatterns reports match[0], so a
- // Markdown hit arrives as "## Terms Of Service" and `##` counts as a
- // token — silently lowering this guard from four content words to three
- // for headings only, which is exactly the class it exists to protect.
- // "## Terms Of Service", "## Bank Of America" and "## Table Of Contents"
- // all flagged as a result: ordinary human headings, on a detector whose
- // stated first priority is not firing on human writing.
- const filtered = titleHits.filter((h) => {
- const title = h.text.replace(MD_HEADING_PREFIX, '');
- const tokens = title.trim().split(/\s+/);
- if (tokens.length < 4) return false;
- // The function word must be MID-title, which is what the comment above
- // has always said and what the test never enforced. A leading "The"
- // satisfied a bare /\bThe\b/, so ordinary human headings flagged:
- // "## The New Security Landscape", "## The Microsoft Approach to
- // Identity", "### The Four Keys to a Successful and Secure Modern
- // Workplace". Measured across 81 files that provably predate LLMs
- // (2018-19 eBooks, 2020 posts): 13 false positives, every one opening
- // with "The", against zero on main.
- //
- // "## Benefits And Strategic Considerations" -- the actual tell, and
- // this rule's own fixture -- is untouched: its "And" is interior.
- return FUNCTION_WORD.test(tokens.slice(1).join(' '));
- });
- const fences = filtered.length ? fenceRanges(text) : [];
- issues.push(...filtered.filter((h) => !inFenceRange(fences, h.index)));
- }
- // ── Normalization-trigger flag ───────────────────────────────────
- // ZWSPs or homoglyphs in pasted prose are near-dispositive: humans
- // don't insert these into their own writing. Single roleplay marker
- // can be a false positive on Markdown emphasis (filtered to multi-
- // word inner already), so requires ≥2.
- if (norm.flags.zeroWidth > 0 || norm.flags.homoglyph >= 2) {
- issues.push({
- type: 'normalization-flag',
- text: `${norm.flags.zeroWidth} zero-width + ${norm.flags.homoglyph} homoglyph swap${norm.flags.homoglyph === 1 ? '' : 's'}`,
- severity: 'critical',
- suggestion: 'Text contains invisible/lookalike chars typical of AI-humanizer bypass tools. Re-type from your own keyboard.',
- });
- }
- if (norm.flags.roleplay >= 2) {
- issues.push({
- type: 'normalization-flag',
- text: `${norm.flags.roleplay} *roleplay-action* markers stripped`,
- severity: 'high',
- suggestion: 'Paired *action* markers are a chat-model artifact.',
- });
- }
- // Em dashes in list-item separator position — a bulleted or numbered
- // list item opening with a bolded lead term or markdown link, then the
- // dash ("- **Term** — desc", "- [label](url) — desc") — are
- // definition-list typography, not prose punctuation. Shared by the
- // smart-punct signature below and the em-dash frequency check (§22).
- // An optional parenthetical or inline-code span may sit between the bold
- // lead term and the dash — "- **Lingering-attention claims**
- // (`lingering-attention`) — the share-post frame…" is the same definition
- // typography as the bare form. Found by the self-scan (see PROOF.md, #67).
- const SEPARATOR_DASH_RE = /^\s*(?:[-*+]|\d+[.)])\s+(?:\*\*[^*\n]+\*\*|\[[^\]\n]+\]\([^)\n]*\))(?:[ \t]*(?:\([^)\n]*\)|`[^`\n]+`))?[ \t]*—/gm;
- // Keep-a-Changelog version headings (`## [3.21.0] — 2026-07-30`) join a
- // label to a value exactly as a list separator does. Deliberately narrow:
- // a bracketed or bare semver token, then a dash, then an ISO date, and
- // nothing else on the line. Ordinary prose dashes in headings still count,
- // because SKILL.md applies the em-dash rule to headings too.
- const VERSION_HEADING_DASH_RE = /^#{1,6}[ \t]+\[?v?\d+\.\d+\.\d+[^\]\n]*\]?[ \t]*—[ \t]*\d{4}-\d{2}-\d{2}[ \t]*$/gm;
- // ── Smart-punctuation co-occurrence signature ────────────────────
- // Curly quotes + em-dash + Oxford comma all present + zero typos
- // (no double-spaces, no missing apostrophes in common contractions)
- // is a near-dispositive paste-from-LLM signature: humans typing
- // directly into a textarea don't produce all four. Standalone any of
- // these is meaningless — co-occurrence is the signal. Separator-position
- // dashes are typography and don't corroborate it.
- {
- const hasCurly = /[“”‘’]/.test(text);
- const totalEmDashes = (text.match(/—/g) || []).length;
- const separatorEmDashes = (text.match(SEPARATOR_DASH_RE) || []).length
- + (text.match(VERSION_HEADING_DASH_RE) || []).length;
- const hasEmDash = totalEmDashes > separatorEmDashes;
- const oxfordHit = text.match(/\b\w+,\s+\w+,\s+and\s+\w+/g);
- const hasOxford = (oxfordHit?.length || 0) >= 1;
- const doubleSpaces = (text.match(/[^.!?] +/g) || []).length;
- const missingApos = /\b(?:dont|wont|cant|isnt|wasnt|shouldnt|wouldnt|couldnt|youre|theyre|its\s+a\s+\w+ing)\b/i.test(text);
- const clean = doubleSpaces === 0 && !missingApos;
- const signals = [hasCurly, hasEmDash, hasOxford, clean].filter(Boolean).length;
- if (signals >= 4 && wordCount >= 80) {
- issues.push({
- type: 'smart-punct-signature',
- text: 'curly-quotes + em-dash + Oxford comma + zero typos',
- severity: 'high',
- suggestion: 'Smart-punctuation signature consistent with LLM output. Humans typing into textareas rarely produce all four.',
- });
- }
- }
- // ── Punctuation distribution mode ────────────────────────────────
- // Humans cluster trimodal across paragraphs (some paras heavy, some
- // light, some none). AI converges on a normal distribution. We can't
- // run a real modality test client-side, but we can flag the AI
- // signature: low variance of per-paragraph punctuation density.
- // Requires ≥4 paragraphs to be meaningful.
- if (paragraphs.length >= 4) {
- const densities = paragraphs.map((p) => {
- const words = (p.match(/\S+/g) || []).length;
- if (words < 5) return null;
- const puncts = (p.match(/[,;:—()]/g) || []).length;
- return puncts / words;
- }).filter((d) => d !== null);
- if (densities.length >= 4) {
- const mean = densities.reduce((a, b) => a + b, 0) / densities.length;
- const variance = densities.reduce((s, d) => s + (d - mean) ** 2, 0) / densities.length;
- const cv = mean > 0 ? Math.sqrt(variance) / mean : 0;
- // CV < 0.25 across paragraphs means each paragraph has the same
- // punctuation density — the AI signature. Humans usually swing
- // wider. Threshold derived from stylometry papers (arxiv 2507.00838).
- if (cv < 0.25 && mean >= 0.04) {
- issues.push({
- type: 'punct-distribution',
- text: `Punctuation density uniform across paragraphs (CV=${cv.toFixed(2)})`,
- severity: 'medium',
- suggestion: 'AI text holds punctuation density steady; human writers swing between dense and sparse paragraphs.',
- });
- }
- }
- }
- // ── Function-word trigram entropy ────────────────────────────────
- // POS-trigram entropy is the academic signal; function-word trigram
- // entropy approximates it without a tagger (function words ARE the
- // closed-class POS classes). AI text has lower entropy because LLM
- // sampling collapses onto a narrower set of grammatical templates.
- //
- // Method: extract function-word indicators per sentence, build
- // trigrams over the sequence, compute Shannon entropy. Bins below
- // threshold flag.
- if (wordCount >= 150) {
- const FUNC_WORDS = new Set([
- 'the','a','an','and','or','but','of','to','in','on','at','by','for','with',
- 'from','as','is','was','are','were','be','been','being','have','has','had',
- 'do','does','did','will','would','should','could','may','might','must','can',
- 'this','that','these','those','it','its','they','them','their','there','here',
- 'we','our','us','i','you','your','he','she','his','her','him','not','no','so',
- 'if','then','than','when','where','which','who','what','how','why','because',
- ]);
- const seq = tokens.map((t) => FUNC_WORDS.has(t) ? t : '_').filter((_, i, arr) => arr[i] !== '_' || (i > 0 && arr[i - 1] !== '_'));
- if (seq.length >= 50) {
- const trigrams = {};
- for (let i = 0; i < seq.length - 2; i++) {
- const tg = `${seq[i]}|${seq[i + 1]}|${seq[i + 2]}`;
- trigrams[tg] = (trigrams[tg] || 0) + 1;
- }
- const total = seq.length - 2;
- let entropy = 0;
- for (const c of Object.values(trigrams)) {
- const p = c / total;
- entropy -= p * Math.log2(p);
- }
- // Normalize by log2(distinct trigrams) so entropy ranges roughly
- // 0..1 and threshold is interpretable. Empirical threshold: human
- // prose ~0.85-0.95 normalized, AI prose ~0.70-0.82.
- const distinctCount = Object.keys(trigrams).length;
- const normalized = distinctCount > 1 ? entropy / Math.log2(distinctCount) : 1;
- if (normalized < 0.82 && total >= 50) {
- issues.push({
- type: 'fnword-trigram-entropy',
- text: `Function-word trigram entropy ${normalized.toFixed(2)} (low)`,
- severity: 'medium',
- suggestion: 'Grammatical structure is unusually repetitive. AI sampling collapses onto narrower templates than human writing.',
- });
- }
- // Degenerate case: single distinct trigram repeated across the
- // whole document is the strongest possible AI signal but the
- // normalized fallback returns 1.0 (= "fully human"), inverting
- // the signal. Catch it explicitly.
- if (distinctCount === 1 && total >= 50) {
- issues.push({
- type: 'fnword-trigram-entropy',
- text: 'Single function-word trigram repeated across document',
- severity: 'high',
- suggestion: 'Grammatical structure is fully degenerate — every clause uses the same function-word skeleton.',
- });
- }
- }
- }
- // ── Cross-paragraph burstiness ───────────────────────────────────
- // We already check within-paragraph sentence-length uniformity. AI
- // is also flat ACROSS paragraphs — every paragraph has roughly the
- // same sentence-length variance. Humans vary: terse paras next to
- // discursive paras. Measure variance of CV across paragraphs.
- if (paragraphs.length >= 4) {
- const cvs = paragraphs.map((p) => {
- const sents = getSentences(p);
- if (sents.length < 3) return null;
- const lens = sents.map(countWords);
- const m = lens.reduce((a, b) => a + b, 0) / lens.length;
- if (m === 0) return null;
- const v = lens.reduce((s, l) => s + (l - m) ** 2, 0) / lens.length;
- return Math.sqrt(v) / m;
- }).filter((c) => c !== null);
- if (cvs.length >= 4) {
- const cvMean = cvs.reduce((a, b) => a + b, 0) / cvs.length;
- const cvVar = cvs.reduce((s, c) => s + (c - cvMean) ** 2, 0) / cvs.length;
- const cvStd = Math.sqrt(cvVar);
- // Std-of-CV below 0.08 means every paragraph has roughly the same
- // internal rhythm — AI signature. Human prose typically swings
- // 0.15-0.40 across paragraphs of mixed purpose.
- if (cvStd < 0.08 && cvMean < 0.45) {
- issues.push({
- type: 'cross-para-burstiness',
- text: `Sentence-rhythm uniform across paragraphs (σCV=${cvStd.toFixed(2)})`,
- severity: 'medium',
- suggestion: 'Every paragraph has the same internal rhythm. Humans vary cadence between terse and discursive paragraphs.',
- });
- }
- }
- }
- // ── Tier 3 multi-word phrase density ─────────────────────────
- // Two complementary rules:
- // (a) Per-phrase density — same gating as single-word Tier 3: each
- // phrase fine alone, repetition is the tell. Threshold = 2.
- // (b) Cross-phrase clustering — ≥3 *distinct* boilerplate phrases
- // in one piece. LLMs varying their own boilerplate often use
- // each phrase only once but stack 5-10 across the text. The
- // per-phrase rule misses this; the cluster rule catches it.
- // Track non-overlapping match spans so a longer phrase swallowing a
- // shorter one (e.g., "designed for long-term sustainability" matches
- // both "designed for long-term" AND "long-term sustainability") only
- // contributes one distinct hit. Without dedup the cluster threshold
- // can be reached by a single sentence stacking overlapping regexes.
- const claimedSpans = [];
- function spanOverlaps(start, end) {
- for (const [s, e] of claimedSpans) {
- if (start < e && end > s) return true;
- }
- return false;
- }
- let distinctPhrasesHit = 0;
- for (const phrase of TIER3_PHRASES) {
- const regex = new RegExp(phrase.source, phrase.flags);
- const phraseSpans = [];
- let phraseMatch;
- while ((phraseMatch = regex.exec(text)) !== null) {
- const start = phraseMatch.index;
- const end = start + phraseMatch[0].length;
- if (!spanOverlaps(start, end)) {
- phraseSpans.push([start, end, phraseMatch[0]]);
- }
- }
- if (phraseSpans.length === 0) continue;
- for (const [s, e] of phraseSpans) claimedSpans.push([s, e]);
- distinctPhrasesHit++;
- if (phraseSpans.length >= 2) {
- issues.push({
- type: 'tier3-phrase',
- text: `"${phraseSpans[0][2].toLowerCase()}" x${phraseSpans.length}`,
- severity: 'medium',
- suggestion: `Boilerplate phrase repeated ${phraseSpans.length}× — replace at least one with specifics`,
- });
- }
- }
- if (distinctPhrasesHit >= 3) {
- issues.push({
- type: 'tier3-phrase-cluster',
- text: `${distinctPhrasesHit} distinct boilerplate phrases`,
- severity: 'high',
- suggestion: 'Several stock crypto/web3 phrases stacked in one piece. Rewrite around one specific claim or observation.',
- });
- }
- // ── Hashtag stuffing ─────────────────────────────────────────
- // 6+ hashtags in a single post is rare for thoughtful humans and
- // near-universal for LLM-generated social posts. Counted globally,
- // not per-paragraph, since the trailing hashtag block is the shape
- // we care about.
- // Match #tag at start of text or after any non-word char (whitespace,
- // punctuation, line breaks). URL fragments are already excluded
- // because the char immediately before `#` in a URL path is always
- // a word char (e.g. `example.com/page#section` — `e` before `#`).
- // Earlier char class `[\s\\]` had a literal backslash and silently
- // missed hashtags after sentence punctuation; an interim `[\s]` fix
- // on origin only caught whitespace-preceded tags.
- const hashtagMatches = text.match(/(?:^|\W)#\w[\w-]*/g) || [];
- if (hashtagMatches.length >= 6) {
- issues.push({
- type: 'hashtag-stuff',
- text: `${hashtagMatches.length} hashtags`,
- severity: 'medium',
- suggestion: 'Cut to 2-3 specific tags or none. Long hashtag blocks read as bot output.',
- });
- }
- // ── Bullet list of bare noun phrases ─────────────────────────
- // ≥5 consecutive bullet items that are short (≤6 words) and contain
- // no finite-verb / modal token. Catches the "Stable mining efficiency
- // / Reliable pool connectivity / Optimized RandomX performance ..."
- // shape LLMs default to. Markdown bullets, escaped Markdown bullets,
- // unicode bullets, and dashes are all matched. Numbered lists are
- // excluded — those have a separate "numbered list inflation" rule.
- //
- // Note: verbRe covers auxiliaries and modals ("was", "will", "can",
- // etc.). Regular past-tense verbs ("fixed", "removed") are not
- // matched here; instead, the ≤6-word length gate excludes most
- // real-world changelog lines, which tend to read "fixed the X that
- // was doing Y" (>6 words). Short two-word action items ("* fixed
- // bug") would pass both gates — an acceptable trade-off to avoid
- // false-negative risk from adjectives ending in -ed ("skilled",
- // "advanced") that share the same surface form.
- const lines = text.split(/\r?\n/);
- const bulletRe = /^\s*(?:\*|-|•|\+)\s+(.+)$/;
- 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;
- const fenceRe = /^\s*(?:```|~~~)/;
- let run = [];
- let blankStreak = 0;
- let inFence = false;
- function flushRun() {
- if (run.length >= 5) {
- const bareNP = run.filter((it) => {
- const wc = (it.match(/\S+/g) || []).length;
- return wc > 0 && wc <= 6 && !verbRe.test(it);
- });
- if (bareNP.length >= 5 && bareNP.length / run.length >= 0.75) {
- issues.push({
- type: 'bullet-np-list',
- text: `${run.length}-item bullet list of bare noun phrases`,
- severity: 'high',
- suggestion: 'Convert to a prose paragraph or merge items. Long lists of bare adj+noun pairs read as AI scaffolding.',
- });
- }
- }
- run = [];
- blankStreak = 0;
- }
- for (const line of lines) {
- if (fenceRe.test(line)) {
- // Code-fence toggle. Bullets inside fences are CLI flag docs or
- // option dumps, not prose AI scaffolding — flush any prose run
- // we were tracking and skip until the fence closes.
- flushRun();
- inFence = !inFence;
- continue;
- }
- if (inFence) continue;
- const m = line.match(bulletRe);
- if (m) {
- run.push(m[1].trim());
- blankStreak = 0;
- } else if (line.trim() === '') {
- // A single blank line inside a list is normal Markdown spacing;
- // two or more blank lines break the run, since visually-disjoint
- // bullet sections shouldn't merge into one logical list.
- blankStreak++;
- if (blankStreak >= 2) flushRun();
- } else {
- flushRun();
- }
- }
- flushRun();
- // NOTE: "Wall-of-text replies" (SKILL.md) is deliberately NOT a
- // detector rule here. A first pass tried "reply-length text, >=4
- // sentences, zero newlines" as a structural gate — it broke the
- // "repeated Tier 1 phrase does not inflate score linearly" fixture
- // and, on reflection, would fire on any ordinary short paragraph
- // (a blog intro, a single-paragraph email) since "one paragraph with
- // no internal line break" is simply what continuous prose looks
- // like, not an AI-specific shape. The tell in SKILL.md depends on
- // knowing the text is conversational-reply register in the first
- // place, which the engine can't reliably infer from the bytes alone
- // (CONTRIBUTING.md: "a signal that fires on most normal prose is not
- // worth adding"). Left as an LLM-judgment rule; see CATEGORIES.md §C.
- // Confidence calibration is only flagged when it stacks (3+ instances).
- // Gating happens pre-dedup on raw match count, since that signals actual
- // stacking, not just vocabulary use.
- const confIssues = matchPatterns(text, CONFIDENCE_CALIBRATION, 'confidence-calibration', 'low');
- if (confIssues.length >= 3) issues.push(...confIssues);
- // ── 22. Em dash frequency ────────────────────────────────────
- // Match real em dashes, plus `--` only when surrounded by whitespace on at
- // least one side (skips CLI flags like --save-dev and YAML `---` blocks).
- // Separator-position em dashes (SEPARATOR_DASH_RE above) are excluded
- // from the rate. The list marker is required on purpose: a line-initial
- // "**Bold lead** — full sentence" outside a list is itself an AI tell
- // and still counts, as does a mid-sentence "**bold** — like this"
- // splice. Em dash only — the `--` substitute is never carved out.
- const rawEmDashCount = (text.match(/—|(?<=\s)--(?=\s|$)|(?<=^|\s)--(?=\s)/gm) || []).length;
- const separatorDashCount = (text.match(SEPARATOR_DASH_RE) || []).length
- + (text.match(VERSION_HEADING_DASH_RE) || []).length;
- const emDashCount = rawEmDashCount - separatorDashCount;
- const emDashRate = emDashCount / (wordCount / 1000);
- if (emDashRate > 1) {
- issues.push({
- type: 'em-dash',
- text: `${emDashCount} em dashes in ${wordCount} words`,
- severity: 'medium',
- suggestion: 'Replace with commas, periods, or rewrite',
- });
- }
- // ── 23. Sentence length uniformity ───────────────────────────
- if (sentences.length >= 5) {
- const lengths = sentences.map(s => countWords(s));
- const avg = lengths.reduce((a, b) => a + b, 0) / lengths.length;
- const variance = lengths.reduce((sum, l) => sum + Math.pow(l - avg, 2), 0) / lengths.length;
- const stdDev = Math.sqrt(variance);
- const cv = avg > 0 ? stdDev / avg : 0;
- if (cv < 0.25 && avg > 10) {
- issues.push({
- type: 'uniformity',
- text: `Sentence lengths cluster around ${Math.round(avg)} words (low variation)`,
- severity: 'medium',
- suggestion: 'Mix short punchy sentences with longer flowing ones',
- });
- }
- }
- // ── Type-token ratio (stylometric — vocabulary diversity) ────
- // TTR = distinct word types / total tokens. Human prose at 200+
- // words typically sits around 0.50–0.65 for English; AI prose
- // tends flatter (0.55–0.75 looks normal, but the lower end of the
- // *too-flat* tail at >=200 words is where the signal lives — too
- // FEW unique words for the length). This is the simplest of the
- // four stylometric signals identified in the May 2026 detection-
- // research review (docs/competitive/detection-research.md): no
- // POS tagger required, no model, pure JS.
- //
- // Threshold tuning: flag only when the sample is large enough
- // that low TTR is meaningfully suspicious (>=200 tokens) AND TTR
- // is below 0.40 (very vocabulary-poor). Conservative on purpose;
- // false positives on short or topic-narrow human prose are easy
- // to trigger and would drown out other signals. The detector-
- // research lens flagged TTR as one of four stylometric add-ons;
- // POS-bigram log-odds, function-word z-scores, and sentence-
- // length burstiness are still TODO.
- if (tokens.length >= 200) {
- const unique = new Set(tokens).size;
- const ttr = unique / tokens.length;
- if (ttr < 0.4) {
- issues.push({
- type: 'low-ttr',
- text: `Vocabulary diversity ${(ttr * 100).toFixed(1)}% (${unique} unique / ${tokens.length} tokens)`,
- severity: 'low',
- suggestion: 'Text reuses a narrow word set. Vary nouns and verbs deliberately, or check if the topic genuinely warrants the repetition.',
- });
- }
- }
- // ── 24. Paragraph length uniformity ──────────────────────────
- if (paragraphs.length >= 4) {
- const paraLengths = paragraphs.map(p => getSentences(p).length);
- const avg = paraLengths.reduce((a, b) => a + b, 0) / paraLengths.length;
- const allSimilar = paraLengths.every(l => Math.abs(l - avg) <= 1);
- if (allSimilar && avg >= 3) {
- issues.push({
- type: 'uniformity',
- text: `All paragraphs are ~${Math.round(avg)} sentences`,
- severity: 'low',
- suggestion: 'Vary paragraph length deliberately',
- });
- }
- }
- // ── 25. Bold overuse ─────────────────────────────────────────
- const boldMatches = text.match(/\*\*[^*]+\*\*/g) || [];
- if (boldMatches.length > 3) {
- issues.push({
- type: 'formatting',
- text: `${boldMatches.length} bold phrases`,
- severity: 'medium',
- suggestion: 'Strip bold from most; restructure to lead with key info',
- });
- }
- // ── Score from the deduped issue list ───────────────────────
- // Previously rawScore was accumulated inline per pattern hit, so
- // repeated hits of the same phrase (or overlapping matches) inflated
- // the score while the displayed issue list was deduplicated. That
- // produced the UX regression where a "heavy AI patterns" label sat
- // above a list of two items. Now the dedup runs first, then each
- // distinct issue contributes its category weight — so the number
- // reflects the same signals the user actually sees.
- const deduped = deduplicateIssues(issues);
- for (const issue of deduped) {
- rawScore += ISSUE_WEIGHTS[issue.type] ?? 2;
- }
- // Scale by text length: longer text gets more chances to trigger.
- const lengthFactor = Math.max(1, Math.log2(wordCount / 50));
- const normalizedScore = Math.min(100, Math.round(rawScore / lengthFactor));
- const label = getLabel(normalizedScore);
- // ── Sentence-region smoothing (HMM-style without an HMM) ─────────
- // Map each text-bearing issue back to its sentence indexes, then
- // merge adjacent flagged sentences into contiguous regions for UI
- // highlighting. Borrowed from GPTZero's sentence-highlighting model
- // — gives users "this paragraph is AI" rather than scattered hits.
- const regions = buildSentenceRegions(text, deduped);
- // Stats derived from the same deduped list so tier counts + patternCount
- // sum to `deduped.length`. Previously patternCount subtracted
- // `tier2Clusters` (a paragraph count) which produced inconsistent totals.
- const tier1Count = deduped.filter((i) => i.type === 'tier1').length;
- const tier2Count = deduped.filter((i) => i.type === 'tier2').length;
- const tier3Count = deduped.filter((i) => i.type === 'tier3').length;
- // ── Trinary classification (GPTZero-shaped) ──────────────────────
- // Decouples confidence from AI-proportion. Maps the 0-100 score plus
- // structural signals into HUMAN_ONLY / MIXED / AI_ONLY with a
- // confidence band. Thresholds are FN-biased: ambiguity routes to
- // MIXED, never AI_ONLY. Quote from GPTZero's design principle:
- // "biases the detector to prefer making less-harmful false-negative
- // errors over false-positive errors."
- // Dense-AI-vocab trifecta: ≥5 distinct tier1 hits + ≥2 tier2 cluster
- // paragraphs + ≥1 transition phrase, AND ≥150 words. Catches
- // saturated ChatGPT prose without firing on dense-jargon human
- // technical writing where the tier1 vocabulary (robust,
- // comprehensive, leverage, ecosystem) legitimately overlaps with
- // systems-programming idiom. Word-count gate prevents short ESL or
- // contrived adversarial sentences from tripping the corroborator.
- const tier1Distinct = new Set(deduped.filter((i) => i.type === 'tier1').map((i) => (i.text || '').toLowerCase())).size;
- const hasTier2Cluster = tier2Clusters >= 2;
- const hasTransition = deduped.some((i) => i.type === 'transition');
- const denseAIVocab = wordCount >= 150 && tier1Distinct >= 5 && hasTier2Cluster && hasTransition;
- const trinary = classifyTrinary({
- score: normalizedScore,
- issues: deduped,
- regions,
- normFlags: norm.flags,
- wordCount,
- denseAIVocab,
- });
- return {
- // Legacy fields preserved for existing callers.
- score: normalizedScore,
- label,
- issues: deduped,
- stats: {
- wordCount,
- tier1Count,
- tier2Count,
- tier2Clusters,
- tier3Count,
- tier3Flags,
- patternCount: deduped.length - tier1Count - tier2Count - tier3Count,
- contextMode,
- contextModeFallback,
- normalization: norm.flags,
- quotedLines,
- unmappedHighlights: regions._unmapped ?? 0,
- denseAIVocab,
- tier1Distinct,
- },
- // Trinary API — shape mirrors GPTZero so integrators can swap.
- document_classification: trinary.classification,
- class_probabilities: trinary.probabilities,
- confidence_category: trinary.confidence,
- highlight_sentence_for_ai: regions,
- };
- }
- // ═══ Sentence regions + trinary classifier ═════════════════════════
- function buildSentenceRegions(text, issues) {
- // Split text into sentences with byte offsets preserved so the UI
- // can highlight spans accurately. Sentence boundaries are coarse
- // (.!?) — fine for highlighting, not for linguistic correctness.
- const sentences = [];
- const sentenceRe = /[^.!?]+[.!?]+|\S[^.!?]*$/g;
- let m;
- while ((m = sentenceRe.exec(text)) !== null) {
- const trimmed = m[0].trim();
- if (trimmed.length < 4) continue;
- sentences.push({ start: m.index, end: m.index + m[0].length, text: trimmed });
- }
- if (sentences.length === 0) return [];
- // Map issue.text back to sentence indexes via substring search. Issues
- // without a meaningful text (e.g. summary signals like "Punctuation
- // density uniform across paragraphs") have no sentence anchor — they
- // contribute to the document-level signal but not to highlights.
- // Filter by issue TYPE not text-regex: text-based filtering used to
- // drop legitimate phrase issues containing "across" / "density".
- const SUMMARY_ONLY_TYPES = new Set([
- 'punct-distribution',
- 'cross-para-burstiness',
- 'fnword-trigram-entropy',
- 'smart-punct-signature',
- 'normalization-flag',
- 'uniformity',
- 'em-dash',
- 'formatting',
- 'tier3',
- 'tier3-phrase',
- 'tier3-phrase-cluster',
- 'hashtag-stuff',
- 'bullet-np-list',
- ]);
- const hits = sentences.map(() => ({ count: 0, weight: 0 }));
- const lowerText = text.toLowerCase();
- let unmappedHighlights = 0;
- for (const issue of issues) {
- if (!issue.text || issue.text.length > 200) continue;
- if (SUMMARY_ONLY_TYPES.has(issue.type)) continue;
- const needle = issue.text.toLowerCase();
- let idx = 0;
- let matched = false;
- while ((idx = lowerText.indexOf(needle, idx)) !== -1) {
- matched = true;
- for (let i = 0; i < sentences.length; i++) {
- if (idx >= sentences[i].start && idx < sentences[i].end) {
- hits[i].count++;
- hits[i].weight += ISSUE_WEIGHTS[issue.type] ?? 2;
- break;
- }
- }
- idx += needle.length;
- }
- if (!matched) unmappedHighlights++;
- }
- // Window-merge contiguous flagged sentences. Allow 1 unflagged
- // sentence gap between two flagged ones (the "smoothing" — keeps
- // a single boring sentence from breaking what's clearly an AI
- // passage). A sentence is "flagged" if it has ≥1 hit.
- const regions = [];
- let cur = null;
- for (let i = 0; i < sentences.length; i++) {
- if (hits[i].count > 0) {
- if (cur === null) {
- cur = { startSentence: i, endSentence: i, start: sentences[i].start, end: sentences[i].end, hitCount: hits[i].count, weight: hits[i].weight };
- } else {
- cur.endSentence = i;
- cur.end = sentences[i].end;
- cur.hitCount += hits[i].count;
- cur.weight += hits[i].weight;
- }
- } else if (cur !== null) {
- // Allow one-sentence gap.
- const next = hits[i + 1];
- if (next && next.count > 0) {
- cur.endSentence = i;
- cur.end = sentences[i].end;
- continue;
- }
- regions.push(finalizeRegion(cur));
- cur = null;
- }
- }
- if (cur !== null) regions.push(finalizeRegion(cur));
- // Expose the unmapped-highlight count via a non-enumerable property
- // so the array length still reads naturally for consumers; the
- // analyzer pulls it into stats.unmappedHighlights for diagnostics.
- Object.defineProperty(regions, '_unmapped', { value: unmappedHighlights, enumerable: false });
- return regions;
- }
- function finalizeRegion(r) {
- // Map cumulative weight inside the region to a 0-1 score. Cap at 20
- // weight = 1.0 (matches Heavy threshold density).
- const score = Math.min(1, r.weight / 20);
- return {
- startSentence: r.startSentence,
- endSentence: r.endSentence,
- start: r.start,
- end: r.end,
- hitCount: r.hitCount,
- score: Math.round(score * 100) / 100,
- };
- }
- // FN-biased: false positives damage trust more than false negatives,
- // so MIXED is wide and AI_ONLY requires multiple signals. Quote from
- // GPTZero: "biases the detector to prefer making less-harmful
- // false-negative errors over false-positive errors."
- function classifyTrinary({ score, issues, regions, normFlags, wordCount, denseAIVocab }) {
- // Strong corroborators — each is near-dispositive on its own:
- // - cutoff-disclaimer (LLM self-identifies as an AI)
- // - reasoning-artifact + chatbot-artifact co-occurrence
- // - normalization-flag at threshold (≥2 ZWSP or homoglyphs).
- // Threshold parity prevents a single stray ZWSP in copy-paste
- // from Word/Notion from flipping to AI_ONLY at score 0.
- // - denseAIVocab: ≥4 distinct tier1 hits AND ≥1 tier2 cluster AND
- // ≥1 transition phrase — the trifecta that saturated ChatGPT
- // prose triggers without needing whitelisted stylometric hits.
- const hasCutoff = issues.some((i) => i.type === 'cutoff-disclaimer');
- const hasNormFlag = normFlags.zeroWidth >= 2 || normFlags.homoglyph >= 2;
- const hasReasoning = issues.some((i) => i.type === 'reasoning-artifact');
- const hasChatbot = issues.some((i) => i.type === 'chatbot');
- const strongCorrob =
- (hasCutoff ? 1 : 0) +
- (hasNormFlag ? 1 : 0) +
- (hasReasoning && hasChatbot ? 1 : 0) +
- (denseAIVocab ? 1 : 0);
- // Weak (stylometric) corroborators — suggestive on their own,
- // dispositive in combination. Smart-punct-signature matches
- // Word-edited human prose so doesn't count without other support.
- const stylometricHits = ['punct-distribution', 'cross-para-burstiness', 'fnword-trigram-entropy']
- .filter((t) => issues.some((i) => i.type === t)).length;
- const hasSmartPunct = issues.some((i) => i.type === 'smart-punct-signature');
- const weakCorrob = (stylometricHits >= 2 ? 1 : 0) + (hasSmartPunct ? 1 : 0);
- // Thresholds:
- // score < 15 with no strong → HUMAN_ONLY
- // strong ≥ 1 OR score ≥ 70 → AI_ONLY (lowered from 80; high
- // density of AI vocab is sufficient evidence)
- // score ≥ 40 with any corroborator → AI_ONLY
- // everything else with score ≥ 15 → MIXED
- const totalCorrob = strongCorrob + weakCorrob;
- let classification;
- if (score < 15 && strongCorrob === 0) classification = 'HUMAN_ONLY';
- else if (strongCorrob >= 1 || score >= 70) classification = 'AI_ONLY';
- else if (score >= 40 && totalCorrob >= 1) classification = 'AI_ONLY';
- else classification = 'MIXED';
- // Humanizer-flag escalation: presence of bypass-trick chars is
- // adversarial signal. If a normalization-flag fired we already
- // counted it in strongCorrob → AI_ONLY. Confidence also gets a
- // floor of 'medium' in that case (an adversary actively evading
- // detection should never read as low-confidence noise).
- // Soft probability distribution. Not calibrated against a labeled
- // corpus yet (TODO when corpus exists — see roadmap.md). Largest
- // class is computed as `1 - others` after rounding to guarantee
- // sum=1 exactly. Sub-1% drift would otherwise hide in toFixed.
- const aiSoft = Math.min(0.97, score / 100 + totalCorrob * 0.06 + strongCorrob * 0.08);
- let p;
- 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) };
- else if (classification === 'AI_ONLY') p = { human: Math.max(0.02, 1 - aiSoft - 0.05), mixed: 0.1, ai: aiSoft };
- else p = { human: Math.max(0.15, 0.6 - aiSoft * 0.5), mixed: 0.5, ai: aiSoft * 0.7 };
- const rawSum = p.human + p.mixed + p.ai;
- p.human = +(p.human / rawSum).toFixed(3);
- p.mixed = +(p.mixed / rawSum).toFixed(3);
- // Assign ai as the remainder so the three values sum to exactly 1.
- // Clamp to >= 0 in case rounding pushes human+mixed above 1 (the
- // remainder would otherwise show as -0 or -0.001 — surfaces as a
- // negative percentage in any UI doing Math.round(p.ai * 100)).
- p.ai = Math.max(0, +(1 - p.human - p.mixed).toFixed(3));
- const probabilities = p;
- // Confidence band:
- // high — strongCorrob ≥ 2, OR cutoff-disclaimer, OR score < 8 (clean long doc)
- // medium — strongCorrob ≥ 1, OR score ≥ 45 with weak corroborator, OR score < 20
- // low — everything else
- let confidence;
- if (strongCorrob >= 2 || hasCutoff || (score < 8 && wordCount >= 100)) confidence = 'high';
- else if (strongCorrob >= 1 || (score >= 45 && weakCorrob >= 1) || score < 20) confidence = 'medium';
- else confidence = 'low';
- return { classification, probabilities, confidence };
- }
- function getLabel(score) {
- if (score === 0) return 'Clean';
- if (score <= 15) return 'Minimal AI signals';
- if (score <= 35) return 'Some AI patterns';
- if (score <= 60) return 'Moderate AI signals';
- if (score <= 80) return 'Strong AI signals';
- return 'Heavy AI patterns';
- }
- function getColor(score) {
- if (score <= 15) return '#44bb66';
- if (score <= 35) return '#88bb44';
- if (score <= 60) return '#ddaa00';
- if (score <= 80) return '#ff8833';
- return '#ff4444';
- }
- function deduplicateIssues(issues) {
- const seen = new Set();
- return issues.filter(issue => {
- const key = `${issue.type}:${issue.text.toLowerCase()}`;
- if (seen.has(key)) return false;
- seen.add(key);
- return true;
- });
- }
- // ─── Severity labels ──────────────────────────────────────────
- const SEVERITY_LABELS = {
- critical: 'P0',
- high: 'P1',
- medium: 'P2',
- low: 'P3',
- };
- const TYPE_LABELS = {
- 'tier1': 'AI vocabulary',
- 'tier1-clarity': 'Wordiness',
- 'tier2': 'Word cluster',
- 'tier3': 'Overused word',
- 'transition': 'AI transition',
- 'chatbot': 'Chatbot artifact',
- 'sycophantic': 'Sycophantic tone',
- 'filler': 'Filler phrase',
- 'generic-conclusion': 'Generic conclusion',
- 'lets-construction': '"Let\'s" opener',
- 'reasoning-artifact': 'Reasoning artifact',
- 'acknowledgment-loop': 'Acknowledgment loop',
- 'significance-inflation': 'Significance inflation',
- 'vague-attribution': 'Vague attribution',
- 'hollow-intensifier': 'Hollow intensifier',
- 'emotional-flatline': 'Emotional flatline',
- 'lingering-attention': 'Lingering-attention claim',
- 'novelty-inflation': 'Novelty inflation',
- 'cutoff-disclaimer': 'Cutoff disclaimer',
- 'template-phrase': 'Template phrase',
- 'false-concession': 'False concession',
- 'rhetorical-question': 'Rhetorical question',
- 'confidence-calibration': 'Confidence stacking',
- 'em-dash': 'Em dash overuse',
- 'uniformity': 'Rhythm uniformity',
- 'formatting': 'Formatting',
- 'tier3-phrase': 'Boilerplate phrase',
- 'tier3-phrase-cluster': 'Boilerplate cluster',
- 'hashtag-stuff': 'Hashtag stuffing',
- 'bullet-np-list': 'Bullet-NP list',
- 'hedge-stack': 'Hedge-stacked prediction',
- 'future-narrative': 'Generic future narrative',
- 'real-actual-inflation': '"Real/actual" inflation',
- 'social-cta-closer': 'Engagement-bait closer',
- 'formulaic-opener': 'Formulaic opener',
- 'speculative-opener': 'Speculative scenario opener',
- 'title-case-header': 'Title Case header',
- 'parenthetical-hedge': 'Parenthetical hedge',
- 'smart-punct-signature': 'Smart-punct signature',
- 'punct-distribution': 'Punctuation distribution',
- 'fnword-trigram-entropy': 'Grammar repetition',
- 'cross-para-burstiness': 'Cross-paragraph rhythm',
- 'normalization-flag': 'Bypass-trick chars',
- 'low-ttr': 'Low vocabulary diversity',
- 'ai-placeholder': 'Unfilled placeholder',
- 'ai-citation-markup': 'Chatbot citation markup leak',
- 'ai-utm-source': 'AI-tool URL parameter',
- };
- return {
- analyzeText,
- normalizeText,
- getLabel,
- getColor,
- SEVERITY_LABELS,
- TYPE_LABELS,
- };
- })();
- if (typeof module !== 'undefined' && module.exports) {
- module.exports = AIDetector;
- }
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.