Topic: behavioral-code-analysis Topic: code-analysis-tool Topic: repository-mining Topic: technical-debt Topic: code-maat

Topic: rust Topic: sarif Topic: clone-detection Topic: hotspot-analysis Topic: developer-tools

License: GPL-3.0-only Rust 1.96+ Clippy: clean

Read the lore of your codebase.

Behind every codebase is a human narrative your linter cannot see: who wrote this, who still understands it, which corners hide tribal knowledge nobody's written down, and where the historical scars are buried. Every commit is a piece of this lore.

CodeLore mines your repository's git history and projects it into 31 behavioral analyses — hotspots, change-coupling, ownership maps, knowledge fragmentation, code health scores, copy-paste clones, live clones (clones ×ばつ Fisher-significant co-change), Leiden community detection on the coupling graph, per-file centrality, knowledge-island bus-factor risk, god-class detection, layered-architecture rule validation, per-module bus factor, pair-programming detection, stale-code surfacing, and more — surfaced as SARIF for your existing CI dashboard. The socio-technical signal your linter cannot see, with the methodological honesty your team can audit.

A Rust drop-in successor to Adam Tornhill's code-maat — every published code-maat analysis is supported under the same --analysis NAME flag, with modern improvements: deterministic tiebreaks, Fisher exact significance gates, SARIF output, persistent cache, PR-mode diffing, and a SQL-queryable fact store. Built on gix (pure-Rust git), DuckDB (embedded analytics), fancy-regex (lookaround support for architectural grouping), and a vendored fork of Mozilla's rust-code-analysis (tree-sitter complexity).

Static analyzers (SonarQube, ESLint, Clippy) read code at a single point in time. CodeLore reads its history, and that history answers questions static tools can't:

• Bus-factor risk — "Which complex hotspots are owned by a single contributor — what happens when they go on leave?"
• Hidden architectural debt — "Which files are implicitly coupled — always modified together — but live in different subsystems?"
• Refactoring ROI — "Which highly complex files are actively changing (refactor!) vs stable (leave alone)?"
• Live clones — "Which copy-pasted blocks keep being edited in lockstep (real debt) vs which are dead patterns nobody touches (noise)?"
• Modernization scope — "Which files do my AI-coding-assistant commits touch most heavily?" (ai_attribution column on every commit; auto-detects Claude / Copilot / Cursor / Aider / Cody / Continue / Codeium / Windsurf / Devin / Tabnine / Amazon Q)

CodeLore focuses on the socio-technical dimension — the legends your codebase tells about itself — so you can focus refactor effort where it actually pays off.

What separates CodeLore from code-maat, CodeScene, and jscpd:

• 🎯 Live-clone ×ばつ co-change intersection. Every clone detector finds copy-pasted blocks. CodeLore intersects clones with Fisher-significant change-coupling — flagging only the clones whose copies actually evolve together. Dead clones (look-alike code nobody touches) are filtered out as noise; live clones (real debt) are surfaced with a combined_score ranking. We're not aware of another OSS tool that ships this intersection.
• 📋 Behavioral SARIF. Findings land natively in SARIF 2.1.0 with three rules — CODELORE-HOTSPOT, CODELORE-CLONE, and CODELORE-LIVE-CLONE. Drop them straight into GitHub Code Scanning, GitLab security dashboards, or Defectdojo and alerts appear inline on pull requests.
• 🔍 Transparency over opaque ML. CodeScene's hotspot ranking is a closed ML model. CodeLore ranks with a published deterministic formula: percentile_rank(revisions) ×ばつ percentile_rank(cognitive_complexity) ×ばつ (100 − code_health) / 10. Every input is emitted alongside the score; anyone can reproduce it.
• 🧾 Provenance manifest. Every run emits a .provenance.json sidecar recording every config knob (auto-derived via canonical Options serialization — adding a new field auto-propagates), version pin, and timestamp. Reproducibility receipt for the run; eliminates the "we got different numbers because we silently used different thresholds" failure mode.
• 💾 SQL-queryable fact store. No proprietary format lock-in. Export the full DuckDB store as Parquet or SQLite and query your git history as a database from the command line.
• ⚡ Persistent cache. Second invocation on the same (repo, HEAD, options) opens read-only in ~10 ms instead of re-walking history — typically a ×ばつ speedup on the dev inner loop depending on repo size, and the foundation of the codelore diff PR-mode subcommand.
• 🔗 Drop-in code-maat compatibility. Every published code-maat analysis is supported under the same --analysis NAME. The --code-maat-compat flag flips internal defaults (min-revs pivot, CSV column headers for summary / code-age / communication / ownership / authors, --min-soc overload) back to legacy semantics for users with dashboards that parse code-maat CSV verbatim — see the migration table below.

Use codelore analyze --analysis NAME for any of these. Code-maat parity is complete; modern additions are marked ★.

In addition to codelore analyze and codelore diff, the CLI exposes:

codelore explain <metric> # formula + citation + SQL source for any metric
codelore check # quality-gate validation against .codelore-thresholds.toml
codelore check --diff base..head # PR-mode quality gate
codelore profile # operational telemetry (version, schema, deps, cache root)
codelore docs # markdown analysis catalogue
codelore notes <base>..<head> # release-notes markdown summary
codelore completions <shell> # bash | zsh | fish | powershell | elvish
codelore schema <row-type> # JSON Schema 2020-12 emit

codelore check writes result=pass|fail + violations=N to $GITHUB_OUTPUT when the env var is set — direct GitHub Actions step-output integration (F-Q4).

Pick whichever fits your machine:

# Homebrew (macOS or Linuxbrew, arm64 or x86_64):
brew install emrecdr/codelore/codelore
# Prebuilt binary via cargo-binstall (any Rust dev environment):
cargo binstall codelore
# From source (Rust 1.96+ toolchain required):
cargo install --git https://github.com/emrecdr/codelore codelore-cli
# From source WITH the optional interactive dashboard emitter
# (`--format spa` — Apache ECharts + d3-hierarchy fetched once at
# build time, SHA-pinned). Requires internet on first build:
cargo install --git https://github.com/emrecdr/codelore codelore-cli --features spa

Or grab a prebuilt archive straight from a GitHub Release — five targets ship per tag (macOS arm64/x86_64, Linux arm64/x86_64-gnu, Windows x86_64-msvc), each with SLSA L3 build provenance attached.

The rest of this README assumes codelore is on your PATH — substitute ./target/release/codelore if you skipped the install step.

# Your first analysis: the top 10 hotspots in any git repo
codelore analyze --analysis hotspots --repo . --min-revs 5 --rows 10

Before the analysis runs, codelore prints a pre-flight banner to stderr (auto-suppressed when piped; suppress explicitly with --no-banner):

────────────────────────────────────────────────────────────────────────
 codelore gix · duckdb
────────────────────────────────────────────────────────────────────────
 Repo: /Users/you/code/your-project
 Branch: main @ a891295
 Analysis: hotspots (min-revs=5, rows=10)
 Status: ✓ ready
────────────────────────────────────────────────────────────────────────

The banner doubles as a fail-fast gate: if the path isn't a git repo, the repo has no commits, or --output points at a directory that doesn't exist, the banner renders Status: ✗ <reason> with a one-line Hint: and codelore exits non-zero — before spending 5–30 seconds on ingest you'd have to abort anyway.

Output (CSV, the default, on stdout — pipeable into other tools):

entity,revisions,cognitive,code-health,hotspot-score
src/auth/session.rs,87,42.00,60.00,9.1837
src/db/migrate.rs,54,28.00,71.20,4.6125
src/api/handlers.rs,38,18.00,80.36,2.4310

• code-health ∈ [60, 100] — higher = healthier (60 is the floor because the cognitive-complexity term contributes at most 40 points of deduction).
• hotspot-score ∈ [0, 10] — higher = more pressing refactor candidate. 9.18 means "near the top of the curve on revisions ×ばつ complexity ×ばつ poor health" — the canonical "on fire" file.

The top row is the file to look at first: high churn ×ばつ high complexity ×ばつ low code health = highest score.

When the analysis completes, codelore prints a footer summary to stderr (same TTY suppression rules):

────────────────────────────────────────────────────────────────────────
 ✓ hotspots completed in 4.3s
────────────────────────────────────────────────────────────────────────

Four commands that build intuition:

1. What does the repo look like?

codelore analyze --analysis summary --repo .

One-page snapshot: commits, files, authors. Confirms you're pointed at the right git history.

2. Where's the technical debt?

codelore analyze --analysis hotspots --repo . --min-revs 5 --rows 10

Top 10 files ranked by hotspot score. Usually 2-3 names jump out as "I've been meaning to refactor that".

3. Who owns the risky code?

codelore analyze --analysis ownership --repo . --rows 10

Files sorted by ownership fragmentation (Fractal Value). High FV = many contributors share the file; low FV = bus-factor risk.

4. Which copy-pasted code is actually hurting you?

codelore analyze --analysis clone-coupling --repo . --format markdown

Live clones — function-level copy-paste families whose copies co-change at Fisher-significant rates. Real code-duplication debt: every change has to be made in N places, every bug has N variants. Dead clones (filtered out) are noise.

Once you've run those four, you have enough signal to triage. From here, the advanced guide covers all 32 analyses, every flag, configuration, CI integration, and tool-stack rationale.

Emit a single self-contained HTML file you can open in any browser, share via Slack, attach to a CI run, or install as a PWA. Runs fully offline — no server, no CDN, no JavaScript bundles to host.

codelore analyze --format spa --output codelore.html --repo .

Fifteen interactive widgets driven by a single embedded JSON blob:

• Codebase at a glance — KPIs: files, commits, contributors, median code-health, complexity peaks, MI band breakdown
• Knowledge islands — files whose primary author has departed and where no other substantial owner exists (no manual ex-developer marking required)
• Hotspots circle-pack — files sized by churn, recoloured across seven behavioural lenses: complexity, code health, tech-debt friction, knowledge map, AI attribution, clones, and knowledge loss under your off-boarding scenario
• Hotspots table + treemap — same data, sortable / filterable / strict-area comparison
• Trends — monthly revision counts for the top-N hotspots
• Multi-metric comparison — parallel coordinates across five behavioural axes, drag-filter on any axis
• Delivery risk — per-commit risk (Kamei JIT-SDP) for the last N commits, with the dominant risk dimension annotated
• Module coupling + Architecture graph — change-coupling chord vs. resolved-import force-graph (agreement = healthy modularity; disagreement = signal worth investigating)
• Change coupling sankey — Fisher-significant file pairs
• Cognitive distribution — boxplot across every file with measured complexity
• Function X-Ray — function-level cognitive complexity sunburst
• Commit activity — GitHub-style calendar heatmap
• File detail drawer — click any file anywhere to slide in a side panel with its full profile

• Tune every chart in place. Depth selectors on the coupling chord / arch graph / sankey; Top-N tabs on Trends / Multi-metric / Delivery risk. Selections survive reload and sync to the URL hash so a pasted link reproduces the exact view your teammate is looking at.
• Simulate off-boarding. Tick departing authors → the hotspot circle-pack recolours, the hotspot table flags affected rows, and the file drawer flags every coupling partner and contributor owned by a departing author. See the bus-factor exposure before it becomes an incident.
• Click any file. The right-side drawer slides in with a 6-axis behavioural radar, hotspot metrics, knowledge-island data, top contributors with +added/-deleted LoC, coupling partners + their authors, top complex functions with line numbers, and clone-group membership. Non-modal — click another row and the content swaps in place.
• Cross-widget highlight. Selecting a file in any widget lights it up across Trends and Multi-metric so its profile reads at a glance across panels.
• Self-explanatory. Every widget has a Learn more disclosure: what it measures, how to read it, what signal to watch for, recommended action, and citation. Hover the ? icons on tabs for one-line explanations.
• Fullscreen any panel. Top-right corner toggle. The hotspots and architecture graphs also have wheel-zoom + drag-pan and a reset button.
• Share the exact view. URL hash carries depth, Top-N, and off-boarding picks. Works on air-gapped CI artefacts too — the link is just a fragment in a file URL.

Signals CodeScene doesn't expose: auto-detected knowledge islands (no manual ex-developer marking), AI-attribution filtering as a hotspot colour mode, clone-detection overlay on the same hotspot view, and auditable per-metric formulas (every number links back to the SQL query that produced it via the provenance sidecar).

The spa Cargo feature gates the visualisation deps. Pre-built binaries (Homebrew, ghcr, GitHub Releases) enable it, so the dashboard works out of the box.

codelore diff origin/main...HEAD \
 --analysis all \
 --format markdown \
 --output - >> "$GITHUB_STEP_SUMMARY"

Four signals per PR, surfaced via SARIF or human-readable Markdown:

• Hotspot deltas — files newly entering the top-N or worsening their score (CODELORE-HOTSPOT SARIF rule)
• Missing co-changes — "you changed auth/login.rs but historically auth/session.rs always changes with it — did you forget?" (CODELORE-MISSING-COCHANGE SARIF rule, the CodeScene-signature signal)
• New clone families — copy-paste debt introduced by the PR (CODELORE-CLONE SARIF rule)
• Live clones — clones whose copies co-change at Fisher-significant rates (CODELORE-LIVE-CLONE SARIF rule)

Quality-gate options:

# Block PRs that promote any file into the top-N hotspots:
codelore diff origin/main...HEAD --fail-on rank-entrant
# Block PRs that worsen an existing hotspot:
codelore diff origin/main...HEAD --fail-on score-increase
# Block on any of the four signals:
codelore diff origin/main...HEAD --fail-on any

See examples/.github/workflows/codelore-pr.yml for the full template with the critical configuration gotchas (fetch-depth: 0, three-dot merge-base, SARIF upload permissions).

Cache the base-rev analysis with --base-cache PATH to halve dual-analysis cost across PRs that share the same base SHA.

For monorepos, treat groups of files as logical components. Drop a groups.txt at the repo root:

# CodeLore architectural grouping. One rule per line; `<path-or-regex> => <group-name>`.
src/auth => Auth
src/db => DB
src/api => API
^src\/.*\/tests\/.*\.rs$ => Tests
^src\/((?!.*test.*).).*$ => Production

Run with --group-file groups.txt:

codelore analyze --group-file groups.txt --analysis revisions

Analyses then operate at the group level — Auth, DB, etc. — instead of raw paths. Plain-text LHS is matched as a prefix (anchored + slash-bound); regex LHS (starting with ^) supports full lookaround via fancy-regex (code-maat's own test fixtures use this).

Default: non-strict (unmapped paths keep their raw names; safer than silent drop). Pass --strict-grouping to drop unmapped paths instead (code-maat's behavior).

 Your git repo
 │ [gix walks history]
 ▼
 ┌─────────────────────┐
 │ codelore-lib │
 │ ┌──────────────┐ │ tree-sitter parses each Tier-1 source
 │ │ codelore-rca │ │ file → cyclomatic, cognitive, Halstead,
 │ └──────────────┘ │ MI metrics, AST structural hash
 └────────┬────────────┘
 │ Stream<CommitEvent>
 ▼ + Kamei 14-feature enrichment
 ┌─────────────────────┐
 │ DuckDB Fact Store │ commits · changes · hunks · entities ·
 │ │ complexity_metrics · clones ·
 │ │ author_aliases · provenance
 └────────┬────────────┘
 │ SQL queries (bind-parameterized) + Rust orchestrators
 ▼
 ┌─────────────────────┐
 │ 23 Analyses │ → 7 output formats (CSV/JSON/SARIF/
 │ │ Markdown/Parquet/SQLite/SPA*)
 │ │ → persistent cache (×ばつ speedup)
 │ │ → provenance.json sidecar
 │ │
 │ │ * SPA = single-HTML interactive
 │ │ dashboard (opt-in `spa` feature)
 └─────────────────────┘

Every commit becomes a CommitEvent projected onto a DuckDB fact store. The 32 analyses are SQL queries over that store plus a thin Rust orchestrator each. Outputs flow through eight format emitters. Every run is cached and audit-trail-stamped with a provenance sidecar.

For deeper architecture, see the design specification (~1100 lines, covers every threshold and identity rule).

What we deliberately don't ship: no async runtime, no libgit2 binding, no LLM-based scoring, no web UI, no non-git VCS support (git-only by design — see docs/github-topics.md and the project memory for the rationale). See the advanced guide for the long version.

Release-ready alpha. 32 analyses ×ばつ 8 output formats ×ばつ codelore diff PR-mode ×ばつ codelore check quality gate ×ばつ 4 SARIF rules. Full test suite (codelore-lib unit + integration, codelore-cli integration, differential GixRepo vs GitCliRepo cross-walker parity, headless-browser SPA smoke) passes on Rust 1.96.0 across Linux, macOS, and Windows; clippy -D warnings, rustfmt --check, and cargo deny check all gate every push. Each tagged release ships prebuilt binaries for five targets (macOS arm64/x86_64, Linux arm64/x86_64-gnu, Windows x86_64-msvc), each with SLSA L3 build provenance attached, a distroless OCI container at ghcr.io/emrecdr/codelore, an auto-regenerated formula in the emrecdr/codelore Homebrew tap, and a cargo binstall-compatible asset layout — all produced by .github/workflows/release.yml on every v* tag push, gated by the protect-release-tags ruleset that requires green CI on the target commit before the tag is accepted.

This session's deliverables (3 sprints + GitHub tags + versioning):

Known limitations (the honest list, validated against the current codebase):

• Code-maat sliding-window --temporal-period N is intentionally not emulated under --code-maat-compat — the modern --time-bucket DAY|WEEK|MONTH (non-overlapping buckets, no commit-duplication artifact) is the recommended surface and what ships; the legacy sliding-window-with-duplication is an opt-in future-work item if migration users hit it

Full backlog: docs/roadmap-v1.x-and-beyond.md.

CodeLore is a drop-in successor. Every published code-maat analysis works under the same --analysis NAME:

# code-maat (Clojure, JVM, log-file based)
java -jar code-maat.jar -l logfile.log -c git -a coupling
# CodeLore (Rust, native, direct git read — no log preprocessing)
codelore analyze --analysis coupling --repo /path/to/repo

CodeLore's default surface reflects modern stack capabilities; code-maat compatibility is opt-in via --code-maat-compat. The divergences below are intentional — see the Modernise, don't migrate framing in docs/reports/deep_analysis_report.md.

Modern CLI design favours long flags; CodeLore does not restore code-maat's 2013-era cryptic shorts. The one-time script rewrite:

The technical category is "behavioral code analysis." The metaphor is reading the legends a codebase tells about itself.

Every commit is tribal lore: who knew this code, who burned themselves on it, where the workarounds calcified, which functions are quietly cloned across a dozen files because everyone fixed the same bug in their corner. The word lore captures that human narrative more honestly than "metrics" or "telemetry" — it acknowledges that the most important signal about your codebase isn't in the code, it's in the people who wrote it.

CodeLore surfaces that lore as data you can act on, without pretending the methodology is more scientific than it is. Every formula is published, every threshold is documented, and every run leaves a provenance receipt. Read the lore. Act on what it tells you.

GPL-3.0-only. Bundles a vendored fork of Mozilla's rust-code-analysis under MPL-2.0 — see crates/codelore-rca/LICENSE-MPL and crates/codelore-rca/UPSTREAM.md for vendoring history.

CodeLore stands on the shoulders of:

• Adam Tornhill for code-maat and the books Your Code as a Crime Scene and Software Design X-Rays — every behavioral analysis we ship was named, validated, or hinted at in his work.
• The gitoxide team for proving pure-Rust git reads can outperform libgit2.
• DuckDB Labs for shipping an embeddable columnar SQL engine that just works.
• The tree-sitter project + Mozilla's rust-code-analysis for cross-language AST parsing.