te.js 1.3.1 → 2.0.0

package/auto-docs/index.js

@@ -0,0 +1,146 @@
+/**
+ * Auto-docs orchestrator.
+ *
+ * Module layout:
+ * - index.js (this file) — generateDocs(registry, options): orchestration, config, spec write, level-3 dispatch
+ * - openapi/generator.js — build OpenAPI spec from registry (levels 1–2: handler analysis, LLM enhancement)
+ * - openapi/level3.js — level-3 pipeline: reorder tags by importance, generate and write overview page
+ * - analysis/handler-analyzer.js — detect HTTP methods from handler source
+ * - analysis/source-resolver.js — resolve target file and dependencies (for level 2 context)
+ * - llm/ — LLM provider (enhanceEndpointDocs, summarizeTargetGroup, reorderTagsByImportance, generateOverviewPage)
+ * - ui/docs-ui.js — build Scalar docs HTML, registerDocRoutes
+ */
+
+import { writeFile } from 'node:fs/promises';
+import TejLogger from 'tej-logger';
+import { createProvider } from './llm/index.js';
+import { generateOpenAPISpec } from './openapi/generator.js';
+import { runLevel3 } from './openapi/level3.js';
+import targetRegistry from '../server/targets/registry.js';
+
+const logger = new TejLogger('Tejas.AutoDocs');
+
+/**
+ * Validate llm config, warn if no API key, create and return LLM provider.
+ * @param {object} llmConfig - options.llm
+ * @returns {object} LLM provider instance
+ */
+function validateAndCreateLlm(llmConfig) {
+  if (!llmConfig || typeof llmConfig !== 'object') {
+    throw new Error(
+      'Documentation generation requires an LLM. Provide options.llm with { baseURL?, apiKey?, model? }.',
+    );
+  }
+  const hasApiKey = llmConfig.apiKey || process.env.OPENAI_API_KEY;
+  if (!hasApiKey) {
+    logger.warn(
+      'No API key set. Provide options.llm.apiKey or OPENAI_API_KEY. Local providers (e.g. Ollama) may work without a key.',
+    );
+  }
+  return createProvider(llmConfig);
+}
+
+/**
+ * Log start summary when verbose (endpoints count, model, title, output file, building message).
+ * @param {object} options - { info?, outputPath? }
+ * @param {number} targetCount
+ * @param {object} log - logger
+ * @param {boolean} verbose
+ */
+function logStartSummary(options, targetCount, log, verbose) {
+  if (!verbose) return;
+  const { info, outputPath } = options;
+  log.info('OpenAPI documentation generation started.');
+  log.info(`  Endpoints in registry: ${targetCount}`);
+  log.info(`  LLM model: ${options.llm?.model ?? 'default'}`);
+  if (info?.title) log.info(`  API title: ${info.title}`);
+  if (outputPath) log.info(`  Output file: ${outputPath}`);
+  if (targetCount === 0) {
+    log.warn('No endpoints in registry; OpenAPI spec will be minimal.');
+  } else {
+    log.info('Building OpenAPI spec (analyzing handlers, LLM enhancement)...');
+  }
+}
+
+/**
+ * Log result summary when verbose (paths count, tags).
+ * @param {object} spec - OpenAPI spec
+ * @param {object} log - logger
+ * @param {boolean} verbose
+ */
+function logResultSummary(spec, log, verbose) {
+  if (!verbose) return;
+  const pathCount = spec.paths ? Object.keys(spec.paths).length : 0;
+  const tagList = Array.isArray(spec.tags) ? spec.tags.map((t) => t.name).join(', ') : '';
+  log.info(`  Paths: ${pathCount}`);
+  log.info(`  Tags (groups): ${spec.tags?.length ?? 0} [ ${tagList || '—'}]`);
+}
+
+/**
+ * Write spec JSON to outputPath if path is set. Logs when verbose.
+ * @param {object} spec - OpenAPI spec
+ * @param {string|undefined} outputPath
+ * @param {object} log - logger
+ * @param {boolean} verbose
+ */
+async function writeSpecIfNeeded(spec, outputPath, log, verbose) {
+  if (!outputPath || typeof outputPath !== 'string') return;
+  if (verbose) log.info(`Writing spec to ${outputPath}...`);
+  await writeFile(outputPath, JSON.stringify(spec, null, 2), 'utf8');
+  if (verbose) log.info(`OpenAPI spec written to ${outputPath}.`);
+}
+
+/**
+ * Generate OpenAPI 3.0 spec from the target registry using an LLM.
+ *
+ * @param {object} [registry] - Target registry with .targets (default: app registry)
+ * @param {object} [options] - llm (required), info, servers, outputPath, level, dirTargets, overviewPath, verbose
+ * @returns {Promise<object>} OpenAPI 3.0 spec object
+ */
+export async function generateDocs(registry = targetRegistry, options = {}) {
+  const {
+    llm: llmConfig,
+    info,
+    servers,
+    outputPath,
+    level,
+    dirTargets,
+    overviewPath: overviewPathOption,
+    verbose = false,
+  } = options;
+  const targets = registry?.targets ?? [];
+
+  const llm = validateAndCreateLlm(llmConfig);
+  logStartSummary({ ...options, llm: llmConfig }, targets.length, logger, verbose);
+
+  const spec = await generateOpenAPISpec(registry, {
+    llm,
+    info,
+    servers,
+    level,
+    dirTargets,
+    verbose,
+    logger,
+  });
+
+  logResultSummary(spec, logger, verbose);
+  await writeSpecIfNeeded(spec, outputPath, logger, verbose);
+
+  if (level === 3 && llm) {
+    await runLevel3(spec, {
+      outputPath,
+      overviewPath: overviewPathOption,
+      info,
+      verbose,
+      logger,
+    }, llm);
+  }
+
+  if (verbose) logger.info('OpenAPI documentation generation completed.');
+  return spec;
+}
+
+export { generateOpenAPISpec } from './openapi/generator.js';
+export { createProvider } from './llm/index.js';
+export { buildDocsPage } from './ui/docs-ui.js';
+export { analyzeHandler, detectMethods } from './analysis/handler-analyzer.js';

package/auto-docs/llm/index.js

@@ -0,0 +1,6 @@
+/**
+ * LLM provider for auto-documentation.
+ * Single OpenAI-compatible setup: use createProvider(config) with baseURL, apiKey, model.
+ */
+
+export { LLMProvider, createProvider, extractJSON, extractJSONArray } from './provider.js';

package/auto-docs/llm/parse.js

@@ -0,0 +1,88 @@
+/**
+ * Parse JSON from LLM response text (handles markdown code blocks).
+ */
+
+/**
+ * Extract the first JSON object from a string.
+ * @param {string} str - Raw LLM response
+ * @returns {object|null}
+ */
+export function extractJSON(str) {
+  if (!str || typeof str !== 'string') return null;
+  const trimmed = str.trim();
+  const open = trimmed.indexOf('{');
+  if (open === -1) return null;
+  let depth = 0;
+  let end = -1;
+  for (let i = open; i < trimmed.length; i++) {
+    if (trimmed[i] === '{') depth++;
+    else if (trimmed[i] === '}') {
+      depth--;
+      if (depth === 0) {
+        end = i + 1;
+        break;
+      }
+    }
+  }
+  if (end === -1) return null;
+  try {
+    return JSON.parse(trimmed.slice(open, end));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract the first JSON array from a string.
+ * @param {string} str - Raw LLM response
+ * @returns {Array|null}
+ */
+export function extractJSONArray(str) {
+  if (!str || typeof str !== 'string') return null;
+  const trimmed = str.trim();
+  const open = trimmed.indexOf('[');
+  if (open === -1) return null;
+  let depth = 0;
+  let end = -1;
+  for (let i = open; i < trimmed.length; i++) {
+    if (trimmed[i] === '[') depth++;
+    else if (trimmed[i] === ']') {
+      depth--;
+      if (depth === 0) {
+        end = i + 1;
+        break;
+      }
+    }
+  }
+  if (end === -1) return null;
+  try {
+    return JSON.parse(trimmed.slice(open, end));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reconcile LLM-ordered tag names with actual tag objects. Returns tags in desired order;
+ * any tag not in orderedTagNames is appended at the end.
+ * @param {string[]} orderedTagNames - Tag names in desired order (from LLM)
+ * @param {Array<{ name: string, description?: string }>} tags - Current spec.tags
+ * @returns {Array<{ name: string, description?: string }>} Tags reordered
+ */
+export function reconcileOrderedTags(orderedTagNames, tags) {
+  if (!Array.isArray(tags) || !tags.length) return [];
+  if (!Array.isArray(orderedTagNames) || !orderedTagNames.length) return [...tags];
+  const byName = new Map(tags.map((t) => [t.name, t]));
+  const ordered = [];
+  for (const name of orderedTagNames) {
+    const tag = byName.get(name);
+    if (tag) {
+      ordered.push(tag);
+      byName.delete(name);
+    }
+  }
+  for (const [, tag] of byName) {
+    ordered.push(tag);
+  }
+  return ordered;
+}

package/auto-docs/llm/prompts.js

@@ -0,0 +1,222 @@
+/**
+ * Prompt builders for auto-documentation LLM calls.
+ * Each function returns the prompt string; provider calls analyze(prompt).
+ */
+
+import {
+  PROMPT_HANDLER_SLICE,
+  PROMPT_HANDLER_SLICE_WITH_DEPS,
+  PROMPT_DEPENDENCY_SLICE,
+  PROMPT_GROUP_CODE_LIMIT,
+  PROMPT_GROUP_CODE_LIMIT_WITH_DEPS,
+  PROMPT_GROUP_SNIPPET_CHARS,
+} from '../constants.js';
+
+/** Shared rule block for enhance prompts: required vs optional and format. */
+const ENHANCE_RULES = `CRITICAL - Required vs optional: Infer from the code which parameters are required and which are optional. Look for: validation that throws or returns error when missing; checks like !payload.field or !ammo.payload.x; required in schema or JSDoc; or optional/undefined/default handling. For every body property and every query parameter you list, you MUST set "required": true or "required": false explicitly. Do not omit "required".
+
+Respond with ONLY a single JSON object (no markdown, no explanation). Use this shape:`;
+
+/** JSON shape example for single-endpoint enhance. */
+const ENHANCE_RESPONSE_SHAPE = `{
+  "summary": "Short one-line description",
+  "description": "Optional longer description",
+  "request": {
+    "body": {
+      "fieldName": { "type": "string", "description": "...", "required": true }
+    },
+    "query": {
+      "paramName": { "type": "string", "description": "...", "required": false }
+    }
+  },
+  "response": { "200": { "description": "Success" }, "201": { "description": "Created" } }
+}
+- For every field in request.body and request.query set "required": true or "required": false based on code context.
+- Include "format" when relevant (e.g. "email", "date-time", "binary").
+- Omit "request" or "response" if not applicable. Keep summary under 80 characters.`;
+
+/** JSON shape example for per-method enhance. */
+const PER_METHOD_RESPONSE_SHAPE = `{
+  "get": { "summary": "...", "description": "...", "response": { "200": { "description": "..." } } },
+  "put": { "summary": "...", "description": "...", "request": { "body": { "name": { "type": "string", "required": true }, "email": { "type": "string", "format": "email", "required": true } } }, "response": { "200": { "description": "..." } } },
+  "delete": { "summary": "...", "description": "...", "response": { "204": { "description": "..." } } }
+}`;
+
+/**
+ * Build handler snippet and related-files section for endpoint prompts. Single place for limits and formatting.
+ * @param {object} endpointInfo - { handlerSource?, dependencySources? }
+ * @returns {{ handlerSnippet: string, relatedSection: string }}
+ */
+export function buildEndpointPromptContext(endpointInfo) {
+  const { handlerSource = '', dependencySources = '' } = endpointInfo;
+  const handlerLimit = dependencySources ? PROMPT_HANDLER_SLICE_WITH_DEPS : PROMPT_HANDLER_SLICE;
+  const handlerSnippet = (handlerSource || '').slice(0, handlerLimit);
+  const relatedSection = dependencySources
+    ? `
+
+Related source files (target and dependencies):
+\`\`\`javascript
+${dependencySources.slice(0, PROMPT_DEPENDENCY_SLICE)}
+\`\`\`
+`
+    : '';
+  return { handlerSnippet, relatedSection };
+}
+
+/**
+ * Build prompt for summarizing a target group (tag name + description).
+ * @param {string} groupId
+ * @param {Array<object>} endpointsInfo - { path, methods, summary?, description?, handlerSource?, dependencySources? }
+ * @param {string} [dependencySources]
+ * @returns {string}
+ */
+export function buildSummarizeGroupPrompt(groupId, endpointsInfo, dependencySources = '') {
+  if (!endpointsInfo?.length) return '';
+  const list = endpointsInfo
+    .map((e) => `- ${e.path} [${(e.methods || []).join(', ')}]: ${e.summary || e.description || '—'}`)
+    .join('\n');
+  const codeSnippets = endpointsInfo
+    .filter((e) => e.handlerSource)
+    .map((e) => `Path ${e.path}:\n${(e.handlerSource || '').slice(0, PROMPT_GROUP_SNIPPET_CHARS)}`)
+    .join('\n\n');
+  const codeLimit = dependencySources ? PROMPT_GROUP_CODE_LIMIT_WITH_DEPS : PROMPT_GROUP_CODE_LIMIT;
+  const { relatedSection } = buildEndpointPromptContext({ dependencySources });
+  return `You are an API documentation assistant. A single source file (group) exposes these endpoints:
+
+Group id: ${groupId}
+
+Endpoints:
+${list}
+
+Handler code (excerpts):
+\`\`\`javascript
+${codeSnippets.slice(0, codeLimit)}
+\`\`\`
+${relatedSection}
+
+Write a SHORT paragraph (2–4 sentences) describing what this group of endpoints does as a whole. Focus on the domain and purpose, not the HTTP details. Respond with ONLY a single JSON object:
+{ "name": "Human-readable group name", "description": "Your paragraph here." }
+Use "name" as a short label (e.g. "Users", "Health & routes"); keep description under 300 characters.`;
+}
+
+/**
+ * Build prompt for enhancing a single endpoint (OpenAPI-style metadata).
+ * @param {object} endpointInfo - { path, methods, metadata?, handlerSource?, dependencySources? }
+ * @returns {string}
+ */
+export function buildEnhanceEndpointPrompt(endpointInfo) {
+  const { path, methods = [], metadata = {} } = endpointInfo;
+  const { handlerSnippet, relatedSection } = buildEndpointPromptContext(endpointInfo);
+  const existing = Object.keys(metadata).length ? `Existing metadata: ${JSON.stringify(metadata)}\n` : '';
+  return `You are an API documentation assistant. Given an HTTP endpoint and its source code, suggest OpenAPI-style metadata.
+
+Endpoint path: ${path}
+HTTP methods: ${methods.join(', ')}
+${existing}Handler source (for context):
+\`\`\`javascript
+${handlerSnippet}
+\`\`\`
+${relatedSection}
+
+${ENHANCE_RULES}
+${ENHANCE_RESPONSE_SHAPE}`;
+}
+
+/**
+ * Build prompt for method-specific endpoint metadata (per-method summary, request, response).
+ * @param {object} endpointInfo - { path, methods, metadata?, handlerSource?, dependencySources? }
+ * @returns {string}
+ */
+export function buildEnhanceEndpointPerMethodPrompt(endpointInfo) {
+  const { path, methods = [], metadata = {} } = endpointInfo;
+  const { handlerSnippet, relatedSection } = buildEndpointPromptContext(endpointInfo);
+  const methodsLower = methods.map((m) => m.toLowerCase());
+  const existing = Object.keys(metadata).length ? `Existing metadata: ${JSON.stringify(metadata)}\n` : '';
+  return `You are an API documentation assistant. This endpoint supports multiple HTTP methods. Provide METHOD-SPECIFIC metadata so each method is documented accurately.
+
+Endpoint path: ${path}
+HTTP methods: ${methods.join(', ')}
+
+${existing}Handler source (for context):
+\`\`\`javascript
+${handlerSnippet}
+\`\`\`
+${relatedSection}
+
+RULES:
+- Return ONE JSON object keyed by lowercase method name: "get", "put", "post", "delete", "patch", "head", "options".
+- Include a key for EACH of: ${methodsLower.map((m) => `"${m}"`).join(', ')}.
+- For each method provide: "summary" (one line, method-specific, e.g. "Get user by id" for GET, "Update user" for PUT), optional "description", optional "request" (only for methods that accept a body: put, post, patch; omit for get, delete, head, options), and "response" (ONLY the status codes that THIS method returns — e.g. GET returns 200, DELETE returns 204; do not list 204 under PUT or 200 under DELETE unless the handler returns it for that branch).
+- For request.body, set "required": true or "required": false on each field based on code. Include "format" when relevant (e.g. "email").
+- Each method's response object must only list the HTTP status codes that that specific method returns.
+
+Respond with ONLY a single JSON object (no markdown, no explanation). Shape:
+${PER_METHOD_RESPONSE_SHAPE}`;
+}
+
+/**
+ * Build prompt for reordering tag groups by importance.
+ * @param {object} spec - OpenAPI 3 spec with spec.tags
+ * @returns {string}
+ */
+export function buildReorderTagsPrompt(spec) {
+  const tags = spec?.tags ?? [];
+  if (!tags.length) return '';
+  const list = tags
+    .map((t) => `- "${t.name}"${t.description ? `: ${t.description.slice(0, 200)}` : ''}`)
+    .join('\n');
+  return `You are an API documentation assistant. This API has the following tag groups (categories):
+
+${list}
+
+Reorder these groups by importance for a reader exploring the API. Put the most important or central groups first (e.g. main resources, auth), and utility or secondary groups last (e.g. health, admin).
+
+Respond with ONLY a JSON array of the tag names in the desired order. Example: ["Users", "Auth", "Health & routes"]
+Do not include any other text or markdown.`;
+}
+
+/**
+ * Build prompt for generating the API overview Markdown page.
+ * @param {object} spec - OpenAPI 3 spec with info, tags, paths
+ * @param {object} [options] - { title?, version?, description? }
+ * @returns {string}
+ */
+export function buildOverviewPrompt(spec, options = {}) {
+  const info = spec?.info ?? {};
+  const title = options.title ?? info.title ?? 'API';
+  const version = options.version ?? info.version ?? '1.0.0';
+  const description = options.description ?? info.description ?? '';
+  const tags = spec?.tags ?? [];
+  const paths = spec?.paths ?? {};
+  const tagList = tags.map((t) => `- **${t.name}**: ${t.description || '—'}`).join('\n');
+  const pathList = Object.entries(paths)
+    .slice(0, 50)
+    .map(([p, ops]) => {
+      const methods = Object.keys(ops)
+        .filter((k) => ['get', 'post', 'put', 'delete', 'patch', 'head', 'options'].includes(k))
+        .join(', ')
+        .toUpperCase();
+      return `- ${p} [${methods}]`;
+    })
+    .join('\n');
+
+  return `You are an API documentation assistant. Generate a single comprehensive Markdown document for this API.
+
+API title: ${title}
+Version: ${version}
+${description ? `Description: ${description.slice(0, 500)}\n` : ''}
+
+Tag groups (API areas):
+${tagList}
+
+Sample of endpoints (path and methods):
+${pathList}
+
+Write a Markdown document that includes:
+1. A short **project summary** (what this API does).
+2. **APIs available**: a high-level list of the tag groups and what they cover.
+3. **Key endpoints** or "Getting started": suggest a few important paths (e.g. health check, main resources).
+4. Any other brief sections that fit (e.g. Authentication, Rate limits) only if clearly inferable from the spec; otherwise omit.
+
+Use clear headings (##, ###). Keep the document concise (under 2 pages). Output ONLY the Markdown, no surrounding explanation or code fence.`;
+}

package/auto-docs/llm/provider.js

@@ -0,0 +1,187 @@
+/**
+ * LLM provider for auto-documentation: single OpenAI-compatible implementation.
+ * Works with OpenAI, OpenRouter, Ollama (OpenAI-compatible endpoint), Azure, etc.
+ * Uses fetch() only — no provider-specific npm dependencies.
+ */
+
+import { extractJSON, extractJSONArray, reconcileOrderedTags } from './parse.js';
+import {
+  buildSummarizeGroupPrompt,
+  buildEnhanceEndpointPrompt,
+  buildEnhanceEndpointPerMethodPrompt,
+  buildReorderTagsPrompt,
+  buildOverviewPrompt,
+} from './prompts.js';
+
+const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
+const DEFAULT_MODEL = 'gpt-4o-mini';
+
+/**
+ * OpenAI-compatible LLM provider. POSTs to {baseURL}/chat/completions.
+ */
+class LLMProvider {
+  constructor(options = {}) {
+    this.baseURL = (options.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, '');
+    this.model = options.model ?? DEFAULT_MODEL;
+    this.apiKey = options.apiKey ?? process.env.OPENAI_API_KEY;
+    this.options = options;
+  }
+
+  /**
+   * Send a prompt to the LLM and return the raw text response.
+   * @param {string} prompt
+   * @returns {Promise<string>}
+   */
+  async analyze(prompt) {
+    const url = `${this.baseURL}/chat/completions`;
+    const headers = {
+      'Content-Type': 'application/json',
+      ...(this.apiKey && { Authorization: `Bearer ${this.apiKey}` }),
+    };
+    const body = {
+      model: this.model,
+      messages: [{ role: 'user', content: prompt }],
+    };
+
+    const res = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`LLM request failed (${res.status}): ${text.slice(0, 300)}`);
+    }
+
+    const data = await res.json();
+    const content = data.choices?.[0]?.message?.content ?? '';
+    const text = typeof content === 'string' ? content : JSON.stringify(content);
+    const rawUsage = data.usage;
+    const usage = {
+      prompt_tokens: rawUsage?.prompt_tokens ?? 0,
+      completion_tokens: rawUsage?.completion_tokens ?? 0,
+      total_tokens: rawUsage?.total_tokens ?? (rawUsage?.prompt_tokens ?? 0) + (rawUsage?.completion_tokens ?? 0),
+    };
+    return { content: text, usage };
+  }
+
+  /**
+   * Summarize what a target file (group) does from its endpoints and handler context.
+   * @param {string} groupId - Group id (e.g. target file path without .target.js)
+   * @param {Array<object>} endpointsInfo - List of { path, methods, summary?, description?, handlerSource?, dependencySources? }
+   * @param {string} [dependencySources] - Optional full context (target + dependencies) for Level 3
+   * @returns {Promise<{ name: string, description: string }>} Tag name and description for OpenAPI
+   */
+  async summarizeTargetGroup(groupId, endpointsInfo, dependencySources = '') {
+    if (!endpointsInfo?.length) {
+      return { name: groupId, description: '', _usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 } };
+    }
+    const prompt = buildSummarizeGroupPrompt(groupId, endpointsInfo, dependencySources);
+    const { content: raw, usage } = await this.analyze(prompt);
+    const json = extractJSON(raw);
+    if (!json)
+      return {
+        name: groupId.split('/').pop() || groupId,
+        description: '',
+        _usage: usage,
+      };
+    return {
+      name: json.name || groupId.split('/').pop() || groupId,
+      description: (json.description || '').trim(),
+      _usage: usage,
+    };
+  }
+
+  /**
+   * Build enhanced OpenAPI-style metadata for an endpoint from handler info.
+   * @param {object} endpointInfo - { path, methods, metadata?, handlerSource?, dependencySources? }
+   * @returns {Promise<object>} Enhanced metadata (summary, description, request?, response?)
+   */
+  async enhanceEndpointDocs(endpointInfo) {
+    const { path } = endpointInfo;
+    const prompt = buildEnhanceEndpointPrompt(endpointInfo);
+    const { content: raw, usage } = await this.analyze(prompt);
+    const json = extractJSON(raw);
+    if (!json) return { summary: path, description: '', _usage: usage };
+    return {
+      summary: json.summary || path,
+      description: json.description || '',
+      ...(json.request && { request: json.request }),
+      ...(json.response && { response: json.response }),
+      _usage: usage,
+    };
+  }
+
+  /**
+   * Build method-specific OpenAPI metadata so each HTTP method gets its own summary, description, request, and response.
+   * Returns an object keyed by lowercase method (get, put, post, delete, patch, head, options). If the LLM
+   * returns a flat shape or omits methods, the caller should fall back to shared metadata.
+   *
+   * @param {object} endpointInfo - { path, methods, metadata?, handlerSource?, dependencySources? }
+   * @returns {Promise<object>} Method-keyed metadata, e.g. { get: { summary, description?, response }, put: { summary, request?, response }, ... }
+   */
+  async enhanceEndpointDocsPerMethod(endpointInfo) {
+    const prompt = buildEnhanceEndpointPerMethodPrompt(endpointInfo);
+    const { content: raw, usage } = await this.analyze(prompt);
+    const json = extractJSON(raw);
+    if (!json || typeof json !== 'object') return { _usage: usage, _fallback: true };
+    return { ...json, _usage: usage };
+  }
+
+  /**
+   * Return tag names ordered by importance (most important first) for use in OpenAPI spec.tags.
+   * @param {object} spec - OpenAPI 3 spec with spec.tags (array of { name, description? })
+   * @returns {Promise<{ orderedTagNames: string[], _usage?: object }>}
+   */
+  async reorderTagsByImportance(spec) {
+    const tags = spec?.tags ?? [];
+    if (!tags.length) return { orderedTagNames: [], _usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 } };
+    const prompt = buildReorderTagsPrompt(spec);
+    const { content: raw, usage } = await this.analyze(prompt);
+    const parsed = extractJSON(raw) ?? extractJSONArray(raw);
+    const orderedTagNames = Array.isArray(parsed)
+      ? parsed.filter((n) => typeof n === 'string').map((n) => String(n).trim()).filter(Boolean)
+      : tags.map((t) => t.name);
+    const orderedTags = reconcileOrderedTags(orderedTagNames, tags);
+    return {
+      orderedTagNames: orderedTags.map((t) => t.name),
+      _usage: usage,
+      _orderedTags: orderedTags,
+    };
+  }
+
+  /**
+   * Generate a comprehensive project/API overview page in Markdown.
+   * @param {object} spec - OpenAPI 3 spec (after reorder) with info, tags, paths
+   * @param {object} [options] - { title?, version?, description? } (defaults from spec.info)
+   * @returns {Promise<{ markdown: string, _usage?: object }>}
+   */
+  async generateOverviewPage(spec, options = {}) {
+    const prompt = buildOverviewPrompt(spec, options);
+    const { content: raw, usage } = await this.analyze(prompt);
+    const markdown = typeof raw === 'string' ? raw.trim() : '';
+    return { markdown, _usage: usage };
+  }
+}
+
+/**
+ * Create an LLM provider from config.
+ * Single OpenAI-compatible setup: works with OpenAI, OpenRouter, Ollama (compat), Azure, etc.
+ *
+ * @param {object} config - { baseURL?, apiKey?, model? }
+ *   - baseURL: e.g. 'https://api.openai.com/v1' | 'https://openrouter.ai/api/v1' | 'http://localhost:11434/v1'
+ *   - apiKey: optional for local (e.g. Ollama); use OPENAI_API_KEY or OPENROUTER_API_KEY
+ *   - model: e.g. 'gpt-4o-mini' | 'openai/gpt-4o-mini' (OpenRouter)
+ * @returns {LLMProvider}
+ */
+function createProvider(config) {
+  if (!config || typeof config !== 'object') {
+    return new LLMProvider({});
+  }
+  return new LLMProvider(config);
+}
+
+export { LLMProvider, createProvider };
+export { extractJSON, extractJSONArray } from './parse.js';
+export default LLMProvider;