api-spec-cli 0.0.1 → 0.0.3

package/src/commands/load.js

@@ -0,0 +1,230 @@
+import { readFileSync, existsSync } from "fs";
+import { resolve } from "path";
+import YAML from "yaml";
+import { saveSpec } from "../store.js";
+import { out, err } from "../output.js";
+
+const INTROSPECTION_QUERY = `{
+  __schema {
+    queryType { name }
+    mutationType { name }
+    subscriptionType { name }
+    types {
+      name
+      kind
+      description
+      fields(includeDeprecated: true) {
+        name
+        description
+        isDeprecated
+        deprecationReason
+        args {
+          name
+          description
+          type { ...TypeRef }
+          defaultValue
+        }
+        type { ...TypeRef }
+      }
+      inputFields {
+        name
+        description
+        type { ...TypeRef }
+        defaultValue
+      }
+      enumValues(includeDeprecated: true) {
+        name
+        description
+        isDeprecated
+        deprecationReason
+      }
+    }
+  }
+}
+
+fragment TypeRef on __Type {
+  kind
+  name
+  ofType {
+    kind
+    name
+    ofType {
+      kind
+      name
+      ofType {
+        kind
+        name
+      }
+    }
+  }
+}`;
+
+export async function loadSpec(args) {
+  const source = args[0];
+  if (!source) throw new Error("Usage: spec load <file-or-url>");
+
+  // Detect if it's a URL or file
+  const isUrl = source.startsWith("http://") || source.startsWith("https://");
+
+  let spec;
+
+  if (isUrl) {
+    spec = await loadFromUrl(source);
+  } else {
+    spec = loadFromFile(source);
+  }
+
+  saveSpec(spec);
+  out({
+    ok: true,
+    type: spec.type,
+    title: spec.title || null,
+    operationCount: countOperations(spec),
+    source: source,
+  });
+}
+
+async function loadFromUrl(url) {
+  // Try GraphQL introspection first if URL doesn't end with known extensions
+  const lowerUrl = url.toLowerCase();
+  const isLikelyFile =
+    lowerUrl.endsWith(".json") ||
+    lowerUrl.endsWith(".yaml") ||
+    lowerUrl.endsWith(".yml");
+
+  if (!isLikelyFile) {
+    // Try GraphQL introspection
+    try {
+      return await loadGraphQL(url);
+    } catch (e) {
+      // Fall through to OpenAPI
+    }
+  }
+
+  // Fetch as OpenAPI
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+  const text = await res.text();
+  return parseOpenAPI(text, url);
+}
+
+function loadFromFile(path) {
+  const abs = resolve(path);
+  if (!existsSync(abs)) throw new Error(`File not found: ${abs}`);
+  const text = readFileSync(abs, "utf-8");
+  return parseOpenAPI(text, path);
+}
+
+async function loadGraphQL(url) {
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ query: INTROSPECTION_QUERY }),
+  });
+
+  if (!res.ok) throw new Error(`GraphQL introspection failed: HTTP ${res.status}`);
+
+  const json = await res.json();
+  if (json.errors && !json.data) {
+    throw new Error(`GraphQL error: ${json.errors[0].message}`);
+  }
+
+  const schema = json.data.__schema;
+
+  // Extract operations from query/mutation/subscription types
+  const operations = [];
+  const typeMap = {};
+  for (const t of schema.types) {
+    typeMap[t.name] = t;
+  }
+
+  for (const [kind, rootType] of [
+    ["query", schema.queryType],
+    ["mutation", schema.mutationType],
+    ["subscription", schema.subscriptionType],
+  ]) {
+    if (!rootType) continue;
+    const type = typeMap[rootType.name];
+    if (!type || !type.fields) continue;
+    for (const field of type.fields) {
+      operations.push({
+        kind,
+        name: field.name,
+        description: field.description,
+        args: field.args,
+        returnType: flattenType(field.type),
+        isDeprecated: field.isDeprecated,
+        deprecationReason: field.deprecationReason,
+      });
+    }
+  }
+
+  return {
+    type: "graphql",
+    title: null,
+    endpoint: url,
+    operations,
+    types: schema.types.filter((t) => !t.name.startsWith("__")),
+    raw: schema,
+  };
+}
+
+function parseOpenAPI(text, source) {
+  let doc;
+  try {
+    doc = JSON.parse(text);
+  } catch {
+    doc = YAML.parse(text);
+  }
+
+  // Detect OpenAPI vs Swagger
+  const version = doc.openapi || doc.swagger;
+  if (!version) throw new Error("Not a valid OpenAPI/Swagger spec");
+
+  const operations = [];
+
+  for (const [path, methods] of Object.entries(doc.paths || {})) {
+    for (const [method, op] of Object.entries(methods)) {
+      if (method.startsWith("x-") || method === "parameters") continue;
+      operations.push({
+        id: op.operationId || `${method.toUpperCase()} ${path}`,
+        method: method.toUpperCase(),
+        path,
+        summary: op.summary || null,
+        description: op.description || null,
+        parameters: op.parameters || [],
+        requestBody: op.requestBody || null,
+        responses: op.responses || {},
+        tags: op.tags || [],
+        deprecated: op.deprecated || false,
+      });
+    }
+  }
+
+  return {
+    type: "openapi",
+    version,
+    title: doc.info?.title || null,
+    description: doc.info?.description || null,
+    servers: doc.servers || (doc.host ? [{ url: `${doc.schemes?.[0] || "https"}://${doc.host}${doc.basePath || ""}` }] : []),
+    operations,
+    components: doc.components || doc.definitions || {},
+    raw: doc,
+  };
+}
+
+function flattenType(t) {
+  if (!t) return null;
+  if (t.name) return t.kind === "NON_NULL" ? `${t.name}!` : t.name;
+  if (t.ofType) {
+    const inner = flattenType(t.ofType);
+    if (t.kind === "LIST") return `[${inner}]`;
+    if (t.kind === "NON_NULL") return `${inner}!`;
+    return inner;
+  }
+  return t.kind;
+}
+
+function countOperations(spec) {
+  return spec.operations?.length || 0;
+}

package/src/commands/show.js

@@ -0,0 +1,176 @@
+import { getSpec } from "../store.js";
+import { out } from "../output.js";
+
+export async function showOperation(args) {
+  const target = args[0];
+  if (!target) throw new Error("Usage: spec show <operationId-or-path>");
+
+  const spec = getSpec();
+  if (!spec) throw new Error("No spec loaded. Run: spec load <file-or-url>");
+
+  if (spec.type === "openapi") {
+    showOpenAPI(spec, target);
+  } else {
+    showGraphQL(spec, target);
+  }
+}
+
+function showOpenAPI(spec, target) {
+  const lower = target.toLowerCase();
+
+  // Match by operationId, path, or "METHOD path"
+  const op = spec.operations.find((o) => {
+    return (
+      o.id.toLowerCase() === lower ||
+      o.path.toLowerCase() === lower ||
+      `${o.method.toLowerCase()} ${o.path.toLowerCase()}` === lower
+    );
+  });
+
+  if (!op) {
+    throw new Error(`Operation not found: ${target}. Run 'spec list' to see available operations.`);
+  }
+
+  const root = spec.raw || spec.components;
+
+  // Resolve $ref in parameters, requestBody, and responses
+  const resolved = {
+    ...op,
+    parameters: op.parameters.map((p) => resolveRef(p, root)),
+    requestBody: op.requestBody ? resolveRequestBody(op.requestBody, root) : null,
+    responses: resolveResponses(op.responses, root),
+  };
+
+  out(resolved);
+}
+
+function showGraphQL(spec, target) {
+  const lower = target.toLowerCase();
+
+  const op = spec.operations.find((o) => o.name.toLowerCase() === lower);
+
+  if (!op) {
+    throw new Error(`Operation not found: ${target}. Run 'spec list' to see available operations.`);
+  }
+
+  // Also find related types
+  const relatedTypes = findRelatedTypes(op, spec.types);
+
+  out({
+    ...op,
+    relatedTypes,
+  });
+}
+
+function resolveRef(obj, root) {
+  if (!obj || typeof obj !== "object") return obj;
+  if (obj.$ref) {
+    const path = obj.$ref.replace("#/", "").split("/");
+    let resolved = root;
+    for (const p of path) {
+      resolved = resolved?.[p];
+    }
+    return resolved || obj;
+  }
+  return obj;
+}
+
+function resolveRequestBody(body, root) {
+  if (!body) return null;
+  const resolved = resolveRef(body, root);
+  if (resolved?.content) {
+    const result = { ...resolved, content: {} };
+    for (const [mediaType, value] of Object.entries(resolved.content)) {
+      result.content[mediaType] = {
+        ...value,
+        schema: resolveSchema(value.schema, root),
+      };
+    }
+    return result;
+  }
+  return resolved;
+}
+
+function resolveResponses(responses, root) {
+  if (!responses) return responses;
+  const result = {};
+  for (const [code, resp] of Object.entries(responses)) {
+    const resolved = resolveRef(resp, root);
+    if (resolved?.content) {
+      result[code] = {
+        ...resolved,
+        content: {},
+      };
+      for (const [mediaType, value] of Object.entries(resolved.content)) {
+        result[code].content[mediaType] = {
+          ...value,
+          schema: resolveSchema(value.schema, root),
+        };
+      }
+    } else {
+      result[code] = resolved;
+    }
+  }
+  return result;
+}
+
+function resolveSchema(schema, root, depth = 0) {
+  if (!schema || depth > 5) return schema;
+  if (schema.$ref) {
+    return resolveRef(schema, root);
+  }
+  if (schema.properties) {
+    const result = { ...schema, properties: {} };
+    for (const [key, val] of Object.entries(schema.properties)) {
+      result.properties[key] = resolveSchema(val, root, depth + 1);
+    }
+    return result;
+  }
+  if (schema.items) {
+    return { ...schema, items: resolveSchema(schema.items, root, depth + 1) };
+  }
+  return schema;
+}
+
+function findRelatedTypes(op, types) {
+  const names = new Set();
+
+  // Collect type names from args and return type
+  function extractTypeNames(typeStr) {
+    if (!typeStr) return;
+    const cleaned = typeStr.replace(/[[\]!]/g, "");
+    if (cleaned) names.add(cleaned);
+  }
+
+  extractTypeNames(op.returnType);
+  for (const arg of op.args || []) {
+    extractTypeNames(flattenType(arg.type));
+  }
+
+  // Filter out built-in scalar types
+  const scalars = new Set(["String", "Int", "Float", "Boolean", "ID"]);
+  return types
+    .filter((t) => names.has(t.name) && !scalars.has(t.name))
+    .map((t) => ({
+      name: t.name,
+      kind: t.kind,
+      fields: t.fields?.map((f) => ({
+        name: f.name,
+        type: flattenType(f.type),
+        description: f.description,
+      })),
+      enumValues: t.enumValues,
+    }));
+}
+
+function flattenType(t) {
+  if (!t) return null;
+  if (t.name) return t.kind === "NON_NULL" ? `${t.name}!` : t.name;
+  if (t.ofType) {
+    const inner = flattenType(t.ofType);
+    if (t.kind === "LIST") return `[${inner}]`;
+    if (t.kind === "NON_NULL") return `${inner}!`;
+    return inner;
+  }
+  return t.kind;
+}

package/src/commands/validate.js

@@ -0,0 +1,269 @@
+import { readFileSync, existsSync } from "fs";
+import { resolve } from "path";
+import YAML from "yaml";
+import { out } from "../output.js";
+import { parseArgs } from "../args.js";
+
+export async function validateSpec(args) {
+  const { positional } = parseArgs(args);
+  const source = positional[0];
+  if (!source) throw new Error("Usage: spec validate <file-or-url>");
+
+  const isUrl = source.startsWith("http://") || source.startsWith("https://");
+
+  let text;
+  if (isUrl) {
+    const res = await fetch(source);
+    if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+    text = await res.text();
+  } else {
+    const abs = resolve(source);
+    if (!existsSync(abs)) throw new Error(`File not found: ${abs}`);
+    text = readFileSync(abs, "utf-8");
+  }
+
+  let doc;
+  try {
+    doc = JSON.parse(text);
+  } catch {
+    try {
+      doc = YAML.parse(text);
+    } catch (e) {
+      out({ valid: false, errors: [{ path: "", message: `Parse error: ${e.message}` }] });
+      return;
+    }
+  }
+
+  const errors = [];
+  const warnings = [];
+
+  // Detect spec version
+  const version = doc.openapi || doc.swagger;
+  if (!version) {
+    errors.push({ path: "", message: "Missing 'openapi' or 'swagger' version field" });
+    out({ valid: false, errors, warnings });
+    return;
+  }
+
+  const isV3 = version.startsWith("3");
+
+  // info object
+  validateInfo(doc, errors, warnings);
+
+  // paths
+  validatePaths(doc, errors, warnings, isV3);
+
+  // components / definitions
+  if (isV3) {
+    validateComponentsV3(doc, errors, warnings);
+  } else {
+    validateDefinitionsV2(doc, errors, warnings);
+  }
+
+  // servers (v3) or host (v2)
+  validateServers(doc, errors, warnings, isV3);
+
+  // Check for broken $ref
+  validateRefs(doc, doc, "", errors);
+
+  out({
+    valid: errors.length === 0,
+    version,
+    title: doc.info?.title || null,
+    operationCount: countOperations(doc),
+    errors,
+    warnings,
+  });
+}
+
+function validateInfo(doc, errors, warnings) {
+  if (!doc.info) {
+    errors.push({ path: "info", message: "Missing required 'info' object" });
+    return;
+  }
+  if (!doc.info.title) {
+    errors.push({ path: "info.title", message: "Missing required 'info.title'" });
+  }
+  if (!doc.info.version) {
+    errors.push({ path: "info.version", message: "Missing required 'info.version'" });
+  }
+  if (!doc.info.description) {
+    warnings.push({ path: "info.description", message: "Missing 'info.description' (recommended)" });
+  }
+}
+
+function validatePaths(doc, errors, warnings, isV3) {
+  if (!doc.paths) {
+    errors.push({ path: "paths", message: "Missing required 'paths' object" });
+    return;
+  }
+
+  if (Object.keys(doc.paths).length === 0) {
+    warnings.push({ path: "paths", message: "No paths defined" });
+    return;
+  }
+
+  const METHODS = new Set(["get", "post", "put", "patch", "delete", "options", "head", "trace"]);
+  const operationIds = new Set();
+
+  for (const [path, methods] of Object.entries(doc.paths)) {
+    // Path must start with /
+    if (!path.startsWith("/")) {
+      errors.push({ path: `paths.${path}`, message: `Path must start with '/'` });
+    }
+
+    // Check for unbalanced path params
+    const pathParams = (path.match(/\{([^}]+)\}/g) || []).map((p) => p.slice(1, -1));
+
+    if (typeof methods !== "object" || methods === null) continue;
+
+    for (const [method, op] of Object.entries(methods)) {
+      if (method.startsWith("x-") || method === "parameters" || method === "$ref") continue;
+
+      if (!METHODS.has(method)) {
+        warnings.push({ path: `paths.${path}.${method}`, message: `Unknown HTTP method '${method}'` });
+        continue;
+      }
+
+      if (typeof op !== "object" || op === null) continue;
+
+      const opPath = `paths.${path}.${method.toUpperCase()}`;
+
+      // operationId uniqueness
+      if (op.operationId) {
+        if (operationIds.has(op.operationId)) {
+          errors.push({ path: opPath, message: `Duplicate operationId '${op.operationId}'` });
+        }
+        operationIds.add(op.operationId);
+      } else {
+        warnings.push({ path: opPath, message: "Missing operationId (recommended for agent use)" });
+      }
+
+      // Responses required
+      if (!op.responses || Object.keys(op.responses).length === 0) {
+        errors.push({ path: opPath, message: "Missing or empty 'responses'" });
+      }
+
+      // Check path params are declared
+      const declaredParams = new Set(
+        (op.parameters || [])
+          .filter((p) => (p.in || p.$ref) && (p.in === "path" || !p.in))
+          .map((p) => p.name)
+      );
+
+      // Also include path-level parameters
+      const pathLevelParams = (methods.parameters || [])
+        .filter((p) => p.in === "path")
+        .map((p) => p.name);
+
+      for (const n of pathLevelParams) declaredParams.add(n);
+
+      for (const param of pathParams) {
+        if (!declaredParams.has(param)) {
+          // Only warn — the param might be declared via $ref
+          warnings.push({ path: opPath, message: `Path parameter '{${param}}' may not be declared in parameters` });
+        }
+      }
+
+      // Request body on GET/DELETE/HEAD
+      if (isV3 && op.requestBody && ["get", "delete", "head"].includes(method)) {
+        warnings.push({ path: opPath, message: `requestBody on ${method.toUpperCase()} is unusual` });
+      }
+    }
+  }
+}
+
+function validateComponentsV3(doc, errors, warnings) {
+  if (!doc.components) return;
+
+  // Check schemas have valid types
+  if (doc.components.schemas) {
+    for (const [name, schema] of Object.entries(doc.components.schemas)) {
+      validateSchema(schema, `components.schemas.${name}`, errors, warnings);
+    }
+  }
+}
+
+function validateDefinitionsV2(doc, errors, warnings) {
+  if (!doc.definitions) return;
+
+  for (const [name, schema] of Object.entries(doc.definitions)) {
+    validateSchema(schema, `definitions.${name}`, errors, warnings);
+  }
+}
+
+function validateSchema(schema, path, errors, warnings) {
+  if (!schema || typeof schema !== "object") return;
+  if (schema.$ref) return; // reference, skip
+
+  const VALID_TYPES = new Set(["string", "number", "integer", "boolean", "array", "object", "null"]);
+
+  if (schema.type && !VALID_TYPES.has(schema.type)) {
+    errors.push({ path, message: `Invalid type '${schema.type}'` });
+  }
+
+  if (schema.type === "array" && !schema.items) {
+    errors.push({ path, message: "Array type must have 'items'" });
+  }
+
+  // Recurse into properties
+  if (schema.properties) {
+    for (const [key, val] of Object.entries(schema.properties)) {
+      validateSchema(val, `${path}.properties.${key}`, errors, warnings);
+    }
+  }
+  if (schema.items) {
+    validateSchema(schema.items, `${path}.items`, errors, warnings);
+  }
+}
+
+function validateServers(doc, errors, warnings, isV3) {
+  if (isV3) {
+    if (!doc.servers || doc.servers.length === 0) {
+      warnings.push({ path: "servers", message: "No servers defined — agent will need baseUrl configured" });
+    }
+  } else {
+    if (!doc.host) {
+      warnings.push({ path: "host", message: "No host defined — agent will need baseUrl configured" });
+    }
+  }
+}
+
+function validateRefs(doc, root, path, errors) {
+  if (!doc || typeof doc !== "object") return;
+
+  if (doc.$ref && typeof doc.$ref === "string") {
+    if (doc.$ref.startsWith("#/")) {
+      const parts = doc.$ref.slice(2).split("/");
+      let target = root;
+      for (const p of parts) {
+        target = target?.[p];
+      }
+      if (target === undefined) {
+        errors.push({ path: path || doc.$ref, message: `Broken $ref: '${doc.$ref}'` });
+      }
+    }
+    return; // Don't recurse into $ref
+  }
+
+  if (Array.isArray(doc)) {
+    for (let i = 0; i < doc.length; i++) {
+      validateRefs(doc[i], root, `${path}[${i}]`, errors);
+    }
+  } else {
+    for (const [key, val] of Object.entries(doc)) {
+      if (key === "raw") continue; // skip stored raw data
+      validateRefs(val, root, path ? `${path}.${key}` : key, errors);
+    }
+  }
+}
+
+function countOperations(doc) {
+  let count = 0;
+  for (const methods of Object.values(doc.paths || {})) {
+    for (const method of Object.keys(methods)) {
+      if (!method.startsWith("x-") && method !== "parameters" && method !== "$ref") count++;
+    }
+  }
+  return count;
+}