ut-priority-scorer

AI-friendly Unit Test priority scoring system based on layered architecture

🎯 Features

• Layered Architecture: Scores based on code layer (Foundation, Business Logic, State Management, UI)
• AI-Optimized: Designed for AI-powered test generation workflows
• Multiple Metrics: Combines testability, complexity, dependency count, and more
• Flexible Configuration: JSON-based config with presets for different project types
• CLI & Programmatic API: Use as a command-line tool or integrate into your workflow
• Rich Reports: Generates Markdown and CSV reports with detailed scoring

📦 Installation

Global Installation (CLI)

npm install -g ut-priority-scorer

Project Installation

npm install --save-dev ut-priority-scorer

🚀 Quick Start

1. Initialize Configuration

ut-score init

This creates ut_scoring_config.json with default settings.

2. Scan and Score

ut-score scan

This will:

1. Scan your codebase for testable targets
2. Analyze Git history for error signals
3. Calculate priority scores
4. Generate reports in reports/

3. View Report

# View complete report
cat reports/ut_scores.md

# View P0 targets only
grep "| P0 |" reports/ut_scores.md

# Export P0 targets to file
grep "| P0 |" reports/ut_scores.md | awk -F'|' '{print $2}' > p0_targets.txt

📖 CLI Commands

ut-score init

Initialize UT scoring configuration.

ut-score init [options]

Options:
  -p, --preset <type>   Use preset config (default)
  -o, --output <path>   Output config file path (default: ut_scoring_config.json)

ut-score scan

Scan code and generate UT priority scoring report.

ut-score scan [options]

Options:
  -c, --config <path>   Config file path (default: ut_scoring_config.json)
  -o, --output <dir>    Output directory (default: reports)
  --skip-git            Skip Git signals generation

Output Files:

• reports/targets.json - List of all scanned targets
• reports/git_signals.json - Git analysis data
• reports/ut_scores.md - Priority scoring report (Markdown)
• reports/ut_scores.csv - Priority scoring report (CSV)

⚙️ Configuration

Basic Configuration

{
  "scoringMode": "layered",
  "layers": {
    "foundation": {
      "name": "Foundation (基础工具层)",
      "patterns": ["utils/**", "helpers/**", "constants/**"],
      "weights": {
        "testability": 0.50,
        "dependencyCount": 0.30,
        "complexity": 0.20
      },
      "thresholds": {
        "P0": 7.5,
        "P1": 6.0,
        "P2": 4.0
      }
    }
  }
}

Presets

• default: Balanced scoring for general projects
• react: Optimized for React applications
• node: Optimized for Node.js projects

📊 Priority Levels

| Priority | Score Range | Description | Action | |----------|-------------|-------------|--------| | P0 | ≥7.5 | Must test | Generate immediately with AI | | P1 | 6.0-7.4 | High priority | Batch generate | | P2 | 4.0-5.9 | Medium priority | Generate with careful review | | P3 | <4.0 | Low priority | Optional coverage |

🏗️ Architecture

Layered Scoring System

1. Foundation Layer: Utils, helpers, constants

   • High testability weight (50%)
   • Focus on pure functions

2. Business Logic Layer: Services, APIs, data processing

   • Balanced metrics
   • Critical for correctness

3. State Management Layer: Stores, contexts, reducers

   • Error risk weight emphasized

4. UI Components Layer: React components, views

   • Complexity and error risk balanced

🔧 Programmatic Usage

If you need to integrate into your Node.js workflow:

import { exec } from 'child_process'
import { promisify } from 'util'

const execAsync = promisify(exec)

// Run scoring workflow
const { stdout } = await execAsync('ut-score scan')
console.log(stdout)

Recommended: Use the CLI directly for simplicity.

🤖 AI Integration

This tool is designed for AI-powered test generation workflows:

1. Run scoring to get prioritized target list

   ut-score scan

2. Extract P0 targets

   grep "| P0 |" reports/ut_scores.md | awk -F'|' '{print $2}' > p0_targets.txt

3. Feed to AI (e.g., ChatGPT, Claude) to generate tests

   Generate unit tests for these P0 priority functions:
   [paste content from p0_targets.txt]
      
   Use Vitest framework and aim for 100% coverage.

4. Iterate through P1, P2 as needed

📈 Metrics Explained

Testability (50% weight in Foundation layer)

• Pure functions: 10/10
• Simple mocks: 8-9/10
• Complex dependencies: 4-6/10

Dependency Count (30% weight in Foundation layer)

• ≥10 modules depend on it: 10/10
• 5-9 modules: 10/10
• 3-4 modules: 9/10
• 1-2 modules: 7/10
• Not referenced: 5/10

Complexity (20% weight in Foundation layer)

• Cyclomatic complexity: 11-15: 10/10
• Cognitive complexity from ESLint
• Adjustments for nesting depth, branch count

🛠️ Development

Project Structure

ut-priority-scorer/
├── bin/
│   └── ut-score.js           # CLI entry point
├── lib/
│   ├── index.js              # Main exports
│   ├── gen-targets.mjs       # Target generation
│   ├── gen-git-signals.mjs   # Git analysis
│   └── score-ut.mjs          # Scoring engine
├── templates/
│   ├── default.config.json   # Default preset
│   ├── react.config.json     # React preset
│   └── node.config.json      # Node.js preset
└── docs/
    ├── workflow.md           # Detailed workflow
    └── architecture.md       # Architecture design

📝 Examples

Example: Scoring a React Project

# Initialize with default config
ut-score init

# Customize config if needed
vim ut_scoring_config.json

# Run scoring
ut-score scan

# View P0 targets
grep "| P0 |" reports/ut_scores.md

Example: npm Scripts Integration

Add to your package.json:

{
  "scripts": {
    "test:priority": "ut-score scan",
    "test:p0": "grep '| P0 |' reports/ut_scores.md"
  }
}

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines.

📄 License

MIT © YuhengZhou

🔗 Links

• GitHub Repository
• npm Package
• Documentation
• Issue Tracker

💬 Support

• GitHub Issues: Report bugs
• Documentation: Read the docs