npm package: @rhino-ai/orchard9-thm
Description: A strongly opinionated tool to monitor the health of TypeScript projects
Latest version: 2.2.4

# TypeScript Health Monitor

A strongly opinionated tool to monitor the health of TypeScript projects.

## Features

- ✅ **Type Checking**: Continuous TypeScript type checking
- 🧹 **Linting**: ESLint with recommended TypeScript rules
- 💅 **Formatting**: Prettier code formatting
- 🧪 **Testing**: Jest test execution and reporting
- 📊 **Coverage**: Track test coverage metrics
- 🔍 **Unused Code Detection**: Find unused exports, dependencies, and files
- 🏗️ **Build Verification**: Ensure your project can build successfully
- 📈 **Trend Analysis**: Track metrics over time
- 🔔 **Notifications**: Get alerts when health metrics change
- 📝 **Reporting**: Generate health reports in multiple formats (HTML, Markdown, JSON, YAML)

## Installation

```bash
npm install -g @rhino-ai/orchard9-thm
```

## Quick Start

```bash
# Navigate to your TypeScript project
cd your-typescript-project

# Initialize health monitoring
ts-health init

# Start monitoring in watch mode
ts-health watch

# Generate a one-time health report
ts-health report

# Fix issues automatically
ts-health fix
```

## Commands

### `ts-health init`

Initialize health monitoring configuration for a project.

```bash
ts-health init [options]
```

Options:

- `--config <path>`: Path to config file (default: .ts-health.json)
- `--force`: Overwrite existing configuration
- `--preset <n>`: Use a specific preset (1: minimal, 2: standard, 3: strict)
- `--no-scripts`: Don't add npm scripts to package.json
- `--non-interactive`: Skip interactive prompts

### `ts-health check`

Run all health checks once and display results.

```bash
ts-health check [options]
```

Options:

- `--config <path>`: Path to config file
- `--only <checks>`: Run only specific checks (comma-separated: type-check,lint,format,test,coverage,unused-code,build)
- `--json`: Output results as JSON
- `--silent`: Suppress console output
- `--verbose`: Show detailed output

### `ts-health fix`

Automatically fix issues that can be auto-fixed.

```bash
ts-health fix [options]
```

Options:

- `--config <path>`: Path to config file
- `--types <checks>`: Fix only specific checks (comma-separated)
- `--dry-run`: Show what would be fixed without making changes
- `--verbose`: Show detailed output

### `ts-health watch`

Watch project for changes and run health checks continuously.

```bash
ts-health watch [options]
```

Options:

- `--config <path>`: Path to config file
- `--only <checks>`: Watch only specific checks
- `--auto-fix`: Automatically fix issues when changes are detected
- `--interval <seconds>`: Check interval in seconds (default: 60)

### `ts-health report`

Generate detailed health reports in various formats.

```bash
ts-health report [options]
```

Options:

- `--config <path>`: Path to config file
- `--format <format>`: Report format (html, markdown, json, yaml, console)
- `--output <path>`: Output file path
- `--types <checks>`: Include only specific checks
- `--verbose`: Show detailed output

### `ts-health clean`

Detect and clean unused code from the project.

```bash
ts-health clean [options]
```

Options:

- `--config <path>`: Path to config file
- `--dry-run`: Show what would be removed without making changes
- `--aggressive`: Enable aggressive unused code detection
- `--entrypoints <paths>`: Specify entrypoint files (comma-separated)
- `--verbose`: Show detailed output

### `ts-health pre-commit`

Run health checks before committing (designed for Git hooks).

```bash
ts-health pre-commit [options]
```

Options:

- `--config <path>`: Path to config file
- `--format <format>`: Report format if --report is used
- `--output <path>`: Output file path for report
- `--report`: Generate a report after checks
- `--types <checks>`: Run only specific checks

### `ts-health pre-commit-fix-all`

Run fix, clean, and report operations in a single command (for Git hooks).

```bash
ts-health pre-commit-fix-all [options]
```

Options:

- `--config <path>`: Path to config file
- `--format <format>`: Report format
- `--output <path>`: Output file path for report
- `--dry-run`: Show what would be fixed/cleaned without making changes
- `--aggressive`: Enable aggressive unused code detection
- `--entrypoints <paths>`: Specify entrypoint files for unused code detection

## Configuration

Create a `.ts-health.json` file in your project root:

```json
{
  "extends": "preset:standard",
  "checks": {
    "typeCheck": true,
    "lint": true,
    "format": true,
    "test": true,
    "coverage": true,
    "unusedCode": true,
    "build": true
  },
  "thresholds": {
    "coverage": {
      "min": 50,
      "good": 70,
      "excellent": 90,
      "metrics": {
        "statements": { "min": 50, "good": 70, "excellent": 90 },
        "branches": { "min": 50, "good": 70, "excellent": 90 },
        "functions": { "min": 50, "good": 70, "excellent": 90 },
        "lines": { "min": 50, "good": 70, "excellent": 90 }
      }
    },
    "unusedCode": 5,
    "buildTime": 60,
    "healthScore": {
      "warning": 70,
      "critical": 50
    }
  },
  "ignore": ["node_modules", "dist", "coverage"],
  "exclusions": {
    "format": ["CHANGELOG.md"],
    "generatedFiles": ["CHANGELOG.md", "**/generated/**"]
  },
  "smartDetection": {
    "enabled": true,
    "indicators": ["@generated", "DO NOT EDIT", "AUTO-GENERATED"]
  },
  "notifications": {
    "slack": false,
    "email": false
  },
  "toolPaths": {
    "eslint": "node_modules/.bin/eslint",
    "jest": "node_modules/.bin/jest",
    "prettier": "node_modules/.bin/prettier"
  },
  "watchMode": {
    "autoFix": false,
    "interval": 60,
    "fileTypes": [".ts", ".tsx", ".js", ".jsx", ".json"]
  },
  "fileTypes": {
    "typeCheck": ["ts", "tsx"],
    "lint": ["ts", "tsx", "js", "jsx"],
    "format": ["ts", "tsx", "js", "jsx", "json", "md", "yml", "yaml"],
    "unusedCode": ["ts", "tsx", "js", "jsx"]
  },
  "duplicateCodeSettings": {
    "blockSize": 5,
    "minLength": 50,
    "maxBlocks": 100,
    "threshold": 2
  },
  "coverageConfig": {
    "tool": "jest",
    "reportPath": "coverage",
    "summaryPath": "coverage/coverage-summary.json",
    "exclude": ["**/*.test.*", "**/__tests__/**"],
    "weightInHealthScore": 25,
    "requireForPerfectScore": true,
    "minimumCoverageScore": 70
  },
  "checkWeights": {
    "typeCheck": 25,
    "lint": 20,
    "format": 10,
    "test": 15,
    "coverage": 15,
    "unusedCode": 10,
    "build": 5
  }
}
```

### Configuration Options Overview

- **Check Enablement**: Enable/disable specific health checks
- **Thresholds**: Define pass/fail criteria for checks
- **Path Settings**: Specify custom paths for tools and files
- **Exclusions**: Pattern-based exclusions for checks
- **Smart Detection**: Auto-detection of generated files
- **File Types**: Extensions to include in each check
- **Watch Mode**: Settings for continuous monitoring
- **Notifications**: Channels for health status alerts
- **Health Score Weights**: Importance of each check in the overall score
- **Inheritance**: Extend from base configurations

See the [Configuration Reference](./docs/configuration-reference.md) for complete documentation.

## Report Formats

TypeScript Health Monitor can generate reports in five different formats:

- **Console**: Terminal-friendly output with ANSI colors (`--format console`)
- **HTML**: Interactive HTML report with styling and visualization (`--format html`)
- **Markdown**: Clean, readable documentation in Markdown (`--format markdown`)
- **JSON**: Structured data for programmatic consumption (`--format json`)
- **YAML**: Structured configuration-friendly format (`--format yaml`)

All reports include:

- Project health score (0-100)
- Health status (healthy, warning, critical)
- Summary of check results
- Detailed issue listings with severity and location
- Coverage metrics (when available)
- Timestamp and project identification

## Health Checks

### Type Check

Verifies TypeScript type safety across the codebase using the TypeScript compiler.

### Lint

Verifies code quality and style using ESLint rules. Supports auto-fixing capabilities.

### Format

Verifies code formatting according to Prettier rules. All formatting issues can be auto-fixed.

### Test

Runs unit tests using Jest to verify code correctness. Reports test failures as issues.

### Coverage

Analyzes test coverage to ensure adequate code testing. Checks coverage against configurable thresholds.

### Unused Code

Analyzes the codebase for unused exports, imports, and declarations. Checks unused code percentage against a threshold.

### Build

Verifies the project build process compiles successfully. Monitors build time and reports if it exceeds threshold.

## CI/CD Integration

TypeScript Health Monitor can be integrated into CI/CD pipelines:

### GitHub Actions

```yaml
steps:
  - uses: actions/checkout@v3
  - uses: actions/setup-node@v3
    with:
      node-version: '16'
  - run: npm install
  - run: npx ts-health check
  - run: npx ts-health report --format markdown --output health-report.md
```

Examples for other CI platforms are available in the [examples/ci-cd](./examples/ci-cd/) directory.

## Exit Codes

- **0**: All checks passed
- **1**: Fatal error occurred
- **2**: One or more checks failed
- **3**: CLI argument error

## Additional Tools

### Git Hooks Integration

Add to your package.json:

```json
{
  "husky": {
    "hooks": {
      "pre-commit": "ts-health pre-commit",
      "pre-push": "ts-health check"
    }
  }
}
```

### Programmatic Usage

You can also use TypeScript Health Monitor programmatically:

```typescript
import { runChecks, generateReport } from '@rhino-ai/orchard9-thm';

async function checkHealth() {
  const results = await runChecks({ only: ['typeCheck', 'lint'] });
  console.log(`Health Score: ${results.healthScore}`);

  if (results.status === 'healthy') {
    console.log('All checks passed!');
  }
}
```

## Requirements

- Node.js >= 14
- TypeScript project

## Documentation

- [Configuration Reference](./docs/configuration-reference.md): Complete reference of all configuration options
- [Troubleshooting Guide](./docs/troubleshooting.md): Solutions for common issues
- [Frequently Asked Questions](./docs/faq.md): Answers to common questions
- [CI/CD Integration](./examples/ci-cd/README.md): Examples for integrating with CI/CD platforms

## AI-Driven Development

TypeScript Health Monitor is maintained through an AI-only development workflow. The entire development process, from planning to implementation and publishing, is managed by AI systems. This approach serves as a demonstration of autonomous software development capabilities.

### How It Works

1. Tasks are defined in markdown files in the `docs/` directory (e.g., `release-0.1.3-tasks.md`)
2. AI systems read these tasks and implement the changes
3. Health checks are run to verify code quality
4. Changes are automatically published when ready

### Automated Publishing

Non-interactive publishing for automated workflows:

```bash
# Publish a patch release automatically
npm run publish-lib:auto

# Publish a minor release
npm run publish-lib:auto-minor

# Publish a major release
npm run publish-lib:auto-major

# Test the publishing process without making changes
npm run publish-lib:dry-run
```

For more details on the AI-driven development process, see [CONTRIBUTING.md](./CONTRIBUTING.md).

## License

MIT