@devrik-tools/claude-gates 0.7.2 → 0.8.0

package/plugins/gates/hooks/gates/no-coauthor/index.mjs

@@ -1,98 +1,116 @@
-// no-coauthor — denies a `git commit` that carries an AI/agent attribution trailer
-// (Co-Authored-By, "Generated with", "Claude-Session", and the like). The defect is fully
-// visible in the command text the tool is about to run, so this is a deterministic deny with
-// an escape hatch, never a prose reminder: the offending trailer is right there to point at.
-//
-// justification: no existing gate covers this. bash-commands denies destructive commands and
-// block-remote-publish denies pushes; neither inspects the commit MESSAGE for attribution.
-// lint-commit runs the linter on a commit but never reads the message text. This is the first
-// gate that reads what a commit says, not just that it is a commit.
-//
-// ── What a project can configure (params) ───────────────────────────────────────────
-//   attributionPatterns  regex sources (matched case-insensitively) of trailers/phrases
-//                        that must not appear in a commit message. Replaces the built-in
-//                        list wholesale, so a project that wants a different policy states
-//                        its full list.
-//   escapeHatch          a substring the author can put in the command to bypass this gate
-//                        for one legitimate commit (e.g. importing external history that
-//                        genuinely carries a co-author). Default '[allow-coauthor]'.
-//
-// ── How it detects a commit and reads its message ────────────────────────────────────
-// Reuses lint-commit's git-global-option normalization so `git -C /repo -c x=y commit` is
-// recognized as a commit. It then scans the WHOLE command text (which contains the -m value
-// or the heredoc body) for any attribution pattern — this over-includes on purpose (a match
-// inside an unrelated string is a rare false block the author clears with the escape hatch)
-// rather than under-includes (a real trailer slipping through in a shape we did not parse).
-//
-// ── Fail-safe shape ──────────────────────────────────────────────────────────────────
-// Not a commit: allow (silent). A commit with no attribution pattern: allow. A commit whose
-// text matches a pattern and does NOT contain the escape hatch: deny, naming the match.
+// no-coauthor — denies a `git commit` whose MESSAGE carries an AI/agent attribution
+// (Co-Authored-By, Claude-Session, "Generated with Claude"), and a delegation prompt that
+// orders one. The message is what the commit will record: -m values, a heredoc body,
+// --trailer values and a -F file read from the project. Only a command segment that RUNS git
+// commit counts (a `git log | grep Co-Authored-By` is not one). Deliberate limit: a message
+// built from a substitution (`-m "$(cat msg)"`) cannot be read without running it.
 
-import { runGate, deny, toolInGroups } from '../../lib/hook-io.mjs';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { projectRootOf } from '../../lib/config.mjs';
+import { hasRealCommandIntent } from '../../lib/delegation.mjs';
+import {
+  commitMessageOf,
+  isDryRunCommit,
+  isGitCommit,
+  normalizeGitCommand,
+} from '../../lib/git.mjs';
+import {
+  compileRegexList,
+  delegationPromptOf,
+  deny,
+  runGate,
+  shellCommandOf,
+  toolInGroups,
+} from '../../lib/hook-io.mjs';
 
 const GATE_ID = 'no-coauthor';
 const CONFIG_KEY = 'blockCoauthorTrailers';
 
-const SHELL_GROUPS = ['shell', 'delegation'];
-
-// Attribution trailers/phrases an AI agent tends to append. Sources, compiled case-insensitively.
+// Narrow on purpose: "generated by vitest" or "usage with Claude Code" in a subject line is
+// not an attribution; a trailer or a "generated with/by <an agent>" phrase is.
 const DEFAULT_ATTRIBUTION_PATTERNS = [
-  String.raw`co-authored-by:`,
-  String.raw`generated with`,
-  String.raw`generated by`,
-  String.raw`🤖 generated`,
+  String.raw`co-authored-by\s*[:=]`,
   String.raw`claude-session:`,
   String.raw`assisted-by:`,
   String.raw`authored-with:`,
-  String.raw`with claude code`,
+  String.raw`generated (?:with|by) (?:claude|ai|copilot|codex|cursor|gemini|chatgpt|an? (?:ai|llm|assistant)|a (?:bot|model))\b`,
+  String.raw`🤖 generated`,
 ];
 
 const DEFAULT_ESCAPE_HATCH = '[allow-coauthor]';
 
-// One global git option at a time, stripped repeatedly — same normalization lint-commit and
-// bash-commands use, so `git -C /repo -c x=y commit` reduces to `git commit` before matching.
-const GIT_OPTION_WITH_VALUE = String.raw`(?:-[Cc]|--git-dir|--work-tree|--namespace|--exec-path|--config-env)(?:\s+|=)\S+`;
-const GIT_FLAG_OPTION = String.raw`--(?:paginate|no-pager|bare|no-optional-locks)|-p`;
-const GIT_GLOBAL_OPTION_PATTERN = new RegExp(
-  String.raw`\bgit\s+(?:${GIT_OPTION_WITH_VALUE}|${GIT_FLAG_OPTION})\s+`,
-  'i',
-);
-const GIT_COMMIT_PATTERN = /\bgit\s+commit\b/i;
+// ── The commit segment ──────────────────────────────────────────────────────────────
+const SEGMENT_SEPARATOR = /;|&&|\|\||\||\n/;
+const ARGUMENT_PATTERN = /"([^"]*)"|'([^']*)'|(\S+)/g;
+const GIT_BINARY_TOKEN = /(?:^|[\\/])git(?:\.exe)?$/i;
+const WRAPPER_TOKEN = /^(?:\w+=\S*|command|sudo|env)$/i;
 
-function normalizeGitOptions(command) {
-  let previous;
-  let normalized = command;
-  do {
-    previous = normalized;
-    normalized = normalized.replace(GIT_GLOBAL_OPTION_PATTERN, 'git ');
-  } while (normalized !== previous);
-  return normalized;
+function runsGit(segment) {
+  const tokens = [];
+  for (const match of segment.matchAll(ARGUMENT_PATTERN))
+    tokens.push(match[1] ?? match[2] ?? match[3]);
+  while (tokens.length > 0 && WRAPPER_TOKEN.test(tokens[0])) tokens.shift();
+  return tokens.length > 0 && GIT_BINARY_TOKEN.test(tokens[0]);
 }
 
-function isGitCommit(command) {
-  return GIT_COMMIT_PATTERN.test(normalizeGitOptions(command));
+// A heredoc body spans lines, so the command is split only after the segment that opens it
+// has been recognized on its first line.
+function runsRealCommit(command) {
+  return String(command)
+    .split(SEGMENT_SEPARATOR)
+    .some((segment) => {
+      if (!runsGit(segment)) return false;
+      const normalized = normalizeGitCommand(segment);
+      return isGitCommit(normalized) && !isDryRunCommit(normalized);
+    });
 }
 
-function commandTextFrom(toolInput) {
-  return String(toolInput.CommandLine ?? toolInput.command ?? '');
-}
-
-/** The first attribution pattern the command text matches, or null when none does. */
-function matchedAttribution(command, attributionPatterns) {
-  for (const source of attributionPatterns) {
-    let pattern;
+function fileReader(root) {
+  return (path) => {
+    const resolved = resolve(root, path);
     try {
-      pattern = new RegExp(source, 'i');
+      return existsSync(resolved) ? readFileSync(resolved, 'utf8') : '';
     } catch {
-      // A malformed override pattern is skipped rather than crashing the gate; the rest of
-      // the list still protects.
-      continue;
+      return '';
     }
-    if (pattern.test(command)) return source;
+  };
+}
+
+function firstMatch(text, patterns) {
+  for (const pattern of patterns) {
+    const match = pattern.exec(text);
+    if (match) return match[0];
   }
   return null;
 }
 
+function denyAttribution(matched, escapeHatch) {
+  deny(
+    CONFIG_KEY,
+    `This commit message carries an AI/agent attribution ("${matched}"). Remove it — no ` +
+      'Co-Authored-By, no "Generated with", no session trailer. If this commit legitimately ' +
+      `must keep a co-author (e.g. importing external history), add "${escapeHatch}" to the ` +
+      `command to allow it once, or set attributionPatterns under ${CONFIG_KEY} in .ai/config.json.`,
+  );
+}
+
+function checkDelegationPrompt(prompt, patterns, escapeHatch) {
+  if (escapeHatch && prompt.includes(escapeHatch)) return;
+  const ordered = patterns.find((pattern) =>
+    hasRealCommandIntent(prompt, pattern),
+  );
+  if (ordered) denyAttribution(ordered.exec(prompt)[0], escapeHatch);
+}
+
+function checkShellCommand(command, patterns, escapeHatch, root) {
+  if (!runsRealCommit(command)) return;
+  if (escapeHatch && command.includes(escapeHatch)) return;
+  const message = commitMessageOf(command, { readFile: fileReader(root) });
+  const matched = firstMatch(message, patterns);
+  if (matched) denyAttribution(matched, escapeHatch);
+}
+
 runGate(
   {
     id: GATE_ID,
@@ -103,25 +121,27 @@ runGate(
       escapeHatch: DEFAULT_ESCAPE_HATCH,
     },
   },
-  ({ toolName, toolInput, parameters }) => {
-    if (!toolInGroups(toolName, SHELL_GROUPS)) return;
-
-    const command = commandTextFrom(toolInput);
-    if (!isGitCommit(command)) return;
+  ({ toolName, toolInput, parameters, cwd }) => {
+    const isShell = toolInGroups(toolName, ['shell']);
+    if (!isShell && !toolInGroups(toolName, ['delegation'])) return;
 
-    const escapeHatch = parameters.escapeHatch ?? DEFAULT_ESCAPE_HATCH;
-    if (escapeHatch && command.includes(escapeHatch)) return;
+    const escapeHatch = String(parameters.escapeHatch ?? '');
+    const { patterns } = compileRegexList(parameters.attributionPatterns);
+    if (patterns.length === 0) return;
 
-    const match = matchedAttribution(command, parameters.attributionPatterns);
-    if (!match) return;
-
-    deny(
-      CONFIG_KEY,
-      `This commit message carries an AI/agent attribution trailer (matched "${match}"). ` +
-        'Remove it — no Co-Authored-By, no "Generated with", no session trailer. If this ' +
-        `commit legitimately must keep a co-author (e.g. importing external history), add ` +
-        `"${escapeHatch}" to the command to allow it once, or set attributionPatterns/` +
-        'blockCoauthorTrailers in .ai/config.json.',
-    );
+    if (isShell) {
+      checkShellCommand(
+        shellCommandOf(toolInput),
+        patterns,
+        escapeHatch,
+        projectRootOf(cwd) ?? cwd,
+      );
+    } else {
+      checkDelegationPrompt(
+        delegationPromptOf(toolInput),
+        patterns,
+        escapeHatch,
+      );
+    }
   },
 );

package/plugins/gates/hooks/gates/no-explanatory-comments/index.mjs

@@ -0,0 +1,281 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { extname, isAbsolute, join } from 'node:path';
+import { projectRootOf } from '../../lib/config.mjs';
+import {
+  compileRegexList,
+  deny,
+  runGate,
+  toolInGroups,
+  writtenContentOf,
+  writtenPathOf,
+} from '../../lib/hook-io.mjs';
+import { withUnicodeWordBoundary } from '../../lib/signals.mjs';
+
+const GATE_ID = 'no-explanatory-comments';
+const CONFIG_KEY = 'blockExplanatoryComments';
+
+const SLASH_EXTENSIONS = [
+  '.js',
+  '.mjs',
+  '.cjs',
+  '.ts',
+  '.tsx',
+  '.jsx',
+  '.vue',
+  '.svelte',
+  '.go',
+  '.rs',
+  '.java',
+  '.kt',
+  '.cs',
+  '.swift',
+  '.c',
+  '.cc',
+  '.cpp',
+  '.h',
+  '.hpp',
+  '.php',
+  '.scss',
+  '.css',
+];
+const HASH_EXTENSIONS = ['.py', '.sh', '.bash', '.ps1', '.rb', '.pl', '.r'];
+const DASH_EXTENSIONS = ['.sql', '.lua'];
+
+const DEFAULT_DECISION_MARKERS = [
+  'because|why|so that|otherwise|instead of|rather than|trade-?offs?|decision|deliberate(?:ly)?|intentional(?:ly)?|on purpose',
+  "workaround|known (?:issue|limitation)|limitation|invariant|must(?: not| never)?|never|cannot|can't|do not|don't|avoid|guard(?:s|ed)?|edge cases?|race|compat\\p{L}*|legacy|deprecated|perf\\p{L}*|security|unsafe|fail-?(?:safe|open|closed)",
+  'porque|por qu[eé]|para que|si no|en vez de|en lugar de|decisi[oó]n|deliberad\\p{L}*|intencional\\p{L}*|a prop[oó]sito|limitaci[oó]n|invariante|nunca|no debe|evita\\p{L}*|compatibilidad|rendimiento|seguridad|casos? borde|justificaci[oó]n',
+];
+const DEFAULT_ESCAPE_HATCH = 'comment-ok:';
+const MAX_REPORTED = 5;
+const MAX_LINE_LENGTH = 90;
+
+const DIRECTIVE_PREFIXES = [
+  '#!',
+  '#pragma',
+  '#include',
+  '#define',
+  '#if',
+  '#endif',
+  '#else',
+  '#region',
+  '#endregion',
+  '#[',
+  '@license',
+  'spdx-',
+  'eslint',
+  'prettier',
+  'cspell',
+  '@ts-',
+  'c8 ',
+  'istanbul ',
+  'noqa',
+  'pylint',
+  'pyright',
+  'nolint',
+  'type:',
+  'neutral-spanish:allow',
+  'lint-ok:',
+  'justification:',
+  'justificación:',
+  'justificacion:',
+  'http://',
+  'https://',
+];
+const DIRECTIVE_WORD_PATTERN = /^(?:todo|fixme|hack|note|xxx)\b/i;
+const JSDOC_TAG_PATTERN =
+  /^@(?:type|typedef|template|deprecated|throws|see|example)\b|^@(?:param|returns?) \{/i;
+
+function isDirective(line) {
+  const lowered = line.trim().toLowerCase();
+  if (DIRECTIVE_PREFIXES.some((prefix) => lowered.startsWith(prefix)))
+    return true;
+  return (
+    DIRECTIVE_WORD_PATTERN.test(lowered) || JSDOC_TAG_PATTERN.test(lowered)
+  );
+}
+
+function commentStyleOf(filePath) {
+  const extension = extname(filePath).toLowerCase();
+  if (SLASH_EXTENSIONS.includes(extension)) return 'slash';
+  if (HASH_EXTENSIONS.includes(extension)) return 'hash';
+  if (DASH_EXTENSIONS.includes(extension)) return 'dash';
+  return null;
+}
+
+function stripLeading(text, characters) {
+  let start = 0;
+  while (start < text.length && characters.includes(text[start])) start += 1;
+  return text.slice(start);
+}
+
+function stripSlashMarkers(text) {
+  let body = text.trim();
+  if (body.endsWith('*/')) body = body.slice(0, -'*/'.length);
+  while (body.endsWith('*')) body = body.slice(0, -1);
+  if (body.startsWith('//')) body = stripLeading(body, '/');
+  else if (body.startsWith('/*')) body = stripLeading(body.slice(1), '*');
+  else body = stripLeading(body, '*');
+  return body.trim();
+}
+
+function slashComments(content) {
+  const units = [];
+  let block = null;
+  let lineRun = [];
+  const flushRun = () => {
+    if (lineRun.length > 0) units.push(lineRun);
+    lineRun = [];
+  };
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (block) {
+      block.push(stripSlashMarkers(line));
+      if (line.includes('*/')) {
+        units.push(block);
+        block = null;
+      }
+      continue;
+    }
+    const blockStart = line.indexOf('/*');
+    const quoteAt = line.search(/['"`]/);
+    if (blockStart !== -1 && (quoteAt === -1 || quoteAt > blockStart)) {
+      flushRun();
+      block = [stripSlashMarkers(line.slice(blockStart))];
+      if (line.indexOf('*/', blockStart + 2) !== -1) {
+        units.push(block);
+        block = null;
+      }
+      continue;
+    }
+    const lineStart = line.indexOf('//');
+    const isCommentLine = line.startsWith('//');
+    const isTrailing =
+      lineStart > 0 &&
+      !/['"`]/.test(line.slice(0, lineStart)) &&
+      !line.slice(0, lineStart).includes(':');
+    if (isCommentLine) {
+      lineRun.push(stripSlashMarkers(line));
+      continue;
+    }
+    flushRun();
+    if (isTrailing) units.push([stripSlashMarkers(line.slice(lineStart))]);
+  }
+  flushRun();
+  if (block) units.push(block);
+  return units;
+}
+
+function prefixComments(content, prefix) {
+  const units = [];
+  let run = [];
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.startsWith(prefix)) {
+      run.push(line.slice(prefix.length).trim());
+      continue;
+    }
+    if (run.length > 0) units.push(run);
+    run = [];
+    const at = line.indexOf(` ${prefix}`);
+    if (at > 0 && !/['"]/.test(line.slice(0, at)))
+      units.push([line.slice(at + prefix.length + 1).trim()]);
+  }
+  if (run.length > 0) units.push(run);
+  return units;
+}
+
+export function commentUnitsOf(content, filePath) {
+  const style = commentStyleOf(filePath);
+  if (style === 'slash') return slashComments(content);
+  if (style === 'hash') return prefixComments(content, '#');
+  if (style === 'dash') return prefixComments(content, '--');
+  return [];
+}
+
+function unitKey(unit) {
+  return unit
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join('\n');
+}
+
+function isAllowed(unit, markers, escapeHatch) {
+  const text = unitKey(unit);
+  if (!text) return true;
+  const lowered = text.toLowerCase();
+  if (escapeHatch && lowered.includes(escapeHatch.toLowerCase())) return true;
+  if (unit.some((line) => isDirective(line))) return true;
+  return markers.some((pattern) => pattern.test(text));
+}
+
+function previousContent(toolInput, absolutePath) {
+  if (typeof toolInput.old_string === 'string') return toolInput.old_string;
+  if (Array.isArray(toolInput.edits))
+    return toolInput.edits
+      .map((edit) => String(edit?.old_string ?? ''))
+      .join('\n');
+  if (!existsSync(absolutePath)) return '';
+  try {
+    return statSync(absolutePath).isFile()
+      ? readFileSync(absolutePath, 'utf8')
+      : '';
+  } catch {
+    return '';
+  }
+}
+
+function excerpt(unit) {
+  const text = unit.filter(Boolean).join(' ');
+  return text.length > MAX_LINE_LENGTH
+    ? `${text.slice(0, MAX_LINE_LENGTH)}…`
+    : text;
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      decisionMarkers: DEFAULT_DECISION_MARKERS,
+      escapeHatch: DEFAULT_ESCAPE_HATCH,
+    },
+  },
+  ({ toolName, toolInput, parameters, cwd }) => {
+    if (!toolInGroups(toolName, ['write'])) return;
+    const filePath = writtenPathOf(toolInput);
+    if (!commentStyleOf(filePath)) return;
+    const content = writtenContentOf(toolInput);
+    if (!content) return;
+    const root = projectRootOf(cwd) ?? cwd;
+    const absolutePath = isAbsolute(filePath) ? filePath : join(root, filePath);
+    const before = new Set(
+      commentUnitsOf(previousContent(toolInput, absolutePath), filePath).map(
+        unitKey,
+      ),
+    );
+    const markers = compileRegexList(
+      parameters.decisionMarkers,
+      'iu',
+    ).patterns.map((pattern) => withUnicodeWordBoundary(pattern.source));
+    const offending = commentUnitsOf(content, filePath)
+      .filter((unit) => !before.has(unitKey(unit)))
+      .filter((unit) => !isAllowed(unit, markers, parameters.escapeHatch));
+    if (offending.length === 0) return;
+    const shown = offending
+      .slice(0, MAX_REPORTED)
+      .map((unit) => `"${excerpt(unit)}"`);
+    const more =
+      offending.length > MAX_REPORTED
+        ? ` (+${offending.length - MAX_REPORTED} more)`
+        : '';
+    deny(
+      CONFIG_KEY,
+      `This write adds ${offending.length} comment(s) that explain what the code does instead of recording a ` +
+        `decision: ${shown.join('; ')}${more}. Make the code say it (a clearer name, a small extracted function) ` +
+        'and delete the comment, or keep only the WHY (start with because/porque, so that/para que, instead of/en vez de, ' +
+        `a trade-off or a known limitation). For a documented exception add "${parameters.escapeHatch} <reason>" in the comment.`,
+    );
+  },
+);