chore: several improvements

Author: chrisbbreuer

.gitignore

@@ -17,3 +17,4 @@ fixtures/generated
 /test/temp-output
 test/debug
 /test/fixtures/generated
+/pantry

packages/dtsx/.test-cli/docs-test/api-docs/API.md

@@ -1,6 +1,6 @@
 # API Documentation
 
-> Generated on 2025-11-30T12:48:29.571Z
+> Generated on 2026-02-08T21:09:35.476Z
 
 ## Table of Contents
 

packages/dtsx/src/cache.ts

@@ -130,15 +130,30 @@ export class BuildCache {
    * Check if a file needs to be regenerated
    */
   needsRegeneration(filePath: string, cwd: string): boolean {
+    return this.getCachedIfValid(filePath, cwd) === null
+  }
+
+  /**
+   * Get cached content for a file
+   */
+  getCached(filePath: string, cwd: string): string | null {
+    return this.getCachedIfValid(filePath, cwd)
+  }
+
+  /**
+   * Get cached DTS content if the cache entry is still valid, or null if regeneration is needed.
+   * Combines cache validation and retrieval in a single operation.
+   */
+  getCachedIfValid(filePath: string, cwd: string): string | null {
     if (!this.manifest) {
-      return true
+      return null
     }
 
     const relativePath = relative(cwd, filePath)
     const entry = this.manifest.entries[relativePath]
 
     if (!entry) {
-      return true
+      return null
     }
 
     try {
@@ -152,37 +167,19 @@ export class BuildCache {
         const hash = this.hashContent(content)
 
         if (hash !== entry.sourceHash) {
-          return true
+          return null
         }
 
         // Hash matches despite mtime change (e.g., touched file)
         // Update mtime in cache
         entry.sourceMtime = mtime
       }
 
-      return false
+      return entry.dtsContent
     }
     catch {
-      return true
-    }
-  }
-
-  /**
-   * Get cached content for a file
-   */
-  getCached(filePath: string, cwd: string): string | null {
-    if (!this.manifest) {
       return null
     }
-
-    const relativePath = relative(cwd, filePath)
-    const entry = this.manifest.entries[relativePath]
-
-    if (!entry) {
-      return null
-    }
-
-    return entry.dtsContent
   }
 
   /**

packages/dtsx/src/compat.ts

@@ -263,31 +263,3 @@ export function getRuntimeInfo(): RuntimeInfo {
   }
 }
 
-/**
- * Namespace export for drop-in Bun API replacement
- */
-export const compat: {
-  file: typeof file
-  write: typeof write
-  spawn: typeof spawnProcess
-  readTextFile: typeof readTextFile
-  writeTextFile: typeof writeTextFile
-  fileExists: typeof fileExists
-  getRuntimeInfo: typeof getRuntimeInfo
-  runtime: typeof runtime
-  isBun: typeof isBun
-  isNode: typeof isNode
-} = {
-  file,
-  write,
-  spawn: spawnProcess,
-  readTextFile,
-  writeTextFile,
-  fileExists,
-  getRuntimeInfo,
-  runtime,
-  isBun,
-  isNode,
-}
-
-export default compat

packages/dtsx/src/extractor/builders.ts

@@ -311,17 +311,6 @@ function isPrivateMemberName(member: { name?: import('typescript').PropertyName
   return member.name ? isPrivateIdentifier(member.name) : false
 }
 
-/**
- * Check if a property name is a symbol expression (Symbol.iterator, etc.)
- */
-function _isSymbolPropertyName(member: { name?: import('typescript').PropertyName }): boolean {
-  if (!member.name)
-    return false
-  const text = member.name.getText()
-  // Check for [Symbol.xxx] pattern
-  return text.startsWith('[Symbol.') || text.startsWith('[customSymbol')
-}
-
 /**
  * Get the property name text, handling computed properties and symbols
  */

packages/dtsx/src/extractor/cache.ts

@@ -59,20 +59,25 @@ export function hashContent(content: string): number {
 }
 
 /**
- * Evict oldest entries if cache exceeds max size
+ * 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 function evictOldestEntries(): void {
   if (sourceFileCache.size <= MAX_CACHE_SIZE) {
     return
   }
 
-  // Sort by last access time and remove oldest entries
-  const entries = Array.from(sourceFileCache.entries())
-    .sort((a, b) => a[1].lastAccess - b[1].lastAccess)
-
-  const toRemove = entries.slice(0, entries.length - MAX_CACHE_SIZE)
-  for (const [key] of toRemove) {
-    sourceFileCache.delete(key)
+  // Find the oldest entry by last access time
+  let oldestKey: string | null = null
+  let oldestTime = Infinity
+  for (const [key, entry] of sourceFileCache) {
+    if (entry.lastAccess < oldestTime) {
+      oldestTime = entry.lastAccess
+      oldestKey = key
+    }
+  }
+  if (oldestKey) {
+    sourceFileCache.delete(oldestKey)
   }
 }
 

packages/dtsx/src/extractor/declarations.ts

@@ -34,16 +34,20 @@ export function extractImportDeclaration(node: ImportDeclaration, sourceCode: st
 /**
  * Extract export declaration
  */
-export function extractExportDeclaration(node: ExportDeclaration, sourceCode: string): Declaration {
+export function extractExportDeclaration(node: ExportDeclaration, sourceCode: string, sourceFile?: SourceFile, keepComments: boolean = false): Declaration {
   const text = getNodeText(node, sourceCode)
   const isTypeOnly = !!node.isTypeOnly
 
+  // Extract comments if enabled and sourceFile is available
+  const leadingComments = keepComments && sourceFile ? extractJSDocComments(node, sourceFile) : undefined
+
   return {
     kind: 'export',
     name: '', // Export declarations don't have a single name
     text,
     isExported: true,
     isTypeOnly,
+    leadingComments,
     source: node.moduleSpecifier?.getText().slice(1, -1), // Remove quotes if present
     start: node.getStart(),
     end: node.getEnd(),
@@ -53,15 +57,19 @@ export function extractExportDeclaration(node: ExportDeclaration, sourceCode: st
 /**
  * Extract export assignment (export default)
  */
-export function extractExportAssignment(node: ExportAssignment, sourceCode: string): Declaration {
+export function extractExportAssignment(node: ExportAssignment, sourceCode: string, sourceFile?: SourceFile, keepComments: boolean = false): Declaration {
   const text = getNodeText(node, sourceCode)
 
+  // Extract comments if enabled and sourceFile is available
+  const leadingComments = keepComments && sourceFile ? extractJSDocComments(node, sourceFile) : undefined
+
   return {
     kind: 'export',
     name: 'default',
     text,
     isExported: true,
     isTypeOnly: false,
+    leadingComments,
     start: node.getStart(),
     end: node.getEnd(),
   }
@@ -170,16 +178,6 @@ function isAsConstAssertion(node: import('typescript').Expression): boolean {
   return false
 }
 
-/**
- * Get the underlying expression from an 'as const' assertion
- */
-function _getAsConstValue(node: import('typescript').Expression): import('typescript').Expression | null {
-  if (isAsExpression(node) && isAsConstAssertion(node)) {
-    return node.expression
-  }
-  return null
-}
-
 /**
  * Infer a literal type from a value for 'as const' declarations
  * This creates readonly types for objects and arrays
@@ -491,7 +489,7 @@ export function findReferencedTypes(declarations: Declaration[], _sourceCode: st
 /**
  * Extract declarations for referenced types by searching the entire source file
  */
-export function extractReferencedTypeDeclarations(sourceFile: SourceFile, referencedTypes: Set<string>, sourceCode: string): Declaration[] {
+export function extractReferencedTypeDeclarations(sourceFile: SourceFile, referencedTypes: Set<string>, sourceCode: string, keepComments: boolean = true): Declaration[] {
   const additionalDeclarations: Declaration[] = []
 
   if (referencedTypes.size === 0) {
@@ -505,7 +503,7 @@ export function extractReferencedTypeDeclarations(sourceFile: SourceFile, refere
         const interfaceNode = node as InterfaceDeclaration
         const interfaceName = interfaceNode.name.getText()
         if (referencedTypes.has(interfaceName)) {
-          const decl = extractInterfaceDeclaration(interfaceNode, sourceCode, sourceFile, false) // Don't extract comments for referenced types
+          const decl = extractInterfaceDeclaration(interfaceNode, sourceCode, sourceFile, keepComments)
           additionalDeclarations.push(decl)
           referencedTypes.delete(interfaceName) // Remove to avoid duplicates
         }
@@ -516,7 +514,7 @@ export function extractReferencedTypeDeclarations(sourceFile: SourceFile, refere
         const typeNode = node as TypeAliasDeclaration
         const typeName = typeNode.name.getText()
         if (referencedTypes.has(typeName)) {
-          const decl = extractTypeAliasDeclaration(typeNode, sourceCode, sourceFile, false) // Don't extract comments for referenced types
+          const decl = extractTypeAliasDeclaration(typeNode, sourceCode, sourceFile, keepComments)
           additionalDeclarations.push(decl)
           referencedTypes.delete(typeName)
         }
@@ -528,7 +526,7 @@ export function extractReferencedTypeDeclarations(sourceFile: SourceFile, refere
         if (classNode.name) {
           const className = classNode.name.getText()
           if (referencedTypes.has(className)) {
-            const decl = extractClassDeclaration(classNode, sourceCode, sourceFile, false) // Don't extract comments for referenced types
+            const decl = extractClassDeclaration(classNode, sourceCode, sourceFile, keepComments)
             additionalDeclarations.push(decl)
             referencedTypes.delete(className)
           }
@@ -540,7 +538,7 @@ export function extractReferencedTypeDeclarations(sourceFile: SourceFile, refere
         const enumNode = node as EnumDeclaration
         const enumName = enumNode.name.getText()
         if (referencedTypes.has(enumName)) {
-          const decl = extractEnumDeclaration(enumNode, sourceCode, sourceFile, false) // Don't extract comments for referenced types
+          const decl = extractEnumDeclaration(enumNode, sourceCode, sourceFile, keepComments)
           additionalDeclarations.push(decl)
           referencedTypes.delete(enumName)
         }