@bfra.me/workspace-analyzer 0.1.0

package/src/cli/commands/analyze.ts

@@ -0,0 +1,240 @@
+/**
+ * Analyze command implementation.
+ *
+ * Provides the main 'analyze' command for running workspace analysis
+ * with interactive and non-interactive modes.
+ */
+
+import type {AnalysisResult} from '../../types/index'
+import type {AnalyzeOptions, AnalyzerSelectionOption} from '../types'
+
+import path from 'node:path'
+import process from 'node:process'
+
+import {BUILTIN_ANALYZER_IDS} from '../../analyzers/index'
+import {analyzeWorkspace} from '../../api/analyze-workspace'
+import {createConsoleReporter} from '../../reporters/console-reporter'
+import {createJsonReporter} from '../../reporters/json-reporter'
+import {createMarkdownReporter} from '../../reporters/markdown-reporter'
+import {
+  createLogger,
+  createSpinner,
+  formatDuration,
+  formatSeveritySummary,
+  handleCancel,
+  selectAnalyzers,
+  showCancel,
+  showIntro,
+  showOutro,
+} from '../ui'
+
+/**
+ * Metadata for built-in analyzers used in selection UI.
+ */
+const ANALYZER_METADATA: Record<string, {label: string; hint: string}> = {
+  [BUILTIN_ANALYZER_IDS.PACKAGE_JSON]: {
+    label: 'Package.json Analyzer',
+    hint: 'Validates package.json structure and required fields',
+  },
+  [BUILTIN_ANALYZER_IDS.TSCONFIG]: {
+    label: 'TSConfig Analyzer',
+    hint: 'Checks TypeScript configuration consistency',
+  },
+  [BUILTIN_ANALYZER_IDS.ESLINT_CONFIG]: {
+    label: 'ESLint Config Analyzer',
+    hint: 'Validates ESLint configuration patterns',
+  },
+  [BUILTIN_ANALYZER_IDS.BUILD_CONFIG]: {
+    label: 'Build Config Analyzer',
+    hint: 'Analyzes tsup and build configuration',
+  },
+  [BUILTIN_ANALYZER_IDS.CONFIG_CONSISTENCY]: {
+    label: 'Config Consistency',
+    hint: 'Cross-validates multiple configuration files',
+  },
+  [BUILTIN_ANALYZER_IDS.VERSION_ALIGNMENT]: {
+    label: 'Version Alignment',
+    hint: 'Checks dependency version consistency',
+  },
+  [BUILTIN_ANALYZER_IDS.EXPORTS_FIELD]: {
+    label: 'Exports Field Analyzer',
+    hint: 'Validates package.json exports against source files',
+  },
+  [BUILTIN_ANALYZER_IDS.UNUSED_DEPENDENCY]: {
+    label: 'Unused Dependencies',
+    hint: 'Detects dependencies not used in source code',
+  },
+  [BUILTIN_ANALYZER_IDS.CIRCULAR_IMPORT]: {
+    label: 'Circular Imports',
+    hint: 'Finds circular import dependencies',
+  },
+  [BUILTIN_ANALYZER_IDS.PEER_DEPENDENCY]: {
+    label: 'Peer Dependencies',
+    hint: 'Validates peer dependency requirements',
+  },
+  [BUILTIN_ANALYZER_IDS.DUPLICATE_DEPENDENCY]: {
+    label: 'Duplicate Dependencies',
+    hint: 'Finds duplicate packages across workspace',
+  },
+  [BUILTIN_ANALYZER_IDS.ARCHITECTURAL]: {
+    label: 'Architecture',
+    hint: 'Validates architectural patterns and layers',
+  },
+  [BUILTIN_ANALYZER_IDS.DEAD_CODE]: {
+    label: 'Dead Code',
+    hint: 'Detects unreachable or unused exports',
+  },
+  [BUILTIN_ANALYZER_IDS.DUPLICATE_CODE]: {
+    label: 'Duplicate Code',
+    hint: 'Finds similar code patterns via AST fingerprinting',
+  },
+  [BUILTIN_ANALYZER_IDS.LARGE_DEPENDENCY]: {
+    label: 'Large Dependencies',
+    hint: 'Identifies oversized dependencies',
+  },
+  [BUILTIN_ANALYZER_IDS.TREE_SHAKING_BLOCKER]: {
+    label: 'Tree Shaking Blockers',
+    hint: 'Finds patterns that prevent tree shaking',
+  },
+}
+
+/**
+ * Gets available analyzer options for selection UI.
+ */
+function getAnalyzerOptions(): readonly AnalyzerSelectionOption[] {
+  return Object.entries(BUILTIN_ANALYZER_IDS).map(([_key, id]) => {
+    const metadata = ANALYZER_METADATA[id] ?? {
+      label: id,
+      hint: 'Analyzer',
+    }
+    return {
+      value: id,
+      label: metadata.label,
+      hint: metadata.hint,
+    }
+  })
+}
+
+/**
+ * Reports analysis results to the console or other formats.
+ */
+function reportResults(result: AnalysisResult, options: AnalyzeOptions): void {
+  if (options.json === true) {
+    const jsonReporter = createJsonReporter()
+    const report = jsonReporter.generate(result)
+    console.log(JSON.stringify(report, null, 2))
+    return
+  }
+
+  if (options.markdown === true) {
+    const mdReporter = createMarkdownReporter()
+    const report = mdReporter.generate(result)
+    console.log(report)
+    return
+  }
+
+  const consoleReporter = createConsoleReporter({verbose: options.verbose})
+  consoleReporter.generate(result)
+}
+
+/**
+ * Runs the analyze command.
+ */
+export async function runAnalyze(inputPath: string, options: AnalyzeOptions): Promise<void> {
+  const logger = createLogger(options)
+  const rootDir = path.resolve(options.root ?? inputPath)
+
+  if (options.quiet !== true) {
+    showIntro('🔍 Workspace Analyzer')
+  }
+
+  let selectedAnalyzers: readonly string[] | undefined
+
+  if (options.interactive === true) {
+    const availableAnalyzers = getAnalyzerOptions()
+    const selection = await selectAnalyzers(availableAnalyzers)
+
+    if (handleCancel(selection)) {
+      showCancel()
+      process.exit(0)
+    }
+
+    selectedAnalyzers = selection
+    logger.debug(`Selected ${selectedAnalyzers.length} analyzers: ${selectedAnalyzers.join(', ')}`)
+  }
+
+  if (options.dryRun === true) {
+    logger.info(`[DRY RUN] Would analyze workspace at: ${rootDir}`)
+    if (selectedAnalyzers != null && selectedAnalyzers.length > 0) {
+      logger.info(`[DRY RUN] Using analyzers: ${selectedAnalyzers.join(', ')}`)
+    } else {
+      logger.info('[DRY RUN] Using all analyzers')
+    }
+    if (options.config != null) {
+      logger.info(`[DRY RUN] Using config: ${options.config}`)
+    }
+    if (options.quiet !== true) {
+      showOutro('Dry run complete - no analysis performed')
+    }
+    return
+  }
+
+  if (options.fix === true) {
+    logger.warn('Auto-fix mode is not yet implemented. Running analysis only.')
+  }
+
+  const spinner = options.quiet === true ? undefined : createSpinner()
+  spinner?.start('Analyzing workspace...')
+
+  const startTime = Date.now()
+
+  const result = await analyzeWorkspace(rootDir, {
+    configPath: options.config,
+    verbose: options.verbose,
+    minSeverity: options.minSeverity,
+    analyzers:
+      selectedAnalyzers != null && selectedAnalyzers.length > 0
+        ? Object.fromEntries(
+            Object.values(BUILTIN_ANALYZER_IDS).map(id => [
+              id,
+              {enabled: selectedAnalyzers.includes(id)},
+            ]),
+          )
+        : undefined,
+    onProgress: progress => {
+      const totalSuffix = progress.total == null ? '' : `/${progress.total}`
+      const currentItem = progress.current ?? ''
+      const message = `${progress.phase}: ${currentItem} (${progress.processed}${totalSuffix})`
+      spinner?.message(message)
+      logger.debug(message)
+    },
+  })
+
+  const duration = Date.now() - startTime
+  spinner?.stop(`Analysis complete in ${formatDuration(duration)}`)
+
+  if (result.success) {
+    const analysisResult = result.data
+
+    reportResults(analysisResult, options)
+
+    if (options.quiet !== true) {
+      const summary = formatSeveritySummary(analysisResult.summary.bySeverity)
+      showOutro(`${summary} (${analysisResult.summary.totalIssues} total issues)`)
+    }
+
+    const hasErrors =
+      (analysisResult.summary.bySeverity.error ?? 0) > 0 ||
+      (analysisResult.summary.bySeverity.critical ?? 0) > 0
+
+    if (hasErrors) {
+      process.exit(1)
+    }
+  } else {
+    logger.error(`Analysis failed: ${result.error.message}`)
+    if (options.verbose === true && result.error.cause != null) {
+      logger.debug(`Cause: ${String(result.error.cause)}`)
+    }
+    process.exit(1)
+  }
+}

package/src/cli/commands/index.ts

@@ -0,0 +1,5 @@
+/**
+ * CLI commands barrel export.
+ */
+
+export {runAnalyze} from './analyze'

package/src/cli/index.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for workspace-analyzer.
+ *
+ * Provides interactive workspace analysis with progress reporting using @clack/prompts.
+ * Uses cac for argument parsing following doc-sync's CLI patterns.
+ */
+
+import type {AnalyzeOptions} from './types'
+
+import process from 'node:process'
+
+import {cac} from 'cac'
+import {consola} from 'consola'
+
+import {runAnalyze} from './commands/analyze'
+
+const cli = cac('workspace-analyzer')
+
+function registerAnalyzeCommand(
+  command: ReturnType<typeof cli.command>,
+): ReturnType<typeof cli.command> {
+  return command
+    .option('-c, --config <path>', 'Path to workspace-analyzer.config.ts file')
+    .option('-r, --root <dir>', 'Root directory of the workspace', {default: process.cwd()})
+    .option('--json', 'Output results as JSON')
+    .option('--markdown', 'Output results as Markdown')
+    .option('-i, --interactive', 'Use interactive analyzer selection')
+    .option('--fix', 'Attempt to auto-fix issues (placeholder for future)')
+    .option('-d, --dry-run', 'Preview what would be analyzed without running')
+    .option('-v, --verbose', 'Enable verbose logging')
+    .option('-q, --quiet', 'Suppress non-essential output')
+    .option(
+      '--min-severity <level>',
+      'Minimum severity level to report (info, warning, error, critical)',
+    )
+    .action(async (inputPath = '.', options: AnalyzeOptions) => {
+      const workspacePath = String(inputPath)
+
+      if (options.verbose === true) {
+        consola.level = 4
+      }
+
+      await runAnalyze(workspacePath, options)
+    })
+}
+
+// Default command: workspace-analyzer [path]
+registerAnalyzeCommand(cli.command('[path]', 'Analyze a workspace for issues'))
+
+// Explicit command: workspace-analyzer analyze [path]
+registerAnalyzeCommand(cli.command('analyze [path]', 'Analyze a workspace for issues'))
+
+cli.command('version', 'Show version information').action(() => {
+  consola.info('@bfra.me/workspace-analyzer v0.0.0')
+})
+
+cli.help()
+cli.version('0.0.0')
+
+cli.parse()

package/src/cli/types.ts

@@ -0,0 +1,65 @@
+/**
+ * Type definitions for CLI options and state.
+ */
+
+import type {Severity} from '../types/index'
+
+/**
+ * Global options available to all CLI commands.
+ */
+export interface GlobalOptions {
+  /** Root directory of the workspace (default: current working directory) */
+  readonly root: string
+  /** Path to configuration file */
+  readonly config?: string
+  /** Enable verbose output for debugging */
+  readonly verbose?: boolean
+  /** Suppress non-error output */
+  readonly quiet?: boolean
+}
+
+/**
+ * Options for the analyze command.
+ */
+export interface AnalyzeOptions extends GlobalOptions {
+  /** Output results as JSON */
+  readonly json?: boolean
+  /** Output results as Markdown */
+  readonly markdown?: boolean
+  /** Show what would be analyzed without making changes */
+  readonly dryRun?: boolean
+  /** Enable interactive mode for analyzer selection */
+  readonly interactive?: boolean
+  /** Attempt to auto-fix issues where supported */
+  readonly fix?: boolean
+  /** Minimum severity level to report */
+  readonly minSeverity?: Severity
+  /** Specific analyzers to run (empty means all) */
+  readonly analyzers?: readonly string[]
+}
+
+/**
+ * Option for analyzer selection in interactive mode.
+ */
+export interface AnalyzerSelectionOption {
+  /** Analyzer ID */
+  readonly value: string
+  /** Display label */
+  readonly label: string
+  /** Optional hint text */
+  readonly hint?: string
+}
+
+/**
+ * Status information for individual analyzer results.
+ */
+export interface AnalyzerStatus {
+  /** Analyzer ID */
+  readonly analyzerId: string
+  /** Whether the analyzer completed successfully */
+  readonly success: boolean
+  /** Number of issues found */
+  readonly issueCount: number
+  /** Duration in milliseconds */
+  readonly durationMs: number
+}

package/src/cli/ui.ts

@@ -0,0 +1,213 @@
+/**
+ * UI utilities for CLI using @clack/prompts.
+ *
+ * Provides a consistent interface for terminal output, progress reporting,
+ * and interactive prompts adapted from doc-sync's UI patterns.
+ */
+
+import type {AnalyzerSelectionOption, GlobalOptions} from './types'
+
+import * as p from '@clack/prompts'
+import {consola} from 'consola'
+
+/**
+ * Logger interface for consistent output across CLI commands.
+ */
+export interface Logger {
+  readonly info: (message: string) => void
+  readonly success: (message: string) => void
+  readonly warn: (message: string) => void
+  readonly error: (message: string) => void
+  readonly debug: (message: string) => void
+}
+
+/**
+ * Options for creating a logger.
+ */
+export interface LoggerOptions {
+  readonly verbose?: boolean
+  readonly quiet?: boolean
+}
+
+/**
+ * Creates a logger that respects verbose/quiet options.
+ */
+export function createLogger(options: LoggerOptions): Logger {
+  const {verbose = false, quiet = false} = options
+
+  return {
+    info(message: string): void {
+      if (!quiet) {
+        p.log.info(message)
+      }
+    },
+    success(message: string): void {
+      if (!quiet) {
+        p.log.success(message)
+      }
+    },
+    warn(message: string): void {
+      p.log.warn(message)
+    },
+    error(message: string): void {
+      p.log.error(message)
+    },
+    debug(message: string): void {
+      if (verbose) {
+        consola.debug(message)
+      }
+    },
+  }
+}
+
+/**
+ * Shows intro banner for the CLI.
+ */
+export function showIntro(title: string): void {
+  p.intro(title)
+}
+
+/**
+ * Shows outro message when CLI completes.
+ */
+export function showOutro(message: string): void {
+  p.outro(message)
+}
+
+/**
+ * Creates a spinner for long-running operations.
+ */
+export function createSpinner(): ReturnType<typeof p.spinner> {
+  return p.spinner()
+}
+
+/**
+ * Shows cancellation message when user cancels operation.
+ */
+export function showCancel(message = 'Operation cancelled.'): void {
+  p.cancel(message)
+}
+
+/**
+ * Checks if a value represents a user cancellation.
+ */
+export function handleCancel(value: unknown): value is symbol {
+  return p.isCancel(value)
+}
+
+/**
+ * Prompts user to select analyzers to run.
+ */
+export async function selectAnalyzers(
+  availableAnalyzers: readonly AnalyzerSelectionOption[],
+): Promise<readonly string[] | symbol> {
+  if (availableAnalyzers.length === 0) {
+    return []
+  }
+
+  const options = availableAnalyzers.map(analyzer => ({
+    value: analyzer.value,
+    label: analyzer.label,
+    hint: analyzer.hint,
+  }))
+
+  const selected = await p.multiselect({
+    message: 'Select analyzers to run',
+    options,
+    required: false,
+    initialValues: options.map(o => o.value),
+  })
+
+  return selected
+}
+
+/**
+ * Prompts user to confirm an action.
+ */
+export async function confirmAction(message: string): Promise<boolean | symbol> {
+  return p.confirm({message})
+}
+
+/**
+ * Formats a duration in milliseconds to a human-readable string.
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) {
+    return `${ms}ms`
+  }
+  if (ms < 60000) {
+    return `${(ms / 1000).toFixed(1)}s`
+  }
+  const minutes = Math.floor(ms / 60000)
+  const seconds = Math.round((ms % 60000) / 1000)
+  return `${minutes}m ${seconds}s`
+}
+
+/**
+ * Formats a list of items for display.
+ */
+export function formatList(items: readonly string[], maxDisplay = 3): string {
+  if (items.length === 0) {
+    return 'none'
+  }
+  if (items.length === 1) {
+    return items[0] ?? 'unknown'
+  }
+  if (items.length <= maxDisplay) {
+    return items.join(', ')
+  }
+  return `${items.slice(0, maxDisplay).join(', ')} and ${items.length - maxDisplay} more`
+}
+
+/**
+ * Creates a progress callback suitable for the onProgress option.
+ */
+export function createProgressCallback(options: GlobalOptions): (message: string) => void {
+  const logger = createLogger(options)
+  return (message: string) => {
+    logger.debug(message)
+  }
+}
+
+/**
+ * Formats issue count with appropriate color indicator.
+ */
+export function formatIssueCount(
+  count: number,
+  severity: 'info' | 'warning' | 'error' | 'critical',
+): string {
+  const severityIndicators = {
+    info: 'ℹ️',
+    warning: '⚠️',
+    error: '❌',
+    critical: '🚨',
+  }
+  return `${severityIndicators[severity]} ${count} ${severity}${count === 1 ? '' : 's'}`
+}
+
+/**
+ * Formats a severity-based summary for display.
+ */
+export function formatSeveritySummary(bySeverity: Readonly<Record<string, number>>): string {
+  const parts: string[] = []
+
+  const critical = bySeverity.critical ?? 0
+  const error = bySeverity.error ?? 0
+  const warning = bySeverity.warning ?? 0
+  const info = bySeverity.info ?? 0
+
+  if (critical > 0) {
+    parts.push(formatIssueCount(critical, 'critical'))
+  }
+  if (error > 0) {
+    parts.push(formatIssueCount(error, 'error'))
+  }
+  if (warning > 0) {
+    parts.push(formatIssueCount(warning, 'warning'))
+  }
+  if (info > 0) {
+    parts.push(formatIssueCount(info, 'info'))
+  }
+
+  return parts.length > 0 ? parts.join(', ') : '✅ No issues'
+}

package/src/cli.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for workspace-analyzer.
+ *
+ * Re-exports from the structured CLI module for backwards compatibility.
+ * The actual CLI implementation is in src/cli/index.ts.
+ */
+
+import './cli/index'