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
import { fileEntityPath } from "../shared/entity/routes";
/** Mirrors `AttentionItemType` in `core/analysis/attention/compose.py`; a Python test pins it. */
export type AttentionItemType =
| "stale_decision"
| "knowledge_silo"
| "ungoverned_hotspot"
| "dead_code"
| "proposed_decision"
| "health_finding"
| "security_finding"
| "doc_drift"
| "refactoring";
export interface AttentionItem {
id: string;
type: AttentionItemType;
title: string;
description: string;
/** Four levels, matching `HealthSeverity`. The three-level version this
* used to declare could not represent a critical health finding, which is
* the band that most needs to outrank everything else on the list. */
severity: AttentionSeverity;
/** What the item points at — a decision id, file path, owner, … Used to
* deep-link straight to the offending entity. */
target_id?: string;
/** The finding's kind within its source — a `biomarker_type`, a scanner
* kind, a drift kind. Resolved to a label by the renderer. */
subtype?: string;
href?: string;
}
/** The four-level ladder, worst first. Matches `HealthSeverity`. */
export type AttentionSeverity = "critical" | "high" | "medium" | "low";
/**
* Sort weight for a severity, worst first.
*
* The server ranks the list before it ships (see
* `core/analysis/attention/compose.py`), so nothing in the UI needs to re-sort by
* severity. This exists for the surfaces that re-mix the order for their own
* reasons — the dashboard panel round-robins by type — and so that they do it
* against one ladder instead of a local literal each.
*/
export const ATTENTION_SEVERITY_RANK: Record<AttentionSeverity, number> = {
critical: 0,
high: 1,
medium: 2,
low: 3,
};
/**
* What to call each source, for every surface that renders these items.
*
* One map rather than one per renderer: the panel and the Overview rows had
* separately maintained copies that had already drifted in case ("Stale
* Decision" against "Stale decision"), and a new source meant remembering to
* add it to both.
*
* Sentence case, per the copy rules: these are labels, not headings.
*/
export const ATTENTION_TYPE_LABEL: Record<AttentionItemType, string> = {
stale_decision: "Stale decision",
proposed_decision: "Needs review",
ungoverned_hotspot: "Ungoverned",
knowledge_silo: "Knowledge silo",
dead_code: "Dead code",
health_finding: "Code health",
security_finding: "Security",
doc_drift: "Doc drift",
refactoring: "Refactoring",
};
/**
* The page that owns a whole source, as opposed to one item of it.
*
* Used for the breakdown beside the list, and as {@link getDefaultHref}'s
* fallback when an item carries no target — those were the same URLs written
* twice, and the copy inside the switch had already started to drift from the
* routes.
*
* `decisions` is not an item type; it is the key the server uses for the three
* decision lanes together in `attention_summary.by_source`.
*/
export function attentionSourceHref(source: string, prefix: string): string {
switch (source) {
// Area keys, from `attention_summary.areas`. Listed beside the item types
// they roll up so one function answers "where does this go" for both.
// `doc_drift` and `dead_code` name an area and an item type at once and
// route to the same page either way, so they need no separate case.
case "security":
return `${prefix}/security`;
case "health":
return `${prefix}/code-health?tab=findings`;
case "ownership":
return `${prefix}/owners`;
case "stale_decision":
case "proposed_decision":
case "decisions":
return `${prefix}/decisions`;
case "knowledge_silo":
return `${prefix}/owners`;
case "ungoverned_hotspot":
return `${prefix}/code-health`;
case "health_finding":
return `${prefix}/code-health?tab=findings`;
case "refactoring":
return `${prefix}/refactoring`;
case "security_finding":
return `${prefix}/security`;
case "doc_drift":
return `${prefix}/code-health?tab=doc-drift`;
case "dead_code":
return `${prefix}/code-health?tab=dead-code`;
default:
return prefix;
}
}
/** The doc drift tab, narrowed to one document when given. */
export function docDriftHref(prefix: string, document?: string): string {
const base = attentionSourceHref("doc_drift", prefix);
return document ? `${base}&document=${encodeURIComponent(document)}` : base;
}
/** Area keys are not item types, so they get their own names. */
const AREA_LABEL: Record<string, string> = {
security: "Security",
health: "Code health",
refactoring: "Refactoring",
doc_drift: "Doc drift",
decisions: "Decisions",
ownership: "Ownership",
dead_code: "Dead code",
};
/** What to call a `by_source` key or an area key. */
export function attentionSourceLabel(source: string): string {
return AREA_LABEL[source] ?? ATTENTION_TYPE_LABEL[source as AttentionItemType] ?? source;
}
/**
* Where an attention item points.
*
* Lives in a plain module rather than beside the panel that renders it,
* because two surfaces need it and only one of them is a client component.
* Importing it from `attention-panel` worked at compile time and failed at
* runtime with "attempted to call getDefaultHref() from the server but
* getDefaultHref is on the client" — a `"use client"` file exports components
* to the server, not callable functions.
*
* Kept in one place because each branch is a per-type routing decision (a silo
* wants the owners view filtered to its path, an ungoverned hotspot wants the
* file page), so a second caller re-deriving them by hand gets most of them
* wrong.
*/
export function getDefaultHref(item: AttentionItem, prefix: string): string {
const target = item.target_id;
switch (item.type) {
case "stale_decision":
case "proposed_decision":
// Deep-link to the specific decision when we know which one.
return target
? `${prefix}/decisions/${encodeURIComponent(target)}`
: attentionSourceHref(item.type, prefix);
case "knowledge_silo":
// The file's own History tab, which is where ownership concentration is
// visible. NOT `/owners?path=`: that route is a directory of people and
// reads no path param at all, so the deep link this used to emit landed
// on an unfiltered contributor list with the offending file nowhere on
// it. A tab a file does not have falls back to its Overview, so this is
// safe for any target.
return target
? `${fileEntityPath(prefix, target)}?tab=history`
: attentionSourceHref(item.type, prefix);
case "ungoverned_hotspot":
// Target is the hotspot's file path → open its file entity page.
return target ? fileEntityPath(prefix, target) : attentionSourceHref(item.type, prefix);
case "health_finding":
// The file's Health tab, where the biomarker that produced this row is
// listed with its deduction.
return target
? `${fileEntityPath(prefix, target)}?tab=health`
: attentionSourceHref(item.type, prefix);
case "security_finding":
// The category, deliberately: a security finding is a file and a line,
// and no per-file surface renders it. Unlike the silo and dead-code
// cases there is no better destination to deep-link to, so this lands
// where the finding is actually readable.
return attentionSourceHref(item.type, prefix);
case "refactoring":
// The plan list, not the file: a refactoring row IS the work, and the
// page that owns it is where the plan can be read and handed to an
// agent.
return attentionSourceHref(item.type, prefix);
case "doc_drift":
// The drift tab filtered to the *document* making the false claim
// (`target_id`); a file page would open the code, the wrong subject.
return docDriftHref(prefix, target);
case "dead_code":
// The row names one symbol, so the category list is the wrong landing:
// the dead-code tab has no per-file filter, and arriving at a few
// hundred unfiltered findings means finding the row again by hand. The
// file page carries the symbol and its health. Untargeted findings still
// get the list.
return target ? fileEntityPath(prefix, target) : attentionSourceHref(item.type, prefix);
default:
return prefix;
}
}