@bfra.me/workspace-analyzer 0.1.0

package/src/reporters/console-reporter.ts

@@ -0,0 +1,355 @@
+/**
+ * Console reporter for terminal output with colors and formatting.
+ *
+ * Generates colorful terminal output using consola and @clack/prompts
+ * for interactive analysis feedback and CI/CD integration.
+ */
+
+import type {AnalysisResult, Issue, Severity} from '../types/index'
+import type {GroupedIssues, Reporter, ReportOptions, ReportSummary} from './reporter'
+
+import * as p from '@clack/prompts'
+import {consola} from 'consola'
+
+import {
+  calculateSummary,
+  CATEGORY_CONFIG,
+  DEFAULT_REPORT_OPTIONS,
+  filterIssuesForReport,
+  formatDuration,
+  getRelativePath,
+  groupIssues,
+  SEVERITY_CONFIG,
+  truncateText,
+} from './reporter'
+
+/**
+ * Options specific to console reporter.
+ */
+export interface ConsoleReporterOptions extends ReportOptions {
+  /** Whether to use colors (auto-detected by default) */
+  readonly colors?: boolean
+  /** Whether to show verbose output with full descriptions */
+  readonly verbose?: boolean
+  /** Whether to show compact output (one line per issue) */
+  readonly compact?: boolean
+  /** Maximum width for text wrapping */
+  readonly maxWidth?: number
+  /** Whether to use @clack/prompts styling */
+  readonly useClack?: boolean
+}
+
+/**
+ * Create a console reporter instance.
+ *
+ * @example
+ * ```ts
+ * const reporter = createConsoleReporter({verbose: true})
+ * reporter.generate(analysisResult) // Outputs to console
+ * ```
+ */
+export function createConsoleReporter(defaultOptions?: ConsoleReporterOptions): Reporter {
+  return {
+    id: 'console',
+    name: 'Console Reporter',
+    generate(result: AnalysisResult, options?: ReportOptions): string {
+      const mergedOptions: ConsoleReporterOptions = {
+        ...DEFAULT_REPORT_OPTIONS,
+        ...defaultOptions,
+        ...options,
+      }
+
+      const output = generateConsoleOutput(result, mergedOptions)
+      printToConsole(output, mergedOptions)
+      return output.join('\n')
+    },
+    stream(result: AnalysisResult, write: (chunk: string) => void, options?: ReportOptions): void {
+      const output = this.generate(result, options)
+      write(output)
+    },
+  }
+}
+
+/**
+ * Generate console output lines.
+ */
+function generateConsoleOutput(result: AnalysisResult, options: ConsoleReporterOptions): string[] {
+  const lines: string[] = []
+  const filteredIssues = filterIssuesForReport(result.issues, options)
+  const summary = calculateSummary({...result, issues: filteredIssues})
+  const grouped = groupIssues(filteredIssues, options.groupBy)
+
+  lines.push(...generateHeader(summary))
+  lines.push('')
+
+  if (options.includeSummary) {
+    lines.push(...generateSummary(summary))
+    lines.push('')
+  }
+
+  lines.push(...generateIssuesList(grouped, result.workspacePath, options))
+
+  lines.push('')
+  lines.push(...generateFooter(summary, result))
+
+  return lines
+}
+
+/**
+ * Generate header section.
+ */
+function generateHeader(summary: ReportSummary): string[] {
+  const lines: string[] = []
+  const status = getStatusIcon(summary.highestSeverity)
+  const statusText =
+    summary.totalIssues === 0 ? 'No issues found' : `${summary.totalIssues} issue(s) found`
+
+  lines.push('─'.repeat(60))
+  lines.push(`${status} Workspace Analysis Report`)
+  lines.push(`   ${statusText}`)
+  lines.push('─'.repeat(60))
+
+  return lines
+}
+
+/**
+ * Generate summary section.
+ */
+function generateSummary(summary: ReportSummary): string[] {
+  const lines: string[] = []
+
+  lines.push('📊 Summary')
+  lines.push('')
+
+  const severityCounts: string[] = []
+  for (const severity of ['critical', 'error', 'warning', 'info'] as const) {
+    const count = summary.bySeverity[severity]
+    if (count > 0) {
+      const icon = SEVERITY_CONFIG[severity].emoji
+      severityCounts.push(`${icon} ${count} ${severity}`)
+    }
+  }
+
+  if (severityCounts.length > 0) {
+    lines.push(`   ${severityCounts.join('  |  ')}`)
+  } else {
+    lines.push('   ✅ No issues!')
+  }
+
+  lines.push('')
+  lines.push(
+    `   📦 ${summary.packagesAnalyzed} packages  |  📄 ${summary.filesAnalyzed} files  |  ⏱️  ${formatDuration(summary.durationMs)}`,
+  )
+
+  return lines
+}
+
+/**
+ * Generate issues list.
+ */
+function generateIssuesList(
+  groups: readonly GroupedIssues[],
+  workspacePath: string,
+  options: ConsoleReporterOptions,
+): string[] {
+  const lines: string[] = []
+
+  if (groups.length === 0 || groups.every(g => g.count === 0)) {
+    lines.push('✅ No issues to report!')
+    return lines
+  }
+
+  for (const group of groups) {
+    if (group.count === 0) {
+      continue
+    }
+
+    lines.push('')
+    lines.push(...generateGroupSection(group, workspacePath, options))
+  }
+
+  return lines
+}
+
+/**
+ * Generate a group section.
+ */
+function generateGroupSection(
+  group: GroupedIssues,
+  workspacePath: string,
+  options: ConsoleReporterOptions,
+): string[] {
+  const lines: string[] = []
+
+  const groupIcon = getGroupIcon(group.key, options.groupBy)
+  lines.push(`${groupIcon} ${group.label} (${group.count})`)
+  lines.push('')
+
+  const maxIssues = options.maxIssuesPerGroup ?? 50
+  const issuesToShow = group.issues.slice(0, maxIssues)
+  const remainingCount = group.count - issuesToShow.length
+
+  for (const issue of issuesToShow) {
+    if (options.compact) {
+      lines.push(formatCompactIssue(issue, workspacePath))
+    } else {
+      lines.push(...formatDetailedIssue(issue, workspacePath, options))
+    }
+  }
+
+  if (remainingCount > 0) {
+    lines.push(`   ... and ${remainingCount} more issue(s)`)
+  }
+
+  return lines
+}
+
+/**
+ * Format an issue in compact mode (single line).
+ */
+function formatCompactIssue(issue: Issue, workspacePath: string): string {
+  const icon = SEVERITY_CONFIG[issue.severity].emoji
+  const relativePath = getRelativePath(issue.location.filePath, workspacePath)
+  const location =
+    issue.location.line === undefined ? relativePath : `${relativePath}:${issue.location.line}`
+  const title = truncateText(issue.title, 50)
+
+  return `   ${icon} ${location}: ${title}`
+}
+
+/**
+ * Format an issue in detailed mode.
+ */
+function formatDetailedIssue(
+  issue: Issue,
+  workspacePath: string,
+  options: ConsoleReporterOptions,
+): string[] {
+  const lines: string[] = []
+  const icon = SEVERITY_CONFIG[issue.severity].emoji
+  const severityLabel = SEVERITY_CONFIG[issue.severity].label.toUpperCase()
+
+  lines.push(`   ${icon} [${severityLabel}] ${issue.title}`)
+
+  const relativePath = getRelativePath(issue.location.filePath, workspacePath)
+  let location = `      📍 ${relativePath}`
+  if (issue.location.line !== undefined) {
+    location += `:${issue.location.line}`
+    if (issue.location.column !== undefined) {
+      location += `:${issue.location.column}`
+    }
+  }
+  lines.push(location)
+
+  if (options.verbose) {
+    const maxWidth = options.maxWidth ?? 80
+    const wrappedDesc = wrapText(issue.description, maxWidth - 9)
+    for (const line of wrappedDesc) {
+      lines.push(`         ${line}`)
+    }
+  }
+
+  if (options.includeSuggestions && issue.suggestion !== undefined) {
+    lines.push(`      💡 ${issue.suggestion}`)
+  }
+
+  lines.push('')
+
+  return lines
+}
+
+/**
+ * Generate footer section.
+ */
+function generateFooter(summary: ReportSummary, result: AnalysisResult): string[] {
+  const lines: string[] = []
+
+  lines.push('─'.repeat(60))
+
+  if (summary.totalIssues === 0) {
+    lines.push('✅ Your workspace looks great!')
+  } else {
+    const recommendations: string[] = []
+    if (summary.bySeverity.critical > 0 || summary.bySeverity.error > 0) {
+      recommendations.push('Fix critical and error issues first')
+    }
+    if (summary.bySeverity.warning > 0) {
+      recommendations.push('Review warnings for potential improvements')
+    }
+
+    if (recommendations.length > 0) {
+      lines.push('💡 Recommendations:')
+      for (const rec of recommendations) {
+        lines.push(`   • ${rec}`)
+      }
+    }
+  }
+
+  const duration = formatDuration(result.completedAt.getTime() - result.startedAt.getTime())
+  lines.push('')
+  lines.push(`Analysis completed in ${duration}`)
+
+  return lines
+}
+
+/**
+ * Print output to console using appropriate method.
+ */
+function printToConsole(lines: string[], options: ConsoleReporterOptions): void {
+  if (options.useClack) {
+    p.log.message(lines.join('\n'))
+  } else {
+    for (const line of lines) {
+      consola.log(line)
+    }
+  }
+}
+
+/**
+ * Get status icon based on severity.
+ */
+function getStatusIcon(severity: Severity | null): string {
+  if (severity === null) {
+    return '✅'
+  }
+  return SEVERITY_CONFIG[severity].emoji
+}
+
+/**
+ * Get group icon based on groupBy option.
+ */
+function getGroupIcon(key: string, groupBy: ReportOptions['groupBy']): string {
+  if (groupBy === 'severity') {
+    return SEVERITY_CONFIG[key as Severity]?.emoji ?? '📋'
+  }
+  if (groupBy === 'category') {
+    return CATEGORY_CONFIG[key as keyof typeof CATEGORY_CONFIG]?.emoji ?? '📋'
+  }
+  return '📄'
+}
+
+/**
+ * Wrap text to specified width.
+ */
+function wrapText(text: string, maxWidth: number): string[] {
+  const words = text.split(/\s+/)
+  const lines: string[] = []
+  let currentLine = ''
+
+  for (const word of words) {
+    if (currentLine.length + word.length + 1 <= maxWidth) {
+      currentLine += (currentLine.length > 0 ? ' ' : '') + word
+    } else {
+      if (currentLine.length > 0) {
+        lines.push(currentLine)
+      }
+      currentLine = word
+    }
+  }
+
+  if (currentLine.length > 0) {
+    lines.push(currentLine)
+  }
+
+  return lines
+}

package/src/reporters/index.ts

@@ -0,0 +1,49 @@
+/**
+ * Reporter exports for workspace analysis output.
+ *
+ * Provides a unified API for generating analysis reports in various formats:
+ * - JSON: Machine-readable output for CI/CD integration
+ * - Markdown: Human-readable reports for documentation and review
+ * - Console: Terminal output with colors for interactive feedback
+ */
+
+// Console reporter exports
+export type {ConsoleReporterOptions} from './console-reporter'
+export {createConsoleReporter} from './console-reporter'
+
+// JSON reporter exports
+export type {
+  JsonReport,
+  JsonReporterOptions,
+  JsonReportGroup,
+  JsonReportIssue,
+  JsonReportLocation,
+  JsonReportMetadata,
+} from './json-reporter'
+export {createJsonReporter} from './json-reporter'
+
+// Markdown reporter exports
+export type {MarkdownReporterOptions} from './markdown-reporter'
+export {createMarkdownReporter} from './markdown-reporter'
+
+// Core reporter types and utilities
+export type {
+  GroupedIssues,
+  Reporter,
+  ReporterFactory,
+  ReportFormat,
+  ReportOptions,
+  ReportSummary,
+} from './reporter'
+export {
+  calculateSummary,
+  CATEGORY_CONFIG,
+  DEFAULT_REPORT_OPTIONS,
+  filterIssuesForReport,
+  formatDuration,
+  formatLocation,
+  getRelativePath,
+  groupIssues,
+  SEVERITY_CONFIG,
+  truncateText,
+} from './reporter'

package/src/reporters/json-reporter.ts

@@ -0,0 +1,273 @@
+/**
+ * JSON reporter for machine-readable analysis output.
+ *
+ * Generates structured JSON reports suitable for CI/CD integration,
+ * programmatic processing, and data analysis tools.
+ */
+
+import type {AnalysisResult, Issue} from '../types/index'
+import type {Reporter, ReportOptions, ReportSummary} from './reporter'
+
+import {
+  calculateSummary,
+  DEFAULT_REPORT_OPTIONS,
+  filterIssuesForReport,
+  getRelativePath,
+  groupIssues,
+} from './reporter'
+
+/**
+ * JSON report structure for serialization.
+ */
+export interface JsonReport {
+  /** Schema version for compatibility checking */
+  readonly $schema?: string
+  /** Report metadata */
+  readonly metadata: JsonReportMetadata
+  /** Summary statistics */
+  readonly summary: ReportSummary
+  /** All issues (filtered based on options) */
+  readonly issues: readonly JsonReportIssue[]
+  /** Issues grouped by the specified key */
+  readonly groupedIssues?: readonly JsonReportGroup[]
+}
+
+/**
+ * Report metadata for provenance tracking.
+ */
+export interface JsonReportMetadata {
+  /** Report generation timestamp (ISO 8601) */
+  readonly generatedAt: string
+  /** Analysis start timestamp (ISO 8601) */
+  readonly analysisStartedAt: string
+  /** Analysis completion timestamp (ISO 8601) */
+  readonly analysisCompletedAt: string
+  /** Workspace path that was analyzed */
+  readonly workspacePath: string
+  /** Report options used for generation */
+  readonly reportOptions: Partial<ReportOptions>
+  /** Analyzer version (if available) */
+  readonly version?: string
+}
+
+/**
+ * Issue representation in JSON report.
+ */
+export interface JsonReportIssue {
+  /** Issue identifier */
+  readonly id: string
+  /** Issue title */
+  readonly title: string
+  /** Issue description */
+  readonly description: string
+  /** Severity level */
+  readonly severity: Issue['severity']
+  /** Issue category */
+  readonly category: Issue['category']
+  /** File location */
+  readonly location: JsonReportLocation
+  /** Related locations (for multi-file issues like circular imports) */
+  readonly relatedLocations?: readonly JsonReportLocation[]
+  /** Suggested fix */
+  readonly suggestion?: string
+  /** Additional metadata */
+  readonly metadata?: Readonly<Record<string, unknown>>
+}
+
+/**
+ * Location representation in JSON report.
+ */
+export interface JsonReportLocation {
+  /** File path (relative to workspace root) */
+  readonly file: string
+  /** Absolute file path */
+  readonly absolutePath: string
+  /** Line number (1-indexed) */
+  readonly line?: number
+  /** Column number (1-indexed) */
+  readonly column?: number
+  /** End line number (1-indexed) */
+  readonly endLine?: number
+  /** End column number (1-indexed) */
+  readonly endColumn?: number
+}
+
+/**
+ * Grouped issues in JSON report.
+ */
+export interface JsonReportGroup {
+  /** Group key */
+  readonly key: string
+  /** Group label */
+  readonly label: string
+  /** Number of issues in group */
+  readonly count: number
+  /** Issues in this group */
+  readonly issues: readonly JsonReportIssue[]
+}
+
+/**
+ * Options specific to JSON reporter.
+ */
+export interface JsonReporterOptions extends ReportOptions {
+  /** Whether to pretty-print JSON output */
+  readonly prettyPrint?: boolean
+  /** Indentation size for pretty-printing (default: 2) */
+  readonly indentation?: number
+  /** Whether to include grouped issues section */
+  readonly includeGroupedIssues?: boolean
+  /** JSON schema URL for validation */
+  readonly schemaUrl?: string
+}
+
+/**
+ * Create a JSON reporter instance.
+ *
+ * @example
+ * ```ts
+ * const reporter = createJsonReporter({prettyPrint: true})
+ * const json = reporter.generate(analysisResult)
+ * await fs.writeFile('report.json', json)
+ * ```
+ */
+export function createJsonReporter(defaultOptions?: JsonReporterOptions): Reporter {
+  return {
+    id: 'json',
+    name: 'JSON Reporter',
+    generate(result: AnalysisResult, options?: ReportOptions): string {
+      const mergedOptions: JsonReporterOptions = {
+        ...DEFAULT_REPORT_OPTIONS,
+        ...defaultOptions,
+        ...options,
+      }
+
+      const report = generateJsonReport(result, mergedOptions)
+      const prettyPrint = mergedOptions.prettyPrint ?? true
+      const indentation = mergedOptions.indentation ?? 2
+
+      return prettyPrint ? JSON.stringify(report, null, indentation) : JSON.stringify(report)
+    },
+    stream(result: AnalysisResult, write: (chunk: string) => void, options?: ReportOptions): void {
+      const output = this.generate(result, options)
+      write(output)
+    },
+  }
+}
+
+/**
+ * Generate the complete JSON report structure.
+ */
+function generateJsonReport(result: AnalysisResult, options: JsonReporterOptions): JsonReport {
+  const filteredIssues = filterIssuesForReport(result.issues, options)
+  const summary = calculateSummary({...result, issues: filteredIssues})
+
+  const baseReport: JsonReport = {
+    metadata: generateMetadata(result, options),
+    summary,
+    issues: filteredIssues.map(issue => formatIssueForJson(issue, result.workspacePath, options)),
+  }
+
+  const report: JsonReport =
+    options.schemaUrl === undefined ? baseReport : {$schema: options.schemaUrl, ...baseReport}
+
+  if (options.includeGroupedIssues ?? options.groupBy !== 'none') {
+    const grouped = groupIssues(filteredIssues, options.groupBy)
+    return {
+      ...report,
+      groupedIssues: grouped.map(group => ({
+        key: group.key,
+        label: group.label,
+        count: group.count,
+        issues: group.issues.map(issue => formatIssueForJson(issue, result.workspacePath, options)),
+      })),
+    }
+  }
+
+  return report
+}
+
+/**
+ * Generate report metadata.
+ */
+function generateMetadata(
+  result: AnalysisResult,
+  options: JsonReporterOptions,
+): JsonReportMetadata {
+  const {schemaUrl, prettyPrint, indentation, includeGroupedIssues, ...reportOptions} = options
+
+  return {
+    generatedAt: new Date().toISOString(),
+    analysisStartedAt: result.startedAt.toISOString(),
+    analysisCompletedAt: result.completedAt.toISOString(),
+    workspacePath: result.workspacePath,
+    reportOptions,
+  }
+}
+
+/**
+ * Format a single issue for JSON output.
+ *
+ * Accumulates optional properties (relatedLocations, suggestion, metadata)
+ * based on issue data and report options.
+ */
+function formatIssueForJson(
+  issue: Issue,
+  workspacePath: string,
+  options: JsonReporterOptions,
+): JsonReportIssue {
+  let jsonIssue: JsonReportIssue = {
+    id: issue.id,
+    title: issue.title,
+    description: issue.description,
+    severity: issue.severity,
+    category: issue.category,
+    location: formatLocationForJson(issue.location, workspacePath, options),
+  }
+
+  if (issue.relatedLocations !== undefined && issue.relatedLocations.length > 0) {
+    jsonIssue = {
+      ...jsonIssue,
+      relatedLocations: issue.relatedLocations.map(loc =>
+        formatLocationForJson(loc, workspacePath, options),
+      ),
+    }
+  }
+
+  if (options.includeSuggestions === true && issue.suggestion !== undefined) {
+    jsonIssue = {...jsonIssue, suggestion: issue.suggestion}
+  }
+
+  if (options.includeMetadata === true && issue.metadata !== undefined) {
+    jsonIssue = {...jsonIssue, metadata: issue.metadata}
+  }
+
+  return jsonIssue
+}
+
+/**
+ * Format a location for JSON output.
+ */
+function formatLocationForJson(
+  location: Issue['location'],
+  workspacePath: string,
+  options: JsonReporterOptions,
+): JsonReportLocation {
+  const baseLocation: JsonReportLocation = {
+    file: getRelativePath(location.filePath, workspacePath),
+    absolutePath: location.filePath,
+  }
+
+  if (!options.includeLocation) {
+    return baseLocation
+  }
+
+  const result: JsonReportLocation = {
+    ...baseLocation,
+    ...(location.line === undefined ? {} : {line: location.line}),
+    ...(location.column === undefined ? {} : {column: location.column}),
+    ...(location.endLine === undefined ? {} : {endLine: location.endLine}),
+    ...(location.endColumn === undefined ? {} : {endColumn: location.endColumn}),
+  }
+
+  return result
+}