@chemx/starter-kit 26.9.16-41 → 26.9.17-1100

package/cli/audit/rules.spec.js

@@ -0,0 +1,205 @@
+import test from "node:test";
+import assert from "node:assert";
+import { auditCode } from "./rules.js";
+
+test("Audit Rules: flags repetitive dispatch switch statement as CONTROL_FLOW_DISPATCH_SWITCH", () => {
+  const code = `
+export const resolveColor = (type) => {
+  switch (type) {
+    case "primary":
+      return "blue";
+    case "secondary":
+      return "gray";
+    case "danger":
+      return "red";
+    case "warning":
+      return "yellow";
+    default:
+      return "white";
+  }
+};
+`;
+
+  const violations = auditCode(code, "src/utils/colors.js", "src/utils/colors.js");
+  const dispatchViolation = violations.find((v) => v.rule === "CONTROL_FLOW_DISPATCH_SWITCH");
+  assert.ok(dispatchViolation, "Expected CONTROL_FLOW_DISPATCH_SWITCH violation");
+  assert.strictEqual(dispatchViolation.severity, "MEDIUM");
+  assert.ok(dispatchViolation.hazard.includes("Dispatch switch smell detected"));
+});
+
+test("Audit Rules: does NOT flag non-dispatch complex switch statements", () => {
+  const code = `
+export const processOrder = (status, order) => {
+  switch (status) {
+    case "pending": {
+      validatePayment(order);
+      sendNotification(order.userId);
+      return queueForFulfillment(order);
+    }
+    case "completed": {
+      archiveOrder(order);
+      emitAnalytics("order_completed", order);
+      break;
+    }
+    default:
+      throw new Error("Invalid status");
+  }
+};
+`;
+
+  const violations = auditCode(code, "src/order.js", "src/order.js");
+  const dispatchViolation = violations.find((v) => v.rule === "CONTROL_FLOW_DISPATCH_SWITCH");
+  assert.strictEqual(dispatchViolation, undefined, "Complex switch should not be flagged as dispatch smell");
+});
+
+test("Audit Rules: clean keyed map implementation produces 0 violations", () => {
+  const code = `
+const COLOR_MAP = {
+  primary: "blue",
+  secondary: "gray",
+  danger: "red",
+  warning: "yellow"
+};
+
+export const resolveColor = (type) => {
+  return Object.prototype.hasOwnProperty.call(COLOR_MAP, type) ? COLOR_MAP[type] : "white";
+};
+`;
+
+  const violations = auditCode(code, "src/utils/colors.js", "src/utils/colors.js");
+  const dispatchViolation = violations.find((v) => v.rule === "CONTROL_FLOW_DISPATCH_SWITCH");
+  assert.strictEqual(dispatchViolation, undefined);
+});
+
+test("Audit Security: flags external link target=_blank missing rel=noopener noreferrer in JSX", () => {
+  const code = `
+export const ExternalLink = () => (
+  <a href="https://example.com" target="_blank">External</a>
+);
+`;
+  const violations = auditCode(code, "src/Link.tsx", "src/Link.tsx");
+  const violation = violations.find((v) => v.rule === "SECURITY_REVERSE_TABNABBING");
+  assert.ok(violation, "Expected SECURITY_REVERSE_TABNABBING violation in JSX");
+  assert.strictEqual(violation.severity, "MEDIUM");
+});
+
+test("Audit Security: passes external link with rel=noopener noreferrer in JSX", () => {
+  const code = `
+export const ExternalLink = () => (
+  <a href="https://example.com" target="_blank" rel="noopener noreferrer">External</a>
+);
+`;
+  const violations = auditCode(code, "src/Link.tsx", "src/Link.tsx");
+  const violation = violations.find((v) => v.rule === "SECURITY_REVERSE_TABNABBING");
+  assert.strictEqual(violation, undefined);
+});
+
+test("Audit Security: flags target=_blank missing rel in Vue template", () => {
+  const code = `
+<template>
+  <a href="https://example.com" target="_blank">External</a>
+</template>
+`;
+  const violations = auditCode(code, "src/Link.vue", "src/Link.vue");
+  const violation = violations.find((v) => v.rule === "SECURITY_REVERSE_TABNABBING");
+  assert.ok(violation, "Expected SECURITY_REVERSE_TABNABBING in Vue template");
+});
+
+test("Audit Security: flags javascript: pseudo-protocol in JSX href", () => {
+  const code = `
+export const BadLink = () => (
+  <a href="javascript:alert(1)">Click Me</a>
+);
+`;
+  const violations = auditCode(code, "src/BadLink.tsx", "src/BadLink.tsx");
+  const violation = violations.find((v) => v.rule === "SECURITY_JAVASCRIPT_URL");
+  assert.ok(violation, "Expected SECURITY_JAVASCRIPT_URL violation");
+  assert.strictEqual(violation.severity, "CRITICAL");
+});
+
+test("Audit Security: flags javascript: in template attributes", () => {
+  const code = `
+<template>
+  <form action="javascript:void(0)">
+    <button type="submit">Submit</button>
+  </form>
+</template>
+`;
+  const violations = auditCode(code, "src/Form.vue", "src/Form.vue");
+  const violation = violations.find((v) => v.rule === "SECURITY_JAVASCRIPT_URL");
+  assert.ok(violation, "Expected SECURITY_JAVASCRIPT_URL in template");
+});
+
+test("Audit Security: flags dynamic code execution via eval()", () => {
+  const code = `
+export const runDynamic = (str: string) => {
+  return eval(str);
+};
+`;
+  const violations = auditCode(code, "src/eval.ts", "src/eval.ts");
+  const violation = violations.find((v) => v.rule === "SECURITY_DYNAMIC_CODE_EXECUTION");
+  assert.ok(violation, "Expected SECURITY_DYNAMIC_CODE_EXECUTION for eval()");
+  assert.strictEqual(violation.severity, "CRITICAL");
+});
+
+test("Audit Security: flags dynamic code execution via new Function()", () => {
+  const code = `
+export const buildFn = (code: string) => {
+  return new Function("return " + code);
+};
+`;
+  const violations = auditCode(code, "src/fn.ts", "src/fn.ts");
+  const violation = violations.find((v) => v.rule === "SECURITY_DYNAMIC_CODE_EXECUTION");
+  assert.ok(violation, "Expected SECURITY_DYNAMIC_CODE_EXECUTION for new Function()");
+  assert.strictEqual(violation.severity, "CRITICAL");
+});
+
+test("Audit Security: flags string-based execution in setTimeout", () => {
+  const code = `
+export const scheduleCode = () => {
+  setTimeout("alert('hello')", 1000);
+};
+`;
+  const violations = auditCode(code, "src/timer.ts", "src/timer.ts");
+  const violation = violations.find((v) => v.rule === "SECURITY_DYNAMIC_CODE_EXECUTION");
+  assert.ok(violation, "Expected SECURITY_DYNAMIC_CODE_EXECUTION for string setTimeout");
+});
+
+test("Audit Security: does NOT flag function callback setTimeout", () => {
+  const code = `
+export const scheduleCode = () => {
+  const timer = setTimeout(() => {
+    // legitimate callback
+  }, 1000);
+  return () => clearTimeout(timer);
+};
+`;
+  const violations = auditCode(code, "src/timer.ts", "src/timer.ts");
+  const violation = violations.find((v) => v.rule === "SECURITY_DYNAMIC_CODE_EXECUTION");
+  assert.strictEqual(violation, undefined);
+});
+
+test("Audit Security: flags sensitive variable logging in console", () => {
+  const code = `
+export const debugAuth = (authToken: string, user: any) => {
+  console.log("Authenticated with token:", authToken);
+  console.info("User details:", { password: user.password });
+};
+`;
+  const violations = auditCode(code, "src/auth.ts", "src/auth.ts");
+  const loggingViolations = violations.filter((v) => v.rule === "SECURITY_SENSITIVE_LOGGING");
+  assert.strictEqual(loggingViolations.length >= 1, true, "Expected SECURITY_SENSITIVE_LOGGING violation");
+  assert.strictEqual(loggingViolations[0].severity, "HIGH");
+});
+
+test("Audit Security: does NOT flag normal non-sensitive console logging", () => {
+  const code = `
+export const debugCount = (itemCount: number) => {
+  console.log("Items rendered:", itemCount);
+};
+`;
+  const violations = auditCode(code, "src/items.ts", "src/items.ts");
+  const violation = violations.find((v) => v.rule === "SECURITY_SENSITIVE_LOGGING");
+  assert.strictEqual(violation, undefined);
+});
+

package/cli/audit-preflight-git.js

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+const SOURCE_FILE_PATTERN = /\.(tsx|ts|jsx|js|vue|svelte)$/;
+const EXCLUDED_PATTERNS = ['.test.', '.spec.', '.min.', '.d.ts'];
+
+export const isSourceFilePath = (filePath) => {
+  const isExtensionValid = SOURCE_FILE_PATTERN.test(filePath);
+  if (!isExtensionValid) return false;
+  const isExcluded = EXCLUDED_PATTERNS.some((pat) => filePath.includes(pat));
+  return !isExcluded;
+};
+
+export const parseGitStatusOutput = (output) => {
+  const lines = output.split('\n');
+  const files = [];
+
+  for (const rawLine of lines) {
+    const trimmed = rawLine.trim();
+    if (!trimmed) continue;
+    const cleanPath = trimmed.replace(/^[MADRCU?! ]+\s+/, '').trim().replace(/^"|"$/g, '');
+    if (cleanPath) {
+      files.push(cleanPath);
+    }
+  }
+
+  return files;
+};
+
+export const getGitChangedFiles = (cwd = process.cwd()) => {
+  try {
+    const result = spawnSync('git', ['status', '--porcelain', '-u'], { cwd, encoding: 'utf-8' });
+    const isSuccess = result.status === 0;
+    if (!isSuccess || !result.stdout) return [];
+    return parseGitStatusOutput(result.stdout);
+  } catch {
+    return [];
+  }
+};
+
+export const resolveGitAuditScope = (cwd = process.cwd()) => {
+  const rawFiles = getGitChangedFiles(cwd);
+  const existingSourceFiles = rawFiles.filter((relPath) => {
+    const isSource = isSourceFilePath(relPath);
+    const exists = fs.existsSync(relPath);
+    return isSource && exists;
+  });
+
+  const hasChangedFiles = existingSourceFiles.length > 0;
+  return {
+    ok: hasChangedFiles,
+    files: existingSourceFiles
+  };
+};

package/cli/audit-preflight-scope.js

@@ -0,0 +1,87 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { hasGum, gumChoose, gumInput, promptQuestion } from './terminal.js';
+import { resolveGitAuditScope } from './audit-preflight-git.js';
+
+const CANDIDATE_NAMES = ['src', 'app', 'cli', 'components', 'lib', 'packages', 'modules'];
+
+export const detectCandidateDirectories = (cwd = process.cwd()) => {
+  return CANDIDATE_NAMES.filter((name) => {
+    const fullPath = path.resolve(cwd, name);
+    return fs.existsSync(fullPath) && fs.statSync(fullPath).isDirectory();
+  });
+};
+
+const promptSpecificDirectory = async (cwd) => {
+  const candidates = detectCandidateDirectories(cwd);
+  const options = [...candidates.map((dir) => `📂 ${dir}`), '✏️  Custom directory path...'];
+
+  let choice = '';
+  if (hasGum()) {
+    choice = gumChoose(options, 'Select Target Directory:');
+  } else {
+    process.stdout.write('\n' + options.map((opt, i) => ` ${i + 1}. ${opt}`).join('\n') + '\n\n');
+    const ans = await promptQuestion(`Select directory [1-${options.length}]: `);
+    const index = parseInt(ans, 10) - 1;
+    choice = options[index] || '';
+  }
+
+  const isCustomPath = !choice || choice.includes('Custom');
+  if (isCustomPath) {
+    if (hasGum()) {
+      return gumInput('Target directory path:', 'src') || 'src';
+    }
+    const entered = await promptQuestion('Target directory path [src]: ');
+    return entered || 'src';
+  }
+
+  const matched = candidates.find((dir) => choice.includes(dir));
+  return matched || 'src';
+};
+
+export const promptAuditScope = async (defaultDir, rawArgs, cwd = process.cwd()) => {
+  const hasGitFlag = rawArgs.includes('--git') || rawArgs.includes('--changed');
+  if (hasGitFlag) {
+    const gitScope = resolveGitAuditScope(cwd);
+    return { targetDir: defaultDir, fileList: gitScope.ok ? gitScope.files : null };
+  }
+
+  const scopeOptions = [
+    '📁 Whole Project (Scan entire workspace)',
+    '📂 Specific Directory (Select target folder)',
+    '🌿 Git Changed Files (Scan modified or staged files only)'
+  ];
+
+  let scopeChoice = '';
+  if (hasGum()) {
+    scopeChoice = gumChoose(scopeOptions, 'Select Audit Scope:');
+  } else {
+    process.stdout.write('\n' + scopeOptions.map((opt, i) => ` ${i + 1}. ${opt}`).join('\n') + '\n\n');
+    const ans = await promptQuestion(`Select audit scope [1-${scopeOptions.length}]: `);
+    const index = parseInt(ans, 10) - 1;
+    scopeChoice = scopeOptions[index] || '';
+  }
+
+  const isCancelled = !scopeChoice;
+  if (isCancelled) return null;
+
+  const isGit = scopeChoice.includes('Git');
+  if (isGit) {
+    const gitScope = resolveGitAuditScope(cwd);
+    const hasFiles = gitScope.ok;
+    if (!hasFiles) {
+      process.stdout.write('\n\x1b[33m⚠ No git modified or staged source files found. Auditing whole project.\x1b[0m\n');
+      return { targetDir: defaultDir, fileList: null };
+    }
+    process.stdout.write(`\n\x1b[32m✔ Focused on ${gitScope.files.length} git modified/staged file(s).\x1b[0m\n`);
+    return { targetDir: defaultDir, fileList: gitScope.files };
+  }
+
+  const isSpecific = scopeChoice.includes('Specific');
+  if (isSpecific) {
+    const chosenDir = await promptSpecificDirectory(cwd);
+    return { targetDir: chosenDir, fileList: null };
+  }
+
+  return { targetDir: defaultDir, fileList: null };
+};

package/cli/audit-preflight.d.ts

@@ -0,0 +1,16 @@
+export interface PreflightResult {
+  readonly targetDir: string;
+  readonly fast: boolean;
+  readonly fileList: readonly string[] | null;
+}
+
+export interface PreflightOptions {
+  readonly customDir?: string | null;
+  readonly defaultDir?: string;
+  readonly cwd?: string;
+}
+
+export declare function detectCandidateDirectories(cwd?: string): string[];
+export declare function resolveGitAuditScope(cwd?: string): { ok: boolean; files: string[] };
+export declare function getGitChangedFiles(cwd?: string): string[];
+export declare function runAuditPreflight(rawArgs: readonly string[], options?: PreflightOptions): Promise<PreflightResult>;

package/cli/audit-preflight.js

@@ -0,0 +1,85 @@
+import { hasGum, gumChoose, promptQuestion } from './terminal.js';
+import { promptAuditScope } from './audit-preflight-scope.js';
+import { isNonInteractiveSession } from './audit/rules-predicates.js';
+import { resolveGitAuditScope } from './audit-preflight-git.js';
+
+export { detectCandidateDirectories } from './audit-preflight-scope.js';
+export { resolveGitAuditScope, getGitChangedFiles } from './audit-preflight-git.js';
+
+const DEPTH_OPTIONS = [
+  '🔬 Full AST Audit (Deep molecular analysis, AST visitors, slop, patterns)',
+  '⚡ Fast Scan (Instant line-budget, token burn, and file metrics)'
+];
+
+const promptAuditDepth = async (rawArgs) => {
+  const hasFastFlag = rawArgs.includes('--fast') || rawArgs.includes('--quick');
+  const hasFullFlag = rawArgs.includes('--full') || rawArgs.includes('--deep');
+
+  if (hasFastFlag) return true;
+  if (hasFullFlag) return false;
+
+  let depthChoice = '';
+  if (hasGum()) {
+    depthChoice = gumChoose(DEPTH_OPTIONS, 'Select Audit Depth:');
+  } else {
+    process.stdout.write('\n' + DEPTH_OPTIONS.map((opt, i) => ` ${i + 1}. ${opt}`).join('\n') + '\n\n');
+    const ans = await promptQuestion(`Select audit depth [1-${DEPTH_OPTIONS.length}]: `);
+    const index = parseInt(ans, 10) - 1;
+    depthChoice = DEPTH_OPTIONS[index] || '';
+  }
+
+  const isCancelled = !depthChoice;
+  if (isCancelled) return null;
+
+  return depthChoice.includes('Fast');
+};
+
+export const runAuditPreflight = async (rawArgs, options = {}) => {
+  const { customDir = null, defaultDir = 'src', cwd = process.cwd() } = options;
+
+  const isNonInteractive = isNonInteractiveSession(rawArgs);
+  const hasTty = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const hasYesFlag = rawArgs.includes('-y') || rawArgs.includes('--yes');
+  const isInteractive = !isNonInteractive && hasTty && !hasYesFlag;
+
+  const hasExplicitDir = Boolean(customDir) || rawArgs.some((arg) => arg.startsWith('--dir='));
+  const hasExplicitGit = rawArgs.includes('--git') || rawArgs.includes('--changed');
+  const hasExplicitFast = rawArgs.includes('--fast') || rawArgs.includes('--quick');
+  const hasExplicitFull = rawArgs.includes('--full') || rawArgs.includes('--deep');
+  const isFullySpecified = (hasExplicitDir || hasExplicitGit) && (hasExplicitFast || hasExplicitFull);
+
+  if (!isInteractive || isFullySpecified) {
+    const fast = hasExplicitFast;
+    const fileList = hasExplicitGit ? resolveGitAuditScope(cwd).files : null;
+    return { targetDir: customDir || defaultDir, fast, fileList };
+  }
+
+  process.stdout.write('\n\x1b[1m\x1b[38;5;45m⚡ Chemical X Protocol\x1b[0m \x1b[38;5;220mInteractive Pre-Flight\x1b[0m\n\n');
+
+  let targetDir = customDir || defaultDir;
+  let fileList = null;
+
+  const needsScopePrompt = !hasExplicitDir && !hasExplicitGit;
+  if (needsScopePrompt) {
+    const scopeResult = await promptAuditScope(defaultDir, rawArgs, cwd);
+    if (!scopeResult) {
+      process.exit(0);
+    }
+    targetDir = scopeResult.targetDir;
+    fileList = scopeResult.fileList;
+  } else if (hasExplicitGit) {
+    fileList = resolveGitAuditScope(cwd).files;
+  }
+
+  const depthResult = await promptAuditDepth(rawArgs);
+  if (depthResult === null) {
+    process.exit(0);
+  }
+  const fast = depthResult;
+
+  const modeLabel = fast ? 'Fast line-budget scan' : 'Full molecular AST audit';
+  const targetLabel = fileList ? `${fileList.length} git modified file(s)` : targetDir;
+  process.stdout.write(`\n\x1b[36m⚡ Starting ${modeLabel} for ${targetLabel}...\x1b[0m\n\n`);
+
+  return { targetDir, fast, fileList };
+};

package/cli/audit-preflight.spec.js

@@ -0,0 +1,115 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import { isSourceFilePath, parseGitStatusOutput } from './audit-preflight-git.js';
+import { detectCandidateDirectories } from './audit-preflight-scope.js';
+import { runAuditPreflight } from './audit-preflight.js';
+import { scanTree, runAudit } from './audit.js';
+import { auditCode } from './audit/rules.js';
+
+test('isSourceFilePath: correctly validates source files and excludes tests', () => {
+  assert.strictEqual(isSourceFilePath('src/app.tsx'), true);
+  assert.strictEqual(isSourceFilePath('cli/index.js'), true);
+  assert.strictEqual(isSourceFilePath('components/card.vue'), true);
+  assert.strictEqual(isSourceFilePath('ui/button.svelte'), true);
+  assert.strictEqual(isSourceFilePath('src/app.test.tsx'), false);
+  assert.strictEqual(isSourceFilePath('src/app.spec.js'), false);
+  assert.strictEqual(isSourceFilePath('dist/bundle.min.js'), false);
+  assert.strictEqual(isSourceFilePath('types/index.d.ts'), false);
+  assert.strictEqual(isSourceFilePath('README.md'), false);
+});
+
+test('parseGitStatusOutput: extracts clean file paths from git porcelain output', () => {
+  const output = [
+    ' M src/components/card.tsx',
+    'A  cli/new-command.js',
+    '?? scripts/scratch.ts',
+    ' D old-file.js',
+    '"quoted/path/with space.ts"'
+  ].join('\n');
+
+  const parsed = parseGitStatusOutput(output);
+  assert.strictEqual(parsed.length, 5);
+  assert.strictEqual(parsed[0], 'src/components/card.tsx');
+  assert.strictEqual(parsed[1], 'cli/new-command.js');
+  assert.strictEqual(parsed[2], 'scripts/scratch.ts');
+  assert.strictEqual(parsed[3], 'old-file.js');
+  assert.strictEqual(parsed[4], 'quoted/path/with space.ts');
+});
+
+test('detectCandidateDirectories: identifies existing directory targets', () => {
+  const detected = detectCandidateDirectories(process.cwd());
+  assert.ok(Array.isArray(detected));
+  assert.ok(detected.includes('cli'));
+});
+
+test('runAuditPreflight: non-interactive mode resolves immediately without questions', async () => {
+  const result = await runAuditPreflight(['--ci'], {
+    defaultDir: 'cli',
+    cwd: process.cwd()
+  });
+
+  assert.strictEqual(result.targetDir, 'cli');
+  assert.strictEqual(result.fast, false);
+  assert.strictEqual(result.fileList, null);
+});
+
+test('runAuditPreflight: explicit fast and customDir flags bypass questions', async () => {
+  const result = await runAuditPreflight(['--fast', '--dir=cli'], {
+    customDir: 'cli',
+    defaultDir: 'src',
+    cwd: process.cwd()
+  });
+
+  assert.strictEqual(result.targetDir, 'cli');
+  assert.strictEqual(result.fast, true);
+  assert.strictEqual(result.fileList, null);
+});
+
+test('runAuditPreflight: yes flag accepts defaults immediately', async () => {
+  const result = await runAuditPreflight(['-y'], {
+    defaultDir: 'cli',
+    cwd: process.cwd()
+  });
+
+  assert.strictEqual(result.targetDir, 'cli');
+  assert.strictEqual(result.fast, false);
+  assert.strictEqual(result.fileList, null);
+});
+
+test('auditCode: fast mode executes line checks and bypasses AST parser', () => {
+  const longFile = 'const a = 1;\n'.repeat(600);
+  const violations = auditCode(longFile, 'src/monolith.ts', 'src/monolith.ts', { fast: true });
+
+  assert.ok(violations.length > 0);
+  const hasLineBudget = violations.some((v) => v.rule === 'LINE_BUDGET_FILE');
+  assert.strictEqual(hasLineBudget, true);
+});
+
+test('scanTree: fileList restricts scanning strictly to specified files', () => {
+  const result = scanTree('cli', process.cwd(), {
+    fileList: ['cli/installer-templates.js']
+  });
+
+  assert.strictEqual(result.fileStats.length, 1);
+  assert.strictEqual(result.fileStats[0].relativePath, 'cli/installer-templates.js');
+});
+
+test('runAudit: fast mode returns valid health metrics with zero AST traversal', () => {
+  const report = runAudit('cli', { fast: true });
+
+  assert.ok(report.scannedFiles > 0);
+  assert.ok(report.health);
+  assert.ok(typeof report.health.score === 'number');
+  assert.ok(typeof report.health.grade === 'string');
+});
+
+test('runAuditPreflight: headless flag resolves immediately without interactive prompts', async () => {
+  const result = await runAuditPreflight(['--headless'], {
+    defaultDir: 'cli',
+    cwd: process.cwd()
+  });
+
+  assert.strictEqual(result.targetDir, 'cli');
+  assert.strictEqual(result.fast, false);
+  assert.strictEqual(result.fileList, null);
+});

package/cli/audit.js

@@ -93,15 +93,53 @@ const isSourceFile = (name) => {
 };
 
 export const auditFile = (filePath, relativePath) => {
+  if (!isSourceFile(path.basename(filePath))) return [];
   const content = fs.readFileSync(filePath, 'utf-8');
   return auditCode(content, filePath, relativePath);
 };
 
+const auditFileEntry = (fullPath, relPath, scanOptions) => {
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  const lines = content.split('\n');
+  const baseName = path.basename(fullPath);
+  const isMolecule = relPath.includes('molecules') || relPath.includes('/m-') || baseName.startsWith('m-');
+
+  const fileStat = {
+    fullPath,
+    relativePath: relPath,
+    lineCount: lines.length,
+    charCount: content.length,
+    isMolecule
+  };
+
+  const hookMatches = content.match(/\buse[A-Z0-9]\w*\b/g);
+  const hookCount = hookMatches ? hookMatches.length : 0;
+  const fileViolations = auditCode(content, fullPath, relPath, {
+    patternRegistry: scanOptions.patternRegistry,
+    fast: scanOptions.fast
+  });
+
+  return { fileStat, hookCount, fileViolations };
+};
+
 export const scanTree = (targetDir, baseDir, scanOptions = {}) => {
   let violations = [];
   let fileStats = [];
   let totalHooks = 0;
-  const { patternRegistry } = scanOptions;
+
+  if (scanOptions.fileList && scanOptions.fileList.length > 0) {
+    for (const item of scanOptions.fileList) {
+      const fullPath = path.isAbsolute(item) ? item : path.resolve(baseDir, item);
+      const relPath = path.relative(baseDir, fullPath);
+      if (fs.existsSync(fullPath) && isSourceFile(path.basename(fullPath))) {
+        const result = auditFileEntry(fullPath, relPath, scanOptions);
+        violations = violations.concat(result.fileViolations);
+        fileStats.push(result.fileStat);
+        totalHooks += result.hookCount;
+      }
+    }
+    return { violations, fileStats, totalHooks };
+  }
 
   if (!fs.existsSync(targetDir)) {
     return { violations, fileStats, totalHooks };
@@ -120,26 +158,10 @@ export const scanTree = (targetDir, baseDir, scanOptions = {}) => {
         totalHooks += sub.totalHooks;
       }
     } else if (isSourceFile(entry.name)) {
-      const content = fs.readFileSync(fullPath, 'utf-8');
-      const lines = content.split('\n');
-      const isMolecule = relPath.includes('molecules') || relPath.includes('/m-') || entry.name.startsWith('m-');
-
-      fileStats.push({
-        fullPath,
-        relativePath: relPath,
-        lineCount: lines.length,
-        charCount: content.length,
-        isMolecule
-      });
-
-      // Count hook declarations / invocations for metric
-      const hookMatches = content.match(/\buse[A-Z0-9]\w*\b/g);
-      if (hookMatches) {
-        totalHooks += hookMatches.length;
-      }
-
-      const fileViolations = auditCode(content, fullPath, relPath, { patternRegistry });
-      violations = violations.concat(fileViolations);
+      const result = auditFileEntry(fullPath, relPath, scanOptions);
+      violations = violations.concat(result.fileViolations);
+      fileStats.push(result.fileStat);
+      totalHooks += result.hookCount;
     }
   }
 
@@ -155,7 +177,11 @@ export const runAudit = (targetDir = 'src', options = {}) => {
   const cwd = process.cwd();
   const absoluteTarget = path.resolve(cwd, targetDir);
   const patternRegistry = createPatternRegistry();
-  const { violations, fileStats, totalHooks } = scanTree(absoluteTarget, cwd, { patternRegistry });
+  const { violations, fileStats, totalHooks } = scanTree(absoluteTarget, cwd, {
+    patternRegistry,
+    fast: Boolean(options.fast),
+    fileList: options.fileList || null
+  });
 
   const scannedFiles = fileStats.length;
   const totalLoc = fileStats.reduce((acc, f) => acc + f.lineCount, 0);