# kardo-core
**AI-Readiness scoring engine for Git repositories.**
[](https://crates.io/crates/kardo-core)
[](https://docs.rs/kardo-core)
[](https://github.com/kardo-dev/kardo/blob/main/LICENSE)
[](#minimum-supported-rust-version)
[](#)
`kardo-core` is the Rust library behind [Kardo](https://kardo.dev). 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`:
```toml
[dependencies]
kardo-core = "0.5"
```
Run an analysis and compute the score:
```rust,no_run,ignore
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:
```rust,no_run,ignore
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/](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
| 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
| 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
| `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)](https://docs.rs/kardo-core)
- [Architecture Overview](docs/ARCHITECTURE.md)
- [Scoring Methodology](docs/SCORING_METHODOLOGY.md)
- [Integration Guide](docs/INTEGRATION_GUIDE.md) — CI/CD, pre-commit hooks, IDE plugins, MCP
- [FAQ](docs/FAQ.md)
- [Tutorial: Your First Scan](docs/marketing/tutorial-first-scan.md)
- [Changelog](CHANGELOG.md)
- [Examples](examples/)
- [Contributing](CONTRIBUTING.md)
## Community
- [GitHub Issues](https://github.com/kardo-dev/kardo/issues) — bug reports and feature requests
- [GitHub Discussions](https://github.com/kardo-dev/kardo/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:
```toml
[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]
[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:
| `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):
| 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
| [kardo-cli](https://crates.io/crates/kardo-cli) | CLI tool powered by kardo-core with TUI dashboard |
| [kardo-gate](https://crates.io/crates/kardo-gate) | Documentation gate rules engine |
| [@kardo/mcp](https://www.npmjs.com/package/@kardo/mcp) | MCP server for AI coding agents |
## License
MIT. See [LICENSE](https://github.com/kardo-dev/kardo/blob/main/LICENSE) for details.