@bfra.me/workspace-analyzer 0.1.0

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

@@ -0,0 +1,356 @@
+/**
+ * UnusedDependencyAnalyzer - Detects unused dependencies in workspace packages.
+ *
+ * Compares declared dependencies in package.json against actual imports
+ * found in source files to identify unused packages that can be removed.
+ *
+ * Handles:
+ * - Static imports (import { x } from 'pkg')
+ * - Dynamic imports (await import('pkg'))
+ * - require() calls (const x = require('pkg'))
+ * - Type-only imports (import type { T } from 'pkg')
+ * - Dev vs production dependency classification
+ */
+
+import type {ImportExtractionResult, ImportExtractorOptions} from '../parser/import-extractor'
+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 {createProject} from '@bfra.me/doc-sync/parsers'
+import {ok} from '@bfra.me/es/result'
+
+import {extractImports, getPackageNameFromSpecifier} from '../parser/import-extractor'
+import {createIssue, filterIssues} from './analyzer'
+
+/**
+ * Configuration options specific to UnusedDependencyAnalyzer.
+ */
+export interface UnusedDependencyAnalyzerOptions {
+  /** Include devDependencies in analysis */
+  readonly checkDevDependencies?: boolean
+  /** Include peerDependencies in analysis */
+  readonly checkPeerDependencies?: boolean
+  /** Include optionalDependencies in analysis */
+  readonly checkOptionalDependencies?: boolean
+  /** Package names to ignore (regex patterns) */
+  readonly ignorePatterns?: readonly string[]
+  /** Packages known to be used implicitly (e.g., type packages, build tools) */
+  readonly implicitlyUsed?: readonly string[]
+  /** Workspace package prefixes for identifying workspace dependencies */
+  readonly workspacePrefixes?: readonly string[]
+}
+
+const DEFAULT_OPTIONS: Required<UnusedDependencyAnalyzerOptions> = {
+  checkDevDependencies: true,
+  checkPeerDependencies: false,
+  checkOptionalDependencies: false,
+  ignorePatterns: [],
+  implicitlyUsed: [
+    // Common packages that are used implicitly or at build time
+    'typescript',
+    '@types/*',
+    'eslint',
+    'prettier',
+    'vitest',
+    '@vitest/*',
+    'tsup',
+    'vite',
+    '@vitejs/*',
+  ],
+  workspacePrefixes: ['@bfra.me/'],
+}
+
+export const unusedDependencyAnalyzerMetadata: AnalyzerMetadata = {
+  id: 'unused-dependency',
+  name: 'Unused Dependency Analyzer',
+  description: 'Detects dependencies declared in package.json that are not imported in source code',
+  categories: ['dependency'],
+  defaultSeverity: 'warning',
+}
+
+/**
+ * Creates an UnusedDependencyAnalyzer instance.
+ *
+ * @example
+ * ```ts
+ * const analyzer = createUnusedDependencyAnalyzer({
+ *   checkDevDependencies: true,
+ *   ignorePatterns: ['@types/*'],
+ * })
+ * const result = await analyzer.analyze(context)
+ * ```
+ */
+export function createUnusedDependencyAnalyzer(
+  options: UnusedDependencyAnalyzerOptions = {},
+): Analyzer {
+  const resolvedOptions = {...DEFAULT_OPTIONS, ...options}
+
+  return {
+    metadata: unusedDependencyAnalyzerMetadata,
+    analyze: async (context: AnalysisContext): Promise<Result<readonly Issue[], AnalyzerError>> => {
+      const issues: Issue[] = []
+
+      for (const pkg of context.packages) {
+        context.reportProgress?.(`Analyzing dependencies for ${pkg.name}...`)
+
+        const packageIssues = await analyzePackageDependencies(pkg, resolvedOptions)
+        issues.push(...packageIssues)
+      }
+
+      return ok(filterIssues(issues, context.config))
+    },
+  }
+}
+
+/**
+ * Dependency classification for proper issue severity and messaging.
+ */
+type DependencyType =
+  | 'dependencies'
+  | 'devDependencies'
+  | 'peerDependencies'
+  | 'optionalDependencies'
+
+interface DeclaredDependency {
+  readonly name: string
+  readonly version: string
+  readonly type: DependencyType
+}
+
+/**
+ * Analyzes a single package for unused dependencies.
+ */
+async function analyzePackageDependencies(
+  pkg: WorkspacePackage,
+  options: Required<UnusedDependencyAnalyzerOptions>,
+): Promise<Issue[]> {
+  const issues: Issue[] = []
+
+  const declaredDeps = collectDeclaredDependencies(pkg, options)
+  if (declaredDeps.length === 0) {
+    return issues
+  }
+
+  const usedPackages = await collectUsedPackages(pkg, options)
+
+  for (const dep of declaredDeps) {
+    if (isIgnored(dep.name, options)) {
+      continue
+    }
+
+    if (isImplicitlyUsed(dep.name, options.implicitlyUsed)) {
+      continue
+    }
+
+    if (!usedPackages.has(dep.name)) {
+      issues.push(createUnusedDependencyIssue(pkg, dep))
+    }
+  }
+
+  return issues
+}
+
+/**
+ * Collects all declared dependencies from package.json based on configuration.
+ */
+function collectDeclaredDependencies(
+  pkg: WorkspacePackage,
+  options: Required<UnusedDependencyAnalyzerOptions>,
+): DeclaredDependency[] {
+  const deps: DeclaredDependency[] = []
+  const pkgJson = pkg.packageJson
+
+  // Always check production dependencies
+  if (pkgJson.dependencies !== undefined) {
+    for (const [name, version] of Object.entries(pkgJson.dependencies)) {
+      deps.push({name, version, type: 'dependencies'})
+    }
+  }
+
+  if (options.checkDevDependencies && pkgJson.devDependencies !== undefined) {
+    for (const [name, version] of Object.entries(pkgJson.devDependencies)) {
+      deps.push({name, version, type: 'devDependencies'})
+    }
+  }
+
+  if (options.checkPeerDependencies && pkgJson.peerDependencies !== undefined) {
+    for (const [name, version] of Object.entries(pkgJson.peerDependencies)) {
+      deps.push({name, version, type: 'peerDependencies'})
+    }
+  }
+
+  if (options.checkOptionalDependencies && pkgJson.optionalDependencies !== undefined) {
+    for (const [name, version] of Object.entries(pkgJson.optionalDependencies)) {
+      deps.push({name, version, type: 'optionalDependencies'})
+    }
+  }
+
+  return deps
+}
+
+/**
+ * Collects all packages actually used in source files.
+ */
+async function collectUsedPackages(
+  pkg: WorkspacePackage,
+  options: Required<UnusedDependencyAnalyzerOptions>,
+): Promise<Set<string>> {
+  const usedPackages = new Set<string>()
+
+  if (pkg.sourceFiles.length === 0) {
+    return usedPackages
+  }
+
+  const project = createProject()
+
+  const extractorOptions: ImportExtractorOptions = {
+    workspacePrefixes: options.workspacePrefixes,
+    includeTypeImports: true,
+    includeDynamicImports: true,
+    includeRequireCalls: true,
+  }
+
+  for (const filePath of pkg.sourceFiles) {
+    try {
+      const sourceFile = project.addSourceFileAtPath(filePath)
+      const result = extractImports(sourceFile, extractorOptions)
+
+      for (const imp of result.imports) {
+        const packageName = getPackageNameFromSpecifier(imp.moduleSpecifier)
+        if (!isRelativeSpecifier(imp.moduleSpecifier)) {
+          usedPackages.add(packageName)
+        }
+      }
+    } catch {
+      // Skip files that can't be parsed (may be invalid syntax or not TypeScript)
+    }
+  }
+
+  return usedPackages
+}
+
+/**
+ * Checks if a module specifier is a relative import.
+ */
+function isRelativeSpecifier(specifier: string): boolean {
+  return specifier.startsWith('.') || specifier.startsWith('/')
+}
+
+/**
+ * Checks if a dependency should be ignored based on patterns.
+ */
+function isIgnored(depName: string, options: Required<UnusedDependencyAnalyzerOptions>): boolean {
+  return options.ignorePatterns.some(pattern => {
+    if (pattern.includes('*')) {
+      const regex = new RegExp(`^${pattern.replaceAll('*', '.*')}$`)
+      return regex.test(depName)
+    }
+    return depName === pattern
+  })
+}
+
+/**
+ * Checks if a dependency is implicitly used (build tools, type definitions, etc.).
+ */
+function isImplicitlyUsed(depName: string, implicitlyUsed: readonly string[]): boolean {
+  return implicitlyUsed.some(pattern => {
+    if (pattern.includes('*')) {
+      const regex = new RegExp(`^${pattern.replaceAll('*', '.*')}$`)
+      return regex.test(depName)
+    }
+    return depName === pattern
+  })
+}
+
+/**
+ * Creates an issue for an unused dependency.
+ */
+function createUnusedDependencyIssue(pkg: WorkspacePackage, dep: DeclaredDependency): Issue {
+  const location: IssueLocation = {
+    filePath: pkg.packageJsonPath,
+  }
+
+  const severityMap: Record<DependencyType, 'warning' | 'info'> = {
+    dependencies: 'warning',
+    devDependencies: 'info',
+    peerDependencies: 'info',
+    optionalDependencies: 'info',
+  }
+
+  const typeDescription = getDependencyTypeDescription(dep.type)
+
+  return createIssue({
+    id: 'unused-dependency',
+    title: `Unused ${typeDescription}: ${dep.name}`,
+    description: `Package "${pkg.name}" declares "${dep.name}" in ${dep.type} but it is not imported in any source file`,
+    severity: severityMap[dep.type],
+    category: 'dependency',
+    location,
+    suggestion: `Remove "${dep.name}" from ${dep.type} in package.json, or verify it is used at runtime/build time`,
+    metadata: {
+      packageName: pkg.name,
+      dependencyName: dep.name,
+      dependencyVersion: dep.version,
+      dependencyType: dep.type,
+    },
+  })
+}
+
+/**
+ * Gets a human-readable description for a dependency type.
+ */
+function getDependencyTypeDescription(type: DependencyType): string {
+  switch (type) {
+    case 'dependencies':
+      return 'dependency'
+    case 'devDependencies':
+      return 'dev dependency'
+    case 'peerDependencies':
+      return 'peer dependency'
+    case 'optionalDependencies':
+      return 'optional dependency'
+  }
+}
+
+/**
+ * Aggregates import information from multiple packages for workspace-wide analysis.
+ */
+export function aggregatePackageImports(
+  packages: readonly WorkspacePackage[],
+  importResults: ReadonlyMap<string, readonly ImportExtractionResult[]>,
+): {
+  readonly externalByPackage: ReadonlyMap<string, Set<string>>
+  readonly workspaceByPackage: ReadonlyMap<string, Set<string>>
+} {
+  const externalByPackage = new Map<string, Set<string>>()
+  const workspaceByPackage = new Map<string, Set<string>>()
+
+  for (const pkg of packages) {
+    const results = importResults.get(pkg.name)
+    if (results === undefined) {
+      continue
+    }
+
+    const external = new Set<string>()
+    const workspace = new Set<string>()
+
+    for (const result of results) {
+      for (const dep of result.externalDependencies) {
+        external.add(dep)
+      }
+      for (const dep of result.workspaceDependencies) {
+        workspace.add(dep)
+      }
+    }
+
+    externalByPackage.set(pkg.name, external)
+    workspaceByPackage.set(pkg.name, workspace)
+  }
+
+  return {
+    externalByPackage,
+    workspaceByPackage,
+  }
+}

package/src/analyzers/version-alignment-analyzer.ts

@@ -0,0 +1,308 @@
+/**
+ * VersionAlignmentAnalyzer - Checks for consistent dependency versions across workspace.
+ *
+ * Detects issues such as:
+ * - Different versions of the same dependency across packages
+ * - Workspace packages with mismatched versions
+ * - Invalid workspace: protocol references
+ */
+
+import type {ParsedPackageJson} from '../parser/config-parser'
+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 {ok} from '@bfra.me/es/result'
+
+import {createIssue, filterIssues} from './analyzer'
+
+/**
+ * Configuration options specific to VersionAlignmentAnalyzer.
+ */
+export interface VersionAlignmentAnalyzerOptions {
+  /** Whether to check for misaligned external dependency versions */
+  readonly checkExternalVersions?: boolean
+  /** Whether to check workspace protocol references */
+  readonly checkWorkspaceProtocol?: boolean
+  /** Dependencies to ignore in version alignment checks */
+  readonly ignoreDependencies?: readonly string[]
+  /** Package names exempt from checks */
+  readonly exemptPackages?: readonly string[]
+}
+
+const DEFAULT_OPTIONS: VersionAlignmentAnalyzerOptions = {
+  checkExternalVersions: true,
+  checkWorkspaceProtocol: true,
+  ignoreDependencies: [],
+  exemptPackages: [],
+}
+
+const METADATA: AnalyzerMetadata = {
+  id: 'version-alignment',
+  name: 'Version Alignment Analyzer',
+  description: 'Checks for consistent dependency versions across workspace packages',
+  categories: ['dependency'],
+  defaultSeverity: 'warning',
+}
+
+/**
+ * Information about a dependency version usage.
+ */
+interface VersionUsage {
+  readonly packageName: string
+  readonly version: string
+  readonly type: 'prod' | 'dev' | 'peer' | 'optional'
+  readonly packageJsonPath: string
+}
+
+/**
+ * Creates a VersionAlignmentAnalyzer instance.
+ */
+export function createVersionAlignmentAnalyzer(
+  options: VersionAlignmentAnalyzerOptions = {},
+): Analyzer {
+  const resolvedOptions = {...DEFAULT_OPTIONS, ...options}
+
+  return {
+    metadata: METADATA,
+    analyze: async (context: AnalysisContext): Promise<Result<readonly Issue[], AnalyzerError>> => {
+      const issues: Issue[] = []
+
+      // Build a map of all dependency versions across workspace
+      const dependencyMap = buildDependencyMap(context.packages, resolvedOptions)
+
+      // Check for version misalignment
+      if (resolvedOptions.checkExternalVersions) {
+        const alignmentIssues = checkVersionAlignment(dependencyMap, resolvedOptions)
+        issues.push(...alignmentIssues)
+      }
+
+      // Check workspace protocol usage
+      if (resolvedOptions.checkWorkspaceProtocol) {
+        const workspaceIssues = checkWorkspaceProtocol(context.packages, resolvedOptions)
+        issues.push(...workspaceIssues)
+      }
+
+      return ok(filterIssues(issues, context.config))
+    },
+  }
+}
+
+function createLocation(filePath: string): IssueLocation {
+  return {filePath}
+}
+
+/**
+ * Builds a map of all dependencies and their versions across the workspace.
+ */
+function buildDependencyMap(
+  packages: readonly WorkspacePackage[],
+  options: VersionAlignmentAnalyzerOptions,
+): Map<string, VersionUsage[]> {
+  const dependencyMap = new Map<string, VersionUsage[]>()
+  const ignoredDeps = new Set(options.ignoreDependencies ?? [])
+  const exemptPackages = new Set(options.exemptPackages ?? [])
+
+  for (const pkg of packages) {
+    if (exemptPackages.has(pkg.name)) {
+      continue
+    }
+
+    const pkgJson = pkg.packageJson as ParsedPackageJson
+
+    // Process each dependency type
+    const depTypes = [
+      {deps: pkgJson.dependencies, type: 'prod' as const},
+      {deps: pkgJson.devDependencies, type: 'dev' as const},
+      {deps: pkgJson.peerDependencies, type: 'peer' as const},
+      {deps: pkgJson.optionalDependencies, type: 'optional' as const},
+    ]
+
+    for (const {deps, type} of depTypes) {
+      if (deps === undefined) {
+        continue
+      }
+
+      for (const [depName, version] of Object.entries(deps)) {
+        // Skip workspace protocol and ignored dependencies
+        if (version.startsWith('workspace:') || ignoredDeps.has(depName)) {
+          continue
+        }
+
+        const usages = dependencyMap.get(depName) ?? []
+        usages.push({
+          packageName: pkg.name,
+          version,
+          type,
+          packageJsonPath: pkg.packageJsonPath,
+        })
+        dependencyMap.set(depName, usages)
+      }
+    }
+  }
+
+  return dependencyMap
+}
+
+/**
+ * Checks for version alignment issues in the dependency map.
+ */
+function checkVersionAlignment(
+  dependencyMap: Map<string, VersionUsage[]>,
+  _options: VersionAlignmentAnalyzerOptions,
+): Issue[] {
+  const issues: Issue[] = []
+
+  for (const [depName, usages] of dependencyMap) {
+    if (usages.length <= 1) {
+      continue
+    }
+
+    // Group by normalized version
+    const versionGroups = groupByVersion(usages)
+
+    if (versionGroups.size <= 1) {
+      continue
+    }
+
+    // Different versions detected
+    const versionList = Array.from(versionGroups.entries())
+      .map(([version, pkgs]) => `"${version}" in ${pkgs.join(', ')}`)
+      .join('; ')
+
+    // Find the most common version
+    let mostCommonVersion = ''
+    let maxCount = 0
+    for (const [version, pkgs] of versionGroups) {
+      if (pkgs.length > maxCount) {
+        maxCount = pkgs.length
+        mostCommonVersion = version
+      }
+    }
+
+    // Report issues for non-common versions
+    for (const [version, pkgs] of versionGroups) {
+      if (version === mostCommonVersion) {
+        continue
+      }
+
+      for (const packageName of pkgs) {
+        const usage = usages.find(u => u.packageName === packageName && u.version === version)
+        if (usage === undefined) {
+          continue
+        }
+
+        issues.push(
+          createIssue({
+            id: 'version-mismatch',
+            title: 'Dependency version mismatch',
+            description: `Dependency "${depName}" has inconsistent versions across workspace: ${versionList}`,
+            severity: 'warning',
+            category: 'dependency',
+            location: createLocation(usage.packageJsonPath),
+            suggestion: `Consider aligning to version "${mostCommonVersion}" used by ${maxCount} package(s)`,
+            metadata: {
+              dependency: depName,
+              currentVersion: version,
+              suggestedVersion: mostCommonVersion,
+              allVersions: Object.fromEntries(versionGroups),
+            },
+          }),
+        )
+      }
+    }
+  }
+
+  return issues
+}
+
+/**
+ * Groups usages by their normalized version.
+ */
+function groupByVersion(usages: VersionUsage[]): Map<string, string[]> {
+  const groups = new Map<string, string[]>()
+
+  for (const usage of usages) {
+    // Normalize version for comparison (remove leading ^ or ~)
+    const normalizedVersion = usage.version
+
+    const packages = groups.get(normalizedVersion) ?? []
+    packages.push(usage.packageName)
+    groups.set(normalizedVersion, packages)
+  }
+
+  return groups
+}
+
+/**
+ * Checks workspace protocol usage for issues.
+ */
+function checkWorkspaceProtocol(
+  packages: readonly WorkspacePackage[],
+  options: VersionAlignmentAnalyzerOptions,
+): Issue[] {
+  const issues: Issue[] = []
+  const packageNames = new Set(packages.map(p => p.name))
+  const exemptPackages = new Set(options.exemptPackages ?? [])
+
+  for (const pkg of packages) {
+    if (exemptPackages.has(pkg.name)) {
+      continue
+    }
+
+    const pkgJson = pkg.packageJson as ParsedPackageJson
+
+    // Check all dependency types
+    const depTypes = [
+      {deps: pkgJson.dependencies, type: 'dependencies'},
+      {deps: pkgJson.devDependencies, type: 'devDependencies'},
+      {deps: pkgJson.peerDependencies, type: 'peerDependencies'},
+    ]
+
+    for (const {deps, type} of depTypes) {
+      if (deps === undefined) {
+        continue
+      }
+
+      for (const [depName, version] of Object.entries(deps)) {
+        // Check for workspace: protocol pointing to non-existent package
+        if (version.startsWith('workspace:') && !packageNames.has(depName)) {
+          issues.push(
+            createIssue({
+              id: 'workspace-invalid-ref',
+              title: 'Invalid workspace protocol reference',
+              description: `Package "${pkg.name}" references "${depName}" with workspace: protocol, but package does not exist in workspace`,
+              severity: 'error',
+              category: 'dependency',
+              location: createLocation(pkg.packageJsonPath),
+              suggestion: `Either add "${depName}" to the workspace or use a valid npm version`,
+              metadata: {dependency: depName, version, dependencyType: type},
+            }),
+          )
+        }
+
+        // Check for workspace package without workspace: protocol
+        if (!version.startsWith('workspace:') && packageNames.has(depName)) {
+          // Not necessarily an error - might be using published version
+          issues.push(
+            createIssue({
+              id: 'workspace-missing-protocol',
+              title: 'Workspace package without workspace: protocol',
+              description: `Package "${pkg.name}" depends on workspace package "${depName}" but uses version "${version}" instead of workspace: protocol`,
+              severity: 'info',
+              category: 'dependency',
+              location: createLocation(pkg.packageJsonPath),
+              suggestion: `Consider using "workspace:*" to link to the local package`,
+              metadata: {dependency: depName, version, dependencyType: type},
+            }),
+          )
+        }
+      }
+    }
+  }
+
+  return issues
+}
+
+export {METADATA as versionAlignmentAnalyzerMetadata}