kardo-core

AI-Readiness scoring engine for Git repositories.

kardo-core is the Rust library behind Kardo. It analyzes Git repositories for AI-readiness — how well a codebase is prepared for LLM-powered coding agents — and produces a calibrated 0-100 score with a traffic light rating. The scoring model was calibrated against expert assessments on 84 real-world repositories.

Key Features

• 5-component weighted scoring — Freshness, Configuration, Integrity, Agent Setup, Structure
• Traffic light classification — Green (AI-ready), Yellow (review recommended), Red (action needed)
• Calibrated on 84 repositories — thresholds tuned against expert assessments (r=0.828)
• Path-to-Green planner — prioritized fix steps sorted by efficiency (score delta per minute)
• Issue detection with priority — severity, fix type, effort estimate, and score delta for every issue
• Zero-config defaults — works out of the box; optional kardo.toml for customization
• Custom rules — YAML-based plugin API for organization-specific checks

Quick Start

Add to your Cargo.toml:

[dependencies]
kardo-core = "0.5"

Run an analysis and compute the score:

use kardo_core::analysis::{
    StalenessAnalyzer, IntegrityAnalyzer,
    ConfigQualityAnalyzer, AgentSetupAnalyzer, StructureAnalyzer,
};
use kardo_core::scoring::engine::ScoringEngine;
use std::path::Path;

let root = Path::new(".");

// Run the five analyzers
let freshness    = StalenessAnalyzer::analyze(root);
let integrity    = IntegrityAnalyzer::analyze(root);
let config       = ConfigQualityAnalyzer::analyze(root);
let agent_setup  = AgentSetupAnalyzer::analyze(root);
let structure    = StructureAnalyzer::analyze(root);

// Compute the overall score
let score = ScoringEngine::score(
    &freshness, &integrity, &config, &agent_setup, &structure,
);

println!("Score: {}/100 [{}]", (score.total * 100.0) as u32, score.traffic_light.label());
println!("Components:");
println!("  Freshness:     {:.0}%", score.components.freshness * 100.0);
println!("  Configuration: {:.0}%", score.components.configuration * 100.0);
println!("  Integrity:     {:.0}%", score.components.integrity * 100.0);
println!("  Agent Setup:   {:.0}%", score.components.agent_setup * 100.0);
println!("  Structure:     {:.0}%", score.components.structure * 100.0);

// List top issues
for issue in score.issues.iter().take(3) {
    println!("[{:?}] {} (fix: {:?}, ~{} min)",
        issue.severity, issue.title, issue.fix_type,
        issue.effort_minutes.unwrap_or(0));
}

// Path-to-Green plan
let plan = ScoringEngine::path_to_green(&score);
if !plan.reachable {
    println!("Green not reachable with automated fixes alone.");
} else {
    println!("Path to Green: {} steps, ~{} min total",
        plan.steps.len(), plan.total_effort_minutes);
}

One-Line API

For the simplest usage, use the convenience function:

use kardo_core::analyze::score_project;

let score = score_project(".").unwrap();
println!("{}/100 [{}]", score.score_percent(), score.traffic_light);

if score.is_green() {
    println!("Your repo is AI-ready!");
} else {
    let plan = kardo_core::scoring::ScoringEngine::path_to_green(&score);
    for step in plan.steps.iter().take(3) {
        println!("  {} (+{:.1} pts)", step.title, step.score_delta);
    }
}

See examples/ for more: quick_scan, json_output, basic_score, path_to_green, custom_rules.

Scoring Model

The overall score is a weighted average of five components, with floor penalties applied when any component falls critically low.

Component Weights

Traffic Light Thresholds

Floor Penalties

• If any component scores zero, the total is capped at 20% (Red).
• If any component scores below 20%, a dynamic cap (45%-65%) is applied based on the number and severity of low components.
• A bonus (up to +8 points) is awarded when all components exceed 85%, lifting the theoretical ceiling above the raw weighted average.

Module Overview

Documentation

• API Reference (docs.rs)
• Architecture Overview
• Scoring Methodology
• Integration Guide — CI/CD, pre-commit hooks, IDE plugins, MCP
• FAQ
• Tutorial: Your First Scan
• Changelog
• Examples
• Contributing

Community

• GitHub Issues — bug reports and feature requests
• GitHub Discussions — questions and ideas

Configuration

Kardo works with zero configuration. Optionally, create a kardo.toml at your project root to customize thresholds, exclude patterns, toggle checks, and configure CI behavior:

[thresholds]
fail_below = 70.0       # CI fails below this score (0 = disabled)
regression_limit = 5.0   # Max allowed regression between scans

[exclude]
patterns = ["vendor/**", "*.generated.md"]

[checks]
freshness = true
configuration = true
integrity = true
agent_setup = true
structure = true

[output]
format = "summary"       # "summary" | "detailed" | "json"

[ci]
enabled = true
pr_comment = true

[custom_rules]
enabled = true
path = ".kardo/rules.yml"
max_deduction = 20.0     # Max score penalty from custom rules

Config discovery order: CLI flag, KARDO_CONFIG env var, walk up to .git root, then built-in defaults.

Feature Flags

Optional capabilities are gated behind feature flags:

Compile with minimal features: cargo add kardo-core --no-default-features

Performance

The scoring engine is designed for speed. Benchmark results (Apple M-series, Criterion):

Total wall-clock time for a full repository scan is typically 1-5 seconds, dominated by file I/O and Git history analysis. Run benchmarks locally with cargo bench -p kardo-core.

Minimum Supported Rust Version

The MSRV is 1.74. This is validated in CI and will only be raised in minor version bumps with prior notice.

Related Crates

License

MIT. See LICENSE for details.