@kirrosh/apitool 0.4.3

package/src/core/generator/coverage-scanner.ts

@@ -0,0 +1,87 @@
+import { Glob } from "bun";
+import type { EndpointInfo } from "./types.ts";
+
+export interface CoveredEndpoint {
+  method: string;
+  path: string;
+  file: string;
+}
+
+const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+
+/**
+ * Scan YAML test files in outputDir and extract method+path from each test step.
+ * Uses simple regex to avoid importing the full parser.
+ */
+export async function scanCoveredEndpoints(outputDir: string): Promise<CoveredEndpoint[]> {
+  const covered: CoveredEndpoint[] = [];
+
+  const glob = new Glob("**/*.yaml");
+  for await (const file of glob.scan({ cwd: outputDir, absolute: true })) {
+    try {
+      const content = await Bun.file(file).text();
+      const lines = content.split("\n");
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        for (const method of HTTP_METHODS) {
+          // Match lines like "POST: /users" or "GET: /users/{{user_id}}"
+          if (trimmed.startsWith(`${method}:`) || trimmed.startsWith(`${method} :`)) {
+            const path = trimmed.slice(trimmed.indexOf(":") + 1).trim().replace(/^["']|["']$/g, "");
+            if (path) {
+              covered.push({ method, path: normalizePath(path), file });
+            }
+          }
+        }
+      }
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  return covered;
+}
+
+/**
+ * Normalize path for comparison:
+ * - Replace {{variable}} with {*}
+ * - Replace {paramName} with {*}
+ * - Remove trailing slashes
+ */
+function normalizePath(path: string): string {
+  return path
+    .replace(/\{\{[^}]+\}\}/g, "{*}")  // {{var}} → {*}
+    .replace(/\{[^}]+\}/g, "{*}")       // {id} → {*}
+    .replace(/\/+$/, "");
+}
+
+/**
+ * Convert a spec path to a regex that matches both parameterized and concrete paths.
+ * e.g. /pet/{petId} matches /pet/100001 and /pet/{{pet_id}}
+ */
+function specPathToRegex(specPath: string): RegExp {
+  const pattern = specPath
+    .split("/")
+    .map((seg) =>
+      /^\{[^}]+\}$/.test(seg)
+        ? "[^/]+"
+        : seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
+    )
+    .join("/");
+  return new RegExp(`^${pattern}$`);
+}
+
+/**
+ * Filter endpoints that don't yet have test coverage.
+ */
+export function filterUncoveredEndpoints(
+  all: EndpointInfo[],
+  covered: CoveredEndpoint[],
+): EndpointInfo[] {
+  return all.filter((ep) => {
+    const specRegex = specPathToRegex(ep.path);
+    return !covered.some(
+      (c) => c.method === ep.method && specRegex.test(normalizePath(c.path)),
+    );
+  });
+}

package/src/core/generator/data-factory.ts

@@ -0,0 +1,115 @@
+import type { OpenAPIV3 } from "openapi-types";
+
+/**
+ * Recursively generates test data from an OpenAPI schema.
+ * Uses heuristic placeholders ({{$...}} generators) where possible.
+ */
+export function generateFromSchema(
+  schema: OpenAPIV3.SchemaObject,
+  propertyName?: string,
+): unknown {
+  // allOf: merge all schemas
+  if (schema.allOf) {
+    const merged: OpenAPIV3.SchemaObject = { type: "object", properties: {} };
+    for (const sub of schema.allOf) {
+      const s = sub as OpenAPIV3.SchemaObject;
+      if (s.properties) {
+        merged.properties = { ...merged.properties, ...s.properties };
+      }
+    }
+    return generateFromSchema(merged, propertyName);
+  }
+
+  // oneOf / anyOf: use first variant
+  if (schema.oneOf) {
+    return generateFromSchema(schema.oneOf[0] as OpenAPIV3.SchemaObject, propertyName);
+  }
+  if (schema.anyOf) {
+    return generateFromSchema(schema.anyOf[0] as OpenAPIV3.SchemaObject, propertyName);
+  }
+
+  // enum: first value
+  if (schema.enum && schema.enum.length > 0) {
+    return schema.enum[0];
+  }
+
+  switch (schema.type) {
+    case "string":
+      return guessStringPlaceholder(schema, propertyName);
+
+    case "integer":
+      return guessIntPlaceholder(propertyName);
+
+    case "number":
+      return "{{$randomInt}}";
+
+    case "boolean":
+      return true;
+
+    case "array": {
+      if (schema.items) {
+        const item = generateFromSchema(schema.items as OpenAPIV3.SchemaObject);
+        return [item];
+      }
+      return [];
+    }
+
+    case "object":
+    default: {
+      // Treat unknown type with properties as object
+      if (schema.properties) {
+        const obj: Record<string, unknown> = {};
+        for (const [key, propSchema] of Object.entries(schema.properties)) {
+          obj[key] = generateFromSchema(propSchema as OpenAPIV3.SchemaObject, key);
+        }
+        return obj;
+      }
+      // Record type: additionalProperties defines value schema
+      if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+        const valSchema = schema.additionalProperties as OpenAPIV3.SchemaObject;
+        return { key1: generateFromSchema(valSchema, "key1"), key2: generateFromSchema(valSchema, "key2") };
+      }
+      if (schema.additionalProperties === true) {
+        return { key1: "value1", key2: "value2" };
+      }
+      // Bare object with no properties
+      if (schema.type === "object") {
+        return {};
+      }
+      return "{{$randomString}}";
+    }
+  }
+}
+
+function guessStringPlaceholder(schema: OpenAPIV3.SchemaObject, name?: string): string {
+  // Format-based
+  if (schema.format === "email") return "{{$randomEmail}}";
+  if (schema.format === "uuid") return "{{$uuid}}";
+  if (schema.format === "date-time" || schema.format === "date") return "2025-01-01T00:00:00Z";
+
+  // Name-based heuristics
+  if (name) {
+    const lower = name.toLowerCase();
+    if (lower === "email" || lower.endsWith("_email") || lower.endsWith("Email")) {
+      return "{{$randomEmail}}";
+    }
+    if (lower === "id" || lower === "uuid" || lower.endsWith("_id") || lower.endsWith("id")) {
+      return "{{$uuid}}";
+    }
+    if (lower === "name" || lower.endsWith("_name") || lower.endsWith("Name")) {
+      return "{{$randomName}}";
+    }
+  }
+
+  return "{{$randomString}}";
+}
+
+function guessIntPlaceholder(name?: string): string {
+  if (name) {
+    const lower = name.toLowerCase();
+    if (lower === "id" || lower.endsWith("_id") || lower.endsWith("Id")) {
+      return "{{$randomInt}}";
+    }
+  }
+  return "{{$randomInt}}";
+}

package/src/core/generator/index.ts

@@ -0,0 +1,10 @@
+export { readOpenApiSpec, extractEndpoints, extractSecuritySchemes } from "./openapi-reader.ts";
+export { serializeSuite, isRelativeUrl, sanitizeEnvName, resolveSpecPath } from "./serializer.ts";
+export type { RawSuite, RawStep } from "./serializer.ts";
+export { generateFromSchema } from "./data-factory.ts";
+export { generateWithAI } from "./ai/ai-generator.ts";
+export { resolveProviderConfig, PROVIDER_DEFAULTS } from "./ai/types.ts";
+export type { AIProviderConfig, AIGenerateOptions, AIGenerateResult } from "./ai/types.ts";
+export { scanCoveredEndpoints, filterUncoveredEndpoints } from "./coverage-scanner.ts";
+export type { CoveredEndpoint } from "./coverage-scanner.ts";
+export type { EndpointInfo, ResponseInfo, GenerateOptions, SecuritySchemeInfo, CrudGroup } from "./types.ts";

package/src/core/generator/openapi-reader.ts

@@ -0,0 +1,142 @@
+import { dereference } from "@readme/openapi-parser";
+import type { OpenAPIV3 } from "openapi-types";
+import type { EndpointInfo, ResponseInfo, SecuritySchemeInfo } from "./types.ts";
+
+const HTTP_METHODS = ["get", "post", "put", "patch", "delete"] as const;
+
+export async function readOpenApiSpec(specPath: string): Promise<OpenAPIV3.Document> {
+  // For HTTP URLs, fetch the spec first then dereference the parsed object
+  if (specPath.startsWith("http://") || specPath.startsWith("https://")) {
+    const resp = await fetch(specPath);
+    if (!resp.ok) throw new Error(`Failed to fetch spec: ${resp.status} ${resp.statusText}`);
+    const spec = await resp.json();
+    const api = await dereference(spec);
+    return api as OpenAPIV3.Document;
+  }
+  const api = await dereference(specPath);
+  return api as OpenAPIV3.Document;
+}
+
+export function extractSecuritySchemes(doc: OpenAPIV3.Document): SecuritySchemeInfo[] {
+  const schemes: SecuritySchemeInfo[] = [];
+  const securitySchemes = doc.components?.securitySchemes;
+  if (!securitySchemes) return schemes;
+
+  for (const [name, schemeObj] of Object.entries(securitySchemes)) {
+    const scheme = schemeObj as OpenAPIV3.SecuritySchemeObject;
+    const info: SecuritySchemeInfo = {
+      name,
+      type: scheme.type as SecuritySchemeInfo["type"],
+    };
+    if (scheme.type === "http") {
+      info.scheme = scheme.scheme;
+      info.bearerFormat = scheme.bearerFormat;
+    }
+    if (scheme.type === "apiKey") {
+      info.in = scheme.in;
+      info.apiKeyName = scheme.name;
+    }
+    schemes.push(info);
+  }
+  return schemes;
+}
+
+export function extractEndpoints(doc: OpenAPIV3.Document): EndpointInfo[] {
+  const endpoints: EndpointInfo[] = [];
+
+  if (!doc.paths) return endpoints;
+
+  for (const [path, pathItem] of Object.entries(doc.paths)) {
+    if (!pathItem) continue;
+
+    for (const method of HTTP_METHODS) {
+      const operation = pathItem[method] as OpenAPIV3.OperationObject | undefined;
+      if (!operation) continue;
+
+      const parameters: OpenAPIV3.ParameterObject[] = [];
+
+      // Path-level parameters
+      if (pathItem.parameters) {
+        for (const p of pathItem.parameters) {
+          parameters.push(p as OpenAPIV3.ParameterObject);
+        }
+      }
+
+      // Operation-level parameters (override path-level)
+      if (operation.parameters) {
+        for (const p of operation.parameters) {
+          const param = p as OpenAPIV3.ParameterObject;
+          const existingIdx = parameters.findIndex(
+            (existing) => existing.name === param.name && existing.in === param.in,
+          );
+          if (existingIdx >= 0) {
+            parameters[existingIdx] = param;
+          } else {
+            parameters.push(param);
+          }
+        }
+      }
+
+      // Request body schema + content type
+      let requestBodySchema: OpenAPIV3.SchemaObject | undefined;
+      let requestBodyContentType: string | undefined;
+      if (operation.requestBody) {
+        const rb = operation.requestBody as OpenAPIV3.RequestBodyObject;
+        if (rb.content) {
+          // Prefer application/json, fall back to first available
+          const contentTypes = Object.keys(rb.content);
+          requestBodyContentType = contentTypes.includes("application/json")
+            ? "application/json"
+            : contentTypes[0];
+          const chosen = rb.content[requestBodyContentType!];
+          if (chosen?.schema) {
+            requestBodySchema = chosen.schema as OpenAPIV3.SchemaObject;
+          }
+        }
+      }
+
+      // Responses
+      const responses: ResponseInfo[] = [];
+      const responseContentTypesSet = new Set<string>();
+      if (operation.responses) {
+        for (const [statusCode, responseObj] of Object.entries(operation.responses)) {
+          const resp = responseObj as OpenAPIV3.ResponseObject;
+          const info: ResponseInfo = {
+            statusCode: parseInt(statusCode, 10),
+            description: resp.description || "",
+          };
+          if (resp.content) {
+            for (const ct of Object.keys(resp.content)) {
+              responseContentTypesSet.add(ct);
+            }
+            const jsonContent = resp.content["application/json"];
+            if (jsonContent?.schema) {
+              info.schema = jsonContent.schema as OpenAPIV3.SchemaObject;
+            }
+          }
+          responses.push(info);
+        }
+      }
+
+      // Security: operation-level overrides doc-level
+      const securityReqs = operation.security ?? doc.security ?? [];
+      const security = securityReqs.flatMap((req) => Object.keys(req));
+
+      endpoints.push({
+        path,
+        method: method.toUpperCase(),
+        operationId: operation.operationId,
+        summary: operation.summary,
+        tags: operation.tags ?? [],
+        parameters,
+        requestBodySchema,
+        requestBodyContentType,
+        responseContentTypes: [...responseContentTypesSet],
+        responses,
+        security,
+      });
+    }
+  }
+
+  return endpoints;
+}

package/src/core/generator/schema-utils.ts

@@ -0,0 +1,52 @@
+import type { OpenAPIV3 } from "openapi-types";
+
+/**
+ * Returns true if the schema is effectively `any` — no type, no properties, no constraints.
+ */
+export function isAnySchema(schema: OpenAPIV3.SchemaObject | undefined): boolean {
+  if (!schema) return false;
+  return Object.keys(schema).length === 0 ||
+    (!schema.type && !schema.properties && !schema.enum && !schema.oneOf && !schema.allOf && !schema.anyOf);
+}
+
+/**
+ * Compress an OpenAPI schema into a concise human-readable string.
+ * E.g. { name: string (req), age: integer, tags: [string] }
+ */
+export function compressSchema(schema: OpenAPIV3.SchemaObject, depth = 0): string {
+  if (depth > 2) return "{...}";
+
+  if (schema.type === "object" && schema.properties) {
+    const required = new Set(schema.required ?? []);
+    const fields = Object.entries(schema.properties).map(([key, propObj]) => {
+      const prop = propObj as OpenAPIV3.SchemaObject;
+      const type = prop.type ?? "any";
+      const flags: string[] = [];
+      if (required.has(key)) flags.push("req");
+      if (prop.format) flags.push(prop.format);
+      if (prop.enum) flags.push(`enum: ${prop.enum.join("|")}`);
+      const flagStr = flags.length > 0 ? ` (${flags.join(", ")})` : "";
+      return `${key}: ${type}${flagStr}`;
+    });
+    return `{ ${fields.join(", ")} }`;
+  }
+
+  if (schema.type === "array") {
+    const items = schema.items as OpenAPIV3.SchemaObject | undefined;
+    if (items) return `[${compressSchema(items, depth + 1)}]`;
+    return "[]";
+  }
+
+  return schema.type ?? "any";
+}
+
+/**
+ * Format an OpenAPI parameter into a concise string.
+ * E.g. "limit: integer" or "id: string (req)"
+ */
+export function formatParam(p: OpenAPIV3.ParameterObject): string {
+  const schema = p.schema as OpenAPIV3.SchemaObject | undefined;
+  const type = schema?.type ?? "string";
+  const req = p.required ? " (req)" : "";
+  return `${p.name}: ${type}${req}`;
+}

package/src/core/generator/serializer.ts

@@ -0,0 +1,189 @@
+import { resolve } from "path";
+
+// ──────────────────────────────────────────────
+// Utility functions (moved from skeleton.ts)
+// ──────────────────────────────────────────────
+
+export function isRelativeUrl(url: string): boolean {
+  return url.startsWith("/") && !url.includes("://");
+}
+
+export function resolveSpecPath(specPath: string): string {
+  if (specPath.startsWith("http://") || specPath.startsWith("https://")) {
+    return specPath;
+  }
+  return resolve(specPath);
+}
+
+export function sanitizeEnvName(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 30);
+}
+
+// ──────────────────────────────────────────────
+// Types for raw suite serialization
+// ──────────────────────────────────────────────
+
+export interface RawStep {
+  name: string;
+  [methodKey: string]: unknown;
+  expect: {
+    status?: number;
+    body?: Record<string, Record<string, string>>;
+  };
+}
+
+export interface RawSuite {
+  name: string;
+  folder?: string;
+  fileStem?: string;
+  base_url?: string;
+  headers?: Record<string, string>;
+  tests: RawStep[];
+}
+
+// ──────────────────────────────────────────────
+// YAML serializer
+// ──────────────────────────────────────────────
+
+export function serializeSuite(suite: RawSuite): string {
+  const lines: string[] = [];
+  lines.push(`name: ${yamlScalar(suite.name)}`);
+  if (suite.base_url) {
+    lines.push(`base_url: ${yamlScalar(suite.base_url)}`);
+  }
+  if (suite.headers && Object.keys(suite.headers).length > 0) {
+    lines.push("headers:");
+    for (const [hk, hv] of Object.entries(suite.headers)) {
+      lines.push(`  ${hk}: ${yamlScalar(String(hv))}`);
+    }
+  }
+  lines.push("tests:");
+
+  for (const test of suite.tests) {
+    lines.push(`  - name: ${yamlScalar(test.name)}`);
+
+    // Write method-as-key (the shorthand)
+    for (const method of ["GET", "POST", "PUT", "PATCH", "DELETE"]) {
+      if (method in test) {
+        lines.push(`    ${method}: ${test[method]}`);
+      }
+    }
+
+    // headers
+    if (test.headers && Object.keys(test.headers as Record<string, string>).length > 0) {
+      lines.push("    headers:");
+      for (const [hk, hv] of Object.entries(test.headers as Record<string, string>)) {
+        lines.push(`      ${hk}: ${yamlScalar(String(hv))}`);
+      }
+    }
+
+    // json body
+    if (test.json !== undefined) {
+      lines.push("    json:");
+      serializeValue(test.json, 3, lines);
+    }
+
+    // query
+    if (test.query) {
+      lines.push("    query:");
+      serializeValue(test.query, 3, lines);
+    }
+
+    // expect
+    lines.push("    expect:");
+    if (test.expect.status !== undefined) {
+      lines.push(`      status: ${test.expect.status}`);
+    }
+    if (test.expect.body) {
+      lines.push("      body:");
+      for (const [key, rule] of Object.entries(test.expect.body)) {
+        lines.push(`        ${key}:`);
+        for (const [rk, rv] of Object.entries(rule)) {
+          lines.push(`          ${rk}: ${yamlScalar(String(rv))}`);
+        }
+      }
+    }
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+function serializeValue(value: unknown, indent: number, lines: string[]): void {
+  const prefix = "  ".repeat(indent);
+
+  if (value === null || value === undefined) {
+    lines.push(`${prefix}null`);
+    return;
+  }
+
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    lines.push(`${prefix}${yamlScalar(String(value))}`);
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      if (typeof item === "object" && item !== null && !Array.isArray(item)) {
+        const entries = Object.entries(item as Record<string, unknown>);
+        if (entries.length > 0) {
+          const [firstKey, firstVal] = entries[0]!;
+          lines.push(`${prefix}- ${firstKey}: ${formatInlineValue(firstVal)}`);
+          for (let i = 1; i < entries.length; i++) {
+            const [k, v] = entries[i]!;
+            lines.push(`${prefix}  ${k}: ${formatInlineValue(v)}`);
+          }
+        } else {
+          lines.push(`${prefix}- {}`);
+        }
+      } else {
+        lines.push(`${prefix}- ${formatInlineValue(item)}`);
+      }
+    }
+    return;
+  }
+
+  if (typeof value === "object") {
+    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+      if (typeof val === "object" && val !== null) {
+        lines.push(`${prefix}${key}:`);
+        serializeValue(val, indent + 1, lines);
+      } else {
+        lines.push(`${prefix}${key}: ${formatInlineValue(val)}`);
+      }
+    }
+  }
+}
+
+function formatInlineValue(val: unknown): string {
+  if (val === null || val === undefined) return "null";
+  if (typeof val === "string") return yamlScalar(val);
+  return String(val);
+}
+
+function yamlScalar(value: string): string {
+  if (
+    value === "" ||
+    value === "true" ||
+    value === "false" ||
+    value === "null" ||
+    value.includes(":") ||
+    value.includes("#") ||
+    value.includes("\n") ||
+    value.includes("'") ||
+    value.includes('"') ||
+    value.includes("{") ||
+    value.includes("}") ||
+    value.includes("[") ||
+    value.includes("]") ||
+    value.startsWith("&") ||
+    value.startsWith("*") ||
+    value.startsWith("!") ||
+    value.startsWith("%") ||
+    value.startsWith("@") ||
+    value.startsWith("`") ||
+    /^\d+$/.test(value)
+  ) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  }
+  return value;
+}

package/src/core/generator/types.ts

@@ -0,0 +1,47 @@
+import type { OpenAPIV3 } from "openapi-types";
+
+export interface ResponseInfo {
+  statusCode: number;
+  description: string;
+  schema?: OpenAPIV3.SchemaObject;
+}
+
+export interface EndpointInfo {
+  path: string;
+  method: string;
+  operationId?: string;
+  summary?: string;
+  tags: string[];
+  parameters: OpenAPIV3.ParameterObject[];
+  requestBodySchema?: OpenAPIV3.SchemaObject;
+  requestBodyContentType?: string;
+  responseContentTypes: string[];
+  responses: ResponseInfo[];
+  security: string[];
+}
+
+export interface SecuritySchemeInfo {
+  name: string;
+  type: "http" | "apiKey" | "oauth2" | "openIdConnect";
+  scheme?: string;
+  bearerFormat?: string;
+  in?: string;
+  apiKeyName?: string;
+}
+
+export interface CrudGroup {
+  resource: string;
+  basePath: string;
+  itemPath: string;
+  idParam: string;
+  create?: EndpointInfo;
+  list?: EndpointInfo;
+  read?: EndpointInfo;
+  update?: EndpointInfo;
+  delete?: EndpointInfo;
+}
+
+export interface GenerateOptions {
+  specPath: string;
+  outputDir: string;
+}

package/src/core/parser/filter.ts

@@ -0,0 +1,14 @@
+import type { TestSuite } from "./types.ts";
+
+/**
+ * Filter suites by tags (OR logic, case-insensitive).
+ * Suites without tags are excluded when filtering is active.
+ */
+export function filterSuitesByTags(suites: TestSuite[], tags: string[]): TestSuite[] {
+  if (tags.length === 0) return suites;
+  const normalizedTags = tags.map(t => t.toLowerCase());
+  return suites.filter(suite => {
+    if (!suite.tags || suite.tags.length === 0) return false;
+    return suite.tags.some(t => normalizedTags.includes(t.toLowerCase()));
+  });
+}

package/src/core/parser/index.ts

@@ -0,0 +1,21 @@
+export type {
+  HttpMethod,
+  AssertionRule,
+  TestStepExpect,
+  TestStep,
+  SuiteConfig,
+  TestSuite,
+  Environment,
+} from "./types.ts";
+
+export { validateSuite, DEFAULT_CONFIG } from "./schema.ts";
+export {
+  GENERATORS,
+  substituteString,
+  substituteDeep,
+  substituteStep,
+  extractVariableReferences,
+  loadEnvironment,
+} from "./variables.ts";
+export { parse, parseFile, parseDirectory } from "./yaml-parser.ts";
+export { filterSuitesByTags } from "./filter.ts";