jsdoczoom 0.2.1 → 0.3.1

package/dist/barrel.js

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync } from "node:fs";
-import { basename, dirname, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
 /**
  * Barrel detection and child discovery for index.ts/index.tsx files.
  * A barrel is strictly `index.ts` or `index.tsx`; other index variants
@@ -83,3 +83,28 @@ function findChildBarrel(subdirPath) {
 	}
 	return null;
 }
+/** Minimum number of .ts/.tsx files in a directory to require a barrel. */
+export const BARREL_THRESHOLD = 3;
+/**
+ * Find directories with more than BARREL_THRESHOLD .ts/.tsx files
+ * that lack a barrel file (index.ts or index.tsx).
+ */
+export function findMissingBarrels(filePaths, cwd) {
+	const dirCounts = new Map();
+	for (const filePath of filePaths) {
+		if (isBarrel(filePath)) continue;
+		const dir = dirname(filePath);
+		dirCounts.set(dir, (dirCounts.get(dir) ?? 0) + 1);
+	}
+	const missing = [];
+	for (const [dir, count] of dirCounts) {
+		if (count <= BARREL_THRESHOLD) continue;
+		const hasBarrel =
+			existsSync(join(dir, "index.ts")) || existsSync(join(dir, "index.tsx"));
+		if (!hasBarrel) {
+			const rel = relative(cwd, dir) || ".";
+			missing.push(rel);
+		}
+	}
+	return missing.sort();
+}

package/dist/cli.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-import { resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { drilldown, drilldownFiles } from "./drilldown.js";
 import { JsdocError } from "./errors.js";
 import { lint } from "./lint.js";
@@ -9,10 +11,10 @@ import { VALIDATION_STATUS_PRIORITY } from "./types.js";
 import { validate } from "./validate.js";
 
 /**
- * Parses argv flags (--help, --validate, --lint, --skill, --pretty, --limit,
- * --no-gitignore), dispatches to drilldown, validation, or lint mode, and
- * handles stdin piping. Errors are written to stderr as JSON; validation and
- * lint failures use exit code 2 while other errors use exit code 1.
+ * Parses argv flags (--help, --version, --check, --lint, --skill, --pretty,
+ * --limit, --no-gitignore), dispatches to drilldown, validation, or lint mode,
+ * and handles stdin piping. Errors are written to stderr as JSON; validation
+ * and lint failures use exit code 2 while other errors use exit code 1.
  *
  * @summary CLI entry point -- argument parsing, mode dispatch, and exit code handling
  */
@@ -24,7 +26,8 @@ Each file has four detail levels (1-indexed): @1 summary, @2 description,
 
 Options:
   -h, --help       Show this help text
-  -v, --validate   Run validation mode
+  -v, --version    Show version number
+  -c, --check      Run validation mode
   -l, --lint       Run lint mode (comprehensive JSDoc quality)
   -s, --skill      Print JSDoc writing guidelines
   --pretty         Format JSON output with 2-space indent
@@ -43,7 +46,7 @@ Stdin:
   Pipe file paths one per line:
     find . -name "*.ts" | jsdoczoom
     find . -name "*.ts" | jsdoczoom @2
-    find . -name "*.ts" | jsdoczoom -v
+    find . -name "*.ts" | jsdoczoom -c
 
 Output:
   JSON items. Items with "next_id" have more detail; use that value as the next
@@ -54,7 +57,7 @@ Barrel gating (glob mode):
   At depth 3 the barrel disappears and its children appear at depth 1.
 
 Modes:
-  -v  Validate file-level structure (has JSDoc block, @summary, description)
+  -c  Validate file-level structure (has JSDoc block, @summary, description)
   -l  Lint comprehensive JSDoc quality (file-level + function-level tags)
 
 Exit codes:
@@ -78,7 +81,8 @@ Workflow:
  */
 function parseArgs(args) {
 	let help = false;
-	let validateMode = false;
+	let version = false;
+	let checkMode = false;
 	let lintMode = false;
 	let skillMode = false;
 	let pretty = false;
@@ -90,8 +94,10 @@ function parseArgs(args) {
 		const arg = args[i];
 		if (arg === "-h" || arg === "--help") {
 			help = true;
-		} else if (arg === "-v" || arg === "--validate") {
-			validateMode = true;
+		} else if (arg === "-v" || arg === "--version") {
+			version = true;
+		} else if (arg === "-c" || arg === "--check") {
+			checkMode = true;
 		} else if (arg === "-l" || arg === "--lint") {
 			lintMode = true;
 		} else if (arg === "-s" || arg === "--skill") {
@@ -114,7 +120,8 @@ function parseArgs(args) {
 	}
 	return {
 		help,
-		validateMode,
+		version,
+		checkMode,
 		lintMode,
 		skillMode,
 		pretty,
@@ -148,7 +155,7 @@ function extractDepthFromArg(selectorArg) {
 async function processStdin(
 	stdin,
 	selectorArg,
-	validateMode,
+	checkMode,
 	lintMode,
 	pretty,
 	limit,
@@ -161,7 +168,7 @@ async function processStdin(
 		const { lintFiles } = await import("./lint.js");
 		const result = await lintFiles(stdinPaths, cwd, limit);
 		writeLintResult(result, pretty);
-	} else if (validateMode) {
+	} else if (checkMode) {
 		const { validateFiles } = await import("./validate.js");
 		const result = await validateFiles(stdinPaths, cwd, limit);
 		writeValidationResult(result, pretty);
@@ -175,7 +182,7 @@ async function processStdin(
  */
 async function processSelector(
 	selectorArg,
-	validateMode,
+	checkMode,
 	lintMode,
 	pretty,
 	limit,
@@ -188,7 +195,7 @@ async function processSelector(
 	if (lintMode) {
 		const result = await lint(selector, cwd, limit, gitignore);
 		writeLintResult(result, pretty);
-	} else if (validateMode) {
+	} else if (checkMode) {
 		const result = await validate(selector, cwd, limit, gitignore);
 		writeValidationResult(result, pretty);
 	} else {
@@ -218,7 +225,8 @@ export async function main(args, stdin) {
 	try {
 		const {
 			help,
-			validateMode,
+			version,
+			checkMode,
 			lintMode,
 			skillMode,
 			pretty,
@@ -231,6 +239,16 @@ export async function main(args, stdin) {
 			process.stdout.write(HELP_TEXT);
 			return;
 		}
+		if (version) {
+			const pkgPath = resolve(
+				dirname(fileURLToPath(import.meta.url)),
+				"..",
+				"package.json",
+			);
+			const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+			process.stdout.write(`${pkg.version}\n`);
+			return;
+		}
 		if (skillMode) {
 			process.stdout.write(SKILL_TEXT);
 			return;
@@ -250,9 +268,9 @@ export async function main(args, stdin) {
 			}
 			return;
 		}
-		if (validateMode && lintMode) {
+		if (checkMode && lintMode) {
 			writeError(
-				new JsdocError("INVALID_SELECTOR", "Cannot use -v and -l together"),
+				new JsdocError("INVALID_SELECTOR", "Cannot use -c and -l together"),
 			);
 			return;
 		}
@@ -261,7 +279,7 @@ export async function main(args, stdin) {
 			await processStdin(
 				stdin,
 				selectorArg,
-				validateMode,
+				checkMode,
 				lintMode,
 				pretty,
 				limit,
@@ -270,7 +288,7 @@ export async function main(args, stdin) {
 		} else {
 			await processSelector(
 				selectorArg,
-				validateMode,
+				checkMode,
 				lintMode,
 				pretty,
 				limit,

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/lint.js

@@ -10,6 +10,7 @@
  */
 import { readFileSync } from "node:fs";
 import { relative } from "node:path";
+import { findMissingBarrels } from "./barrel.js";
 import { JsdocError } from "./errors.js";
 import { createLintLinter, lintFileForLint } from "./eslint-engine.js";
 import { discoverFiles } from "./file-discovery.js";
@@ -36,9 +37,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 +50,7 @@ function buildLintResult(fileResults, totalFiles, limit) {
 	const truncated = filesWithIssues.length > limit;
 	return {
 		files: cappedFiles,
+		...(missingBarrels.length > 0 ? { missingBarrels } : {}),
 		summary: {
 			totalFiles,
 			filesWithIssues: filesWithIssues.length,
@@ -83,7 +86,8 @@ export async function lint(selector, cwd, limit = 100, gitignore = true) {
 	const fileResults = await Promise.all(
 		tsFiles.map((f) => lintSingleFile(eslint, f, cwd)),
 	);
-	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.
@@ -104,5 +108,6 @@ export async function lintFiles(filePaths, cwd, limit = 100) {
 	const fileResults = await Promise.all(
 		tsFiles.map((f) => lintSingleFile(eslint, f, cwd)),
 	);
-	return buildLintResult(fileResults, tsFiles.length, limit);
+	const missingBarrels = findMissingBarrels(tsFiles, cwd);
+	return buildLintResult(fileResults, tsFiles.length, limit, missingBarrels);
 }

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,147 @@ 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__";
+	const cached = compilerOptionsCache.get(cacheKey);
+	if (cached) {
+		return cached;
+	}
+	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__";
+	const cachedService = serviceCache.get(cacheKey);
+	if (cachedService) {
+		return cachedService;
+	}
+	// 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 +172,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/dist/validate.js

@@ -1,6 +1,6 @@
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
-import { isBarrel } from "./barrel.js";
+import { readFileSync } from "node:fs";
+import { relative } from "node:path";
+import { findMissingBarrels } from "./barrel.js";
 import { JsdocError } from "./errors.js";
 import {
 	createValidationLinter,
@@ -29,31 +29,6 @@ async function classifyFile(eslint, filePath, cwd) {
 	const status = mapToValidationStatus(messages);
 	return { path: relativePath, status };
 }
-/** Minimum number of .ts/.tsx files in a directory to require a barrel. */
-const BARREL_THRESHOLD = 3;
-/**
- * Find directories with more than BARREL_THRESHOLD .ts/.tsx files
- * that lack a barrel file (index.ts or index.tsx).
- */
-function findMissingBarrels(filePaths, cwd) {
-	const dirCounts = new Map();
-	for (const filePath of filePaths) {
-		if (isBarrel(filePath)) continue;
-		const dir = dirname(filePath);
-		dirCounts.set(dir, (dirCounts.get(dir) ?? 0) + 1);
-	}
-	const missing = [];
-	for (const [dir, count] of dirCounts) {
-		if (count <= BARREL_THRESHOLD) continue;
-		const hasBarrel =
-			existsSync(join(dir, "index.ts")) || existsSync(join(dir, "index.tsx"));
-		if (!hasBarrel) {
-			const rel = relative(cwd, dir) || ".";
-			missing.push(rel);
-		}
-	}
-	return missing.sort();
-}
 /**
  * Group file statuses into a ValidationResult, applying a limit
  * to the total number of invalid file paths shown.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "jsdoczoom",
-	"version": "0.2.1",
+	"version": "0.3.1",
 	"description": "CLI tool for extracting JSDoc summaries at configurable depths",
 	"type": "module",
 	"sideEffects": false,
@@ -42,16 +42,16 @@
 		"release:dry-run": "bash ../../scripts/release-package.sh jsdoczoom --dry-run"
 	},
 	"dependencies": {
-		"@typescript-eslint/parser": "^8.21.0",
-		"eslint": "^9.20.0",
-		"eslint-plugin-jsdoc": "^50.6.4",
-		"glob": "^11.0.0",
+		"@typescript-eslint/parser": "^8.55.0",
+		"eslint": "^10.0.0",
+		"eslint-plugin-jsdoc": "^62.5.5",
+		"glob": "^13.0.3",
 		"ignore": "^7.0.5",
 		"typescript": "^5.9.3"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.3.14",
-		"@types/node": "^24",
-		"vitest": "4.0.13"
+		"@biomejs/biome": "2.4.1",
+		"@types/node": "^25.2.3",
+		"vitest": "4.0.18"
 	}
 }

package/types/barrel.d.ts

@@ -33,3 +33,13 @@ export declare function getBarrelChildren(
 	barrelPath: string,
 	_cwd: string,
 ): string[];
+/** Minimum number of .ts/.tsx files in a directory to require a barrel. */
+export declare const BARREL_THRESHOLD = 3;
+/**
+ * Find directories with more than BARREL_THRESHOLD .ts/.tsx files
+ * that lack a barrel file (index.ts or index.tsx).
+ */
+export declare function findMissingBarrels(
+	filePaths: string[],
+	cwd: string,
+): string[];

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;
@@ -98,6 +104,7 @@ export interface LintFileResult {
 /** Overall lint result with summary statistics */
 export interface LintResult {
 	files: LintFileResult[];
+	missingBarrels?: string[];
 	summary: {
 		totalFiles: number;
 		filesWithIssues: number;