quick-gate 0.2.0-alpha.1

package/src/run-command.js

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { runCommand as runShell } from './exec.js';
+import { loadConfig } from './config.js';
+import { nowIso, writeJsonFileSync, ensureDirSync } from './fs-utils.js';
+import { runDeterministicGates } from './gates.js';
+import {
+  FAILURES_FILE,
+  QUICK_GATE_DIR,
+  RUN_METADATA_FILE,
+} from './constants.js';
+import { validateAgainstSchema } from './schema.js';
+import { hasGit } from './env-check.js';
+
+function gitInfo(cwd) {
+  if (!hasGit()) return { repo: undefined, branch: undefined };
+  const repoResult = runShell('git config --get remote.origin.url', { cwd });
+  const branchResult = runShell('git rev-parse --abbrev-ref HEAD', { cwd });
+  return {
+    repo: repoResult.exit_code === 0 ? repoResult.stdout.trim() : undefined,
+    branch: branchResult.exit_code === 0 ? branchResult.stdout.trim() : undefined,
+  };
+}
+
+export function executeRun({ mode, changedFiles, cwd = process.cwd() }) {
+  ensureDirSync(path.join(cwd, QUICK_GATE_DIR));
+
+  const runId = `run_${new Date().toISOString().replace(/[-:.TZ]/g, '').slice(0, 14)}_${randomUUID().slice(0, 8)}`;
+  const startedAt = Date.now();
+  const config = loadConfig(cwd);
+
+  const gateResult = runDeterministicGates({ mode, cwd, config, changedFiles });
+  const status = gateResult.findings.length > 0 ? 'fail' : 'pass';
+  const git = gitInfo(cwd);
+
+  const failuresPayload = {
+    version: '1.0.0',
+    run_id: runId,
+    mode,
+    status,
+    timestamp: nowIso(),
+    repo: git.repo,
+    branch: git.branch,
+    changed_files: changedFiles,
+    gates: gateResult.gates,
+    findings: gateResult.findings,
+    inferred_hints: gateResult.findings.map((finding) => ({
+      finding_id: finding.id,
+      hint: `Start with the deterministic gate failure in ${finding.gate} and inspect command output in run-metadata traces.`,
+      confidence: 'low',
+    })),
+  };
+
+  const validation = validateAgainstSchema('failures.schema.json', failuresPayload);
+  if (!validation.valid) {
+    throw new Error(`failures.json schema validation failed: ${JSON.stringify(validation.errors, null, 2)}`);
+  }
+
+  const metadataPayload = {
+    run_id: runId,
+    mode,
+    started_at: new Date(startedAt).toISOString(),
+    completed_at: nowIso(),
+    duration_ms: Date.now() - startedAt,
+    config_source: config.source,
+    command_traces: gateResult.traces,
+  };
+
+  writeJsonFileSync(path.join(cwd, FAILURES_FILE), failuresPayload);
+  writeJsonFileSync(path.join(cwd, RUN_METADATA_FILE), metadataPayload);
+
+  return {
+    status,
+    failuresPath: path.join(cwd, FAILURES_FILE),
+    metadataPath: path.join(cwd, RUN_METADATA_FILE),
+    runId,
+  };
+}

package/src/schema.js

@@ -0,0 +1,34 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { readJsonFileSync } from './fs-utils.js';
+
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+addFormats(ajv);
+
+const schemaCache = new Map();
+
+const currentDir = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(currentDir, '..');
+
+function loadSchema(schemaPath) {
+  if (schemaCache.has(schemaPath)) {
+    return schemaCache.get(schemaPath);
+  }
+  const schema = readJsonFileSync(schemaPath);
+  const validate = ajv.compile(schema);
+  schemaCache.set(schemaPath, validate);
+  return validate;
+}
+
+export function validateAgainstSchema(schemaFileName, payload) {
+  const schemaPath = path.join(packageRoot, 'schemas', schemaFileName);
+  const validate = loadSchema(schemaPath);
+  const valid = validate(payload);
+  return {
+    valid: Boolean(valid),
+    errors: validate.errors || [],
+    schemaPath,
+  };
+}

package/src/summarize-command.js

@@ -0,0 +1,118 @@
+import path from 'node:path';
+import {
+  AGENT_BRIEF_JSON_FILE,
+  AGENT_BRIEF_MD_FILE,
+  DEFAULT_POLICY,
+} from './constants.js';
+import { readJsonFileSync, writeJsonFileSync, writeTextFileSync } from './fs-utils.js';
+import { validateAgainstSchema } from './schema.js';
+
+function scopeForFinding(finding) {
+  if (Array.isArray(finding.files) && finding.files.length === 1) return 'single_file';
+  if (finding.route && (!finding.files || finding.files.length <= 1)) return 'single_route';
+  return 'cross_route';
+}
+
+function actionForGate(gate) {
+  if (gate === 'lint') return 'Apply targeted lint fixes and re-run lint deterministically.';
+  if (gate === 'typecheck') return 'Resolve TypeScript errors for impacted files and re-run typecheck.';
+  if (gate === 'build') return 'Fix build-breaking code paths and confirm production build passes.';
+  return 'Reduce route-level performance/accessibility regressions and re-run lighthouse.';
+}
+
+function createMarkdown(failures, brief) {
+  const lines = [];
+  lines.push('# Quick Gate Agent Brief');
+  lines.push('');
+  lines.push(`Run: \`${failures.run_id}\``);
+  lines.push(`Mode: \`${failures.mode}\``);
+  lines.push(`Status: \`${failures.status}\``);
+  lines.push('');
+  lines.push('## Deterministic failures');
+  lines.push('');
+
+  if (failures.findings.length === 0) {
+    lines.push('- No deterministic failures detected.');
+  } else {
+    for (const finding of failures.findings) {
+      const routePart = finding.route ? ` (${finding.route})` : '';
+      lines.push(`- \`${finding.id}\`${routePart}: ${finding.summary} (actual: ${finding.actual}, threshold: ${finding.threshold})`);
+    }
+  }
+
+  lines.push('');
+  lines.push('## Priority actions');
+  lines.push('');
+  if (brief.priority_actions.length === 0) {
+    lines.push('- No actions required.');
+  } else {
+    for (const action of brief.priority_actions) {
+      const targets = action.target_files?.length ? ` targets: ${action.target_files.join(', ')}` : '';
+      lines.push(`- [${action.scope}] ${action.action}${targets}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('## Retry policy');
+  lines.push('');
+  lines.push(`- Max attempts: ${brief.retry_policy.max_attempts}`);
+  lines.push(`- Max patch lines: ${brief.retry_policy.max_patch_lines}`);
+  lines.push(`- Abort on no improvement after: ${brief.retry_policy.abort_on_no_improvement} attempt(s)`);
+  lines.push('');
+  lines.push('## Escalation conditions');
+  lines.push('');
+  lines.push('- Escalate with reason code and evidence (`.quick-gate/failures.json`, `.quick-gate/run-metadata.json`) if unresolved.');
+  lines.push('- Stop when no-improvement cap, patch budget, or time cap is hit.');
+
+  return `${lines.join('\n')}\n`;
+}
+
+export function executeSummarize({ input, cwd = process.cwd() }) {
+  const failures = readJsonFileSync(path.resolve(cwd, input));
+
+  const priorityActions = failures.findings.map((finding) => ({
+    finding_id: finding.id,
+    action: actionForGate(finding.gate),
+    scope: scopeForFinding(finding),
+    target_files: finding.files || [],
+    rationale: `${finding.gate} failed deterministically. Address this fact before any inferred optimizations.`,
+  }));
+
+  const brief = {
+    run_id: failures.run_id,
+    mode: failures.mode,
+    status: failures.status,
+    summary:
+      failures.status === 'pass'
+        ? 'All deterministic gates passed.'
+        : `${failures.findings.length} deterministic finding(s) require repair.`,
+    priority_actions: priorityActions,
+    retry_policy: {
+      max_attempts: DEFAULT_POLICY.maxAttempts,
+      max_patch_lines: DEFAULT_POLICY.maxPatchLines,
+      abort_on_no_improvement: DEFAULT_POLICY.abortOnNoImprovement,
+    },
+    escalation: failures.status === 'pass'
+      ? { required: false }
+      : {
+        required: true,
+        reason_code: 'UNRESOLVED_DETERMINISTIC_FAILURES',
+        message: 'Escalate with evidence packet if bounded repair loop cannot clear deterministic failures.',
+      },
+  };
+
+  const validation = validateAgainstSchema('agent-brief.schema.json', brief);
+  if (!validation.valid) {
+    throw new Error(`agent-brief schema validation failed: ${JSON.stringify(validation.errors, null, 2)}`);
+  }
+
+  const md = createMarkdown(failures, brief);
+  writeJsonFileSync(path.join(cwd, AGENT_BRIEF_JSON_FILE), brief);
+  writeTextFileSync(path.join(cwd, AGENT_BRIEF_MD_FILE), md);
+
+  return {
+    briefJsonPath: path.join(cwd, AGENT_BRIEF_JSON_FILE),
+    briefMdPath: path.join(cwd, AGENT_BRIEF_MD_FILE),
+    status: brief.status,
+  };
+}