markupr 2.1.8

package/src/main/output/MarkdownGenerator.ts

@@ -0,0 +1,791 @@
+/**
+ * MarkdownGenerator - AI-Ready Output Generator for markupr
+ *
+ * Generates structured Markdown documents following llms.txt-inspired format.
+ * Designed to be easily parsed by AI coding assistants like Claude Code.
+ *
+ * Features:
+ * - Full document with all feedback items, screenshots, and metadata
+ * - Clipboard summary (<1500 chars) for quick sharing
+ * - File references for images (no base64 bloat)
+ * - Consistent FB-XXX item numbering
+ */
+
+import * as path from 'path';
+import type { FeedbackSession, Screenshot, TranscriptionSegment } from '../../shared/types';
+import type { PostProcessResult, TranscriptSegment, ExtractedFrame } from '../pipeline/PostProcessor';
+
+const REPORT_SUPPORT_LINE = '*If this report saved you time, support development: [Ko-fi](https://ko-fi.com/eddiesanjuan)*';
+
+// ============================================================================
+// Types for Enhanced Output Generation
+// ============================================================================
+
+/**
+ * Category types for feedback items
+ */
+export type FeedbackCategory = 'Bug' | 'UX Issue' | 'Suggestion' | 'Performance' | 'Question' | 'General';
+
+/**
+ * Severity levels for prioritization
+ */
+export type FeedbackSeverity = 'Critical' | 'High' | 'Medium' | 'Low';
+
+/**
+ * A single feedback item with transcription and associated screenshots
+ */
+export interface FeedbackItem {
+  id: string;
+  transcription: string;
+  timestamp: number;
+  screenshots: Screenshot[];
+  title?: string;
+  keywords?: string[];
+  category?: FeedbackCategory;
+  severity?: FeedbackSeverity;
+}
+
+/**
+ * Session metadata for context
+ */
+export interface SessionMetadata {
+  os?: string;
+  sourceName?: string;
+  sourceType?: 'screen' | 'window';
+}
+
+/**
+ * Enhanced session structure for markdown generation
+ */
+export interface Session {
+  id: string;
+  startTime: number;
+  endTime?: number;
+  feedbackItems: FeedbackItem[];
+  metadata?: SessionMetadata;
+}
+
+/**
+ * Options for generating the full markdown document
+ */
+export interface GenerateOptions {
+  projectName: string;
+  screenshotDir: string; // Relative path for image references
+}
+
+/**
+ * The generated markdown document with metadata
+ */
+export interface MarkdownDocument {
+  content: string;
+  filename: string;
+  metadata: {
+    itemCount: number;
+    screenshotCount: number;
+    duration: number;
+    types: Record<string, number>;
+  };
+}
+
+/**
+ * Interface for the MarkdownGenerator
+ */
+export interface IMarkdownGenerator {
+  generateFullDocument(session: Session, options: GenerateOptions): MarkdownDocument;
+  generateFromPostProcess(result: PostProcessResult, sessionDir: string): string;
+  generateClipboardSummary(session: Session, projectName?: string): string;
+  generateFeedbackItemId(index: number): string;
+}
+
+// ============================================================================
+// Adapter: Convert FeedbackSession to Session
+// ============================================================================
+
+/**
+ * Convert the existing FeedbackSession type to the enhanced Session type.
+ * Groups transcription segments with their associated screenshots.
+ */
+export function adaptFeedbackSession(
+  feedbackSession: FeedbackSession,
+  options?: { pauseThresholdMs?: number }
+): Session {
+  const pauseThreshold = options?.pauseThresholdMs ?? 1500;
+  const { id, startedAt, endedAt, screenshots, transcription } = feedbackSession;
+
+  // Group transcription segments into feedback items
+  // A new item starts when there's a significant pause between segments
+  const feedbackItems: FeedbackItem[] = [];
+  let currentItem: FeedbackItem | null = null;
+
+  const sortedTranscription = [...transcription].sort((a, b) => a.startTime - b.startTime);
+  const sortedScreenshots = [...screenshots].sort((a, b) => a.timestamp - b.timestamp);
+
+  for (const segment of sortedTranscription) {
+    const shouldStartNewItem =
+      !currentItem ||
+      (segment.startTime - (currentItem.timestamp + getPreviousSegmentDuration(currentItem, sortedTranscription))) > pauseThreshold;
+
+    if (shouldStartNewItem) {
+      // Save previous item
+      if (currentItem) {
+        feedbackItems.push(currentItem);
+      }
+
+      // Start new item
+      currentItem = {
+        id: `item-${feedbackItems.length + 1}`,
+        transcription: segment.text,
+        timestamp: segment.startTime,
+        screenshots: [],
+        category: inferCategory(segment.text),
+      };
+    } else if (currentItem) {
+      // Continue current item
+      currentItem.transcription += ' ' + segment.text;
+    }
+  }
+
+  // Don't forget the last item
+  if (currentItem) {
+    feedbackItems.push(currentItem);
+  }
+
+  // Associate screenshots with feedback items
+  for (const screenshot of sortedScreenshots) {
+    // Find the feedback item that this screenshot belongs to
+    // (screenshot timestamp falls within or just after the item's timeframe)
+    const matchingItem = findMatchingItem(feedbackItems, screenshot.timestamp, pauseThreshold);
+    if (matchingItem) {
+      matchingItem.screenshots.push(screenshot);
+    } else if (feedbackItems.length > 0) {
+      // Associate with the last item if no match found
+      feedbackItems[feedbackItems.length - 1].screenshots.push(screenshot);
+    }
+  }
+
+  return {
+    id,
+    startTime: startedAt,
+    endTime: endedAt,
+    feedbackItems,
+    metadata: {
+      os: process?.platform || 'Unknown',
+      sourceName: 'markupr Session',
+      sourceType: 'screen',
+    },
+  };
+}
+
+function getPreviousSegmentDuration(item: FeedbackItem, _allSegments: TranscriptionSegment[]): number {
+  // Estimate duration based on transcription length (rough: 150 words/min)
+  const words = item.transcription.split(/\s+/).length;
+  return (words / 150) * 60 * 1000; // ms
+}
+
+function findMatchingItem(
+  items: FeedbackItem[],
+  timestamp: number,
+  threshold: number
+): FeedbackItem | undefined {
+  // Find item where screenshot timestamp is within item timeframe + threshold
+  for (let i = items.length - 1; i >= 0; i--) {
+    const item = items[i];
+    const estimatedDuration = (item.transcription.split(/\s+/).length / 150) * 60 * 1000;
+    const itemEnd = item.timestamp + estimatedDuration + threshold;
+
+    if (timestamp >= item.timestamp && timestamp <= itemEnd) {
+      return item;
+    }
+  }
+  return undefined;
+}
+
+function inferCategory(text: string): FeedbackCategory {
+  const lowerText = text.toLowerCase();
+
+  if (lowerText.includes('bug') || lowerText.includes('broken') || lowerText.includes('error') ||
+      lowerText.includes('crash') || lowerText.includes('doesn\'t work') || lowerText.includes('not working')) {
+    return 'Bug';
+  }
+
+  if (lowerText.includes('confusing') || lowerText.includes('hard to') || lowerText.includes('unclear') ||
+      lowerText.includes('ux') || lowerText.includes('user experience') || lowerText.includes('usability')) {
+    return 'UX Issue';
+  }
+
+  if (lowerText.includes('slow') || lowerText.includes('lag') || lowerText.includes('sluggish') ||
+      lowerText.includes('performance') || lowerText.includes('latency') || lowerText.includes('janky')) {
+    return 'Performance';
+  }
+
+  if (lowerText.includes('should') || lowerText.includes('could') || lowerText.includes('would be nice') ||
+      lowerText.includes('suggestion') || lowerText.includes('feature') || lowerText.includes('add')) {
+    return 'Suggestion';
+  }
+
+  if (lowerText.includes('?') || lowerText.includes('how') || lowerText.includes('why') ||
+      lowerText.includes('what') || lowerText.includes('question')) {
+    return 'Question';
+  }
+
+  return 'General';
+}
+
+// ============================================================================
+// MarkdownGenerator Implementation
+// ============================================================================
+
+class MarkdownGeneratorImpl implements IMarkdownGenerator {
+  /**
+   * Generate a full markdown document with all feedback items and metadata.
+   * Follows llms.txt-inspired format for AI readability.
+   */
+  generateFullDocument(session: Session, options: GenerateOptions): MarkdownDocument {
+    const { projectName, screenshotDir } = options;
+    const items = session.feedbackItems;
+    const duration = session.endTime
+      ? this.formatDuration(session.endTime - session.startTime)
+      : 'In Progress';
+    const timestamp = this.formatTimestamp(session.endTime || Date.now());
+    const filename = this.generateFilename(projectName, session.startTime);
+
+    // Early return for empty sessions — produce a clean minimal document
+    if (items.length === 0) {
+      const content = `# ${projectName} Feedback Report
+> Generated by markupr on ${timestamp}
+> Duration: ${duration}
+
+_No feedback items were captured during this session._
+
+---
+*Generated by [markupr](https://markupr.com)*
+${REPORT_SUPPORT_LINE}
+`;
+      return {
+        content,
+        filename,
+        metadata: {
+          itemCount: 0,
+          screenshotCount: 0,
+          duration: session.endTime ? session.endTime - session.startTime : 0,
+          types: {},
+        },
+      };
+    }
+
+    // Count types
+    const typeCounts = this.countTypes(items);
+    const severityCounts = this.countSeverities(items);
+    const screenshotCount = this.countScreenshots(items);
+    const topThemes = this.extractTopThemes(items);
+    const highImpactCount = (severityCounts.Critical || 0) + (severityCounts.High || 0);
+
+    let content = `# ${projectName} Feedback Report
+> Generated by markupr on ${timestamp}
+> Duration: ${duration} | Items: ${items.length} | Screenshots: ${screenshotCount}
+
+## Session Overview
+- **Session ID:** \`${session.id}\`
+- **Source:** ${session.metadata?.sourceName || 'Unknown'} (${session.metadata?.sourceType || 'screen'})
+- **Environment:** ${session.metadata?.os || 'Unknown'}
+- **High-impact items:** ${highImpactCount}
+
+---
+
+## Executive Summary
+
+- ${items.length} total feedback items were captured.
+- ${highImpactCount} items are categorized as **Critical** or **High** priority.
+- ${screenshotCount} screenshots were aligned to spoken context.
+`;
+
+    if (topThemes.length > 0) {
+      content += `- Top themes: ${topThemes.join(', ')}.\n`;
+    }
+
+    content += `
+---
+
+## Actionable Feedback
+
+`;
+
+    items.forEach((item, index) => {
+      const id = this.generateFeedbackItemId(index);
+      const title = item.title || this.generateTitle(item.transcription);
+      const itemTimestamp = this.formatItemTimestamp(item.timestamp - session.startTime);
+      const category = item.category || 'General';
+      const severity = item.severity || this.defaultSeverityForCategory(category);
+      const signals = item.keywords?.slice(0, 5) || [];
+      const suggestedAction = this.suggestAction(category, severity, item.transcription);
+
+      content += `### ${id}: ${title}
+- **Severity:** ${severity}
+- **Type:** ${category}
+- **Timestamp:** ${itemTimestamp}
+`;
+
+      if (signals.length > 0) {
+        content += `- **Signals:** ${signals.join(', ')}\n`;
+      }
+
+      content += `
+#### What Happened
+
+> ${this.wrapTranscription(item.transcription)}
+
+`;
+
+      if (item.screenshots.length > 0) {
+        content += `#### Evidence\n`;
+        item.screenshots.forEach((ss, ssIndex) => {
+          // Use the item's position index (not the FB-XXX display ID) for the
+          // filename so it stays aligned with FileManager.saveSession which
+          // names files by the original feedbackItems array index.
+          const screenshotFilename = this.generateScreenshotFilename(index, ssIndex, item.screenshots.length);
+          content += `![${id}${item.screenshots.length > 1 ? `-${ssIndex + 1}` : ''}](${screenshotDir}/${screenshotFilename})\n\n`;
+        });
+      } else {
+        content += `#### Evidence\n_No screenshot captured for this item._\n\n`;
+      }
+
+      content += `#### Suggested Next Step
+- ${suggestedAction}
+
+`;
+
+      content += `---
+
+`;
+    });
+
+    // Summary tables
+    content += `## Summary
+
+| Type | Count |
+|------|-------|
+`;
+    Object.entries(typeCounts).forEach(([type, count]) => {
+      content += `| ${type} | ${count} |\n`;
+    });
+    content += `| **Total** | **${items.length}** |\n`;
+
+    content += `
+| Severity | Count |
+|----------|-------|
+`;
+    Object.entries(severityCounts).forEach(([severity, count]) => {
+      content += `| ${severity} | ${count} |\n`;
+    });
+    content += `| **Total** | **${items.length}** |\n`;
+
+    content += `
+---
+*Generated by [markupr](https://markupr.com)*
+${REPORT_SUPPORT_LINE}
+`;
+
+    return {
+      content,
+      filename,
+      metadata: {
+        itemCount: items.length,
+        screenshotCount,
+        duration: session.endTime ? session.endTime - session.startTime : 0,
+        types: typeCounts,
+      },
+    };
+  }
+
+  /**
+   * Generate markdown from a PostProcessResult (post-recording pipeline output).
+   *
+   * Produces a clean, AI-readable document with:
+   * - Session header with human-readable timestamp
+   * - Each transcript segment as a heading with [M:SS] timestamp
+   * - Blockquoted transcript text
+   * - Associated frame images referenced as relative paths
+   *
+   * @param result - The combined transcript + frame output from PostProcessor
+   * @param sessionDir - Absolute path to the session directory (used to compute relative frame paths)
+   * @returns The generated markdown string
+   */
+  generateFromPostProcess(result: PostProcessResult, sessionDir: string): string {
+    const { transcriptSegments, extractedFrames } = result;
+    const now = new Date();
+    const sessionTimestamp = now.toLocaleString('en-US', {
+      year: 'numeric',
+      month: 'short',
+      day: 'numeric',
+      hour: '2-digit',
+      minute: '2-digit',
+    });
+
+    let md = `# markupr Session — ${sessionTimestamp}\n\n`;
+
+    if (transcriptSegments.length === 0) {
+      md += `_No speech was detected during this recording._\n`;
+      return md;
+    }
+
+    md += `## Transcript\n\n`;
+
+    // Build a map from transcript segment index to associated frames.
+    // A frame is associated with the segment whose time range contains the
+    // frame timestamp, or the closest segment by start time.
+    const segmentFrameMap = this.mapFramesToSegments(transcriptSegments, extractedFrames);
+
+    for (let i = 0; i < transcriptSegments.length; i++) {
+      const segment = transcriptSegments[i];
+      const formattedTime = this.formatPostProcessTimestamp(segment.startTime);
+      const title = this.generateSegmentTitle(segment.text);
+
+      md += `### [${formattedTime}] ${title}\n`;
+      md += `> ${this.wrapTranscription(segment.text)}\n\n`;
+
+      // Append any frames associated with this segment
+      const frames = segmentFrameMap.get(i);
+      if (frames && frames.length > 0) {
+        for (const frame of frames) {
+          const frameTimestamp = this.formatPostProcessTimestamp(frame.timestamp);
+          const relativePath = this.computeRelativeFramePath(frame.path, sessionDir);
+          md += `![Frame at ${frameTimestamp}](${relativePath})\n\n`;
+        }
+      }
+    }
+
+    md += `---\n*Generated by [markupr](https://markupr.com)*\n${REPORT_SUPPORT_LINE}\n`;
+
+    return md;
+  }
+
+  /**
+   * Map extracted frames to their closest transcript segments.
+   * Returns a Map from segment index to an array of frames.
+   */
+  private mapFramesToSegments(
+    segments: TranscriptSegment[],
+    frames: ExtractedFrame[]
+  ): Map<number, ExtractedFrame[]> {
+    const map = new Map<number, ExtractedFrame[]>();
+
+    for (const frame of frames) {
+      let bestIndex = 0;
+      let bestDistance = Infinity;
+
+      for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+
+        // If the frame timestamp falls within the segment range, it is a direct match
+        if (frame.timestamp >= seg.startTime && frame.timestamp <= seg.endTime) {
+          bestIndex = i;
+          bestDistance = 0;
+          break;
+        }
+
+        // Otherwise track the closest segment by start time
+        const distance = Math.abs(frame.timestamp - seg.startTime);
+        if (distance < bestDistance) {
+          bestDistance = distance;
+          bestIndex = i;
+        }
+      }
+
+      const existing = map.get(bestIndex) || [];
+      existing.push(frame);
+      map.set(bestIndex, existing);
+    }
+
+    // Sort frames within each segment by timestamp
+    for (const [, frameList] of map) {
+      frameList.sort((a, b) => a.timestamp - b.timestamp);
+    }
+
+    return map;
+  }
+
+  /**
+   * Compute a relative path for a frame image from the session directory.
+   * If the frame path is already relative, return it as-is.
+   * If absolute, compute the relative path from sessionDir.
+   */
+  private computeRelativeFramePath(framePath: string, sessionDir: string): string {
+    if (!path.isAbsolute(framePath)) {
+      return framePath;
+    }
+    return path.relative(sessionDir, framePath);
+  }
+
+  /**
+   * Format a timestamp in seconds to M:SS format for post-process output.
+   * Examples: 0 -> "0:00", 15.3 -> "0:15", 125 -> "2:05"
+   */
+  private formatPostProcessTimestamp(seconds: number): string {
+    const totalSeconds = Math.max(0, Math.floor(seconds));
+    const mins = Math.floor(totalSeconds / 60);
+    const secs = totalSeconds % 60;
+    return `${mins}:${secs.toString().padStart(2, '0')}`;
+  }
+
+  /**
+   * Generate a short title from transcript text (first sentence, max 60 chars).
+   */
+  private generateSegmentTitle(text: string): string {
+    const firstSentence = text.split(/[.!?]/)[0].trim();
+    if (firstSentence.length <= 60) return firstSentence;
+    return firstSentence.slice(0, 57) + '...';
+  }
+
+  /**
+   * Generate a clipboard-friendly summary (<1500 chars).
+   * Includes priority items and a reference to the full report.
+   */
+  generateClipboardSummary(session: Session, projectName?: string): string {
+    const name = projectName || session.metadata?.sourceName || 'Project';
+    const items = session.feedbackItems;
+
+    let summary = `# Feedback: ${name} - ${items.length} items\n\n`;
+
+    // Priority items (first 3)
+    const maxPriorityItems = 3;
+    summary += `## Priority Items\n`;
+
+    items.slice(0, maxPriorityItems).forEach((item, index) => {
+      const id = this.generateFeedbackItemId(index);
+      const title = this.generateTitle(item.transcription);
+      const oneLineSummary = this.truncateText(item.transcription, 60);
+      summary += `- **${id}:** ${title} - ${oneLineSummary}\n`;
+    });
+
+    if (items.length > maxPriorityItems) {
+      const remainingIds = items
+        .slice(maxPriorityItems)
+        .map((_, i) => this.generateFeedbackItemId(i + maxPriorityItems))
+        .join(', ');
+      summary += `\n## Other\n- ${remainingIds} (see full report)\n`;
+    }
+
+    summary += `\n**Full report:** ./feedback-report.md`;
+
+    // Ensure we stay under 1500 chars
+    if (summary.length > 1500) {
+      summary = summary.slice(0, 1497) + '...';
+    }
+
+    return summary;
+  }
+
+  /**
+   * Generate a feedback item ID (FB-001, FB-002, etc.)
+   */
+  generateFeedbackItemId(index: number): string {
+    return `FB-${(index + 1).toString().padStart(3, '0')}`;
+  }
+
+  // ==========================================================================
+  // Private Helper Methods
+  // ==========================================================================
+
+  /**
+   * Generate a title from the transcription (first sentence or 50 chars)
+   */
+  private generateTitle(transcription: string): string {
+    // Extract first sentence
+    const firstSentence = transcription.split(/[.!?]/)[0].trim();
+    if (firstSentence.length <= 50) return firstSentence;
+    return firstSentence.slice(0, 47) + '...';
+  }
+
+  /**
+   * Truncate text to specified length
+   */
+  private truncateText(text: string, maxLength: number): string {
+    if (text.length <= maxLength) return text;
+    return text.slice(0, maxLength - 3) + '...';
+  }
+
+  /**
+   * Wrap transcription for markdown blockquote (handle multi-line)
+   */
+  private wrapTranscription(transcription: string): string {
+    // Split by natural sentence breaks for readability
+    const sentences = transcription.match(/[^.!?]+[.!?]+/g);
+    if (!sentences) return transcription;
+
+    // Append any trailing text that doesn't end with punctuation.
+    // Whisper transcripts frequently end mid-sentence.
+    const lastMatch = sentences[sentences.length - 1];
+    const lastMatchEnd = transcription.lastIndexOf(lastMatch) + lastMatch.length;
+    const remainder = transcription.slice(lastMatchEnd).trim();
+    if (remainder) {
+      sentences.push(remainder);
+    }
+
+    if (sentences.length <= 2) return transcription;
+
+    // For longer transcriptions, add line breaks between sentences
+    return sentences.map(s => s.trim()).join('\n> ');
+  }
+
+  /**
+   * Format duration from milliseconds to M:SS
+   */
+  private formatDuration(ms: number): string {
+    const totalSeconds = Math.floor(ms / 1000);
+    const mins = Math.floor(totalSeconds / 60);
+    const secs = totalSeconds % 60;
+    return `${mins}:${secs.toString().padStart(2, '0')}`;
+  }
+
+  /**
+   * Format timestamp to locale string
+   */
+  private formatTimestamp(ms: number): string {
+    return new Date(ms).toLocaleString('en-US', {
+      year: 'numeric',
+      month: 'short',
+      day: 'numeric',
+      hour: '2-digit',
+      minute: '2-digit',
+    });
+  }
+
+  /**
+   * Format item timestamp as MM:SS from session start
+   */
+  private formatItemTimestamp(ms: number): string {
+    const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+    const mins = Math.floor(totalSeconds / 60);
+    const secs = totalSeconds % 60;
+    return `${mins.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
+  }
+
+  /**
+   * Generate filename following pattern: {project}-feedback-{YYYYMMDD-HHmmss}.md
+   */
+  private generateFilename(projectName: string, startTime: number): string {
+    const date = new Date(startTime);
+    const year = date.getFullYear();
+    const month = (date.getMonth() + 1).toString().padStart(2, '0');
+    const day = date.getDate().toString().padStart(2, '0');
+    const hours = date.getHours().toString().padStart(2, '0');
+    const minutes = date.getMinutes().toString().padStart(2, '0');
+    const seconds = date.getSeconds().toString().padStart(2, '0');
+
+    const dateStr = `${year}${month}${day}`;
+    const timeStr = `${hours}${minutes}${seconds}`;
+    const safeName = projectName.toLowerCase().replace(/[^a-z0-9]/g, '-').replace(/-+/g, '-');
+
+    return `${safeName}-feedback-${dateStr}-${timeStr}.md`;
+  }
+
+  /**
+   * Generate screenshot filename for a feedback item.
+   * Uses the item's position index to produce `fb-{NNN}.png`, matching the
+   * naming convention in FileManager.saveSession.
+   */
+  private generateScreenshotFilename(itemIndex: number, screenshotIndex: number, total: number): string {
+    const num = (itemIndex + 1).toString().padStart(3, '0');
+    const suffix = total > 1 ? `-${screenshotIndex + 1}` : '';
+    return `fb-${num}${suffix}.png`;
+  }
+
+  /**
+   * Provide a severity fallback when upstream analysis is unavailable.
+   */
+  private defaultSeverityForCategory(category: FeedbackCategory): FeedbackSeverity {
+    switch (category) {
+      case 'Bug':
+        return 'High';
+      case 'Performance':
+        return 'High';
+      case 'UX Issue':
+        return 'Medium';
+      case 'Suggestion':
+        return 'Low';
+      case 'Question':
+        return 'Low';
+      default:
+        return 'Medium';
+    }
+  }
+
+  private countSeverities(items: FeedbackItem[]): Record<string, number> {
+    return items.reduce((acc, item) => {
+      const severity = item.severity || this.defaultSeverityForCategory(item.category || 'General');
+      acc[severity] = (acc[severity] || 0) + 1;
+      return acc;
+    }, {} as Record<string, number>);
+  }
+
+  private extractTopThemes(items: FeedbackItem[]): string[] {
+    const counts = new Map<string, number>();
+
+    items.forEach((item) => {
+      (item.keywords || []).forEach((keyword) => {
+        const normalized = keyword.toLowerCase();
+        counts.set(normalized, (counts.get(normalized) || 0) + 1);
+      });
+    });
+
+    return Array.from(counts.entries())
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 5)
+      .map(([keyword]) => keyword);
+  }
+
+  private suggestAction(
+    category: FeedbackCategory,
+    severity: FeedbackSeverity,
+    transcription: string
+  ): string {
+    const excerpt = this.truncateText(transcription, 120);
+
+    switch (category) {
+      case 'Bug':
+        return `Reproduce and patch this defect, then add a regression test that validates: "${excerpt}".`;
+      case 'Performance':
+        return `Profile this flow, target the slow step first, and validate before/after metrics for: "${excerpt}".`;
+      case 'UX Issue':
+        return `Revise the UI interaction and run a quick usability check focused on: "${excerpt}".`;
+      case 'Suggestion':
+        return severity === 'High' || severity === 'Critical'
+          ? `Treat this suggestion as near-term roadmap work and define implementation scope for: "${excerpt}".`
+          : `Track this as an enhancement request and prioritize against current sprint goals: "${excerpt}".`;
+      case 'Question':
+        return `Answer this explicitly in product/docs so future reviews don't block on: "${excerpt}".`;
+      default:
+        return `Investigate this item and convert it into a concrete engineering task: "${excerpt}".`;
+    }
+  }
+
+  /**
+   * Count feedback items by type/category
+   */
+  private countTypes(items: FeedbackItem[]): Record<string, number> {
+    return items.reduce((acc, item) => {
+      const type = item.category || 'General';
+      acc[type] = (acc[type] || 0) + 1;
+      return acc;
+    }, {} as Record<string, number>);
+  }
+
+  /**
+   * Count total screenshots across all items
+   */
+  private countScreenshots(items: FeedbackItem[]): number {
+    return items.reduce((sum, item) => sum + item.screenshots.length, 0);
+  }
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+/**
+ * Singleton instance for easy import
+ */
+export const markdownGenerator = new MarkdownGeneratorImpl();
+
+// Re-export the class for testing
+export { MarkdownGeneratorImpl as MarkdownGenerator };