@stacksjs/dtsx 0.9.9 → 0.9.10

package/dist/compat.d.ts

@@ -0,0 +1,108 @@
+import type { ChildProcess } from 'node:child_process';
+/**
+ * Cross-runtime file handle creator
+ * Compatible with Bun.file() API
+ */
+export declare function file(path: string): FileHandle;
+/**
+ * Cross-runtime file writer
+ * Compatible with Bun.write() API
+ */
+export declare function write(path: string, content: string | Uint8Array | ArrayBuffer): Promise<number>;
+/**
+ * Cross-runtime process spawner
+ * Compatible with Bun.spawn() API
+ */
+export declare function spawnProcess(command: string | string[], options?: CompatSpawnOptions): SpawnResult;
+/**
+ * Read a file as text with cross-runtime compatibility
+ */
+export declare function readTextFile(path: string): Promise<string>;
+/**
+ * Check if a file exists with cross-runtime compatibility
+ */
+export declare function fileExists(path: string): Promise<boolean>;
+/**
+ * Write text to a file with cross-runtime compatibility
+ */
+export declare function writeTextFile(path: string, content: string): Promise<void>;
+/**
+ * Get runtime information
+ */
+export declare function getRuntimeInfo(): RuntimeInfo;
+/**
+ * Runtime detection
+ */
+export declare const isBun: boolean;
+export declare const isNode: boolean;
+/**
+ * Current runtime name
+ */
+export declare const runtime: 'bun' | 'node';
+/**
+ * File handle interface compatible with Bun.file()
+ */
+export declare interface FileHandle {
+  exists: () => Promise<boolean>
+  text: () => Promise<string>
+  arrayBuffer: () => Promise<ArrayBuffer>
+  size: number
+  name: string
+}
+/**
+ * Spawn result interface compatible with Bun.spawn()
+ */
+export declare interface SpawnResult {
+  pid: number
+  stdout: ReadableStream<Uint8Array> | NodeJS.ReadableStream
+  stderr: ReadableStream<Uint8Array> | NodeJS.ReadableStream
+  stdin: WritableStream<Uint8Array> | NodeJS.WritableStream | null
+  exited: Promise<number>
+  kill: (signal?: number) => void
+  ref: () => void
+  unref: () => void
+}
+/**
+ * Spawn options compatible with Bun.spawn()
+ */
+export declare interface CompatSpawnOptions {
+  cwd?: string
+  env?: Record<string, string | undefined>
+  stdin?: 'inherit' | 'pipe' | 'ignore' | null
+  stdout?: 'inherit' | 'pipe' | 'ignore' | null
+  stderr?: 'inherit' | 'pipe' | 'ignore' | null
+}
+/**
+ * Runtime information
+ */
+export declare interface RuntimeInfo {
+  name: 'bun' | 'node'
+  version: string
+  isBun: boolean
+  isNode: boolean
+}
+/**
+ * Node.js implementation of Bun-like file handle
+ */
+declare class NodeFileHandle implements FileHandle {
+  name: string;
+  constructor(path: string);
+  exists(): Promise<boolean>;
+  text(): Promise<string>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  get size(): number;
+}
+/**
+ * Node.js implementation of Bun-like spawn result
+ */
+declare class NodeSpawnResult implements SpawnResult {
+  pid: number;
+  stdout: NodeJS.ReadableStream;
+  stderr: NodeJS.ReadableStream;
+  stdin: NodeJS.WritableStream | null;
+  exited: Promise<number>;
+  constructor(proc: ChildProcess);
+  kill(signal?: number): void;
+  ref(): void;
+  unref(): void;
+}

package/dist/config.d.ts

@@ -1,5 +1,35 @@
 import type { DtsGenerationConfig } from './types';
+/**
+ * Get the configuration, loading from config file if available
+ */
+export declare function getConfig(cwd?: string): Promise<DtsGenerationConfig>;
+/**
+ * Reset the cached config (useful for testing)
+ */
+export declare function resetConfig(): void;
+/*.ts'],
+ *   keepComments: true,
+ * })
+ * ```
+ */
+export declare function defineConfig(config: Partial<DtsGenerationConfig>): DtsGenerationConfig;
+/**
+ * Define a dtsx configuration with async support
+ * Allows loading plugins or other async dependencies
+ *
+ * @example
+ * ```ts
+ * // dtsx.config.ts
+ * import { defineConfigAsync } from 'dtsx'
+ *
+ * export default defineConfigAsync(async () => ({
+ *   root: './src',
+ *   outdir: './dist',
+ *   plugins: [await loadPlugin()],
+ * }))
+ * ```
+ */
+export declare function defineConfigAsync(configFn: () => Promise<Partial<DtsGenerationConfig>>): () => Promise<DtsGenerationConfig>;
 export declare const defaultConfig: DtsGenerationConfig;
-// Get loaded config
-// eslint-disable-next-line antfu/no-top-level-await
-export declare const config: DtsGenerationConfig;
+// For backwards compatibility - synchronous access with default fallback
+export declare const config: DtsGenerationConfig;

package/dist/diff.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Compute diff between two strings
+ */
+export declare function computeDiff(oldContent: string, newContent: string, filePath: string, options?: DiffOptions): DiffResult;
+/**
+ * Format diff result as unified diff string
+ */
+export declare function formatUnifiedDiff(result: DiffResult): string;
+/**
+ * Format diff with colors for terminal output
+ */
+export declare function formatColoredDiff(result: DiffResult): string;
+/**
+ * Format diff as simple summary
+ */
+export declare function formatDiffSummary(result: DiffResult): string;
+/**
+ * Compare a file against new content
+ */
+export declare function diffFile(filePath: string, newContent: string, options?: DiffOptions): Promise<DiffResult>;
+/**
+ * Compare multiple files
+ */
+export declare function diffFiles(files: Map<string, string>, options?: DiffOptions): Promise<Map<string, DiffResult>>;
+/**
+ * Generate a summary of all diffs
+ */
+export declare function summarizeDiffs(results: Map<string, DiffResult>): {
+  totalFiles: number
+  changedFiles: number
+  unchangedFiles: number
+  totalAdditions: number
+  totalDeletions: number
+  newFiles: number
+};
+/**
+ * Print colored diff to console
+ */
+export declare function printDiff(result: DiffResult): void;
+/**
+ * Print all diffs to console
+ */
+export declare function printDiffs(results: Map<string, DiffResult>, showUnchanged?: boolean): void;
+/**
+ * A single diff hunk (change)
+ */
+export declare interface DiffHunk {
+  operation: DiffOperation
+  lines: string[]
+  oldStart: number
+  oldCount: number
+  newStart: number
+  newCount: number
+}
+/**
+ * Complete diff result
+ */
+export declare interface DiffResult {
+  filePath: string
+  identical: boolean
+  hunks: DiffHunk[]
+  stats: {
+    additions: number
+    deletions: number
+    unchanged: number
+  }
+  oldContent?: string
+  newContent: string
+}
+/**
+ * Options for diff generation
+ */
+export declare interface DiffOptions {
+  context?: number
+  ignoreWhitespace?: boolean
+  ignoreBlankLines?: boolean
+  treatMissingAsEmpty?: boolean
+}
+/**
+ * Diff operation type
+ */
+export type DiffOperation = 'add' | 'remove' | 'equal';

package/dist/docs.d.ts

@@ -0,0 +1,97 @@
+import type { Declaration } from './types';
+/**
+ * Parse JSDoc comments from a declaration
+ */
+export declare function parseJSDoc(comments: string[] | undefined): JSDocInfo;
+/**
+ * Extract documentation from source files
+ */
+export declare function extractDocumentation(files: string[], config?: Partial<DocsConfig>): Promise<Documentation>;
+/**
+ * Generate markdown documentation
+ */
+export declare function generateMarkdown(docs: Documentation, config?: Partial<DocsConfig>): string;
+/**
+ * Generate HTML documentation
+ */
+export declare function generateHTML(docs: Documentation, config?: Partial<DocsConfig>): string;
+/**
+ * Generate JSON documentation
+ */
+export declare function generateJSON(docs: Documentation, config?: Partial<DocsConfig>): string;
+/**
+ * Generate documentation in TypeDoc-compatible JSON format
+ */
+export declare function generateTypeDocJSON(docs: Documentation): string;
+/**
+ * Generate and write documentation files
+ */
+export declare function generateDocs(files: string[], config: DocsConfig): Promise<void>;
+/**
+ * Create a documentation generator with preset configuration
+ */
+export declare function createDocsGenerator(config?: Partial<DocsConfig>): {
+  extract: (files: string[]) => Promise<Documentation>
+  generateMarkdown: (docs: Documentation) => string
+  generateHTML: (docs: Documentation) => string
+  generateJSON: (docs: Documentation) => string
+  parseJSDoc: typeof parseJSDoc
+};
+/**
+ * Documentation configuration
+ */
+export declare interface DocsConfig {
+  format: 'markdown' | 'html' | 'json'
+  outdir: string
+  includePrivate?: boolean
+  includeInternal?: boolean
+  groupByCategory?: boolean
+  title?: string
+  description?: string
+  includeSourceLinks?: boolean
+  sourceBaseUrl?: string
+  includeTypes?: boolean
+  splitByModule?: boolean
+  template?: 'default' | 'minimal' | 'detailed'
+  customCss?: string
+  includeSidebar?: boolean
+}
+/**
+ * Parsed JSDoc information
+ */
+export declare interface JSDocInfo {
+  description: string
+  params: Array<{ name: string, type?: string, description: string, optional?: boolean }>
+  returns?: { type?: string, description: string }
+  examples: string[]
+  tags: Record<string, string[]>
+  deprecated?: string
+  since?: string
+  see: string[]
+  throws: Array<{ type?: string, description: string }>
+  category?: string
+}
+/**
+ * Documentation entry for a declaration
+ */
+export declare interface DocEntry {
+  name: string
+  kind: Declaration['kind']
+  signature: string
+  jsdoc: JSDocInfo
+  isExported: boolean
+  isDefault?: boolean
+  sourceFile?: string
+  sourceLine?: number
+  members?: DocEntry[]
+}
+/**
+ * Documentation output structure
+ */
+export declare interface Documentation {
+  title: string
+  description?: string
+  entries: DocEntry[]
+  categories: Map<string, DocEntry[]>
+  generatedAt: Date
+}

package/dist/errors.d.ts

@@ -0,0 +1,113 @@
+import type { DtsError, SourceLocation } from './types';
+/**
+ * Type guards for error types
+ */
+export declare function isDtsxError(error: unknown): error is DtsxError;
+export declare function isParseError(error: unknown): error is ParseError;
+export declare function isFileError(error: unknown): error is FileError;
+export declare function isConfigError(error: unknown): error is ConfigError;
+/**
+ * Wrap an unknown error in a DtsxError
+ */
+export declare function wrapError(error: unknown, code?: ErrorCode, message?: string): DtsxError;
+/**
+ * Calculate line and column from source code offset
+ */
+export declare function getLocationFromOffset(sourceCode: string, offset: number): SourceLocation;
+/**
+ * Create a formatted error message with source location context
+ */
+export declare function formatErrorWithContext(sourceCode: string, location: SourceLocation, message: string, filePath?: string): string;
+/**
+ * Create a DtsError from an exception
+ */
+export declare function createDtsError(error: unknown, file: string, _sourceCode?: string): DtsError;
+/**
+ * Format a DtsError for display
+ */
+export declare function formatDtsError(error: DtsError, sourceCode?: string): string;
+/**
+ * Aggregate multiple errors into a summary
+ */
+export declare function summarizeErrors(errors: DtsError[]): string;
+/**
+ * Error codes for categorizing errors
+ */
+export declare const ErrorCodes: {
+  PARSE_ERROR: 'PARSE_ERROR';
+  SYNTAX_ERROR: 'SYNTAX_ERROR';
+  FILE_NOT_FOUND: 'FILE_NOT_FOUND';
+  FILE_READ_ERROR: 'FILE_READ_ERROR';
+  FILE_WRITE_ERROR: 'FILE_WRITE_ERROR';
+  TYPE_INFERENCE_ERROR: 'TYPE_INFERENCE_ERROR';
+  UNRESOLVED_TYPE: 'UNRESOLVED_TYPE';
+  EXTRACTION_ERROR: 'EXTRACTION_ERROR';
+  PROCESSING_ERROR: 'PROCESSING_ERROR';
+  VALIDATION_ERROR: 'VALIDATION_ERROR';
+  INVALID_DECLARATION: 'INVALID_DECLARATION';
+  CONFIG_ERROR: 'CONFIG_ERROR';
+  INVALID_ENTRYPOINT: 'INVALID_ENTRYPOINT';
+  CIRCULAR_DEPENDENCY: 'CIRCULAR_DEPENDENCY';
+  TIMEOUT_ERROR: 'TIMEOUT_ERROR';
+  NOT_SUPPORTED: 'NOT_SUPPORTED';
+  UNKNOWN_ERROR: 'UNKNOWN_ERROR'
+};
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
+/**
+ * Base error class for dtsx errors
+ */
+export declare class DtsxError extends Error {
+  readonly code: ErrorCode;
+  readonly context?: Record<string, unknown>;
+  constructor(message: string, code?: ErrorCode, context?: Record<string, unknown>);
+  toString(): string;
+  toJSON(): Record<string, unknown>;
+}
+/**
+ * Error during file parsing
+ */
+export declare class ParseError extends DtsxError {
+  readonly filePath: string;
+  readonly line?: number;
+  readonly column?: number;
+  constructor(message: string, filePath: string, options?: { line?: number, column?: number, cause?: Error });
+  get locationString(): string;
+}
+/**
+ * Error during declaration extraction
+ */
+export declare class ExtractionError extends DtsxError {
+  readonly filePath: string;
+  readonly declarationKind?: string;
+  constructor(message: string, filePath: string, declarationKind?: string, cause?: Error);
+}
+/**
+ * Error during type processing
+ */
+export declare class ProcessingError extends DtsxError {
+  readonly declarationName?: string;
+  constructor(message: string, declarationName?: string, cause?: Error);
+}
+/**
+ * Error during file I/O operations
+ */
+export declare class FileError extends DtsxError {
+  readonly filePath: string;
+  readonly operation: 'read' | 'write' | 'delete' | 'stat' | 'glob';
+  constructor(message: string, filePath: string, operation: 'read' | 'write' | 'delete' | 'stat' | 'glob', cause?: Error);
+}
+/**
+ * Error during configuration loading or validation
+ */
+export declare class ConfigError extends DtsxError {
+  readonly configPath?: string;
+  readonly invalidKey?: string;
+  constructor(message: string, options?: { configPath?: string, invalidKey?: string, cause?: Error });
+}
+/**
+ * Error when circular dependency is detected
+ */
+export declare class CircularDependencyError extends DtsxError {
+  readonly cycle: string[];
+  constructor(cycle: string[]);
+}

package/dist/extractor/builders.d.ts

@@ -0,0 +1,38 @@
+import type { ClassDeclaration, FunctionDeclaration, InterfaceDeclaration, ModuleDeclaration, SourceFile, TypeAliasDeclaration } from 'typescript';
+/**
+ * Build clean function signature for DTS output
+ */
+export declare function buildFunctionSignature(node: FunctionDeclaration, sf: SourceFile): string;
+/**
+ * Build clean variable declaration for DTS
+ */
+export declare function buildVariableDeclaration(name: string, type: string | undefined, kind: string, isExported: boolean): string;
+/**
+ * Build clean interface declaration for DTS
+ */
+export declare function buildInterfaceDeclaration(node: InterfaceDeclaration, isExported: boolean, sf: SourceFile): string;
+/**
+ * Get interface body with proper formatting
+ */
+export declare function getInterfaceBody(node: InterfaceDeclaration, sf: SourceFile): string;
+/**
+ * Build clean type declaration for DTS
+ */
+export declare function buildTypeDeclaration(node: TypeAliasDeclaration, isExported: boolean, sf: SourceFile): string;
+/**
+ * Build clean class declaration for DTS
+ */
+export declare function buildClassDeclaration(node: ClassDeclaration, isExported: boolean, sf: SourceFile): string;
+/**
+ * Build clean class body for DTS (signatures only, no implementations)
+ * Excludes: private fields (#field), private methods (#method), static blocks
+ */
+export declare function buildClassBody(node: ClassDeclaration, sf: SourceFile): string;
+/**
+ * Build clean module declaration for DTS
+ */
+export declare function buildModuleDeclaration(node: ModuleDeclaration, isExported: boolean, sf: SourceFile): string;
+/**
+ * Build clean module body for DTS (signatures only, no implementations)
+ */
+export declare function buildModuleBody(node: ModuleDeclaration, sf: SourceFile): string;

package/dist/extractor/cache.d.ts

@@ -0,0 +1,47 @@
+import { hashContent } from './hash';
+import type { SourceFile } from 'typescript';
+/**
+ * Evict oldest entry if cache exceeds max size
+ * Uses O(n) scan instead of O(n log n) sort since we add one entry at a time
+ */
+export declare function evictOldestEntries(): void;
+/**
+ * Get or create a cached SourceFile
+ * Accepts an optional pre-computed contentHash to avoid re-hashing
+ */
+export declare function getSourceFile(filePath: string, sourceCode: string, precomputedHash?: number | bigint): SourceFile;
+/**
+ * Clear the SourceFile cache (useful for testing or memory management)
+ */
+export declare function clearSourceFileCache(): void;
+/**
+ * Get the current cache size (useful for debugging)
+ */
+export declare function getSourceFileCacheSize(): number;
+/**
+ * Async version of getSourceFile that yields to the event loop for large files
+ * Prevents blocking when processing many large files in parallel
+ */
+export declare function getSourceFileAsync(filePath: string, sourceCode: string, config?: AsyncParseConfig): Promise<SourceFile>;
+/**
+ * Batch parse multiple files asynchronously with concurrency control
+ * Useful for processing many files while keeping the event loop responsive
+ */
+export declare function batchParseSourceFiles(files: Array<{ filePath: string, sourceCode: string }>, config?: AsyncParseConfig & { concurrency?: number }): Promise<Map<string, SourceFile>>;
+/**
+ * Check if a file should use async parsing based on size
+ */
+export declare function shouldUseAsyncParsing(sourceCode: string, config?: AsyncParseConfig): boolean;
+/**
+ * Get statistics about pending parse operations
+ */
+export declare function getPendingParseCount(): number;
+/**
+ * Configuration for async parsing
+ */
+export declare interface AsyncParseConfig {
+  asyncThreshold?: number
+  chunkSize?: number
+  yieldInterval?: number
+}
+export { hashContent } from './hash';

package/dist/extractor/declarations.d.ts

@@ -0,0 +1,50 @@
+import type { ClassDeclaration, EnumDeclaration, ExportAssignment, ExportDeclaration, FunctionDeclaration, ImportDeclaration, InterfaceDeclaration, ModuleDeclaration, SourceFile, TypeAliasDeclaration, VariableStatement } from 'typescript';
+import type { Declaration } from '../types';
+/**
+ * Extract import declaration
+ */
+export declare function extractImportDeclaration(node: ImportDeclaration, sourceCode: string, sourceFile: SourceFile): Declaration;
+/**
+ * Extract export declaration
+ */
+export declare function extractExportDeclaration(node: ExportDeclaration, sourceCode: string, sourceFile: SourceFile, keepComments?: boolean): Declaration;
+/**
+ * Extract export assignment (export default)
+ */
+export declare function extractExportAssignment(node: ExportAssignment, sourceCode: string, sourceFile: SourceFile, keepComments?: boolean): Declaration;
+/**
+ * Extract function declaration with proper signature
+ */
+export declare function extractFunctionDeclaration(node: FunctionDeclaration, _sourceCode: string, sourceFile: SourceFile, keepComments: boolean): Declaration | null;
+/**
+ * Extract variable statement (only exported ones for DTS)
+ */
+export declare function extractVariableStatement(node: VariableStatement, _sourceCode: string, sourceFile: SourceFile, keepComments: boolean): Declaration[];
+/**
+ * Extract interface declaration
+ */
+export declare function extractInterfaceDeclaration(node: InterfaceDeclaration, _sourceCode: string, sourceFile: SourceFile, keepComments: boolean): Declaration;
+/**
+ * Extract type alias declaration
+ */
+export declare function extractTypeAliasDeclaration(node: TypeAliasDeclaration, _sourceCode: string, sourceFile: SourceFile, keepComments: boolean): Declaration;
+/**
+ * Extract class declaration
+ */
+export declare function extractClassDeclaration(node: ClassDeclaration, _sourceCode: string, sourceFile: SourceFile, keepComments: boolean): Declaration;
+/**
+ * Extract enum declaration
+ */
+export declare function extractEnumDeclaration(node: EnumDeclaration, sourceCode: string, sourceFile: SourceFile, keepComments: boolean): Declaration;
+/**
+ * Extract module/namespace declaration
+ */
+export declare function extractModuleDeclaration(node: ModuleDeclaration, _sourceCode: string, sourceFile: SourceFile, keepComments: boolean): Declaration;
+/**
+ * Find types that are referenced in declarations but not imported or declared
+ */
+export declare function findReferencedTypes(declarations: Declaration[], _sourceCode: string): Set<string>;
+/**
+ * Extract declarations for referenced types by searching the entire source file
+ */
+export declare function extractReferencedTypeDeclarations(sourceFile: SourceFile, referencedTypes: Set<string>, sourceCode: string, keepComments?: boolean): Declaration[];

package/dist/extractor/directives.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Triple-slash directive extraction — NO TypeScript dependency.
+ * Pure string processing for maximum startup speed.
+ */
+/**
+ * Extract triple-slash directives from source code.
+ * These are special comments like /// <reference types="..." />
+ */
+export declare function extractTripleSlashDirectives(sourceCode: string): string[];

package/dist/extractor/extract.d.ts

@@ -0,0 +1,10 @@
+import type { Declaration } from '../types';
+/**
+ * Extract declarations using the fast string scanner (no TS parser).
+ * Results are cached by file path + keepComments flag.
+ */
+export declare function extractDeclarations(sourceCode: string, filePath: string, keepComments?: boolean, isolatedDeclarations?: boolean): Declaration[];
+/**
+ * Clear the declaration cache (for benchmarks and testing)
+ */
+export declare function clearDeclarationCache(): void;

package/dist/extractor/hash.d.ts

@@ -0,0 +1 @@
+export declare function hashContent(content: string): number | bigint;

package/dist/extractor/helpers.d.ts

@@ -0,0 +1,39 @@
+import type { FunctionDeclaration, Node, ParameterDeclaration, SourceFile } from 'typescript';
+/**
+ * Get the text of a node from source code
+ */
+export declare function getNodeText(node: Node, sourceCode: string, sf?: SourceFile): string;
+/**
+ * Extract JSDoc comments from a node
+ */
+export declare function extractJSDocComments(node: Node, sourceFile: SourceFile): string[];
+/**
+ * Get parameter name without default values for DTS
+ */
+export declare function getParameterName(param: ParameterDeclaration, sf?: SourceFile): string;
+/**
+ * Check if a node has export modifier
+ */
+export declare function hasExportModifier(node: Node): boolean;
+/**
+ * Check if a function has async modifier
+ */
+export declare function hasAsyncModifier(node: FunctionDeclaration): boolean;
+/**
+ * Check if a non-exported function should be included (e.g., if it's referenced by exported items)
+ */
+export declare function shouldIncludeNonExportedFunction(_functionName?: string, _sourceCode?: string): boolean;
+/**
+ * Check if a non-exported interface should be included (e.g., if it's used by exported items)
+ */
+export declare function shouldIncludeNonExportedInterface(interfaceName: string, sourceCode: string): boolean;
+/**
+ * Check if a type is a built-in TypeScript type
+ */
+export declare function isBuiltInType(typeName: string): boolean;
+/**
+ * Extract type names from module/namespace text
+ */
+export declare function extractTypesFromModuleText(moduleText: string): string[];
+// Re-exported from directives.ts for backward compatibility
+export { extractTripleSlashDirectives } from './directives';