jsdoczoom 1.0.0 → 1.2.0

package/dist/barrel.js

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync } from "node:fs";
+import { access, readdir } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve } from "node:path";
 /**
  * Barrel detection and child discovery for index.ts/index.tsx files.
@@ -34,29 +34,34 @@ export function isBarrel(filePath) {
  * @param _cwd - Working directory (unused, kept for API consistency)
  * @returns Sorted array of absolute paths to child files
  */
-export function getBarrelChildren(barrelPath, _cwd) {
+export async function getBarrelChildren(barrelPath, _cwd) {
 	const dir = dirname(barrelPath);
 	const barrelName = basename(barrelPath);
-	let entries;
+	let rawEntries;
 	try {
-		entries = readdirSync(dir, { withFileTypes: true })
-			.map((e) => ({ name: e.name, isDirectory: e.isDirectory() }))
-			.flatMap((entry) => {
+		const dirents = await readdir(dir, { withFileTypes: true });
+		rawEntries = dirents.map((e) => ({
+			name: e.name,
+			isDirectory: e.isDirectory(),
+		}));
+	} catch {
+		// Directory unreadable (permissions, deleted, etc.) — no children discoverable
+		return [];
+	}
+	const entries = (
+		await Promise.all(
+			rawEntries.map(async (entry) => {
 				if (entry.isDirectory) {
-					// Check for child barrel in this subdirectory
-					const childBarrel = findChildBarrel(resolve(dir, entry.name));
+					const childBarrel = await findChildBarrel(resolve(dir, entry.name));
 					return childBarrel ? [childBarrel] : [];
 				}
-				// Sibling file: must be .ts/.tsx, not .d.ts, not the barrel itself
 				if (isTsFile(entry.name) && entry.name !== barrelName) {
 					return [resolve(dir, entry.name)];
 				}
 				return [];
-			});
-	} catch {
-		// Directory unreadable (permissions, deleted, etc.) — no children discoverable
-		return [];
-	}
+			}),
+		)
+	).flat();
 	return entries.sort();
 }
 /**
@@ -72,16 +77,21 @@ function isTsFile(name) {
  * index.ts takes priority over index.tsx.
  * Returns the absolute path to the barrel, or null if none found.
  */
-function findChildBarrel(subdirPath) {
+async function findChildBarrel(subdirPath) {
 	const tsPath = resolve(subdirPath, "index.ts");
-	if (existsSync(tsPath)) {
+	try {
+		await access(tsPath);
 		return tsPath;
+	} catch {
+		// no index.ts
 	}
 	const tsxPath = resolve(subdirPath, "index.tsx");
-	if (existsSync(tsxPath)) {
+	try {
+		await access(tsxPath);
 		return tsxPath;
+	} catch {
+		return null;
 	}
-	return null;
 }
 /** Minimum number of .ts/.tsx files in a directory to require a barrel. */
 export const BARREL_THRESHOLD = 3;
@@ -89,7 +99,7 @@ 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) {
+export async function findMissingBarrels(filePaths, cwd) {
 	const dirCounts = new Map();
 	for (const filePath of filePaths) {
 		if (isBarrel(filePath)) continue;
@@ -97,14 +107,23 @@ export function findMissingBarrels(filePaths, cwd) {
 		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);
-		}
-	}
+	await Promise.all(
+		[...dirCounts.entries()].map(async ([dir, count]) => {
+			if (count <= BARREL_THRESHOLD) return;
+			const [tsExists, tsxExists] = await Promise.all([
+				access(join(dir, "index.ts")).then(
+					() => true,
+					() => false,
+				),
+				access(join(dir, "index.tsx")).then(
+					() => true,
+					() => false,
+				),
+			]);
+			if (!tsExists && !tsxExists) {
+				missing.push(relative(cwd, dir) || ".");
+			}
+		}),
+	);
 	return missing.sort();
 }

package/dist/cli.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
-import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { drilldown, drilldownFiles } from "./drilldown.js";
 import { JsdocError } from "./errors.js";
 import { lint, lintFiles } from "./lint.js";
+import { search, searchFiles } from "./search.js";
 import { parseSelector } from "./selector.js";
 import { RULE_EXPLANATIONS, SKILL_TEXT } from "./skill-text.js";
 import { formatTextOutput } from "./text-format.js";
@@ -28,48 +29,54 @@ Each file has four detail levels (1-indexed): @1 summary, @2 description,
 Options:
   -h, --help       Show this help text
   -v, --version    Show version number
-  -c, --check      Run validation mode
-  -l, --lint       Run lint mode (comprehensive JSDoc quality)
+  -c, --check      Validate file-level structure (has JSDoc block, @summary, description)
+  -l, --lint       Lint comprehensive JSDoc quality (file-level + function-level tags)
   -s, --skill      Print JSDoc writing guidelines
   --json           Output as JSON (default is plain text)
   --pretty         Format JSON output with 2-space indent (use with --json)
   --limit N        Max results shown (default 500)
   --no-gitignore   Include files ignored by .gitignore
+  --search <query>   Search files by regex pattern
   --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)
 
 Selector:
   A glob pattern or file path, optionally with @depth suffix (1-4).
+	
   Examples:
     jsdoczoom src/**/*.ts       # All .ts files at depth 1 (summary)
-    jsdoczoom src/index.ts@2    # Single file at depth 2 (description)
+    jsdoczoom src/foo.ts@2      # Single file at depth 2 (description)
     jsdoczoom **/*.ts@3         # All .ts files at depth 3 (type decls)
 
-Stdin:
-  Pipe file paths one per line:
-    find . -name "*.ts" | jsdoczoom
-    find . -name "*.ts" | jsdoczoom @2
-    find . -name "*.ts" | jsdoczoom -c
+Search (--search):
+  Searches all **/*.{ts,tsx} files (or a selector's file set) by regex.
+
+  Examples:
+    jsdoczoom --search "CacheConfig"          # find where CacheConfig is used
+    jsdoczoom --search "auth-loader"          # searches file name
+    jsdoczoom src/*.ts --search "TODO|FIXME"  # restrict to a file subset
 
 Output:
   Plain text by default. Each item has a "# path@depth" header followed by
   content. Use the header value as the next selector to drill deeper.
-  Use --json for machine-parseable JSON output.
+
+  Use --json for machine-parseable JSON output, use "next_id" to drill deeper.
 
   Type declarations (@3) include source line annotations (// LN or // LN-LM)
   so you can locate the implementation in the source file.
 
+Stdin:
+  Pipe file paths one per line (useful with -c/-l for targeted validation):
+    git diff --name-only | jsdoczoom -c    # validate changed files
+    cat filelist.txt | jsdoczoom -l        # lint a specific set of files
+
 Barrel gating (glob mode):
   A barrel's @summary and description reflect the cumulative functionality
   of its directory's children, not the barrel file itself. Barrels with a
   @summary gate sibling files at depths 1-2. At depth 3 the barrel
   disappears and its children appear at depth 1.
 
-Modes:
-  -c  Validate file-level structure (has JSDoc block, @summary, description)
-  -l  Lint comprehensive JSDoc quality (file-level + function-level tags)
-
 Exit codes:
   0  Success (all files pass)
   1  Runtime error (invalid arguments, missing files)
@@ -79,12 +86,7 @@ Workflow:
   $ jsdoczoom src/**/*.ts                # list summaries
   $ jsdoczoom src/utils@2                # drill into description
   $ jsdoczoom src/utils@3                # see type declarations
-
-Pipe examples:
-  $ jsdoczoom src/utils.ts@3 | grep "functionName"     # find symbol + source line
-  $ jsdoczoom src/utils.ts@3 | grep "// L"              # list all declarations with lines
-  $ jsdoczoom src/**/*.ts | grep "^#"                   # list all file headers
-  $ grep -rl "term" src/ --include="*.ts" | jsdoczoom   # describe matching files
+  $ jsdoczoom src/**/*.ts | grep "^#"   # list all file headers
 `;
 /**
  * Parse a flag that requires a value argument.
@@ -111,6 +113,7 @@ function parseArgs(args) {
 		cacheDirectory: undefined,
 		explainRule: undefined,
 		selectorArg: undefined,
+		searchQuery: undefined,
 	};
 	for (let i = 0; i < args.length; i++) {
 		const arg = args[i];
@@ -170,6 +173,15 @@ function parseArgs(args) {
 			i = nextIndex;
 			continue;
 		}
+		if (arg === "--search") {
+			const { value, nextIndex } = parseValueFlag(args, i);
+			if (value === undefined) {
+				throw new JsdocError("INVALID_SELECTOR", "--search requires a value");
+			}
+			parsed.searchQuery = value;
+			i = nextIndex;
+			continue;
+		}
 		// Unknown flag or positional arg
 		if (arg.startsWith("-")) {
 			throw new JsdocError("INVALID_SELECTOR", `Unrecognized option: ${arg}`);
@@ -212,10 +224,22 @@ async function processStdin(
 	limit,
 	cwd,
 	cacheConfig,
+	searchQuery,
 ) {
 	const stdinPaths = parseStdinPaths(stdin, cwd);
 	const depth =
 		selectorArg !== undefined ? extractDepthFromArg(selectorArg) : undefined;
+	if (searchQuery !== undefined) {
+		const result = await searchFiles(
+			stdinPaths,
+			searchQuery,
+			cwd,
+			limit,
+			cacheConfig,
+		);
+		writeDrilldownResult(result, json, pretty);
+		return;
+	}
 	if (lintMode) {
 		const result = await lintFiles(stdinPaths, cwd, limit, cacheConfig);
 		writeLintResult(result, pretty);
@@ -246,10 +270,23 @@ async function processSelector(
 	gitignore,
 	cwd,
 	cacheConfig,
+	searchQuery,
 ) {
 	const selector = selectorArg
 		? parseSelector(selectorArg)
 		: { type: "glob", pattern: "**/*.{ts,tsx}", depth: undefined };
+	if (searchQuery !== undefined) {
+		const result = await search(
+			{ type: selector.type, pattern: selector.pattern, depth: undefined },
+			searchQuery,
+			cwd,
+			gitignore,
+			limit,
+			cacheConfig,
+		);
+		writeDrilldownResult(result, json, pretty);
+		return;
+	}
 	if (lintMode) {
 		const result = await lint(selector, cwd, limit, gitignore, cacheConfig);
 		writeLintResult(result, pretty);
@@ -291,13 +328,13 @@ function handleHelp() {
 /**
  * Handle --version flag by reading and printing version from package.json.
  */
-function handleVersion() {
+async function handleVersion() {
 	const pkgPath = resolve(
 		dirname(fileURLToPath(import.meta.url)),
 		"..",
 		"package.json",
 	);
-	const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+	const pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
 	void process.stdout.write(`${pkg.version}\n`);
 }
 /**
@@ -323,37 +360,59 @@ function handleExplainRule(ruleName) {
 		),
 	);
 }
+/**
+ * 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) {
+	if (parsed.help) {
+		handleHelp();
+		return true;
+	}
+	if (parsed.version) {
+		await handleVersion();
+		return true;
+	}
+	if (parsed.skillMode) {
+		handleSkill();
+		return true;
+	}
+	if (parsed.explainRule !== undefined) {
+		handleExplainRule(parsed.explainRule);
+		return true;
+	}
+	return false;
+}
+/**
+ * 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) {
+	if (parsed.checkMode && parsed.lintMode) {
+		writeError(
+			new JsdocError("INVALID_SELECTOR", "Cannot use -c and -l together"),
+		);
+		return false;
+	}
+	if (
+		parsed.searchQuery !== undefined &&
+		(parsed.checkMode || parsed.lintMode)
+	) {
+		writeError(
+			new JsdocError("INVALID_SELECTOR", "Cannot use --search with -c or -l"),
+		);
+		return false;
+	}
+	return true;
+}
 /**
  * Main CLI entry point. Exported for testability.
  */
 export async function main(args, stdin) {
 	try {
 		const parsed = parseArgs(args);
-		// Handle early-exit flags
-		if (parsed.help) {
-			handleHelp();
-			return;
-		}
-		if (parsed.version) {
-			handleVersion();
-			return;
-		}
-		if (parsed.skillMode) {
-			handleSkill();
-			return;
-		}
-		if (parsed.explainRule !== undefined) {
-			handleExplainRule(parsed.explainRule);
-			return;
-		}
-		// Validate mode combinations
-		if (parsed.checkMode && parsed.lintMode) {
-			writeError(
-				new JsdocError("INVALID_SELECTOR", "Cannot use -c and -l together"),
-			);
-			return;
-		}
-		// Build cache config and process files
+		if (await handleEarlyExitFlags(parsed)) return;
+		if (!validateModeCombinations(parsed)) return;
 		const cacheConfig = {
 			enabled: !parsed.disableCache,
 			directory: parsed.cacheDirectory ?? DEFAULT_CACHE_DIR,
@@ -370,6 +429,7 @@ export async function main(args, stdin) {
 				parsed.limit,
 				cwd,
 				cacheConfig,
+				parsed.searchQuery,
 			);
 		} else {
 			await processSelector(
@@ -382,6 +442,7 @@ export async function main(args, stdin) {
 				parsed.gitignore,
 				cwd,
 				cacheConfig,
+				parsed.searchQuery,
 			);
 		}
 	} catch (error) {

package/dist/drilldown.js

@@ -32,8 +32,13 @@ function buildLevels(info, typeDeclarations, fileContent) {
 	return [
 		summary !== null ? { text: summary } : null,
 		description !== null ? { text: description } : null,
-		{ text: typeDeclarations },
-		{ text: fileContent },
+		{
+			text:
+				typeDeclarations.length > 0
+					? `\`\`\`typescript\n${typeDeclarations}\n\`\`\``
+					: typeDeclarations,
+		},
+		{ text: `\`\`\`typescript\n${fileContent}\n\`\`\`` },
 	];
 }
 /**
@@ -177,7 +182,7 @@ async function gatherBarrelInfos(barrelPaths, cwd, config) {
 				const info = await processWithCache(config, "drilldown", content, () =>
 					parseFileSummaries(barrelPath),
 				);
-				const children = getBarrelChildren(barrelPath, cwd);
+				const children = await getBarrelChildren(barrelPath, cwd);
 				return {
 					type: "info",
 					data: {
@@ -328,7 +333,7 @@ export async function drilldown(
 ) {
 	const depth = selector.depth ?? 1;
 	if (selector.type === "path") {
-		const files = discoverFiles(selector.pattern, cwd, gitignore);
+		const files = await discoverFiles(selector.pattern, cwd, gitignore);
 		if (files.length > 1) {
 			// Directory expanded to multiple files — route through glob pipeline
 			const results = await processGlobWithBarrels(files, depth, cwd, config);
@@ -358,7 +363,7 @@ export async function drilldown(
 				barrelEffectiveDepth = 3;
 			}
 			if (barrelEffectiveDepth >= 3) {
-				const children = getBarrelChildren(filePath, cwd);
+				const children = await getBarrelChildren(filePath, cwd);
 				const childDepth = barrelEffectiveDepth - 2;
 				const results = await collectSafeResults(
 					children,
@@ -385,7 +390,7 @@ export async function drilldown(
 		return { items, truncated: false };
 	}
 	// Glob selector — apply barrel gating
-	const files = discoverFiles(selector.pattern, cwd, gitignore);
+	const files = await discoverFiles(selector.pattern, cwd, gitignore);
 	if (files.length === 0) {
 		throw new JsdocError(
 			"NO_FILES_MATCHED",
@@ -422,7 +427,7 @@ export async function drilldownFiles(
 	config = DEFAULT_CACHE_CONFIG,
 ) {
 	const d = depth ?? 1;
-	const ig = loadGitignore(cwd);
+	const ig = await loadGitignore(cwd);
 	const tsFiles = filePaths.filter((f) => {
 		if (!(f.endsWith(".ts") || f.endsWith(".tsx")) || f.endsWith(".d.ts")) {
 			return false;

package/dist/file-discovery.js

@@ -1,6 +1,6 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
-import { globSync } from "glob";
+import { glob } from "glob";
 import ignore from "ignore";
 import { JsdocError } from "./errors.js";
 /**
@@ -15,13 +15,13 @@ 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.
  */
-export function loadGitignore(cwd) {
+export async function loadGitignore(cwd) {
 	const ig = ignore();
 	let dir = resolve(cwd);
 	while (true) {
 		const gitignorePath = join(dir, ".gitignore");
-		if (existsSync(gitignorePath)) {
-			const content = readFileSync(gitignorePath, "utf-8");
+		try {
+			const content = await readFile(gitignorePath, "utf-8");
 			const prefix = relative(cwd, dir);
 			const lines = content
 				.split("\n")
@@ -32,6 +32,8 @@ export function loadGitignore(cwd) {
 				// relative to `cwd`, which is where glob results are anchored.
 				ig.add(prefix ? `${prefix}/${line}` : line);
 			}
+		} catch {
+			// No .gitignore at this level, continue walking up
 		}
 		const parent = dirname(dir);
 		if (parent === dir) break;
@@ -52,25 +54,28 @@ export function loadGitignore(cwd) {
  * @returns Array of absolute file paths
  * @throws {JsdocError} FILE_NOT_FOUND when a direct path does not exist
  */
-export function discoverFiles(pattern, cwd, gitignore = true) {
+export async function discoverFiles(pattern, cwd, gitignore = true) {
 	const hasGlobChars = /[*?[\]{]/.test(pattern);
 	if (hasGlobChars) {
-		const matches = globSync(pattern, { cwd, absolute: true });
+		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 ig = loadGitignore(cwd);
+			const ig = await loadGitignore(cwd);
 			filtered = filtered.filter((abs) => !ig.ignores(relative(cwd, abs)));
 		}
 		return filtered.sort();
 	}
 	// Direct path
 	const resolved = resolve(cwd, pattern);
-	if (!existsSync(resolved)) {
+	let statResult;
+	try {
+		statResult = await stat(resolved);
+	} catch {
 		throw new JsdocError("FILE_NOT_FOUND", `File not found: ${pattern}`);
 	}
-	if (statSync(resolved).isDirectory()) {
+	if (statResult.isDirectory()) {
 		return discoverFiles(`${resolved}/**`, cwd, gitignore);
 	}
 	return [resolved];

package/dist/index.js

@@ -13,8 +13,13 @@ export { JsdocError } from "./errors.js";
 export { discoverFiles } from "./file-discovery.js";
 export { extractFileJsdoc, parseFileSummaries } from "./jsdoc-parser.js";
 export { lint, lintFiles } from "./lint.js";
+export { search, searchFiles } from "./search.js";
 export { parseSelector } from "./selector.js";
 export { formatTextOutput } from "./text-format.js";
-export { generateTypeDeclarations } from "./type-declarations.js";
+export {
+	extractSourceBlocks,
+	generateTypeDeclarations,
+	splitDeclarations,
+} from "./type-declarations.js";
 export { DEFAULT_CACHE_DIR, VALIDATION_STATUS_PRIORITY } from "./types.js";
 export { validate, validateFiles } from "./validate.js";

package/dist/jsdoc-parser.js

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import ts from "typescript";
 import { JsdocError } from "./errors.js";
 import { appendText, DESCRIPTION_TAGS } from "./types.js";
@@ -220,10 +220,10 @@ function parseJsdocContent(jsdocText) {
  * Reads the file, extracts the first file-level JSDoc block, and parses the first
  * @summary tag and free-text description.
  */
-export function parseFileSummaries(filePath) {
+export async function parseFileSummaries(filePath) {
 	let sourceText;
 	try {
-		sourceText = readFileSync(filePath, "utf-8");
+		sourceText = await readFile(filePath, "utf-8");
 	} catch {
 		throw new JsdocError("FILE_NOT_FOUND", `File not found: ${filePath}`);
 	}

package/dist/lint.js

@@ -89,7 +89,7 @@ export async function lint(
 	gitignore = true,
 	config = { enabled: true, directory: DEFAULT_CACHE_DIR },
 ) {
-	const files = discoverFiles(selector.pattern, cwd, gitignore);
+	const files = await discoverFiles(selector.pattern, cwd, gitignore);
 	if (files.length === 0 && selector.type === "glob") {
 		throw new JsdocError(
 			"NO_FILES_MATCHED",
@@ -101,7 +101,7 @@ export async function lint(
 	const fileResults = await Promise.all(
 		tsFiles.map((f) => lintSingleFile(eslint, f, cwd, config)),
 	);
-	const missingBarrels = findMissingBarrels(tsFiles, cwd);
+	const missingBarrels = await findMissingBarrels(tsFiles, cwd);
 	return buildLintResult(fileResults, tsFiles.length, limit, missingBarrels);
 }
 /**
@@ -129,6 +129,6 @@ export async function lintFiles(
 	const fileResults = await Promise.all(
 		tsFiles.map((f) => lintSingleFile(eslint, f, cwd, config)),
 	);
-	const missingBarrels = findMissingBarrels(tsFiles, cwd);
+	const missingBarrels = await findMissingBarrels(tsFiles, cwd);
 	return buildLintResult(fileResults, tsFiles.length, limit, missingBarrels);
 }

package/dist/search.js

@@ -0,0 +1,226 @@
+import { readFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { processWithCache } from "./cache.js";
+import { JsdocError } from "./errors.js";
+import { discoverFiles, loadGitignore } from "./file-discovery.js";
+import { parseFileSummaries } from "./jsdoc-parser.js";
+import {
+	extractAllSourceBlocks,
+	generateTypeDeclarations,
+	splitDeclarations,
+} from "./type-declarations.js";
+import { DEFAULT_CACHE_DIR } from "./types.js";
+
+/**
+ * Searches TypeScript files for a regex query, returning results at the
+ * shallowest matching depth level. Processes each file through a 4-level
+ * matching hierarchy: filename/path, summary, description/declarations,
+ * and full source content.
+ *
+ * @summary Search TypeScript documentation and source by regex query
+ */
+/** Default cache configuration used when no config is provided. */
+const DEFAULT_CACHE_CONFIG = {
+	enabled: true,
+	directory: DEFAULT_CACHE_DIR,
+};
+/**
+ * Compute the display id path for a file.
+ * Uses simple relative path — no barrel-to-directory conversion.
+ */
+function displayPath(filePath, cwd) {
+	return relative(cwd, filePath);
+}
+/**
+ * Extract the sort key from an output entry (either next_id or id).
+ */
+function sortKey(entry) {
+	if ("next_id" in entry) return entry.next_id;
+	return entry.id;
+}
+/**
+ * Process a single file through the 4-level search hierarchy.
+ * Returns an OutputEntry if the file matches the query at any level,
+ * or null if there is no match. PARSE_ERROR exceptions are rethrown
+ * for the caller to handle silently.
+ */
+async function processFileSafe(filePath, regex, cwd, config) {
+	const content = await readFile(filePath, "utf-8");
+	const idPath = displayPath(filePath, cwd);
+	// Parse summaries once for levels 1-3a
+	const info = await processWithCache(config, "drilldown", content, () =>
+		parseFileSummaries(filePath),
+	);
+	// Level 1: filename/path match — fall back through levels like drilldown
+	if (regex.test(idPath)) {
+		if (info.summary !== null) {
+			return { next_id: `${idPath}@2`, text: info.summary };
+		}
+		if (info.description !== null) {
+			return { next_id: `${idPath}@3`, text: info.description };
+		}
+		const dts = await processWithCache(
+			config,
+			"drilldown",
+			`${content}\0typedecl`,
+			() => generateTypeDeclarations(filePath),
+		);
+		if (dts.length > 0) {
+			const chunks = splitDeclarations(dts);
+			return {
+				next_id: `${idPath}@4`,
+				text: chunks.map((c) => `\`\`\`typescript\n${c}\n\`\`\``).join("\n\n"),
+			};
+		}
+		return { id: `${idPath}@4`, text: `\`\`\`typescript\n${content}\n\`\`\`` };
+	}
+	// Level 2: summary match
+	if (info.summary !== null && regex.test(info.summary)) {
+		return { next_id: `${idPath}@2`, text: info.summary };
+	}
+	// Level 3a: description match
+	if (info.description !== null && regex.test(info.description)) {
+		return { next_id: `${idPath}@3`, text: info.description };
+	}
+	// Level 3b: type declaration match
+	const dts = await processWithCache(
+		config,
+		"drilldown",
+		`${content}\0typedecl`,
+		() => generateTypeDeclarations(filePath),
+	);
+	if (dts.length > 0) {
+		const chunks = splitDeclarations(dts);
+		const matching = chunks.filter((c) => regex.test(c));
+		if (matching.length > 0) {
+			return {
+				next_id: `${idPath}@3`,
+				text: matching
+					.map((c) => `\`\`\`typescript\n${c}\n\`\`\``)
+					.join("\n\n"),
+			};
+		}
+	}
+	// Level 4: source match — cache block extraction, filter by regex
+	const allBlocks = await processWithCache(
+		config,
+		"drilldown",
+		`${content}\0sourceblocks`,
+		() => extractAllSourceBlocks(filePath, content),
+	);
+	const matchingBlocks = allBlocks.filter((b) => regex.test(b.blockText));
+	if (matchingBlocks.length > 0) {
+		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)) {
+		return { id: `${idPath}@4`, text: `\`\`\`typescript\n${content}\n\`\`\`` };
+	}
+	return null; // no match
+}
+/**
+ * Compile a query string into a case-insensitive regex.
+ * Throws INVALID_SELECTOR if the query is not a valid regex pattern.
+ */
+function compileRegex(query) {
+	try {
+		return new RegExp(query, "i");
+	} catch (_error) {
+		throw new JsdocError("INVALID_SELECTOR", `Invalid regex: ${query}`);
+	}
+}
+/**
+ * Apply limit/truncation to sorted results.
+ */
+function applyLimit(sorted, limit) {
+	const count = sorted.length;
+	const isTruncated = count > limit;
+	return {
+		items: sorted.slice(0, limit),
+		truncated: isTruncated,
+		...(isTruncated ? { total: count } : {}),
+	};
+}
+/**
+ * Process a list of file paths through the search hierarchy and return sorted results.
+ * 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 matched = results.filter((r) => r !== null);
+	const sorted = matched.sort((a, b) => sortKey(a).localeCompare(sortKey(b)));
+	return applyLimit(sorted, limit);
+}
+/**
+ * Search TypeScript files matching a selector for a regex query.
+ *
+ * Discovers files from the selector pattern, processes each through
+ * the 4-level matching hierarchy, and returns results at the shallowest
+ * matching depth. Files with parse errors are silently skipped.
+ *
+ * @param selector - Parsed selector with type and pattern
+ * @param query - Regex query string (case-insensitive)
+ * @param cwd - Working directory for file resolution
+ * @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
+ */
+export async function search(
+	selector,
+	query,
+	cwd,
+	gitignore = true,
+	limit = 100,
+	config = DEFAULT_CACHE_CONFIG,
+) {
+	const regex = compileRegex(query);
+	const files = await discoverFiles(selector.pattern, cwd, gitignore);
+	return searchFileList(files, regex, cwd, limit, config);
+}
+/**
+ * Search an explicit list of file paths for a regex query.
+ *
+ * Used for stdin input. Filters to .ts/.tsx files, excludes .d.ts.
+ * Processes each file through the 4-level matching hierarchy.
+ *
+ * @param filePaths - Array of absolute file paths
+ * @param query - Regex query string (case-insensitive)
+ * @param cwd - Working directory for relative path output
+ * @param limit - Maximum number of results to return (default 100)
+ * @param config - Cache configuration
+ * @throws {JsdocError} INVALID_SELECTOR for invalid regex
+ */
+export async function searchFiles(
+	filePaths,
+	query,
+	cwd,
+	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);
+	});
+	return searchFileList(tsFiles, regex, cwd, limit, config);
+}

package/dist/text-format.js

@@ -19,12 +19,12 @@ function formatEntry(entry) {
 		if (children) {
 			lines.push(`## children: ${children.join(", ")}`);
 		}
-		if (text) lines.push(text);
+		if (text) lines.push("", text);
 		return lines.join("\n");
 	}
 	// Terminal item
 	if (!text) return `# ${entry.id}`;
-	return `# ${entry.id}\n${text}`;
+	return `# ${entry.id}\n\n${text}`;
 }
 /**
  * Format a DrilldownResult as plain text for CLI output.
@@ -32,7 +32,7 @@ function formatEntry(entry) {
  */
 export function formatTextOutput(result) {
 	const blocks = result.items.map(formatEntry);
-	let output = blocks.join("\n\n");
+	let output = blocks.join("\n\n\n");
 	if (result.truncated && result.total !== undefined) {
 		output += `\n\n# truncated (showing ${result.items.length} of ${result.total})`;
 	} else if (result.truncated) {

package/dist/type-declarations.js

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import ts from "typescript";
 import { JsdocError } from "./errors.js";
@@ -153,12 +153,44 @@ export function resetCache() {
 	compilerOptionsCache.clear();
 	serviceCache.clear();
 }
+/**
+ * Extract exported symbol names from a top-level statement.
+ * Returns an array of names (variable statements may have multiple).
+ */
+function exportedNamesOf(statement) {
+	if (ts.isTypeAliasDeclaration(statement)) return [statement.name.text];
+	if (ts.isInterfaceDeclaration(statement)) return [statement.name.text];
+	if (ts.isFunctionDeclaration(statement) && statement.name) {
+		return [statement.name.text];
+	}
+	if (ts.isClassDeclaration(statement) && statement.name) {
+		return [statement.name.text];
+	}
+	if (ts.isEnumDeclaration(statement)) return [statement.name.text];
+	if (ts.isVariableStatement(statement)) {
+		return statement.declarationList.declarations
+			.filter((d) => ts.isIdentifier(d.name))
+			.map((d) => d.name.text);
+	}
+	return [];
+}
+/**
+ * Return true if the statement has an `export` modifier.
+ */
+function isExportedStatement(statement) {
+	if (!ts.canHaveModifiers(statement)) return false;
+	return (
+		ts
+			.getModifiers(statement)
+			?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false
+	);
+}
 /**
  * Build a map of exported symbol names to their source line ranges.
  * Walks top-level statements looking for export modifiers.
  */
-function buildSourceLineMap(filePath) {
-	const content = readFileSync(filePath, "utf-8");
+async function buildSourceLineMap(filePath) {
+	const content = await readFile(filePath, "utf-8");
 	const sourceFile = ts.createSourceFile(
 		filePath,
 		content,
@@ -167,36 +199,14 @@ function buildSourceLineMap(filePath) {
 	);
 	const map = new Map();
 	for (const statement of sourceFile.statements) {
-		// Only process exported declarations
-		const modifiers = ts.canHaveModifiers(statement)
-			? ts.getModifiers(statement)
-			: undefined;
-		const isExported = modifiers?.some(
-			(m) => m.kind === ts.SyntaxKind.ExportKeyword,
-		);
-		if (!isExported) continue;
+		if (!isExportedStatement(statement)) continue;
 		const start =
 			sourceFile.getLineAndCharacterOfPosition(statement.getStart(sourceFile))
 				.line + 1;
 		const end =
 			sourceFile.getLineAndCharacterOfPosition(statement.getEnd()).line + 1;
-		const addName = (name) => map.set(name, { start, end });
-		if (ts.isTypeAliasDeclaration(statement)) {
-			addName(statement.name.text);
-		} else if (ts.isInterfaceDeclaration(statement)) {
-			addName(statement.name.text);
-		} else if (ts.isFunctionDeclaration(statement) && statement.name) {
-			addName(statement.name.text);
-		} else if (ts.isClassDeclaration(statement) && statement.name) {
-			addName(statement.name.text);
-		} else if (ts.isEnumDeclaration(statement)) {
-			addName(statement.name.text);
-		} else if (ts.isVariableStatement(statement)) {
-			for (const decl of statement.declarationList.declarations) {
-				if (ts.isIdentifier(decl.name)) {
-					addName(decl.name.text);
-				}
-			}
+		for (const name of exportedNamesOf(statement)) {
+			map.set(name, { start, end });
 		}
 	}
 	return map;
@@ -234,8 +244,8 @@ function findChunkStart(lines, declLine) {
  * Inserts GitHub-style `// LN` or `// LN-LM` on a separate line before each
  * declaration chunk, with a blank line above for visual separation.
  */
-function annotateWithSourceLines(dtsText, filePath) {
-	const lineMap = buildSourceLineMap(filePath);
+async function annotateWithSourceLines(dtsText, filePath) {
+	const lineMap = await buildSourceLineMap(filePath);
 	if (lineMap.size === 0) return dtsText;
 	const lines = dtsText.split("\n");
 	// First pass: map chunk start lines to their annotations
@@ -263,6 +273,127 @@ function annotateWithSourceLines(dtsText, filePath) {
 	}
 	return result.join("\n");
 }
+/**
+ * Splits annotated .d.ts text into individual declaration chunks.
+ *
+ * Splits on blank-line boundaries that precede a line annotation (`// L`)
+ * or a declaration keyword (`export`, `declare`). Each chunk is a complete
+ * declaration including its preceding JSDoc comment and line annotation.
+ * Trailing whitespace is trimmed from each chunk. Empty chunks are filtered out.
+ *
+ * @param dtsText - The annotated .d.ts text to split
+ * @returns Array of declaration chunks
+ */
+export function splitDeclarations(dtsText) {
+	if (dtsText === "") return [];
+	const lines = dtsText.split("\n");
+	const chunks = [];
+	let start = 0;
+	for (let i = 1; i < lines.length; i++) {
+		// A split point is a blank line followed by a line annotation or declaration keyword
+		if (lines[i - 1].trim() === "") {
+			const nextLine = lines[i].trimStart();
+			const isAnnotation = nextLine.startsWith("// L");
+			const isDeclaration =
+				nextLine.startsWith("export") || nextLine.startsWith("declare");
+			if (isAnnotation || isDeclaration) {
+				const chunk = lines
+					.slice(start, i - 1)
+					.join("\n")
+					.trimEnd();
+				if (chunk !== "") chunks.push(chunk);
+				start = i;
+			}
+		}
+	}
+	// Push final chunk
+	const last = lines.slice(start).join("\n").trimEnd();
+	if (last !== "") chunks.push(last);
+	return chunks;
+}
+/**
+ * Find the 0-based line index where a leading JSDoc block starts above a statement.
+ * Skips blank lines above the statement, then looks for a `/** ... * /` block.
+ * Returns `statementLine` itself when no leading JSDoc is found.
+ */
+function findJsdocStart(lines, statementLine) {
+	let line = statementLine - 1;
+	// Skip blank lines immediately before the statement
+	while (line >= 0 && lines[line].trim() === "") line--;
+	if (line < 0) return statementLine;
+	const trimmed = lines[line].trimEnd();
+	if (trimmed === "*/" || trimmed.endsWith("*/")) {
+		// Multi-line JSDoc: walk back to find opening /**
+		for (let j = line; j >= 0; j--) {
+			if (lines[j].trimStart().startsWith("/**")) return j;
+		}
+	} else if (trimmed.trimStart().startsWith("/**")) {
+		// Single-line JSDoc: /** comment */
+		return line;
+	}
+	return statementLine;
+}
+/**
+ * Extracts all top-level source blocks from a TypeScript file.
+ * Walks all top-level statements (not just exported), includes leading
+ * JSDoc comments, and annotates each block with source line references.
+ * Import declarations are excluded.
+ *
+ * Returns an empty array for empty files.
+ *
+ * @param filePath - Absolute path to the TypeScript source file
+ * @param content - Pre-read file content (avoids redundant disk read)
+ */
+export function extractAllSourceBlocks(filePath, content) {
+	if (content.trim() === "") return [];
+	const lines = content.split("\n");
+	const sourceFile = ts.createSourceFile(
+		filePath,
+		content,
+		ts.ScriptTarget.Latest,
+		true,
+	);
+	const blocks = [];
+	const seen = new Set();
+	for (const statement of sourceFile.statements) {
+		// Skip import declarations — callers fall back to full file for import matches
+		if (ts.isImportDeclaration(statement)) continue;
+		const endLine =
+			sourceFile.getLineAndCharacterOfPosition(statement.getEnd()).line + 1;
+		const stmtStartLine = sourceFile.getLineAndCharacterOfPosition(
+			statement.getStart(sourceFile),
+		).line; // 0-based
+		const jsdocStartLine = findJsdocStart(lines, stmtStartLine); // 0-based
+		// Skip if we've already included this block (deduplication by start position)
+		if (seen.has(jsdocStartLine)) continue;
+		seen.add(jsdocStartLine);
+		// Extract the source text for this block (lines are 0-based, endLine is 1-based)
+		const blockText = lines.slice(jsdocStartLine, endLine).join("\n");
+		const startLine1based = jsdocStartLine + 1; // 1-based
+		const annotation = formatLineRef({ start: startLine1based, end: endLine });
+		blocks.push({ annotation, blockText });
+	}
+	return blocks;
+}
+/**
+ * Extracts top-level source blocks from a file that match a regex.
+ *
+ * Walks all top-level statements (not just exported ones), includes leading
+ * JSDoc comments, and tests the regex against each block's source text.
+ * Matching blocks are annotated with `// LN` or `// LN-LM` and joined with
+ * blank line separators.
+ *
+ * @param filePath - Absolute path to the TypeScript source file
+ * @param content - Pre-read file content (avoids redundant disk read)
+ * @param regex - Regular expression to test against each block's source text
+ * @returns Annotated matching blocks joined with blank lines, or null if no match
+ */
+export function extractSourceBlocks(filePath, content, regex) {
+	const allBlocks = extractAllSourceBlocks(filePath, content);
+	const matching = allBlocks.filter((b) => regex.test(b.blockText));
+	if (matching.length === 0) return null;
+	return matching.map((b) => `${b.annotation}\n${b.blockText}`).join("\n\n");
+}
 /**
  * Generates TypeScript declaration output from a source file.
  *
@@ -282,10 +413,10 @@ function annotateWithSourceLines(dtsText, filePath) {
  * @returns The declaration output as a string
  * @throws {JsdocError} If the file cannot be read or parsed
  */
-export function generateTypeDeclarations(filePath) {
+export async function generateTypeDeclarations(filePath) {
 	// Verify the file exists and throw FILE_NOT_FOUND for any read errors
 	try {
-		readFileSync(filePath, "utf-8");
+		await readFile(filePath, "utf-8");
 	} catch (_error) {
 		throw new JsdocError("FILE_NOT_FOUND", `Failed to read file: ${filePath}`);
 	}
@@ -319,7 +450,7 @@ export function generateTypeDeclarations(filePath) {
 		cleaned = "";
 	}
 	if (cleaned.length > 0) {
-		cleaned = annotateWithSourceLines(cleaned, filePath);
+		cleaned = await annotateWithSourceLines(cleaned, filePath);
 	}
 	return cleaned;
 }

package/dist/validate.js

@@ -97,7 +97,7 @@ export async function validate(
 	gitignore = true,
 	config = { enabled: true, directory: DEFAULT_CACHE_DIR },
 ) {
-	const files = discoverFiles(selector.pattern, cwd, gitignore);
+	const files = await discoverFiles(selector.pattern, cwd, gitignore);
 	if (files.length === 0) {
 		throw new JsdocError(
 			"NO_FILES_MATCHED",
@@ -108,7 +108,7 @@ export async function validate(
 	const statuses = await Promise.all(
 		files.map((f) => classifyFile(eslint, f, cwd, config)),
 	);
-	const missingBarrels = findMissingBarrels(files, cwd);
+	const missingBarrels = await findMissingBarrels(files, cwd);
 	return buildGroupedResult(statuses, missingBarrels, limit);
 }
 /**
@@ -135,6 +135,6 @@ export async function validateFiles(
 	const statuses = await Promise.all(
 		tsFiles.map((f) => classifyFile(eslint, f, cwd, config)),
 	);
-	const missingBarrels = findMissingBarrels(tsFiles, cwd);
+	const missingBarrels = await findMissingBarrels(tsFiles, cwd);
 	return buildGroupedResult(statuses, missingBarrels, limit);
 }

package/package.json

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

package/types/barrel.d.ts

@@ -32,7 +32,7 @@ export declare function isBarrel(filePath: string): boolean;
 export declare function getBarrelChildren(
 	barrelPath: string,
 	_cwd: string,
-): string[];
+): Promise<string[]>;
 /** Minimum number of .ts/.tsx files in a directory to require a barrel. */
 export declare const BARREL_THRESHOLD = 3;
 /**
@@ -42,4 +42,4 @@ export declare const BARREL_THRESHOLD = 3;
 export declare function findMissingBarrels(
 	filePaths: string[],
 	cwd: string,
-): string[];
+): Promise<string[]>;

package/types/file-discovery.d.ts

@@ -11,7 +11,7 @@ import { type Ignore } from "ignore";
  * Walk from `cwd` up to the filesystem root, collecting .gitignore entries.
  * Returns an Ignore instance loaded with all discovered rules.
  */
-export declare function loadGitignore(cwd: string): Ignore;
+export declare function loadGitignore(cwd: string): Promise<Ignore>;
 /**
  * Resolve a selector pattern to a list of .ts/.tsx file paths.
  *
@@ -29,4 +29,4 @@ export declare function discoverFiles(
 	pattern: string,
 	cwd: string,
 	gitignore?: boolean,
-): string[];
+): Promise<string[]>;

package/types/index.d.ts

@@ -13,9 +13,14 @@ export { JsdocError } from "./errors.js";
 export { discoverFiles } from "./file-discovery.js";
 export { extractFileJsdoc, parseFileSummaries } from "./jsdoc-parser.js";
 export { lint, lintFiles } from "./lint.js";
+export { search, searchFiles } from "./search.js";
 export { parseSelector } from "./selector.js";
 export { formatTextOutput } from "./text-format.js";
-export { generateTypeDeclarations } from "./type-declarations.js";
+export {
+	extractSourceBlocks,
+	generateTypeDeclarations,
+	splitDeclarations,
+} from "./type-declarations.js";
 export {
 	type CacheConfig,
 	type CacheOperationMode,

package/types/jsdoc-parser.d.ts

@@ -24,4 +24,6 @@ export declare function extractFileJsdoc(
  * Reads the file, extracts the first file-level JSDoc block, and parses the first
  * @summary tag and free-text description.
  */
-export declare function parseFileSummaries(filePath: string): ParsedFileInfo;
+export declare function parseFileSummaries(
+	filePath: string,
+): Promise<ParsedFileInfo>;

package/types/search.d.ts

@@ -0,0 +1,44 @@
+import type { CacheConfig, DrilldownResult, SelectorInfo } from "./types.js";
+/**
+ * Search TypeScript files matching a selector for a regex query.
+ *
+ * Discovers files from the selector pattern, processes each through
+ * the 4-level matching hierarchy, and returns results at the shallowest
+ * matching depth. Files with parse errors are silently skipped.
+ *
+ * @param selector - Parsed selector with type and pattern
+ * @param query - Regex query string (case-insensitive)
+ * @param cwd - Working directory for file resolution
+ * @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
+ */
+export declare function search(
+	selector: SelectorInfo,
+	query: string,
+	cwd: string,
+	gitignore?: boolean,
+	limit?: number,
+	config?: CacheConfig,
+): Promise<DrilldownResult>;
+/**
+ * Search an explicit list of file paths for a regex query.
+ *
+ * Used for stdin input. Filters to .ts/.tsx files, excludes .d.ts.
+ * Processes each file through the 4-level matching hierarchy.
+ *
+ * @param filePaths - Array of absolute file paths
+ * @param query - Regex query string (case-insensitive)
+ * @param cwd - Working directory for relative path output
+ * @param limit - Maximum number of results to return (default 100)
+ * @param config - Cache configuration
+ * @throws {JsdocError} INVALID_SELECTOR for invalid regex
+ */
+export declare function searchFiles(
+	filePaths: string[],
+	query: string,
+	cwd: string,
+	limit?: number,
+	config?: CacheConfig,
+): Promise<DrilldownResult>;

package/types/type-declarations.d.ts

@@ -35,6 +35,56 @@ export declare function getLanguageService(
  * @internal
  */
 export declare function resetCache(): void;
+/**
+ * Splits annotated .d.ts text into individual declaration chunks.
+ *
+ * Splits on blank-line boundaries that precede a line annotation (`// L`)
+ * or a declaration keyword (`export`, `declare`). Each chunk is a complete
+ * declaration including its preceding JSDoc comment and line annotation.
+ * Trailing whitespace is trimmed from each chunk. Empty chunks are filtered out.
+ *
+ * @param dtsText - The annotated .d.ts text to split
+ * @returns Array of declaration chunks
+ */
+export declare function splitDeclarations(dtsText: string): string[];
+/** A single top-level source block with its line annotation. */
+export interface SourceBlock {
+	annotation: string;
+	blockText: string;
+}
+/**
+ * Extracts all top-level source blocks from a TypeScript file.
+ * Walks all top-level statements (not just exported), includes leading
+ * JSDoc comments, and annotates each block with source line references.
+ * Import declarations are excluded.
+ *
+ * Returns an empty array for empty files.
+ *
+ * @param filePath - Absolute path to the TypeScript source file
+ * @param content - Pre-read file content (avoids redundant disk read)
+ */
+export declare function extractAllSourceBlocks(
+	filePath: string,
+	content: string,
+): SourceBlock[];
+/**
+ * Extracts top-level source blocks from a file that match a regex.
+ *
+ * Walks all top-level statements (not just exported ones), includes leading
+ * JSDoc comments, and tests the regex against each block's source text.
+ * Matching blocks are annotated with `// LN` or `// LN-LM` and joined with
+ * blank line separators.
+ *
+ * @param filePath - Absolute path to the TypeScript source file
+ * @param content - Pre-read file content (avoids redundant disk read)
+ * @param regex - Regular expression to test against each block's source text
+ * @returns Annotated matching blocks joined with blank lines, or null if no match
+ */
+export declare function extractSourceBlocks(
+	filePath: string,
+	content: string,
+	regex: RegExp,
+): string | null;
 /**
  * Generates TypeScript declaration output from a source file.
  *
@@ -54,4 +104,6 @@ export declare function resetCache(): void;
  * @returns The declaration output as a string
  * @throws {JsdocError} If the file cannot be read or parsed
  */
-export declare function generateTypeDeclarations(filePath: string): string;
+export declare function generateTypeDeclarations(
+	filePath: string,
+): Promise<string>;