@bfra.me/workspace-analyzer 0.1.0

package/src/analyzers/duplicate-dependency-analyzer.ts

@@ -0,0 +1,381 @@
+/**
+ * DuplicateDependencyAnalyzer - Detects duplicate and inconsistent dependencies across workspace packages.
+ *
+ * Identifies:
+ * - Same dependency with different versions across packages
+ * - Dependencies that could be hoisted to workspace root
+ * - Redundant devDependencies that match production dependencies
+ * - Version conflicts that may cause runtime issues
+ */
+
+import type {WorkspacePackage} from '../scanner/workspace-scanner'
+import type {Issue, IssueLocation, Severity} from '../types/index'
+import type {Result} from '../types/result'
+import type {AnalysisContext, Analyzer, AnalyzerError, AnalyzerMetadata} from './analyzer'
+
+import {ok} from '@bfra.me/es/result'
+
+import {createIssue, filterIssues} from './analyzer'
+
+/**
+ * Configuration options specific to DuplicateDependencyAnalyzer.
+ */
+export interface DuplicateDependencyAnalyzerOptions {
+  /** Ignore version differences for these packages */
+  readonly ignorePackages?: readonly string[]
+  /** Severity for version conflicts */
+  readonly conflictSeverity?: Severity
+  /** Whether to suggest hoisting common dependencies */
+  readonly suggestHoisting?: boolean
+  /** Minimum number of packages using a dependency to suggest hoisting */
+  readonly hoistingThreshold?: number
+  /** Check for redundant dev dependencies */
+  readonly checkRedundantDev?: boolean
+}
+
+const DEFAULT_OPTIONS: Required<DuplicateDependencyAnalyzerOptions> = {
+  ignorePackages: [],
+  conflictSeverity: 'warning',
+  suggestHoisting: true,
+  hoistingThreshold: 3,
+  checkRedundantDev: true,
+}
+
+export const duplicateDependencyAnalyzerMetadata: AnalyzerMetadata = {
+  id: 'duplicate-dependency',
+  name: 'Duplicate Dependency Analyzer',
+  description: 'Detects duplicate and version-inconsistent dependencies across workspace packages',
+  categories: ['dependency'],
+  defaultSeverity: 'warning',
+}
+
+/**
+ * Information about a dependency occurrence.
+ */
+interface DependencyOccurrence {
+  readonly packageName: string
+  readonly version: string
+  readonly type: 'dependencies' | 'devDependencies' | 'peerDependencies' | 'optionalDependencies'
+  readonly packageJsonPath: string
+}
+
+/**
+ * Aggregated dependency information across all packages.
+ */
+interface DependencyInfo {
+  readonly dependencyName: string
+  readonly occurrences: readonly DependencyOccurrence[]
+  readonly versions: readonly string[]
+  readonly hasConflict: boolean
+}
+
+/**
+ * Creates a DuplicateDependencyAnalyzer instance.
+ *
+ * @example
+ * ```ts
+ * const analyzer = createDuplicateDependencyAnalyzer({
+ *   conflictSeverity: 'error',
+ *   suggestHoisting: true,
+ * })
+ * const result = await analyzer.analyze(context)
+ * ```
+ */
+export function createDuplicateDependencyAnalyzer(
+  options: DuplicateDependencyAnalyzerOptions = {},
+): Analyzer {
+  const resolvedOptions = {...DEFAULT_OPTIONS, ...options}
+
+  return {
+    metadata: duplicateDependencyAnalyzerMetadata,
+    analyze: async (context: AnalysisContext): Promise<Result<readonly Issue[], AnalyzerError>> => {
+      const issues: Issue[] = []
+
+      context.reportProgress?.('Collecting dependency information across workspace...')
+
+      const dependencyMap = collectDependencies(context.packages)
+
+      context.reportProgress?.('Analyzing for duplicates and conflicts...')
+
+      // Check for version conflicts
+      for (const [depName, info] of dependencyMap) {
+        if (isIgnored(depName, resolvedOptions.ignorePackages)) {
+          continue
+        }
+
+        if (info.hasConflict) {
+          issues.push(createVersionConflictIssue(info, resolvedOptions))
+        }
+
+        // Suggest hoisting if same version used in multiple packages
+        if (
+          resolvedOptions.suggestHoisting &&
+          info.occurrences.length >= resolvedOptions.hoistingThreshold &&
+          !info.hasConflict
+        ) {
+          issues.push(createHoistingSuggestion(info, resolvedOptions))
+        }
+      }
+
+      // Check for redundant dev dependencies
+      if (resolvedOptions.checkRedundantDev) {
+        for (const pkg of context.packages) {
+          issues.push(...checkRedundantDevDependencies(pkg))
+        }
+      }
+
+      return ok(filterIssues(issues, context.config))
+    },
+  }
+}
+
+/**
+ * Collects all dependencies from all packages into a unified map.
+ */
+function collectDependencies(packages: readonly WorkspacePackage[]): Map<string, DependencyInfo> {
+  const depMap = new Map<string, DependencyOccurrence[]>()
+
+  for (const pkg of packages) {
+    const pkgJson = pkg.packageJson
+
+    collectFromObject(depMap, pkg, pkgJson.dependencies, 'dependencies')
+    collectFromObject(depMap, pkg, pkgJson.devDependencies, 'devDependencies')
+    collectFromObject(depMap, pkg, pkgJson.peerDependencies, 'peerDependencies')
+    collectFromObject(depMap, pkg, pkgJson.optionalDependencies, 'optionalDependencies')
+  }
+
+  const result = new Map<string, DependencyInfo>()
+
+  for (const [depName, occurrences] of depMap) {
+    const versions = [...new Set(occurrences.map(o => normalizeVersion(o.version)))].sort()
+    const hasConflict = versions.length > 1
+
+    result.set(depName, {
+      dependencyName: depName,
+      occurrences,
+      versions,
+      hasConflict,
+    })
+  }
+
+  return result
+}
+
+/**
+ * Collects dependencies from a dependency object.
+ */
+function collectFromObject(
+  depMap: Map<string, DependencyOccurrence[]>,
+  pkg: WorkspacePackage,
+  deps: Readonly<Record<string, string>> | undefined,
+  type: DependencyOccurrence['type'],
+): void {
+  if (deps === undefined) {
+    return
+  }
+
+  for (const [depName, version] of Object.entries(deps)) {
+    const occurrence: DependencyOccurrence = {
+      packageName: pkg.name,
+      version,
+      type,
+      packageJsonPath: pkg.packageJsonPath,
+    }
+
+    const existing = depMap.get(depName)
+    if (existing === undefined) {
+      depMap.set(depName, [occurrence])
+    } else {
+      existing.push(occurrence)
+    }
+  }
+}
+
+/**
+ * Normalizes a version string for comparison.
+ * Removes workspace: prefix and leading ^ or ~ for basic comparison.
+ */
+function normalizeVersion(version: string): string {
+  let normalized = version
+
+  // Handle workspace protocol
+  if (normalized.startsWith('workspace:')) {
+    normalized = normalized.slice('workspace:'.length)
+  }
+
+  // Keep the original if it's a range operator we want to compare
+  // Only normalize simple prefixes for exact matching
+  if (normalized.startsWith('^') || normalized.startsWith('~')) {
+    return normalized
+  }
+
+  return normalized
+}
+
+/**
+ * Checks if a dependency should be ignored.
+ */
+function isIgnored(depName: string, ignorePackages: readonly string[]): boolean {
+  return ignorePackages.some(pattern => {
+    if (pattern.includes('*')) {
+      const regex = new RegExp(`^${pattern.replaceAll('*', '.*')}$`)
+      return regex.test(depName)
+    }
+    return depName === pattern
+  })
+}
+
+/**
+ * Creates an issue for a version conflict.
+ */
+function createVersionConflictIssue(
+  info: DependencyInfo,
+  options: Required<DuplicateDependencyAnalyzerOptions>,
+): Issue {
+  const firstOccurrence = info.occurrences[0]
+  const location: IssueLocation = {
+    filePath: firstOccurrence?.packageJsonPath ?? '',
+  }
+
+  const relatedLocations: IssueLocation[] = info.occurrences.slice(1).map(o => ({
+    filePath: o.packageJsonPath,
+  }))
+
+  const versionList = info.occurrences
+    .map(o => `  - ${o.packageName}: ${o.version} (${o.type})`)
+    .join('\n')
+
+  return createIssue({
+    id: 'version-conflict',
+    title: `Version conflict: ${info.dependencyName}`,
+    description: `Dependency "${info.dependencyName}" has ${info.versions.length} different versions across packages:\n${versionList}`,
+    severity: options.conflictSeverity,
+    category: 'dependency',
+    location,
+    relatedLocations,
+    suggestion: `Align all packages to use the same version of "${info.dependencyName}" to avoid potential runtime issues`,
+    metadata: {
+      dependencyName: info.dependencyName,
+      versions: info.versions,
+      packages: info.occurrences.map(o => o.packageName),
+    },
+  })
+}
+
+/**
+ * Creates a suggestion to hoist a dependency.
+ */
+function createHoistingSuggestion(
+  info: DependencyInfo,
+  _options: Required<DuplicateDependencyAnalyzerOptions>,
+): Issue {
+  const firstOccurrence = info.occurrences[0]
+  const location: IssueLocation = {
+    filePath: firstOccurrence?.packageJsonPath ?? '',
+  }
+
+  const packageCount = info.occurrences.length
+  const packageNames = info.occurrences.map(o => o.packageName).join(', ')
+
+  return createIssue({
+    id: 'hoisting-candidate',
+    title: `Hoisting candidate: ${info.dependencyName}`,
+    description: `Dependency "${info.dependencyName}" is used in ${packageCount} packages (${packageNames}) with the same version`,
+    severity: 'info',
+    category: 'dependency',
+    location,
+    suggestion: `Consider hoisting "${info.dependencyName}" to the workspace root package.json to reduce duplication`,
+    metadata: {
+      dependencyName: info.dependencyName,
+      version: info.versions[0],
+      packageCount,
+      packages: info.occurrences.map(o => o.packageName),
+    },
+  })
+}
+
+/**
+ * Checks for redundant dev dependencies (same package in both deps and devDeps).
+ */
+function checkRedundantDevDependencies(pkg: WorkspacePackage): Issue[] {
+  const issues: Issue[] = []
+  const pkgJson = pkg.packageJson
+
+  if (pkgJson.dependencies === undefined || pkgJson.devDependencies === undefined) {
+    return issues
+  }
+
+  for (const [depName, devVersion] of Object.entries(pkgJson.devDependencies)) {
+    if (depName in pkgJson.dependencies) {
+      const prodVersion = pkgJson.dependencies[depName]
+
+      issues.push(
+        createIssue({
+          id: 'redundant-dev-dependency',
+          title: `Redundant dev dependency: ${depName}`,
+          description: `Package "${pkg.name}" has "${depName}" in both dependencies (${prodVersion}) and devDependencies (${devVersion})`,
+          severity: 'info',
+          category: 'dependency',
+          location: {filePath: pkg.packageJsonPath},
+          suggestion: `Remove "${depName}" from devDependencies as it's already in dependencies`,
+          metadata: {
+            packageName: pkg.name,
+            dependencyName: depName,
+            prodVersion,
+            devVersion,
+          },
+        }),
+      )
+    }
+  }
+
+  return issues
+}
+
+/**
+ * Aggregates duplicate dependency statistics.
+ */
+export interface DuplicateDependencyStats {
+  /** Total unique dependencies across workspace */
+  readonly totalUniqueDependencies: number
+  /** Number of dependencies with version conflicts */
+  readonly conflictingDependencies: number
+  /** Number of packages with redundant dev dependencies */
+  readonly packagesWithRedundantDev: number
+  /** Dependencies appearing in most packages */
+  readonly mostCommon: readonly {readonly name: string; readonly count: number}[]
+  /** Dependencies with the most version variants */
+  readonly mostVariants: readonly {readonly name: string; readonly versionCount: number}[]
+}
+
+/**
+ * Computes statistics about dependency duplicates.
+ */
+export function computeDuplicateStats(
+  dependencyMap: ReadonlyMap<string, DependencyInfo>,
+  topN = 10,
+): DuplicateDependencyStats {
+  let conflictingDependencies = 0
+  const commonDeps: {name: string; count: number}[] = []
+  const variantDeps: {name: string; versionCount: number}[] = []
+
+  for (const [name, info] of dependencyMap) {
+    if (info.hasConflict) {
+      conflictingDependencies++
+    }
+
+    commonDeps.push({name, count: info.occurrences.length})
+    variantDeps.push({name, versionCount: info.versions.length})
+  }
+
+  commonDeps.sort((a, b) => b.count - a.count)
+  variantDeps.sort((a, b) => b.versionCount - a.versionCount)
+
+  return {
+    totalUniqueDependencies: dependencyMap.size,
+    conflictingDependencies,
+    packagesWithRedundantDev: 0, // Computed separately per-package
+    mostCommon: commonDeps.slice(0, topN),
+    mostVariants: variantDeps.filter(d => d.versionCount > 1).slice(0, topN),
+  }
+}

package/src/analyzers/eslint-config-analyzer.ts

@@ -0,0 +1,281 @@
+/**
+ * EslintConfigAnalyzer - Validates ESLint configuration for consistency and best practices.
+ *
+ * Detects issues such as:
+ * - Missing ESLint configuration files
+ * - Inconsistent config patterns across packages
+ * - Missing recommended plugins for TypeScript packages
+ */
+
+import type {WorkspacePackage} from '../scanner/workspace-scanner'
+import type {Issue, IssueLocation} from '../types/index'
+import type {Result} from '../types/result'
+import type {AnalysisContext, Analyzer, AnalyzerError, AnalyzerMetadata} from './analyzer'
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import {ok} from '@bfra.me/es/result'
+
+import {createIssue, filterIssues} from './analyzer'
+
+/**
+ * Configuration options specific to EslintConfigAnalyzer.
+ */
+export interface EslintConfigAnalyzerOptions {
+  /** Whether to require ESLint config for all packages */
+  readonly requireConfig?: boolean
+  /** Expected config file pattern (e.g., 'eslint.config.ts') */
+  readonly expectedConfigFile?: string
+  /** Whether to check for flat config usage */
+  readonly requireFlatConfig?: boolean
+  /** Package names exempt from checks */
+  readonly exemptPackages?: readonly string[]
+}
+
+const DEFAULT_OPTIONS: EslintConfigAnalyzerOptions = {
+  requireConfig: true,
+  expectedConfigFile: 'eslint.config.ts',
+  requireFlatConfig: true,
+  exemptPackages: [],
+}
+
+const METADATA: AnalyzerMetadata = {
+  id: 'eslint-config',
+  name: 'ESLint Config Analyzer',
+  description: 'Validates ESLint configuration for consistency and best practices',
+  categories: ['configuration'],
+  defaultSeverity: 'warning',
+}
+
+const ESLINT_CONFIG_FILES = [
+  'eslint.config.ts',
+  'eslint.config.mts',
+  'eslint.config.cts',
+  'eslint.config.js',
+  'eslint.config.mjs',
+  'eslint.config.cjs',
+  '.eslintrc.json',
+  '.eslintrc.js',
+  '.eslintrc.cjs',
+  '.eslintrc.yaml',
+  '.eslintrc.yml',
+  '.eslintrc',
+] as const
+
+/**
+ * Creates an EslintConfigAnalyzer instance.
+ */
+export function createEslintConfigAnalyzer(options: EslintConfigAnalyzerOptions = {}): Analyzer {
+  const resolvedOptions = {...DEFAULT_OPTIONS, ...options}
+
+  return {
+    metadata: METADATA,
+    analyze: async (context: AnalysisContext): Promise<Result<readonly Issue[], AnalyzerError>> => {
+      const issues: Issue[] = []
+
+      for (const pkg of context.packages) {
+        if (isExemptPackage(pkg.name, resolvedOptions.exemptPackages)) {
+          continue
+        }
+
+        const packageIssues = await analyzePackageEslint(pkg, resolvedOptions)
+        issues.push(...packageIssues)
+      }
+
+      return ok(filterIssues(issues, context.config))
+    },
+  }
+}
+
+function isExemptPackage(name: string, exemptPackages: readonly string[] | undefined): boolean {
+  return exemptPackages?.includes(name) ?? false
+}
+
+function createLocation(filePath: string): IssueLocation {
+  return {filePath}
+}
+
+async function analyzePackageEslint(
+  pkg: WorkspacePackage,
+  options: EslintConfigAnalyzerOptions,
+): Promise<Issue[]> {
+  const issues: Issue[] = []
+
+  // Find existing ESLint config
+  const configResult = await findEslintConfig(pkg.packagePath)
+
+  if (!configResult.found) {
+    if (options.requireConfig) {
+      issues.push(
+        createIssue({
+          id: 'eslint-no-config',
+          title: 'Missing ESLint configuration',
+          description: `Package "${pkg.name}" has no ESLint configuration file`,
+          severity: 'warning',
+          category: 'configuration',
+          location: createLocation(path.join(pkg.packagePath, 'package.json')),
+          suggestion: `Create "${options.expectedConfigFile ?? 'eslint.config.ts'}" for code quality enforcement`,
+        }),
+      )
+    }
+    return issues
+  }
+
+  // Check for legacy config files
+  if (options.requireFlatConfig && configResult.isLegacy) {
+    issues.push(
+      createIssue({
+        id: 'eslint-legacy-config',
+        title: 'Using legacy ESLint configuration',
+        description: `Package "${pkg.name}" uses legacy config format "${configResult.fileName}"`,
+        severity: 'info',
+        category: 'configuration',
+        location: createLocation(configResult.filePath),
+        suggestion: 'Migrate to flat config format (eslint.config.ts) for ESLint v9+',
+      }),
+    )
+  }
+
+  // Check if expected config file is used
+  if (
+    options.expectedConfigFile !== undefined &&
+    configResult.fileName !== options.expectedConfigFile &&
+    !configResult.isLegacy
+  ) {
+    issues.push(
+      createIssue({
+        id: 'eslint-unexpected-config-file',
+        title: 'Unexpected ESLint config file name',
+        description: `Package "${pkg.name}" uses "${configResult.fileName}" instead of "${options.expectedConfigFile}"`,
+        severity: 'info',
+        category: 'configuration',
+        location: createLocation(configResult.filePath),
+        suggestion: `Consider renaming to "${options.expectedConfigFile}" for consistency`,
+      }),
+    )
+  }
+
+  // Analyze config content for common issues
+  if (!configResult.isLegacy) {
+    const contentIssues = await analyzeEslintConfigContent(pkg, configResult.filePath)
+    issues.push(...contentIssues)
+  }
+
+  return issues
+}
+
+interface EslintConfigResult {
+  found: boolean
+  fileName: string
+  filePath: string
+  isLegacy: boolean
+}
+
+async function findEslintConfig(packagePath: string): Promise<EslintConfigResult> {
+  for (const configFile of ESLINT_CONFIG_FILES) {
+    const configPath = path.join(packagePath, configFile)
+    if (await fileExists(configPath)) {
+      return {
+        found: true,
+        fileName: configFile,
+        filePath: configPath,
+        isLegacy: isLegacyConfig(configFile),
+      }
+    }
+  }
+
+  return {
+    found: false,
+    fileName: '',
+    filePath: '',
+    isLegacy: false,
+  }
+}
+
+function isLegacyConfig(fileName: string): boolean {
+  return fileName.startsWith('.eslintrc')
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function analyzeEslintConfigContent(
+  pkg: WorkspacePackage,
+  configPath: string,
+): Promise<Issue[]> {
+  const issues: Issue[] = []
+
+  let content: string
+  try {
+    content = await fs.readFile(configPath, 'utf-8')
+  } catch {
+    return issues
+  }
+
+  // Check for defineConfig usage
+  if (!content.includes('defineConfig')) {
+    issues.push(
+      createIssue({
+        id: 'eslint-no-define-config',
+        title: 'ESLint config not using defineConfig',
+        description: `Package "${pkg.name}" ESLint config may not be using defineConfig() helper`,
+        severity: 'info',
+        category: 'configuration',
+        location: createLocation(configPath),
+        suggestion: 'Use defineConfig() from your ESLint config package for better type safety',
+      }),
+    )
+  }
+
+  // Check for TypeScript plugin in TS packages
+  if (pkg.hasTsConfig) {
+    const hasTypescriptPlugin =
+      content.includes('typescript-eslint') ||
+      content.includes('@typescript-eslint') ||
+      content.includes('tseslint')
+
+    if (!hasTypescriptPlugin) {
+      issues.push(
+        createIssue({
+          id: 'eslint-no-typescript-plugin',
+          title: 'ESLint config missing TypeScript support',
+          description: `Package "${pkg.name}" is a TypeScript package but ESLint config may not include TypeScript plugin`,
+          severity: 'warning',
+          category: 'configuration',
+          location: createLocation(configPath),
+          suggestion: 'Add @typescript-eslint/eslint-plugin for TypeScript-specific linting rules',
+        }),
+      )
+    }
+  }
+
+  // Check for Prettier integration
+  const hasPrettierConfig =
+    content.includes('prettier') || content.includes('eslint-config-prettier')
+
+  if (!hasPrettierConfig) {
+    issues.push(
+      createIssue({
+        id: 'eslint-no-prettier',
+        title: 'ESLint config may not include Prettier integration',
+        description: `Package "${pkg.name}" ESLint config may not disable Prettier-conflicting rules`,
+        severity: 'info',
+        category: 'configuration',
+        location: createLocation(configPath),
+        suggestion:
+          'Consider adding eslint-config-prettier to avoid formatting conflicts with Prettier',
+      }),
+    )
+  }
+
+  return issues
+}
+
+export {METADATA as eslintConfigAnalyzerMetadata}