jsdoczoom 0.3.0 → 0.4.5

package/dist/drilldown.js

@@ -1,13 +1,20 @@
-import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { dirname, relative } from "node:path";
 import { getBarrelChildren, isBarrel } from "./barrel.js";
+import { processWithCache } from "./cache.js";
 import { JsdocError } from "./errors.js";
-import { discoverFiles } from "./file-discovery.js";
+import { discoverFiles, loadGitignore } from "./file-discovery.js";
 import { parseFileSummaries } from "./jsdoc-parser.js";
 import { generateTypeDeclarations } from "./type-declarations.js";
+import { DEFAULT_CACHE_DIR } from "./types.js";
 
 /** Terminal level (1-indexed): 1=summary, 2=description, 3=type declarations, 4=full file. */
 const TERMINAL_LEVEL = 4;
+/** Default cache configuration used when no config is provided. */
+const DEFAULT_CACHE_CONFIG = {
+	enabled: true,
+	directory: DEFAULT_CACHE_DIR,
+};
 /**
  * Build the fixed drill-down level array for a file.
  *
@@ -17,14 +24,16 @@ const TERMINAL_LEVEL = 4;
  * - Level 4 (index 3): full file content (always present, terminal)
  *
  * The array always has 4 entries. Null entries are skipped during processing.
+ * Type declarations and file content are pre-computed and passed in to support
+ * async cache integration.
  */
-function buildLevels(info) {
+function buildLevels(info, typeDeclarations, fileContent) {
 	const { summary, description } = info;
 	return [
-		summary !== null ? { text: () => summary } : null,
-		description !== null ? { text: () => description } : null,
-		{ text: () => generateTypeDeclarations(info.path) },
-		{ text: () => readFileSync(info.path, "utf-8") },
+		summary !== null ? { text: summary } : null,
+		description !== null ? { text: description } : null,
+		{ text: typeDeclarations },
+		{ text: fileContent },
 	];
 }
 /**
@@ -53,9 +62,9 @@ function sortKey(entry) {
  * If the requested depth level is null (empty), advance to the next non-null level.
  * Output contains next_id when more detail is available, or id at terminal level.
  */
-function processFile(info, depth, cwd) {
+function processFile(info, typeDeclarations, fileContent, depth, cwd) {
 	const idPath = displayPath(info.path, cwd);
-	const levels = buildLevels(info);
+	const levels = buildLevels(info, typeDeclarations, fileContent);
 	// Clamp depth to [1, TERMINAL_LEVEL], advance past null levels
 	let effectiveDepth = Math.max(1, Math.min(depth, TERMINAL_LEVEL));
 	while (
@@ -68,12 +77,12 @@ function processFile(info, depth, cwd) {
 	if (effectiveDepth < TERMINAL_LEVEL) {
 		return {
 			next_id: `${idPath}@${effectiveDepth + 1}`,
-			text: level.text(),
+			text: level.text,
 		};
 	}
 	return {
 		id: `${idPath}@${effectiveDepth}`,
-		text: level.text(),
+		text: level.text,
 	};
 }
 /**
@@ -91,14 +100,56 @@ function makeParseErrorItem(filePath, error, cwd) {
 function isParseError(error) {
 	return error instanceof JsdocError && error.code === "PARSE_ERROR";
 }
+/**
+ * Determine the effective depth after null-level advancement.
+ * Advances past null summary (L1) and null description (L2) levels.
+ */
+function computeEffectiveDepth(depth, info) {
+	let effectiveDepth = Math.max(1, Math.min(depth, TERMINAL_LEVEL));
+	if (effectiveDepth < TERMINAL_LEVEL && info.summary === null) {
+		effectiveDepth = Math.max(effectiveDepth, 2);
+	}
+	if (effectiveDepth < TERMINAL_LEVEL && info.description === null) {
+		effectiveDepth = Math.max(effectiveDepth, 3);
+	}
+	return effectiveDepth;
+}
+/**
+ * Conditionally compute type declarations if effective depth requires it (L3+).
+ * Uses cache to avoid redundant TypeScript compilation.
+ */
+async function computeTypeDeclarationsIfNeeded(
+	content,
+	filePath,
+	effectiveDepth,
+	config,
+) {
+	if (effectiveDepth < 3) {
+		return "";
+	}
+	return processWithCache(config, "drilldown", `${content}\0typedecl`, () =>
+		generateTypeDeclarations(filePath),
+	);
+}
 /**
  * Process a file safely, returning an OutputErrorItem on PARSE_ERROR.
- * Rethrows non-PARSE_ERROR exceptions.
+ * Rethrows non-PARSE_ERROR exceptions. Uses cache for expensive operations
+ * (parseFileSummaries and generateTypeDeclarations).
  */
-function processFileSafe(filePath, depth, cwd) {
+async function processFileSafe(filePath, depth, cwd, config) {
 	try {
-		const info = parseFileSummaries(filePath);
-		return processFile(info, depth, cwd);
+		const content = await readFile(filePath, "utf-8");
+		const info = await processWithCache(config, "drilldown", content, () =>
+			parseFileSummaries(filePath),
+		);
+		const effectiveDepth = computeEffectiveDepth(depth, info);
+		const typeDeclarations = await computeTypeDeclarationsIfNeeded(
+			content,
+			filePath,
+			effectiveDepth,
+			config,
+		);
+		return processFile(info, typeDeclarations, content, depth, cwd);
 	} catch (error) {
 		if (isParseError(error)) return makeParseErrorItem(filePath, error, cwd);
 		throw error;
@@ -107,26 +158,44 @@ function processFileSafe(filePath, depth, cwd) {
 /**
  * Gather barrel info and error entries from a list of barrel file paths.
  * Returns successfully parsed barrel infos and error entries for unparseable barrels.
+ * Uses cache for parseFileSummaries calls.
  */
-function gatherBarrelInfos(barrelPaths, cwd) {
+async function gatherBarrelInfos(barrelPaths, cwd, config) {
 	const infos = [];
 	const errors = [];
-	for (const barrelPath of barrelPaths) {
-		try {
-			const info = parseFileSummaries(barrelPath);
-			const children = getBarrelChildren(barrelPath, cwd);
-			infos.push({
-				path: barrelPath,
-				hasSummary: info.summary !== null,
-				hasDescription: info.description !== null,
-				children,
-			});
-		} catch (error) {
-			if (isParseError(error)) {
-				errors.push(makeParseErrorItem(barrelPath, error, cwd));
-				continue;
+	const results = await Promise.all(
+		barrelPaths.map(async (barrelPath) => {
+			try {
+				const content = await readFile(barrelPath, "utf-8");
+				const info = await processWithCache(config, "drilldown", content, () =>
+					parseFileSummaries(barrelPath),
+				);
+				const children = getBarrelChildren(barrelPath, cwd);
+				return {
+					type: "info",
+					data: {
+						path: barrelPath,
+						hasSummary: info.summary !== null,
+						hasDescription: info.description !== null,
+						children,
+					},
+				};
+			} catch (error) {
+				if (isParseError(error)) {
+					return {
+						type: "error",
+						data: makeParseErrorItem(barrelPath, error, cwd),
+					};
+				}
+				throw error;
 			}
-			throw error;
+		}),
+	);
+	for (const result of results) {
+		if (result.type === "info") {
+			infos.push(result.data);
+		} else {
+			errors.push(result.data);
 		}
 	}
 	return { infos, errors };
@@ -151,8 +220,9 @@ function buildGatedFileSet(barrelInfos) {
  * Barrels with summaries gate children for two depths (L1 summary, L2 description),
  * then transition at depth 3 where the barrel disappears and children appear.
  */
-function processBarrelAtDepth(barrel, depth, cwd) {
-	if (!barrel.hasSummary) return [processFileSafe(barrel.path, depth, cwd)];
+async function processBarrelAtDepth(barrel, depth, cwd, config) {
+	if (!barrel.hasSummary)
+		return [await processFileSafe(barrel.path, depth, cwd, config)];
 	// Null-skip: if depth 2 but no description, advance to transition depth
 	let effectiveDepth = depth;
 	if (effectiveDepth === 2 && !barrel.hasDescription) {
@@ -160,7 +230,12 @@ function processBarrelAtDepth(barrel, depth, cwd) {
 	}
 	if (effectiveDepth < 3) {
 		// Show barrel's own L1 (summary) or L2 (description)
-		const entry = processFileSafe(barrel.path, effectiveDepth, cwd);
+		const entry = await processFileSafe(
+			barrel.path,
+			effectiveDepth,
+			cwd,
+			config,
+		);
 		if ("next_id" in entry) {
 			entry.children = barrel.children.map((c) => relative(cwd, c));
 		}
@@ -168,13 +243,15 @@ function processBarrelAtDepth(barrel, depth, cwd) {
 	}
 	// Barrel transitions: barrel disappears, children appear
 	const childDepth = effectiveDepth - 2;
-	return collectSafeResults(barrel.children, childDepth, cwd);
+	return collectSafeResults(barrel.children, childDepth, cwd, config);
 }
 /**
- * Process a list of files through processFileSafe.
+ * Process a list of files through processFileSafe in parallel.
  */
-function collectSafeResults(files, depth, cwd) {
-	return files.map((filePath) => processFileSafe(filePath, depth, cwd));
+async function collectSafeResults(files, depth, cwd, config) {
+	return Promise.all(
+		files.map((filePath) => processFileSafe(filePath, depth, cwd, config)),
+	);
 }
 /**
  * Process files discovered via glob with barrel gating.
@@ -187,7 +264,7 @@ function collectSafeResults(files, depth, cwd) {
  * A barrel that is itself gated by a parent barrel is not processed independently.
  * Non-barrel files that are not gated by any barrel are processed normally.
  */
-function processGlobWithBarrels(files, depth, cwd) {
+async function processGlobWithBarrels(files, depth, cwd, config) {
 	const barrelPaths = [];
 	const nonBarrelPaths = [];
 	for (const filePath of files) {
@@ -198,20 +275,27 @@ function processGlobWithBarrels(files, depth, cwd) {
 		}
 	}
 	if (barrelPaths.length === 0) {
-		return collectSafeResults(nonBarrelPaths, depth, cwd);
+		return collectSafeResults(nonBarrelPaths, depth, cwd, config);
 	}
-	const { infos: barrelInfos, errors: barrelErrors } = gatherBarrelInfos(
+	const { infos: barrelInfos, errors: barrelErrors } = await gatherBarrelInfos(
 		barrelPaths,
 		cwd,
+		config,
 	);
 	const gatedFiles = buildGatedFileSet(barrelInfos);
 	const results = [...barrelErrors];
-	for (const barrel of barrelInfos) {
-		if (gatedFiles.has(barrel.path)) continue;
-		results.push(...processBarrelAtDepth(barrel, depth, cwd));
+	const barrelResults = await Promise.all(
+		barrelInfos
+			.filter((barrel) => !gatedFiles.has(barrel.path))
+			.map((barrel) => processBarrelAtDepth(barrel, depth, cwd, config)),
+	);
+	for (const entries of barrelResults) {
+		results.push(...entries);
 	}
 	const ungatedNonBarrels = nonBarrelPaths.filter((f) => !gatedFiles.has(f));
-	results.push(...collectSafeResults(ungatedNonBarrels, depth, cwd));
+	results.push(
+		...(await collectSafeResults(ungatedNonBarrels, depth, cwd, config)),
+	);
 	return results;
 }
 /**
@@ -228,13 +312,19 @@ function processGlobWithBarrels(files, depth, cwd) {
  * @throws {JsdocError} NO_FILES_MATCHED for empty glob results
  * @throws {JsdocError} PARSE_ERROR for path selector targeting file with syntax errors
  */
-export function drilldown(selector, cwd, gitignore = true, limit = 100) {
+export async function drilldown(
+	selector,
+	cwd,
+	gitignore = true,
+	limit = 100,
+	config = DEFAULT_CACHE_CONFIG,
+) {
 	const depth = selector.depth ?? 1;
 	if (selector.type === "path") {
 		const files = discoverFiles(selector.pattern, cwd, gitignore);
 		if (files.length > 1) {
 			// Directory expanded to multiple files — route through glob pipeline
-			const results = processGlobWithBarrels(files, depth, cwd);
+			const results = await processGlobWithBarrels(files, depth, cwd, config);
 			const sorted = results.sort((a, b) =>
 				sortKey(a).localeCompare(sortKey(b)),
 			);
@@ -247,8 +337,18 @@ export function drilldown(selector, cwd, gitignore = true, limit = 100) {
 		}
 		// Single file path — errors are fatal, no barrel gating
 		const filePath = files[0];
-		const info = parseFileSummaries(filePath);
-		const items = [processFile(info, depth, cwd)];
+		const content = await readFile(filePath, "utf-8");
+		const info = await processWithCache(config, "drilldown", content, () =>
+			parseFileSummaries(filePath),
+		);
+		const effectiveDepth = computeEffectiveDepth(depth, info);
+		const typeDeclarations = await computeTypeDeclarationsIfNeeded(
+			content,
+			filePath,
+			effectiveDepth,
+			config,
+		);
+		const items = [processFile(info, typeDeclarations, content, depth, cwd)];
 		return { items, truncated: false };
 	}
 	// Glob selector — apply barrel gating
@@ -259,7 +359,7 @@ export function drilldown(selector, cwd, gitignore = true, limit = 100) {
 			`No files matched: ${selector.pattern}`,
 		);
 	}
-	const results = processGlobWithBarrels(files, depth, cwd);
+	const results = await processGlobWithBarrels(files, depth, cwd, config);
 	// Sort alphabetically by key
 	const sorted = results.sort((a, b) => sortKey(a).localeCompare(sortKey(b)));
 	const total = sorted.length;
@@ -280,12 +380,22 @@ export function drilldown(selector, cwd, gitignore = true, limit = 100) {
  * @param cwd - Working directory for relative path output
  * @returns Array of output entries sorted alphabetically by path
  */
-export function drilldownFiles(filePaths, depth, cwd, limit = 100) {
+export async function drilldownFiles(
+	filePaths,
+	depth,
+	cwd,
+	limit = 100,
+	config = DEFAULT_CACHE_CONFIG,
+) {
 	const d = depth ?? 1;
+	const ig = loadGitignore(cwd);
 	const tsFiles = filePaths.filter(
-		(f) => f.endsWith(".ts") || f.endsWith(".tsx"),
+		(f) =>
+			(f.endsWith(".ts") || f.endsWith(".tsx")) &&
+			!f.endsWith(".d.ts") &&
+			!ig.ignores(relative(cwd, f)),
 	);
-	const results = collectSafeResults(tsFiles, d, cwd);
+	const results = await collectSafeResults(tsFiles, d, cwd, config);
 	const sorted = results.sort((a, b) => sortKey(a).localeCompare(sortKey(b)));
 	const total = sorted.length;
 	const truncated = total > limit;

package/dist/file-discovery.js

@@ -3,7 +3,6 @@ import { dirname, join, relative, resolve } from "node:path";
 import { globSync } from "glob";
 import ignore from "ignore";
 import { JsdocError } from "./errors.js";
-
 /**
  * Walks .gitignore files from cwd to filesystem root, building an ignore
  * filter that glob results pass through. Direct-path lookups bypass the
@@ -16,7 +15,7 @@ import { JsdocError } from "./errors.js";
  * Walk from `cwd` up to the filesystem root, collecting .gitignore entries.
  * Returns an Ignore instance loaded with all discovered rules.
  */
-function loadGitignore(cwd) {
+export function loadGitignore(cwd) {
 	const ig = ignore();
 	let dir = resolve(cwd);
 	while (true) {

package/dist/index.js

@@ -1,9 +1,11 @@
 /**
- * Re-exports all public functions, classes, and types from internal modules.
- * This is the sole entry point for programmatic consumers of the jsdoczoom
- * package.
+ * Progressively explores TypeScript codebase documentation through a 4-level
+ * drill-down (summary, description, type declarations, full source), validates
+ * file-level JSDoc structure, and lints comprehensive JSDoc quality using
+ * ESLint. Barrel files gate their children at shallow depths, revealing
+ * individual files only at deeper levels.
  *
- * @summary Public API barrel re-exporting all functions, types, and classes
+ * @summary Progressive JSDoc exploration, validation, and linting for TypeScript codebases
  */
 export { getBarrelChildren, isBarrel } from "./barrel.js";
 export { drilldown, drilldownFiles } from "./drilldown.js";
@@ -13,5 +15,5 @@ export { extractFileJsdoc, parseFileSummaries } from "./jsdoc-parser.js";
 export { lint, lintFiles } from "./lint.js";
 export { parseSelector } from "./selector.js";
 export { generateTypeDeclarations } from "./type-declarations.js";
-export { VALIDATION_STATUS_PRIORITY } from "./types.js";
+export { DEFAULT_CACHE_DIR, VALIDATION_STATUS_PRIORITY } from "./types.js";
 export { validate, validateFiles } from "./validate.js";

package/dist/lint.js

@@ -8,11 +8,14 @@
  *
  * @summary Lint files for comprehensive JSDoc quality using ESLint engine
  */
-import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { relative } from "node:path";
+import { findMissingBarrels } from "./barrel.js";
+import { processWithCache } from "./cache.js";
 import { JsdocError } from "./errors.js";
 import { createLintLinter, lintFileForLint } from "./eslint-engine.js";
 import { discoverFiles } from "./file-discovery.js";
+import { DEFAULT_CACHE_DIR } from "./types.js";
 
 /**
  * Lint a single file and return per-file diagnostics.
@@ -20,15 +23,18 @@ import { discoverFiles } from "./file-discovery.js";
  * @param eslint - Reusable ESLint instance with correct cwd
  * @param filePath - Absolute path to the file
  * @param cwd - Working directory for computing relative paths
+ * @param config - Cache configuration
  * @returns File result with relative path and diagnostics array
  */
-async function lintSingleFile(eslint, filePath, cwd) {
-	const sourceText = readFileSync(filePath, "utf-8");
-	const diagnostics = await lintFileForLint(eslint, sourceText, filePath);
-	return {
-		filePath: relative(cwd, filePath),
-		diagnostics,
-	};
+async function lintSingleFile(eslint, filePath, cwd, config) {
+	const sourceText = await readFile(filePath, "utf-8");
+	return processWithCache(config, "lint", sourceText, async () => {
+		const diagnostics = await lintFileForLint(eslint, sourceText, filePath);
+		return {
+			filePath: relative(cwd, filePath),
+			diagnostics,
+		};
+	});
 }
 /**
  * Build a LintResult from per-file results, applying a limit to files with issues.
@@ -36,9 +42,10 @@ async function lintSingleFile(eslint, filePath, cwd) {
  * @param fileResults - All per-file lint results
  * @param totalFiles - Total number of files that were linted
  * @param limit - Maximum number of files with issues to include
+ * @param missingBarrels - Directories missing barrel files
  * @returns Aggregated lint result with summary statistics
  */
-function buildLintResult(fileResults, totalFiles, limit) {
+function buildLintResult(fileResults, totalFiles, limit, missingBarrels) {
 	const filesWithIssues = fileResults.filter((f) => f.diagnostics.length > 0);
 	const totalDiagnostics = filesWithIssues.reduce(
 		(sum, f) => sum + f.diagnostics.length,
@@ -48,6 +55,7 @@ function buildLintResult(fileResults, totalFiles, limit) {
 	const truncated = filesWithIssues.length > limit;
 	return {
 		files: cappedFiles,
+		...(missingBarrels.length > 0 ? { missingBarrels } : {}),
 		summary: {
 			totalFiles,
 			filesWithIssues: filesWithIssues.length,
@@ -67,10 +75,17 @@ function buildLintResult(fileResults, totalFiles, limit) {
  * @param cwd - Working directory for resolving paths
  * @param limit - Max number of files with issues to include (default 100)
  * @param gitignore - Whether to respect .gitignore rules (default true)
+ * @param config - Cache configuration (default enabled with DEFAULT_CACHE_DIR)
  * @returns Lint result with per-file diagnostics and summary
  * @throws {JsdocError} NO_FILES_MATCHED if glob selector matches no files
  */
-export async function lint(selector, cwd, limit = 100, gitignore = true) {
+export async function lint(
+	selector,
+	cwd,
+	limit = 100,
+	gitignore = true,
+	config = { enabled: true, directory: DEFAULT_CACHE_DIR },
+) {
 	const files = discoverFiles(selector.pattern, cwd, gitignore);
 	if (files.length === 0 && selector.type === "glob") {
 		throw new JsdocError(
@@ -81,9 +96,10 @@ export async function lint(selector, cwd, limit = 100, gitignore = true) {
 	const tsFiles = files.filter((f) => f.endsWith(".ts") || f.endsWith(".tsx"));
 	const eslint = createLintLinter(cwd);
 	const fileResults = await Promise.all(
-		tsFiles.map((f) => lintSingleFile(eslint, f, cwd)),
+		tsFiles.map((f) => lintSingleFile(eslint, f, cwd, config)),
 	);
-	return buildLintResult(fileResults, tsFiles.length, limit);
+	const missingBarrels = findMissingBarrels(tsFiles, cwd);
+	return buildLintResult(fileResults, tsFiles.length, limit, missingBarrels);
 }
 /**
  * Lint an explicit list of file paths for comprehensive JSDoc quality.
@@ -94,15 +110,22 @@ export async function lint(selector, cwd, limit = 100, gitignore = true) {
  * @param filePaths - List of absolute file paths to lint
  * @param cwd - Working directory for computing relative paths
  * @param limit - Max number of files with issues to include (default 100)
+ * @param config - Cache configuration (default enabled with DEFAULT_CACHE_DIR)
  * @returns Lint result with per-file diagnostics and summary
  */
-export async function lintFiles(filePaths, cwd, limit = 100) {
+export async function lintFiles(
+	filePaths,
+	cwd,
+	limit = 100,
+	config = { enabled: true, directory: DEFAULT_CACHE_DIR },
+) {
 	const tsFiles = filePaths.filter(
 		(f) => f.endsWith(".ts") || f.endsWith(".tsx"),
 	);
 	const eslint = createLintLinter(cwd);
 	const fileResults = await Promise.all(
-		tsFiles.map((f) => lintSingleFile(eslint, f, cwd)),
+		tsFiles.map((f) => lintSingleFile(eslint, f, cwd, config)),
 	);
-	return buildLintResult(fileResults, tsFiles.length, limit);
+	const missingBarrels = findMissingBarrels(tsFiles, cwd);
+	return buildLintResult(fileResults, tsFiles.length, limit, missingBarrels);
 }

package/dist/skill-text.js

@@ -55,7 +55,7 @@ Each file must have exactly one \`@summary\` tag. Remove the extra \`@summary\`
 
 Directories with more than 3 TypeScript files should have an \`index.ts\` barrel file. The barrel provides a module-level \`@summary\` and description that helps agents understand what the directory contains before drilling into individual files.
 
-Create an \`index.ts\` that re-exports the directory's public API and add a file-level JSDoc block describing the module's capabilities.`,
+Create an \`index.ts\` that re-exports the directory's public API and add a file-level JSDoc block describing what the child files collectively accomplish — not the re-export mechanism itself.`,
 	missing_description: `### The description paragraph
 
 The description is prose that **must appear before the first \`@\` tag** in the file-level JSDoc block. Text placed after tags is not recognized as description content.
@@ -220,10 +220,10 @@ The description is prose that appears before any \`@\` tags. It provides the dee
 
 ### Barrel files (index.ts / index.tsx)
 
-Barrel files represent their directory. The \`@summary\` and description describe the module, not individual files.
+Barrel files represent their directory. Their \`@summary\` and description should describe the **cumulative functionality of the directory's children**, not the barrel file itself.
 
-- **\`@summary\`**: What the module does as a unit
-- **Description**: The module's capabilities and concerns — describe concepts, not child filenames
+- **\`@summary\`**: The collective purpose of the files in this directory
+- **Description**: The combined capabilities and responsibilities of child modules — what they do together, not their filenames or the re-export mechanism
 
 \`\`\`typescript
 // packages/auth/src/index.ts
@@ -238,9 +238,10 @@ Barrel files represent their directory. The \`@summary\` and description describ
 \`\`\`
 
 **Avoid:**
-- Listing child filenames in the description
+- \`@summary Re-exports all functions and types\` — describes the barrel mechanism, not what the children do
 - \`@summary Exports for the auth module\` — describes the mechanism, not the purpose
-- \`@summary Index file\` — no information about what the module does
+- \`@summary Public API barrel\` — names the pattern rather than describing functionality
+- Listing child filenames or saying "This is the entry point"
 
 ### Placement
 

package/dist/type-declarations.js

@@ -48,8 +48,9 @@ export function resolveCompilerOptions(filePath) {
 	);
 	// Use cache key based on tsconfig path (or "__default__" if none found)
 	const cacheKey = tsconfigPath ?? "__default__";
-	if (compilerOptionsCache.has(cacheKey)) {
-		return compilerOptionsCache.get(cacheKey);
+	const cached = compilerOptionsCache.get(cacheKey);
+	if (cached) {
+		return cached;
 	}
 	let result;
 	if (!tsconfigPath) {
@@ -109,8 +110,9 @@ export function resolveCompilerOptions(filePath) {
  */
 export function getLanguageService(tsconfigPath, compilerOptions) {
 	const cacheKey = tsconfigPath ?? "__default__";
-	if (serviceCache.has(cacheKey)) {
-		return serviceCache.get(cacheKey);
+	const cachedService = serviceCache.get(cacheKey);
+	if (cachedService) {
+		return cachedService;
 	}
 	// Create a mutable set to track files for this service
 	const files = new Set();

package/dist/types.js

@@ -5,6 +5,8 @@
  *
  * @summary Shared type definitions for output shapes, error codes, and parsed structures
  */
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 /** Priority order for validation status categories */
 export const VALIDATION_STATUS_PRIORITY = [
 	"syntax_error",
@@ -29,3 +31,5 @@ export function appendText(existing, addition) {
 	if (existing.length === 0) return addition;
 	return `${existing} ${addition}`;
 }
+/** Default cache directory under os.tmpdir() */
+export const DEFAULT_CACHE_DIR = join(tmpdir(), ".jsdoczoom-cache");