jsdoczoom 0.3.0 → 0.3.1

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/cli.js

@@ -1,5 +1,7 @@
 #!/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";
@@ -9,10 +11,10 @@ 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
- * 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,7 +26,8 @@ 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
@@ -43,7 +46,7 @@ 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
@@ -54,7 +57,7 @@ Barrel gating (glob mode):
   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:
@@ -78,7 +81,8 @@ Workflow:
  */
 function parseArgs(args) {
 	let help = false;
-	let validateMode = false;
+	let version = false;
+	let checkMode = false;
 	let lintMode = false;
 	let skillMode = false;
 	let pretty = false;
@@ -90,8 +94,10 @@ function parseArgs(args) {
 		const arg = args[i];
 		if (arg === "-h" || arg === "--help") {
 			help = true;
-		} else if (arg === "-v" || arg === "--validate") {
-			validateMode = 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") {
@@ -114,7 +120,8 @@ function parseArgs(args) {
 	}
 	return {
 		help,
-		validateMode,
+		version,
+		checkMode,
 		lintMode,
 		skillMode,
 		pretty,
@@ -148,7 +155,7 @@ function extractDepthFromArg(selectorArg) {
 async function processStdin(
 	stdin,
 	selectorArg,
-	validateMode,
+	checkMode,
 	lintMode,
 	pretty,
 	limit,
@@ -161,7 +168,7 @@ async function processStdin(
 		const { lintFiles } = await import("./lint.js");
 		const result = await lintFiles(stdinPaths, cwd, limit);
 		writeLintResult(result, pretty);
-	} else if (validateMode) {
+	} else if (checkMode) {
 		const { validateFiles } = await import("./validate.js");
 		const result = await validateFiles(stdinPaths, cwd, limit);
 		writeValidationResult(result, pretty);
@@ -175,7 +182,7 @@ async function processStdin(
  */
 async function processSelector(
 	selectorArg,
-	validateMode,
+	checkMode,
 	lintMode,
 	pretty,
 	limit,
@@ -188,7 +195,7 @@ async function processSelector(
 	if (lintMode) {
 		const result = await lint(selector, cwd, limit, gitignore);
 		writeLintResult(result, pretty);
-	} else if (validateMode) {
+	} else if (checkMode) {
 		const result = await validate(selector, cwd, limit, gitignore);
 		writeValidationResult(result, pretty);
 	} else {
@@ -218,7 +225,8 @@ export async function main(args, stdin) {
 	try {
 		const {
 			help,
-			validateMode,
+			version,
+			checkMode,
 			lintMode,
 			skillMode,
 			pretty,
@@ -231,6 +239,16 @@ export async function main(args, stdin) {
 			process.stdout.write(HELP_TEXT);
 			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`);
+			return;
+		}
 		if (skillMode) {
 			process.stdout.write(SKILL_TEXT);
 			return;
@@ -250,9 +268,9 @@ export async function main(args, stdin) {
 			}
 			return;
 		}
-		if (validateMode && lintMode) {
+		if (checkMode && lintMode) {
 			writeError(
-				new JsdocError("INVALID_SELECTOR", "Cannot use -v and -l together"),
+				new JsdocError("INVALID_SELECTOR", "Cannot use -c and -l together"),
 			);
 			return;
 		}
@@ -261,7 +279,7 @@ export async function main(args, stdin) {
 			await processStdin(
 				stdin,
 				selectorArg,
-				validateMode,
+				checkMode,
 				lintMode,
 				pretty,
 				limit,
@@ -270,7 +288,7 @@ export async function main(args, stdin) {
 		} else {
 			await processSelector(
 				selectorArg,
-				validateMode,
+				checkMode,
 				lintMode,
 				pretty,
 				limit,

package/dist/lint.js

@@ -10,6 +10,7 @@
  */
 import { readFileSync } from "node:fs";
 import { relative } from "node:path";
+import { findMissingBarrels } from "./barrel.js";
 import { JsdocError } from "./errors.js";
 import { createLintLinter, lintFileForLint } from "./eslint-engine.js";
 import { discoverFiles } from "./file-discovery.js";
@@ -36,9 +37,10 @@ async function lintSingleFile(eslint, filePath, cwd) {
  * @param fileResults - All per-file lint results
  * @param totalFiles - Total number of files that were linted
  * @param limit - Maximum number of files with issues to include
+ * @param missingBarrels - Directories missing barrel files
  * @returns Aggregated lint result with summary statistics
  */
-function buildLintResult(fileResults, totalFiles, limit) {
+function buildLintResult(fileResults, totalFiles, limit, missingBarrels) {
 	const filesWithIssues = fileResults.filter((f) => f.diagnostics.length > 0);
 	const totalDiagnostics = filesWithIssues.reduce(
 		(sum, f) => sum + f.diagnostics.length,
@@ -48,6 +50,7 @@ function buildLintResult(fileResults, totalFiles, limit) {
 	const truncated = filesWithIssues.length > limit;
 	return {
 		files: cappedFiles,
+		...(missingBarrels.length > 0 ? { missingBarrels } : {}),
 		summary: {
 			totalFiles,
 			filesWithIssues: filesWithIssues.length,
@@ -83,7 +86,8 @@ export async function lint(selector, cwd, limit = 100, gitignore = true) {
 	const fileResults = await Promise.all(
 		tsFiles.map((f) => lintSingleFile(eslint, f, cwd)),
 	);
-	return buildLintResult(fileResults, tsFiles.length, limit);
+	const missingBarrels = findMissingBarrels(tsFiles, cwd);
+	return buildLintResult(fileResults, tsFiles.length, limit, missingBarrels);
 }
 /**
  * Lint an explicit list of file paths for comprehensive JSDoc quality.
@@ -104,5 +108,6 @@ export async function lintFiles(filePaths, cwd, limit = 100) {
 	const fileResults = await Promise.all(
 		tsFiles.map((f) => lintSingleFile(eslint, f, cwd)),
 	);
-	return buildLintResult(fileResults, tsFiles.length, limit);
+	const missingBarrels = findMissingBarrels(tsFiles, cwd);
+	return buildLintResult(fileResults, tsFiles.length, limit, missingBarrels);
 }

package/dist/type-declarations.js

@@ -48,8 +48,9 @@ export function resolveCompilerOptions(filePath) {
 	);
 	// Use cache key based on tsconfig path (or "__default__" if none found)
 	const cacheKey = tsconfigPath ?? "__default__";
-	if (compilerOptionsCache.has(cacheKey)) {
-		return compilerOptionsCache.get(cacheKey);
+	const cached = compilerOptionsCache.get(cacheKey);
+	if (cached) {
+		return cached;
 	}
 	let result;
 	if (!tsconfigPath) {
@@ -109,8 +110,9 @@ export function resolveCompilerOptions(filePath) {
  */
 export function getLanguageService(tsconfigPath, compilerOptions) {
 	const cacheKey = tsconfigPath ?? "__default__";
-	if (serviceCache.has(cacheKey)) {
-		return serviceCache.get(cacheKey);
+	const cachedService = serviceCache.get(cacheKey);
+	if (cachedService) {
+		return cachedService;
 	}
 	// Create a mutable set to track files for this service
 	const files = new Set();

package/dist/validate.js

@@ -1,6 +1,6 @@
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
-import { isBarrel } from "./barrel.js";
+import { readFileSync } from "node:fs";
+import { relative } from "node:path";
+import { findMissingBarrels } from "./barrel.js";
 import { JsdocError } from "./errors.js";
 import {
 	createValidationLinter,
@@ -29,31 +29,6 @@ async function classifyFile(eslint, filePath, cwd) {
 	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();
-}
 /**
  * Group file statuses into a ValidationResult, applying a limit
  * to the total number of invalid file paths shown.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "jsdoczoom",
-	"version": "0.3.0",
+	"version": "0.3.1",
 	"description": "CLI tool for extracting JSDoc summaries at configurable depths",
 	"type": "module",
 	"sideEffects": false,
@@ -42,16 +42,16 @@
 		"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",
+		"@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/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;