@ibm/ibmi-mcp-server 0.1.0

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

@@ -0,0 +1,348 @@
+/**
+ * @fileoverview Markdown builder utility for creating well-structured, semantic markdown content
+ * @module utils/formatting/markdownBuilder
+ */
+/**
+ * Utility class for building well-formatted markdown content with consistent structure.
+ *
+ * This builder provides a fluent API for creating markdown documents with proper
+ * spacing, hierarchy, and semantic structure. It helps eliminate string concatenation
+ * and ensures consistent formatting across all tool response formatters.
+ *
+ * @example
+ * ```typescript
+ * const md = new MarkdownBuilder()
+ *   .h1('Commit Created Successfully')
+ *   .keyValue('Commit Hash', 'abc123def')
+ *   .keyValue('Author', 'John Doe')
+ *   .section('Files Changed', () => {
+ *     md.list(['file1.ts', 'file2.ts']);
+ *   });
+ *
+ * const markdown = md.build();
+ * ```
+ */
+export declare class MarkdownBuilder {
+    private sections;
+    /**
+     * Add a level 1 heading.
+     * @param text - The heading text
+     * @param emoji - Optional emoji to prepend
+     * @returns this builder for chaining
+     */
+    h1(text: string, emoji?: string): this;
+    /**
+     * Add a level 2 heading.
+     * @param text - The heading text
+     * @param emoji - Optional emoji to prepend
+     * @returns this builder for chaining
+     */
+    h2(text: string, emoji?: string): this;
+    /**
+     * Add a level 3 heading.
+     * @param text - The heading text
+     * @param emoji - Optional emoji to prepend
+     * @returns this builder for chaining
+     */
+    h3(text: string, emoji?: string): this;
+    /**
+     * Add a level 4 heading.
+     * @param text - The heading text
+     * @returns this builder for chaining
+     */
+    h4(text: string): this;
+    /**
+     * Add a bold key-value pair on a single line.
+     * @param key - The key (will be bolded)
+     * @param value - The value
+     * @returns this builder for chaining
+     */
+    keyValue(key: string, value: string | number | boolean | null): this;
+    /**
+     * Add a key-value pair without bolding (for less emphasis).
+     * @param key - The key
+     * @param value - The value
+     * @returns this builder for chaining
+     */
+    keyValuePlain(key: string, value: string | number | boolean | null): this;
+    /**
+     * Add a bulleted or numbered list.
+     * @param items - Array of items to list
+     * @param ordered - If true, creates a numbered list
+     * @returns this builder for chaining
+     */
+    list(items: string[], ordered?: boolean): this;
+    /**
+     * Add a code block with optional language syntax highlighting.
+     * @param content - The code content
+     * @param language - Optional language identifier (e.g., 'typescript', 'diff', 'json')
+     * @returns this builder for chaining
+     */
+    codeBlock(content: string, language?: string): this;
+    /**
+     * Add inline code (backticks).
+     * @param code - The code text
+     * @returns this builder for chaining
+     */
+    inlineCode(code: string): this;
+    /**
+     * Add a paragraph of text.
+     * @param text - The paragraph content
+     * @returns this builder for chaining
+     */
+    paragraph(text: string): this;
+    /**
+     * Add a blockquote.
+     * @param text - The quoted text
+     * @returns this builder for chaining
+     */
+    blockquote(text: string): this;
+    /**
+     * Add a horizontal rule.
+     * @returns this builder for chaining
+     */
+    hr(): this;
+    /**
+     * Add a link.
+     * @param text - The link text
+     * @param url - The URL
+     * @returns this builder for chaining
+     */
+    link(text: string, url: string): this;
+    /**
+     * Add a table from structured data.
+     * @param headers - Array of column headers
+     * @param rows - Array of rows, each row is an array of cell values
+     * @returns this builder for chaining
+     */
+    table(headers: string[], rows: string[][]): this;
+    /**
+     * Add a section with a heading and callback for content.
+     * This is useful for grouping related content.
+     *
+     * @example
+     * ```typescript
+     * md.section('Files Changed', () => {
+     *   md.list(['file1.ts', 'file2.ts']);
+     * });
+     * ```
+     *
+     * @param title - The section heading
+     * @param levelOrContent - Heading level (2-4) or callback function
+     * @param content - Callback function (if level is provided)
+     * @returns this builder for chaining
+     */
+    section(title: string, levelOrContent: 2 | 3 | 4 | (() => void), content?: () => void): this;
+    /**
+     * Add a collapsible details section (HTML details/summary).
+     * Note: Not all markdown renderers support this.
+     *
+     * @param summary - The summary text (always visible)
+     * @param details - The detailed content (collapsed by default)
+     * @returns this builder for chaining
+     */
+    details(summary: string, details: string): this;
+    /**
+     * Add a status/alert box (GitHub/GitLab style).
+     * Renders as a highlighted blockquote with an icon.
+     *
+     * Supported types:
+     * - 'note': 📝 Neutral information
+     * - 'tip': 💡 Helpful suggestions
+     * - 'important': ❗ Critical information
+     * - 'warning': ⚠️ Warning/caution
+     * - 'caution': 🚨 Danger/destructive action
+     *
+     * @param type - Alert type
+     * @param content - Alert content (can be multi-line)
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * md.alert('warning', 'This operation cannot be undone!');
+     * // Renders: > [!WARNING]
+     * //          > This operation cannot be undone!
+     * ```
+     */
+    alert(type: "note" | "tip" | "important" | "warning" | "caution", content: string): this;
+    /**
+     * Add a task list with checkboxes (GitHub style).
+     *
+     * @param items - Array of tasks with checked status
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * md.taskList([
+     *   { checked: true, text: 'Complete setup' },
+     *   { checked: false, text: 'Run tests' },
+     * ]);
+     * // Renders: - [x] Complete setup
+     * //          - [ ] Run tests
+     * ```
+     */
+    taskList(items: Array<{
+        checked: boolean;
+        text: string;
+    }>): this;
+    /**
+     * Add an image with alt text and optional title.
+     *
+     * @param altText - Alternative text for the image
+     * @param url - Image URL
+     * @param title - Optional title (shown on hover)
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * md.image('Architecture diagram', '/assets/diagram.png', 'System Architecture');
+     * // Renders: ![Architecture diagram](/assets/diagram.png "System Architecture")
+     * ```
+     */
+    image(altText: string, url: string, title?: string): this;
+    /**
+     * Add strikethrough text.
+     *
+     * @param text - Text to strike through
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * md.text('Price: ').strikethrough('$100').text(' $80');
+     * // Renders: Price: ~~$100~~ $80
+     * ```
+     */
+    strikethrough(text: string): this;
+    /**
+     * Add a diff-style code block showing additions and deletions.
+     * Useful for showing file changes, configuration updates, etc.
+     *
+     * @param changes - Object with optional additions, deletions, and context lines
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * md.diff({
+     *   additions: ['const newFeature = true;'],
+     *   deletions: ['const oldFeature = false;'],
+     *   context: ['// Configuration'],
+     * });
+     * // Renders as a diff code block with +/- prefixes
+     * ```
+     */
+    diff(changes: {
+        additions?: string[];
+        deletions?: string[];
+        context?: string[];
+    }): this;
+    /**
+     * Add a badge/shield (uses shields.io style).
+     *
+     * @param label - Badge label (left side)
+     * @param message - Badge message (right side)
+     * @param color - Optional color (e.g., 'green', 'red', 'blue', 'yellow')
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * md.badge('build', 'passing', 'green');
+     * // Renders: ![build: passing](https://img.shields.io/badge/build-passing-green)
+     * ```
+     */
+    badge(label: string, message: string, color?: string): this;
+    /**
+     * Add bold text.
+     *
+     * @param text - Text to make bold
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * md.text('This is ').bold('important').text(' information.');
+     * // Renders: This is **important** information.
+     * ```
+     */
+    bold(text: string): this;
+    /**
+     * Add italic text.
+     *
+     * @param text - Text to make italic
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * md.text('This is ').italic('emphasized').text('.');
+     * // Renders: This is *emphasized*.
+     * ```
+     */
+    italic(text: string): this;
+    /**
+     * Add bold and italic text.
+     *
+     * @param text - Text to make bold and italic
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * md.boldItalic('Very important');
+     * // Renders: ***Very important***
+     * ```
+     */
+    boldItalic(text: string): this;
+    /**
+     * Add raw markdown content directly.
+     * Use this for custom formatting not covered by other methods.
+     *
+     * @param markdown - Raw markdown string
+     * @returns this builder for chaining
+     */
+    raw(markdown: string): this;
+    /**
+     * Add a blank line for spacing.
+     * @returns this builder for chaining
+     */
+    blankLine(): this;
+    /**
+     * Add text without any formatting or line breaks.
+     * Useful for inline text that will be followed by other inline elements.
+     *
+     * @param text - The text to add
+     * @returns this builder for chaining
+     */
+    text(text: string): this;
+    /**
+     * Conditionally add content based on a predicate.
+     *
+     * @example
+     * ```typescript
+     * md.when(files.length > 0, () => {
+     *   md.h2('Files Changed').list(files);
+     * });
+     * ```
+     *
+     * @param condition - If true, execute the callback
+     * @param content - Callback function to build conditional content
+     * @returns this builder for chaining
+     */
+    when(condition: boolean, content: () => void): this;
+    /**
+     * Build the final markdown string.
+     * Trims trailing whitespace and ensures the document ends cleanly.
+     *
+     * @returns The complete markdown document as a string
+     */
+    build(): string;
+    /**
+     * Reset the builder to start building a new document.
+     * @returns this builder for chaining
+     */
+    reset(): this;
+}
+/**
+ * Helper function to create a MarkdownBuilder instance.
+ * Provides a shorter alternative to `new MarkdownBuilder()`.
+ *
+ * @returns A new MarkdownBuilder instance
+ */
+export declare function markdown(): MarkdownBuilder;
+//# sourceMappingURL=markdownBuilder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"markdownBuilder.d.ts","sourceRoot":"","sources":["../../../src/utils/formatting/markdownBuilder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAgB;IAEhC;;;;;OAKG;IACH,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAMtC;;;;;OAKG;IACH,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAMtC;;;;;OAKG;IACH,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAMtC;;;;OAIG;IACH,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKtB;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI;IAMpE;;;;;OAKG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI;IAMzE;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,UAAQ,GAAG,IAAI;IAU5C;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAK,GAAG,IAAI;IAK/C;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK9B;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK7B;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAO9B;;;OAGG;IACH,EAAE,IAAI,IAAI;IAKV;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAKrC;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI;IAkBhD;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CACL,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,EACxC,OAAO,CAAC,EAAE,MAAM,IAAI,GACnB,IAAI;IAmBP;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAO/C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CACH,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,EAC1D,OAAO,EAAE,MAAM,GACd,IAAI;IAWP;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI;IAWhE;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAMzD;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKjC;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,OAAO,EAAE;QACZ,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;KACpB,GAAG,IAAI;IAyBR;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,SAAS,GAAG,IAAI;IAQ3D;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKxB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK1B;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK9B;;;;;;OAMG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAK3B;;;OAGG;IACH,SAAS,IAAI,IAAI;IAKjB;;;;;;OAMG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKxB;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI;IAOnD;;;;;OAKG;IACH,KAAK,IAAI,MAAM;IAIf;;;OAGG;IACH,KAAK,IAAI,IAAI;CAId;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,IAAI,eAAe,CAE1C"}