@kirrosh/apitool 0.4.3

package/src/core/parser/schema.ts

@@ -0,0 +1,175 @@
+import { z } from "zod";
+import type { TestSuite, TestStep, AssertionRule, TestStepExpect, SuiteConfig } from "./types.ts";
+
+const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;
+
+function extractMethodAndPath(raw: unknown): unknown {
+  if (typeof raw !== "object" || raw === null) return raw;
+  const obj = raw as Record<string, unknown>;
+
+  let foundMethod: string | undefined;
+  for (const method of HTTP_METHODS) {
+    if (method in obj) {
+      if (foundMethod) {
+        throw new Error(`Ambiguous step: found both ${foundMethod} and ${method} keys`);
+      }
+      foundMethod = method;
+    }
+  }
+
+  if (foundMethod) {
+    const path = obj[foundMethod];
+    if (typeof path !== "string") {
+      throw new Error(`${foundMethod} value must be a string path, got ${typeof path}`);
+    }
+    const { [foundMethod]: _, ...rest } = obj;
+    return { ...rest, method: foundMethod, path };
+  }
+
+  return raw;
+}
+
+const ASSERTION_KEYS = new Set([
+  "capture", "type", "equals", "contains", "matches", "gt", "lt", "exists",
+]);
+
+/**
+ * Recursively flattens nested body assertion objects into dot-notation keys.
+ * e.g. { category: { name: { equals: "Dogs" } } } → { "category.name": { equals: "Dogs" } }
+ * Leaves assertion-level objects untouched (objects where all keys are ASSERTION_KEYS).
+ * Also skips the special `_body` key prefix.
+ */
+export function flattenBodyAssertions(body: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  function walk(obj: Record<string, unknown>, prefix: string) {
+    for (const [key, value] of Object.entries(obj)) {
+      const fullKey = prefix ? `${prefix}.${key}` : key;
+
+      if (
+        typeof value === "object" && value !== null && !Array.isArray(value) &&
+        !fullKey.startsWith("_body")
+      ) {
+        const objKeys = Object.keys(value as Record<string, unknown>);
+        const isAssertionRule = objKeys.length > 0 && objKeys.every(k => ASSERTION_KEYS.has(k));
+
+        if (isAssertionRule) {
+          result[fullKey] = value;
+        } else {
+          walk(value as Record<string, unknown>, fullKey);
+        }
+      } else {
+        result[fullKey] = value;
+      }
+    }
+  }
+
+  walk(body, "");
+  return result;
+}
+
+const AssertionRuleSchema: z.ZodType<AssertionRule> = z.preprocess(
+  (val) => {
+    if (typeof val === "string") return { type: val };
+    if (val === null || val === undefined) return { exists: true };
+    if (typeof val === "object" && val !== null) {
+      const obj = val as Record<string, unknown>;
+      // Coerce exists: "true"/"false" → boolean
+      if (typeof obj.exists === "string") {
+        obj.exists = obj.exists === "true";
+      }
+      return obj;
+    }
+    return val;
+  },
+  z.object({
+    capture: z.string().optional(),
+    type: z.enum(["string", "integer", "number", "boolean", "array", "object"]).optional(),
+    equals: z.unknown().optional(),
+    contains: z.string().optional(),
+    matches: z.string().optional(),
+    gt: z.number().optional(),
+    lt: z.number().optional(),
+    exists: z.boolean().optional(),
+  }),
+) as z.ZodType<AssertionRule>;
+
+const TestStepExpectSchema: z.ZodType<TestStepExpect> = z.preprocess(
+  (val) => {
+    if (typeof val !== "object" || val === null) return val;
+    const obj = val as Record<string, unknown>;
+    // body: null → remove it
+    if (obj.body === null) {
+      const { body: _, ...rest } = obj;
+      return rest;
+    }
+    // Flatten nested body assertions into dot-notation
+    if (obj.body && typeof obj.body === "object" && !Array.isArray(obj.body)) {
+      obj.body = flattenBodyAssertions(obj.body as Record<string, unknown>);
+    }
+    return obj;
+  },
+  z.object({
+    status: z.number().int().optional(),
+    body: z.record(z.string(), AssertionRuleSchema).optional(),
+    headers: z.record(z.string(), z.string()).optional(),
+    duration: z.number().optional(),
+  }),
+) as z.ZodType<TestStepExpect>;
+
+const TestStepSchema: z.ZodType<TestStep> = z.preprocess(
+  extractMethodAndPath,
+  z.object({
+    name: z.string(),
+    method: z.enum(HTTP_METHODS),
+    path: z.string(),
+    headers: z.record(z.string(), z.string()).optional(),
+    json: z.unknown().optional(),
+    form: z.record(z.string(), z.string()).optional(),
+    query: z.record(z.string(), z.string()).optional(),
+    expect: TestStepExpectSchema,
+  }),
+) as z.ZodType<TestStep>;
+
+export const DEFAULT_CONFIG: SuiteConfig = {
+  timeout: 30000,
+  retries: 0,
+  retry_delay: 1000,
+  follow_redirects: true,
+  verify_ssl: true,
+};
+
+const SuiteConfigSchema = z.preprocess(
+  (val) => ({ ...DEFAULT_CONFIG, ...(typeof val === "object" && val !== null ? val : {}) }),
+  z.object({
+    timeout: z.number(),
+    retries: z.number(),
+    retry_delay: z.number(),
+    follow_redirects: z.boolean(),
+    verify_ssl: z.boolean(),
+  }),
+) as z.ZodType<SuiteConfig>;
+
+const TestSuiteSchema = z.preprocess(
+  (val) => {
+    if (typeof val === "object" && val !== null && !("config" in val)) {
+      return { ...val, config: DEFAULT_CONFIG };
+    }
+    return val;
+  },
+  z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    base_url: z.string().optional(),
+    headers: z.record(z.string(), z.string()).optional(),
+    config: SuiteConfigSchema,
+    tests: z.array(TestStepSchema).min(1),
+  }),
+);
+
+export function validateSuite(raw: unknown): TestSuite {
+  return TestSuiteSchema.parse(raw) as TestSuite;
+}
+
+export { TestSuiteSchema, TestStepSchema, AssertionRuleSchema, ASSERTION_KEYS };

package/src/core/parser/types.ts

@@ -0,0 +1,50 @@
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+export interface AssertionRule {
+  capture?: string;
+  type?: "string" | "integer" | "number" | "boolean" | "array" | "object";
+  equals?: unknown;
+  contains?: string;
+  matches?: string;
+  gt?: number;
+  lt?: number;
+  exists?: boolean;
+}
+
+export interface TestStepExpect {
+  status?: number;
+  body?: Record<string, AssertionRule>;
+  headers?: Record<string, string>;
+  duration?: number;
+}
+
+export interface TestStep {
+  name: string;
+  method: HttpMethod;
+  path: string;
+  headers?: Record<string, string>;
+  json?: unknown;
+  form?: Record<string, string>;
+  query?: Record<string, string>;
+  expect: TestStepExpect;
+}
+
+export interface SuiteConfig {
+  timeout: number;
+  retries: number;
+  retry_delay: number;
+  follow_redirects: boolean;
+  verify_ssl: boolean;
+}
+
+export interface TestSuite {
+  name: string;
+  description?: string;
+  tags?: string[];
+  base_url?: string;
+  headers?: Record<string, string>;
+  config: SuiteConfig;
+  tests: TestStep[];
+}
+
+export type Environment = Record<string, string>;

package/src/core/parser/variables.ts

@@ -0,0 +1,146 @@
+import { dirname } from "path";
+import type { TestStep } from "./types.ts";
+
+const NAMES = ["John Smith", "Jane Doe", "Alice Brown", "Bob Wilson", "Emma Davis", "James Miller"];
+const CHARS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+
+function randomFrom<T>(arr: T[]): T {
+  return arr[Math.floor(Math.random() * arr.length)]!;
+}
+
+function randomChars(len: number): string {
+  let result = "";
+  for (let i = 0; i < len; i++) {
+    result += CHARS[Math.floor(Math.random() * CHARS.length)];
+  }
+  return result;
+}
+
+export const GENERATORS: Record<string, () => string | number> = {
+  "$uuid": () => crypto.randomUUID(),
+  "$timestamp": () => Math.floor(Date.now() / 1000),
+  "$randomName": () => randomFrom(NAMES),
+  "$randomEmail": () => `${randomChars(8).toLowerCase()}@test.com`,
+  "$randomInt": () => Math.floor(Math.random() * 10000),
+  "$randomString": () => randomChars(8),
+};
+
+const VAR_PATTERN = /\{\{(.+?)\}\}/g;
+
+export function substituteString(template: string, vars: Record<string, unknown>): unknown {
+  // If entire string is a single {{var}}, return raw value (number stays number)
+  const singleMatch = template.match(/^\{\{([^{}]+)\}\}$/);
+  if (singleMatch) {
+    const key = singleMatch[1]!;
+    if (key in vars) return vars[key];
+    if (key in GENERATORS) return GENERATORS[key]!();
+    return template;
+  }
+
+  // Create new regex each time to avoid lastIndex issues with /g flag
+  return template.replace(new RegExp(VAR_PATTERN.source, "g"), (_, key: string) => {
+    if (key in vars) return String(vars[key]);
+    if (key in GENERATORS) return String(GENERATORS[key]!());
+    return `{{${key}}}`;
+  });
+}
+
+export function substituteDeep<T>(value: T, vars: Record<string, unknown>): T {
+  if (typeof value === "string") {
+    return substituteString(value, vars) as T;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => substituteDeep(item, vars)) as T;
+  }
+  if (typeof value === "object" && value !== null) {
+    const result: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = substituteDeep(v, vars);
+    }
+    return result as T;
+  }
+  return value;
+}
+
+export function substituteStep(step: TestStep, vars: Record<string, unknown>): TestStep {
+  const result: TestStep = {
+    ...step,
+    path: substituteString(step.path, vars) as string,
+    expect: { ...step.expect },
+  };
+
+  if (step.headers) {
+    result.headers = substituteDeep(step.headers, vars);
+  }
+  if (step.json !== undefined) {
+    result.json = substituteDeep(step.json, vars);
+  }
+  if (step.form) {
+    result.form = substituteDeep(step.form, vars);
+  }
+  if (step.query) {
+    result.query = substituteDeep(step.query, vars);
+  }
+  if (step.expect.body) {
+    result.expect.body = substituteDeep(step.expect.body, vars);
+  }
+
+  return result;
+}
+
+export function extractVariableReferences(step: TestStep): string[] {
+  const refs = new Set<string>();
+  const scan = (value: unknown): void => {
+    if (typeof value === "string") {
+      for (const match of value.matchAll(VAR_PATTERN)) {
+        const key = match[1]!;
+        if (!key.startsWith("$")) refs.add(key);
+      }
+    } else if (Array.isArray(value)) {
+      value.forEach(scan);
+    } else if (typeof value === "object" && value !== null) {
+      Object.values(value).forEach(scan);
+    }
+  };
+  scan(step);
+  return [...refs];
+}
+
+async function loadEnvFile(filePath: string): Promise<Record<string, string> | null> {
+  try {
+    const text = await Bun.file(filePath).text();
+    const parsed = Bun.YAML.parse(text);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error(`Environment file ${filePath} must contain a YAML object`);
+    }
+    const result: Record<string, string> = {};
+    for (const [k, v] of Object.entries(parsed as Record<string, unknown>)) {
+      result[k] = String(v);
+    }
+    return result;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    return null;
+  }
+}
+
+export async function loadEnvironment(envName?: string, searchDir: string = ".", collectionId?: number): Promise<Record<string, string>> {
+  const fileName = envName ? `.env.${envName}.yaml` : ".env.yaml";
+
+  // Try both searchDir and parent dir — env file may be in collection root while tests are in tests/ subdir
+  const fileVars = await loadEnvFile(`${searchDir}/${fileName}`);
+  const parentFileVars = await loadEnvFile(`${dirname(searchDir)}/${fileName}`);
+
+  // DB fallback/merge: resolve scoped + global env from DB
+  let dbVars: Record<string, string> | null = null;
+  if (envName) {
+    try {
+      const { resolveEnvironment } = await import("../../db/queries.ts");
+      dbVars = resolveEnvironment(envName, collectionId);
+    } catch { /* DB not initialized — OK */ }
+  }
+
+  // Merge priority: dbGlobal < dbScoped < parentFile < file (local file beats everything)
+  const merged: Record<string, string> = { ...dbVars, ...parentFileVars, ...fileVars };
+  return merged;
+}

package/src/core/parser/yaml-parser.ts

@@ -0,0 +1,85 @@
+import { Glob } from "bun";
+import { validateSuite } from "./schema.ts";
+import type { TestSuite } from "./types.ts";
+
+export async function parseFile(filePath: string): Promise<TestSuite> {
+  let text: string;
+  try {
+    text = await Bun.file(filePath).text();
+  } catch (err) {
+    throw new Error(`Failed to read file ${filePath}: ${(err as Error).message}`);
+  }
+
+  let raw: unknown;
+  try {
+    raw = Bun.YAML.parse(text);
+  } catch (err) {
+    throw new Error(`Invalid YAML in ${filePath}: ${(err as Error).message}`);
+  }
+
+  try {
+    const suite = validateSuite(raw);
+    (suite as any)._source = filePath;
+    return suite;
+  } catch (err) {
+    throw new Error(`Validation error in ${filePath}: ${(err as Error).message}`);
+  }
+}
+
+export async function parseDirectory(dirPath: string): Promise<TestSuite[]> {
+  const glob = new Glob("**/*.{yaml,yml}");
+  const suites: TestSuite[] = [];
+
+  for await (const file of glob.scan({ cwd: dirPath, absolute: false })) {
+    // Skip environment files
+    if (file.match(/\.env(\..+)?\.yaml$/) || file.match(/\.env(\..+)?\.yml$/)) {
+      continue;
+    }
+    const fullPath = `${dirPath}/${file}`;
+    try {
+      suites.push(await parseFile(fullPath));
+    } catch {
+      // Skip files that fail to parse (e.g. invalid AI-generated YAML)
+      // so one bad file doesn't block the entire directory
+    }
+  }
+
+  return suites;
+}
+
+export interface ParseDirectoryResult {
+  suites: TestSuite[];
+  errors: { file: string; error: string }[];
+}
+
+export async function parseDirectorySafe(dirPath: string): Promise<ParseDirectoryResult> {
+  const glob = new Glob("**/*.{yaml,yml}");
+  const suites: TestSuite[] = [];
+  const errors: { file: string; error: string }[] = [];
+
+  for await (const file of glob.scan({ cwd: dirPath, absolute: false })) {
+    if (file.match(/\.env(\..+)?\.yaml$/) || file.match(/\.env(\..+)?\.yml$/)) {
+      continue;
+    }
+    const fullPath = `${dirPath}/${file}`;
+    try {
+      suites.push(await parseFile(fullPath));
+    } catch (err) {
+      errors.push({ file, error: (err as Error).message });
+    }
+  }
+
+  return { suites, errors };
+}
+
+export async function parse(path: string): Promise<TestSuite[]> {
+  const file = Bun.file(path);
+  const exists = await file.exists();
+
+  if (exists) {
+    return [await parseFile(path)];
+  }
+
+  // Not a file, try as directory
+  return parseDirectory(path);
+}

package/src/core/reporter/console.ts

@@ -0,0 +1,175 @@
+import type { TestRunResult, StepResult, AssertionResult } from "../runner/types.ts";
+import type { Reporter, ReporterOptions } from "./types.ts";
+
+// ANSI escape codes
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const RED = "\x1b[31m";
+const GRAY = "\x1b[90m";
+
+const PASS_ICON = "\u2713"; // ✓
+const FAIL_ICON = "\u2717"; // ✗
+const SKIP_ICON = "\u25CB"; // ○
+
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  const mins = Math.floor(ms / 60000);
+  const secs = Math.round((ms % 60000) / 1000);
+  return secs > 0 ? `${mins}m ${secs}s` : `${mins}m`;
+}
+
+export function formatStep(step: StepResult, color: boolean): string {
+  const duration = formatDuration(step.duration_ms);
+
+  switch (step.status) {
+    case "pass": {
+      const icon = color ? `${GREEN}${PASS_ICON}${RESET}` : PASS_ICON;
+      const dim = color ? `${DIM}(${duration})${RESET}` : `(${duration})`;
+      return `  ${icon} ${step.name} ${dim}`;
+    }
+    case "fail": {
+      const icon = color ? `${RED}${FAIL_ICON}${RESET}` : FAIL_ICON;
+      const dim = color ? `${DIM}(${duration})${RESET}` : `(${duration})`;
+      return `  ${icon} ${step.name} ${dim}`;
+    }
+    case "skip": {
+      const icon = color ? `${GRAY}${SKIP_ICON}${RESET}` : SKIP_ICON;
+      const label = color ? `${GRAY}(skipped)${RESET}` : "(skipped)";
+      return `  ${icon} ${step.name} ${label}`;
+    }
+    case "error": {
+      const icon = color ? `${RED}${FAIL_ICON}${RESET}` : FAIL_ICON;
+      const label = color ? `${DIM}(error)${RESET}` : "(error)";
+      return `  ${icon} ${step.name} ${label}`;
+    }
+  }
+}
+
+export function formatFailures(step: StepResult, color: boolean): string {
+  const lines: string[] = [];
+
+  if (step.status === "error" && step.error) {
+    const msg = color ? `${RED}Error: ${step.error}${RESET}` : `Error: ${step.error}`;
+    lines.push(`    ${msg}`);
+    return lines.join("\n");
+  }
+
+  const failed = step.assertions.filter((a) => !a.passed);
+  for (const a of failed) {
+    const msg = `${a.field}: expected ${a.rule} but got ${formatValue(a.actual)}`;
+    lines.push(color ? `    ${RED}${msg}${RESET}` : `    ${msg}`);
+  }
+  return lines.join("\n");
+}
+
+function formatValue(value: unknown): string {
+  if (value === undefined) return "undefined";
+  if (value === null) return "null";
+  if (typeof value === "string") return `"${value}"`;
+  return String(value);
+}
+
+export function formatSuiteResult(result: TestRunResult, color: boolean): string {
+  const lines: string[] = [];
+
+  // Suite header
+  const header = color ? ` ${BOLD}${result.suite_name}${RESET}` : ` ${result.suite_name}`;
+  lines.push(header);
+
+  // Tags
+  if (result.suite_tags?.length) {
+    const tagsStr = result.suite_tags.map(t => `[${t}]`).join(" ");
+    lines.push(color ? `  ${DIM}${tagsStr}${RESET}` : `  ${tagsStr}`);
+  }
+
+  // Steps
+  for (const step of result.steps) {
+    lines.push(formatStep(step, color));
+    if (step.status === "fail" || step.status === "error") {
+      const details = formatFailures(step, color);
+      if (details) lines.push(details);
+    }
+  }
+
+  // Summary
+  const totalMs = Date.parse(result.finished_at) - Date.parse(result.started_at);
+  const duration = formatDuration(totalMs > 0 ? totalMs : 0);
+  const parts: string[] = [];
+
+  if (result.passed > 0) {
+    parts.push(color ? `${GREEN}${result.passed} passed${RESET}` : `${result.passed} passed`);
+  }
+  if (result.failed > 0) {
+    parts.push(color ? `${RED}${result.failed} failed${RESET}` : `${result.failed} failed`);
+  }
+  if (result.skipped > 0) {
+    parts.push(color ? `${GRAY}${result.skipped} skipped${RESET}` : `${result.skipped} skipped`);
+  }
+  if (parts.length === 0) {
+    parts.push("0 tests");
+  }
+
+  lines.push("");
+  lines.push(`Results: ${parts.join(", ")} (${duration})`);
+
+  return lines.join("\n");
+}
+
+export function formatGrandTotal(results: TestRunResult[], color: boolean): string {
+  const totals = { passed: 0, failed: 0, skipped: 0, total: 0 };
+  let minStart = Infinity;
+  let maxEnd = -Infinity;
+
+  for (const r of results) {
+    totals.passed += r.passed;
+    totals.failed += r.failed;
+    totals.skipped += r.skipped;
+    totals.total += r.total;
+    const start = Date.parse(r.started_at);
+    const end = Date.parse(r.finished_at);
+    if (start < minStart) minStart = start;
+    if (end > maxEnd) maxEnd = end;
+  }
+
+  const totalMs = maxEnd - minStart;
+  const duration = formatDuration(totalMs > 0 ? totalMs : 0);
+  const parts: string[] = [];
+
+  if (totals.passed > 0) {
+    parts.push(color ? `${GREEN}${totals.passed} passed${RESET}` : `${totals.passed} passed`);
+  }
+  if (totals.failed > 0) {
+    parts.push(color ? `${RED}${totals.failed} failed${RESET}` : `${totals.failed} failed`);
+  }
+  if (totals.skipped > 0) {
+    parts.push(color ? `${GRAY}${totals.skipped} skipped${RESET}` : `${totals.skipped} skipped`);
+  }
+
+  const header = color ? `${BOLD}Total:${RESET}` : "Total:";
+  return `${header} ${parts.join(", ")} (${duration})`;
+}
+
+export const consoleReporter: Reporter = {
+  report(results: TestRunResult[], options?: ReporterOptions): void {
+    const color = options?.color ?? (process.stdout.isTTY ?? false);
+
+    if (results.length === 0) {
+      console.log("No test suites found.");
+      return;
+    }
+
+    const blocks: string[] = [];
+    for (const result of results) {
+      blocks.push(formatSuiteResult(result, color));
+    }
+
+    console.log(blocks.join("\n\n"));
+
+    if (results.length > 1) {
+      console.log("\n" + formatGrandTotal(results, color));
+    }
+  },
+};

package/src/core/reporter/index.ts

@@ -0,0 +1,23 @@
+export type { Reporter, ReporterOptions, ReporterName } from "./types.ts";
+export { consoleReporter, formatDuration, formatStep, formatFailures, formatSuiteResult, formatGrandTotal } from "./console.ts";
+export { jsonReporter } from "./json.ts";
+export { junitReporter } from "./junit.ts";
+
+import type { Reporter, ReporterName } from "./types.ts";
+import { consoleReporter } from "./console.ts";
+import { jsonReporter } from "./json.ts";
+import { junitReporter } from "./junit.ts";
+
+const reporters: Record<ReporterName, Reporter> = {
+  console: consoleReporter,
+  json: jsonReporter,
+  junit: junitReporter,
+};
+
+export function getReporter(name: ReporterName): Reporter {
+  const reporter = reporters[name];
+  if (!reporter) {
+    throw new Error(`Unknown reporter: ${name}. Available: ${Object.keys(reporters).join(", ")}`);
+  }
+  return reporter;
+}

package/src/core/reporter/json.ts

@@ -0,0 +1,9 @@
+import type { TestRunResult } from "../runner/types.ts";
+import type { Reporter, ReporterOptions } from "./types.ts";
+
+export const jsonReporter: Reporter = {
+  report(results: TestRunResult[], _options?: ReporterOptions): void {
+    const json = JSON.stringify(results, null, 2);
+    console.log(json);
+  },
+};