jsdoczoom 0.1.0

package/types/barrel.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Barrel detection and child discovery for index.ts/index.tsx files.
+ * A barrel is strictly `index.ts` or `index.tsx`; other index variants
+ * (e.g. `index.test.ts`, `index.d.ts`) are excluded. Children include
+ * sibling .ts/.tsx files and child barrels in immediate subdirectories,
+ * with index.ts taking priority over index.tsx in the same subdirectory.
+ *
+ * @summary Detect barrel files and discover their children for drill-down gating
+ */
+/**
+ * Check if a file path refers to a barrel file (index.ts or index.tsx).
+ *
+ * A barrel is a file named exactly `index.ts` or `index.tsx`.
+ * Files like `index.test.ts`, `index.d.ts`, `index.stories.tsx` are NOT barrels.
+ *
+ * @param filePath - Absolute or relative file path to check
+ * @returns true if the file is a barrel (index.ts or index.tsx)
+ */
+export declare function isBarrel(filePath: string): boolean;
+/**
+ * Discover the children of a barrel file.
+ *
+ * Children include:
+ * - Sibling .ts/.tsx files in the same directory (excluding the barrel itself, excluding .d.ts)
+ * - Child barrels (index.ts or index.tsx) in immediate subdirectories
+ *   - index.ts takes priority over index.tsx in the same subdirectory
+ *
+ * @param barrelPath - Absolute path to the barrel file (index.ts or index.tsx)
+ * @param _cwd - Working directory (unused, kept for API consistency)
+ * @returns Sorted array of absolute paths to child files
+ */
+export declare function getBarrelChildren(barrelPath: string, _cwd: string): string[];

package/types/cli.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+/**
+ * Main CLI entry point. Exported for testability.
+ */
+export declare function main(args: string[], stdin?: string): Promise<void>;

package/types/drilldown.d.ts

@@ -0,0 +1,28 @@
+import type { DrilldownResult, SelectorInfo } from "./types.js";
+/**
+ * Main entry point for normal-mode processing.
+ *
+ * Resolves files from a selector, processes each through the drill-down model,
+ * and returns an array of output entries. Barrel gating is applied in glob mode.
+ * Depth is 1-indexed (default 1).
+ *
+ * @param selector - Parsed selector with type, pattern, and optional depth
+ * @param cwd - Working directory for file resolution
+ * @returns Array of output entries sorted alphabetically by path
+ * @throws {JsdocError} FILE_NOT_FOUND for missing path selector target
+ * @throws {JsdocError} NO_FILES_MATCHED for empty glob results
+ * @throws {JsdocError} PARSE_ERROR for path selector targeting file with syntax errors
+ */
+export declare function drilldown(selector: SelectorInfo, cwd: string, gitignore?: boolean, limit?: number): DrilldownResult;
+/**
+ * Process an explicit list of file paths at a given depth.
+ *
+ * Used for stdin input. Always treats paths as leaf files (no barrel gating).
+ * Filters to .ts/.tsx only. Depth is 1-indexed (default 1).
+ *
+ * @param filePaths - Array of absolute file paths
+ * @param depth - Drill-down depth, 1-indexed (defaults to 1 if undefined)
+ * @param cwd - Working directory for relative path output
+ * @returns Array of output entries sorted alphabetically by path
+ */
+export declare function drilldownFiles(filePaths: string[], depth: number | undefined, cwd: string, limit?: number): DrilldownResult;

package/types/errors.d.ts

@@ -0,0 +1,19 @@
+import type { ErrorCode } from "./types.js";
+/**
+ * JsdocError extends Error with an error code and serializes to the
+ * `{ error: { code, message } }` JSON shape. This is the single error type
+ * used across the entire tool for both programmatic and CLI error output.
+ *
+ * @summary Structured error type with JSON serialization for CLI and programmatic use
+ */
+/** Custom error class that serializes to the documented JSON error contract */
+export declare class JsdocError extends Error {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string);
+    toJSON(): {
+        error: {
+            code: ErrorCode;
+            message: string;
+        };
+    };
+}

package/types/eslint-engine.d.ts

@@ -0,0 +1,65 @@
+/**
+ * ESLint validation engine for jsdoczoom.
+ *
+ * @summary Bridge between ESLint API and jsdoczoom validation/lint formats
+ */
+import { ESLint } from "eslint";
+import type { LintDiagnostic, ValidationStatus } from "./types.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 declare function createValidationLinter(): 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 declare function createLintLinter(cwd?: string): 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 declare function lintFileForValidation(eslint: ESLint, sourceText: string, filePath: string): Promise<Array<{
+    ruleId: string | null;
+    messageId?: string;
+    fatal?: boolean;
+}>>;
+/**
+ * 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 declare function lintFileForLint(eslint: ESLint, sourceText: string, filePath: string): Promise<LintDiagnostic[]>;
+/**
+ * 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 declare function mapToValidationStatus(messages: Array<{
+    ruleId: string | null;
+    messageId?: string;
+    fatal?: boolean;
+}>): ValidationStatus | "valid";

package/types/eslint-plugin.d.ts

@@ -0,0 +1,9 @@
+import type { Rule } from "eslint";
+declare const plugin: {
+    readonly rules: {
+        readonly "require-file-jsdoc": Rule.RuleModule;
+        readonly "require-file-summary": Rule.RuleModule;
+        readonly "require-file-description": Rule.RuleModule;
+    };
+};
+export default plugin;

package/types/file-discovery.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 declare function discoverFiles(pattern: string, cwd: string, gitignore?: boolean): string[];

package/types/index.d.ts

@@ -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 { type DrilldownResult, type ErrorCode, type LintDiagnostic, type LintFileResult, type LintResult, type OutputEntry, type OutputErrorItem, type OutputItem, type OutputItemNext, type OutputItemTerminal, type ParsedFileInfo, type SelectorInfo, VALIDATION_STATUS_PRIORITY, type ValidationGroup, type ValidationResult, type ValidationStatus, } from "./types.js";
+export { validate, validateFiles } from "./validate.js";

package/types/jsdoc-parser.d.ts

@@ -0,0 +1,24 @@
+import type { ParsedFileInfo } from "./types.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 declare function extractFileJsdoc(sourceText: string): string | null;
+/**
+ * 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 declare function parseFileSummaries(filePath: string): ParsedFileInfo;

package/types/lint.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 type { LintResult, SelectorInfo } from "./types.js";
+/**
+ * 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 declare function lint(selector: SelectorInfo, cwd: string, limit?: number, gitignore?: boolean): Promise<LintResult>;
+/**
+ * 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 declare function lintFiles(filePaths: string[], cwd: string, limit?: number): Promise<LintResult>;

package/types/selector.d.ts

@@ -0,0 +1,18 @@
+import type { SelectorInfo } from "./types.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 declare function parseSelector(input: string): SelectorInfo;

package/types/skill-text.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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
+ */
+import type { ValidationStatus } from "./types.js";
+/** Markdown guidance text for each validation status category */
+export declare const GUIDANCE: Record<ValidationStatus, string>;
+export declare const SKILL_TEXT = "# World-Class JSDoc Guidelines for TypeScript\n\nThese 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.\n\n## Core principle\n\nTypeScript projects already have explicit types. JSDoc should add **intent, behavior, and constraints** rather than repeat what the type system already expresses.\n\n## Would have (high-signal properties)\n\n- **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).\n- **Behavioral contract**: Clearly states what inputs are accepted, what outputs represent, and how boundary cases are treated.\n- **Domain vocabulary**: Uses project-specific terms consistently so readers can navigate the codebase by vocabulary.\n- **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.\n- **Runtime effects**: Calls out side effects, temporal dependency (polling vs. event-driven), filesystem reads/writes, or external service behavior when those matter.\n- **Edge-case prompts**: Captures \"what happens if...\" questions that a reviewer would ask, especially where external APIs or platform behavior has caveats.\n- **Consistency with existing style**: Matches the formatting conventions already established in the codebase (multi-line descriptions, bullet lists where helpful).\n- **Future-proof hints**: Notes invariants and assumptions that must hold if the code evolves.\n- **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.\n\n## Would not have (low-signal or risky properties)\n\n- **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\u2014just make the descriptions add meaning beyond the type.\n- **Obvious narration**: Comments that paraphrase the code or parameter name without additional insight.\n- **Incorrect authority**: Claims that are not enforced by code (e.g., \"never throws\" when it can, or \"always\" without guardrails).\n- **Redundant verbosity**: Long descriptions that could be expressed more directly, or boilerplate that hides the key idea.\n- **Unbounded examples**: Large blocks or full payloads when a minimal example would do.\n- **Out-of-date operational details**: References to tooling, CLI flags, or config knobs that are not enforced or checked.\n- **Implementation leakage**: Unnecessary internal steps or private details that are likely to change and add churn to docs.\n- **Non-ASCII decoration**: Fancy symbols or emojis that do not already exist in the file; keep ASCII unless needed.\n\n## Tag usage cues (not rules)\n\n### IntelliSense tags (always include)\n\nThese tags power IDE hover tooltips, autocomplete, and signature help. Always include them for public APIs, constructors, and functions:\n\n- **`@param`**: Include for every parameter. Describe the parameter's purpose, valid ranges, or constraints\u2014not just its type.\n- **`@returns`**: Include when the function returns a value. Describe what the return value represents, especially for edge cases.\n- **`@throws`**: Include when the function can throw. Describe the conditions that cause the error.\n- **`@template`**: Include for generic functions and types. Describe what the type parameter represents.\n\n### Cross-reference tags (use to aid navigation)\n\n- **`@see`**: Link to related functions, types, or external documentation.\n- **`{@link Symbol}`**: Inline reference within descriptions. Creates a clickable link to another symbol.\n\n### Structural tags (use when appropriate)\n\n- Use `@module` at the top of files that define a cohesive domain concept.\n- Use `@example` when parsing or formatting behavior could be misread, or when a type is complex.\n- Use `@deprecated` on exports that are retained for compatibility.\n- Prefer short description + bullets for concepts with multiple facets.\n\n---\n\n## Writing file-level @summary and description\n\nEvery TypeScript file should have a file-level JSDoc block before the first code statement. This block is what jsdoczoom reads for orientation and validation.\n\n### Structure\n\n```typescript\n/**\n * Description paragraph goes here. It explains the file's responsibilities,\n * invariants, trade-offs, and failure modes. This is the deepest level of\n * native documentation \u2014 enough for someone to understand why this file\n * exists and how it fits into the broader system.\n *\n * @summary Concise one-line overview for quick orientation when scanning a codebase.\n */\n```\n\n### The @summary tag\n\nThe `@summary` tag provides a one-line overview \u2014 the first thing someone sees when scanning with jsdoczoom at the shallowest depth.\n\n**Good summaries:**\n- State what the file *does* or *is responsible for*, not what it contains\n- Are self-contained \u2014 understandable without reading other files\n- Use domain vocabulary consistently with the rest of the codebase\n- Fit on a single line (joined if multi-line in source)\n\n**Examples:**\n- `@summary Barrel tree model for hierarchical gating in glob mode`\n- `@summary Resolve selector patterns to absolute file paths with gitignore filtering`\n- `@summary CLI entry point \u2014 argument parsing, mode dispatch, and exit code handling`\n\n**Avoid:**\n- `@summary This file contains utility functions` \u2014 says what it *contains*, not what it *does*\n- `@summary Helpers` \u2014 too vague, no domain context\n- `@summary The main module` \u2014 no information about purpose or scope\n\n### The description paragraph\n\nThe description is prose that appears before any `@` tags. It provides the deeper context that the summary cannot \u2014 responsibilities, invariants, trade-offs, and failure modes.\n\n**Good descriptions:**\n- Explain *why* this file exists and what problem it solves\n- State invariants and assumptions that callers or maintainers must know\n- Note trade-offs and design decisions (e.g., \"uses priority-order fill to keep the limit algorithm simple\")\n- Mention failure modes and edge cases relevant to the file as a whole\n- Are 1-4 sentences, not an essay\n\n**Examples:**\n```typescript\n/**\n * Walks .gitignore files from cwd to filesystem root, building an ignore\n * filter that glob results pass through. Direct-path lookups bypass the\n * filter since the user explicitly named the file. The ignore instance is\n * created per call \u2014 no caching \u2014 because cwd may differ between invocations.\n *\n * @summary Resolve selector patterns to absolute file paths with gitignore filtering\n */\n```\n\n```typescript\n/**\n * Each file is classified into exactly one status category: the first\n * failing check wins (syntax_error > missing_jsdoc > missing_summary >\n * missing_description). Valid files are omitted from output entirely.\n * The limit parameter caps the total number of invalid paths shown,\n * filled in priority order across groups.\n *\n * @summary Validate file-level JSDoc and group results by status category\n */\n```\n\n**Avoid:**\n- Restating the summary in longer words\n- Listing every function in the file\n- Implementation details that change frequently (line numbers, internal variable names)\n\n### Barrel files (index.ts / index.tsx)\n\nBarrel files represent their directory. The `@summary` and description describe the module, not individual files.\n\n- **`@summary`**: What the module does as a unit\n- **Description**: The module's capabilities and concerns \u2014 describe concepts, not child filenames\n\n```typescript\n// packages/auth/src/index.ts\n/**\n * Provides session lifecycle management, token validation and refresh,\n * and middleware for route-level access control. OAuth2 provider\n * integration is handled here; cryptographic primitives are delegated\n * to the crypto package.\n *\n * @summary Authentication and authorization module\n */\n```\n\n**Avoid:**\n- Listing child filenames in the description\n- `@summary Exports for the auth module` \u2014 describes the mechanism, not the purpose\n- `@summary Index file` \u2014 no information about what the module does\n\n### Placement\n\nThe 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:\n\n```typescript\nimport { resolve } from \"node:path\";\nimport { globSync } from \"glob\";\n\n/**\n * Description paragraph here.\n *\n * @summary One-line overview here\n */\n\nexport function discoverFiles(...) { ... }\n```\n\n";

package/types/type-declarations.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 declare function generateTypeDeclarations(filePath: string): string;

package/types/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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
+ */
+/** Output item with more detail available — next_id points to the next level */
+export interface OutputItemNext {
+    next_id: string;
+    text: string;
+    children?: string[];
+}
+/** Output item at terminal level — id represents the current (final) state */
+export interface OutputItemTerminal {
+    id: string;
+    text: string;
+}
+/** Single output item representing a file at a specific drill-down level */
+export type OutputItem = OutputItemNext | OutputItemTerminal;
+/** Output item for files that encountered errors during processing */
+export interface OutputErrorItem {
+    id: string;
+    error: {
+        code: string;
+        message: string;
+    };
+}
+/** Union of successful and error output entries */
+export type OutputEntry = OutputItem | OutputErrorItem;
+/** Drilldown result with items and truncation flag */
+export interface DrilldownResult {
+    items: OutputEntry[];
+    truncated: boolean;
+}
+/** All recognized error codes */
+export type ErrorCode = "INVALID_SELECTOR" | "INVALID_DEPTH" | "FILE_NOT_FOUND" | "NO_FILES_MATCHED" | "PARSE_ERROR" | "VALIDATION_FAILED" | "INTERNAL_ERROR";
+/** Validation status categories for invalid files */
+export type ValidationStatus = "syntax_error" | "missing_jsdoc" | "missing_summary" | "multiple_summary" | "missing_description" | "missing_barrel";
+/** Priority order for validation status categories */
+export declare const VALIDATION_STATUS_PRIORITY: ValidationStatus[];
+/** A validation group: guidance text and file paths */
+export interface ValidationGroup {
+    guidance: string;
+    files: string[];
+}
+/** Grouped validation result — only invalid-file groups appear */
+export interface ValidationResult {
+    syntax_error?: ValidationGroup;
+    missing_jsdoc?: ValidationGroup;
+    missing_summary?: ValidationGroup;
+    multiple_summary?: ValidationGroup;
+    missing_description?: ValidationGroup;
+    missing_barrel?: ValidationGroup;
+}
+/** Parsed summary and description from a file's JSDoc */
+export interface ParsedFileInfo {
+    path: string;
+    summary: string | null;
+    description: string | null;
+    summaryCount: number;
+    hasFileJsdoc: boolean;
+}
+/** Parsed selector information */
+export interface SelectorInfo {
+    type: "glob" | "path";
+    pattern: string;
+    depth: number | undefined;
+}
+/** A single lint diagnostic from ESLint */
+export interface LintDiagnostic {
+    line: number;
+    column: number;
+    rule: string;
+    message: string;
+    severity: "error" | "warning";
+}
+/** Lint result for a single file */
+export interface LintFileResult {
+    filePath: string;
+    diagnostics: LintDiagnostic[];
+}
+/** Overall lint result with summary statistics */
+export interface LintResult {
+    files: LintFileResult[];
+    summary: {
+        totalFiles: number;
+        filesWithIssues: number;
+        totalDiagnostics: number;
+    };
+}

package/types/validate.d.ts

@@ -0,0 +1,23 @@
+import type { SelectorInfo, ValidationResult } from "./types.js";
+/**
+ * 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 declare function validate(selector: SelectorInfo, cwd: string, limit?: number, gitignore?: boolean): Promise<ValidationResult>;
+/**
+ * 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 declare function validateFiles(filePaths: string[], cwd: string, limit?: number): Promise<ValidationResult>;