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
/**
* Flow: Claude's tool calls this session as the engine reported them, in
* order and timed: what each Repowise reply carried, how many bytes each
* result put in Claude's context, the files it read and edited after a reply
* named them, and what the index says each edited file reaches. Pure: every
* time arrives on an action (epoch ms); nothing here reads a clock. The map
* reads visit order and timing from `visits`.
*/
import { summarizeReply, type ReplySummary } from "./replies";
/** Turns kept whole; older ones fold into `earlier`. */
export const MAX_TURNS = 6;
/** Activities kept per turn; older ones are counted in `dropped`. */
export const MAX_ACTIVITIES = 60;
const PROMPT_CHARS = 160;
/**
* Paths Repowise named this session, for "found via". Ceiling: past this the
* newest namings are not kept; raise it if long sessions need more.
*/
const MAX_NAMED = 2_000;
/** Argument values kept per activity, and their length. */
const MAX_ARGS = 4;
const ARG_CHARS = 160;
/** Characters of a shell command kept, to see which tests it ran. */
const COMMAND_CHARS = 2_000;
/** Hit paths kept per search. */
const MAX_HIT_PATHS = 200;
/** Tool names of the Repowise MCP servers: a user-level one, the plugin's, the hosted connector. */
const REPOWISE_TOOL = /^mcp__(?:repowise|plugin_repowise_repowise|claude_ai_repowise)__(\w+)$/i;
/** Lens's own MCP calls fire tool events too; they are not Claude's steps. */
const OWN_CALL_PREFIX = "toolu_plugin_";
export type ActivityKind = "repowise" | "read" | "edit" | "search" | "shell" | "other";
export interface Activity {
/** The call's tool_use_id. */
id: string;
kind: ActivityKind;
/** The tool's short name: `get_context`, `Read`, `Bash`. */
tool: string;
/** Set on a subagent's call. */
agentId: string | null;
startedAt: number;
endedAt: number | null;
/** Arguments as sent, compacted to a few named values. */
args: ReadonlyArray<readonly [string, string]>;
/** Files the call worked on, relative to the session's directory when inside it. */
paths: readonly string[];
/** The files a Repowise call asked about (its `targets`), relative like `paths`. */
asked: readonly string[];
/** A shell call's command, for which tests it ran. */
command: string | null;
isError: boolean;
/** UTF-8 bytes of the result Claude received; null until it lands. */
bytes: number | null;
reply: ReplySummary | null;
/** For a read or edit: the Repowise reply that named this file first this session. */
namedBy: Naming | null;
/** An edit's size from its arguments: lines added less removed, or lines written. */
lines: { delta: number } | { written: number } | null;
/** Files a search returned, and (up to a cap) which, relative like `paths`. */
hits: number | null;
hitPaths: readonly string[];
}
export interface Naming {
id: string;
/** The Repowise tool whose reply named the file. */
tool: string;
at: number;
turn: number;
}
export type TurnEnd = "answer" | "stopped" | "failed";
export interface FlowTurn {
/** 1 for the session's first turn. */
seq: number;
turnId: string | null;
/** The prompt's first characters; "" for a turn Lens did not see start. */
prompt: string;
startedAt: number;
endedAt: number | null;
durationMs: number | null;
/** How the turn ended: an answer, stopped (aborted), or did not finish (refusal, error); null while open. */
end: TurnEnd | null;
activities: readonly Activity[];
dropped: number;
}
/** What the index says an edited file reaches (the depth-1 blast radius), repo-relative. */
export interface BlastFacts {
/** Files that import it directly. */
importers: readonly string[];
/** Files that usually change with it, strongest first, with the server's 0 to 1 score. */
cochange: ReadonlyArray<{ path: string; score: number }>;
/** Tests that reach it: how many, which (as emitted), and whether measured or inferred. */
tests: { total: number; files: readonly string[]; basis: "measured" | "inferred" } | null;
}
export interface Totals {
turns: number;
repowise: number;
reads: number;
edits: number;
}
export interface FlowState {
turns: readonly FlowTurn[];
/** Totals of the turns folded away. */
earlier: Totals;
/** Paths Repowise named, by `pathKey`, at their first naming. */
named: Readonly<Record<string, Naming>>;
/** Blast radius facts of edited files, by `pathKey`, as the map's request returned them. */
blast: Readonly<Record<string, BlastFacts>>;
/** The Repowise call whose detail is open. */
open: string | null;
}
export const initialFlow: FlowState = {
turns: [],
earlier: { turns: 0, repowise: 0, reads: 0, edits: 0 },
named: {},
blast: {},
open: null,
};
/** A tool call as `tool.call` sees it: its arguments ride beside these keys. */
export interface ToolCall {
tool: string;
tool_use_id: string;
agentId?: string | undefined;
[arg: string]: unknown;
}
export type FlowAction =
| { type: "turnStarted"; turnId: string | null; prompt: string; at: number }
| { type: "turnEnded"; at: number; durationMs: number | null; end: TurnEnd }
| { type: "toolStarted"; activity: Activity }
| {
type: "toolEnded";
id: string;
at: number;
isError: boolean;
bytes: number | null;
reply: ReplySummary | null;
hits: number | null;
hitPaths: readonly string[];
}
| { type: "blastLanded"; path: string; facts: BlastFacts }
| { type: "toggle"; id: string }
| { type: "step"; by: 1 | -1 };
const END_OF: Record<string, TurnEnd> = { answer: "answer", aborted: "stopped", refusal: "failed", error: "failed" };
/** How a `turn.complete` ended the turn, from its `reason` (and `isAborted` when no reason came). */
export function turnEnd(reason: string | undefined, isAborted: boolean | undefined): TurnEnd {
return END_OF[reason ?? ""] ?? (isAborted === true ? "stopped" : "answer");
}
/** The Repowise tool a name calls (`get_context`), or null for any other tool. */
export function repowiseTool(name: string): string | null {
return REPOWISE_TOOL.exec(name)?.[1] ?? null;
}
const KIND_OF: Record<string, ActivityKind> = {
Read: "read",
Edit: "edit",
MultiEdit: "edit",
Write: "edit",
NotebookEdit: "edit",
Grep: "search",
Glob: "search",
Bash: "shell",
};
/** The arguments worth a glance, in this order. */
const ARG_KEYS = ["targets", "query", "question", "id", "file_path", "notebook_path", "pattern", "path", "command", "url", "description"];
const PATH_ARGS = new Set(["file_path", "notebook_path", "path"]);
/** `path` relative to `root` with `/` separators when inside it; else as given, slashed. */
export function shortPath(path: string, root: string | null): string {
const slashed = path.replace(/\\/g, "/");
if (root === null) return slashed;
const base = root.replace(/\\/g, "/").replace(/\/+$/, "");
const inside = slashed.toLowerCase().startsWith(`${base.toLowerCase()}/`);
return inside ? slashed.slice(base.length + 1) : slashed;
}
function argValue(key: string, v: unknown, root: string | null): string | null {
if (typeof v === "string") return (PATH_ARGS.has(key) ? shortPath(v, root) : v.replace(/\s+/g, " ")).slice(0, ARG_CHARS);
if (Array.isArray(v)) return v.map((x) => (typeof x === "string" ? x : JSON.stringify(x))).join(", ").slice(0, ARG_CHARS);
if (v === undefined || v === null) return null;
return JSON.stringify(v).slice(0, ARG_CHARS);
}
function compactArgs(e: ToolCall, root: string | null): Array<readonly [string, string]> {
const out: Array<readonly [string, string]> = [];
for (const key of ARG_KEYS) {
const value = argValue(key, e[key], root);
if (value !== null && out.length < MAX_ARGS) out.push([key, value]);
}
return out;
}
const lineCount = (s: unknown): number | null => (typeof s === "string" ? s.split("\n").length : null);
function editLines(e: ToolCall): Activity["lines"] {
const written = e.tool === "Write" ? lineCount(e["content"]) : null;
if (written !== null) return { written };
const before = lineCount(e["old_string"]);
const after = lineCount(e["new_string"]);
return before !== null && after !== null ? { delta: after - before } : null;
}
/** The files a Repowise call names in its `targets` (symbol ids left out), as paths. */
function askedFiles(e: ToolCall, root: string | null): string[] {
const targets = e["targets"];
const list: unknown[] = Array.isArray(targets) ? targets : [];
return list.filter((t): t is string => typeof t === "string" && !t.includes("::")).map((t) => shortPath(t, root));
}
/** A call Claude made: it has an id, and not one of Lens's own. */
function isClaudeCall(e: ToolCall): boolean {
return typeof e.tool_use_id === "string" && typeof e.tool === "string" && !e.tool_use_id.startsWith(OWN_CALL_PREFIX);
}
/**
* The activity a tool call starts, or null for Lens's own calls. `root` is
* the session's directory, which paths are shown relative to.
*/
export function activityOf(e: ToolCall, at: number, root: string | null): Activity | null {
if (!isClaudeCall(e)) return null;
const rw = repowiseTool(e.tool);
const kind: ActivityKind = rw !== null ? "repowise" : (KIND_OF[e.tool] ?? "other");
return { ...BLANK, id: e.tool_use_id, kind, tool: rw ?? e.tool, agentId: agentOf(e), startedAt: at, args: compactArgs(e, root), ...BY_KIND[kind](e, root) };
}
/** An activity's fields before anything about its call is known. */
const BLANK: Omit<Activity, "id" | "kind" | "tool" | "agentId" | "startedAt" | "args"> = {
endedAt: null,
paths: [],
asked: [],
command: null,
isError: false,
bytes: null,
reply: null,
namedBy: null,
lines: null,
hits: null,
hitPaths: [],
};
const agentOf = (e: ToolCall): string | null => (typeof e.agentId === "string" ? e.agentId : null);
/** The file a file tool works on, relative to `root`. */
function fileOf(e: ToolCall, root: string | null): Pick<Activity, "paths"> {
const file = e["file_path"] ?? e["notebook_path"];
return { paths: typeof file === "string" ? [shortPath(file, root)] : [] };
}
/** A shell call's command, kept to see which tests it ran. */
function commandOf(e: ToolCall): Pick<Activity, "command"> {
const command = e["command"];
return { command: typeof command === "string" ? command.slice(0, COMMAND_CHARS) : null };
}
/** What each kind of call adds to its activity. */
const BY_KIND: Record<ActivityKind, (e: ToolCall, root: string | null) => Partial<Activity>> = {
repowise: (e, root) => ({ ...fileOf(e, root), asked: askedFiles(e, root) }),
read: fileOf,
edit: (e, root) => ({ ...fileOf(e, root), lines: editLines(e) }),
search: fileOf,
shell: (e) => commandOf(e),
other: fileOf,
};
/**
* Files a search returned, from what `next(e)` resolved to: the count, and
* the names relative to `root` (a Grep that printed lines names none).
*/
export function searchHits(outcome: unknown, root: string | null): { hits: number | null; hitPaths: string[] } {
const result = (outcome as { result?: { filenames?: unknown; numFiles?: unknown } } | null)?.result;
if (typeof result !== "object" || result === null) return { hits: null, hitPaths: [] };
if (!Array.isArray(result.filenames)) return { hits: typeof result.numFiles === "number" ? result.numFiles : null, hitPaths: [] };
const names = result.filenames.filter((f): f is string => typeof f === "string");
return { hits: names.length, hitPaths: names.slice(0, MAX_HIT_PATHS).map((f) => shortPath(f, root)) };
}
/** The text of a call's outcome (`next(e)`'s `text`): what Claude received, or null. */
export function outcomeText(outcome: unknown): string | null {
const text = (outcome as { text?: unknown } | null)?.text;
return typeof text === "string" ? text : null;
}
/**
* The end of a tool call, from what `next(e)` resolved to (null when it
* threw): its time, whether it failed, the bytes Claude received (counted,
* never kept), a Repowise reply's summary, a search's hits. Null for Lens's
* own calls.
*/
export function toolEnded(e: ToolCall, outcome: unknown, at: number, root: string | null): FlowAction | null {
if (!isClaudeCall(e)) return null;
const rw = repowiseTool(e.tool);
const text = outcomeText(outcome);
const isError = outcome === null || (outcome as { isError?: unknown } | undefined)?.isError === true;
const summary = rw === null || text === null ? null : summarizeReply(rw, text);
// Named paths compare repo-relative: an absolute one under the root is made relative here.
const reply = summary === null ? null : { ...summary, paths: summary.paths.map((p) => shortPath(p, root)) };
const bytes = summary?.bytes ?? (text === null ? null : new TextEncoder().encode(text).length);
return { type: "toolEnded", id: e.tool_use_id, at, isError, bytes, reply, ...searchHits(outcome, root) };
}
/** A key matching a path however it was written: `/` separators, no case. */
export function pathKey(path: string): string {
// Ceiling: case is folded everywhere, so two files differing only in case share a key.
return path.replace(/\\/g, "/").replace(/^\.\//, "").toLowerCase();
}
/**
* The first naming of exactly this path. Both sides are relative to the same
* root (`shortPath`), so a file outside it never matches a reply's path.
*/
function namingOf(named: FlowState["named"], path: string): Naming | null {
return named[pathKey(path)] ?? null;
}
/** Folds paths a reply named into the session's namings; first naming wins. */
function withNamed(named: FlowState["named"], paths: readonly string[], naming: Naming): FlowState["named"] {
let out = named;
let size = Object.keys(named).length;
for (const p of paths) {
const key = pathKey(p);
if (out[key] !== undefined || size >= MAX_NAMED) continue;
if (out === named) out = { ...named };
(out as Record<string, Naming>)[key] = naming;
size++;
}
return out;
}
export interface TurnTotals {
/** Repowise calls made, and those that came back without an error, with their time. */
repowise: number;
answered: number;
answeredMs: number;
reads: number;
edits: number;
/** Distinct files read or edited, and how many of them a Repowise reply named first. */
opened: number;
named: number;
/** An edit landed in a file a Repowise reply named first. */
editNamed: boolean;
}
export const isFile = (a: Activity): boolean => a.kind === "read" || a.kind === "edit";
const isAnswered = (a: Activity): boolean => a.kind === "repowise" && a.endedAt !== null && !a.isError;
/** Counts for a turn: Repowise calls and their time, distinct files read and edited, and how many Repowise named first. */
export function turnTotals(turn: FlowTurn): TurnTotals {
const files = turn.activities.filter(isFile);
const keys = (list: Activity[]) => new Set(list.map((a) => pathKey(a.paths[0] ?? "")));
const answered = turn.activities.filter(isAnswered);
const edits = files.filter((a) => a.kind === "edit");
return {
repowise: turn.activities.filter((a) => a.kind === "repowise").length,
answered: answered.length,
answeredMs: answered.reduce((ms, a) => ms + (a.endedAt as number) - a.startedAt, 0),
reads: keys(files.filter((a) => a.kind === "read")).size,
edits: keys(edits).size,
opened: keys(files).size,
named: keys(files.filter((a) => a.namedBy !== null)).size,
editNamed: edits.some((a) => a.namedBy !== null),
};
}
function fold(earlier: Totals, turn: FlowTurn): Totals {
const t = turnTotals(turn);
return { turns: earlier.turns + 1, repowise: earlier.repowise + t.repowise, reads: earlier.reads + t.reads, edits: earlier.edits + t.edits };
}
function withTurn(state: FlowState, turn: FlowTurn): FlowState {
const turns = [...state.turns, turn];
if (turns.length <= MAX_TURNS) return { ...state, turns };
const gone = turns.shift() as FlowTurn;
return { ...state, turns, earlier: fold(state.earlier, gone) };
}
/**
* Blocks the harness puts around what the person typed: agent hand-backs,
* system reminders, task notifications, slash-command wrappers. A tag may
* arrive escaped (`<\\agent-message`); one never closed runs to the end.
*/
const INJECTED = /\s*<\\?((?:agent-message|system-reminder|task-notification|local-command-[\w-]+|command-[\w-]+))\b[^>]*>[\s\S]*?(?:<\/\1>|$)\s*/g;
/** The person's own words in a turn's text: injected blocks removed wherever they sit; "" when nothing they typed remains. */
export function userWords(text: string): string {
return text.replace(INJECTED, " ").trim();
}
function newTurn(state: FlowState, turnId: string | null, prompt: string, at: number): FlowTurn {
const seq = (state.turns.at(-1)?.seq ?? state.earlier.turns) + 1;
return { seq, turnId, prompt: userWords(prompt).slice(0, PROMPT_CHARS), startedAt: at, endedAt: null, durationMs: null, end: null, activities: [], dropped: 0 };
}
/** The open turn, or a new one when Lens did not see this turn start. */
function openTurn(state: FlowState, at: number): FlowState {
const last = state.turns.at(-1);
return last !== undefined && last.endedAt === null ? state : withTurn(state, newTurn(state, null, "", at));
}
function mapLast(state: FlowState, f: (t: FlowTurn) => FlowTurn): FlowState {
const last = state.turns.at(-1);
const next = last === undefined ? last : f(last);
return next === last ? state : { ...state, turns: [...state.turns.slice(0, -1), next as FlowTurn] };
}
/** Rewrites the activity `id` wherever it is; the state as it was when no turn holds it. */
function mapActivity(state: FlowState, id: string, f: (a: Activity) => Activity): FlowState {
const i = state.turns.findIndex((t) => t.activities.some((a) => a.id === id));
if (i < 0) return state;
const turn = state.turns[i] as FlowTurn;
const activities = turn.activities.map((a) => (a.id === id ? f(a) : a));
const turns = state.turns.map((t, j) => (j === i ? { ...turn, activities } : t));
return { ...state, turns };
}
/** The turn with one more activity, the oldest dropped (and counted) past the cap. */
function pushActivity(t: FlowTurn, activity: Activity): FlowTurn {
const all = [...t.activities, activity];
const over = all.length - MAX_ACTIVITIES;
return over > 0 ? { ...t, activities: all.slice(over), dropped: t.dropped + over } : { ...t, activities: all };
}
function append(state: FlowState, activity: Activity): FlowState {
return mapLast(openTurn(state, activity.startedAt), (t) => pushActivity(t, activity));
}
/** Ends the open turn, if any, as `end`. */
function closeTurn(state: FlowState, at: number, durationMs: number | null, end: TurnEnd): FlowState {
return mapLast(state, (t) => (t.endedAt !== null ? t : { ...t, endedAt: at, durationMs: durationMs ?? at - t.startedAt, end }));
}
function started(state: FlowState, activity: Activity): FlowState {
const namedBy = isFile(activity) && activity.paths[0] !== undefined ? namingOf(state.named, activity.paths[0]) : null;
return append(state, { ...activity, namedBy });
}
function ended(state: FlowState, action: Extract<FlowAction, { type: "toolEnded" }>): FlowState {
const { id, at, isError, bytes, reply, hits, hitPaths } = action;
const next = mapActivity(state, id, (a) => ({ ...a, endedAt: at, isError, bytes, reply, hits, hitPaths }));
if (next === state || reply === null || isError) return next;
const turn = next.turns.find((t) => t.activities.some((a) => a.id === id)) as FlowTurn;
return { ...next, named: withNamed(next.named, reply.paths, { id, tool: reply.tool, at, turn: turn.seq }) };
}
/** The rows a press or a hotkey can open: Repowise calls, oldest first. */
export function openable(state: FlowState): string[] {
return state.turns.flatMap((t) => t.activities.filter((a) => a.kind === "repowise").map((a) => a.id));
}
function stepped(state: FlowState, by: 1 | -1): FlowState {
const ids = openable(state);
if (ids.length === 0) return state;
const at = state.open === null ? -1 : ids.indexOf(state.open);
const i = at < 0 ? (by === 1 ? 0 : ids.length - 1) : Math.min(ids.length - 1, Math.max(0, at + by));
return ids[i] === state.open ? state : { ...state, open: ids[i] as string };
}
export function reduceFlow(state: FlowState, action: FlowAction): FlowState {
switch (action.type) {
case "turnStarted": {
// A prompt while the last turn is still open: that one was stopped.
const closed = closeTurn(state, action.at, null, "stopped");
return withTurn(closed, newTurn(closed, action.turnId, action.prompt, action.at));
}
case "turnEnded":
return closeTurn(state, action.at, action.durationMs, action.end);
case "toolStarted":
return started(state, action.activity);
case "toolEnded":
return ended(state, action);
case "blastLanded":
return { ...state, blast: { ...state.blast, [pathKey(action.path)]: action.facts } };
case "toggle":
return { ...state, open: state.open === action.id ? null : action.id };
case "step":
return stepped(state, action.by);
}
}
/** Every activity kept, oldest first, across turns. */
export function activities(state: FlowState): Activity[] {
return state.turns.flatMap((t) => [...t.activities]);
}
/** One place Claude's attention went: a file read or edited, or a file a search returned. */
export interface Visit {
path: string;
kind: "read" | "edit" | "search-hit";
/** Increasing per read, edit or search; every hit of one search shares its search's number. */
order: number;
at: number;
turn: number;
}
/**
* Claude's visits this session, in order, for the map: reads and
* edits each get the next number, and a search's hits all share one. Paths
* are as `activityOf` and `searchHits` kept them (relative to the session's
* root, `/` separators). Failed calls are left out.
*/
export function visits(state: FlowState): Visit[] {
const out: Visit[] = [];
let order = 0;
const steps = state.turns.flatMap((t) => t.activities.map((a) => [a, t.seq] as const));
for (const [a, turn] of steps) {
const found = visitsOf(a, turn, order + 1);
if (found.length > 0) order++;
out.push(...found);
}
return out;
}
/** One activity's visits, all numbered `order`: a read or edit's file, or a search's hits. */
function visitsOf(a: Activity, turn: number, order: number): Visit[] {
if (a.isError) return [];
if (a.kind === "search") return a.hitPaths.map((path): Visit => ({ path, kind: "search-hit", order, at: a.endedAt ?? a.startedAt, turn }));
const path = a.paths[0];
return (a.kind === "read" || a.kind === "edit") && path !== undefined ? [{ path, kind: a.kind, order, at: a.startedAt, turn }] : [];
}
/** Whether Claude is in a turn now. */
export function isWorking(state: FlowState): boolean {
const last = state.turns.at(-1);
return last !== undefined && last.endedAt === null;
}
/** A Repowise call still waiting on its reply. */
export function inFlight(state: FlowState): Activity | null {
return state.turns.at(-1)?.activities.find((a) => a.kind === "repowise" && a.endedAt === null) ?? null;
}