jsdoczoom 0.4.21 → 1.0.0

package/dist/cli.js

@@ -7,6 +7,7 @@ import { JsdocError } from "./errors.js";
 import { lint, lintFiles } from "./lint.js";
 import { parseSelector } from "./selector.js";
 import { RULE_EXPLANATIONS, SKILL_TEXT } from "./skill-text.js";
+import { formatTextOutput } from "./text-format.js";
 import { DEFAULT_CACHE_DIR, VALIDATION_STATUS_PRIORITY } from "./types.js";
 import { validate, validateFiles } from "./validate.js";
 
@@ -30,7 +31,8 @@ Options:
   -c, --check      Run validation mode
   -l, --lint       Run lint mode (comprehensive JSDoc quality)
   -s, --skill      Print JSDoc writing guidelines
-  --pretty         Format JSON output with 2-space indent
+  --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
   --disable-cache    Skip all cache operations
@@ -51,8 +53,12 @@ Stdin:
     find . -name "*.ts" | jsdoczoom -c
 
 Output:
-  JSON items. Items with "next_id" have more detail; use that value as the next
-  selector. Items with "id" (no next_id) are at terminal depth.
+  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.
+
+  Type declarations (@3) include source line annotations (// LN or // LN-LM)
+  so you can locate the implementation in the source file.
 
 Barrel gating (glob mode):
   A barrel's @summary and description reflect the cumulative functionality
@@ -70,15 +76,15 @@ Exit codes:
   2  Validation or lint failures found
 
 Workflow:
-  $ jsdoczoom src/**/*.ts
-  { "items": [{ "next_id": "src/utils@2", "text": "..." }, ...] }
-
-  $ jsdoczoom src/utils@2                # use next_id from above
-  { "items": [{ "next_id": "src/utils@3", "text": "..." }] }
+  $ jsdoczoom src/**/*.ts                # list summaries
+  $ jsdoczoom src/utils@2                # drill into description
+  $ jsdoczoom src/utils@3                # see type declarations
 
-  $ jsdoczoom src/utils@3                # use next_id again
-  { "items": [{ "id": "src/utils@3", "text": "..." }] }
-  # "id" instead of "next_id" means terminal depth — stop here
+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
 `;
 /**
  * Parse a flag that requires a value argument.
@@ -97,6 +103,7 @@ function parseArgs(args) {
 		checkMode: false,
 		lintMode: false,
 		skillMode: false,
+		json: false,
 		pretty: false,
 		limit: 500,
 		gitignore: true,
@@ -128,6 +135,10 @@ function parseArgs(args) {
 			parsed.skillMode = true;
 			continue;
 		}
+		if (arg === "--json") {
+			parsed.json = true;
+			continue;
+		}
 		if (arg === "--pretty") {
 			parsed.pretty = true;
 			continue;
@@ -196,6 +207,7 @@ async function processStdin(
 	selectorArg,
 	checkMode,
 	lintMode,
+	json,
 	pretty,
 	limit,
 	cwd,
@@ -218,7 +230,7 @@ async function processStdin(
 			limit,
 			cacheConfig,
 		);
-		writeResult(result, pretty);
+		writeDrilldownResult(result, json, pretty);
 	}
 }
 /**
@@ -228,6 +240,7 @@ async function processSelector(
 	selectorArg,
 	checkMode,
 	lintMode,
+	json,
 	pretty,
 	limit,
 	gitignore,
@@ -251,7 +264,7 @@ async function processSelector(
 			limit,
 			cacheConfig,
 		);
-		writeResult(result, pretty);
+		writeDrilldownResult(result, json, pretty);
 	}
 }
 /**
@@ -352,6 +365,7 @@ export async function main(args, stdin) {
 				parsed.selectorArg,
 				parsed.checkMode,
 				parsed.lintMode,
+				parsed.json,
 				parsed.pretty,
 				parsed.limit,
 				cwd,
@@ -362,6 +376,7 @@ export async function main(args, stdin) {
 				parsed.selectorArg,
 				parsed.checkMode,
 				parsed.lintMode,
+				parsed.json,
 				parsed.pretty,
 				parsed.limit,
 				parsed.gitignore,
@@ -373,6 +388,16 @@ export async function main(args, stdin) {
 		writeError(error);
 	}
 }
+/**
+ * Write a drilldown result to stdout as text (default) or JSON.
+ */
+function writeDrilldownResult(result, json, pretty) {
+	if (json) {
+		writeResult(result, pretty);
+	} else {
+		void process.stdout.write(formatTextOutput(result));
+	}
+}
 /**
  * Write a result to stdout as JSON.
  */

package/dist/drilldown.js

@@ -335,11 +335,12 @@ export async function drilldown(
 			const sorted = results.sort((a, b) =>
 				sortKey(a).localeCompare(sortKey(b)),
 			);
-			const total = sorted.length;
-			const truncated = total > limit;
+			const count = sorted.length;
+			const isTruncated = count > limit;
 			return {
 				items: sorted.slice(0, limit),
-				truncated,
+				truncated: isTruncated,
+				...(isTruncated ? { total: count } : {}),
 			};
 		}
 		// Single file path — errors are fatal
@@ -394,11 +395,12 @@ export async function drilldown(
 	const results = await processGlobWithBarrels(files, depth, cwd, config);
 	// Sort alphabetically by key
 	const sorted = results.sort((a, b) => sortKey(a).localeCompare(sortKey(b)));
-	const total = sorted.length;
-	const truncated = total > limit;
+	const count = sorted.length;
+	const isTruncated = count > limit;
 	return {
 		items: sorted.slice(0, limit),
-		truncated,
+		truncated: isTruncated,
+		...(isTruncated ? { total: count } : {}),
 	};
 }
 /**
@@ -432,10 +434,11 @@ export async function drilldownFiles(
 	});
 	const results = await collectSafeResults(tsFiles, d, cwd, config);
 	const sorted = results.sort((a, b) => sortKey(a).localeCompare(sortKey(b)));
-	const total = sorted.length;
-	const truncated = total > limit;
+	const count = sorted.length;
+	const isTruncated = count > limit;
 	return {
 		items: sorted.slice(0, limit),
-		truncated,
+		truncated: isTruncated,
+		...(isTruncated ? { total: count } : {}),
 	};
 }

package/dist/index.js

@@ -14,6 +14,7 @@ export { discoverFiles } from "./file-discovery.js";
 export { extractFileJsdoc, parseFileSummaries } from "./jsdoc-parser.js";
 export { lint, lintFiles } from "./lint.js";
 export { parseSelector } from "./selector.js";
+export { formatTextOutput } from "./text-format.js";
 export { generateTypeDeclarations } from "./type-declarations.js";
 export { DEFAULT_CACHE_DIR, VALIDATION_STATUS_PRIORITY } from "./types.js";
 export { validate, validateFiles } from "./validate.js";

package/dist/skill-text.js

@@ -368,6 +368,24 @@ function parse(input: string | Buffer): number {
 }
 \`\`\`
 
+## Text output and piping
+
+jsdoczoom outputs human-readable text by default. Each item has a \`# path\` header followed by content. This makes it composable with standard Unix tools:
+
+\`\`\`sh
+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 summaries
+grep -rl "term" src/ --include="*.ts" | jsdoczoom    # describe matching files
+\`\`\`
+
+Type 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.
+
+For machine-parseable output, use \`--json\`:
+
+\`\`\`sh
+jsdoczoom --json src/**/*.ts | jq '.items[].text'
+\`\`\`
 `;
 /** Explanation text for each lint rule, used by --explain-rule */
 export const RULE_EXPLANATIONS = {

package/dist/text-format.js

@@ -0,0 +1,42 @@
+/**
+ * Formats drilldown results as human-readable text for shell piping.
+ * Each item gets a `# id` header line followed by its content.
+ * Items are separated by blank lines.
+ *
+ * @summary Plain-text output formatter for drilldown results
+ */
+/**
+ * Format a single output entry as a text block (header + content).
+ */
+function formatEntry(entry) {
+	if ("error" in entry) {
+		return `# ${entry.id} [${entry.error.code}]\n${entry.error.message}`;
+	}
+	const text = entry.text.trimEnd();
+	if ("next_id" in entry) {
+		const lines = [`# ${entry.next_id}`];
+		const children = entry.children;
+		if (children) {
+			lines.push(`## children: ${children.join(", ")}`);
+		}
+		if (text) lines.push(text);
+		return lines.join("\n");
+	}
+	// Terminal item
+	if (!text) return `# ${entry.id}`;
+	return `# ${entry.id}\n${text}`;
+}
+/**
+ * Format a DrilldownResult as plain text for CLI output.
+ * Returns the formatted string with a trailing newline.
+ */
+export function formatTextOutput(result) {
+	const blocks = result.items.map(formatEntry);
+	let output = blocks.join("\n\n");
+	if (result.truncated && result.total !== undefined) {
+		output += `\n\n# truncated (showing ${result.items.length} of ${result.total})`;
+	} else if (result.truncated) {
+		output += "\n\n# truncated";
+	}
+	return `${output}\n`;
+}

package/dist/type-declarations.js

@@ -153,6 +153,116 @@ export function resetCache() {
 	compilerOptionsCache.clear();
 	serviceCache.clear();
 }
+/**
+ * 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");
+	const sourceFile = ts.createSourceFile(
+		filePath,
+		content,
+		ts.ScriptTarget.Latest,
+		true,
+	);
+	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;
+		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);
+				}
+			}
+		}
+	}
+	return map;
+}
+/** Regex matching the start of a top-level export declaration in .d.ts output. */
+const DECL_PATTERN =
+	/^export\s+(?:default\s+)?(?:declare\s+)?(?:abstract\s+)?(?:type|interface|function|const|let|var|class|enum)\s+(\w+)/;
+/**
+ * Format a source range as a GitHub-style line annotation.
+ */
+function formatLineRef(range) {
+	return range.start === range.end
+		? `// L${range.start}`
+		: `// L${range.start}-L${range.end}`;
+}
+/**
+ * Find the start of the JSDoc block above a declaration line.
+ * Returns the declaration line index itself if no JSDoc is found.
+ */
+function findChunkStart(lines, declLine) {
+	if (declLine === 0) return 0;
+	const prev = lines[declLine - 1]?.trimEnd();
+	if (prev === "*/" || prev?.endsWith("*/")) {
+		for (let j = declLine - 1; j >= 0; j--) {
+			if (lines[j].trimStart().startsWith("/**")) return j;
+		}
+	} else if (prev?.trimStart().startsWith("/**")) {
+		// Single-line JSDoc: /** comment */
+		return declLine - 1;
+	}
+	return declLine;
+}
+/**
+ * Annotate .d.ts text with source line references for each top-level declaration.
+ * 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);
+	if (lineMap.size === 0) return dtsText;
+	const lines = dtsText.split("\n");
+	// First pass: map chunk start lines to their annotations
+	const annotations = new Map();
+	for (let i = 0; i < lines.length; i++) {
+		const match = lines[i].match(DECL_PATTERN);
+		if (!match) continue;
+		const range = lineMap.get(match[1]);
+		if (!range) continue;
+		annotations.set(findChunkStart(lines, i), formatLineRef(range));
+	}
+	if (annotations.size === 0) return dtsText;
+	// Second pass: build output with annotations inserted
+	const result = [];
+	for (let i = 0; i < lines.length; i++) {
+		const annotation = annotations.get(i);
+		if (annotation) {
+			// Blank line separator before annotation (if there's content above)
+			if (result.length > 0 && result[result.length - 1]?.trim() !== "") {
+				result.push("");
+			}
+			result.push(annotation);
+		}
+		result.push(lines[i]);
+	}
+	return result.join("\n");
+}
 /**
  * Generates TypeScript declaration output from a source file.
  *
@@ -208,5 +318,8 @@ export function generateTypeDeclarations(filePath) {
 	if (withoutComments === "export {};") {
 		cleaned = "";
 	}
+	if (cleaned.length > 0) {
+		cleaned = annotateWithSourceLines(cleaned, filePath);
+	}
 	return cleaned;
 }

package/package.json

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

package/types/index.d.ts

@@ -14,6 +14,7 @@ export { discoverFiles } from "./file-discovery.js";
 export { extractFileJsdoc, parseFileSummaries } from "./jsdoc-parser.js";
 export { lint, lintFiles } from "./lint.js";
 export { parseSelector } from "./selector.js";
+export { formatTextOutput } from "./text-format.js";
 export { generateTypeDeclarations } from "./type-declarations.js";
 export {
 	type CacheConfig,

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/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 =