@marcomigozzi/trailhead 0.6.0 → 0.8.0

package/plugins/trailhead/hooks/lib/shell-scan.js

@@ -0,0 +1,247 @@
+'use strict';
+// shell-scan.js: shared quote-aware shell scanning helpers, extracted from
+// trailhead-search-guard.js (#135 follow-up) so trailhead's Bash-command
+// guards share ONE tokenizer/statement-splitter instead of drifting copies.
+// trailhead-secret-read-guard.js's original Bash leg used a naive
+// `.split(/\s+/)` tokenizer over the WHOLE command string, which let glued
+// shell metacharacters (`cat .env|grep KEY`, `cat .env;echo done`) slip past
+// detection entirely (a false negative in a security guard) and let a bare
+// `.env` inside multi-word quoted prose (`"document .env usage"`) trip a
+// false positive. This module's `splitStatements` + `tokenize` fix both: the
+// former is quote-aware and splits on operator characters regardless of
+// surrounding whitespace, the latter keeps a multi-word quoted phrase as ONE
+// opaque token instead of splitting it into separate words.
+//
+// Consumers: trailhead-search-guard.js and trailhead-secret-read-guard.js.
+// Self-contained, no external dependencies. Best-effort, like the guards that
+// use it: not a full shell parser, just enough to close their known gaps.
+
+// --- path helpers ------------------------------------------------------------
+
+function basename(p) {
+  const s = String(p).split('/');
+  return s[s.length - 1];
+}
+
+// --- quoting -----------------------------------------------------------------
+
+// Strip a single pair of enclosing quotes: the WHOLE token must start AND end
+// with the same quote character. A multi-word quoted phrase kept as one token
+// by tokenize() (below) round-trips through this to its bare content
+// (spaces and all) - callers testing that bare content against a basename
+// pattern then correctly see prose, not a path, unless the phrase IS exactly
+// a path (e.g. `".env"` -> `.env`, still flagged by design).
+function stripQuotes(t) {
+  const s = String(t);
+  if ((s.startsWith('"') && s.endsWith('"') && s.length >= 2) ||
+      (s.startsWith("'") && s.endsWith("'") && s.length >= 2)) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+// --- heredoc bodies ------------------------------------------------------------
+
+// Matches a heredoc introducer anywhere it can appear on a line: `<<TAG`,
+// `<<'TAG'`, `<<"TAG"`, and `<<-TAG` (which also allows the terminator line to
+// be indented with leading tabs). Captures the operator's `-` and the tag
+// (quoted or bare) separately.
+const HEREDOC_RE = /<<(-?)\s*(?:'([^']+)'|"([^"]+)"|([A-Za-z0-9_]+))/;
+
+// A heredoc BODY is literal data (e.g. a script being written to a file), not
+// shell statements executed in the current shell. Scan the command line by
+// line; whenever a line introduces a heredoc, skip every following line up to
+// and including the matching terminator line before it ever reaches the
+// statement splitter below. Handles multiple heredocs on the same command and
+// both quoted and unquoted tags. Best-effort: not a full shell parser.
+function stripHeredocBodies(cmd) {
+  const lines = String(cmd).split('\n');
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i];
+    out.push(line);
+    let m;
+    // A single line can introduce more than one heredoc (`cmd <<A <<B`); walk
+    // left to right and skip each body in turn.
+    while ((m = HEREDOC_RE.exec(line))) {
+      const dashStrip = m[1] === '-';
+      const tag = m[2] || m[3] || m[4];
+      line = line.slice(m.index + m[0].length); // keep scanning the rest of this line for more `<<TAG`s
+      if (!tag) break;
+      // Skip lines until the terminator: an exact match, or (for `<<-`) the
+      // tag preceded only by tabs.
+      while (i + 1 < lines.length) {
+        i++;
+        const body = lines[i];
+        const term = dashStrip ? body.replace(/^\t+/, '') : body;
+        if (term === tag) break; // terminator line: consumed, not a candidate statement either
+        // else: heredoc data line, deliberately NOT pushed to `out` - it must
+        // never become a candidate statement.
+      }
+    }
+  }
+  return out.join('\n');
+}
+
+// --- statement splitting -------------------------------------------------------
+
+// Split a shell string into top-level statements on `&&`, `||`, `;`, `|`, and
+// newlines, respecting single/double quotes (so a separator INSIDE a quoted
+// argument, e.g. a grep pattern, does not fracture the statement). Heredoc
+// bodies are stripped first (see stripHeredocBodies) so literal data written
+// via `<<TAG` is never mistaken for statements. Splitting is purely
+// character-driven (not whitespace-driven), so a glued separator with no
+// surrounding spaces (`cat .env|grep KEY`, `cat .env;echo done`) still splits
+// correctly. Best-effort: not a full shell parser, just enough to avoid the
+// common false splits.
+function splitStatements(cmd) {
+  const s = stripHeredocBodies(String(cmd));
+  const stmts = [];
+  let cur = '';
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (inSingle) {
+      cur += c;
+      if (c === "'") inSingle = false;
+      continue;
+    }
+    if (inDouble) {
+      cur += c;
+      if (c === '\\' && i + 1 < s.length) { cur += s[++i]; continue; } // escaped char stays literal
+      if (c === '"') inDouble = false;
+      continue;
+    }
+    if (c === "'") { inSingle = true; cur += c; continue; }
+    if (c === '"') { inDouble = true; cur += c; continue; }
+    if (c === '\\' && i + 1 < s.length) { cur += c + s[++i]; continue; }
+    if (c === '&' && s[i + 1] === '&') { stmts.push(cur); cur = ''; i++; continue; }
+    if (c === '|' && s[i + 1] === '|') { stmts.push(cur); cur = ''; i++; continue; }
+    if (c === ';' || c === '|' || c === '\n') { stmts.push(cur); cur = ''; continue; }
+    cur += c;
+  }
+  stmts.push(cur);
+  return stmts.map((t) => t.trim()).filter(Boolean);
+}
+
+// --- tokenizing ----------------------------------------------------------------
+
+// Quote-aware whitespace tokenizer: splits a statement on UNQUOTED
+// whitespace, keeping a `"..."`/`'...'` span - even a MULTI-WORD one - as a
+// single opaque token (quotes are kept in the token; stripQuotes() unwraps
+// them). This is what keeps quoted prose like `"document .env usage"` safe:
+// the whole phrase is one token, so a bare `.env` glued mid-phrase is never a
+// separate candidate token, while a lone quoted path like `".env"` still
+// round-trips to the bare `.env` via stripQuotes for basename testing.
+// Mirrors splitStatements' escape handling (`\"` inside a double-quoted span
+// stays literal, never closes the quote early). Best-effort: not a full shell
+// parser (a real shell also strips quotes/joins adjacent quoted+bare runs
+// into one word; this keeps the surrounding quotes intact instead, which is
+// enough for the callers' basename tests).
+function tokenize(stmt) {
+  const s = String(stmt).trim();
+  const tokens = [];
+  let cur = '';
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (inSingle) {
+      cur += c;
+      if (c === "'") inSingle = false;
+      continue;
+    }
+    if (inDouble) {
+      cur += c;
+      if (c === '\\' && i + 1 < s.length) { cur += s[++i]; continue; }
+      if (c === '"') inDouble = false;
+      continue;
+    }
+    if (c === "'") { inSingle = true; cur += c; continue; }
+    if (c === '"') { inDouble = true; cur += c; continue; }
+    if (c === '\\' && i + 1 < s.length) { cur += c + s[++i]; continue; }
+    if (/\s/.test(c)) {
+      if (cur) { tokens.push(cur); cur = ''; }
+      continue;
+    }
+    cur += c;
+  }
+  if (cur) tokens.push(cur);
+  return tokens;
+}
+
+function skipEnvPrefix(tokens) {
+  let i = 0;
+  while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i])) i++;
+  return i;
+}
+
+// --- search-verb argument scanning ----------------------------------------
+
+// grep/rg/ag/sed/awk take a PATTERN (or script/program) as their first
+// positional. Shared between the search guard (which skips the pattern before
+// flagging a relative FILE arg) and the secret-read guard (which skips the
+// pattern before flagging a SECRET FILE arg), so e.g. `grep ".env" config.txt`
+// is never mistaken for a `.env` read: the FILE operand is config.txt, the
+// PATTERN just happens to look like a secret path.
+const GREP_VALUE_FLAGS = new Set([
+  '-e', '-f', '-A', '-B', '-C', '-m', '-D',
+  '--include', '--exclude', '--exclude-dir', '--exclude-from',
+  '--after-context', '--before-context', '--context', '--max-count',
+]);
+
+// ripgrep has several value-taking flags GNU grep doesn't (glob/type filters,
+// column limits); without these, scanning treats their value as a plain
+// positional and misattributes it as the pattern/file in the block reason.
+const RG_VALUE_FLAGS = new Set([
+  ...GREP_VALUE_FLAGS,
+  '-g', '--glob', '-t', '--type', '-T', '--type-not', '-M', '--max-columns',
+]);
+
+const SEARCH_VERB_CONFIG = {
+  grep: { patternFirst: true, valueFlags: GREP_VALUE_FLAGS, patternFlags: new Set(['-e']) },
+  rg: { patternFirst: true, valueFlags: RG_VALUE_FLAGS, patternFlags: new Set(['-e']) },
+  ag: { patternFirst: true, valueFlags: GREP_VALUE_FLAGS, patternFlags: new Set(['-e']) },
+  sed: { patternFirst: true, valueFlags: new Set(['-e', '-f']), patternFlags: new Set(['-e']) },
+  awk: { patternFirst: true, valueFlags: new Set(['-f', '-v']), patternFlags: new Set() },
+};
+
+// Walk a verb's argument tokens (verb itself already stripped), skipping
+// flags (and their separate-token values), an explicit `--` end-of-options
+// marker (which must not itself swallow the next real positional), and the
+// leading pattern/script positional when the verb has one (`config.patternFirst`).
+// Returns the first token for which `isMatch(token)` is true, or null.
+// Generic over the predicate so both guards can drive it with their own
+// notion of "interesting" (a relative file arg vs. a secret path arg).
+function scanArgsSkippingPattern(args, config, isMatch) {
+  let patternConsumed = !config.patternFirst;
+  let afterDashDash = false; // once seen, every remaining token is positional, never a flag
+  for (let j = 0; j < args.length; j++) {
+    const t = args[j];
+    if (!afterDashDash && t === '--') { afterDashDash = true; continue; }
+    if (!afterDashDash && t.startsWith('-') && t !== '-') {
+      if (config.valueFlags.has(t)) {
+        j++; // consume its separate-token value
+        if (config.patternFlags && config.patternFlags.has(t)) patternConsumed = true;
+      }
+      continue;
+    }
+    if (!patternConsumed) { patternConsumed = true; continue; } // leading pattern/script positional
+    if (isMatch(t)) return t;
+  }
+  return null;
+}
+
+module.exports = {
+  basename,
+  stripQuotes,
+  stripHeredocBodies,
+  splitStatements,
+  tokenize,
+  skipEnvPrefix,
+  GREP_VALUE_FLAGS,
+  RG_VALUE_FLAGS,
+  SEARCH_VERB_CONFIG,
+  scanArgsSkippingPattern,
+};

package/plugins/trailhead/hooks/lib/shell-scan.test.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// Tests for shell-scan.js. Run: node shell-scan.test.js
+const assert = require('assert');
+const {
+  basename,
+  stripQuotes,
+  splitStatements,
+  tokenize,
+  scanArgsSkippingPattern,
+  SEARCH_VERB_CONFIG,
+} = require('./shell-scan.js');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// --- basename ---
+ok('basename strips leading dirs', basename('a/b/.env') === '.env');
+ok('basename passes through a bare name', basename('.env') === '.env');
+
+// --- stripQuotes ---
+ok('stripQuotes unwraps a double-quoted token', stripQuotes('".env"') === '.env');
+ok('stripQuotes unwraps a single-quoted token', stripQuotes("'.env'") === '.env');
+ok('stripQuotes leaves a bare token alone', stripQuotes('.env') === '.env');
+
+// --- splitStatements: glued metacharacters (no surrounding whitespace) ---
+ok('splitStatements splits a glued pipe', JSON.stringify(splitStatements('cat .env|grep KEY')) === JSON.stringify(['cat .env', 'grep KEY']));
+ok('splitStatements splits a glued semicolon', JSON.stringify(splitStatements('cat .env;echo done')) === JSON.stringify(['cat .env', 'echo done']));
+ok('splitStatements splits a glued &&', JSON.stringify(splitStatements('cat .env&&echo done')) === JSON.stringify(['cat .env', 'echo done']));
+ok('splitStatements keeps a quoted separator intact', JSON.stringify(splitStatements('grep "a;b" f.txt')) === JSON.stringify(['grep "a;b" f.txt']));
+
+// --- tokenize: quoted multi-word phrase stays ONE token ---
+ok('tokenize keeps a multi-word double-quoted phrase as one token',
+  JSON.stringify(tokenize('git commit -m "document .env usage"')) ===
+  JSON.stringify(['git', 'commit', '-m', '"document .env usage"']));
+ok('tokenize keeps a multi-word single-quoted phrase as one token',
+  JSON.stringify(tokenize("echo 'a b c'")) === JSON.stringify(['echo', "'a b c'"]));
+ok('tokenize round-trips a lone quoted path via stripQuotes',
+  stripQuotes(tokenize('cat ".env"')[1]) === '.env');
+ok('tokenize handles an escaped quote inside a double-quoted span without closing early',
+  JSON.stringify(tokenize('grep "a\\"b" f.txt')) === JSON.stringify(['grep', '"a\\"b"', 'f.txt']));
+
+// --- scanArgsSkippingPattern: search-verb pattern-positional skipping ---
+const isDotEnv = (t) => stripQuotes(t) === '.env';
+ok('scanArgsSkippingPattern skips the pattern positional (grep ".env" config.txt allows)',
+  scanArgsSkippingPattern(['".env"', 'config.txt'], SEARCH_VERB_CONFIG.grep, isDotEnv) === null);
+ok('scanArgsSkippingPattern still finds a secret FILE operand after the pattern',
+  scanArgsSkippingPattern(['-n', 'KEY', '.env'], SEARCH_VERB_CONFIG.grep, isDotEnv) === '.env');
+
+console.log(`✓ shell-scan: ${passed} assertions passed`);

package/plugins/trailhead/hooks/trailhead-commit-guard.js

@@ -31,12 +31,23 @@ function isGitCommit(cmd) {
   return toks[i] === 'commit';
 }
 
+// $(...) and backticks are the two command-substitution syntaxes. Inside a
+// double-quoted (or unquoted) value the shell expands them, so the text the
+// regex captured is shell syntax, not the real message -> fail open, or we'd
+// raise false positives on valid commits (#121). But a backslash-escaped
+// `\$(` / `` \` `` (an EVEN count preceding the marker means it is NOT escaped;
+// an ODD count means it is) is a LITERAL, fully-static message that must still
+// be validated, so only an UNESCAPED marker triggers fail-open. Inside single
+// quotes everything is literal, so the captured text is always the real message.
+const UNEXPANDABLE = /(?:^|[^\\])(?:\\\\)*(?:\$\(|`)/;
+
 function extractMessage(cmd) {
   // -m "…" / -m '…' / -m token / --message=…
   let m = cmd.match(/(?:^|\s)(?:-m|--message)(?:=|\s+)(["'])([\s\S]*?)\1/);
-  if (m) return m[2];
+  if (m) return (m[1] === '"' && UNEXPANDABLE.test(m[2])) ? null : m[2];
   m = cmd.match(/(?:^|\s)(?:-m|--message)(?:=|\s+)(\S+)/);
-  return m ? m[1] : null;
+  if (m) return UNEXPANDABLE.test(m[1]) ? null : m[1];
+  return null;
 }
 
 let data = '';

package/plugins/trailhead/hooks/trailhead-commit-guard.test.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// Tests for trailhead-commit-guard.js. Run: node trailhead-commit-guard.test.js
+// No framework: plain asserts + child_process for the end-to-end hook behaviour.
+const assert = require('assert');
+const { execFileSync } = require('child_process');
+const path = require('path');
+
+const HOOK = path.join(__dirname, 'trailhead-commit-guard.js');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// Run the hook end-to-end: pipe tool_input JSON on stdin, capture {code, out}.
+function runHook(command) {
+  const input = JSON.stringify({ tool_input: { command } });
+  try {
+    const out = execFileSync('node', [HOOK], { input });
+    return { code: 0, out: out.toString() };
+  } catch (e) {
+    return { code: e.status, out: (e.stdout || '').toString(), err: (e.stderr || '').toString() };
+  }
+}
+
+// --- regression #121: a command-substitution / heredoc -m carrying a VALID
+// conventional message must be ALLOWED, not blocked on the literal heredoc
+// syntax the guard cannot statically expand.
+const heredocCmd = [
+  'git commit -m "$(cat <<\'EOF\'',
+  'feat: something valid',
+  'EOF',
+  ')"',
+].join('\n');
+const r1 = runHook(heredocCmd);
+ok('command-substitution/heredoc -m with a valid message is allowed (exit 0)', r1.code === 0 && r1.out.trim() === '');
+
+// --- a backtick-containing -m value is allowed (fail open) ---
+const r2 = runHook('git commit -m "`echo feat: something valid`"');
+ok('backtick -m value is allowed (exit 0)', r2.code === 0 && r2.out.trim() === '');
+
+// --- a plain quoted VALID -m is still allowed ---
+const r3 = runHook('git commit -m "feat: something valid"');
+ok('plain quoted valid -m is allowed (exit 0)', r3.code === 0 && r3.out.trim() === '');
+
+// --- a plain quoted INVALID -m is still BLOCKED ---
+const r4 = runHook('git commit -m "not a conventional subject"');
+ok('plain quoted invalid -m is blocked (exit 2)', r4.code === 2 && /CONVENTIONAL_COMMITS_VIOLATION/.test(r4.out));
+
+// --- a Co-Authored-By trailer anywhere is still BLOCKED ---
+const r5 = runHook('git commit -m "feat: ok\n\nCo-Authored-By: Someone <a@b.c>"');
+ok('Co-Authored-By trailer is blocked (exit 2)', r5.code === 2 && /CO_AUTHORED_BY_FORBIDDEN/.test(r5.out));
+
+// --- a non-git-commit command is allowed ---
+const r6 = runHook('ls -la');
+ok('non-git-commit command is allowed (exit 0)', r6.code === 0 && r6.out.trim() === '');
+
+// --- code review follow-up (#121): single-quoted values are shell-literal,
+// so `$(` / backtick text inside single quotes is NOT expanded and must be
+// validated like any other message. A single-quoted bad message containing
+// `$(` must still be BLOCKED.
+const r7 = runHook("git commit -m '$(not a conventional subject)'");
+ok('single-quoted bad -m with $( is blocked (exit 2)', r7.code === 2 && /CONVENTIONAL_COMMITS_VIOLATION/.test(r7.out));
+
+// --- single-quoted bad message containing a backtick must still be BLOCKED ---
+const r8 = runHook("git commit -m 'has a ` backtick and is not conventional'");
+ok('single-quoted bad -m with a backtick is blocked (exit 2)', r8.code === 2 && /CONVENTIONAL_COMMITS_VIOLATION/.test(r8.out));
+
+// --- the `<<` sub-pattern was redundant and caused false negatives on
+// ordinary text like "a<<b"; it must be removed so this is BLOCKED ---
+const r9 = runHook('git commit -m "a<<b is not a conventional subject"');
+ok('double-quoted bad -m containing a<<b is blocked (exit 2)', r9.code === 2 && /CONVENTIONAL_COMMITS_VIOLATION/.test(r9.out));
+
+// --- regression guard: a single-quoted VALID conventional message is
+// still allowed ---
+const r10 = runHook("git commit -m 'feat: valid subject'");
+ok('single-quoted valid -m is allowed (exit 0)', r10.code === 0 && r10.out.trim() === '');
+
+// --- re-review follow-up (#121): a backslash-escaped `\$(` / `` \` `` inside
+// double quotes is a LITERAL, fully-static message (bash does not expand an
+// escaped marker), so it must be validated like any other message, not
+// fail-opened. A bad message using the escaped form must still be BLOCKED.
+const r11 = runHook('git commit -m "\\$(x) not conventional"');
+ok('double-quoted bad -m with escaped \\$( is blocked (exit 2)', r11.code === 2 && /CONVENTIONAL_COMMITS_VIOLATION/.test(r11.out));
+
+const r12 = runHook('git commit -m "\\`x\\` not conventional"');
+ok('double-quoted bad -m with escaped backticks is blocked (exit 2)', r12.code === 2 && /CONVENTIONAL_COMMITS_VIOLATION/.test(r12.out));
+
+const r13 = runHook('git commit --message="\\$(x) not conventional"');
+ok('--message= bad value with escaped \\$( is blocked (exit 2)', r13.code === 2 && /CONVENTIONAL_COMMITS_VIOLATION/.test(r13.out));
+
+// --- positive-path guard for the guard's HARD invariant (never a false
+// positive): a VALID conventional message that merely contains an escaped
+// `\$(` / `` \` `` marker must stay ALLOWED. Without these, a future regex
+// tweak could reintroduce the #121 false positive on the escaped-literal path
+// and no test would catch it.
+const r14 = runHook('git commit -m "fix: escape \\$(VAR) safely"');
+ok('double-quoted valid -m with escaped \\$( is allowed (exit 0)', r14.code === 0 && r14.out.trim() === '');
+
+const r15 = runHook('git commit -m "fix: rename \\`getUser\\` to \\`fetchUser\\`"');
+ok('double-quoted valid -m with escaped backticks is allowed (exit 0)', r15.code === 0 && r15.out.trim() === '');
+
+console.log(`✓ commit-guard: ${passed} assertions passed`);