jsdoczoom 0.1.0

package/dist/barrel.js

@@ -0,0 +1,84 @@
+import { existsSync, readdirSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+/**
+ * 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 function isBarrel(filePath) {
+    const name = basename(filePath);
+    return name === "index.ts" || name === "index.tsx";
+}
+/**
+ * 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 function getBarrelChildren(barrelPath, _cwd) {
+    const dir = dirname(barrelPath);
+    const barrelName = basename(barrelPath);
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true })
+            .map((e) => ({ name: e.name, isDirectory: e.isDirectory() }))
+            .flatMap((entry) => {
+            if (entry.isDirectory) {
+                // Check for child barrel in this subdirectory
+                const childBarrel = findChildBarrel(resolve(dir, entry.name));
+                return childBarrel ? [childBarrel] : [];
+            }
+            // Sibling file: must be .ts/.tsx, not .d.ts, not the barrel itself
+            if (isTsFile(entry.name) && entry.name !== barrelName) {
+                return [resolve(dir, entry.name)];
+            }
+            return [];
+        });
+    }
+    catch {
+        // Directory unreadable (permissions, deleted, etc.) — no children discoverable
+        return [];
+    }
+    return entries.sort();
+}
+/**
+ * Check if a filename is a .ts or .tsx file (excluding .d.ts).
+ */
+function isTsFile(name) {
+    return ((name.endsWith(".ts") || name.endsWith(".tsx")) && !name.endsWith(".d.ts"));
+}
+/**
+ * Find the barrel file in a subdirectory.
+ * index.ts takes priority over index.tsx.
+ * Returns the absolute path to the barrel, or null if none found.
+ */
+function findChildBarrel(subdirPath) {
+    const tsPath = resolve(subdirPath, "index.ts");
+    if (existsSync(tsPath)) {
+        return tsPath;
+    }
+    const tsxPath = resolve(subdirPath, "index.tsx");
+    if (existsSync(tsxPath)) {
+        return tsxPath;
+    }
+    return null;
+}

package/dist/cli.js

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { drilldown, drilldownFiles } from "./drilldown.js";
+import { JsdocError } from "./errors.js";
+import { lint } from "./lint.js";
+import { parseSelector } from "./selector.js";
+import { SKILL_TEXT } from "./skill-text.js";
+import { VALIDATION_STATUS_PRIORITY } from "./types.js";
+import { validate } from "./validate.js";
+/**
+ * Parses argv flags (--help, --validate, --lint, --skill, --pretty, --limit,
+ * --no-gitignore), dispatches to drilldown, validation, or lint mode, and
+ * handles stdin piping. Errors are written to stderr as JSON; validation and
+ * lint failures use exit code 2 while other errors use exit code 1.
+ *
+ * @summary CLI entry point -- argument parsing, mode dispatch, and exit code handling
+ */
+const HELP_TEXT = `Usage: jsdoczoom [options] [selector]
+
+Progressively explore TypeScript codebase documentation.
+Each file has four detail levels (1-indexed): @1 summary, @2 description,
+@3 type declarations, @4 full source. Higher depth = more detail.
+
+Options:
+  -h, --help       Show this help text
+  -v, --validate   Run validation mode
+  -l, --lint       Run lint mode (comprehensive JSDoc quality)
+  -s, --skill      Print JSDoc writing guidelines
+  --pretty         Format JSON output with 2-space indent
+  --limit N        Max results shown (default 100)
+  --no-gitignore   Include files ignored by .gitignore
+
+Selector:
+  A glob pattern or file path, optionally with @depth suffix (1-4).
+  Examples:
+    jsdoczoom src/**/*.ts       # All .ts files at depth 1 (summary)
+    jsdoczoom src/index.ts@2    # Single file at depth 2 (description)
+    jsdoczoom **/*.ts@3         # All .ts files at depth 3 (type decls)
+
+Stdin:
+  Pipe file paths one per line:
+    find . -name "*.ts" | jsdoczoom
+    find . -name "*.ts" | jsdoczoom @2
+    find . -name "*.ts" | jsdoczoom -v
+
+Output:
+  JSON items. Items with "next_id" have more detail; use that value as the next
+  selector. Items with "id" (no next_id) are at terminal depth.
+
+Barrel gating (glob mode):
+  index.ts files with a @summary gate sibling files at depths 1-2.
+  At depth 3 the barrel disappears and its children appear at depth 1.
+
+Workflow:
+  $ jsdoczoom src/**/*.ts
+  { "items": [{ "next_id": "src/utils@2", "text": "..." }, ...] }
+
+  $ jsdoczoom src/utils@2                # use next_id from above
+  { "items": [{ "next_id": "src/utils@3", "text": "..." }] }
+
+  $ jsdoczoom src/utils@3                # use next_id again
+  { "items": [{ "id": "src/utils@3", "text": "..." }] }
+  # "id" instead of "next_id" means terminal depth — stop here
+`;
+/**
+ * Parse CLI arguments into flags and positional args.
+ */
+function parseArgs(args) {
+    let help = false;
+    let validateMode = false;
+    let lintMode = false;
+    let skillMode = false;
+    let pretty = false;
+    let limit = 100;
+    let gitignore = true;
+    let selectorArg;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "-h" || arg === "--help") {
+            help = true;
+        }
+        else if (arg === "-v" || arg === "--validate") {
+            validateMode = true;
+        }
+        else if (arg === "-l" || arg === "--lint") {
+            lintMode = true;
+        }
+        else if (arg === "-s" || arg === "--skill") {
+            skillMode = true;
+        }
+        else if (arg === "--pretty") {
+            pretty = true;
+        }
+        else if (arg === "--limit") {
+            const next = args[++i];
+            limit = Number(next);
+        }
+        else if (arg === "--no-gitignore") {
+            gitignore = false;
+        }
+        else if (arg.startsWith("-")) {
+            throw new JsdocError("INVALID_SELECTOR", `Unrecognized option: ${arg}`);
+        }
+        else if (selectorArg === undefined) {
+            selectorArg = arg;
+        }
+    }
+    return {
+        help,
+        validateMode,
+        lintMode,
+        skillMode,
+        pretty,
+        limit,
+        gitignore,
+        selectorArg,
+    };
+}
+/**
+ * Resolve stdin file paths to absolute paths.
+ */
+function parseStdinPaths(stdin, cwd) {
+    return stdin
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => resolve(cwd, line));
+}
+/**
+ * Extract depth from a selector argument string.
+ * Returns undefined if no @depth suffix is present.
+ */
+function extractDepthFromArg(selectorArg) {
+    const parsed = parseSelector(selectorArg);
+    return parsed.depth;
+}
+/**
+ * Process stdin mode: file paths piped in.
+ */
+async function processStdin(stdin, selectorArg, validateMode, lintMode, pretty, limit, cwd) {
+    const stdinPaths = parseStdinPaths(stdin, cwd);
+    const depth = selectorArg !== undefined ? extractDepthFromArg(selectorArg) : undefined;
+    if (lintMode) {
+        const { lintFiles } = await import("./lint.js");
+        const result = await lintFiles(stdinPaths, cwd, limit);
+        writeLintResult(result, pretty);
+    }
+    else if (validateMode) {
+        const { validateFiles } = await import("./validate.js");
+        const result = await validateFiles(stdinPaths, cwd, limit);
+        writeValidationResult(result, pretty);
+    }
+    else {
+        const result = drilldownFiles(stdinPaths, depth, cwd, limit);
+        writeResult(result, pretty);
+    }
+}
+/**
+ * Process selector mode: glob or path argument.
+ */
+async function processSelector(selectorArg, validateMode, lintMode, pretty, limit, gitignore, cwd) {
+    const selector = selectorArg
+        ? parseSelector(selectorArg)
+        : { type: "glob", pattern: "**/*.{ts,tsx}", depth: undefined };
+    if (lintMode) {
+        const result = await lint(selector, cwd, limit, gitignore);
+        writeLintResult(result, pretty);
+    }
+    else if (validateMode) {
+        const result = await validate(selector, cwd, limit, gitignore);
+        writeValidationResult(result, pretty);
+    }
+    else {
+        const result = drilldown(selector, cwd, gitignore, limit);
+        writeResult(result, pretty);
+    }
+}
+/**
+ * Write an error to stderr as JSON and set exit code.
+ */
+function writeError(error) {
+    if (error instanceof JsdocError) {
+        process.stderr.write(`${JSON.stringify(error.toJSON())}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${JSON.stringify({ error: { code: "INTERNAL_ERROR", message } })}\n`);
+    process.exitCode = 1;
+}
+/**
+ * Main CLI entry point. Exported for testability.
+ */
+export async function main(args, stdin) {
+    try {
+        const { help, validateMode, lintMode, skillMode, pretty, limit, gitignore, selectorArg, } = parseArgs(args);
+        if (help) {
+            process.stdout.write(HELP_TEXT);
+            return;
+        }
+        if (skillMode) {
+            process.stdout.write(SKILL_TEXT);
+            return;
+        }
+        if (validateMode && lintMode) {
+            writeError(new JsdocError("INVALID_SELECTOR", "Cannot use -v and -l together"));
+            return;
+        }
+        const cwd = process.cwd();
+        if (stdin !== undefined) {
+            await processStdin(stdin, selectorArg, validateMode, lintMode, pretty, limit, cwd);
+        }
+        else {
+            await processSelector(selectorArg, validateMode, lintMode, pretty, limit, gitignore, cwd);
+        }
+    }
+    catch (error) {
+        writeError(error);
+    }
+}
+/**
+ * Write a result to stdout as JSON.
+ */
+function writeResult(result, pretty) {
+    const json = pretty
+        ? JSON.stringify(result, null, 2)
+        : JSON.stringify(result);
+    process.stdout.write(`${json}\n`);
+}
+/**
+ * Count invalid files across all validation groups.
+ */
+function countInvalid(result) {
+    return VALIDATION_STATUS_PRIORITY.reduce((sum, status) => sum + (result[status]?.files.length ?? 0), 0);
+}
+/**
+ * Write validation result to stdout and set exit code.
+ * Adds success/message fields to the output.
+ */
+function writeValidationResult(result, pretty) {
+    const invalidCount = countInvalid(result);
+    if (invalidCount === 0) {
+        writeResult({ success: true, message: "All files passed validation" }, pretty);
+    }
+    else {
+        writeResult({ ...result, success: false }, pretty);
+        process.stderr.write(`${JSON.stringify(new JsdocError("VALIDATION_FAILED", `${invalidCount} file(s) failed validation`).toJSON())}\n`);
+        process.exitCode = 2;
+    }
+}
+/**
+ * Write lint result to stdout and set exit code 2 if issues found.
+ */
+function writeLintResult(result, pretty) {
+    writeResult(result, pretty);
+    if (result.summary.filesWithIssues > 0) {
+        process.exitCode = 2;
+    }
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf-8");
+}
+// Auto-invoke when run as CLI
+function isDirectRun() {
+    if (!process.argv[1])
+        return false;
+    try {
+        const scriptPath = process.argv[1].replace(/\\/g, "/");
+        return (import.meta.url.endsWith(scriptPath) ||
+            import.meta.url.endsWith("/cli.js"));
+    }
+    catch {
+        // Cannot determine script path — safe to skip auto-invoke
+        return false;
+    }
+}
+if (isDirectRun()) {
+    // Only read stdin when it's explicitly piped (isTTY === false, not just undefined)
+    const stdinText = process.stdin.isTTY === false ? await readStdin() : undefined;
+    main(process.argv.slice(2), stdinText).catch(() => {
+        // Error already handled in main
+    });
+}

package/dist/drilldown.js

@@ -0,0 +1,286 @@
+import { readFileSync } from "node:fs";
+import { dirname, relative } from "node:path";
+import { getBarrelChildren, isBarrel } from "./barrel.js";
+import { JsdocError } from "./errors.js";
+import { discoverFiles } from "./file-discovery.js";
+import { parseFileSummaries } from "./jsdoc-parser.js";
+import { generateTypeDeclarations } from "./type-declarations.js";
+/** Terminal level (1-indexed): 1=summary, 2=description, 3=type declarations, 4=full file. */
+const TERMINAL_LEVEL = 4;
+/**
+ * Build the fixed drill-down level array for a file.
+ *
+ * - Level 1 (index 0): @summary text (null if absent)
+ * - Level 2 (index 1): description text (null if absent)
+ * - Level 3 (index 2): type declarations (always present)
+ * - Level 4 (index 3): full file content (always present, terminal)
+ *
+ * The array always has 4 entries. Null entries are skipped during processing.
+ */
+function buildLevels(info) {
+    const { summary, description } = info;
+    return [
+        summary !== null ? { text: () => summary } : null,
+        description !== null ? { text: () => description } : null,
+        { text: () => generateTypeDeclarations(info.path) },
+        { text: () => readFileSync(info.path, "utf-8") },
+    ];
+}
+/**
+ * Compute the display id path for a file. Barrel files (index.ts/index.tsx)
+ * use their parent directory path so they represent the directory.
+ */
+function displayPath(filePath, cwd) {
+    const rel = relative(cwd, filePath);
+    if (isBarrel(filePath)) {
+        const dir = relative(cwd, dirname(filePath));
+        return dir || ".";
+    }
+    return rel;
+}
+/**
+ * Extract the sort key from an output entry (either next_id or id).
+ */
+function sortKey(entry) {
+    if ("next_id" in entry)
+        return entry.next_id;
+    return entry.id;
+}
+/**
+ * Process a single file at a given depth through the drill-down levels.
+ *
+ * Levels are 1-indexed: 1=summary, 2=description, 3=type declarations, 4=full file.
+ * If the requested depth level is null (empty), advance to the next non-null level.
+ * Output contains next_id when more detail is available, or id at terminal level.
+ */
+function processFile(info, depth, cwd) {
+    const idPath = displayPath(info.path, cwd);
+    const levels = buildLevels(info);
+    // Clamp depth to [1, TERMINAL_LEVEL], advance past null levels
+    let effectiveDepth = Math.max(1, Math.min(depth, TERMINAL_LEVEL));
+    while (effectiveDepth < TERMINAL_LEVEL &&
+        levels[effectiveDepth - 1] === null) {
+        effectiveDepth++;
+    }
+    const level = levels[effectiveDepth - 1];
+    if (effectiveDepth < TERMINAL_LEVEL) {
+        return {
+            next_id: `${idPath}@${effectiveDepth + 1}`,
+            text: level.text(),
+        };
+    }
+    return {
+        id: `${idPath}@${effectiveDepth}`,
+        text: level.text(),
+    };
+}
+/**
+ * Create an OutputErrorItem for a PARSE_ERROR.
+ */
+function makeParseErrorItem(filePath, error, cwd) {
+    return {
+        id: displayPath(filePath, cwd),
+        error: { code: error.code, message: error.message },
+    };
+}
+/**
+ * Check if an error is a PARSE_ERROR JsdocError.
+ */
+function isParseError(error) {
+    return error instanceof JsdocError && error.code === "PARSE_ERROR";
+}
+/**
+ * Process a file safely, returning an OutputErrorItem on PARSE_ERROR.
+ * Rethrows non-PARSE_ERROR exceptions.
+ */
+function processFileSafe(filePath, depth, cwd) {
+    try {
+        const info = parseFileSummaries(filePath);
+        return processFile(info, depth, cwd);
+    }
+    catch (error) {
+        if (isParseError(error))
+            return makeParseErrorItem(filePath, error, cwd);
+        throw error;
+    }
+}
+/**
+ * Gather barrel info and error entries from a list of barrel file paths.
+ * Returns successfully parsed barrel infos and error entries for unparseable barrels.
+ */
+function gatherBarrelInfos(barrelPaths, cwd) {
+    const infos = [];
+    const errors = [];
+    for (const barrelPath of barrelPaths) {
+        try {
+            const info = parseFileSummaries(barrelPath);
+            const children = getBarrelChildren(barrelPath, cwd);
+            infos.push({
+                path: barrelPath,
+                hasSummary: info.summary !== null,
+                hasDescription: info.description !== null,
+                children,
+            });
+        }
+        catch (error) {
+            if (isParseError(error)) {
+                errors.push(makeParseErrorItem(barrelPath, error, cwd));
+                continue;
+            }
+            throw error;
+        }
+    }
+    return { infos, errors };
+}
+/**
+ * Build the set of files gated by barrels that have summaries.
+ */
+function buildGatedFileSet(barrelInfos) {
+    const gated = new Set();
+    for (const barrel of barrelInfos) {
+        if (barrel.hasSummary) {
+            for (const child of barrel.children) {
+                gated.add(child);
+            }
+        }
+    }
+    return gated;
+}
+/**
+ * Process a single barrel at the given depth (1-indexed).
+ * Barrels without summaries appear as regular files (no gating).
+ * Barrels with summaries gate children for two depths (L1 summary, L2 description),
+ * then transition at depth 3 where the barrel disappears and children appear.
+ */
+function processBarrelAtDepth(barrel, depth, cwd) {
+    if (!barrel.hasSummary)
+        return [processFileSafe(barrel.path, depth, cwd)];
+    // Null-skip: if depth 2 but no description, advance to transition depth
+    let effectiveDepth = depth;
+    if (effectiveDepth === 2 && !barrel.hasDescription) {
+        effectiveDepth = 3;
+    }
+    if (effectiveDepth < 3) {
+        // Show barrel's own L1 (summary) or L2 (description)
+        return [processFileSafe(barrel.path, effectiveDepth, cwd)];
+    }
+    // Barrel transitions: barrel disappears, children appear
+    const childDepth = effectiveDepth - 2;
+    return collectSafeResults(barrel.children, childDepth, cwd);
+}
+/**
+ * Process a list of files through processFileSafe.
+ */
+function collectSafeResults(files, depth, cwd) {
+    return files.map((filePath) => processFileSafe(filePath, depth, cwd));
+}
+/**
+ * Process files discovered via glob with barrel gating.
+ *
+ * When a glob discovers an index.ts barrel:
+ * 1. If the barrel has a summary and depth < 3: show barrel summary/description (gates children)
+ * 2. If depth >= 3: barrel transitions -- barrel disappears and children appear at depth - 2
+ * 3. If barrel has no summary: not a tree node, children appear as leaves
+ *
+ * A barrel that is itself gated by a parent barrel is not processed independently.
+ * Non-barrel files that are not gated by any barrel are processed normally.
+ */
+function processGlobWithBarrels(files, depth, cwd) {
+    const barrelPaths = [];
+    const nonBarrelPaths = [];
+    for (const filePath of files) {
+        if (isBarrel(filePath)) {
+            barrelPaths.push(filePath);
+        }
+        else {
+            nonBarrelPaths.push(filePath);
+        }
+    }
+    if (barrelPaths.length === 0) {
+        return collectSafeResults(nonBarrelPaths, depth, cwd);
+    }
+    const { infos: barrelInfos, errors: barrelErrors } = gatherBarrelInfos(barrelPaths, cwd);
+    const gatedFiles = buildGatedFileSet(barrelInfos);
+    const results = [...barrelErrors];
+    for (const barrel of barrelInfos) {
+        if (gatedFiles.has(barrel.path))
+            continue;
+        results.push(...processBarrelAtDepth(barrel, depth, cwd));
+    }
+    const ungatedNonBarrels = nonBarrelPaths.filter((f) => !gatedFiles.has(f));
+    results.push(...collectSafeResults(ungatedNonBarrels, depth, cwd));
+    return results;
+}
+/**
+ * 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 function drilldown(selector, cwd, gitignore = true, limit = 100) {
+    const depth = selector.depth ?? 1;
+    if (selector.type === "path") {
+        const files = discoverFiles(selector.pattern, cwd, gitignore);
+        if (files.length > 1) {
+            // Directory expanded to multiple files — route through glob pipeline
+            const results = processGlobWithBarrels(files, depth, cwd);
+            const sorted = results.sort((a, b) => sortKey(a).localeCompare(sortKey(b)));
+            const total = sorted.length;
+            const truncated = total > limit;
+            return {
+                items: sorted.slice(0, limit),
+                truncated,
+            };
+        }
+        // Single file path — errors are fatal, no barrel gating
+        const filePath = files[0];
+        const info = parseFileSummaries(filePath);
+        const items = [processFile(info, depth, cwd)];
+        return { items, truncated: false };
+    }
+    // Glob selector — apply barrel gating
+    const files = discoverFiles(selector.pattern, cwd, gitignore);
+    if (files.length === 0) {
+        throw new JsdocError("NO_FILES_MATCHED", `No files matched: ${selector.pattern}`);
+    }
+    const results = processGlobWithBarrels(files, depth, cwd);
+    // Sort alphabetically by key
+    const sorted = results.sort((a, b) => sortKey(a).localeCompare(sortKey(b)));
+    const total = sorted.length;
+    const truncated = total > limit;
+    return {
+        items: sorted.slice(0, limit),
+        truncated,
+    };
+}
+/**
+ * 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 function drilldownFiles(filePaths, depth, cwd, limit = 100) {
+    const d = depth ?? 1;
+    const tsFiles = filePaths.filter((f) => f.endsWith(".ts") || f.endsWith(".tsx"));
+    const results = collectSafeResults(tsFiles, d, cwd);
+    const sorted = results.sort((a, b) => sortKey(a).localeCompare(sortKey(b)));
+    const total = sorted.length;
+    const truncated = total > limit;
+    return {
+        items: sorted.slice(0, limit),
+        truncated,
+    };
+}

package/dist/errors.js

@@ -0,0 +1,24 @@
+/**
+ * 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 class JsdocError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "JsdocError";
+    }
+    toJSON() {
+        return {
+            error: {
+                code: this.code,
+                message: this.message,
+            },
+        };
+    }
+}