Codexray

A local-first code-health and refactoring analysis tool for TypeScript repositories.

Overview

Codexray scans TypeScript codebases, detects maintainability and structural issues, reports findings in a clean structured way, and optionally applies a limited set of safe autofixes. It runs entirely offline after install and is designed to be easy to Dockerize.

Features

• CLI-first UX - Simple command-line interface
• Local-first - No network dependencies at runtime
• TypeScript only - Focused analysis for TypeScript projects
• Structured findings - Clear, actionable reports
• JSON output - Easy integration with other tools
• Safe autofixes - Limited transformations for clearly safe cases
• Extensible - Designed to support more rules and output adapters

Quick Start

# Clone and build
git clone <repo-url>
cd codexray
npm install
npm run build

# Scan the sample fixture project
npm run scan:sample

# Scan Codexray's own source code
npm run scan:src

# Scan any TypeScript project (use -- to pass arguments)
npm run scan -- /path/to/your/project

# Scan with options
npm run scan -- ./src --verbose
npm run scan -- ./src --format json
npm run scan -- ./src --rules max-params,no-large-functions

# Preview autofixes (dry-run)
npm run fix:dry

# Run all tests
npm test

Installation

npm install -g codexray

Or use directly with npx:

npx codexray scan ./src

Usage

Scan a project

# Scan a directory
codexray scan ./src

# Scan with JSON output
codexray scan ./src --format json

# Scan with specific rules
codexray scan ./src --rules max-params,no-large-functions

# Verbose output
codexray scan ./src --verbose

# Save output to file
codexray scan ./src --format json --output report.json

Fix issues

# Preview fixes (dry-run)
codexray fix ./src --dry-run

# Apply fixes
codexray fix ./src

# Fix specific rules only
codexray fix ./src --rules prefer-early-return

# Create backups before fixing
codexray fix ./src --backup

Generate reports

# Generate terminal report
codexray report ./src

# Generate JSON report
codexray report ./src --format json --output report.json

Explain rules

# List all available rules
codexray explain

# Explain a specific rule
codexray explain no-large-functions

Built-in Rules

no-large-functions

Detects functions that exceed a configurable line threshold.

• Default threshold: 50 lines
• Severity: warning
• Options: maxLines - Maximum allowed lines

{
  "rules": {
    "no-large-functions": {
      "enabled": true,
      "severity": "warning",
      "options": { "maxLines": 50 }
    }
  }
}

max-params

Detects functions with too many parameters.

• Default threshold: 4 parameters
• Severity: warning
• Options: maxParams - Maximum allowed parameters

{
  "rules": {
    "max-params": {
      "enabled": true,
      "severity": "warning",
      "options": { "maxParams": 4 }
    }
  }
}

no-deep-nesting

Detects functions whose nesting depth exceeds a threshold.

• Default threshold: 4 levels
• Severity: warning
• Options: maxDepth - Maximum allowed nesting depth

{
  "rules": {
    "no-deep-nesting": {
      "enabled": true,
      "severity": "warning",
      "options": { "maxDepth": 4 }
    }
  }
}

prefer-early-return

Detects nested conditionals that could be simplified with guard clauses.

• Default threshold: 2 levels of nesting
• Severity: info
• Has autofix: Yes (for safe cases)
• Options: minNestingLevel - Minimum nesting to report

{
  "rules": {
    "prefer-early-return": {
      "enabled": true,
      "severity": "info",
      "options": { "minNestingLevel": 2 }
    }
  }
}

boolean-parameter-trap

Detects boolean parameters that create ambiguous call sites.

• Severity: warning
• Options: minPosition - Minimum parameter position to flag (0-indexed)

{
  "rules": {
    "boolean-parameter-trap": {
      "enabled": true,
      "severity": "warning",
      "options": { "minPosition": 0 }
    }
  }
}

Example:

// ❌ Bad - what does true mean?
createUser('john', true);

// ✅ Better - use options object
createUser('john', { isAdmin: true });

// ✅ Or split into separate functions
createAdminUser('john');

mixed-abstraction-levels

Detects functions that mix high-level orchestration with low-level implementation.

• Severity: warning
• Options:
  • minHighLevelScore - Minimum high-level signals (default: 1)
  • minLowLevelScore - Minimum low-level signals (default: 2)

{
  "rules": {
    "mixed-abstraction-levels": {
      "enabled": true,
      "severity": "warning",
      "options": { "minHighLevelScore": 1, "minLowLevelScore": 2 }
    }
  }
}

High-level signals: function calls, branching, orchestration verbs in name Low-level signals: loops, new expressions, property assignments, string formatting

inconsistent-error-handling

Detects files using multiple error handling strategies.

• Severity: warning
• Options: minFunctionCount - Minimum functions to check (default: 2)

{
  "rules": {
    "inconsistent-error-handling": {
      "enabled": true,
      "severity": "warning",
      "options": { "minFunctionCount": 2 }
    }
  }
}

Strategies detected:

• throw - throws exceptions
• null-return - returns null on error
• undefined-return - returns undefined on error
• result-object - returns { ok, data, error } style objects
• fallback-in-catch - catches and returns fallback value

switch-wants-polymorphism

Detects switch statements that would be better as handler maps or polymorphism.

• Severity: info
• Options:
  • minCases - Minimum cases to consider (default: 3)
  • minStructuralSimilarity - Similarity threshold 0-1 (default: 0.6)

{
  "rules": {
    "switch-wants-polymorphism": {
      "enabled": true,
      "severity": "info",
      "options": { "minCases": 3 }
    }
  }
}

Detects:

• Type-like discriminants (type, kind, status, mode, provider)
• Similar case structures
• Repeated assignment targets across cases

god-module

Detects files that are doing too much.

• Severity: warning
• Options: minScore - Minimum score to trigger (default: 3)

{
  "rules": {
    "god-module": {
      "enabled": true,
      "severity": "warning",
      "options": { "minScore": 3 }
    }
  }
}

Scoring:

• Lines: +1 for >300, +2 for >600
• Exports: +1 for >8, +2 for >15
• Functions/methods: +1 for >10
• Classes: +1 for >2
• Top-level statements: +1 for >20
• Import areas: +1 for >8

Configuration

Create a codexray.config.json file in your project root:

{
  "version": "1.0.0",
  "include": ["**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules/**", "dist/**", "**/*.d.ts"],
  "rules": {
    "no-large-functions": {
      "enabled": true,
      "options": { "maxLines": 40 }
    },
    "max-params": {
      "enabled": true,
      "options": { "maxParams": 3 }
    },
    "no-deep-nesting": {
      "enabled": true,
      "options": { "maxDepth": 3 }
    },
    "prefer-early-return": {
      "enabled": true
    }
  }
}

Exit Codes

• 0 - No errors found
• 1 - Errors found or command failed

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test
npm run test:watch    # Watch mode

# Available npm scripts
npm run scan          # Scan (pass path after --)
npm run scan:sample   # Scan sample fixture
npm run scan:src      # Scan Codexray's source
npm run scan:json     # Scan with JSON output
npm run fix:dry       # Preview autofixes

Passing Arguments

Use -- to pass arguments to npm scripts:

npm run scan -- ./your-project
npm run scan -- ./src --verbose --format json

Architecture

Codexray is designed with clean separation of concerns:

src/
├── cli/           # CLI layer (commands, entry point)
├── core/          # Analysis engine (scanner, analyzer, project loader)
├── rules/         # Rule system (types, registry, implementations)
├── findings/      # Finding model (types)
├── fixes/         # Fix/edit model (types, apply logic)
├── reporters/     # Output adapters (terminal, JSON)
├── config/        # Configuration (types, defaults)
└── utils/         # AST utilities

Extension Points

• Rules: Add new rules by implementing the Rule interface
• Reporters: Add new output formats by implementing the reporter pattern
• Fixes: Add autofix capabilities by implementing AutoFixableRule

License

MIT