@oxog/npm-llms 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,427 @@
+import { E as ExtractorOptions, a as Extractor, b as ExtractOptions, c as ExtractResult, C as CacheStats, d as CacheOptions, e as ContentPriority, P as PackageInfo, f as PackageMetadata } from './kernel-I4Zn2uXv.cjs';
+export { u as AIProvider, A as AIProviderName, k as AIProviderOptions, l as AITask, o as APIEntry, m as APIEntryKind, q as ChangelogEntry, t as CompletionOptions, j as EventHandler, s as ExtractorContext, J as JSDocParsed, K as Kernel, O as OutputFormat, n as ParamDoc, r as ParsedChangelog, p as ParsedReadme, g as Plugin, h as PluginCategory, i as PluginInfo, R as ReturnDoc, T as TarEntry, v as TarHeader, y as composePlugins, w as createKernel, x as definePlugin } from './kernel-I4Zn2uXv.cjs';
+
+/**
+ * Custom error classes for @oxog/npm-llms
+ * @module errors
+ */
+/**
+ * Base error class for npm-llms
+ * @example
+ * ```typescript
+ * try {
+ *   await extractor.extract('nonexistent-package');
+ * } catch (error) {
+ *   if (error instanceof NpmLlmsError) {
+ *     console.log(error.code); // 'PACKAGE_NOT_FOUND'
+ *   }
+ * }
+ * ```
+ */
+declare class NpmLlmsError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown> | undefined;
+    /**
+     * Create a new NpmLlmsError
+     * @param message - Error message
+     * @param code - Error code
+     * @param details - Additional error details
+     */
+    constructor(message: string, code: string, details?: Record<string, unknown> | undefined);
+    /**
+     * Convert error to JSON
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown when a package is not found on npm
+ * @example
+ * ```typescript
+ * throw new PackageNotFoundError('nonexistent-package');
+ * // Error: Package "nonexistent-package" not found on npm
+ * ```
+ */
+declare class PackageNotFoundError extends NpmLlmsError {
+    constructor(packageName: string);
+}
+/**
+ * Error thrown when a specific version is not found
+ * @example
+ * ```typescript
+ * throw new VersionNotFoundError('lodash', '99.99.99');
+ * // Error: Version "99.99.99" not found for package "lodash"
+ * ```
+ */
+declare class VersionNotFoundError extends NpmLlmsError {
+    constructor(packageName: string, version: string);
+}
+/**
+ * Error thrown when a download fails
+ * @example
+ * ```typescript
+ * throw new DownloadError('Network timeout', 'https://registry.npmjs.org/...');
+ * ```
+ */
+declare class DownloadError extends NpmLlmsError {
+    constructor(message: string, url?: string);
+}
+/**
+ * Error thrown when parsing fails
+ * @example
+ * ```typescript
+ * throw new ParseError('Invalid TypeScript syntax', 'index.d.ts');
+ * ```
+ */
+declare class ParseError extends NpmLlmsError {
+    constructor(message: string, file?: string, position?: {
+        line: number;
+        column: number;
+    });
+}
+/**
+ * Error thrown when AI provider fails
+ * @example
+ * ```typescript
+ * throw new AIError('Rate limit exceeded', 'claude');
+ * ```
+ */
+declare class AIError extends NpmLlmsError {
+    constructor(message: string, provider?: string);
+}
+/**
+ * Error thrown when a plugin fails
+ * @example
+ * ```typescript
+ * throw new PluginError('Plugin "custom-parser" failed to initialize', 'custom-parser');
+ * ```
+ */
+declare class PluginError extends NpmLlmsError {
+    constructor(message: string, pluginName?: string);
+}
+/**
+ * Error thrown when cache operation fails
+ * @example
+ * ```typescript
+ * throw new CacheError('Failed to write to cache directory');
+ * ```
+ */
+declare class CacheError extends NpmLlmsError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when configuration is invalid
+ * @example
+ * ```typescript
+ * throw new ConfigError('Invalid AI provider: "invalid"');
+ * ```
+ */
+declare class ConfigError extends NpmLlmsError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when tar extraction fails
+ * @example
+ * ```typescript
+ * throw new TarError('Invalid tar header at offset 512');
+ * ```
+ */
+declare class TarError extends NpmLlmsError {
+    constructor(message: string, offset?: number);
+}
+/**
+ * Error thrown when a network request times out
+ * @example
+ * ```typescript
+ * throw new TimeoutError('Request timed out after 30000ms', 30000);
+ * ```
+ */
+declare class TimeoutError extends NpmLlmsError {
+    constructor(message: string, timeout?: number);
+}
+/**
+ * Error thrown when validation fails
+ * @example
+ * ```typescript
+ * throw new ValidationError('Package name cannot be empty');
+ * ```
+ */
+declare class ValidationError extends NpmLlmsError {
+    constructor(message: string, field?: string);
+}
+/**
+ * Check if an error is a NpmLlmsError
+ * @param error - Error to check
+ * @returns True if error is a NpmLlmsError
+ * @example
+ * ```typescript
+ * if (isNpmLlmsError(error)) {
+ *   console.log(error.code);
+ * }
+ * ```
+ */
+declare function isNpmLlmsError(error: unknown): error is NpmLlmsError;
+/**
+ * Get error code from any error
+ * @param error - Error to get code from
+ * @returns Error code or 'UNKNOWN_ERROR'
+ * @example
+ * ```typescript
+ * const code = getErrorCode(error); // 'PACKAGE_NOT_FOUND' or 'UNKNOWN_ERROR'
+ * ```
+ */
+declare function getErrorCode(error: unknown): string;
+/**
+ * Wrap any error as NpmLlmsError
+ * @param error - Error to wrap
+ * @param code - Error code to use
+ * @returns NpmLlmsError
+ * @example
+ * ```typescript
+ * try {
+ *   await someOperation();
+ * } catch (error) {
+ *   throw wrapError(error, 'OPERATION_FAILED');
+ * }
+ * ```
+ */
+declare function wrapError(error: unknown, code?: string): NpmLlmsError;
+
+/**
+ * Main extractor implementation
+ * Ties together fetching, parsing, and output generation
+ * @module core/extractor
+ */
+
+/**
+ * Create a new extractor instance
+ * @param options - Extractor configuration options
+ * @returns Extractor instance
+ * @example
+ * ```typescript
+ * const extractor = createExtractor();
+ * const result = await extractor.extract('lodash@4.17.21');
+ * console.log(result.outputs.llms);
+ * ```
+ */
+declare function createExtractor(options?: ExtractorOptions): Extractor;
+/**
+ * Quick extract function for simple use cases
+ * @param packageSpec - Package specifier
+ * @param options - Extract options
+ * @returns Extract result
+ * @example
+ * ```typescript
+ * const result = await extract('lodash');
+ * console.log(result.outputs.llms);
+ * ```
+ */
+declare function extract(packageSpec: string, options?: ExtractOptions): Promise<ExtractResult>;
+
+/**
+ * File-based cache with TTL support
+ * Caches package data and AI responses to reduce API calls
+ * @module core/cache
+ */
+
+/**
+ * File-based cache implementation
+ * @example
+ * ```typescript
+ * const cache = new FileCache('.cache', 3600000); // 1 hour TTL
+ *
+ * // Get cached data
+ * const data = await cache.get<MyData>('my-key');
+ *
+ * // Set cached data
+ * await cache.set('my-key', myData);
+ *
+ * // Clear cache
+ * await cache.clear();
+ * ```
+ */
+declare class FileCache {
+    private readonly dir;
+    private readonly defaultTtl;
+    /**
+     * Create a new FileCache
+     * @param dir - Cache directory path
+     * @param defaultTtl - Default TTL in milliseconds
+     */
+    constructor(dir?: string, defaultTtl?: number);
+    /**
+     * Generate a cache key hash
+     * @param input - Input string
+     * @returns Hashed key
+     */
+    private getKey;
+    /**
+     * Get file path for a cache key
+     * @param key - Cache key
+     * @returns File path
+     */
+    private getPath;
+    /**
+     * Get cached data
+     * @param key - Cache key
+     * @returns Cached data or null if not found/expired
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Set cached data
+     * @param key - Cache key
+     * @param data - Data to cache
+     * @param ttl - Optional TTL override
+     */
+    set<T>(key: string, data: T, ttl?: number): Promise<void>;
+    /**
+     * Delete a cached entry
+     * @param key - Cache key
+     * @returns True if deleted, false if not found
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Check if a key is cached and not expired
+     * @param key - Cache key
+     * @returns True if cached and valid
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Clear all cached data
+     */
+    clear(): Promise<void>;
+    /**
+     * Remove expired entries
+     * @returns Number of entries removed
+     */
+    prune(): Promise<number>;
+    /**
+     * Get cache statistics
+     * @returns Cache stats
+     */
+    getStats(): Promise<CacheStats>;
+    /**
+     * Get cache directory path
+     */
+    getDir(): string;
+    /**
+     * Get default TTL
+     */
+    getDefaultTtl(): number;
+}
+/**
+ * Create a file cache from options
+ * @param options - Cache options
+ * @returns FileCache instance or null if disabled
+ */
+declare function createCache(options?: CacheOptions): FileCache | null;
+/**
+ * Format bytes for display
+ * @param bytes - Byte count
+ * @returns Formatted string
+ */
+declare function formatBytes(bytes: number): string;
+
+/**
+ * Token counting and truncation utilities
+ * Approximates GPT-4/Claude tokenization for content budgeting
+ * @module core/tokens
+ */
+
+/**
+ * Count approximate tokens in text
+ * Uses character-based heuristic optimized for LLM tokenization
+ * @param text - Text to count tokens in
+ * @returns Approximate token count
+ * @example
+ * ```typescript
+ * const tokens = countTokens("Hello, world!");
+ * console.log(tokens); // ~4
+ * ```
+ */
+declare function countTokens(text: string): number;
+/**
+ * Truncation result
+ */
+interface TruncateResult {
+    /** Truncated text */
+    text: string;
+    /** Whether truncation occurred */
+    truncated: boolean;
+    /** Actual token count */
+    tokenCount: number;
+    /** Sections included */
+    includedSections: string[];
+    /** Sections removed */
+    removedSections: string[];
+}
+/**
+ * Truncate text to fit within token limit while preserving structure
+ * @param text - Text to truncate
+ * @param limit - Token limit
+ * @param priorities - Priority order for content
+ * @returns Truncated text and metadata
+ * @example
+ * ```typescript
+ * const result = truncateToTokenLimit(content, 2000);
+ * if (result.truncated) {
+ *   console.log(`Removed: ${result.removedSections.join(', ')}`);
+ * }
+ * ```
+ */
+declare function truncateToTokenLimit(text: string, limit: number, priorities?: ContentPriority[]): TruncateResult;
+/**
+ * Format token count for display
+ * @param tokens - Token count
+ * @returns Formatted string
+ */
+declare function formatTokenCount(tokens: number): string;
+
+/**
+ * NPM package fetcher
+ * Downloads and extracts packages from the NPM registry
+ * @module core/fetcher
+ */
+
+/**
+ * Validate package name format
+ * @param name - Package name to validate
+ * @throws ValidationError if invalid
+ */
+declare function validatePackageName(name: string): void;
+/**
+ * Parse package specifier (name@version)
+ * @param spec - Package specifier (e.g., "lodash", "lodash@4.17.21", "@scope/pkg@1.0.0")
+ * @returns Parsed name and version
+ */
+declare function parsePackageSpec(spec: string): {
+    name: string;
+    version?: string;
+};
+/**
+ * Fetcher options
+ */
+interface FetcherOptions {
+    /** NPM registry URL */
+    registry?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Fetch package metadata from NPM registry
+ * @param name - Package name
+ * @param version - Optional version
+ * @param options - Fetcher options
+ * @returns Package metadata
+ * @throws PackageNotFoundError if package not found
+ * @throws VersionNotFoundError if version not found
+ */
+declare function fetchPackageMetadata(name: string, version?: string, options?: FetcherOptions): Promise<PackageMetadata>;
+/**
+ * Fetch complete package with files
+ * @param spec - Package specifier (e.g., "lodash@4.17.21")
+ * @param options - Fetcher options
+ * @returns Package info with files
+ */
+declare function fetchPackage(spec: string, options?: FetcherOptions): Promise<PackageInfo>;
+
+export { AIError, CacheError, CacheOptions, CacheStats, ConfigError, ContentPriority, DownloadError, ExtractOptions, ExtractResult, Extractor, ExtractorOptions, FileCache, NpmLlmsError, PackageInfo, PackageMetadata, PackageNotFoundError, ParseError, PluginError, TarError, TimeoutError, ValidationError, VersionNotFoundError, countTokens, createCache, createExtractor, extract, fetchPackage, fetchPackageMetadata, formatBytes, formatTokenCount, getErrorCode, isNpmLlmsError, parsePackageSpec, truncateToTokenLimit, validatePackageName, wrapError };