jsdoczoom 0.2.1 → 0.3.0

package/dist/eslint-plugin.js

@@ -1,3 +1,5 @@
+import { appendText, DESCRIPTION_TAGS } from "./types.js";
+
 /**
  * Custom ESLint plugin for jsdoczoom file-level JSDoc validation.
  *
@@ -8,13 +10,6 @@
  *
  * @summary Custom ESLint plugin with file-level JSDoc validation rules
  */
-/** Tags whose content is treated as description (free-text). */
-const DESCRIPTION_TAGS = new Set([
-	"desc",
-	"description",
-	"file",
-	"fileoverview",
-]);
 /**
  * Find the file-level JSDoc block comment from the source code.
  *
@@ -51,13 +46,6 @@ function findFileJsdocComment(sourceCode, programBody) {
 	// If no non-import statements, return first JSDoc comment in file
 	return jsdocComments[0] ?? null;
 }
-/**
- * Append non-empty text to an accumulator with space separation.
- */
-function appendText(existing, addition) {
-	if (!addition) return existing;
-	return existing ? `${existing} ${addition}` : addition;
-}
 /**
  * Parse the inner content of a JSDoc block comment.
  *

package/dist/jsdoc-parser.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import ts from "typescript";
 import { JsdocError } from "./errors.js";
+import { appendText, DESCRIPTION_TAGS } from "./types.js";
 /**
  * Uses the TypeScript compiler to locate the first JSDoc block before any
  * code statements, then extracts the first `@summary` tag and free-text
@@ -123,21 +124,6 @@ function getDiagnostics(sourceFile) {
 	if (!diags || diags.length === 0) return [];
 	return diags.map((d) => ts.flattenDiagnosticMessageText(d.messageText, "\n"));
 }
-/**
- * Append non-empty text to an accumulator with space separation.
- */
-function appendText(existing, addition) {
-	if (addition.length === 0) return existing;
-	if (existing.length === 0) return addition;
-	return `${existing} ${addition}`;
-}
-/** Tags whose content is treated as description (free-text). */
-const DESCRIPTION_TAGS = new Set([
-	"desc",
-	"description",
-	"file",
-	"fileoverview",
-]);
 /**
  * Parse @summary tag and free-text description from raw JSDoc inner text.
  *

package/dist/type-declarations.js

@@ -1,6 +1,8 @@
 import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
 import ts from "typescript";
 import { JsdocError } from "./errors.js";
+
 /**
  * Produces .d.ts-like output from a TypeScript source file using the
  * TypeScript compiler's declaration emit. Preserves JSDoc comments and
@@ -9,6 +11,145 @@ import { JsdocError } from "./errors.js";
  *
  * @summary Generate TypeScript declaration output from source files
  */
+// Cache for resolved compiler options, keyed by tsconfig path
+const compilerOptionsCache = new Map();
+// Shared document registry for caching parsed source files across language services
+const documentRegistry = ts.createDocumentRegistry();
+// Cache for language services, keyed by tsconfig path
+const serviceCache = new Map();
+/**
+ * Resolves compiler options for a given file path by finding and parsing
+ * the nearest tsconfig.json file.
+ *
+ * @internal
+ * @param filePath - Absolute path to the TypeScript source file
+ * @returns Object containing the tsconfig path and resolved compiler options
+ */
+export function resolveCompilerOptions(filePath) {
+	// Required overrides that must always be present
+	const requiredOverrides = {
+		declaration: true,
+		emitDeclarationOnly: true,
+		removeComments: false,
+		skipLibCheck: true,
+	};
+	// Fallback defaults when no tsconfig is found
+	const fallbackDefaults = {
+		...requiredOverrides,
+		target: ts.ScriptTarget.Latest,
+		module: ts.ModuleKind.NodeNext,
+		moduleResolution: ts.ModuleResolutionKind.NodeNext,
+	};
+	// Try to find the nearest tsconfig.json
+	const tsconfigPath = ts.findConfigFile(
+		dirname(filePath),
+		ts.sys.fileExists,
+		"tsconfig.json",
+	);
+	// Use cache key based on tsconfig path (or "__default__" if none found)
+	const cacheKey = tsconfigPath ?? "__default__";
+	if (compilerOptionsCache.has(cacheKey)) {
+		return compilerOptionsCache.get(cacheKey);
+	}
+	let result;
+	if (!tsconfigPath) {
+		// No tsconfig found - use fallback defaults
+		result = {
+			tsconfigPath: null,
+			options: fallbackDefaults,
+		};
+	} else {
+		// Try to parse the tsconfig
+		try {
+			const configFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+			if (configFile.error) {
+				// Malformed JSON - fall back to defaults
+				result = {
+					tsconfigPath: null,
+					options: fallbackDefaults,
+				};
+			} else {
+				// Parse the config content
+				const parsedConfig = ts.parseJsonConfigFileContent(
+					configFile.config,
+					ts.sys,
+					dirname(tsconfigPath),
+				);
+				// Merge parsed options with required overrides
+				result = {
+					tsconfigPath,
+					options: {
+						...parsedConfig.options,
+						...requiredOverrides,
+					},
+				};
+			}
+		} catch (_error) {
+			// Error reading or parsing tsconfig - fall back to defaults
+			// Note: This catches file system errors (EACCES, ENOENT) and any unexpected
+			// errors from ts.readConfigFile or ts.parseJsonConfigFileContent
+			result = {
+				tsconfigPath: null,
+				options: fallbackDefaults,
+			};
+		}
+	}
+	compilerOptionsCache.set(cacheKey, result);
+	return result;
+}
+/**
+ * Gets or creates a cached language service for the given tsconfig and compiler options.
+ * Language services are shared across files in the same project (same tsconfig path) and
+ * reuse parsed source files via the document registry.
+ *
+ * @internal
+ * @param tsconfigPath - Path to the tsconfig.json file, or null if using defaults
+ * @param compilerOptions - Resolved compiler options for this project
+ * @returns Object containing the language service and mutable set of files
+ */
+export function getLanguageService(tsconfigPath, compilerOptions) {
+	const cacheKey = tsconfigPath ?? "__default__";
+	if (serviceCache.has(cacheKey)) {
+		return serviceCache.get(cacheKey);
+	}
+	// Create a mutable set to track files for this service
+	const files = new Set();
+	// Create a language service host
+	const host = {
+		getScriptFileNames: () => Array.from(files),
+		getScriptVersion: (_fileName) => "0", // Static version - no watch mode
+		getScriptSnapshot: (fileName) => {
+			const content = ts.sys.readFile(fileName);
+			if (content === undefined) {
+				return undefined;
+			}
+			return ts.ScriptSnapshot.fromString(content);
+		},
+		getCompilationSettings: () => compilerOptions,
+		getCurrentDirectory: () => ts.sys.getCurrentDirectory(),
+		getDefaultLibFileName: (options) => ts.getDefaultLibFilePath(options),
+		fileExists: ts.sys.fileExists,
+		readFile: ts.sys.readFile,
+		readDirectory: ts.sys.readDirectory,
+		directoryExists: ts.sys.directoryExists,
+		getDirectories: ts.sys.getDirectories,
+	};
+	// Create the language service with the document registry for caching
+	const service = ts.createLanguageService(host, documentRegistry);
+	const cacheEntry = { service, files };
+	serviceCache.set(cacheKey, cacheEntry);
+	return cacheEntry;
+}
+/**
+ * Resets all caches (compiler options, language services, and document registry).
+ * Used for test isolation to ensure a clean state between test runs.
+ *
+ * @internal
+ */
+export function resetCache() {
+	compilerOptionsCache.clear();
+	serviceCache.clear();
+}
 /**
  * Generates TypeScript declaration output from a source file.
  *
@@ -29,86 +170,39 @@ import { JsdocError } from "./errors.js";
  * @throws {JsdocError} If the file cannot be read or parsed
  */
 export function generateTypeDeclarations(filePath) {
-	let sourceText;
+	// Verify the file exists and throw FILE_NOT_FOUND for any read errors
 	try {
-		sourceText = readFileSync(filePath, "utf-8");
+		readFileSync(filePath, "utf-8");
 	} catch (_error) {
 		throw new JsdocError("FILE_NOT_FOUND", `Failed to read file: ${filePath}`);
 	}
-	// Create compiler options matching the project setup
-	const compilerOptions = {
-		declaration: true,
-		emitDeclarationOnly: true,
-		target: ts.ScriptTarget.Latest,
-		module: ts.ModuleKind.NodeNext,
-		moduleResolution: ts.ModuleResolutionKind.NodeNext,
-		skipLibCheck: true,
-		removeComments: false, // Preserve JSDoc comments
-	};
-	// Create a custom compiler host that provides our file
-	const host = ts.createCompilerHost(compilerOptions);
-	const originalGetSourceFile = host.getSourceFile;
-	host.getSourceFile = (
-		fileName,
-		languageVersion,
-		onError,
-		shouldCreateNewSourceFile,
-	) => {
-		if (fileName === filePath) {
-			return ts.createSourceFile(fileName, sourceText, languageVersion, true);
-		}
-		return originalGetSourceFile.call(
-			host,
-			fileName,
-			languageVersion,
-			onError,
-			shouldCreateNewSourceFile,
-		);
-	};
-	// Capture emitted output
-	let declarationOutput = "";
-	host.writeFile = (fileName, data) => {
-		if (fileName.endsWith(".d.ts")) {
-			declarationOutput = data;
-		}
-	};
-	// Create program and emit declarations
-	const program = ts.createProgram([filePath], compilerOptions, host);
-	const sourceFile = program.getSourceFile(filePath);
-	if (!sourceFile) {
-		throw new JsdocError("PARSE_ERROR", `Failed to parse file: ${filePath}`);
-	}
-	const emitResult = program.emit(sourceFile, undefined, undefined, true);
-	// Check for emit errors
-	const diagnostics = ts
-		.getPreEmitDiagnostics(program)
-		.concat(emitResult.diagnostics);
+	// Resolve compiler options from nearest tsconfig.json
+	const { tsconfigPath, options } = resolveCompilerOptions(filePath);
+	// Get or create a cached language service for this project
+	const { service, files } = getLanguageService(tsconfigPath, options);
+	// Register the file with the language service
+	files.add(filePath);
+	// Check for parse errors first
+	const diagnostics = service.getSyntacticDiagnostics(filePath);
 	if (diagnostics.length > 0) {
-		const errors = diagnostics
-			.map((diagnostic) => {
-				if (diagnostic.file && diagnostic.start !== undefined) {
-					const { line, character } =
-						diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
-					const message = ts.flattenDiagnosticMessageText(
-						diagnostic.messageText,
-						"\n",
-					);
-					return `${diagnostic.file.fileName} (${line + 1},${character + 1}): ${message}`;
-				}
-				return ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
-			})
-			.join("\n");
-		throw new JsdocError("PARSE_ERROR", `TypeScript errors:\n${errors}`);
+		throw new JsdocError("PARSE_ERROR", `Failed to parse file: ${filePath}`);
 	}
-	if (!declarationOutput) {
-		// If no output was generated, the file may have no exports
-		// Return empty string in this case
+	// Get emit output using the language service
+	const emitOutput = service.getEmitOutput(filePath, true); // true = emitOnlyDtsFiles
+	// Find the .d.ts output file
+	const dtsFile = emitOutput.outputFiles.find((file) =>
+		file.name.endsWith(".d.ts"),
+	);
+	if (!dtsFile) {
+		// No declaration output - file has no exports
 		return "";
 	}
 	// Clean up the output
-	let cleaned = declarationOutput;
+	let cleaned = dtsFile.text;
 	// Remove empty export statement if present and no other exports
-	if (cleaned.trim() === "export {};") {
+	// Strip out any leading comments first to check if the only actual code is "export {};"
+	const withoutComments = cleaned.replace(/\/\*\*[\s\S]*?\*\//g, "").trim();
+	if (withoutComments === "export {};") {
 		cleaned = "";
 	}
 	return cleaned;

package/dist/types.js

@@ -14,3 +14,18 @@ export const VALIDATION_STATUS_PRIORITY = [
 	"missing_description",
 	"missing_barrel",
 ];
+/** Tags whose content is treated as description (free-text). */
+export const DESCRIPTION_TAGS = new Set([
+	"desc",
+	"description",
+	"file",
+	"fileoverview",
+]);
+/**
+ * Append non-empty text to an accumulator with space separation.
+ */
+export function appendText(existing, addition) {
+	if (addition.length === 0) return existing;
+	if (existing.length === 0) return addition;
+	return `${existing} ${addition}`;
+}

package/package.json

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

package/types/jsdoc-parser.d.ts

@@ -1,4 +1,4 @@
-import type { ParsedFileInfo } from "./types.js";
+import { type ParsedFileInfo } from "./types.js";
 /**
  * Uses the TypeScript compiler to locate the first JSDoc block before any
  * code statements, then extracts the first `@summary` tag and free-text

package/types/type-declarations.d.ts

@@ -1,11 +1,40 @@
+import ts from "typescript";
 /**
- * Produces .d.ts-like output from a TypeScript source file using the
- * TypeScript compiler's declaration emit. Preserves JSDoc comments and
- * source order while stripping implementation bodies and non-exported
- * internals.
+ * Resolves compiler options for a given file path by finding and parsing
+ * the nearest tsconfig.json file.
  *
- * @summary Generate TypeScript declaration output from source files
+ * @internal
+ * @param filePath - Absolute path to the TypeScript source file
+ * @returns Object containing the tsconfig path and resolved compiler options
+ */
+export declare function resolveCompilerOptions(filePath: string): {
+	tsconfigPath: string | null;
+	options: ts.CompilerOptions;
+};
+/**
+ * Gets or creates a cached language service for the given tsconfig and compiler options.
+ * Language services are shared across files in the same project (same tsconfig path) and
+ * reuse parsed source files via the document registry.
+ *
+ * @internal
+ * @param tsconfigPath - Path to the tsconfig.json file, or null if using defaults
+ * @param compilerOptions - Resolved compiler options for this project
+ * @returns Object containing the language service and mutable set of files
+ */
+export declare function getLanguageService(
+	tsconfigPath: string | null,
+	compilerOptions: ts.CompilerOptions,
+): {
+	service: ts.LanguageService;
+	files: Set<string>;
+};
+/**
+ * Resets all caches (compiler options, language services, and document registry).
+ * Used for test isolation to ensure a clean state between test runs.
+ *
+ * @internal
  */
+export declare function resetCache(): void;
 /**
  * Generates TypeScript declaration output from a source file.
  *

package/types/types.d.ts

@@ -81,6 +81,12 @@ export interface SelectorInfo {
 	pattern: string;
 	depth: number | undefined;
 }
+/** Tags whose content is treated as description (free-text). */
+export declare const DESCRIPTION_TAGS: Set<string>;
+/**
+ * Append non-empty text to an accumulator with space separation.
+ */
+export declare function appendText(existing: string, addition: string): string;
 /** A single lint diagnostic from ESLint */
 export interface LintDiagnostic {
 	line: number;