jsdoczoom 0.1.0 → 0.2.1

package/dist/barrel.js

@@ -19,8 +19,8 @@ import { basename, dirname, resolve } from "node:path";
  * @returns true if the file is a barrel (index.ts or index.tsx)
  */
 export function isBarrel(filePath) {
-    const name = basename(filePath);
-    return name === "index.ts" || name === "index.tsx";
+	const name = basename(filePath);
+	return name === "index.ts" || name === "index.tsx";
 }
 /**
  * Discover the children of a barrel file.
@@ -35,36 +35,37 @@ export function isBarrel(filePath) {
  * @returns Sorted array of absolute paths to child files
  */
 export function getBarrelChildren(barrelPath, _cwd) {
-    const dir = dirname(barrelPath);
-    const barrelName = basename(barrelPath);
-    let entries;
-    try {
-        entries = readdirSync(dir, { withFileTypes: true })
-            .map((e) => ({ name: e.name, isDirectory: e.isDirectory() }))
-            .flatMap((entry) => {
-            if (entry.isDirectory) {
-                // Check for child barrel in this subdirectory
-                const childBarrel = findChildBarrel(resolve(dir, entry.name));
-                return childBarrel ? [childBarrel] : [];
-            }
-            // Sibling file: must be .ts/.tsx, not .d.ts, not the barrel itself
-            if (isTsFile(entry.name) && entry.name !== barrelName) {
-                return [resolve(dir, entry.name)];
-            }
-            return [];
-        });
-    }
-    catch {
-        // Directory unreadable (permissions, deleted, etc.) — no children discoverable
-        return [];
-    }
-    return entries.sort();
+	const dir = dirname(barrelPath);
+	const barrelName = basename(barrelPath);
+	let entries;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true })
+			.map((e) => ({ name: e.name, isDirectory: e.isDirectory() }))
+			.flatMap((entry) => {
+				if (entry.isDirectory) {
+					// Check for child barrel in this subdirectory
+					const childBarrel = findChildBarrel(resolve(dir, entry.name));
+					return childBarrel ? [childBarrel] : [];
+				}
+				// Sibling file: must be .ts/.tsx, not .d.ts, not the barrel itself
+				if (isTsFile(entry.name) && entry.name !== barrelName) {
+					return [resolve(dir, entry.name)];
+				}
+				return [];
+			});
+	} catch {
+		// Directory unreadable (permissions, deleted, etc.) — no children discoverable
+		return [];
+	}
+	return entries.sort();
 }
 /**
  * Check if a filename is a .ts or .tsx file (excluding .d.ts).
  */
 function isTsFile(name) {
-    return ((name.endsWith(".ts") || name.endsWith(".tsx")) && !name.endsWith(".d.ts"));
+	return (
+		(name.endsWith(".ts") || name.endsWith(".tsx")) && !name.endsWith(".d.ts")
+	);
 }
 /**
  * Find the barrel file in a subdirectory.
@@ -72,13 +73,13 @@ function isTsFile(name) {
  * Returns the absolute path to the barrel, or null if none found.
  */
 function findChildBarrel(subdirPath) {
-    const tsPath = resolve(subdirPath, "index.ts");
-    if (existsSync(tsPath)) {
-        return tsPath;
-    }
-    const tsxPath = resolve(subdirPath, "index.tsx");
-    if (existsSync(tsxPath)) {
-        return tsxPath;
-    }
-    return null;
+	const tsPath = resolve(subdirPath, "index.ts");
+	if (existsSync(tsPath)) {
+		return tsPath;
+	}
+	const tsxPath = resolve(subdirPath, "index.tsx");
+	if (existsSync(tsxPath)) {
+		return tsxPath;
+	}
+	return null;
 }

package/dist/cli.js

@@ -4,9 +4,10 @@ import { drilldown, drilldownFiles } from "./drilldown.js";
 import { JsdocError } from "./errors.js";
 import { lint } from "./lint.js";
 import { parseSelector } from "./selector.js";
-import { SKILL_TEXT } from "./skill-text.js";
+import { RULE_EXPLANATIONS, SKILL_TEXT } from "./skill-text.js";
 import { VALIDATION_STATUS_PRIORITY } from "./types.js";
 import { validate } from "./validate.js";
+
 /**
  * Parses argv flags (--help, --validate, --lint, --skill, --pretty, --limit,
  * --no-gitignore), dispatches to drilldown, validation, or lint mode, and
@@ -27,8 +28,9 @@ Options:
   -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 100)
+  --limit N        Max results shown (default 500)
   --no-gitignore   Include files ignored by .gitignore
+  --explain-rule R  Explain a lint rule with examples (e.g. jsdoc/informative-docs)
 
 Selector:
   A glob pattern or file path, optionally with @depth suffix (1-4).
@@ -51,6 +53,15 @@ 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.
 
+Modes:
+  -v  Validate file-level structure (has JSDoc block, @summary, description)
+  -l  Lint comprehensive JSDoc quality (file-level + function-level tags)
+
+Exit codes:
+  0  Success (all files pass)
+  1  Runtime error (invalid arguments, missing files)
+  2  Validation or lint failures found
+
 Workflow:
   $ jsdoczoom src/**/*.ts
   { "items": [{ "next_id": "src/utils@2", "text": "..." }, ...] }
@@ -66,222 +77,296 @@ Workflow:
  * 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 = 100;
-    let gitignore = true;
-    let selectorArg;
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        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.startsWith("-")) {
-            throw new JsdocError("INVALID_SELECTOR", `Unrecognized option: ${arg}`);
-        }
-        else if (selectorArg === undefined) {
-            selectorArg = arg;
-        }
-    }
-    return {
-        help,
-        validateMode,
-        lintMode,
-        skillMode,
-        pretty,
-        limit,
-        gitignore,
-        selectorArg,
-    };
+	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;
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		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("-")) {
+			throw new JsdocError("INVALID_SELECTOR", `Unrecognized option: ${arg}`);
+		} else if (selectorArg === undefined) {
+			selectorArg = arg;
+		}
+	}
+	return {
+		help,
+		validateMode,
+		lintMode,
+		skillMode,
+		pretty,
+		limit,
+		gitignore,
+		explainRule,
+		selectorArg,
+	};
 }
 /**
  * Resolve stdin file paths to absolute paths.
  */
 function parseStdinPaths(stdin, cwd) {
-    return stdin
-        .split("\n")
-        .map((line) => line.trim())
-        .filter((line) => line.length > 0)
-        .map((line) => resolve(cwd, line));
+	return stdin
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => line.length > 0)
+		.map((line) => resolve(cwd, line));
 }
 /**
  * Extract depth from a selector argument string.
  * Returns undefined if no @depth suffix is present.
  */
 function extractDepthFromArg(selectorArg) {
-    const parsed = parseSelector(selectorArg);
-    return parsed.depth;
+	const parsed = parseSelector(selectorArg);
+	return parsed.depth;
 }
 /**
  * Process stdin mode: file paths piped in.
  */
-async function processStdin(stdin, selectorArg, validateMode, lintMode, pretty, limit, cwd) {
-    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);
-        writeLintResult(result, pretty);
-    }
-    else if (validateMode) {
-        const { validateFiles } = await import("./validate.js");
-        const result = await validateFiles(stdinPaths, cwd, limit);
-        writeValidationResult(result, pretty);
-    }
-    else {
-        const result = drilldownFiles(stdinPaths, depth, cwd, limit);
-        writeResult(result, pretty);
-    }
+async function processStdin(
+	stdin,
+	selectorArg,
+	validateMode,
+	lintMode,
+	pretty,
+	limit,
+	cwd,
+) {
+	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);
+		writeLintResult(result, pretty);
+	} else if (validateMode) {
+		const { validateFiles } = await import("./validate.js");
+		const result = await validateFiles(stdinPaths, cwd, limit);
+		writeValidationResult(result, pretty);
+	} else {
+		const result = drilldownFiles(stdinPaths, depth, cwd, limit);
+		writeResult(result, pretty);
+	}
 }
 /**
  * Process selector mode: glob or path argument.
  */
-async function processSelector(selectorArg, validateMode, lintMode, pretty, limit, gitignore, cwd) {
-    const selector = selectorArg
-        ? parseSelector(selectorArg)
-        : { type: "glob", pattern: "**/*.{ts,tsx}", depth: undefined };
-    if (lintMode) {
-        const result = await lint(selector, cwd, limit, gitignore);
-        writeLintResult(result, pretty);
-    }
-    else if (validateMode) {
-        const result = await validate(selector, cwd, limit, gitignore);
-        writeValidationResult(result, pretty);
-    }
-    else {
-        const result = drilldown(selector, cwd, gitignore, limit);
-        writeResult(result, pretty);
-    }
+async function processSelector(
+	selectorArg,
+	validateMode,
+	lintMode,
+	pretty,
+	limit,
+	gitignore,
+	cwd,
+) {
+	const selector = selectorArg
+		? parseSelector(selectorArg)
+		: { type: "glob", pattern: "**/*.{ts,tsx}", depth: undefined };
+	if (lintMode) {
+		const result = await lint(selector, cwd, limit, gitignore);
+		writeLintResult(result, pretty);
+	} else if (validateMode) {
+		const result = await validate(selector, cwd, limit, gitignore);
+		writeValidationResult(result, pretty);
+	} else {
+		const result = drilldown(selector, cwd, gitignore, limit);
+		writeResult(result, pretty);
+	}
 }
 /**
  * Write an error to stderr as JSON and set exit code.
  */
 function writeError(error) {
-    if (error instanceof JsdocError) {
-        process.stderr.write(`${JSON.stringify(error.toJSON())}\n`);
-        process.exitCode = 1;
-        return;
-    }
-    const message = error instanceof Error ? error.message : String(error);
-    process.stderr.write(`${JSON.stringify({ error: { code: "INTERNAL_ERROR", message } })}\n`);
-    process.exitCode = 1;
+	if (error instanceof JsdocError) {
+		process.stderr.write(`${JSON.stringify(error.toJSON())}\n`);
+		process.exitCode = 1;
+		return;
+	}
+	const message = error instanceof Error ? error.message : String(error);
+	process.stderr.write(
+		`${JSON.stringify({ error: { code: "INTERNAL_ERROR", message } })}\n`,
+	);
+	process.exitCode = 1;
 }
 /**
  * Main CLI entry point. Exported for testability.
  */
 export async function main(args, stdin) {
-    try {
-        const { help, validateMode, lintMode, skillMode, pretty, limit, gitignore, selectorArg, } = parseArgs(args);
-        if (help) {
-            process.stdout.write(HELP_TEXT);
-            return;
-        }
-        if (skillMode) {
-            process.stdout.write(SKILL_TEXT);
-            return;
-        }
-        if (validateMode && lintMode) {
-            writeError(new JsdocError("INVALID_SELECTOR", "Cannot use -v and -l together"));
-            return;
-        }
-        const cwd = process.cwd();
-        if (stdin !== undefined) {
-            await processStdin(stdin, selectorArg, validateMode, lintMode, pretty, limit, cwd);
-        }
-        else {
-            await processSelector(selectorArg, validateMode, lintMode, pretty, limit, gitignore, cwd);
-        }
-    }
-    catch (error) {
-        writeError(error);
-    }
+	try {
+		const {
+			help,
+			validateMode,
+			lintMode,
+			skillMode,
+			pretty,
+			limit,
+			gitignore,
+			explainRule,
+			selectorArg,
+		} = parseArgs(args);
+		if (help) {
+			process.stdout.write(HELP_TEXT);
+			return;
+		}
+		if (skillMode) {
+			process.stdout.write(SKILL_TEXT);
+			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}`,
+					),
+				);
+			}
+			return;
+		}
+		if (validateMode && lintMode) {
+			writeError(
+				new JsdocError("INVALID_SELECTOR", "Cannot use -v and -l together"),
+			);
+			return;
+		}
+		const cwd = process.cwd();
+		if (stdin !== undefined) {
+			await processStdin(
+				stdin,
+				selectorArg,
+				validateMode,
+				lintMode,
+				pretty,
+				limit,
+				cwd,
+			);
+		} else {
+			await processSelector(
+				selectorArg,
+				validateMode,
+				lintMode,
+				pretty,
+				limit,
+				gitignore,
+				cwd,
+			);
+		}
+	} catch (error) {
+		writeError(error);
+	}
 }
 /**
  * Write a result to stdout as JSON.
  */
 function writeResult(result, pretty) {
-    const json = pretty
-        ? JSON.stringify(result, null, 2)
-        : JSON.stringify(result);
-    process.stdout.write(`${json}\n`);
+	const json = pretty
+		? JSON.stringify(result, null, 2)
+		: JSON.stringify(result);
+	process.stdout.write(`${json}\n`);
 }
 /**
  * Count invalid files across all validation groups.
  */
 function countInvalid(result) {
-    return VALIDATION_STATUS_PRIORITY.reduce((sum, status) => sum + (result[status]?.files.length ?? 0), 0);
+	return VALIDATION_STATUS_PRIORITY.reduce(
+		(sum, status) => sum + (result[status]?.files.length ?? 0),
+		0,
+	);
 }
 /**
  * Write validation result to stdout and set exit code.
  * Adds success/message fields to the output.
  */
 function writeValidationResult(result, pretty) {
-    const invalidCount = countInvalid(result);
-    if (invalidCount === 0) {
-        writeResult({ success: true, message: "All files passed validation" }, pretty);
-    }
-    else {
-        writeResult({ ...result, success: false }, pretty);
-        process.stderr.write(`${JSON.stringify(new JsdocError("VALIDATION_FAILED", `${invalidCount} file(s) failed validation`).toJSON())}\n`);
-        process.exitCode = 2;
-    }
+	const invalidCount = countInvalid(result);
+	if (invalidCount === 0) {
+		writeResult(
+			{ success: true, message: "All files passed validation" },
+			pretty,
+		);
+	} else {
+		writeResult(
+			{
+				...result,
+				success: false,
+				error: {
+					code: "VALIDATION_FAILED",
+					message: `${invalidCount} file(s) failed validation`,
+				},
+			},
+			pretty,
+		);
+		process.exitCode = 2;
+	}
 }
 /**
  * Write lint result to stdout and set exit code 2 if issues found.
  */
 function writeLintResult(result, pretty) {
-    writeResult(result, pretty);
-    if (result.summary.filesWithIssues > 0) {
-        process.exitCode = 2;
-    }
+	writeResult(result, pretty);
+	if (result.summary.filesWithIssues > 0) {
+		process.exitCode = 2;
+		// Warn if output was truncated
+		if (result.summary.filesWithIssues > result.files.length) {
+			process.stderr.write(
+				`Warning: output truncated to ${result.files.length} of ${result.summary.filesWithIssues} files with issues. Use --limit to see more.\n`,
+			);
+		}
+	}
 }
 async function readStdin() {
-    const chunks = [];
-    for await (const chunk of process.stdin) {
-        chunks.push(chunk);
-    }
-    return Buffer.concat(chunks).toString("utf-8");
+	const chunks = [];
+	for await (const chunk of process.stdin) {
+		chunks.push(chunk);
+	}
+	return Buffer.concat(chunks).toString("utf-8");
 }
 // Auto-invoke when run as CLI
 function isDirectRun() {
-    if (!process.argv[1])
-        return false;
-    try {
-        const scriptPath = process.argv[1].replace(/\\/g, "/");
-        return (import.meta.url.endsWith(scriptPath) ||
-            import.meta.url.endsWith("/cli.js"));
-    }
-    catch {
-        // Cannot determine script path — safe to skip auto-invoke
-        return false;
-    }
+	if (!process.argv[1]) return false;
+	try {
+		const scriptPath = process.argv[1].replace(/\\/g, "/");
+		return (
+			import.meta.url.endsWith(scriptPath) ||
+			import.meta.url.endsWith("/cli.js")
+		);
+	} catch {
+		// Cannot determine script path — safe to skip auto-invoke
+		return false;
+	}
 }
 if (isDirectRun()) {
-    // Only read stdin when it's explicitly piped (isTTY === false, not just undefined)
-    const stdinText = process.stdin.isTTY === false ? await readStdin() : undefined;
-    main(process.argv.slice(2), stdinText).catch(() => {
-        // Error already handled in main
-    });
+	// Only read stdin when it's explicitly piped (isTTY === false, not just undefined)
+	const stdinText =
+		process.stdin.isTTY === false ? await readStdin() : undefined;
+	main(process.argv.slice(2), stdinText).catch(() => {
+		// Error already handled in main
+	});
 }