jsdoczoom 0.3.0 → 0.4.5

package/dist/validate.js

@@ -1,6 +1,7 @@
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
-import { isBarrel } from "./barrel.js";
+import { readFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { findMissingBarrels } from "./barrel.js";
+import { processWithCache } from "./cache.js";
 import { JsdocError } from "./errors.js";
 import {
 	createValidationLinter,
@@ -9,50 +10,28 @@ import {
 } from "./eslint-engine.js";
 import { discoverFiles } from "./file-discovery.js";
 import { GUIDANCE } from "./skill-text.js";
-import { VALIDATION_STATUS_PRIORITY } from "./types.js";
+import { DEFAULT_CACHE_DIR, VALIDATION_STATUS_PRIORITY } from "./types.js";
 
 /**
  * Classify a single file against validation requirements.
  *
  * Reads the file, lints it with the ESLint engine, and maps the
  * resulting messages to a single ValidationStatus using priority order.
+ * Results are cached by file content hash.
  */
-async function classifyFile(eslint, filePath, cwd) {
+async function classifyFile(eslint, filePath, cwd, config) {
 	const relativePath = relative(cwd, 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}`);
 	}
-	const messages = await lintFileForValidation(eslint, sourceText, filePath);
-	const status = mapToValidationStatus(messages);
-	return { path: relativePath, status };
-}
-/** Minimum number of .ts/.tsx files in a directory to require a barrel. */
-const BARREL_THRESHOLD = 3;
-/**
- * Find directories with more than BARREL_THRESHOLD .ts/.tsx files
- * that lack a barrel file (index.ts or index.tsx).
- */
-function findMissingBarrels(filePaths, cwd) {
-	const dirCounts = new Map();
-	for (const filePath of filePaths) {
-		if (isBarrel(filePath)) continue;
-		const dir = dirname(filePath);
-		dirCounts.set(dir, (dirCounts.get(dir) ?? 0) + 1);
-	}
-	const missing = [];
-	for (const [dir, count] of dirCounts) {
-		if (count <= BARREL_THRESHOLD) continue;
-		const hasBarrel =
-			existsSync(join(dir, "index.ts")) || existsSync(join(dir, "index.tsx"));
-		if (!hasBarrel) {
-			const rel = relative(cwd, dir) || ".";
-			missing.push(rel);
-		}
-	}
-	return missing.sort();
+	return processWithCache(config, "validate", sourceText, async () => {
+		const messages = await lintFileForValidation(eslint, sourceText, filePath);
+		const status = mapToValidationStatus(messages);
+		return { path: relativePath, status };
+	});
 }
 /**
  * Group file statuses into a ValidationResult, applying a limit
@@ -95,11 +74,19 @@ function buildGroupedResult(statuses, missingBarrels, limit) {
  * @param selector - Selector information (glob or path)
  * @param cwd - Working directory for resolving paths
  * @param limit - Max number of invalid file paths to include (default 100)
+ * @param gitignore - Whether to respect .gitignore (default true)
+ * @param config - Cache configuration (default: enabled with system temp dir)
  * @returns Grouped validation results
  * @throws {JsdocError} NO_FILES_MATCHED if glob selector matches no files
  * @throws {JsdocError} FILE_NOT_FOUND if path selector targets nonexistent file
  */
-export async function validate(selector, cwd, limit = 100, gitignore = true) {
+export async function validate(
+	selector,
+	cwd,
+	limit = 100,
+	gitignore = true,
+	config = { enabled: true, directory: DEFAULT_CACHE_DIR },
+) {
 	const files = discoverFiles(selector.pattern, cwd, gitignore);
 	if (files.length === 0) {
 		throw new JsdocError(
@@ -109,7 +96,7 @@ export async function validate(selector, cwd, limit = 100, gitignore = true) {
 	}
 	const eslint = createValidationLinter();
 	const statuses = await Promise.all(
-		files.map((f) => classifyFile(eslint, f, cwd)),
+		files.map((f) => classifyFile(eslint, f, cwd, config)),
 	);
 	const missingBarrels = findMissingBarrels(files, cwd);
 	return buildGroupedResult(statuses, missingBarrels, limit);
@@ -122,15 +109,21 @@ export async function validate(selector, cwd, limit = 100, gitignore = true) {
  * @param filePaths - List of file paths to validate
  * @param cwd - Working directory for resolving relative paths
  * @param limit - Max number of invalid file paths to include (default 100)
+ * @param config - Cache configuration (default: enabled with system temp dir)
  * @returns Grouped validation results
  */
-export async function validateFiles(filePaths, cwd, limit = 100) {
+export async function validateFiles(
+	filePaths,
+	cwd,
+	limit = 100,
+	config = { enabled: true, directory: DEFAULT_CACHE_DIR },
+) {
 	const tsFiles = filePaths.filter(
 		(f) => f.endsWith(".ts") || f.endsWith(".tsx"),
 	);
 	const eslint = createValidationLinter();
 	const statuses = await Promise.all(
-		tsFiles.map((f) => classifyFile(eslint, f, cwd)),
+		tsFiles.map((f) => classifyFile(eslint, f, cwd, config)),
 	);
 	const missingBarrels = findMissingBarrels(tsFiles, cwd);
 	return buildGroupedResult(statuses, missingBarrels, limit);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "jsdoczoom",
-	"version": "0.3.0",
+	"version": "0.4.5",
 	"description": "CLI tool for extracting JSDoc summaries at configurable depths",
 	"type": "module",
 	"sideEffects": false,
@@ -35,23 +35,27 @@
 	},
 	"scripts": {
 		"typecheck": "tsc --noEmit",
-		"build": "tsc --build tsconfig.build.json",
+		"build": "yarn build:claude-code-hooks && yarn build:cli && yarn build:hooks",
+		"build:cli": "tsc --build tsconfig.build.json",
+		"build:claude-code-hooks": "cd ../claude-code-hooks && yarn build",
+		"build:hooks": "claude-code-hooks -i \"src/hooks/*.ts\" -o \"../../plugins/jsdoczoom/hooks/hooks.json\"",
 		"test": "vitest run",
 		"lint": "biome check --write --unsafe --max-diagnostics 500 .",
 		"release": "bash ../../scripts/release-package.sh jsdoczoom",
 		"release:dry-run": "bash ../../scripts/release-package.sh jsdoczoom --dry-run"
 	},
 	"dependencies": {
-		"@typescript-eslint/parser": "^8.21.0",
-		"eslint": "^9.20.0",
-		"eslint-plugin-jsdoc": "^50.6.4",
-		"glob": "^11.0.0",
+		"@goodfoot/claude-code-hooks": "workspace:*",
+		"@typescript-eslint/parser": "^8.55.0",
+		"eslint": "^10.0.0",
+		"eslint-plugin-jsdoc": "^62.5.5",
+		"glob": "^13.0.3",
 		"ignore": "^7.0.5",
 		"typescript": "^5.9.3"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.3.14",
-		"@types/node": "^24",
-		"vitest": "4.0.13"
+		"@biomejs/biome": "2.4.1",
+		"@types/node": "^25.2.3",
+		"vitest": "4.0.18"
 	}
 }

package/types/barrel.d.ts

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

package/types/cache.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Content-hash-based disk caching layer for expensive operations (TypeScript
+ * compilation, ESLint linting, JSDoc parsing). Uses SHA-256 hashing to cache
+ * results keyed by file content, enabling near-instantaneous repeated runs
+ * when files haven't changed. All cache errors degrade gracefully without
+ * propagating to callers.
+ *
+ * @summary Content-hash-based disk cache with graceful error handling
+ */
+import type { CacheConfig, CacheOperationMode } from "./types.js";
+/**
+ * Compute a SHA-256 content hash for the given string.
+ *
+ * @param content - The content to hash
+ * @returns Hex-encoded SHA-256 digest
+ */
+export declare function computeContentHash(content: string): string;
+/**
+ * Ensure the cache directory exists for the given operation mode.
+ * Silently swallows all errors (mkdir failures are handled by read/write ops).
+ *
+ * @param config - Cache configuration
+ * @param mode - Operation mode (drilldown, validate, or lint)
+ */
+export declare function ensureCacheDir(
+	config: CacheConfig,
+	mode: CacheOperationMode,
+): Promise<void>;
+/**
+ * Read a cached entry from disk. Returns null on any error (cache miss, ENOENT,
+ * corrupted JSON, permission denied, etc.). Never throws.
+ *
+ * @param config - Cache configuration
+ * @param mode - Operation mode namespace
+ * @param hash - Content hash key
+ * @returns Parsed cached data or null on any error
+ */
+export declare function readCacheEntry<T>(
+	config: CacheConfig,
+	mode: CacheOperationMode,
+	hash: string,
+): Promise<T | null>;
+/**
+ * Write a cache entry to disk using atomic write (write to .tmp then rename).
+ * Silently swallows all errors (permission denied, disk full, etc.). Never throws.
+ *
+ * @param config - Cache configuration
+ * @param mode - Operation mode namespace
+ * @param hash - Content hash key
+ * @param data - Data to cache (must be JSON-serializable)
+ */
+export declare function writeCacheEntry<T>(
+	config: CacheConfig,
+	mode: CacheOperationMode,
+	hash: string,
+	data: T,
+): Promise<void>;
+/**
+ * Execute a computation with caching. If cache is enabled and entry exists,
+ * returns cached result. Otherwise, computes result, stores it (fire-and-forget),
+ * and returns it. Degrades gracefully on all cache errors by always computing.
+ *
+ * @param config - Cache configuration
+ * @param mode - Operation mode namespace
+ * @param content - File content to hash for cache key
+ * @param compute - Function to compute the result on cache miss
+ * @returns Cached or computed result
+ */
+export declare function processWithCache<T>(
+	config: CacheConfig,
+	mode: CacheOperationMode,
+	content: string,
+	compute: () => T | Promise<T>,
+): Promise<T>;

package/types/drilldown.d.ts

@@ -1,4 +1,4 @@
-import type { DrilldownResult, SelectorInfo } from "./types.js";
+import type { CacheConfig, DrilldownResult, SelectorInfo } from "./types.js";
 /**
  * Main entry point for normal-mode processing.
  *
@@ -18,7 +18,8 @@ export declare function drilldown(
 	cwd: string,
 	gitignore?: boolean,
 	limit?: number,
-): DrilldownResult;
+	config?: CacheConfig,
+): Promise<DrilldownResult>;
 /**
  * Process an explicit list of file paths at a given depth.
  *
@@ -35,4 +36,5 @@ export declare function drilldownFiles(
 	depth: number | undefined,
 	cwd: string,
 	limit?: number,
-): DrilldownResult;
+	config?: CacheConfig,
+): Promise<DrilldownResult>;

package/types/file-discovery.d.ts

@@ -1,3 +1,17 @@
+import { type Ignore } from "ignore";
+/**
+ * Walks .gitignore files from cwd to filesystem root, building an ignore
+ * filter that glob results pass through. Direct-path lookups bypass the
+ * filter since the user explicitly named the file. The ignore instance is
+ * created per call -- no caching -- because cwd may differ between invocations.
+ *
+ * @summary Resolve selector patterns to absolute file paths with gitignore filtering
+ */
+/**
+ * Walk from `cwd` up to the filesystem root, collecting .gitignore entries.
+ * Returns an Ignore instance loaded with all discovered rules.
+ */
+export declare function loadGitignore(cwd: string): Ignore;
 /**
  * Resolve a selector pattern to a list of .ts/.tsx file paths.
  *

package/types/index.d.ts

@@ -1,9 +1,11 @@
 /**
- * Re-exports all public functions, classes, and types from internal modules.
- * This is the sole entry point for programmatic consumers of the jsdoczoom
- * package.
+ * Progressively explores TypeScript codebase documentation through a 4-level
+ * drill-down (summary, description, type declarations, full source), validates
+ * file-level JSDoc structure, and lints comprehensive JSDoc quality using
+ * ESLint. Barrel files gate their children at shallow depths, revealing
+ * individual files only at deeper levels.
  *
- * @summary Public API barrel re-exporting all functions, types, and classes
+ * @summary Progressive JSDoc exploration, validation, and linting for TypeScript codebases
  */
 export { getBarrelChildren, isBarrel } from "./barrel.js";
 export { drilldown, drilldownFiles } from "./drilldown.js";
@@ -14,6 +16,9 @@ export { lint, lintFiles } from "./lint.js";
 export { parseSelector } from "./selector.js";
 export { generateTypeDeclarations } from "./type-declarations.js";
 export {
+	type CacheConfig,
+	type CacheOperationMode,
+	DEFAULT_CACHE_DIR,
 	type DrilldownResult,
 	type ErrorCode,
 	type LintDiagnostic,

package/types/lint.d.ts

@@ -8,7 +8,7 @@
  *
  * @summary Lint files for comprehensive JSDoc quality using ESLint engine
  */
-import type { LintResult, SelectorInfo } from "./types.js";
+import type { CacheConfig, LintResult, SelectorInfo } from "./types.js";
 /**
  * Lint files matching a selector pattern for comprehensive JSDoc quality.
  *
@@ -20,6 +20,7 @@ import type { LintResult, SelectorInfo } from "./types.js";
  * @param cwd - Working directory for resolving paths
  * @param limit - Max number of files with issues to include (default 100)
  * @param gitignore - Whether to respect .gitignore rules (default true)
+ * @param config - Cache configuration (default enabled with DEFAULT_CACHE_DIR)
  * @returns Lint result with per-file diagnostics and summary
  * @throws {JsdocError} NO_FILES_MATCHED if glob selector matches no files
  */
@@ -28,6 +29,7 @@ export declare function lint(
 	cwd: string,
 	limit?: number,
 	gitignore?: boolean,
+	config?: CacheConfig,
 ): Promise<LintResult>;
 /**
  * Lint an explicit list of file paths for comprehensive JSDoc quality.
@@ -38,10 +40,12 @@ export declare function lint(
  * @param filePaths - List of absolute file paths to lint
  * @param cwd - Working directory for computing relative paths
  * @param limit - Max number of files with issues to include (default 100)
+ * @param config - Cache configuration (default enabled with DEFAULT_CACHE_DIR)
  * @returns Lint result with per-file diagnostics and summary
  */
 export declare function lintFiles(
 	filePaths: string[],
 	cwd: string,
 	limit?: number,
+	config?: CacheConfig,
 ): Promise<LintResult>;

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. The `@summary` and description describe the module, not individual files.\n\n- **`@summary`**: What the module does as a unit\n- **Description**: The module\'s capabilities and concerns \u2014 describe concepts, not child filenames\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- Listing child filenames in the description\n- `@summary Exports for the auth module` \u2014 describes the mechanism, not the purpose\n- `@summary Index file` \u2014 no information about what the module does\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';
 /** Explanation text for each lint rule, used by --explain-rule */
 export declare const RULE_EXPLANATIONS: Record<string, string>;

package/types/types.d.ts

@@ -104,6 +104,7 @@ export interface LintFileResult {
 /** Overall lint result with summary statistics */
 export interface LintResult {
 	files: LintFileResult[];
+	missingBarrels?: string[];
 	summary: {
 		totalFiles: number;
 		filesWithIssues: number;
@@ -111,3 +112,12 @@ export interface LintResult {
 		truncated?: boolean;
 	};
 }
+/** Configuration for the disk cache layer */
+export interface CacheConfig {
+	enabled: boolean;
+	directory: string;
+}
+/** Operation modes that produce cacheable results */
+export type CacheOperationMode = "drilldown" | "validate" | "lint";
+/** Default cache directory under os.tmpdir() */
+export declare const DEFAULT_CACHE_DIR: string;

package/types/validate.d.ts

@@ -1,10 +1,12 @@
-import type { SelectorInfo, ValidationResult } from "./types.js";
+import type { CacheConfig, SelectorInfo, ValidationResult } from "./types.js";
 /**
  * Validate files matching a selector pattern.
  *
  * @param selector - Selector information (glob or path)
  * @param cwd - Working directory for resolving paths
  * @param limit - Max number of invalid file paths to include (default 100)
+ * @param gitignore - Whether to respect .gitignore (default true)
+ * @param config - Cache configuration (default: enabled with system temp dir)
  * @returns Grouped validation results
  * @throws {JsdocError} NO_FILES_MATCHED if glob selector matches no files
  * @throws {JsdocError} FILE_NOT_FOUND if path selector targets nonexistent file
@@ -14,6 +16,7 @@ export declare function validate(
 	cwd: string,
 	limit?: number,
 	gitignore?: boolean,
+	config?: CacheConfig,
 ): Promise<ValidationResult>;
 /**
  * Validate an explicit list of file paths.
@@ -23,10 +26,12 @@ export declare function validate(
  * @param filePaths - List of file paths to validate
  * @param cwd - Working directory for resolving relative paths
  * @param limit - Max number of invalid file paths to include (default 100)
+ * @param config - Cache configuration (default: enabled with system temp dir)
  * @returns Grouped validation results
  */
 export declare function validateFiles(
 	filePaths: string[],
 	cwd: string,
 	limit?: number,
+	config?: CacheConfig,
 ): Promise<ValidationResult>;