Skip to main content

Module knowledge_islands

codelore_lib::analyses

Module knowledge_islands 

Expand description

knowledge-islands analysis — automatic bus-factor / knowledge-loss detection per file.

§What this signal tells you

For each currently-live file, surfaces the highest-risk knowledge-loss cases: files where the primary author (by LoC added) has effectively departed (--departed-threshold-days, default 90) AND no other contributor owns a substantial share (default 10%). These are the files that would become unmaintainable if you needed to ship a fix tomorrow — the people who could fix them have already left.

§Why this is CodeLore’s strategic differentiator

Industry behavioural-code-analysis tools have two of the three ingredients for this signal:

  • CodeScene’s Knowledge Distribution + Bus Factor: identifies primary owners but requires you to manually mark each “Ex-Developer” in a list. Maintaining that list is organisational labour — and dashboards stay wrong until someone updates them after every offboard.
  • code-maat: has none of the three (no departure detection, no bus-factor analysis).
  • GitHub Insights: shows contributor counts but no risk modeling.

CodeLore ships all three automatically:

  1. Primary-author detection (existing ownership analysis logic — author with max LoC added per file).
  2. Departed-author detection (new — commits.canonical_author grouped by MAX(commits.date) falloff > --departed-threshold-days).
  3. Substantial-other-owner check (new — n_substantial_others = count of authors with ≥ 10% LoC share on the file, excluding the main author).

§Output columns (modern default)

  • entity — the file path (or canonical-lineage entity under --use-canonical-lineage).
  • main_author — author with max LoC added on the file (alphabetical-first tiebreak; deterministic).
  • ownership_pct — main_author LoC share of the file (0–100, two decimals).
  • days_since_main_active — days since main_author’s most-recent commit anywhere in the repo (not just on this file).
  • last_main_author_commit — calendar date (YYYY-MM-DD) of that most-recent commit.
  • n_substantial_others — count of other authors with ≥ 10% LoC share on this file. Zero is the actionable signal.
  • total_loc — total LoC across all (non-bot) authors on this path, the ownership_pct denominator. Lets a consumer judge whether e.g. ownership_pct: 100.0 comes from a thin sample.

Sort: ownership_pct DESC, days_since_main_active DESC, entity ASC. Highest-concentration-then-longest-departed first — exactly the triage order a tech lead wants.

§Practitioner heuristics

  • ownership_pct > 80 + n_substantial_others = 0 + is_departed = true: red flag. Find someone to learn this file BEFORE you need to ship a fix.
  • ownership_pct < 50: ownership is genuinely diffuse; bus factor is healthy regardless of any one departure.
  • days_since_main_active between 60 and 90: gray zone. May be sabbatical / between projects rather than permanent departure. Lower --departed-threshold-days to see these flagged.

Research basis: see docs/research-foundations.md entry “knowledge-islands” (Bird et al., FSE 2011 — original n-authors risk indicator; Avelino et al., SANER 2016 — Truck Factor estimation; Cosentino et al., CHASE 2015 — bus-factor measurement; CodeScene — productisation reference with the modernise-don’t-migrate improvement of automatic departure detection).

Structs§

KnowledgeIslandRow
OwnerActivity
Un-thresholded per-path owner-activity snapshot — the same ownership/activity primitive behind KnowledgeIslandRow, but returned for every requested path regardless of how recently the main author committed. Callers (e.g. the agent-loop pre-write briefing) decide what counts as “departed” by comparing days_since_main_active against their own threshold.

Functions§

count_live_files
Count files present at HEAD — the live-tree prevalence denominator.
owner_activity_for_paths
Batched, un-thresholded owner-activity lookup for an arbitrary set of paths: the same ownership/activity primitive run_knowledge_islands computes internally, but returned for every path with LoC-attributable ownership — not just the ones already past departed_threshold_days. The caller (e.g. a pre-write briefing) compares days_since_main_active to its own threshold.
run_knowledge_islands