Module knowledge_islands 

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.

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