@oxog/npm-llms 1.0.0

package/dist/plugins/index.d.cts

@@ -0,0 +1,452 @@
+import { g as Plugin, s as ExtractorContext, u as AIProvider, t as CompletionOptions, r as ParsedChangelog, q as ChangelogEntry } from '../kernel-I4Zn2uXv.cjs';
+export { j as EventHandler, K as Kernel, h as PluginCategory, i as PluginInfo, y as composePlugins, w as createKernel, x as definePlugin } from '../kernel-I4Zn2uXv.cjs';
+
+/**
+ * Types Resolver Plugin
+ * Automatically fetches @types/* packages when main package lacks .d.ts files
+ * @module plugins/core/types-resolver
+ */
+
+/**
+ * Types Resolver Plugin
+ * Fetches @types/* package when main package has no .d.ts files
+ */
+declare const typesResolverPlugin: Plugin<ExtractorContext>;
+
+/**
+ * DTS Parser Plugin
+ * Parses TypeScript declaration files to extract API information
+ * @module plugins/core/dts-parser
+ */
+
+/**
+ * DTS Parser Plugin
+ * Parses .d.ts files to extract API entries
+ */
+declare const dtsParserPlugin: Plugin<ExtractorContext>;
+
+/**
+ * TypeScript Source Parser Plugin
+ * Fallback parser for packages without .d.ts files
+ * @module plugins/core/ts-source-parser
+ */
+
+/**
+ * TypeScript Source Parser Plugin
+ * Parses .ts/.tsx files when .d.ts files are not available
+ */
+declare const tsSourceParserPlugin: Plugin<ExtractorContext>;
+
+/**
+ * README Parser Plugin
+ * Parses README.md to extract documentation content
+ * @module plugins/core/readme-parser
+ */
+
+/**
+ * README Parser Plugin
+ * Extracts structured content from package README
+ */
+declare const readmeParserPlugin: Plugin<ExtractorContext>;
+
+/**
+ * llms.txt Output Plugin
+ * Generates concise LLM-optimized documentation
+ * @module plugins/core/llms-output
+ */
+
+/**
+ * llms.txt Output Plugin
+ * Generates llms.txt within token limits
+ */
+declare const llmsOutputPlugin: Plugin<ExtractorContext>;
+
+/**
+ * llms-full.txt Output Plugin
+ * Generates complete LLM-optimized documentation
+ * @module plugins/core/llms-full-output
+ */
+
+/**
+ * llms-full.txt Output Plugin
+ * Generates complete API documentation without token limits
+ */
+declare const llmsFullOutputPlugin: Plugin<ExtractorContext>;
+
+/**
+ * Markdown Output Plugin
+ * Generates API documentation in Markdown format
+ * @module plugins/core/markdown-output
+ */
+
+/**
+ * Markdown Output Plugin
+ * Generates formatted API documentation
+ */
+declare const markdownOutputPlugin: Plugin<ExtractorContext>;
+
+/**
+ * JSON Output Plugin
+ * Generates structured JSON documentation
+ * @module plugins/core/json-output
+ */
+
+/**
+ * JSON Output Plugin
+ * Generates structured JSON for programmatic use
+ */
+declare const jsonOutputPlugin: Plugin<ExtractorContext>;
+
+/**
+ * Core plugins for @oxog/npm-llms
+ * @module plugins/core
+ */
+
+/**
+ * All core parser plugins
+ * Note: typesResolverPlugin must come first to fetch @types/* before parsing
+ */
+declare const coreParserPlugins: Plugin<ExtractorContext>[];
+/**
+ * All core output plugins
+ */
+declare const coreOutputPlugins: Plugin<ExtractorContext>[];
+/**
+ * All core plugins
+ */
+declare const corePlugins: Plugin<ExtractorContext>[];
+
+/**
+ * AI Base Plugin
+ * Provides common infrastructure for AI-powered documentation enrichment
+ * @module plugins/optional/ai-base
+ */
+
+/**
+ * AI enrichment task types
+ */
+type AIEnrichmentTask = 'descriptions' | 'examples' | 'summary' | 'params' | 'returns';
+/**
+ * AI enrichment options
+ */
+interface AIEnrichmentOptions {
+    /** Tasks to perform */
+    tasks: AIEnrichmentTask[];
+    /** Maximum tokens per request */
+    maxTokensPerRequest?: number;
+    /** Temperature for generation */
+    temperature?: number;
+    /** Batch size for processing entries */
+    batchSize?: number;
+    /** Whether to skip entries that already have content */
+    skipExisting?: boolean;
+}
+/**
+ * Create AI enrichment plugin
+ * @param provider - AI provider implementation
+ * @param options - Enrichment options
+ * @returns Plugin instance
+ */
+declare function createAIEnrichmentPlugin(provider: AIProvider, options?: Partial<AIEnrichmentOptions>): Plugin;
+/**
+ * Create a simple AI provider from a completion function
+ */
+declare function createSimpleProvider(name: string, completeFn: (prompt: string, options?: CompletionOptions) => Promise<string>, isAvailableFn?: () => boolean): AIProvider;
+
+/**
+ * Claude API configuration
+ */
+interface ClaudeConfig {
+    /** API key (or set ANTHROPIC_API_KEY env var) */
+    apiKey?: string;
+    /** Model to use */
+    model?: 'claude-opus-4-5-20251101' | 'claude-sonnet-4-5-20250929' | 'claude-haiku-4-5-20251001' | 'claude-opus-4-5' | 'claude-sonnet-4-5' | 'claude-haiku-4-5' | string;
+    /** API base URL */
+    baseUrl?: string;
+    /** Request timeout in ms */
+    timeout?: number;
+}
+/**
+ * Create Claude AI provider
+ * @param config - Claude configuration
+ * @returns AI provider instance
+ */
+declare function createClaudeProvider(config?: ClaudeConfig): AIProvider;
+/**
+ * Create Claude AI enrichment plugin
+ * @param config - Claude configuration
+ * @param enrichmentOptions - Enrichment options
+ * @returns Plugin instance
+ */
+declare function createClaudePlugin(config?: ClaudeConfig, enrichmentOptions?: Partial<AIEnrichmentOptions>): Plugin<ExtractorContext>;
+
+/**
+ * OpenAI-compatible provider presets
+ */
+declare const OPENAI_COMPATIBLE_PRESETS: {
+    readonly openai: {
+        readonly name: "openai";
+        readonly baseUrl: "https://api.openai.com/v1";
+        readonly envKey: "OPENAI_API_KEY";
+        readonly defaultModel: "gpt-4.1-nano";
+    };
+    readonly xai: {
+        readonly name: "xai";
+        readonly baseUrl: "https://api.x.ai/v1";
+        readonly envKey: "XAI_API_KEY";
+        readonly defaultModel: "grok-3-mini-fast";
+    };
+    readonly zai: {
+        readonly name: "zai";
+        readonly baseUrl: "https://api.z.ai/api/paas/v4";
+        readonly envKey: "ZAI_API_KEY";
+        readonly defaultModel: "glm-4.7";
+    };
+    readonly together: {
+        readonly name: "together";
+        readonly baseUrl: "https://api.together.xyz/v1";
+        readonly envKey: "TOGETHER_API_KEY";
+        readonly defaultModel: "meta-llama/Llama-3.3-70B-Instruct-Turbo";
+    };
+    readonly perplexity: {
+        readonly name: "perplexity";
+        readonly baseUrl: "https://api.perplexity.ai";
+        readonly envKey: "PERPLEXITY_API_KEY";
+        readonly defaultModel: "sonar-pro";
+    };
+    readonly openrouter: {
+        readonly name: "openrouter";
+        readonly baseUrl: "https://openrouter.ai/api/v1";
+        readonly envKey: "OPENROUTER_API_KEY";
+        readonly defaultModel: "anthropic/claude-3.5-sonnet";
+    };
+    readonly deepseek: {
+        readonly name: "deepseek";
+        readonly baseUrl: "https://api.deepseek.com/v1";
+        readonly envKey: "DEEPSEEK_API_KEY";
+        readonly defaultModel: "deepseek-chat";
+    };
+    readonly mistral: {
+        readonly name: "mistral";
+        readonly baseUrl: "https://api.mistral.ai/v1";
+        readonly envKey: "MISTRAL_API_KEY";
+        readonly defaultModel: "mistral-small-latest";
+    };
+};
+type OpenAICompatiblePreset = keyof typeof OPENAI_COMPATIBLE_PRESETS;
+/**
+ * OpenAI API configuration
+ */
+interface OpenAIConfig {
+    /** API key (or set OPENAI_API_KEY env var) */
+    apiKey?: string;
+    /** Model to use */
+    model?: 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-4o' | 'gpt-4o-mini' | 'o4-mini' | 'o3' | 'o3-mini' | 'o3-pro' | 'o1' | 'o1-pro' | string;
+    /** API base URL (with /v1 suffix for chat/completions endpoint) */
+    baseUrl?: string;
+    /** Request timeout in ms */
+    timeout?: number;
+    /** Organization ID (OpenAI only) */
+    organization?: string;
+    /** Provider preset for OpenAI-compatible APIs */
+    preset?: OpenAICompatiblePreset;
+}
+/**
+ * Create OpenAI provider
+ * @param config - OpenAI configuration
+ * @returns AI provider instance
+ */
+declare function createOpenAIProvider(config?: OpenAIConfig): AIProvider;
+/**
+ * Create OpenAI enrichment plugin
+ * @param config - OpenAI configuration
+ * @param enrichmentOptions - Enrichment options
+ * @returns Plugin instance
+ */
+declare function createOpenAIPlugin(config?: OpenAIConfig, enrichmentOptions?: Partial<AIEnrichmentOptions>): Plugin<ExtractorContext>;
+
+/**
+ * Gemini AI plugin for @oxog/npm-llms
+ * Uses Google's Gemini API for documentation enrichment
+ * @module plugins/optional/gemini-ai
+ */
+
+/**
+ * Gemini configuration options
+ */
+interface GeminiConfig {
+    /** Gemini API key (defaults to GOOGLE_API_KEY or GEMINI_API_KEY env var) */
+    apiKey?: string;
+    /** Model to use */
+    model?: 'gemini-3-pro-preview' | 'gemini-3-pro-image-preview' | 'gemini-3-flash-preview' | 'gemini-2.5-flash-image' | 'gemini-2.5-pro' | 'gemini-2.5-flash' | 'gemini-2.5-flash-lite' | 'gemini-2.0-flash' | 'gemini-2.0-flash-lite' | 'gemini-flash-latest' | 'gemini-flash-lite-latest' | string;
+    /** API base URL */
+    baseUrl?: string;
+    /** Request timeout in ms */
+    timeout?: number;
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Temperature for generation */
+    temperature?: number;
+}
+/**
+ * Create a Gemini AI provider
+ * @param config - Gemini configuration
+ * @returns AI provider instance
+ */
+declare function createGeminiProvider(config?: GeminiConfig): AIProvider;
+/**
+ * Create a Gemini enrichment plugin
+ * @param config - Gemini configuration
+ * @param enrichmentOptions - Enrichment options
+ * @returns Gemini plugin
+ */
+declare function createGeminiPlugin(config?: GeminiConfig, enrichmentOptions?: Partial<AIEnrichmentOptions>): Plugin;
+/**
+ * Check if Gemini is available (API key is set)
+ * @returns True if Gemini is available
+ */
+declare function checkGeminiAvailable(): boolean;
+
+/**
+ * Ollama configuration
+ */
+interface OllamaConfig {
+    /** Model to use */
+    model?: string;
+    /** Ollama API base URL */
+    baseUrl?: string;
+    /** Request timeout in ms */
+    timeout?: number;
+}
+/**
+ * Create Ollama provider
+ * @param config - Ollama configuration
+ * @returns AI provider instance
+ */
+declare function createOllamaProvider(config?: OllamaConfig): AIProvider;
+/**
+ * Create Ollama enrichment plugin
+ * @param config - Ollama configuration
+ * @param enrichmentOptions - Enrichment options
+ * @returns Plugin instance
+ */
+declare function createOllamaPlugin(config?: OllamaConfig, enrichmentOptions?: Partial<AIEnrichmentOptions>): Plugin<ExtractorContext>;
+/**
+ * Check if Ollama is available
+ * @param baseUrl - Ollama base URL
+ * @returns True if Ollama is running
+ */
+declare function checkOllamaAvailable(baseUrl?: string): Promise<boolean>;
+/**
+ * List available Ollama models
+ * @param baseUrl - Ollama base URL
+ * @returns List of model names
+ */
+declare function listOllamaModels(baseUrl?: string): Promise<string[]>;
+
+/**
+ * Groq API configuration
+ */
+interface GroqConfig {
+    /** API key (or set GROQ_API_KEY env var) */
+    apiKey?: string;
+    /** Model to use */
+    model?: 'llama-3.3-70b-versatile' | 'llama-3.1-8b-instant' | 'meta-llama/llama-4-maverick-17b-128e-instruct' | 'meta-llama/llama-4-scout-17b-16e-instruct' | 'qwen/qwen3-32b' | 'moonshotai/kimi-k2-instruct-0905' | 'groq/compound' | 'groq/compound-mini' | 'openai/gpt-oss-120b' | 'openai/gpt-oss-20b' | string;
+    /** API base URL */
+    baseUrl?: string;
+    /** Request timeout in ms */
+    timeout?: number;
+}
+/**
+ * Create Groq provider
+ * @param config - Groq configuration
+ * @returns AI provider instance
+ */
+declare function createGroqProvider(config?: GroqConfig): AIProvider;
+/**
+ * Create Groq enrichment plugin
+ * @param config - Groq configuration
+ * @param enrichmentOptions - Enrichment options
+ * @returns Plugin instance
+ */
+declare function createGroqPlugin(config?: GroqConfig, enrichmentOptions?: Partial<AIEnrichmentOptions>): Plugin<ExtractorContext>;
+
+/**
+ * Changelog parser plugin for @oxog/npm-llms
+ * Parses CHANGELOG.md files in Keep a Changelog format
+ * @module plugins/optional/changelog-parser
+ */
+
+/**
+ * Parse a changelog file into structured data
+ * @param content - Raw changelog content
+ * @returns Parsed changelog structure
+ */
+declare function parseChangelog(content: string): ParsedChangelog;
+/**
+ * Find changelog file in package files
+ * @param files - Map of file paths to content
+ * @returns Changelog content or undefined
+ */
+declare function findChangelog(files: Map<string, string>): string | undefined;
+/**
+ * Get latest version from changelog
+ * @param changelog - Parsed changelog
+ * @returns Latest version entry or undefined
+ */
+declare function getLatestVersion(changelog: ParsedChangelog): ChangelogEntry | undefined;
+/**
+ * Get version by number
+ * @param changelog - Parsed changelog
+ * @param version - Version number to find
+ * @returns Version entry or undefined
+ */
+declare function getVersion(changelog: ParsedChangelog, version: string): ChangelogEntry | undefined;
+/**
+ * Format changelog entry as text
+ * @param entry - Changelog entry
+ * @returns Formatted text
+ */
+declare function formatChangelogEntry(entry: ChangelogEntry): string;
+/**
+ * Create changelog parser plugin
+ * @returns Changelog parser plugin
+ */
+declare function createChangelogParserPlugin(): Plugin;
+
+/**
+ * HTML output plugin for @oxog/npm-llms
+ * Generates HTML documentation from API entries
+ * @module plugins/optional/html-output
+ */
+
+/**
+ * HTML output options
+ */
+interface HTMLOutputOptions {
+    /** Page title (uses package name if not provided) */
+    title?: string;
+    /** Include inline styles */
+    includeStyles?: boolean;
+    /** Include syntax highlighting CSS classes */
+    syntaxHighlighting?: boolean;
+    /** Dark mode support */
+    darkMode?: boolean;
+    /** Custom CSS to inject */
+    customCSS?: string;
+}
+/**
+ * Generate full HTML document
+ * @param ctx - Extractor context
+ * @param options - HTML options
+ * @returns HTML string
+ */
+declare function generateHTML(ctx: ExtractorContext, options?: HTMLOutputOptions): string;
+/**
+ * Create HTML output plugin
+ * @param options - HTML options
+ * @returns HTML output plugin
+ */
+declare function createHTMLOutputPlugin(options?: HTMLOutputOptions): Plugin;
+
+export { type AIEnrichmentOptions, type AIEnrichmentTask, AIProvider, type ClaudeConfig, CompletionOptions, ExtractorContext, type GeminiConfig, type GroqConfig, type HTMLOutputOptions, type OllamaConfig, type OpenAIConfig, Plugin, checkGeminiAvailable, checkOllamaAvailable, coreOutputPlugins, coreParserPlugins, corePlugins, createAIEnrichmentPlugin, createChangelogParserPlugin, createClaudePlugin, createClaudeProvider, createGeminiPlugin, createGeminiProvider, createGroqPlugin, createGroqProvider, createHTMLOutputPlugin, createOllamaPlugin, createOllamaProvider, createOpenAIPlugin, createOpenAIProvider, createSimpleProvider, dtsParserPlugin, findChangelog, formatChangelogEntry, generateHTML, getLatestVersion, getVersion, jsonOutputPlugin, listOllamaModels, llmsFullOutputPlugin, llmsOutputPlugin, markdownOutputPlugin, parseChangelog, readmeParserPlugin, tsSourceParserPlugin, typesResolverPlugin };