jsdoczoom 0.3.1 → 0.4.10

package/dist/src/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 → src/cli.js}

@@ -4,11 +4,11 @@ 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, --version, --check, --lint, --skill, --pretty,
@@ -33,6 +33,8 @@ Options:
   --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:
@@ -53,8 +55,10 @@ Output:
   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:
   -c  Validate file-level structure (has JSDoc block, @summary, description)
@@ -76,60 +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 version = false;
-	let checkMode = 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 === "--version") {
-			version = true;
-		} else if (arg === "-c" || arg === "--check") {
-			checkMode = 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,
-		version,
-		checkMode,
-		lintMode,
-		skillMode,
-		pretty,
-		limit,
-		gitignore,
-		explainRule,
-		selectorArg,
-	};
+	return parsed;
 }
 /**
  * Resolve stdin file paths to absolute paths.
@@ -160,20 +199,25 @@ async function processStdin(
 	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 (checkMode) {
-		const { validateFiles } = await import("./validate.js");
-		const result = await validateFiles(stdinPaths, cwd, limit);
+		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);
 	}
 }
@@ -188,18 +232,25 @@ async function processSelector(
 	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 (checkMode) {
-		const result = await validate(selector, cwd, limit, gitignore);
+		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);
 	}
 }
@@ -208,92 +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,
-			version,
-			checkMode,
-			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 (version) {
-			const pkgPath = resolve(
-				dirname(fileURLToPath(import.meta.url)),
-				"..",
-				"package.json",
-			);
-			const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-			process.stdout.write(`${pkg.version}\n`);
+		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 (checkMode && lintMode) {
+		// Validate mode combinations
+		if (parsed.checkMode && parsed.lintMode) {
 			writeError(
 				new JsdocError("INVALID_SELECTOR", "Cannot use -c and -l together"),
 			);
 			return;
 		}
+		// Build cache config and process files
+		const cacheConfig = {
+			enabled: !parsed.disableCache,
+			directory: parsed.cacheDirectory ?? DEFAULT_CACHE_DIR,
+		};
 		const cwd = process.cwd();
 		if (stdin !== undefined) {
 			await processStdin(
 				stdin,
-				selectorArg,
-				checkMode,
-				lintMode,
-				pretty,
-				limit,
+				parsed.selectorArg,
+				parsed.checkMode,
+				parsed.lintMode,
+				parsed.pretty,
+				parsed.limit,
 				cwd,
+				cacheConfig,
 			);
 		} else {
 			await processSelector(
-				selectorArg,
-				checkMode,
-				lintMode,
-				pretty,
-				limit,
-				gitignore,
+				parsed.selectorArg,
+				parsed.checkMode,
+				parsed.lintMode,
+				parsed.pretty,
+				parsed.limit,
+				parsed.gitignore,
 				cwd,
+				cacheConfig,
 			);
 		}
 	} catch (error) {
@@ -307,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.
@@ -353,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`,
 			);
 		}