@rhino-ai/orchard9-thm v2.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

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

Quick Start

# 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.

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.

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.

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.

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.

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.

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).

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).

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:

{
  "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 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

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 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:

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

Programmatic Usage

You can also use TypeScript Health Monitor programmatically:

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: Complete reference of all configuration options
• Troubleshooting Guide: Solutions for common issues
• Frequently Asked Questions: Answers to common questions
• CI/CD Integration: 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:

# 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.

License

MIT