jhste-skills 0.1.0

package/cli/guard/scanners/single-responsibility.mjs

@@ -0,0 +1,205 @@
+import path from 'node:path';
+import { isSourceCodePath, lineAt, maskCommentsAndStrings, violation } from './utils.mjs';
+
+const DEFAULT_SETTINGS = Object.freeze({
+  function_review_lines: 80,
+  mixed_responsibility_hints: 3,
+  module_export_family_hints: 4,
+});
+
+const RESPONSIBILITY_HINTS = [
+  { label: 'input parsing', patterns: [/\b(JSON\.parse|parseArgs|process\.argv|request\.json\(|new URL\(|URLSearchParams|yaml|frontmatter)\b/i] },
+  { label: 'validation', patterns: [/\b(validate|validator|safeParse|parseAsync|schema|assert|parseEnv|errors\.push)\b/i] },
+  { label: 'filesystem IO', patterns: [/\b(fs\.|readFile|writeFile|mkdir|rmSync|cpSync|readdirSync)\b/i] },
+  { label: 'process/git/network IO', patterns: [/\b(spawnSync|execFileSync|fetch\(|axios\.|git\(|git\s+-C)\b/i] },
+  { label: 'persistence', patterns: [/\b(prisma|pool\.query|client\.query|db\.|INSERT\s+INTO|UPDATE\s+\w|DELETE\s+FROM|SELECT\s+.+\s+FROM)\b/i] },
+  { label: 'rendering/reporting', patterns: [/\b(console\.|Response\.json|NextResponse\.json|res\.json|render|markdown|tableRows|print|logger\.)\b/i] },
+  { label: 'prompting', patterns: [/\b(ask\(|readline|question\(|prompt)\b/i] },
+  { label: 'data transformation', patterns: [/\btransform|serialize|deserialize\b/i] },
+  { label: 'time/crypto policy', patterns: [/\b(Date\.now|new Date\(|crypto\.|randomUUID|createHash)\b/i] },
+];
+
+const EXPORT_NAME_FAMILIES = [
+  { family: 'argument parsing', pattern: /^(parseArgs|arg|args|option|options|usage|mode|choice|normalize)$/i },
+  { family: 'git/repo discovery', pattern: /^(git|repo|repository|branch|changed|staged)$/i },
+  { family: 'filesystem', pattern: /^(file|files|dir|directory|path|read|write|copy|digest|atomic|ensure)$/i },
+  { family: 'prompting', pattern: /^(ask|confirm|prompt|question|user)$/i },
+  { family: 'time/template', pattern: /^(now|template|profile|bridge|block|time)$/i },
+  { family: 'validation/schema', pattern: /^(validate|validator|schema|known|default|settings)$/i },
+  { family: 'reporting', pattern: /^(print|render|report|summary|table)$/i },
+  { family: 'install orchestration', pattern: /^(install|apply|preflight|hook|skill|manifest)$/i },
+];
+
+function settingsOrDefault(settings = {}) {
+  return { ...DEFAULT_SETTINGS, ...(settings || {}) };
+}
+
+function matchingHints(text) {
+  return RESPONSIBILITY_HINTS
+    .filter((hint) => hint.patterns.some((pattern) => pattern.test(text)))
+    .map((hint) => hint.label);
+}
+
+function functionDeclarations(text) {
+  const pattern = /(?:^|\n)([ \t]*(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\([^)]*\)\s*\{|[ \t]*(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?\([^)]*\)\s*=>\s*\{)/gu;
+  const out = [];
+  for (const match of text.matchAll(pattern)) {
+    const declaration = match[1];
+    const name = match[2] || match[3] || 'anonymous';
+    const start = (match.index || 0) + (match[0].startsWith('\n') ? 1 : 0);
+    const openBrace = text.indexOf('{', start + declaration.indexOf(declaration.trim()));
+    if (openBrace === -1) continue;
+    const end = matchingBraceIndex(text, openBrace);
+    if (end === -1) continue;
+    out.push({ name, start, end, body: text.slice(start, end + 1) });
+  }
+  return out;
+}
+
+function matchingBraceIndex(text, openBrace) {
+  let depth = 0;
+  let quote = '';
+  let escaped = false;
+  for (let index = openBrace; index < text.length; index += 1) {
+    const char = text[index];
+    if (quote) {
+      escaped = char === '\\' && !escaped;
+      if (char === quote && !escaped) quote = '';
+      if (char !== '\\') escaped = false;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === '`') {
+      quote = char;
+      continue;
+    }
+    if (char === '{') depth += 1;
+    if (char === '}') {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
+  }
+  return -1;
+}
+
+
+function pythonFunctionDeclarations(text) {
+  const lines = text.split(/\r?\n/);
+  const out = [];
+  let offset = 0;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const match = /^(\s*)def\s+([A-Za-z_][\w]*)\s*\([^)]*\)\s*:/.exec(line);
+    if (!match) {
+      offset += line.length + 1;
+      continue;
+    }
+    const indent = match[1].length;
+    const start = offset;
+    let endLine = index + 1;
+    for (; endLine < lines.length; endLine += 1) {
+      const candidate = lines[endLine];
+      if (!candidate.trim()) continue;
+      const candidateIndent = /^(\s*)/.exec(candidate)?.[1]?.length || 0;
+      if (candidateIndent <= indent) break;
+    }
+    const body = lines.slice(index, endLine).join('\n');
+    out.push({ name: match[2], start, end: start + body.length, body });
+    for (let consumed = index; consumed < endLine; consumed += 1) offset += lines[consumed].length + 1;
+    index = Math.max(index, endLine - 1);
+  }
+  return out;
+}
+
+function declarationsForPath(relPath, text) {
+  return relPath.endsWith('.py') ? pythonFunctionDeclarations(text) : functionDeclarations(text);
+}
+
+function exportedCallableNames(text) {
+  const names = [];
+  for (const match of text.matchAll(/(?:^|\n)\s*export\s+(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(/gu)) names.push(match[1]);
+  for (const match of text.matchAll(/(?:^|\n)\s*export\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?\(/gu)) names.push(match[1]);
+  return [...new Set(names.filter(Boolean))];
+}
+
+function nameTokens(name) {
+  return String(name)
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .split(/[^A-Za-z0-9]+/)
+    .map((token) => token.toLowerCase())
+    .filter(Boolean);
+}
+
+function exportFamilies(names) {
+  const families = new Set();
+  for (const name of names) {
+    const tokens = new Set(nameTokens(name));
+    for (const candidate of EXPORT_NAME_FAMILIES) {
+      if (candidate.pattern.test(name) || [...tokens].some((token) => candidate.pattern.test(token))) families.add(candidate.family);
+    }
+  }
+  return [...families];
+}
+
+function onlyReexports(text) {
+  const meaningful = text
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('//'));
+  return meaningful.length > 0 && meaningful.every((line) => /^export\s+.*\s+from\s+['"][^'"]+['"];?$/.test(line));
+}
+
+export function scanSingleResponsibility(relPath, text, rawSettings = {}) {
+  if (!isSourceCodePath(relPath)) return [];
+  if (/(^|\/)scripts\/smoke\/|fixtures-test\.mjs$/.test(relPath)) return [];
+  const ext = path.extname(relPath).toLowerCase();
+  if (!['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.py'].includes(ext)) return [];
+  const settings = settingsOrDefault(rawSettings);
+  const out = [];
+  const scanText = maskCommentsAndStrings(text);
+
+  for (const fn of declarationsForPath(relPath, scanText)) {
+    const lineCount = fn.body.split(/\r?\n/).length;
+    const hints = matchingHints(fn.body);
+    const scannerLikeFunction = /^scan[A-Z_]/.test(fn.name) || fn.name === 'scanMixedResponsibilities';
+    const optionNormalizer = /^normalize/.test(fn.name) && hints.every((hint) => ['input parsing', 'validation', 'filesystem IO'].includes(hint));
+    if (lineCount >= settings.function_review_lines) {
+      out.push(violation({
+        ruleId: 'srp.function.length',
+        severity: 'warning',
+        relPath,
+        line: lineAt(text, fn.start),
+        symbol: fn.name,
+        message: `${fn.name} is ${lineCount} lines; name its one responsibility and consider whether a real seam would improve locality.`,
+        confidence: 'medium',
+      }));
+    }
+    if ((fn.name === 'main' && lineCount < settings.function_review_lines) || scannerLikeFunction || optionNormalizer) continue;
+    if (hints.length >= settings.mixed_responsibility_hints) {
+      out.push(violation({
+        ruleId: 'srp.function.mixed_responsibility',
+        severity: 'warning',
+        relPath,
+        line: lineAt(text, fn.start),
+        symbol: fn.name,
+        message: `${fn.name} appears to mix ${hints.slice(0, 5).join(', ')}; review whether one responsibility can move behind a named seam without creating pass-through wrappers.`,
+        confidence: 'low',
+      }));
+    }
+  }
+
+  if (!onlyReexports(text)) {
+    const families = exportFamilies(exportedCallableNames(scanText));
+    if (families.length >= settings.module_export_family_hints) {
+      out.push(violation({
+        ruleId: 'srp.module.mixed_exports',
+        severity: 'warning',
+        relPath,
+        symbol: 'module-exports',
+        message: `Module exports span ${families.slice(0, 6).join(', ')}; review whether this is a cohesive deep module or a shared utility bucket.`,
+        confidence: 'low',
+      }));
+    }
+  }
+
+  return out;
+}

package/cli/guard/scanners/ui-runtime.mjs

@@ -0,0 +1,140 @@
+import {
+  countMatches,
+  hasUseClientDirective,
+  lineAt,
+  violation,
+} from './utils.mjs';
+
+export function scanClientServerBoundary(relPath, text) {
+  if (!hasUseClientDirective(text)) return [];
+  const out = [];
+  const pattern = /^\s*import\s+(?!type\b)[^;\n]*\sfrom\s+['"]([^'"]+)['"]/gmu;
+  for (const match of text.matchAll(pattern)) {
+    const source = match[1] || '';
+    if (/^(fs|path|crypto|child_process|server-only|next\/headers|next\/cookies|next\/server)$/.test(source)
+      || /(^|\/)(server|db|database|repositories?|prisma|postgres)(\/|$)/i.test(source)) {
+      out.push(violation({
+        ruleId: 'boundary.import.server_in_client',
+        severity: 'error',
+        relPath,
+        line: lineAt(text, match.index || 0),
+        symbol: `import:${source}`,
+        message: `Client file imports server/runtime module '${source}'. Move loading to a server boundary or pass shaped data into the client module.`,
+        confidence: 'high',
+      }));
+    }
+  }
+  return out;
+}
+
+export function scanStateSafety(relPath, text) {
+  const out = [];
+  if (!/\.(tsx?|jsx?)$/u.test(relPath)) return out;
+  for (const match of text.matchAll(/\b[A-Za-z_$][\w$]*!\s*(?:\.|\[|\()/gu)) {
+    out.push(violation({
+      ruleId: 'state.non_null_assertion',
+      severity: 'warning',
+      relPath,
+      line: lineAt(text, match.index || 0),
+      symbol: match[0].trim(),
+      message: 'Non-null assertion hides null or empty-state risk; prefer an explicit guard or fallback on the affected path.',
+      confidence: 'medium',
+    }));
+  }
+  if ((hasUseClientDirective(text) || /page\.(tsx|jsx)$/.test(relPath))
+    && /\b(useQuery|useSuspenseQuery|fetch\s*\(|axios\.)\b/.test(text)
+    && !/\b(isLoading|loading|isError|error|notFound|empty|Empty|skeleton|placeholder)\b/.test(text)) {
+    out.push(violation({
+      ruleId: 'state.async_ui_missing_fallback',
+      severity: 'warning',
+      relPath,
+      symbol: 'async-ui-state',
+      message: 'Async UI path has data-loading hints but no obvious loading, empty, or error fallback; review state handling before ship.',
+      confidence: 'low',
+    }));
+  }
+  return out;
+}
+
+export function scanRuntimeEnvSafety(relPath, text) {
+  const out = [];
+  const lines = text.split(/\r?\n/);
+  lines.forEach((line, index) => {
+    if (/\bprocess\.env\.(?!NODE_ENV\b|JHSTE_HOOK_ACTIVE\b)[A-Z0-9_]+\b/.test(line) && !/\?\?|\|\||default|safeParse|parseEnv|assertEnv|requiredEnv|validate|schema/i.test(line)) {
+      out.push(violation({
+        ruleId: 'runtime.env_direct_access',
+        severity: 'warning',
+        relPath,
+        line: index + 1,
+        symbol: line.trim(),
+        message: 'Env var is read directly without an obvious validation or fallback path; review build/runtime setup safety.',
+        confidence: 'medium',
+      }));
+    }
+    if (/\bimport\.meta\.env\.(?!MODE\b|DEV\b|PROD\b|SSR\b)[A-Z0-9_]+\b/.test(line) && !/\?\?|\|\||default|safeParse|validate|schema/i.test(line)) {
+      out.push(violation({
+        ruleId: 'runtime.import_meta_env_direct_access',
+        severity: 'warning',
+        relPath,
+        line: index + 1,
+        symbol: line.trim(),
+        message: 'Client env var is read directly without an obvious fallback or validation; review runtime safety before ship.',
+        confidence: 'medium',
+      }));
+    }
+    if (/\bos\.getenv\(['"][A-Z0-9_]+['"]\)/.test(line) && !/\bor\b|\bif\b|default|validate|schema/i.test(line)) {
+      out.push(violation({
+        ruleId: 'runtime.getenv_direct_access',
+        severity: 'warning',
+        relPath,
+        line: index + 1,
+        symbol: line.trim(),
+        message: 'Python env lookup has no obvious fallback or validation; review startup/runtime safety.',
+        confidence: 'medium',
+      }));
+    }
+  });
+  return out;
+}
+
+export function scanPerformanceDuplicateFetch(relPath, text) {
+  const out = [];
+  if (!/\.(tsx?|jsx?)$/u.test(relPath)) return out;
+  const fetchCount = countMatches(text, /\b(fetch\s*\(|axios\.|useQuery\s*\(|useSuspenseQuery\s*\()/g);
+  if (fetchCount >= 2) {
+    out.push(violation({
+      ruleId: 'performance.multiple_fetch_sources',
+      severity: 'warning',
+      relPath,
+      symbol: `fetch-count:${fetchCount}`,
+      message: 'File appears to trigger multiple fetch paths; review whether duplicate requests or split caches are avoidable.',
+      confidence: 'low',
+    }));
+  }
+  if (hasUseClientDirective(text) && /useEffect\s*\([\s\S]{0,500}\b(fetch\s*\(|axios\.)/su.test(text)) {
+    out.push(violation({
+      ruleId: 'performance.fetch_in_effect',
+      severity: 'warning',
+      relPath,
+      symbol: 'fetch-in-effect',
+      message: 'Client module fetches inside useEffect; review whether the request can move to a cached loader or shared data hook.',
+      confidence: 'low',
+    }));
+  }
+  return out;
+}
+
+export function scanSideEffectBoundary(relPath, text) {
+  if (!/\.(tsx?|jsx?|mjs|cjs|py)$/u.test(relPath)) return [];
+  if (/function\s+(format|helper|build|make|map)\w*\s*\([^)]*\)\s*{[\s\S]{0,1200}\b(fetch|writeFile|readFile|exec|spawn|setTimeout)\b/.test(text)) {
+    return [violation({
+      ruleId: 'side_effect.hidden_in_helper',
+      severity: 'warning',
+      relPath,
+      symbol: 'hidden-side-effect',
+      message: 'Generic helper appears to perform a side effect; make the side-effect seam visible in name, directory, or dependency injection.',
+      confidence: 'low',
+    })];
+  }
+  return [];
+}

package/cli/guard/scanners/utils.mjs

@@ -0,0 +1,167 @@
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export function normalizePath(value) {
+  return value.replaceAll(path.sep, '/').replace(/^\.\//, '');
+}
+
+export function lineAt(text, index) {
+  return text.slice(0, index).split(/\r?\n/).length;
+}
+
+export function maskCommentsAndStrings(text) {
+  const input = String(text || '');
+  let output = '';
+  let state = 'code';
+  let quote = '';
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index];
+    const next = input[index + 1] || '';
+    if (state === 'line-comment') {
+      if (char === '\n') {
+        state = 'code';
+        output += '\n';
+      } else {
+        output += ' ';
+      }
+      continue;
+    }
+    if (state === 'block-comment') {
+      if (char === '*' && next === '/') {
+        output += '  ';
+        index += 1;
+        state = 'code';
+      } else {
+        output += char === '\n' ? '\n' : ' ';
+      }
+      continue;
+    }
+    if (state === 'string') {
+      if (char === '\\') {
+        output += ' ';
+        if (next) {
+          output += next === '\n' ? '\n' : ' ';
+          index += 1;
+        }
+        continue;
+      }
+      output += char === '\n' ? '\n' : ' ';
+      if (char === quote) {
+        state = 'code';
+        quote = '';
+      }
+      continue;
+    }
+    if (char === '/' && next === '/') {
+      output += '  ';
+      index += 1;
+      state = 'line-comment';
+      continue;
+    }
+    if (char === '/' && next === '*') {
+      output += '  ';
+      index += 1;
+      state = 'block-comment';
+      continue;
+    }
+    if (char === '"' || char === "'" || char === '`') {
+      output += ' ';
+      quote = char;
+      state = 'string';
+      continue;
+    }
+    output += char;
+  }
+  return output;
+}
+
+export function localWindow(text, index, before = 320, after = 520) {
+  const start = Math.max(0, Number(index || 0) - before);
+  const end = Math.min(String(text || '').length, Number(index || 0) + after);
+  return String(text || '').slice(start, end);
+}
+
+export function hasUseClientDirective(text) {
+  return /^\s*(?:"use client"|'use client')\s*;?/u.test(text);
+}
+
+export function isRouteLikePath(relPath) {
+  return /(^|\/)(api|routes?|controllers?|pages\/api)\//i.test(relPath) || /route\.(ts|js)$/.test(relPath);
+}
+
+export function isScriptPipelinePath(relPath) {
+  return /(^|\/)scripts\/(data|ops|import|imports|backfill|repair|migrate|migration)\//.test(relPath);
+}
+
+export function isSourceCodePath(relPath) {
+  return ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.py'].includes(path.extname(relPath).toLowerCase());
+}
+
+export function isCrawlerProducerPath(relPath) {
+  return /(^|\/)(crawler|crawlers|scraper|scrapers|automation|workers?|schedulers?)\//i.test(relPath)
+    || /crawler|scraper|automation|producer/i.test(path.basename(relPath));
+}
+
+export function hasPersistenceRead(text) {
+  return /\b(prisma\.\w+\.(find(?:Unique|First|Many)?|aggregate|count)|pool\.query|client\.query|db\.|database\.)\b/i.test(text)
+    || /\bSELECT\b[\s\S]{0,120}\bFROM\b/i.test(text);
+}
+
+export function hasPersistenceWrite(text) {
+  return /\b(prisma\.\w+\.(create|update|delete|upsert)|pool\.query|client\.query|db\.)\b/i.test(text)
+    || /\b(INSERT\s+INTO|UPDATE\s+\w+\s+SET|DELETE\s+FROM)\b/i.test(text);
+}
+
+export function hasPersistenceAccess(text) {
+  return hasPersistenceRead(text) || hasPersistenceWrite(text);
+}
+
+export function hasReadHandler(text) {
+  return /\b(export\s+async\s+function\s+GET|router\.get|app\.get)\b/i.test(text);
+}
+
+export function hasMutationHandler(text) {
+  return /\b(export\s+async\s+function\s+(POST|PUT|PATCH|DELETE)|router\.(post|put|patch|delete)|app\.(post|put|patch|delete))\b/i.test(text);
+}
+
+export function hasAuthContext(text) {
+  return /\b(auth\s*\(|session|currentUser|getUser|permission|requireUser|requireAuth)\b/i.test(text);
+}
+
+export function hasScopeHint(text) {
+  return /\b(userId|user\.id|accountId|orgId|tenantId|ownerId|workspaceId|teamId|projectId|where\s*:|filter\s*:)\b/i.test(text);
+}
+
+export function countMatches(text, pattern) {
+  return [...text.matchAll(pattern)].length;
+}
+
+function occurrenceKeyFor(ruleId, relPath, symbol, line) {
+  const stable = `${ruleId}|${normalizePath(relPath)}|${line || 1}|${symbol || ''}`;
+  return crypto.createHash('sha1').update(stable).digest('hex').slice(0, 16);
+}
+
+function fingerprintFor(ruleId, relPath, occurrenceKey) {
+  const stable = `${ruleId}|${normalizePath(relPath)}|${occurrenceKey}`;
+  return crypto.createHash('sha1').update(stable).digest('hex');
+}
+
+export function violation({ ruleId, severity, relPath, line = 1, symbol = '', message, source = 'builtin', confidence = 'medium', relatedKey = '' }) {
+  const isHeuristic = confidence !== 'high';
+  const occurrenceKey = occurrenceKeyFor(ruleId, relPath, symbol, line);
+  return {
+    rule_id: ruleId,
+    severity,
+    path: normalizePath(relPath),
+    line,
+    symbol,
+    message,
+    occurrence_key: occurrenceKey,
+    fingerprint: fingerprintFor(ruleId, relPath, occurrenceKey),
+    source,
+    confidence,
+    category: isHeuristic ? 'heuristic_candidate' : 'proof_like',
+    why_not_proof: isHeuristic ? 'Pattern-based scanner result; confirm against code context before treating as proof.' : null,
+    related_key: relatedKey || null,
+  };
+}

package/cli/guard/scope.mjs

@@ -0,0 +1,181 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const TEXT_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.py', '.yml', '.yaml']);
+const EXCLUDED_DIRS = new Set(['.git', 'node_modules', 'vendor', 'dist', 'build', '.next', 'out', 'coverage', '.turbo', '.cache', '__pycache__']);
+const EXCLUDED_FILE_NAMES = new Set(['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lockb', 'bun.lock', 'poetry.lock', 'Pipfile.lock']);
+const SECRET_FILE_RE = /(^|\/)(\.env(\..*)?|.*\.(pem|key|p12|pfx|crt)|id_rsa|id_ed25519)$/i;
+
+function git(repoRoot, args, options = {}) {
+  return execFileSync('git', ['-C', repoRoot, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    ...options,
+  });
+}
+
+function normalizePath(value) {
+  return value.replaceAll(path.sep, '/').replace(/^\.\//, '');
+}
+
+function isScannablePath(relPath) {
+  const normalized = normalizePath(relPath);
+  if (!normalized || normalized.startsWith('..')) return false;
+  if (EXCLUDED_FILE_NAMES.has(path.basename(normalized)) || SECRET_FILE_RE.test(normalized)) return false;
+  if (normalized.split('/').some((part) => EXCLUDED_DIRS.has(part))) return false;
+  return TEXT_EXTENSIONS.has(path.extname(normalized).toLowerCase());
+}
+
+function listAllFiles(repoRoot) {
+  const out = [];
+  function walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      const rel = normalizePath(path.relative(repoRoot, full));
+      if (entry.isDirectory()) {
+        if (!EXCLUDED_DIRS.has(entry.name)) walk(full);
+        continue;
+      }
+      if (entry.isFile() && isScannablePath(rel)) out.push(rel);
+    }
+  }
+  walk(repoRoot);
+  return out;
+}
+
+function listGitBackedAllFiles(repoRoot) {
+  return readGitPathList(repoRoot, ['ls-files', '--cached', '--others', '--exclude-standard', '-z']);
+}
+
+function readNulFile(filePath) {
+  const raw = fs.readFileSync(filePath);
+  return raw.toString('utf8').split('\0').map((item) => item.trim()).filter(Boolean);
+}
+
+function readGitPathList(repoRoot, args) {
+  const raw = execFileSync('git', ['-C', repoRoot, ...args], { encoding: 'buffer', stdio: ['ignore', 'pipe', 'pipe'] });
+  return raw.toString('utf8').split('\0').map((item) => item.trim()).filter(Boolean);
+}
+
+function resolveBaseRef(repoRoot, explicitBase, headRef) {
+  if (explicitBase) return explicitBase;
+  for (const candidate of ['origin/main', 'main', 'origin/master', 'master']) {
+    try {
+      git(repoRoot, ['rev-parse', '--verify', '--quiet', `${candidate}^{commit}`]);
+      return git(repoRoot, ['merge-base', candidate, headRef]).trim();
+    } catch {
+      // Try the next common base candidate.
+    }
+  }
+  try {
+    return git(repoRoot, ['rev-parse', `${headRef}^`]).trim();
+  } catch {
+    return '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+  }
+}
+
+function repoRelativePath(repoRoot, rawPath) {
+  const raw = String(rawPath || '').trim();
+  if (!raw) return '';
+  const resolved = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(repoRoot, raw);
+  const relative = normalizePath(path.relative(repoRoot, resolved));
+  if (!relative || relative === '.') return '';
+  if (relative.startsWith('../') || relative === '..' || path.isAbsolute(relative)) {
+    throw new Error(`Path escapes repo root: ${raw}`);
+  }
+  return relative;
+}
+
+function uniqueExistingScannableWithCount(repoRoot, relPaths) {
+  const normalized = [];
+  for (const relPath of relPaths) {
+    if (!relPath) continue;
+    normalized.push(repoRelativePath(repoRoot, relPath));
+  }
+  const unique = [...new Set(normalized)].sort();
+  return {
+    considered: unique.length,
+    files: unique.filter(isScannablePath).filter((rel) => fs.existsSync(path.join(repoRoot, rel))),
+  };
+}
+
+function scopePayload(repoRoot, scope, relPaths, gitMeta = {}) {
+  const { files, considered } = uniqueExistingScannableWithCount(repoRoot, relPaths);
+  return { scope, files, files_considered: considered, git: gitMeta };
+}
+
+export function resolveScopeFiles(repoRoot, args, callbacks = {}) {
+  const failConfig = callbacks.failConfig || ((message) => { throw new Error(message); });
+  const failGuard = callbacks.failGuard || ((message) => { throw new Error(message); });
+  const scope = String(args.scope || 'changed');
+  if (!['changed', 'staged', 'all', 'files-from'].includes(scope)) {
+    failConfig(`Unsupported --scope ${scope}. Use changed, staged, all, or files-from.`);
+  }
+  const gitMeta = {
+    root: repoRoot,
+    head: '',
+    base: '',
+    file_source: null,
+    fallback_reason: null,
+  };
+  try {
+    gitMeta.head = git(repoRoot, ['rev-parse', '--short', 'HEAD']).trim();
+  } catch {
+    gitMeta.head = 'unavailable';
+  }
+
+  if (scope === 'all') {
+    try {
+      git(repoRoot, ['rev-parse', '--is-inside-work-tree']);
+      const rawFiles = listGitBackedAllFiles(repoRoot);
+      gitMeta.file_source = 'git-ls-files';
+      return scopePayload(repoRoot, scope, rawFiles, gitMeta);
+    } catch (error) {
+      gitMeta.file_source = 'filesystem-fallback';
+      gitMeta.fallback_reason = error instanceof Error ? error.message : String(error);
+      const files = listAllFiles(repoRoot).sort();
+      return { scope, files, files_considered: files.length, git: gitMeta };
+    }
+  }
+
+  if (scope === 'files-from') {
+    if (!args['files-from']) failConfig('--scope files-from requires --files-from <nul-delimited-file>.');
+    let rawPaths;
+    try {
+      rawPaths = readNulFile(path.resolve(String(args['files-from'])));
+    } catch (error) {
+      failGuard('Failed to read --files-from input.', [error instanceof Error ? error.message : String(error)]);
+    }
+    try {
+      return scopePayload(repoRoot, scope, rawPaths, gitMeta);
+    } catch (error) {
+      failGuard('Invalid path in --files-from input.', [error instanceof Error ? error.message : String(error)]);
+    }
+  }
+
+  if (scope === 'staged') {
+    try {
+      return scopePayload(repoRoot, scope, readGitPathList(repoRoot, ['diff', '--cached', '--name-only', '-z', '--diff-filter=ACMRTUX', '--']), gitMeta);
+    } catch (error) {
+      failGuard('Failed to resolve staged files.', [error instanceof Error ? error.message : String(error)]);
+    }
+  }
+
+  try {
+    const headRef = String(args.head || 'HEAD');
+    const baseRef = resolveBaseRef(repoRoot, args.base ? String(args.base) : '', headRef);
+    gitMeta.head = git(repoRoot, ['rev-parse', '--short', headRef]).trim();
+    gitMeta.base = baseRef;
+    const files = [
+      ...readGitPathList(repoRoot, ['diff', '--name-only', '-z', '--diff-filter=ACMRTUX', baseRef, headRef, '--']),
+      ...readGitPathList(repoRoot, ['diff', '--name-only', '-z', '--diff-filter=ACMRTUX', '--']),
+      ...readGitPathList(repoRoot, ['diff', '--cached', '--name-only', '-z', '--diff-filter=ACMRTUX', '--']),
+      ...readGitPathList(repoRoot, ['ls-files', '--others', '--exclude-standard', '-z']),
+    ];
+    return scopePayload(repoRoot, scope, files, gitMeta);
+  } catch (error) {
+    failGuard('Failed to resolve changed files.', [error instanceof Error ? error.message : String(error)]);
+  }
+  return { scope, files: [], files_considered: 0, git: gitMeta };
+}