jsdoczoom 0.1.0

package/dist/lint.js

@@ -0,0 +1,93 @@
+/**
+ * Lint mode runs eslint-plugin-jsdoc and custom jsdoczoom rules against
+ * discovered files, returning per-file diagnostics with line/column
+ * positions, rule names, messages, and severity levels. A single ESLint
+ * instance is created per invocation with the correct working directory
+ * so that files outside the process cwd are handled correctly. The limit
+ * parameter caps the number of files with issues included in the result.
+ *
+ * @summary Lint files for comprehensive JSDoc quality using ESLint engine
+ */
+import { readFileSync } from "node:fs";
+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.
+ *
+ * @param eslint - Reusable ESLint instance with correct cwd
+ * @param filePath - Absolute path to the file
+ * @param cwd - Working directory for computing relative paths
+ * @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,
+    };
+}
+/**
+ * Build a LintResult from per-file results, applying a limit to files with issues.
+ *
+ * @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
+ * @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,
+        },
+    };
+}
+/**
+ * Lint files matching a selector pattern for comprehensive JSDoc quality.
+ *
+ * Discovers files via glob or path selector, creates a single ESLint instance
+ * with both jsdoczoom and eslint-plugin-jsdoc rules, and returns per-file
+ * diagnostics with summary statistics.
+ *
+ * @param selector - Selector information (glob or path)
+ * @param cwd - Working directory for resolving paths
+ * @param limit - Max number of files with issues to include (default 100)
+ * @param gitignore - Whether to respect .gitignore rules (default true)
+ * @returns Lint result with per-file diagnostics and summary
+ * @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);
+}
+/**
+ * Lint an explicit list of file paths for comprehensive JSDoc quality.
+ *
+ * Filters to .ts/.tsx files only (useful for stdin input), then runs
+ * the full lint rule set against each file.
+ *
+ * @param filePaths - List of absolute file paths to lint
+ * @param cwd - Working directory for computing relative paths
+ * @param limit - Max number of files with issues to include (default 100)
+ * @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);
+}

package/dist/selector.js

@@ -0,0 +1,40 @@
+import { JsdocError } from "./errors.js";
+/**
+ * Extracts glob vs. path classification and an optional `@depth` suffix
+ * from selector strings. Float depths are rejected; negative or non-digit
+ * suffixes are left as part of the pattern string. An empty selector
+ * throws INVALID_SELECTOR.
+ *
+ * @summary Parse selector strings into type, pattern, and optional depth components
+ */
+/**
+ * Parses a selector string into its components.
+ *
+ * @param input - Selector string (e.g., "src/star-star/star.ts@3", "file.ts", "../config.js@2")
+ * @returns SelectorInfo with type, pattern, and optional depth
+ * @throws JsdocError INVALID_SELECTOR if input is empty
+ * @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,
+    };
+}

package/dist/skill-text.js

@@ -0,0 +1,244 @@
+/**
+ * Combines the jsdoc skill guidelines with concrete guidance on writing
+ * file-level @summary tags and description paragraphs that pass validation.
+ * SKILL_TEXT is emitted verbatim to stdout when the CLI receives `--skill` / `-s`.
+ * GUIDANCE maps each validation status to a markdown snippet used in validation
+ * output to explain how to fix that category.
+ *
+ * @summary Skill text and per-category guidance constants for JSDoc writing
+ */
+/** Markdown guidance text for each validation status category */
+export const GUIDANCE = {
+    syntax_error: `### Syntax error
+
+The file has TypeScript parse errors that prevent analysis. Fix syntax errors first — no JSDoc validation can run until the file parses cleanly.`,
+    missing_jsdoc: `### Missing file-level JSDoc
+
+Add a \`/** ... */\` block before the first code statement (after imports). This block is what jsdoczoom reads for orientation and validation.
+
+\`\`\`typescript
+import { resolve } from "node:path";
+
+/**
+ * Description paragraph here.
+ *
+ * @summary One-line overview here
+ */
+
+export function example() { ... }
+\`\`\``,
+    missing_summary: `### The @summary tag
+
+The \`@summary\` tag provides a one-line overview — the first thing someone sees when scanning with jsdoczoom at the shallowest depth.
+
+**Important:** Only exact lowercase \`@summary\` is recognized. \`@Summary\`, \`@SUMMARY\`, and other case variants are ignored.
+
+**Good summaries:**
+- State what the file *does* or *is responsible for*, not what it contains
+- Are self-contained — understandable without reading other files
+- Use domain vocabulary consistently with the rest of the codebase
+- Fit on a single line (joined if multi-line in source)
+
+**Examples:**
+- \`@summary Barrel tree model for hierarchical gating in glob mode\`
+- \`@summary Resolve selector patterns to absolute file paths with gitignore filtering\`
+- \`@summary CLI entry point — argument parsing, mode dispatch, and exit code handling\`
+
+**Avoid:**
+- \`@summary This file contains utility functions\` — says what it *contains*, not what it *does*
+- \`@summary Helpers\` — too vague, no domain context
+- \`@summary The main module\` — no information about purpose or scope`,
+    multiple_summary: `### Multiple @summary tags
+
+Each file must have exactly one \`@summary\` tag. Remove the extra \`@summary\` tags and keep a single one-line overview.`,
+    missing_barrel: `### Missing barrel file
+
+Directories with more than 3 TypeScript files should have an \`index.ts\` barrel file. The barrel provides a module-level \`@summary\` and description that helps agents understand what the directory contains before drilling into individual files.
+
+Create an \`index.ts\` that re-exports the directory's public API and add a file-level JSDoc block describing the module's capabilities.`,
+    missing_description: `### The description paragraph
+
+The description is prose that appears before any \`@\` tags. It provides the deeper context that the summary cannot — responsibilities, invariants, trade-offs, and failure modes.
+
+**Good descriptions:**
+- Explain *why* this file exists and what problem it solves
+- State invariants and assumptions that callers or maintainers must know
+- Note trade-offs and design decisions
+- Mention failure modes and edge cases relevant to the file as a whole
+- Are 1–4 sentences, not an essay`,
+};
+export const SKILL_TEXT = `# World-Class JSDoc Guidelines for TypeScript
+
+These guidelines describe the *properties* of excellent inline JSDoc in TypeScript repositories. They are a target to aim for, not a checklist. Use judgment; clarity beats volume.
+
+## Core principle
+
+TypeScript projects already have explicit types. JSDoc should add **intent, behavior, and constraints** rather than repeat what the type system already expresses.
+
+## Would have (high-signal properties)
+
+- **Intent and constraints**: Explains the non-obvious decision, constraint, or tradeoff (e.g., why a particular algorithm is used, why a heuristic exists, or what the runtime environment forbids).
+- **Behavioral contract**: Clearly states what inputs are accepted, what outputs represent, and how boundary cases are treated.
+- **Domain vocabulary**: Uses project-specific terms consistently so readers can navigate the codebase by vocabulary.
+- **Examples that disambiguate**: Includes \`@example\` blocks when behavior is otherwise ambiguous (e.g., parsing rules, path formats, or object schemas). Examples are short and realistic.
+- **Runtime effects**: Calls out side effects, temporal dependency (polling vs. event-driven), filesystem reads/writes, or external service behavior when those matter.
+- **Edge-case prompts**: Captures "what happens if..." questions that a reviewer would ask, especially where external APIs or platform behavior has caveats.
+- **Consistency with existing style**: Matches the formatting conventions already established in the codebase (multi-line descriptions, bullet lists where helpful).
+- **Future-proof hints**: Notes invariants and assumptions that must hold if the code evolves.
+- **LLM-friendly structure**: Uses short, self-contained paragraphs written in clear International Business English. Avoids prescriptive headers (e.g., "Why:", "Constraint:") in favor of natural prose that states context, purpose, and caveats directly.
+
+## Would not have (low-signal or risky properties)
+
+- **Type restatements**: Repeating TypeScript types in prose (e.g., "@param options - The options object" when the type is already \`Options\`). Keep \`@param\`, \`@returns\`, and \`@throws\` tags—just make the descriptions add meaning beyond the type.
+- **Obvious narration**: Comments that paraphrase the code or parameter name without additional insight.
+- **Incorrect authority**: Claims that are not enforced by code (e.g., "never throws" when it can, or "always" without guardrails).
+- **Redundant verbosity**: Long descriptions that could be expressed more directly, or boilerplate that hides the key idea.
+- **Unbounded examples**: Large blocks or full payloads when a minimal example would do.
+- **Out-of-date operational details**: References to tooling, CLI flags, or config knobs that are not enforced or checked.
+- **Implementation leakage**: Unnecessary internal steps or private details that are likely to change and add churn to docs.
+- **Non-ASCII decoration**: Fancy symbols or emojis that do not already exist in the file; keep ASCII unless needed.
+
+## Tag usage cues (not rules)
+
+### IntelliSense tags (always include)
+
+These tags power IDE hover tooltips, autocomplete, and signature help. Always include them for public APIs, constructors, and functions:
+
+- **\`@param\`**: Include for every parameter. Describe the parameter's purpose, valid ranges, or constraints—not just its type.
+- **\`@returns\`**: Include when the function returns a value. Describe what the return value represents, especially for edge cases.
+- **\`@throws\`**: Include when the function can throw. Describe the conditions that cause the error.
+- **\`@template\`**: Include for generic functions and types. Describe what the type parameter represents.
+
+### Cross-reference tags (use to aid navigation)
+
+- **\`@see\`**: Link to related functions, types, or external documentation.
+- **\`{@link Symbol}\`**: Inline reference within descriptions. Creates a clickable link to another symbol.
+
+### Structural tags (use when appropriate)
+
+- Use \`@module\` at the top of files that define a cohesive domain concept.
+- Use \`@example\` when parsing or formatting behavior could be misread, or when a type is complex.
+- Use \`@deprecated\` on exports that are retained for compatibility.
+- Prefer short description + bullets for concepts with multiple facets.
+
+---
+
+## Writing file-level @summary and description
+
+Every TypeScript file should have a file-level JSDoc block before the first code statement. This block is what jsdoczoom reads for orientation and validation.
+
+### Structure
+
+\`\`\`typescript
+/**
+ * Description paragraph goes here. It explains the file's responsibilities,
+ * invariants, trade-offs, and failure modes. This is the deepest level of
+ * native documentation — enough for someone to understand why this file
+ * exists and how it fits into the broader system.
+ *
+ * @summary Concise one-line overview for quick orientation when scanning a codebase.
+ */
+\`\`\`
+
+### The @summary tag
+
+The \`@summary\` tag provides a one-line overview — the first thing someone sees when scanning with jsdoczoom at the shallowest depth.
+
+**Good summaries:**
+- State what the file *does* or *is responsible for*, not what it contains
+- Are self-contained — understandable without reading other files
+- Use domain vocabulary consistently with the rest of the codebase
+- Fit on a single line (joined if multi-line in source)
+
+**Examples:**
+- \`@summary Barrel tree model for hierarchical gating in glob mode\`
+- \`@summary Resolve selector patterns to absolute file paths with gitignore filtering\`
+- \`@summary CLI entry point — argument parsing, mode dispatch, and exit code handling\`
+
+**Avoid:**
+- \`@summary This file contains utility functions\` — says what it *contains*, not what it *does*
+- \`@summary Helpers\` — too vague, no domain context
+- \`@summary The main module\` — no information about purpose or scope
+
+### The description paragraph
+
+The description is prose that appears before any \`@\` tags. It provides the deeper context that the summary cannot — responsibilities, invariants, trade-offs, and failure modes.
+
+**Good descriptions:**
+- Explain *why* this file exists and what problem it solves
+- State invariants and assumptions that callers or maintainers must know
+- Note trade-offs and design decisions (e.g., "uses priority-order fill to keep the limit algorithm simple")
+- Mention failure modes and edge cases relevant to the file as a whole
+- Are 1-4 sentences, not an essay
+
+**Examples:**
+\`\`\`typescript
+/**
+ * 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
+ */
+\`\`\`
+
+\`\`\`typescript
+/**
+ * Each file is classified into exactly one status category: the first
+ * failing check wins (syntax_error > missing_jsdoc > missing_summary >
+ * missing_description). Valid files are omitted from output entirely.
+ * The limit parameter caps the total number of invalid paths shown,
+ * filled in priority order across groups.
+ *
+ * @summary Validate file-level JSDoc and group results by status category
+ */
+\`\`\`
+
+**Avoid:**
+- Restating the summary in longer words
+- Listing every function in the file
+- Implementation details that change frequently (line numbers, internal variable names)
+
+### Barrel files (index.ts / index.tsx)
+
+Barrel files represent their directory. The \`@summary\` and description describe the module, not individual files.
+
+- **\`@summary\`**: What the module does as a unit
+- **Description**: The module's capabilities and concerns — describe concepts, not child filenames
+
+\`\`\`typescript
+// packages/auth/src/index.ts
+/**
+ * Provides session lifecycle management, token validation and refresh,
+ * and middleware for route-level access control. OAuth2 provider
+ * integration is handled here; cryptographic primitives are delegated
+ * to the crypto package.
+ *
+ * @summary Authentication and authorization module
+ */
+\`\`\`
+
+**Avoid:**
+- Listing child filenames in the description
+- \`@summary Exports for the auth module\` — describes the mechanism, not the purpose
+- \`@summary Index file\` — no information about what the module does
+
+### Placement
+
+The file-level JSDoc block must appear **before the first code statement** (imports are fine above it, but the block must precede any \`export\`, \`const\`, \`function\`, \`class\`, etc.). A common pattern is to place it immediately after imports:
+
+\`\`\`typescript
+import { resolve } from "node:path";
+import { globSync } from "glob";
+
+/**
+ * Description paragraph here.
+ *
+ * @summary One-line overview here
+ */
+
+export function discoverFiles(...) { ... }
+\`\`\`
+
+`;

package/dist/type-declarations.js

@@ -0,0 +1,101 @@
+import { readFileSync } from "node:fs";
+import ts from "typescript";
+import { JsdocError } from "./errors.js";
+/**
+ * Produces .d.ts-like output from a TypeScript source file using the
+ * TypeScript compiler's declaration emit. Preserves JSDoc comments and
+ * source order while stripping implementation bodies and non-exported
+ * internals.
+ *
+ * @summary Generate TypeScript declaration output from source files
+ */
+/**
+ * Generates TypeScript declaration output from a source file.
+ *
+ * Produces .d.ts-like output containing:
+ * - All exported type aliases, interfaces, enums
+ * - All exported function signatures (no implementation bodies)
+ * - All exported const/let/var declarations (type signatures only)
+ * - All exported class declarations (signatures only, no method bodies)
+ * - All JSDoc comments preserved
+ * - Source order maintained
+ *
+ * Excludes:
+ * - Import statements
+ * - Non-exported internals
+ *
+ * @param filePath - Absolute path to the TypeScript source file
+ * @returns The declaration output as a string
+ * @throws {JsdocError} If the file cannot be read or parsed
+ */
+export function generateTypeDeclarations(filePath) {
+    let sourceText;
+    try {
+        sourceText = readFileSync(filePath, "utf-8");
+    }
+    catch (_error) {
+        throw new JsdocError("FILE_NOT_FOUND", `Failed to read file: ${filePath}`);
+    }
+    // Create compiler options matching the project setup
+    const compilerOptions = {
+        declaration: true,
+        emitDeclarationOnly: true,
+        target: ts.ScriptTarget.Latest,
+        module: ts.ModuleKind.NodeNext,
+        moduleResolution: ts.ModuleResolutionKind.NodeNext,
+        skipLibCheck: true,
+        removeComments: false, // Preserve JSDoc comments
+    };
+    // Create a custom compiler host that provides our file
+    const host = ts.createCompilerHost(compilerOptions);
+    const originalGetSourceFile = host.getSourceFile;
+    host.getSourceFile = (fileName, languageVersion, onError, shouldCreateNewSourceFile) => {
+        if (fileName === filePath) {
+            return ts.createSourceFile(fileName, sourceText, languageVersion, true);
+        }
+        return originalGetSourceFile.call(host, fileName, languageVersion, onError, shouldCreateNewSourceFile);
+    };
+    // Capture emitted output
+    let declarationOutput = "";
+    host.writeFile = (fileName, data) => {
+        if (fileName.endsWith(".d.ts")) {
+            declarationOutput = data;
+        }
+    };
+    // Create program and emit declarations
+    const program = ts.createProgram([filePath], compilerOptions, host);
+    const sourceFile = program.getSourceFile(filePath);
+    if (!sourceFile) {
+        throw new JsdocError("PARSE_ERROR", `Failed to parse file: ${filePath}`);
+    }
+    const emitResult = program.emit(sourceFile, undefined, undefined, true);
+    // Check for emit errors
+    const diagnostics = ts
+        .getPreEmitDiagnostics(program)
+        .concat(emitResult.diagnostics);
+    if (diagnostics.length > 0) {
+        const errors = diagnostics
+            .map((diagnostic) => {
+            if (diagnostic.file && diagnostic.start !== undefined) {
+                const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
+                const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
+                return `${diagnostic.file.fileName} (${line + 1},${character + 1}): ${message}`;
+            }
+            return ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
+        })
+            .join("\n");
+        throw new JsdocError("PARSE_ERROR", `TypeScript errors:\n${errors}`);
+    }
+    if (!declarationOutput) {
+        // If no output was generated, the file may have no exports
+        // Return empty string in this case
+        return "";
+    }
+    // Clean up the output
+    let cleaned = declarationOutput;
+    // Remove empty export statement if present and no other exports
+    if (cleaned.trim() === "export {};") {
+        cleaned = "";
+    }
+    return cleaned;
+}

package/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * Defines the output shapes, error codes, validation statuses, and
+ * parsed-file structures used across all modules. These types form the
+ * public contract for both JSON output and programmatic API consumers.
+ *
+ * @summary Shared type definitions for output shapes, error codes, and parsed structures
+ */
+/** Priority order for validation status categories */
+export const VALIDATION_STATUS_PRIORITY = [
+    "syntax_error",
+    "missing_jsdoc",
+    "missing_summary",
+    "multiple_summary",
+    "missing_description",
+    "missing_barrel",
+];

package/dist/validate.js

@@ -0,0 +1,122 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { isBarrel } from "./barrel.js";
+import { JsdocError } from "./errors.js";
+import { createValidationLinter, lintFileForValidation, mapToValidationStatus, } from "./eslint-engine.js";
+import { discoverFiles } from "./file-discovery.js";
+import { GUIDANCE } from "./skill-text.js";
+import { VALIDATION_STATUS_PRIORITY } from "./types.js";
+/**
+ * Classify a single file against validation requirements.
+ *
+ * Reads the file, lints it with the ESLint engine, and maps the
+ * resulting messages to a single ValidationStatus using priority order.
+ */
+async function classifyFile(eslint, filePath, cwd) {
+    const relativePath = relative(cwd, filePath);
+    let sourceText;
+    try {
+        sourceText = readFileSync(filePath, "utf-8");
+    }
+    catch {
+        throw new JsdocError("FILE_NOT_FOUND", `File not found: ${filePath}`);
+    }
+    const messages = await lintFileForValidation(eslint, sourceText, filePath);
+    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.
+ */
+function buildGroupedResult(statuses, missingBarrels, limit) {
+    const groups = {
+        syntax_error: [],
+        missing_jsdoc: [],
+        missing_summary: [],
+        multiple_summary: [],
+        missing_description: [],
+        missing_barrel: missingBarrels,
+    };
+    for (const { path, status } of statuses) {
+        if (status !== "valid") {
+            groups[status].push(path);
+        }
+    }
+    const result = {};
+    let remaining = limit;
+    for (const status of VALIDATION_STATUS_PRIORITY) {
+        const files = groups[status];
+        if (files.length === 0)
+            continue;
+        if (remaining <= 0)
+            break;
+        const slice = files.slice(0, remaining);
+        result[status] = { guidance: GUIDANCE[status], files: slice };
+        remaining -= slice.length;
+    }
+    return result;
+}
+/**
+ * Validate files matching a selector pattern.
+ *
+ * @param selector - Selector information (glob or path)
+ * @param cwd - Working directory for resolving paths
+ * @param limit - Max number of invalid file paths to include (default 100)
+ * @returns Grouped validation results
+ * @throws {JsdocError} NO_FILES_MATCHED if glob selector matches no files
+ * @throws {JsdocError} FILE_NOT_FOUND if path selector targets nonexistent file
+ */
+export async function validate(selector, cwd, limit = 100, gitignore = true) {
+    const files = discoverFiles(selector.pattern, cwd, gitignore);
+    if (files.length === 0) {
+        throw new JsdocError("NO_FILES_MATCHED", `No files matched: ${selector.pattern}`);
+    }
+    const eslint = createValidationLinter();
+    const statuses = await Promise.all(files.map((f) => classifyFile(eslint, f, cwd)));
+    const missingBarrels = findMissingBarrels(files, cwd);
+    return buildGroupedResult(statuses, missingBarrels, limit);
+}
+/**
+ * Validate an explicit list of file paths.
+ *
+ * Filters to .ts/.tsx files only (useful for stdin input).
+ *
+ * @param filePaths - List of file paths to validate
+ * @param cwd - Working directory for resolving relative paths
+ * @param limit - Max number of invalid file paths to include (default 100)
+ * @returns Grouped validation results
+ */
+export async function validateFiles(filePaths, cwd, limit = 100) {
+    const tsFiles = filePaths.filter((f) => f.endsWith(".ts") || f.endsWith(".tsx"));
+    const eslint = createValidationLinter();
+    const statuses = await Promise.all(tsFiles.map((f) => classifyFile(eslint, f, cwd)));
+    const missingBarrels = findMissingBarrels(tsFiles, cwd);
+    return buildGroupedResult(statuses, missingBarrels, limit);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "jsdoczoom",
+	"version": "0.1.0",
+	"description": "CLI tool for extracting JSDoc summaries at configurable depths",
+	"type": "module",
+	"sideEffects": false,
+	"engines": {
+		"node": ">=20.11.0"
+	},
+	"files": [
+		"dist",
+		"types"
+	],
+	"bin": "./dist/cli.js",
+	"publishConfig": {
+		"bin": {
+			"jsdoczoom": "./dist/cli.js"
+		}
+	},
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./types/index.d.ts"
+		},
+		"./*": {
+			"import": "./dist/*.js",
+			"types": "./types/*.d.ts"
+		}
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"build": "tsc --build tsconfig.build.json",
+		"test": "vitest run",
+		"lint": "biome check --write --unsafe --max-diagnostics 500 .",
+		"release": "bash ../../scripts/release-package.sh jsdoczoom",
+		"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",
+		"ignore": "^7.0.5",
+		"typescript": "^5.9.3"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.3.14",
+		"@types/node": "^24",
+		"vitest": "4.0.13"
+	}
+}