refactor: simplify modules

Author: zoedsoupe

.github/workflows/ci.yml

@@ -36,7 +36,7 @@ jobs:
         run: npm run lint
 
       - name: Type check
-        run: npm run type-check
+        run: npm run type:check
 
   test:
     runs-on: ubuntu-latest

.github/workflows/publish.yml

@@ -34,7 +34,7 @@ jobs:
         run: npm run lint
 
       - name: Type check
-        run: npm run type-check
+        run: npm run type:check
 
       - name: Build project
         run: npm run build

src/core/types.ts src/core.tssrc/core/types.ts renamed to src/core.ts

@@ -1,8 +1,8 @@
 // src/index.ts
-export { extractSymbol, extractDocs, getSourcePath, formatOutput } from './extraction/typescript';
-export * from './core/types';
+export { extractSymbol, extractDocs, getSourcePath, formatOutput } from './resolution';
+export * from './core';
 
-import { extractDocs, getSourcePath, formatOutput } from './extraction/typescript';
+import { extractDocs, getSourcePath, formatOutput } from './resolution';
 
 export const TidewaveExtractor = {
   extractDocs,

src/core/analyzer.ts

@@ -1,7 +1,7 @@
 // src/extraction/typescript.ts
 import ts from 'typescript';
 import path from 'node:path';
-import type { ExtractionRequest, ExtractResult, ExtractorOptions, SymbolInfo } from '../core/types';
+import type { ExtractionRequest, ExtractResult, ExtractorOptions, SymbolInfo } from './core';
 
 // Load TypeScript configuration
 function loadTsConfig(tsConfigPath?: string): {
@@ -14,7 +14,7 @@ function loadTsConfig(tsConfigPath?: string): {
   let compilerOptions: ts.CompilerOptions = {
     target: ts.ScriptTarget.ES2020,
     module: ts.ModuleKind.CommonJS,
-    moduleResolution: ts.ModuleResolutionKind.NodeJs,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
     esModuleInterop: true,
     allowSyntheticDefaultImports: true,
     skipLibCheck: true,
@@ -71,18 +71,16 @@ function resolveModule(
   moduleName: string,
   compilerOptions: ts.CompilerOptions,
 ): { sourceFile: ts.SourceFile; program: ts.Program } | null {
-  // Use TypeScript's built-in module resolution
+  // First try normal module resolution
   const moduleResolver = ts.resolveModuleName(
     moduleName,
-    path.resolve('./index.ts'), // Use absolute path for containing file
+    path.resolve('./index.ts'),
     compilerOptions,
     ts.sys,
   );
 
   if (moduleResolver.resolvedModule) {
     const { resolvedFileName } = moduleResolver.resolvedModule;
-
-    // Create a dedicated program for this file like
     const dedicatedProgram = ts.createProgram([resolvedFileName], compilerOptions);
     const sourceFile = dedicatedProgram.getSourceFile(resolvedFileName);
 
@@ -94,6 +92,53 @@ function resolveModule(
   return null;
 }
 
+// Handle global symbols from lib.d.ts (like Math, console, etc.)
+function resolveGlobalSymbol(
+  symbolName: string,
+  compilerOptions: ts.CompilerOptions,
+): { sourceFile: ts.SourceFile; program: ts.Program; isGlobal: true } | null {
+  try {
+    // Create a minimal TypeScript file that references the global symbol
+    const virtualFileName = 'virtual-globals.ts';
+    const virtualContent = `// Global symbol reference\nconst _ref = ${symbolName};`;
+
+    // Create program with default host and proper lib files
+    const program = ts.createProgram(
+      [virtualFileName],
+      {
+        ...compilerOptions,
+        lib: compilerOptions.lib || ['lib.es2020.d.ts'],
+        skipLibCheck: false,
+        moduleResolution: ts.ModuleResolutionKind.NodeJs,
+      },
+      {
+        ...ts.createCompilerHost(compilerOptions),
+        getSourceFile: (fileName: string, languageVersion: ts.ScriptTarget) => {
+          if (fileName === virtualFileName) {
+            return ts.createSourceFile(virtualFileName, virtualContent, languageVersion, true);
+          }
+          // Use the default compiler host for everything else (including lib.d.ts files)
+          return ts.createCompilerHost(compilerOptions).getSourceFile(fileName, languageVersion);
+        },
+        fileExists: (fileName: string) => {
+          if (fileName === virtualFileName) return true;
+          return ts.createCompilerHost(compilerOptions).fileExists(fileName);
+        },
+      },
+    );
+
+    const sourceFile = program.getSourceFile(virtualFileName);
+    if (sourceFile) {
+      return { sourceFile, program, isGlobal: true };
+    }
+  } catch (error) {
+    // If global symbol resolution fails, return null
+    console.debug(`Failed to resolve global symbol ${symbolName}:`, error);
+  }
+
+  return null;
+}
+
 // Find symbol in JavaScript file
 function findSymbolInJavaScriptFile(
   sourceFile: ts.SourceFile,
@@ -334,45 +379,73 @@ export async function extractDocs(
 ): Promise<SymbolInfo | null> {
   try {
     const { module, symbol, member, isStatic } = parseModulePath(modulePath);
-
-    // Load config like
     const config = loadTsConfig(options.tsConfigPath);
 
-    // Resolve module with dedicated program like
-    const resolvedModule = resolveModule(module, config.options);
+    // Try to resolve as a regular module first
+    let resolvedModule = resolveModule(module, config.options);
+    let isGlobalModule = false;
+
+    // If regular module resolution fails, try as a global symbol
+    if (!resolvedModule) {
+      const globalResolution = resolveGlobalSymbol(module, config.options);
+      if (globalResolution) {
+        resolvedModule = globalResolution;
+        isGlobalModule = true;
+      }
+    }
+
     if (!resolvedModule) {
       throw new Error(`Module '${module}' not found`);
     }
 
     const { sourceFile, program } = resolvedModule;
     const checker = program.getTypeChecker();
-
-    // Get the module symbol
-    const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
     let targetSymbol: ts.Symbol | undefined;
 
-    if (moduleSymbol) {
-      // TypeScript module with proper exports
-      const exports = checker.getExportsOfModule(moduleSymbol);
-      targetSymbol = exports.find(exp => exp.getName() === symbol);
+    if (isGlobalModule) {
+      // For global modules, get the symbol from the global scope
+      const globalSymbols = checker.getSymbolsInScope(sourceFile, ts.SymbolFlags.Value);
+      targetSymbol = globalSymbols.find(s => s.getName() === module);
 
       if (!targetSymbol) {
-        throw new Error(
-          `Symbol '${symbol}' not found in module '${module}'. Available exports: ${exports
-            .map(e => e.getName())
-            .join(', ')}`,
-        );
+        // Try getting it from the AST node directly
+        const [identifierNode] = sourceFile.statements;
+        if (ts.isVariableStatement(identifierNode)) {
+          const [declaration] = identifierNode.declarationList.declarations;
+          if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
+            targetSymbol = checker.getSymbolAtLocation(declaration.initializer);
+          }
+        }
       }
     } else {
-      // JavaScript file - look for symbols in statements
-      targetSymbol = findSymbolInJavaScriptFile(sourceFile, checker, symbol);
+      // Regular module handling
+      const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
 
-      if (!targetSymbol) {
-        throw new Error(`Symbol '${symbol}' not found in JavaScript module '${module}'`);
+      if (moduleSymbol) {
+        const exports = checker.getExportsOfModule(moduleSymbol);
+        targetSymbol = exports.find(exp => exp.getName() === symbol);
+
+        if (!targetSymbol) {
+          throw new Error(
+            `Symbol '${symbol}' not found in module '${module}'. Available exports: ${exports
+              .map(e => e.getName())
+              .join(', ')}`,
+          );
+        }
+      } else {
+        // JavaScript file - look for symbols in statements
+        targetSymbol = findSymbolInJavaScriptFile(sourceFile, checker, symbol);
+
+        if (!targetSymbol) {
+          throw new Error(`Symbol '${symbol}' not found in JavaScript module '${module}'`);
+        }
       }
     }
 
-    // Get symbol info like
+    if (!targetSymbol) {
+      throw new Error(`Symbol '${isGlobalModule ? module : symbol}' not found`);
+    }
+
     const result = getSymbolInfo(checker, targetSymbol, member, isStatic);
     return result;
   } catch (error) {

src/core/extractor.ts

@@ -0,0 +1,40 @@
+/**
+ * A simple test function for JavaScript support
+ * @param {string} name - The name to greet
+ * @returns {string} A greeting message
+ */
+function greetUser(name) {
+  return `Hello, ${name}!`;
+}
+
+/**
+ * A test class with JSDoc
+ */
+class TestClass {
+  /**
+   * Constructor for TestClass
+   * @param {number} value - Initial value
+   */
+  constructor(value) {
+    this.value = value;
+  }
+
+  /**
+   * Get the current value
+   * @returns {number} The current value
+   */
+  getValue() {
+    return this.value;
+  }
+
+  /**
+   * Static method to create a new instance
+   * @param {number} value - The value to use
+   * @returns {TestClass} A new TestClass instance
+   */
+  static create(value) {
+    return new TestClass(value);
+  }
+}
+
+module.exports = { greetUser, TestClass };