_  ______  ___    _                    _
 | |/ /  _ \|_ _|  / \   __ _  ___ _ __ | |_
 | ' /| |_) || |  / _ \ / _` |/ _ \ '_ \| __|
 | . \|  __/ | | / ___ \ (_| |  __/ | | | |_
 |_|\_\_|  |___/_/   \_\__, |\___|_| |_|\__|
                        |___/

KPI Agent

Analyze any web project and generate a comprehensive quality report with actionable insights.

KPI Agent is a CLI tool and programmatic API that performs deep analysis of your web project across 7 quality dimensions: clean code, architecture, performance, SEO, maintainability, accessibility, and developer experience.

Features

• 7 Quality Dimensions - Clean code, architecture, performance, SEO, maintainability, accessibility, developer experience
• AST-Based Analysis - Uses TypeScript Compiler API (ts-morph) for accurate code analysis
• Beautiful Reports - Generate HTML dashboards, Markdown reports, or JSON data
• Framework Detection - Automatically detects React, Vue, Angular, Next.js, Nuxt, Svelte
• Goal Tracking - Set target scores and get a prioritized roadmap to reach them
• CI/CD Integration - Use as a quality gate with configurable thresholds
• Report Comparison - Track progress over time by comparing reports
• Plugin Architecture - Extensible with custom analyzer plugins
• Configurable - Fine-tune weights, thresholds, and enabled plugins
• Caching - File-based caching for faster re-analysis

Quick Start

# 1. Install
npm install -g kpi-agent

# 2. Analyze your project
kpi-agent analyze .

# 3. View the HTML report
open ./kpi-reports/kpi-report-*.html

Installation

Global (CLI)

npm install -g kpi-agent

Local (Project dependency)

npm install --save-dev kpi-agent

Programmatic API

npm install kpi-agent

Usage

CLI

# Full analysis with defaults
kpi-agent analyze

# Analyze a specific directory
kpi-agent analyze ./my-project

# Custom output directory and formats
kpi-agent analyze -o ./reports -f json,html,md

# Only run specific plugins
kpi-agent analyze --only cleanCode,architecture

# Exclude plugins
kpi-agent analyze --exclude seo,performance

# Set target score
kpi-agent analyze --target 90

# Compare with previous report
kpi-agent analyze --compare ./kpi-reports/previous-report.json

# CI mode (exit code 1 if below threshold)
kpi-agent analyze --ci --threshold 80

# Verbose output
kpi-agent analyze --verbose

# Initialize config file
kpi-agent init

# View history
kpi-agent history

# Compare two reports
kpi-agent diff report1.json report2.json

Programmatic API

import { KPIAgent } from "kpi-agent";

const agent = new KPIAgent({
  target: 90,
  formats: ["json", "html"],
  plugins: {
    cleanCode: { enabled: true, weight: 25 },
    architecture: { enabled: true, weight: 20 },
  },
});

const report = await agent.analyze("./my-project");

console.log(`Score: ${report.overallScore.total}`);
console.log(`Grade: ${report.overallScore.grade.grade}`);

for (const category of report.overallScore.categories) {
  console.log(`${category.category}: ${category.score} (${category.grade.grade})`);
}

CLI Commands

kpi-agent analyze [path]

Run a full analysis on a project.

| Option | Description | Default | |--------|-------------|---------| | -o, --output <path> | Output directory for reports | ./kpi-reports | | -f, --format <formats> | Report formats (json,html,md) | json,html | | --only <plugins> | Run specific plugins only | all | | --exclude <plugins> | Exclude specific plugins | none | | --target <score> | Target score for goal tracking | 100 | | --compare <file> | Compare with previous JSON report | - | | --ci | CI mode: exit code 1 if below threshold | false | | --threshold <score> | Minimum passing score for CI | 70 | | --cache / --no-cache | Enable/disable caching | true | | --verbose | Verbose output | false | | --silent | Only output the report file | false |

kpi-agent init

Create a .kpiagentrc.json configuration file interactively.

kpi-agent history [path]

List past analysis reports from the reports directory.

kpi-agent diff <report1> <report2>

Compare two JSON reports side by side.

Configuration

Create a .kpiagentrc.json in your project root:

{
  "$schema": "./node_modules/kpi-agent/config-schema.json",
  "target": 90,
  "outputDir": "./kpi-reports",
  "formats": ["json", "html"],
  "plugins": {
    "cleanCode": {
      "enabled": true,
      "weight": 20,
      "thresholds": {
        "maxFunctionLength": 30,
        "maxFileLength": 300,
        "maxComplexity": 10,
        "maxDuplication": 5
      }
    },
    "architecture": {
      "enabled": true,
      "weight": 20,
      "layers": {
        "ui": ["src/components", "src/pages", "src/views"],
        "business": ["src/services", "src/usecases"],
        "data": ["src/repositories", "src/api", "src/store"]
      }
    },
    "performance": { "enabled": true, "weight": 20 },
    "seo": { "enabled": true, "weight": 15 },
    "maintainability": { "enabled": true, "weight": 15 },
    "accessibility": { "enabled": true, "weight": 5 },
    "devex": { "enabled": true, "weight": 5 }
  },
  "ignore": ["node_modules", "dist", "build", ".next", ".nuxt", "coverage"],
  "frameworks": "auto"
}

Plugin Development

Create custom analyzer plugins by extending BaseAnalyzer:

import { BaseAnalyzer } from "kpi-agent";
import type { AnalysisContext, Finding, Recommendation, KPICategory } from "kpi-agent";

export default class MyCustomAnalyzer extends BaseAnalyzer {
  name = "my-custom-analyzer";
  category: KPICategory = "cleanCode";
  weight = 10;

  protected async runChecks(context: AnalysisContext) {
    const findings: Finding[] = [];
    const recommendations: Recommendation[] = [];

    // Your custom analysis logic here
    for (const file of context.sourceFiles) {
      // Analyze each file...
    }

    return { findings, recommendations };
  }
}

Grading Scale

| Score | Grade | Label | Color | |-------|-------|-------|-------| | 95-100 | A+ | Excellent | Green | | 90-94 | A | Great | Green | | 85-89 | B+ | Good | Green | | 80-84 | B | Above Average | Yellow | | 70-79 | C | Needs Work | Yellow | | 60-69 | D | Poor | Orange | | < 60 | F | Critical | Red |

Framework Support

| Framework | Auto-Detection | Specialized Checks | |-----------|---------------|-------------------| | React | Yes | JSX analysis, hooks patterns | | Next.js | Yes | SSR/SSG patterns, API routes | | Vue | Yes | SFC analysis, composition API | | Nuxt | Yes | Auto-imports, server routes | | Angular | Yes | Module structure, DI patterns | | Svelte | Yes | Component analysis | | Vanilla JS/TS | Yes | General best practices |

Analysis Categories

Clean Code (Default weight: 20%)

Cyclomatic complexity, function length, file length, naming conventions, dead code, code duplication, magic numbers, console leftovers, TODO tracking, type safety, import organization.

Architecture (Default weight: 20%)

Folder structure, dependency graph analysis, circular dependency detection, layer violations, separation of concerns, dependency freshness, security audit, environment configuration.

Performance (Default weight: 20%)

Bundle size analysis, Lighthouse integration, lazy loading detection, image optimization, font loading strategy.

SEO (Default weight: 15%)

Meta tags, structured data (JSON-LD), sitemap, robots.txt, heading hierarchy, image alt text.

Maintainability (Default weight: 15%)

Test coverage, documentation (JSDoc), README quality, CI/CD configuration, git health, error handling, logging strategy.

Accessibility (Default weight: 5%)

ARIA attributes, color contrast heuristics, keyboard navigation support.

Developer Experience (Default weight: 5%)

Build tool configuration, linter/formatter setup, pre-commit hooks, package.json scripts completeness.

Roadmap

• [ ] VS Code extension for inline KPI feedback
• [ ] GitHub Action for PR quality gates
• [ ] Custom plugin marketplace
• [ ] Historical trend dashboard
• [ ] Team/organization benchmarks
• [ ] AI-powered fix suggestions

Contributing

See CONTRIBUTING.md for guidelines on how to contribute to this project.

License

MIT - see LICENSE file for details.