Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

refactor(gateguard): split change profile and search filters into focused modules

Jeffrey Montoyab15c0538f6de
diff --git a/scripts/hooks/gateguard-fact-force.js b/scripts/hooks/gateguard-fact-force.js
index 3dc9ece8e..0d6bcf065 100644
--- a/scripts/hooks/gateguard-fact-force.js
+++ b/scripts/hooks/gateguard-fact-force.js
@@ -1640,7 +1640,7 @@ function markCheckedAndCountCredit(key, cls) {
}
// --- Trivial edits ---
-// see docs/gateguard/design-notes.md#trivial-edits
+// see docs/gateguard/change-profile.md#trivial-edits
const TRIVIAL_CLASSES = new Set(['code', 'test', 'prose']);
@@ -2132,7 +2132,7 @@ function subagentRestrictedDenial(filePath, data, isWrite) {
}
// --- Change profile ---
-// see docs/gateguard/design-notes.md#file-context
+// see docs/gateguard/change-profile.md#file-context
const MAX_CONTEXT_FILE_BYTES = 1024 * 1024;
diff --git a/scripts/lib/gateguard-change-profile.js b/scripts/lib/gateguard-change-profile.js
index 716088c03..89f655ca5 100644
--- a/scripts/lib/gateguard-change-profile.js
+++ b/scripts/lib/gateguard-change-profile.js
@@ -1,6 +1,9 @@
'use strict';
-// see docs/gateguard/design-notes.md#change-profile
+const { isSpace, isIdentChar, isLetter, shCodeLines, psCodeLines, batchCodeLines, normalizeShellLine } = require('./gateguard-code-lexer');
+const { MAX_FILE_CHARS, lineEndAt, lineStartOf, cFamilyStartsFresh, pythonStartsFresh, shStartsFresh, psStartsFresh, batchStartsFresh, trivialInFile } = require('./gateguard-file-context');
+
+// see docs/gateguard/change-profile.md#change-profile
const MAX_SIDE_BYTES = 64 * 1024;
const MAX_TOTAL_BYTES = 256 * 1024;
@@ -24,7 +27,7 @@ const LANGUAGE_BY_EXT = new Map([
]);
// --- Lexing ---
-// see docs/gateguard/design-notes.md#trivial-edits
+// see docs/gateguard/change-profile.md#trivial-edits
const C_FAMILY = { lineComment: '//', blockComment: true, quotes: '"\'', indentSensitive: false };
@@ -53,1204 +56,6 @@ function lexSpecFor(filePath, language) {
return TS_EXTS.has(base.slice(base.lastIndexOf('.'))) ? TS_SPEC : LEX_SPECS.js;
}
-function isSpace(ch) {
- return ch === ' ' || ch === '\t' || ch === '\f' || ch === '\v';
-}
-
-function isIdentChar(ch) {
- return ch !== undefined && ((ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') || (ch >= '0' && ch <= '9') || ch === '_' || ch === '$');
-}
-
-function isLetter(ch) {
- return ch !== undefined && ((ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z'));
-}
-
-function rustCharEnd(text, i) {
- if (text[i + 1] === '\\') {
- if (text[i + 2] === "'") return text[i + 3] === "'" ? i + 3 : -1;
- const end = text.indexOf("'", i + 3);
- return end !== -1 && end <= i + 12 ? end : -1;
- }
- const cp = text.codePointAt(i + 1);
- if (cp === undefined || text[i + 1] === '\n' || text[i + 1] === '\r' || text[i + 1] === "'") return -1;
- const end = i + (cp > 0xffff ? 3 : 2);
- return text[end] === "'" ? end : -1;
-}
-
-function stringPrefixIsUnsafe(code, spec) {
- const last = code[code.length - 1];
- if (spec.rawPrefixes && last !== undefined && spec.rawPrefixes.includes(last)) return true;
- if (!spec.fStrings || !isLetter(last)) return false;
- const prefix = isLetter(code[code.length - 2]) ? code.slice(-2) : last;
- return prefix.toLowerCase().includes('f');
-}
-
-// --- Directive comments ---
-// see docs/gateguard/design-notes.md#directive-comments
-
-const DIRECTIVE_LEADS = ['@', '#', '<', '+', '!', 'type:', 'global ', 'globals ', 'exported ', 'requires'];
-const DIRECTIVE_RAW_LEADS = ['!', '/', 'go:', 'export ', 'extern ', 'line '];
-const DIRECTIVE_WORDS = [
- 'lint', 'jshint', 'ts-', 'noqa', 'nosec', 'semgrep', 'sonar', 'noinspection', 'pragma', 'coding:', 'coding=', 'fmt:', 'isort:',
- 'mypy:', 'pyright:', 'pyre-', 'yapf:', 'ruff:', 'flake8', 'bandit', 'no cover', 'nocover', 'istanbul', 'c8 ', 'v8 ',
- 'prettier-', 'biome-', 'deno-', 'dprint-', 'rome-', 'webpack', 'vite-', '__pure__', '__no_side_effects__',
- '__inline__', '@preserve', '@license', 'sourcemappingurl', 'sourceurl', '+build', 'cgo', 'clang-', 'cppcheck',
- 'coverity', 'iwyu', 'fallthrough', 'fall through', 'fall-through', 'fallthru', 'fall thru', 'shellcheck',
- 'psscriptanalyzer', 'suppress', 'jscs', 'checkstyle', 'spotbugs', 'findbugs', 'nopmd', 'codeql', 'lgtm', 'gitleaks',
- 'trufflehog', 'detect-secrets', 'allowlist', 'vim:', 'vi:', ' ex:', '-*-', 'code generated', 'do not edit',
- 'rubocop', 'swiftlint', 'resharper', '@ts-', '@type', '@typedef', '@template', '@satisfies', '@import', '@callback',
- '@overload', '@enum', '@this', '@implements', '@extends', '@augments', '@jsx', '@flow', '@noflow', '@generated',
- 'compdef', 'autoload', 'output:'
-];
-
-function isDirectiveComment(body, spec) {
- if (spec.rustDocs && (body[0] === '/' || body[0] === '!' || body[0] === '*')) return true;
- if (DIRECTIVE_RAW_LEADS.some(lead => body.startsWith(lead))) return true;
- const lower = body.toLowerCase();
- let start = 0;
- while (start < lower.length && (isSpace(lower[start]) || lower[start] === '*' || lower[start] === '/')) start++;
- const lead = lower.slice(start);
- if (DIRECTIVE_LEADS.some(word => lead.startsWith(word))) return true;
- if (DIRECTIVE_WORDS.some(word => lower.includes(word))) return true;
- return lower.includes('@') && lower.includes('{');
-}
-
-function directiveMarker(body, spec) {
- return isDirectiveComment(body, spec) ? ` \u0001${Buffer.from(body, 'utf8').toString('hex')}\u0001 ` : '';
-}
-
-function endsWithContinuation(code) {
- let end = code.length;
- while (end > 0 && isSpace(code[end - 1])) end--;
- return code[end - 1] === '\\';
-}
-
-function lexCodeLines(text, spec) {
- const lines = [];
- let code = '';
- let state = 'code';
- let quote = '';
- let stringBody = '';
- let commentStart = 0;
- let tail = '';
- const append = piece => {
- code += piece;
- tail = (tail + piece).slice(-2);
- };
- const endComment = end => {
- const marker = directiveMarker(text.slice(commentStart, end), spec);
- if (marker) append(marker);
- };
- const endLine = () => {
- if (endsWithContinuation(code)) return false;
- lines.push(code);
- code = '';
- tail = '';
- return true;
- };
- if (spec.jsx !== undefined && text.startsWith('#!')) state = 'line';
- for (let i = 0; i < text.length; i++) {
- const ch = text[i];
- if (ch === '\n' || ch === '\r') {
- if (state === 'string') return null;
- if (state === 'line') {
- if (text.slice(commentStart, i).trimEnd().endsWith('\\')) return null;
- endComment(i);
- state = 'code';
- }
- if (state === 'block') {
- lines.push(code);
- code = '';
- tail = '';
- } else if (!endLine()) {
- return null;
- }
- if (ch === '\r' && text[i + 1] === '\n') i++;
- continue;
- }
- if (state === 'line') continue;
- if (state === 'block') {
- if (ch === '*' && text[i + 1] === '/') {
- endComment(i);
- state = 'code';
- append(' ');
- i++;
- } else if (ch === '/' && text[i + 1] === '*') {
- return null;
- }
- continue;
- }
- if (state === 'string') {
- append(ch);
- if (ch === '\\') {
- const next = text[i + 1];
- if (next === undefined || next === '\n' || next === '\r') return null;
- append(next);
- i++;
- } else if (ch === quote) {
- if (spec.noDollarInStrings && stringBody.includes('$')) return null;
- state = 'code';
- } else {
- stringBody += ch;
- }
- continue;
- }
- if (spec.lineComment === '//' && ch === '/' && text[i + 1] === '/') {
- state = 'line';
- commentStart = i + 2;
- i++;
- continue;
- }
- if (spec.lineComment === '#' && ch === '#') {
- state = 'line';
- commentStart = i + 1;
- continue;
- }
- if (spec.blockComment && ch === '/' && text[i + 1] === '*') {
- state = 'block';
- commentStart = i + 2;
- i++;
- continue;
- }
- if (spec.forbiddenCode && spec.forbiddenCode.includes(ch)) return null;
- if (spec.jsx && ch === '<' && (isLetter(text[i + 1]) || text[i + 1] === '/' || text[i + 1] === '>' || text[i + 1] === '!')) return null;
- if (spec.jsx !== undefined && ch === '-' && text[i + 1] === '-' && text[i + 2] === '>') return null;
- if (ch === "'" && spec.rustChars) {
- const end = rustCharEnd(text, i);
- append(end === -1 ? ch : text.slice(i, end + 1));
- if (end !== -1) i = end;
- continue;
- }
- if (spec.quotes.includes(ch)) {
- if (spec.tripleQuotes && text[i + 1] === ch && text[i + 2] === ch) return null;
- if (stringPrefixIsUnsafe(tail, spec)) return null;
- state = 'string';
- quote = ch;
- stringBody = '';
- append(ch);
- continue;
- }
- append(ch);
- }
- if (state === 'string' || state === 'block') return null;
- if (state === 'line') {
- if (text.slice(commentStart).trimEnd().endsWith('\\')) return null;
- endComment(text.length);
- }
- return endLine() ? lines : null;
-}
-
-function normalizeCodeLine(line, spec) {
- let out = '';
- let pendingSpace = false;
- let quote = '';
- let indent = '';
- let leading = true;
- for (let i = 0; i < line.length; i++) {
- const ch = line[i];
- if (quote) {
- out += ch;
- if (ch === '\\' && i + 1 < line.length) out += line[++i];
- else if (ch === quote) quote = '';
- continue;
- }
- if (isSpace(ch)) {
- if (leading) indent += ch;
- else pendingSpace = true;
- continue;
- }
- leading = false;
- if (pendingSpace && out) out += ' ';
- pendingSpace = false;
- if (ch === "'" && spec.rustChars) {
- const end = rustCharEnd(line, i);
- out += end === -1 ? ch : line.slice(i, end + 1);
- if (end !== -1) i = end;
- continue;
- }
- if (spec.quotes.includes(ch)) quote = ch;
- out += ch;
- }
- if (!out) return '';
- return spec.indentSensitive ? `${indent}\u0000${out}` : out;
-}
-
-function hasSpaceAfterContinuation(line) {
- let end = line.length;
- while (end > 0 && isSpace(line[end - 1])) end--;
- return end < line.length && line[end - 1] === '\\';
-}
-
-function codeSignature(text, spec) {
- const lines = spec.lexer ? spec.lexer(text) : lexCodeLines(text, spec);
- if (lines === null) return null;
- const signature = [];
- for (const line of lines) {
- if (hasSpaceAfterContinuation(line)) return null;
- const normalized = spec.normalize ? spec.normalize(line) : normalizeCodeLine(line, spec);
- if (normalized === null) return null;
- if (normalized) signature.push(normalized);
- }
- return signature;
-}
-
-function isTrivialEdit(oldString, newString, spec) {
- if (spec.lineComment === '//' && (oldString.includes('??/') || newString.includes('??/'))) return false;
- const before = codeSignature(oldString, spec);
- if (before === null) return false;
- const after = codeSignature(newString, spec);
- if (after === null || before.length !== after.length) return false;
- return before.every((line, index) => line === after[index]);
-}
-
-// --- File context ---
-// see docs/gateguard/design-notes.md#file-context
-
-const REPLACEMENT_PATTERN = /\$[$&'`<0-9]/;
-const MAX_FILE_CHARS = 1024 * 1024;
-const MAX_WINDOW_CHARS = 128 * 1024;
-const MAX_CONTEXT_WORK = 8 * 1024 * 1024;
-const JS_REGEX_KEYWORDS = new Set(['return', 'typeof', 'instanceof', 'in', 'of', 'new', 'delete', 'void', 'throw', 'case', 'do', 'else', 'yield', 'await']);
-const JS_CONTROL_HEADERS = new Set(['if', 'while', 'for', 'with']);
-const CPP_RAW_PREFIXES = new Set(['R', 'u8R', 'uR', 'UR', 'LR']);
-
-function isNewline(ch) {
- return ch === '\n' || ch === '\r';
-}
-
-function lineEndAt(text, i) {
- let j = i;
- while (j < text.length && !isNewline(text[j])) j++;
- return j;
-}
-
-function quotedEnd(text, i, quote, multiline) {
- for (let j = i + 1; j < text.length; j++) {
- const ch = text[j];
- if (ch === '\\') {
- j++;
- if (text[j] === '\r' && text[j + 1] === '\n') j++;
- } else if (ch === quote) {
- return j + 1;
- } else if (isNewline(ch) && !multiline) {
- return -1;
- }
- }
- return -1;
-}
-
-function regexEnd(text, i) {
- let inClass = false;
- for (let j = i + 1; j < text.length; j++) {
- const ch = text[j];
- if (isNewline(ch)) return -1;
- if (ch === '\\') {
- if (j + 1 >= text.length || isNewline(text[j + 1])) return -1;
- j++;
- } else if (inClass) {
- if (ch === ']') inClass = false;
- } else if (ch === '[') {
- inClass = true;
- } else if (ch === '/') {
- let k = j + 1;
- while (isIdentChar(text[k])) k++;
- return k;
- }
- }
- return -1;
-}
-
-function nestedBlockEnd(text, i) {
- let depth = 0;
- for (let j = i; j + 1 < text.length; j++) {
- if (text[j] === '/' && text[j + 1] === '*') {
- depth++;
- j++;
- } else if (text[j] === '*' && text[j + 1] === '/') {
- depth--;
- j++;
- if (depth === 0) return j + 1;
- }
- }
- return -1;
-}
-
-function textBlockEnd(text, i, escapes) {
- for (let j = i + 3; j < text.length; j++) {
- if (escapes && text[j] === '\\') {
- j++;
- } else if (!escapes && text[j] === '$' && text[j + 1] === '{') {
- return -1;
- } else if (text.startsWith('"""', j)) {
- let end = j + 3;
- while (text[end] === '"') end++;
- return end;
- }
- }
- return -1;
-}
-
-function kotlinStringEnd(text, i) {
- for (let j = i + 1; j < text.length; j++) {
- const ch = text[j];
- if (ch === '\\') j++;
- else if (ch === '$' && text[j + 1] === '{') return -1;
- else if (ch === '"') return j + 1;
- else if (isNewline(ch)) return -1;
- }
- return -1;
-}
-
-function csharpStringEnd(text, i) {
- let j = i;
- let verbatim = false;
- let interpolated = false;
- while (text[j] === '@' || text[j] === '$') {
- if (text[j] === '@') verbatim = true;
- else interpolated = true;
- j++;
- }
- if (text.startsWith('"""', j)) return -1;
- for (let k = j + 1; k < text.length; k++) {
- const ch = text[k];
- if (ch === '"') {
- if (verbatim && text[k + 1] === '"') {
- k++;
- continue;
- }
- return k + 1;
- }
- if (!verbatim && ch === '\\') {
- k++;
- } else if (!verbatim && isNewline(ch)) {
- return -1;
- } else if (interpolated && ch === '{') {
- if (text[k + 1] === '{') {
- k++;
- continue;
- }
- let m = k + 1;
- while (m < text.length && text[m] !== '}') {
- if ('"\'{/\n\r'.includes(text[m])) return -1;
- m++;
- }
- if (m >= text.length) return -1;
- k = m;
- }
- }
- return -1;
-}
-
-function cppRawEnd(text, quote) {
- const open = text.indexOf('(', quote + 1);
- if (open === -1 || open - quote - 1 > 16) return -1;
- const delimiter = text.slice(quote + 1, open);
- for (const ch of delimiter) {
- if (isSpace(ch) || isNewline(ch) || '()\\"'.includes(ch)) return -1;
- }
- const end = text.indexOf(`)${delimiter}"`, open + 1);
- return end === -1 ? -1 : end + delimiter.length + 2;
-}
-
-function rustRawEnd(text, i) {
- let j = i + (text[i] === 'r' ? 1 : 2);
- let hashes = '';
- while (text[j] === '#') {
- hashes += '#';
- j++;
- }
- if (text[j] !== '"') return null;
- const end = text.indexOf(`"${hashes}`, j + 1);
- return end === -1 ? -1 : end + 1 + hashes.length;
-}
-
-function wordStart(text, i) {
- let start = i;
- while (start > 0 && isIdentChar(text[start - 1])) start--;
- return start;
-}
-
-function cFamilyStringEnd(text, i, spec) {
- const ch = text[i];
- const flavor = spec.flavor;
- if (ch === '`') {
- if (flavor === 'kotlin') return quotedEnd(text, i, '`', false);
- if (flavor !== 'go') return -1;
- const end = text.indexOf('`', i + 1);
- return end === -1 ? -1 : end + 1;
- }
- if (ch === "'") {
- if (flavor === 'rust') {
- const end = rustCharEnd(text, i);
- return end === -1 ? null : end + 1;
- }
- if (flavor === 'c' && isIdentChar(text[i - 1]) && isIdentChar(text[i + 1])) {
- const first = text[wordStart(text, i)];
- if (first >= '0' && first <= '9') return null;
- }
- return quotedEnd(text, i, "'", false);
- }
- if (flavor === 'c') {
- const start = wordStart(text, i);
- const prefix = text.slice(start, i);
- if (CPP_RAW_PREFIXES.has(prefix)) return cppRawEnd(text, i);
- if (prefix.endsWith('R')) return -1;
- }
- if (flavor === 'java' && text.startsWith('"""', i)) return textBlockEnd(text, i, true);
- if (flavor === 'kotlin') return text.startsWith('"""', i) ? textBlockEnd(text, i, false) : kotlinStringEnd(text, i);
- if (flavor === 'csharp' && text.startsWith('"""', i)) return -1;
- return quotedEnd(text, i, '"', flavor === 'rust');
-}
-
-function cFamilyStartsFresh(text, spec) {
- const js = spec.flavor === 'js';
- const frames = [{ template: false, depth: 0 }];
- const parens = [];
- let lastWord = '';
- let lastSig = 'op';
- let lineEnd = '';
- let continued = false;
- let i = js && text.startsWith('#!') ? lineEndAt(text, 0) : 0;
- while (i < text.length) {
- const frame = frames[frames.length - 1];
- const ch = text[i];
- const next = text[i + 1];
- if (frame.template) {
- if (ch === '\\') {
- i += 2;
- } else if (ch === '`') {
- frames.pop();
- lastSig = 'value';
- i++;
- } else if (ch === '$' && next === '{') {
- frames.push({ template: false, depth: 0 });
- lastSig = 'op';
- i += 2;
- } else {
- i++;
- }
- continue;
- }
- if (isNewline(ch)) {
- continued = lineEnd === '\\';
- lineEnd = '';
- i++;
- continue;
- }
- if (isSpace(ch)) {
- i++;
- continue;
- }
- if (ch === '/' && next === '/') {
- const end = lineEndAt(text, i);
- if (text.slice(i, end).trimEnd().endsWith('\\')) return false;
- i = end;
- continue;
- }
- if (ch === '/' && next === '*') {
- const end = spec.rustDocs ? nestedBlockEnd(text, i) : text.indexOf('*/', i + 2);
- if (end === -1) return false;
- i = spec.rustDocs ? end : end + 2;
- lineEnd = '';
- continue;
- }
- lineEnd = ch;
- if (js) {
- if (ch === '`') {
- frames.push({ template: true, depth: 0 });
- i++;
- continue;
- }
- if (ch === '/') {
- if (lastSig === 'op') {
- const end = regexEnd(text, i);
- if (end === -1) return false;
- lineEnd = text[end - 1];
- lastSig = 'value';
- i = end;
- continue;
- }
- if (lastSig === 'close' && /[/'"`]/.test(text.slice(i + 1, lineEndAt(text, i)))) return false;
- lastSig = 'op';
- i++;
- continue;
- }
- if (ch === '<' && (next === '!' || (spec.jsx && (isLetter(next) || next === '/' || next === '>')))) return false;
- if (ch === '-' && next === '-' && text[i + 2] === '>') return false;
- if (frames.length > 1 && ch === '{') frame.depth++;
- if (frames.length > 1 && ch === '}') {
- if (frame.depth === 0) {
- frames.pop();
- i++;
- continue;
- }
- frame.depth--;
- }
- }
- if (spec.flavor === 'csharp' && (ch === '@' || ch === '$') && /^[@$]{1,3}"/.test(text.slice(i, i + 4))) {
- const end = csharpStringEnd(text, i);
- if (end === -1) return false;
- lineEnd = '"';
- i = end;
- continue;
- }
- if (spec.flavor === 'rust' && (ch === 'r' || ((ch === 'b' || ch === 'c') && next === 'r')) && !isIdentChar(text[i - 1])) {
- const end = rustRawEnd(text, i);
- if (end === -1) return false;
- if (end !== null) {
- lineEnd = text[end - 1];
- lastSig = 'value';
- i = end;
- continue;
- }
- }
- if (ch === '"' || ch === "'" || ch === '`') {
- const end = cFamilyStringEnd(text, i, spec);
- if (end === -1) return false;
- if (end !== null) {
- lineEnd = text[end - 1];
- lastSig = 'value';
- i = end;
- continue;
- }
- i++;
- continue;
- }
- if (isIdentChar(ch)) {
- let end = i;
- while (end < text.length && isIdentChar(text[end])) end++;
- lastWord = text.slice(i, end);
- lastSig = js && JS_REGEX_KEYWORDS.has(lastWord) ? 'op' : 'value';
- lineEnd = text[end - 1];
- i = end;
- continue;
- }
- if (ch === '(') {
- parens.push(lastSig === 'value' && JS_CONTROL_HEADERS.has(lastWord));
- lastSig = 'op';
- } else if (ch === ')') {
- lastSig = parens.pop() ? 'op' : 'value';
- } else {
- lastSig = ch === '}' ? 'close' : ch === ']' ? 'value' : 'op';
- }
- lastWord = '';
- i++;
- }
- return frames.length === 1 && !continued;
-}
-
-function pythonStringEnd(text, i, prefix) {
- const quote = text[i];
- const triple = text[i + 1] === quote && text[i + 2] === quote;
- const fString = prefix.toLowerCase().includes('f');
- let depth = 0;
- for (let j = i + (triple ? 3 : 1); j < text.length; j++) {
- const ch = text[j];
- if (fString && depth > 0) {
- if (ch === '{') {
- depth++;
- } else if (ch === '}') {
- depth--;
- } else if ((ch === '"' || ch === "'") && ch !== quote) {
- let k = j + 1;
- while (k < text.length && text[k] !== ch) {
- if (text[k] === quote || text[k] === '\\' || isNewline(text[k])) return -1;
- k++;
- }
- if (k >= text.length) return -1;
- j = k;
- } else if (ch === quote || ch === '#' || ch === '\\' || isNewline(ch)) {
- return -1;
- }
- continue;
- }
- if (ch === '\\') {
- j++;
- if (text[j] === '\r' && text[j + 1] === '\n') j++;
- } else if (fString && ch === '{') {
- if (text[j + 1] === '{') j++;
- else depth = 1;
- } else if (isNewline(ch) && !triple) {
- return -1;
- } else if (ch === quote && (!triple || (text[j + 1] === quote && text[j + 2] === quote))) {
- return j + (triple ? 3 : 1);
- }
- }
- return -1;
-}
-
-function pythonStartsFresh(text) {
- let lineEnd = '';
- let continued = false;
- let i = 0;
- while (i < text.length) {
- const ch = text[i];
- if (isNewline(ch)) {
- continued = lineEnd === '\\';
- lineEnd = '';
- i++;
- } else if (isSpace(ch)) {
- i++;
- } else if (ch === '#') {
- i = lineEndAt(text, i);
- } else if (ch === '"' || ch === "'") {
- const start = wordStart(text, i);
- const prefix = text.slice(start, i);
- if (prefix.length > 2 || /[^rbuf]/i.test(prefix)) return false;
- const end = pythonStringEnd(text, i, prefix);
- if (end === -1) return false;
- lineEnd = ch;
- i = end;
- } else {
- lineEnd = ch;
- i++;
- }
- }
- return !continued;
-}
-
-function heredocDelimiter(text, i) {
- let j = i + 2;
- const stripTabs = text[j] === '-';
- if (stripTabs) j++;
- while (isBlank(text[j])) j++;
- let word = '';
- while (j < text.length && !isBlank(text[j]) && !isNewline(text[j]) && !';|&<>()'.includes(text[j])) {
- if (!'\'"\\'.includes(text[j])) word += text[j];
- j++;
- }
- return word ? { word, stripTabs, end: j } : null;
-}
-
-function skipHeredocs(text, i, pending) {
- let at = i;
- for (const doc of pending) {
- for (;;) {
- if (at >= text.length) return -1;
- const end = lineEndAt(text, at);
- let line = text.slice(at, end);
- if (doc.stripTabs) line = line.replace(/^\t+/, '');
- at = end + (text[end] === '\r' && text[end + 1] === '\n' ? 2 : 1);
- if (line === doc.word) break;
- }
- }
- return at;
-}
-
-const MAX_NESTING = 8;
-
-function shSingleQuoteEnd(text, i) {
- if (text[i - 1] === '$') return quotedEnd(text, i, "'", true);
- return text.indexOf("'", i + 1) + 1 || -1;
-}
-
-function shSubstitutionEnd(text, i, level) {
- if (level > MAX_NESTING) return -1;
- let depth = 0;
- for (let j = i + 1; j < text.length; j++) {
- const ch = text[j];
- if (ch === '\\') {
- j++;
- } else if (ch === '(') {
- depth++;
- } else if (ch === ')') {
- depth--;
- if (depth === 0) return j + 1;
- } else if (ch === "'" || ch === '"') {
- const end = ch === "'" ? shSingleQuoteEnd(text, j) : shDoubleQuoteScan(text, j, level + 1);
- if (end === -1) return -1;
- j = end - 1;
- } else if (ch === '`' || (ch === '<' && text[j + 1] === '<') || (ch === '#' && hashStartsComment(text, j) !== false)) {
- return -1;
- } else if (ch === 'c' && text.startsWith('case', j) && !isIdentChar(text[j - 1]) && !isIdentChar(text[j + 4])) {
- return -1;
- }
- }
- return -1;
-}
-
-function shDoubleQuoteScan(text, i, level) {
- for (let j = i + 1; j < text.length; j++) {
- const ch = text[j];
- if (ch === '"') return j + 1;
- if (ch === '\\') {
- j++;
- } else if (ch === '`') {
- return -1;
- } else if (ch === '$' && text[j + 1] === '(') {
- const end = shSubstitutionEnd(text, j, level);
- if (end === -1) return -1;
- j = end - 1;
- } else if (ch === '$' && text[j + 1] === '{') {
- const close = text.indexOf('}', j + 2);
- if (close === -1 || /["'\n\r]/.test(text.slice(j + 2, close))) return -1;
- j = close;
- }
- }
- return -1;
-}
-
-function shStartsFresh(text) {
- if (hasLoneCarriageReturn(text)) return false;
- const pending = [];
- let lineEnd = '';
- let continued = false;
- let i = 0;
- while (i < text.length) {
- const ch = text[i];
- if (isNewline(ch)) {
- continued = lineEnd === '\\';
- lineEnd = '';
- i += ch === '\r' && text[i + 1] === '\n' ? 2 : 1;
- if (pending.length > 0) {
- i = skipHeredocs(text, i, pending);
- if (i === -1) return false;
- pending.length = 0;
- }
- continue;
- }
- if (isBlank(ch)) {
- i++;
- continue;
- }
- lineEnd = ch;
- if (ch === '\\') {
- i += isNewline(text[i + 1]) ? 1 : 2;
- } else if (ch === "'") {
- const end = shSingleQuoteEnd(text, i);
- if (end === -1) return false;
- i = end;
- } else if (ch === '"') {
- const end = shDoubleQuoteScan(text, i, 0);
- if (end === -1) return false;
- i = end;
- } else if (ch === '`') {
- const end = text.indexOf('`', i + 1);
- if (end === -1 || /['"\\#\n\r]/.test(text.slice(i + 1, end))) return false;
- i = end + 1;
- } else if (ch === '#') {
- const starts = hashStartsComment(text, i);
- if (starts === null) return false;
- i = starts ? lineEndAt(text, i) : i + 1;
- if (starts) lineEnd = '';
- } else if (ch === '<' && text[i + 1] === '<') {
- if (text[i + 2] === '<') {
- i += 3;
- continue;
- }
- const doc = heredocDelimiter(text, i);
- if (!doc) return false;
- pending.push(doc);
- i = doc.end;
- } else {
- i++;
- }
- }
- return !continued && pending.length === 0;
-}
-
-function psSingleQuoteEnd(text, i) {
- for (let j = i + 1; j < text.length; j++) {
- if (text[j] !== "'") continue;
- if (text[j + 1] !== "'") return j + 1;
- j++;
- }
- return -1;
-}
-
-function psSubexpressionEnd(text, i, level) {
- if (level > MAX_NESTING) return -1;
- let depth = 0;
- for (let j = i + 1; j < text.length; j++) {
- const ch = text[j];
- if (ch === '`') {
- j++;
- } else if (ch === '(') {
- depth++;
- } else if (ch === ')') {
- depth--;
- if (depth === 0) return j + 1;
- } else if (ch === "'" || ch === '"') {
- const end = ch === "'" ? psSingleQuoteEnd(text, j) : psDoubleQuoteScan(text, j, level + 1);
- if (end === -1) return -1;
- j = end - 1;
- } else if (ch === '#' || (ch === '@' && (text[j + 1] === '"' || text[j + 1] === "'"))) {
- return -1;
- }
- }
- return -1;
-}
-
-function psDoubleQuoteScan(text, i, level) {
- for (let j = i + 1; j < text.length; j++) {
- const ch = text[j];
- if (ch === '`') {
- j++;
- } else if (ch === '$' && text[j + 1] === '(') {
- const end = psSubexpressionEnd(text, j, level);
- if (end === -1) return -1;
- j = end - 1;
- } else if (ch === '"') {
- if (text[j + 1] !== '"') return j + 1;
- j++;
- }
- }
- return -1;
-}
-
-function psStartsFresh(text) {
- if (PS_SMART_QUOTES.test(text)) return false;
- let lineEnd = '';
- let continued = false;
- let i = 0;
- while (i < text.length) {
- const ch = text[i];
- const next = text[i + 1];
- if (isNewline(ch)) {
- continued = lineEnd === '`';
- lineEnd = '';
- i++;
- continue;
- }
- if (isBlank(ch)) {
- i++;
- continue;
- }
- lineEnd = ch;
- if (ch === '`') {
- i += isNewline(next) ? 1 : 2;
- } else if (ch === '@' && (next === '"' || next === "'")) {
- const open = lineEndAt(text, i);
- if (text.slice(i + 2, open).trim() !== '') return false;
- let at = open;
- let found = -1;
- while (at < text.length) {
- at += text[at] === '\r' && text[at + 1] === '\n' ? 2 : 1;
- if (text.startsWith(`${next}@`, at)) {
- found = at + 2;
- break;
- }
- at = lineEndAt(text, at);
- }
- if (found === -1) return false;
- i = found;
- } else if (ch === "'" || ch === '"') {
- const end = ch === "'" ? psSingleQuoteEnd(text, i) : psDoubleQuoteScan(text, i, 0);
- if (end === -1) return false;
- i = end;
- } else if (ch === '<' && next === '#') {
- if (!psHashStartsComment(text, i)) return false;
- const end = text.indexOf('#>', i + 2);
- if (end === -1) return false;
- i = end + 2;
- lineEnd = '';
- } else if (ch === '#') {
- if (psHashStartsComment(text, i)) {
- i = lineEndAt(text, i);
- lineEnd = '';
- } else if (isIdentChar(text[i - 1]) || '-.:'.includes(text[i - 1])) {
- i++;
- } else {
- return false;
- }
- } else {
- i++;
- }
- }
- return !continued;
-}
-
-function batchStartsFresh(text) {
- const lines = text.split(/\r\n|\r|\n/);
- const last = lines.length > 1 ? lines[lines.length - 2] : '';
- return !last.endsWith('^');
-}
-
-function lineStartOf(text, i) {
- let start = i;
- while (start > 0 && !isNewline(text[start - 1])) start--;
- return start;
-}
-
-function windowStart(text, at) {
- const start = lineStartOf(text, at);
- if (start === 0) return 0;
- let end = start - 1;
- if (text[end] === '\n' && text[end - 1] === '\r') end--;
- return lineStartOf(text, end);
-}
-
-function windowEnd(text, at) {
- const end = lineEndAt(text, at);
- if (end >= text.length) return text.length;
- return end + (text[end] === '\r' && text[end + 1] === '\n' ? 2 : 1);
-}
-
-function occurrences(text, needle, replaceAll) {
- const first = text.indexOf(needle);
- if (first === -1) return null;
- let last = first;
- for (let at = text.indexOf(needle, first + needle.length); at !== -1; at = text.indexOf(needle, at + needle.length)) {
- if (!replaceAll) return null;
- last = at;
- }
- return { first, last };
-}
-
-function trivialInFile(pairs, fileText, spec) {
- if (typeof fileText !== 'string' || fileText.length > MAX_FILE_CHARS || !spec.startsFresh) return false;
- if (spec.flavor === 'go' && fileText.includes('"C"')) return false;
- let text = fileText;
- let work = 0;
- for (const [oldString, newString, replaceAll] of pairs) {
- if (!oldString || REPLACEMENT_PATTERN.test(newString)) return false;
- const found = occurrences(text, oldString, replaceAll);
- if (!found) return false;
- const start = windowStart(text, found.first);
- const end = windowEnd(text, found.last + oldString.length);
- work += start + 2 * (end - start);
- if (end - start > MAX_WINDOW_CHARS || work > MAX_CONTEXT_WORK || !spec.startsFresh(text.slice(0, start), spec)) return false;
- const before = text.slice(start, end);
- const after = replaceAll
- ? before.split(oldString).join(newString)
- : `${text.slice(start, found.first)}${newString}${text.slice(found.first + oldString.length, end)}`;
- if (!isTrivialEdit(before, after, spec)) return false;
- text = `${text.slice(0, start)}${after}${text.slice(end)}`;
- if (text.length > MAX_FILE_CHARS) return false;
- }
- return true;
-}
-
-// --- Shell lexing ---
-// see docs/gateguard/design-notes.md#shell-scripts
-
-const SHELL_SPEC = Object.freeze({});
-
-function isLineStart(text, i) {
- return i === 0 || text[i - 1] === '\n' || text[i - 1] === '\r';
-}
-
-function hashStartsComment(text, i) {
- if (isLineStart(text, i)) return true;
- const prev = text[i - 1];
- if (prev === ' ' || prev === '\t' || prev === ';') return true;
- return '()|&<>'.includes(prev) ? null : false;
-}
-
-function shDoubleQuoteEnd(text, i) {
- for (let j = i + 1; j < text.length; j++) {
- const ch = text[j];
- if (ch === '"') return j;
- if (ch === '\n' || ch === '\r' || ch === '`') return -1;
- if (ch === '\\') {
- if (j + 1 >= text.length || text[j + 1] === '\n' || text[j + 1] === '\r') return -1;
- j++;
- } else if (ch === '$' && text[j + 1] === '(') {
- return -1;
- } else if (ch === '$' && text[j + 1] === '{') {
- const close = text.indexOf('}', j + 2);
- if (close === -1) return -1;
- for (let k = j + 2; k < close; k++) {
- if ('"\'\n\r'.includes(text[k])) return -1;
- }
- j = close;
- }
- }
- return -1;
-}
-
-function hasLoneCarriageReturn(text) {
- for (let at = text.indexOf('\r'); at !== -1; at = text.indexOf('\r', at + 1)) {
- if (text[at + 1] !== '\n') return true;
- }
- return false;
-}
-
-function isBlank(ch) {
- return ch === ' ' || ch === '\t';
-}
-
-function shCodeLines(text) {
- if (text.includes('<<') || text.includes('`') || hasLoneCarriageReturn(text)) return null;
- const lines = [];
- let code = '';
- for (let i = 0; i < text.length; i++) {
- const ch = text[i];
- if (ch === '\n' || ch === '\r') {
- lines.push(code);
- code = '';
- if (ch === '\r' && text[i + 1] === '\n') i++;
- continue;
- }
- if (ch === '\\') {
- const next = text[i + 1];
- if (next === undefined || next === '\n' || next === '\r') return null;
- code += ch + next;
- i++;
- continue;
- }
- if (ch === "'") {
- if (text[i - 1] === '$') return null;
- const end = text.indexOf("'", i + 1);
- if (end === -1) return null;
- const body = text.slice(i, end + 1);
- if (body.includes('\n') || body.includes('\r')) return null;
- code += body;
- i = end;
- continue;
- }
- if (ch === '"') {
- const end = shDoubleQuoteEnd(text, i);
- if (end === -1) return null;
- code += text.slice(i, end + 1);
- i = end;
- continue;
- }
- if (ch === '#') {
- const starts = hashStartsComment(text, i);
- if (starts === null) return null;
- if (starts) {
- const start = i + 1;
- while (i + 1 < text.length && text[i + 1] !== '\n' && text[i + 1] !== '\r') i++;
- code += directiveMarker(text.slice(start, i + 1), SHELL_SPEC);
- continue;
- }
- }
- code += ch;
- }
- lines.push(code);
- return lines;
-}
-
-const PS_SMART_QUOTES = /[\u2018\u2019\u201a\u201b\u201c\u201d\u201e]/;
-
-function psHashStartsComment(text, i) {
- if (isLineStart(text, i)) return true;
- const prev = text[i - 1];
- return prev === ' ' || prev === '\t' || prev === ';';
-}
-
-function psQuoteEnd(text, i) {
- const quote = text[i];
- for (let j = i + 1; j < text.length; j++) {
- const ch = text[j];
- if (ch === '\n' || ch === '\r') return -1;
- if (quote === '"' && ch === '`') {
- if (j + 1 >= text.length || text[j + 1] === '\n' || text[j + 1] === '\r') return -1;
- j++;
- } else if (quote === '"' && ch === '$' && text[j + 1] === '(') {
- return -1;
- } else if (ch === quote) {
- if (text[j + 1] !== quote) return j;
- j++;
- }
- }
- return -1;
-}
-
-function psCodeLines(text) {
- if (text.includes('@"') || text.includes("@'") || PS_SMART_QUOTES.test(text)) return null;
- const lines = [];
- let code = '';
- let block = false;
- let blockStart = 0;
- for (let i = 0; i < text.length; i++) {
- const ch = text[i];
- if (ch === '\n' || ch === '\r') {
- lines.push(code);
- code = '';
- if (ch === '\r' && text[i + 1] === '\n') i++;
- continue;
- }
- if (block) {
- if (ch === '<' && text[i + 1] === '#') return null;
- if (ch === '#' && text[i + 1] === '>') {
- block = false;
- code += directiveMarker(text.slice(blockStart, i), SHELL_SPEC) || ' ';
- i++;
- }
- continue;
- }
- if (ch === '`') {
- const next = text[i + 1];
- if (next === undefined || next === '\n' || next === '\r') return null;
- code += ch + next;
- i++;
- continue;
- }
- if (ch === "'" || ch === '"') {
- const end = psQuoteEnd(text, i);
- if (end === -1) return null;
- code += text.slice(i, end + 1);
- i = end;
- continue;
- }
- if (ch === '<' && text[i + 1] === '#') {
- if (!psHashStartsComment(text, i)) return null;
- block = true;
- blockStart = i + 2;
- i++;
- continue;
- }
- if (ch === '#') {
- if (!psHashStartsComment(text, i)) return null;
- const start = i + 1;
- while (i + 1 < text.length && text[i + 1] !== '\n' && text[i + 1] !== '\r') i++;
- code += directiveMarker(text.slice(start, i + 1), SHELL_SPEC);
- continue;
- }
- code += ch;
- }
- if (block) return null;
- lines.push(code);
- return lines;
-}
-
-function batchCodeLines(text) {
- const lines = [];
- for (const line of text.split(/\r\n|\r|\n/)) {
- if (line.endsWith('^')) return null;
- let start = 0;
- while (isBlank(line[start])) start++;
- if (line[start] === '@') start++;
- while (isBlank(line[start])) start++;
- const word = line.slice(start, start + 3).toLowerCase();
- const after = line[start + 3];
- if (word === 'rem' && (after === undefined || isBlank(after))) {
- if (/[%^&|<>()]/.test(line)) return null;
- lines.push(directiveMarker(line.slice(start + 4), SHELL_SPEC));
- } else {
- lines.push(line.trim() ? line : '');
- }
- }
- return lines;
-}
-
-function normalizeShellLine(line, escape) {
- let out = '';
- let pendingSpace = false;
- for (let i = 0; i < line.length; i++) {
- const ch = line[i];
- if (isBlank(ch)) {
- pendingSpace = true;
- continue;
- }
- if (pendingSpace && out) out += ' ';
- pendingSpace = false;
- if (ch === escape && i + 1 < line.length) {
- out += ch + line[++i];
- } else if (ch === "'" || ch === '"') {
- const end = escape === '`' ? psQuoteEnd(line, i) : ch === "'" ? line.indexOf("'", i + 1) : shDoubleQuoteEnd(line, i);
- if (end === -1) return null;
- out += line.slice(i, end + 1);
- i = end;
- } else {
- out += ch;
- }
- }
- return out;
-}
-
// --- Public surface ---
function leadingWord(text, word) {
@@ -1392,7 +197,7 @@ function textTouchesSurface(text, lineIsSurface) {
}
// --- Container members ---
-// see docs/gateguard/design-notes.md#public-surface
+// see docs/gateguard/change-profile.md#public-surface
const MAX_OPENER_SCAN = 4 * 1024 * 1024;
const JS_BODY_KINDS = ['function', 'async'];
diff --git a/scripts/lib/gateguard-code-lexer.js b/scripts/lib/gateguard-code-lexer.js
new file mode 100644
index 000000000..ab855f492
--- /dev/null
+++ b/scripts/lib/gateguard-code-lexer.js
@@ -0,0 +1,503 @@
+'use strict';
+
+// --- Code lines ---
+// see docs/gateguard/change-profile.md#trivial-edits
+
+function isSpace(ch) {
+ return ch === ' ' || ch === '\t' || ch === '\f' || ch === '\v';
+}
+
+function isIdentChar(ch) {
+ return ch !== undefined && ((ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') || (ch >= '0' && ch <= '9') || ch === '_' || ch === '$');
+}
+
+function isLetter(ch) {
+ return ch !== undefined && ((ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z'));
+}
+
+function rustCharEnd(text, i) {
+ if (text[i + 1] === '\\') {
+ if (text[i + 2] === "'") return text[i + 3] === "'" ? i + 3 : -1;
+ const end = text.indexOf("'", i + 3);
+ return end !== -1 && end <= i + 12 ? end : -1;
+ }
+ const cp = text.codePointAt(i + 1);
+ if (cp === undefined || text[i + 1] === '\n' || text[i + 1] === '\r' || text[i + 1] === "'") return -1;
+ const end = i + (cp > 0xffff ? 3 : 2);
+ return text[end] === "'" ? end : -1;
+}
+
+function stringPrefixIsUnsafe(code, spec) {
+ const last = code[code.length - 1];
+ if (spec.rawPrefixes && last !== undefined && spec.rawPrefixes.includes(last)) return true;
+ if (!spec.fStrings || !isLetter(last)) return false;
+ const prefix = isLetter(code[code.length - 2]) ? code.slice(-2) : last;
+ return prefix.toLowerCase().includes('f');
+}
+
+// --- Directive comments ---
+// see docs/gateguard/change-profile.md#directive-comments
+
+const DIRECTIVE_LEADS = ['@', '#', '<', '+', '!', 'type:', 'global ', 'globals ', 'exported ', 'requires'];
+const DIRECTIVE_RAW_LEADS = ['!', '/', 'go:', 'export ', 'extern ', 'line '];
+const DIRECTIVE_WORDS = [
+ 'lint', 'jshint', 'ts-', 'noqa', 'nosec', 'semgrep', 'sonar', 'noinspection', 'pragma', 'coding:', 'coding=', 'fmt:', 'isort:',
+ 'mypy:', 'pyright:', 'pyre-', 'yapf:', 'ruff:', 'flake8', 'bandit', 'no cover', 'nocover', 'istanbul', 'c8 ', 'v8 ',
+ 'prettier-', 'biome-', 'deno-', 'dprint-', 'rome-', 'webpack', 'vite-', '__pure__', '__no_side_effects__',
+ '__inline__', '@preserve', '@license', 'sourcemappingurl', 'sourceurl', '+build', 'cgo', 'clang-', 'cppcheck',
+ 'coverity', 'iwyu', 'fallthrough', 'fall through', 'fall-through', 'fallthru', 'fall thru', 'shellcheck',
+ 'psscriptanalyzer', 'suppress', 'jscs', 'checkstyle', 'spotbugs', 'findbugs', 'nopmd', 'codeql', 'lgtm', 'gitleaks',
+ 'trufflehog', 'detect-secrets', 'allowlist', 'vim:', 'vi:', ' ex:', '-*-', 'code generated', 'do not edit',
+ 'rubocop', 'swiftlint', 'resharper', '@ts-', '@type', '@typedef', '@template', '@satisfies', '@import', '@callback',
+ '@overload', '@enum', '@this', '@implements', '@extends', '@augments', '@jsx', '@flow', '@noflow', '@generated',
+ 'compdef', 'autoload', 'output:'
+];
+
+function isDirectiveComment(body, spec) {
+ if (spec.rustDocs && (body[0] === '/' || body[0] === '!' || body[0] === '*')) return true;
+ if (DIRECTIVE_RAW_LEADS.some(lead => body.startsWith(lead))) return true;
+ const lower = body.toLowerCase();
+ let start = 0;
+ while (start < lower.length && (isSpace(lower[start]) || lower[start] === '*' || lower[start] === '/')) start++;
+ const lead = lower.slice(start);
+ if (DIRECTIVE_LEADS.some(word => lead.startsWith(word))) return true;
+ if (DIRECTIVE_WORDS.some(word => lower.includes(word))) return true;
+ return lower.includes('@') && lower.includes('{');
+}
+
+function directiveMarker(body, spec) {
+ return isDirectiveComment(body, spec) ? ` \u0001${Buffer.from(body, 'utf8').toString('hex')}\u0001 ` : '';
+}
+
+function endsWithContinuation(code) {
+ let end = code.length;
+ while (end > 0 && isSpace(code[end - 1])) end--;
+ return code[end - 1] === '\\';
+}
+
+function lexCodeLines(text, spec) {
+ const lines = [];
+ let code = '';
+ let state = 'code';
+ let quote = '';
+ let stringBody = '';
+ let commentStart = 0;
+ let tail = '';
+ const append = piece => {
+ code += piece;
+ tail = (tail + piece).slice(-2);
+ };
+ const endComment = end => {
+ const marker = directiveMarker(text.slice(commentStart, end), spec);
+ if (marker) append(marker);
+ };
+ const endLine = () => {
+ if (endsWithContinuation(code)) return false;
+ lines.push(code);
+ code = '';
+ tail = '';
+ return true;
+ };
+ if (spec.jsx !== undefined && text.startsWith('#!')) state = 'line';
+ for (let i = 0; i < text.length; i++) {
+ const ch = text[i];
+ if (ch === '\n' || ch === '\r') {
+ if (state === 'string') return null;
+ if (state === 'line') {
+ if (text.slice(commentStart, i).trimEnd().endsWith('\\')) return null;
+ endComment(i);
+ state = 'code';
+ }
+ if (state === 'block') {
+ lines.push(code);
+ code = '';
+ tail = '';
+ } else if (!endLine()) {
+ return null;
+ }
+ if (ch === '\r' && text[i + 1] === '\n') i++;
+ continue;
+ }
+ if (state === 'line') continue;
+ if (state === 'block') {
+ if (ch === '*' && text[i + 1] === '/') {
+ endComment(i);
+ state = 'code';
+ append(' ');
+ i++;
+ } else if (ch === '/' && text[i + 1] === '*') {
+ return null;
+ }
+ continue;
+ }
+ if (state === 'string') {
+ append(ch);
+ if (ch === '\\') {
+ const next = text[i + 1];
+ if (next === undefined || next === '\n' || next === '\r') return null;
+ append(next);
+ i++;
+ } else if (ch === quote) {
+ if (spec.noDollarInStrings && stringBody.includes('$')) return null;
+ state = 'code';
+ } else {
+ stringBody += ch;
+ }
+ continue;
+ }
+ if (spec.lineComment === '//' && ch === '/' && text[i + 1] === '/') {
+ state = 'line';
+ commentStart = i + 2;
+ i++;
+ continue;
+ }
+ if (spec.lineComment === '#' && ch === '#') {
+ state = 'line';
+ commentStart = i + 1;
+ continue;
+ }
+ if (spec.blockComment && ch === '/' && text[i + 1] === '*') {
+ state = 'block';
+ commentStart = i + 2;
+ i++;
+ continue;
+ }
+ if (spec.forbiddenCode && spec.forbiddenCode.includes(ch)) return null;
+ if (spec.jsx && ch === '<' && (isLetter(text[i + 1]) || text[i + 1] === '/' || text[i + 1] === '>' || text[i + 1] === '!')) return null;
+ if (spec.jsx !== undefined && ch === '-' && text[i + 1] === '-' && text[i + 2] === '>') return null;
+ if (ch === "'" && spec.rustChars) {
+ const end = rustCharEnd(text, i);
+ append(end === -1 ? ch : text.slice(i, end + 1));
+ if (end !== -1) i = end;
+ continue;
+ }
+ if (spec.quotes.includes(ch)) {
+ if (spec.tripleQuotes && text[i + 1] === ch && text[i + 2] === ch) return null;
+ if (stringPrefixIsUnsafe(tail, spec)) return null;
+ state = 'string';
+ quote = ch;
+ stringBody = '';
+ append(ch);
+ continue;
+ }
+ append(ch);
+ }
+ if (state === 'string' || state === 'block') return null;
+ if (state === 'line') {
+ if (text.slice(commentStart).trimEnd().endsWith('\\')) return null;
+ endComment(text.length);
+ }
+ return endLine() ? lines : null;
+}
+
+function normalizeCodeLine(line, spec) {
+ let out = '';
+ let pendingSpace = false;
+ let quote = '';
+ let indent = '';
+ let leading = true;
+ for (let i = 0; i < line.length; i++) {
+ const ch = line[i];
+ if (quote) {
+ out += ch;
+ if (ch === '\\' && i + 1 < line.length) out += line[++i];
+ else if (ch === quote) quote = '';
+ continue;
+ }
+ if (isSpace(ch)) {
+ if (leading) indent += ch;
+ else pendingSpace = true;
+ continue;
+ }
+ leading = false;
+ if (pendingSpace && out) out += ' ';
+ pendingSpace = false;
+ if (ch === "'" && spec.rustChars) {
+ const end = rustCharEnd(line, i);
+ out += end === -1 ? ch : line.slice(i, end + 1);
+ if (end !== -1) i = end;
+ continue;
+ }
+ if (spec.quotes.includes(ch)) quote = ch;
+ out += ch;
+ }
+ if (!out) return '';
+ return spec.indentSensitive ? `${indent}\u0000${out}` : out;
+}
+
+function hasSpaceAfterContinuation(line) {
+ let end = line.length;
+ while (end > 0 && isSpace(line[end - 1])) end--;
+ return end < line.length && line[end - 1] === '\\';
+}
+
+function codeSignature(text, spec) {
+ const lines = spec.lexer ? spec.lexer(text) : lexCodeLines(text, spec);
+ if (lines === null) return null;
+ const signature = [];
+ for (const line of lines) {
+ if (hasSpaceAfterContinuation(line)) return null;
+ const normalized = spec.normalize ? spec.normalize(line) : normalizeCodeLine(line, spec);
+ if (normalized === null) return null;
+ if (normalized) signature.push(normalized);
+ }
+ return signature;
+}
+
+function isTrivialEdit(oldString, newString, spec) {
+ if (spec.lineComment === '//' && (oldString.includes('??/') || newString.includes('??/'))) return false;
+ const before = codeSignature(oldString, spec);
+ if (before === null) return false;
+ const after = codeSignature(newString, spec);
+ if (after === null || before.length !== after.length) return false;
+ return before.every((line, index) => line === after[index]);
+}
+
+
+// --- Shell lexing ---
+// see docs/gateguard/change-profile.md#shell-scripts
+
+const SHELL_SPEC = Object.freeze({});
+
+function isLineStart(text, i) {
+ return i === 0 || text[i - 1] === '\n' || text[i - 1] === '\r';
+}
+
+function hashStartsComment(text, i) {
+ if (isLineStart(text, i)) return true;
+ const prev = text[i - 1];
+ if (prev === ' ' || prev === '\t' || prev === ';') return true;
+ return '()|&<>'.includes(prev) ? null : false;
+}
+
+function shDoubleQuoteEnd(text, i) {
+ for (let j = i + 1; j < text.length; j++) {
+ const ch = text[j];
+ if (ch === '"') return j;
+ if (ch === '\n' || ch === '\r' || ch === '`') return -1;
+ if (ch === '\\') {
+ if (j + 1 >= text.length || text[j + 1] === '\n' || text[j + 1] === '\r') return -1;
+ j++;
+ } else if (ch === '$' && text[j + 1] === '(') {
+ return -1;
+ } else if (ch === '$' && text[j + 1] === '{') {
+ const close = text.indexOf('}', j + 2);
+ if (close === -1) return -1;
+ for (let k = j + 2; k < close; k++) {
+ if ('"\'\n\r'.includes(text[k])) return -1;
+ }
+ j = close;
+ }
+ }
+ return -1;
+}
+
+function hasLoneCarriageReturn(text) {
+ for (let at = text.indexOf('\r'); at !== -1; at = text.indexOf('\r', at + 1)) {
+ if (text[at + 1] !== '\n') return true;
+ }
+ return false;
+}
+
+function isBlank(ch) {
+ return ch === ' ' || ch === '\t';
+}
+
+function shCodeLines(text) {
+ if (text.includes('<<') || text.includes('`') || hasLoneCarriageReturn(text)) return null;
+ const lines = [];
+ let code = '';
+ for (let i = 0; i < text.length; i++) {
+ const ch = text[i];
+ if (ch === '\n' || ch === '\r') {
+ lines.push(code);
+ code = '';
+ if (ch === '\r' && text[i + 1] === '\n') i++;
+ continue;
+ }
+ if (ch === '\\') {
+ const next = text[i + 1];
+ if (next === undefined || next === '\n' || next === '\r') return null;
+ code += ch + next;
+ i++;
+ continue;
+ }
+ if (ch === "'") {
+ if (text[i - 1] === '$') return null;
+ const end = text.indexOf("'", i + 1);
+ if (end === -1) return null;
+ const body = text.slice(i, end + 1);
+ if (body.includes('\n') || body.includes('\r')) return null;
+ code += body;
+ i = end;
+ continue;
+ }
+ if (ch === '"') {
+ const end = shDoubleQuoteEnd(text, i);
+ if (end === -1) return null;
+ code += text.slice(i, end + 1);
+ i = end;
+ continue;
+ }
+ if (ch === '#') {
+ const starts = hashStartsComment(text, i);
+ if (starts === null) return null;
+ if (starts) {
+ const start = i + 1;
+ while (i + 1 < text.length && text[i + 1] !== '\n' && text[i + 1] !== '\r') i++;
+ code += directiveMarker(text.slice(start, i + 1), SHELL_SPEC);
+ continue;
+ }
+ }
+ code += ch;
+ }
+ lines.push(code);
+ return lines;
+}
+
+const PS_SMART_QUOTES = /[\u2018\u2019\u201a\u201b\u201c\u201d\u201e]/;
+
+function psHashStartsComment(text, i) {
+ if (isLineStart(text, i)) return true;
+ const prev = text[i - 1];
+ return prev === ' ' || prev === '\t' || prev === ';';
+}
+
+function psQuoteEnd(text, i) {
+ const quote = text[i];
+ for (let j = i + 1; j < text.length; j++) {
+ const ch = text[j];
+ if (ch === '\n' || ch === '\r') return -1;
+ if (quote === '"' && ch === '`') {
+ if (j + 1 >= text.length || text[j + 1] === '\n' || text[j + 1] === '\r') return -1;
+ j++;
+ } else if (quote === '"' && ch === '$' && text[j + 1] === '(') {
+ return -1;
+ } else if (ch === quote) {
+ if (text[j + 1] !== quote) return j;
+ j++;
+ }
+ }
+ return -1;
+}
+
+function psCodeLines(text) {
+ if (text.includes('@"') || text.includes("@'") || PS_SMART_QUOTES.test(text)) return null;
+ const lines = [];
+ let code = '';
+ let block = false;
+ let blockStart = 0;
+ for (let i = 0; i < text.length; i++) {
+ const ch = text[i];
+ if (ch === '\n' || ch === '\r') {
+ lines.push(code);
+ code = '';
+ if (ch === '\r' && text[i + 1] === '\n') i++;
+ continue;
+ }
+ if (block) {
+ if (ch === '<' && text[i + 1] === '#') return null;
+ if (ch === '#' && text[i + 1] === '>') {
+ block = false;
+ code += directiveMarker(text.slice(blockStart, i), SHELL_SPEC) || ' ';
+ i++;
+ }
+ continue;
+ }
+ if (ch === '`') {
+ const next = text[i + 1];
+ if (next === undefined || next === '\n' || next === '\r') return null;
+ code += ch + next;
+ i++;
+ continue;
+ }
+ if (ch === "'" || ch === '"') {
+ const end = psQuoteEnd(text, i);
+ if (end === -1) return null;
+ code += text.slice(i, end + 1);
+ i = end;
+ continue;
+ }
+ if (ch === '<' && text[i + 1] === '#') {
+ if (!psHashStartsComment(text, i)) return null;
+ block = true;
+ blockStart = i + 2;
+ i++;
+ continue;
+ }
+ if (ch === '#') {
+ if (!psHashStartsComment(text, i)) return null;
+ const start = i + 1;
+ while (i + 1 < text.length && text[i + 1] !== '\n' && text[i + 1] !== '\r') i++;
+ code += directiveMarker(text.slice(start, i + 1), SHELL_SPEC);
+ continue;
+ }
+ code += ch;
+ }
+ if (block) return null;
+ lines.push(code);
+ return lines;
+}
+
+function batchCodeLines(text) {
+ const lines = [];
+ for (const line of text.split(/\r\n|\r|\n/)) {
+ if (line.endsWith('^')) return null;
+ let start = 0;
+ while (isBlank(line[start])) start++;
+ if (line[start] === '@') start++;
+ while (isBlank(line[start])) start++;
+ const word = line.slice(start, start + 3).toLowerCase();
+ const after = line[start + 3];
+ if (word === 'rem' && (after === undefined || isBlank(after))) {
+ if (/[%^&|<>()]/.test(line)) return null;
+ lines.push(directiveMarker(line.slice(start + 4), SHELL_SPEC));
+ } else {
+ lines.push(line.trim() ? line : '');
+ }
+ }
+ return lines;
+}
+
+function normalizeShellLine(line, escape) {
+ let out = '';
+ let pendingSpace = false;
+ for (let i = 0; i < line.length; i++) {
+ const ch = line[i];
+ if (isBlank(ch)) {
+ pendingSpace = true;
+ continue;
+ }
+ if (pendingSpace && out) out += ' ';
+ pendingSpace = false;
+ if (ch === escape && i + 1 < line.length) {
+ out += ch + line[++i];
+ } else if (ch === "'" || ch === '"') {
+ const end = escape === '`' ? psQuoteEnd(line, i) : ch === "'" ? line.indexOf("'", i + 1) : shDoubleQuoteEnd(line, i);
+ if (end === -1) return null;
+ out += line.slice(i, end + 1);
+ i = end;
+ } else {
+ out += ch;
+ }
+ }
+ return out;
+}
+
+
+module.exports = {
+ isSpace,
+ isIdentChar,
+ isLetter,
+ rustCharEnd,
+ isBlank,
+ hashStartsComment,
+ hasLoneCarriageReturn,
+ PS_SMART_QUOTES,
+ psHashStartsComment,
+ isTrivialEdit,
+ shCodeLines,
+ psCodeLines,
+ batchCodeLines,
+ normalizeShellLine
+};
diff --git a/scripts/lib/gateguard-file-context.js b/scripts/lib/gateguard-file-context.js
new file mode 100644
index 000000000..67996fd2a
--- /dev/null
+++ b/scripts/lib/gateguard-file-context.js
@@ -0,0 +1,734 @@
+'use strict';
+
+const { isSpace, isIdentChar, isLetter, rustCharEnd, isBlank, hashStartsComment, hasLoneCarriageReturn, PS_SMART_QUOTES, psHashStartsComment, isTrivialEdit } = require('./gateguard-code-lexer');
+
+// --- File context ---
+// see docs/gateguard/change-profile.md#file-context
+
+const REPLACEMENT_PATTERN = /\$[$&'`<0-9]/;
+const MAX_FILE_CHARS = 1024 * 1024;
+const MAX_WINDOW_CHARS = 128 * 1024;
+const MAX_CONTEXT_WORK = 8 * 1024 * 1024;
+const JS_REGEX_KEYWORDS = new Set(['return', 'typeof', 'instanceof', 'in', 'of', 'new', 'delete', 'void', 'throw', 'case', 'do', 'else', 'yield', 'await']);
+const JS_CONTROL_HEADERS = new Set(['if', 'while', 'for', 'with']);
+const CPP_RAW_PREFIXES = new Set(['R', 'u8R', 'uR', 'UR', 'LR']);
+
+function isNewline(ch) {
+ return ch === '\n' || ch === '\r';
+}
+
+function lineEndAt(text, i) {
+ let j = i;
+ while (j < text.length && !isNewline(text[j])) j++;
+ return j;
+}
+
+function quotedEnd(text, i, quote, multiline) {
+ for (let j = i + 1; j < text.length; j++) {
+ const ch = text[j];
+ if (ch === '\\') {
+ j++;
+ if (text[j] === '\r' && text[j + 1] === '\n') j++;
+ } else if (ch === quote) {
+ return j + 1;
+ } else if (isNewline(ch) && !multiline) {
+ return -1;
+ }
+ }
+ return -1;
+}
+
+function regexEnd(text, i) {
+ let inClass = false;
+ for (let j = i + 1; j < text.length; j++) {
+ const ch = text[j];
+ if (isNewline(ch)) return -1;
+ if (ch === '\\') {
+ if (j + 1 >= text.length || isNewline(text[j + 1])) return -1;
+ j++;
+ } else if (inClass) {
+ if (ch === ']') inClass = false;
+ } else if (ch === '[') {
+ inClass = true;
+ } else if (ch === '/') {
+ let k = j + 1;
+ while (isIdentChar(text[k])) k++;
+ return k;
+ }
+ }
+ return -1;
+}
+
+function nestedBlockEnd(text, i) {
+ let depth = 0;
+ for (let j = i; j + 1 < text.length; j++) {
+ if (text[j] === '/' && text[j + 1] === '*') {
+ depth++;
+ j++;
+ } else if (text[j] === '*' && text[j + 1] === '/') {
+ depth--;
+ j++;
+ if (depth === 0) return j + 1;
+ }
+ }
+ return -1;
+}
+
+function textBlockEnd(text, i, escapes) {
+ for (let j = i + 3; j < text.length; j++) {
+ if (escapes && text[j] === '\\') {
+ j++;
+ } else if (!escapes && text[j] === '$' && text[j + 1] === '{') {
+ return -1;
+ } else if (text.startsWith('"""', j)) {
+ let end = j + 3;
+ while (text[end] === '"') end++;
+ return end;
+ }
+ }
+ return -1;
+}
+
+function kotlinStringEnd(text, i) {
+ for (let j = i + 1; j < text.length; j++) {
+ const ch = text[j];
+ if (ch === '\\') j++;
+ else if (ch === '$' && text[j + 1] === '{') return -1;
+ else if (ch === '"') return j + 1;
+ else if (isNewline(ch)) return -1;
+ }
+ return -1;
+}
+
+function csharpStringEnd(text, i) {
+ let j = i;
+ let verbatim = false;
+ let interpolated = false;
+ while (text[j] === '@' || text[j] === '$') {
+ if (text[j] === '@') verbatim = true;
+ else interpolated = true;
+ j++;
+ }
+ if (text.startsWith('"""', j)) return -1;
+ for (let k = j + 1; k < text.length; k++) {
+ const ch = text[k];
+ if (ch === '"') {
+ if (verbatim && text[k + 1] === '"') {
+ k++;
+ continue;
+ }
+ return k + 1;
+ }
+ if (!verbatim && ch === '\\') {
+ k++;
+ } else if (!verbatim && isNewline(ch)) {
+ return -1;
+ } else if (interpolated && ch === '{') {
+ if (text[k + 1] === '{') {
+ k++;
+ continue;
+ }
+ let m = k + 1;
+ while (m < text.length && text[m] !== '}') {
+ if ('"\'{/\n\r'.includes(text[m])) return -1;
+ m++;
+ }
+ if (m >= text.length) return -1;
+ k = m;
+ }
+ }
+ return -1;
+}
+
+function cppRawEnd(text, quote) {
+ const open = text.indexOf('(', quote + 1);
+ if (open === -1 || open - quote - 1 > 16) return -1;
+ const delimiter = text.slice(quote + 1, open);
+ for (const ch of delimiter) {
+ if (isSpace(ch) || isNewline(ch) || '()\\"'.includes(ch)) return -1;
+ }
+ const end = text.indexOf(`)${delimiter}"`, open + 1);
+ return end === -1 ? -1 : end + delimiter.length + 2;
+}
+
+function rustRawEnd(text, i) {
+ let j = i + (text[i] === 'r' ? 1 : 2);
+ let hashes = '';
+ while (text[j] === '#') {
+ hashes += '#';
+ j++;
+ }
+ if (text[j] !== '"') return null;
+ const end = text.indexOf(`"${hashes}`, j + 1);
+ return end === -1 ? -1 : end + 1 + hashes.length;
+}
+
+function wordStart(text, i) {
+ let start = i;
+ while (start > 0 && isIdentChar(text[start - 1])) start--;
+ return start;
+}
+
+function cFamilyStringEnd(text, i, spec) {
+ const ch = text[i];
+ const flavor = spec.flavor;
+ if (ch === '`') {
+ if (flavor === 'kotlin') return quotedEnd(text, i, '`', false);
+ if (flavor !== 'go') return -1;
+ const end = text.indexOf('`', i + 1);
+ return end === -1 ? -1 : end + 1;
+ }
+ if (ch === "'") {
+ if (flavor === 'rust') {
+ const end = rustCharEnd(text, i);
+ return end === -1 ? null : end + 1;
+ }
+ if (flavor === 'c' && isIdentChar(text[i - 1]) && isIdentChar(text[i + 1])) {
+ const first = text[wordStart(text, i)];
+ if (first >= '0' && first <= '9') return null;
+ }
+ return quotedEnd(text, i, "'", false);
+ }
+ if (flavor === 'c') {
+ const start = wordStart(text, i);
+ const prefix = text.slice(start, i);
+ if (CPP_RAW_PREFIXES.has(prefix)) return cppRawEnd(text, i);
+ if (prefix.endsWith('R')) return -1;
+ }
+ if (flavor === 'java' && text.startsWith('"""', i)) return textBlockEnd(text, i, true);
+ if (flavor === 'kotlin') return text.startsWith('"""', i) ? textBlockEnd(text, i, false) : kotlinStringEnd(text, i);
+ if (flavor === 'csharp' && text.startsWith('"""', i)) return -1;
+ return quotedEnd(text, i, '"', flavor === 'rust');
+}
+
+function cFamilyStartsFresh(text, spec) {
+ const js = spec.flavor === 'js';
+ const frames = [{ template: false, depth: 0 }];
+ const parens = [];
+ let lastWord = '';
+ let lastSig = 'op';
+ let lineEnd = '';
+ let continued = false;
+ let i = js && text.startsWith('#!') ? lineEndAt(text, 0) : 0;
+ while (i < text.length) {
+ const frame = frames[frames.length - 1];
+ const ch = text[i];
+ const next = text[i + 1];
+ if (frame.template) {
+ if (ch === '\\') {
+ i += 2;
+ } else if (ch === '`') {
+ frames.pop();
+ lastSig = 'value';
+ i++;
+ } else if (ch === '$' && next === '{') {
+ frames.push({ template: false, depth: 0 });
+ lastSig = 'op';
+ i += 2;
+ } else {
+ i++;
+ }
+ continue;
+ }
+ if (isNewline(ch)) {
+ continued = lineEnd === '\\';
+ lineEnd = '';
+ i++;
+ continue;
+ }
+ if (isSpace(ch)) {
+ i++;
+ continue;
+ }
+ if (ch === '/' && next === '/') {
+ const end = lineEndAt(text, i);
+ if (text.slice(i, end).trimEnd().endsWith('\\')) return false;
+ i = end;
+ continue;
+ }
+ if (ch === '/' && next === '*') {
+ const end = spec.rustDocs ? nestedBlockEnd(text, i) : text.indexOf('*/', i + 2);
+ if (end === -1) return false;
+ i = spec.rustDocs ? end : end + 2;
+ lineEnd = '';
+ continue;
+ }
+ lineEnd = ch;
+ if (js) {
+ if (ch === '`') {
+ frames.push({ template: true, depth: 0 });
+ i++;
+ continue;
+ }
+ if (ch === '/') {
+ if (lastSig === 'op') {
+ const end = regexEnd(text, i);
+ if (end === -1) return false;
+ lineEnd = text[end - 1];
+ lastSig = 'value';
+ i = end;
+ continue;
+ }
+ if (lastSig === 'close' && /[/'"`]/.test(text.slice(i + 1, lineEndAt(text, i)))) return false;
+ lastSig = 'op';
+ i++;
+ continue;
+ }
+ if (ch === '<' && (next === '!' || (spec.jsx && (isLetter(next) || next === '/' || next === '>')))) return false;
+ if (ch === '-' && next === '-' && text[i + 2] === '>') return false;
+ if (frames.length > 1 && ch === '{') frame.depth++;
+ if (frames.length > 1 && ch === '}') {
+ if (frame.depth === 0) {
+ frames.pop();
+ i++;
+ continue;
+ }
+ frame.depth--;
+ }
+ }
+ if (spec.flavor === 'csharp' && (ch === '@' || ch === '$') && /^[@$]{1,3}"/.test(text.slice(i, i + 4))) {
+ const end = csharpStringEnd(text, i);
+ if (end === -1) return false;
+ lineEnd = '"';
+ i = end;
+ continue;
+ }
+ if (spec.flavor === 'rust' && (ch === 'r' || ((ch === 'b' || ch === 'c') && next === 'r')) && !isIdentChar(text[i - 1])) {
+ const end = rustRawEnd(text, i);
+ if (end === -1) return false;
+ if (end !== null) {
+ lineEnd = text[end - 1];
+ lastSig = 'value';
+ i = end;
+ continue;
+ }
+ }
+ if (ch === '"' || ch === "'" || ch === '`') {
+ const end = cFamilyStringEnd(text, i, spec);
+ if (end === -1) return false;
+ if (end !== null) {
+ lineEnd = text[end - 1];
+ lastSig = 'value';
+ i = end;
+ continue;
+ }
+ i++;
+ continue;
+ }
+ if (isIdentChar(ch)) {
+ let end = i;
+ while (end < text.length && isIdentChar(text[end])) end++;
+ lastWord = text.slice(i, end);
+ lastSig = js && JS_REGEX_KEYWORDS.has(lastWord) ? 'op' : 'value';
+ lineEnd = text[end - 1];
+ i = end;
+ continue;
+ }
+ if (ch === '(') {
+ parens.push(lastSig === 'value' && JS_CONTROL_HEADERS.has(lastWord));
+ lastSig = 'op';
+ } else if (ch === ')') {
+ lastSig = parens.pop() ? 'op' : 'value';
+ } else {
+ lastSig = ch === '}' ? 'close' : ch === ']' ? 'value' : 'op';
+ }
+ lastWord = '';
+ i++;
+ }
+ return frames.length === 1 && !continued;
+}
+
+function pythonStringEnd(text, i, prefix) {
+ const quote = text[i];
+ const triple = text[i + 1] === quote && text[i + 2] === quote;
+ const fString = prefix.toLowerCase().includes('f');
+ let depth = 0;
+ for (let j = i + (triple ? 3 : 1); j < text.length; j++) {
+ const ch = text[j];
+ if (fString && depth > 0) {
+ if (ch === '{') {
+ depth++;
+ } else if (ch === '}') {
+ depth--;
+ } else if ((ch === '"' || ch === "'") && ch !== quote) {
+ let k = j + 1;
+ while (k < text.length && text[k] !== ch) {
+ if (text[k] === quote || text[k] === '\\' || isNewline(text[k])) return -1;
+ k++;
+ }
+ if (k >= text.length) return -1;
+ j = k;
+ } else if (ch === quote || ch === '#' || ch === '\\' || isNewline(ch)) {
+ return -1;
+ }
+ continue;
+ }
+ if (ch === '\\') {
+ j++;
+ if (text[j] === '\r' && text[j + 1] === '\n') j++;
+ } else if (fString && ch === '{') {
+ if (text[j + 1] === '{') j++;
+ else depth = 1;
+ } else if (isNewline(ch) && !triple) {
+ return -1;
+ } else if (ch === quote && (!triple || (text[j + 1] === quote && text[j + 2] === quote))) {
+ return j + (triple ? 3 : 1);
+ }
+ }
+ return -1;
+}
+
+function pythonStartsFresh(text) {
+ let lineEnd = '';
+ let continued = false;
+ let i = 0;
+ while (i < text.length) {
+ const ch = text[i];
+ if (isNewline(ch)) {
+ continued = lineEnd === '\\';
+ lineEnd = '';
+ i++;
+ } else if (isSpace(ch)) {
+ i++;
+ } else if (ch === '#') {
+ i = lineEndAt(text, i);
+ } else if (ch === '"' || ch === "'") {
+ const start = wordStart(text, i);
+ const prefix = text.slice(start, i);
+ if (prefix.length > 2 || /[^rbuf]/i.test(prefix)) return false;
+ const end = pythonStringEnd(text, i, prefix);
+ if (end === -1) return false;
+ lineEnd = ch;
+ i = end;
+ } else {
+ lineEnd = ch;
+ i++;
+ }
+ }
+ return !continued;
+}
+
+function heredocDelimiter(text, i) {
+ let j = i + 2;
+ const stripTabs = text[j] === '-';
+ if (stripTabs) j++;
+ while (isBlank(text[j])) j++;
+ let word = '';
+ while (j < text.length && !isBlank(text[j]) && !isNewline(text[j]) && !';|&<>()'.includes(text[j])) {
+ if (!'\'"\\'.includes(text[j])) word += text[j];
+ j++;
+ }
+ return word ? { word, stripTabs, end: j } : null;
+}
+
+function skipHeredocs(text, i, pending) {
+ let at = i;
+ for (const doc of pending) {
+ for (;;) {
+ if (at >= text.length) return -1;
+ const end = lineEndAt(text, at);
+ let line = text.slice(at, end);
+ if (doc.stripTabs) line = line.replace(/^\t+/, '');
+ at = end + (text[end] === '\r' && text[end + 1] === '\n' ? 2 : 1);
+ if (line === doc.word) break;
+ }
+ }
+ return at;
+}
+
+const MAX_NESTING = 8;
+
+function shSingleQuoteEnd(text, i) {
+ if (text[i - 1] === '$') return quotedEnd(text, i, "'", true);
+ return text.indexOf("'", i + 1) + 1 || -1;
+}
+
+function shSubstitutionEnd(text, i, level) {
+ if (level > MAX_NESTING) return -1;
+ let depth = 0;
+ for (let j = i + 1; j < text.length; j++) {
+ const ch = text[j];
+ if (ch === '\\') {
+ j++;
+ } else if (ch === '(') {
+ depth++;
+ } else if (ch === ')') {
+ depth--;
+ if (depth === 0) return j + 1;
+ } else if (ch === "'" || ch === '"') {
+ const end = ch === "'" ? shSingleQuoteEnd(text, j) : shDoubleQuoteScan(text, j, level + 1);
+ if (end === -1) return -1;
+ j = end - 1;
+ } else if (ch === '`' || (ch === '<' && text[j + 1] === '<') || (ch === '#' && hashStartsComment(text, j) !== false)) {
+ return -1;
+ } else if (ch === 'c' && text.startsWith('case', j) && !isIdentChar(text[j - 1]) && !isIdentChar(text[j + 4])) {
+ return -1;
+ }
+ }
+ return -1;
+}
+
+function shDoubleQuoteScan(text, i, level) {
+ for (let j = i + 1; j < text.length; j++) {
+ const ch = text[j];
+ if (ch === '"') return j + 1;
+ if (ch === '\\') {
+ j++;
+ } else if (ch === '`') {
+ return -1;
+ } else if (ch === '$' && text[j + 1] === '(') {
+ const end = shSubstitutionEnd(text, j, level);
+ if (end === -1) return -1;
+ j = end - 1;
+ } else if (ch === '$' && text[j + 1] === '{') {
+ const close = text.indexOf('}', j + 2);
+ if (close === -1 || /["'\n\r]/.test(text.slice(j + 2, close))) return -1;
+ j = close;
+ }
+ }
+ return -1;
+}
+
+function shStartsFresh(text) {
+ if (hasLoneCarriageReturn(text)) return false;
+ const pending = [];
+ let lineEnd = '';
+ let continued = false;
+ let i = 0;
+ while (i < text.length) {
+ const ch = text[i];
+ if (isNewline(ch)) {
+ continued = lineEnd === '\\';
+ lineEnd = '';
+ i += ch === '\r' && text[i + 1] === '\n' ? 2 : 1;
+ if (pending.length > 0) {
+ i = skipHeredocs(text, i, pending);
+ if (i === -1) return false;
+ pending.length = 0;
+ }
+ continue;
+ }
+ if (isBlank(ch)) {
+ i++;
+ continue;
+ }
+ lineEnd = ch;
+ if (ch === '\\') {
+ i += isNewline(text[i + 1]) ? 1 : 2;
+ } else if (ch === "'") {
+ const end = shSingleQuoteEnd(text, i);
+ if (end === -1) return false;
+ i = end;
+ } else if (ch === '"') {
+ const end = shDoubleQuoteScan(text, i, 0);
+ if (end === -1) return false;
+ i = end;
+ } else if (ch === '`') {
+ const end = text.indexOf('`', i + 1);
+ if (end === -1 || /['"\\#\n\r]/.test(text.slice(i + 1, end))) return false;
+ i = end + 1;
+ } else if (ch === '#') {
+ const starts = hashStartsComment(text, i);
+ if (starts === null) return false;
+ i = starts ? lineEndAt(text, i) : i + 1;
+ if (starts) lineEnd = '';
+ } else if (ch === '<' && text[i + 1] === '<') {
+ if (text[i + 2] === '<') {
+ i += 3;
+ continue;
+ }
+ const doc = heredocDelimiter(text, i);
+ if (!doc) return false;
+ pending.push(doc);
+ i = doc.end;
+ } else {
+ i++;
+ }
+ }
+ return !continued && pending.length === 0;
+}
+
+function psSingleQuoteEnd(text, i) {
+ for (let j = i + 1; j < text.length; j++) {
+ if (text[j] !== "'") continue;
+ if (text[j + 1] !== "'") return j + 1;
+ j++;
+ }
+ return -1;
+}
+
+function psSubexpressionEnd(text, i, level) {
+ if (level > MAX_NESTING) return -1;
+ let depth = 0;
+ for (let j = i + 1; j < text.length; j++) {
+ const ch = text[j];
+ if (ch === '`') {
+ j++;
+ } else if (ch === '(') {
+ depth++;
+ } else if (ch === ')') {
+ depth--;
+ if (depth === 0) return j + 1;
+ } else if (ch === "'" || ch === '"') {
+ const end = ch === "'" ? psSingleQuoteEnd(text, j) : psDoubleQuoteScan(text, j, level + 1);
+ if (end === -1) return -1;
+ j = end - 1;
+ } else if (ch === '#' || (ch === '@' && (text[j + 1] === '"' || text[j + 1] === "'"))) {
+ return -1;
+ }
+ }
+ return -1;
+}
+
+function psDoubleQuoteScan(text, i, level) {
+ for (let j = i + 1; j < text.length; j++) {
+ const ch = text[j];
+ if (ch === '`') {
+ j++;
+ } else if (ch === '$' && text[j + 1] === '(') {
+ const end = psSubexpressionEnd(text, j, level);
+ if (end === -1) return -1;
+ j = end - 1;
+ } else if (ch === '"') {
+ if (text[j + 1] !== '"') return j + 1;
+ j++;
+ }
+ }
+ return -1;
+}
+
+function psStartsFresh(text) {
+ if (PS_SMART_QUOTES.test(text)) return false;
+ let lineEnd = '';
+ let continued = false;
+ let i = 0;
+ while (i < text.length) {
+ const ch = text[i];
+ const next = text[i + 1];
+ if (isNewline(ch)) {
+ continued = lineEnd === '`';
+ lineEnd = '';
+ i++;
+ continue;
+ }
+ if (isBlank(ch)) {
+ i++;
+ continue;
+ }
+ lineEnd = ch;
+ if (ch === '`') {
+ i += isNewline(next) ? 1 : 2;
+ } else if (ch === '@' && (next === '"' || next === "'")) {
+ const open = lineEndAt(text, i);
+ if (text.slice(i + 2, open).trim() !== '') return false;
+ let at = open;
+ let found = -1;
+ while (at < text.length) {
+ at += text[at] === '\r' && text[at + 1] === '\n' ? 2 : 1;
+ if (text.startsWith(`${next}@`, at)) {
+ found = at + 2;
+ break;
+ }
+ at = lineEndAt(text, at);
+ }
+ if (found === -1) return false;
+ i = found;
+ } else if (ch === "'" || ch === '"') {
+ const end = ch === "'" ? psSingleQuoteEnd(text, i) : psDoubleQuoteScan(text, i, 0);
+ if (end === -1) return false;
+ i = end;
+ } else if (ch === '<' && next === '#') {
+ if (!psHashStartsComment(text, i)) return false;
+ const end = text.indexOf('#>', i + 2);
+ if (end === -1) return false;
+ i = end + 2;
+ lineEnd = '';
+ } else if (ch === '#') {
+ if (psHashStartsComment(text, i)) {
+ i = lineEndAt(text, i);
+ lineEnd = '';
+ } else if (isIdentChar(text[i - 1]) || '-.:'.includes(text[i - 1])) {
+ i++;
+ } else {
+ return false;
+ }
+ } else {
+ i++;
+ }
+ }
+ return !continued;
+}
+
+function batchStartsFresh(text) {
+ const lines = text.split(/\r\n|\r|\n/);
+ const last = lines.length > 1 ? lines[lines.length - 2] : '';
+ return !last.endsWith('^');
+}
+
+function lineStartOf(text, i) {
+ let start = i;
+ while (start > 0 && !isNewline(text[start - 1])) start--;
+ return start;
+}
+
+function windowStart(text, at) {
+ const start = lineStartOf(text, at);
+ if (start === 0) return 0;
+ let end = start - 1;
+ if (text[end] === '\n' && text[end - 1] === '\r') end--;
+ return lineStartOf(text, end);
+}
+
+function windowEnd(text, at) {
+ const end = lineEndAt(text, at);
+ if (end >= text.length) return text.length;
+ return end + (text[end] === '\r' && text[end + 1] === '\n' ? 2 : 1);
+}
+
+function occurrences(text, needle, replaceAll) {
+ const first = text.indexOf(needle);
+ if (first === -1) return null;
+ let last = first;
+ for (let at = text.indexOf(needle, first + needle.length); at !== -1; at = text.indexOf(needle, at + needle.length)) {
+ if (!replaceAll) return null;
+ last = at;
+ }
+ return { first, last };
+}
+
+function trivialInFile(pairs, fileText, spec) {
+ if (typeof fileText !== 'string' || fileText.length > MAX_FILE_CHARS || !spec.startsFresh) return false;
+ if (spec.flavor === 'go' && fileText.includes('"C"')) return false;
+ let text = fileText;
+ let work = 0;
+ for (const [oldString, newString, replaceAll] of pairs) {
+ if (!oldString || REPLACEMENT_PATTERN.test(newString)) return false;
+ const found = occurrences(text, oldString, replaceAll);
+ if (!found) return false;
+ const start = windowStart(text, found.first);
+ const end = windowEnd(text, found.last + oldString.length);
+ work += start + 2 * (end - start);
+ if (end - start > MAX_WINDOW_CHARS || work > MAX_CONTEXT_WORK || !spec.startsFresh(text.slice(0, start), spec)) return false;
+ const before = text.slice(start, end);
+ const after = replaceAll
+ ? before.split(oldString).join(newString)
+ : `${text.slice(start, found.first)}${newString}${text.slice(found.first + oldString.length, end)}`;
+ if (!isTrivialEdit(before, after, spec)) return false;
+ text = `${text.slice(0, start)}${after}${text.slice(end)}`;
+ if (text.length > MAX_FILE_CHARS) return false;
+ }
+ return true;
+}
+
+
+module.exports = {
+ MAX_FILE_CHARS,
+ lineEndAt,
+ lineStartOf,
+ cFamilyStartsFresh,
+ pythonStartsFresh,
+ shStartsFresh,
+ psStartsFresh,
+ batchStartsFresh,
+ trivialInFile
+};
diff --git a/scripts/lib/gateguard-search-evidence.js b/scripts/lib/gateguard-search-evidence.js
index 2be6bb446..27ae44111 100644
--- a/scripts/lib/gateguard-search-evidence.js
+++ b/scripts/lib/gateguard-search-evidence.js
@@ -4,6 +4,16 @@ const fs = require('fs');
const path = require('path');
const { WINDOWS_PATH_PATTERN, classifyTargetFor } = require('./gateguard-target-class');
const { excludedBatchId } = require('./gateguard-turn-scan');
+const {
+ POWERSHELL_SEARCHES,
+ isInsideDir,
+ valueFlagsFor,
+ powershellFilterArg,
+ grepToolFilters,
+ shellSearchFilters,
+ filtersAdmitTarget,
+ includesAdmitTarget
+} = require('./gateguard-search-filters');
// --- Search commands and flags ---
@@ -27,37 +37,10 @@ const DIRECTORY_CHANGE_COMMANDS = new Set(['cd', 'pushd', 'popd', 'chdir', 'set-
const PATTERN_FIRST_SEARCHES = new Set(['grep', 'egrep', 'fgrep', 'rg', 'git grep', 'select-string', 'sls', 'fd']);
const RECURSIVE_BY_DEFAULT = new Set(['rg', 'git grep', 'git ls-files', 'find', 'fd', 'tree']);
const GREP_FAMILY = new Set(['grep', 'egrep', 'fgrep']);
-const POWERSHELL_SEARCHES = new Set(['get-childitem', 'gci', 'select-string', 'sls']);
const PATTERN_VALUE_FLAGS = new Set(['-e', '-f', '--regexp', '--file']);
-const VALUE_FLAGS = new Set([
- '-e', '-f', '-g', '-t', '-T', '-m', '-A', '-B', '-C',
- '--regexp', '--file', '--type', '--glob', '--iglob', '--include', '--exclude', '--exclude-dir', '--exclude-from',
- '--ignore-file', '--max-count', '--replace',
- '-name', '-iname', '-path', '-ipath', '-type', '-maxdepth', '-mindepth', '-newer', '-regex', '-size', '-user', '-group', '-perm'
-]);
-const LS_VALUE_FLAGS = new Set(['-I', '--ignore', '--hide']);
-const TREE_VALUE_FLAGS = new Set(['-L', '-P', '-I', '-o']);
-const FD_VALUE_FLAGS = new Set([...VALUE_FLAGS, '-E']);
const PATTERN_FLAG_SEARCHES = new Set(['grep', 'egrep', 'fgrep', 'rg', 'git grep']);
const POWERSHELL_VALUE_FLAGS = new Set(['-path', '-literalpath', '-depth', '-pattern']);
const POWERSHELL_PATH_FLAGS = new Set(['-path', '-literalpath']);
-const POWERSHELL_FILTER_PARAMS = new Set(['filter', 'include', 'exclude']);
-const POWERSHELL_COMMON_PARAMS = [
- 'verbose', 'debug', 'erroraction', 'warningaction', 'informationaction', 'progressaction',
- 'errorvariable', 'warningvariable', 'informationvariable', 'outvariable', 'outbuffer', 'pipelinevariable'
-];
-const POWERSHELL_CHILDITEM_PARAMS = [
- 'path', 'literalpath', 'filter', 'include', 'exclude', 'recurse', 'depth', 'force', 'name',
- 'attributes', 'directory', 'file', 'hidden', 'readonly', 'system', 'followsymlink'
-];
-const POWERSHELL_SELECTSTRING_PARAMS = [
- 'pattern', 'path', 'literalpath', 'inputobject', 'simplematch', 'casesensitive', 'quiet', 'list', 'noemphasis',
- 'include', 'exclude', 'notmatch', 'allmatches', 'encoding', 'context', 'raw', 'culture'
-];
-const POWERSHELL_PARAM_ALIASES = new Set([
- 's', 'ad', 'd', 'af', 'ah', 'h', 'ar', 'as', 'lp', 'pspath',
- 'vb', 'db', 'ea', 'wa', 'infa', 'proga', 'ev', 'wv', 'iv', 'ov', 'ob', 'pv'
-]);
const GENERIC_STEMS = new Set([
'index',
'main',
@@ -132,10 +115,6 @@ function dirContext(targetPath, data) {
return { resolveDir, resolveNative, targetKey, targetDir: path.posix.dirname(targetKey) };
}
-function isInsideDir(targetKey, dirKey) {
- return targetKey.startsWith(dirKey.endsWith('/') ? dirKey : `${dirKey}/`);
-}
-
function isDirectoryNow(nativePath) {
try {
return fs.statSync(nativePath).isDirectory();
@@ -197,13 +176,6 @@ function isRecursiveFlag(kind, arg) {
return kind === 'ls' && arg.includes('R');
}
-function valueFlagsFor(kind) {
- if (kind === 'ls' || kind === 'git ls-files') return LS_VALUE_FLAGS;
- if (kind === 'tree') return TREE_VALUE_FLAGS;
- if (kind === 'fd') return FD_VALUE_FLAGS;
- return VALUE_FLAGS;
-}
-
function flagEffect(kind, args, i) {
const arg = args[i];
if (POWERSHELL_SEARCHES.has(kind)) {
@@ -296,403 +268,6 @@ function evidenceNamesDir(item, ctx) {
);
}
-// --- Search filters ---
-// see docs/gateguard/design-notes.md#search-filters
-
-const MAX_FILTER_GLOB_CHARS = 256;
-const MAX_BRACE_ALTERNATIVES = 32;
-const MAX_FILTERS_PER_SEARCH = 32;
-const FIND_NAME_FLAGS = new Set(['-name', '-iname', '-path', '-ipath', '-wholename', '-iwholename', '-regex', '-iregex']);
-const FIND_BASENAME_FLAGS = new Set(['-name', '-iname']);
-const OPAQUE_FILTER_FLAGS = new Set(['--exclude-from', '--ignore-file', '--exclude-per-directory']);
-const EXCLUDE_LONG_FLAGS = new Set(['--exclude', '--exclude-dir', '--ignore', '--hide']);
-const LS_ONLY_EXCLUDE_FLAGS = new Set(['--ignore', '--hide']);
-const GIT_EXCLUDE_PATHSPEC = /^:(?:[!^]|\([^)]*\bexclude\b[^)]*\))/;
-
-function splitTopLevelCommas(value) {
- const parts = [];
- let depth = 0;
- let current = '';
- for (const ch of String(value)) {
- if (ch === '{') depth += 1;
- else if (ch === '}' && depth > 0) depth -= 1;
- if (ch === ',' && depth === 0) {
- parts.push(current);
- current = '';
- } else {
- current += ch;
- }
- }
- parts.push(current);
- return parts.map(part => part.trim()).filter(Boolean);
-}
-
-function expandBraces(glob) {
- const open = glob.indexOf('{');
- if (open === -1) return [glob];
- let depth = 0;
- for (let i = open; i < glob.length; i++) {
- if (glob[i] === '{') depth += 1;
- else if (glob[i] === '}' && --depth === 0) {
- const head = glob.slice(0, open);
- const tail = glob.slice(i + 1);
- const results = [];
- for (const option of splitTopLevelCommas(glob.slice(open + 1, i)).concat(glob[open + 1] === ',' ? [''] : [])) {
- const expanded = expandBraces(`${head}${option}${tail}`);
- if (!expanded) return null;
- results.push(...expanded);
- if (results.length > MAX_BRACE_ALTERNATIVES) return null;
- }
- return results;
- }
- }
- return [glob];
-}
-
-function globTokens(glob) {
- const tokens = [];
- for (let i = 0; i < glob.length; i++) {
- const ch = glob[i];
- if (ch === '*' && glob[i + 1] === '*') {
- const dirs = glob[i + 2] === '/';
- tokens.push({ type: dirs ? 'dirs' : 'deep' });
- i += dirs ? 2 : 1;
- } else if (ch === '*') {
- tokens.push({ type: 'star' });
- } else if (ch === '?') {
- tokens.push({ type: 'one' });
- } else if (ch === '[') {
- const parsed = bracketClass(glob, i);
- if (!parsed) return null;
- tokens.push(parsed.token);
- i = parsed.end;
- } else {
- tokens.push({ type: 'lit', ch });
- }
- }
- return tokens;
-}
-
-function bracketClass(glob, open) {
- let i = open + 1;
- const negated = glob[i] === '!' || glob[i] === '^';
- if (negated) i += 1;
- const ranges = [];
- for (let first = true; i < glob.length && (first || glob[i] !== ']'); first = false) {
- if (glob[i + 1] === '-' && i + 2 < glob.length && glob[i + 2] !== ']') {
- ranges.push([glob[i], glob[i + 2]]);
- i += 3;
- } else {
- ranges.push([glob[i], glob[i]]);
- i += 1;
- }
- }
- if (i >= glob.length) return null;
- return { token: { type: 'class', negated, ranges }, end: i };
-}
-
-function classMatches(token, ch) {
- if (ch === '/') return false;
- const forms = [ch, ch.toLowerCase(), ch.toUpperCase()];
- const member = token.ranges.some(([lo, hi]) => forms.some(form => form >= lo && form <= hi));
- return member !== token.negated;
-}
-
-// see docs/gateguard/design-notes.md#glob-matching-without-regexp
-function wildcardMatch(glob, text) {
- const tokens = globTokens(glob);
- if (!tokens) return null;
- const n = text.length;
- let next = new Array(n + 1).fill(false);
- next[n] = true;
- for (let t = tokens.length - 1; t >= 0; t--) {
- const token = tokens[t];
- const row = new Array(n + 1).fill(false);
- let afterSlash = false;
- for (let j = n; j >= 0; j--) {
- if (token.type === 'lit') row[j] = j < n && text[j] === token.ch && next[j + 1];
- else if (token.type === 'one') row[j] = j < n && text[j] !== '/' && next[j + 1];
- else if (token.type === 'class') row[j] = j < n && classMatches(token, text[j]) && next[j + 1];
- else if (token.type === 'star') row[j] = next[j] || (j < n && text[j] !== '/' && row[j + 1]);
- else if (token.type === 'deep') row[j] = next[j] || (j < n && row[j + 1]);
- else {
- if (j < n && text[j] === '/' && next[j + 1]) afterSlash = true;
- row[j] = next[j] || afterSlash;
- }
- }
- next = row;
- }
- return next[0];
-}
-
-function normalizeFilterGlob(glob) {
- return String(glob).toLowerCase().replace(/\\/g, '/').replace(/^(?:\.\/)+/, '').replace(/^\/+/, '').replace(/\/+$/, '');
-}
-
-function globMatches(glob, text, malformed) {
- if (glob.length > MAX_FILTER_GLOB_CHARS) return null;
- const alternatives = expandBraces(glob);
- if (!alternatives) return null;
- return alternatives.some(alternative => {
- const matched = wildcardMatch(alternative, text);
- return matched === null ? malformed : matched;
- });
-}
-
-function targetSegments(ctx) {
- return ctx.targetKey.toLowerCase().split('/').filter(Boolean);
-}
-
-function exclusionCoversTarget(exclusion, segments, stem) {
- const glob = normalizeFilterGlob(exclusion);
- if (!glob) return true;
- if (stem !== null && stem.test(glob)) return true;
- for (let start = 0; start < segments.length; start++) {
- for (let end = start + 1; end <= segments.length; end++) {
- const matched = globMatches(glob, segments.slice(start, end).join('/'), true);
- if (matched !== false) return true;
- }
- }
- return false;
-}
-
-function filtersAdmitTarget(item, ctx, stem) {
- if (item.opaque) return false;
- const exclusions = Array.isArray(item.exclusions) ? item.exclusions : [];
- if (exclusions.length === 0) return true;
- if (exclusions.length > MAX_FILTERS_PER_SEARCH) return false;
- const segments = targetSegments(ctx);
- return !exclusions.some(exclusion => exclusionCoversTarget(exclusion, segments, stem));
-}
-
-function scopeRelativeSegments(item, ctx) {
- const scopes = item.scopes || (item.scope ? [item.scope] : []);
- const relatives = [];
- for (const parts of scopes) {
- const scope = ctx.resolveDir(...parts);
- if (isInsideDir(ctx.targetKey, scope)) relatives.push(ctx.targetKey.slice(scope.replace(/\/+$/, '').length + 1).toLowerCase().split('/'));
- }
- return relatives;
-}
-
-function includeAdmitsTarget(include, item, ctx) {
- const glob = normalizeFilterGlob(include);
- const unanchored = glob.replace(/^(?:\*\*\/)+/, '');
- if (!unanchored) return false;
- if (isBasenameGlob(unanchored)) {
- const segments = targetSegments(ctx);
- return globMatches(unanchored, segments[segments.length - 1] || '', false) === true;
- }
- if (!item.pathIncludes) return false;
- return scopeRelativeSegments(item, ctx).some(segments => {
- const starts = unanchored === glob ? [0] : segments.map((_, start) => start);
- return starts.some(start => globMatches(unanchored, segments.slice(start).join('/'), false) === true);
- });
-}
-
-// see docs/gateguard/design-notes.md#include-filters
-function includesAdmitTarget(item, ctx) {
- const includes = Array.isArray(item.includes) ? item.includes : [];
- if (includes.length === 0) return true;
- if (includes.length > MAX_FILTERS_PER_SEARCH) return false;
- return includes.some(include => includeAdmitsTarget(include, item, ctx));
-}
-
-function isBasenameGlob(glob) {
- return !/[\\/]/.test(String(glob).replace(/^(?:\*\*[\\/])+/, ''));
-}
-
-function grepToolFilters(glob) {
- const filters = { positives: [], includes: [], exclusions: [], opaque: false };
- if (typeof glob !== 'string' || !glob) return filters;
- for (const part of splitTopLevelCommas(glob)) {
- if (part.startsWith('!')) filters.exclusions.push(part.slice(1));
- else {
- filters.positives.push(part);
- filters.includes.push(part);
- }
- }
- return filters;
-}
-
-function shellSearchFilters(kind, args) {
- const filters = { exclusions: [], includes: [], opaque: false, dropped: new Set() };
- if (kind === 'find') return findSearchFilters(args, filters);
- if (POWERSHELL_SEARCHES.has(kind)) return powershellSearchFilters(kind, args, filters);
- for (let i = 0; i < args.length; i++) {
- const arg = args[i];
- if (/^\d*[<>]/.test(arg)) break;
- const consumed = applyShellFilterArg(kind, args, i, filters);
- i += consumed;
- }
- return filters;
-}
-
-function applyShellFilterArg(kind, args, i, filters) {
- const arg = args[i];
- const exclude = (value, indexes, separator) => {
- for (const glob of separator ? String(value).split(separator) : [value]) {
- if (glob) filters.exclusions.push(glob);
- }
- indexes.forEach(index => filters.dropped.add(index));
- };
- const include = value => {
- if (value) filters.includes.push(value);
- };
- if (kind.startsWith('git ') && GIT_EXCLUDE_PATHSPEC.test(arg)) {
- exclude(arg.replace(GIT_EXCLUDE_PATHSPEC, ''), [i]);
- return 0;
- }
- if (arg.startsWith('--')) {
- const eq = arg.indexOf('=');
- const name = eq > 0 ? arg.slice(0, eq) : arg;
- const hasNext = eq <= 0 && i + 1 < args.length;
- const value = eq > 0 ? arg.slice(eq + 1) : hasNext ? args[i + 1] : '';
- const indexes = eq > 0 || !hasNext ? [i] : [i, i + 1];
- const consumed = indexes.length - 1;
- if (OPAQUE_FILTER_FLAGS.has(name)) {
- filters.opaque = true;
- return consumed;
- }
- if (name === '--glob' || name === '--iglob') {
- if (value.startsWith('!')) exclude(value.slice(1), indexes);
- else include(value);
- return consumed;
- }
- if (name === '--include') {
- include(value);
- return consumed;
- }
- if (EXCLUDE_LONG_FLAGS.has(name) && (kind === 'ls' || !LS_ONLY_EXCLUDE_FLAGS.has(name))) {
- exclude(value, indexes);
- return consumed;
- }
- return 0;
- }
- if (!/^-[A-Za-z]/.test(arg)) return 0;
- const letters = shortFilterLetters(kind);
- const valueFlags = valueFlagsFor(kind);
- for (let k = 1; k < arg.length; k++) {
- const letter = arg[k];
- if (!letters.has(letter)) {
- if (valueFlags.has(`-${letter}`)) return k === arg.length - 1 ? 1 : 0;
- continue;
- }
- const attached = arg.slice(k + 1);
- const value = attached || args[i + 1] || '';
- const indexes = attached || i + 1 >= args.length ? [i] : [i, i + 1];
- const consumed = indexes.length - 1;
- applyShortFilter(kind, letter, value, indexes, { filters, exclude, include });
- return consumed;
- }
- return 0;
-}
-
-function shortFilterLetters(kind) {
- if (kind === 'rg') return new Set(['g']);
- if (kind === 'fd') return new Set(['E']);
- if (kind === 'ls') return new Set(['I']);
- if (kind === 'tree') return new Set(['I', 'P']);
- if (kind === 'git ls-files') return new Set(['x', 'X']);
- return new Set();
-}
-
-function applyShortFilter(kind, letter, value, indexes, { filters, exclude, include }) {
- if (kind === 'rg') {
- if (value.startsWith('!')) exclude(value.slice(1), indexes);
- else include(value);
- } else if (kind === 'tree' && letter === 'P') {
- value.split('|').forEach(include);
- } else if (kind === 'git ls-files' && letter === 'X') {
- filters.opaque = true;
- } else {
- exclude(value, indexes, kind === 'tree' ? '|' : '');
- }
-}
-
-function findSearchFilters(args, filters) {
- let negateNext = false;
- let negatedDepth = 0;
- let depth = 0;
- for (let i = 0; i < args.length; i++) {
- const arg = args[i];
- if (/^\d*[<>]/.test(arg)) break;
- if (arg === '-not' || arg === '!') {
- negateNext = true;
- filters.dropped.add(i);
- continue;
- }
- if (arg === '(') {
- depth += 1;
- if (negateNext && negatedDepth === 0) negatedDepth = depth;
- negateNext = false;
- continue;
- }
- if (arg === ')') {
- if (negatedDepth === depth) negatedDepth = 0;
- depth = Math.max(depth - 1, 0);
- continue;
- }
- if (FIND_NAME_FLAGS.has(arg) && i + 1 < args.length) {
- const value = args[i + 1];
- if (negateNext || negatedDepth > 0 || args[i + 2] === '-prune') {
- filters.exclusions.push(value);
- filters.dropped.add(i);
- filters.dropped.add(i + 1);
- } else if (FIND_BASENAME_FLAGS.has(arg)) {
- filters.includes.push(value);
- }
- i += 1;
- }
- negateNext = false;
- }
- return filters;
-}
-
-function powershellParam(kind, arg) {
- const colon = arg.indexOf(':');
- const spelled = (colon === -1 ? arg.slice(1) : arg.slice(1, colon)).toLowerCase();
- const inline = colon === -1 ? null : arg.slice(colon + 1);
- const own = kind === 'get-childitem' || kind === 'gci' ? POWERSHELL_CHILDITEM_PARAMS : POWERSHELL_SELECTSTRING_PARAMS;
- const params = own.concat(POWERSHELL_COMMON_PARAMS);
- if (!spelled) return { name: null, inline };
- if (params.includes(spelled) || POWERSHELL_PARAM_ALIASES.has(spelled)) return { name: spelled, inline };
- const matches = params.filter(param => param.startsWith(spelled));
- return { name: matches.length === 1 ? matches[0] : null, inline };
-}
-
-function powershellFilterArg(kind, args, i) {
- if (!/^-[A-Za-z]/.test(args[i])) return null;
- const { name, inline } = powershellParam(kind, args[i]);
- if (!POWERSHELL_FILTER_PARAMS.has(name)) return null;
- const first = inline ? i : i + 1;
- if (first >= args.length) return { name, globs: [], end: i };
- let end = first;
- while (end + 1 < args.length && (args[end].endsWith(',') || args[end + 1].startsWith(','))) end += 1;
- const parts = [inline || args[first]].concat(args.slice(first + 1, end + 1));
- return { name, globs: splitTopLevelCommas(parts.join(',')), end };
-}
-
-function powershellSearchFilters(kind, args, filters) {
- for (let i = 0; i < args.length; i++) {
- const filter = powershellFilterArg(kind, args, i);
- if (filter) {
- if (filter.name === 'exclude') {
- filters.exclusions.push(...filter.globs);
- for (let k = i; k <= filter.end; k++) filters.dropped.add(k);
- } else {
- filter.globs.filter(Boolean).forEach(glob => filters.includes.push(glob));
- }
- i = filter.end;
- } else if (/^-[A-Za-z]/.test(args[i]) && powershellParam(kind, args[i]).name === null) {
- // see docs/gateguard/design-notes.md#powershell-parameter-binding
- filters.dropped.add(i);
- if (!args[i].includes(':') && i + 1 < args.length && !args[i + 1].startsWith('-')) filters.dropped.add(i + 1);
- }
- }
- return filters;
-}
-
// --- Prior-search credit ---
const MIN_GENERIC_MISS_STEM = 3;
diff --git a/scripts/lib/gateguard-search-filters.js b/scripts/lib/gateguard-search-filters.js
new file mode 100644
index 000000000..2077aff7f
--- /dev/null
+++ b/scripts/lib/gateguard-search-filters.js
@@ -0,0 +1,459 @@
+'use strict';
+
+// --- Search flags ---
+
+const POWERSHELL_SEARCHES = new Set(['get-childitem', 'gci', 'select-string', 'sls']);
+
+const VALUE_FLAGS = new Set([
+ '-e', '-f', '-g', '-t', '-T', '-m', '-A', '-B', '-C',
+ '--regexp', '--file', '--type', '--glob', '--iglob', '--include', '--exclude', '--exclude-dir', '--exclude-from',
+ '--ignore-file', '--max-count', '--replace',
+ '-name', '-iname', '-path', '-ipath', '-type', '-maxdepth', '-mindepth', '-newer', '-regex', '-size', '-user', '-group', '-perm'
+]);
+
+const LS_VALUE_FLAGS = new Set(['-I', '--ignore', '--hide']);
+
+const TREE_VALUE_FLAGS = new Set(['-L', '-P', '-I', '-o']);
+
+const FD_VALUE_FLAGS = new Set([...VALUE_FLAGS, '-E']);
+
+const POWERSHELL_FILTER_PARAMS = new Set(['filter', 'include', 'exclude']);
+
+const POWERSHELL_COMMON_PARAMS = [
+ 'verbose', 'debug', 'erroraction', 'warningaction', 'informationaction', 'progressaction',
+ 'errorvariable', 'warningvariable', 'informationvariable', 'outvariable', 'outbuffer', 'pipelinevariable'
+];
+
+const POWERSHELL_CHILDITEM_PARAMS = [
+ 'path', 'literalpath', 'filter', 'include', 'exclude', 'recurse', 'depth', 'force', 'name',
+ 'attributes', 'directory', 'file', 'hidden', 'readonly', 'system', 'followsymlink'
+];
+
+const POWERSHELL_SELECTSTRING_PARAMS = [
+ 'pattern', 'path', 'literalpath', 'inputobject', 'simplematch', 'casesensitive', 'quiet', 'list', 'noemphasis',
+ 'include', 'exclude', 'notmatch', 'allmatches', 'encoding', 'context', 'raw', 'culture'
+];
+
+const POWERSHELL_PARAM_ALIASES = new Set([
+ 's', 'ad', 'd', 'af', 'ah', 'h', 'ar', 'as', 'lp', 'pspath',
+ 'vb', 'db', 'ea', 'wa', 'infa', 'proga', 'ev', 'wv', 'iv', 'ov', 'ob', 'pv'
+]);
+
+function isInsideDir(targetKey, dirKey) {
+ return targetKey.startsWith(dirKey.endsWith('/') ? dirKey : `${dirKey}/`);
+}
+
+function valueFlagsFor(kind) {
+ if (kind === 'ls' || kind === 'git ls-files') return LS_VALUE_FLAGS;
+ if (kind === 'tree') return TREE_VALUE_FLAGS;
+ if (kind === 'fd') return FD_VALUE_FLAGS;
+ return VALUE_FLAGS;
+}
+
+// --- Search filters ---
+// see docs/gateguard/design-notes.md#search-filters
+
+const MAX_FILTER_GLOB_CHARS = 256;
+const MAX_BRACE_ALTERNATIVES = 32;
+const MAX_FILTERS_PER_SEARCH = 32;
+const FIND_NAME_FLAGS = new Set(['-name', '-iname', '-path', '-ipath', '-wholename', '-iwholename', '-regex', '-iregex']);
+const FIND_BASENAME_FLAGS = new Set(['-name', '-iname']);
+const OPAQUE_FILTER_FLAGS = new Set(['--exclude-from', '--ignore-file', '--exclude-per-directory']);
+const EXCLUDE_LONG_FLAGS = new Set(['--exclude', '--exclude-dir', '--ignore', '--hide']);
+const LS_ONLY_EXCLUDE_FLAGS = new Set(['--ignore', '--hide']);
+const GIT_EXCLUDE_PATHSPEC = /^:(?:[!^]|\([^)]*\bexclude\b[^)]*\))/;
+
+function splitTopLevelCommas(value) {
+ const parts = [];
+ let depth = 0;
+ let current = '';
+ for (const ch of String(value)) {
+ if (ch === '{') depth += 1;
+ else if (ch === '}' && depth > 0) depth -= 1;
+ if (ch === ',' && depth === 0) {
+ parts.push(current);
+ current = '';
+ } else {
+ current += ch;
+ }
+ }
+ parts.push(current);
+ return parts.map(part => part.trim()).filter(Boolean);
+}
+
+function expandBraces(glob) {
+ const open = glob.indexOf('{');
+ if (open === -1) return [glob];
+ let depth = 0;
+ for (let i = open; i < glob.length; i++) {
+ if (glob[i] === '{') depth += 1;
+ else if (glob[i] === '}' && --depth === 0) {
+ const head = glob.slice(0, open);
+ const tail = glob.slice(i + 1);
+ const results = [];
+ for (const option of splitTopLevelCommas(glob.slice(open + 1, i)).concat(glob[open + 1] === ',' ? [''] : [])) {
+ const expanded = expandBraces(`${head}${option}${tail}`);
+ if (!expanded) return null;
+ results.push(...expanded);
+ if (results.length > MAX_BRACE_ALTERNATIVES) return null;
+ }
+ return results;
+ }
+ }
+ return [glob];
+}
+
+function globTokens(glob) {
+ const tokens = [];
+ for (let i = 0; i < glob.length; i++) {
+ const ch = glob[i];
+ if (ch === '*' && glob[i + 1] === '*') {
+ const dirs = glob[i + 2] === '/';
+ tokens.push({ type: dirs ? 'dirs' : 'deep' });
+ i += dirs ? 2 : 1;
+ } else if (ch === '*') {
+ tokens.push({ type: 'star' });
+ } else if (ch === '?') {
+ tokens.push({ type: 'one' });
+ } else if (ch === '[') {
+ const parsed = bracketClass(glob, i);
+ if (!parsed) return null;
+ tokens.push(parsed.token);
+ i = parsed.end;
+ } else {
+ tokens.push({ type: 'lit', ch });
+ }
+ }
+ return tokens;
+}
+
+function bracketClass(glob, open) {
+ let i = open + 1;
+ const negated = glob[i] === '!' || glob[i] === '^';
+ if (negated) i += 1;
+ const ranges = [];
+ for (let first = true; i < glob.length && (first || glob[i] !== ']'); first = false) {
+ if (glob[i + 1] === '-' && i + 2 < glob.length && glob[i + 2] !== ']') {
+ ranges.push([glob[i], glob[i + 2]]);
+ i += 3;
+ } else {
+ ranges.push([glob[i], glob[i]]);
+ i += 1;
+ }
+ }
+ if (i >= glob.length) return null;
+ return { token: { type: 'class', negated, ranges }, end: i };
+}
+
+function classMatches(token, ch) {
+ if (ch === '/') return false;
+ const forms = [ch, ch.toLowerCase(), ch.toUpperCase()];
+ const member = token.ranges.some(([lo, hi]) => forms.some(form => form >= lo && form <= hi));
+ return member !== token.negated;
+}
+
+// see docs/gateguard/design-notes.md#glob-matching-without-regexp
+function wildcardMatch(glob, text) {
+ const tokens = globTokens(glob);
+ if (!tokens) return null;
+ const n = text.length;
+ let next = new Array(n + 1).fill(false);
+ next[n] = true;
+ for (let t = tokens.length - 1; t >= 0; t--) {
+ const token = tokens[t];
+ const row = new Array(n + 1).fill(false);
+ let afterSlash = false;
+ for (let j = n; j >= 0; j--) {
+ if (token.type === 'lit') row[j] = j < n && text[j] === token.ch && next[j + 1];
+ else if (token.type === 'one') row[j] = j < n && text[j] !== '/' && next[j + 1];
+ else if (token.type === 'class') row[j] = j < n && classMatches(token, text[j]) && next[j + 1];
+ else if (token.type === 'star') row[j] = next[j] || (j < n && text[j] !== '/' && row[j + 1]);
+ else if (token.type === 'deep') row[j] = next[j] || (j < n && row[j + 1]);
+ else {
+ if (j < n && text[j] === '/' && next[j + 1]) afterSlash = true;
+ row[j] = next[j] || afterSlash;
+ }
+ }
+ next = row;
+ }
+ return next[0];
+}
+
+function normalizeFilterGlob(glob) {
+ return String(glob).toLowerCase().replace(/\\/g, '/').replace(/^(?:\.\/)+/, '').replace(/^\/+/, '').replace(/\/+$/, '');
+}
+
+function globMatches(glob, text, malformed) {
+ if (glob.length > MAX_FILTER_GLOB_CHARS) return null;
+ const alternatives = expandBraces(glob);
+ if (!alternatives) return null;
+ return alternatives.some(alternative => {
+ const matched = wildcardMatch(alternative, text);
+ return matched === null ? malformed : matched;
+ });
+}
+
+function targetSegments(ctx) {
+ return ctx.targetKey.toLowerCase().split('/').filter(Boolean);
+}
+
+function exclusionCoversTarget(exclusion, segments, stem) {
+ const glob = normalizeFilterGlob(exclusion);
+ if (!glob) return true;
+ if (stem !== null && stem.test(glob)) return true;
+ for (let start = 0; start < segments.length; start++) {
+ for (let end = start + 1; end <= segments.length; end++) {
+ const matched = globMatches(glob, segments.slice(start, end).join('/'), true);
+ if (matched !== false) return true;
+ }
+ }
+ return false;
+}
+
+function filtersAdmitTarget(item, ctx, stem) {
+ if (item.opaque) return false;
+ const exclusions = Array.isArray(item.exclusions) ? item.exclusions : [];
+ if (exclusions.length === 0) return true;
+ if (exclusions.length > MAX_FILTERS_PER_SEARCH) return false;
+ const segments = targetSegments(ctx);
+ return !exclusions.some(exclusion => exclusionCoversTarget(exclusion, segments, stem));
+}
+
+function scopeRelativeSegments(item, ctx) {
+ const scopes = item.scopes || (item.scope ? [item.scope] : []);
+ const relatives = [];
+ for (const parts of scopes) {
+ const scope = ctx.resolveDir(...parts);
+ if (isInsideDir(ctx.targetKey, scope)) relatives.push(ctx.targetKey.slice(scope.replace(/\/+$/, '').length + 1).toLowerCase().split('/'));
+ }
+ return relatives;
+}
+
+function includeAdmitsTarget(include, item, ctx) {
+ const glob = normalizeFilterGlob(include);
+ const unanchored = glob.replace(/^(?:\*\*\/)+/, '');
+ if (!unanchored) return false;
+ if (isBasenameGlob(unanchored)) {
+ const segments = targetSegments(ctx);
+ return globMatches(unanchored, segments[segments.length - 1] || '', false) === true;
+ }
+ if (!item.pathIncludes) return false;
+ return scopeRelativeSegments(item, ctx).some(segments => {
+ const starts = unanchored === glob ? [0] : segments.map((_, start) => start);
+ return starts.some(start => globMatches(unanchored, segments.slice(start).join('/'), false) === true);
+ });
+}
+
+// see docs/gateguard/design-notes.md#include-filters
+function includesAdmitTarget(item, ctx) {
+ const includes = Array.isArray(item.includes) ? item.includes : [];
+ if (includes.length === 0) return true;
+ if (includes.length > MAX_FILTERS_PER_SEARCH) return false;
+ return includes.some(include => includeAdmitsTarget(include, item, ctx));
+}
+
+function isBasenameGlob(glob) {
+ return !/[\\/]/.test(String(glob).replace(/^(?:\*\*[\\/])+/, ''));
+}
+
+function grepToolFilters(glob) {
+ const filters = { positives: [], includes: [], exclusions: [], opaque: false };
+ if (typeof glob !== 'string' || !glob) return filters;
+ for (const part of splitTopLevelCommas(glob)) {
+ if (part.startsWith('!')) filters.exclusions.push(part.slice(1));
+ else {
+ filters.positives.push(part);
+ filters.includes.push(part);
+ }
+ }
+ return filters;
+}
+
+function shellSearchFilters(kind, args) {
+ const filters = { exclusions: [], includes: [], opaque: false, dropped: new Set() };
+ if (kind === 'find') return findSearchFilters(args, filters);
+ if (POWERSHELL_SEARCHES.has(kind)) return powershellSearchFilters(kind, args, filters);
+ for (let i = 0; i < args.length; i++) {
+ const arg = args[i];
+ if (/^\d*[<>]/.test(arg)) break;
+ const consumed = applyShellFilterArg(kind, args, i, filters);
+ i += consumed;
+ }
+ return filters;
+}
+
+function applyShellFilterArg(kind, args, i, filters) {
+ const arg = args[i];
+ const exclude = (value, indexes, separator) => {
+ for (const glob of separator ? String(value).split(separator) : [value]) {
+ if (glob) filters.exclusions.push(glob);
+ }
+ indexes.forEach(index => filters.dropped.add(index));
+ };
+ const include = value => {
+ if (value) filters.includes.push(value);
+ };
+ if (kind.startsWith('git ') && GIT_EXCLUDE_PATHSPEC.test(arg)) {
+ exclude(arg.replace(GIT_EXCLUDE_PATHSPEC, ''), [i]);
+ return 0;
+ }
+ if (arg.startsWith('--')) {
+ const eq = arg.indexOf('=');
+ const name = eq > 0 ? arg.slice(0, eq) : arg;
+ const hasNext = eq <= 0 && i + 1 < args.length;
+ const value = eq > 0 ? arg.slice(eq + 1) : hasNext ? args[i + 1] : '';
+ const indexes = eq > 0 || !hasNext ? [i] : [i, i + 1];
+ const consumed = indexes.length - 1;
+ if (OPAQUE_FILTER_FLAGS.has(name)) {
+ filters.opaque = true;
+ return consumed;
+ }
+ if (name === '--glob' || name === '--iglob') {
+ if (value.startsWith('!')) exclude(value.slice(1), indexes);
+ else include(value);
+ return consumed;
+ }
+ if (name === '--include') {
+ include(value);
+ return consumed;
+ }
+ if (EXCLUDE_LONG_FLAGS.has(name) && (kind === 'ls' || !LS_ONLY_EXCLUDE_FLAGS.has(name))) {
+ exclude(value, indexes);
+ return consumed;
+ }
+ return 0;
+ }
+ if (!/^-[A-Za-z]/.test(arg)) return 0;
+ const letters = shortFilterLetters(kind);
+ const valueFlags = valueFlagsFor(kind);
+ for (let k = 1; k < arg.length; k++) {
+ const letter = arg[k];
+ if (!letters.has(letter)) {
+ if (valueFlags.has(`-${letter}`)) return k === arg.length - 1 ? 1 : 0;
+ continue;
+ }
+ const attached = arg.slice(k + 1);
+ const value = attached || args[i + 1] || '';
+ const indexes = attached || i + 1 >= args.length ? [i] : [i, i + 1];
+ const consumed = indexes.length - 1;
+ applyShortFilter(kind, letter, value, indexes, { filters, exclude, include });
+ return consumed;
+ }
+ return 0;
+}
+
+function shortFilterLetters(kind) {
+ if (kind === 'rg') return new Set(['g']);
+ if (kind === 'fd') return new Set(['E']);
+ if (kind === 'ls') return new Set(['I']);
+ if (kind === 'tree') return new Set(['I', 'P']);
+ if (kind === 'git ls-files') return new Set(['x', 'X']);
+ return new Set();
+}
+
+function applyShortFilter(kind, letter, value, indexes, { filters, exclude, include }) {
+ if (kind === 'rg') {
+ if (value.startsWith('!')) exclude(value.slice(1), indexes);
+ else include(value);
+ } else if (kind === 'tree' && letter === 'P') {
+ value.split('|').forEach(include);
+ } else if (kind === 'git ls-files' && letter === 'X') {
+ filters.opaque = true;
+ } else {
+ exclude(value, indexes, kind === 'tree' ? '|' : '');
+ }
+}
+
+function findSearchFilters(args, filters) {
+ let negateNext = false;
+ let negatedDepth = 0;
+ let depth = 0;
+ for (let i = 0; i < args.length; i++) {
+ const arg = args[i];
+ if (/^\d*[<>]/.test(arg)) break;
+ if (arg === '-not' || arg === '!') {
+ negateNext = true;
+ filters.dropped.add(i);
+ continue;
+ }
+ if (arg === '(') {
+ depth += 1;
+ if (negateNext && negatedDepth === 0) negatedDepth = depth;
+ negateNext = false;
+ continue;
+ }
+ if (arg === ')') {
+ if (negatedDepth === depth) negatedDepth = 0;
+ depth = Math.max(depth - 1, 0);
+ continue;
+ }
+ if (FIND_NAME_FLAGS.has(arg) && i + 1 < args.length) {
+ const value = args[i + 1];
+ if (negateNext || negatedDepth > 0 || args[i + 2] === '-prune') {
+ filters.exclusions.push(value);
+ filters.dropped.add(i);
+ filters.dropped.add(i + 1);
+ } else if (FIND_BASENAME_FLAGS.has(arg)) {
+ filters.includes.push(value);
+ }
+ i += 1;
+ }
+ negateNext = false;
+ }
+ return filters;
+}
+
+function powershellParam(kind, arg) {
+ const colon = arg.indexOf(':');
+ const spelled = (colon === -1 ? arg.slice(1) : arg.slice(1, colon)).toLowerCase();
+ const inline = colon === -1 ? null : arg.slice(colon + 1);
+ const own = kind === 'get-childitem' || kind === 'gci' ? POWERSHELL_CHILDITEM_PARAMS : POWERSHELL_SELECTSTRING_PARAMS;
+ const params = own.concat(POWERSHELL_COMMON_PARAMS);
+ if (!spelled) return { name: null, inline };
+ if (params.includes(spelled) || POWERSHELL_PARAM_ALIASES.has(spelled)) return { name: spelled, inline };
+ const matches = params.filter(param => param.startsWith(spelled));
+ return { name: matches.length === 1 ? matches[0] : null, inline };
+}
+
+function powershellFilterArg(kind, args, i) {
+ if (!/^-[A-Za-z]/.test(args[i])) return null;
+ const { name, inline } = powershellParam(kind, args[i]);
+ if (!POWERSHELL_FILTER_PARAMS.has(name)) return null;
+ const first = inline ? i : i + 1;
+ if (first >= args.length) return { name, globs: [], end: i };
+ let end = first;
+ while (end + 1 < args.length && (args[end].endsWith(',') || args[end + 1].startsWith(','))) end += 1;
+ const parts = [inline || args[first]].concat(args.slice(first + 1, end + 1));
+ return { name, globs: splitTopLevelCommas(parts.join(',')), end };
+}
+
+function powershellSearchFilters(kind, args, filters) {
+ for (let i = 0; i < args.length; i++) {
+ const filter = powershellFilterArg(kind, args, i);
+ if (filter) {
+ if (filter.name === 'exclude') {
+ filters.exclusions.push(...filter.globs);
+ for (let k = i; k <= filter.end; k++) filters.dropped.add(k);
+ } else {
+ filter.globs.filter(Boolean).forEach(glob => filters.includes.push(glob));
+ }
+ i = filter.end;
+ } else if (/^-[A-Za-z]/.test(args[i]) && powershellParam(kind, args[i]).name === null) {
+ // see docs/gateguard/design-notes.md#powershell-parameter-binding
+ filters.dropped.add(i);
+ if (!args[i].includes(':') && i + 1 < args.length && !args[i + 1].startsWith('-')) filters.dropped.add(i + 1);
+ }
+ }
+ return filters;
+}
+
+module.exports = {
+ POWERSHELL_SEARCHES,
+ isInsideDir,
+ valueFlagsFor,
+ powershellFilterArg,
+ grepToolFilters,
+ shellSearchFilters,
+ filtersAdmitTarget,
+ includesAdmitTarget
+};
diff --git a/scripts/lib/gateguard-target-class.js b/scripts/lib/gateguard-target-class.js
index 30cd89405..c963de76d 100644
--- a/scripts/lib/gateguard-target-class.js
+++ b/scripts/lib/gateguard-target-class.js
@@ -183,7 +183,7 @@ const CLASS_QUESTIONS = Object.fromEntries(
Object.entries(CLASS_QUESTION_IDS).map(([cls, ids]) => [cls, isWrite => ids(isWrite).map(id => QUESTION_TEXT[id])])
);
-// see docs/gateguard/design-notes.md#questions-from-the-change-profile
+// see docs/gateguard/change-profile.md#questions-from-the-change-profile
function codeQuestionIds(isWrite, profile) {
const known = Boolean(profile) && profile.known === true;
const surface = !known || profile.touchesPublicSurface !== false;
diff --git a/tests/lib/gateguard-code-lexer.test.js b/tests/lib/gateguard-code-lexer.test.js
new file mode 100644
index 000000000..e40908ac3
--- /dev/null
+++ b/tests/lib/gateguard-code-lexer.test.js
@@ -0,0 +1,79 @@
+'use strict';
+/**
+ * Tests for scripts/lib/gateguard-code-lexer.js.
+ *
+ * Run with: node tests/lib/gateguard-code-lexer.test.js
+ */
+
+const assert = require('assert');
+const path = require('path');
+
+const { isTrivialEdit, shCodeLines, psCodeLines, batchCodeLines, normalizeShellLine } = require(
+ path.join(__dirname, '..', '..', 'scripts', 'lib', 'gateguard-code-lexer.js')
+);
+
+console.log('=== Testing gateguard-code-lexer.js ===\n');
+
+let passed = 0;
+let failed = 0;
+
+function test(desc, fn) {
+ try {
+ fn();
+ console.log(` ✓ ${desc}`);
+ passed++;
+ } catch (e) {
+ console.log(` ✗ ${desc}: ${e.message}`);
+ failed++;
+ }
+}
+
+const JS = { lineComment: '//', blockComment: true, quotes: '"\'', indentSensitive: false, flavor: 'js', forbiddenCode: '`/', jsx: true };
+const PY = { lineComment: '#', blockComment: false, quotes: '"\'', indentSensitive: true, tripleQuotes: true, fStrings: true };
+
+test('a comment-only change to C-family code is trivial', () => {
+ assert.strictEqual(isTrivialEdit('a(); // x', 'a(); // y', JS), true);
+});
+
+test('a code change is not trivial', () => {
+ assert.strictEqual(isTrivialEdit('a();', 'b();', JS), false);
+});
+
+test('a directive comment counts as code', () => {
+ assert.strictEqual(isTrivialEdit('// eslint-disable-next-line', '// note', JS), false);
+});
+
+test('an indentation change is not trivial in an indentation-sensitive language', () => {
+ assert.strictEqual(isTrivialEdit(' x = 1', 'x = 1', PY), false);
+});
+
+test('a trailing comment change in Python is trivial', () => {
+ assert.strictEqual(isTrivialEdit('x = 1 # a', 'x = 1 # b', PY), true);
+});
+
+test('shell code lines drop comments', () => {
+ assert.deepStrictEqual(shCodeLines('echo hi # c\nls'), ['echo hi ', 'ls']);
+});
+
+test('shell heredocs are not lexed', () => {
+ assert.strictEqual(shCodeLines('cat <<EOF\nx\nEOF'), null);
+});
+
+test('PowerShell code lines drop line and block comments', () => {
+ assert.deepStrictEqual(psCodeLines('Get-X # c\n<# b #>\nY'), ['Get-X ', ' ', 'Y']);
+});
+
+test('batch code lines drop REM lines', () => {
+ assert.deepStrictEqual(batchCodeLines('@echo off\nREM x\nset a=1'), ['@echo off', '', 'set a=1']);
+});
+
+test('a batch line continuation is not lexed', () => {
+ assert.strictEqual(batchCodeLines('echo ^'), null);
+});
+
+test('shell line normalization collapses blanks but keeps escaped ones', () => {
+ assert.strictEqual(normalizeShellLine('a b\\ c', '\\'), 'a b\\ c');
+});
+
+console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
+process.exit(failed > 0 ? 1 : 0);
diff --git a/tests/lib/gateguard-file-context.test.js b/tests/lib/gateguard-file-context.test.js
new file mode 100644
index 000000000..3266aa1a8
--- /dev/null
+++ b/tests/lib/gateguard-file-context.test.js
@@ -0,0 +1,69 @@
+'use strict';
+/**
+ * Tests for scripts/lib/gateguard-file-context.js.
+ *
+ * Run with: node tests/lib/gateguard-file-context.test.js
+ */
+
+const assert = require('assert');
+const path = require('path');
+
+const { shCodeLines, normalizeShellLine } = require(path.join(__dirname, '..', '..', 'scripts', 'lib', 'gateguard-code-lexer.js'));
+const { trivialInFile, cFamilyStartsFresh, pythonStartsFresh, shStartsFresh, lineStartOf, lineEndAt } = require(
+ path.join(__dirname, '..', '..', 'scripts', 'lib', 'gateguard-file-context.js')
+);
+
+console.log('=== Testing gateguard-file-context.js ===\n');
+
+let passed = 0;
+let failed = 0;
+
+function test(desc, fn) {
+ try {
+ fn();
+ console.log(` ✓ ${desc}`);
+ passed++;
+ } catch (e) {
+ console.log(` ✗ ${desc}: ${e.message}`);
+ failed++;
+ }
+}
+
+const JS = { lineComment: '//', blockComment: true, quotes: '"\'', indentSensitive: false, flavor: 'js', forbiddenCode: '`/', jsx: true, startsFresh: cFamilyStartsFresh };
+const PY = { lineComment: '#', blockComment: false, quotes: '"\'', indentSensitive: true, tripleQuotes: true, fStrings: true, startsFresh: pythonStartsFresh };
+const SH = { lexer: shCodeLines, normalize: line => normalizeShellLine(line, '\\'), startsFresh: shStartsFresh };
+
+test('a comment edit between statements is trivial in its file', () => {
+ assert.strictEqual(trivialInFile([['// old', '// new']], 'const a = 1;\n// old\nconst b = 2;\n', JS), true);
+});
+
+test('comment-looking text inside a template literal is code', () => {
+ assert.strictEqual(trivialInFile([['// old', '// new']], 'const s = `\n// old\n`;\n', JS), false);
+});
+
+test('comment-looking text inside a Python triple-quoted string is code', () => {
+ assert.strictEqual(trivialInFile([['# old', '# new']], 'x = """\n# old\n"""\n', PY), false);
+});
+
+test('comment-looking text inside a shell heredoc is code', () => {
+ assert.strictEqual(trivialInFile([['# a', '# b']], 'cat <<EOF\n# a\nEOF\n', SH), false);
+});
+
+test('a replacement with a $ pattern is never trivial', () => {
+ assert.strictEqual(trivialInFile([['// a', '// $& b']], '// a\n', JS), false);
+});
+
+test('a file prefix ends fresh only outside strings and comments', () => {
+ assert.strictEqual(cFamilyStartsFresh('const a = 1;\n', JS), true);
+ assert.strictEqual(cFamilyStartsFresh('const s = "abc', JS), false);
+ assert.strictEqual(pythonStartsFresh('x = 1\n'), true);
+ assert.strictEqual(pythonStartsFresh('x = """\n'), false);
+});
+
+test('line bounds are found around an offset', () => {
+ assert.strictEqual(lineStartOf('ab\ncd', 4), 3);
+ assert.strictEqual(lineEndAt('ab\ncd', 0), 2);
+});
+
+console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
+process.exit(failed > 0 ? 1 : 0);
diff --git a/tests/lib/gateguard-search-filters.test.js b/tests/lib/gateguard-search-filters.test.js
new file mode 100644
index 000000000..1222e6c22
--- /dev/null
+++ b/tests/lib/gateguard-search-filters.test.js
@@ -0,0 +1,90 @@
+'use strict';
+/**
+ * Tests for scripts/lib/gateguard-search-filters.js.
+ *
+ * Run with: node tests/lib/gateguard-search-filters.test.js
+ */
+
+const assert = require('assert');
+const path = require('path');
+
+const { grepToolFilters, shellSearchFilters, filtersAdmitTarget, includesAdmitTarget, powershellFilterArg } = require(
+ path.join(__dirname, '..', '..', 'scripts', 'lib', 'gateguard-search-filters.js')
+);
+
+console.log('=== Testing gateguard-search-filters.js ===\n');
+
+let passed = 0;
+let failed = 0;
+
+function test(desc, fn) {
+ try {
+ fn();
+ console.log(` ✓ ${desc}`);
+ passed++;
+ } catch (e) {
+ console.log(` ✗ ${desc}: ${e.message}`);
+ failed++;
+ }
+}
+
+const ROOT = '/proj';
+const ctxFor = rel => ({ targetKey: `${ROOT}/${rel}`, resolveDir: (...parts) => path.posix.resolve(ROOT, ...parts) });
+const rgItem = (args, scope = '.') => ({ ...shellSearchFilters('rg', args), scopes: [[scope]], pathIncludes: true });
+const admits = (item, rel) => includesAdmitTarget(item, ctxFor(rel));
+
+test('Grep tool globs split into includes and exclusions', () => {
+ const filters = grepToolFilters('*.py,!tests/**,src/*.js');
+ assert.deepStrictEqual(filters.includes, ['*.py', 'src/*.js']);
+ assert.deepStrictEqual(filters.exclusions, ['tests/**']);
+});
+
+test('rg -g keeps directory-qualified includes', () => {
+ assert.deepStrictEqual(shellSearchFilters('rg', ['-g', 'src/*.js', 'foo', '.']).includes, ['src/*.js']);
+});
+
+test('a basename include matches the file name anywhere', () => {
+ assert.strictEqual(admits(rgItem(['-g', '*.py']), 'a/b/widget.py'), true);
+ assert.strictEqual(admits(rgItem(['-g', '*.md']), 'a/b/widget.py'), false);
+});
+
+test('a directory-qualified include is anchored at the search root', () => {
+ const item = rgItem(['-g', 'src/*.js']);
+ assert.strictEqual(admits(item, 'src/foo.js'), true);
+ assert.strictEqual(admits(item, 'lib/foo.js'), false);
+ assert.strictEqual(admits(item, 'vendor/src/foo.js'), false);
+ assert.strictEqual(admits(item, 'src/deep/foo.js'), false);
+});
+
+test('a leading **/ lets a directory-qualified include start anywhere', () => {
+ assert.strictEqual(admits(rgItem(['-g', '**/src/*.js']), 'vendor/src/foo.js'), true);
+});
+
+test('a directory-qualified include is relative to a narrower search path', () => {
+ assert.strictEqual(admits(rgItem(['-g', 'deep/*.js'], 'src'), 'src/deep/foo.js'), true);
+ assert.strictEqual(admits(rgItem(['-g', 'src/*.js'], 'src'), 'src/foo.js'), false);
+});
+
+test('tools that match names only never admit a directory-qualified include', () => {
+ const item = { ...shellSearchFilters('grep', ['-r', '--include=src/*.py', 'widget', '.']), scopes: [['.']], pathIncludes: false };
+ assert.strictEqual(admits(item, 'src/widget.py'), false);
+});
+
+test('an include past the length bound admits nothing', () => {
+ assert.strictEqual(admits(rgItem(['-g', `${'a'.repeat(300)}*.py`]), 'src/widget.py'), false);
+});
+
+test('an exclusion that covers the target blocks it', () => {
+ const item = rgItem(['-g', '!src/**']);
+ assert.strictEqual(filtersAdmitTarget(item, ctxFor('src/widget.py'), null), false);
+ assert.strictEqual(filtersAdmitTarget(item, ctxFor('lib/widget.py'), null), true);
+});
+
+test('PowerShell -Exclude binds from an unambiguous prefix', () => {
+ const filter = powershellFilterArg('get-childitem', ['-Recurse', '-excl', 'a.py,', 'widget.py'], 1);
+ assert.strictEqual(filter.name, 'exclude');
+ assert.deepStrictEqual(filter.globs, ['a.py', 'widget.py']);
+});
+
+console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
+process.exit(failed > 0 ? 1 : 0);