Crate kardo_core 

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

Component	Weight	What it measures
Freshness	30%	How recently AI-relevant docs were updated
Configuration	25%	Quality and depth of CLAUDE.md, README, and config files
Integrity	20%	Internal link and reference validity
Agent Setup	15%	Presence of AI agent infrastructure (.claude/, MCP, etc)
Structure	10%	Directory organization, naming, depth

Traffic Light Thresholds

Rating	Range	Label
Green	>= 76%	AI-ready
Yellow	42% - 75%	Review recommended
Red	< 42%	Action needed

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

Module	Description
analysis	Five analyzers: staleness, integrity, config quality, agent setup, structure. Plus AGENTS.md analysis, AI config detection, and cross-config consistency checking.
scoring	Weighted scoring engine, traffic light classification, percentile benchmarks, issue enrichment, and path-to-green planner.
scanner	File discovery with .gitignore support via the ignore crate.
parser	Markdown parsing (headings, links, code blocks, word count) via pulldown-cmark.
git	Git history analysis and doc-code coupling detection via git2.
db	SQLite persistence (WAL mode) for project and application data.
rules	Configurable rules engine (ESLint-like pattern) with YAML custom rules.
config	kardo.toml loading with zero-config defaults and auto-discovery.
fix	Auto-fix engine that scaffolds missing files from templates.
watcher	File system watcher for real-time project monitoring via notify.
llm	Local LLM integration (Ollama backend) for document classification.
embeddings	Embedding generation and semantic search via Ollama (nomic-embed-text).
anonymize	Strips sensitive data (paths, keys, emails) before cloud AI calls.
pro	License management, reverse trial, and feature gating.
workspace	Multi-project workspace management with aggregated scoring.

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:

Flag	Default	Dependencies	Purpose
watcher	yes	notify	Real-time file system monitoring
llm	yes	reqwest, tokio	Local LLM integration (Ollama)
embeddings	yes	reqwest, tokio	Semantic search and embedding generation
tui	no	ratatui, crossterm	Terminal UI rendering

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

Operation	Time	Notes
Score computation	~16 ns	Pre-computed analysis results
Path-to-Green planning	~248 ns	From existing score
Score with floor penalties	~2.1 us	Degraded repo simulation
Score with 50+ issues	~11.3 us	Worst-case scenario

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

Crate	Description
kardo-cli	CLI tool powered by kardo-core with TUI dashboard
kardo-gate	Documentation gate rules engine
@kardo/mcp	MCP server for AI coding agents

License

MIT. See LICENSE for details.

Re-exports

pub use error::KardoError;

pub use error::KardoResult;

Modules

analysis

Stage 4 (ANALYZE): Staleness detection, reference integrity, config quality assessment, agent setup infrastructure, and project structure quality.

analyze

High-level convenience API for quick scoring.

anonymize

Anonymization engine — strips sensitive data before sending to cloud AI.

config

Configuration file support for Kardo.

db

Database layer for Kardo — SQLite with WAL mode.

embeddings

Embedding generation and semantic search via Ollama.

error

Unified error type for kardo-core operations.

fix

Auto-fix engine — scaffolds missing files from templates.

git

Git repository analysis — file history, commit metadata, and code-documentation coupling detection.

llm

Local LLM integration for document classification.

parser

Markdown and document parsing for Kardo.

prelude

Convenience re-exports for common kardo-core types.

pro

Pro features module — licensing, trial management, and feature gating.

rules

Configurable rules engine for Kardo (ESLint-like pattern).

scanner

File discovery and watching for Kardo.

scoring

Stage 5 (SCORE): 5-component AI-Readiness scoring engine.

tui

Terminal UI rendering for scoring results via Ratatui.

watcher

File system watcher for real-time project monitoring.

workspace

Multi-project workspace management.