jsdoczoom 0.1.0 → 0.3.0

package/dist/drilldown.js

@@ -5,6 +5,7 @@ import { JsdocError } from "./errors.js";
 import { discoverFiles } from "./file-discovery.js";
 import { parseFileSummaries } from "./jsdoc-parser.js";
 import { generateTypeDeclarations } from "./type-declarations.js";
+
 /** Terminal level (1-indexed): 1=summary, 2=description, 3=type declarations, 4=full file. */
 const TERMINAL_LEVEL = 4;
 /**
@@ -18,33 +19,32 @@ const TERMINAL_LEVEL = 4;
  * The array always has 4 entries. Null entries are skipped during processing.
  */
 function buildLevels(info) {
-    const { summary, description } = info;
-    return [
-        summary !== null ? { text: () => summary } : null,
-        description !== null ? { text: () => description } : null,
-        { text: () => generateTypeDeclarations(info.path) },
-        { text: () => readFileSync(info.path, "utf-8") },
-    ];
+	const { summary, description } = info;
+	return [
+		summary !== null ? { text: () => summary } : null,
+		description !== null ? { text: () => description } : null,
+		{ text: () => generateTypeDeclarations(info.path) },
+		{ text: () => readFileSync(info.path, "utf-8") },
+	];
 }
 /**
  * Compute the display id path for a file. Barrel files (index.ts/index.tsx)
  * use their parent directory path so they represent the directory.
  */
 function displayPath(filePath, cwd) {
-    const rel = relative(cwd, filePath);
-    if (isBarrel(filePath)) {
-        const dir = relative(cwd, dirname(filePath));
-        return dir || ".";
-    }
-    return rel;
+	const rel = relative(cwd, filePath);
+	if (isBarrel(filePath)) {
+		const dir = relative(cwd, dirname(filePath));
+		return dir || ".";
+	}
+	return rel;
 }
 /**
  * Extract the sort key from an output entry (either next_id or id).
  */
 function sortKey(entry) {
-    if ("next_id" in entry)
-        return entry.next_id;
-    return entry.id;
+	if ("next_id" in entry) return entry.next_id;
+	return entry.id;
 }
 /**
  * Process a single file at a given depth through the drill-down levels.
@@ -54,97 +54,96 @@ function sortKey(entry) {
  * Output contains next_id when more detail is available, or id at terminal level.
  */
 function processFile(info, depth, cwd) {
-    const idPath = displayPath(info.path, cwd);
-    const levels = buildLevels(info);
-    // Clamp depth to [1, TERMINAL_LEVEL], advance past null levels
-    let effectiveDepth = Math.max(1, Math.min(depth, TERMINAL_LEVEL));
-    while (effectiveDepth < TERMINAL_LEVEL &&
-        levels[effectiveDepth - 1] === null) {
-        effectiveDepth++;
-    }
-    const level = levels[effectiveDepth - 1];
-    if (effectiveDepth < TERMINAL_LEVEL) {
-        return {
-            next_id: `${idPath}@${effectiveDepth + 1}`,
-            text: level.text(),
-        };
-    }
-    return {
-        id: `${idPath}@${effectiveDepth}`,
-        text: level.text(),
-    };
+	const idPath = displayPath(info.path, cwd);
+	const levels = buildLevels(info);
+	// Clamp depth to [1, TERMINAL_LEVEL], advance past null levels
+	let effectiveDepth = Math.max(1, Math.min(depth, TERMINAL_LEVEL));
+	while (
+		effectiveDepth < TERMINAL_LEVEL &&
+		levels[effectiveDepth - 1] === null
+	) {
+		effectiveDepth++;
+	}
+	const level = levels[effectiveDepth - 1];
+	if (effectiveDepth < TERMINAL_LEVEL) {
+		return {
+			next_id: `${idPath}@${effectiveDepth + 1}`,
+			text: level.text(),
+		};
+	}
+	return {
+		id: `${idPath}@${effectiveDepth}`,
+		text: level.text(),
+	};
 }
 /**
  * Create an OutputErrorItem for a PARSE_ERROR.
  */
 function makeParseErrorItem(filePath, error, cwd) {
-    return {
-        id: displayPath(filePath, cwd),
-        error: { code: error.code, message: error.message },
-    };
+	return {
+		id: displayPath(filePath, cwd),
+		error: { code: error.code, message: error.message },
+	};
 }
 /**
  * Check if an error is a PARSE_ERROR JsdocError.
  */
 function isParseError(error) {
-    return error instanceof JsdocError && error.code === "PARSE_ERROR";
+	return error instanceof JsdocError && error.code === "PARSE_ERROR";
 }
 /**
  * Process a file safely, returning an OutputErrorItem on PARSE_ERROR.
  * Rethrows non-PARSE_ERROR exceptions.
  */
 function processFileSafe(filePath, depth, cwd) {
-    try {
-        const info = parseFileSummaries(filePath);
-        return processFile(info, depth, cwd);
-    }
-    catch (error) {
-        if (isParseError(error))
-            return makeParseErrorItem(filePath, error, cwd);
-        throw error;
-    }
+	try {
+		const info = parseFileSummaries(filePath);
+		return processFile(info, depth, cwd);
+	} catch (error) {
+		if (isParseError(error)) return makeParseErrorItem(filePath, error, cwd);
+		throw error;
+	}
 }
 /**
  * Gather barrel info and error entries from a list of barrel file paths.
  * Returns successfully parsed barrel infos and error entries for unparseable barrels.
  */
 function gatherBarrelInfos(barrelPaths, cwd) {
-    const infos = [];
-    const errors = [];
-    for (const barrelPath of barrelPaths) {
-        try {
-            const info = parseFileSummaries(barrelPath);
-            const children = getBarrelChildren(barrelPath, cwd);
-            infos.push({
-                path: barrelPath,
-                hasSummary: info.summary !== null,
-                hasDescription: info.description !== null,
-                children,
-            });
-        }
-        catch (error) {
-            if (isParseError(error)) {
-                errors.push(makeParseErrorItem(barrelPath, error, cwd));
-                continue;
-            }
-            throw error;
-        }
-    }
-    return { infos, errors };
+	const infos = [];
+	const errors = [];
+	for (const barrelPath of barrelPaths) {
+		try {
+			const info = parseFileSummaries(barrelPath);
+			const children = getBarrelChildren(barrelPath, cwd);
+			infos.push({
+				path: barrelPath,
+				hasSummary: info.summary !== null,
+				hasDescription: info.description !== null,
+				children,
+			});
+		} catch (error) {
+			if (isParseError(error)) {
+				errors.push(makeParseErrorItem(barrelPath, error, cwd));
+				continue;
+			}
+			throw error;
+		}
+	}
+	return { infos, errors };
 }
 /**
  * Build the set of files gated by barrels that have summaries.
  */
 function buildGatedFileSet(barrelInfos) {
-    const gated = new Set();
-    for (const barrel of barrelInfos) {
-        if (barrel.hasSummary) {
-            for (const child of barrel.children) {
-                gated.add(child);
-            }
-        }
-    }
-    return gated;
+	const gated = new Set();
+	for (const barrel of barrelInfos) {
+		if (barrel.hasSummary) {
+			for (const child of barrel.children) {
+				gated.add(child);
+			}
+		}
+	}
+	return gated;
 }
 /**
  * Process a single barrel at the given depth (1-indexed).
@@ -153,26 +152,29 @@ function buildGatedFileSet(barrelInfos) {
  * then transition at depth 3 where the barrel disappears and children appear.
  */
 function processBarrelAtDepth(barrel, depth, cwd) {
-    if (!barrel.hasSummary)
-        return [processFileSafe(barrel.path, depth, cwd)];
-    // Null-skip: if depth 2 but no description, advance to transition depth
-    let effectiveDepth = depth;
-    if (effectiveDepth === 2 && !barrel.hasDescription) {
-        effectiveDepth = 3;
-    }
-    if (effectiveDepth < 3) {
-        // Show barrel's own L1 (summary) or L2 (description)
-        return [processFileSafe(barrel.path, effectiveDepth, cwd)];
-    }
-    // Barrel transitions: barrel disappears, children appear
-    const childDepth = effectiveDepth - 2;
-    return collectSafeResults(barrel.children, childDepth, cwd);
+	if (!barrel.hasSummary) return [processFileSafe(barrel.path, depth, cwd)];
+	// Null-skip: if depth 2 but no description, advance to transition depth
+	let effectiveDepth = depth;
+	if (effectiveDepth === 2 && !barrel.hasDescription) {
+		effectiveDepth = 3;
+	}
+	if (effectiveDepth < 3) {
+		// Show barrel's own L1 (summary) or L2 (description)
+		const entry = processFileSafe(barrel.path, effectiveDepth, cwd);
+		if ("next_id" in entry) {
+			entry.children = barrel.children.map((c) => relative(cwd, c));
+		}
+		return [entry];
+	}
+	// Barrel transitions: barrel disappears, children appear
+	const childDepth = effectiveDepth - 2;
+	return collectSafeResults(barrel.children, childDepth, cwd);
 }
 /**
  * Process a list of files through processFileSafe.
  */
 function collectSafeResults(files, depth, cwd) {
-    return files.map((filePath) => processFileSafe(filePath, depth, cwd));
+	return files.map((filePath) => processFileSafe(filePath, depth, cwd));
 }
 /**
  * Process files discovered via glob with barrel gating.
@@ -186,30 +188,31 @@ function collectSafeResults(files, depth, cwd) {
  * Non-barrel files that are not gated by any barrel are processed normally.
  */
 function processGlobWithBarrels(files, depth, cwd) {
-    const barrelPaths = [];
-    const nonBarrelPaths = [];
-    for (const filePath of files) {
-        if (isBarrel(filePath)) {
-            barrelPaths.push(filePath);
-        }
-        else {
-            nonBarrelPaths.push(filePath);
-        }
-    }
-    if (barrelPaths.length === 0) {
-        return collectSafeResults(nonBarrelPaths, depth, cwd);
-    }
-    const { infos: barrelInfos, errors: barrelErrors } = gatherBarrelInfos(barrelPaths, cwd);
-    const gatedFiles = buildGatedFileSet(barrelInfos);
-    const results = [...barrelErrors];
-    for (const barrel of barrelInfos) {
-        if (gatedFiles.has(barrel.path))
-            continue;
-        results.push(...processBarrelAtDepth(barrel, depth, cwd));
-    }
-    const ungatedNonBarrels = nonBarrelPaths.filter((f) => !gatedFiles.has(f));
-    results.push(...collectSafeResults(ungatedNonBarrels, depth, cwd));
-    return results;
+	const barrelPaths = [];
+	const nonBarrelPaths = [];
+	for (const filePath of files) {
+		if (isBarrel(filePath)) {
+			barrelPaths.push(filePath);
+		} else {
+			nonBarrelPaths.push(filePath);
+		}
+	}
+	if (barrelPaths.length === 0) {
+		return collectSafeResults(nonBarrelPaths, depth, cwd);
+	}
+	const { infos: barrelInfos, errors: barrelErrors } = gatherBarrelInfos(
+		barrelPaths,
+		cwd,
+	);
+	const gatedFiles = buildGatedFileSet(barrelInfos);
+	const results = [...barrelErrors];
+	for (const barrel of barrelInfos) {
+		if (gatedFiles.has(barrel.path)) continue;
+		results.push(...processBarrelAtDepth(barrel, depth, cwd));
+	}
+	const ungatedNonBarrels = nonBarrelPaths.filter((f) => !gatedFiles.has(f));
+	results.push(...collectSafeResults(ungatedNonBarrels, depth, cwd));
+	return results;
 }
 /**
  * Main entry point for normal-mode processing.
@@ -226,40 +229,45 @@ function processGlobWithBarrels(files, depth, cwd) {
  * @throws {JsdocError} PARSE_ERROR for path selector targeting file with syntax errors
  */
 export function drilldown(selector, cwd, gitignore = true, limit = 100) {
-    const depth = selector.depth ?? 1;
-    if (selector.type === "path") {
-        const files = discoverFiles(selector.pattern, cwd, gitignore);
-        if (files.length > 1) {
-            // Directory expanded to multiple files — route through glob pipeline
-            const results = processGlobWithBarrels(files, depth, cwd);
-            const sorted = results.sort((a, b) => sortKey(a).localeCompare(sortKey(b)));
-            const total = sorted.length;
-            const truncated = total > limit;
-            return {
-                items: sorted.slice(0, limit),
-                truncated,
-            };
-        }
-        // Single file path — errors are fatal, no barrel gating
-        const filePath = files[0];
-        const info = parseFileSummaries(filePath);
-        const items = [processFile(info, depth, cwd)];
-        return { items, truncated: false };
-    }
-    // Glob selector — apply barrel gating
-    const files = discoverFiles(selector.pattern, cwd, gitignore);
-    if (files.length === 0) {
-        throw new JsdocError("NO_FILES_MATCHED", `No files matched: ${selector.pattern}`);
-    }
-    const results = processGlobWithBarrels(files, depth, cwd);
-    // Sort alphabetically by key
-    const sorted = results.sort((a, b) => sortKey(a).localeCompare(sortKey(b)));
-    const total = sorted.length;
-    const truncated = total > limit;
-    return {
-        items: sorted.slice(0, limit),
-        truncated,
-    };
+	const depth = selector.depth ?? 1;
+	if (selector.type === "path") {
+		const files = discoverFiles(selector.pattern, cwd, gitignore);
+		if (files.length > 1) {
+			// Directory expanded to multiple files — route through glob pipeline
+			const results = processGlobWithBarrels(files, depth, cwd);
+			const sorted = results.sort((a, b) =>
+				sortKey(a).localeCompare(sortKey(b)),
+			);
+			const total = sorted.length;
+			const truncated = total > limit;
+			return {
+				items: sorted.slice(0, limit),
+				truncated,
+			};
+		}
+		// Single file path — errors are fatal, no barrel gating
+		const filePath = files[0];
+		const info = parseFileSummaries(filePath);
+		const items = [processFile(info, depth, cwd)];
+		return { items, truncated: false };
+	}
+	// Glob selector — apply barrel gating
+	const files = discoverFiles(selector.pattern, cwd, gitignore);
+	if (files.length === 0) {
+		throw new JsdocError(
+			"NO_FILES_MATCHED",
+			`No files matched: ${selector.pattern}`,
+		);
+	}
+	const results = processGlobWithBarrels(files, depth, cwd);
+	// Sort alphabetically by key
+	const sorted = results.sort((a, b) => sortKey(a).localeCompare(sortKey(b)));
+	const total = sorted.length;
+	const truncated = total > limit;
+	return {
+		items: sorted.slice(0, limit),
+		truncated,
+	};
 }
 /**
  * Process an explicit list of file paths at a given depth.
@@ -273,14 +281,16 @@ export function drilldown(selector, cwd, gitignore = true, limit = 100) {
  * @returns Array of output entries sorted alphabetically by path
  */
 export function drilldownFiles(filePaths, depth, cwd, limit = 100) {
-    const d = depth ?? 1;
-    const tsFiles = filePaths.filter((f) => f.endsWith(".ts") || f.endsWith(".tsx"));
-    const results = collectSafeResults(tsFiles, d, cwd);
-    const sorted = results.sort((a, b) => sortKey(a).localeCompare(sortKey(b)));
-    const total = sorted.length;
-    const truncated = total > limit;
-    return {
-        items: sorted.slice(0, limit),
-        truncated,
-    };
+	const d = depth ?? 1;
+	const tsFiles = filePaths.filter(
+		(f) => f.endsWith(".ts") || f.endsWith(".tsx"),
+	);
+	const results = collectSafeResults(tsFiles, d, cwd);
+	const sorted = results.sort((a, b) => sortKey(a).localeCompare(sortKey(b)));
+	const total = sorted.length;
+	const truncated = total > limit;
+	return {
+		items: sorted.slice(0, limit),
+		truncated,
+	};
 }

package/dist/errors.js

@@ -7,18 +7,18 @@
  */
 /** Custom error class that serializes to the documented JSON error contract */
 export class JsdocError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.code = code;
-        this.name = "JsdocError";
-    }
-    toJSON() {
-        return {
-            error: {
-                code: this.code,
-                message: this.message,
-            },
-        };
-    }
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "JsdocError";
+	}
+	toJSON() {
+		return {
+			error: {
+				code: this.code,
+				message: this.message,
+			},
+		};
+	}
 }