jsdoczoom 0.4.21 → 1.2.0

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/skill-text.d.ts

@@ -11,6 +11,6 @@ import type { ValidationStatus } from "./types.js";
 /** Markdown guidance text for each validation status category */
 export declare const GUIDANCE: Record<ValidationStatus, string>;
 export declare const SKILL_TEXT =
-	'# World-Class JSDoc Guidelines for TypeScript\n\nThese guidelines describe the *properties* of excellent inline JSDoc in TypeScript repositories. They are a target to aim for, not a checklist. Use judgment; clarity beats volume.\n\n## Core principle\n\nTypeScript projects already have explicit types. JSDoc should add **intent, behavior, and constraints** rather than repeat what the type system already expresses.\n\n## Would have (high-signal properties)\n\n- **Intent and constraints**: Explains the non-obvious decision, constraint, or tradeoff (e.g., why a particular algorithm is used, why a heuristic exists, or what the runtime environment forbids).\n- **Behavioral contract**: Clearly states what inputs are accepted, what outputs represent, and how boundary cases are treated.\n- **Domain vocabulary**: Uses project-specific terms consistently so readers can navigate the codebase by vocabulary.\n- **Examples that disambiguate**: Includes `@example` blocks when behavior is otherwise ambiguous (e.g., parsing rules, path formats, or object schemas). Examples are short and realistic.\n- **Runtime effects**: Calls out side effects, temporal dependency (polling vs. event-driven), filesystem reads/writes, or external service behavior when those matter.\n- **Edge-case prompts**: Captures "what happens if..." questions that a reviewer would ask, especially where external APIs or platform behavior has caveats.\n- **Consistency with existing style**: Matches the formatting conventions already established in the codebase (multi-line descriptions, bullet lists where helpful).\n- **Future-proof hints**: Notes invariants and assumptions that must hold if the code evolves.\n- **LLM-friendly structure**: Uses short, self-contained paragraphs written in clear International Business English. Avoids prescriptive headers (e.g., "Why:", "Constraint:") in favor of natural prose that states context, purpose, and caveats directly.\n\n## Would not have (low-signal or risky properties)\n\n- **Type restatements**: Repeating TypeScript types in prose (e.g., "@param options - The options object" when the type is already `Options`). Keep `@param`, `@returns`, and `@throws` tags\u2014just make the descriptions add meaning beyond the type.\n- **Obvious narration**: Comments that paraphrase the code or parameter name without additional insight.\n- **Incorrect authority**: Claims that are not enforced by code (e.g., "never throws" when it can, or "always" without guardrails).\n- **Redundant verbosity**: Long descriptions that could be expressed more directly, or boilerplate that hides the key idea.\n- **Unbounded examples**: Large blocks or full payloads when a minimal example would do.\n- **Out-of-date operational details**: References to tooling, CLI flags, or config knobs that are not enforced or checked.\n- **Implementation leakage**: Unnecessary internal steps or private details that are likely to change and add churn to docs.\n- **Non-ASCII decoration**: Fancy symbols or emojis that do not already exist in the file; keep ASCII unless needed.\n\n## Tag usage cues (not rules)\n\n### IntelliSense tags (always include)\n\nThese tags power IDE hover tooltips, autocomplete, and signature help. Always include them for public APIs, constructors, and functions:\n\n- **`@param`**: Include for every parameter. Describe the parameter\'s purpose, valid ranges, or constraints\u2014not just its type.\n- **`@returns`**: Include when the function returns a value. Describe what the return value represents, especially for edge cases.\n- **`@throws`**: Include when the function can throw. Describe the conditions that cause the error.\n- **`@template`**: Include for generic functions and types. Describe what the type parameter represents.\n\n### Cross-reference tags (use to aid navigation)\n\n- **`@see`**: Link to related functions, types, or external documentation.\n- **`{@link Symbol}`**: Inline reference within descriptions. Creates a clickable link to another symbol.\n\n### Structural tags (use when appropriate)\n\n- Use `@module` at the top of files that define a cohesive domain concept.\n- Use `@example` when parsing or formatting behavior could be misread, or when a type is complex.\n- Use `@deprecated` on exports that are retained for compatibility.\n- Prefer short description + bullets for concepts with multiple facets.\n\n---\n\n## Writing file-level @summary and description\n\nEvery TypeScript file should have a file-level JSDoc block before the first code statement. This block is what jsdoczoom reads for orientation and validation.\n\n### Structure\n\n```typescript\n/**\n * Description paragraph goes here. It explains the file\'s responsibilities,\n * invariants, trade-offs, and failure modes. This is the deepest level of\n * native documentation \u2014 enough for someone to understand why this file\n * exists and how it fits into the broader system.\n *\n * @summary Concise one-line overview for quick orientation when scanning a codebase.\n */\n```\n\n### The @summary tag\n\nThe `@summary` tag provides a one-line overview \u2014 the first thing someone sees when scanning with jsdoczoom at the shallowest depth.\n\n**Good summaries:**\n- State what the file *does* or *is responsible for*, not what it contains\n- Are self-contained \u2014 understandable without reading other files\n- Use domain vocabulary consistently with the rest of the codebase\n- Fit on a single line (joined if multi-line in source)\n\n**Examples:**\n- `@summary Barrel tree model for hierarchical gating in glob mode`\n- `@summary Resolve selector patterns to absolute file paths with gitignore filtering`\n- `@summary CLI entry point \u2014 argument parsing, mode dispatch, and exit code handling`\n\n**Avoid:**\n- `@summary This file contains utility functions` \u2014 says what it *contains*, not what it *does*\n- `@summary Helpers` \u2014 too vague, no domain context\n- `@summary The main module` \u2014 no information about purpose or scope\n\n### The description paragraph\n\nThe description is prose that appears before any `@` tags. It provides the deeper context that the summary cannot \u2014 responsibilities, invariants, trade-offs, and failure modes.\n\n**Good descriptions:**\n- Explain *why* this file exists and what problem it solves\n- State invariants and assumptions that callers or maintainers must know\n- Note trade-offs and design decisions (e.g., "uses priority-order fill to keep the limit algorithm simple")\n- Mention failure modes and edge cases relevant to the file as a whole\n- Are 1-4 sentences, not an essay\n\n**Examples:**\n```typescript\n/**\n * Walks .gitignore files from cwd to filesystem root, building an ignore\n * filter that glob results pass through. Direct-path lookups bypass the\n * filter since the user explicitly named the file. The ignore instance is\n * created per call \u2014 no caching \u2014 because cwd may differ between invocations.\n *\n * @summary Resolve selector patterns to absolute file paths with gitignore filtering\n */\n```\n\n```typescript\n/**\n * Each file is classified into exactly one status category: the first\n * failing check wins (syntax_error > missing_jsdoc > missing_summary >\n * missing_description). Valid files are omitted from output entirely.\n * The limit parameter caps the total number of invalid paths shown,\n * filled in priority order across groups.\n *\n * @summary Validate file-level JSDoc and group results by status category\n */\n```\n\n**Avoid:**\n- Restating the summary in longer words\n- Listing every function in the file\n- Implementation details that change frequently (line numbers, internal variable names)\n\n### Barrel files (index.ts / index.tsx)\n\nBarrel files represent their directory. Their `@summary` and description should describe the **cumulative functionality of the directory\'s children**, not the barrel file itself.\n\n- **`@summary`**: The collective purpose of the files in this directory\n- **Description**: The combined capabilities and responsibilities of child modules \u2014 what they do together, not their filenames or the re-export mechanism\n\n```typescript\n// packages/auth/src/index.ts\n/**\n * Provides session lifecycle management, token validation and refresh,\n * and middleware for route-level access control. OAuth2 provider\n * integration is handled here; cryptographic primitives are delegated\n * to the crypto package.\n *\n * @summary Authentication and authorization module\n */\n```\n\n**Avoid:**\n- `@summary Re-exports all functions and types` \u2014 describes the barrel mechanism, not what the children do\n- `@summary Exports for the auth module` \u2014 describes the mechanism, not the purpose\n- `@summary Public API barrel` \u2014 names the pattern rather than describing functionality\n- Listing child filenames or saying "This is the entry point"\n\n### Placement\n\nThe file-level JSDoc block must appear **before the first code statement** (imports are fine above it, but the block must precede any `export`, `const`, `function`, `class`, etc.). A common pattern is to place it immediately after imports:\n\n```typescript\nimport { resolve } from "node:path";\nimport { globSync } from "glob";\n\n/**\n * Description paragraph here.\n *\n * @summary One-line overview here\n */\n\nexport function discoverFiles(...) { ... }\n```\n\n### Common lint rules and examples\n\nThese rules are enforced in lint mode (`-l`). Understanding what passes and fails reduces trial-and-rerun cycles.\n\n#### `jsdoc/informative-docs` \u2014 descriptions must add meaning\n\nThis rule rejects descriptions that merely restate the parameter name, type, or containing symbol name. Descriptions must provide behavioral context.\n\n**Fails:**\n- `@param id - The id`\n- `@param options - The options object`\n- `@returns The result`\n- `@param name - The name string`\n\n**Passes:**\n- `@param id - Unique identifier used for cache lookup and deduplication`\n- `@param options - Controls retry behavior, timeout, and error handling strategy`\n- `@returns Parsed configuration with defaults applied for missing fields`\n- `@param name - Display name shown in the navigation sidebar`\n\n**Rule of thumb:** If removing the parameter name from the description leaves no useful information, the description is not informative enough.\n\n#### `jsdoc/check-tag-names` \u2014 allowed tags only\n\nThe lint configuration rejects non-standard JSDoc tags. Common tags to **avoid in JSDoc blocks**:\n- `@remarks` \u2014 move content to the description paragraph (prose before tags)\n- `@packageDocumentation` \u2014 use `@module` instead\n- `@concept`, `@constraint` \u2014 move content to the description paragraph\n\nFramework directives that look like tags (e.g., `@vitest-environment`) should use plain comments instead:\n```typescript\n// @vitest-environment node   \u2190 correct (plain comment)\n/** @vitest-environment node */  \u2190 incorrect (treated as JSDoc tag)\n```\n\n#### `jsdoc/require-throws` \u2014 document throw conditions\n\nInclude `@throws` for any function that can throw, including catch-and-rethrow patterns:\n```typescript\n/**\n * @param path - File path to read\n * @returns Parsed configuration object\n * @throws {ConfigError} When the file is missing or contains invalid YAML\n */\n```\n\nIf a function catches errors and rethrows them (wrapped or unwrapped), it still needs `@throws`.\n\n### Nested object parameters\n\nWhen a function accepts an inline object parameter, document each property with a nested `@param` tag:\n\n```typescript\n/**\n * Create a new user account.\n *\n * @param data - Account creation payload\n * @param data.email - Email address used for login and notifications\n * @param data.displayName - Public-facing name shown in the UI\n * @param data.role - Initial permission level assigned to the account\n * @returns The created user record with generated ID\n */\nfunction createUser(data: { email: string; displayName: string; role: Role }): User {\n```\n\nFor React component props, use `props` (or `root0` if destructured) as the root:\n\n```typescript\n/**\n * @param props - Component properties\n * @param props.title - Page heading displayed at the top\n * @param props.onSubmit - Callback invoked when the form is submitted\n */\nfunction MyComponent(props: { title: string; onSubmit: () => void }) {\n```\n\n### Overload documentation\n\nWhen a function has TypeScript overload signatures, document **both** the overload declarations and the implementation signature:\n\n```typescript\n/**\n * Parse a value from a string representation.\n *\n * @param input - Raw string to parse\n * @returns Parsed numeric value\n */\nfunction parse(input: string): number;\n/**\n * Parse a value from a buffer.\n *\n * @param input - Binary buffer to parse\n * @returns Parsed numeric value\n */\nfunction parse(input: Buffer): number;\n/**\n * Parse a value from string or buffer input. String inputs are decoded\n * as UTF-8 before numeric parsing.\n *\n * @param input - String or buffer to parse\n * @returns Parsed numeric value\n * @throws {ParseError} When the input cannot be interpreted as a number\n */\nfunction parse(input: string | Buffer): number {\n  // implementation\n}\n```\n\n';
+	'# World-Class JSDoc Guidelines for TypeScript\n\nThese guidelines describe the *properties* of excellent inline JSDoc in TypeScript repositories. They are a target to aim for, not a checklist. Use judgment; clarity beats volume.\n\n## Core principle\n\nTypeScript projects already have explicit types. JSDoc should add **intent, behavior, and constraints** rather than repeat what the type system already expresses.\n\n## Would have (high-signal properties)\n\n- **Intent and constraints**: Explains the non-obvious decision, constraint, or tradeoff (e.g., why a particular algorithm is used, why a heuristic exists, or what the runtime environment forbids).\n- **Behavioral contract**: Clearly states what inputs are accepted, what outputs represent, and how boundary cases are treated.\n- **Domain vocabulary**: Uses project-specific terms consistently so readers can navigate the codebase by vocabulary.\n- **Examples that disambiguate**: Includes `@example` blocks when behavior is otherwise ambiguous (e.g., parsing rules, path formats, or object schemas). Examples are short and realistic.\n- **Runtime effects**: Calls out side effects, temporal dependency (polling vs. event-driven), filesystem reads/writes, or external service behavior when those matter.\n- **Edge-case prompts**: Captures "what happens if..." questions that a reviewer would ask, especially where external APIs or platform behavior has caveats.\n- **Consistency with existing style**: Matches the formatting conventions already established in the codebase (multi-line descriptions, bullet lists where helpful).\n- **Future-proof hints**: Notes invariants and assumptions that must hold if the code evolves.\n- **LLM-friendly structure**: Uses short, self-contained paragraphs written in clear International Business English. Avoids prescriptive headers (e.g., "Why:", "Constraint:") in favor of natural prose that states context, purpose, and caveats directly.\n\n## Would not have (low-signal or risky properties)\n\n- **Type restatements**: Repeating TypeScript types in prose (e.g., "@param options - The options object" when the type is already `Options`). Keep `@param`, `@returns`, and `@throws` tags\u2014just make the descriptions add meaning beyond the type.\n- **Obvious narration**: Comments that paraphrase the code or parameter name without additional insight.\n- **Incorrect authority**: Claims that are not enforced by code (e.g., "never throws" when it can, or "always" without guardrails).\n- **Redundant verbosity**: Long descriptions that could be expressed more directly, or boilerplate that hides the key idea.\n- **Unbounded examples**: Large blocks or full payloads when a minimal example would do.\n- **Out-of-date operational details**: References to tooling, CLI flags, or config knobs that are not enforced or checked.\n- **Implementation leakage**: Unnecessary internal steps or private details that are likely to change and add churn to docs.\n- **Non-ASCII decoration**: Fancy symbols or emojis that do not already exist in the file; keep ASCII unless needed.\n\n## Tag usage cues (not rules)\n\n### IntelliSense tags (always include)\n\nThese tags power IDE hover tooltips, autocomplete, and signature help. Always include them for public APIs, constructors, and functions:\n\n- **`@param`**: Include for every parameter. Describe the parameter\'s purpose, valid ranges, or constraints\u2014not just its type.\n- **`@returns`**: Include when the function returns a value. Describe what the return value represents, especially for edge cases.\n- **`@throws`**: Include when the function can throw. Describe the conditions that cause the error.\n- **`@template`**: Include for generic functions and types. Describe what the type parameter represents.\n\n### Cross-reference tags (use to aid navigation)\n\n- **`@see`**: Link to related functions, types, or external documentation.\n- **`{@link Symbol}`**: Inline reference within descriptions. Creates a clickable link to another symbol.\n\n### Structural tags (use when appropriate)\n\n- Use `@module` at the top of files that define a cohesive domain concept.\n- Use `@example` when parsing or formatting behavior could be misread, or when a type is complex.\n- Use `@deprecated` on exports that are retained for compatibility.\n- Prefer short description + bullets for concepts with multiple facets.\n\n---\n\n## Writing file-level @summary and description\n\nEvery TypeScript file should have a file-level JSDoc block before the first code statement. This block is what jsdoczoom reads for orientation and validation.\n\n### Structure\n\n```typescript\n/**\n * Description paragraph goes here. It explains the file\'s responsibilities,\n * invariants, trade-offs, and failure modes. This is the deepest level of\n * native documentation \u2014 enough for someone to understand why this file\n * exists and how it fits into the broader system.\n *\n * @summary Concise one-line overview for quick orientation when scanning a codebase.\n */\n```\n\n### The @summary tag\n\nThe `@summary` tag provides a one-line overview \u2014 the first thing someone sees when scanning with jsdoczoom at the shallowest depth.\n\n**Good summaries:**\n- State what the file *does* or *is responsible for*, not what it contains\n- Are self-contained \u2014 understandable without reading other files\n- Use domain vocabulary consistently with the rest of the codebase\n- Fit on a single line (joined if multi-line in source)\n\n**Examples:**\n- `@summary Barrel tree model for hierarchical gating in glob mode`\n- `@summary Resolve selector patterns to absolute file paths with gitignore filtering`\n- `@summary CLI entry point \u2014 argument parsing, mode dispatch, and exit code handling`\n\n**Avoid:**\n- `@summary This file contains utility functions` \u2014 says what it *contains*, not what it *does*\n- `@summary Helpers` \u2014 too vague, no domain context\n- `@summary The main module` \u2014 no information about purpose or scope\n\n### The description paragraph\n\nThe description is prose that appears before any `@` tags. It provides the deeper context that the summary cannot \u2014 responsibilities, invariants, trade-offs, and failure modes.\n\n**Good descriptions:**\n- Explain *why* this file exists and what problem it solves\n- State invariants and assumptions that callers or maintainers must know\n- Note trade-offs and design decisions (e.g., "uses priority-order fill to keep the limit algorithm simple")\n- Mention failure modes and edge cases relevant to the file as a whole\n- Are 1-4 sentences, not an essay\n\n**Examples:**\n```typescript\n/**\n * Walks .gitignore files from cwd to filesystem root, building an ignore\n * filter that glob results pass through. Direct-path lookups bypass the\n * filter since the user explicitly named the file. The ignore instance is\n * created per call \u2014 no caching \u2014 because cwd may differ between invocations.\n *\n * @summary Resolve selector patterns to absolute file paths with gitignore filtering\n */\n```\n\n```typescript\n/**\n * Each file is classified into exactly one status category: the first\n * failing check wins (syntax_error > missing_jsdoc > missing_summary >\n * missing_description). Valid files are omitted from output entirely.\n * The limit parameter caps the total number of invalid paths shown,\n * filled in priority order across groups.\n *\n * @summary Validate file-level JSDoc and group results by status category\n */\n```\n\n**Avoid:**\n- Restating the summary in longer words\n- Listing every function in the file\n- Implementation details that change frequently (line numbers, internal variable names)\n\n### Barrel files (index.ts / index.tsx)\n\nBarrel files represent their directory. Their `@summary` and description should describe the **cumulative functionality of the directory\'s children**, not the barrel file itself.\n\n- **`@summary`**: The collective purpose of the files in this directory\n- **Description**: The combined capabilities and responsibilities of child modules \u2014 what they do together, not their filenames or the re-export mechanism\n\n```typescript\n// packages/auth/src/index.ts\n/**\n * Provides session lifecycle management, token validation and refresh,\n * and middleware for route-level access control. OAuth2 provider\n * integration is handled here; cryptographic primitives are delegated\n * to the crypto package.\n *\n * @summary Authentication and authorization module\n */\n```\n\n**Avoid:**\n- `@summary Re-exports all functions and types` \u2014 describes the barrel mechanism, not what the children do\n- `@summary Exports for the auth module` \u2014 describes the mechanism, not the purpose\n- `@summary Public API barrel` \u2014 names the pattern rather than describing functionality\n- Listing child filenames or saying "This is the entry point"\n\n### Placement\n\nThe file-level JSDoc block must appear **before the first code statement** (imports are fine above it, but the block must precede any `export`, `const`, `function`, `class`, etc.). A common pattern is to place it immediately after imports:\n\n```typescript\nimport { resolve } from "node:path";\nimport { globSync } from "glob";\n\n/**\n * Description paragraph here.\n *\n * @summary One-line overview here\n */\n\nexport function discoverFiles(...) { ... }\n```\n\n### Common lint rules and examples\n\nThese rules are enforced in lint mode (`-l`). Understanding what passes and fails reduces trial-and-rerun cycles.\n\n#### `jsdoc/informative-docs` \u2014 descriptions must add meaning\n\nThis rule rejects descriptions that merely restate the parameter name, type, or containing symbol name. Descriptions must provide behavioral context.\n\n**Fails:**\n- `@param id - The id`\n- `@param options - The options object`\n- `@returns The result`\n- `@param name - The name string`\n\n**Passes:**\n- `@param id - Unique identifier used for cache lookup and deduplication`\n- `@param options - Controls retry behavior, timeout, and error handling strategy`\n- `@returns Parsed configuration with defaults applied for missing fields`\n- `@param name - Display name shown in the navigation sidebar`\n\n**Rule of thumb:** If removing the parameter name from the description leaves no useful information, the description is not informative enough.\n\n#### `jsdoc/check-tag-names` \u2014 allowed tags only\n\nThe lint configuration rejects non-standard JSDoc tags. Common tags to **avoid in JSDoc blocks**:\n- `@remarks` \u2014 move content to the description paragraph (prose before tags)\n- `@packageDocumentation` \u2014 use `@module` instead\n- `@concept`, `@constraint` \u2014 move content to the description paragraph\n\nFramework directives that look like tags (e.g., `@vitest-environment`) should use plain comments instead:\n```typescript\n// @vitest-environment node   \u2190 correct (plain comment)\n/** @vitest-environment node */  \u2190 incorrect (treated as JSDoc tag)\n```\n\n#### `jsdoc/require-throws` \u2014 document throw conditions\n\nInclude `@throws` for any function that can throw, including catch-and-rethrow patterns:\n```typescript\n/**\n * @param path - File path to read\n * @returns Parsed configuration object\n * @throws {ConfigError} When the file is missing or contains invalid YAML\n */\n```\n\nIf a function catches errors and rethrows them (wrapped or unwrapped), it still needs `@throws`.\n\n### Nested object parameters\n\nWhen a function accepts an inline object parameter, document each property with a nested `@param` tag:\n\n```typescript\n/**\n * Create a new user account.\n *\n * @param data - Account creation payload\n * @param data.email - Email address used for login and notifications\n * @param data.displayName - Public-facing name shown in the UI\n * @param data.role - Initial permission level assigned to the account\n * @returns The created user record with generated ID\n */\nfunction createUser(data: { email: string; displayName: string; role: Role }): User {\n```\n\nFor React component props, use `props` (or `root0` if destructured) as the root:\n\n```typescript\n/**\n * @param props - Component properties\n * @param props.title - Page heading displayed at the top\n * @param props.onSubmit - Callback invoked when the form is submitted\n */\nfunction MyComponent(props: { title: string; onSubmit: () => void }) {\n```\n\n### Overload documentation\n\nWhen a function has TypeScript overload signatures, document **both** the overload declarations and the implementation signature:\n\n```typescript\n/**\n * Parse a value from a string representation.\n *\n * @param input - Raw string to parse\n * @returns Parsed numeric value\n */\nfunction parse(input: string): number;\n/**\n * Parse a value from a buffer.\n *\n * @param input - Binary buffer to parse\n * @returns Parsed numeric value\n */\nfunction parse(input: Buffer): number;\n/**\n * Parse a value from string or buffer input. String inputs are decoded\n * as UTF-8 before numeric parsing.\n *\n * @param input - String or buffer to parse\n * @returns Parsed numeric value\n * @throws {ParseError} When the input cannot be interpreted as a number\n */\nfunction parse(input: string | Buffer): number {\n  // implementation\n}\n```\n\n## Text output and piping\n\njsdoczoom outputs human-readable text by default. Each item has a `# path` header followed by content. This makes it composable with standard Unix tools:\n\n```sh\njsdoczoom src/utils.ts@3 | grep "functionName"      # find symbol + source line\njsdoczoom src/utils.ts@3 | grep "// L"              # list all declarations with lines\njsdoczoom src/**/*.ts | grep "^#"                    # list all file summaries\ngrep -rl "term" src/ --include="*.ts" | jsdoczoom    # describe matching files\n```\n\nType declarations include source line annotations (`// LN` or `// LN-LM` for ranges), so you can locate implementations in the source file without a separate search step.\n\nFor machine-parseable output, use `--json`:\n\n```sh\njsdoczoom --json src/**/*.ts | jq \'.items[].text\'\n```\n';
 /** Explanation text for each lint rule, used by --explain-rule */
 export declare const RULE_EXPLANATIONS: Record<string, string>;

package/types/text-format.d.ts

@@ -0,0 +1,6 @@
+import type { DrilldownResult } from "./types.js";
+/**
+ * Format a DrilldownResult as plain text for CLI output.
+ * Returns the formatted string with a trailing newline.
+ */
+export declare function formatTextOutput(result: DrilldownResult): string;

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>;

package/types/types.d.ts

@@ -32,6 +32,7 @@ export type OutputEntry = OutputItem | OutputErrorItem;
 export interface DrilldownResult {
 	items: OutputEntry[];
 	truncated: boolean;
+	total?: number;
 }
 /** All recognized error codes */
 export type ErrorCode =