jamdesk 1.0.0

package/vendored/lib/openapi/parser.ts

@@ -0,0 +1,474 @@
+/**
+ * OpenAPI Parser
+ * 
+ * Parses endpoint data from validated OpenAPI specifications.
+ * Extracts parameters, request bodies, responses, and security info.
+ */
+
+import type { OpenAPI, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
+import type {
+  HttpMethod,
+  ParsedOpenApiFrontmatter,
+  OpenApiEndpointData,
+  ParsedParameter,
+  ParsedRequestBody,
+  ParsedResponse,
+  ServerInfo,
+  SecurityRequirement,
+  JsonSchema,
+} from './types';
+import { createFrontmatterError, createEndpointNotFoundError } from './errors';
+
+// Valid HTTP methods
+const VALID_METHODS: HttpMethod[] = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+
+/**
+ * Parse the openapi frontmatter string
+ * Full format: "/path/to/spec.yaml METHOD /endpoint/path"
+ * Short format (with defaultSpecPath): "METHOD /endpoint/path"
+ */
+export function parseOpenApiFrontmatter(value: string, defaultSpecPath?: string): ParsedOpenApiFrontmatter {
+  const trimmed = value.trim();
+  const parts = trimmed.split(/\s+/);
+
+  // Check if this is the short format (METHOD /path) when a default spec is configured
+  if (parts.length >= 2) {
+    const firstPart = parts[0].toUpperCase();
+    const isMethodFirst = VALID_METHODS.includes(firstPart as HttpMethod);
+
+    if (isMethodFirst) {
+      // Short format: "METHOD /endpoint/path"
+      if (!defaultSpecPath) {
+        throw createFrontmatterError(
+          value,
+          'Short format (e.g., "GET /users") requires api.openapi to be configured in docs.json.\n' +
+          'Either add api.openapi to docs.json or use the full format: "/path/to/spec.yaml METHOD /endpoint/path"'
+        );
+      }
+
+      const [method, ...pathParts] = parts;
+      const endpointPath = pathParts.join(' ');
+
+      // Validate endpoint path
+      if (!endpointPath.startsWith('/')) {
+        throw createFrontmatterError(
+          value,
+          'Endpoint path must start with "/"'
+        );
+      }
+
+      return {
+        specPath: defaultSpecPath.startsWith('/') ? defaultSpecPath : `/${defaultSpecPath}`,
+        method: method.toUpperCase() as HttpMethod,
+        path: endpointPath,
+      };
+    }
+  }
+
+  // Full format: "/path/to/spec.yaml METHOD /endpoint/path"
+  if (parts.length < 3) {
+    throw createFrontmatterError(
+      value,
+      'Expected format: "/path/to/spec.yaml METHOD /endpoint/path"\n' +
+      'Example: "/openapi/api.yaml GET /users/{id}"'
+    );
+  }
+
+  const [specPath, method, ...pathParts] = parts;
+  const endpointPath = pathParts.join(' '); // Handle paths with spaces (unlikely but safe)
+
+  // Validate spec path
+  if (!specPath.match(/\.(ya?ml|json)$/i)) {
+    throw createFrontmatterError(
+      value,
+      'OpenAPI spec must be a .yaml, .yml, or .json file'
+    );
+  }
+
+  // Validate method
+  const upperMethod = method.toUpperCase() as HttpMethod;
+  if (!VALID_METHODS.includes(upperMethod)) {
+    throw createFrontmatterError(
+      value,
+      `Invalid HTTP method "${method}". Must be one of: ${VALID_METHODS.join(', ')}`
+    );
+  }
+
+  // Validate endpoint path
+  if (!endpointPath.startsWith('/')) {
+    throw createFrontmatterError(
+      value,
+      'Endpoint path must start with "/"'
+    );
+  }
+
+  return {
+    specPath,
+    method: upperMethod,
+    path: endpointPath,
+  };
+}
+
+/**
+ * Convert OpenAPI schema to our JsonSchema type
+ */
+function toJsonSchema(schema: unknown): JsonSchema {
+  if (!schema || typeof schema !== 'object') {
+    return {};
+  }
+  
+  const s = schema as Record<string, unknown>;
+  const result: JsonSchema = {};
+  
+  // Copy relevant properties
+  if (s.type) result.type = s.type as string | string[];
+  if (s.format) result.format = s.format as string;
+  if (s.description) result.description = s.description as string;
+  if (s.enum) result.enum = s.enum as unknown[];
+  if (s.default !== undefined) result.default = s.default;
+  if (s.example !== undefined) result.example = s.example;
+  if (s.nullable) result.nullable = s.nullable as boolean;
+  if (s.deprecated) result.deprecated = s.deprecated as boolean;
+  if (s.readOnly) result.readOnly = s.readOnly as boolean;
+  if (s.writeOnly) result.writeOnly = s.writeOnly as boolean;
+  if (s.minimum !== undefined) result.minimum = s.minimum as number;
+  if (s.maximum !== undefined) result.maximum = s.maximum as number;
+  if (s.minLength !== undefined) result.minLength = s.minLength as number;
+  if (s.maxLength !== undefined) result.maxLength = s.maxLength as number;
+  if (s.minItems !== undefined) result.minItems = s.minItems as number;
+  if (s.maxItems !== undefined) result.maxItems = s.maxItems as number;
+  if (s.pattern) result.pattern = s.pattern as string;
+  if (s.required) result.required = s.required as string[];
+  
+  // Handle nested schemas
+  if (s.items) {
+    result.items = toJsonSchema(s.items);
+  }
+  
+  if (s.properties && typeof s.properties === 'object') {
+    result.properties = {};
+    for (const [key, value] of Object.entries(s.properties)) {
+      result.properties[key] = toJsonSchema(value);
+    }
+  }
+  
+  if (s.additionalProperties !== undefined) {
+    if (typeof s.additionalProperties === 'boolean') {
+      result.additionalProperties = s.additionalProperties;
+    } else {
+      result.additionalProperties = toJsonSchema(s.additionalProperties);
+    }
+  }
+  
+  // Handle composition
+  if (Array.isArray(s.oneOf)) {
+    result.oneOf = s.oneOf.map(toJsonSchema);
+  }
+  if (Array.isArray(s.anyOf)) {
+    result.anyOf = s.anyOf.map(toJsonSchema);
+  }
+  if (Array.isArray(s.allOf)) {
+    result.allOf = s.allOf.map(toJsonSchema);
+  }
+  
+  return result;
+}
+
+/**
+ * Parse server info from OpenAPI spec
+ */
+function parseServers(api: OpenAPI.Document): ServerInfo[] {
+  // OpenAPI 3.x
+  if ('servers' in api && Array.isArray(api.servers)) {
+    return api.servers.map((server) => ({
+      url: server.url,
+      description: server.description,
+      variables: server.variables as ServerInfo['variables'],
+    }));
+  }
+  
+  // Swagger 2.0
+  if ('host' in api && typeof api.host === 'string') {
+    const scheme = (api as any).schemes?.[0] || 'https';
+    const basePath = (api as any).basePath || '';
+    return [{
+      url: `${scheme}://${api.host}${basePath}`,
+    }];
+  }
+  
+  return [];
+}
+
+/**
+ * Parse security schemes from OpenAPI spec
+ */
+function parseSecuritySchemes(api: OpenAPI.Document): Map<string, SecurityRequirement> {
+  const schemes = new Map<string, SecurityRequirement>();
+  
+  // OpenAPI 3.x
+  if ('components' in api && api.components?.securitySchemes) {
+    for (const [name, scheme] of Object.entries(api.components.securitySchemes)) {
+      const s = scheme as OpenAPIV3.SecuritySchemeObject;
+      schemes.set(name, {
+        name,
+        type: s.type as SecurityRequirement['type'],
+        scheme: 'scheme' in s ? s.scheme : undefined,
+        in: 'in' in s ? s.in as SecurityRequirement['in'] : undefined,
+        bearerFormat: 'bearerFormat' in s ? s.bearerFormat : undefined,
+      });
+    }
+  }
+  
+  // Swagger 2.0
+  if ('securityDefinitions' in api) {
+    const defs = (api as any).securityDefinitions;
+    for (const [name, scheme] of Object.entries(defs || {})) {
+      const s = scheme as any;
+      schemes.set(name, {
+        name,
+        type: s.type,
+        scheme: s.scheme,
+        in: s.in,
+      });
+    }
+  }
+  
+  return schemes;
+}
+
+/**
+ * Parse security requirements for an operation
+ */
+function parseSecurity(
+  operationSecurity: OpenAPIV3.SecurityRequirementObject[] | undefined,
+  globalSecurity: OpenAPIV3.SecurityRequirementObject[] | undefined,
+  schemes: Map<string, SecurityRequirement>
+): SecurityRequirement[] {
+  const securityReqs = operationSecurity ?? globalSecurity ?? [];
+  const result: SecurityRequirement[] = [];
+  
+  for (const req of securityReqs) {
+    for (const name of Object.keys(req)) {
+      const scheme = schemes.get(name);
+      if (scheme) {
+        result.push(scheme);
+      }
+    }
+  }
+  
+  return result;
+}
+
+/**
+ * Parse parameters from operation and path item
+ */
+function parseParameters(
+  operationParams: unknown[] | undefined,
+  pathParams: unknown[] | undefined
+): ParsedParameter[] {
+  const params: ParsedParameter[] = [];
+  const seen = new Set<string>();
+  
+  // Operation parameters override path parameters
+  const allParams = [...(operationParams || []), ...(pathParams || [])];
+  
+  for (const param of allParams) {
+    const p = param as OpenAPIV3.ParameterObject;
+    
+    // Skip if we've already seen this parameter (operation overrides path)
+    const key = `${p.in}:${p.name}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    
+    params.push({
+      name: p.name,
+      in: p.in as ParsedParameter['in'],
+      required: p.required || p.in === 'path', // Path params are always required
+      description: p.description,
+      schema: toJsonSchema(p.schema),
+      example: p.example,
+      deprecated: p.deprecated,
+      style: p.style,
+      explode: p.explode,
+    });
+  }
+  
+  return params;
+}
+
+/**
+ * Parse request body
+ */
+function parseRequestBody(
+  requestBody: OpenAPIV3.RequestBodyObject | undefined
+): ParsedRequestBody | undefined {
+  if (!requestBody) return undefined;
+  
+  const content: ParsedRequestBody['content'] = {};
+  
+  for (const [mediaType, mediaObj] of Object.entries(requestBody.content || {})) {
+    content[mediaType] = {
+      schema: toJsonSchema(mediaObj.schema),
+      example: mediaObj.example,
+      examples: mediaObj.examples as any,
+    };
+  }
+  
+  return {
+    required: requestBody.required || false,
+    description: requestBody.description,
+    content,
+  };
+}
+
+/**
+ * Parse responses
+ */
+function parseResponses(
+  responses: OpenAPIV3.ResponsesObject | undefined
+): Record<string, ParsedResponse> {
+  const result: Record<string, ParsedResponse> = {};
+  
+  for (const [code, response] of Object.entries(responses || {})) {
+    const r = response as OpenAPIV3.ResponseObject;
+    
+    const content: ParsedResponse['content'] = {};
+    for (const [mediaType, mediaObj] of Object.entries(r.content || {})) {
+      content[mediaType] = {
+        schema: toJsonSchema(mediaObj.schema),
+        example: mediaObj.example,
+        examples: mediaObj.examples as any,
+      };
+    }
+    
+    const headers: ParsedResponse['headers'] = {};
+    for (const [headerName, header] of Object.entries(r.headers || {})) {
+      const h = header as OpenAPIV3.HeaderObject;
+      headers[headerName] = {
+        description: h.description,
+        schema: toJsonSchema(h.schema),
+      };
+    }
+    
+    result[code] = {
+      description: r.description,
+      content: Object.keys(content).length > 0 ? content : undefined,
+      headers: Object.keys(headers).length > 0 ? headers : undefined,
+    };
+  }
+  
+  return result;
+}
+
+/**
+ * Parse a single endpoint from an OpenAPI spec
+ */
+export function parseEndpoint(
+  api: OpenAPI.Document,
+  method: HttpMethod,
+  endpointPath: string,
+  specPath: string
+): OpenApiEndpointData {
+  const paths = (api as OpenAPIV3.Document).paths || {};
+  const pathItem = paths[endpointPath] as OpenAPIV3.PathItemObject | undefined;
+
+  // Collect available endpoints for helpful error messages
+  const availableEndpoints = Object.entries(paths).flatMap(([path, methods]) => {
+    if (!methods || typeof methods !== 'object') return [];
+    return Object.keys(methods)
+      .filter(m => ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'].includes(m.toLowerCase()))
+      .map(m => `${m.toUpperCase()} ${path}`);
+  });
+
+  if (!pathItem) {
+    throw createEndpointNotFoundError(specPath, method, endpointPath, availableEndpoints);
+  }
+
+  const operation = pathItem[method.toLowerCase() as keyof OpenAPIV3.PathItemObject] as
+    | OpenAPIV3.OperationObject
+    | undefined;
+
+  if (!operation) {
+    throw createEndpointNotFoundError(specPath, method, endpointPath, availableEndpoints);
+  }
+  
+  const securitySchemes = parseSecuritySchemes(api);
+  
+  return {
+    method,
+    path: endpointPath,
+    summary: operation.summary,
+    description: operation.description,
+    operationId: operation.operationId,
+    deprecated: operation.deprecated,
+    tags: operation.tags,
+    servers: parseServers(api),
+    security: parseSecurity(
+      operation.security,
+      (api as OpenAPIV3.Document).security,
+      securitySchemes
+    ),
+    parameters: parseParameters(
+      operation.parameters as unknown[],
+      pathItem.parameters as unknown[]
+    ),
+    requestBody: parseRequestBody(operation.requestBody as OpenAPIV3.RequestBodyObject),
+    responses: parseResponses(operation.responses),
+    externalDocs: operation.externalDocs,
+  };
+}
+
+/**
+ * Get all endpoints from an OpenAPI spec
+ */
+export function getAllEndpoints(api: OpenAPI.Document): Array<{
+  method: HttpMethod;
+  path: string;
+  operation: OpenAPIV3.OperationObject;
+  tags: string[];
+}> {
+  const paths = (api as OpenAPIV3.Document).paths || {};
+  const endpoints: Array<{
+    method: HttpMethod;
+    path: string;
+    operation: OpenAPIV3.OperationObject;
+    tags: string[];
+  }> = [];
+  
+  for (const [path, pathItem] of Object.entries(paths)) {
+    const item = pathItem as OpenAPIV3.PathItemObject;
+    
+    for (const method of VALID_METHODS) {
+      const operation = item[method.toLowerCase() as keyof OpenAPIV3.PathItemObject] as
+        | OpenAPIV3.OperationObject
+        | undefined;
+      
+      if (operation) {
+        endpoints.push({
+          method,
+          path,
+          operation,
+          tags: operation.tags || [],
+        });
+      }
+    }
+  }
+  
+  return endpoints;
+}
+
+/**
+ * Get spec info (title, version, description)
+ */
+export function getSpecInfo(api: OpenAPI.Document): {
+  title: string;
+  version: string;
+  description?: string;
+} {
+  const info = (api as OpenAPIV3.Document).info;
+  return {
+    title: info?.title || 'API',
+    version: info?.version || '1.0.0',
+    description: info?.description,
+  };
+}

package/vendored/lib/openapi/types.ts

@@ -0,0 +1,232 @@
+/**
+ * OpenAPI Types
+ * 
+ * TypeScript interfaces for OpenAPI parsing and endpoint data.
+ * Designed to be playground-ready for future interactive API testing.
+ */
+
+import type { OpenAPI, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
+
+// Re-export for convenience
+export type { OpenAPI, OpenAPIV3, OpenAPIV3_1 };
+
+/**
+ * JSON Schema type (simplified for our use case)
+ */
+export interface JsonSchema {
+  type?: string | string[];
+  format?: string;
+  title?: string;
+  description?: string;
+  enum?: unknown[];
+  default?: unknown;
+  example?: unknown;
+  items?: JsonSchema;
+  properties?: Record<string, JsonSchema>;
+  additionalProperties?: boolean | JsonSchema;
+  required?: string[];
+  oneOf?: JsonSchema[];
+  anyOf?: JsonSchema[];
+  allOf?: JsonSchema[];
+  nullable?: boolean;
+  deprecated?: boolean;
+  readOnly?: boolean;
+  writeOnly?: boolean;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  minItems?: number;
+  maxItems?: number;
+  pattern?: string;
+  $ref?: string;
+}
+
+/**
+ * HTTP methods supported
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+
+/**
+ * Parameter location in the request
+ */
+export type ParameterLocation = 'query' | 'path' | 'header' | 'cookie';
+
+/**
+ * Parsed parameter from OpenAPI spec
+ */
+export interface ParsedParameter {
+  name: string;
+  in: ParameterLocation;
+  required: boolean;
+  description?: string;
+  schema: JsonSchema;
+  example?: unknown;
+  deprecated?: boolean;
+  style?: string;
+  explode?: boolean;
+}
+
+/**
+ * Parsed request body from OpenAPI spec
+ */
+export interface ParsedRequestBody {
+  required: boolean;
+  description?: string;
+  content: Record<string, {
+    schema: JsonSchema;
+    example?: unknown;
+    examples?: Record<string, { value: unknown; summary?: string }>;
+  }>;
+}
+
+/**
+ * Parsed response from OpenAPI spec
+ */
+export interface ParsedResponse {
+  description: string;
+  content?: Record<string, {
+    schema: JsonSchema;
+    example?: unknown;
+    examples?: Record<string, { value: unknown; summary?: string }>;
+  }>;
+  headers?: Record<string, {
+    description?: string;
+    schema: JsonSchema;
+  }>;
+}
+
+/**
+ * Server info from OpenAPI spec
+ */
+export interface ServerInfo {
+  url: string;
+  description?: string;
+  variables?: Record<string, {
+    default: string;
+    enum?: string[];
+    description?: string;
+  }>;
+}
+
+/**
+ * Security requirement from OpenAPI spec
+ */
+export interface SecurityRequirement {
+  name: string;
+  type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
+  scheme?: string;  // For http type: 'bearer', 'basic'
+  in?: 'query' | 'header' | 'cookie';  // For apiKey type
+  bearerFormat?: string;
+}
+
+/**
+ * Full endpoint data structure (playground-ready)
+ */
+export interface OpenApiEndpointData {
+  // Basic info
+  method: HttpMethod;
+  path: string;
+  summary?: string;
+  description?: string;
+  operationId?: string;
+  deprecated?: boolean;
+  tags?: string[];
+  
+  // Server info (for future playground)
+  servers: ServerInfo[];
+  
+  // Authentication (for future playground)
+  security: SecurityRequirement[];
+  
+  // Parameters
+  parameters: ParsedParameter[];
+  
+  // Request body
+  requestBody?: ParsedRequestBody;
+  
+  // Responses
+  responses: Record<string, ParsedResponse>;
+  
+  // External docs
+  externalDocs?: {
+    url: string;
+    description?: string;
+  };
+}
+
+/**
+ * Parsed frontmatter from MDX openapi field
+ */
+export interface ParsedOpenApiFrontmatter {
+  specPath: string;
+  method: HttpMethod;
+  path: string;
+}
+
+/**
+ * Validation error types
+ */
+export type OpenApiErrorType = 
+  | 'file_not_found'
+  | 'parse_error'
+  | 'validation_error'
+  | 'ref_error'
+  | 'endpoint_not_found'
+  | 'frontmatter_error';
+
+/**
+ * Validation error structure
+ */
+export interface OpenApiValidationError {
+  type: OpenApiErrorType;
+  specPath: string;
+  message: string;
+  suggestion: string;
+  details?: string;
+  location?: {
+    path: string;
+    line?: number;
+  };
+}
+
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+  valid: boolean;
+  api?: OpenAPI.Document;
+  version?: '2.0' | '3.0' | '3.1';
+  error?: OpenApiValidationError;
+}
+
+/**
+ * Generated code examples
+ */
+export interface CodeExamples {
+  curl: string;
+  python: string;
+  javascript: string;
+}
+
+/**
+ * Generated page from auto-generation
+ */
+export interface GeneratedPage {
+  slug: string;
+  title: string;
+  description?: string;
+  group: string;
+  method: HttpMethod;
+  path: string;
+  endpointData: OpenApiEndpointData;
+}
+
+/**
+ * Spec cache entry
+ */
+export interface CachedSpec {
+  api: OpenAPI.Document;
+  version: '2.0' | '3.0' | '3.1';
+  timestamp: number;
+}