@bfra.me/workspace-analyzer 0.1.0

package/src/scanner/workspace-scanner.ts

@@ -0,0 +1,403 @@
+/**
+ * Workspace scanner for discovering and analyzing packages in a monorepo.
+ *
+ * Adapts the createPackageScanner() pattern from @bfra.me/doc-sync for workspace analysis.
+ * Uses fs.readdir pattern (not fast-glob) for better control over directory traversal.
+ */
+
+import type {Result} from '../types/result'
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import {err, ok} from '@bfra.me/es/result'
+
+/**
+ * Options for configuring the workspace scanner.
+ */
+export interface WorkspaceScannerOptions {
+  /** Root directory of the workspace/monorepo */
+  readonly rootDir: string
+  /** Glob patterns for package locations (e.g., ['packages/*', 'apps/*']) */
+  readonly includePatterns?: readonly string[]
+  /** Package names to exclude from scanning */
+  readonly excludePackages?: readonly string[]
+  /** File extensions to include in source file collection */
+  readonly sourceExtensions?: readonly string[]
+  /** Directories to skip during source file collection */
+  readonly excludeDirs?: readonly string[]
+}
+
+/**
+ * Minimal package.json structure for workspace analysis.
+ */
+export interface WorkspacePackageJson {
+  readonly name: string
+  readonly version: string
+  readonly description?: string
+  readonly main?: string
+  readonly module?: string
+  readonly types?: string
+  readonly exports?: Record<string, unknown>
+  readonly dependencies?: Readonly<Record<string, string>>
+  readonly devDependencies?: Readonly<Record<string, string>>
+  readonly peerDependencies?: Readonly<Record<string, string>>
+  readonly optionalDependencies?: Readonly<Record<string, string>>
+}
+
+/**
+ * Information about a discovered workspace package.
+ */
+export interface WorkspacePackage {
+  /** Package name from package.json */
+  readonly name: string
+  /** Package version from package.json */
+  readonly version: string
+  /** Absolute path to the package directory */
+  readonly packagePath: string
+  /** Absolute path to package.json */
+  readonly packageJsonPath: string
+  /** Absolute path to source directory (if exists) */
+  readonly srcPath: string
+  /** Parsed package.json content */
+  readonly packageJson: WorkspacePackageJson
+  /** List of source file paths in the package */
+  readonly sourceFiles: readonly string[]
+  /** Whether the package has a tsconfig.json */
+  readonly hasTsConfig: boolean
+  /** Whether the package has an eslint config */
+  readonly hasEslintConfig: boolean
+}
+
+/**
+ * Error that occurred during workspace scanning.
+ */
+export interface ScanError {
+  /** Error code for programmatic handling */
+  readonly code: 'INVALID_PATH' | 'NO_PACKAGE_JSON' | 'INVALID_PACKAGE_JSON' | 'READ_ERROR'
+  /** Human-readable error message */
+  readonly message: string
+  /** Path where the error occurred */
+  readonly path: string
+  /** Underlying error cause */
+  readonly cause?: unknown
+}
+
+/**
+ * Result of a workspace scan operation.
+ */
+export interface WorkspaceScanResult {
+  /** All discovered packages */
+  readonly packages: readonly WorkspacePackage[]
+  /** Root workspace path */
+  readonly workspacePath: string
+  /** Errors encountered during scanning */
+  readonly errors: readonly ScanError[]
+  /** Duration of scan in milliseconds */
+  readonly durationMs: number
+}
+
+const DEFAULT_OPTIONS = {
+  includePatterns: ['packages/*'],
+  excludePackages: [],
+  sourceExtensions: ['.ts', '.tsx', '.js', '.jsx', '.mts', '.cts', '.mjs', '.cjs'],
+  excludeDirs: ['node_modules', '__tests__', '__mocks__', 'test', 'tests', 'dist', 'lib', 'build'],
+} as const
+
+/**
+ * Check if a file exists at the given path.
+ */
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Creates a workspace scanner for discovering and analyzing packages.
+ *
+ * @example
+ * ```ts
+ * const scanner = createWorkspaceScanner({rootDir: '/path/to/monorepo'})
+ * const result = await scanner.scan()
+ *
+ * for (const pkg of result.packages) {
+ *   console.log(`Found package: ${pkg.name}`)
+ * }
+ * ```
+ */
+export function createWorkspaceScanner(options: WorkspaceScannerOptions): {
+  /** Scan the entire workspace for packages */
+  readonly scan: () => Promise<WorkspaceScanResult>
+  /** Scan a single package directory */
+  readonly scanPackage: (packagePath: string) => Promise<Result<WorkspacePackage, ScanError>>
+  /** Collect source files from a directory */
+  readonly collectSourceFiles: (dir: string) => Promise<readonly string[]>
+} {
+  const {
+    rootDir,
+    includePatterns = DEFAULT_OPTIONS.includePatterns,
+    excludePackages = DEFAULT_OPTIONS.excludePackages,
+    sourceExtensions = DEFAULT_OPTIONS.sourceExtensions,
+    excludeDirs = DEFAULT_OPTIONS.excludeDirs,
+  } = options
+
+  const extensionSet = new Set(sourceExtensions)
+  const excludeDirSet = new Set(excludeDirs)
+
+  /**
+   * Discover package directories based on include patterns.
+   * Uses fs.readdir pattern for consistent behavior with doc-sync.
+   */
+  async function discoverPackages(): Promise<string[]> {
+    const packagePaths: string[] = []
+
+    for (const pattern of includePatterns) {
+      const baseDir = path.join(rootDir, pattern.replace('/*', ''))
+
+      try {
+        const entries = await fs.readdir(baseDir, {withFileTypes: true})
+
+        for (const entry of entries) {
+          if (!entry.isDirectory()) {
+            continue
+          }
+
+          const packagePath = path.join(baseDir, entry.name)
+          const packageJsonPath = path.join(packagePath, 'package.json')
+
+          try {
+            await fs.access(packageJsonPath)
+            packagePaths.push(packagePath)
+          } catch {
+            // Directory doesn't contain package.json, skip
+          }
+        }
+      } catch {
+        // Pattern directory doesn't exist, skip
+      }
+    }
+
+    return packagePaths
+  }
+
+  /**
+   * Recursively collect source files from a directory.
+   */
+  async function collectSourceFiles(dir: string): Promise<readonly string[]> {
+    const files: string[] = []
+
+    try {
+      await collectSourceFilesRecursive(dir, files)
+    } catch {
+      // Source directory doesn't exist or is not accessible
+    }
+
+    return files
+  }
+
+  async function collectSourceFilesRecursive(dir: string, files: string[]): Promise<void> {
+    const entries = await fs.readdir(dir, {withFileTypes: true})
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name)
+
+      if (entry.isDirectory()) {
+        if (excludeDirSet.has(entry.name)) {
+          continue
+        }
+        await collectSourceFilesRecursive(fullPath, files)
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name).toLowerCase()
+        const isSourceFile = extensionSet.has(ext)
+        const isTestFile = entry.name.includes('.test.') || entry.name.includes('.spec.')
+
+        if (isSourceFile && !isTestFile) {
+          files.push(fullPath)
+        }
+      }
+    }
+  }
+
+  /**
+   * Scan a single package directory.
+   */
+  async function scanPackage(packagePath: string): Promise<Result<WorkspacePackage, ScanError>> {
+    const packageJsonPath = path.join(packagePath, 'package.json')
+
+    let content: string
+    try {
+      content = await fs.readFile(packageJsonPath, 'utf-8')
+    } catch (error) {
+      return err({
+        code: 'READ_ERROR',
+        message: `Failed to read package.json: ${packageJsonPath}`,
+        path: packageJsonPath,
+        cause: error,
+      })
+    }
+
+    let packageJson: unknown
+    try {
+      packageJson = JSON.parse(content)
+    } catch (error) {
+      return err({
+        code: 'INVALID_PACKAGE_JSON',
+        message: `Invalid JSON in package.json: ${packageJsonPath}`,
+        path: packageJsonPath,
+        cause: error,
+      })
+    }
+
+    if (!isValidPackageJson(packageJson)) {
+      return err({
+        code: 'INVALID_PACKAGE_JSON',
+        message: 'package.json is missing required fields (name, version)',
+        path: packageJsonPath,
+      })
+    }
+
+    const srcPath = path.join(packagePath, 'src')
+    const sourceFiles = await collectSourceFiles(srcPath)
+
+    const [hasTsConfig, hasEslintTs, hasEslintJs] = await Promise.all([
+      fileExists(path.join(packagePath, 'tsconfig.json')),
+      fileExists(path.join(packagePath, 'eslint.config.ts')),
+      fileExists(path.join(packagePath, 'eslint.config.js')),
+    ])
+
+    return ok({
+      name: packageJson.name,
+      version: packageJson.version,
+      packagePath,
+      packageJsonPath,
+      srcPath,
+      packageJson,
+      sourceFiles,
+      hasTsConfig,
+      hasEslintConfig: hasEslintTs === true || hasEslintJs === true,
+    })
+  }
+
+  /**
+   * Scan the entire workspace for packages.
+   */
+  async function scan(): Promise<WorkspaceScanResult> {
+    const startTime = Date.now()
+    const packagePaths = await discoverPackages()
+    const packages: WorkspacePackage[] = []
+    const errors: ScanError[] = []
+
+    for (const packagePath of packagePaths) {
+      const result = await scanPackage(packagePath)
+
+      if (result.success) {
+        const scanned = result.data
+
+        if (excludePackages.includes(scanned.name)) {
+          continue
+        }
+
+        packages.push(scanned)
+      } else {
+        errors.push(result.error)
+      }
+    }
+
+    return {
+      packages,
+      workspacePath: rootDir,
+      errors,
+      durationMs: Date.now() - startTime,
+    }
+  }
+
+  return {
+    scan,
+    scanPackage,
+    collectSourceFiles,
+  }
+}
+
+/**
+ * Type guard for validating package.json structure.
+ */
+function isValidPackageJson(value: unknown): value is WorkspacePackageJson {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  if (typeof obj.name !== 'string' || obj.name.length === 0) {
+    return false
+  }
+
+  if (typeof obj.version !== 'string' || obj.version.length === 0) {
+    return false
+  }
+
+  return true
+}
+
+/**
+ * Filter packages by name pattern.
+ */
+export function filterPackagesByPattern(
+  packages: readonly WorkspacePackage[],
+  pattern: string,
+): WorkspacePackage[] {
+  const regex = new RegExp(pattern.replaceAll('*', '.*'), 'i')
+  return packages.filter(pkg => regex.test(pkg.name))
+}
+
+/**
+ * Group packages by their npm scope.
+ */
+export function groupPackagesByScope(
+  packages: readonly WorkspacePackage[],
+): Map<string, WorkspacePackage[]> {
+  const grouped = new Map<string, WorkspacePackage[]>()
+
+  for (const pkg of packages) {
+    const scope = getPackageScope(pkg.name) ?? '__unscoped__'
+    const existing = grouped.get(scope)
+
+    if (existing === undefined) {
+      grouped.set(scope, [pkg])
+    } else {
+      existing.push(pkg)
+    }
+  }
+
+  return grouped
+}
+
+/**
+ * Extract the scope from a scoped package name.
+ */
+export function getPackageScope(packageName: string): string | undefined {
+  if (packageName.startsWith('@')) {
+    const slashIndex = packageName.indexOf('/')
+    if (slashIndex > 0) {
+      return packageName.slice(0, slashIndex)
+    }
+  }
+  return undefined
+}
+
+/**
+ * Get the unscoped name from a package name.
+ */
+export function getUnscopedName(packageName: string): string {
+  if (packageName.startsWith('@')) {
+    const slashIndex = packageName.indexOf('/')
+    if (slashIndex > 0) {
+      return packageName.slice(slashIndex + 1)
+    }
+  }
+  return packageName
+}

package/src/types/index.ts

@@ -0,0 +1,176 @@
+/**
+ * Core type definitions for workspace analysis.
+ *
+ * These types define the structure of analysis results, issues, severity levels,
+ * and configuration options used throughout the analyzer.
+ */
+
+import type {Result} from './result'
+
+/**
+ * Severity levels for analysis issues, from informational to critical errors.
+ */
+export type Severity = 'info' | 'warning' | 'error' | 'critical'
+
+/**
+ * Categories of analysis issues for grouping and filtering.
+ */
+export type IssueCategory =
+  | 'configuration'
+  | 'dependency'
+  | 'architecture'
+  | 'performance'
+  | 'circular-import'
+  | 'unused-export'
+  | 'type-safety'
+
+/**
+ * Location information for precise issue reporting.
+ */
+export interface IssueLocation {
+  /** Absolute file path where the issue was detected */
+  readonly filePath: string
+  /** Starting line number (1-indexed) */
+  readonly line?: number
+  /** Starting column number (1-indexed) */
+  readonly column?: number
+  /** Ending line number (1-indexed) */
+  readonly endLine?: number
+  /** Ending column number (1-indexed) */
+  readonly endColumn?: number
+}
+
+/**
+ * Represents a single issue detected during analysis.
+ */
+export interface Issue {
+  /** Unique identifier for the issue type (e.g., 'circular-import', 'unused-dep') */
+  readonly id: string
+  /** Human-readable title summarizing the issue */
+  readonly title: string
+  /** Detailed description explaining the problem and potential impact */
+  readonly description: string
+  /** Severity level determining how critical this issue is */
+  readonly severity: Severity
+  /** Category for grouping related issues */
+  readonly category: IssueCategory
+  /** Location where the issue was detected */
+  readonly location: IssueLocation
+  /** Additional locations related to this issue (e.g., cycle participants) */
+  readonly relatedLocations?: readonly IssueLocation[]
+  /** Suggested fix or action to resolve the issue */
+  readonly suggestion?: string
+  /** Additional metadata for machine processing */
+  readonly metadata?: Readonly<Record<string, unknown>>
+}
+
+/**
+ * Summary statistics for an analysis run.
+ */
+export interface AnalysisSummary {
+  /** Total number of issues found */
+  readonly totalIssues: number
+  /** Issues grouped by severity */
+  readonly bySeverity: Readonly<Record<Severity, number>>
+  /** Issues grouped by category */
+  readonly byCategory: Readonly<Record<IssueCategory, number>>
+  /** Number of packages analyzed */
+  readonly packagesAnalyzed: number
+  /** Number of source files analyzed */
+  readonly filesAnalyzed: number
+  /** Analysis duration in milliseconds */
+  readonly durationMs: number
+}
+
+/**
+ * Complete result of a workspace analysis run.
+ */
+export interface AnalysisResult {
+  /** All issues detected during analysis */
+  readonly issues: readonly Issue[]
+  /** Summary statistics */
+  readonly summary: AnalysisSummary
+  /** Workspace root path that was analyzed */
+  readonly workspacePath: string
+  /** Timestamp when analysis started */
+  readonly startedAt: Date
+  /** Timestamp when analysis completed */
+  readonly completedAt: Date
+}
+
+/**
+ * Configuration for controlling analyzer behavior.
+ */
+export interface AnalyzerConfig {
+  /** Glob patterns for files to include in analysis */
+  readonly include?: readonly string[]
+  /** Glob patterns for files to exclude from analysis */
+  readonly exclude?: readonly string[]
+  /** Minimum severity level to report */
+  readonly minSeverity?: Severity
+  /** Categories of issues to check */
+  readonly categories?: readonly IssueCategory[]
+  /** Whether to enable caching for incremental analysis */
+  readonly cache?: boolean
+  /** Custom rules configuration */
+  readonly rules?: Readonly<Record<string, unknown>>
+}
+
+/**
+ * Options for the analyzeWorkspace function.
+ */
+export interface AnalyzeWorkspaceOptions extends AnalyzerConfig {
+  /** Path to workspace-analyzer.config.ts file */
+  readonly configPath?: string
+  /** Callback for progress reporting */
+  readonly onProgress?: (progress: AnalysisProgress) => void
+}
+
+/**
+ * Progress information during analysis.
+ */
+export interface AnalysisProgress {
+  /** Current phase of analysis */
+  readonly phase: 'scanning' | 'parsing' | 'analyzing' | 'reporting'
+  /** Current item being processed */
+  readonly current?: string
+  /** Number of items processed so far */
+  readonly processed: number
+  /** Total number of items to process (if known) */
+  readonly total?: number
+}
+
+/**
+ * Represents an error that occurred during analysis.
+ */
+export interface AnalysisError {
+  /** Error code for programmatic handling */
+  readonly code: string
+  /** Human-readable error message */
+  readonly message: string
+  /** Stack trace if available */
+  readonly stack?: string
+  /** Additional context about the error */
+  readonly context?: Readonly<Record<string, unknown>>
+}
+
+/**
+ * Type alias for analysis operations that may fail.
+ */
+export type AnalysisResultType<T> = Result<T, AnalysisError>
+
+// Re-export Result types for convenience
+export type {Err, Ok, Result} from './result'
+export {
+  err,
+  flatMap,
+  fromPromise,
+  fromThrowable,
+  isErr,
+  isOk,
+  map,
+  mapErr,
+  ok,
+  unwrap,
+  unwrapOr,
+} from './result'

package/src/types/result.ts

@@ -0,0 +1,19 @@
+/**
+ * Re-export Result types from @bfra.me/es/result for discriminated union error handling.
+ *
+ * The Result pattern provides type-safe error handling without exceptions.
+ * Prefer this pattern over throwing for expected/recoverable errors in analysis operations.
+ */
+
+export {err, ok} from '@bfra.me/es/result'
+export {isErr, isOk} from '@bfra.me/es/result'
+export {
+  flatMap,
+  fromPromise,
+  fromThrowable,
+  map,
+  mapErr,
+  unwrap,
+  unwrapOr,
+} from '@bfra.me/es/result'
+export type {Err, Ok, Result} from '@bfra.me/es/result'

package/src/utils/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Utility module exports.
+ *
+ * Provides shared utility functions used across the workspace analyzer package.
+ */
+
+export {matchAnyPattern, matchPattern, normalizePath} from './pattern-matcher'

package/src/utils/pattern-matcher.ts

@@ -0,0 +1,48 @@
+/**
+ * Pattern matching utilities for glob-style file path matching.
+ *
+ * Provides simple glob pattern matching supporting ** (any path segments)
+ * and * (single segment) without external dependencies.
+ */
+
+/**
+ * Matches a file path against a glob pattern.
+ *
+ * Supported patterns:
+ * - `**` matches any number of path segments
+ * - `*` matches any characters except path separator
+ */
+export function matchPattern(filePath: string, pattern: string): boolean {
+  const normalizedPath = normalizePath(filePath)
+
+  const DOUBLE_STAR_PLACEHOLDER = '\0DOUBLE_STAR\0'
+  const regexPattern = pattern
+    .replaceAll('**', DOUBLE_STAR_PLACEHOLDER)
+    .replaceAll('*', '[^/]*')
+    .replaceAll(DOUBLE_STAR_PLACEHOLDER, '.*')
+    .replaceAll('/', String.raw`\/`)
+
+  const regex = new RegExp(regexPattern)
+  return regex.test(normalizedPath)
+}
+
+/**
+ * Checks if a file path matches any of the given patterns.
+ */
+export function matchAnyPattern(filePath: string, patterns: readonly string[]): boolean {
+  for (const pattern of patterns) {
+    if (matchPattern(filePath, pattern)) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * Normalizes a file path for consistent pattern matching.
+ *
+ * Converts backslashes to forward slashes for cross-platform compatibility.
+ */
+export function normalizePath(filePath: string): string {
+  return filePath.replaceAll('\\', '/')
+}