@stacksjs/dtsx 0.9.9 → 0.9.11

package/dist/transformers.d.ts

@@ -0,0 +1,173 @@
+import type { Declaration, DeclarationKind, ParameterDeclaration } from './types';
+import type { Plugin } from './plugins';
+/**
+ * Create a new declaration with defaults
+ */
+export declare function createDeclaration(kind: DeclarationKind, name: string, text: string, options?: Partial<Omit<Declaration, 'kind' | 'name' | 'text'>>): Declaration;
+/**
+ * Clone a declaration (deep copy)
+ */
+export declare function cloneDeclaration(decl: Declaration): Declaration;
+/**
+ * Walk declarations with a visitor
+ */
+export declare function walkDeclarations(declarations: Declaration[], visitor: DeclarationVisitor, parent?: Declaration | null): void;
+/**
+ * Find declarations matching a predicate
+ */
+export declare function findDeclarations(declarations: Declaration[], predicate: (decl: Declaration) => boolean): Declaration[];
+/**
+ * Map declarations with a transformer
+ */
+export declare function mapDeclarations(declarations: Declaration[], transformer: Transformer, context: Omit<TransformerContext, 'index' | 'total' | 'allDeclarations'>): Promise<Declaration[]>;
+/**
+ * Compose multiple transformers into one
+ */
+export declare function composeTransformers(...transformers: Transformer[]): Transformer;
+/**
+ * Create a transformer that only applies to specific declaration kinds
+ */
+export declare function filterByKind(kinds: DeclarationKind | DeclarationKind[], transformer: Transformer): Transformer;
+/**
+ * Create a transformer that only applies when a predicate is true
+ */
+export declare function filterByPredicate(predicate: (decl: Declaration) => boolean, transformer: Transformer): Transformer;
+/**
+ * Create a transformer plugin from transformers
+ */
+export declare function createTransformerPlugin(options: {
+  name: string
+  version?: string
+  description?: string
+  /** Transform source code before parsing */
+  beforeParse?: TextTransformer
+  /** Transform declarations */
+  transform?: Transformer
+  /** Transform generated .d.ts content after generation */
+  afterGenerate?: TextTransformer
+}): Plugin;
+/**
+ * Rename declarations matching a pattern
+ */
+export declare function createRenameTransformer(pattern: string | RegExp, replacement: string | ((_match: string, _decl: Declaration) => string)): Transformer;
+/**
+ * Add a prefix to declaration names
+ */
+export declare function createPrefixTransformer(prefix: string, filter?: (decl: Declaration) => boolean): Transformer;
+/**
+ * Add a suffix to declaration names
+ */
+export declare function createSuffixTransformer(suffix: string, filter?: (decl: Declaration) => boolean): Transformer;
+/**
+ * Remove declarations by name pattern
+ */
+export declare function createRemoveTransformer(pattern: string | RegExp | ((_decl: Declaration) => boolean)): Transformer;
+/**
+ * Add JSDoc comments to declarations
+ */
+export declare function createJSDocTransformer(getJSDoc: (decl: Declaration) => string | string[] | null | undefined): Transformer;
+/**
+ * Modify type annotations
+ */
+export declare function createTypeTransformer(transformer: (type: string, decl: Declaration) => string | null | undefined): Transformer;
+/**
+ * Modify return types of functions
+ */
+export declare function createReturnTypeTransformer(transformer: (returnType: string, decl: Declaration) => string | null | undefined): Transformer;
+/**
+ * Transform function parameters
+ */
+export declare function createParameterTransformer(transformer: (
+    params: ParameterDeclaration[],
+    decl: Declaration,
+  ) => ParameterDeclaration[] | null | undefined): Transformer;
+/**
+ * Add modifiers (export, declare, etc.)
+ */
+export declare function createModifierTransformer(modifier: string, filter?: (decl: Declaration) => boolean): Transformer;
+/**
+ * Strip specific JSDoc tags
+ */
+export declare function createStripTagsTransformer(tags: string[]): Transformer;
+/**
+ * Wrap types in a utility type
+ */
+export declare function createWrapTypeTransformer(utilityType: string, filter?: (decl: Declaration) => boolean): Transformer;
+/**
+ * Plugin that prefixes all exported types with a namespace
+ */
+export declare function createNamespacePrefixPlugin(namespace: string): Plugin;
+/**
+ * Plugin that makes all interface properties readonly
+ */
+export declare const readonlyPlugin: Plugin;
+/**
+ * Plugin that strips @internal, @private, and @hidden tags
+ */
+export declare const stripPrivatePlugin: Plugin;
+/**
+ * Plugin that adds 'declare' keyword to all declarations
+ */
+export declare const declarePlugin: Plugin;
+/**
+ * Context available to transformers
+ */
+export declare interface TransformerContext {
+  filePath: string
+  sourceCode: string
+  index: number
+  total: number
+  allDeclarations: readonly Declaration[]
+  createDeclaration: typeof createDeclaration
+  cloneDeclaration: typeof cloneDeclaration
+  modifyText: (decl: Declaration, text: string) => Declaration
+  addModifier: (decl: Declaration, modifier: string) => Declaration
+  removeModifier: (decl: Declaration, modifier: string) => Declaration
+}
+/**
+ * Context for text transformers
+ */
+export declare interface TextTransformerContext {
+  filePath: string
+  phase: 'before' | 'after'
+}
+/**
+ * Visitor pattern for walking declaration trees
+ */
+export declare interface DeclarationVisitor {
+  enter?: (decl: Declaration, parent: Declaration | null) => void
+  leave?: (decl: Declaration, parent: Declaration | null) => void
+  function?: (_decl: Declaration, _parent: Declaration | null) => void
+  variable?: (decl: Declaration, parent: Declaration | null) => void
+  interface?: (decl: Declaration, parent: Declaration | null) => void
+  type?: (decl: Declaration, parent: Declaration | null) => void
+  class?: (decl: Declaration, parent: Declaration | null) => void
+  enum?: (decl: Declaration, parent: Declaration | null) => void
+  import?: (decl: Declaration, parent: Declaration | null) => void
+  export?: (decl: Declaration, parent: Declaration | null) => void
+  module?: (decl: Declaration, parent: Declaration | null) => void
+  namespace?: (decl: Declaration, parent: Declaration | null) => void
+  unknown?: (decl: Declaration, parent: Declaration | null) => void
+}
+/**
+ * Result of a transformer, can be:
+ * - Declaration: replaced declaration
+ * - Declaration[]: multiple declarations (split)
+ * - null: remove the declaration
+ * - undefined: no change
+ */
+export type TransformResult = Declaration | Declaration[] | null | undefined;
+/**
+ * Transformer function that operates on a single declaration
+ */
+export type Transformer = (
+  declaration: Declaration,
+  context: TransformerContext,
+) => TransformResult | Promise<TransformResult>;
+/**
+ * Text transformer operates on the raw text before/after processing
+ */
+export type TextTransformer = (
+  content: string,
+  context: TextTransformerContext,
+) => string | Promise<string>;

package/dist/tree-shaker.d.ts

@@ -0,0 +1,69 @@
+import type { Declaration, DeclarationKind } from './types';
+/**
+ * Shake unused declarations from the tree
+ */
+export declare function treeShake(declarations: Declaration[], config?: TreeShakeConfig): TreeShakeResult;
+/**
+ * Build a declaration dependency graph for tree shaking
+ */
+export declare function buildDeclarationDependencyGraph(declarations: Declaration[]): Map<string, Set<string>>;
+/**
+ * Extract type references from a declaration
+ */
+export declare function extractTypeReferences(decl: Declaration): Set<string>;
+/**
+ * Tree shake content string
+ */
+export declare function treeShakeContent(content: string, config?: TreeShakeConfig): { content: string, removed: string[] };
+/**
+ * Get unused declarations (those that could be removed)
+ */
+export declare function findUnusedDeclarations(declarations: Declaration[], config?: Omit<TreeShakeConfig, 'debug'>): string[];
+/**
+ * Analyze dependencies for a declaration
+ */
+export declare function analyzeDependencies(declarationName: string, declarations: Declaration[]): {
+    directDependencies: string[]
+    transitiveDependencies: string[]
+    dependents: string[]
+  };
+/**
+ * Create a tree shaker with preset configuration
+ */
+export declare function createTreeShaker(config?: TreeShakeConfig): {
+  shake: (declarations: Declaration[]) => TreeShakeResult
+  shakeContent: (content: string) => { content: string, removed: string[] }
+  findUnused: (declarations: Declaration[]) => string[]
+  analyzeDependencies: (name: string, declarations: Declaration[]) => { directDependencies: string[], transitiveDependencies: string[], dependents: string[] }
+  buildGraph: typeof buildDeclarationDependencyGraph
+  extractRefs: typeof extractTypeReferences
+};
+/**
+ * Tree shaking configuration
+ */
+export declare interface TreeShakeConfig {
+  entryPoints?: string[]
+  keepExported?: boolean
+  keep?: (string | RegExp)[]
+  remove?: (string | RegExp)[]
+  shakableKinds?: DeclarationKind[]
+  debug?: boolean
+}
+/**
+ * Result of tree shaking
+ */
+export declare interface TreeShakeResult {
+  declarations: Declaration[]
+  removed: string[]
+  dependencyGraph: Map<string, Set<string>>
+  stats: TreeShakeStats
+}
+/**
+ * Tree shaking statistics
+ */
+export declare interface TreeShakeStats {
+  totalBefore: number
+  totalAfter: number
+  removedCount: number
+  reductionPercent: number
+}

package/dist/type-mappings.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Get preset mappings
+ */
+export declare function getPresetMappings(preset: TypeMappingPreset): TypeMappingRule[];
+/**
+ * Create a type mapper with configuration
+ */
+export declare function createTypeMapper(config?: TypeMappingConfig): TypeMapper;
+/**
+ * Apply type mappings to declaration text
+ */
+export declare function applyTypeMappings(declarationText: string, mapper: TypeMapper, context?: Partial<TypeMappingContext>): string;
+/**
+ * Default type mapper instance
+ */
+export declare const defaultTypeMapper: TypeMapper;
+/**
+ * Strict type mapper instance
+ */
+export declare const strictTypeMapper: TypeMapper;
+/**
+ * Built-in type transformers
+ * @defaultValue
+ * ```ts
+ * {
+ *   makeReadonly: (type: string) => any,
+ *   makeNullable: (type: string) => any,
+ *   makeOptional: (type: string) => any,
+ *   makeRequired: (type: string) => any,
+ *   promisify: (type: string) => any,
+ *   unpromisify: (type: string) => any,
+ *   arrayify: (type: string) => any,
+ *   unarrayify: (type: string) => any
+ * }
+ * ```
+ */
+export declare const TypeTransformers: {
+  /**
+   * Make all types readonly
+   */
+  makeReadonly: (type: string) => any;
+  /**
+   * Make type nullable
+   */
+  makeNullable: (type: string) => any;
+  /**
+   * Make type optional (add undefined)
+   */
+  makeOptional: (type: string) => any;
+  /**
+   * Remove null/undefined from type
+   */
+  makeRequired: (type: string) => any;
+  /**
+   * Wrap in Promise
+   */
+  promisify: (type: string) => any;
+  /**
+   * Unwrap Promise
+   */
+  unpromisify: (type: string) => any;
+  /**
+   * Convert to array type
+   */
+  arrayify: (type: string) => any;
+  /**
+   * Unwrap array type
+   */
+  unarrayify: (type: string) => any
+};
+/**
+ * Custom type mappings for DTS generation
+ * Allows users to specify type replacements and transformations
+ */
+/**
+ * Type mapping rule
+ */
+export declare interface TypeMappingRule {
+  pattern: string | RegExp
+  replacement: string
+  condition?: (context: TypeMappingContext) => boolean
+  global?: boolean
+  priority?: number
+}
+/**
+ * Context passed to type mapping functions
+ */
+export declare interface TypeMappingContext {
+  type: string
+  declarationName?: string
+  declarationKind?: string
+  filePath?: string
+  isReturnType?: boolean
+  isParameterType?: boolean
+  isPropertyType?: boolean
+}
+/**
+ * Type mapping configuration
+ */
+export declare interface TypeMappingConfig {
+  rules: TypeMappingRule[]
+  presets?: TypeMappingPreset[]
+  includeDefaults?: boolean
+}
+/**
+ * Available type mapping presets
+ */
+export type TypeMappingPreset = | 'strict' // Convert 'any' to 'unknown'
+  | 'readonly' // Add readonly to array types
+  | 'nullable' // Convert undefined unions to optional
+  | 'branded' // Use branded types for primitives
+  | 'simplified' // Simplify complex utility types;
+/**
+ * Type mapper class for applying transformations
+ */
+export declare class TypeMapper {
+  constructor(config?: TypeMappingConfig);
+  map(type: string, context?: Partial<TypeMappingContext>): string;
+  mapAll(types: string[], context?: Partial<TypeMappingContext>): string[];
+  addRule(rule: TypeMappingRule): void;
+  removeRules(pattern: string | RegExp): number;
+  clearCache(): void;
+  getRules(): readonly TypeMappingRule[];
+}

package/dist/types.d.ts

@@ -13,6 +13,131 @@ export declare interface DtsGenerationConfig {
   tsconfigPath: string
   verbose: boolean | string[]
   outputStructure?: 'mirror' | 'flat'
+  importOrder?: string[]
+  dryRun?: boolean
+  stats?: boolean
+  continueOnError?: boolean
+  logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent'
+  exclude?: string[]
+  outputFormat?: 'text' | 'json'
+  progress?: boolean
+  diff?: boolean
+  validate?: boolean
+  watch?: boolean
+  parallel?: boolean
+  concurrency?: number
+  declarationMap?: boolean
+  plugins?: import('./plugins').Plugin[]
+  bundle?: boolean
+  bundleOutput?: string
+  incremental?: boolean
+  clearCache?: boolean
+  indentStyle?: 'spaces' | 'tabs'
+  indentSize?: number
+  prettier?: boolean
+  include?: string[]
+  isolatedDeclarations?: boolean
+  typeMappings?: import('./type-mappings').TypeMappingConfig
+  lineEnding?: 'lf' | 'crlf' | 'auto'
+  normalizeOutput?: boolean
+  declarationOrder?: {
+    kinds?: import('./types').DeclarationKind[]
+    alphabetize?: boolean
+    groupExports?: boolean
+  }
+  tracking?: TrackingConfig
+  profiling?: ProfilingConfig
+  typeInference?: TypeInferenceConfig
+  typeChecking?: TypeCheckingConfig
+  typeValidation?: TypeValidationConfig
+}
+/**
+ * Tracking configuration for debugging type and import usage
+ */
+export declare interface TrackingConfig {
+  types?: boolean
+  relationships?: boolean
+  usage?: boolean
+  imports?: boolean
+  importUsage?: boolean
+  importRelationships?: boolean
+}
+/**
+ * Profiling configuration for performance analysis
+ */
+export declare interface ProfilingConfig {
+  memory?: boolean
+  memoryLimit?: number
+  cpu?: boolean
+  samplingInterval?: number
+  io?: boolean
+  trackOperations?: ('read' | 'write')[]
+  outputFile?: string
+}
+/**
+ * Type inference configuration
+ */
+export declare interface TypeInferenceConfig {
+  enabled?: boolean
+  strictness?: 'loose' | 'normal' | 'strict'
+  inferReturnTypes?: boolean
+  inferConstTypes?: boolean
+}
+/**
+ * Type checking configuration
+ */
+export declare interface TypeCheckingConfig {
+  enabled?: boolean
+  strictness?: 'loose' | 'normal' | 'strict'
+  warningsAsErrors?: boolean
+  maxErrors?: number
+}
+/**
+ * Type validation configuration
+ */
+export declare interface TypeValidationConfig {
+  enabled?: boolean
+  rules?: {
+    noAny?: boolean
+    noUnknown?: boolean
+    noImplicitAny?: boolean
+    explicitReturnTypes?: boolean
+    explicitParameterTypes?: boolean
+  }
+}
+/**
+ * Source location for error reporting
+ */
+export declare interface SourceLocation {
+  line: number
+  column: number
+  offset?: number
+}
+/**
+ * Detailed error information with source location
+ */
+export declare interface DtsError {
+  file: string
+  message: string
+  code?: string
+  location?: SourceLocation
+  stack?: string
+  suggestion?: string
+}
+/**
+ * Generation statistics
+ */
+export declare interface GenerationStats {
+  filesProcessed: number
+  filesGenerated: number
+  filesFailed: number
+  filesValidated: number
+  validationErrors: number
+  declarationsFound: number
+  importsProcessed: number
+  exportsProcessed: number
+  durationMs: number
+  errors: DtsError[]
 }
 /**
  * Declaration
@@ -20,7 +145,7 @@ export declare interface DtsGenerationConfig {
  * Represents a parsed declaration from TypeScript source
  */
 export declare interface Declaration {
-  kind: 'function' | 'variable' | 'interface' | 'type' | 'class' | 'enum' | 'import' | 'export' | 'module'
+  kind: DeclarationKind
   name: string
   text: string
   leadingComments?: string[]
@@ -34,10 +159,11 @@ export declare interface Declaration {
   members?: Declaration[]
   parameters?: ParameterDeclaration[]
   returnType?: string
-  value?: any
+  value?: unknown
   source?: string
   specifiers?: ImportSpecifier[]
   isTypeOnly?: boolean
+  isSideEffect?: boolean
   isAsync?: boolean
   isGenerator?: boolean
   overloads?: string[]
@@ -71,19 +197,23 @@ export declare interface ProcessingContext {
   filePath: string
   sourceCode: string
   declarations: Declaration[]
-  imports: Map<string, Set<string>>
-  exports: Set<string>
-  usedTypes: Set<string>
+  imports?: Map<string, Set<string>>
+  exports?: Set<string>
+  usedTypes?: Set<string>
 }
 /**
  * DtsGenerationOption
  *
  * This is the configuration object for the DTS generation process.
  */
-export type DtsGenerationOption = Partial<DtsGenerationConfig>
+export type DtsGenerationOption = Partial<DtsGenerationConfig>;
 /**
  * DtsGenerationOptions
  *
  * This is the configuration object for the DTS generation process.
  */
-export type DtsGenerationOptions = DtsGenerationOption | DtsGenerationOption[]
+export type DtsGenerationOptions = DtsGenerationOption | DtsGenerationOption[];
+/**
+ * Declaration kind - all possible declaration types
+ */
+export type DeclarationKind = 'function' | 'variable' | 'interface' | 'type' | 'class' | 'enum' | 'import' | 'export' | 'module' | 'namespace' | 'unknown';

package/dist/utils.d.ts

@@ -1,5 +1,57 @@
 import type { DtsGenerationConfig } from './types';
+/**
+ * Exhaustive check helper for switch statements
+ * This function should never be called if all cases are handled
+ * TypeScript will error if a case is missing
+ */
+export declare function assertNever(value: never, message?: string): never;
 export declare function writeToFile(filePath: string, content: string): Promise<void>;
 export declare function getAllTypeScriptFiles(directory?: string): Promise<string[]>;
 // only checks for 2 potentially nested levels
-export declare function checkIsolatedDeclarations(options?: DtsGenerationConfig): Promise<boolean>;
+export declare function checkIsolatedDeclarationsConfig(options?: DtsGenerationConfig): Promise<boolean>;
+/**
+ * Validate a .d.ts file content against TypeScript compiler
+ */
+export declare function validateDtsContent(content: string, filename: string): ValidationResult;
+/**
+ * Simple line-by-line diff between two strings
+ * Returns formatted diff output with +/- prefixes
+ */
+export declare function createDiff(oldContent: string, newContent: string, filename: string): string;
+/**
+ * Generate a simple source map for a declaration file
+ * This creates a basic 1:1 mapping since we're doing declaration extraction
+ */
+export declare function generateDeclarationMap(dtsContent: string, dtsFilename: string, sourceFilename: string, sourceContent: string): DeclarationSourceMap;
+/**
+ * Add source map URL comment to declaration content
+ */
+export declare function addSourceMapComment(dtsContent: string, mapFilename: string): string;
+/**
+ * Validation error details
+ */
+export declare interface ValidationError {
+  line: number
+  column: number
+  message: string
+  code?: string
+  suggestion?: string
+}
+/**
+ * Validation result for a .d.ts file
+ */
+export declare interface ValidationResult {
+  isValid: boolean
+  errors: ValidationError[]
+}
+/**
+ * Source map for declaration files
+ */
+export declare interface DeclarationSourceMap {
+  version: 3
+  file: string
+  sourceRoot: string
+  sources: string[]
+  sourcesContent: string[]
+  mappings: string
+}

package/dist/watcher.d.ts

@@ -0,0 +1,64 @@
+import type { DtsGenerationConfig } from './types';
+/**
+ * Create a file watcher for .d.ts generation
+ */
+export declare function createWatcher(config: WatchConfig, buildFn: (files?: string[]) => Promise<WatchBuildResult>): Watcher;
+/**
+ * Watch and generate .d.ts files
+ */
+export declare function watchAndGenerate(config: DtsGenerationConfig & WatchConfig, generator: (config: DtsGenerationConfig) => Promise<{ filesProcessed: number, errors: string[] }>): Promise<Watcher>;
+/**
+ * Format watch build result for display
+ */
+export declare function formatWatchResult(result: WatchBuildResult): string;
+/**
+ * Create a simple console logger for watch mode
+ */
+export declare function createWatchLogger(): {
+  onChange: (event: WatchEvent) => void
+  onBuildStart: () => void
+  onBuildComplete: (result: WatchBuildResult) => void
+  onError: (error: Error) => void
+};
+/**
+ * Watch configuration
+ */
+export declare interface WatchConfig {
+  root: string
+  include?: string[]
+  exclude?: string[]
+  debounce?: number
+  initialBuild?: boolean
+  clearScreen?: boolean
+  onChange?: (event: WatchEvent) => void | Promise<void>
+  onBuildStart?: () => void | Promise<void>
+  onBuildComplete?: (result: WatchBuildResult) => void | Promise<void>
+  onError?: (error: Error) => void | Promise<void>
+}
+/**
+ * Watch event
+ */
+export declare interface WatchEvent {
+  type: 'add' | 'change' | 'unlink'
+  path: string
+  relativePath: string
+}
+/**
+ * Build result from watch
+ */
+export declare interface WatchBuildResult {
+  success: boolean
+  duration: number
+  filesProcessed: number
+  errors: string[]
+}
+/**
+ * Watcher instance
+ */
+export declare interface Watcher {
+  start: () => Promise<void>
+  stop: () => void
+  rebuild: () => Promise<WatchBuildResult>
+  isWatching: () => boolean
+  getWatchedFiles: () => string[]
+}