jsdoczoom 0.1.0

package/dist/eslint-engine.js

@@ -0,0 +1,160 @@
+/**
+ * ESLint validation engine for jsdoczoom.
+ *
+ * @summary Bridge between ESLint API and jsdoczoom validation/lint formats
+ */
+import tsParser from "@typescript-eslint/parser";
+import { ESLint } from "eslint";
+import jsdocPlugin from "eslint-plugin-jsdoc";
+import plugin from "./eslint-plugin.js";
+/**
+ * Creates an ESLint instance configured for validation mode.
+ *
+ * This linter only runs jsdoczoom's custom rules for file-level JSDoc validation.
+ *
+ * @returns Configured ESLint instance for validation
+ */
+export function createValidationLinter() {
+    const eslint = new ESLint({
+        overrideConfigFile: true,
+        overrideConfig: [
+            {
+                files: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"],
+                plugins: { jsdoczoom: plugin },
+                rules: {
+                    "jsdoczoom/require-file-jsdoc": "error",
+                    "jsdoczoom/require-file-summary": "error",
+                    "jsdoczoom/require-file-description": "error",
+                },
+                languageOptions: {
+                    parser: tsParser,
+                    ecmaVersion: "latest",
+                    sourceType: "module",
+                },
+            },
+        ],
+    });
+    return eslint;
+}
+/**
+ * Creates an ESLint instance configured for lint mode.
+ *
+ * This linter runs both jsdoczoom rules and eslint-plugin-jsdoc rules for comprehensive JSDoc validation.
+ *
+ * @param cwd - Optional working directory for ESLint base path resolution
+ * @returns Configured ESLint instance for lint mode
+ */
+export function createLintLinter(cwd) {
+    const eslint = new ESLint({
+        cwd,
+        overrideConfigFile: true,
+        overrideConfig: [
+            {
+                files: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"],
+                plugins: { jsdoczoom: plugin, jsdoc: jsdocPlugin },
+                rules: {
+                    "jsdoczoom/require-file-jsdoc": "error",
+                    "jsdoczoom/require-file-summary": "error",
+                    "jsdoczoom/require-file-description": "error",
+                    "jsdoc/require-jsdoc": ["error", { publicOnly: true }],
+                    "jsdoc/require-param": "warn",
+                    "jsdoc/require-param-description": "warn",
+                    "jsdoc/require-returns": "warn",
+                    "jsdoc/require-returns-description": "warn",
+                    "jsdoc/require-throws": "warn",
+                    "jsdoc/check-param-names": "error",
+                    "jsdoc/check-tag-names": "error",
+                    "jsdoc/no-types": "error",
+                    "jsdoc/informative-docs": "error",
+                    "jsdoc/tag-lines": "off",
+                    "jsdoc/no-blank-blocks": "error",
+                    "jsdoc/require-description": "error",
+                },
+                languageOptions: {
+                    parser: tsParser,
+                    ecmaVersion: "latest",
+                    sourceType: "module",
+                },
+            },
+        ],
+    });
+    return eslint;
+}
+/**
+ * Lints source text for validation mode and returns simplified messages.
+ *
+ * @param eslint - ESLint instance (typically from createValidationLinter)
+ * @param sourceText - Source code to lint
+ * @param filePath - Path to the file being linted
+ * @returns Simplified message list with ruleId, messageId, and fatal flag
+ */
+export async function lintFileForValidation(eslint, sourceText, filePath) {
+    const results = await eslint.lintText(sourceText, { filePath });
+    if (results.length === 0)
+        return [];
+    return results[0].messages.map((msg) => ({
+        ruleId: msg.ruleId,
+        messageId: msg.messageId,
+        fatal: msg.fatal,
+    }));
+}
+/**
+ * Lints source text for lint mode and returns detailed diagnostics.
+ *
+ * @param eslint - ESLint instance (typically from createLintLinter)
+ * @param sourceText - Source code to lint
+ * @param filePath - Path to the file being linted
+ * @returns Array of lint diagnostics with line, column, rule, message, and severity
+ */
+export async function lintFileForLint(eslint, sourceText, filePath) {
+    const results = await eslint.lintText(sourceText, { filePath });
+    if (results.length === 0)
+        return [];
+    return results[0].messages.map((msg) => ({
+        line: msg.line,
+        column: msg.column,
+        rule: msg.ruleId ?? "unknown",
+        message: msg.message,
+        severity: msg.severity === 2 ? "error" : "warning",
+    }));
+}
+/**
+ * Maps ESLint messages to a single ValidationStatus using priority order.
+ *
+ * Priority order (first match wins):
+ * 1. Parse errors (null ruleId with fatal flag) → syntax_error
+ * 2. jsdoczoom/require-file-jsdoc → missing_jsdoc
+ * 3. jsdoczoom/require-file-summary with missingSummary → missing_summary
+ * 4. jsdoczoom/require-file-summary with multipleSummary → multiple_summary
+ * 5. jsdoczoom/require-file-description → missing_description
+ * 6. No matches → valid
+ *
+ * @param messages - Simplified ESLint messages from lintFileForValidation
+ * @returns ValidationStatus or "valid"
+ */
+export function mapToValidationStatus(messages) {
+    // Priority 1: Parse errors
+    if (messages.some((msg) => msg.ruleId === null && msg.fatal)) {
+        return "syntax_error";
+    }
+    // Priority 2: Missing JSDoc
+    if (messages.some((msg) => msg.ruleId === "jsdoczoom/require-file-jsdoc")) {
+        return "missing_jsdoc";
+    }
+    // Priority 3: Missing summary
+    if (messages.some((msg) => msg.ruleId === "jsdoczoom/require-file-summary" &&
+        msg.messageId === "missingSummary")) {
+        return "missing_summary";
+    }
+    // Priority 4: Multiple summary
+    if (messages.some((msg) => msg.ruleId === "jsdoczoom/require-file-summary" &&
+        msg.messageId === "multipleSummary")) {
+        return "multiple_summary";
+    }
+    // Priority 5: Missing description
+    if (messages.some((msg) => msg.ruleId === "jsdoczoom/require-file-description")) {
+        return "missing_description";
+    }
+    // No matches
+    return "valid";
+}

package/dist/eslint-plugin.js

@@ -0,0 +1,205 @@
+/**
+ * Custom ESLint plugin for jsdoczoom file-level JSDoc validation.
+ *
+ * Provides three rules that replicate the file-level JSDoc checks from
+ * jsdoc-parser.ts: detecting presence of file-level JSDoc blocks,
+ * validating exact lowercase @summary tags, and checking for description
+ * content (free-text or description-synonym tags).
+ *
+ * @summary Custom ESLint plugin with file-level JSDoc validation rules
+ */
+/** Tags whose content is treated as description (free-text). */
+const DESCRIPTION_TAGS = new Set([
+    "desc",
+    "description",
+    "file",
+    "fileoverview",
+]);
+/**
+ * Find the file-level JSDoc block comment from the source code.
+ *
+ * The file-level JSDoc block is the first block comment that starts with
+ * a single asterisk (not double) and appears before the first non-import
+ * statement. When no non-import statements exist, the first qualifying
+ * block comment in the file is used.
+ */
+function findFileJsdocComment(sourceCode, programBody) {
+    const firstNonImport = programBody.find((node) => node.type !== "ImportDeclaration");
+    const allComments = sourceCode.getAllComments();
+    // Filter to JSDoc block comments (/** but not /***)
+    // In ESLint's AST, /** foo */ has comment.type === "Block" and
+    // comment.value === "* foo ". A /*** foo */ has value === "** foo ".
+    const jsdocComments = allComments.filter((c) => c.type === "Block" &&
+        c.value.startsWith("*") &&
+        !c.value.startsWith("**"));
+    if (firstNonImport) {
+        // Find first JSDoc comment that ends before the first non-import statement starts
+        return (jsdocComments.find((c) => c.range !== undefined &&
+            firstNonImport.range !== undefined &&
+            c.range[1] <= firstNonImport.range[0]) ?? null);
+    }
+    // If no non-import statements, return first JSDoc comment in file
+    return jsdocComments[0] ?? null;
+}
+/**
+ * Append non-empty text to an accumulator with space separation.
+ */
+function appendText(existing, addition) {
+    if (!addition)
+        return existing;
+    return existing ? `${existing} ${addition}` : addition;
+}
+/**
+ * Parse the inner content of a JSDoc block comment.
+ *
+ * Extracts summary tags (exact lowercase only), description tags
+ * (case-insensitive), and free-text content before any @ tags.
+ * Replicates the parsing behavior from jsdoc-parser.ts parseJsdocContent().
+ */
+function parseJsdocBlock(comment) {
+    // comment.value is the text between /* and */
+    // For /** ... */, value starts with "*". Strip that leading *.
+    const innerText = comment.value.slice(1);
+    const lines = innerText.split("\n");
+    let freeText = "";
+    const summaryTags = [];
+    let currentTag = null;
+    let currentContent = "";
+    function flushCurrentTag() {
+        if (currentTag === "summary") {
+            const trimmed = currentContent.trim();
+            // Only count non-whitespace summaries
+            if (trimmed.length > 0) {
+                summaryTags.push({ name: "summary", content: trimmed });
+            }
+        }
+    }
+    for (const rawLine of lines) {
+        const stripped = rawLine.replace(/^\s*\*?\s?/, "");
+        const tagMatch = stripped.match(/^@([a-zA-Z]+)(?:\s|$)/);
+        if (tagMatch) {
+            flushCurrentTag();
+            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 {
+                // Store exact tag name (case-sensitive for @summary)
+                currentTag = rawTagName;
+                currentContent = tagContent;
+            }
+            continue;
+        }
+        // Continuation line
+        if (currentTag === null) {
+            freeText = appendText(freeText, stripped);
+        }
+        else if (stripped.length > 0) {
+            currentContent += ` ${stripped}`;
+        }
+    }
+    flushCurrentTag();
+    const trimmedFreeText = freeText.trim();
+    return {
+        freeText: trimmedFreeText,
+        summaryTags,
+        hasDescription: trimmedFreeText.length > 0,
+    };
+}
+const requireFileJsdoc = {
+    meta: {
+        type: "problem",
+        messages: {
+            missingFileJsdoc: "File is missing a file-level JSDoc block (/** ... */) before the first code statement.",
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            Program(node) {
+                const sourceCode = context.sourceCode;
+                const jsdocComment = findFileJsdocComment(sourceCode, node.body);
+                if (jsdocComment === null) {
+                    context.report({
+                        node,
+                        messageId: "missingFileJsdoc",
+                    });
+                }
+            },
+        };
+    },
+};
+const requireFileSummary = {
+    meta: {
+        type: "problem",
+        messages: {
+            missingSummary: "File-level JSDoc is missing an @summary tag (exact lowercase required).",
+            multipleSummary: "File-level JSDoc has multiple @summary tags. Use exactly one.",
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            Program(node) {
+                const sourceCode = context.sourceCode;
+                const jsdocComment = findFileJsdocComment(sourceCode, node.body);
+                // If no file-level JSDoc exists, that's rule 1's job to report
+                if (jsdocComment === null) {
+                    return;
+                }
+                const parsed = parseJsdocBlock(jsdocComment);
+                if (parsed.summaryTags.length === 0) {
+                    context.report({
+                        node,
+                        messageId: "missingSummary",
+                    });
+                }
+                else if (parsed.summaryTags.length > 1) {
+                    context.report({
+                        node,
+                        messageId: "multipleSummary",
+                    });
+                }
+            },
+        };
+    },
+};
+const requireFileDescription = {
+    meta: {
+        type: "problem",
+        messages: {
+            missingDescription: "File-level JSDoc is missing a description. Add free-text before @tags or use @desc/@description/@file/@fileoverview.",
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            Program(node) {
+                const sourceCode = context.sourceCode;
+                const jsdocComment = findFileJsdocComment(sourceCode, node.body);
+                // If no file-level JSDoc exists, that's rule 1's job to report
+                if (jsdocComment === null) {
+                    return;
+                }
+                const parsed = parseJsdocBlock(jsdocComment);
+                if (!parsed.hasDescription) {
+                    context.report({
+                        node,
+                        messageId: "missingDescription",
+                    });
+                }
+            },
+        };
+    },
+};
+const plugin = {
+    rules: {
+        "require-file-jsdoc": requireFileJsdoc,
+        "require-file-summary": requireFileSummary,
+        "require-file-description": requireFileDescription,
+    },
+};
+export default plugin;

package/dist/file-discovery.js

@@ -0,0 +1,76 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { globSync } from "glob";
+import ignore from "ignore";
+import { JsdocError } from "./errors.js";
+/**
+ * Walks .gitignore files from cwd to filesystem root, building an ignore
+ * filter that glob results pass through. Direct-path lookups bypass the
+ * filter since the user explicitly named the file. The ignore instance is
+ * created per call -- no caching -- because cwd may differ between invocations.
+ *
+ * @summary Resolve selector patterns to absolute file paths with gitignore filtering
+ */
+/**
+ * Walk from `cwd` up to the filesystem root, collecting .gitignore entries.
+ * Returns an Ignore instance loaded with all discovered rules.
+ */
+function loadGitignore(cwd) {
+    const ig = ignore();
+    let dir = resolve(cwd);
+    while (true) {
+        const gitignorePath = join(dir, ".gitignore");
+        if (existsSync(gitignorePath)) {
+            const content = readFileSync(gitignorePath, "utf-8");
+            const prefix = relative(cwd, dir);
+            const lines = content
+                .split("\n")
+                .map((l) => l.trim())
+                .filter((l) => l && !l.startsWith("#"));
+            for (const line of lines) {
+                // Prefix rules from ancestor .gitignore files so paths are
+                // relative to `cwd`, which is where glob results are anchored.
+                ig.add(prefix ? `${prefix}/${line}` : line);
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return ig;
+}
+/**
+ * Resolve a selector pattern to a list of .ts/.tsx file paths.
+ *
+ * Glob patterns use the glob package. Plain paths resolve to single-element arrays.
+ * Results exclude .d.ts files and are sorted alphabetically.
+ * When gitignore is true (default), results are filtered through .gitignore rules.
+ *
+ * @param pattern - A glob pattern or direct file path
+ * @param cwd - The working directory for resolving relative paths
+ * @param gitignore - Whether to respect .gitignore rules (default true)
+ * @returns Array of absolute file paths
+ * @throws {JsdocError} FILE_NOT_FOUND when a direct path does not exist
+ */
+export function discoverFiles(pattern, cwd, gitignore = true) {
+    const hasGlobChars = /[*?[\]{]/.test(pattern);
+    if (hasGlobChars) {
+        const matches = globSync(pattern, { cwd, absolute: true });
+        let filtered = matches.filter((f) => (f.endsWith(".ts") || f.endsWith(".tsx")) && !f.endsWith(".d.ts"));
+        if (gitignore) {
+            const ig = loadGitignore(cwd);
+            filtered = filtered.filter((abs) => !ig.ignores(relative(cwd, abs)));
+        }
+        return filtered.sort();
+    }
+    // Direct path
+    const resolved = resolve(cwd, pattern);
+    if (!existsSync(resolved)) {
+        throw new JsdocError("FILE_NOT_FOUND", `File not found: ${pattern}`);
+    }
+    if (statSync(resolved).isDirectory()) {
+        return discoverFiles(`${resolved}/**`, cwd, gitignore);
+    }
+    return [resolved];
+}

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * Re-exports all public functions, classes, and types from internal modules.
+ * This is the sole entry point for programmatic consumers of the jsdoczoom
+ * package.
+ *
+ * @summary Public API barrel re-exporting all functions, types, and classes
+ */
+export { getBarrelChildren, isBarrel } from "./barrel.js";
+export { drilldown, drilldownFiles } from "./drilldown.js";
+export { JsdocError } from "./errors.js";
+export { discoverFiles } from "./file-discovery.js";
+export { extractFileJsdoc, parseFileSummaries } from "./jsdoc-parser.js";
+export { lint, lintFiles } from "./lint.js";
+export { parseSelector } from "./selector.js";
+export { generateTypeDeclarations } from "./type-declarations.js";
+export { VALIDATION_STATUS_PRIORITY, } from "./types.js";
+export { validate, validateFiles } from "./validate.js";

package/dist/jsdoc-parser.js

@@ -0,0 +1,238 @@
+import { readFileSync } from "node:fs";
+import ts from "typescript";
+import { JsdocError } from "./errors.js";
+/**
+ * Uses the TypeScript compiler to locate the first JSDoc block before any
+ * code statements, then extracts the first `@summary` tag and free-text
+ * description. Syntax errors in the source file produce PARSE_ERROR;
+ * whitespace-only summaries are skipped in favor of the next non-empty one.
+ *
+ * @summary Extract file-level JSDoc summary and description from TypeScript source files
+ */
+/**
+ * Extract the first file-level JSDoc block from TypeScript source text.
+ *
+ * The JSDoc block must appear before any code statements (after imports is OK).
+ * Returns the raw JSDoc text without the leading `/**` and trailing `*​/` delimiters,
+ * 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);
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * Skip past a line comment starting at `pos` (after the `//`).
+ */
+function findLineCommentEnd(sourceText, pos) {
+    while (pos < sourceText.length && sourceText[pos] !== "\n") {
+        pos++;
+    }
+    return pos;
+}
+const WHITESPACE = new Set([" ", "\t", "\n", "\r"]);
+/**
+ * Scan for block comments in the source text between start and end positions.
+ * 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;
+}
+/**
+ * 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"));
+}
+/**
+ * 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}`;
+}
+/** Tags whose content is treated as description (free-text). */
+const DESCRIPTION_TAGS = new Set([
+    "desc",
+    "description",
+    "file",
+    "fileoverview",
+]);
+/**
+ * Parse @summary tag and free-text description from raw JSDoc inner text.
+ *
+ * Returns:
+ * - summary: First non-empty @summary tag content (or null if none)
+ * - description: Free-text before first @ tag (or null if none)
+ *
+ * Only exact lowercase @summary is recognized. Case variants like
+ * @Summary or @SUMMARY are ignored (causing missing_summary in
+ * validation). The @desc, @description, @file, and @fileoverview
+ * tags (case-insensitive) are treated as description synonyms —
+ * their content is included in the description field.
+ *
+ * Additional @summary tags are silently ignored.
+ * 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,
+    };
+}
+/**
+ * Parse a TypeScript file and extract its summary and description from file-level JSDoc.
+ *
+ * Reads the file, extracts the first file-level JSDoc block, and parses the first
+ * @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,
+    };
+}