@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/utils/formatting/treeFormatter.d.ts

@@ -0,0 +1,344 @@
+/**
+ * @fileoverview Tree formatter utility for visualizing hierarchical data structures.
+ * Supports ASCII, Unicode box-drawing, and compact tree styles with icons and metadata.
+ * @module src/utils/formatting/treeFormatter
+ */
+import { type RequestContext } from '../../utils/internal/requestContext.js';
+/**
+ * Tree output style options.
+ *
+ * - `unicode`: Box-drawing characters (`├──`, `└──`, `│`) — best for terminal output.
+ * - `ascii`:   ASCII characters (`+--`, `\--`, `|`) — safe for environments without Unicode support.
+ * - `compact`: Simple indented list with no connectors — minimal decoration.
+ *
+ * @example
+ * ```
+ * // unicode
+ * root
+ * ├── child1
+ * └── child2
+ *
+ * // ascii
+ * root
+ * +-- child1
+ * \-- child2
+ *
+ * // compact
+ * root
+ *   child1
+ *   child2
+ * ```
+ */
+export type TreeStyle = 'ascii' | 'unicode' | 'compact';
+/**
+ * Node in a hierarchical tree structure.
+ *
+ * Nodes are recursive: any node can have `children`, forming an arbitrarily deep tree.
+ * Circular references (a node appearing in its own descendant chain) are detected at
+ * render time and replaced with a `[Circular Reference]` marker.
+ */
+export interface TreeNode {
+    /**
+     * Child nodes nested under this node.
+     * A node with children is treated as a "folder" node; one without is a "leaf" node.
+     * This distinction affects icon selection when `icons` is enabled.
+     */
+    children?: TreeNode[];
+    /**
+     * Arbitrary key-value metadata to display alongside the node name.
+     * When `showMetadata` is enabled, entries are rendered as `key=value` pairs in
+     * parentheses after the node name — e.g. `file.txt (size=1KB, type=text)`.
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Display name for this node. Must be a non-empty string.
+     */
+    name: string;
+}
+/**
+ * Configuration options for tree formatting.
+ */
+export interface TreeFormatterOptions {
+    /**
+     * Icon to use for leaf nodes (nodes without children) when `icons` is enabled.
+     * Default: `'📄'`
+     */
+    fileIcon?: string;
+    /**
+     * Icon to use for branch nodes (nodes with children) when `icons` is enabled.
+     * Default: `'📁'`
+     */
+    folderIcon?: string;
+    /**
+     * Whether to prefix each node name with an icon.
+     * Leaf nodes use `fileIcon`; branch nodes use `folderIcon`.
+     * Default: `false`
+     */
+    icons?: boolean;
+    /**
+     * String used to indent each level of the tree.
+     * Combined with vertical connector characters for `unicode` and `ascii` styles
+     * to keep the tree visually aligned. Must be at least one character wide.
+     * Default: `'  '` (two spaces)
+     */
+    indent?: string;
+    /**
+     * Maximum depth to render (0-based). Nodes at depth greater than this value are
+     * omitted entirely. `undefined` means no limit.
+     * Default: `undefined`
+     */
+    maxDepth?: number;
+    /**
+     * Whether to append node metadata after each node name.
+     * Metadata entries are rendered as `key=value` pairs enclosed in parentheses.
+     * Default: `false`
+     */
+    showMetadata?: boolean;
+    /**
+     * Visual style used to draw branch connectors. See {@link TreeStyle} for details.
+     * Default: `'unicode'`
+     */
+    style?: TreeStyle;
+}
+/**
+ * Utility class for formatting hierarchical data as tree structures.
+ *
+ * Renders a {@link TreeNode} graph as a multi-line string using ASCII, Unicode
+ * box-drawing, or compact indented styles. Handles arbitrary depth, optional icons,
+ * inline metadata, and detects circular references at render time.
+ *
+ * Use the exported {@link treeFormatter} singleton rather than constructing directly.
+ *
+ * @example
+ * ```typescript
+ * import { treeFormatter } from '../../utils/formatting/treeFormatter.js';
+ *
+ * const tree: TreeNode = {
+ *   name: 'src',
+ *   children: [
+ *     { name: 'index.ts' },
+ *     { name: 'utils', children: [{ name: 'helper.ts' }] },
+ *   ],
+ * };
+ *
+ * console.log(treeFormatter.format(tree, { style: 'unicode' }));
+ * // src
+ * // ├── index.ts
+ * // └── utils
+ * //     └── helper.ts
+ * ```
+ */
+export declare class TreeFormatter {
+    /**
+     * Default formatting options.
+     * @private
+     */
+    private readonly defaultOptions;
+    /**
+     * Track seen nodes for circular reference detection.
+     * @private
+     */
+    private seenNodes;
+    /**
+     * Format a single tree into a multi-line string.
+     *
+     * Merges `options` with defaults, resets circular-reference tracking, then
+     * recursively renders each node with branch connectors, optional icons, and
+     * optional metadata. Lines are joined with `\n`.
+     *
+     * @param root - Root node of the tree. Must have a non-empty `name` string.
+     * @param options - Formatting options. Merged with defaults; all fields are optional.
+     * @param context - Optional request context for correlated log output. A new context
+     *   is created automatically when omitted.
+     * @returns Multi-line tree string. The root node appears on the first line with no
+     *   connector prefix; child nodes are indented and prefixed with branch connectors.
+     * @throws {McpError} With code `ValidationError` if `root` is missing or has no `name`.
+     * @throws {McpError} With code `InternalError` if rendering fails unexpectedly.
+     *
+     * @example
+     * ```typescript
+     * const tree = {
+     *   name: 'src',
+     *   children: [
+     *     { name: 'index.ts' },
+     *     {
+     *       name: 'utils',
+     *       children: [
+     *         { name: 'helper.ts' },
+     *         { name: 'types.ts' },
+     *       ],
+     *     },
+     *   ],
+     * };
+     *
+     * console.log(treeFormatter.format(tree, { style: 'unicode', icons: true }));
+     * // 📁 src
+     * // ├── 📄 index.ts
+     * // └── 📁 utils
+     * //     ├── 📄 helper.ts
+     * //     └── 📄 types.ts
+     * ```
+     */
+    format(root: TreeNode, options?: TreeFormatterOptions, context?: RequestContext): string;
+    /**
+     * Format multiple independent trees (forest) into a single string.
+     *
+     * Calls {@link format} on each root in order and joins the results with a blank
+     * line (`\n\n`) between them. Useful for rendering several top-level structures
+     * side-by-side in one output block (e.g. `src/`, `tests/`, `docs/`).
+     *
+     * @param roots - Non-empty array of root nodes. Each must satisfy the same
+     *   constraints as the `root` parameter of {@link format}.
+     * @param options - Formatting options applied uniformly to every tree.
+     * @param context - Optional request context for correlated log output. A new context
+     *   is created automatically when omitted.
+     * @returns Each formatted tree separated by a blank line.
+     * @throws {McpError} With code `ValidationError` if `roots` is empty or not an array.
+     * @throws {McpError} With code `ValidationError` / `InternalError` propagated from
+     *   {@link format} if any individual tree fails to render.
+     *
+     * @example
+     * ```typescript
+     * const roots = [
+     *   { name: 'src', children: [{ name: 'index.ts' }] },
+     *   { name: 'tests', children: [{ name: 'index.test.ts' }] },
+     * ];
+     *
+     * console.log(treeFormatter.formatMultiple(roots, { style: 'unicode' }));
+     * // src
+     * // └── index.ts
+     * //
+     * // tests
+     * // └── index.test.ts
+     * ```
+     */
+    formatMultiple(roots: TreeNode[], options?: TreeFormatterOptions, context?: RequestContext): string;
+    /**
+     * Recursively render a tree node and its children into `lines`.
+     *
+     * Uses a post-order removal strategy for circular-reference detection: the node is
+     * added to `seenNodes` before descending into children and removed afterward, so
+     * the same node can appear in multiple independent branches without false positives —
+     * only true ancestor-descendant cycles are flagged.
+     *
+     * @param node - Current node to render.
+     * @param prefix - String prepended to every line produced by this call and its
+     *   descendants (carries the vertical-connector continuation from parent levels).
+     * @param isRoot - Whether this is the top-level node (suppresses the leading connector).
+     * @param isLast - Whether this node is the last sibling (determines corner vs. tee connector).
+     * @param lines - Accumulator array; rendered lines are pushed here in order.
+     * @param options - Resolved formatting options.
+     * @param depth - Current render depth (0 = root). Used to enforce `maxDepth`.
+     * @private
+     */
+    private renderNode;
+    /**
+     * Return the branch-connector string that precedes a node's name.
+     *
+     * For `type === 'circular'`, always uses a minimal connector regardless of style
+     * (compact: two spaces; others: corner or tee). For normal nodes, the connector
+     * depends on `style` and whether this is the last sibling.
+     *
+     * @param type - `'node'` for a normal node; `'circular'` for a cycle marker.
+     * @param isLast - Whether this node is the last among its siblings.
+     * @param style - Active tree style.
+     * @returns Connector string (e.g. `'└── '`, `'+-- '`, or `''`).
+     * @private
+     */
+    private getConnector;
+    /**
+     * Return the prefix string to prepend to all lines produced by child nodes.
+     *
+     * When the parent is not the last sibling, a vertical connector (`│` for unicode,
+     * `|` for ascii) is prepended and padded to match `indent`'s width, keeping the
+     * tree visually connected. When the parent is last, a blank indent is used instead.
+     *
+     * @param isLast - Whether the parent node is the last among its siblings.
+     * @param style - Active tree style.
+     * @param indent - Configured indentation string (its length determines padding width).
+     * @returns Prefix string to pass as `prefix` when recursing into children.
+     * @private
+     */
+    private getChildPrefix;
+    /**
+     * Return the icon prefix string for a node, or an empty string when icons are disabled.
+     *
+     * A node is treated as a "folder" (uses `folderIcon`) if it has at least one child;
+     * otherwise it uses `fileIcon`. The returned string includes a trailing space so
+     * the icon is separated from the node name.
+     *
+     * @param node - Node to select an icon for.
+     * @param options - Resolved formatting options.
+     * @returns Icon string with trailing space (e.g. `'📁 '`), or `''` if `icons` is false.
+     * @private
+     */
+    private getIcon;
+    /**
+     * Return the metadata suffix string for a node, or an empty string when metadata display
+     * is disabled or the node has no metadata.
+     *
+     * Entries are formatted as `key=value` pairs joined by `', '` and wrapped in
+     * parentheses: ` (size=1KB, type=text)`. All values are coerced to strings via
+     * `String()`. Returns `''` if the resulting entry list is empty.
+     *
+     * @param node - Node whose `metadata` record to format.
+     * @param options - Resolved formatting options (`showMetadata` must be `true` to emit output).
+     * @returns Metadata suffix string (e.g. `' (size=1KB)'`) or `''`.
+     * @private
+     */
+    private formatMetadata;
+}
+/**
+ * Singleton instance of TreeFormatter.
+ * Use this instance to format hierarchical data as tree structures.
+ *
+ * @example
+ * ```typescript
+ * import { treeFormatter } from '../../utils/formatting/treeFormatter.js';
+ *
+ * // Simple directory tree
+ * const tree = {
+ *   name: 'project',
+ *   children: [
+ *     {
+ *       name: 'src',
+ *       children: [
+ *         { name: 'index.ts' },
+ *         { name: 'types.ts' }
+ *       ]
+ *     },
+ *     { name: 'package.json' },
+ *     { name: 'README.md' }
+ *   ]
+ * };
+ *
+ * // Unicode tree with icons
+ * console.log(treeFormatter.format(tree, {
+ *   style: 'unicode',
+ *   icons: true
+ * }));
+ * // 📁 project
+ * // ├── 📁 src
+ * // │   ├── 📄 index.ts
+ * // │   └── 📄 types.ts
+ * // ├── 📄 package.json
+ * // └── 📄 README.md
+ *
+ * // With metadata
+ * const treeWithMeta = {
+ *   name: 'files',
+ *   metadata: { count: 3 },
+ *   children: [
+ *     { name: 'file1.txt', metadata: { size: '1KB' } },
+ *     { name: 'file2.txt', metadata: { size: '2KB' } }
+ *   ]
+ * };
+ *
+ * console.log(treeFormatter.format(treeWithMeta, { showMetadata: true }));
+ * // files (count=3)
+ * // ├── file1.txt (size=1KB)
+ * // └── file2.txt (size=2KB)
+ * ```
+ */
+export declare const treeFormatter: TreeFormatter;
+//# sourceMappingURL=treeFormatter.d.ts.map

package/dist/utils/formatting/treeFormatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeFormatter.d.ts","sourceRoot":"","sources":["../../../src/utils/formatting/treeFormatter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,KAAK,cAAc,EAAyB,MAAM,oCAAoC,CAAC;AAEhG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAC;IAEtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,aAAa;IACxB;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAQ7B;IAEF;;;OAGG;IACH,OAAO,CAAC,SAAS,CAAuB;IAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,oBAAoB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM;IA6DxF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,cAAc,CACZ,KAAK,EAAE,QAAQ,EAAE,EACjB,OAAO,CAAC,EAAE,oBAAoB,EAC9B,OAAO,CAAC,EAAE,cAAc,GACvB,MAAM;IAuCT;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,UAAU;IAoDlB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,YAAY;IAiBpB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,cAAc;IAgBtB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,OAAO;IAgBf;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,cAAc;CAgBvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,eAAO,MAAM,aAAa,eAAsB,CAAC"}