@bfra.me/workspace-analyzer

@bfra.me/workspace-analyzer

Comprehensive monorepo static analysis for workspace configuration, dependencies, and architecture.

Features

• Configuration Analysis: Detect inconsistencies across package.json, tsconfig.json, eslint.config.ts, and tsup.config.ts files
• Dependency Analysis: Identify unused dependencies and circular imports with full path reporting
• Architectural Validation: Validate against configurable rule sets (layer violations, barrel export misuse)
• Performance Analysis: Identify tree-shaking blockers, large dependencies, and dead code
• Modern CLI: Interactive TUI using @clack/prompts with progress reporting
• Incremental Analysis: Caching support for fast re-analysis of large codebases
• Multiple Output Formats: Console, JSON, and Markdown report generation

Installation

pnpm add -D @bfra.me/workspace-analyzer

Quick Start

# Analyze current workspace
npx workspace-analyzer

# Interactive mode with package selection
npx workspace-analyzer --interactive

# CI-friendly JSON output
npx workspace-analyzer --json > analysis-report.json

CLI Usage

The CLI provides a modern, interactive experience powered by @clack/prompts:

# Basic analysis
workspace-analyzer [path]

# With configuration file
workspace-analyzer --config workspace-analyzer.config.ts

# Output formats
workspace-analyzer --json          # JSON output
workspace-analyzer --markdown      # Markdown report

# Filtering options
workspace-analyzer --min-severity warning
workspace-analyzer --categories dependency,architecture

# Analysis control
workspace-analyzer --no-cache      # Disable caching
workspace-analyzer --verbose       # Detailed output
workspace-analyzer --dry-run       # Preview without analysis

CLI Options

Option	Description
--config <path>	Path to configuration file
--json	Output results as JSON
--markdown	Output results as Markdown
--min-severity <level>	Minimum severity to report (info, warning, error, critical)
--categories <list>	Comma-separated categories to analyze
--include <patterns>	Glob patterns for files to include
--exclude <patterns>	Glob patterns for files to exclude
--no-cache	Disable incremental analysis caching
--cache-dir <path>	Custom cache directory
--concurrency <n>	Maximum parallel operations
--verbose	Enable verbose logging
--quiet	Suppress non-essential output
--dry-run	Preview analysis without executing
--interactive	Interactive package selection
--fix	Apply auto-fixes where available (placeholder)

Visualization Command

Generate interactive dependency graph visualizations with the visualize command:

# Generate interactive HTML visualization
workspace-analyzer visualize

# Generate JSON data for external tools
workspace-analyzer visualize --format json --output graph.json

# Generate Mermaid diagram
workspace-analyzer visualize --format mermaid --output graph.mmd

# Interactive mode with options
workspace-analyzer visualize --interactive

# Custom title and node limits
workspace-analyzer visualize --title "My Project" --max-nodes 100

# Generate both HTML and JSON
workspace-analyzer visualize --format both

Visualization Options

Option	Description	Default
--output <path>	Output file path	workspace-graph.html
--format <format>	Output format: html, json, mermaid, both	html
--no-open	Disable auto-opening in browser	false (opens by default)
--title <title>	Visualization title	Workspace Dependency Graph
--max-nodes <number>	Maximum nodes to render (performance)	1000
--include-type-imports	Include type-only imports in graph	false
--interactive	Interactive mode for options selection	false

Export Formats

HTML - Self-contained interactive visualization with D3.js:

• Force-directed graph layout with zoom/pan controls
• Filter by layer, severity, package scope
• View modes: all, cycles-only, violations-only
• Node tooltips with violation details
• No external network requests (fully offline)

JSON - Structured data for external tools and custom processing:

{
  "nodes": [
    {
      "id": "src/utils/helpers.ts",
      "name": "helpers.ts",
      "filePath": "src/utils/helpers.ts",
      "packageName": "@myorg/utils",
      "layer": "infrastructure",
      "importsCount": 5,
      "importedByCount": 12,
      "isInCycle": false,
      "violations": [
        {
          "id": "v1",
          "message": "Layer violation: infrastructure importing from domain",
          "severity": "error",
          "ruleId": "layer-dependency"
        }
      ],
      "highestViolationSeverity": "error"
    }
  ],
  "edges": [
    {
      "source": "src/utils/helpers.ts",
      "target": "src/core/types.ts",
      "type": "static",
      "isInCycle": false
    }
  ],
  "cycles": [
    {
      "id": "cycle-1",
      "nodes": ["src/a.ts", "src/b.ts"],
      "edges": [
        {"from": "src/a.ts", "to": "src/b.ts"},
        {"from": "src/b.ts", "to": "src/a.ts"}
      ],
      "length": 2,
      "description": "Circular dependency: a.ts → b.ts → a.ts"
    }
  ],
  "statistics": {
    "totalNodes": 250,
    "totalEdges": 380,
    "totalCycles": 3,
    "nodesByLayer": {
      "domain": 50,
      "application": 80,
      "infrastructure": 120
    },
    "violationsBySeverity": {
      "critical": 0,
      "error": 5,
      "warning": 15,
      "info": 2
    },
    "packagesAnalyzed": 12,
    "filesAnalyzed": 250
  },
  "metadata": {
    "workspacePath": "/path/to/workspace",
    "generatedAt": "2025-12-10T00:00:00Z",
    "analyzerVersion": "0.1.0"
  }
}

Mermaid - Diagram markup for documentation and external rendering:

graph LR
  src_utils_helpers_ts["helpers.ts"]:::class-error
  src_core_types_ts["types.ts"]:::class-normal
  src_utils_helpers_ts --> src_core_types_ts

  classDef class-critical fill:#ff4444,stroke:#cc0000,stroke-width:3px,color:#fff
  classDef class-error fill:#ff8844,stroke:#cc4400,stroke-width:2px,color:#fff
  classDef class-warning fill:#ffcc44,stroke:#ccaa00,stroke-width:2px,color:#000
  classDef class-info fill:#4488ff,stroke:#0044cc,stroke-width:1px,color:#fff
  classDef class-normal fill:#88ccff,stroke:#0088cc,stroke-width:1px,color:#000

Common Visualization Scenarios

Investigate Circular Dependencies:

# Generate visualization focusing on cycles
workspace-analyzer visualize --title "Circular Dependencies" --output cycles.html

# Export cycle data for CI validation
workspace-analyzer visualize --format json --output cycles.json

# Generate Mermaid diagram for documentation
workspace-analyzer visualize --format mermaid --output cycles.mmd

Analyze Layer Architecture:

# Visualize architectural boundaries with violations highlighted
workspace-analyzer visualize --title "Architecture Review" --output architecture.html

# Focus on specific package scope
workspace-analyzer visualize --title "Core Packages" --output core.html

Performance Analysis:

# Limit visualization to high-impact nodes
workspace-analyzer visualize --max-nodes 200 --output critical-paths.html

# Export JSON for custom metrics calculation
workspace-analyzer visualize --format json --output metrics.json

CI/CD Integration:

# Generate artifacts for PR review
workspace-analyzer visualize --format both --no-open --output build/graph

# Validate no new circular dependencies
workspace-analyzer visualize --format json | jq '.statistics.totalCycles == 0'

Integration with External Tools

The JSON export format is designed for integration with custom analysis pipelines:

import {readFile} from 'node:fs/promises'

const data = JSON.parse(await readFile('graph.json', 'utf-8'))

// Find all files with critical violations
const criticalFiles = data.nodes.filter(
  node => node.highestViolationSeverity === 'critical'
)

// Identify largest cycles
const largeCycles = data.cycles
  .filter(cycle => cycle.length > 5)
  .sort((a, b) => b.length - a.length)

// Calculate dependency metrics
const avgImportsPerFile = data.statistics.totalEdges / data.statistics.totalNodes
const cycleRate = data.statistics.totalCycles / data.statistics.totalNodes

// Detect architectural hotspots
const layerViolations = data.nodes
  .filter(node => node.violations.some(v => v.ruleId === 'layer-dependency'))
  .map(node => ({
    file: node.filePath,
    layer: node.layer,
    violations: node.violations.length,
  }))
  .sort((a, b) => b.violations - a.violations)

// Find most connected nodes (potential coupling issues)
const highlyConnected = data.nodes
  .filter(node => node.importsCount + node.importedByCount > 20)
  .sort((a, b) =>
    (b.importsCount + b.importedByCount) - (a.importsCount + a.importedByCount)
  )

Programmatic API

analyzeWorkspace(path, options)

Analyzes an entire workspace for issues.

import {analyzeWorkspace} from '@bfra.me/workspace-analyzer'

const result = await analyzeWorkspace('./my-monorepo', {
  minSeverity: 'warning',
  categories: ['dependency', 'architecture'],
  onProgress: (progress) => {
    console.log(`${progress.phase}: ${progress.processed}/${progress.total}`)
  },
})

if (result.success) {
  console.log(`Found ${result.data.summary.totalIssues} issues`)
  for (const issue of result.data.issues) {
    console.log(`[${issue.severity}] ${issue.title}`)
    console.log(`  ${issue.location.filePath}:${issue.location.line}`)
    if (issue.suggestion) {
      console.log(`  Fix: ${issue.suggestion}`)
    }
  }
} else {
  console.error(`Analysis failed: ${result.error.message}`)
}

analyzePackages(path, packageNames, options)

Analyzes specific packages within a workspace.

import {analyzePackages} from '@bfra.me/workspace-analyzer'

const result = await analyzePackages('./my-monorepo', [
  '@myorg/core',
  '@myorg/utils',
])

if (result.success) {
  console.log(`Analyzed ${result.data.summary.packagesAnalyzed} packages`)
}

defineConfig(config)

Type-safe configuration helper.

import {defineConfig} from '@bfra.me/workspace-analyzer'

export default defineConfig({
  minSeverity: 'warning',
  categories: ['dependency', 'architecture'],
})

Configuration

Create a workspace-analyzer.config.ts file in your workspace root:

import {defineConfig} from '@bfra.me/workspace-analyzer'

export default defineConfig({
  // File patterns
  include: ['**/*.ts', '**/*.tsx'],
  exclude: ['**/node_modules/**', '**/lib/**', '**/dist/**'],

  // Analysis settings
  minSeverity: 'warning',
  categories: ['dependency', 'configuration', 'architecture'],

  // Performance
  cache: true,
  cacheDir: '.workspace-analyzer-cache',
  concurrency: 4,

  // Package patterns (for monorepo scanning)
  packagePatterns: ['packages/*', 'apps/*'],

  // Per-analyzer configuration
  analyzers: {
    'circular-import': {enabled: true, severity: 'error'},
    'unused-dependency': {enabled: true, severity: 'warning'},
    'config-consistency': {enabled: true},
    'tree-shaking-blocker': {enabled: true},
    'dead-code': {enabled: false}, // Disable specific analyzer
  },

  // Architectural rules
  architecture: {
    layers: [
      {name: 'domain', patterns: ['**/domain/**'], allowedImports: []},
      {name: 'application', patterns: ['**/application/**'], allowedImports: ['domain']},
      {name: 'infrastructure', patterns: ['**/infrastructure/**'], allowedImports: ['domain', 'application']},
    ],
    allowBarrelExports: ['**/index.ts'],
    enforcePublicApi: true,
  },
})

Configuration File Names

The analyzer searches for configuration in these files (in order):

• workspace-analyzer.config.ts
• workspace-analyzer.config.js
• workspace-analyzer.config.mjs
• workspace-analyzer.config.cjs

Built-in Analyzers

Configuration Analyzers

Analyzer	Description
package-json	Validates package.json structure, exports, and scripts
tsconfig	Checks TypeScript configuration consistency
eslint-config	Validates ESLint configuration patterns
build-config	Analyzes tsup/build configuration
config-consistency	Cross-validates configuration across files
version-alignment	Checks dependency version consistency across packages
exports-field	Validates exports field against actual source files

Dependency Analyzers

Analyzer	Description
unused-dependency	Detects dependencies declared but not imported
circular-import	Finds circular import chains using Tarjan's algorithm
peer-dependency	Validates peer dependency declarations
duplicate-dependency	Finds duplicate dependencies across packages

Architectural Analyzers

Analyzer	Description
architectural	Enforces layer boundaries and import restrictions

Performance Analyzers

Analyzer	Description
tree-shaking-blocker	Detects patterns that prevent tree-shaking
dead-code	Finds unreachable/unused exports
duplicate-code	Identifies similar code blocks via AST fingerprinting
large-dependency	Flags large dependencies that may impact bundle size

Issue Categories

Category	Description
configuration	Package.json, tsconfig.json, and build config issues
dependency	Unused, duplicate, or misversioned dependencies
architecture	Layer violations, barrel export misuse, public API issues
performance	Tree-shaking blockers, large dependencies
circular-import	Circular dependency chains
unused-export	Exports not used within the workspace
type-safety	TypeScript configuration issues

Severity Levels

Level	Description
info	Informational findings, suggestions for improvement
warning	Potential issues that should be reviewed
error	Problems that should be fixed
critical	Severe issues requiring immediate attention

Architectural Rules

Layer Violation Rule

Enforces architectural layer boundaries:

defineConfig({
  architecture: {
    layers: [
      {name: 'domain', patterns: ['**/domain/**'], allowedImports: []},
      {name: 'application', patterns: ['**/app/**'], allowedImports: ['domain']},
      {name: 'infrastructure', patterns: ['**/infra/**'], allowedImports: ['domain', 'application']},
    ],
  },
})

Barrel Export Rule

Controls export * usage:

defineConfig({
  architecture: {
    // Allow barrel exports only in specific files
    allowBarrelExports: ['**/index.ts'],
    // Or disable barrel exports entirely
    // allowBarrelExports: false,
  },
})

Public API Rule

Enforces explicit public API surface:

defineConfig({
  architecture: {
    enforcePublicApi: true,
  },
})

Output Formats

Console (Default)

Colorized terminal output with severity highlighting and file locations.

JSON

Machine-readable output for CI integration:

workspace-analyzer --json > report.json

{
  "issues": [],
  "summary": {
    "totalIssues": 5,
    "bySeverity": {"warning": 3, "error": 2},
    "byCategory": {"dependency": 2, "architecture": 3},
    "packagesAnalyzed": 8,
    "filesAnalyzed": 150,
    "durationMs": 2500
  }
}

Markdown

Human-readable report for documentation or PR comments:

workspace-analyzer --markdown > ANALYSIS.md

Caching

The analyzer supports incremental caching for improved performance:

defineConfig({
  cache: true,
  cacheDir: '.workspace-analyzer-cache',
  maxCacheAge: 7 * 24 * 60 * 60 * 1000, // 7 days
  hashAlgorithm: 'sha256',
})

Cache is automatically invalidated when:

• Source files change (content hash)
• Configuration files change
• Analyzer versions change

CI Integration

GitHub Actions

- name: Run workspace analysis
  run: pnpm workspace-analyzer --json > analysis-report.json

- name: Check for errors
  run: |
    if jq -e '.summary.bySeverity.error > 0' analysis-report.json; then
      echo "Analysis found errors"
      exit 1
    fi

Pre-commit Hook

# package.json
{
  "lint-staged": {
    "*.{ts,tsx}": ["workspace-analyzer --categories dependency,architecture"]
  }
}

Development

# Build the package
pnpm --filter @bfra.me/workspace-analyzer build

# Run tests
pnpm --filter @bfra.me/workspace-analyzer test

# Type check
pnpm --filter @bfra.me/workspace-analyzer type-check

Related Packages

• @bfra.me/es - Core utilities (Result type, async helpers)
• @bfra.me/doc-sync - Documentation sync (shares TypeScript parsing infrastructure)
• @bfra.me/eslint-config - ESLint configuration

License

MIT © Marcus R. Brown