jsdoczoom 0.3.0 → 0.4.5

package/dist/barrel.js

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync } from "node:fs";
-import { basename, dirname, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
 /**
  * Barrel detection and child discovery for index.ts/index.tsx files.
  * A barrel is strictly `index.ts` or `index.tsx`; other index variants
@@ -83,3 +83,28 @@ function findChildBarrel(subdirPath) {
 	}
 	return null;
 }
+/** Minimum number of .ts/.tsx files in a directory to require a barrel. */
+export const BARREL_THRESHOLD = 3;
+/**
+ * Find directories with more than BARREL_THRESHOLD .ts/.tsx files
+ * that lack a barrel file (index.ts or index.tsx).
+ */
+export function findMissingBarrels(filePaths, cwd) {
+	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();
+}

package/dist/cache.js

@@ -0,0 +1,97 @@
+/**
+ * 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 { createHash } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Compute a SHA-256 content hash for the given string.
+ *
+ * @param content - The content to hash
+ * @returns Hex-encoded SHA-256 digest
+ */
+export function computeContentHash(content) {
+	return createHash("sha256").update(content).digest("hex");
+}
+/**
+ * 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 async function ensureCacheDir(config, mode) {
+	try {
+		await mkdir(join(config.directory, mode), { recursive: true });
+	} catch {
+		// Silently swallow - subsequent reads will miss, writes will fail silently
+	}
+}
+/**
+ * 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 async function readCacheEntry(config, mode, hash) {
+	try {
+		const filePath = join(config.directory, mode, `${hash}.json`);
+		const content = await readFile(filePath, "utf-8");
+		return JSON.parse(content);
+	} catch {
+		return 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 async function writeCacheEntry(config, mode, hash, data) {
+	try {
+		const filePath = join(config.directory, mode, `${hash}.json`);
+		const tmpPath = `${filePath}.tmp`;
+		await writeFile(tmpPath, JSON.stringify(data), "utf-8");
+		await rename(tmpPath, filePath);
+	} catch {
+		// Silently swallow - cache write failures should never affect correctness
+	}
+}
+/**
+ * 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 async function processWithCache(config, mode, content, compute) {
+	if (!config.enabled) {
+		return await compute();
+	}
+	const hash = computeContentHash(content);
+	await ensureCacheDir(config, mode);
+	const cached = await readCacheEntry(config, mode, hash);
+	if (cached !== null) {
+		return cached;
+	}
+	const result = await compute();
+	await writeCacheEntry(config, mode, hash, result);
+	return result;
+}

package/dist/cli.js

@@ -1,18 +1,20 @@
 #!/usr/bin/env node
-import { resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { drilldown, drilldownFiles } from "./drilldown.js";
 import { JsdocError } from "./errors.js";
-import { lint } from "./lint.js";
+import { lint, lintFiles } from "./lint.js";
 import { parseSelector } from "./selector.js";
 import { RULE_EXPLANATIONS, SKILL_TEXT } from "./skill-text.js";
-import { VALIDATION_STATUS_PRIORITY } from "./types.js";
-import { validate } from "./validate.js";
+import { DEFAULT_CACHE_DIR, VALIDATION_STATUS_PRIORITY } from "./types.js";
+import { validate, validateFiles } from "./validate.js";
 
 /**
- * Parses argv flags (--help, --validate, --lint, --skill, --pretty, --limit,
- * --no-gitignore), dispatches to drilldown, validation, or lint mode, and
- * handles stdin piping. Errors are written to stderr as JSON; validation and
- * lint failures use exit code 2 while other errors use exit code 1.
+ * Parses argv flags (--help, --version, --check, --lint, --skill, --pretty,
+ * --limit, --no-gitignore), dispatches to drilldown, validation, or lint mode,
+ * and handles stdin piping. Errors are written to stderr as JSON; validation
+ * and lint failures use exit code 2 while other errors use exit code 1.
  *
  * @summary CLI entry point -- argument parsing, mode dispatch, and exit code handling
  */
@@ -24,12 +26,15 @@ Each file has four detail levels (1-indexed): @1 summary, @2 description,
 
 Options:
   -h, --help       Show this help text
-  -v, --validate   Run validation mode
+  -v, --version    Show version number
+  -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
   --limit N        Max results shown (default 500)
   --no-gitignore   Include files ignored by .gitignore
+  --disable-cache    Skip all cache operations
+  --cache-directory  Override cache directory (default: system temp)
   --explain-rule R  Explain a lint rule with examples (e.g. jsdoc/informative-docs)
 
 Selector:
@@ -43,18 +48,20 @@ Stdin:
   Pipe file paths one per line:
     find . -name "*.ts" | jsdoczoom
     find . -name "*.ts" | jsdoczoom @2
-    find . -name "*.ts" | jsdoczoom -v
+    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.
 
 Barrel gating (glob mode):
-  index.ts files with a @summary gate sibling files at depths 1-2.
-  At depth 3 the barrel disappears and its children appear at depth 1.
+  A barrel's @summary and description reflect the cumulative functionality
+  of its directory's children, not the barrel file itself. Barrels with a
+  @summary gate sibling files at depths 1-2. At depth 3 the barrel
+  disappears and its children appear at depth 1.
 
 Modes:
-  -v  Validate file-level structure (has JSDoc block, @summary, description)
+  -c  Validate file-level structure (has JSDoc block, @summary, description)
   -l  Lint comprehensive JSDoc quality (file-level + function-level tags)
 
 Exit codes:
@@ -73,56 +80,95 @@ Workflow:
   { "items": [{ "id": "src/utils@3", "text": "..." }] }
   # "id" instead of "next_id" means terminal depth — stop here
 `;
+/**
+ * Parse a flag that requires a value argument.
+ * @returns Updated index after consuming the value
+ */
+function parseValueFlag(args, index) {
+	return { value: args[index + 1], nextIndex: index + 1 };
+}
 /**
  * Parse CLI arguments into flags and positional args.
  */
 function parseArgs(args) {
-	let help = false;
-	let validateMode = false;
-	let lintMode = false;
-	let skillMode = false;
-	let pretty = false;
-	let limit = 500;
-	let gitignore = true;
-	let explainRule;
-	let selectorArg;
+	const parsed = {
+		help: false,
+		version: false,
+		checkMode: false,
+		lintMode: false,
+		skillMode: false,
+		pretty: false,
+		limit: 500,
+		gitignore: true,
+		disableCache: false,
+		cacheDirectory: undefined,
+		explainRule: undefined,
+		selectorArg: undefined,
+	};
 	for (let i = 0; i < args.length; i++) {
 		const arg = args[i];
+		// Boolean flags
 		if (arg === "-h" || arg === "--help") {
-			help = true;
-		} else if (arg === "-v" || arg === "--validate") {
-			validateMode = true;
-		} else if (arg === "-l" || arg === "--lint") {
-			lintMode = true;
-		} else if (arg === "-s" || arg === "--skill") {
-			skillMode = true;
-		} else if (arg === "--pretty") {
-			pretty = true;
-		} else if (arg === "--limit") {
-			const next = args[++i];
-			limit = Number(next);
-		} else if (arg === "--no-gitignore") {
-			gitignore = false;
-		} else if (arg === "--explain-rule") {
-			const next = args[++i];
-			explainRule = next;
-		} else if (arg.startsWith("-")) {
+			parsed.help = true;
+			continue;
+		}
+		if (arg === "-v" || arg === "--version") {
+			parsed.version = true;
+			continue;
+		}
+		if (arg === "-c" || arg === "--check") {
+			parsed.checkMode = true;
+			continue;
+		}
+		if (arg === "-l" || arg === "--lint") {
+			parsed.lintMode = true;
+			continue;
+		}
+		if (arg === "-s" || arg === "--skill") {
+			parsed.skillMode = true;
+			continue;
+		}
+		if (arg === "--pretty") {
+			parsed.pretty = true;
+			continue;
+		}
+		if (arg === "--no-gitignore") {
+			parsed.gitignore = false;
+			continue;
+		}
+		if (arg === "--disable-cache") {
+			parsed.disableCache = true;
+			continue;
+		}
+		// Value flags
+		if (arg === "--limit") {
+			const { value, nextIndex } = parseValueFlag(args, i);
+			parsed.limit = Number(value);
+			i = nextIndex;
+			continue;
+		}
+		if (arg === "--cache-directory") {
+			const { value, nextIndex } = parseValueFlag(args, i);
+			parsed.cacheDirectory = value;
+			i = nextIndex;
+			continue;
+		}
+		if (arg === "--explain-rule") {
+			const { value, nextIndex } = parseValueFlag(args, i);
+			parsed.explainRule = value;
+			i = nextIndex;
+			continue;
+		}
+		// Unknown flag or positional arg
+		if (arg.startsWith("-")) {
 			throw new JsdocError("INVALID_SELECTOR", `Unrecognized option: ${arg}`);
-		} else if (selectorArg === undefined) {
-			selectorArg = arg;
+		}
+		// Positional selector arg
+		if (parsed.selectorArg === undefined) {
+			parsed.selectorArg = arg;
 		}
 	}
-	return {
-		help,
-		validateMode,
-		lintMode,
-		skillMode,
-		pretty,
-		limit,
-		gitignore,
-		explainRule,
-		selectorArg,
-	};
+	return parsed;
 }
 /**
  * Resolve stdin file paths to absolute paths.
@@ -148,25 +194,30 @@ function extractDepthFromArg(selectorArg) {
 async function processStdin(
 	stdin,
 	selectorArg,
-	validateMode,
+	checkMode,
 	lintMode,
 	pretty,
 	limit,
 	cwd,
+	cacheConfig,
 ) {
 	const stdinPaths = parseStdinPaths(stdin, cwd);
 	const depth =
 		selectorArg !== undefined ? extractDepthFromArg(selectorArg) : undefined;
 	if (lintMode) {
-		const { lintFiles } = await import("./lint.js");
-		const result = await lintFiles(stdinPaths, cwd, limit);
+		const result = await lintFiles(stdinPaths, cwd, limit, cacheConfig);
 		writeLintResult(result, pretty);
-	} else if (validateMode) {
-		const { validateFiles } = await import("./validate.js");
-		const result = await validateFiles(stdinPaths, cwd, limit);
+	} else if (checkMode) {
+		const result = await validateFiles(stdinPaths, cwd, limit, cacheConfig);
 		writeValidationResult(result, pretty);
 	} else {
-		const result = drilldownFiles(stdinPaths, depth, cwd, limit);
+		const result = await drilldownFiles(
+			stdinPaths,
+			depth,
+			cwd,
+			limit,
+			cacheConfig,
+		);
 		writeResult(result, pretty);
 	}
 }
@@ -175,24 +226,31 @@ async function processStdin(
  */
 async function processSelector(
 	selectorArg,
-	validateMode,
+	checkMode,
 	lintMode,
 	pretty,
 	limit,
 	gitignore,
 	cwd,
+	cacheConfig,
 ) {
 	const selector = selectorArg
 		? parseSelector(selectorArg)
 		: { type: "glob", pattern: "**/*.{ts,tsx}", depth: undefined };
 	if (lintMode) {
-		const result = await lint(selector, cwd, limit, gitignore);
+		const result = await lint(selector, cwd, limit, gitignore, cacheConfig);
 		writeLintResult(result, pretty);
-	} else if (validateMode) {
-		const result = await validate(selector, cwd, limit, gitignore);
+	} else if (checkMode) {
+		const result = await validate(selector, cwd, limit, gitignore, cacheConfig);
 		writeValidationResult(result, pretty);
 	} else {
-		const result = drilldown(selector, cwd, gitignore, limit);
+		const result = await drilldown(
+			selector,
+			cwd,
+			gitignore,
+			limit,
+			cacheConfig,
+		);
 		writeResult(result, pretty);
 	}
 }
@@ -201,81 +259,114 @@ async function processSelector(
  */
 function writeError(error) {
 	if (error instanceof JsdocError) {
-		process.stderr.write(`${JSON.stringify(error.toJSON())}\n`);
+		void process.stderr.write(`${JSON.stringify(error.toJSON())}\n`);
 		process.exitCode = 1;
 		return;
 	}
 	const message = error instanceof Error ? error.message : String(error);
-	process.stderr.write(
+	void process.stderr.write(
 		`${JSON.stringify({ error: { code: "INTERNAL_ERROR", message } })}\n`,
 	);
 	process.exitCode = 1;
 }
+/**
+ * Handle --help flag by printing help text.
+ */
+function handleHelp() {
+	void process.stdout.write(HELP_TEXT);
+}
+/**
+ * Handle --version flag by reading and printing version from package.json.
+ */
+function handleVersion() {
+	const pkgPath = resolve(
+		dirname(fileURLToPath(import.meta.url)),
+		"..",
+		"package.json",
+	);
+	const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+	void process.stdout.write(`${pkg.version}\n`);
+}
+/**
+ * Handle --skill flag by printing JSDoc writing guidelines.
+ */
+function handleSkill() {
+	void process.stdout.write(SKILL_TEXT);
+}
+/**
+ * Handle --explain-rule flag by printing rule explanation.
+ */
+function handleExplainRule(ruleName) {
+	const explanation = RULE_EXPLANATIONS[ruleName];
+	if (explanation) {
+		void process.stdout.write(explanation);
+		return;
+	}
+	const available = Object.keys(RULE_EXPLANATIONS).join(", ");
+	writeError(
+		new JsdocError(
+			"INVALID_SELECTOR",
+			`Unknown rule: ${ruleName}. Available rules: ${available}`,
+		),
+	);
+}
 /**
  * Main CLI entry point. Exported for testability.
  */
 export async function main(args, stdin) {
 	try {
-		const {
-			help,
-			validateMode,
-			lintMode,
-			skillMode,
-			pretty,
-			limit,
-			gitignore,
-			explainRule,
-			selectorArg,
-		} = parseArgs(args);
-		if (help) {
-			process.stdout.write(HELP_TEXT);
+		const parsed = parseArgs(args);
+		// Handle early-exit flags
+		if (parsed.help) {
+			handleHelp();
+			return;
+		}
+		if (parsed.version) {
+			handleVersion();
 			return;
 		}
-		if (skillMode) {
-			process.stdout.write(SKILL_TEXT);
+		if (parsed.skillMode) {
+			handleSkill();
 			return;
 		}
-		if (explainRule !== undefined) {
-			const explanation = RULE_EXPLANATIONS[explainRule];
-			if (explanation) {
-				process.stdout.write(explanation);
-			} else {
-				const available = Object.keys(RULE_EXPLANATIONS).join(", ");
-				writeError(
-					new JsdocError(
-						"INVALID_SELECTOR",
-						`Unknown rule: ${explainRule}. Available rules: ${available}`,
-					),
-				);
-			}
+		if (parsed.explainRule !== undefined) {
+			handleExplainRule(parsed.explainRule);
 			return;
 		}
-		if (validateMode && lintMode) {
+		// Validate mode combinations
+		if (parsed.checkMode && parsed.lintMode) {
 			writeError(
-				new JsdocError("INVALID_SELECTOR", "Cannot use -v and -l together"),
+				new JsdocError("INVALID_SELECTOR", "Cannot use -c and -l together"),
 			);
 			return;
 		}
+		// Build cache config and process files
+		const cacheConfig = {
+			enabled: !parsed.disableCache,
+			directory: parsed.cacheDirectory ?? DEFAULT_CACHE_DIR,
+		};
 		const cwd = process.cwd();
 		if (stdin !== undefined) {
 			await processStdin(
 				stdin,
-				selectorArg,
-				validateMode,
-				lintMode,
-				pretty,
-				limit,
+				parsed.selectorArg,
+				parsed.checkMode,
+				parsed.lintMode,
+				parsed.pretty,
+				parsed.limit,
 				cwd,
+				cacheConfig,
 			);
 		} else {
 			await processSelector(
-				selectorArg,
-				validateMode,
-				lintMode,
-				pretty,
-				limit,
-				gitignore,
+				parsed.selectorArg,
+				parsed.checkMode,
+				parsed.lintMode,
+				parsed.pretty,
+				parsed.limit,
+				parsed.gitignore,
 				cwd,
+				cacheConfig,
 			);
 		}
 	} catch (error) {
@@ -289,7 +380,7 @@ function writeResult(result, pretty) {
 	const json = pretty
 		? JSON.stringify(result, null, 2)
 		: JSON.stringify(result);
-	process.stdout.write(`${json}\n`);
+	void process.stdout.write(`${json}\n`);
 }
 /**
  * Count invalid files across all validation groups.
@@ -335,7 +426,7 @@ function writeLintResult(result, pretty) {
 		process.exitCode = 2;
 		// Warn if output was truncated
 		if (result.summary.filesWithIssues > result.files.length) {
-			process.stderr.write(
+			void process.stderr.write(
 				`Warning: output truncated to ${result.files.length} of ${result.summary.filesWithIssues} files with issues. Use --limit to see more.\n`,
 			);
 		}