apigrip 0.1.0

package/core/response-store.js

@@ -0,0 +1,121 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getConfigDir, getProjectHash } from './env-resolver.js';
+
+/**
+ * Get the responses file path for a project.
+ */
+function getResponsesFilePath(projectDir) {
+  const configDir = getConfigDir();
+  const hash = getProjectHash(projectDir);
+  return path.join(configDir, 'responses', `${hash}.json`);
+}
+
+/**
+ * Read and parse the responses file.
+ * Returns an empty object if the file doesn't exist or is corrupt.
+ */
+function readResponsesFile(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return {};
+    }
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      console.warn(`[response-store] Corrupt responses file at ${filePath}, returning defaults`);
+      return {};
+    }
+    return parsed;
+  } catch (err) {
+    console.warn(`[response-store] Failed to read responses file at ${filePath}: ${err.message}`);
+    return {};
+  }
+}
+
+/**
+ * Write the full responses object to the responses file.
+ */
+function writeResponsesFile(filePath, data) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+}
+
+/**
+ * Save the last response for a specific endpoint.
+ * @param {string} projectDir - Project directory path
+ * @param {string} method - HTTP method (e.g., "GET")
+ * @param {string} endpointPath - Endpoint path (e.g., "/users/{id}")
+ * @param {object} response - Response object to save
+ * @param {number} response.status - HTTP status code
+ * @param {string} [response.status_text] - HTTP status text
+ * @param {object} [response.headers] - Response headers
+ * @param {string} [response.body] - Response body
+ * @param {number} [response.size_bytes] - Response size
+ * @param {object} [response.timing] - Timing info (dns_ms, tcp_ms, tls_ms, ttfb_ms, total_ms)
+ * @param {string} [response.curl_command] - curl command used
+ * @param {object} [response.validation] - Schema validation result
+ */
+export function saveLastResponse(projectDir, method, endpointPath, response) {
+  const filePath = getResponsesFilePath(projectDir);
+  const all = readResponsesFile(filePath);
+  const key = `${method.toUpperCase()} ${endpointPath}`;
+  all[key] = {
+    ...response,
+    saved_at: new Date().toISOString(),
+  };
+  writeResponsesFile(filePath, all);
+}
+
+/**
+ * Load the last response for a specific endpoint.
+ * @param {string} projectDir - Project directory path
+ * @param {string} method - HTTP method (e.g., "GET")
+ * @param {string} endpointPath - Endpoint path (e.g., "/users/{id}")
+ * @returns {object|null} The saved response or null if none exists
+ */
+export function loadLastResponse(projectDir, method, endpointPath) {
+  const filePath = getResponsesFilePath(projectDir);
+  const all = readResponsesFile(filePath);
+  const key = `${method.toUpperCase()} ${endpointPath}`;
+  return all[key] || null;
+}
+
+/**
+ * Load all saved responses for a project.
+ * @param {string} projectDir - Project directory path
+ * @returns {object} Full responses object keyed by "METHOD /path"
+ */
+export function loadAllResponses(projectDir) {
+  const filePath = getResponsesFilePath(projectDir);
+  return readResponsesFile(filePath);
+}
+
+/**
+ * Clear the saved response for a specific endpoint.
+ * @param {string} projectDir - Project directory path
+ * @param {string} method - HTTP method
+ * @param {string} endpointPath - Endpoint path
+ * @returns {boolean} True if a response was cleared, false if none existed
+ */
+export function clearLastResponse(projectDir, method, endpointPath) {
+  const filePath = getResponsesFilePath(projectDir);
+  const all = readResponsesFile(filePath);
+  const key = `${method.toUpperCase()} ${endpointPath}`;
+  if (key in all) {
+    delete all[key];
+    writeResponsesFile(filePath, all);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Clear all saved responses for a project.
+ * @param {string} projectDir - Project directory path
+ */
+export function clearAllResponses(projectDir) {
+  const filePath = getResponsesFilePath(projectDir);
+  writeResponsesFile(filePath, {});
+}

package/core/schema-validator.js

@@ -0,0 +1,196 @@
+/**
+ * schema-validator.js - Validate JSON against JSON Schema using ajv.
+ */
+
+import Ajv from 'ajv';
+
+/**
+ * Create a configured Ajv instance.
+ */
+function createAjv() {
+  return new Ajv({
+    allErrors: true,
+    strict: false,
+    validateFormats: false,
+  });
+}
+
+/**
+ * Convert Ajv errors to our standard error format.
+ *
+ * @param {Array} ajvErrors - Errors from ajv.errors
+ * @returns {Array<{path: string, message: string, expected: string, actual: string}>}
+ */
+function formatErrors(ajvErrors) {
+  if (!ajvErrors || ajvErrors.length === 0) return [];
+
+  return ajvErrors.map(err => {
+    const path = err.instancePath || '/';
+    let expected = '';
+    let actual = '';
+
+    if (err.keyword === 'type') {
+      expected = String(err.params.type);
+      actual = err.data != null ? typeof err.data : 'undefined';
+    } else if (err.keyword === 'required') {
+      expected = 'required';
+      actual = 'missing';
+    } else if (err.keyword === 'enum') {
+      expected = `one of: ${(err.params.allowedValues || []).join(', ')}`;
+      actual = String(err.data);
+    } else if (err.keyword === 'format') {
+      expected = `${err.params.format} format`;
+      actual = String(err.data);
+    } else if (err.keyword === 'minimum' || err.keyword === 'maximum') {
+      expected = `${err.keyword}: ${err.params.limit}`;
+      actual = String(err.data);
+    } else if (err.keyword === 'minLength' || err.keyword === 'maxLength') {
+      expected = `${err.keyword}: ${err.params.limit}`;
+      actual = `length: ${String(err.data).length}`;
+    } else if (err.keyword === 'additionalProperties') {
+      expected = 'no additional properties';
+      actual = `property: ${err.params.additionalProperty}`;
+    } else if (err.keyword === 'pattern') {
+      expected = `pattern: ${err.params.pattern}`;
+      actual = String(err.data);
+    } else {
+      expected = err.keyword || '';
+      actual = err.data != null ? String(err.data) : '';
+    }
+
+    return {
+      path,
+      message: err.message || 'Validation error',
+      expected,
+      actual,
+    };
+  });
+}
+
+/**
+ * Validate a request body against a JSON schema.
+ *
+ * @param {object} schema - JSON Schema to validate against
+ * @param {string} body - Body string to validate
+ * @param {string} contentType - Content type of the body
+ * @returns {{ valid: boolean|null, errors: Array }}
+ */
+export function validateBody(schema, body, contentType) {
+  // For non-JSON content types, skip validation
+  if (!contentType || !contentType.includes('json')) {
+    return { valid: null, errors: [] };
+  }
+
+  if (!schema) {
+    return { valid: null, errors: [] };
+  }
+
+  // Parse body as JSON
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch (err) {
+    return {
+      valid: false,
+      errors: [{
+        path: '/',
+        message: `Invalid JSON: ${err.message}`,
+        expected: 'valid JSON',
+        actual: 'parse error',
+      }],
+    };
+  }
+
+  const ajv = createAjv();
+  let validate;
+  try {
+    validate = ajv.compile(schema);
+  } catch (err) {
+    return {
+      valid: null,
+      errors: [{
+        path: '/',
+        message: `Schema compilation error: ${err.message}`,
+        expected: 'valid schema',
+        actual: 'invalid schema',
+      }],
+    };
+  }
+
+  const valid = validate(parsed);
+  if (valid) {
+    return { valid: true, errors: [] };
+  }
+
+  return {
+    valid: false,
+    errors: formatErrors(validate.errors),
+  };
+}
+
+/**
+ * Validate a response body against the spec's schema for the given status code and content type.
+ *
+ * @param {object} spec - Parsed OpenAPI spec
+ * @param {string} method - HTTP method (case-insensitive)
+ * @param {string} path - OpenAPI path template
+ * @param {number|string} statusCode - HTTP status code
+ * @param {string} responseBody - Response body string
+ * @param {string} responseContentType - Response content type
+ * @returns {{ valid: boolean|null, errors: Array }}
+ */
+export function validateResponse(spec, method, path, statusCode, responseBody, responseContentType) {
+  if (!spec || !spec.paths || !spec.paths[path]) {
+    return { valid: null, errors: [] };
+  }
+
+  const pathItem = spec.paths[path];
+  const operation = pathItem[method.toLowerCase()];
+  if (!operation || !operation.responses) {
+    return { valid: null, errors: [] };
+  }
+
+  const statusStr = String(statusCode);
+
+  // Try the exact status code first, then fallback to default
+  let responseDef = operation.responses[statusStr] || operation.responses.default;
+  if (!responseDef) {
+    return { valid: null, errors: [] };
+  }
+
+  // OpenAPI 3.x: responses have content map
+  if (responseDef.content) {
+    const schema = findSchemaForContentType(responseDef.content, responseContentType);
+    if (!schema) {
+      return { valid: null, errors: [] };
+    }
+    return validateBody(schema, responseBody, responseContentType);
+  }
+
+  // Swagger 2.0: responses have a direct schema property
+  if (responseDef.schema) {
+    return validateBody(responseDef.schema, responseBody, responseContentType || 'application/json');
+  }
+
+  return { valid: null, errors: [] };
+}
+
+/**
+ * Find a schema in a content map for a given content type.
+ * Handles exact match and partial match (e.g., 'application/json' matches 'application/json; charset=utf-8').
+ */
+function findSchemaForContentType(content, responseContentType) {
+  if (!content || !responseContentType) return null;
+
+  // Normalize the content type: take just the media type part (before semicolon)
+  const normalizedType = responseContentType.split(';')[0].trim().toLowerCase();
+
+  for (const [ct, def] of Object.entries(content)) {
+    const normalizedCt = ct.split(';')[0].trim().toLowerCase();
+    if (normalizedCt === normalizedType) {
+      return def.schema || null;
+    }
+  }
+
+  return null;
+}

package/core/spec-discovery.js

@@ -0,0 +1,109 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, extname } from 'node:path';
+import yaml from 'js-yaml';
+
+const EXCLUDED_DIRS = new Set([
+  'node_modules', '.git', 'vendor', 'dist', 'build', '__pycache__', '.venv', 'target'
+]);
+
+const ROOT_PRIORITY = ['openapi.yaml', 'openapi.yml', 'openapi.json'];
+
+/**
+ * Check if a file is a valid OpenAPI/Swagger spec by examining its top-level keys.
+ */
+async function isSpecFile(filePath) {
+  try {
+    const ext = extname(filePath).toLowerCase();
+    if (!['.yaml', '.yml', '.json'].includes(ext)) {
+      return false;
+    }
+
+    const content = await readFile(filePath, 'utf-8');
+    let parsed;
+
+    if (ext === '.json') {
+      parsed = JSON.parse(content);
+    } else {
+      parsed = yaml.load(content);
+    }
+
+    if (parsed && typeof parsed === 'object') {
+      return ('openapi' in parsed) || ('swagger' in parsed);
+    }
+
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a directory name should be excluded from recursive search.
+ */
+function isExcludedDir(name) {
+  if (EXCLUDED_DIRS.has(name)) return true;
+  if (name.startsWith('.')) return true;
+  return false;
+}
+
+/**
+ * Discover an OpenAPI spec file in a directory.
+ *
+ * Priority:
+ *   1. openapi.yaml > openapi.yml > openapi.json in the project root
+ *   2. Recursive BFS, alphabetical order, excluding certain directories
+ *
+ * @param {string} projectDir - The project directory to search in
+ * @returns {Promise<{specPath: string, specFile: string} | null>}
+ */
+export async function discoverSpec(projectDir) {
+  // Phase 1: Check root priority files
+  for (const fileName of ROOT_PRIORITY) {
+    const filePath = join(projectDir, fileName);
+    if (await isSpecFile(filePath)) {
+      return { specPath: filePath, specFile: fileName };
+    }
+  }
+
+  // Phase 2: Recursive BFS
+  const queue = [projectDir];
+
+  while (queue.length > 0) {
+    const currentDir = queue.shift();
+    let entries;
+
+    try {
+      entries = await readdir(currentDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    // Sort entries alphabetically for deterministic order
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+
+    const subdirs = [];
+
+    for (const entry of entries) {
+      const fullPath = join(currentDir, entry.name);
+
+      if (entry.isFile()) {
+        // Skip root priority files if we're in the root dir (already checked)
+        if (currentDir === projectDir && ROOT_PRIORITY.includes(entry.name)) {
+          continue;
+        }
+
+        if (await isSpecFile(fullPath)) {
+          const relative = fullPath.slice(projectDir.length + 1);
+          return { specPath: fullPath, specFile: relative };
+        }
+      } else if (entry.isDirectory() && !isExcludedDir(entry.name)) {
+        subdirs.push(fullPath);
+      }
+    }
+
+    // Add subdirs to queue (they're already sorted)
+    queue.push(...subdirs);
+  }
+
+  return null;
+}

package/core/spec-parser.js

@@ -0,0 +1,172 @@
+import SwaggerParser from '@apidevtools/swagger-parser';
+
+const HTTP_METHODS = ['get', 'post', 'put', 'delete', 'patch', 'options', 'head'];
+
+/**
+ * Parse and dereference an OpenAPI spec file.
+ *
+ * @param {string} specPath - Absolute path to the spec file
+ * @returns {Promise<object>} - Parsed and dereferenced spec object
+ */
+export async function parseSpec(specPath) {
+  const spec = await SwaggerParser.dereference(specPath);
+  return spec;
+}
+
+/**
+ * Extract a lean endpoint list from a parsed spec.
+ *
+ * @param {object} spec - Parsed OpenAPI spec
+ * @returns {Array<{method: string, path: string, summary: string, tags: string[], deprecated: boolean}>}
+ */
+export function extractEndpoints(spec) {
+  const endpoints = [];
+
+  if (!spec || !spec.paths) {
+    return endpoints;
+  }
+
+  for (const [path, pathItem] of Object.entries(spec.paths)) {
+    if (!pathItem || typeof pathItem !== 'object') continue;
+
+    for (const method of HTTP_METHODS) {
+      const operation = pathItem[method];
+      if (!operation) continue;
+
+      endpoints.push({
+        method: method.toUpperCase(),
+        path,
+        summary: operation.summary || '',
+        tags: operation.tags || [],
+        deprecated: operation.deprecated || false,
+      });
+    }
+  }
+
+  return endpoints;
+}
+
+/**
+ * Get full details for a single endpoint.
+ * Merges path-level and operation-level parameters (operation params override
+ * path params with the same name+in combination).
+ *
+ * @param {object} spec - Parsed OpenAPI spec
+ * @param {string} method - HTTP method (case-insensitive)
+ * @param {string} path - OpenAPI path template
+ * @returns {object|null} - Full endpoint details or null if not found
+ */
+export function getEndpointDetails(spec, method, path) {
+  if (!spec || !spec.paths || !spec.paths[path]) {
+    return null;
+  }
+
+  const pathItem = spec.paths[path];
+  const lowerMethod = method.toLowerCase();
+  const operation = pathItem[lowerMethod];
+
+  if (!operation) {
+    return null;
+  }
+
+  // Merge parameters: path-level first, then operation-level overrides
+  const pathParams = pathItem.parameters || [];
+  const opParams = operation.parameters || [];
+
+  // Build a map keyed by name+in, path-level first, operation overrides
+  const paramMap = new Map();
+  for (const param of pathParams) {
+    const key = `${param.name}:${param.in}`;
+    paramMap.set(key, { ...param });
+  }
+  for (const param of opParams) {
+    const key = `${param.name}:${param.in}`;
+    paramMap.set(key, { ...param });
+  }
+
+  const mergedParams = Array.from(paramMap.values());
+
+  // Build request_body
+  let requestBody = null;
+  if (operation.requestBody) {
+    requestBody = {
+      required: operation.requestBody.required || false,
+      content: operation.requestBody.content || {},
+    };
+  }
+
+  // Build responses
+  const responses = {};
+  if (operation.responses) {
+    for (const [statusCode, responseDef] of Object.entries(operation.responses)) {
+      responses[statusCode] = {
+        description: responseDef.description || '',
+      };
+      if (responseDef.content) {
+        responses[statusCode].content = responseDef.content;
+      }
+    }
+  }
+
+  // Resolve servers: operation-level > path-level > spec-level
+  let servers = [];
+  if (operation.servers && operation.servers.length > 0) {
+    servers = operation.servers;
+  } else if (pathItem.servers && pathItem.servers.length > 0) {
+    servers = pathItem.servers;
+  } else if (spec.servers && spec.servers.length > 0) {
+    servers = spec.servers;
+  }
+
+  // For Swagger 2.0, construct servers from host + basePath + schemes
+  if (servers.length === 0 && spec.swagger && spec.host) {
+    const scheme = (spec.schemes && spec.schemes[0]) || 'https';
+    const basePath = spec.basePath || '';
+    servers = [{
+      url: `${scheme}://${spec.host}${basePath}`,
+      description: 'Default server',
+    }];
+  }
+
+  return {
+    method: method.toUpperCase(),
+    path,
+    summary: operation.summary || '',
+    description: operation.description || '',
+    tags: operation.tags || [],
+    deprecated: operation.deprecated || false,
+    parameters: mergedParams,
+    request_body: requestBody,
+    responses,
+    servers,
+  };
+}
+
+/**
+ * Get all external file paths referenced via $ref in the spec.
+ *
+ * @param {string} specPath - Absolute path to the spec file
+ * @returns {Promise<string[]>} - Array of external file paths
+ */
+export async function getRefDeps(specPath) {
+  const parser = new SwaggerParser();
+  await parser.resolve(specPath);
+  const allPaths = parser.$refs.paths();
+
+  // Filter out the spec file itself and return only external refs.
+  // $refs.paths() returns file URLs or absolute paths depending on platform.
+  return allPaths.filter(p => {
+    let normalized = p;
+    let specNormalized = specPath;
+
+    // Handle file:// URLs
+    if (p.startsWith('file://')) {
+      try { normalized = new URL(p).pathname; } catch { /* keep as-is */ }
+    }
+    if (specPath.startsWith('file://')) {
+      try { specNormalized = new URL(specPath).pathname; } catch { /* keep as-is */ }
+    }
+
+    return normalized !== specNormalized;
+  });
+}

package/lib/index.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+// CJS compatibility wrapper for ESM-only core modules.
+//
+// Usage in CommonJS projects:
+//
+//   const apigrip = await require('apigrip');
+//   const { spec, endpoints } = await apigrip.loadSpec('./my-api/');
+//
+// Or with .then():
+//
+//   require('apigrip').then(({ loadSpec, send }) => {
+//     // ...
+//   });
+
+module.exports = import('./index.js');