jsdoczoom 1.2.0 → 1.2.2

package/dist/cache.js

@@ -10,6 +10,7 @@
 import { createHash } from "node:crypto";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { debugCache, recordCacheHit, recordCacheMiss } from "./debug.js";
 /**
  * Compute a SHA-256 content hash for the given string.
  *
@@ -89,8 +90,11 @@ export async function processWithCache(config, mode, content, compute) {
 	await ensureCacheDir(config, mode);
 	const cached = await readCacheEntry(config, mode, hash);
 	if (cached !== null) {
+		recordCacheHit();
 		return cached;
 	}
+	recordCacheMiss();
+	debugCache("[MISS] mode=%s hash=%s", mode, hash.slice(0, 8));
 	const result = await compute();
 	await writeCacheEntry(config, mode, hash, result);
 	return result;

package/dist/cli.js

@@ -2,8 +2,15 @@
 import { readFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+	createDebug,
+	debugDiscovery,
+	flushCacheSummary,
+	time,
+} from "./debug.js";
 import { drilldown, drilldownFiles } from "./drilldown.js";
 import { JsdocError } from "./errors.js";
+import { discoverFiles } from "./file-discovery.js";
 import { lint, lintFiles } from "./lint.js";
 import { search, searchFiles } from "./search.js";
 import { parseSelector } from "./selector.js";
@@ -40,6 +47,7 @@ Options:
   --disable-cache    Skip all cache operations
   --cache-directory  Override cache directory (default: system temp)
   --explain-rule R  Explain a lint rule with examples (e.g. jsdoc/informative-docs)
+  --debug            Enable debug timing output (stderr). Equivalent to DEBUG=jsdoczoom:*
 
 Selector:
   A glob pattern or file path, optionally with @depth suffix (1-4).
@@ -113,7 +121,9 @@ function parseArgs(args) {
 		cacheDirectory: undefined,
 		explainRule: undefined,
 		selectorArg: undefined,
+		extraArgs: [],
 		searchQuery: undefined,
+		debug: false,
 	};
 	for (let i = 0; i < args.length; i++) {
 		const arg = args[i];
@@ -154,6 +164,10 @@ function parseArgs(args) {
 			parsed.disableCache = true;
 			continue;
 		}
+		if (arg === "--debug") {
+			parsed.debug = true;
+			continue;
+		}
 		// Value flags
 		if (arg === "--limit") {
 			const { value, nextIndex } = parseValueFlag(args, i);
@@ -189,6 +203,8 @@ function parseArgs(args) {
 		// Positional selector arg
 		if (parsed.selectorArg === undefined) {
 			parsed.selectorArg = arg;
+		} else {
+			parsed.extraArgs.push(arg);
 		}
 	}
 	return parsed;
@@ -212,28 +228,29 @@ function extractDepthFromArg(selectorArg) {
 	return parsed.depth;
 }
 /**
- * Process stdin mode: file paths piped in.
+ * Process an explicit list of resolved file paths.
  */
-async function processStdin(
-	stdin,
+async function processFileList(
+	filePaths,
 	selectorArg,
 	checkMode,
 	lintMode,
 	json,
 	pretty,
 	limit,
+	gitignore,
 	cwd,
 	cacheConfig,
 	searchQuery,
 ) {
-	const stdinPaths = parseStdinPaths(stdin, cwd);
 	const depth =
 		selectorArg !== undefined ? extractDepthFromArg(selectorArg) : undefined;
 	if (searchQuery !== undefined) {
 		const result = await searchFiles(
-			stdinPaths,
+			filePaths,
 			searchQuery,
 			cwd,
+			gitignore,
 			limit,
 			cacheConfig,
 		);
@@ -241,22 +258,54 @@ async function processStdin(
 		return;
 	}
 	if (lintMode) {
-		const result = await lintFiles(stdinPaths, cwd, limit, cacheConfig);
+		const result = await lintFiles(filePaths, cwd, limit, cacheConfig);
 		writeLintResult(result, pretty);
 	} else if (checkMode) {
-		const result = await validateFiles(stdinPaths, cwd, limit, cacheConfig);
+		const result = await validateFiles(filePaths, cwd, limit, cacheConfig);
 		writeValidationResult(result, pretty);
 	} else {
 		const result = await drilldownFiles(
-			stdinPaths,
+			filePaths,
 			depth,
 			cwd,
 			limit,
 			cacheConfig,
 		);
+		flushCacheSummary(`drilldown ${filePaths.length} files`);
 		writeDrilldownResult(result, json, pretty);
 	}
 }
+/**
+ * Process stdin mode: file paths piped in.
+ */
+async function processStdin(
+	stdin,
+	selectorArg,
+	checkMode,
+	lintMode,
+	json,
+	pretty,
+	limit,
+	gitignore,
+	cwd,
+	cacheConfig,
+	searchQuery,
+) {
+	const stdinPaths = parseStdinPaths(stdin, cwd);
+	await processFileList(
+		stdinPaths,
+		selectorArg,
+		checkMode,
+		lintMode,
+		json,
+		pretty,
+		limit,
+		gitignore,
+		cwd,
+		cacheConfig,
+		searchQuery,
+	);
+}
 /**
  * Process selector mode: glob or path argument.
  */
@@ -305,19 +354,27 @@ async function processSelector(
 	}
 }
 /**
- * Write an error to stderr as JSON and set exit code.
+ * Write an error to stderr as JSON or plain text depending on the json flag.
  */
-function writeError(error) {
+function writeError(error, json) {
+	process.exitCode = 1;
+	if (json) {
+		if (error instanceof JsdocError) {
+			void process.stderr.write(`${JSON.stringify(error.toJSON())}\n`);
+			return;
+		}
+		const message = error instanceof Error ? error.message : String(error);
+		void process.stderr.write(
+			`${JSON.stringify({ error: { code: "INTERNAL_ERROR", message } })}\n`,
+		);
+		return;
+	}
 	if (error instanceof JsdocError) {
-		void process.stderr.write(`${JSON.stringify(error.toJSON())}\n`);
-		process.exitCode = 1;
+		void process.stderr.write(`Error [${error.code}]: ${error.message}\n`);
 		return;
 	}
 	const message = error instanceof Error ? error.message : String(error);
-	void process.stderr.write(
-		`${JSON.stringify({ error: { code: "INTERNAL_ERROR", message } })}\n`,
-	);
-	process.exitCode = 1;
+	void process.stderr.write(`Error: ${message}\n`);
 }
 /**
  * Handle --help flag by printing help text.
@@ -346,7 +403,7 @@ function handleSkill() {
 /**
  * Handle --explain-rule flag by printing rule explanation.
  */
-function handleExplainRule(ruleName) {
+function handleExplainRule(ruleName, json) {
 	const explanation = RULE_EXPLANATIONS[ruleName];
 	if (explanation) {
 		void process.stdout.write(explanation);
@@ -358,13 +415,14 @@ function handleExplainRule(ruleName) {
 			"INVALID_SELECTOR",
 			`Unknown rule: ${ruleName}. Available rules: ${available}`,
 		),
+		json,
 	);
 }
 /**
  * Handle early-exit flags that print output and return without processing files.
  * Returns true if an early-exit flag was handled.
  */
-async function handleEarlyExitFlags(parsed) {
+async function handleEarlyExitFlags(parsed, json) {
 	if (parsed.help) {
 		handleHelp();
 		return true;
@@ -378,7 +436,7 @@ async function handleEarlyExitFlags(parsed) {
 		return true;
 	}
 	if (parsed.explainRule !== undefined) {
-		handleExplainRule(parsed.explainRule);
+		handleExplainRule(parsed.explainRule, json);
 		return true;
 	}
 	return false;
@@ -387,10 +445,11 @@ async function handleEarlyExitFlags(parsed) {
  * Validate that mode flags are not used in incompatible combinations.
  * Returns true if validation passed (no conflicts), false if an error was written.
  */
-function validateModeCombinations(parsed) {
+function validateModeCombinations(parsed, json) {
 	if (parsed.checkMode && parsed.lintMode) {
 		writeError(
 			new JsdocError("INVALID_SELECTOR", "Cannot use -c and -l together"),
+			json,
 		);
 		return false;
 	}
@@ -400,6 +459,7 @@ function validateModeCombinations(parsed) {
 	) {
 		writeError(
 			new JsdocError("INVALID_SELECTOR", "Cannot use --search with -c or -l"),
+			json,
 		);
 		return false;
 	}
@@ -409,10 +469,14 @@ function validateModeCombinations(parsed) {
  * Main CLI entry point. Exported for testability.
  */
 export async function main(args, stdin) {
+	const json = args.includes("--json");
+	if (args.includes("--debug")) {
+		createDebug.enable("jsdoczoom:*");
+	}
 	try {
 		const parsed = parseArgs(args);
-		if (await handleEarlyExitFlags(parsed)) return;
-		if (!validateModeCombinations(parsed)) return;
+		if (await handleEarlyExitFlags(parsed, json)) return;
+		if (!validateModeCombinations(parsed, json)) return;
 		const cacheConfig = {
 			enabled: !parsed.disableCache,
 			directory: parsed.cacheDirectory ?? DEFAULT_CACHE_DIR,
@@ -427,6 +491,37 @@ export async function main(args, stdin) {
 				parsed.json,
 				parsed.pretty,
 				parsed.limit,
+				parsed.gitignore,
+				cwd,
+				cacheConfig,
+				parsed.searchQuery,
+			);
+		} else if (parsed.extraArgs.length > 0) {
+			// Multiple positional args (e.g. shell-expanded glob): expand each to
+			// .ts/.tsx files via discoverFiles (handles directories recursively)
+			const allArgPaths = [
+				...(parsed.selectorArg ? [parsed.selectorArg] : []),
+				...parsed.extraArgs,
+			];
+			const fileLists = await time(
+				debugDiscovery,
+				`discover ${allArgPaths.length} paths`,
+				() =>
+					Promise.all(
+						allArgPaths.map((p) => discoverFiles(p, cwd, parsed.gitignore)),
+					),
+			);
+			const filePaths = [...new Set(fileLists.flat())];
+			debugDiscovery("discover total=%d unique files", filePaths.length);
+			await processFileList(
+				filePaths,
+				parsed.selectorArg,
+				parsed.checkMode,
+				parsed.lintMode,
+				parsed.json,
+				parsed.pretty,
+				parsed.limit,
+				parsed.gitignore,
 				cwd,
 				cacheConfig,
 				parsed.searchQuery,
@@ -446,7 +541,7 @@ export async function main(args, stdin) {
 			);
 		}
 	} catch (error) {
-		writeError(error);
+		writeError(error, json);
 	}
 }
 /**

package/dist/debug.js

@@ -0,0 +1,61 @@
+/**
+ * Shared debug instances and timing utilities for jsdoczoom.
+ *
+ * Activate with DEBUG=jsdoczoom:* or via the --debug CLI flag.
+ * Each namespace maps to a source module. Delta timing (+NNNms) is
+ * provided automatically by the debug package between calls on the
+ * same namespace.
+ *
+ * @summary Namespaced debug loggers and perf_hooks timing helper
+ */
+import { performance } from "node:perf_hooks";
+import createDebug from "debug";
+export const debugDiscovery = createDebug("jsdoczoom:discovery");
+export const debugSearch = createDebug("jsdoczoom:search");
+export const debugCache = createDebug("jsdoczoom:cache");
+export const debugEslint = createDebug("jsdoczoom:eslint");
+export const debugLint = createDebug("jsdoczoom:lint");
+export const debugValidate = createDebug("jsdoczoom:validate");
+export const debugBarrel = createDebug("jsdoczoom:barrel");
+export const debugDrilldown = createDebug("jsdoczoom:drilldown");
+export const debugTs = createDebug("jsdoczoom:ts");
+export { createDebug };
+/** Accumulated cache hits since last flushCacheSummary call. */
+let _cacheHits = 0;
+/** Accumulated cache misses since last flushCacheSummary call. */
+let _cacheMisses = 0;
+/** Record a cache hit without emitting a log line. */
+export function recordCacheHit() {
+	_cacheHits++;
+}
+/** Record a cache miss without emitting a log line. */
+export function recordCacheMiss() {
+	_cacheMisses++;
+}
+/**
+ * Emit a single cache summary line and reset the counters.
+ * Call this after each batch of processWithCache operations.
+ *
+ * @param label - Describes the batch (e.g. "search 326 files")
+ */
+export function flushCacheSummary(label) {
+	if (_cacheHits === 0 && _cacheMisses === 0) return;
+	debugCache("[SUMMARY] %s hits=%d misses=%d", label, _cacheHits, _cacheMisses);
+	_cacheHits = 0;
+	_cacheMisses = 0;
+}
+/**
+ * Wrap an async operation with start/done timing logs.
+ *
+ * @param dbg - Debug instance to log to
+ * @param label - Label shown in start/done messages
+ * @param fn - Async operation to time
+ * @returns Result of fn
+ */
+export async function time(dbg, label, fn) {
+	const t0 = performance.now();
+	dbg("%s start", label);
+	const result = await fn();
+	dbg("%s done %sms", label, (performance.now() - t0).toFixed(1));
+	return result;
+}

package/dist/drilldown.js

@@ -2,6 +2,7 @@ import { readFile } from "node:fs/promises";
 import { dirname, relative } from "node:path";
 import { getBarrelChildren, isBarrel } from "./barrel.js";
 import { processWithCache } from "./cache.js";
+import { debugDrilldown } from "./debug.js";
 import { JsdocError } from "./errors.js";
 import { discoverFiles, loadGitignore } from "./file-discovery.js";
 import { parseFileSummaries } from "./jsdoc-parser.js";
@@ -83,6 +84,12 @@ function processFile(
 		effectiveDepth < TERMINAL_LEVEL &&
 		levels[effectiveDepth - 1] === null
 	) {
+		debugDrilldown(
+			"depth advance: depth=%d → %d (null level) file=%s",
+			effectiveDepth,
+			effectiveDepth + 1,
+			idPath,
+		);
 		effectiveDepth++;
 	}
 	const level = levels[effectiveDepth - 1];
@@ -238,6 +245,10 @@ async function processBarrelAtDepth(barrel, depth, cwd, config) {
 	// Null-skip: if depth 2 but no description, advance to transition depth
 	let effectiveDepth = depth;
 	if (effectiveDepth === 2 && !barrel.hasDescription) {
+		debugDrilldown(
+			"barrel depth advance: depth=2 → 3 (no description) barrel=%s",
+			relative(cwd, barrel.path),
+		);
 		effectiveDepth = 3;
 	}
 	if (effectiveDepth < 3) {
@@ -255,6 +266,13 @@ async function processBarrelAtDepth(barrel, depth, cwd, config) {
 	}
 	// Barrel transitions: barrel disappears, children appear
 	const childDepth = effectiveDepth - 2;
+	debugDrilldown(
+		"barrel transition: barrel=%s depth=%d → children=%d at childDepth=%d",
+		relative(cwd, barrel.path),
+		effectiveDepth,
+		barrel.children.length,
+		childDepth,
+	);
 	return collectSafeResults(barrel.children, childDepth, cwd, config);
 }
 /**
@@ -295,6 +313,13 @@ async function processGlobWithBarrels(files, depth, cwd, config) {
 		config,
 	);
 	const gatedFiles = buildGatedFileSet(barrelInfos);
+	debugDrilldown(
+		"barrel gating: barrels=%d non-barrels=%d gated=%d depth=%d",
+		barrelPaths.length,
+		nonBarrelPaths.length,
+		gatedFiles.size,
+		depth,
+	);
 	const results = [...barrelErrors];
 	const barrelResults = await Promise.all(
 		barrelInfos

package/dist/eslint-engine.js

@@ -6,6 +6,7 @@
 import tsParser from "@typescript-eslint/parser";
 import { ESLint } from "eslint";
 import jsdocPlugin from "eslint-plugin-jsdoc";
+import { debugEslint, time } from "./debug.js";
 import plugin from "./eslint-plugin.js";
 
 /** Common invalid JSDoc tags and their recommended replacements */
@@ -115,7 +116,9 @@ export function createLintLinter(cwd) {
  * @returns Simplified message list with ruleId, messageId, and fatal flag
  */
 export async function lintFileForValidation(eslint, sourceText, filePath) {
-	const results = await eslint.lintText(sourceText, { filePath });
+	const results = await time(debugEslint, `validate ${filePath}`, () =>
+		eslint.lintText(sourceText, { filePath }),
+	);
 	if (results.length === 0) return [];
 	return results[0].messages.map((msg) => ({
 		ruleId: msg.ruleId,
@@ -204,7 +207,9 @@ function extractSymbolName(sourceText, line) {
  * @returns Array of lint diagnostics with line, column, rule, message, and severity
  */
 export async function lintFileForLint(eslint, sourceText, filePath) {
-	const results = await eslint.lintText(sourceText, { filePath });
+	const results = await time(debugEslint, `lint ${filePath}`, () =>
+		eslint.lintText(sourceText, { filePath }),
+	);
 	if (results.length === 0) return [];
 	return results[0].messages.map((msg) => {
 		const diagnostic = {

package/dist/file-discovery.js

@@ -1,24 +1,43 @@
-import { readFile, stat } from "node:fs/promises";
+import { readFile, realpath, stat } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
 import { glob } from "glob";
 import ignore from "ignore";
+import { debugDiscovery } from "./debug.js";
 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
- * filter since the user explicitly named the file. The ignore instance is
- * created per call -- no caching -- because cwd may differ between invocations.
+ * filter since the user explicitly named the file. Results are cached per
+ * cwd for the process lifetime so concurrent discoverFiles calls sharing a
+ * cwd only walk the filesystem once.
  *
  * @summary Resolve selector patterns to absolute file paths with gitignore filtering
  */
+/** Process-lifetime cache: cwd → in-flight or settled Ignore promise. */
+const gitignoreCache = new Map();
 /**
  * Walk from `cwd` up to the filesystem root, collecting .gitignore entries.
- * Returns an Ignore instance loaded with all discovered rules.
+ * Returns an Ignore instance loaded with all discovered rules. Results are
+ * cached per cwd so repeated calls (e.g. from concurrent discoverFiles calls)
+ * only perform the filesystem walk once.
  */
-export async function loadGitignore(cwd) {
+export function loadGitignore(cwd) {
+	const key = resolve(cwd);
+	const cached = gitignoreCache.get(key);
+	if (cached !== undefined) {
+		return cached;
+	}
+	const promise = loadGitignoreUncached(key);
+	gitignoreCache.set(key, promise);
+	return promise;
+}
+async function loadGitignoreUncached(cwd) {
 	const ig = ignore();
 	let dir = resolve(cwd);
+	let walkDepth = 0;
 	while (true) {
+		debugDiscovery("gitignore walk depth=%d dir=%s", walkDepth, dir);
 		const gitignorePath = join(dir, ".gitignore");
 		try {
 			const content = await readFile(gitignorePath, "utf-8");
@@ -27,6 +46,12 @@ export async function loadGitignore(cwd) {
 				.split("\n")
 				.map((l) => l.trim())
 				.filter((l) => l && !l.startsWith("#"));
+			debugDiscovery(
+				"gitignore depth=%d loaded %d rules from %s",
+				walkDepth,
+				lines.length,
+				gitignorePath,
+			);
 			for (const line of lines) {
 				// Prefix rules from ancestor .gitignore files so paths are
 				// relative to `cwd`, which is where glob results are anchored.
@@ -36,8 +61,15 @@ export async function loadGitignore(cwd) {
 			// No .gitignore at this level, continue walking up
 		}
 		const parent = dirname(dir);
-		if (parent === dir) break;
+		if (parent === dir) {
+			debugDiscovery(
+				"gitignore walk complete at depth=%d (reached root)",
+				walkDepth,
+			);
+			break;
+		}
 		dir = parent;
+		walkDepth++;
 	}
 	return ig;
 }
@@ -57,15 +89,52 @@ export async function loadGitignore(cwd) {
 export async function discoverFiles(pattern, cwd, gitignore = true) {
 	const hasGlobChars = /[*?[\]{]/.test(pattern);
 	if (hasGlobChars) {
+		debugDiscovery("glob pattern=%s", pattern);
 		const matches = await glob(pattern, { cwd, absolute: true });
 		let filtered = matches.filter(
 			(f) => (f.endsWith(".ts") || f.endsWith(".tsx")) && !f.endsWith(".d.ts"),
 		);
 		if (gitignore) {
+			const preFilter = filtered.length;
 			const ig = await loadGitignore(cwd);
 			filtered = filtered.filter((abs) => !ig.ignores(relative(cwd, abs)));
+			debugDiscovery(
+				"glob done pattern=%s matched=%d after-gitignore=%d",
+				pattern,
+				preFilter,
+				filtered.length,
+			);
+		} else {
+			debugDiscovery(
+				"glob done pattern=%s matched=%d",
+				pattern,
+				filtered.length,
+			);
 		}
-		return filtered.sort();
+		// Deduplicate by realpath so symlinks to the same physical file are
+		// processed only once. Glob prevents infinite cycles but can still
+		// return the same inode at multiple paths (e.g. via directory symlinks).
+		const withRealpaths = await Promise.all(
+			filtered.map(async (abs) => ({
+				abs,
+				real: await realpath(abs).catch(() => abs),
+			})),
+		);
+		const seen = new Set();
+		const deduped = [];
+		for (const { abs, real } of withRealpaths) {
+			if (seen.has(real)) {
+				debugDiscovery(
+					"symlink dedup: skipping %s (same realpath as earlier entry %s)",
+					abs,
+					real,
+				);
+				continue;
+			}
+			seen.add(real);
+			deduped.push(abs);
+		}
+		return deduped.sort();
 	}
 	// Direct path
 	const resolved = resolve(cwd, pattern);
@@ -76,6 +145,10 @@ export async function discoverFiles(pattern, cwd, gitignore = true) {
 		throw new JsdocError("FILE_NOT_FOUND", `File not found: ${pattern}`);
 	}
 	if (statResult.isDirectory()) {
+		debugDiscovery(
+			"discoverFiles recursing: directory path=%s → glob",
+			resolved,
+		);
 		return discoverFiles(`${resolved}/**`, cwd, gitignore);
 	}
 	return [resolved];

package/dist/lint.js

@@ -12,6 +12,7 @@ import { readFile } from "node:fs/promises";
 import { relative } from "node:path";
 import { findMissingBarrels } from "./barrel.js";
 import { processWithCache } from "./cache.js";
+import { debugLint, flushCacheSummary, time } from "./debug.js";
 import { JsdocError } from "./errors.js";
 import { createLintLinter, lintFileForLint } from "./eslint-engine.js";
 import { discoverFiles } from "./file-discovery.js";
@@ -98,9 +99,14 @@ export async function lint(
 	}
 	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, config)),
+	debugLint("lint start files=%d pattern=%s", tsFiles.length, selector.pattern);
+	const fileResults = await time(
+		debugLint,
+		`lint ${tsFiles.length} files`,
+		() =>
+			Promise.all(tsFiles.map((f) => lintSingleFile(eslint, f, cwd, config))),
 	);
+	flushCacheSummary(`lint ${tsFiles.length} files`);
 	const missingBarrels = await findMissingBarrels(tsFiles, cwd);
 	return buildLintResult(fileResults, tsFiles.length, limit, missingBarrels);
 }
@@ -126,9 +132,14 @@ export async function lintFiles(
 		(f) => f.endsWith(".ts") || f.endsWith(".tsx"),
 	);
 	const eslint = createLintLinter(cwd);
-	const fileResults = await Promise.all(
-		tsFiles.map((f) => lintSingleFile(eslint, f, cwd, config)),
+	debugLint("lintFiles start files=%d", tsFiles.length);
+	const fileResults = await time(
+		debugLint,
+		`lintFiles ${tsFiles.length} files`,
+		() =>
+			Promise.all(tsFiles.map((f) => lintSingleFile(eslint, f, cwd, config))),
 	);
+	flushCacheSummary(`lintFiles ${tsFiles.length} files`);
 	const missingBarrels = await findMissingBarrels(tsFiles, cwd);
 	return buildLintResult(fileResults, tsFiles.length, limit, missingBarrels);
 }

package/dist/search.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { relative } from "node:path";
 import { processWithCache } from "./cache.js";
+import { debugSearch, flushCacheSummary, time } from "./debug.js";
 import { JsdocError } from "./errors.js";
 import { discoverFiles, loadGitignore } from "./file-discovery.js";
 import { parseFileSummaries } from "./jsdoc-parser.js";
@@ -53,6 +54,7 @@ async function processFileSafe(filePath, regex, cwd, config) {
 	);
 	// Level 1: filename/path match — fall back through levels like drilldown
 	if (regex.test(idPath)) {
+		debugSearch("depth=1 path match file=%s", idPath);
 		if (info.summary !== null) {
 			return { next_id: `${idPath}@2`, text: info.summary };
 		}
@@ -76,10 +78,12 @@ async function processFileSafe(filePath, regex, cwd, config) {
 	}
 	// Level 2: summary match
 	if (info.summary !== null && regex.test(info.summary)) {
+		debugSearch("depth=2 summary match file=%s", idPath);
 		return { next_id: `${idPath}@2`, text: info.summary };
 	}
 	// Level 3a: description match
 	if (info.description !== null && regex.test(info.description)) {
+		debugSearch("depth=3a description match file=%s", idPath);
 		return { next_id: `${idPath}@3`, text: info.description };
 	}
 	// Level 3b: type declaration match
@@ -93,6 +97,11 @@ async function processFileSafe(filePath, regex, cwd, config) {
 		const chunks = splitDeclarations(dts);
 		const matching = chunks.filter((c) => regex.test(c));
 		if (matching.length > 0) {
+			debugSearch(
+				"depth=3b type-decl match file=%s chunks=%d",
+				idPath,
+				matching.length,
+			);
 			return {
 				next_id: `${idPath}@3`,
 				text: matching
@@ -110,12 +119,18 @@ async function processFileSafe(filePath, regex, cwd, config) {
 	);
 	const matchingBlocks = allBlocks.filter((b) => regex.test(b.blockText));
 	if (matchingBlocks.length > 0) {
+		debugSearch(
+			"depth=4 source-block match file=%s blocks=%d",
+			idPath,
+			matchingBlocks.length,
+		);
 		const fenced = matchingBlocks
 			.map((b) => `\`\`\`typescript\n${b.annotation}\n${b.blockText}\n\`\`\``)
 			.join("\n\n");
 		return { id: `${idPath}@4`, text: fenced };
 	}
 	if (regex.test(content)) {
+		debugSearch("depth=4 full-source match file=%s", idPath);
 		return { id: `${idPath}@4`, text: `\`\`\`typescript\n${content}\n\`\`\`` };
 	}
 	return null; // no match
@@ -148,20 +163,27 @@ function applyLimit(sorted, limit) {
  * Files with parse errors are silently skipped.
  */
 async function searchFileList(files, regex, cwd, limit, config) {
-	const results = await Promise.all(
-		files.map(async (filePath) => {
-			try {
-				return await processFileSafe(filePath, regex, cwd, config);
-			} catch (error) {
-				if (error instanceof JsdocError && error.code === "PARSE_ERROR") {
-					return null;
-				}
-				throw error;
-			}
-		}),
+	const results = await time(
+		debugSearch,
+		`search ${files.length} files query=${regex.source}`,
+		() =>
+			Promise.all(
+				files.map(async (filePath) => {
+					try {
+						return await processFileSafe(filePath, regex, cwd, config);
+					} catch (error) {
+						if (error instanceof JsdocError && error.code === "PARSE_ERROR") {
+							return null;
+						}
+						throw error;
+					}
+				}),
+			),
 	);
+	flushCacheSummary(`search ${files.length} files`);
 	const matched = results.filter((r) => r !== null);
 	const sorted = matched.sort((a, b) => sortKey(a).localeCompare(sortKey(b)));
+	debugSearch("matches=%d", matched.length);
 	return applyLimit(sorted, limit);
 }
 /**
@@ -200,6 +222,7 @@ export async function search(
  * @param filePaths - Array of absolute file paths
  * @param query - Regex query string (case-insensitive)
  * @param cwd - Working directory for relative path output
+ * @param gitignore - Whether to respect .gitignore rules (default true)
  * @param limit - Maximum number of results to return (default 100)
  * @param config - Cache configuration
  * @throws {JsdocError} INVALID_SELECTOR for invalid regex
@@ -208,19 +231,22 @@ export async function searchFiles(
 	filePaths,
 	query,
 	cwd,
+	gitignore = true,
 	limit = 100,
 	config = DEFAULT_CACHE_CONFIG,
 ) {
 	const regex = compileRegex(query);
-	const ig = await loadGitignore(cwd);
-	const tsFiles = filePaths.filter((f) => {
-		if (!(f.endsWith(".ts") || f.endsWith(".tsx")) || f.endsWith(".d.ts")) {
-			return false;
-		}
-		const rel = relative(cwd, f);
-		// Files outside cwd (traversal paths) are beyond the gitignore scope
-		if (rel.startsWith("..")) return true;
-		return !ig.ignores(rel);
-	});
+	let tsFiles = filePaths.filter(
+		(f) => (f.endsWith(".ts") || f.endsWith(".tsx")) && !f.endsWith(".d.ts"),
+	);
+	if (gitignore) {
+		const ig = await loadGitignore(cwd);
+		tsFiles = tsFiles.filter((f) => {
+			const rel = relative(cwd, f);
+			// Files outside cwd (traversal paths) are beyond the gitignore scope
+			if (rel.startsWith("..")) return true;
+			return !ig.ignores(rel);
+		});
+	}
 	return searchFileList(tsFiles, regex, cwd, limit, config);
 }

package/dist/type-declarations.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import ts from "typescript";
+import { debugTs, time } from "./debug.js";
 import { JsdocError } from "./errors.js";
 
 /**
@@ -432,7 +433,11 @@ export async function generateTypeDeclarations(filePath) {
 		throw new JsdocError("PARSE_ERROR", `Failed to parse file: ${filePath}`);
 	}
 	// Get emit output using the language service
-	const emitOutput = service.getEmitOutput(filePath, true); // true = emitOnlyDtsFiles
+	const emitOutput = await time(
+		debugTs,
+		`getEmitOutput ${filePath}`,
+		async () => service.getEmitOutput(filePath, true),
+	);
 	// Find the .d.ts output file
 	const dtsFile = emitOutput.outputFiles.find((file) =>
 		file.name.endsWith(".d.ts"),

package/dist/validate.js

@@ -2,6 +2,7 @@ import { readFile } from "node:fs/promises";
 import { relative } from "node:path";
 import { findMissingBarrels } from "./barrel.js";
 import { processWithCache } from "./cache.js";
+import { debugValidate, flushCacheSummary, time } from "./debug.js";
 import { JsdocError } from "./errors.js";
 import {
 	createValidationLinter,
@@ -105,9 +106,17 @@ export async function validate(
 		);
 	}
 	const eslint = createValidationLinter();
-	const statuses = await Promise.all(
-		files.map((f) => classifyFile(eslint, f, cwd, config)),
+	debugValidate(
+		"validate start files=%d pattern=%s",
+		files.length,
+		selector.pattern,
 	);
+	const statuses = await time(
+		debugValidate,
+		`validate ${files.length} files`,
+		() => Promise.all(files.map((f) => classifyFile(eslint, f, cwd, config))),
+	);
+	flushCacheSummary(`validate ${files.length} files`);
 	const missingBarrels = await findMissingBarrels(files, cwd);
 	return buildGroupedResult(statuses, missingBarrels, limit);
 }
@@ -132,9 +141,13 @@ export async function validateFiles(
 		(f) => f.endsWith(".ts") || f.endsWith(".tsx"),
 	);
 	const eslint = createValidationLinter();
-	const statuses = await Promise.all(
-		tsFiles.map((f) => classifyFile(eslint, f, cwd, config)),
+	debugValidate("validateFiles start files=%d", tsFiles.length);
+	const statuses = await time(
+		debugValidate,
+		`validateFiles ${tsFiles.length} files`,
+		() => Promise.all(tsFiles.map((f) => classifyFile(eslint, f, cwd, config))),
 	);
+	flushCacheSummary(`validateFiles ${tsFiles.length} files`);
 	const missingBarrels = await findMissingBarrels(tsFiles, cwd);
 	return buildGroupedResult(statuses, missingBarrels, limit);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "jsdoczoom",
-	"version": "1.2.0",
+	"version": "1.2.2",
 	"description": "CLI tool for extracting JSDoc summaries at configurable depths",
 	"type": "module",
 	"sideEffects": false,
@@ -43,6 +43,7 @@
 	},
 	"dependencies": {
 		"@typescript-eslint/parser": "^8.55.0",
+		"debug": "^4.4.3",
 		"eslint": "^9.0.0",
 		"eslint-plugin-jsdoc": "^62.5.5",
 		"glob": "^13.0.3",
@@ -51,6 +52,7 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.4.1",
+		"@types/debug": "^4.1.12",
 		"@types/node": "^25.2.3",
 		"vitest": "4.0.18"
 	}

package/types/debug.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared debug instances and timing utilities for jsdoczoom.
+ *
+ * Activate with DEBUG=jsdoczoom:* or via the --debug CLI flag.
+ * Each namespace maps to a source module. Delta timing (+NNNms) is
+ * provided automatically by the debug package between calls on the
+ * same namespace.
+ *
+ * @summary Namespaced debug loggers and perf_hooks timing helper
+ */
+import createDebug from "debug";
+import type { Debugger } from "debug";
+export declare const debugDiscovery: createDebug.Debugger;
+export declare const debugSearch: createDebug.Debugger;
+export declare const debugCache: createDebug.Debugger;
+export declare const debugEslint: createDebug.Debugger;
+export declare const debugLint: createDebug.Debugger;
+export declare const debugValidate: createDebug.Debugger;
+export declare const debugBarrel: createDebug.Debugger;
+export declare const debugDrilldown: createDebug.Debugger;
+export declare const debugTs: createDebug.Debugger;
+export { createDebug };
+/** Record a cache hit without emitting a log line. */
+export declare function recordCacheHit(): void;
+/** Record a cache miss without emitting a log line. */
+export declare function recordCacheMiss(): void;
+/**
+ * Emit a single cache summary line and reset the counters.
+ * Call this after each batch of processWithCache operations.
+ *
+ * @param label - Describes the batch (e.g. "search 326 files")
+ */
+export declare function flushCacheSummary(label: string): void;
+/**
+ * Wrap an async operation with start/done timing logs.
+ *
+ * @param dbg - Debug instance to log to
+ * @param label - Label shown in start/done messages
+ * @param fn - Async operation to time
+ * @returns Result of fn
+ */
+export declare function time<T>(
+	dbg: Debugger,
+	label: string,
+	fn: () => Promise<T>,
+): Promise<T>;

package/types/file-discovery.d.ts

@@ -1,15 +1,9 @@
 import { type Ignore } from "ignore";
-/**
- * Walks .gitignore files from cwd to filesystem root, building an ignore
- * filter that glob results pass through. Direct-path lookups bypass the
- * filter since the user explicitly named the file. The ignore instance is
- * created per call -- no caching -- because cwd may differ between invocations.
- *
- * @summary Resolve selector patterns to absolute file paths with gitignore filtering
- */
 /**
  * Walk from `cwd` up to the filesystem root, collecting .gitignore entries.
- * Returns an Ignore instance loaded with all discovered rules.
+ * Returns an Ignore instance loaded with all discovered rules. Results are
+ * cached per cwd so repeated calls (e.g. from concurrent discoverFiles calls)
+ * only perform the filesystem walk once.
  */
 export declare function loadGitignore(cwd: string): Promise<Ignore>;
 /**

package/types/search.d.ts

@@ -31,6 +31,7 @@ export declare function search(
  * @param filePaths - Array of absolute file paths
  * @param query - Regex query string (case-insensitive)
  * @param cwd - Working directory for relative path output
+ * @param gitignore - Whether to respect .gitignore rules (default true)
  * @param limit - Maximum number of results to return (default 100)
  * @param config - Cache configuration
  * @throws {JsdocError} INVALID_SELECTOR for invalid regex
@@ -39,6 +40,7 @@ export declare function searchFiles(
 	filePaths: string[],
 	query: string,
 	cwd: string,
+	gitignore?: boolean,
 	limit?: number,
 	config?: CacheConfig,
 ): Promise<DrilldownResult>;