te.js 2.1.0 → 2.1.1

package/auto-docs/docs-llm/provider.js

@@ -1,132 +1,132 @@
-/**
- * LLM provider for auto-documentation: extends shared lib/llm client with doc-specific methods.
- * Single OpenAI-compatible implementation; works with OpenAI, OpenRouter, Ollama, Azure, etc.
- */
-
-import { LLMProvider as BaseLLMProvider, extractJSON, extractJSONArray, reconcileOrderedTags } from '../../lib/llm/index.js';
-import {
-  buildSummarizeGroupPrompt,
-  buildEnhanceEndpointPrompt,
-  buildEnhanceEndpointPerMethodPrompt,
-  buildReorderTagsPrompt,
-  buildOverviewPrompt,
-} from './prompts.js';
-
-/**
- * Docs-specific LLM provider: base analyze() from lib/llm plus summarizeTargetGroup, enhanceEndpointDocs, etc.
- */
-class DocsLLMProvider extends BaseLLMProvider {
-  /**
-   * 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 a docs-specific LLM provider from config (same config shape as lib/llm).
- * @param {object} config - { baseURL?, apiKey?, model? }
- * @returns {DocsLLMProvider}
- */
-function createProvider(config) {
-  if (!config || typeof config !== 'object') {
-    return new DocsLLMProvider({});
-  }
-  return new DocsLLMProvider(config);
-}
-
-export { DocsLLMProvider as LLMProvider, createProvider };
-export { extractJSON, extractJSONArray, reconcileOrderedTags } from '../../lib/llm/index.js';
-export default DocsLLMProvider;
+/**
+ * LLM provider for auto-documentation: extends shared lib/llm client with doc-specific methods.
+ * Single OpenAI-compatible implementation; works with OpenAI, OpenRouter, Ollama, Azure, etc.
+ */
+
+import { LLMProvider as BaseLLMProvider, extractJSON, extractJSONArray, reconcileOrderedTags } from '../../lib/llm/index.js';
+import {
+  buildSummarizeGroupPrompt,
+  buildEnhanceEndpointPrompt,
+  buildEnhanceEndpointPerMethodPrompt,
+  buildReorderTagsPrompt,
+  buildOverviewPrompt,
+} from './prompts.js';
+
+/**
+ * Docs-specific LLM provider: base analyze() from lib/llm plus summarizeTargetGroup, enhanceEndpointDocs, etc.
+ */
+class DocsLLMProvider extends BaseLLMProvider {
+  /**
+   * 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 a docs-specific LLM provider from config (same config shape as lib/llm).
+ * @param {object} config - { baseURL?, apiKey?, model? }
+ * @returns {DocsLLMProvider}
+ */
+function createProvider(config) {
+  if (!config || typeof config !== 'object') {
+    return new DocsLLMProvider({});
+  }
+  return new DocsLLMProvider(config);
+}
+
+export { DocsLLMProvider as LLMProvider, createProvider };
+export { extractJSON, extractJSONArray, reconcileOrderedTags } from '../../lib/llm/index.js';
+export default DocsLLMProvider;

package/auto-docs/index.js

@@ -1,146 +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)
- * - docs-llm/ — Docs-specific 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 './docs-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 './docs-llm/index.js';
-export { buildDocsPage } from './ui/docs-ui.js';
-export { analyzeHandler, detectMethods } from './analysis/handler-analyzer.js';
+/**
+ * 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)
+ * - docs-llm/ — Docs-specific 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 './docs-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 './docs-llm/index.js';
+export { buildDocsPage } from './ui/docs-ui.js';
+export { analyzeHandler, detectMethods } from './analysis/handler-analyzer.js';