jsdoczoom 0.4.13 → 0.4.16

package/dist/jsdoc-parser.js

@@ -17,9 +17,9 @@ import { appendText, DESCRIPTION_TAGS } from "./types.js";
  * Returns the raw JSDoc text without the leading `/**` and trailing `*​/` delimiters,
  * or null if no file-level JSDoc is found.
  */
-export function extractFileJsdoc(sourceText) {
+export function extractFileJsdoc(sourceText, fileName = "input.tsx") {
 	const sourceFile = ts.createSourceFile(
-		"input.ts",
+		fileName,
 		sourceText,
 		ts.ScriptTarget.Latest,
 		true,
@@ -33,9 +33,11 @@ export function extractFileJsdoc(sourceText) {
 		);
 	}
 	// Find the first non-import top-level statement
+	let firstImport;
 	let firstNonImportStatement;
 	for (const statement of sourceFile.statements) {
 		if (ts.isImportDeclaration(statement)) {
+			firstImport ??= statement;
 			continue;
 		}
 		firstNonImportStatement = statement;
@@ -45,7 +47,24 @@ export function extractFileJsdoc(sourceText) {
 	if (firstNonImportStatement === undefined) {
 		return findFirstJsdocBlock(sourceText, 0, sourceText.length);
 	}
-	// The JSDoc block sits in the leading trivia of the first non-import statement.
+	// When imports exist, the file-level JSDoc lives in the leading trivia of
+	// the first import (before any imports), not the first non-import statement.
+	// Check there first; fall back to the first non-import statement's trivia
+	// for the "JSDoc after imports" pattern.
+	if (firstImport) {
+		const importFullStart = firstImport.getFullStart();
+		const importNodeStart = firstImport.getStart(sourceFile);
+		const preImportJsdoc = findFirstJsdocBlock(
+			sourceText,
+			importFullStart,
+			importNodeStart,
+		);
+		if (preImportJsdoc !== null) {
+			return preImportJsdoc;
+		}
+	}
+	// JSDoc in the leading trivia of the first non-import statement
+	// (handles "JSDoc after imports but before code" pattern).
 	const fullStart = firstNonImportStatement.getFullStart();
 	const nodeStart = firstNonImportStatement.getStart(sourceFile);
 	return findFirstJsdocBlock(sourceText, fullStart, nodeStart);
@@ -203,7 +222,7 @@ export function parseFileSummaries(filePath) {
 	} catch {
 		throw new JsdocError("FILE_NOT_FOUND", `File not found: ${filePath}`);
 	}
-	const jsdocText = extractFileJsdoc(sourceText);
+	const jsdocText = extractFileJsdoc(sourceText, filePath);
 	if (jsdocText === null) {
 		return {
 			path: filePath,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "jsdoczoom",
-	"version": "0.4.13",
+	"version": "0.4.16",
 	"description": "CLI tool for extracting JSDoc summaries at configurable depths",
 	"type": "module",
 	"sideEffects": false,

package/types/jsdoc-parser.d.ts

@@ -14,7 +14,10 @@ import { type ParsedFileInfo } from "./types.js";
  * Returns the raw JSDoc text without the leading `/**` and trailing `*​/` delimiters,
  * or null if no file-level JSDoc is found.
  */
-export declare function extractFileJsdoc(sourceText: string): string | null;
+export declare function extractFileJsdoc(
+	sourceText: string,
+	fileName?: string,
+): string | null;
 /**
  * Parse a TypeScript file and extract its summary and description from file-level JSDoc.
  *