🏥 SHCE - Structural Health & Code Evolution

SHCE is an open-source engine that continuously analyzes your codebase, predicts structural decay, and automatically proposes or applies safe refactors with mathematical or test-based guarantees that behavior remains unchanged.

🌟 Features

• 📊 Continuous Analysis: Real-time monitoring of code structure and quality metrics
• 🔮 Decay Prediction: Machine learning-based prediction of structural degradation
• 🔧 Automated Refactoring: Safe, behavior-preserving code transformations
• 📈 Metrics Tracking: Cyclomatic complexity, coupling, cohesion, maintainability index, and more
• 🎯 Multi-Platform: Available as VS Code extension, CLI tool, and GitHub Actions
• ✅ Behavioral Guarantees: Mathematical proofs and test-based verification of refactorings

🚀 Quick Start

VS Code Extension

1. Install from the VS Code Marketplace (search for "SHCE")
2. Open your workspace
3. Run command: SHCE: Analyze Workspace for Structural Decay
4. View results in the SHCE Health Monitor panel

CLI Tool

# Install globally
npm install -g shce

# Analyze a codebase
shce analyze ./my-project

# Generate HTML report
shce report ./my-project --output report.html --format html

# Continuous monitoring
shce watch ./my-project --interval 60

GitHub Actions

Add to .github/workflows/code-health.yml:

name: Code Health Check

on: [push, pull_request]

jobs:
  shce:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: SHCE Analysis
        uses: your-org/shce-action@v1
        with:
          threshold: 0.7
          fail-on-violation: true

📖 Usage

VS Code Extension Commands

• Analyze Workspace: Perform full structural analysis
• Show Health Dashboard: View interactive metrics dashboard
• Apply Refactoring: Apply suggested safe refactorings
• Enable Continuous Monitoring: Automatic analysis on file changes
• Export Report: Save analysis results to file

CLI Commands

# Analyze codebase
shce analyze <path> [options]
  --output <file>         Output file for report
  --format <format>       Output format (json, html, markdown)
  --threshold <number>    Health threshold (0-1)

# Generate report
shce report <path> [options]
  --output <file>         Output file (default: shce-report.html)
  --format <format>       Report format

# Apply refactorings
shce refactor <path> [options]
  --strategy <strategies> Refactoring strategies to apply
  --dry-run              Preview without applying
  --confidence <number>   Minimum confidence threshold

# Continuous monitoring
shce watch <path> [options]
  --interval <seconds>    Analysis interval

📊 Metrics Tracked

Code Quality Metrics

• Cyclomatic Complexity: Measures code complexity and decision points
• Maintainability Index: Overall code maintainability score (0-100)
• Lines of Code: Physical lines of code (excluding comments/blanks)
• Coupling: Dependencies between modules
• Cohesion: Internal consistency of modules

Structural Health Metrics

• Health Score: Overall codebase health (0-1)
• Decay Rate: Predicted rate of structural degradation
• High-Risk Files: Files requiring immediate attention
• Technical Debt: Estimated refactoring effort

🔧 Refactoring Strategies

SHCE supports multiple safe refactoring strategies:

Extract Function

Identifies complex code blocks that should be extracted into separate functions.

Trigger Conditions:

• Cyclomatic complexity > 10
• Nested control structures > 3 levels

Guarantee: Behavior preservation through AST analysis and test verification

Extract Variable

Simplifies complex expressions by extracting them to named variables.

Trigger Conditions:

• Expression complexity > threshold
• Repeated sub-expressions

Guarantee: Referential transparency verification

Simplify Conditionals

Refactors complex boolean expressions into clearer forms.

Trigger Conditions:

• Logical operators > 3
• Deeply nested conditions

Guarantee: Boolean algebra equivalence proofs

Remove Dead Code

Identifies and removes unused code.

Trigger Conditions:

• Unused variables, functions, imports
• Unreachable code blocks

Guarantee: Static analysis + test coverage verification

Inline Function

Removes unnecessary function indirection.

Trigger Conditions:

• Single-use functions
• Trivial function bodies

Guarantee: Inline expansion equivalence

🧮 Mathematical Guarantees

SHCE uses formal methods to ensure refactorings preserve behavior:

AST Equivalence

Refactorings must produce semantically equivalent Abstract Syntax Trees.

Type Preservation

All type relationships must be maintained after refactoring.

Test Coverage

All affected code paths must maintain 100% test pass rate.

Static Analysis

No new linting errors, type errors, or warnings introduced.

📈 Decay Prediction Model

SHCE uses a predictive model to forecast structural decay:

DecayRate = f(complexity, coupling, churn, duplication)
PredictedHealth(t) = CurrentHealth - (DecayRate × t)
DaysUntilCritical = (CurrentHealth - 0.5) / DecayRate

Factors Considered

• Complexity Growth: Increasing cyclomatic complexity
• Coupling Increase: Growing module dependencies
• Code Churn: Frequency of changes to files
• Duplication: Code clone detection
• Cohesion Decrease: Loss of module coherence

⚙️ Configuration

VS Code Settings

{
  "shce.autoAnalyze": true,
  "shce.autoApplyRefactors": false,
  "shce.decayThreshold": 0.7,
  "shce.metricsToTrack": [
    "cyclomaticComplexity",
    "codeChurn",
    "duplication",
    "coupling",
    "cohesion"
  ],
  "shce.refactorStrategies": [
    "extractFunction",
    "extractVariable",
    "simplifyConditionals",
    "removeDeadCode"
  ]
}

Configuration File (.shcerc.json)

{
  "analysis": {
    "includePatterns": ["src/**/*.ts", "lib/**/*.js"],
    "excludePatterns": ["**/*.test.ts", "**/node_modules/**"],
    "thresholds": {
      "healthScore": 0.7,
      "complexity": 10,
      "maintainability": 60
    }
  },
  "refactoring": {
    "autoApply": false,
    "minConfidence": 0.8,
    "strategies": ["extractFunction", "removeDeadCode"]
  },
  "reporting": {
    "format": "html",
    "outputPath": "./reports"
  }
}

🧪 Testing

SHCE includes comprehensive test suites:

# Run all tests
npm test

# Run specific test suite
npm test -- --grep "AnalysisEngine"

# Run with coverage
npm run test:coverage

🏗️ Architecture

SHCE
├── Core Engines
│   ├── Analysis Engine      # Metrics calculation
│   ├── Decay Predictor     # Structural degradation prediction
│   └── Refactoring Engine  # Safe transformation engine
├── Interfaces
│   ├── VS Code Extension   # Editor integration
│   ├── CLI Tool           # Command-line interface
│   └── GitHub Actions     # CI/CD integration
└── Utilities
    ├── AST Parser         # Code parsing
    ├── Metrics Calculator # Quality metrics
    └── Report Generator   # Output formatting

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development Setup

# Clone repository
git clone https://github.com/your-org/shce.git
cd shce

# Install dependencies
npm install

# Build project
npm run compile

# Run tests
npm test

# Package extension
npm run package

📝 License

MIT License - see LICENSE file for details.

🔗 Links

• Documentation
• VS Code Marketplace
• GitHub Repository
• Issue Tracker

🙏 Acknowledgments

Built with:

• Babel - AST parsing and transformation
• TypeScript - Type-safe development
• VS Code Extension API - Editor integration

📧 Contact

• Email: [email protected]
• Twitter: @shce_dev
• Discord: Join our community

Made with ❤️ by the SHCE Team