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
/**
* Session state and its reducer. Pure: no I/O, no clock, no `$`.
*/
import type { AskReply, AskState, AskTool, PaneTab } from "./ask";
import { mayHaveUsedModel } from "./ask";
import { initialReview, reduceReview, reviewable, type ChangeRisk, type ReviewAction, type ReviewState } from "./review";
/** `no-repo`: not inside a git work tree, so there is nothing to index and Lens stays quiet. */
export type Mode = "full" | "lite" | "no-index" | "no-cli" | "no-repo";
/** Why a lite session has no map, when it is not simply "no server". */
export type LiteReason = "no-server" | "auth" | "unlisted";
/** One setup hint; each shows at most once per session. */
export type HintKind = "no-server" | "auth" | "unlisted" | "no-index" | "no-cli";
export interface IndexFreshness {
/** Files changed between the indexed commit and HEAD; null when git could not count them. */
changedFiles: number | null;
}
/** What the spinner shows for a file. null fields are unknown, not zero. */
export interface FileContext {
/** Files that import this one or call into it (the server's file-level rollup). */
callerFiles: number | null;
contributors: number | null;
/** The index marks the file a hotspot; null when it did not say. */
hotspot: boolean | null;
/** Who changed it most lately, and their share of its recent commits (0 to 1). */
recentOwner: { name: string; share: number } | null;
}
/** A Read, Edit or Write running on a file inside the indexed repo. */
export interface RunningTool {
id: string;
/** Repo-relative, forward slashes. */
file: string;
}
/**
* One exception the augment hook flagged on an edited file, as it worded it.
* Lens reads these; the thresholds and caps are the hook's own.
*/
export type MarginNote =
| { kind: "decision"; reviewed: boolean; title: string }
| { kind: "fixes"; count: number; age: string; symbol: string | null };
/**
* What the savings ledger gained since the session's first snapshot. It
* covers every agent on this repo: savings events carry a per-connection id,
* not Claude's session id.
*/
export interface SavingsDelta {
/** Input tokens saved, measured and inferred together. */
tokens: number;
/** The inferred part of `tokens`. */
inferredTokens: number;
/** Priced input savings in US dollars; unpriced tokens add nothing here. */
usd: number;
}
export interface SessionState {
/** null until the first discovery settles. */
mode: Mode | null;
/** Shown while the index is behind HEAD, in full and lite mode only. */
freshness: IndexFreshness | null;
/** The hint on screen now. */
hint: HintKind | null;
/** Every hint already shown this session, so none comes back. */
hintsShown: readonly HintKind[];
/** The indexed repo's root, once discovered. */
repoRoot: string | null;
/** The file tool running now, if any. */
running: RunningTool | null;
/** File context fetched this session, by repo-relative path. */
contexts: Readonly<Record<string, FileContext>>;
/** Margin notes by the Edit or Write call they belong to. */
notes: Readonly<Record<string, readonly MarginNote[]>>;
/** Shown only once something was saved; full mode only. */
savings: SavingsDelta | null;
/** The last turn's change review. */
review: ReviewState;
/** The latest review that came back this session, kept past the turn for the recap and the brief. */
lastReview: ChangeRisk | null;
/** Files Claude (or a subagent) wrote this session, repo-relative when inside the repo, each once. */
touched: readonly string[];
/** The pane's tab, and the text the Ask field starts with. */
pane: { tab: PaneTab; draft: string };
ask: AskState;
/** get_answer asks that may have used the repo's configured model: counted at the start, dropped when the reply says no provider. */
modelAsks: number;
/** The context was compacted and the brief not yet sent or passed over. */
compacted: boolean;
}
export type SessionAction =
| { type: "discovered"; mode: Mode; liteReason?: LiteReason; freshness: IndexFreshness | null; repoRoot?: string | null }
| { type: "turnCompleted" }
| { type: "toolStarted"; tool: RunningTool }
| { type: "toolEnded"; id: string }
| { type: "contextLoaded"; file: string; context: FileContext }
| { type: "notesFor"; id: string; notes: readonly MarginNote[] }
| { type: "savings"; delta: SavingsDelta }
| { type: "touched"; path: string }
| { type: "tab"; tab: PaneTab; draft?: string }
| { type: "asked"; question: string; tool: AskTool }
| { type: "answered"; question: string; answer: AskReply }
| { type: "askFailed"; question: string; tool: AskTool; message: string }
| { type: "askBusy" }
| { type: "compacted" }
| { type: "briefDone" }
| ReviewAction;
export const initialSession: SessionState = {
mode: null,
freshness: null,
hint: null,
hintsShown: [],
repoRoot: null,
running: null,
contexts: {},
notes: {},
savings: null,
review: initialReview,
lastReview: null,
touched: [],
pane: { tab: "flow", draft: "" },
ask: { phase: "idle" },
modelAsks: 0,
compacted: false,
};
export function hintFor(mode: Mode, liteReason: LiteReason | undefined): HintKind | null {
if (mode === "full" || mode === "no-repo") return null;
if (mode === "lite") return liteReason ?? "no-server";
return mode;
}
/**
* After a `/clear`: what the index said stays (mode, freshness, hints, the repo,
* file cards) and so does the pane's tab; everything the old conversation did
* goes (its tools, notes, savings, review, touched files, Ask, compaction).
*/
export function clearedConversation(state: SessionState): SessionState {
const { mode, freshness, hint, hintsShown, repoRoot, contexts } = state;
return { ...initialSession, mode, freshness, hint, hintsShown, repoRoot, contexts, pane: { tab: state.pane.tab, draft: "" } };
}
export function reduce(state: SessionState, action: SessionAction): SessionState {
switch (action.type) {
case "discovered": {
const kind = hintFor(action.mode, action.liteReason);
const indexed = action.mode === "full" || action.mode === "lite";
const freshness = indexed ? action.freshness : null;
const repoRoot = indexed ? (action.repoRoot ?? null) : null;
// Savings come from the local server: the row leaves with it.
const savings = action.mode === "full" ? state.savings : null;
if (kind !== null && !state.hintsShown.includes(kind)) {
const hintsShown = [...state.hintsShown, kind];
return { ...state, mode: action.mode, freshness, repoRoot, savings, hint: kind, hintsShown };
}
// A hint for a state that no longer holds (the server came up) leaves at once.
const hint = state.hint === kind ? state.hint : null;
return { ...state, mode: action.mode, freshness, repoRoot, savings, hint };
}
case "turnCompleted":
// A hint stays up through the first turn that ends while it shows, then retires.
return state.hint === null ? state : { ...state, hint: null };
case "toolStarted":
return { ...state, running: action.tool };
case "toolEnded":
// Calls overlap: only the one shown clears the slot.
return state.running?.id === action.id ? { ...state, running: null } : state;
case "contextLoaded":
return { ...state, contexts: { ...state.contexts, [action.file]: action.context } };
case "notesFor": {
if (action.notes.length === 0) return state;
const notes = { ...state.notes, [action.id]: action.notes };
const decision = action.notes.find((n) => n.kind === "decision");
const review = decision === undefined ? state.review : reduceReview(state.review, { type: "decisionNoted", title: decision.title });
return { ...state, notes, review };
}
case "savings":
return { ...state, savings: action.delta.tokens > 0 ? action.delta : null };
case "touched":
return state.touched.includes(action.path) ? state : { ...state, touched: [...state.touched, action.path] };
case "tab":
return { ...state, pane: { tab: action.tab, draft: action.draft ?? state.pane.draft } };
case "asked": {
// Counted when it starts (it may fail or time out after the provider saw it); the Why draft is spent.
const modelAsks = state.modelAsks + (action.tool === "get_answer" ? 1 : 0);
const ask: AskState = { phase: "asking", question: action.question, tool: action.tool, busy: false };
return { ...state, modelAsks, ask, pane: { ...state.pane, draft: "" } };
}
case "askBusy":
return state.ask.phase === "asking" && !state.ask.busy ? { ...state, ask: { ...state.ask, busy: true } } : state;
case "answered": {
// A reply that says it had no provider is known to have used no model: no longer counted.
const modelAsks = Math.max(0, state.modelAsks - (action.answer.tool === "get_answer" && !mayHaveUsedModel(action.answer) ? 1 : 0));
return { ...state, modelAsks, ask: { phase: "answered", question: action.question, answer: action.answer } };
}
case "askFailed":
return { ...state, ask: { phase: "failed", question: action.question, tool: action.tool, message: action.message } };
case "compacted":
return state.compacted ? state : { ...state, compacted: true };
case "briefDone":
return state.compacted ? { ...state, compacted: false } : state;
default:
return reduceTurn(state, action);
}
}
/** The review's actions; a new turn also retires the brief offer, and a landed review is kept for the recap. */
function reduceTurn(state: SessionState, action: ReviewAction): SessionState {
const review = reduceReview(state.review, action);
const compacted = action.type === "turnStarted" ? false : state.compacted;
// Only a review with something to say is kept: an error or an empty diff leaves the last one.
const lastReview = action.type === "reviewed" && reviewable(action.risk) ? action.risk : state.lastReview;
if (review === state.review && compacted === state.compacted && lastReview === state.lastReview) return state;
return { ...state, review, compacted, lastReview };
}
/** Each decision the augment hook surfaced on an edit this session, once, in the order seen. */
export function surfacedDecisions(state: SessionState): Array<{ title: string; reviewed: boolean }> {
const seen = new Map<string, boolean>();
for (const notes of Object.values(state.notes)) {
for (const n of notes) if (n.kind === "decision" && !seen.has(n.title)) seen.set(n.title, n.reviewed);
}
return [...seen].map(([title, reviewed]) => ({ title, reviewed }));
}