Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
/**
* The map's inspector: a cursor over the files the turn lit, in a fixed order
* (the edits, then the files Claude opened, then the edit's other importers, then
* files a Repowise reply named), and what one of them is: why it is lit and
* what the index already told Lens about it. Nothing here asks for more. Pure.
*/
import type { Lit } from "../views/overlay";
import { pathKey, type FlowState } from "./flow";
import type { FileContext } from "./session";
import type { Story } from "./story";
/** What Lens already knows of a file, from lookups it made anyway. */
export interface Knows {
/** The file's card (get_context), when the spinner fetched it. */
context: FileContext | null;
/** Tests that reach it (the edit's blast radius), when known. */
tests: { total: number; basis: "measured" | "inferred" } | null;
/** The Repowise tool whose reply named it, when one did. */
namedBy: string | null;
}
export const KNOWS_NOTHING: Knows = { context: null, tests: null, namedBy: null };
const key = (p: string): string => p.toLowerCase();
/** The lit files in cursor order, each once. */
export function litPaths(lit: Lit): string[] {
const edits = [...lit.edits].reverse();
const order = [...edits, ...lit.reads, ...lit.importers, ...lit.named];
const seen = new Set<string>();
return order.filter((p) => {
if (seen.has(key(p))) return false;
seen.add(key(p));
return true;
});
}
/** The next (`by` 1) or previous (-1) lit file after `current`, wrapping; the first or last when `current` is not lit. */
export function step(paths: readonly string[], current: string | null, by: 1 | -1): string | null {
if (paths.length === 0) return null;
const at = current === null ? -1 : paths.findIndex((p) => key(p) === key(current));
if (at === -1) return (by === 1 ? paths[0] : paths.at(-1)) ?? null;
return paths[(at + by + paths.length) % paths.length] ?? null;
}
/** Why a file is lit, as facts the copy words: edited (with its size), opened, an importer of the edit, named. */
export interface Why {
edited: { lines: Story["edited"][number]["lines"] } | null;
opened: boolean;
imports: string | null;
namedBy: string | null;
}
const nameOf = (p: string): string => p.slice(p.lastIndexOf("/") + 1);
const has = (paths: readonly string[], p: string): boolean => paths.some((x) => key(x) === key(p));
export function whyLit(path: string, lit: Lit, story: Story, knows: Knows): Why {
const edit = has(lit.edits, path) ? (story.edited.find((e) => e.name === nameOf(path)) ?? { lines: null }) : null;
return {
edited: edit === null ? null : { lines: edit.lines },
opened: edit === null && has(lit.reads, path),
imports: has(lit.importers, path) && lit.edit !== null ? nameOf(lit.edit) : null,
namedBy: knows.namedBy,
};
}
/** A file's card by repo-relative path, case aside. */
function contextOf(contexts: Readonly<Record<string, FileContext>>, path: string): FileContext | null {
const exact = contexts[path];
if (exact !== undefined) return exact;
const lower = key(path);
const found = Object.keys(contexts).find((k) => key(k) === lower);
return found === undefined ? null : (contexts[found] ?? null);
}
/** What Lens already holds about a file: its card, the tests that reach an edited one, and which reply named it (Flow's record, when on). */
export function knowsOf(path: string, contexts: Readonly<Record<string, FileContext>>, flow: FlowState | null): Knows {
const facts = flow === null ? undefined : flow.blast[pathKey(path)];
const tests = facts?.tests ?? null;
return {
context: contextOf(contexts, path),
tests: tests === null ? null : { total: tests.total, basis: tests.basis },
namedBy: flow === null ? null : (flow.named[pathKey(path)]?.tool ?? null),
};
}