feat(ai): Foundation — Error Types + Constants [PR 1/7]

eslint.config.js

@@ -6,7 +6,7 @@ export default [
   {
     files: ['**/*.js', '**/*.jsx'],
     languageOptions: {
-      ecmaVersion: 2017,
+      ecmaVersion: 2022,
       sourceType: 'module',
       parserOptions: {
         ecmaFeatures: {
@@ -37,12 +37,13 @@ export default [
     plugins: {
       react
     },
-    rules: Object.assign({}, react.configs.recommended.rules, {
+    rules: {
+      ...react.configs.recommended.rules,
       'indent': ['error', 2],
       'linebreak-style': ['error', 'unix'],
       'quotes': ['error', 'single'],
       'semi': ['error', 'always']
-    }),
+    },
     settings: {
       react: {
         version: 'detect'

package.json

@@ -94,7 +94,6 @@
     "@types/cheerio": "^1.0.0",
     "@types/node": "^24.7.0",
     "@types/react": "^19.2.2",
-    "error-causes": "^3.0.2",
     "eslint": "^9.37.0",
     "eslint-plugin-react": "^7.37.5",
     "react": "^19.2.0",
@@ -107,12 +106,14 @@
   "dependencies": {
     "cheerio": "1.2.0",
     "dotignore": "^0.1.2",
+    "error-causes": "^3.0.2",
     "esm": "3.2.25",
     "glob": "^11.0.3",
     "minimist": "^1.2.8",
     "react-dom": "^19.2.0",
     "resolve": "^1.22.10",
     "tape": "^5.9.0",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "zod": "^4.3.6"
   }
 }

source/ai-errors.js

@@ -0,0 +1,26 @@
+import { errorCauses } from 'error-causes';
+
+// Error types for AI agent execution and related operations
+export const [aiErrors, handleAIErrors] = errorCauses({
+  ParseError: { code: 'PARSE_FAILURE', message: 'Failed to parse AI response' },
+  ValidationError: { code: 'VALIDATION_FAILURE', message: 'Invalid input parameters' },
+  SecurityError: { code: 'SECURITY_VIOLATION', message: 'Security violation detected' },
+  TimeoutError: { code: 'AGENT_TIMEOUT', message: 'AI agent timed out' },
+  AgentProcessError: { code: 'AGENT_PROCESS_FAILURE', message: 'AI agent process failed' },
+  AITestError: { code: 'AI_TEST_ERROR', message: 'AI test execution failed' },
+  OutputError: { code: 'OUTPUT_ERROR', message: 'Test output recording failed' },
+  ExtractionParseError: { code: 'EXTRACTION_PARSE_FAILURE', message: 'Failed to parse extraction result' },
+  ExtractionValidationError: { code: 'EXTRACTION_VALIDATION_FAILURE', message: 'Invalid extraction result' }
+});
+
+export const {
+  ParseError,
+  ValidationError,
+  SecurityError,
+  TimeoutError,
+  AgentProcessError,
+  AITestError,
+  OutputError,
+  ExtractionParseError,
+  ExtractionValidationError
+} = aiErrors;

source/ai-errors.test.js

@@ -0,0 +1,128 @@
+import { describe, test } from 'vitest';
+import { assert } from './vitest.js';
+import { createError } from 'error-causes';
+import {
+  aiErrors,
+  handleAIErrors,
+  ParseError,
+  ValidationError,
+  SecurityError,
+  TimeoutError,
+  AgentProcessError,
+  AITestError,
+  OutputError,
+  ExtractionParseError,
+  ExtractionValidationError
+} from './ai-errors.js';
+
+const errorTable = [
+  ['ParseError',               'PARSE_FAILURE',              ParseError],
+  ['ValidationError',          'VALIDATION_FAILURE',         ValidationError],
+  ['SecurityError',            'SECURITY_VIOLATION',         SecurityError],
+  ['TimeoutError',             'AGENT_TIMEOUT',              TimeoutError],
+  ['AgentProcessError',        'AGENT_PROCESS_FAILURE',      AgentProcessError],
+  ['AITestError',              'AI_TEST_ERROR',              AITestError],
+  ['OutputError',              'OUTPUT_ERROR',               OutputError],
+  ['ExtractionParseError',     'EXTRACTION_PARSE_FAILURE',   ExtractionParseError],
+  ['ExtractionValidationError','EXTRACTION_VALIDATION_FAILURE', ExtractionValidationError],
+];
+
+describe('ai-errors module', () => {
+  describe('error descriptors', () => {
+    test.each(errorTable)('%s descriptor has correct name', (name) => {
+      assert({
+        given: `${name} descriptor`,
+        should: 'have the correct error name',
+        actual: aiErrors[name].name,
+        expected: name
+      });
+    });
+
+    test.each(errorTable)('%s descriptor has correct code', (name, code) => {
+      assert({
+        given: `${name} descriptor`,
+        should: 'have the correct error code',
+        actual: aiErrors[name].code,
+        expected: code
+      });
+    });
+
+    test.each(errorTable)('%s named export matches aiErrors entry', (name, _code, descriptor) => {
+      assert({
+        given: `destructured ${name} export`,
+        should: 'equal aiErrors entry',
+        actual: descriptor,
+        expected: aiErrors[name]
+      });
+    });
+  });
+
+  describe('createError integration', () => {
+    test.each([
+      ['ParseError',    ParseError,    'PARSE_FAILURE'],
+      ['SecurityError', SecurityError, 'SECURITY_VIOLATION'],
+    ])('%s produces an Error with structured cause', (name, descriptor, code) => {
+      const err = createError(descriptor);
+
+      assert({
+        given: `a ${name} descriptor`,
+        should: 'produce an Error instance',
+        actual: err instanceof Error,
+        expected: true
+      });
+
+      assert({
+        given: `a ${name} descriptor`,
+        should: `set cause.name to ${name}`,
+        actual: err.cause.name,
+        expected: name
+      });
+
+      assert({
+        given: `a ${name} descriptor`,
+        should: `set cause.code to ${code}`,
+        actual: err.cause.code,
+        expected: code
+      });
+    });
+  });
+
+  describe('handleAIErrors', () => {
+    // handleAIErrors is exhaustive: every registered error type must have a handler.
+    // Build a no-op map for all types, then override the one under test.
+    const noop = () => {};
+    const allNoop = {
+      ParseError: noop, ValidationError: noop, SecurityError: noop,
+      TimeoutError: noop, AgentProcessError: noop, AITestError: noop,
+      OutputError: noop, ExtractionParseError: noop, ExtractionValidationError: noop
+    };
+
+    test('routes a ParseError to the ParseError handler', () => {
+      const err = createError(ParseError);
+      const invoked = [];
+
+      handleAIErrors({ ...allNoop, ParseError: () => invoked.push('ParseError') })(err);
+
+      assert({
+        given: 'an error created from ParseError',
+        should: 'invoke only the ParseError handler',
+        actual: invoked,
+        expected: ['ParseError']
+      });
+    });
+
+    test('routes a ValidationError to the ValidationError handler', () => {
+      const err = createError(ValidationError);
+      const invoked = [];
+
+      handleAIErrors({ ...allNoop, ValidationError: () => invoked.push('ValidationError') })(err);
+
+      assert({
+        given: 'an error created from ValidationError',
+        should: 'invoke only the ValidationError handler',
+        actual: invoked,
+        expected: ['ValidationError']
+      });
+    });
+  });
+});

source/constants.js

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+
+export const defaults = {
+  runs: 4,
+  threshold: 75,
+  concurrency: 4,
+  agent: 'claude',
+  timeoutMs: 300_000,
+  color: false,
+  debug: false,
+  debugLog: false
+};
+
+export const constraints = {
+  thresholdMin: 0,
+  thresholdMax: 100,
+  runsMin: 1,
+  runsMax: 1000,
+  concurrencyMin: 1,
+  concurrencyMax: 50,
+  timeoutMinMs: 1000,
+  timeoutMaxMs: 3_600_000,
+  supportedAgents: ['claude', 'opencode', 'cursor']
+};
+
+export const runsSchema = z.number()
+  .int({ message: 'runs must be an integer' })
+  .min(constraints.runsMin, { message: `runs must be at least ${constraints.runsMin}` })
+  .max(constraints.runsMax, { message: `runs must be at most ${constraints.runsMax}` });
+
+export const thresholdSchema = z.number()
+  .finite({ message: 'threshold must be a finite number' })
+  .min(constraints.thresholdMin, { message: `threshold must be at least ${constraints.thresholdMin}` })
+  .max(constraints.thresholdMax, { message: `threshold must be at most ${constraints.thresholdMax}` });
+
+export const concurrencySchema = z.number()
+  .int({ message: 'concurrency must be an integer' })
+  .min(constraints.concurrencyMin, { message: `concurrency must be at least ${constraints.concurrencyMin}` })
+  .max(constraints.concurrencyMax, { message: `concurrency must be at most ${constraints.concurrencyMax}` });
+
+export const timeoutSchema = z.number()
+  .int({ message: 'timeout must be an integer' })
+  .min(constraints.timeoutMinMs, { message: `timeout must be at least ${constraints.timeoutMinMs}ms` })
+  .max(constraints.timeoutMaxMs, { message: `timeout must be at most ${constraints.timeoutMaxMs}ms` });
+
+export const agentSchema = z.enum(constraints.supportedAgents, {
+  message: `agent must be one of: ${constraints.supportedAgents.join(', ')}`
+});
+
+export const calculateRequiredPassesSchema = z.object({
+  runs: runsSchema,
+  threshold: thresholdSchema
+});
+
+export const aiTestOptionsSchema = z.object({
+  filePath: z.string().min(1, { message: 'Test file path is required' }),
+  runs: runsSchema.default(defaults.runs),
+  threshold: thresholdSchema.default(defaults.threshold),
+  timeout: timeoutSchema.default(defaults.timeoutMs),
+  concurrency: concurrencySchema.default(defaults.concurrency),
+  agent: agentSchema.default(defaults.agent),
+  agentConfigPath: z.string().optional(),
+  debug: z.boolean().default(defaults.debug),
+  debugLog: z.boolean().default(defaults.debugLog),
+  color: z.boolean().default(defaults.color),
+  // Lazy default — evaluated at parse time, not module load time
+  cwd: z.string().default(() => process.cwd()),
+  projectRoot: z.string().optional()
+});