@bfra.me/workspace-analyzer 0.1.0 → 0.2.0

package/src/visualizer/types.ts

@@ -0,0 +1,226 @@
+/**
+ * Type definitions for dependency graph visualization.
+ *
+ * These types define the data structures used to transform a DependencyGraph
+ * into a format suitable for interactive D3.js visualization.
+ */
+
+import type {Severity} from '../types/index'
+
+/**
+ * A node in the visualization graph representing a module.
+ */
+export interface VisualizationNode {
+  /** Unique identifier (typically the normalized file path) */
+  readonly id: string
+  /** Display name for the node */
+  readonly name: string
+  /** Full file path of the module */
+  readonly filePath: string
+  /** Package name if the module belongs to a workspace package */
+  readonly packageName: string | undefined
+  /** Architectural layer (e.g., 'domain', 'application', 'infrastructure') */
+  readonly layer: string | undefined
+  /** Number of modules this node imports */
+  readonly importsCount: number
+  /** Number of modules that import this node */
+  readonly importedByCount: number
+  /** Whether this node is part of a dependency cycle */
+  readonly isInCycle: boolean
+  /** Violations associated with this node */
+  readonly violations: readonly VisualizationViolation[]
+  /** Highest severity level among violations (undefined if no violations) */
+  readonly highestViolationSeverity: Severity | undefined
+}
+
+/**
+ * An edge in the visualization graph representing an import relationship.
+ */
+export interface VisualizationEdge {
+  /** Source node ID (the importing module) */
+  readonly source: string
+  /** Target node ID (the imported module) */
+  readonly target: string
+  /** Import type classification */
+  readonly type: 'static' | 'dynamic' | 'type-only' | 'require'
+  /** Whether this edge is part of a dependency cycle */
+  readonly isInCycle: boolean
+  /** ID of the cycle this edge belongs to (undefined if not in a cycle) */
+  readonly cycleId: string | undefined
+}
+
+/**
+ * A violation displayed on a node or edge in the visualization.
+ */
+export interface VisualizationViolation {
+  /** Unique identifier for this violation */
+  readonly id: string
+  /** Human-readable message describing the violation */
+  readonly message: string
+  /** Severity level of the violation */
+  readonly severity: Severity
+  /** ID of the rule that generated this violation */
+  readonly ruleId: string
+}
+
+/**
+ * Cycle information for visualization highlighting.
+ */
+export interface VisualizationCycle {
+  /** Unique identifier for this cycle */
+  readonly id: string
+  /** Node IDs participating in the cycle, in order */
+  readonly nodes: readonly string[]
+  /** Edges forming the cycle path */
+  readonly edges: readonly {readonly from: string; readonly to: string}[]
+  /** Number of nodes in the cycle */
+  readonly length: number
+  /** Human-readable description of the cycle path */
+  readonly description: string
+}
+
+/**
+ * Statistics summary for the visualization.
+ */
+export interface VisualizationStatistics {
+  /** Total number of nodes in the graph */
+  readonly totalNodes: number
+  /** Total number of edges (import relationships) */
+  readonly totalEdges: number
+  /** Total number of dependency cycles detected */
+  readonly totalCycles: number
+  /** Count of nodes grouped by architectural layer */
+  readonly nodesByLayer: Readonly<Record<string, number>>
+  /** Count of violations grouped by severity level */
+  readonly violationsBySeverity: Readonly<Record<Severity, number>>
+  /** Number of workspace packages analyzed */
+  readonly packagesAnalyzed: number
+  /** Number of source files analyzed */
+  readonly filesAnalyzed: number
+}
+
+/**
+ * Metadata about the visualization generation.
+ */
+export interface VisualizationMetadata {
+  /** Root path of the analyzed workspace */
+  readonly workspacePath: string
+  /** ISO 8601 timestamp when the visualization was generated */
+  readonly generatedAt: string
+  /** Version of the workspace-analyzer that generated this data */
+  readonly analyzerVersion: string
+}
+
+/**
+ * Layer definition for architectural boundary visualization.
+ */
+export interface VisualizationLayerDefinition {
+  /** Layer name (e.g., 'domain', 'application') */
+  readonly name: string
+  /** Layers this layer is allowed to depend on */
+  readonly allowedDependencies: readonly string[]
+}
+
+/**
+ * Complete visualization data ready for rendering.
+ */
+export interface VisualizationData {
+  /** All nodes in the visualization graph */
+  readonly nodes: readonly VisualizationNode[]
+  /** All edges (import relationships) in the graph */
+  readonly edges: readonly VisualizationEdge[]
+  /** Detected dependency cycles */
+  readonly cycles: readonly VisualizationCycle[]
+  /** Summary statistics */
+  readonly statistics: VisualizationStatistics
+  /** Architectural layer definitions for filtering */
+  readonly layers: readonly VisualizationLayerDefinition[]
+  /** Generation metadata */
+  readonly metadata: VisualizationMetadata
+}
+
+/**
+ * Filter configuration for the visualization UI.
+ */
+export interface VisualizationFilters {
+  /** Layers to display (empty = all layers) */
+  readonly layers: readonly string[]
+  /** Severity levels to display (empty = all severities) */
+  readonly severities: readonly Severity[]
+  /** Package scopes to display (e.g., '@bfra.me/*') */
+  readonly packages: readonly string[]
+  /** Show only nodes that are part of cycles */
+  readonly showCyclesOnly: boolean
+  /** Show only nodes with violations */
+  readonly showViolationsOnly: boolean
+}
+
+/**
+ * Options for configuring visualization generation.
+ */
+export interface VisualizerOptions {
+  /** Output path for the generated HTML file */
+  readonly outputPath: string
+  /** Output format(s) to generate */
+  readonly format: 'html' | 'json' | 'both'
+  /** Whether to auto-open the generated file in the browser */
+  readonly autoOpen: boolean
+  /** Title displayed in the visualization */
+  readonly title: string
+  /** Pre-applied filters for the initial visualization state */
+  readonly filters: Partial<VisualizationFilters>
+  /** Include type-only imports in the graph */
+  readonly includeTypeImports: boolean
+  /** Maximum number of nodes to render (for performance) */
+  readonly maxNodes: number
+}
+
+/**
+ * Default visualization options.
+ */
+export const DEFAULT_VISUALIZER_OPTIONS: VisualizerOptions = {
+  outputPath: './workspace-graph.html',
+  format: 'html',
+  autoOpen: true,
+  title: 'Workspace Dependency Graph',
+  filters: {},
+  includeTypeImports: true,
+  maxNodes: 1000,
+}
+
+/**
+ * Severity levels ordered by importance (highest first).
+ */
+export const SEVERITY_ORDER: readonly Severity[] = ['critical', 'error', 'warning', 'info'] as const
+
+/**
+ * Error type for visualization generation failures.
+ */
+export interface VisualizationError {
+  /** Error code for programmatic handling */
+  readonly code: 'INVALID_GRAPH' | 'TRANSFORM_FAILED' | 'LIMIT_EXCEEDED'
+  /** Human-readable error message */
+  readonly message: string
+  /** Optional details about the error */
+  readonly details?: Record<string, unknown>
+}
+
+/**
+ * Gets the highest severity from a list of severities.
+ *
+ * @param severities - Array of severity levels
+ * @returns The highest severity, or undefined if the array is empty
+ */
+export function getHighestSeverity(severities: readonly Severity[]): Severity | undefined {
+  if (severities.length === 0) {
+    return undefined
+  }
+
+  for (const level of SEVERITY_ORDER) {
+    if (severities.includes(level)) {
+      return level
+    }
+  }
+
+  return severities[0]
+}

package/src/visualizer/violation-collector.ts

@@ -0,0 +1,246 @@
+/**
+ * Violation collection utilities for gathering architectural issues from RuleEngine.
+ *
+ * Provides functions to collect violations from the rule engine and associate them
+ * with visualization nodes for display in the interactive graph.
+ */
+
+import type {Project, SourceFile} from 'ts-morph'
+
+import type {createRuleEngine, RuleContext} from '../rules/rule-engine'
+import type {WorkspacePackage} from '../scanner/workspace-scanner'
+import type {Issue} from '../types/index'
+import type {Result} from '../types/result'
+import type {VisualizationError, VisualizationNode} from './types'
+
+import path from 'node:path'
+
+import {createProject} from '@bfra.me/doc-sync'
+import {err, isErr, ok} from '@bfra.me/es/result'
+
+import {getHighestSeverity} from './types'
+
+/**
+ * Context for collecting violations from the workspace.
+ */
+export interface ViolationCollectionContext {
+  /** The rule engine instance to use for evaluation */
+  readonly ruleEngine: ReturnType<typeof createRuleEngine>
+  /** All packages in the workspace */
+  readonly packages: readonly WorkspacePackage[]
+  /** Root path of the workspace */
+  readonly workspacePath: string
+  /** Optional tsconfig path mappings */
+  readonly tsconfigPaths?: Readonly<Record<string, readonly string[]>>
+  /** Optional progress reporting callback */
+  readonly reportProgress?: (message: string) => void
+}
+
+/**
+ * Options for violation collection.
+ */
+export interface ViolationCollectionOptions {
+  /** Whether to include info-level issues */
+  readonly includeInfo: boolean
+  /** Maximum number of issues to collect (for performance) */
+  readonly maxIssues: number
+  /** File patterns to exclude from analysis */
+  readonly excludePatterns: readonly string[]
+}
+
+/**
+ * Default options for violation collection.
+ */
+export const DEFAULT_VIOLATION_COLLECTION_OPTIONS: ViolationCollectionOptions = {
+  includeInfo: true,
+  maxIssues: 10000,
+  excludePatterns: ['**/*.test.ts', '**/*.spec.ts', '**/node_modules/**'],
+}
+
+/**
+ * Collects architectural violations using the RuleEngine.
+ *
+ * Evaluates all source files in the workspace packages against the configured
+ * architectural rules and collects the resulting issues for visualization.
+ *
+ * @param context - Context containing rule engine and workspace information
+ * @param options - Options for controlling collection behavior
+ * @returns Result containing collected issues or an error
+ */
+export async function collectVisualizationViolations(
+  context: ViolationCollectionContext,
+  options: Partial<ViolationCollectionOptions> = {},
+): Promise<Result<readonly Issue[], VisualizationError>> {
+  const opts: ViolationCollectionOptions = {
+    ...DEFAULT_VIOLATION_COLLECTION_OPTIONS,
+    ...options,
+  }
+
+  const {ruleEngine, packages, workspacePath, tsconfigPaths, reportProgress} = context
+
+  const allIssues: Issue[] = []
+
+  try {
+    for (const pkg of packages) {
+      reportProgress?.(`Collecting violations from ${pkg.name}...`)
+
+      const tsconfigPath = path.join(pkg.packagePath, 'tsconfig.json')
+
+      let project: Project
+      try {
+        project = createProject({
+          tsConfigPath: tsconfigPath,
+        })
+      } catch {
+        continue
+      }
+
+      const sourceFiles = getSourceFiles(project)
+
+      for (const sourceFile of sourceFiles) {
+        const filePath = sourceFile.getFilePath()
+
+        if (shouldSkipFile(filePath, opts.excludePatterns)) {
+          continue
+        }
+
+        const ruleContext: RuleContext = {
+          sourceFile,
+          pkg,
+          workspacePath,
+          allPackages: packages,
+          tsconfigPaths,
+        }
+
+        const result = await ruleEngine.evaluateFile(ruleContext)
+
+        if (isErr(result)) {
+          continue
+        }
+
+        const issues = result.data
+
+        const filteredIssues = opts.includeInfo
+          ? issues
+          : issues.filter(issue => issue.severity !== 'info')
+
+        allIssues.push(...filteredIssues)
+
+        if (allIssues.length >= opts.maxIssues) {
+          reportProgress?.(`Reached maximum issue limit (${opts.maxIssues})`)
+          break
+        }
+      }
+
+      if (allIssues.length >= opts.maxIssues) {
+        break
+      }
+    }
+
+    return ok(allIssues)
+  } catch (error) {
+    return err({
+      code: 'TRANSFORM_FAILED',
+      message: `Error collecting violations: ${error instanceof Error ? error.message : String(error)}`,
+    })
+  }
+}
+
+/**
+ * Maps issues to their corresponding visualization nodes.
+ *
+ * Associates each issue with the node(s) it affects by matching file paths.
+ * Updates nodes with their violations and highest severity level.
+ *
+ * @param nodes - Visualization nodes to annotate with violations
+ * @param issues - Issues collected from rule engine
+ * @returns Updated nodes with violation information
+ */
+export function mapIssuesToNodes(
+  nodes: readonly VisualizationNode[],
+  issues: readonly Issue[],
+): readonly VisualizationNode[] {
+  const nodesByPath = new Map<string, VisualizationNode>()
+
+  for (const node of nodes) {
+    const normalizedPath = normalizePath(node.filePath)
+    nodesByPath.set(normalizedPath, node)
+  }
+
+  const issuesByPath = new Map<string, Issue[]>()
+  for (const issue of issues) {
+    const normalizedPath = normalizePath(issue.location.filePath)
+    const existing = issuesByPath.get(normalizedPath) ?? []
+    existing.push(issue)
+    issuesByPath.set(normalizedPath, existing)
+  }
+
+  return nodes.map(node => {
+    const normalizedPath = normalizePath(node.filePath)
+    const nodeIssues = issuesByPath.get(normalizedPath) ?? []
+
+    if (nodeIssues.length === 0) {
+      return node
+    }
+
+    const violations = nodeIssues.map((issue, index) => ({
+      id: `${issue.id}-${index}`,
+      message: issue.description,
+      severity: issue.severity,
+      ruleId: issue.id,
+    }))
+
+    const severities = violations.map(v => v.severity)
+    const highestSeverity = getHighestSeverity(severities)
+
+    return {
+      ...node,
+      violations,
+      highestViolationSeverity: highestSeverity,
+    }
+  })
+}
+
+/**
+ * Gets source files from a TypeScript project.
+ *
+ * @param project - The ts-morph project
+ * @returns Array of source files for analysis
+ */
+function getSourceFiles(project: Project): readonly SourceFile[] {
+  return project.getSourceFiles().filter(sf => {
+    const filePath = sf.getFilePath()
+    return (
+      (filePath.endsWith('.ts') ||
+        filePath.endsWith('.tsx') ||
+        filePath.endsWith('.js') ||
+        filePath.endsWith('.jsx')) &&
+      !filePath.includes('node_modules') &&
+      !filePath.includes('.test.') &&
+      !filePath.includes('.spec.')
+    )
+  })
+}
+
+/**
+ * Determines if a file should be skipped based on exclude patterns.
+ */
+function shouldSkipFile(filePath: string, excludePatterns: readonly string[]): boolean {
+  if (excludePatterns.length === 0) {
+    return false
+  }
+
+  const normalized = normalizePath(filePath)
+
+  return excludePatterns.some(pattern => {
+    const normalizedPattern = pattern.replaceAll('\\', '/').toLowerCase()
+    return normalized.includes(normalizedPattern.replaceAll('**', '').replaceAll('*', ''))
+  })
+}
+
+/**
+ * Normalizes a file path for comparison.
+ */
+function normalizePath(filePath: string): string {
+  return filePath.replaceAll('\\', '/').toLowerCase()
+}