jsdoczoom 0.1.0 → 0.2.1

package/dist/jsdoc-parser.js

@@ -17,65 +17,73 @@ import { JsdocError } from "./errors.js";
  * or null if no file-level JSDoc is found.
  */
 export function extractFileJsdoc(sourceText) {
-    const sourceFile = ts.createSourceFile("input.ts", sourceText, ts.ScriptTarget.Latest, true);
-    // Check for syntax errors — if the file has diagnostics, throw PARSE_ERROR
-    const diagnostics = getDiagnostics(sourceFile);
-    if (diagnostics.length > 0) {
-        throw new JsdocError("PARSE_ERROR", `TypeScript parse error: ${diagnostics[0]}`);
-    }
-    // Find the first non-import top-level statement
-    let firstNonImportStatement;
-    for (const statement of sourceFile.statements) {
-        if (ts.isImportDeclaration(statement)) {
-            continue;
-        }
-        firstNonImportStatement = statement;
-        break;
-    }
-    // If there are no non-import statements, check for comments at file start
-    if (firstNonImportStatement === undefined) {
-        return findFirstJsdocBlock(sourceText, 0, sourceText.length);
-    }
-    // The JSDoc block sits in the leading trivia of the first non-import statement.
-    const fullStart = firstNonImportStatement.getFullStart();
-    const nodeStart = firstNonImportStatement.getStart(sourceFile);
-    return findFirstJsdocBlock(sourceText, fullStart, nodeStart);
+	const sourceFile = ts.createSourceFile(
+		"input.ts",
+		sourceText,
+		ts.ScriptTarget.Latest,
+		true,
+	);
+	// Check for syntax errors — if the file has diagnostics, throw PARSE_ERROR
+	const diagnostics = getDiagnostics(sourceFile);
+	if (diagnostics.length > 0) {
+		throw new JsdocError(
+			"PARSE_ERROR",
+			`TypeScript parse error: ${diagnostics[0]}`,
+		);
+	}
+	// Find the first non-import top-level statement
+	let firstNonImportStatement;
+	for (const statement of sourceFile.statements) {
+		if (ts.isImportDeclaration(statement)) {
+			continue;
+		}
+		firstNonImportStatement = statement;
+		break;
+	}
+	// If there are no non-import statements, check for comments at file start
+	if (firstNonImportStatement === undefined) {
+		return findFirstJsdocBlock(sourceText, 0, sourceText.length);
+	}
+	// The JSDoc block sits in the leading trivia of the first non-import statement.
+	const fullStart = firstNonImportStatement.getFullStart();
+	const nodeStart = firstNonImportStatement.getStart(sourceFile);
+	return findFirstJsdocBlock(sourceText, fullStart, nodeStart);
 }
 /**
  * Find the first `/** ... *​/` block comment in the given text range.
  */
 function findFirstJsdocBlock(sourceText, start, end) {
-    const commentRanges = getAllBlockComments(sourceText, start, end);
-    for (const range of commentRanges) {
-        const commentText = sourceText.slice(range.start, range.end);
-        if (commentText.startsWith("/**") && !commentText.startsWith("/***")) {
-            // Strip /** and */ delimiters
-            const inner = commentText.slice(3, -2);
-            return inner;
-        }
-    }
-    return null;
+	const commentRanges = getAllBlockComments(sourceText, start, end);
+	for (const range of commentRanges) {
+		const commentText = sourceText.slice(range.start, range.end);
+		if (commentText.startsWith("/**") && !commentText.startsWith("/***")) {
+			// Strip /** and */ delimiters
+			const inner = commentText.slice(3, -2);
+			return inner;
+		}
+	}
+	return null;
 }
 /**
  * Find the end position of a block comment starting at `pos` (after the `/*`).
  */
 function findBlockCommentEnd(sourceText, pos) {
-    while (pos < sourceText.length) {
-        if (sourceText[pos] === "*" && sourceText[pos + 1] === "/") {
-            return pos + 2;
-        }
-        pos++;
-    }
-    return pos;
+	while (pos < sourceText.length) {
+		if (sourceText[pos] === "*" && sourceText[pos + 1] === "/") {
+			return pos + 2;
+		}
+		pos++;
+	}
+	return pos;
 }
 /**
  * Skip past a line comment starting at `pos` (after the `//`).
  */
 function findLineCommentEnd(sourceText, pos) {
-    while (pos < sourceText.length && sourceText[pos] !== "\n") {
-        pos++;
-    }
-    return pos;
+	while (pos < sourceText.length && sourceText[pos] !== "\n") {
+		pos++;
+	}
+	return pos;
 }
 const WHITESPACE = new Set([" ", "\t", "\n", "\r"]);
 /**
@@ -83,56 +91,52 @@ const WHITESPACE = new Set([" ", "\t", "\n", "\r"]);
  * Stops at the first non-whitespace, non-comment character (code).
  */
 function getAllBlockComments(sourceText, start, end) {
-    const results = [];
-    let pos = start;
-    while (pos < end) {
-        if (WHITESPACE.has(sourceText[pos])) {
-            pos++;
-            continue;
-        }
-        const nextChar = sourceText[pos + 1];
-        if (sourceText[pos] !== "/" || pos + 1 >= end)
-            break;
-        if (nextChar === "*") {
-            const commentStart = pos;
-            pos = findBlockCommentEnd(sourceText, pos + 2);
-            results.push({ start: commentStart, end: pos });
-            continue;
-        }
-        if (nextChar === "/") {
-            pos = findLineCommentEnd(sourceText, pos + 2);
-            continue;
-        }
-        break;
-    }
-    return results;
+	const results = [];
+	let pos = start;
+	while (pos < end) {
+		if (WHITESPACE.has(sourceText[pos])) {
+			pos++;
+			continue;
+		}
+		const nextChar = sourceText[pos + 1];
+		if (sourceText[pos] !== "/" || pos + 1 >= end) break;
+		if (nextChar === "*") {
+			const commentStart = pos;
+			pos = findBlockCommentEnd(sourceText, pos + 2);
+			results.push({ start: commentStart, end: pos });
+			continue;
+		}
+		if (nextChar === "/") {
+			pos = findLineCommentEnd(sourceText, pos + 2);
+			continue;
+		}
+		break;
+	}
+	return results;
 }
 /**
  * Get syntax error diagnostics from a parsed source file.
  */
 function getDiagnostics(sourceFile) {
-    // parseDiagnostics is available on the internal SourceFile
-    const diags = sourceFile.parseDiagnostics;
-    if (!diags || diags.length === 0)
-        return [];
-    return diags.map((d) => ts.flattenDiagnosticMessageText(d.messageText, "\n"));
+	// parseDiagnostics is available on the internal SourceFile
+	const diags = sourceFile.parseDiagnostics;
+	if (!diags || diags.length === 0) return [];
+	return diags.map((d) => ts.flattenDiagnosticMessageText(d.messageText, "\n"));
 }
 /**
  * Append non-empty text to an accumulator with space separation.
  */
 function appendText(existing, addition) {
-    if (addition.length === 0)
-        return existing;
-    if (existing.length === 0)
-        return addition;
-    return `${existing} ${addition}`;
+	if (addition.length === 0) return existing;
+	if (existing.length === 0) return addition;
+	return `${existing} ${addition}`;
 }
 /** Tags whose content is treated as description (free-text). */
 const DESCRIPTION_TAGS = new Set([
-    "desc",
-    "description",
-    "file",
-    "fileoverview",
+	"desc",
+	"description",
+	"file",
+	"fileoverview",
 ]);
 /**
  * Parse @summary tag and free-text description from raw JSDoc inner text.
@@ -151,57 +155,54 @@ const DESCRIPTION_TAGS = new Set([
  * Whitespace-only @summary tags are skipped.
  */
 function parseJsdocContent(jsdocText) {
-    const lines = jsdocText.split("\n");
-    let freeText = "";
-    let firstSummary = null;
-    let summaryCount = 0;
-    let currentTag = null;
-    let currentContent = "";
-    /** Flush a pending @summary tag, counting all non-empty occurrences. */
-    function flushSummary() {
-        if (currentTag !== "summary")
-            return;
-        const trimmed = currentContent.trim();
-        if (trimmed.length > 0) {
-            summaryCount++;
-            if (firstSummary === null) {
-                firstSummary = trimmed;
-            }
-        }
-    }
-    for (const rawLine of lines) {
-        const stripped = rawLine.replace(/^\s*\*?\s?/, "");
-        const tagMatch = stripped.match(/^@([a-zA-Z]+)(?:\s|$)/);
-        if (tagMatch) {
-            flushSummary();
-            const rawTagName = tagMatch[1];
-            const tagContent = stripped.slice(tagMatch[0].length);
-            if (DESCRIPTION_TAGS.has(rawTagName.toLowerCase())) {
-                freeText = appendText(freeText, tagContent);
-                currentTag = null;
-                currentContent = "";
-            }
-            else {
-                currentTag = rawTagName;
-                currentContent = tagContent;
-            }
-            continue;
-        }
-        // Continuation line
-        if (currentTag === null) {
-            freeText = appendText(freeText, stripped);
-        }
-        else if (stripped.length > 0) {
-            currentContent += ` ${stripped}`;
-        }
-    }
-    flushSummary();
-    const trimmedFreeText = freeText.trim();
-    return {
-        summary: firstSummary,
-        description: trimmedFreeText.length > 0 ? trimmedFreeText : null,
-        summaryCount,
-    };
+	const lines = jsdocText.split("\n");
+	let freeText = "";
+	let firstSummary = null;
+	let summaryCount = 0;
+	let currentTag = null;
+	let currentContent = "";
+	/** Flush a pending @summary tag, counting all non-empty occurrences. */
+	function flushSummary() {
+		if (currentTag !== "summary") return;
+		const trimmed = currentContent.trim();
+		if (trimmed.length > 0) {
+			summaryCount++;
+			if (firstSummary === null) {
+				firstSummary = trimmed;
+			}
+		}
+	}
+	for (const rawLine of lines) {
+		const stripped = rawLine.replace(/^\s*\*?\s?/, "");
+		const tagMatch = stripped.match(/^@([a-zA-Z]+)(?:\s|$)/);
+		if (tagMatch) {
+			flushSummary();
+			const rawTagName = tagMatch[1];
+			const tagContent = stripped.slice(tagMatch[0].length);
+			if (DESCRIPTION_TAGS.has(rawTagName.toLowerCase())) {
+				freeText = appendText(freeText, tagContent);
+				currentTag = null;
+				currentContent = "";
+			} else {
+				currentTag = rawTagName;
+				currentContent = tagContent;
+			}
+			continue;
+		}
+		// Continuation line
+		if (currentTag === null) {
+			freeText = appendText(freeText, stripped);
+		} else if (stripped.length > 0) {
+			currentContent += ` ${stripped}`;
+		}
+	}
+	flushSummary();
+	const trimmedFreeText = freeText.trim();
+	return {
+		summary: firstSummary,
+		description: trimmedFreeText.length > 0 ? trimmedFreeText : null,
+		summaryCount,
+	};
 }
 /**
  * Parse a TypeScript file and extract its summary and description from file-level JSDoc.
@@ -210,29 +211,28 @@ function parseJsdocContent(jsdocText) {
  * @summary tag and free-text description.
  */
 export function parseFileSummaries(filePath) {
-    let sourceText;
-    try {
-        sourceText = readFileSync(filePath, "utf-8");
-    }
-    catch {
-        throw new JsdocError("FILE_NOT_FOUND", `File not found: ${filePath}`);
-    }
-    const jsdocText = extractFileJsdoc(sourceText);
-    if (jsdocText === null) {
-        return {
-            path: filePath,
-            summary: null,
-            description: null,
-            summaryCount: 0,
-            hasFileJsdoc: false,
-        };
-    }
-    const { summary, description, summaryCount } = parseJsdocContent(jsdocText);
-    return {
-        path: filePath,
-        summary,
-        description,
-        summaryCount,
-        hasFileJsdoc: true,
-    };
+	let sourceText;
+	try {
+		sourceText = readFileSync(filePath, "utf-8");
+	} catch {
+		throw new JsdocError("FILE_NOT_FOUND", `File not found: ${filePath}`);
+	}
+	const jsdocText = extractFileJsdoc(sourceText);
+	if (jsdocText === null) {
+		return {
+			path: filePath,
+			summary: null,
+			description: null,
+			summaryCount: 0,
+			hasFileJsdoc: false,
+		};
+	}
+	const { summary, description, summaryCount } = parseJsdocContent(jsdocText);
+	return {
+		path: filePath,
+		summary,
+		description,
+		summaryCount,
+		hasFileJsdoc: true,
+	};
 }

package/dist/lint.js

@@ -13,6 +13,7 @@ import { relative } from "node:path";
 import { JsdocError } from "./errors.js";
 import { createLintLinter, lintFileForLint } from "./eslint-engine.js";
 import { discoverFiles } from "./file-discovery.js";
+
 /**
  * Lint a single file and return per-file diagnostics.
  *
@@ -22,12 +23,12 @@ import { discoverFiles } from "./file-discovery.js";
  * @returns File result with relative path and diagnostics array
  */
 async function lintSingleFile(eslint, filePath, cwd) {
-    const sourceText = readFileSync(filePath, "utf-8");
-    const diagnostics = await lintFileForLint(eslint, sourceText, filePath);
-    return {
-        filePath: relative(cwd, filePath),
-        diagnostics,
-    };
+	const sourceText = readFileSync(filePath, "utf-8");
+	const diagnostics = await lintFileForLint(eslint, sourceText, filePath);
+	return {
+		filePath: relative(cwd, filePath),
+		diagnostics,
+	};
 }
 /**
  * Build a LintResult from per-file results, applying a limit to files with issues.
@@ -38,17 +39,22 @@ async function lintSingleFile(eslint, filePath, cwd) {
  * @returns Aggregated lint result with summary statistics
  */
 function buildLintResult(fileResults, totalFiles, limit) {
-    const filesWithIssues = fileResults.filter((f) => f.diagnostics.length > 0);
-    const totalDiagnostics = filesWithIssues.reduce((sum, f) => sum + f.diagnostics.length, 0);
-    const cappedFiles = filesWithIssues.slice(0, limit);
-    return {
-        files: cappedFiles,
-        summary: {
-            totalFiles,
-            filesWithIssues: filesWithIssues.length,
-            totalDiagnostics,
-        },
-    };
+	const filesWithIssues = fileResults.filter((f) => f.diagnostics.length > 0);
+	const totalDiagnostics = filesWithIssues.reduce(
+		(sum, f) => sum + f.diagnostics.length,
+		0,
+	);
+	const cappedFiles = filesWithIssues.slice(0, limit);
+	const truncated = filesWithIssues.length > limit;
+	return {
+		files: cappedFiles,
+		summary: {
+			totalFiles,
+			filesWithIssues: filesWithIssues.length,
+			totalDiagnostics,
+			...(truncated ? { truncated: true } : {}),
+		},
+	};
 }
 /**
  * Lint files matching a selector pattern for comprehensive JSDoc quality.
@@ -65,14 +71,19 @@ function buildLintResult(fileResults, totalFiles, limit) {
  * @throws {JsdocError} NO_FILES_MATCHED if glob selector matches no files
  */
 export async function lint(selector, cwd, limit = 100, gitignore = true) {
-    const files = discoverFiles(selector.pattern, cwd, gitignore);
-    if (files.length === 0 && selector.type === "glob") {
-        throw new JsdocError("NO_FILES_MATCHED", `No files matched: ${selector.pattern}`);
-    }
-    const tsFiles = files.filter((f) => f.endsWith(".ts") || f.endsWith(".tsx"));
-    const eslint = createLintLinter(cwd);
-    const fileResults = await Promise.all(tsFiles.map((f) => lintSingleFile(eslint, f, cwd)));
-    return buildLintResult(fileResults, tsFiles.length, limit);
+	const files = discoverFiles(selector.pattern, cwd, gitignore);
+	if (files.length === 0 && selector.type === "glob") {
+		throw new JsdocError(
+			"NO_FILES_MATCHED",
+			`No files matched: ${selector.pattern}`,
+		);
+	}
+	const tsFiles = files.filter((f) => f.endsWith(".ts") || f.endsWith(".tsx"));
+	const eslint = createLintLinter(cwd);
+	const fileResults = await Promise.all(
+		tsFiles.map((f) => lintSingleFile(eslint, f, cwd)),
+	);
+	return buildLintResult(fileResults, tsFiles.length, limit);
 }
 /**
  * Lint an explicit list of file paths for comprehensive JSDoc quality.
@@ -86,8 +97,12 @@ export async function lint(selector, cwd, limit = 100, gitignore = true) {
  * @returns Lint result with per-file diagnostics and summary
  */
 export async function lintFiles(filePaths, cwd, limit = 100) {
-    const tsFiles = filePaths.filter((f) => f.endsWith(".ts") || f.endsWith(".tsx"));
-    const eslint = createLintLinter(cwd);
-    const fileResults = await Promise.all(tsFiles.map((f) => lintSingleFile(eslint, f, cwd)));
-    return buildLintResult(fileResults, tsFiles.length, limit);
+	const tsFiles = filePaths.filter(
+		(f) => f.endsWith(".ts") || f.endsWith(".tsx"),
+	);
+	const eslint = createLintLinter(cwd);
+	const fileResults = await Promise.all(
+		tsFiles.map((f) => lintSingleFile(eslint, f, cwd)),
+	);
+	return buildLintResult(fileResults, tsFiles.length, limit);
 }

package/dist/selector.js

@@ -16,25 +16,28 @@ import { JsdocError } from "./errors.js";
  * @throws JsdocError INVALID_DEPTH if depth is negative, non-integer, or float
  */
 export function parseSelector(input) {
-    if (!input || input.trim() === "") {
-        throw new JsdocError("INVALID_SELECTOR", "Selector cannot be empty");
-    }
-    // Reject float depths like @2.5 before extracting integer depth
-    if (/@\d+\.\d+$/.test(input)) {
-        throw new JsdocError("INVALID_DEPTH", "Depth must be an integer, not a float");
-    }
-    let pattern = input;
-    let depth;
-    // Match @<digits> at the end of the string
-    const depthMatch = input.match(/@(\d+)$/);
-    if (depthMatch) {
-        depth = parseInt(depthMatch[1], 10);
-        pattern = input.substring(0, depthMatch.index);
-    }
-    const hasGlobChars = /[*?[\]{]/.test(pattern);
-    return {
-        type: hasGlobChars ? "glob" : "path",
-        pattern,
-        depth,
-    };
+	if (!input || input.trim() === "") {
+		throw new JsdocError("INVALID_SELECTOR", "Selector cannot be empty");
+	}
+	// Reject float depths like @2.5 before extracting integer depth
+	if (/@\d+\.\d+$/.test(input)) {
+		throw new JsdocError(
+			"INVALID_DEPTH",
+			"Depth must be an integer, not a float",
+		);
+	}
+	let pattern = input;
+	let depth;
+	// Match @<digits> at the end of the string
+	const depthMatch = input.match(/@(\d+)$/);
+	if (depthMatch) {
+		depth = parseInt(depthMatch[1], 10);
+		pattern = input.substring(0, depthMatch.index);
+	}
+	const hasGlobChars = /[*?[\]{]/.test(pattern);
+	return {
+		type: hasGlobChars ? "glob" : "path",
+		pattern,
+		depth,
+	};
 }