Support namespaces/files in get_docs (#52)

And it includes a list of all exports.

Author: josevalim

README.md

@@ -317,6 +317,7 @@ Here are some examples:
 
 ```bash
 # Local TypeScript/JavaScript files
+npx tidewave docs ./src/utils
 npx tidewave docs ./src/utils:formatDate
 npx tidewave docs ./components:Button#onClick
 

src/core.ts

@@ -27,7 +27,7 @@ export interface InternalResolvedModule {
 
 export interface ExtractionRequest {
   readonly module: string;
-  readonly symbol: string;
+  readonly symbol?: string;
   readonly member?: string;
   readonly isStatic?: boolean;
 }
@@ -42,6 +42,20 @@ export interface SymbolInfo {
   readonly jsDoc?: string;
 }
 
+export interface ExportSummary {
+  readonly name: string;
+  readonly kind: string;
+  readonly line: number;
+  readonly documentation?: string;
+}
+
+export interface FileInfo {
+  readonly path: string;
+  readonly overview?: string;
+  readonly exportCount: number;
+  readonly exports: ExportSummary[];
+}
+
 export interface ExtractorOptions {
   readonly prefix?: string;
 }
@@ -83,7 +97,7 @@ export interface EvaluatedModuleResult {
 }
 
 export type ResolveResult = ResolvedModule | ResolveError;
-export type ExtractResult = SymbolInfo | ExtractError;
+export type ExtractResult = SymbolInfo | FileInfo | ExtractError;
 export type InternalResolveResult = InternalResolvedModule | ResolveError;
 
 export function isResolveError(
@@ -96,6 +110,10 @@ export function isExtractError(result: ExtractResult): result is ExtractError {
   return result != null && 'error' in result;
 }
 
+export function isFileInfo(result: ExtractResult): result is FileInfo {
+  return result != null && 'exports' in result && Array.isArray((result as FileInfo).exports);
+}
+
 export function resolveError(
   specifier: ModuleRequest['specifier'],
   source: ModuleRequest['source'],

src/mcp.ts

@@ -79,7 +79,9 @@ async function handleGetDocs({ reference }: DocsInputSchema): Promise<CallToolRe
     };
   }
 
-  if (!docs.documentation) {
+  // Handle both FileInfo and SymbolInfo
+  // For SymbolInfo, check if documentation is available
+  if ('documentation' in docs && !docs.documentation) {
     return {
       content: [
         {

src/resolution/formatters.ts

@@ -1,5 +1,6 @@
 import ts from 'typescript';
-import type { SymbolInfo } from '../core';
+import type { SymbolInfo, FileInfo } from '../core';
+import { isFileInfo } from '../core';
 
 // Get signature
 export function getSignature(checker: ts.TypeChecker, symbol: ts.Symbol, type: ts.Type): string {
@@ -134,8 +135,8 @@ export function getTypeString(checker: ts.TypeChecker, symbol: ts.Symbol, type:
   return defaultTypeString;
 }
 
-// Format output for display
-export function formatOutput(info: SymbolInfo): string {
+// Format symbol info for display
+function formatSymbolInfo(info: SymbolInfo): string {
   const output: string[] = [];
 
   output.push(`\n${info.name}`);
@@ -166,3 +167,37 @@ export function formatOutput(info: SymbolInfo): string {
 
   return output.join('\n');
 }
+
+// Format file info for display
+function formatFileInfo(info: FileInfo): string {
+  const output: string[] = [];
+
+  output.push(`\nFile: ${info.path}`);
+  output.push('');
+
+  if (info.overview) {
+    output.push('Overview:');
+    output.push(info.overview);
+    output.push('');
+  }
+
+  output.push(`Symbols (${info.exportCount} total):`);
+  output.push('');
+
+  for (const exp of info.exports) {
+    output.push(`${exp.name} (${exp.kind}) - line ${exp.line}`);
+    if (exp.documentation) {
+      output.push(exp.documentation);
+    }
+  }
+
+  return output.join('\n');
+}
+
+// Format output dispatcher - handles both SymbolInfo and FileInfo
+export function formatOutput(info: SymbolInfo | FileInfo): string {
+  if (isFileInfo(info)) {
+    return formatFileInfo(info);
+  }
+  return formatSymbolInfo(info);
+}

src/resolution/index.ts

@@ -7,17 +7,23 @@ import type {
   ResolveResult,
   ExtractError,
   InternalResolveResult,
+  ExportSummary,
 } from '../core';
 import { createExtractError, resolveError, isResolveError, isExtractError } from '../core';
 import { loadTsConfig, resolveModule, resolveNodeBuiltin } from './module-resolver';
 import { findSymbolInJavaScriptFile, getSymbolInfo } from './symbol-finder';
-import { formatOutput } from './formatters';
+import { getSymbolKind, getFileOverview } from './utils';
 
 // Parse module path into extraction request
 function parseModulePath(modulePath: string): ExtractionRequest | ExtractError {
+  // Handle empty or invalid paths
+  if (!modulePath || modulePath.trim() === '') {
+    return createExtractError('INVALID_REQUEST', 'Module path is required');
+  }
+
   // Handle node: prefix specially
   let module: string;
-  let symbolPath: string;
+  let symbolPath: string | undefined;
 
   if (modulePath.startsWith('node:')) {
     // For node:Math -> module='node:Math', symbol='Math'
@@ -27,16 +33,31 @@ function parseModulePath(modulePath: string): ExtractionRequest | ExtractError {
     module = `node:${baseSymbol}`; // 'node:Math'
     symbolPath = nodeSymbol; // 'Math' or 'Math.min'
   } else {
-    // Regular module:symbol format
-    const [mod, symPath] = modulePath.split(':');
-    if (!mod || !symPath) {
-      return createExtractError(
-        'INVALID_REQUEST',
-        `Invalid format. Expected 'module:symbol', got '${modulePath}'`,
-      );
+    // Regular module[:symbol] format
+    const colonIndex = modulePath.indexOf(':');
+
+    if (colonIndex === -1) {
+      // No colon found - file-level request
+      module = modulePath;
+      symbolPath = undefined;
+    } else if (colonIndex === 0) {
+      // Only colon at start
+      return createExtractError('INVALID_REQUEST', 'Module path is required before ":"');
+    } else {
+      // Split on first colon
+      module = modulePath.substring(0, colonIndex);
+      symbolPath = modulePath.substring(colonIndex + 1);
+
+      // If symbol part is empty after colon, return error
+      if (!symbolPath || symbolPath.trim() === '') {
+        return createExtractError('INVALID_REQUEST', 'Symbol name is required after ":"');
+      }
     }
-    module = mod;
-    symbolPath = symPath;
+  }
+
+  // If no symbol path, return file-level request
+  if (!symbolPath) {
+    return { module, symbol: undefined, member: undefined, isStatic: false };
   }
 
   // Check for instance member (Constructor#instanceMember)
@@ -66,6 +87,51 @@ function parseModulePath(modulePath: string): ExtractionRequest | ExtractError {
   return { module, symbol: symbolPath, member: undefined, isStatic: false };
 }
 
+// Get all exported symbols with their summaries
+function getExportSummaries(
+  moduleSymbol: ts.Symbol | undefined,
+  sourceFile: ts.SourceFile,
+  checker: ts.TypeChecker,
+): ExportSummary[] {
+  if (!moduleSymbol) {
+    return [];
+  }
+
+  try {
+    const exports = checker.getExportsOfModule(moduleSymbol);
+    const summaries: ExportSummary[] = [];
+
+    for (const exp of exports) {
+      const name = exp.getName();
+      const kind = getSymbolKind(exp);
+
+      // Get line number from declaration
+      const decl = exp.valueDeclaration ?? exp.declarations?.[0];
+      let line = 0;
+      if (decl) {
+        const pos = sourceFile.getLineAndCharacterOfPosition(decl.getStart());
+        line = pos.line + 1; // 1-indexed
+      }
+
+      // Get brief documentation (first line)
+      const fullDoc = ts.displayPartsToString(exp.getDocumentationComment(checker));
+      const briefDoc = fullDoc.split('\n')[0]?.trim();
+
+      summaries.push({
+        name,
+        kind,
+        line,
+        documentation: briefDoc || undefined,
+      });
+    }
+
+    // Sort by line number
+    return summaries.sort((a, b) => a.line - b.line);
+  } catch {
+    return [];
+  }
+}
+
 // Extract documentation for a module:symbol path
 export async function extractDocs(modulePath: string): Promise<ExtractResult> {
   const options: ExtractorOptions = { prefix: process.cwd() };
@@ -95,6 +161,28 @@ export async function extractDocs(modulePath: string): Promise<ExtractResult> {
 
   const { sourceFile, program } = resolvedModule;
   const checker = program.getTypeChecker();
+
+  // Handle file-level request (no symbol specified)
+  if (symbol === undefined) {
+    const overview = getFileOverview(sourceFile);
+    const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+    const exports = getExportSummaries(moduleSymbol, sourceFile, checker);
+
+    // Format path as relative (consistent with SymbolInfo.location)
+    let relativePath = sourceFile.fileName;
+    const cwd = process.cwd();
+    if (relativePath.startsWith(cwd)) {
+      relativePath = path.relative(cwd, relativePath);
+    }
+
+    return {
+      path: relativePath,
+      overview,
+      exportCount: exports.length,
+      exports,
+    };
+  }
+
   let targetSymbol: ts.Symbol | undefined;
 
   if (isGlobalModule) {
@@ -196,6 +284,20 @@ export async function getSourceLocation(reference: string): Promise<ResolveResul
     }
 
     const { module, symbol, member, isStatic } = parseResult;
+
+    // In this branch, we know reference contains ':', so symbol should be defined
+    // If symbol is undefined here, it means parseModulePath returned successfully for a file-level request
+    // which shouldn't happen in this code path
+    if (!symbol) {
+      return {
+        success: false,
+        error: {
+          code: 'INVALID_SPECIFIER',
+          message: 'Symbol reference required for source location lookup',
+        },
+      };
+    }
+
     const config = loadTsConfig(options.prefix);
 
     // Try to resolve as a regular module first
@@ -365,6 +467,8 @@ export async function extractSymbol(
       };
     }
 
+    // After the check above, we know symbol is defined
+    const { symbol } = request;
     const config = loadTsConfig(options.prefix);
 
     // Resolve module with dedicated program
@@ -388,27 +492,27 @@ export async function extractSymbol(
     if (moduleSymbol) {
       // TypeScript module with proper exports
       const exports = checker.getExportsOfModule(moduleSymbol);
-      targetSymbol = exports.find((exp: ts.Symbol) => exp.getName() === request.symbol);
+      targetSymbol = exports.find((exp: ts.Symbol) => exp.getName() === symbol);
 
       if (!targetSymbol) {
         return {
           error: {
             code: 'SYMBOL_NOT_FOUND',
-            message: `Symbol '${request.symbol}' not found in module '${request.module}'. Available exports: ${exports
+            message: `Symbol '${symbol}' not found in module '${request.module}'. Available exports: ${exports
               .map((e: ts.Symbol) => e.getName())
               .join(', ')}`,
           },
         };
       }
     } else {
       // JavaScript file - look for symbols in statements
-      targetSymbol = findSymbolInJavaScriptFile(sourceFile, checker, request.symbol);
+      targetSymbol = findSymbolInJavaScriptFile(sourceFile, checker, symbol);
 
       if (!targetSymbol) {
         return {
           error: {
             code: 'SYMBOL_NOT_FOUND',
-            message: `Symbol '${request.symbol}' not found in JavaScript module '${request.module}'`,
+            message: `Symbol '${symbol}' not found in JavaScript module '${request.module}'`,
           },
         };
       }
@@ -426,5 +530,5 @@ export async function extractSymbol(
   }
 }
 
-// Re-export formatOutput
-export { formatOutput };
+// Re-export formatters
+export { formatOutput } from './formatters';

src/resolution/symbol-finder.ts

@@ -1,5 +1,5 @@
 import ts from 'typescript';
-import type { ExtractResult } from '../core';
+import type { SymbolInfo, ExtractError } from '../core';
 import { createExtractError } from '../core';
 import { getLocation, getDocumentation, getJSDoc, getSymbolKind } from './utils';
 import { getSignature, getTypeString } from './formatters';
@@ -128,7 +128,7 @@ export function getSymbolInfo(
   symbol: ts.Symbol,
   member?: string,
   isStatic?: boolean,
-): ExtractResult {
+): SymbolInfo | ExtractError {
   // For symbols without valueDeclaration (like interfaces), use the first declaration
   const declaration = symbol.valueDeclaration || (symbol.declarations && symbol.declarations[0]);
   if (!declaration && (!symbol.declarations || symbol.declarations.length === 0)) {

src/resolution/utils.ts

@@ -91,3 +91,39 @@ export function getSymbolKind(symbol: ts.Symbol): string {
 
   return 'unknown';
 }
+
+// Get file overview from @fileoverview or @file JSDoc tags
+export function getFileOverview(sourceFile: ts.SourceFile): string | undefined {
+  // Get leading comments from the source file (before first statement)
+  const leadingComments = ts.getLeadingCommentRanges(sourceFile.text, 0);
+
+  if (!leadingComments || leadingComments.length === 0) {
+    return undefined;
+  }
+
+  // Extract text and parse JSDoc
+  for (const comment of leadingComments) {
+    const commentText = sourceFile.text.slice(comment.pos, comment.end);
+
+    // Parse @fileoverview or @file tags
+    const fileoverviewMatch = commentText.match(/@fileoverview\s+([\s\S]*?)(?=@\w+|$)/);
+    const fileMatch = commentText.match(/@file\s+([\s\S]*?)(?=@\w+|$)/);
+    const match = fileoverviewMatch || fileMatch;
+
+    if (match && match[1]) {
+      // Clean up the matched text: remove leading asterisks and whitespace
+      const overviewText = match[1]
+        .split('\n')
+        .map(line => line.replace(/^\s*\*\s?/, '').trim())
+        .filter(line => line.length > 0)
+        .join('\n')
+        .trim();
+
+      if (overviewText) {
+        return overviewText;
+      }
+    }
+  }
+
+  return undefined;
+}