quick-gate 0.2.0-alpha.1

package/src/cli.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { loadChangedFiles } from './fs-utils.js';
+import { executeRun } from './run-command.js';
+import { executeSummarize } from './summarize-command.js';
+import { executeRepair } from './repair-command.js';
+import { checkEnvironment, hasOllama } from './env-check.js';
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) continue;
+    const key = token.replace(/^--/, '');
+    const value = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : true;
+    args[key] = value;
+    if (value !== true) i += 1;
+  }
+  return args;
+}
+
+function usage() {
+  console.log(`Quick Gate v0.2.0-alpha
+
+Commands:
+  quick-gate run --mode canary|full --changed-files <path>
+  quick-gate summarize --input .quick-gate/failures.json
+  quick-gate repair --input .quick-gate/failures.json [--max-attempts 3] [--deterministic-only]
+
+Options:
+  --deterministic-only   Skip model-assisted repair (no Ollama required)
+  --help, -h             Show this help message`);
+}
+
+async function main() {
+  const [, , cmd, ...rest] = process.argv;
+  if (!cmd || cmd === '--help' || cmd === '-h') {
+    usage();
+    process.exit(0);
+  }
+
+  const args = parseArgs(rest);
+
+  const warnings = checkEnvironment({ command: cmd });
+  for (const w of warnings) {
+    console.error(`[quick-gate] ${w}`);
+  }
+
+  try {
+    if (cmd === 'run') {
+      if (!args.mode || !['canary', 'full'].includes(String(args.mode))) {
+        throw new Error('run requires --mode canary|full');
+      }
+      if (!args['changed-files']) {
+        throw new Error('run requires --changed-files <path>');
+      }
+      const changedFilesPath = path.resolve(process.cwd(), String(args['changed-files']));
+      const changedFiles = loadChangedFiles(changedFilesPath);
+      const result = executeRun({ mode: String(args.mode), changedFiles });
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(result.status === 'pass' ? 0 : 1);
+    }
+
+    if (cmd === 'summarize') {
+      if (!args.input) {
+        throw new Error('summarize requires --input <path>');
+      }
+      const result = executeSummarize({ input: String(args.input) });
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(0);
+    }
+
+    if (cmd === 'repair') {
+      if (!args.input) {
+        throw new Error('repair requires --input <path>');
+      }
+      const deterministicOnly = args['deterministic-only'] === true || !hasOllama();
+      const result = executeRepair({
+        input: String(args.input),
+        maxAttempts: args['max-attempts'],
+        deterministicOnly,
+      });
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(result.status === 'pass' ? 0 : 2);
+    }
+
+    throw new Error(`Unknown command: ${cmd}`);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+main();

package/src/config.js

@@ -0,0 +1,38 @@
+import path from 'node:path';
+import { DEFAULT_POLICY } from './constants.js';
+import { fileExists, readJsonFileSync } from './fs-utils.js';
+
+export function loadConfig(cwd = process.cwd()) {
+  const configPath = path.join(cwd, 'quick-gate.config.json');
+  if (!fileExists(configPath)) {
+    return {
+      policy: { ...DEFAULT_POLICY },
+      commands: {},
+      lighthouse: {
+        thresholds: {
+          performance: 0.8,
+          accessibility: 0.8,
+          'best-practices': 0.8,
+          seo: 0.8,
+        },
+      },
+      source: 'defaults',
+    };
+  }
+
+  const userConfig = readJsonFileSync(configPath);
+  return {
+    policy: { ...DEFAULT_POLICY, ...(userConfig.policy || {}) },
+    commands: { ...(userConfig.commands || {}) },
+    lighthouse: {
+      thresholds: {
+        performance: 0.8,
+        accessibility: 0.8,
+        'best-practices': 0.8,
+        seo: 0.8,
+        ...(userConfig.lighthouse?.thresholds || {}),
+      },
+    },
+    source: configPath,
+  };
+}

package/src/constants.js

@@ -0,0 +1,20 @@
+export const QUICK_GATE_DIR = '.quick-gate';
+export const FAILURES_FILE = '.quick-gate/failures.json';
+export const RUN_METADATA_FILE = '.quick-gate/run-metadata.json';
+export const AGENT_BRIEF_MD_FILE = '.quick-gate/agent-brief.md';
+export const AGENT_BRIEF_JSON_FILE = '.quick-gate/agent-brief.json';
+
+export const DEFAULT_POLICY = {
+  maxAttempts: 3,
+  maxPatchLines: 150,
+  abortOnNoImprovement: 2,
+  timeCapMs: 20 * 60 * 1000,
+};
+
+export const ESCALATION_CODES = {
+  NO_IMPROVEMENT: 'NO_IMPROVEMENT',
+  PATCH_BUDGET_EXCEEDED: 'PATCH_BUDGET_EXCEEDED',
+  ARCHITECTURAL_CHANGE_REQUIRED: 'ARCHITECTURAL_CHANGE_REQUIRED',
+  FLAKY_EVALUATOR: 'FLAKY_EVALUATOR',
+  UNKNOWN_BLOCKER: 'UNKNOWN_BLOCKER',
+};

package/src/deterministic-prefix.js

@@ -0,0 +1,66 @@
+import path from 'node:path';
+import { runCommand } from './exec.js';
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'"'"'`)}'`;
+}
+
+function inScopeFiles(failures) {
+  const fromChanged = Array.isArray(failures.changed_files) ? failures.changed_files : [];
+  const fromFindings = (failures.findings || []).flatMap((f) => (Array.isArray(f.files) ? f.files : []));
+  const unique = [];
+  const seen = new Set();
+  for (const file of [...fromChanged, ...fromFindings]) {
+    if (!file || seen.has(file)) continue;
+    seen.add(file);
+    unique.push(file);
+  }
+  return unique;
+}
+
+function hasGateFailure(failures, gate) {
+  return (failures.findings || []).some((f) => f.gate === gate);
+}
+
+function runLintProblemAutofix({ cwd, files }) {
+  if (files.length === 0) return null;
+  const fileArgs = files.map((f) => shellQuote(f)).join(' ');
+  const cmd = `npx eslint ${fileArgs} --fix --fix-type problem`;
+  const result = runCommand(cmd, { cwd });
+  return {
+    rule_id: 'LINT_PROBLEM_AUTOFIX',
+    strategy: 'deterministic_prefix',
+    accepted: result.exit_code === 0,
+    command: cmd,
+    exit_code: result.exit_code,
+    files,
+    rationale: 'Apply only ESLint problem fixes on scoped files to minimize semantic-risk edits.',
+  };
+}
+
+export function runDeterministicPreFix({ cwd, failures }) {
+  const actions = [];
+  const isEligibleFile = (f) => {
+    if (!/\.(js|jsx|ts|tsx|mjs|cjs)$/.test(f)) return false;
+    if (/(^|\/)(dist|build|coverage|\.next)\//.test(f)) return false;
+    if (/\.min\.(js|mjs|cjs)$/.test(f)) return false;
+    return true;
+  };
+  const scopedFiles = inScopeFiles(failures)
+    .filter((f) => !f.startsWith('.'))
+    .filter((f) => !path.isAbsolute(f))
+    .filter((f) => !f.includes('..'))
+    .filter((f) => !f.includes('node_modules'))
+    .filter((f) => path.extname(f) !== '')
+    .filter((f) => isEligibleFile(f))
+    .slice(0, 20);
+
+  // Rule 1 (low risk): only lint "problem" fixes, scoped to impacted files.
+  if (hasGateFailure(failures, 'lint')) {
+    const action = runLintProblemAutofix({ cwd, files: scopedFiles });
+    if (action) actions.push(action);
+  }
+
+  // Future rules should follow same invariants: explicit trigger, scoped files, rollback-safe rerun.
+  return actions;
+}

package/src/env-check.js

@@ -0,0 +1,41 @@
+import { spawnSync } from 'node:child_process';
+
+const cache = new Map();
+
+function commandExists(name) {
+  if (cache.has(name)) return cache.get(name);
+  const result = spawnSync('which', [name], { encoding: 'utf8', timeout: 5000 });
+  const exists = result.status === 0;
+  cache.set(name, exists);
+  return exists;
+}
+
+export function hasGit() {
+  return commandExists('git');
+}
+
+export function hasOllama() {
+  return commandExists('ollama');
+}
+
+export function hasRsync() {
+  return commandExists('rsync');
+}
+
+export function checkEnvironment({ command }) {
+  const warnings = [];
+
+  if (!hasGit()) {
+    warnings.push('git not found -- repo metadata (branch, remote) will be unavailable.');
+  }
+
+  if (command === 'repair' && !hasOllama()) {
+    warnings.push('Ollama not found -- running deterministic fixes only (eslint --fix). Install Ollama for model-assisted repair: https://ollama.ai');
+  }
+
+  if (command === 'repair' && !hasRsync()) {
+    warnings.push('rsync not found -- using cp for workspace backup (slower but functional).');
+  }
+
+  return warnings;
+}

package/src/exec.js

@@ -0,0 +1,24 @@
+import { spawnSync } from 'node:child_process';
+
+export function runCommand(command, options = {}) {
+  const startedAt = Date.now();
+  const result = spawnSync(command, {
+    shell: true,
+    cwd: options.cwd || process.cwd(),
+    encoding: 'utf8',
+    env: { ...process.env, ...(options.env || {}) },
+    timeout: options.timeoutMs,
+    maxBuffer: 20 * 1024 * 1024,
+  });
+
+  return {
+    command,
+    cwd: options.cwd || process.cwd(),
+    started_at: new Date(startedAt).toISOString(),
+    duration_ms: Date.now() - startedAt,
+    exit_code: typeof result.status === 'number' ? result.status : 1,
+    timed_out: Boolean(result.error && result.error.code === 'ETIMEDOUT'),
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+  };
+}

package/src/fs-utils.js

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function ensureDirSync(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+export function readJsonFileSync(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+export function writeJsonFileSync(filePath, data) {
+  ensureDirSync(path.dirname(filePath));
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+
+export function writeTextFileSync(filePath, text) {
+  ensureDirSync(path.dirname(filePath));
+  fs.writeFileSync(filePath, text, 'utf8');
+}
+
+export function fileExists(filePath) {
+  return fs.existsSync(filePath);
+}
+
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+export function loadChangedFiles(changedFilesPath) {
+  const raw = fs.readFileSync(changedFilesPath, 'utf8').trim();
+  if (!raw) {
+    return [];
+  }
+
+  if (raw.startsWith('[')) {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) {
+      throw new Error(`Changed files JSON must be an array: ${changedFilesPath}`);
+    }
+    return parsed.map(String);
+  }
+
+  return raw
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+}

package/src/gates.js

@@ -0,0 +1,191 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { runCommand } from './exec.js';
+
+function packageScripts(cwd) {
+  const packagePath = path.join(cwd, 'package.json');
+  if (!fs.existsSync(packagePath)) {
+    throw new Error(`No package.json found in ${cwd}`);
+  }
+  const pkg = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+  return pkg.scripts || {};
+}
+
+function resolveGateCommand(gate, scripts, configCommands) {
+  if (configCommands[gate]) {
+    return configCommands[gate];
+  }
+  if (gate === 'typecheck') {
+    if (scripts.typecheck) return 'npm run typecheck';
+    return 'npx tsc --noEmit';
+  }
+  if (scripts[gate]) {
+    return `npm run ${gate}`;
+  }
+  if (gate === 'lighthouse') {
+    if (scripts.lighthouse) return 'npm run lighthouse';
+    if (scripts['ci:lighthouse']) return 'npm run ci:lighthouse';
+    if (scripts.lhci) return 'npm run lhci';
+    return 'npx lhci autorun --upload.target=filesystem --upload.outputDir=.quick-gate/lhci';
+  }
+  return null;
+}
+
+function parseLighthouseFindings(cwd, thresholds) {
+  const assertionResultsPath = path.join(cwd, '.lighthouseci', 'assertion-results.json');
+  if (!fs.existsSync(assertionResultsPath)) {
+    return [];
+  }
+
+  const data = JSON.parse(fs.readFileSync(assertionResultsPath, 'utf8'));
+  const findings = [];
+
+  const metricThresholds = thresholds || {};
+  const routePath = (rawUrl) => {
+    if (!rawUrl) return '/';
+    try {
+      const u = new URL(rawUrl);
+      return u.pathname || '/';
+    } catch {
+      return String(rawUrl);
+    }
+  };
+
+  const thresholdForAssertion = (row) => {
+    if (typeof row.expected === 'number' || typeof row.expected === 'string') {
+      return {
+        value: row.expected,
+        source: 'assertion_expected',
+      };
+    }
+
+    const assertion = String(row.assertion || '');
+    const parts = assertion.split(':');
+    if (parts.length === 2 && parts[0] === 'categories' && metricThresholds[parts[1]] !== undefined) {
+      return {
+        value: metricThresholds[parts[1]],
+        source: `config_category:${parts[1]}`,
+      };
+    }
+
+    if (metricThresholds[assertion] !== undefined) {
+      return {
+        value: metricThresholds[assertion],
+        source: `config_metric:${assertion}`,
+      };
+    }
+
+    return {
+      value: 'n/a',
+      source: 'unknown',
+    };
+  };
+
+  for (const row of data) {
+    if (row.passed) continue;
+    const route = routePath(row.url);
+    const metric = String(row.assertion || 'lighthouse_assertion');
+    const threshold = thresholdForAssertion(row);
+    const findingId = `lh_${route.replace(/[^a-zA-Z0-9]+/g, '_')}_${metric.replace(/[^a-zA-Z0-9]+/g, '_')}`.toLowerCase();
+    const actual = typeof row.numericValue === 'number' ? row.numericValue : String(row.value ?? 'n/a');
+    findings.push({
+      id: findingId,
+      gate: 'lighthouse',
+      severity: 'high',
+      summary: row.message || `Lighthouse assertion failed: ${metric}`,
+      route,
+      metric,
+      actual,
+      threshold: threshold.value,
+      status: 'fail',
+      raw: {
+        level: row.level,
+        auditProperty: row.auditProperty,
+        threshold_source: threshold.source,
+        operator: row.operator ?? null,
+      },
+    });
+  }
+
+  return findings;
+}
+
+function findingForExitCode(gate, result) {
+  return {
+    id: `${gate}_exit_${Date.now()}`,
+    gate,
+    severity: gate === 'build' ? 'critical' : 'high',
+    summary: `${gate} command failed with exit code ${result.exit_code}`,
+    actual: result.exit_code,
+    threshold: 0,
+    status: 'fail',
+    raw: {
+      command: result.command,
+      stderr_excerpt: result.stderr.split('\n').slice(0, 30).join('\n'),
+      stdout_excerpt: result.stdout.split('\n').slice(0, 30).join('\n'),
+    },
+  };
+}
+
+export function runDeterministicGates({ mode, cwd, config, changedFiles }) {
+  const scripts = packageScripts(cwd);
+  const traces = [];
+  const findings = [];
+
+  const gatePlan = [
+    { name: 'lint', enabled: true },
+    { name: 'typecheck', enabled: true },
+    { name: 'build', enabled: mode === 'full' },
+    { name: 'lighthouse', enabled: true },
+  ];
+
+  const gates = [];
+
+  for (const gate of gatePlan) {
+    if (!gate.enabled) {
+      gates.push({ name: gate.name, status: 'skipped', duration_ms: 0 });
+      continue;
+    }
+
+    const command = resolveGateCommand(gate.name, scripts, config.commands);
+    if (!command) {
+      gates.push({ name: gate.name, status: 'fail', duration_ms: 0 });
+      findings.push({
+        id: `${gate.name}_missing_command`,
+        gate: gate.name,
+        severity: 'high',
+        summary: `No command configured for gate: ${gate.name}`,
+        files: changedFiles,
+        actual: 'missing',
+        threshold: 'configured_command_required',
+        status: 'fail',
+      });
+      continue;
+    }
+
+    const result = runCommand(command, { cwd });
+    traces.push(result);
+
+    const status = result.exit_code === 0 ? 'pass' : 'fail';
+    gates.push({ name: gate.name, status, duration_ms: result.duration_ms });
+
+    if (status === 'fail') {
+      if (gate.name === 'lighthouse') {
+        const lighthouseFindings = parseLighthouseFindings(cwd, config.lighthouse.thresholds);
+        if (lighthouseFindings.length > 0) {
+          findings.push(...lighthouseFindings);
+        } else {
+          findings.push(findingForExitCode(gate.name, result));
+        }
+      } else {
+        findings.push(findingForExitCode(gate.name, result));
+      }
+    }
+  }
+
+  return {
+    gates,
+    findings,
+    traces,
+  };
+}