Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(chat): a chart tool that draws any repository dataset in one call (#3860)

Raghav Chamadiya90e8d4964c07
diff --git a/docs/architecture/chat.md b/docs/architecture/chat.md
index c138d011e..6bb64c75a 100644
--- a/docs/architecture/chat.md
+++ b/docs/architecture/chat.md
@@ -273,16 +273,17 @@ for each iteration:
After the loop, the assistant message (text + all tool calls with results) is
saved to the database and a `done` event is emitted.
-**Charts in chat:** the model calls an analysis tool, then the chat-only
-`show_view` tool, which the server turns into a table or chart from that
-result. Every result the model sees starts with its `artifact_id`, and
-`show_view` takes any id from the conversation or `latest:<tool_name>` for
-that tool's newest result. A chart whose values are all zero is not drawn.
-When no named view fits, the `chart` view takes a small spec (rows, x, y,
-series, filter, aggregate, sort, top with an Other bucket, kind) and the server
-filters, groups and draws it, picking the chart type from the data's shape
-unless one is asked for. The same guards apply: no person fields, no risk score
-as a plotted value, and attribution figures only through `changes.provenance`.
+**Charts in chat:** the chat-only `chart` tool draws a repository dataset
+(files, findings, changes, health_trend, coverage, dead_code, dependencies,
+layers) in one call: the server reads every row from the index (cached per
+index state), filters, aggregates and draws it as a bar, horizontal bar,
+stacked bar, line, area, donut, scatter, treemap, heatmap or table. Its receipt
+carries the exact totals, shares and averages, every repair it made to the spec,
+a `kind_note` when the asked kind did not fit, and a `suggested_spec` on error.
+`show_view` draws a tool result already in the conversation (by `artifact_id`
+or `latest:<tool_name>`), redraws an earlier view by its id, and lets named
+views take `options.kind`. The same guards apply: no person fields, no risk
+score as a plotted value, and attribution figures only through `changes.provenance`.
---
diff --git a/packages/api-client/src/validation.ts b/packages/api-client/src/validation.ts
index 9ba862592..f0680f1b1 100644
--- a/packages/api-client/src/validation.ts
+++ b/packages/api-client/src/validation.ts
@@ -64,6 +64,13 @@ export const matches =
(v, p, e) => {
if (typeof v !== "string" || !pattern.test(v)) e.push(`${p}: expected ${what}`);
};
+export const oneOfNumbers =
+ (values: readonly number[]): Check =>
+ (v, p, e) => {
+ if (typeof v !== "number" || !values.includes(v)) {
+ e.push(`${p}: expected one of ${values.join(", ")}`);
+ }
+ };
export const constant =
(expected: string | number): Check =>
(v, p, e) => {
diff --git a/packages/api-client/src/views.test.ts b/packages/api-client/src/views.test.ts
index 2eef26159..0a4e7c9ff 100644
--- a/packages/api-client/src/views.test.ts
+++ b/packages/api-client/src/views.test.ts
@@ -12,6 +12,7 @@ import {
VIEW_KINDS,
VIEW_LIMITS,
VIEW_SCHEMA_VERSION,
+ VIEW_SCHEMA_VERSIONS,
parseViewParts,
validateViewPart,
validateViewParts,
@@ -87,6 +88,7 @@ describe("view part contract shared with the server", () => {
it("uses the shared vocabulary and limits", () => {
expect({
schema_version: VIEW_SCHEMA_VERSION,
+ schema_versions: VIEW_SCHEMA_VERSIONS,
max_wire_number: MAX_WIRE_NUMBER,
view_kinds: VIEW_KINDS,
chart_types: CHART_TYPES,
@@ -186,4 +188,25 @@ describe("view part validator", () => {
VIEW_LIMITS.parts,
);
});
+
+ it("keeps a chart it cannot draw as its data table", () => {
+ const { c1 } = fixture.valid as Record<string, ViewPart>;
+ const newer = { ...c1!, schema_version: 3, chart_type: "sankey", flows: [] };
+ const [kept] = parseViewParts([newer]);
+ expect(kept?.kind).toBe("table");
+ expect(kept && "rows" in kept ? kept.rows : null).toEqual((c1 as { data: { rows: unknown } }).data.rows);
+ expect(kept?.schema_version).toBe(VIEW_SCHEMA_VERSION);
+ // A table with a field this client does not know keeps its known fields.
+ const { t1 } = fixture.valid as Record<string, ViewPart>;
+ expect(parseViewParts([{ ...t1!, sparkline: [1, 2] }])[0]?.kind).toBe("table");
+ // Something that is no table at all is still dropped.
+ expect(parseViewParts([{ ...c1!, chart_type: "sankey", data: { rows: "x" } }])).toEqual([]);
+ });
+
+ it("reads parts stored at schema version 1", () => {
+ const { c1 } = fixture.valid as Record<string, ViewPart>;
+ expect(c1?.schema_version).toBe(1);
+ expect(validateViewPart(c1).ok).toBe(true);
+ expect(validateViewPart({ ...c1!, schema_version: 2 }).ok).toBe(true);
+ });
});
diff --git a/packages/api-client/src/views.ts b/packages/api-client/src/views.ts
index 0a275bf46..b1fb9fc16 100644
--- a/packages/api-client/src/views.ts
+++ b/packages/api-client/src/views.ts
@@ -11,6 +11,8 @@
import {
VIEW_LIMITS,
+ VIEW_SCHEMA_VERSION,
+ VIEW_SCHEMA_VERSIONS,
type ViewKind,
type ViewPart,
type ViewPartsByKind,
@@ -93,16 +95,42 @@ export function validateViewParts(input: unknown): ViewListValidation {
return errors.length ? { ok: false, errors } : { ok: true, views };
}
+const TABLE_FIELDS = ["id", "title", "summary", "source", "basis", "coverage", "stale", "as_of"];
+const TABLE_DATA = ["columns", "rows", "total_rows", "truncated"];
+
+/**
+ * A chart or table this client cannot check as sent (a newer chart type or
+ * field) kept as its data table, so newer parts degrade instead of vanishing.
+ * Null when even the table does not hold.
+ */
+export function asDataTable(input: unknown): ViewPart | null {
+ if (!isRec(input) || (input.kind !== "chart" && input.kind !== "table")) return null;
+ const data = input.kind === "chart" ? input.data : input;
+ if (!isRec(data)) return null;
+ const known = (VIEW_SCHEMA_VERSIONS as readonly unknown[]).includes(input.schema_version);
+ const table: Record<string, unknown> = {
+ schema_version: known ? input.schema_version : VIEW_SCHEMA_VERSION,
+ kind: "table",
+ };
+ for (const key of TABLE_FIELDS) if (Object.hasOwn(input, key)) table[key] = input[key];
+ for (const key of TABLE_DATA) if (Object.hasOwn(data, key)) table[key] = data[key];
+ const result = validateViewPart(table);
+ return result.ok ? result.view : null;
+}
+
/**
* Keeps what a renderer can show from an untrusted list: the valid parts among
- * the first `VIEW_LIMITS.parts`, the first part for each id, and only the
- * parts whose references all resolve to a kept data part.
+ * the first `VIEW_LIMITS.parts` (a chart it cannot draw as its table), the
+ * first part for each id, and only the parts whose references all resolve to
+ * a kept data part.
*/
export function parseViewParts(input: unknown): ViewPart[] {
if (!Array.isArray(input)) return [];
const seen = new Set<string>();
const kept = input.slice(0, VIEW_LIMITS.parts).flatMap((item) => {
- const result = validateViewPart(item);
+ const checked = validateViewPart(item);
+ const degraded = checked.ok ? null : asDataTable(item);
+ const result: ViewValidation = degraded ? { ok: true, view: degraded } : checked;
if (!result.ok || seen.has(result.view.id)) return [];
seen.add(result.view.id);
return [result.view];
diff --git a/packages/api-client/src/views/base.ts b/packages/api-client/src/views/base.ts
index 451c30ea8..9560c25e2 100644
--- a/packages/api-client/src/views/base.ts
+++ b/packages/api-client/src/views/base.ts
@@ -5,7 +5,7 @@
import {
VIEW_COVERAGE_METRICS,
- VIEW_SCHEMA_VERSION,
+ VIEW_SCHEMA_VERSIONS,
type ViewCoverage,
type ViewKind,
type ViewPartBase,
@@ -23,6 +23,7 @@ import {
nullable,
obj,
oneOf,
+ oneOfNumbers,
ratio,
str,
type Check,
@@ -50,7 +51,7 @@ export const COVERAGE_SPEC: Spec<ViewCoverage> = {
export function baseSpec<K extends string>(kind: K): Spec<ViewPartBase<K>> {
return {
required: {
- schema_version: constant(VIEW_SCHEMA_VERSION),
+ schema_version: oneOfNumbers(VIEW_SCHEMA_VERSIONS),
kind: constant(kind),
id: partId,
title: str,
diff --git a/packages/api-client/src/views/chart.ts b/packages/api-client/src/views/chart.ts
index 0dc27933a..8fa3bf172 100644
--- a/packages/api-client/src/views/chart.ts
+++ b/packages/api-client/src/views/chart.ts
@@ -1,11 +1,11 @@
/**
* The `chart` view kind. Charts plot their own table, so these rules only
* check that the chart reads that table honestly: axes name real columns,
- * plotted values are numbers in one unit, a donut is a whole of two to five
- * non-negative parts with a positive total, a stacked bar is not all zeros,
- * a scatter's x is a number, and a stated sort order is the order the rows
- * are in (a sorted chart may not hold nulls in its series, since a null has
- * no place in the order).
+ * plotted values are numbers in one unit, a donut is a whole of two to eight
+ * non-negative parts with a positive total, a stacked bar or treemap is not
+ * all zeros, a scatter's x is a number, a stated sort order is the order the
+ * rows are in (a sorted chart may not hold nulls in its series, since a null
+ * has no place in the order), and only a treemap names `groups` or `color`.
*/
import {
@@ -33,13 +33,17 @@ import { columnKeys, tableData } from "./table";
/** Fewest and most series each chart type plots. */
const SERIES_BOUNDS: { [T in ChartType]: [number, number] } = {
bar: [1, VIEW_LIMITS.chart_series],
+ horizontal_bar: [1, VIEW_LIMITS.chart_series],
line: [1, VIEW_LIMITS.chart_series],
+ area: [1, VIEW_LIMITS.chart_series],
stacked_bar: [2, VIEW_LIMITS.chart_series],
donut: [1, 1],
scatter: [1, VIEW_LIMITS.chart_series],
+ treemap: [1, 1],
+ heatmap: [1, VIEW_LIMITS.chart_series],
};
/** Chart types whose values are parts of a whole, so never negative. */
-const PARTS_OF_A_WHOLE: ReadonlySet<ChartType> = new Set(["stacked_bar", "donut"]);
+const PARTS_OF_A_WHOLE: ReadonlySet<ChartType> = new Set(["stacked_bar", "donut", "treemap"]);
const base = baseSpec("chart");
export const CHART_SPEC: Spec<ChartView> = {
@@ -52,7 +56,12 @@ export const CHART_SPEC: Spec<ChartView> = {
series: list(str, VIEW_LIMITS.chart_series),
summary: str,
},
- optional: { ...PROVENANCE_SPEC.optional, sort: oneOf(CHART_SORT_ORDERS) },
+ optional: {
+ ...PROVENANCE_SPEC.optional,
+ sort: oneOf(CHART_SORT_ORDERS),
+ groups: list(str, VIEW_LIMITS.treemap_groups),
+ color: str,
+ },
};
function chartRules(v: Rec, p: string, e: string[]): void {
@@ -66,6 +75,7 @@ function chartRules(v: Rec, p: string, e: string[]): void {
const type = v.chart_type as ChartType;
if (typeof v.x === "string" && !keys.has(v.x)) e.push(`${p}.x: not a column of data`);
+ treemapRules(v, keys, series, p, e);
series.forEach((s, i) => {
if (!keys.has(s)) e.push(`${p}.series[${i}]: not a column of data`);
else if (s === v.x) e.push(`${p}.series[${i}]: is the x column`);
@@ -132,6 +142,23 @@ function chartRules(v: Rec, p: string, e: string[]): void {
}
}
+function treemapRules(v: Rec, keys: Set<unknown>, series: string[], p: string, e: string[]): void {
+ if (v.groups === undefined && v.color === undefined) return;
+ if (v.chart_type !== "treemap") {
+ e.push(`${p}: groups and color apply to a treemap only`);
+ return;
+ }
+ const groups = Array.isArray(v.groups) ? v.groups.filter((g): g is string => typeof g === "string") : [];
+ groups.forEach((g, i) => {
+ if (!keys.has(g)) e.push(`${p}.groups[${i}]: not a column of data`);
+ else if (g === v.x || series.includes(g)) e.push(`${p}.groups[${i}]: is the x or a series column`);
+ });
+ for (const g of duplicates(groups)) e.push(`${p}.groups: duplicate ${g}`);
+ if (typeof v.color === "string" && (!keys.has(v.color) || v.color === v.x)) {
+ e.push(`${p}.color: not a column of data other than x`);
+ }
+}
+
export const CHART_KIND: ViewKindEntry<"chart"> = {
check: obj(CHART_SPEC, chartRules),
isData: true,
diff --git a/packages/server/src/repowise/server/chat_chart.py b/packages/server/src/repowise/server/chat_chart.py
new file mode 100644
index 000000000..ed57642cd
--- /dev/null
+++ b/packages/server/src/repowise/server/chat_chart.py
@@ -0,0 +1,162 @@
+"""The chat-only ``chart`` tool: one call from a question to a drawn chart.
+
+``show_view`` needs a tool result first, a list found inside it and an
+artifact id; a light model trips on each step. ``chart`` names a dataset
+(:mod:`repowise.server.chat_datasets`) and the chart spec instead, and the
+server reads every row, filters, aggregates and draws through the same spec,
+guards and part validation ``show_view``'s ``chart`` view uses. The part goes
+out as the turn's ``view`` event and is stored with the reply, like any view.
+
+Its receipt carries the totals, shares and overall averages the transform
+computed, and every repair or kind change it made, so the reply quotes
+numbers instead of working them out. Like ``find_suspects`` it reads the
+index in process, so it is offered on the local backend only.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from typing import Any
+from uuid import uuid4
+
+from repowise.server import chat_spec
+from repowise.server.chat_chart_part import ChartSource, chart_part
+from repowise.server.chat_datasets import catalog, dataset_names, get_dataset, load_rows
+from repowise.server.chat_references import CHART_TOOL
+from repowise.server.chat_views import (
+ TurnViews,
+ ViewError,
+ args_hash,
+ finish_part,
+ part_receipt,
+)
+
+logger = logging.getLogger(__name__)
+
+_NAME_OR_LIST = {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}]}
+
+
+def chart_schema() -> dict[str, Any]:
+ """OpenAI-format definition of the ``chart`` tool, listing each dataset's fields."""
+ names = dataset_names()
+ lines = [f"{name}: {', '.join(get_dataset(name).fields)}" for name in names]
+ kinds = [k for k in chat_spec.KINDS if k != "auto"]
+ return {
+ "type": "function",
+ "function": {
+ "name": CHART_TOOL,
+ "description": (
+ "Draw a chart or table of repository data in one call. The server reads "
+ "every row of the dataset, filters, groups and draws it, and returns the "
+ "exact totals, shares and averages to quote. Datasets and fields:\n"
+ + "\n".join(lines)
+ + "\nCall with only `dataset` for what each field means and an example. "
+ + chat_spec.SPEC_HELP
+ ),
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "dataset": {"type": "string", "enum": names},
+ "x": _NAME_OR_LIST,
+ "y": _NAME_OR_LIST,
+ "aggregate": {"type": "string", "enum": list(chat_spec.AGGREGATES)},
+ "series": {"type": "string"},
+ "filter": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "field": {"type": "string"},
+ "op": {"type": "string", "enum": list(chat_spec.OPS)},
+ "value": {},
+ },
+ "required": ["field", "value"],
+ },
+ },
+ "sort": {
+ "type": "object",
+ "properties": {
+ "field": {"type": "string"},
+ "order": {"type": "string", "enum": ["asc", "desc"]},
+ },
+ },
+ "top": {"type": "integer", "minimum": 1},
+ "other": {
+ "type": "boolean",
+ "description": "Add up the rows past top as Other.",
+ },
+ "kind": {"type": "string", "enum": kinds},
+ "color": {"type": "string"},
+ "weight": {
+ "type": "string",
+ "description": "A field an avg is weighted by, or none for a plain mean.",
+ },
+ "title": {"type": "string"},
+ },
+ "required": ["dataset"],
+ },
+ },
+ }
+
+
+def _discovery(name: str | None) -> dict[str, Any]:
+ entries = catalog()
+ if name is not None:
+ entries = [e for e in entries if e["dataset"] == name]
+ return {"datasets": entries}
+
+
+async def run_chart(
+ arguments: Mapping[str, Any], repo: str | None, views: TurnViews
+) -> dict[str, Any]:
+ """Run ``chart``: a receipt on success, an error payload (with a fix) otherwise."""
+ name = arguments.get("dataset")
+ dataset = get_dataset(name) if isinstance(name, str) else None
+ if dataset is None:
+ return {
+ "error": f"no dataset {name!r}; datasets: {dataset_names()}",
+ "error_code": "unknown_dataset",
+ }
+ options = {k: v for k, v in arguments.items() if k != "dataset"}
+ if options.get("x") is None:
+ # Discovery: the fields and an example, nothing drawn.
+ return _discovery(name)
+ try:
+ loaded = await load_rows(name, repo)
+ except Exception as exc: # a read failure is the model's to report, not the turn's end
+ return {"error": f"{type(exc).__name__}: {exc}", "error_code": "tool_failed"}
+ source = ChartSource(
+ rows=loaded.rows,
+ what=dataset.noun,
+ basis={"kind": dataset.basis[0], "source": dataset.basis[1]},
+ meta=dataset.fields,
+ hierarchy=dataset.hierarchy,
+ example=dataset.example,
+ )
+ try:
+ part = finish_part(
+ chart_part(source, options),
+ part_id=views.next_id(),
+ source={
+ "artifact_id": uuid4().hex,
+ "tool_name": CHART_TOOL,
+ "args_hash": args_hash(arguments),
+ },
+ stale=loaded.stale,
+ as_of=loaded.as_of,
+ )
+ extra = part.pop("receipt", None) or {}
+ views.keep(part)
+ except ViewError as exc:
+ payload = exc.payload()
+ if isinstance(payload.get("suggested_spec"), Mapping):
+ payload["suggested_spec"] = {"dataset": name, **payload["suggested_spec"]}
+ return payload
+ except Exception:
+ logger.exception("chat_chart_failed", extra={"dataset": name})
+ return ViewError("the chart builder failed", code="builder_failed").payload()
+ return {**part_receipt(part), **extra}
+
+
+__all__ = ["CHART_TOOL", "chart_schema", "run_chart"]
diff --git a/packages/server/src/repowise/server/chat_chart_part.py b/packages/server/src/repowise/server/chat_chart_part.py
new file mode 100644
index 000000000..1da692d62
--- /dev/null
+++ b/packages/server/src/repowise/server/chat_chart_part.py
@@ -0,0 +1,381 @@
+"""Rows and a chart spec to a chart or table part, shared by ``show_view``'s
+``chart`` view and the chat-only ``chart`` tool, and an earlier view redrawn.
+
+Spec errors come back with a ``suggested_spec`` that was itself run, so the
+model can resend it as is.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from repowise.server import chat_spec
+from repowise.server.chat_spec import SpecError
+from repowise.server.chat_spec import label as _label
+from repowise.server.chat_spec.fit import _repair_name
+from repowise.server.chat_views import (
+ _ATTRIBUTION,
+ _PERSON,
+ _RISK_SCORE,
+ ViewError,
+ _cell,
+ _wire,
+ finish_part,
+)
+from repowise.server.schemas.views import (
+ VIEW_LIMITS,
+)
+
+
+def _spec_error(
+ exc: SpecError, suggested: tuple[dict[str, Any], list[str]] | None = None
+) -> ViewError:
+ extra: dict[str, Any] = {"fields": exc.fields} if exc.fields else {}
+ if suggested is not None:
+ extra["suggested_spec"], extra["adjustments"] = dict(suggested[0]), suggested[1]
+ return ViewError(str(exc), code=exc.code, **extra)
+
+
+@dataclass(frozen=True)
+class ChartSource:
+ """The rows a chart is drawn over, and what they are."""
+
+ rows: list[dict[str, Any]]
+ #: Names the rows in the summary: "files", "rows of tiers.medium.findings".
+ what: str
+ basis: dict[str, str]
+ #: Rows the source holds when the rows given are fewer (a capped tool list).
+ total: int | None = None
+ #: Declared fields (``aggregates``, ``weight``, ``unit``), when a dataset gives them.
+ meta: Mapping[str, Any] = field(default_factory=dict)
+ hierarchy: tuple[str, ...] = ()
+ #: A spec known to chart these rows, the last resort of a ``suggested_spec``.
+ example: Mapping[str, Any] | None = None
+ #: The result path the rows came from; the guards read its segments too.
+ path: tuple[str, ...] = ()
+
+
+def _check_names(names: list[str], path: tuple[str, ...]) -> None:
+ for name in names:
+ if _PERSON.search(name):
+ raise ViewError(
+ f"views never group or filter by person ({name!r})", code="person_grouping"
+ )
+ for name in [*names, *path]:
+ if _ATTRIBUTION.search(name):
+ # Deliberate ceiling: no coverage check per row here, so these are
+ # refused; changes.provenance draws them with their coverage.
+ raise ViewError(
+ f"attribution figures ({name!r}) are shown only by changes.provenance, "
+ "which checks their coverage",
+ code="attribution_figure",
+ )
+
+
+def _plan(
+ source: ChartSource, options: Mapping[str, Any]
+) -> tuple[chat_spec.ChartSpec, chat_spec.ChartRows]:
+ spec = chat_spec.parse_spec(options)
+ _check_names(spec.fields(), source.path)
+ types = {
+ k: t for k, t in chat_spec.field_types(source.rows).items() if not _PERSON.search(k)
+ }
+ spec = chat_spec.fit(spec, source.rows, types, source.meta, source.hierarchy)
+ _check_names(spec.fields(), ())
+ numeric_x = not spec.x_parts and types.get(spec.x) == "number"
+ plotted = [*spec.y, *([spec.series] if spec.series else []), *([spec.x] if numeric_x else [])]
+ if spec.color and types.get(spec.color) == "number":
+ plotted.append(spec.color)
+ for name in plotted:
+ if _RISK_SCORE.search(name):
+ raise ViewError(
+ f"a risk score is never a chart series ({name!r}); show it in a table",
+ code="risk_score_series",
+ )
+ return spec, chat_spec.transform(spec, source.rows, types)
+
+
+def _closest(name: Any, types: Mapping[str, str]) -> str | None:
+ """*name* as a field: the same near-miss rule ``fit`` reads names by, nothing looser."""
+ return _repair_name(name, types) if isinstance(name, str) else None
+
+
+def _repaired(
+ options: Mapping[str, Any], types: Mapping[str, str]
+) -> tuple[dict[str, Any], list[str]] | None:
+ """*options* with near-miss field names swapped for the field, and what was changed.
+
+ None when a name has no near miss: a guessed field would chart another
+ measure, so the error stands with the fields listed instead.
+ """
+ fixed, changed = dict(options), []
+
+ def swap(name: Any, role: str) -> str | None:
+ found = _closest(name, types)
+ if found is not None and found != name:
+ changed.append(f"{role} {name!r} read as {found!r}")
+ return found
+
+ for key in ("x", "y", "groups"):
+ value = fixed.get(key)
+ if value is None:
+ continue
+ names = value if isinstance(value, list) else [value]
+ kept = [swap(n, key) for n in names]
+ if None in kept:
+ return None
+ fixed[key] = kept if isinstance(value, list) else kept[0]
+ for key in ("series", "weight", "color"):
+ if key in fixed and not (key == "weight" and str(fixed[key]).lower() == "none"):
+ name = swap(fixed[key], key)
+ if name is None:
+ return None
+ fixed[key] = name
+ filters = fixed.get("filter")
+ if isinstance(filters, (list, Mapping)):
+ kept_filters = []
+ for f in [filters] if isinstance(filters, Mapping) else filters:
+ name = swap(f.get("field"), "filter field") if isinstance(f, Mapping) else None
+ if name is None:
+ return None
+ kept_filters.append({**f, "field": name})
+ fixed["filter"] = kept_filters
+ return fixed, changed
+
+
+#: What each fallback gives up, in the order they are tried.
+_DROPS: tuple[tuple[tuple[str, ...], str], ...] = (
+ ((), ""),
+ (("kind",), "kind dropped, so the kind is picked from the data"),
+ (("sort", "top", "other"), "sort, top and other dropped"),
+ (("filter",), "filter dropped, so every row is charted"),
+ (("series",), "series dropped, so the chart is not split"),
+)
+
+
+def _suggest(
+ source: ChartSource, options: Mapping[str, Any]
+) -> tuple[dict[str, Any], list[str]] | None:
+ """A spec that draws, close to *options*, and every way it differs from them.
+
+ Each candidate is run, so a suggestion is never itself an error. Names are
+ repaired only by the near-miss rule; a dropped filter, series or kind is
+ always listed in the adjustments, so the model can tell the user. Last
+ comes the source's own example, said to be one.
+ """
+ types = chat_spec.field_types(source.rows)
+ repaired = _repaired(options, types)
+ candidates: list[tuple[dict[str, Any], list[str]]] = []
+ if repaired is not None:
+ base, changed = repaired
+ for keys, why in _DROPS:
+ if keys and not any(k in base for k in keys):
+ continue
+ candidate = {k: v for k, v in base.items() if k not in keys}
+ candidates.append((candidate, [*changed, *([why] if why else [])]))
+ if source.example is not None:
+ example = {**dict(source.example), **({"rows": options["rows"]} if "rows" in options else {})}
+ candidates.append((example, ["the dataset's example in place of this spec"]))
+ for candidate, changed in candidates:
+ if candidate == dict(options):
+ continue
+ try:
+ _plan(source, candidate)
+ except (SpecError, ViewError):
+ continue
+ return candidate, changed
+ return None
+
+
+def _refuse_risk(source: ChartSource, options: Mapping[str, Any]) -> None:
+ """A risk score asked for as a plotted value is refused before anything is suggested."""
+ types = chat_spec.field_types(source.rows)
+ asked: list[Any] = []
+ for key in ("y", "series", "color"):
+ value = options.get(key)
+ asked.extend(value if isinstance(value, list) else [value])
+ x = options.get("x")
+ if isinstance(x, str) and types.get(x) == "number":
+ asked.append(x)
+ for name in asked:
+ if isinstance(name, str) and _RISK_SCORE.search(name):
+ raise ViewError(
+ f"a risk score is never a chart series ({name!r}); show it in a table",
+ code="risk_score_series",
+ )
+
+
+def _units(spec: chat_spec.ChartSpec, meta: Mapping[str, Any]) -> str | None:
+ """The plotted columns' one unit, when the fields declare one they share."""
+ if spec.aggregate == "count":
+ return None
+ units = {getattr(meta.get(y), "unit", None) for y in spec.y}
+ return units.pop() if len(units) == 1 else None
+
+
+def _n(value: Any) -> str:
+ """A number as a summary writes it: digits grouped, averages to two places."""
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
+ return str(value)
+ if isinstance(value, float) and not value.is_integer():
+ return f"{value:,.2f}"
+ return f"{int(value):,}"
+
+
+def chart_part(source: ChartSource, options: Mapping[str, Any]) -> dict[str, Any]:
+ """A chart (or table) part from *source*'s rows by the spec in *options*, with its receipt.
+
+ Shared by ``show_view``'s ``chart`` view and the ``chart`` tool. Raises
+ ``ViewError``; a spec error carries a ``suggested_spec`` when one draws.
+ """
+ _refuse_risk(source, options)
+ try:
+ spec, result = _plan(source, options)
+ except SpecError as exc:
+ raise _spec_error(exc, _suggest(source, options)) from None
+
+ def cell(key: str, value: Any) -> Any:
+ value = _cell(key, value) if key not in result.series else _wire(value)
+ if isinstance(value, float) and not value.is_integer():
+ # Rows keep full precision for exact averages; a cell reads at two places.
+ return round(value, 2)
+ return None if value is ... else value
+
+ figures = result.figures
+ x_label = _label(spec.x) if not spec.x_parts else dict(result.columns).get(spec.x, spec.x)
+ drawn = result.matched - result.missing_x
+ grouped = bool(spec.aggregate) and figures.get("groups", drawn) < drawn
+ shown = (
+ f"{_n(result.matched)} of {_n(result.source_rows)}"
+ if spec.filters
+ else _n(result.source_rows)
+ )
+ summary = f"{shown} {source.what}"
+ if grouped:
+ summary += f", grouped by {x_label.lower()} into {_n(figures['groups'])}"
+ summary += "."
+ if grouped and spec.aggregate == "sum" and "total" in figures:
+ measures = " and ".join(_label(y).lower() for y in spec.y)
+ summary += f" Total {measures}: {_n(figures['total'])}."
+ for name, value in (figures.get("overall") or {}).items():
+ if grouped and value is not None:
+ weighted = f", weighted by {_label(spec.weight).lower()}" if spec.weight else ""
+ summary += f" {name} across them: {_n(value)}{weighted}."
+ if result.total_rows > len(result.rows) and not result.other:
+ summary += f" Showing {_n(len(result.rows))} of {_n(result.total_rows)}."
+ figures["drawn"] = len(result.rows)
+ if result.missing_x:
+ summary += f" {_n(result.missing_x)} without {x_label.lower()} are left out."
+ if result.other:
+ summary += f" {chat_spec.OTHER_LABEL} adds up the rest."
+ if source.total is not None and source.total > len(source.rows):
+ summary += (
+ f" The tool returned {len(source.rows)} of {source.total} rows; "
+ "the chart covers those only."
+ )
+ unit = _units(spec, source.meta)
+ columns = [
+ {"key": k, "label": label, **({"unit": unit} if unit and k in result.series else {})}
+ for k, label in result.columns
+ ]
+ rows = [{k: cell(k, v) for k, v in row.items()} for row in result.rows]
+ title = spec.title or chat_spec.default_title(spec)
+ summary = f"{spec.subtitle} {summary}" if spec.subtitle else summary
+ receipt: dict[str, Any] = {"reason": result.reason}
+ if result.kind_note:
+ receipt["kind_note"] = result.kind_note
+ if result.notes:
+ receipt["notes"] = result.notes
+ receipt["figures"] = figures
+ if result.chart_type == "table":
+ return {
+ "kind": "table",
+ "title": title,
+ "summary": summary,
+ "basis": source.basis,
+ "columns": columns[: VIEW_LIMITS["columns"]],
+ "rows": [
+ {c["key"]: row.get(c["key"]) for c in columns[: VIEW_LIMITS["columns"]]}
+ for row in rows
+ ],
+ "total_rows": result.total_rows,
+ "truncated": result.total_rows > len(rows),
+ "receipt": receipt,
+ }
+ part: dict[str, Any] = {
+ "kind": "chart",
+ "chart_type": result.chart_type,
+ "title": title,
+ "summary": summary,
+ "basis": source.basis,
+ "x": result.x,
+ "series": result.series,
+ "data": {
+ "columns": columns,
+ "rows": rows,
+ "total_rows": result.total_rows,
+ "truncated": result.total_rows > len(result.rows),
+ },
+ "receipt": {"chart_type": result.chart_type, **receipt},
+ }
+ if result.sort:
+ part["sort"] = result.sort
+ if result.chart_type == "treemap":
+ if result.groups:
+ part["groups"] = result.groups
+ if result.color:
+ part["color"] = result.color
+ return part
+
+
+def redraw(part: Mapping[str, Any], options: Any, *, part_id: str) -> dict[str, Any]:
+ """An earlier chart drawn again as ``options.kind``: another chart type, or its table.
+
+ Its rows and provenance are the earlier part's; only the form changes, and
+ the part is validated again, so a kind the rows cannot take is refused.
+ """
+ asked = options.get("kind") if isinstance(options, Mapping) else None
+ if asked is None:
+ raise ViewError("pass options.kind: the kind to draw this view as", code="bad_arguments")
+ try:
+ kind, _ = chat_spec.read_kind(asked)
+ except SpecError as exc:
+ raise ViewError(str(exc), code="bad_arguments") from None
+ if part.get("kind") != "chart":
+ raise ViewError(
+ "only a chart can be redrawn; call chart with kind table or another kind",
+ code="bad_arguments",
+ )
+ copy = {
+ k: v
+ for k, v in part.items()
+ if k not in ("id", "schema_version", "source", "stale", "as_of", "groups", "color", "sort")
+ }
+ if kind == "table":
+ for key in ("chart_type", "x", "series", "data"):
+ copy.pop(key, None)
+ copy.update(kind="table", **part["data"])
+ elif kind != "auto":
+ copy["chart_type"] = kind
+ if kind == "treemap":
+ copy.update({k: part[k] for k in ("groups", "color") if k in part})
+ if isinstance(options.get("title"), str) and options["title"].strip():
+ copy["title"] = options["title"].strip()
+ if kind in ("bar", "horizontal_bar", "stacked_bar", "line", "area") and "sort" in part:
+ copy["sort"] = part["sort"]
+ try:
+ return finish_part(
+ copy,
+ part_id=part_id,
+ source=part["source"],
+ stale=bool(part.get("stale")),
+ as_of=part.get("as_of"),
+ what=f"a {kind}",
+ )
+ except ViewError as exc:
+ raise ViewError(
+ f"{exc}; call chart with the spec and kind {kind} to draw it from the data",
+ code=exc.code,
+ ) from None
diff --git a/packages/server/src/repowise/server/chat_datasets/__init__.py b/packages/server/src/repowise/server/chat_datasets/__init__.py
new file mode 100644
index 000000000..95a904c41
--- /dev/null
+++ b/packages/server/src/repowise/server/chat_datasets/__init__.py
@@ -0,0 +1,253 @@
+"""Chart datasets for chat: whole tables read from the local index, one row per thing.
+
+The chat-only ``chart`` tool (:mod:`repowise.server.chat_chart`) charts a
+dataset in one call, so the model never has to find a list inside a tool's
+JSON or copy an artifact id. Each dataset declares its fields (type, one-line
+meaning, the aggregations that are valid on it) and a loader that reads the
+index with the same queries the MCP tools and REST services use. Every row is
+kept: the chart transform filters and aggregates server-side.
+
+Rows are cached per repository and index state (``index_state_key``), so a
+conversation's second chart over the same dataset costs no query. Datasets are
+registered on the ``chat-dataset`` seam, so a plugin adds one without editing
+this package. No dataset holds a person, a risk score or an attribution
+figure: the view guards would refuse them anyway, and a dataset that never
+loads them cannot leak them into a filter.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib
+from collections import OrderedDict
+from collections.abc import Awaitable, Callable, Iterable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from repowise.core.registry.plugins import SeamRegistry, load_plugins
+from repowise.server.chat_spec import ARROW
+
+#: Aggregations a numeric field takes; the first is the one used when rows must combine.
+SUMS = ("sum", "avg", "min", "max")
+AVERAGES = ("avg", "min", "max")
+#: Text fields are grouped and counted, never added up.
+TEXT = ()
+
+_CACHE_LIMIT = 32
+
+
+@dataclass(frozen=True)
+class DatasetField:
+ """One column of a dataset: its type, what it means, and how it combines."""
+
+ type: str # "text", "number", "time" or "bool"
+ meaning: str
+ aggregates: tuple[str, ...] = TEXT
+ #: A numeric field whose ``avg`` is weighted by this field (coverage by coverable lines).
+ weight: str | None = None
+ #: A date field's calendar step ("week"): a grouped chart fills empty steps with zero.
+ step: str | None = None
+ #: The least weight one row carries, as the field's own surface floors it.
+ weight_floor: float | None = None
+ unit: str | None = None
+
+
+@dataclass(frozen=True)
+class LoadContext:
+ """What a loader reads with: one session, the repository row and its root."""
+
+ session: Any
+ repository: Any
+ repo_path: str
+ #: Rows of another dataset, from the same cache (``files`` maps paths to packages).
+ rows: Callable[[str], Awaitable[list[dict[str, Any]]]]
+
+
+@dataclass(frozen=True)
+class Dataset:
+ name: str
+ description: str
+ fields: Mapping[str, DatasetField]
+ load: Callable[[LoadContext], Awaitable[list[dict[str, Any]]]]
+ #: ``(kind, source)`` of the values, as a view's basis.
+ basis: tuple[str, str]
+ #: A spec that charts this dataset, offered when a spec cannot be repaired.
+ example: Mapping[str, Any]
+ #: Text fields from coarse to fine; a treemap nests by the ones above its x.
+ hierarchy: tuple[str, ...] = ()
+ #: What one row is, plural, for a chart's summary ("files", "changes").
+ noun: str = "rows"
+
+
+datasets: SeamRegistry[Dataset] = SeamRegistry("chat-dataset")
+
+# Built-in families, imported for their registrations on first use.
+_FAMILIES = ("files", "findings", "history", "architecture")
+
+
+def register_dataset(
+ name: str,
+ *,
+ description: str,
+ fields: Mapping[str, DatasetField],
+ basis: tuple[str, str],
+ example: Mapping[str, Any],
+ hierarchy: Iterable[str] = (),
+ noun: str = "rows",
+) -> Callable[[Callable[[LoadContext], Awaitable[list[dict[str, Any]]]]], Any]:
+ """Register a loader as dataset *name*; the function is returned unchanged."""
+
+ def decorate(fn: Callable[[LoadContext], Awaitable[list[dict[str, Any]]]]) -> Any:
+ datasets.register(
+ name,
+ Dataset(
+ name=name,
+ description=description,
+ fields=dict(fields),
+ load=fn,
+ basis=basis,
+ example=dict(example),
+ hierarchy=tuple(hierarchy),
+ noun=noun,
+ ),
+ )
+ return fn
+
+ return decorate
+
+
+def dataset_names() -> list[str]:
+ for family in _FAMILIES:
+ importlib.import_module(f"{__name__}.{family}")
+ load_plugins()
+ return datasets.names
+
+
+def get_dataset(name: str) -> Dataset | None:
+ return datasets.get(name) if name in dataset_names() else None
+
+
+def catalog() -> list[dict[str, Any]]:
+ """Every dataset with its fields, for the ``chart`` tool's discovery mode."""
+ out = []
+ for name in dataset_names():
+ ds = datasets.get(name)
+ out.append(
+ {
+ "dataset": name,
+ "about": ds.description,
+ "fields": {key: _field_line(f) for key, f in ds.fields.items()},
+ "example": ds.example,
+ }
+ )
+ return out
+
+
+def _field_line(f: DatasetField) -> str:
+ line = f"{f.type}: {f.meaning}"
+ if f.aggregates:
+ line += f" [{', '.join(f.aggregates)}]"
+ if f.weight:
+ line += f" (avg weighted by {f.weight})"
+ return line
+
+
+# ---------------------------------------------------------------------------
+# Rows, cached per index state
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class DatasetRows:
+ rows: list[dict[str, Any]]
+ #: The index commit the rows were read at, and whether the code moved past it.
+ as_of: str | None
+ stale: bool
+ cached: bool = False
+
+
+#: Rows by ``(repository id, index state, dataset)``, oldest first, so the
+#: oldest is the one evicted at the cap.
+_cache: OrderedDict[tuple[str, str, str], list[dict[str, Any]]] = OrderedDict()
+_locks: dict[tuple[str, str, str], asyncio.Lock] = {}
+
+
+def _store(key: tuple[str, str, str], rows: list[dict[str, Any]]) -> None:
+ """Keep *rows*: a repository's older index states go, then the oldest past the cap."""
+ repo_id, state, _ = key
+ for old in [k for k in _cache if k[0] == repo_id and k[1] != state]:
+ del _cache[old]
+ _cache[key] = rows
+ while len(_cache) > _CACHE_LIMIT:
+ _cache.popitem(last=False)
+
+
+async def load_rows(name: str, repo: str | None) -> DatasetRows:
+ """Every row of dataset *name* for the repository *repo* names (None: the served one).
+
+ Rows are cached per index state; the freshness (``as_of``, ``stale``) is
+ read on every call, since the checkout can move while the index stays put.
+ """
+ from repowise.core.persistence.database import get_session
+ from repowise.server.mcp_server._helpers import _get_repo, _resolve_repo_context
+ from repowise.server.mcp_server._index_state import index_state_key
+
+ ctx = await _resolve_repo_context(repo)
+ async with get_session(ctx.session_factory) as session:
+ repository = await _get_repo(session)
+ state = index_state_key(repository)
+ repo_path = str(ctx.path)
+ hit = (repository.id, state, name) in _cache
+
+ async def rows(dataset: str) -> list[dict[str, Any]]:
+ key = (repository.id, state, dataset)
+ if key in _cache:
+ return _cache[key]
+ lock = _locks.setdefault(key, asyncio.Lock())
+ try:
+ async with lock:
+ if key not in _cache:
+ ds = get_dataset(dataset)
+ if ds is None:
+ raise KeyError(dataset)
+ _store(key, await ds.load(LoadContext(session, repository, repo_path, rows)))
+ finally:
+ # A failed load leaves no lock behind, so the next call reads again.
+ _locks.pop(key, None)
+ return _cache[key]
+
+ loaded = await rows(name)
+ as_of, stale = _fresh(repository)
+ return DatasetRows(rows=loaded, as_of=as_of, stale=stale, cached=hit)
+
+
+def _fresh(repository: Any) -> tuple[str | None, bool]:
+ """The indexed commit and the stale flag ``_meta`` reports for *repository* now."""
+ from repowise.server.mcp_server._meta import build_meta
+
+ meta = build_meta(repository=repository)
+ commit = meta.get("indexed_commit")
+ return commit if isinstance(commit, str) else None, bool(meta.get("stale_warning"))
+
+
+def clear_cache() -> None:
+ _cache.clear()
+
+
+__all__ = [
+ "ARROW",
+ "AVERAGES",
+ "SUMS",
+ "TEXT",
+ "Dataset",
+ "DatasetField",
+ "DatasetRows",
+ "LoadContext",
+ "catalog",
+ "clear_cache",
+ "dataset_names",
+ "datasets",
+ "get_dataset",
+ "load_rows",
+ "register_dataset",
+]
diff --git a/packages/server/src/repowise/server/chat_datasets/architecture.py b/packages/server/src/repowise/server/chat_datasets/architecture.py
new file mode 100644
index 000000000..2c7b582fb
--- /dev/null
+++ b/packages/server/src/repowise/server/chat_datasets/architecture.py
@@ -0,0 +1,85 @@
+"""The ``dependencies`` and ``layers`` datasets: how the code is put together.
+
+``dependencies`` is every package-to-package edge of the container view (the
+roll-up get_overview's dependency block shows its top ten of); ``layers`` is
+the architecture layers get_overview lists, in stack order.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from repowise.server.chat_datasets import (
+ ARROW,
+ SUMS,
+ DatasetField,
+ LoadContext,
+ register_dataset,
+)
+
+
+@register_dataset(
+ "dependencies",
+ description="One row per package-to-package dependency edge (get_overview's dependencies).",
+ fields={
+ "edge": DatasetField("text", f"the edge as 'from {ARROW} to', for labels"),
+ "from_package": DatasetField("text", "the package that depends"),
+ "to_package": DatasetField("text", "the package it depends on"),
+ "weight": DatasetField("number", "file pairs behind the edge (test files add none)", SUMS),
+ "coupling": DatasetField("text", "loose, moderate or tight"),
+ },
+ basis=("inferred", "import graph"),
+ example={"x": "edge", "y": "weight", "top": 10},
+ noun="dependency edges",
+)
+async def load_dependencies(ctx: LoadContext) -> list[dict[str, Any]]:
+ from repowise.server.mcp_server._helpers import _get_exclude_spec
+ from repowise.server.services.c4_builder import container_dependencies
+
+ containers, relations = await container_dependencies(
+ ctx.session, ctx.repository.id, exclude_spec=_get_exclude_spec(ctx.repo_path)
+ )
+ path_of = {c.id: c.path or "." for c in containers}
+ return [
+ {
+ "edge": f"{path_of[r.source_id]} {ARROW} {path_of[r.target_id]}",
+ "from_package": path_of[r.source_id],
+ "to_package": path_of[r.target_id],
+ "weight": r.edge_count,
+ "coupling": r.coupling,
+ }
+ for r in relations
+ if r.source_id in path_of and r.target_id in path_of
+ ]
+
+
+@register_dataset(
+ "layers",
+ description="One row per architecture layer, in stack order (get_overview's layers).",
+ fields={
+ "layer": DatasetField("text", "the layer's name"),
+ "files": DatasetField("number", "files in the layer", SUMS, unit="files"),
+ "order": DatasetField("number", "the layer's place in the stack, top first", ("min",)),
+ },
+ basis=("inferred", "knowledge graph"),
+ example={"x": "layer", "y": "files"},
+ noun="layers",
+)
+async def load_layers(ctx: LoadContext) -> list[dict[str, Any]]:
+ from repowise.core.generation.layers import is_adjacent_layer
+ from repowise.core.persistence.crud.knowledge_graph import get_kg_layers
+
+ layers = [
+ layer
+ for layer in await get_kg_layers(ctx.session, ctx.repository.id)
+ if not is_adjacent_layer(layer.layer_id)
+ ]
+ return [
+ {
+ "layer": layer.name,
+ "files": len(json.loads(layer.node_ids_json) if layer.node_ids_json else []),
+ "order": i + 1,
+ }
+ for i, layer in enumerate(layers)
+ ]
diff --git a/packages/server/src/repowise/server/chat_datasets/files.py b/packages/server/src/repowise/server/chat_datasets/files.py
new file mode 100644
index 000000000..9030a0f36
--- /dev/null
+++ b/packages/server/src/repowise/server/chat_datasets/files.py
@@ -0,0 +1,278 @@
+"""The ``files`` and ``coverage`` datasets: one row per indexed file.
+
+``files`` joins what get_health, get_risk and the coverage report each hold
+per file, so "worst files by health", "health against coverage" and "fixes
+per package" are one chart. Rows come from the same reads get_health makes
+(``HealthFileMetric`` under the health exclude rule), git metadata's own
+columns, and the coverage report's per-file rows.
+"""
+
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from collections.abc import Iterable
+from typing import Any
+
+from sqlalchemy import select
+
+from repowise.server.chat_datasets import (
+ AVERAGES,
+ SUMS,
+ DatasetField,
+ LoadContext,
+ register_dataset,
+)
+
+ROOT_PACKAGE = "(root)"
+#: A child holding at least this share of a level's files is a wrapper to look past.
+_WRAPPER_SHARE = 0.7
+
+_PACKAGE = DatasetField("text", "the package the file belongs to (its nearest manifest root)")
+_DIRECTORY = DatasetField(
+ "text", "a directory one level inside the package, below any path every file shares"
+)
+_FILE = DatasetField("text", "the file's shortest unique path suffix, for labels")
+_PATH = DatasetField("text", "the file's full repository path")
+
+FILES_FIELDS = {
+ "path": _PATH,
+ "file": _FILE,
+ "package": _PACKAGE,
+ "directory": _DIRECTORY,
+ "language": DatasetField("text", "the file's language"),
+ "health_score": DatasetField(
+ "number",
+ "maintainability health, 0 (worst) to 10; null when unscored",
+ AVERAGES,
+ # As nloc_weighted_score averages it, so the repo figure is get_health's.
+ weight="nloc",
+ weight_floor=1,
+ unit="score",
+ ),
+ "health_band": DatasetField(
+ "text", "at risk, needs work, fair, good or excellent; null when unscored"
+ ),
+ "nloc": DatasetField("number", "lines of code, without blanks and comments", SUMS, unit="lines"),
+ "max_ccn": DatasetField("number", "highest cyclomatic complexity of a function in the file", ("max", "avg", "sum")),
+ "commits_90d": DatasetField("number", "commits touching the file in the last 90 days", SUMS, unit="commits"),
+ "fix_count": DatasetField(
+ "number", "bug-fix commits on the file's production code in about 6 months", SUMS, unit="fixes"
+ ),
+ "coverage_pct": DatasetField(
+ "number", "measured line coverage, 0 to 100; null when no report covers it",
+ AVERAGES, weight="coverable_lines", unit="%",
+ ),
+ "coverable_lines": DatasetField("number", "lines the coverage report can measure", SUMS, unit="lines"),
+ "is_hotspot": DatasetField("bool", "high churn and complexity, by git history"),
+ "is_test": DatasetField("bool", "a test file"),
+ "is_production": DatasetField("bool", "in the fix-first scope: not test, tooling, vendored or generated"),
+}
+
+COVERAGE_FIELDS = {
+ "path": _PATH,
+ "file": _FILE,
+ "package": _PACKAGE,
+ "directory": _DIRECTORY,
+ "coverage_pct": DatasetField(
+ "number", "measured line coverage, 0 to 100", AVERAGES, weight="coverable_lines", unit="%"
+ ),
+ "covered_lines": DatasetField("number", "lines the tests ran", SUMS, unit="lines"),
+ "coverable_lines": DatasetField("number", "lines the report can measure", SUMS, unit="lines"),
+}
+
+
+# ---------------------------------------------------------------------------
+# Path helpers shared by every per-file dataset
+# ---------------------------------------------------------------------------
+
+
+def unique_suffixes(paths: Iterable[str]) -> dict[str, str]:
+ """Each path's shortest trailing run of segments no other path ends with."""
+ parts = {p: p.split("/") for p in dict.fromkeys(paths)}
+ depth = max((len(s) for s in parts.values()), default=0)
+ counts = [Counter("/".join(s[-k:]) for s in parts.values()) for k in range(1, depth + 1)]
+ out: dict[str, str] = {}
+ for path, segments in parts.items():
+ for k in range(1, len(segments) + 1):
+ label = "/".join(segments[-k:])
+ if counts[k - 1][label] == 1 or k == len(segments):
+ out[path] = label
+ break
+ return out
+
+
+def directories(packages: dict[str, str]) -> dict[str, str]:
+ """Each file's directory one level inside its package, past wrapper levels.
+
+ A level where one child holds most of the files (``src/repowise/core``
+ holding nearly all of ``packages/core``) tells a chart nothing, so those
+ files descend through it; the rest stop at their own child of that level.
+ """
+ by_package: dict[str, list[str]] = defaultdict(list)
+ for path, package in packages.items():
+ by_package[package].append(path)
+ out: dict[str, str] = {}
+ for package, paths in by_package.items():
+ root = "" if package == ROOT_PACKAGE else package
+ rel = {p: (p[len(root) + 1 :] if root and p.startswith(root + "/") else p) for p in paths}
+ _descend(root or package, root, {p: r.split("/")[:-1] for p, r in rel.items()}, out)
+ return out
+
+
+def _descend(package: str, base: str, dirs: dict[str, list[str]], out: dict[str, str]) -> None:
+ children = Counter(d[0] for d in dirs.values() if d)
+ top, n = children.most_common(1)[0] if children else ("", 0)
+ if n and n >= _WRAPPER_SHARE * len(dirs) and n > 1:
+ inner = {p: d[1:] for p, d in dirs.items() if d and d[0] == top}
+ _descend(package, f"{base}/{top}" if base else top, inner, out)
+ dirs = {p: d for p, d in dirs.items() if p not in inner}
+ for path, d in dirs.items():
+ out[path] = (f"{base}/{d[0]}" if base else d[0]) if d else (base or package)
+
+
+def place(paths: Iterable[str], files: dict[str, dict[str, Any]]) -> dict[str, tuple[str, str]]:
+ """``(package, directory)`` for paths a dataset holds: the files dataset's, else the top level."""
+ known = {p: (files[p]["package"], files[p]["directory"]) for p in paths if p in files}
+ unknown = {p: _top_level(p) for p in paths if p not in files}
+ dirs = directories(unknown)
+ return {**known, **{p: (unknown[p], dirs[p]) for p in unknown}}
+
+
+def _top_level(path: str) -> str:
+ head, sep, _ = path.partition("/")
+ return head if sep else ROOT_PACKAGE
+
+
+async def files_index(ctx: LoadContext) -> dict[str, dict[str, Any]]:
+ """The files dataset by path, for datasets that place rows by file."""
+ return {row["path"]: row for row in await ctx.rows("files")}
+
+
+# ---------------------------------------------------------------------------
+# Loaders
+# ---------------------------------------------------------------------------
+
+
+async def _coverage_rows(session: Any, repo_id: str) -> list[Any]:
+ from repowise.core.persistence.crud.analysis.plain_rows import plain_rows
+ from repowise.core.persistence.models import CoverageFile
+
+ q = select(
+ CoverageFile.file_path,
+ CoverageFile.line_coverage_pct,
+ CoverageFile.total_coverable_lines,
+ CoverageFile.covered_line_count,
+ ).where(CoverageFile.repository_id == repo_id)
+ return plain_rows(await session.execute(q))
+
+
+@register_dataset(
+ "files",
+ description="One row per indexed file: health, size, complexity, churn, fixes, coverage.",
+ fields=FILES_FIELDS,
+ basis=("inferred", "health engine and git history"),
+ example={"x": "file", "y": "health_score", "sort": {"field": "health_score", "order": "asc"}, "top": 15},
+ hierarchy=("package", "directory", "file"),
+ noun="files",
+)
+async def load_files(ctx: LoadContext) -> list[dict[str, Any]]:
+ from repowise.core.analysis.health.grading import band_for
+ from repowise.core.analysis.health.ranking import scope_reason
+ from repowise.core.persistence.crud.analysis.health import (
+ get_file_language_map,
+ health_exclude_spec,
+ )
+ from repowise.core.persistence.crud.analysis.plain_rows import plain_rows
+ from repowise.core.persistence.crud.git import code_file_rows
+ from repowise.core.persistence.models import GitMetadata, HealthFileMetric
+ from repowise.server.mcp_server._helpers import filter_rows_by_attr
+
+ session, repo_id = ctx.session, ctx.repository.id
+ metric_q = select(
+ HealthFileMetric.file_path,
+ HealthFileMetric.score,
+ HealthFileMetric.nloc,
+ HealthFileMetric.max_ccn,
+ HealthFileMetric.module,
+ HealthFileMetric.is_test,
+ HealthFileMetric.code_origin,
+ ).where(HealthFileMetric.repository_id == repo_id)
+ # The rule get_health counts files by, so totals here match its numbers.
+ spec = await health_exclude_spec(session, repo_id, ctx.repo_path)
+ metrics = filter_rows_by_attr(plain_rows(await session.execute(metric_q)), "file_path", spec)
+
+ git_q = select(
+ GitMetadata.file_path,
+ GitMetadata.commit_count_90d,
+ GitMetadata.prior_defect_count,
+ GitMetadata.is_hotspot,
+ ).where(code_file_rows(repo_id))
+ git = {g.file_path: g for g in plain_rows(await session.execute(git_q))}
+ coverage = {c.file_path: c for c in await _coverage_rows(session, repo_id)}
+ languages = await get_file_language_map(session, repo_id)
+
+ paths = [m.file_path for m in metrics]
+ packages = {m.file_path: m.module or ROOT_PACKAGE for m in metrics}
+ dirs = directories(packages)
+ labels = unique_suffixes(paths)
+ rows = []
+ for m in metrics:
+ g = git.get(m.file_path)
+ c = coverage.get(m.file_path)
+ # Unrounded, so an average here is exactly the engine's; views round for display.
+ score = m.score
+ rows.append(
+ {
+ "path": m.file_path,
+ "file": labels[m.file_path],
+ "package": packages[m.file_path],
+ "directory": dirs[m.file_path],
+ "language": languages.get(m.file_path),
+ "health_score": score,
+ "health_band": band_for(score).replace("_", " ") if score is not None else None,
+ "nloc": m.nloc,
+ "max_ccn": m.max_ccn,
+ "commits_90d": g.commit_count_90d if g else 0,
+ "fix_count": g.prior_defect_count if g else 0,
+ "coverage_pct": round(c.line_coverage_pct, 2) if c else None,
+ "coverable_lines": c.total_coverable_lines if c else None,
+ "is_hotspot": bool(g and g.is_hotspot),
+ "is_test": bool(m.is_test),
+ "is_production": scope_reason(m) is None,
+ }
+ )
+ return rows
+
+
+@register_dataset(
+ "coverage",
+ description="One row per file the coverage report measured; avg coverage_pct is line-weighted.",
+ fields=COVERAGE_FIELDS,
+ basis=("measured", "coverage report"),
+ example={"x": "package", "y": "coverage_pct", "aggregate": "avg"},
+ hierarchy=("package", "directory", "file"),
+ noun="measured files",
+)
+async def load_coverage(ctx: LoadContext) -> list[dict[str, Any]]:
+ report = await _coverage_rows(ctx.session, ctx.repository.id)
+ files = await files_index(ctx)
+ placed = place([c.file_path for c in report], files)
+ labels = unique_suffixes(placed)
+ rows = []
+ for c in report:
+ package, directory = placed[c.file_path]
+ covered = c.covered_line_count
+ if covered is None:
+ covered = round(c.line_coverage_pct / 100 * (c.total_coverable_lines or 0))
+ rows.append(
+ {
+ "path": c.file_path,
+ "file": labels[c.file_path],
+ "package": package,
+ "directory": directory,
+ "coverage_pct": round(c.line_coverage_pct, 2),
+ "covered_lines": covered,
+ "coverable_lines": c.total_coverable_lines,
+ }
+ )
+ return rows
diff --git a/packages/server/src/repowise/server/chat_datasets/findings.py b/packages/server/src/repowise/server/chat_datasets/findings.py
new file mode 100644
index 000000000..863ac2c01
--- /dev/null
+++ b/packages/server/src/repowise/server/chat_datasets/findings.py
@@ -0,0 +1,119 @@
+"""The ``findings`` and ``dead_code`` datasets: one row per open finding.
+
+Health findings are the ones get_health lists (the registry's shown types,
+language gates and file holds, on files the health exclude rule keeps); dead
+code is the open findings get_dead_code reads, tiered by the engine's own
+confidence floors.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import select
+
+from repowise.server.chat_datasets import SUMS, DatasetField, LoadContext, register_dataset
+from repowise.server.chat_datasets.files import files_index, place, unique_suffixes
+
+_PLACE_FIELDS = {
+ "path": DatasetField("text", "the file's full repository path"),
+ "file": DatasetField("text", "the file's shortest unique path suffix, for labels"),
+ "package": DatasetField("text", "the package the file belongs to"),
+ "directory": DatasetField("text", "a directory one level inside the package"),
+}
+
+
+@register_dataset(
+ "findings",
+ description="One row per open health finding (what get_health lists).",
+ fields={
+ "kind": DatasetField("text", "the finding type (a health biomarker)"),
+ "severity": DatasetField("text", "critical, high, medium or low"),
+ "dimension": DatasetField("text", "defect, maintainability, performance or advisory"),
+ **_PLACE_FIELDS,
+ },
+ basis=("inferred", "health engine"),
+ example={"x": "severity", "aggregate": "count"},
+ hierarchy=("package", "directory", "file"),
+ noun="open findings",
+)
+async def load_findings(ctx: LoadContext) -> list[dict[str, Any]]:
+ from repowise.core.persistence.crud.analysis.plain_rows import plain_rows
+ from repowise.core.persistence.crud.analysis.shown import shown
+ from repowise.core.persistence.models import HealthFinding
+
+ q = select(
+ HealthFinding.file_path,
+ HealthFinding.biomarker_type,
+ HealthFinding.severity,
+ HealthFinding.dimension,
+ ).where(
+ HealthFinding.repository_id == ctx.repository.id,
+ HealthFinding.status == "open",
+ shown("health", HealthFinding.biomarker_type, HealthFinding.file_path),
+ )
+ files = await files_index(ctx)
+ # Files the health exclude rule drops carry no listed finding either.
+ found = [f for f in plain_rows(await ctx.session.execute(q)) if f.file_path in files]
+ placed = place([f.file_path for f in found], files)
+ return [
+ {
+ "kind": f.biomarker_type,
+ "severity": f.severity,
+ "dimension": f.dimension or "defect",
+ "path": f.file_path,
+ "file": files[f.file_path]["file"],
+ "package": placed[f.file_path][0],
+ "directory": placed[f.file_path][1],
+ }
+ for f in found
+ ]
+
+
+def _tier(confidence: float) -> str:
+ from repowise.core.analysis.dead_code.serving import TIER_FLOORS
+
+ return next(t for t, floor in TIER_FLOORS.items() if confidence >= floor)
+
+
+@register_dataset(
+ "dead_code",
+ description="One row per open dead-code finding (what get_dead_code reads).",
+ fields={
+ "kind": DatasetField(
+ "text", "unreachable_file, unused_export, unused_internal or zombie_package"
+ ),
+ "tier": DatasetField("text", "confidence tier: high, medium or low"),
+ "confidence": DatasetField("number", "the engine's confidence, 0 to 1", ("avg", "min", "max")),
+ "symbol": DatasetField("text", "the unused symbol; null for a whole file or package"),
+ "lines": DatasetField("number", "lines the finding covers; null when uncounted", SUMS, unit="lines"),
+ "safe_to_delete": DatasetField("bool", "the engine judged it safe to delete"),
+ **_PLACE_FIELDS,
+ },
+ basis=("inferred", "reachability graph"),
+ example={"x": "kind", "series": "tier", "aggregate": "count"},
+ hierarchy=("package", "directory", "file"),
+ noun="dead-code findings",
+)
+async def load_dead_code(ctx: LoadContext) -> list[dict[str, Any]]:
+ from repowise.core.persistence.crud.analysis.dead_code import get_dead_code_findings
+
+ found = await get_dead_code_findings(ctx.session, ctx.repository.id)
+ files = await files_index(ctx)
+ placed = place([f.file_path for f in found], files)
+ labels = unique_suffixes(placed)
+ return [
+ {
+ "kind": f.kind,
+ "tier": _tier(f.confidence or 0.0),
+ "confidence": f.confidence,
+ "symbol": f.symbol_name,
+ "lines": f.lines,
+ "safe_to_delete": bool(f.safe_to_delete),
+ "path": f.file_path,
+ "file": files[f.file_path]["file"] if f.file_path in files else labels[f.file_path],
+ "package": placed[f.file_path][0],
+ "directory": placed[f.file_path][1],
+ }
+ for f in found
+ ]
diff --git a/packages/server/src/repowise/server/chat_datasets/history.py b/packages/server/src/repowise/server/chat_datasets/history.py
new file mode 100644
index 000000000..1ca9ee8e0
--- /dev/null
+++ b/packages/server/src/repowise/server/chat_datasets/history.py
@@ -0,0 +1,104 @@
+"""The ``changes`` and ``health_trend`` datasets: what happened over time.
+
+``changes`` is one row per merged change in the indexed history, the records
+get_overview's change block counts; ``health_trend`` is one row per health
+snapshot, the scalars get_health's trend reads.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC
+from typing import Any
+
+from sqlalchemy import select
+
+from repowise.server.chat_datasets import (
+ AVERAGES,
+ SUMS,
+ DatasetField,
+ LoadContext,
+ register_dataset,
+)
+
+
+@register_dataset(
+ "changes",
+ description="One row per merged change in the indexed history (get_overview's change records).",
+ fields={
+ "date": DatasetField("time", "the day it merged"),
+ "week": DatasetField("time", "the Monday of the week it merged", step="week"),
+ "month": DatasetField("time", "the month it merged"),
+ "category": DatasetField(
+ "text", "feature, fix, refactor, docs, test, deps, chore or other"
+ ),
+ "shape": DatasetField("text", "merge, squash or commit"),
+ "files_changed": DatasetField(
+ "number", "files the change touched (to count changes, omit y)", SUMS, unit="files"
+ ),
+ "lines_added": DatasetField("number", "lines added", SUMS, unit="lines"),
+ "lines_deleted": DatasetField("number", "lines deleted", SUMS, unit="lines"),
+ },
+ basis=("measured", "git history"),
+ example={"x": "week", "series": "category", "aggregate": "count"},
+ noun="merged changes",
+)
+async def load_changes(ctx: LoadContext) -> list[dict[str, Any]]:
+ from repowise.core.persistence.models import Change
+ from repowise.server.mcp_server._changes import _week
+
+ q = select(
+ Change.merged_at,
+ Change.category,
+ Change.shape,
+ Change.files_changed,
+ Change.lines_added,
+ Change.lines_deleted,
+ ).where(Change.repository_id == ctx.repository.id)
+ rows = []
+ for merged_at, category, shape, files, added, deleted in await ctx.session.execute(q):
+ if merged_at is None:
+ continue
+ moment = merged_at if merged_at.tzinfo else merged_at.replace(tzinfo=UTC)
+ rows.append(
+ {
+ "date": moment.date().isoformat(),
+ "week": _week(moment),
+ "month": moment.strftime("%Y-%m"),
+ "category": category,
+ "shape": shape,
+ "files_changed": files,
+ "lines_added": added,
+ "lines_deleted": deleted,
+ }
+ )
+ rows.sort(key=lambda r: r["date"])
+ return rows
+
+
+@register_dataset(
+ "health_trend",
+ description="One row per health snapshot, oldest first (get_health's trend).",
+ fields={
+ "taken_at": DatasetField("time", "when the snapshot was taken"),
+ "average_health": DatasetField("number", "average file health, 0 to 10", AVERAGES, unit="score"),
+ "hotspot_health": DatasetField(
+ "number", "average health of hotspot files, 0 to 10", AVERAGES, unit="score"
+ ),
+ },
+ basis=("inferred", "health snapshots"),
+ example={"x": "taken_at", "y": ["average_health", "hotspot_health"], "kind": "line"},
+ noun="health snapshots",
+)
+async def load_health_trend(ctx: LoadContext) -> list[dict[str, Any]]:
+ from repowise.core.persistence.crud.analysis.health import get_health_snapshot_headline
+
+ # Scalars only: whole snapshot rows carry every file's score.
+ headline = await get_health_snapshot_headline(ctx.session, ctx.repository.id, recent=50)
+ return [
+ {
+ "taken_at": s.taken_at.isoformat(timespec="seconds"),
+ "average_health": round(s.average_health, 2),
+ "hotspot_health": round(s.hotspot_health, 2) if s.hotspot_health is not None else None,
+ }
+ for s in headline.recent
+ ]
diff --git a/packages/server/src/repowise/server/chat_prompt.py b/packages/server/src/repowise/server/chat_prompt.py
index 3bc790275..b0b28ccdd 100644
--- a/packages/server/src/repowise/server/chat_prompt.py
+++ b/packages/server/src/repowise/server/chat_prompt.py
@@ -22,6 +22,7 @@ Guidelines:
- Format responses in markdown. File paths in backticks. Code in fenced blocks.
- When tool results contain documentation, synthesize and explain rather than dumping raw content
- If a tool returns an error, explain what happened and suggest alternatives
+- Never name, rank or compare people (authors, owners, developers) as the answer to who wrote, owns or caused code, even when a tool lists them: say repowise describes code, not people, and give the code-side answer (the riskiest files or packages)
- Never claim a tool ran when it did not, and never reveal or invent hidden chain-of-thought
- A mutating tool cannot run without an explicit user confirmation grant"""
@@ -72,7 +73,19 @@ def _page_advisory(page_context: ChatPageContext | None) -> str:
_VIEWS_GUIDANCE = """
-Charts and tables: call the analysis tool first, then show_view with that result's artifact_id or latest:<tool_name>. The show_view schema lists the views. A view carries its numbers, so explain what they mean and do not repeat them.
+Charts and tables: call the analysis tool first, then show_view with that result's artifact_id or latest:<tool_name>. The show_view schema lists the views. A view carries its numbers, so explain what they mean and do not repeat them. Never draw a chart in text (no ASCII art, block characters or markdown bars).
+"""
+
+_CHART_GUIDANCE = """
+Charts and tables:
+- For any chart, graph, plot, visual, "show X by Y", "break it down" or how something changed over time, call chart with a dataset; use kind "table" only when a table or list is asked for. Use show_view only for a result you already fetched.
+- Count rows (omit y) unless a measure was asked for: "changes by week" counts changes.
+- Never draw a chart in text: no ASCII art, block characters or markdown bars.
+- Quote totals, shares and averages from the receipt's figures; never work them out yourself.
+- If the receipt has a kind_note or notes, or the asked kind or measure does not exist, say so plainly and name what was drawn instead. Never swap in another measure without saying so.
+- To redraw a view of this conversation as another kind, call show_view with its view id (v1) and options.kind.
+- Views appear under your reply on their own: never link to them or put their ids in your text.
+- The view shows its numbers, so explain what they mean; do not list them all again.
"""
@@ -83,6 +96,7 @@ def _build_system_prompt(
page_context: ChatPageContext | None = None,
*,
shows_views: bool = False,
+ draws_charts: bool = False,
) -> str:
recipes = [recipe.call for tool in tools for recipe in tool.entry.recipes]
recipe_text = (
@@ -97,7 +111,7 @@ def _build_system_prompt(
routing=_routing_guidance(tools),
recipes=recipe_text,
page=_page_advisory(page_context),
- views=_VIEWS_GUIDANCE if shows_views else "",
+ views=_CHART_GUIDANCE if draws_charts else _VIEWS_GUIDANCE if shows_views else "",
)
diff --git a/packages/server/src/repowise/server/chat_references.py b/packages/server/src/repowise/server/chat_references.py
index f7265f92c..6a8fbdcf9 100644
--- a/packages/server/src/repowise/server/chat_references.py
+++ b/packages/server/src/repowise/server/chat_references.py
@@ -18,6 +18,10 @@ from typing import Any
from repowise.server.chat_artifacts import ARTIFACT_ID_FIELD, normalize_message_artifacts
SHOW_VIEW_TOOL = "show_view"
+#: The chat-only tool that charts a dataset in one call (:mod:`repowise.server.chat_chart`).
+CHART_TOOL = "chart"
+#: Tools whose result is a view of data, never data a view may cite.
+VIEW_TOOLS = frozenset({SHOW_VIEW_TOOL, CHART_TOOL})
LATEST_PREFIX = "latest:"
#: References an unknown-id error lists, newest first.
_LISTED = 8
@@ -52,7 +56,7 @@ def replayed_result(call: Mapping[str, Any]) -> Any:
artifact = call.get("artifact")
data = artifact.get("data", {}) if isinstance(artifact, Mapping) else {}
if (
- call.get("name") != SHOW_VIEW_TOOL
+ call.get("name") not in VIEW_TOOLS
and isinstance(data, Mapping)
and "error" not in data
and isinstance(artifact.get("id"), str)
@@ -72,6 +76,9 @@ class ArtifactIndex:
def __init__(self) -> None:
self._entries: dict[str, tuple[ViewArtifact, int]] = {}
+ #: Earlier turns' view parts by id, the newest turn's winning: view
+ #: ids restart each turn, and "the chart above" means the latest one.
+ self.views: dict[str, dict[str, Any]] = {}
#: The current turn's number; earlier turns are 1..turn-1.
self.turn = 1
@@ -86,12 +93,15 @@ class ArtifactIndex:
for call in content.get("tool_calls") or []:
if isinstance(call, dict):
index._add_stored(call)
+ for part in content.get("views") or []:
+ if isinstance(part, dict) and isinstance(part.get("id"), str):
+ index.views[part["id"]] = part
index.turn += 1
return index
def _add_stored(self, call: dict[str, Any]) -> None:
artifact = call.get("artifact")
- if call.get("name") == SHOW_VIEW_TOOL or not isinstance(artifact, dict):
+ if call.get("name") in VIEW_TOOLS or not isinstance(artifact, dict):
return
artifact_id, data = artifact.get("id"), artifact.get("data")
if not isinstance(artifact_id, str) or not isinstance(data, dict):
diff --git a/packages/server/src/repowise/server/chat_session.py b/packages/server/src/repowise/server/chat_session.py
index 1c48da8ba..f84082068 100644
--- a/packages/server/src/repowise/server/chat_session.py
+++ b/packages/server/src/repowise/server/chat_session.py
@@ -11,8 +11,10 @@ events as SSE, and an in-process caller uses the class directly.
The tools a model is shown, and the only ones it can run, are the backend's
catalog for the principal narrowed by the policy's allowlist and safety
ceiling, plus the chat-only ``show_view`` tool, which builds tables and
-charts from the conversation's tool results (:mod:`repowise.server.chat_views`), and
-the chat-only ``find_suspects`` (:mod:`repowise.server.chat_suspects`).
+charts from the conversation's tool results (:mod:`repowise.server.chat_views`),
+the chat-only ``chart``, which draws a repository dataset in one call
+(:mod:`repowise.server.chat_chart`), and the chat-only ``find_suspects``
+(:mod:`repowise.server.chat_suspects`).
Everything outside the loop goes through the seams in
:mod:`repowise.server.chat_seams`.
"""
@@ -31,6 +33,7 @@ from pydantic import ValidationError
from repowise.core.providers.llm.base import ChatProvider
from repowise.server.auth import Principal
from repowise.server.chat_artifacts import create_artifact_envelope
+from repowise.server.chat_chart import CHART_TOOL, chart_schema, run_chart
from repowise.server.chat_context import (
OVERFLOW_MESSAGE,
bound_history,
@@ -48,7 +51,7 @@ from repowise.server.chat_prompt import (
stored_messages_to_llm_format,
tool_result_message,
)
-from repowise.server.chat_references import ArtifactIndex
+from repowise.server.chat_references import VIEW_TOOLS, ArtifactIndex
from repowise.server.chat_seams import (
ConversationStore,
NoTurnHooks,
@@ -346,6 +349,7 @@ class _Turn:
is_cancelled: IsCancelled,
shows_views: bool = False,
finds_suspects: bool = False,
+ draws_charts: bool = False,
question: str = "",
prior_calls: list[dict[str, Any]] | None = None,
artifacts: ArtifactIndex | None = None,
@@ -355,6 +359,7 @@ class _Turn:
self.catalog = {tool.entry.name: tool for tool in catalog}
self.shows_views = shows_views
self.finds_suspects = finds_suspects
+ self.draws_charts = draws_charts
#: Earlier turns' results stay citable by show_view.
self.views = TurnViews(artifacts)
self.policy = policy
@@ -395,6 +400,8 @@ class _Turn:
"""
if name == SHOW_VIEW_TOOL and self.shows_views:
return self.views.show(arguments)
+ if name == CHART_TOOL and self.draws_charts:
+ return await run_chart(arguments, getattr(self.tools, "repo_alias", None), self.views)
if name == SUSPECTS_TOOL and self.finds_suspects:
result = await run_find_suspects(arguments, getattr(self.tools, "repo_alias", None))
return self.views.record(name, arguments, result, evidence_basis="inferred")
@@ -593,7 +600,7 @@ class _Turn:
"summary": summary,
"artifact": artifact,
}
- view = self.views.event(tool_id, result) if name == SHOW_VIEW_TOOL else None
+ view = self.views.event(tool_id, result) if name in VIEW_TOOLS else None
return [event] if view is None else [event, view]
def reply_content(self) -> dict[str, Any]:
@@ -940,7 +947,15 @@ class ChatSession:
and any(tool.entry.name == SCOPE_TOOL for tool in catalog)
and self.policy.admits_name(SUSPECTS_TOOL, "read_only")
)
+ # chart reads the same index in process, so it is local like find_suspects.
+ draws_charts = (
+ shows_views
+ and isinstance(self.tools, LocalToolBackend)
+ and self.policy.admits_name(CHART_TOOL, "read_only")
+ )
schemas = tool_schemas(catalog)
+ if draws_charts:
+ schemas.append(chart_schema())
if shows_views:
schemas.append(show_view_schema([tool.entry.artifact_type for tool in catalog]))
if finds_suspects:
@@ -957,6 +972,7 @@ class ChatSession:
is_cancelled=is_cancelled,
shows_views=shows_views,
finds_suspects=finds_suspects,
+ draws_charts=draws_charts,
question=message,
prior_calls=[
call
@@ -971,7 +987,12 @@ class ChatSession:
if grounded is not None:
yield grounded
system_prompt = _build_system_prompt(
- self.scope.repo_name, self.scope.repo_path, catalog, context, shows_views=shows_views
+ self.scope.repo_name,
+ self.scope.repo_path,
+ catalog,
+ context,
+ shows_views=shows_views,
+ draws_charts=draws_charts,
)
async for event in turn.run(system_prompt, schemas):
yield event
diff --git a/packages/server/src/repowise/server/chat_spec/__init__.py b/packages/server/src/repowise/server/chat_spec/__init__.py
new file mode 100644
index 000000000..b228da9d2
--- /dev/null
+++ b/packages/server/src/repowise/server/chat_spec/__init__.py
@@ -0,0 +1,49 @@
+"""The chart spec: parse and repair it, fit it to the rows, then turn rows into chart rows.
+
+Pure functions over a list of row dicts. ``parse_spec`` checks a spec's shape
+and repairs the obvious slips; ``fit`` checks it against the rows and repairs
+what the rows decide; ``transform`` filters, groups, sorts and cuts in one
+pass and picks the chart type. Every refusal is a ``SpecError`` whose message
+says what to change. Callers: :mod:`repowise.server.chat_chart_part`.
+"""
+
+from repowise.server.chat_spec.fit import check_fields, field_types, fit
+from repowise.server.chat_spec.kinds import default_title
+from repowise.server.chat_spec.parse import (
+ AGGREGATES,
+ ARROW,
+ KINDS,
+ OPS,
+ OPTIONS,
+ OTHER_LABEL,
+ SPEC_HELP,
+ ChartSpec,
+ Filter,
+ SpecError,
+ label,
+ parse_spec,
+ read_kind,
+)
+from repowise.server.chat_spec.transform import ChartRows, transform
+
+__all__ = [
+ "AGGREGATES",
+ "ARROW",
+ "KINDS",
+ "OPS",
+ "OPTIONS",
+ "OTHER_LABEL",
+ "SPEC_HELP",
+ "ChartRows",
+ "ChartSpec",
+ "Filter",
+ "SpecError",
+ "check_fields",
+ "default_title",
+ "field_types",
+ "fit",
+ "label",
+ "parse_spec",
+ "read_kind",
+ "transform",
+]
diff --git a/packages/server/src/repowise/server/chat_spec/fit.py b/packages/server/src/repowise/server/chat_spec/fit.py
new file mode 100644
index 000000000..bcf8f20cd
--- /dev/null
+++ b/packages/server/src/repowise/server/chat_spec/fit.py
@@ -0,0 +1,318 @@
+"""A spec checked against the rows it charts, with the repairs the rows decide.
+
+``fit`` swaps a near-miss field name for the field, combines rows that share
+an x by the field's declared aggregate, and weights an average the way the
+field's own surface does. Every repair is a note.
+"""
+
+from __future__ import annotations
+
+import difflib
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import replace
+from typing import Any
+
+from repowise.server.chat_spec.parse import (
+ _ADDITIVE,
+ _KEY,
+ ChartSpec,
+ SpecError,
+ _composite_key,
+ _flag,
+ _passes,
+ _x_value,
+)
+
+_TIME = re.compile(
+ r"^\d{4}-\d{2}(-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?)?(Z|[+-]\d{2}:?\d{2})?)?$"
+)
+
+
+_FIELDS_SHOWN = 30
+
+
+def _value_type(value: Any) -> str:
+ if isinstance(value, bool):
+ return "text"
+ if isinstance(value, (int, float)):
+ return "number"
+ if isinstance(value, str):
+ return "time" if _TIME.match(value) else "text"
+ return "nested"
+
+
+def field_types(rows: Sequence[Mapping[str, Any]]) -> dict[str, str]:
+ """Chartable fields of *rows* and their type: number, time or text.
+
+ A field mixing numbers and text is text; one holding objects or lists is
+ left out, as is a key that cannot be a column key.
+ """
+ seen: dict[str, str | None] = {}
+ for row in rows:
+ for key, value in row.items():
+ if value is None:
+ seen.setdefault(key, None)
+ continue
+ kind = _value_type(value)
+ before = seen.get(key)
+ if before is None or before == kind:
+ seen[key] = kind
+ elif "nested" in (before, kind):
+ seen[key] = "nested"
+ else:
+ seen[key] = "text"
+ return {k: t or "text" for k, t in seen.items() if t != "nested" and _KEY.match(k)}
+
+
+def _shown(types: Mapping[str, str]) -> dict[str, str]:
+ return dict(list(types.items())[:_FIELDS_SHOWN])
+
+
+def _unknown(name: str, role: str, types: Mapping[str, str]) -> SpecError:
+ close = difflib.get_close_matches(name, list(types), n=3, cutoff=0.6)
+ hint = f" Did you mean {', '.join(repr(c) for c in close)}?" if close else ""
+ return SpecError(
+ f"{role} {name!r} is not a field of these rows.{hint} Fields are listed in `fields`.",
+ fields=_shown(types),
+ )
+
+
+def check_fields(spec: ChartSpec, types: Mapping[str, str]) -> None:
+ """Every field the spec reads is in *types*, and measures are numeric."""
+ roles = [
+ *(("x", x) for x in (spec.x_parts or (spec.x,))),
+ *(("y", y) for y in spec.y),
+ *(("filter field", f.field) for f in spec.filters),
+ *(("group", g) for g in spec.groups),
+ ]
+ for role, extra in (("series", spec.series), ("weight", spec.weight), ("color", spec.color)):
+ if extra:
+ roles.append((role, extra))
+ for role, name in roles:
+ if name not in types:
+ raise _unknown(name, role, types)
+ numeric = [k for k, t in types.items() if t == "number"]
+ for y in (*spec.y, *([spec.weight] if spec.weight else [])):
+ if types[y] != "number":
+ raise SpecError(
+ f"{'weight' if y == spec.weight else 'y'} {y!r} holds {types[y]}; "
+ f"it must be numeric: {numeric[:_FIELDS_SHOWN]}",
+ fields=_shown(types),
+ )
+ x_type = "text" if spec.x_parts else types[spec.x]
+ if spec.other and x_type != "text":
+ raise SpecError(
+ f"other needs a category x and {spec.x!r} holds {x_type}; "
+ "drop other, or use top alone"
+ )
+ # Unaggregated rows may sort by any number or date they hold, before top cuts them.
+ if (
+ spec.sort
+ and spec.sort[0] not in (spec.x, *spec.measures)
+ and (spec.aggregate is not None or types.get(spec.sort[0]) not in ("number", "time"))
+ ):
+ choices = [spec.x, *spec.measures]
+ raise SpecError(
+ f"sort field {spec.sort[0]!r} must be one of {choices}"
+ + ("" if spec.aggregate is None else "; with aggregate, sort by x or the measure")
+ )
+
+
+def _repair_name(name: str, types: Mapping[str, str]) -> str | None:
+ """*name* as a field of *types*: itself, another case, or one near-identical spelling."""
+ if name in types:
+ return name
+ lowered = {k.lower(): k for k in types}
+ if name.lower() in lowered:
+ return lowered[name.lower()]
+ close = difflib.get_close_matches(name, list(types), n=2, cutoff=0.85)
+ return close[0] if len(close) == 1 else None
+
+
+def _repair_names(spec: ChartSpec, types: Mapping[str, str]) -> ChartSpec:
+ notes: list[str] = []
+
+ def fix(name: str | None) -> str | None:
+ if name is None:
+ return None
+ fixed = _repair_name(name, types)
+ if fixed is None or fixed == name:
+ return name
+ notes.append(f"field {name!r} read as {fixed!r}")
+ return fixed
+
+ x_parts = tuple(fix(p) or p for p in spec.x_parts)
+ x = _composite_key(x_parts) if x_parts else (fix(spec.x) or spec.x)
+ y = tuple(fix(v) or v for v in spec.y)
+ aggregate = spec.aggregate
+ # "y": "count" over rows with no count field means: count the rows.
+ if y == ("count",) and "count" not in types:
+ y, aggregate = (), "count"
+ notes.append("y 'count' read as aggregate count")
+ sort = spec.sort
+ if sort and sort[0] not in ("__value", x, *y) and (fixed := _repair_name(sort[0], types)):
+ sort = (fixed, sort[1])
+ return replace(
+ spec,
+ x=x,
+ x_parts=x_parts,
+ y=y,
+ aggregate=aggregate,
+ series=fix(spec.series),
+ filters=tuple(replace(f, field=fix(f.field) or f.field) for f in spec.filters),
+ groups=tuple(fix(g) or g for g in spec.groups),
+ weight=fix(spec.weight),
+ color=fix(spec.color),
+ sort=sort,
+ notes=(*spec.notes, *notes),
+ )
+
+
+def _coerce_filters(spec: ChartSpec, rows: Sequence[Mapping[str, Any]]) -> ChartSpec:
+ """A filter's text value read as the bool or number its field holds."""
+ if not spec.filters:
+ return spec
+ sample: dict[str, Any] = {}
+ for f in spec.filters:
+ sample[f.field] = next((r[f.field] for r in rows if r.get(f.field) is not None), None)
+ fixed = []
+ for f in spec.filters:
+ held, value = sample.get(f.field), f.value
+ if isinstance(held, bool) and not isinstance(value, bool) and _flag(value) is not None:
+ value = _flag(value)
+ elif (
+ isinstance(held, (int, float))
+ and not isinstance(held, bool)
+ and isinstance(value, str)
+ and re.fullmatch(r"-?\d+(\.\d+)?", value.strip())
+ ):
+ value = float(value) if "." in value else int(value)
+ fixed.append(replace(f, value=value))
+ return replace(spec, filters=tuple(fixed))
+
+
+def fit(
+ spec: ChartSpec,
+ rows: Sequence[Mapping[str, Any]],
+ types: Mapping[str, str],
+ meta: Mapping[str, Any] | None = None,
+ hierarchy: Sequence[str] = (),
+) -> ChartSpec:
+ """*spec* checked against *rows*, with the repairs the rows decide.
+
+ *meta* maps field names to their declared ``aggregates`` and ``weight``
+ (a dataset's fields); *hierarchy* is a dataset's nesting, which a treemap
+ takes its groups from when it names none. Raises ``SpecError``.
+ """
+ meta = meta or {}
+ spec = _coerce_filters(_repair_names(spec, types), rows)
+ # "x" and "value" name the axis and the plotted value when no field has that name.
+ if spec.sort and spec.sort[0] not in types:
+ name, order = spec.sort
+ if name == "x":
+ spec = replace(spec, sort=(spec.x, order))
+ elif name in ("__value", "value", "y", "count", "total") and spec.measures:
+ spec = replace(spec, sort=(spec.measures[0], order))
+ x_types = [types.get(p) for p in (spec.x_parts or (spec.x,))]
+ x_type = "text" if spec.x_parts else x_types[0]
+
+ step = None if spec.x_parts else getattr(meta.get(spec.x), "step", None)
+ if step:
+ spec = replace(spec, x_step=step)
+ if spec.kind == "scatter" and x_type != "number":
+ spec = replace(
+ spec,
+ kind="bar",
+ kind_note=(
+ f"a scatter needs a numeric x and {spec.x!r} holds {x_type}, so this is a bar; "
+ "for a scatter pass two numeric fields as x and y"
+ ),
+ )
+
+ # A declared aggregate the field cannot take is swapped for one it can, and said.
+ if spec.aggregate not in (None, "count"):
+ for y in spec.y:
+ allowed = getattr(meta.get(y), "aggregates", ())
+ if allowed and spec.aggregate not in allowed:
+ spec = spec.noted(
+ f"{y} does not take {spec.aggregate}, so it is {allowed[0]}",
+ aggregate=allowed[0],
+ )
+ break
+ if spec.aggregate == "avg" and len(spec.y) == 1:
+ spec = _declared_weight(spec, types, meta, grouped=_repeats(spec, rows))
+
+ if spec.kind == "treemap" and spec.aggregate in ("avg", "min", "max") and len(spec.y) == 1:
+ measure, size = spec.y[0], spec.weight
+ spec = spec.noted(
+ f"a treemap's cells add up, so they are sized by {size or 'the row count'} "
+ f"and coloured by the {spec.aggregate} {measure}",
+ y=(size,) if size else (),
+ aggregate="sum" if size else "count",
+ color=spec.color or measure,
+ )
+ if spec.kind == "treemap" and not spec.groups and hierarchy:
+ leaf = spec.x_parts[-1] if spec.x_parts else spec.x
+ above = tuple(hierarchy[: hierarchy.index(leaf)]) if leaf in hierarchy else ()
+ if above:
+ spec = spec.noted(f"the treemap nests by {', '.join(above)}", groups=above)
+ if spec.kind != "treemap" and (spec.groups or spec.color):
+ spec = spec.noted("groups and color shape a treemap only, so they were left out", groups=(), color=None)
+
+ check_fields(spec, types)
+
+ # Rows that share an x combine: by the field's declared aggregate, else summed.
+ scatter = spec.kind == "scatter" or (
+ spec.kind == "auto" and spec.aggregate is None and x_type == "number"
+ )
+ if spec.aggregate is None and not scatter and spec.kind != "table" and _repeats(spec, rows):
+ allowed = getattr(meta.get(spec.y[0]), "aggregates", ()) if spec.y else ()
+ chosen = allowed[0] if allowed else "sum"
+ spec = spec.noted(
+ f"several rows share each {spec.x}, so {', '.join(spec.y)} is combined by {chosen}",
+ aggregate=chosen,
+ )
+ if chosen == "avg" and len(spec.y) == 1:
+ spec = _declared_weight(spec, types, meta, grouped=True)
+ if spec.other and chosen not in _ADDITIVE:
+ spec = spec.noted("an average does not add up, so no Other", other=False)
+ return spec
+
+
+def _declared_weight(
+ spec: ChartSpec, types: Mapping[str, str], meta: Mapping[str, Any], *, grouped: bool
+) -> ChartSpec:
+ """An average of a field that declares a weight is weighted by it, as its own surface
+ averages it (health by lines of code, coverage by coverable lines), unless asked not to."""
+ if spec.unweighted:
+ return spec
+ declared = getattr(meta.get(spec.y[0]), "weight", None)
+ if spec.weight is not None:
+ # The declared weight asked for by name takes its declared floor too.
+ if spec.weight == declared:
+ return replace(spec, weight_floor=getattr(meta.get(spec.y[0]), "weight_floor", None))
+ return spec
+ if not declared or declared not in types:
+ return spec
+ # One row per x averages nothing, so only the overall figure is weighted.
+ what = f"{spec.y[0]} is averaged" if grouped else f"the overall {spec.y[0]} is"
+ return spec.noted(
+ f"{what} weighted by {declared}; pass weight: none for a plain mean",
+ weight=declared,
+ weight_floor=getattr(meta.get(spec.y[0]), "weight_floor", None),
+ )
+
+
+def _repeats(spec: ChartSpec, rows: Sequence[Mapping[str, Any]]) -> bool:
+ seen: set[Any] = set()
+ for row in rows:
+ if not all(_passes(f, row.get(f.field)) for f in spec.filters):
+ continue
+ key = (_x_value(spec, row), row.get(spec.series) if spec.series else None)
+ if key[0] is None:
+ continue
+ if key in seen:
+ return True
+ seen.add(key)
+ return False
diff --git a/packages/server/src/repowise/server/chat_spec/kinds.py b/packages/server/src/repowise/server/chat_spec/kinds.py
new file mode 100644
index 000000000..6a7cb2198
--- /dev/null
+++ b/packages/server/src/repowise/server/chat_spec/kinds.py
@@ -0,0 +1,114 @@
+"""The chart type a spec is drawn as: the asked kind when the rows fit it, else
+the nearest one that does, with a note saying why.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from repowise.server.chat_spec.parse import _ADDITIVE, _AGGREGATE_LABEL, ChartSpec, _number, label
+from repowise.server.schemas.views import VIEW_LIMITS
+
+_LINE_KINDS = frozenset({"line", "area"})
+
+
+def _whole(keys: list[str], rows: list[dict[str, Any]]) -> bool:
+ values = [r.get(k) for r in rows for k in keys if r.get(k) is not None]
+ return bool(values) and all(_number(v) and v >= 0 for v in values) and sum(values) > 0
+
+
+def _choose_kind(
+ spec: ChartSpec,
+ x_type: str,
+ keys: list[str],
+ rows: list[dict[str, Any]],
+ truncated: bool,
+ scatter: bool,
+) -> tuple[str, str, str | None]:
+ """The chart type, why, and a note when the asked kind could not be drawn as asked.
+
+ An asked kind is drawn whenever the data fits it; when it does not, the
+ nearest kind that fits is drawn and ``kind_note`` says why.
+ """
+ additive = spec.aggregate in _ADDITIVE or spec.aggregate is None
+ low, high = VIEW_LIMITS["donut_min_parts"], VIEW_LIMITS["donut_max_parts"]
+ whole = _whole(keys, rows)
+ donut_ok = (
+ len(keys) == 1
+ and low <= len(rows) <= high
+ and not truncated
+ and whole
+ and all(r.get(keys[0]) is not None for r in rows)
+ )
+ stack_ok = len(keys) >= 2 and additive and whole
+ kind = spec.kind
+ asked = f"kind {kind} was asked for"
+ if kind == "donut":
+ if donut_ok and additive:
+ return "donut", asked, None
+ if not additive:
+ why = f"an {spec.aggregate} does not add up to a whole"
+ elif len(keys) > 1:
+ why = f"there are {len(keys)} series"
+ elif len(rows) < low:
+ why = f"there is only {len(rows)} part" if len(rows) == 1 else "there are no parts"
+ elif truncated or len(rows) > high:
+ why = f"{len(rows)} parts with some cut"
+ else:
+ why = "the values are not parts of a positive whole"
+ fallback = "stacked_bar" if stack_ok else "bar"
+ return fallback, f"kind {fallback} drawn in place of donut", (
+ f"a donut shows one measure as {low} to {high} parts of a whole; here {why}, "
+ f"so this is a {fallback.replace('_', ' ')}"
+ )
+ if kind == "stacked_bar":
+ if stack_ok:
+ return "stacked_bar", asked, None
+ return "bar", "kind bar drawn in place of stacked_bar", (
+ "a stacked bar needs two or more series of counts or sums; pass series "
+ "(a field to split each bar by), so this is a plain bar"
+ )
+ if kind == "treemap":
+ if len(keys) == 1 and whole and additive:
+ return "treemap", asked, None
+ return "bar", "kind bar drawn in place of treemap", (
+ "a treemap sizes cells by one count or sum that adds up; "
+ + ("an average does not" if not additive else "this measure does not")
+ + ", so this is a bar (size it by a sum such as nloc and colour it by the average)"
+ )
+ if kind in _LINE_KINDS:
+ if x_type in ("time", "number"):
+ return kind, asked, None
+ return kind, asked, (
+ f"a {kind} joins points in order, and {spec.x!r} holds categories with no order, "
+ "so the slope between them means nothing; a bar may read better"
+ )
+ if kind in ("bar", "horizontal_bar", "heatmap", "scatter", "table"):
+ return kind, asked, None
+ if scatter:
+ return "scatter", f"x {spec.x!r} and the plotted values are both numeric", None
+ if x_type == "time":
+ return "line", f"x {spec.x!r} holds dates", None
+ if spec.series and len(keys) > 1:
+ if additive and whole:
+ return "stacked_bar", f"series {spec.series!r} splits each bar into parts", None
+ why = f"{spec.aggregate} does not add up"
+ return "bar", f"series {spec.series!r} values sit side by side ({why})", None
+ if len(keys) > 1:
+ return "bar", "several measures sit side by side", None
+ if spec.aggregate in _ADDITIVE and donut_ok and len(rows) <= 5:
+ return "donut", f"{len(rows)} parts that add up to one whole", None
+ return "bar", "one measure across categories", None
+
+
+def default_title(spec: ChartSpec) -> str:
+ if spec.aggregate == "count":
+ measure = "Count"
+ else:
+ names = ", ".join(label(y).lower() for y in spec.y)
+ measure = (
+ f"{_AGGREGATE_LABEL[spec.aggregate]} {names}" if spec.aggregate else names.capitalize()
+ )
+ x = " and ".join(label(p).lower() for p in spec.x_parts) if spec.x_parts else label(spec.x).lower()
+ by = x + (f" and {label(spec.series).lower()}" if spec.series else "")
+ return f"{measure} by {by}"
diff --git a/packages/server/src/repowise/server/chat_spec/parse.py b/packages/server/src/repowise/server/chat_spec/parse.py
new file mode 100644
index 000000000..4416f46e8
--- /dev/null
+++ b/packages/server/src/repowise/server/chat_spec/parse.py
@@ -0,0 +1,478 @@
+"""A chart spec as sent: parsed, checked for shape, and the obvious slips repaired.
+
+``parse_spec`` reads chart options into a ``ChartSpec``; every repair is a note
+the receipt reports, so a change to what is drawn is never silent.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from typing import Any
+
+from repowise.server.schemas.views import VIEW_LIMITS
+
+AGGREGATES = ("count", "sum", "avg", "min", "max")
+
+
+OPS = ("eq", "ne", "lt", "lte", "gt", "gte", "in", "contains", "prefix")
+
+
+KINDS = (
+ "auto",
+ "bar",
+ "horizontal_bar",
+ "stacked_bar",
+ "line",
+ "area",
+ "donut",
+ "scatter",
+ "treemap",
+ "heatmap",
+ "table",
+)
+
+
+OPTIONS = frozenset(
+ {"rows", "x", "y", "series", "filter", "group_by", "aggregate", "sort", "top", "other"}
+ | {"kind", "title", "subtitle", "weight", "groups", "color"}
+)
+
+
+OTHER_LABEL = "Other"
+#: The spec in one paragraph, for every tool that takes one (chart, show_view's chart view).
+SPEC_HELP = (
+ "Spec: x is a field (a list joins them, e.g. [from_package, to_package]). Omit y to "
+ "count rows (the usual case: changes by week is x week, no y); y names a numeric field "
+ "to sum or average (aggregate count|sum|avg|min|max). series splits by a field; filter "
+ "[{field, op, value}]; sort {field, order}; top; other adds up the rest; color colours "
+ "treemap cells; kind, title. The receipt says the kind drawn and why; on an error, "
+ "resend its suggested_spec and tell the user its adjustments."
+)
+
+
+#: Joins the fields of a composite x, as in "packages/server → packages/core".
+ARROW = "→"
+
+
+# Names a model reaches for, read as the kind or aggregate they mean.
+_KIND_ALIASES = {
+ "pie": "donut",
+ "doughnut": "donut",
+ "ring": "donut",
+ "column": "bar",
+ "columns": "bar",
+ "vertical_bar": "bar",
+ "histogram": "bar",
+ "hbar": "horizontal_bar",
+ "barh": "horizontal_bar",
+ "horizontal": "horizontal_bar",
+ "stacked": "stacked_bar",
+ "stacked_column": "stacked_bar",
+ "timeseries": "line",
+ "time_series": "line",
+ "points": "scatter",
+ "heat_map": "heatmap",
+ "grid": "heatmap",
+ "tree_map": "treemap",
+ "list": "table",
+}
+
+
+_AGGREGATE_ALIASES = {"mean": "avg", "average": "avg", "total": "sum", "n": "count"}
+
+
+_ADDITIVE = frozenset({"count", "sum"})
+
+
+_AGGREGATE_LABEL = {
+ "count": "Count",
+ "sum": "Total",
+ "avg": "Average",
+ "min": "Lowest",
+ "max": "Highest",
+}
+
+
+_KEY = re.compile(r"^[a-z][a-z0-9_]{0,63}$")
+
+
+_MAX_FILTERS = 10
+
+
+_MAX_TEXT = 120
+
+
+_MAX_X_PARTS = 3
+
+
+#: Parts a donut keeps when it folds the rest into Other.
+_DONUT_KEEP = VIEW_LIMITS["donut_max_parts"] - 1
+
+
+_DEFAULT_TOP = 10
+
+
+class SpecError(ValueError):
+ """A spec the rows cannot satisfy; the message says what to change."""
+
+ def __init__(
+ self, message: str, code: str = "bad_spec", fields: Mapping[str, str] | None = None
+ ) -> None:
+ super().__init__(message)
+ self.code = code
+ self.fields = dict(fields) if fields else None
+
+
+@dataclass(frozen=True)
+class Filter:
+ field: str
+ op: str
+ value: Any
+
+
+@dataclass(frozen=True)
+class ChartSpec:
+ x: str
+ y: tuple[str, ...]
+ series: str | None = None
+ filters: tuple[Filter, ...] = ()
+ aggregate: str | None = None
+ sort: tuple[str, str] | None = None
+ top: int | None = None
+ other: bool = False
+ kind: str = "auto"
+ title: str | None = None
+ subtitle: str | None = None
+ #: The fields a composite x joins, in order; ``x`` is then their joined key.
+ x_parts: tuple[str, ...] = ()
+ #: A numeric field an ``avg`` is weighted by; ``unweighted`` turns off a declared one.
+ weight: str | None = None
+ unweighted: bool = False
+ #: The calendar step of a date x ("week"), so a grouped series shows empty steps as zero.
+ x_step: str | None = None
+ #: Each row weighs at least this much (``nloc_weighted_score`` floors lines at 1).
+ weight_floor: float | None = None
+ #: A treemap's nesting fields (outermost first) and the field colouring its cells.
+ groups: tuple[str, ...] = ()
+ color: str | None = None
+ #: Repairs made to the spec as sent, for the receipt.
+ notes: tuple[str, ...] = ()
+ #: Set when ``fit`` had to draw another kind than the one asked for.
+ kind_note: str | None = None
+
+ @property
+ def measures(self) -> tuple[str, ...]:
+ """Keys of the plotted measures before any series split."""
+ return ("count",) if self.aggregate == "count" else self.y
+
+ def fields(self) -> list[str]:
+ """Every row field the spec reads."""
+ names = [
+ *(self.x_parts or (self.x,)),
+ *self.y,
+ *(f.field for f in self.filters),
+ *self.groups,
+ ]
+ for extra in (self.series, self.weight, self.color):
+ if extra:
+ names.append(extra)
+ return list(dict.fromkeys(names))
+
+ def noted(self, *notes: str, **changes: Any) -> ChartSpec:
+ return replace(self, notes=(*self.notes, *notes), **changes)
+
+
+def _name(options: Mapping[str, Any], key: str) -> str | None:
+ value = options.get(key)
+ if value is None:
+ return None
+ if not isinstance(value, str) or not value:
+ raise SpecError(f"{key} must be a field name")
+ return value
+
+
+def _names(options: Mapping[str, Any], key: str, most: int) -> tuple[str, ...]:
+ value = options.get(key)
+ if value is None:
+ return ()
+ if isinstance(value, str) and value:
+ return (value,)
+ if isinstance(value, list) and value and all(isinstance(v, str) and v for v in value):
+ if len(value) > most:
+ raise SpecError(f"{key} takes at most {most} fields")
+ return tuple(dict.fromkeys(value))
+ raise SpecError(f"{key} must be a field name or a list of field names")
+
+
+def _text(options: Mapping[str, Any], key: str) -> str | None:
+ value = options.get(key)
+ if value is None:
+ return None
+ if not isinstance(value, str) or not value.strip() or len(value) > _MAX_TEXT:
+ raise SpecError(f"{key} must be text of 1 to {_MAX_TEXT} characters")
+ return value.strip()
+
+
+def _scalar(value: Any) -> bool:
+ return value is None or isinstance(value, (str, int, float, bool))
+
+
+def _filter(raw: Any, i: int) -> Filter:
+ if not isinstance(raw, Mapping) or not isinstance(raw.get("field"), str):
+ raise SpecError(f"filter[{i}] must be {{field, op, value}}")
+ op = raw.get("op", "eq")
+ if op not in OPS:
+ raise SpecError(f"filter[{i}].op {op!r} is not one of {list(OPS)}")
+ value = raw.get("value")
+ if op == "in":
+ if not isinstance(value, list) or not value or not all(_scalar(v) for v in value):
+ raise SpecError(f"filter[{i}]: op in takes a non-empty list of values")
+ value = tuple(value)
+ elif op in ("contains", "prefix"):
+ if not isinstance(value, str):
+ raise SpecError(f"filter[{i}]: op {op} takes a text value")
+ elif op in ("lt", "lte", "gt", "gte"):
+ if isinstance(value, bool) or not isinstance(value, (int, float, str)):
+ raise SpecError(f"filter[{i}]: op {op} takes a number or text value")
+ elif not _scalar(value):
+ raise SpecError(f"filter[{i}]: op {op} takes one value")
+ return Filter(raw["field"], op, value)
+
+
+def _flag(value: Any) -> bool | None:
+ """``True``/``False`` from a bool or an obvious spelling of one; None otherwise."""
+ if isinstance(value, bool):
+ return value
+ if isinstance(value, int) and value in (0, 1):
+ return bool(value)
+ if isinstance(value, str):
+ word = value.strip().lower()
+ if word in ("true", "yes", "on", "other", "1"):
+ return True
+ if word in ("false", "no", "off", "none", "0", ""):
+ return False
+ return None
+
+
+def _whole_number(value: Any) -> int | None:
+ if isinstance(value, bool):
+ return None
+ if isinstance(value, int):
+ return value
+ if isinstance(value, float) and value.is_integer():
+ return int(value)
+ if isinstance(value, str) and value.strip().isdigit():
+ return int(value.strip())
+ return None
+
+
+def _composite_key(parts: tuple[str, ...]) -> str:
+ key = "_".join(parts)[:64]
+ return key if _KEY.match(key) else "x"
+
+
+def _parse_kind(options: Mapping[str, Any], notes: list[str]) -> str:
+ kind = options.get("kind", "auto")
+ if kind is None:
+ return "auto"
+ if isinstance(kind, str):
+ word = kind.strip().lower().replace("-", "_").replace(" ", "_")
+ alias = _KIND_ALIASES.get(word, word)
+ if alias in KINDS:
+ if alias != kind:
+ notes.append(f"kind {kind!r} read as {alias!r}")
+ return alias
+ raise SpecError(f"kind {kind!r} is not one of {list(KINDS)}")
+
+
+def read_kind(value: Any) -> tuple[str, str | None]:
+ """A kind as asked (``"pie"``, ``"Donut"``) and the note when it was read as another name."""
+ notes: list[str] = []
+ return _parse_kind({"kind": value}, notes), (notes[0] if notes else None)
+
+
+def _parse_aggregate(options: Mapping[str, Any], notes: list[str]) -> str | None:
+ aggregate = options.get("aggregate")
+ if aggregate is None:
+ return None
+ word = aggregate.strip().lower() if isinstance(aggregate, str) else aggregate
+ word = _AGGREGATE_ALIASES.get(word, word) if isinstance(word, str) else word
+ if word not in AGGREGATES:
+ raise SpecError(f"aggregate {aggregate!r} is not one of {list(AGGREGATES)}")
+ if word != aggregate:
+ notes.append(f"aggregate {aggregate!r} read as {word!r}")
+ return word
+
+
+def _parse_sort(options: Mapping[str, Any]) -> tuple[str, str] | None:
+ sort = options.get("sort")
+ if sort is None:
+ return None
+ if isinstance(sort, str):
+ # A bare order sorts by the plotted value; a bare name sorts by that field.
+ sort = {"order": sort} if sort.strip().lower() in ("asc", "desc") else {"field": sort}
+ if not isinstance(sort, Mapping):
+ raise SpecError('sort must be {"field": <x or a y field>, "order": "asc" | "desc"}')
+ name = sort.get("field", "__value")
+ if not isinstance(name, str) or not name:
+ raise SpecError('sort must be {"field": <x or a y field>, "order": "asc" | "desc"}')
+ order = sort.get("order", "desc")
+ order = order.strip().lower() if isinstance(order, str) else order
+ if order not in ("asc", "desc"):
+ raise SpecError('sort order must be "asc" or "desc"')
+ return name, order
+
+
+def parse_spec(options: Mapping[str, Any]) -> ChartSpec:
+ """A spec from chart options, checked for shape and repaired where the intent is plain."""
+ notes: list[str] = []
+ raw_x = options.get("x")
+ group_by = _name(options, "group_by")
+ x_parts: tuple[str, ...] = ()
+ if isinstance(raw_x, list):
+ x_parts = _names(options, "x", _MAX_X_PARTS)
+ x = _composite_key(x_parts) if len(x_parts) > 1 else x_parts[0]
+ if len(x_parts) == 1:
+ x_parts = ()
+ else:
+ x = _name(options, "x")
+ if x and group_by and x != group_by:
+ raise SpecError("x and group_by name the same axis; pass one of them")
+ x = x or group_by
+ if x is None:
+ raise SpecError("pass x: the field the chart runs along (a category or a date)")
+
+ y = _names(options, "y", VIEW_LIMITS["chart_series"])
+ aggregate = _parse_aggregate(options, notes)
+ if aggregate == "count" and y:
+ notes.append(f"aggregate count counts rows, so y {list(y)} was dropped")
+ y = ()
+ if aggregate is None and not y:
+ aggregate = "count"
+ if aggregate is None and group_by:
+ aggregate = "sum"
+ notes.append("group_by combines rows, so y is summed")
+ if aggregate not in (None, "count") and not y:
+ raise SpecError(f"aggregate {aggregate} needs y, the numeric field to {aggregate}")
+
+ series = _name(options, "series")
+ if series and len(y) > 1:
+ raise SpecError("with series, y takes one field, which series splits by value")
+ if series and (series == x or series in y):
+ notes.append(f"series {series!r} repeats x or y, so it was dropped")
+ series = None
+ if x in y:
+ raise SpecError("x cannot also be a y field")
+
+ raw_filters = options.get("filter") or []
+ if isinstance(raw_filters, Mapping):
+ raw_filters = [raw_filters]
+ if not isinstance(raw_filters, list) or len(raw_filters) > _MAX_FILTERS:
+ raise SpecError(f"filter must be a list of at most {_MAX_FILTERS} {{field, op, value}}")
+ filters = tuple(_filter(raw, i) for i, raw in enumerate(raw_filters))
+
+ kind = _parse_kind(options, notes)
+ other = options.get("other", False)
+ flag = _flag(other)
+ if flag is None:
+ raise SpecError("other must be true or false")
+ if flag is not other:
+ notes.append(f"other {other!r} read as {str(flag).lower()}")
+ other = flag
+
+ top = options.get("top")
+ if top is not None:
+ whole = _whole_number(top)
+ if whole is None or whole < 1:
+ raise SpecError(f"top must be a whole number from 1 to {VIEW_LIMITS['chart_points']}")
+ if whole != top:
+ notes.append(f"top {top!r} read as {whole}")
+ top = whole
+ most = VIEW_LIMITS["chart_points"] - (1 if other else 0)
+ if top is not None and top > most and kind != "table":
+ notes.append(f"top {top} is past the {most} points a chart holds, so it shows {most}")
+ top = most
+ if other and top is None:
+ top = _DONUT_KEEP if kind == "donut" else _DEFAULT_TOP
+ notes.append(f"other needs top, so the largest {top} are kept and the rest go to Other")
+ if other and aggregate not in _ADDITIVE:
+ if aggregate is None:
+ aggregate = "sum"
+ notes.append("other adds up the rows past top, so y is summed")
+ else:
+ other = False
+ notes.append(f"other adds up the rest, and an {aggregate} does not add up, so no Other")
+
+ unweighted = isinstance(options.get("weight"), str) and options["weight"].lower() == "none"
+ unweighted = unweighted or options.get("weight") is False
+ return ChartSpec(
+ x=x,
+ y=y,
+ series=series,
+ filters=filters,
+ aggregate=aggregate,
+ sort=_parse_sort(options),
+ top=top,
+ other=other,
+ kind=kind,
+ title=_text(options, "title"),
+ subtitle=_text(options, "subtitle"),
+ x_parts=x_parts,
+ weight=None if unweighted else _name(options, "weight"),
+ unweighted=unweighted,
+ groups=_names(options, "groups", VIEW_LIMITS["treemap_groups"]),
+ color=_name(options, "color"),
+ notes=tuple(notes),
+ )
+
+
+def _passes(f: Filter, value: Any) -> bool:
+ op, want = f.op, f.value
+ if op == "eq":
+ return value == want
+ if op == "ne":
+ return value != want
+ if op == "in":
+ return value in want
+ if op == "contains":
+ return isinstance(value, str) and want in value
+ if op == "prefix":
+ return isinstance(value, str) and value.startswith(want)
+ # Ordering compares like with like; a null or a type mismatch never passes.
+ if value is None or isinstance(value, bool) or isinstance(value, str) != isinstance(want, str):
+ return False
+ if op == "lt":
+ return value < want
+ if op == "lte":
+ return value <= want
+ if op == "gt":
+ return value > want
+ return value >= want
+
+
+def _x_value(spec: ChartSpec, row: Mapping[str, Any]) -> Any:
+ if not spec.x_parts:
+ return row.get(spec.x)
+ parts = [row.get(p) for p in spec.x_parts]
+ if any(p is None for p in parts):
+ return None
+ return f" {ARROW} ".join(_value_label(p) for p in parts)
+
+
+def _number(value: Any) -> bool:
+ return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _value_label(value: Any) -> str:
+ if value is None:
+ return "none"
+ if isinstance(value, bool):
+ return "true" if value else "false"
+ return str(value)
+
+
+def label(key: str) -> str:
+ """A field name as a column label: ``line_count`` is "Line count"."""
+ return key.replace("_", " ").capitalize()
diff --git a/packages/server/src/repowise/server/chat_spec/transform.py b/packages/server/src/repowise/server/chat_spec/transform.py
new file mode 100644
index 000000000..ae0af0f92
--- /dev/null
+++ b/packages/server/src/repowise/server/chat_spec/transform.py
@@ -0,0 +1,575 @@
+"""Rows to chart rows: one pass filters and groups, then sort, top and the
+Other bucket work on the groups, and the figures a reply quotes are added up.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from repowise.server.chat_spec.kinds import _choose_kind
+from repowise.server.chat_spec.parse import (
+ _ADDITIVE,
+ _AGGREGATE_LABEL,
+ _DONUT_KEEP,
+ ARROW,
+ OTHER_LABEL,
+ ChartSpec,
+ SpecError,
+ _number,
+ _passes,
+ _value_label,
+ _x_value,
+ label,
+)
+from repowise.server.schemas.views import VIEW_LIMITS
+
+# Fields that name a point in a scatter or an unaggregated chart, in preference order.
+_LABEL_FIELDS = ("file", "file_path", "path", "name", "title", "id")
+
+
+#: Shares a receipt lists, so the model quotes them instead of dividing.
+_SHARES_LISTED = 12
+
+
+_SORT_KEY = "__sort"
+
+
+#: Rows a receipt previews when it has no shares to list.
+_ROWS_PREVIEWED = 15
+
+
+@dataclass
+class ChartRows:
+ """Chart rows and what was done to get them."""
+
+ x: str
+ x_type: str
+ columns: list[tuple[str, str]]
+ series: list[str]
+ rows: list[dict[str, Any]]
+ chart_type: str
+ reason: str
+ total_rows: int
+ matched: int
+ source_rows: int
+ missing_x: int = 0
+ sort: str | None = None
+ other: bool = False
+ #: Why the asked kind was not drawn as asked, or a caution about it.
+ kind_note: str | None = None
+ #: Totals, shares and the overall average, computed here so nobody divides.
+ figures: dict[str, Any] = field(default_factory=dict)
+ notes: list[str] = field(default_factory=list)
+ groups: list[str] = field(default_factory=list)
+ color: str | None = None
+
+
+class _Acc:
+ """Running count, sum, min, max and weighted sum of one measure in one group."""
+
+ __slots__ = ("hi", "lo", "n", "rows", "total", "weighted", "weights")
+
+ def __init__(self) -> None:
+ self.rows = 0
+ self.n = 0
+ self.total: float = 0
+ self.lo: float | None = None
+ self.hi: float | None = None
+ self.weighted: float = 0
+ self.weights: float = 0
+
+ def add(self, value: Any, weight: Any = None) -> None:
+ self.rows += 1
+ if _number(value):
+ self.n += 1
+ self.total += value
+ self.lo = value if self.lo is None or value < self.lo else self.lo
+ self.hi = value if self.hi is None or value > self.hi else self.hi
+ if _number(weight) and weight > 0:
+ self.weighted += value * weight
+ self.weights += weight
+
+ def merge(self, other: _Acc) -> None:
+ self.rows += other.rows
+ self.n += other.n
+ self.total += other.total
+ self.weighted += other.weighted
+ self.weights += other.weights
+ for value in (other.lo, other.hi):
+ if value is not None:
+ self.lo = value if self.lo is None or value < self.lo else self.lo
+ self.hi = value if self.hi is None or value > self.hi else self.hi
+
+ def value(self, aggregate: str, weighted: bool = False) -> float | None:
+ if aggregate == "count":
+ return self.rows
+ if not self.n:
+ return None
+ if aggregate == "sum":
+ return _round(self.total)
+ if aggregate == "avg":
+ if weighted:
+ return round(self.weighted / self.weights, 2) if self.weights else None
+ return round(self.total / self.n, 2)
+ return self.lo if aggregate == "min" else self.hi
+
+
+def _round(value: float) -> float:
+ # Float sums carry noise (0.1 + 0.2); a whole number stays an int.
+ return value if isinstance(value, int) else round(value, 6)
+
+
+def _x_order(value: Any) -> tuple[bool, Any]:
+ return (isinstance(value, str), value)
+
+
+@dataclass
+class _Pass:
+ """What the single pass over the rows found."""
+
+ groups: dict[Any, dict[Any, list[_Acc]]] = field(default_factory=dict)
+ points: list[dict[str, Any]] = field(default_factory=list)
+ series_values: dict[Any, None] = field(default_factory=dict)
+ #: Per x group: the first value of each treemap group field, and the colour accumulator.
+ places: dict[Any, dict[str, Any]] = field(default_factory=dict)
+ colors: dict[Any, Any] = field(default_factory=dict)
+ overall: list[_Acc] = field(default_factory=list)
+ matched: int = 0
+ missing_x: int = 0
+
+
+def _collect(
+ spec: ChartSpec,
+ rows: Sequence[Mapping[str, Any]],
+ keep_points: bool,
+ label_key: str | None,
+ unique_x: bool,
+) -> _Pass:
+ """Filter, then group (aggregate), pivot (series) or keep each row as a point."""
+ found = _Pass(overall=[_Acc() for _ in spec.measures])
+ seen_x: set[Any] | None = set() if unique_x else None
+ numeric_color = spec.color is not None
+ for row in rows:
+ if not all(_passes(f, row.get(f.field)) for f in spec.filters):
+ continue
+ found.matched += 1
+ weight = row.get(spec.weight) if spec.weight else None
+ if spec.weight_floor is not None and spec.weight:
+ weight = max(weight if _number(weight) else 0, spec.weight_floor)
+ for acc, measure in zip(found.overall, spec.measures, strict=True):
+ acc.add(None if measure == "count" else row.get(measure), weight)
+ x_value = _x_value(spec, row)
+ if x_value is None:
+ found.missing_x += 1
+ continue
+ s_value = row.get(spec.series) if spec.series else None
+ if spec.series:
+ found.series_values.setdefault(s_value)
+ if spec.groups and x_value not in found.places:
+ found.places[x_value] = {g: row.get(g) for g in spec.groups}
+ if spec.color:
+ value = row.get(spec.color)
+ numeric_color = numeric_color and (value is None or _number(value))
+ found.colors.setdefault(x_value, []).append((value, weight))
+ if keep_points:
+ if seen_x is not None:
+ if x_value in seen_x:
+ raise SpecError(
+ f"x {spec.x!r} repeats ({x_value!r}); add aggregate (count or sum) "
+ "to combine the rows that share it"
+ )
+ seen_x.add(x_value)
+ point = {spec.x: x_value, **{y: row.get(y) for y in spec.y}, "__series": s_value}
+ if label_key:
+ point[label_key] = row.get(label_key)
+ if spec.sort:
+ point[_SORT_KEY] = row.get(spec.sort[0])
+ found.points.append(point)
+ continue
+ cells = found.groups.setdefault(x_value, {})
+ accs = cells.get(s_value)
+ if accs is None:
+ accs = cells[s_value] = [_Acc() for _ in spec.measures]
+ elif spec.aggregate is None:
+ raise SpecError(
+ f"several rows share {spec.x}={x_value!r} and {spec.series}={s_value!r}; "
+ "add aggregate (sum, avg, min or max) to combine them"
+ )
+ for acc, measure in zip(accs, spec.measures, strict=True):
+ acc.add(None if measure == "count" else row.get(measure), weight)
+
+ if found.matched == 0:
+ what = "match the filters" if spec.filters else "were selected"
+ raise SpecError(f"no rows {what} ({len(rows)} rows before filtering)", code="no_data")
+ if found.matched == found.missing_x:
+ raise SpecError(f"no matching row has a value for x {spec.x!r}", code="no_data")
+ found.colors = {
+ x: _color_value(values, numeric_color, bool(spec.weight))
+ for x, values in found.colors.items()
+ }
+ return found
+
+
+def _color_value(values: list[tuple[Any, Any]], numeric: bool, weighted: bool) -> Any:
+ """A group's colour: the average of a number (weighted when asked), else the commonest text."""
+ present = [(v, w) for v, w in values if v is not None]
+ if not present:
+ return None
+ if numeric:
+ acc = _Acc()
+ for v, w in present:
+ acc.add(v, w)
+ return acc.value("avg", weighted)
+ return Counter(_value_label(v) for v, _ in present).most_common(1)[0][0]
+
+
+def _fold_series(spec: ChartSpec, found: _Pass, notes: list[str]) -> None:
+ """Keep the chart's series cap: the largest values stay, the rest fold into Other."""
+ cap = VIEW_LIMITS["chart_series"]
+ if len(found.series_values) <= cap:
+ return
+ if spec.aggregate not in _ADDITIVE:
+ raise SpecError(
+ f"series {spec.series!r} has {len(found.series_values)} values and a chart plots "
+ f"at most {cap}; filter it with op in, or drop series"
+ )
+ totals: Counter[Any] = Counter()
+ for cells in found.groups.values():
+ for s_value, accs in cells.items():
+ totals[s_value] += accs[0].value(spec.aggregate) or 0
+ keep = {s for s, _ in totals.most_common(cap - 1)}
+ folded = len(found.series_values) - len(keep)
+ for cells in found.groups.values():
+ rest = _Acc()
+ for s_value in [s for s in cells if s not in keep]:
+ rest.merge(cells.pop(s_value)[0])
+ if rest.rows:
+ cells[OTHER_LABEL] = [rest]
+ found.series_values = {
+ **{s: None for s in found.series_values if s in keep},
+ OTHER_LABEL: None,
+ }
+ notes.append(
+ f"series {spec.series} has {len(keep) + folded} values; the {len(keep)} largest are "
+ f"drawn and {folded} more are added up as {OTHER_LABEL}"
+ )
+
+
+def _measure_columns(spec: ChartSpec, found: _Pass) -> tuple[list[str], list[str]]:
+ """Keys and labels of the plotted columns: one per measure, or one per series value."""
+ if spec.series:
+ keys = [f"s{i + 1}" for i in range(len(found.series_values))]
+ return keys, [_value_label(v) for v in found.series_values]
+ keys = ["row_count" if m == "count" and spec.x == "count" else m for m in spec.measures]
+ labels = [_measure_label(spec, m) for m in spec.measures]
+ return keys, labels
+
+
+def _measure_label(spec: ChartSpec, measure: str) -> str:
+ if measure == "count":
+ return _AGGREGATE_LABEL["count"]
+ if spec.aggregate in ("avg", "min", "max"):
+ return f"{_AGGREGATE_LABEL[spec.aggregate]} {label(measure).lower()}"
+ return label(measure)
+
+
+def _chart_rows(
+ spec: ChartSpec, found: _Pass, keys: list[str], label_key: str | None
+) -> list[dict[str, Any]]:
+ by_value = dict(zip(found.series_values, keys, strict=True)) if spec.series else {}
+ weighted = bool(spec.weight)
+ out: list[dict[str, Any]] = []
+ for p in found.points:
+ if spec.series:
+ # One series per point: the other series columns stay null.
+ row_out = {spec.x: p[spec.x], **dict.fromkeys(keys)}
+ row_out[by_value[p["__series"]]] = p.get(spec.y[0])
+ else:
+ values = zip(keys, spec.measures, strict=True)
+ row_out = {spec.x: p[spec.x], **{k: p.get(m) for k, m in values}}
+ if label_key:
+ row_out[label_key] = p[label_key]
+ if _SORT_KEY in p:
+ row_out[_SORT_KEY] = p[_SORT_KEY]
+ out.append(row_out)
+ # Without aggregate each cell holds one row's value, read through "sum".
+ aggregate = spec.aggregate or "sum"
+ empty = 0 if spec.aggregate in _ADDITIVE else None
+ for x_value, cells in found.groups.items():
+ row_out = {spec.x: x_value}
+ if spec.series:
+ row_out.update(dict.fromkeys(keys, empty))
+ for s_value, accs in cells.items():
+ row_out[by_value[s_value]] = accs[0].value(aggregate, weighted)
+ else:
+ row_out.update(
+ (k, acc.value(aggregate, weighted))
+ for k, acc in zip(keys, cells[None], strict=True)
+ )
+ out.append(row_out)
+ for row_out in out:
+ place = found.places.get(row_out[spec.x], {})
+ for g in spec.groups:
+ row_out[g] = place.get(g)
+ if spec.color:
+ row_out[_color_key(spec, keys)] = found.colors.get(row_out[spec.x])
+ return out
+
+
+def _color_key(spec: ChartSpec, keys: list[str]) -> str:
+ key = spec.color or "color"
+ return f"{key}_color" if key in keys or key == spec.x else key
+
+
+def _total(row: Mapping[str, Any], keys: list[str]) -> float:
+ return sum(v for k in keys if isinstance(v := row.get(k), (int, float)))
+
+
+def _sort(
+ spec: ChartSpec, out: list[dict[str, Any]], keys: list[str], x_type: str, scatter: bool
+) -> tuple[tuple[str, str] | None, str | None]:
+ """Sort *out* in place; returns the sort used and the order a chart may claim.
+
+ As asked; else grouped categories largest first and dates oldest first.
+ """
+ sort = spec.sort
+ if sort is None and x_type == "time":
+ sort = (spec.x, "asc")
+ elif sort is None and spec.aggregate and not scatter:
+ sort = ("__total", "desc")
+ if sort is None:
+ return None, None
+ name, order = sort
+ reverse = order == "desc"
+ if name == spec.x:
+ out.sort(key=lambda r: _x_order(r[spec.x]), reverse=reverse)
+ return sort, None
+ # Series columns sort by their row total; a measure by its own value; any
+ # other field by the value each point carried from its row.
+ if name in spec.measures:
+ key = None if spec.series else keys[spec.measures.index(name)]
+ else:
+ key = None if name == "__total" else _SORT_KEY
+
+ def value_of(r: Mapping[str, Any]) -> Any:
+ return _total(r, keys) if key is None else r.get(key)
+
+ # Nulls last either way; a stable sort keeps ties in source order.
+ present = [r for r in out if value_of(r) is not None]
+ present.sort(key=value_of, reverse=reverse)
+ out[:] = present + [r for r in out if value_of(r) is None]
+ # A chart claims an order only by its series total, which a null has no place in.
+ sums = key != _SORT_KEY and (key is None or len(keys) == 1)
+ claim = order if sums and all(r.get(k) is not None for r in out for k in keys) else None
+ return sort, claim
+
+
+def _is_scatter(spec: ChartSpec, x_type: str) -> bool:
+ return spec.kind == "scatter" or (
+ spec.kind == "auto" and spec.aggregate is None and x_type == "number"
+ )
+
+
+def transform(
+ spec: ChartSpec, rows: Sequence[Mapping[str, Any]], types: Mapping[str, str]
+) -> ChartRows:
+ """Filter, group, sort and cut *rows* by *spec*, and pick the chart type.
+
+ *spec* must already pass ``fit`` (or ``check_fields``) for these *types*.
+ """
+ x_type = "text" if spec.x_parts else types[spec.x]
+ scatter = _is_scatter(spec, x_type)
+ table = spec.kind == "table"
+ label_key = None
+ if spec.aggregate is None and not spec.series:
+ label_key = next(
+ (
+ k
+ for k in _LABEL_FIELDS
+ if k in types and k != spec.x and k not in spec.y and k not in spec.x_parts
+ ),
+ None,
+ )
+ keep_points = spec.aggregate is None and (scatter or table or not spec.series)
+ notes: list[str] = list(spec.notes)
+ found = _collect(spec, rows, keep_points, label_key, unique_x=not (scatter or table))
+ if spec.series:
+ _fold_series(spec, found, notes)
+ keys, labels = _measure_columns(spec, found)
+ columns = [(spec.x, _x_label(spec)), *zip(keys, labels, strict=True)]
+ if label_key:
+ columns.insert(0, (label_key, label(label_key)))
+ if spec.groups:
+ columns[:0] = [(g, label(g)) for g in spec.groups]
+ if spec.color:
+ color_label = label(spec.color)
+ if spec.aggregate and types.get(spec.color) == "number":
+ color_label = f"Average {color_label.lower()}"
+ columns.append((_color_key(spec, keys), color_label))
+ out = _chart_rows(spec, found, keys, label_key)
+ if spec.x_step == "week" and spec.aggregate:
+ out = _fill_weeks(spec, out, keys)
+ sort, claim = _sort(spec, out, keys, x_type, scatter)
+
+ top, other = spec.top, spec.other
+ additive_one = len(keys) == 1 and spec.aggregate in _ADDITIVE
+ if (
+ spec.kind == "donut"
+ and additive_one
+ and len(out) > VIEW_LIMITS["donut_max_parts"]
+ and x_type == "text"
+ and (top is None or top > _DONUT_KEEP)
+ ):
+ top, other = _DONUT_KEEP, True
+ notes.append(
+ f"a donut holds {VIEW_LIMITS['donut_max_parts']} parts, so the largest {_DONUT_KEEP} "
+ f"are drawn and the other {len(out) - _DONUT_KEEP} are added up as {OTHER_LABEL}"
+ )
+ if sort is None or sort[0] == spec.x:
+ out.sort(key=lambda r: -(r.get(keys[0]) or 0))
+
+ # Top N, with the rest added up as Other; else the chart-point cap.
+ total_rows = len(out)
+ all_rows = out
+ folded = False
+ if top is not None and len(out) > top:
+ rest, out = out[top:], out[:top]
+ if other:
+ bucket: dict[str, Any] = {spec.x: f"{OTHER_LABEL} ({len(rest)} more)"}
+ for k in keys:
+ values = [r[k] for r in rest if isinstance(r.get(k), (int, float))]
+ bucket[k] = _round(sum(values)) if values else None
+ for g in spec.groups:
+ bucket[g] = OTHER_LABEL
+ if spec.color:
+ bucket[_color_key(spec, keys)] = None
+ if label_key:
+ bucket[label_key] = None
+ out.append(bucket)
+ # The bucket sits last whatever its size, so no order is claimed.
+ folded, claim, total_rows = True, None, len(out)
+ cap = VIEW_LIMITS["rows"] if table else VIEW_LIMITS["chart_points"]
+ if len(out) > cap:
+ # A time axis keeps its newest points; anything else keeps its first.
+ newest = x_type == "time" and (sort is None or sort[0] == spec.x)
+ out = out[-cap:] if newest else out[:cap]
+
+ for row in out:
+ row.pop(_SORT_KEY, None)
+ chart_type, reason, kind_note = _choose_kind(
+ spec, x_type, keys, out, total_rows > len(out), scatter
+ )
+ return ChartRows(
+ x=spec.x,
+ x_type=x_type,
+ columns=columns,
+ series=keys,
+ rows=out,
+ chart_type=chart_type,
+ reason=reason,
+ total_rows=total_rows,
+ matched=found.matched,
+ source_rows=len(rows),
+ missing_x=found.missing_x,
+ sort=claim if chart_type not in ("scatter", "treemap", "table") else None,
+ other=folded,
+ kind_note=kind_note or spec.kind_note,
+ figures=_figures(spec, found, keys, labels, all_rows, out, folded, x_type == "time"),
+ notes=notes,
+ groups=list(spec.groups),
+ color=_color_key(spec, keys) if spec.color else None,
+ )
+
+
+def _fill_weeks(spec: ChartSpec, out: list[dict[str, Any]], keys: list[str]) -> list[dict[str, Any]]:
+ """Weeks between the first and last with no row, as rows of zero (or null for an average)."""
+ from datetime import date, timedelta
+
+ try:
+ present = {date.fromisoformat(str(r[spec.x])[:10]): r for r in out}
+ except ValueError:
+ return out
+ if len(present) < 2:
+ return out
+ empty = 0 if spec.aggregate in _ADDITIVE else None
+ day, last = min(present), max(present)
+ filled = []
+ while day <= last:
+ row = present.get(day)
+ filled.append(row if row is not None else {spec.x: day.isoformat(), **dict.fromkeys(keys, empty)})
+ day += timedelta(days=7)
+ # Rows off the Monday grid (none from the changes dataset) stay as they were.
+ on_grid = {id(r) for r in filled}
+ return filled + [r for r in out if id(r) not in on_grid]
+
+
+def _x_label(spec: ChartSpec) -> str:
+ if spec.x_parts:
+ return f" {ARROW} ".join(label(p) for p in spec.x_parts)
+ return label(spec.x)
+
+
+def _pct(part: float, whole: float) -> float:
+ return round(100 * part / whole, 1)
+
+
+def _figures(
+ spec: ChartSpec,
+ found: _Pass,
+ keys: list[str],
+ labels: list[str],
+ all_rows: list[dict[str, Any]],
+ shown: list[dict[str, Any]],
+ folded: bool,
+ time_axis: bool = False,
+) -> dict[str, Any]:
+ """The numbers a reply quotes: totals and shares of a whole, or the overall average."""
+ figures: dict[str, Any] = {"rows_matched": found.matched, "groups": len(all_rows)}
+ if spec.aggregate in _ADDITIVE:
+ totals = {
+ label_: _round(sum(r.get(k) or 0 for r in all_rows))
+ for k, label_ in zip(keys, labels, strict=True)
+ }
+ whole = sum(totals.values())
+ figures["total"] = _round(whole)
+ if len(keys) > 1:
+ figures["total_by_series"] = totals
+ if whole > 0:
+ figures["shares"] = [
+ {
+ "x": _value_label(r[spec.x]),
+ "value": _round(_total(r, keys)),
+ "pct": _pct(_total(r, keys), whole),
+ }
+ for r in shown[:_SHARES_LISTED]
+ ]
+ if folded:
+ figures["shares_note"] = f"pct is of the total {figures['total']}, Other included"
+ elif spec.aggregate in ("avg", "min", "max") and not spec.series:
+ weighted = bool(spec.weight)
+ figures["overall"] = {
+ label_: acc.value(spec.aggregate, weighted)
+ for acc, label_ in zip(found.overall, labels, strict=True)
+ }
+ if weighted:
+ figures["weighted_by"] = spec.weight
+ if "shares" not in figures:
+ # Over time the newest rows matter most, and the first one anchors a change.
+ newest = time_axis and len(shown) > _ROWS_PREVIEWED
+ preview = shown[-_ROWS_PREVIEWED:] if newest else shown[:_ROWS_PREVIEWED]
+ figures["rows"] = [{k: _preview(v) for k, v in r.items() if v is not None} for r in preview]
+ if newest:
+ figures["first_row"] = {k: _preview(v) for k, v in shown[0].items() if v is not None}
+ if len(shown) > _ROWS_PREVIEWED:
+ which = "newest" if newest else "first"
+ figures["rows_note"] = f"the {which} {_ROWS_PREVIEWED} of {len(shown)} drawn rows"
+ return figures
+
+
+def _preview(value: Any) -> Any:
+ if isinstance(value, bool):
+ return _value_label(value)
+ return round(value, 2) if isinstance(value, float) else value
diff --git a/packages/server/src/repowise/server/chat_view_builders.py b/packages/server/src/repowise/server/chat_view_builders.py
new file mode 100644
index 000000000..1811b285d
--- /dev/null
+++ b/packages/server/src/repowise/server/chat_view_builders.py
@@ -0,0 +1,609 @@
+"""The named views ``show_view`` builds from a tool result: ``table``, ``chart``
+and one per known result shape (``health.bands``, ``changes.by_week``, ...).
+
+Each is registered on the ``chat-view`` seam when :mod:`repowise.server.chat_views`
+is imported. A named view takes ``options.kind`` when its rows fit that kind.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from typing import Any
+
+# The module, not its names: it may still be loading when chat_views imports this one.
+from repowise.server import chat_chart_part, chat_spec
+from repowise.server.chat_references import (
+ ViewArtifact,
+)
+from repowise.server.chat_spec import SpecError
+from repowise.server.chat_spec import label as _label
+from repowise.server.chat_views import _PERSON, ViewError, _cell, _wire, register_view_builder
+from repowise.server.schemas.views import (
+ VIEW_LIMITS,
+)
+
+_DEFAULT_ROWS = 50
+
+
+def _basis(kind: str, source: str) -> dict[str, str]:
+ return {"kind": kind, "source": source}
+
+
+def _tool_basis(artifact: ViewArtifact) -> dict[str, str]:
+ declared = artifact.data.get("evidence_kind") or artifact.data.get("basis")
+ kind = declared if declared in ("measured", "inferred", "declared") else artifact.evidence_basis
+ if kind not in ("measured", "inferred", "declared"):
+ return _basis("unresolved", artifact.tool_name)
+ return _basis(kind, artifact.tool_name)
+
+
+def _limit(options: Mapping[str, Any], default: int = _DEFAULT_ROWS, cap: int | None = None) -> int:
+ cap = cap or VIEW_LIMITS["rows"]
+ value = options.get("limit", default)
+ if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+ raise ViewError("limit must be a positive integer", code="bad_arguments")
+ return min(value, cap)
+
+
+def _node(data: Any, path: str) -> Any:
+ node = data
+ for segment in path.split("."):
+ if isinstance(node, Mapping) and segment in node:
+ node = node[segment]
+ elif isinstance(node, list) and segment.isdigit() and int(segment) < len(node):
+ node = node[int(segment)]
+ else:
+ raise ViewError(f"no {path!r} in the artifact", code="bad_path")
+ return node
+
+
+def _tabular(node: Any, scalars: bool = False) -> list[dict[str, Any]] | None:
+ """Rows from a list of objects, a map of objects keyed by id, or (*scalars*)
+ a map of plain values such as ``{"fix": 312, "feature": 120}`` as ``{key, value}``."""
+ if isinstance(node, list) and node and all(isinstance(row, Mapping) for row in node):
+ return [dict(row) for row in node]
+ if isinstance(node, Mapping) and node and all(isinstance(v, Mapping) for v in node.values()):
+ return [{"id": key, **value} for key, value in node.items()]
+ if (
+ scalars
+ and isinstance(node, Mapping)
+ and node
+ and all(isinstance(v, (str, int, float, bool)) or v is None for v in node.values())
+ ):
+ return [{"key": str(key), "value": value} for key, value in node.items()]
+ return None
+
+
+def _table_paths(data: Mapping[str, Any], prefix: str = "", depth: int = 0) -> list[str]:
+ paths: list[str] = []
+ for key, value in data.items():
+ if key == "_meta" or _PERSON.search(key):
+ continue
+ path = f"{prefix}{key}"
+ if _tabular(value) is not None:
+ paths.append(path)
+ elif isinstance(value, Mapping) and depth < 2:
+ paths.extend(_table_paths(value, f"{path}.", depth + 1))
+ return paths
+
+
+def _rows_at(
+ data: Mapping[str, Any], path: Any, option: str
+) -> tuple[str, list[dict[str, Any]], int]:
+ """The list or map of objects at *path* (picked when the result holds one),
+ its rows, and the row count the tool reports for it (``<leaf>_total``)."""
+ if path is None:
+ candidates = _table_paths(data)
+ if len(candidates) != 1:
+ raise ViewError(
+ f"pass options.{option}; tables in this result: {candidates}", code="bad_path"
+ )
+ path = candidates[0]
+ if not isinstance(path, str) or any(_PERSON.search(seg) for seg in path.split(".")):
+ raise ViewError(f"views never group by person ({path!r})", code="person_grouping")
+ rows = _tabular(_node(data, path), scalars=True)
+ if rows is None:
+ raise ViewError(
+ f"{path!r} is not a list or map; tables in this result: {_table_paths(data)}",
+ code="bad_path",
+ )
+ parent_path, _, leaf = path.rpartition(".")
+ parent = _node(data, parent_path) if parent_path else data
+ total = parent.get(f"{leaf}_total") if isinstance(parent, Mapping) else None
+ return path, rows, total if isinstance(total, int) and total >= len(rows) else len(rows)
+
+
+@register_view_builder(
+ "table",
+ description="Any list or map of objects in a result, as a table.",
+ options={"path", "columns", "limit"},
+)
+def table_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
+ path, rows, total_rows = _rows_at(artifact.data, options.get("path"), "path")
+ wanted = options.get("columns")
+ if wanted is not None and not (
+ isinstance(wanted, list) and all(isinstance(k, str) for k in wanted)
+ ):
+ raise ViewError("columns must be a list of keys", code="bad_arguments")
+ keys = list(dict.fromkeys(k for row in rows for k in row))
+ # A column is a key whose every value is a cell; nested values and people are left out.
+ keys = [
+ k
+ for k in keys
+ if not _PERSON.search(k)
+ and re.fullmatch(r"[a-z][a-z0-9_]{0,63}", k)
+ and all(_cell(k, row.get(k)) is not ... for row in rows)
+ ]
+ if wanted is not None:
+ if missing := [k for k in wanted if k not in keys]:
+ raise ViewError(
+ f"columns not available as cells: {missing}; columns of {path!r}: {keys}",
+ code="bad_arguments",
+ suggested_options={**options, "columns": [k for k in wanted if k in keys] or keys},
+ )
+ keys = list(dict.fromkeys(wanted))
+ keys = keys[: VIEW_LIMITS["columns"]]
+ if not keys:
+ raise ViewError(f"{path!r} has no scalar fields to show", code="bad_path")
+
+ shown = rows[: _limit(options)]
+ return {
+ "kind": "table",
+ "title": f"{artifact.tool_name}: {path}",
+ "summary": f"{len(shown)} of {total_rows} rows.",
+ "basis": _tool_basis(artifact),
+ "columns": [{"key": k, "label": _label(k)} for k in keys],
+ "rows": [{k: _cell(k, row.get(k)) for k in keys} for row in shown],
+ "total_rows": total_rows,
+ "truncated": total_rows > len(shown),
+ }
+
+
+@register_view_builder(
+ "chart",
+ description="A chart you specify over any list or map in a result.",
+ options=chat_spec.OPTIONS,
+)
+def chart_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
+ path, rows, source_total = _rows_at(artifact.data, options.get("rows"), "rows")
+ source = chat_chart_part.ChartSource(
+ rows=rows,
+ what=f"rows of {path}",
+ basis=_tool_basis(artifact),
+ total=source_total,
+ path=tuple(path.split(".")),
+ )
+ return chat_chart_part.chart_part(source, options)
+
+
+#: Kinds a named view takes in ``options.kind``: categories, or points in time.
+_CATEGORY_KINDS = ("bar", "horizontal_bar", "donut", "table")
+
+
+_TIME_KINDS = ("line", "area", "bar", "table")
+
+
+def _chart(
+ *,
+ title: str,
+ summary: str,
+ basis: dict[str, str],
+ x: tuple[str, str],
+ series: list[tuple[str, str]],
+ unit: str,
+ rows: list[dict[str, Any]],
+ total_rows: int | None = None,
+ chart_type: str = "bar",
+ options: Mapping[str, Any] | None = None,
+ kinds: tuple[str, ...] = _CATEGORY_KINDS,
+ parts: bool = True,
+) -> dict[str, Any]:
+ """A named view's chart. ``options.kind`` redraws it as another of *kinds*
+ when the rows fit that kind; *parts* says the rows add up to a whole, so
+ the receipt carries their total and shares."""
+ if not rows:
+ raise ViewError("this result has nothing to chart", code="no_data")
+ total = len(rows) if total_rows is None else max(total_rows, len(rows))
+ part: dict[str, Any] = {
+ "kind": "chart",
+ "chart_type": chart_type,
+ "title": title,
+ "summary": summary,
+ "basis": basis,
+ "x": x[0],
+ "series": [key for key, _ in series],
+ "data": {
+ "columns": [
+ {"key": x[0], "label": x[1]},
+ *({"key": key, "label": label, "unit": unit} for key, label in series),
+ ],
+ "rows": rows,
+ "total_rows": total,
+ "truncated": total > len(rows),
+ },
+ }
+ receipt: dict[str, Any] = {}
+ if parts and len(series) == 1:
+ receipt["figures"] = _shares(rows, x[0], series[0][0])
+ asked = (options or {}).get("kind")
+ if asked is not None:
+ _redraw(part, asked, kinds, receipt)
+ if receipt:
+ part["receipt"] = {**({"chart_type": part["chart_type"]} if part["kind"] == "chart" else {}), **receipt}
+ return part
+
+
+def _shares(rows: list[dict[str, Any]], x: str, key: str) -> dict[str, Any]:
+ values = [(_label_of(r[x]), r[key]) for r in rows if isinstance(r.get(key), (int, float))]
+ whole = sum(v for _, v in values)
+ figures: dict[str, Any] = {"total": whole}
+ if whole > 0:
+ figures["shares"] = [
+ {"x": name, "value": v, "pct": round(100 * v / whole, 1)} for name, v in values[:12]
+ ]
+ return figures
+
+
+def _label_of(cell: Any) -> str:
+ return str(cell.get("id")) if isinstance(cell, Mapping) else str(cell)
+
+
+def _redraw(part: dict[str, Any], asked: Any, kinds: tuple[str, ...], receipt: dict[str, Any]) -> None:
+ """Draw *part* as the *asked* kind when its rows fit it; else keep it and say why."""
+ try:
+ kind, note = chat_spec.read_kind(asked)
+ except SpecError as exc:
+ raise ViewError(f"{exc}; this view takes {list(kinds)}", code="bad_arguments") from None
+ if note:
+ receipt.setdefault("notes", []).append(note)
+ drawn = part["chart_type"]
+ if kind == drawn or kind == "auto":
+ return
+ if kind not in kinds:
+ receipt["kind_note"] = (
+ f"this view draws as {', '.join(kinds)}, not {kind}, so it stays a {drawn}"
+ )
+ return
+ data = part["data"]
+ if kind == "table":
+ for key in ("chart_type", "x", "series", "sort", "data"):
+ part.pop(key, None)
+ part.update(kind="table", **data)
+ return
+ if kind == "donut":
+ values = [r.get(s) for r in data["rows"] for s in part["series"]]
+ low, high = VIEW_LIMITS["donut_min_parts"], VIEW_LIMITS["donut_max_parts"]
+ fits = (
+ len(part["series"]) == 1
+ and low <= len(data["rows"]) <= high
+ and not data["truncated"]
+ and all(isinstance(v, (int, float)) and v >= 0 for v in values)
+ and sum(values) > 0
+ )
+ if not fits:
+ receipt["kind_note"] = (
+ f"a donut shows {low} to {high} parts of one whole, which these "
+ f"{len(data['rows'])} rows are not, so it stays a {drawn}"
+ )
+ return
+ part["chart_type"] = kind
+ part.pop("sort", None)
+
+
+_HEALTH_BANDS = ("at_risk", "needs_work", "fair", "good", "excellent")
+
+
+@register_view_builder(
+ "health.bands",
+ description="Files per health band.",
+ artifact_types={"health", "overview"},
+ options=frozenset({"kind"}),
+)
+def health_bands_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
+ data = artifact.data
+ distribution = data.get("distribution") or (data.get("code_health") or {}).get("distribution")
+ bands = distribution.get("bands") if isinstance(distribution, Mapping) else None
+ if not isinstance(bands, Mapping):
+ raise ViewError("this result has no health distribution; call get_health with no targets")
+ rows = [
+ {"band": band.replace("_", " "), "files": bands[band]["files"]}
+ for band in _HEALTH_BANDS
+ if isinstance(bands.get(band), Mapping) and isinstance(bands[band].get("files"), int)
+ ]
+ total = sum(row["files"] for row in rows)
+ return _chart(
+ title="Files by health band",
+ summary=f"{total} files across {len(rows)} health bands.",
+ basis=_basis("inferred", "health engine"),
+ x=("band", "Health band"),
+ series=[("files", "Files")],
+ unit="files",
+ rows=rows,
+ options=options,
+ )
+
+
+@register_view_builder(
+ "health.trend",
+ description="Average and hotspot health over recent snapshots.",
+ artifact_types={"health"},
+ options=frozenset({"kind"}),
+)
+def health_trend_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
+ trend = artifact.data.get("trend")
+ recent = trend.get("recent") if isinstance(trend, Mapping) else None
+ if not isinstance(recent, list) or not recent:
+ raise ViewError('this result has no trend; call get_health(include=["trend"])')
+ snapshots = sorted(
+ (s for s in recent if isinstance(s, Mapping) and isinstance(s.get("taken_at"), str)),
+ key=lambda s: s["taken_at"],
+ )
+ rows = [
+ {
+ "taken_at": s["taken_at"],
+ "average_health": _wire(s.get("average_health")),
+ "hotspot_health": _wire(s.get("hotspot_health")),
+ }
+ for s in snapshots
+ ]
+ total = trend.get("recent_total")
+ return _chart(
+ chart_type="line",
+ title="Health over recent snapshots",
+ summary=f"{len(rows)} health snapshots, oldest first.",
+ basis=_basis("inferred", "health snapshots"),
+ x=("taken_at", "Snapshot"),
+ series=[("average_health", "Average health"), ("hotspot_health", "Hotspot health")],
+ unit="score",
+ rows=rows,
+ total_rows=total if isinstance(total, int) else None,
+ options=options,
+ kinds=_TIME_KINDS,
+ parts=False,
+ )
+
+
+@register_view_builder(
+ "health.test_coverage",
+ description="Measured line coverage per file, from the ingested coverage report.",
+ artifact_types={"health"},
+ options=frozenset({"limit", "kind"}),
+)
+def health_test_coverage_view(
+ artifact: ViewArtifact, options: Mapping[str, Any]
+) -> dict[str, Any]:
+ coverage = artifact.data.get("coverage")
+ files = coverage.get("files") if isinstance(coverage, Mapping) else None
+ if not isinstance(files, list):
+ raise ViewError('this result has no coverage; call get_health(include=["coverage"])')
+ usable = [f for f in files if isinstance(f, Mapping) and f.get("file_path")]
+ shown = usable[: _limit(options, cap=100)]
+ rows = [
+ {
+ "file": {"type": "file", "id": f["file_path"]},
+ "line_coverage": _wire(f.get("line_coverage_pct")),
+ }
+ for f in shown
+ ]
+ summary_pct = (coverage.get("summary") or {}).get("line_coverage_pct")
+ total = coverage.get("files_total")
+ total = max(total, len(usable)) if isinstance(total, int) else len(usable)
+ part = _chart(
+ title="Line coverage by file",
+ summary=f"{len(rows)} files from the coverage report.",
+ basis=_basis("measured", "coverage report"),
+ x=("file", "File"),
+ series=[("line_coverage", "Line coverage")],
+ unit="%",
+ rows=rows,
+ total_rows=total,
+ options=options,
+ parts=False,
+ )
+ if isinstance(summary_pct, (int, float)) and 0 <= summary_pct <= 100:
+ # Rounded so the percentage converts without float noise (88.84 -> 0.8884).
+ part["coverage"] = {"metric": "test_reach", "ratio": round(summary_pct / 100, 6)}
+ return part
+
+
+@register_view_builder(
+ "dead_code.by_tier",
+ description="Dead-code findings per confidence tier.",
+ artifact_types={"dead_code"},
+ options=frozenset({"kind"}),
+)
+def dead_code_by_tier_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
+ tiers = artifact.data.get("tiers")
+ if not isinstance(tiers, Mapping):
+ raise ViewError("this result has no confidence tiers")
+ rows = [
+ {"tier": tier, "findings": tiers[tier]["count"]}
+ for tier in ("high", "medium", "low")
+ if isinstance(tiers.get(tier), Mapping) and isinstance(tiers[tier].get("count"), int)
+ ]
+ return _chart(
+ title="Dead-code findings by tier",
+ summary=f"{sum(r['findings'] for r in rows)} findings kept by the call's filters.",
+ basis=_basis("inferred", "reachability graph"),
+ x=("tier", "Confidence tier"),
+ series=[("findings", "Findings")],
+ unit="findings",
+ rows=rows,
+ options=options,
+ )
+
+
+@register_view_builder(
+ "dead_code.by_kind",
+ description="Open dead-code findings per kind.",
+ artifact_types={"dead_code"},
+ options=frozenset({"kind"}),
+)
+def dead_code_by_kind_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
+ by_kind = (artifact.data.get("summary") or {}).get("by_kind")
+ if not isinstance(by_kind, Mapping) or not by_kind:
+ raise ViewError("this result has no findings by kind")
+ rows = [
+ {"kind": kind, "findings": count}
+ for kind, count in by_kind.items()
+ if isinstance(count, int) and not isinstance(count, bool)
+ ]
+ return _chart(
+ title="Dead-code findings by kind",
+ summary=f"{sum(r['findings'] for r in rows)} open findings.",
+ basis=_basis("inferred", "reachability graph"),
+ x=("kind", "Kind"),
+ series=[("findings", "Findings")],
+ unit="findings",
+ rows=rows,
+ options=options,
+ )
+
+
+@register_view_builder(
+ "risk.hotspots",
+ description="Bug-fix commits on the repository's top hotspots.",
+ artifact_types={"risk"},
+ options=frozenset({"limit", "kind"}),
+)
+def risk_hotspots_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
+ hotspots = artifact.data.get("global_hotspots")
+ if not isinstance(hotspots, list) or not hotspots:
+ raise ViewError("this result has no global hotspots")
+ usable = [h for h in hotspots if isinstance(h, Mapping) and h.get("file_path")]
+ shown = usable[: _limit(options, cap=100)]
+ rows = [
+ {"file": {"type": "file", "id": h["file_path"]}, "fix_count": _wire(h.get("fix_count"))}
+ for h in shown
+ ]
+ total = artifact.data.get("global_hotspots_total")
+ total = max(total, len(usable)) if isinstance(total, int) else len(usable)
+ return _chart(
+ title="Bug fixes on top hotspots",
+ summary=f"Bug-fix commits on {len(rows)} hotspot files.",
+ basis=_basis("measured", "git history"),
+ x=("file", "File"),
+ series=[("fix_count", "Bug-fix commits")],
+ unit="commits",
+ rows=rows,
+ total_rows=total,
+ options=options,
+ parts=False,
+ )
+
+
+def _changes_block(artifact: ViewArtifact) -> Mapping[str, Any]:
+ block = artifact.data.get("changes")
+ if not isinstance(block, Mapping) or not block.get("total"):
+ raise ViewError(
+ 'this result has no change records; call get_overview(include=["changes"])'
+ )
+ return block
+
+
+def _window(block: Mapping[str, Any]) -> str:
+ window = block.get("window")
+ start = window.get("history_from") if isinstance(window, Mapping) else None
+ if isinstance(start, str):
+ return f" since {start[:10]}, where the indexed history starts"
+ days = window.get("days") if isinstance(window, Mapping) else None
+ return f" over the last {days} days of merged changes" if isinstance(days, int) else ""
+
+
+@register_view_builder(
+ "changes.by_category",
+ description="Merged changes per category (feature, fix, ...).",
+ artifact_types={"overview"},
+ options=frozenset({"kind"}),
+)
+def changes_by_category_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
+ block = _changes_block(artifact)
+ by_category = block.get("by_category")
+ rows = [
+ {"category": category, "changes": count}
+ for category, count in (by_category.items() if isinstance(by_category, Mapping) else ())
+ if isinstance(count, int) and not isinstance(count, bool)
+ ]
+ return _chart(
+ title="Changes by category",
+ summary=f"{sum(r['changes'] for r in rows)} changes{_window(block)}.",
+ basis=_basis("measured", "git history"),
+ x=("category", "Category"),
+ series=[("changes", "Changes")],
+ unit="changes",
+ rows=rows,
+ options=options,
+ )
+
+
+@register_view_builder(
+ "changes.by_week",
+ description="Merged changes per week.",
+ artifact_types={"overview"},
+ options=frozenset({"kind"}),
+)
+def changes_by_week_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
+ block = _changes_block(artifact)
+ weeks = block.get("by_week")
+ rows = [
+ {"week": w["week"], "changes": w["changes"]}
+ for w in (weeks if isinstance(weeks, list) else ())
+ if isinstance(w, Mapping)
+ and isinstance(w.get("week"), str)
+ and isinstance(w.get("changes"), int)
+ and not isinstance(w.get("changes"), bool)
+ ][-VIEW_LIMITS["chart_points"] :]
+ return _chart(
+ chart_type="line",
+ title="Changes per week",
+ summary=f"{len(rows)} weeks{_window(block)}, oldest first.",
+ basis=_basis("measured", "git history"),
+ x=("week", "Week of"),
+ series=[("changes", "Changes")],
+ unit="changes",
+ rows=rows,
+ options=options,
+ kinds=_TIME_KINDS,
+ )
+
+
+_PROVENANCE_BANDS = (
+ ("agent", "agent_changes"),
+ ("human attested", "human_attested_changes"),
+ ("unknown", "unknown_changes"),
+)
+
+
+@register_view_builder(
+ "changes.provenance",
+ description="Merged changes by source: agent, human-attested, unknown.",
+ artifact_types={"overview"},
+ options=frozenset(),
+ coverage_metric="attribution",
+)
+def changes_provenance_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
+ block = _changes_block(artifact)
+ provenance = block.get("provenance")
+ if not isinstance(provenance, Mapping) or "coverage" not in provenance:
+ raise ViewError("attribution is off for this repository", code="attribution_off")
+ # Unknown is its own band, never folded into human.
+ rows = [
+ {"source": label, "changes": provenance[key]}
+ for label, key in _PROVENANCE_BANDS
+ if isinstance(provenance.get(key), int) and not isinstance(provenance.get(key), bool)
+ ]
+ part = _chart(
+ chart_type="donut",
+ title="Changes by source",
+ summary=f"{sum(r['changes'] for r in rows)} changes{_window(block)}.",
+ basis=_basis("measured", "git attribution markers"),
+ x=("source", "Source"),
+ series=[("changes", "Changes")],
+ unit="changes",
+ rows=rows,
+ )
+ coverage = provenance.get("coverage")
+ if isinstance(coverage, (int, float)) and not isinstance(coverage, bool):
+ part["coverage"] = {"metric": "attribution", "ratio": coverage}
+ return part
diff --git a/packages/server/src/repowise/server/chat_view_spec.py b/packages/server/src/repowise/server/chat_view_spec.py
deleted file mode 100644
index a0a4638c4..000000000
--- a/packages/server/src/repowise/server/chat_view_spec.py
+++ /dev/null
@@ -1,699 +0,0 @@
-"""The ``chart`` view's spec: parse and check it, then turn rows into chart rows.
-
-Pure functions over a list of row dicts; the ``chart`` builder in
-:mod:`repowise.server.chat_views` picks the rows, applies the view guards and
-makes the part. One pass over the rows filters and groups; sort, top and the
-Other bucket then work on the groups. Every refusal is a ``SpecError`` whose
-message says what to change, and names the fields the rows hold, so the model
-can fix its spec in one retry.
-"""
-
-from __future__ import annotations
-
-import difflib
-import re
-from collections.abc import Mapping, Sequence
-from dataclasses import dataclass, field
-from typing import Any
-
-from repowise.server.schemas.views import VIEW_LIMITS
-
-AGGREGATES = ("count", "sum", "avg", "min", "max")
-OPS = ("eq", "ne", "lt", "lte", "gt", "gte", "in", "contains", "prefix")
-KINDS = ("auto", "bar", "stacked_bar", "line", "donut", "scatter")
-OPTIONS = frozenset(
- {"rows", "x", "y", "series", "filter", "group_by", "aggregate", "sort", "top", "other"}
- | {"kind", "title", "subtitle"}
-)
-OTHER_LABEL = "Other"
-
-_ADDITIVE = frozenset({"count", "sum"})
-_AGGREGATE_LABEL = {
- "count": "Count",
- "sum": "Total",
- "avg": "Average",
- "min": "Lowest",
- "max": "Highest",
-}
-_KEY = re.compile(r"^[a-z][a-z0-9_]{0,63}$")
-_TIME = re.compile(
- r"^\d{4}-\d{2}(-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?)?(Z|[+-]\d{2}:?\d{2})?)?$"
-)
-# Fields that name a point in a scatter or an unaggregated chart, in preference order.
-_LABEL_FIELDS = ("file_path", "path", "name", "title", "id")
-_MAX_FILTERS = 10
-_MAX_TEXT = 120
-_FIELDS_SHOWN = 30
-
-
-class SpecError(ValueError):
- """A spec the rows cannot satisfy; the message says what to change."""
-
- def __init__(
- self, message: str, code: str = "bad_spec", fields: Mapping[str, str] | None = None
- ) -> None:
- super().__init__(message)
- self.code = code
- self.fields = dict(fields) if fields else None
-
-
-@dataclass(frozen=True)
-class Filter:
- field: str
- op: str
- value: Any
-
-
-@dataclass(frozen=True)
-class ChartSpec:
- x: str
- y: tuple[str, ...]
- series: str | None = None
- filters: tuple[Filter, ...] = ()
- aggregate: str | None = None
- sort: tuple[str, str] | None = None
- top: int | None = None
- other: bool = False
- kind: str = "auto"
- title: str | None = None
- subtitle: str | None = None
-
- @property
- def measures(self) -> tuple[str, ...]:
- """Keys of the plotted measures before any series split."""
- return ("count",) if self.aggregate == "count" else self.y
-
- def fields(self) -> list[str]:
- """Every row field the spec reads."""
- names = [self.x, *self.y, *(f.field for f in self.filters)]
- if self.series:
- names.append(self.series)
- return list(dict.fromkeys(names))
-
-
-@dataclass
-class ChartRows:
- """Chart rows and what was done to get them."""
-
- x: str
- x_type: str
- columns: list[tuple[str, str]]
- series: list[str]
- rows: list[dict[str, Any]]
- chart_type: str
- reason: str
- total_rows: int
- matched: int
- source_rows: int
- missing_x: int = 0
- sort: str | None = None
- other: bool = False
-
-
-# ---------------------------------------------------------------------------
-# Parse
-# ---------------------------------------------------------------------------
-
-
-def _name(options: Mapping[str, Any], key: str) -> str | None:
- value = options.get(key)
- if value is None:
- return None
- if not isinstance(value, str) or not value:
- raise SpecError(f"{key} must be a field name")
- return value
-
-
-def _text(options: Mapping[str, Any], key: str) -> str | None:
- value = options.get(key)
- if value is None:
- return None
- if not isinstance(value, str) or not value.strip() or len(value) > _MAX_TEXT:
- raise SpecError(f"{key} must be text of 1 to {_MAX_TEXT} characters")
- return value.strip()
-
-
-def _scalar(value: Any) -> bool:
- return value is None or isinstance(value, (str, int, float, bool))
-
-
-def _filter(raw: Any, i: int) -> Filter:
- if not isinstance(raw, Mapping) or not isinstance(raw.get("field"), str):
- raise SpecError(f"filter[{i}] must be {{field, op, value}}")
- op = raw.get("op", "eq")
- if op not in OPS:
- raise SpecError(f"filter[{i}].op {op!r} is not one of {list(OPS)}")
- value = raw.get("value")
- if op == "in":
- if not isinstance(value, list) or not value or not all(_scalar(v) for v in value):
- raise SpecError(f"filter[{i}]: op in takes a non-empty list of values")
- value = tuple(value)
- elif op in ("contains", "prefix"):
- if not isinstance(value, str):
- raise SpecError(f"filter[{i}]: op {op} takes a text value")
- elif op in ("lt", "lte", "gt", "gte"):
- if isinstance(value, bool) or not isinstance(value, (int, float, str)):
- raise SpecError(f"filter[{i}]: op {op} takes a number or text value")
- elif not _scalar(value):
- raise SpecError(f"filter[{i}]: op {op} takes one value")
- return Filter(raw["field"], op, value)
-
-
-def parse_spec(options: Mapping[str, Any]) -> ChartSpec:
- """A spec from ``show_view`` options, checked for shape only (not against rows)."""
- x, group_by = _name(options, "x"), _name(options, "group_by")
- if x and group_by and x != group_by:
- raise SpecError("x and group_by name the same axis; pass one of them")
- x = x or group_by
- if x is None:
- raise SpecError("pass x: the field the chart runs along (a category or a date)")
-
- raw_y = options.get("y")
- if raw_y is None:
- y: tuple[str, ...] = ()
- elif isinstance(raw_y, str):
- y = (raw_y,)
- elif isinstance(raw_y, list) and raw_y and all(isinstance(v, str) and v for v in raw_y):
- y = tuple(dict.fromkeys(raw_y))
- else:
- raise SpecError("y must be a field name or a list of field names")
- if len(y) > VIEW_LIMITS["chart_series"]:
- raise SpecError(f"y takes at most {VIEW_LIMITS['chart_series']} fields")
-
- aggregate = options.get("aggregate")
- if aggregate is not None and aggregate not in AGGREGATES:
- raise SpecError(f"aggregate {aggregate!r} is not one of {list(AGGREGATES)}")
- if aggregate is None and not y:
- aggregate = "count"
- if aggregate is None and group_by:
- raise SpecError(f"group_by needs aggregate, one of {list(AGGREGATES)}")
- if aggregate == "count" and y:
- raise SpecError("aggregate count counts rows; drop y, or use sum, avg, min or max")
- if aggregate not in (None, "count") and not y:
- raise SpecError(f"aggregate {aggregate} needs y, the numeric field to {aggregate}")
-
- series = _name(options, "series")
- if series and len(y) > 1:
- raise SpecError("with series, y takes one field, which series splits by value")
- if series and (series == x or series in y):
- raise SpecError("series must be a field other than x and y")
- if x in y:
- raise SpecError("x cannot also be a y field")
-
- raw_filters = options.get("filter") or []
- if isinstance(raw_filters, Mapping):
- raw_filters = [raw_filters]
- if not isinstance(raw_filters, list) or len(raw_filters) > _MAX_FILTERS:
- raise SpecError(f"filter must be a list of at most {_MAX_FILTERS} {{field, op, value}}")
- filters = tuple(_filter(raw, i) for i, raw in enumerate(raw_filters))
-
- sort = options.get("sort")
- if sort is not None:
- if isinstance(sort, str):
- sort = {"field": sort}
- if not isinstance(sort, Mapping) or not isinstance(sort.get("field"), str):
- raise SpecError('sort must be {"field": <x or a y field>, "order": "asc" | "desc"}')
- order = sort.get("order", "desc")
- if order not in ("asc", "desc"):
- raise SpecError('sort order must be "asc" or "desc"')
- sort = (sort["field"], order)
-
- other = options.get("other", False)
- if not isinstance(other, bool):
- raise SpecError("other must be true or false")
- top = options.get("top")
- most = VIEW_LIMITS["chart_points"] - (1 if other else 0)
- whole = isinstance(top, int) and not isinstance(top, bool)
- if top is not None and not (whole and 1 <= top <= most):
- raise SpecError(f"top must be a whole number from 1 to {most}")
- if other and top is None:
- raise SpecError("other needs top: the rows past top go into Other")
- if other and aggregate not in _ADDITIVE:
- raise SpecError("other adds up the rows past top, so it needs aggregate count or sum")
-
- kind = options.get("kind", "auto")
- if kind not in KINDS:
- raise SpecError(f"kind {kind!r} is not one of {list(KINDS)}")
-
- return ChartSpec(
- x=x,
- y=y,
- series=series,
- filters=filters,
- aggregate=aggregate,
- sort=sort,
- top=top,
- other=other,
- kind=kind,
- title=_text(options, "title"),
- subtitle=_text(options, "subtitle"),
- )
-
-
-# ---------------------------------------------------------------------------
-# Fields
-# ---------------------------------------------------------------------------
-
-
-def _value_type(value: Any) -> str:
- if isinstance(value, bool):
- return "text"
- if isinstance(value, (int, float)):
- return "number"
- if isinstance(value, str):
- return "time" if _TIME.match(value) else "text"
- return "nested"
-
-
-def field_types(rows: Sequence[Mapping[str, Any]]) -> dict[str, str]:
- """Chartable fields of *rows* and their type: number, time or text.
-
- A field mixing numbers and text is text; one holding objects or lists is
- left out, as is a key that cannot be a column key.
- """
- seen: dict[str, str | None] = {}
- for row in rows:
- for key, value in row.items():
- if value is None:
- seen.setdefault(key, None)
- continue
- kind = _value_type(value)
- before = seen.get(key)
- if before is None or before == kind:
- seen[key] = kind
- elif "nested" in (before, kind):
- seen[key] = "nested"
- else:
- seen[key] = "text"
- return {k: t or "text" for k, t in seen.items() if t != "nested" and _KEY.match(k)}
-
-
-def _shown(types: Mapping[str, str]) -> dict[str, str]:
- return dict(list(types.items())[:_FIELDS_SHOWN])
-
-
-def _unknown(name: str, role: str, types: Mapping[str, str]) -> SpecError:
- close = difflib.get_close_matches(name, list(types), n=3, cutoff=0.6)
- hint = f" Did you mean {', '.join(repr(c) for c in close)}?" if close else ""
- return SpecError(
- f"{role} {name!r} is not a field of these rows.{hint} Fields are listed in `fields`.",
- fields=_shown(types),
- )
-
-
-def check_fields(spec: ChartSpec, types: Mapping[str, str]) -> None:
- """Every field the spec reads is in *types*, and measures are numeric."""
- roles = [
- ("x", spec.x),
- *(("y", y) for y in spec.y),
- *(("filter field", f.field) for f in spec.filters),
- ]
- if spec.series:
- roles.append(("series", spec.series))
- for role, name in roles:
- if name not in types:
- raise _unknown(name, role, types)
- numeric = [k for k, t in types.items() if t == "number"]
- for y in spec.y:
- if types[y] != "number":
- raise SpecError(
- f"y {y!r} holds {types[y]}; y fields must be numeric: {numeric[:_FIELDS_SHOWN]}",
- fields=_shown(types),
- )
- if spec.kind == "scatter" and types[spec.x] != "number":
- raise SpecError(
- f"a scatter needs a numeric x and {spec.x!r} holds {types[spec.x]}; "
- f"numeric fields: {numeric[:_FIELDS_SHOWN]}",
- fields=_shown(types),
- )
- if spec.other and types[spec.x] != "text":
- raise SpecError(
- f"other needs a category x and {spec.x!r} holds {types[spec.x]}; "
- "drop other, or use top alone"
- )
- if spec.sort and spec.sort[0] not in (spec.x, *spec.measures):
- choices = [spec.x, *spec.measures]
- raise SpecError(f"sort field {spec.sort[0]!r} must be one of {choices}")
-
-
-# ---------------------------------------------------------------------------
-# Transform
-# ---------------------------------------------------------------------------
-
-
-def _passes(f: Filter, value: Any) -> bool:
- op, want = f.op, f.value
- if op == "eq":
- return value == want
- if op == "ne":
- return value != want
- if op == "in":
- return value in want
- if op == "contains":
- return isinstance(value, str) and want in value
- if op == "prefix":
- return isinstance(value, str) and value.startswith(want)
- # Ordering compares like with like; a null or a type mismatch never passes.
- if value is None or isinstance(value, bool) or isinstance(value, str) != isinstance(want, str):
- return False
- if op == "lt":
- return value < want
- if op == "lte":
- return value <= want
- if op == "gt":
- return value > want
- return value >= want
-
-
-class _Acc:
- """Running count, sum, min and max of one measure in one group."""
-
- __slots__ = ("hi", "lo", "n", "rows", "total")
-
- def __init__(self) -> None:
- self.rows = 0
- self.n = 0
- self.total: float = 0
- self.lo: float | None = None
- self.hi: float | None = None
-
- def add(self, value: Any) -> None:
- self.rows += 1
- if isinstance(value, (int, float)) and not isinstance(value, bool):
- self.n += 1
- self.total += value
- self.lo = value if self.lo is None or value < self.lo else self.lo
- self.hi = value if self.hi is None or value > self.hi else self.hi
-
- def value(self, aggregate: str) -> float | None:
- if aggregate == "count":
- return self.rows
- if not self.n:
- return None
- if aggregate == "sum":
- return _round(self.total)
- if aggregate == "avg":
- return round(self.total / self.n, 4)
- return self.lo if aggregate == "min" else self.hi
-
-
-def _round(value: float) -> float:
- # Float sums carry noise (0.1 + 0.2); a whole number stays an int.
- return value if isinstance(value, int) else round(value, 6)
-
-
-def _x_order(value: Any) -> tuple[bool, Any]:
- return (isinstance(value, str), value)
-
-
-def label(key: str) -> str:
- """A field name as a column label: ``line_count`` is "Line count"."""
- return key.replace("_", " ").capitalize()
-
-
-@dataclass
-class _Pass:
- """What the single pass over the rows found."""
-
- groups: dict[Any, dict[Any, list[_Acc]]] = field(default_factory=dict)
- points: list[dict[str, Any]] = field(default_factory=list)
- series_values: dict[Any, None] = field(default_factory=dict)
- matched: int = 0
- missing_x: int = 0
-
-
-def _collect(
- spec: ChartSpec,
- rows: Sequence[Mapping[str, Any]],
- keep_points: bool,
- label_key: str | None,
- scatter: bool,
-) -> _Pass:
- """Filter, then group (aggregate), pivot (series) or keep each row as a point."""
- found = _Pass()
- # Outside a scatter, a kept point is a category or a date, which must not repeat.
- seen_x: set[Any] | None = None if scatter else set()
- for row in rows:
- if not all(_passes(f, row.get(f.field)) for f in spec.filters):
- continue
- found.matched += 1
- x_value = row.get(spec.x)
- if x_value is None:
- found.missing_x += 1
- continue
- s_value = row.get(spec.series) if spec.series else None
- if spec.series:
- found.series_values.setdefault(s_value)
- if keep_points:
- if seen_x is not None:
- if x_value in seen_x:
- raise SpecError(
- f"x {spec.x!r} repeats ({x_value!r}); add aggregate (count or sum) "
- "to combine the rows that share it"
- )
- seen_x.add(x_value)
- point = {spec.x: x_value, **{y: row.get(y) for y in spec.y}, "__series": s_value}
- if label_key:
- point[label_key] = row.get(label_key)
- found.points.append(point)
- continue
- cells = found.groups.setdefault(x_value, {})
- accs = cells.get(s_value)
- if accs is None:
- accs = cells[s_value] = [_Acc() for _ in spec.measures]
- elif spec.aggregate is None:
- raise SpecError(
- f"several rows share {spec.x}={x_value!r} and {spec.series}={s_value!r}; "
- "add aggregate (sum, avg, min or max) to combine them"
- )
- for acc, measure in zip(accs, spec.measures, strict=True):
- acc.add(None if measure == "count" else row.get(measure))
-
- if found.matched == 0:
- what = "match the filters" if spec.filters else "were selected"
- raise SpecError(f"no rows {what} ({len(rows)} rows before filtering)", code="no_data")
- if found.matched == found.missing_x:
- raise SpecError(f"no matching row has a value for x {spec.x!r}", code="no_data")
- if len(found.series_values) > VIEW_LIMITS["chart_series"]:
- raise SpecError(
- f"series {spec.series!r} has {len(found.series_values)} values and a chart plots "
- f"at most {VIEW_LIMITS['chart_series']}; filter it with op in, or drop series"
- )
- return found
-
-
-def _value_label(value: Any) -> str:
- if value is None:
- return "none"
- if isinstance(value, bool):
- return "true" if value else "false"
- return str(value)
-
-
-def _measure_columns(spec: ChartSpec, found: _Pass) -> tuple[list[str], list[str]]:
- """Keys and labels of the plotted columns: one per measure, or one per series value."""
- if spec.series:
- keys = [f"s{i + 1}" for i in range(len(found.series_values))]
- return keys, [_value_label(v) for v in found.series_values]
- keys = ["row_count" if m == "count" and spec.x == "count" else m for m in spec.measures]
- labels = [_AGGREGATE_LABEL["count"] if m == "count" else label(m) for m in spec.measures]
- return keys, labels
-
-
-def _chart_rows(
- spec: ChartSpec, found: _Pass, keys: list[str], label_key: str | None
-) -> list[dict[str, Any]]:
- by_value = dict(zip(found.series_values, keys, strict=True)) if spec.series else {}
- out: list[dict[str, Any]] = []
- for p in found.points:
- if spec.series:
- # One series per point: the other series columns stay null.
- row_out = {spec.x: p[spec.x], **dict.fromkeys(keys)}
- row_out[by_value[p["__series"]]] = p.get(spec.y[0])
- else:
- values = zip(keys, spec.measures, strict=True)
- row_out = {spec.x: p[spec.x], **{k: p.get(m) for k, m in values}}
- if label_key:
- row_out[label_key] = p[label_key]
- out.append(row_out)
- # Without aggregate each cell holds one row's value, read through "sum".
- aggregate = spec.aggregate or "sum"
- empty = 0 if spec.aggregate in _ADDITIVE else None
- for x_value, cells in found.groups.items():
- row_out = {spec.x: x_value}
- if spec.series:
- row_out.update(dict.fromkeys(keys, empty))
- for s_value, accs in cells.items():
- row_out[by_value[s_value]] = accs[0].value(aggregate)
- else:
- row_out.update(
- (k, acc.value(aggregate)) for k, acc in zip(keys, cells[None], strict=True)
- )
- out.append(row_out)
- return out
-
-
-def _total(row: Mapping[str, Any], keys: list[str]) -> float:
- return sum(v for k in keys if isinstance(v := row.get(k), (int, float)))
-
-
-def _sort(
- spec: ChartSpec, out: list[dict[str, Any]], keys: list[str], x_type: str, scatter: bool
-) -> tuple[tuple[str, str] | None, str | None]:
- """Sort *out* in place; returns the sort used and the order a chart may claim.
-
- As asked; else grouped categories largest first and dates oldest first.
- """
- sort = spec.sort
- if sort is None and x_type == "time":
- sort = (spec.x, "asc")
- elif sort is None and spec.aggregate and not scatter:
- sort = ("__total", "desc")
- if sort is None:
- return None, None
- name, order = sort
- reverse = order == "desc"
- if name == spec.x:
- out.sort(key=lambda r: _x_order(r[spec.x]), reverse=reverse)
- return sort, None
- # Series columns sort by their row total; a measure by its own value.
- key = None if name == "__total" or spec.series else keys[spec.measures.index(name)]
-
- def by_value(r: Mapping[str, Any]) -> tuple[bool, float]:
- value = _total(r, keys) if key is None else r.get(key)
- if value is None:
- return (True, 0) # nulls last either way
- return (False, -value if reverse else value)
-
- out.sort(key=by_value)
- # A chart claims an order only by its series total, which a null has no place in.
- sums = key is None or len(keys) == 1
- claim = order if sums and all(r.get(k) is not None for r in out for k in keys) else None
- return sort, claim
-
-
-def transform(
- spec: ChartSpec, rows: Sequence[Mapping[str, Any]], types: Mapping[str, str]
-) -> ChartRows:
- """Filter, group, sort and cut *rows* by *spec*, and pick the chart type.
-
- *types* comes from ``field_types`` and must already pass ``check_fields``.
- """
- x_type = types[spec.x]
- scatter = spec.kind == "scatter" or (
- spec.kind == "auto" and spec.aggregate is None and x_type == "number"
- )
- label_key = None
- if spec.aggregate is None and not spec.series:
- label_key = next(
- (k for k in _LABEL_FIELDS if k in types and k != spec.x and k not in spec.y), None
- )
- keep_points = spec.aggregate is None and (scatter or not spec.series)
- found = _collect(spec, rows, keep_points, label_key, scatter)
- keys, labels = _measure_columns(spec, found)
- columns = [(spec.x, label(spec.x)), *zip(keys, labels, strict=True)]
- if label_key:
- columns.insert(0, (label_key, label(label_key)))
- out = _chart_rows(spec, found, keys, label_key)
- sort, claim = _sort(spec, out, keys, x_type, scatter)
-
- # Top N, with the rest added up as Other; else the chart-point cap.
- total_rows = len(out)
- other = False
- if spec.top is not None and len(out) > spec.top:
- rest, out = out[spec.top :], out[: spec.top]
- if spec.other:
- bucket: dict[str, Any] = {spec.x: f"{OTHER_LABEL} ({len(rest)} more)"}
- for k in keys:
- values = [r[k] for r in rest if isinstance(r.get(k), (int, float))]
- bucket[k] = _round(sum(values)) if values else None
- out.append(bucket)
- # The bucket sits last whatever its size, so no order is claimed.
- other, claim, total_rows = True, None, len(out)
- cap = VIEW_LIMITS["chart_points"]
- if len(out) > cap:
- # A time axis keeps its newest points; anything else keeps its first.
- newest = x_type == "time" and (sort is None or sort[0] == spec.x)
- out = out[-cap:] if newest else out[:cap]
-
- chart_type, reason = _choose_kind(spec, x_type, keys, out, total_rows > len(out), scatter)
- return ChartRows(
- x=spec.x,
- x_type=x_type,
- columns=columns,
- series=keys,
- rows=out,
- chart_type=chart_type,
- reason=reason,
- total_rows=total_rows,
- matched=found.matched,
- source_rows=len(rows),
- missing_x=found.missing_x,
- sort=claim if chart_type != "scatter" else None,
- other=other,
- )
-
-
-# ---------------------------------------------------------------------------
-# Chart type
-# ---------------------------------------------------------------------------
-
-
-def _whole(keys: list[str], rows: list[dict[str, Any]]) -> bool:
- values = [r.get(k) for r in rows for k in keys]
- return all(isinstance(v, (int, float)) and v >= 0 for v in values) and sum(values) > 0
-
-
-def _choose_kind(
- spec: ChartSpec,
- x_type: str,
- keys: list[str],
- rows: list[dict[str, Any]],
- truncated: bool,
- scatter: bool,
-) -> tuple[str, str]:
- """The chart type and why: the spec's ``kind``, checked, or one picked from the data's shape."""
- additive = spec.aggregate in _ADDITIVE or spec.aggregate is None
- low, high = VIEW_LIMITS["donut_min_parts"], VIEW_LIMITS["donut_max_parts"]
- donut_ok = len(keys) == 1 and low <= len(rows) <= high and not truncated and _whole(keys, rows)
- kind = spec.kind
- if kind == "donut" and not donut_ok:
- raise SpecError(
- f"a donut shows one measure as {low} to {high} non-negative parts of a whole, and this "
- f"chart has {len(rows)} rows and {len(keys)} series"
- f"{' with some cut' if truncated else ''}; "
- f"use top: {high - 1} with other: true, or kind bar"
- )
- if kind == "stacked_bar" and (len(keys) < 2 or not additive or not _whole(keys, rows)):
- raise SpecError(
- "a stacked_bar needs two or more series of non-negative counts or sums; "
- "pass series (a field to split by) or several y fields, or use kind bar"
- )
- if kind != "auto":
- return kind, f"kind {kind} was asked for"
- if scatter:
- return "scatter", f"x {spec.x!r} and the plotted values are both numeric"
- if x_type == "time":
- return "line", f"x {spec.x!r} holds dates"
- if spec.series and len(keys) > 1:
- if additive and _whole(keys, rows):
- return "stacked_bar", f"series {spec.series!r} splits each bar into parts"
- why = f"{spec.aggregate} does not add up"
- return "bar", f"series {spec.series!r} values sit side by side ({why})"
- if len(keys) > 1:
- return "bar", "several measures sit side by side"
- if spec.aggregate in _ADDITIVE and donut_ok:
- return "donut", f"{len(rows)} parts that add up to one whole"
- return "bar", "one measure across categories"
-
-
-def default_title(spec: ChartSpec) -> str:
- if spec.aggregate == "count":
- measure = "Count"
- else:
- names = ", ".join(label(y).lower() for y in spec.y)
- measure = (
- f"{_AGGREGATE_LABEL[spec.aggregate]} {names}" if spec.aggregate else names.capitalize()
- )
- by = label(spec.x).lower() + (f" and {label(spec.series).lower()}" if spec.series else "")
- return f"{measure} by {by}"
diff --git a/packages/server/src/repowise/server/chat_views.py b/packages/server/src/repowise/server/chat_views.py
index 18ffc5560..6e923c915 100644
--- a/packages/server/src/repowise/server/chat_views.py
+++ b/packages/server/src/repowise/server/chat_views.py
@@ -8,6 +8,10 @@ from that result, and ``build_view`` adds provenance, applies the guards and
validates it as a ``ViewPart``. Builders are pure functions registered on the
``chat-view`` seam, so a plugin adds one without editing this module.
+The named views live in :mod:`repowise.server.chat_view_builders`; the
+``chart`` view and the chat-only ``chart`` tool share
+:mod:`repowise.server.chat_chart_part`.
+
Guards every builder passes through: no column or axis keyed by a person, no
risk score as a chart series, and an attribution figure below
``ATTRIBUTION_COVERAGE_FLOOR`` (or without coverage) is refused with its
@@ -28,7 +32,7 @@ from uuid import uuid4
from pydantic import TypeAdapter, ValidationError
from repowise.core.registry.plugins import SeamRegistry, load_plugins
-from repowise.server import chat_view_spec
+from repowise.server import chat_spec
from repowise.server.chat_artifacts import ARTIFACT_ID_FIELD
from repowise.server.chat_references import (
LATEST_PREFIX,
@@ -37,8 +41,6 @@ from repowise.server.chat_references import (
ViewArtifact,
stamp,
)
-from repowise.server.chat_view_spec import SpecError
-from repowise.server.chat_view_spec import label as _label
from repowise.server.schemas.evidence import MAX_WIRE_NUMBER
from repowise.server.schemas.views import (
VIEW_LIMITS,
@@ -49,18 +51,27 @@ from repowise.server.schemas.views import (
logger = logging.getLogger(__name__)
+
ATTRIBUTION_COVERAGE_FLOOR = 0.30
+
_PART = TypeAdapter(ViewPart)
+
+
_SHA = re.compile(r"^[0-9a-f]{7,64}$")
+
+
_PERSON = re.compile(
r"(^|_)(authors?|owners?|ownership|committers?|emails?|users?|username|login|assignees?"
r"|reviewers?|maintainers?|contributors?|person|people|knowledge_map)(_|$)"
)
+
+
_RISK_SCORE = re.compile(r"risk|impact_score|hotspot_score")
+
+
# Attribution figures are drawn only by views that check their coverage.
_ATTRIBUTION = re.compile(r"(^|_)(agents?|attested|provenance|attribution)(_|$)")
-_DEFAULT_ROWS = 50
class ViewError(ValueError):
@@ -147,7 +158,7 @@ def _meta(data: Mapping[str, Any]) -> Mapping[str, Any]:
return meta if isinstance(meta, Mapping) else {}
-def _guard(part: dict[str, Any], spec: ViewBuilder) -> None:
+def _guard(part: dict[str, Any], coverage_metric: str | None = None) -> None:
data = part.get("data", part)
for column in data.get("columns", []):
if _PERSON.search(str(column.get("key", ""))):
@@ -162,7 +173,7 @@ def _guard(part: dict[str, Any], spec: ViewBuilder) -> None:
f"a risk score is never a chart series ({key!r}); show it in a table",
code="risk_score_series",
)
- if spec.coverage_metric == "attribution":
+ if coverage_metric == "attribution":
coverage = part.get("coverage")
ratio = coverage.get("ratio") if isinstance(coverage, Mapping) else None
if not isinstance(ratio, (int, float)) or ratio < ATTRIBUTION_COVERAGE_FLOOR:
@@ -219,19 +230,44 @@ def build_view(
raise ViewError(f"unknown options {unknown}; {view!r} takes {sorted(spec.options)}")
part = spec.build(artifact, options)
- receipt = part.pop("receipt", None)
meta = _meta(artifact.data)
commit = meta.get("indexed_commit")
- part.update(
- schema_version=VIEW_SCHEMA_VERSION,
- id=part_id,
+ return finish_part(
+ part,
+ part_id=part_id,
source={
"artifact_id": artifact.artifact_id,
"tool_name": artifact.tool_name,
"args_hash": args_hash(artifact.arguments),
},
stale=bool(meta.get("stale_warning")),
- as_of=commit if isinstance(commit, str) and _SHA.match(commit) else None,
+ as_of=commit if isinstance(commit, str) else None,
+ coverage_metric=spec.coverage_metric,
+ what=f"view {view!r}",
+ )
+
+
+def finish_part(
+ part: dict[str, Any],
+ *,
+ part_id: str,
+ source: Mapping[str, str],
+ stale: bool,
+ as_of: str | None,
+ coverage_metric: str | None = None,
+ what: str = "the chart",
+) -> dict[str, Any]:
+ """Add provenance to a builder's part, apply the guards and validate it.
+
+ A builder's ``receipt`` comes back under ``"receipt"``; ``TurnViews`` pops it.
+ """
+ receipt = part.pop("receipt", None)
+ part.update(
+ schema_version=VIEW_SCHEMA_VERSION,
+ id=part_id,
+ source=dict(source),
+ stale=stale,
+ as_of=as_of if isinstance(as_of, str) and _SHA.match(as_of) else None,
)
if part.get("kind") == "chart" and _all_zero(part):
raise ViewError(
@@ -239,12 +275,12 @@ def build_view(
"say so in a sentence instead",
code="no_data",
)
- _guard(part, spec)
+ _guard(part, coverage_metric)
try:
model = _PART.validate_python(part)
except ValidationError as exc:
raise ViewError(
- f"view {view!r} could not be built from this result: {exc.errors()[0]['msg']}",
+ f"{what} could not be built from this result: {exc.errors()[0]['msg']}",
code="invalid_view",
) from None
built = _PART.dump_python(model, mode="json", exclude_unset=True)
@@ -316,39 +352,62 @@ class TurnViews:
logger.exception("chat_view_builder_failed", extra={"view": arguments.get("view")})
return ViewError("the view builder failed", code="builder_failed").payload()
self.parts.append(part)
- receipt = {"view_id": part["id"], "kind": part["kind"], "title": part["title"]}
+ receipt = part_receipt(part)
reference = arguments.get("artifact_id")
if isinstance(reference, str) and reference.startswith(LATEST_PREFIX):
# Say which result a symbolic reference picked.
receipt["resolved_artifact_id"] = part["source"]["artifact_id"]
receipt["source_tool"] = part["source"]["tool_name"]
- if "summary" in part:
- receipt["summary"] = part["summary"]
return {**receipt, **extra}
+ def next_id(self) -> str:
+ return f"v{len(self.parts) + 1}"
+
+ def keep(self, part: dict[str, Any]) -> None:
+ """Add a finished part to the turn, within the turn's view cap."""
+ self._check_room(part)
+ self.parts.append(part)
+
+ def _check_room(self, part: dict[str, Any]) -> None:
+ try:
+ ViewPartList.model_validate([*self.parts, part])
+ except ValidationError:
+ raise ViewError(
+ f"a turn holds at most {VIEW_LIMITS['parts']} views", code="view_limit"
+ ) from None
+
def _build(self, arguments: Mapping[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
reference = arguments.get("artifact_id")
view = arguments.get("view")
options = arguments.get("options") or {}
artifact = self.artifacts.resolve(reference)
+ if artifact is None and isinstance(reference, str) and re.fullmatch(r"v\d+", reference):
+ shown = next((p for p in reversed(self.parts) if p["id"] == reference), None)
+ shown = shown or self.artifacts.views.get(reference)
+ if shown is None:
+ raise ViewError(
+ f"no view {reference!r} in this conversation; call chart to draw one",
+ code="unknown_artifact",
+ )
+ # Deferred: chat_chart_part builds on this module.
+ from repowise.server.chat_chart_part import redraw
+
+ part = redraw(shown, options, part_id=self.next_id())
+ self._check_room(part)
+ return part, {"redrawn_from": reference}
if artifact is None:
raise ViewError(
f"no tool result matches artifact_id {reference!r}. Pass an artifact_id "
f"from `available` or {LATEST_PREFIX}<tool_name>; if the result you need "
- "is not listed, call its tool first",
+ "is not listed, call its tool first, or draw repository data with chart",
code="unknown_artifact",
available=self.artifacts.available(),
)
if not isinstance(view, str) or not isinstance(options, Mapping):
raise ViewError("view must be a string and options an object", code="bad_arguments")
- part = build_view(artifact, view, options, part_id=f"v{len(self.parts) + 1}")
+ part = build_view(artifact, view, options, part_id=self.next_id())
extra = part.pop("receipt", None) or {}
- try:
- ViewPartList.model_validate([*self.parts, part])
- except ValidationError:
- raise ViewError(
- f"a turn holds at most {VIEW_LIMITS['parts']} views", code="view_limit"
- ) from None
+ self._check_room(part)
return part, extra
def event(self, tool_id: str, result: Mapping[str, Any]) -> dict[str, Any] | None:
@@ -358,6 +417,16 @@ class TurnViews:
return None if part is None else {"type": "view", "tool_id": tool_id, "view": part}
+def part_receipt(part: Mapping[str, Any]) -> dict[str, Any]:
+ """What the model reads back about a part it made: its id, kind, title and summary."""
+ receipt = {"view_id": part["id"], "kind": part["kind"], "title": part["title"]}
+ if part.get("kind") == "chart":
+ receipt["chart_type"] = part["chart_type"]
+ if "summary" in part:
+ receipt["summary"] = part["summary"]
+ return receipt
+
+
def show_view_schema(artifact_types: list[str] | None = None) -> dict[str, Any]:
"""OpenAI-format definition of the chat-only ``show_view`` tool."""
names = sorted(
@@ -368,18 +437,14 @@ def show_view_schema(artifact_types: list[str] | None = None) -> dict[str, Any]:
"function": {
"name": SHOW_VIEW_TOOL,
"description": (
- "Show a table or chart built by the server from a tool result of this "
- "conversation. Call the tool first (an earlier call in the same round "
- "counts), then pass its artifact_id, or latest:<tool_name> for that "
- "tool's newest result. Never restate the numbers yourself; the view "
- "carries them. Views: " + ", ".join(names) + ". "
- "`table` takes options path (dotted path to a list or map in the result), "
- "columns and limit. When no named view fits, `chart` plots any list in the "
- "result from options rows (path), x, y (field or list; omit to count rows), "
- "series, filter [{field, op: eq|ne|lt|lte|gt|gte|in|contains|prefix, value}], "
- "aggregate count|sum|avg|min|max, sort {field, order}, top, other (bucket the "
- "rest), kind auto|bar|stacked_bar|line|donut|scatter, title. Its receipt says "
- "the kind picked and why; an error lists the fields."
+ "Show a table or chart of a tool result already in this conversation "
+ "(for repository data prefer the chart tool, which needs no prior call). "
+ "Pass its artifact_id, or latest:<tool_name>, or an earlier view's id (v1) "
+ "with options.kind to redraw it. Views: " + ", ".join(names) + "; "
+ "named views take options.kind (e.g. donut, bar, table). `table` takes "
+ "options path (a list or map in the result), columns, limit. `chart` plots "
+ "any list or map in the result: options rows is its path. "
+ + chat_spec.SPEC_HELP
),
"parameters": {
"type": "object",
@@ -397,31 +462,6 @@ def show_view_schema(artifact_types: list[str] | None = None) -> dict[str, Any]:
}
-# ---------------------------------------------------------------------------
-# Builders
-# ---------------------------------------------------------------------------
-
-
-def _basis(kind: str, source: str) -> dict[str, str]:
- return {"kind": kind, "source": source}
-
-
-def _tool_basis(artifact: ViewArtifact) -> dict[str, str]:
- declared = artifact.data.get("evidence_kind") or artifact.data.get("basis")
- kind = declared if declared in ("measured", "inferred", "declared") else artifact.evidence_basis
- if kind not in ("measured", "inferred", "declared"):
- return _basis("unresolved", f"{artifact.tool_name} declares no basis")
- return _basis(kind, artifact.tool_name)
-
-
-def _limit(options: Mapping[str, Any], default: int = _DEFAULT_ROWS, cap: int | None = None) -> int:
- cap = cap or VIEW_LIMITS["rows"]
- value = options.get("limit", default)
- if isinstance(value, bool) or not isinstance(value, int) or value < 1:
- raise ViewError("limit must be a positive integer", code="bad_arguments")
- return min(value, cap)
-
-
def _wire(value: Any) -> Any:
"""A source value as a cell, or ``...`` when it cannot be one."""
if value is None or isinstance(value, str):
@@ -439,518 +479,5 @@ def _cell(key: str, value: Any) -> Any:
return _wire(value)
-def _node(data: Any, path: str) -> Any:
- node = data
- for segment in path.split("."):
- if isinstance(node, Mapping) and segment in node:
- node = node[segment]
- elif isinstance(node, list) and segment.isdigit() and int(segment) < len(node):
- node = node[int(segment)]
- else:
- raise ViewError(f"no {path!r} in the artifact", code="bad_path")
- return node
-
-
-def _tabular(node: Any) -> list[dict[str, Any]] | None:
- """Rows from a list of objects, or a map of objects keyed by id."""
- if isinstance(node, list) and node and all(isinstance(row, Mapping) for row in node):
- return [dict(row) for row in node]
- if isinstance(node, Mapping) and node and all(isinstance(v, Mapping) for v in node.values()):
- return [{"id": key, **value} for key, value in node.items()]
- return None
-
-
-def _table_paths(data: Mapping[str, Any], prefix: str = "", depth: int = 0) -> list[str]:
- paths: list[str] = []
- for key, value in data.items():
- if key == "_meta" or _PERSON.search(key):
- continue
- path = f"{prefix}{key}"
- if _tabular(value) is not None:
- paths.append(path)
- elif isinstance(value, Mapping) and depth < 2:
- paths.extend(_table_paths(value, f"{path}.", depth + 1))
- return paths
-
-
-def _rows_at(
- data: Mapping[str, Any], path: Any, option: str
-) -> tuple[str, list[dict[str, Any]], int]:
- """The list or map of objects at *path* (picked when the result holds one),
- its rows, and the row count the tool reports for it (``<leaf>_total``)."""
- if path is None:
- candidates = _table_paths(data)
- if len(candidates) != 1:
- raise ViewError(
- f"pass options.{option}; tables in this result: {candidates}", code="bad_path"
- )
- path = candidates[0]
- if not isinstance(path, str) or any(_PERSON.search(seg) for seg in path.split(".")):
- raise ViewError(f"views never group by person ({path!r})", code="person_grouping")
- rows = _tabular(_node(data, path))
- if rows is None:
- raise ViewError(f"{path!r} is not a list or map of objects", code="bad_path")
- parent_path, _, leaf = path.rpartition(".")
- parent = _node(data, parent_path) if parent_path else data
- total = parent.get(f"{leaf}_total") if isinstance(parent, Mapping) else None
- return path, rows, total if isinstance(total, int) and total >= len(rows) else len(rows)
-
-
-@register_view_builder(
- "table",
- description="Any list or map of objects in a result, as a table.",
- options={"path", "columns", "limit"},
-)
-def table_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
- path, rows, total_rows = _rows_at(artifact.data, options.get("path"), "path")
- wanted = options.get("columns")
- if wanted is not None and not (
- isinstance(wanted, list) and all(isinstance(k, str) for k in wanted)
- ):
- raise ViewError("columns must be a list of keys", code="bad_arguments")
- keys = list(dict.fromkeys(k for row in rows for k in row))
- # A column is a key whose every value is a cell; nested values and people are left out.
- keys = [
- k
- for k in keys
- if not _PERSON.search(k)
- and re.fullmatch(r"[a-z][a-z0-9_]{0,63}", k)
- and all(_cell(k, row.get(k)) is not ... for row in rows)
- ]
- if wanted is not None:
- if missing := [k for k in wanted if k not in keys]:
- raise ViewError(f"columns not available as cells: {missing}", code="bad_arguments")
- keys = list(dict.fromkeys(wanted))
- keys = keys[: VIEW_LIMITS["columns"]]
- if not keys:
- raise ViewError(f"{path!r} has no scalar fields to show", code="bad_path")
-
- shown = rows[: _limit(options)]
- return {
- "kind": "table",
- "title": f"{artifact.tool_name}: {path}",
- "summary": f"{len(shown)} of {total_rows} rows.",
- "basis": _tool_basis(artifact),
- "columns": [{"key": k, "label": _label(k)} for k in keys],
- "rows": [{k: _cell(k, row.get(k)) for k in keys} for row in shown],
- "total_rows": total_rows,
- "truncated": total_rows > len(shown),
- }
-
-
-def _spec_error(exc: SpecError) -> ViewError:
- extra = {"fields": exc.fields} if exc.fields else {}
- return ViewError(str(exc), code=exc.code, **extra)
-
-
-@register_view_builder(
- "chart",
- description="A chart you specify over any list of objects in a result.",
- options=chat_view_spec.OPTIONS,
-)
-def chart_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
- try:
- spec = chat_view_spec.parse_spec(options)
- except SpecError as exc:
- raise _spec_error(exc) from None
- path, rows, source_total = _rows_at(artifact.data, options.get("rows"), "rows")
- for name in spec.fields():
- if _PERSON.search(name):
- raise ViewError(
- f"views never group or filter by person ({name!r})", code="person_grouping"
- )
- for name in [*spec.fields(), *path.split(".")]:
- if _ATTRIBUTION.search(name):
- # Deliberate ceiling: no coverage check per row here, so these are
- # refused; changes.provenance draws them with their coverage.
- raise ViewError(
- f"attribution figures ({name!r}) are shown only by changes.provenance, "
- "which checks their coverage",
- code="attribution_figure",
- )
- types = {k: t for k, t in chat_view_spec.field_types(rows).items() if not _PERSON.search(k)}
- numeric_x = types.get(spec.x) == "number"
- split = [spec.series] if spec.series else []
- for name in [*spec.y, *split, *([spec.x] if numeric_x else [])]:
- if _RISK_SCORE.search(name):
- raise ViewError(
- f"a risk score is never a chart series ({name!r}); show it in a table",
- code="risk_score_series",
- )
- try:
- chat_view_spec.check_fields(spec, types)
- result = chat_view_spec.transform(spec, rows, types)
- except SpecError as exc:
- raise _spec_error(exc) from None
-
- def cell(key: str, value: Any) -> Any:
- value = _cell(key, value) if key not in result.series else _wire(value)
- return None if value is ... else value
-
- shown = f"{result.matched} of {result.source_rows}" if spec.filters else f"{result.source_rows}"
- summary = f"{shown} rows of {path}" + (f", grouped by {spec.x}" if spec.aggregate else "") + "."
- if result.missing_x:
- summary += f" {result.missing_x} rows without {spec.x} are left out."
- if result.other:
- summary += f" {chat_view_spec.OTHER_LABEL} adds up the rows past the top {spec.top}."
- if source_total > len(rows):
- summary += (
- f" The tool returned {len(rows)} of {source_total} rows; the chart covers those only."
- )
- part: dict[str, Any] = {
- "kind": "chart",
- "chart_type": result.chart_type,
- "title": spec.title or chat_view_spec.default_title(spec),
- "summary": f"{spec.subtitle} {summary}" if spec.subtitle else summary,
- "basis": _tool_basis(artifact),
- "x": result.x,
- "series": result.series,
- "data": {
- "columns": [{"key": k, "label": label} for k, label in result.columns],
- "rows": [{k: cell(k, v) for k, v in row.items()} for row in result.rows],
- "total_rows": result.total_rows,
- "truncated": result.total_rows > len(result.rows),
- },
- "receipt": {"chart_type": result.chart_type, "reason": result.reason},
- }
- if result.sort:
- part["sort"] = result.sort
- return part
-
-
-def _chart(
- *,
- title: str,
- summary: str,
- basis: dict[str, str],
- x: tuple[str, str],
- series: list[tuple[str, str]],
- unit: str,
- rows: list[dict[str, Any]],
- total_rows: int | None = None,
- chart_type: str = "bar",
-) -> dict[str, Any]:
- if not rows:
- raise ViewError("this result has nothing to chart", code="no_data")
- total = len(rows) if total_rows is None else max(total_rows, len(rows))
- return {
- "kind": "chart",
- "chart_type": chart_type,
- "title": title,
- "summary": summary,
- "basis": basis,
- "x": x[0],
- "series": [key for key, _ in series],
- "data": {
- "columns": [
- {"key": x[0], "label": x[1]},
- *({"key": key, "label": label, "unit": unit} for key, label in series),
- ],
- "rows": rows,
- "total_rows": total,
- "truncated": total > len(rows),
- },
- }
-
-
-_HEALTH_BANDS = ("at_risk", "needs_work", "fair", "good", "excellent")
-
-
-@register_view_builder(
- "health.bands",
- description="Files per health band.",
- artifact_types={"health", "overview"},
- options=frozenset(),
-)
-def health_bands_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
- data = artifact.data
- distribution = data.get("distribution") or (data.get("code_health") or {}).get("distribution")
- bands = distribution.get("bands") if isinstance(distribution, Mapping) else None
- if not isinstance(bands, Mapping):
- raise ViewError("this result has no health distribution; call get_health with no targets")
- rows = [
- {"band": band.replace("_", " "), "files": bands[band]["files"]}
- for band in _HEALTH_BANDS
- if isinstance(bands.get(band), Mapping) and isinstance(bands[band].get("files"), int)
- ]
- total = sum(row["files"] for row in rows)
- return _chart(
- title="Files by health band",
- summary=f"{total} files across {len(rows)} health bands.",
- basis=_basis("inferred", "health engine"),
- x=("band", "Health band"),
- series=[("files", "Files")],
- unit="files",
- rows=rows,
- )
-
-
-@register_view_builder(
- "health.trend",
- description="Average and hotspot health over recent snapshots.",
- artifact_types={"health"},
- options=frozenset(),
-)
-def health_trend_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
- trend = artifact.data.get("trend")
- recent = trend.get("recent") if isinstance(trend, Mapping) else None
- if not isinstance(recent, list) or not recent:
- raise ViewError('this result has no trend; call get_health(include=["trend"])')
- snapshots = sorted(
- (s for s in recent if isinstance(s, Mapping) and isinstance(s.get("taken_at"), str)),
- key=lambda s: s["taken_at"],
- )
- rows = [
- {
- "taken_at": s["taken_at"],
- "average_health": _wire(s.get("average_health")),
- "hotspot_health": _wire(s.get("hotspot_health")),
- }
- for s in snapshots
- ]
- total = trend.get("recent_total")
- return _chart(
- chart_type="line",
- title="Health over recent snapshots",
- summary=f"{len(rows)} health snapshots, oldest first.",
- basis=_basis("inferred", "health snapshots"),
- x=("taken_at", "Snapshot"),
- series=[("average_health", "Average health"), ("hotspot_health", "Hotspot health")],
- unit="score",
- rows=rows,
- total_rows=total if isinstance(total, int) else None,
- )
-
-
-@register_view_builder(
- "health.test_coverage",
- description="Measured line coverage per file, from the ingested coverage report.",
- artifact_types={"health"},
-)
-def health_test_coverage_view(
- artifact: ViewArtifact, options: Mapping[str, Any]
-) -> dict[str, Any]:
- coverage = artifact.data.get("coverage")
- files = coverage.get("files") if isinstance(coverage, Mapping) else None
- if not isinstance(files, list):
- raise ViewError('this result has no coverage; call get_health(include=["coverage"])')
- usable = [f for f in files if isinstance(f, Mapping) and f.get("file_path")]
- shown = usable[: _limit(options, cap=100)]
- rows = [
- {
- "file": {"type": "file", "id": f["file_path"]},
- "line_coverage": _wire(f.get("line_coverage_pct")),
- }
- for f in shown
- ]
- summary_pct = (coverage.get("summary") or {}).get("line_coverage_pct")
- total = coverage.get("files_total")
- total = max(total, len(usable)) if isinstance(total, int) else len(usable)
- part = _chart(
- title="Line coverage by file",
- summary=f"{len(rows)} files from the coverage report.",
- basis=_basis("measured", "coverage report"),
- x=("file", "File"),
- series=[("line_coverage", "Line coverage")],
- unit="%",
- rows=rows,
- total_rows=total,
- )
- if isinstance(summary_pct, (int, float)) and 0 <= summary_pct <= 100:
- # Rounded so the percentage converts without float noise (88.84 -> 0.8884).
- part["coverage"] = {"metric": "test_reach", "ratio": round(summary_pct / 100, 6)}
- return part
-
-
-@register_view_builder(
- "dead_code.by_tier",
- description="Dead-code findings per confidence tier.",
- artifact_types={"dead_code"},
- options=frozenset(),
-)
-def dead_code_by_tier_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
- tiers = artifact.data.get("tiers")
- if not isinstance(tiers, Mapping):
- raise ViewError("this result has no confidence tiers")
- rows = [
- {"tier": tier, "findings": tiers[tier]["count"]}
- for tier in ("high", "medium", "low")
- if isinstance(tiers.get(tier), Mapping) and isinstance(tiers[tier].get("count"), int)
- ]
- return _chart(
- title="Dead-code findings by tier",
- summary=f"{sum(r['findings'] for r in rows)} findings kept by the call's filters.",
- basis=_basis("inferred", "reachability graph"),
- x=("tier", "Confidence tier"),
- series=[("findings", "Findings")],
- unit="findings",
- rows=rows,
- )
-
-
-@register_view_builder(
- "dead_code.by_kind",
- description="Open dead-code findings per kind.",
- artifact_types={"dead_code"},
- options=frozenset(),
-)
-def dead_code_by_kind_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
- by_kind = (artifact.data.get("summary") or {}).get("by_kind")
- if not isinstance(by_kind, Mapping) or not by_kind:
- raise ViewError("this result has no findings by kind")
- rows = [
- {"kind": kind, "findings": count}
- for kind, count in by_kind.items()
- if isinstance(count, int) and not isinstance(count, bool)
- ]
- return _chart(
- title="Dead-code findings by kind",
- summary=f"{sum(r['findings'] for r in rows)} open findings.",
- basis=_basis("inferred", "reachability graph"),
- x=("kind", "Kind"),
- series=[("findings", "Findings")],
- unit="findings",
- rows=rows,
- )
-
-
-@register_view_builder(
- "risk.hotspots",
- description="Bug-fix commits on the repository's top hotspots.",
- artifact_types={"risk"},
-)
-def risk_hotspots_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
- hotspots = artifact.data.get("global_hotspots")
- if not isinstance(hotspots, list) or not hotspots:
- raise ViewError("this result has no global hotspots")
- usable = [h for h in hotspots if isinstance(h, Mapping) and h.get("file_path")]
- shown = usable[: _limit(options, cap=100)]
- rows = [
- {"file": {"type": "file", "id": h["file_path"]}, "fix_count": _wire(h.get("fix_count"))}
- for h in shown
- ]
- total = artifact.data.get("global_hotspots_total")
- total = max(total, len(usable)) if isinstance(total, int) else len(usable)
- return _chart(
- title="Bug fixes on top hotspots",
- summary=f"Bug-fix commits on {len(rows)} hotspot files.",
- basis=_basis("measured", "git history"),
- x=("file", "File"),
- series=[("fix_count", "Bug-fix commits")],
- unit="commits",
- rows=rows,
- total_rows=total,
- )
-
-
-def _changes_block(artifact: ViewArtifact) -> Mapping[str, Any]:
- block = artifact.data.get("changes")
- if not isinstance(block, Mapping) or not block.get("total"):
- raise ViewError(
- 'this result has no change records; call get_overview(include=["changes"])'
- )
- return block
-
-
-def _window(block: Mapping[str, Any]) -> str:
- window = block.get("window")
- start = window.get("history_from") if isinstance(window, Mapping) else None
- if isinstance(start, str):
- return f" since {start[:10]}, where the indexed history starts"
- days = window.get("days") if isinstance(window, Mapping) else None
- return f" over the last {days} days of merged changes" if isinstance(days, int) else ""
-
-
-@register_view_builder(
- "changes.by_category",
- description="Merged changes per category (feature, fix, ...).",
- artifact_types={"overview"},
- options=frozenset(),
-)
-def changes_by_category_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
- block = _changes_block(artifact)
- by_category = block.get("by_category")
- rows = [
- {"category": category, "changes": count}
- for category, count in (by_category.items() if isinstance(by_category, Mapping) else ())
- if isinstance(count, int) and not isinstance(count, bool)
- ]
- return _chart(
- title="Changes by category",
- summary=f"{sum(r['changes'] for r in rows)} changes{_window(block)}.",
- basis=_basis("measured", "git history"),
- x=("category", "Category"),
- series=[("changes", "Changes")],
- unit="changes",
- rows=rows,
- )
-
-
-@register_view_builder(
- "changes.by_week",
- description="Merged changes per week.",
- artifact_types={"overview"},
- options=frozenset(),
-)
-def changes_by_week_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
- block = _changes_block(artifact)
- weeks = block.get("by_week")
- rows = [
- {"week": w["week"], "changes": w["changes"]}
- for w in (weeks if isinstance(weeks, list) else ())
- if isinstance(w, Mapping)
- and isinstance(w.get("week"), str)
- and isinstance(w.get("changes"), int)
- and not isinstance(w.get("changes"), bool)
- ][-VIEW_LIMITS["chart_points"] :]
- return _chart(
- chart_type="line",
- title="Changes per week",
- summary=f"{len(rows)} weeks{_window(block)}, oldest first.",
- basis=_basis("measured", "git history"),
- x=("week", "Week of"),
- series=[("changes", "Changes")],
- unit="changes",
- rows=rows,
- )
-
-
-_PROVENANCE_BANDS = (
- ("agent", "agent_changes"),
- ("human attested", "human_attested_changes"),
- ("unknown", "unknown_changes"),
-)
-
-
-@register_view_builder(
- "changes.provenance",
- description="Merged changes by source: agent, human-attested, unknown.",
- artifact_types={"overview"},
- options=frozenset(),
- coverage_metric="attribution",
-)
-def changes_provenance_view(artifact: ViewArtifact, options: Mapping[str, Any]) -> dict[str, Any]:
- block = _changes_block(artifact)
- provenance = block.get("provenance")
- if not isinstance(provenance, Mapping) or "coverage" not in provenance:
- raise ViewError("attribution is off for this repository", code="attribution_off")
- # Unknown is its own band, never folded into human.
- rows = [
- {"source": label, "changes": provenance[key]}
- for label, key in _PROVENANCE_BANDS
- if isinstance(provenance.get(key), int) and not isinstance(provenance.get(key), bool)
- ]
- part = _chart(
- chart_type="donut",
- title="Changes by source",
- summary=f"{sum(r['changes'] for r in rows)} changes{_window(block)}.",
- basis=_basis("measured", "git attribution markers"),
- x=("source", "Source"),
- series=[("changes", "Changes")],
- unit="changes",
- rows=rows,
- )
- coverage = provenance.get("coverage")
- if isinstance(coverage, (int, float)) and not isinstance(coverage, bool):
- part["coverage"] = {"metric": "attribution", "ratio": coverage}
- return part
+# The named views register themselves on import; they build on this module, so last.
+from repowise.server import chat_view_builders as _builders # noqa: E402, F401
diff --git a/packages/server/src/repowise/server/schemas/views.py b/packages/server/src/repowise/server/schemas/views.py
index 669048912..cd369f088 100644
--- a/packages/server/src/repowise/server/schemas/views.py
+++ b/packages/server/src/repowise/server/schemas/views.py
@@ -31,9 +31,21 @@ from repowise.server.schemas.evidence import (
WireInt,
)
-VIEW_SCHEMA_VERSION = 1
-
-ChartType = Literal["bar", "stacked_bar", "line", "donut", "scatter"]
+VIEW_SCHEMA_VERSION = 2
+#: Versions a reader accepts: 1 is every part stored before treemaps and heatmaps.
+VIEW_SCHEMA_VERSIONS: tuple[int, ...] = (1, 2)
+
+ChartType = Literal[
+ "bar",
+ "horizontal_bar",
+ "stacked_bar",
+ "line",
+ "area",
+ "donut",
+ "scatter",
+ "treemap",
+ "heatmap",
+]
CHART_TYPES: tuple[str, ...] = get_args(ChartType)
ViewCoverageMetric = Literal["attribution", "test_reach"]
@@ -50,7 +62,8 @@ VIEW_LIMITS: dict[str, int] = {
"chart_points": 100,
"chart_series": 8,
"donut_min_parts": 2,
- "donut_max_parts": 5,
+ "donut_max_parts": 8,
+ "treemap_groups": 3,
"narrative_blocks": 50,
"section_views": 20,
}
@@ -79,7 +92,7 @@ class ViewPartBase(StrictContract):
#: Data parts carry provenance and are what other parts may name.
is_data: ClassVar[bool] = False
- schema_version: Literal[1]
+ schema_version: Literal[1, 2]
id: PartId
title: NonEmpty
summary: NonEmpty | None = None
@@ -87,9 +100,9 @@ class ViewPartBase(StrictContract):
@field_validator("schema_version", mode="before")
@classmethod
def _not_a_bool(cls, value: object) -> object:
- # Literal[1] alone accepts True, which the TypeScript side rejects.
+ # Literal[1, 2] alone accepts True, which the TypeScript side rejects.
if isinstance(value, bool):
- raise ValueError(f"expected {VIEW_SCHEMA_VERSION}")
+ raise ValueError(f"expected one of {VIEW_SCHEMA_VERSIONS}")
return value
def references(self) -> list[str]:
@@ -144,12 +157,16 @@ class TableView(ViewTableData, ViewProvenance, ViewPartBase):
_SERIES_BOUNDS: dict[str, tuple[int, int]] = {
"bar": (1, VIEW_LIMITS["chart_series"]),
+ "horizontal_bar": (1, VIEW_LIMITS["chart_series"]),
"line": (1, VIEW_LIMITS["chart_series"]),
+ "area": (1, VIEW_LIMITS["chart_series"]),
"stacked_bar": (2, VIEW_LIMITS["chart_series"]),
"donut": (1, 1),
"scatter": (1, VIEW_LIMITS["chart_series"]),
+ "treemap": (1, 1),
+ "heatmap": (1, VIEW_LIMITS["chart_series"]),
}
-_PARTS_OF_A_WHOLE = frozenset({"stacked_bar", "donut"})
+_PARTS_OF_A_WHOLE = frozenset({"stacked_bar", "donut", "treemap"})
class ChartView(ViewProvenance, ViewPartBase):
@@ -162,6 +179,8 @@ class ChartView(ViewProvenance, ViewPartBase):
series: list[NonEmpty] = Field(max_length=VIEW_LIMITS["chart_series"])
sort: ChartSortOrder | None = None
summary: NonEmpty
+ groups: list[NonEmpty] | None = Field(default=None, max_length=VIEW_LIMITS["treemap_groups"])
+ color: NonEmpty | None = None
@model_validator(mode="after")
def _chart_rules(self) -> ChartView:
@@ -170,6 +189,7 @@ class ChartView(ViewProvenance, ViewPartBase):
kind = self.chart_type
if self.x not in columns:
raise ValueError("x is not a column of data")
+ self._treemap_rules(columns)
for s in self.series:
if s not in columns:
raise ValueError(f"series {s!r} is not a column of data")
@@ -218,6 +238,22 @@ class ChartView(ViewProvenance, ViewPartBase):
raise ValueError(f"rows are not in {self.sort} order of their series total")
return self
+ def _treemap_rules(self, columns: dict[str, ViewColumn]) -> None:
+ if self.groups is None and self.color is None:
+ return
+ if self.chart_type != "treemap":
+ raise ValueError("groups and color apply to a treemap only")
+ groups = self.groups or []
+ for g in groups:
+ if g not in columns:
+ raise ValueError(f"group {g!r} is not a column of data")
+ if g == self.x or g in self.series:
+ raise ValueError(f"group {g!r} is the x or a series column")
+ if _duplicates(groups):
+ raise ValueError("groups repeats a column")
+ if self.color is not None and (self.color not in columns or self.color == self.x):
+ raise ValueError("color is not a column of data other than x")
+
def _finite_number(cell: object) -> bool:
"""A number as the TypeScript ``isFiniteNumber`` sees one: no bools, no NaN or infinity."""
diff --git a/packages/types/fixtures/views.conformance.json b/packages/types/fixtures/views.conformance.json
index 5eade432c..f9212892f 100644
--- a/packages/types/fixtures/views.conformance.json
+++ b/packages/types/fixtures/views.conformance.json
@@ -1,10 +1,11 @@
{
- "about": "Shared conformance cases for chat view parts. The TypeScript validator (packages/api-client/src/views.test.ts) and the server models (tests/unit/server/test_view_parts_contract.py) both run every case, so they accept and reject the same payloads. An invalid case copies a valid part (from), then applies drop (paths), set (path to value) and grow (path to length, repeating the array's first item). Paths are dotted; numeric segments index arrays. error is the substring the TypeScript validator reports. valid_variants are accepted by both sides but not round-tripped (JSON writes -0 as 0). Strings have no maximum length, only non-empty, so UTF-16 units and code points agree; ids and column keys are ASCII patterns. Numbers stay within +/-(2^53 - 1).",
+ "about": "Shared conformance cases for chat view parts. The TypeScript validator (packages/api-client/src/views.test.ts) and the server models (tests/unit/server/test_view_parts_contract.py) both run every case, so they accept and reject the same payloads. An invalid case copies a valid part (from), then applies drop (paths), set (path to value) and grow (path to length, repeating the array's first item). Paths are dotted; numeric segments index arrays. error is the substring the TypeScript validator reports. valid_variants are accepted by both sides but not round-tripped (JSON writes -0 as 0). Strings have no maximum length, only non-empty, so UTF-16 units and code points agree; ids and column keys are ASCII patterns. Numbers stay within +/-(2^53 - 1). Valid parts are written at schema version 1, as parts stored before version 2 are, so both sides prove those still validate.",
"vocabulary": {
- "schema_version": 1,
+ "schema_version": 2,
+ "schema_versions": [1, 2],
"max_wire_number": 9007199254740991,
"view_kinds": ["table", "chart", "section"],
- "chart_types": ["bar", "stacked_bar", "line", "donut", "scatter"],
+ "chart_types": ["bar", "horizontal_bar", "stacked_bar", "line", "area", "donut", "scatter", "treemap", "heatmap"],
"coverage_metrics": ["attribution", "test_reach"],
"sort_orders": ["asc", "desc"],
"basis_kinds": ["measured", "inferred", "declared", "unresolved"],
@@ -17,7 +18,8 @@
"chart_points": 100,
"chart_series": 8,
"donut_min_parts": 2,
- "donut_max_parts": 5,
+ "donut_max_parts": 8,
+ "treemap_groups": 3,
"narrative_blocks": 50,
"section_views": 20
},
@@ -30,7 +32,7 @@
"ViewTableData": ["columns", "rows", "total_rows", "truncated"],
"NarrativeBlock": ["text", "cites"],
"TableView": ["schema_version", "kind", "id", "title", "summary", "source", "basis", "coverage", "stale", "as_of", "columns", "rows", "total_rows", "truncated"],
- "ChartView": ["schema_version", "kind", "id", "title", "summary", "source", "basis", "coverage", "stale", "as_of", "chart_type", "data", "x", "series", "sort"],
+ "ChartView": ["schema_version", "kind", "id", "title", "summary", "source", "basis", "coverage", "stale", "as_of", "chart_type", "data", "x", "series", "sort", "groups", "color"],
"SectionView": ["schema_version", "kind", "id", "title", "summary", "narrative", "view_ids"]
},
"valid": {
@@ -195,6 +197,65 @@
"x": "max_ccn",
"series": ["commits"]
},
+ "c6": {
+ "schema_version": 1,
+ "kind": "chart",
+ "id": "c6",
+ "title": "Lines by package and directory",
+ "summary": "Core holds most lines.",
+ "source": { "artifact_id": "a7", "tool_name": "chart", "args_hash": "0123abcd" },
+ "basis": { "kind": "inferred", "source": "health engine" },
+ "stale": false,
+ "as_of": null,
+ "chart_type": "treemap",
+ "data": {
+ "columns": [
+ { "key": "package", "label": "Package" },
+ { "key": "directory", "label": "Directory" },
+ { "key": "file", "label": "File" },
+ { "key": "nloc", "label": "Lines", "unit": "lines" },
+ { "key": "health_band", "label": "Health band" }
+ ],
+ "rows": [
+ { "package": "core", "directory": "core/a", "file": "x.py", "nloc": 120, "health_band": "good" },
+ { "package": "core", "directory": "core/b", "file": "y.py", "nloc": 40, "health_band": "at risk" },
+ { "package": "web", "directory": "web/src", "file": "z.ts", "nloc": 0, "health_band": "excellent" }
+ ],
+ "total_rows": 3,
+ "truncated": false
+ },
+ "x": "file",
+ "series": ["nloc"],
+ "groups": ["package", "directory"],
+ "color": "health_band"
+ },
+ "c7": {
+ "schema_version": 1,
+ "kind": "chart",
+ "id": "c7",
+ "title": "Changes by week and category",
+ "summary": "Fixes lead every week.",
+ "source": { "artifact_id": "a8", "tool_name": "chart", "args_hash": "0123abcd" },
+ "basis": { "kind": "measured", "source": "git history" },
+ "stale": false,
+ "as_of": null,
+ "chart_type": "heatmap",
+ "data": {
+ "columns": [
+ { "key": "week", "label": "Week" },
+ { "key": "s1", "label": "fix", "unit": "changes" },
+ { "key": "s2", "label": "feature", "unit": "changes" }
+ ],
+ "rows": [
+ { "week": "2026-09-28", "s1": 4, "s2": 1 },
+ { "week": "2026-10-05", "s1": 6, "s2": null }
+ ],
+ "total_rows": 2,
+ "truncated": false
+ },
+ "x": "week",
+ "series": ["s1", "s2"]
+ },
"s1": {
"schema_version": 1,
"kind": "section",
@@ -211,7 +272,7 @@
"invalid": [
{ "name": "unknown kind", "from": "t1", "set": { "kind": "pie" }, "error": "view.kind" },
{ "name": "missing kind", "from": "t1", "drop": ["kind"], "error": "view.kind" },
- { "name": "wrong schema version", "from": "t1", "set": { "schema_version": 2 }, "error": "view.schema_version" },
+ { "name": "wrong schema version", "from": "t1", "set": { "schema_version": 3 }, "error": "view.schema_version" },
{ "name": "boolean schema version", "from": "s1", "set": { "schema_version": true }, "error": "view.schema_version" },
{ "name": "missing source", "from": "t1", "drop": ["source"], "error": "view.source: required" },
{ "name": "missing basis", "from": "c1", "drop": ["basis"], "error": "view.basis: required" },
@@ -252,8 +313,15 @@
{ "name": "negative stacked value", "from": "c2", "set": { "data.rows.0.measured": -1 }, "error": "cannot be negative" },
{ "name": "series in different units", "from": "c2", "set": { "data.columns.2.unit": "lines" }, "error": "share one unit" },
{ "name": "chart points over the cap", "from": "c3", "grow": { "data.rows": 101 }, "set": { "data.total_rows": 101 }, "error": "a chart plots at most 100 rows" },
- { "name": "donut with six parts", "from": "c4", "grow": { "data.rows": 6 }, "set": { "data.total_rows": 6 }, "error": "a donut has 2 to 5 parts" },
+ { "name": "donut with nine parts", "from": "c4", "grow": { "data.rows": 9 }, "set": { "data.total_rows": 9 }, "error": "a donut has 2 to 8 parts" },
{ "name": "donut over truncated data", "from": "c4", "set": { "data.total_rows": 10, "data.truncated": true }, "error": "a donut must show the whole" },
+ { "name": "groups on a bar chart", "from": "c1", "set": { "groups": ["component"] }, "error": "groups and color apply to a treemap only" },
+ { "name": "treemap group naming a missing column", "from": "c6", "set": { "groups": ["nope"] }, "error": "view.groups[0]: not a column of data" },
+ { "name": "treemap group that is the x column", "from": "c6", "set": { "groups": ["file"] }, "error": "is the x or a series column" },
+ { "name": "treemap coloured by its x", "from": "c6", "set": { "color": "file" }, "error": "view.color: not a column of data other than x" },
+ { "name": "treemap with two series", "from": "c6", "set": { "series": ["nloc", "health_band"] }, "error": "a treemap chart plots 1 series" },
+ { "name": "negative treemap cell", "from": "c6", "set": { "data.rows.0.nloc": -1 }, "error": "cannot be negative" },
+ { "name": "string in a heatmap cell", "from": "c7", "set": { "data.rows.0.s1": "4" }, "error": "plotted values must be numbers" },
{ "name": "scatter with a text x", "from": "c5", "set": { "data.rows.0.max_ccn": "high" }, "error": "a scatter x is a number" },
{ "name": "donut with a null part", "from": "c4", "set": { "data.rows.0.files": null }, "error": "a donut part is null" },
{ "name": "empty section", "from": "s1", "set": { "narrative": [], "view_ids": [] }, "error": "a section needs narrative or views" },
@@ -271,6 +339,7 @@
{"name": "stacked bar of all zeros", "from": "c2", "set": {"data.rows.0.measured": 0, "data.rows.0.inferred": 0, "data.rows.1.measured": 0, "data.rows.1.inferred": 0}, "error": "a stacked_bar needs a positive total"}
],
"valid_variants": [
+ { "name": "a part at the current schema version", "from": "c6", "set": { "schema_version": 2 } },
{ "name": "non-BMP title and summary", "from": "t1", "set": { "title": "😀", "summary": "Payments 💳 leads" } },
{ "name": "negative zero in a line", "from": "c3", "set": { "data.rows.0.commits": -0 } },
{ "name": "negative zero donut part", "from": "c4", "set": { "data.rows.2.files": -0.0 } },
@@ -279,7 +348,7 @@
{ "name": "line chart with a null and no sort", "from": "c3", "set": { "data.rows.0.commits": null } }
],
"valid_lists": [
- { "name": "every valid part together", "items": [{ "from": "t1" }, { "from": "c1" }, { "from": "c2" }, { "from": "c3" }, { "from": "c4" }, { "from": "c5" }, { "from": "s1" }] },
+ { "name": "every valid part together", "items": [{ "from": "t1" }, { "from": "c1" }, { "from": "c2" }, { "from": "c3" }, { "from": "c4" }, { "from": "c5" }, { "from": "c6" }, { "from": "c7" }, { "from": "s1" }] },
{ "name": "no parts", "items": [] }
],
"invalid_lists": [
diff --git a/packages/types/src/views.ts b/packages/types/src/views.ts
index 9e48a0a0b..399194876 100644
--- a/packages/types/src/views.ts
+++ b/packages/types/src/views.ts
@@ -15,18 +15,38 @@
* and its cases in `packages/types/fixtures/views.conformance.json`. Maps
* keyed by `ViewKind` (validator, renderers) fail to compile until filled.
* `schema_version` changes whenever a field is added or removed, because both
- * validators reject unknown fields.
+ * validators reject unknown fields; readers keep accepting the older versions
+ * so stored parts still render, and a client meeting a chart it cannot draw
+ * shows its table (`parseViewParts`).
*/
import type { CardBasis, CardRef } from "./evidence.js";
-export const VIEW_SCHEMA_VERSION = 1 as const;
+/** The version a server writes. */
+export const VIEW_SCHEMA_VERSION = 2 as const;
+/** Versions a reader accepts: 1 is every part stored before treemaps and heatmaps. */
+export const VIEW_SCHEMA_VERSIONS = [1, 2] as const;
+export type ViewSchemaVersion = (typeof VIEW_SCHEMA_VERSIONS)[number];
/** The chat-only tool that builds views. Its call is plumbing, not evidence. */
export const SHOW_VIEW_TOOL = "show_view";
+/** The chat-only tool that charts a server dataset in one call; plumbing too. */
+export const CHART_TOOL = "chart";
+/** Tool calls whose result is a view, not evidence. */
+export const VIEW_TOOLS: ReadonlySet<string> = new Set([SHOW_VIEW_TOOL, CHART_TOOL]);
/** Chart forms. A new form is added with its builder, never as a general grammar. */
-export const CHART_TYPES = ["bar", "stacked_bar", "line", "donut", "scatter"] as const;
+export const CHART_TYPES = [
+ "bar",
+ "horizontal_bar",
+ "stacked_bar",
+ "line",
+ "area",
+ "donut",
+ "scatter",
+ "treemap",
+ "heatmap",
+] as const;
export type ChartType = (typeof CHART_TYPES)[number];
/** What a coverage ratio measures. */
@@ -50,7 +70,9 @@ export const VIEW_LIMITS = {
chart_series: 8,
/** Rows a donut needs at least and at most. */
donut_min_parts: 2,
- donut_max_parts: 5,
+ donut_max_parts: 8,
+ /** Nesting levels a treemap may name in `groups`. */
+ treemap_groups: 3,
narrative_blocks: 50,
section_views: 20,
} as const;
@@ -72,7 +94,7 @@ export interface ViewCoverage {
}
export interface ViewPartBase<K extends string> {
- schema_version: typeof VIEW_SCHEMA_VERSION;
+ schema_version: ViewSchemaVersion;
kind: K;
/** Unique within one turn or report; sections and narrative cite parts by it. */
id: string;
@@ -126,6 +148,10 @@ export interface TableView extends ViewPartBase<"table">, ViewProvenance, ViewTa
* one shared unit. `sort` states the rows' order by the sum of their series
* values (absent means source order) and is checked, not trusted. A scatter's
* `x` is numeric too: each row is one point per series it has a value in.
+ * A heatmap reads the same table as a grid: rows by `x`, one column per
+ * series, each cell its value. A treemap sizes one cell per row by its one
+ * series, nests cells by `groups` (column keys, outermost first) and may
+ * colour them by `color` (a column key); both fields belong to treemaps only.
*/
export interface ChartView extends ViewPartBase<"chart">, ViewProvenance {
chart_type: ChartType;
@@ -135,6 +161,8 @@ export interface ChartView extends ViewPartBase<"chart">, ViewProvenance {
sort?: ChartSortOrder;
/** Required: a chart always comes with its text summary. */
summary: string;
+ groups?: string[];
+ color?: string;
}
/** One paragraph of report narrative and the parts its facts rest on. */
diff --git a/packages/ui/__tests__/chat/view-part.test.tsx b/packages/ui/__tests__/chat/view-part.test.tsx
index 9fa4bca15..08598c0a1 100644
--- a/packages/ui/__tests__/chat/view-part.test.tsx
+++ b/packages/ui/__tests__/chat/view-part.test.tsx
@@ -227,6 +227,116 @@ describe("ViewPartList", () => {
expect(cite.getAttribute("href")).toBe(`#${part("c1").id}`);
});
+ it("nests a treemap by its groups and colours its cells by health band", () => {
+ const TREEMAP = valid.c6 as ChartView;
+ render(<ViewPartList views={[TREEMAP]} />);
+ const figure = part("c6");
+
+ expect(figure).toHaveAttribute("data-chart-type", "treemap");
+ // A zero-sized row draws no cell; two packages hold the rest.
+ const cells = figure.querySelectorAll("[data-treemap-cell]");
+ expect(cells).toHaveLength(2);
+ expect(figure.querySelectorAll("[data-treemap-group]").length).toBeGreaterThanOrEqual(1);
+ expect((cells[0] as HTMLElement).style.background).toBe("var(--color-node-good)");
+ // The band is named on the cell and in its title, not only coloured.
+ expect(cells[0]).toHaveAttribute("title", expect.stringContaining("good"));
+ const legend = within(figure).getByRole("list");
+ expect(legend).toHaveTextContent("at risk");
+ expect(legend).toHaveTextContent("good");
+ });
+
+ it("draws a heatmap as a grid with every value in its cell", () => {
+ const HEATMAP = valid.c7 as ChartView;
+ render(<ViewPartList views={[HEATMAP]} />);
+ const figure = part("c7");
+
+ const cells = [...figure.querySelectorAll("[data-heat-cell]")] as HTMLElement[];
+ expect(cells.map((c) => c.textContent)).toEqual(["4", "1", "6"]);
+ // The largest value is the darkest step and carries card-coloured text.
+ expect(cells[2]!.style.color).toBe("var(--color-bg-surface)");
+ expect(cells[1]!.style.color).toBe("var(--color-text-primary)");
+ expect(within(figure).getByRole("list")).toHaveTextContent("6 (darkest)");
+ // A table to assistive tech: a header row, then one row per week.
+ const grid = figure.querySelector('[role="table"]') as HTMLElement;
+ expect(grid).toHaveAttribute("aria-label", HEATMAP.title);
+ expect(within(grid).getAllByRole("columnheader").map((h) => h.textContent)).toEqual(["Week", "fix", "feature"]);
+ expect(within(grid).getAllByRole("rowheader").map((h) => h.textContent)).toEqual(["2026-09-28", "2026-10-05"]);
+ expect(within(grid).getAllByRole("cell")).toHaveLength(4);
+ expect(within(grid).getByText("none")).toHaveClass("sr-only");
+ });
+
+ it("renders parts stored at schema version 1 and at the current one", () => {
+ expect(BAR.schema_version).toBe(1);
+ render(<ViewPartList views={[BAR, { ...BAR, id: "v2part", schema_version: 2 }]} />);
+ expect(part("c1").querySelector("svg.recharts-surface")).not.toBeNull();
+ expect(part("v2part").querySelector("svg.recharts-surface")).not.toBeNull();
+ });
+
+ it("fills an area chart and runs bars over dates as columns", () => {
+ const weeks = ["2026-09-28", "2026-10-05", "2026-10-12"];
+ const dated = { ...LINE.data, rows: LINE.data.rows.map((r, i) => ({ ...r, week: weeks[i]! })) };
+ render(
+ <ViewPartList
+ views={[
+ { ...LINE, id: "a1", chart_type: "area" },
+ { ...LINE, id: "b1", chart_type: "bar", data: dated },
+ { ...LINE, id: "h1", chart_type: "horizontal_bar", data: dated },
+ ]}
+ />,
+ );
+
+ expect(part("a1").querySelector(".recharts-area-area")).not.toBeNull();
+ // Columns put the dates on the x axis; a horizontal bar puts them on y.
+ expect(part("b1").querySelector(".recharts-xAxis-tick-labels")).toHaveTextContent("2026-09-28");
+ expect(part("h1").querySelector(".recharts-yAxis-tick-labels")).toHaveTextContent("2026-09-28");
+ });
+
+ it("folds up to eight donut parts, each named with its value", () => {
+ const rows = Array.from({ length: 8 }, (_, i) => ({ tier: `t${i}`, files: i + 1 }));
+ render(
+ <ViewPartList views={[{ ...DONUT, id: "d8", data: { ...DONUT.data, rows, total_rows: 8 } }]} />,
+ );
+ const items = within(part("d8")).getAllByRole("listitem");
+
+ expect(items).toHaveLength(8);
+ expect(items[7]).toHaveTextContent("t7");
+ expect(items[7]).toHaveTextContent("8");
+ });
+
+ it("labels two files of one name by their shortest distinct path", () => {
+ const rows = [
+ { component: { type: "file" as const, id: "a/update_cmd/command.py" }, changes: 3 },
+ { component: { type: "file" as const, id: "a/init_cmd/command.py" }, changes: 2 },
+ ];
+ const { sort: _sort, ...unsorted } = BAR;
+ const data = { ...BAR.data, rows, total_rows: 2 };
+ render(<ViewPartList views={[{ ...unsorted, id: "u1", chart_type: "donut", data }]} />);
+
+ const legend = within(part("u1")).getByRole("list");
+ expect(legend).toHaveTextContent("update_cmd/command.py");
+ expect(legend).toHaveTextContent("init_cmd/command.py");
+ });
+
+ it("names a view tool's chart by its basis alone, and never says unresolved", () => {
+ const fromChart: ChartView = {
+ ...BAR,
+ id: "p1",
+ source: { ...BAR.source, tool_name: "chart" },
+ };
+ const unresolved: ChartView = {
+ ...BAR,
+ id: "p2",
+ basis: { kind: "unresolved", source: "get_overview" },
+ source: { ...BAR.source, tool_name: "get_overview" },
+ };
+ render(<ViewPartList views={[fromChart, unresolved]} />);
+
+ expect(part("p1").querySelector("[data-view-provenance]")).not.toHaveTextContent("chart");
+ const line = part("p2").querySelector("[data-view-provenance]") as HTMLElement;
+ expect(line).toHaveTextContent("From get_overview");
+ expect(line).not.toHaveTextContent(/unresolved/i);
+ });
+
it("gives repeated view ids page-unique anchors across turns", () => {
render(
<>
diff --git a/packages/ui/scripts/contrast-check.py b/packages/ui/scripts/contrast-check.py
index ff84fd57e..77b383700 100755
--- a/packages/ui/scripts/contrast-check.py
+++ b/packages/ui/scripts/contrast-check.py
@@ -142,6 +142,10 @@ LIGHT = {
# 86/74/63/54/47%. The tail (20%) is exempt: it is always named.
"share-1": "#413846", "share-2": "#59515C", "share-3": "#6F6871",
"share-4": "#827B82", "share-5": "#90898F",
+ # Heat steps (light): --color-text-primary mixed into --color-bg-surface
+ # at 6/14/26/62/82%.
+ "heat-1": "#F2F1F2", "heat-2": "#E0DFE1", "heat-3": "#C6C4C8",
+ "heat-4": "#77727C", "heat-5": "#4B4452",
}
DARK = {
@@ -186,6 +190,9 @@ DARK = {
# Share steps (dark): 86/71/58/48/40%; tail (18%) exempt.
"share-1": "#D2D2D3", "share-2": "#AFAFB0", "share-3": "#919192",
"share-4": "#79797A", "share-5": "#676768",
+ # Heat steps (dark): the same mixes over the dark card.
+ "heat-1": "#212123", "heat-2": "#333335", "heat-3": "#4E4E4F",
+ "heat-4": "#9E9E9F", "heat-5": "#CACACB",
}
# (fg, bg, floor, label) — floor is the WCAG ratio the pair must meet.
@@ -230,6 +237,9 @@ CHECKS = [
for n in range(1, 6)
for bg, where in (("bg-root", "page"), ("bg-surface", "card"))
],
+ # Heatmap cells print their value: ink on the light steps, card colour on the dark.
+ *[("text-primary", f"heat-{n}", 4.5, f"Value on heat step {n}") for n in (1, 2, 3)],
+ *[("bg-surface", f"heat-{n}", 4.5, f"Value on heat step {n}") for n in (4, 5)],
]
diff --git a/packages/ui/src/chat/tool-call-block.tsx b/packages/ui/src/chat/tool-call-block.tsx
index 9795a2d9f..3f8c65f5f 100644
--- a/packages/ui/src/chat/tool-call-block.tsx
+++ b/packages/ui/src/chat/tool-call-block.tsx
@@ -11,7 +11,7 @@ import { ArrowUpRight, ChevronRight } from "lucide-react";
import { cn } from "../lib/cn";
import { HighlightedCodeBlock } from "../shared/code-block";
import type { ChatUIToolCall } from "@repowise-dev/types/chat";
-import { SHOW_VIEW_TOOL } from "@repowise-dev/types/views";
+import { CHART_TOOL, SHOW_VIEW_TOOL } from "@repowise-dev/types/views";
const TOOL_LABELS: Record<string, string> = {
get_overview: "Getting codebase overview",
@@ -25,6 +25,7 @@ const TOOL_LABELS: Record<string, string> = {
get_dead_code: "Checking dead code",
get_answer: "Asking the index",
[SHOW_VIEW_TOOL]: "Building a view",
+ [CHART_TOOL]: "Drawing a chart",
};
/** A step the server took for the page, before the model's first turn. */
diff --git a/packages/ui/src/chat/view-part.tsx b/packages/ui/src/chat/view-part.tsx
index 5418899bf..f73e5468f 100644
--- a/packages/ui/src/chat/view-part.tsx
+++ b/packages/ui/src/chat/view-part.tsx
@@ -6,10 +6,15 @@
* rows it is given: every chart keeps a text summary, a "Data" toggle opens
* the table it plots, and the line under each part names where the values
* came from. On paper the toggle goes and every chart prints with its table.
+ * Treemaps and heatmaps are drawn as HTML boxes, so their labels keep their
+ * size at any width and need no measuring.
*/
import { useId, useState, type ReactNode } from "react";
+import { hierarchy, treemap, type HierarchyRectangularNode } from "d3-hierarchy";
import {
+ Area,
+ AreaChart,
Bar,
BarChart,
CartesianGrid,
@@ -28,14 +33,15 @@ import {
type SymbolType,
} from "recharts";
import type { CardRef } from "@repowise-dev/types/cards";
-import type {
- ChartView,
- SectionView,
- TableView,
- ViewCell,
- ViewColumn,
- ViewPart,
- ViewTableData,
+import {
+ VIEW_TOOLS,
+ type ChartView,
+ type SectionView,
+ type TableView,
+ type ViewCell,
+ type ViewColumn,
+ type ViewPart,
+ type ViewTableData,
} from "@repowise-dev/types/views";
import { BasisNote, RefView, refLabel, type RefHref } from "../cards/evidence-card";
import { cn } from "../lib/cn";
@@ -64,6 +70,49 @@ const lineDash = (i: number): string => LINE_DASHES[Math.min(i, LINE_DASHES.leng
const pointShape = (i: number): SymbolType => POINT_SHAPES[Math.min(i, POINT_SHAPES.length - 1)]!;
/** The series a chart draws; the rest stay in its data table. */
const drawnSeries = (view: ChartView): string[] => view.series.slice(0, SERIES_FILLS.length);
+/**
+ * A donut's parts: the five share steps, then two neutral steps and the
+ * tail, which sit last where an Other part goes. Past five the steps no
+ * longer clear 3:1, so every part is also named with its value in the legend.
+ */
+const DONUT_FILLS = [
+ ...SERIES_FILLS,
+ "var(--color-neutral-1)",
+ "var(--color-neutral-2)",
+ "var(--color-share-tail)",
+] as const;
+const donutFill = (i: number): string => DONUT_FILLS[Math.min(i, DONUT_FILLS.length - 1)]!;
+
+/**
+ * Heatmap steps, light to dark (the heat tokens). The two dark steps carry
+ * card-coloured text and the light ones ink, each pair clearing 4.5:1, so a
+ * value reads on its cell.
+ */
+const HEAT_STEPS = [
+ { fill: "var(--color-heat-1)", ink: false },
+ { fill: "var(--color-heat-2)", ink: false },
+ { fill: "var(--color-heat-3)", ink: false },
+ { fill: "var(--color-heat-4)", ink: true },
+ { fill: "var(--color-heat-5)", ink: true },
+] as const;
+
+/** Health bands as fills, worst first: the health galaxy's node ramp. */
+const BAND_FILLS: Record<string, string> = {
+ "at risk": "var(--color-node-at-risk)",
+ "needs work": "var(--color-node-needs-work)",
+ fair: "var(--color-node-fair)",
+ good: "var(--color-node-good)",
+ excellent: "var(--color-node-excellent)",
+};
+/** The health engine's band floors (grading.py): a 0 to 10 score to its band. */
+const BAND_FLOORS: Array<[number, string]> = [
+ [8.5, "excellent"],
+ [7, "good"],
+ [5.5, "fair"],
+ [4, "needs work"],
+ [-Infinity, "at risk"],
+];
+const bandOf = (score: number): string => BAND_FLOORS.find(([floor]) => score >= floor)![1];
const COVERAGE_LABEL: Record<string, string> = {
attribution: "Attribution coverage",
@@ -97,8 +146,29 @@ function columnHeading(column: ViewColumn): string {
: column.label;
}
+/** A label cut to *max*; a path keeps its end, which is the part that names it. */
function short(text: string, max = 22): string {
- return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+ if (text.length <= max) return text;
+ return text.includes("/") ? `…${text.slice(text.length - max + 1)}` : `${text.slice(0, max - 1)}…`;
+}
+
+/**
+ * Axis labels for x cells. File refs show their shortest path suffix no
+ * other file in the chart shares, so two `command.py` never read alike.
+ */
+export function axisLabels(cells: ViewCell[]): string[] {
+ const paths = cells.map((cell) => (isRef(cell) && cell.type === "file" && !cell.start_line ? cell.id : null));
+ const parts = paths.map((path) => path?.split("/") ?? []);
+ return cells.map((cell, i) => {
+ const own = parts[i]!;
+ if (paths[i] === null) return cellText(cell);
+ for (let k = 1; k <= own.length; k++) {
+ const tail = own.slice(-k).join("/");
+ const shared = parts.some((other, j) => j !== i && paths[j] !== null && other.slice(-k).join("/") === tail);
+ if (!shared) return tail;
+ }
+ return paths[i]!;
+ });
}
interface PartProps {
@@ -179,8 +249,14 @@ function ProvenanceLine({ part }: { part: TableView | ChartView }) {
const coverage = part.coverage;
return (
<p data-view-provenance="" className="flex flex-wrap gap-x-2 gap-y-0.5 text-xs text-[var(--color-text-tertiary)]">
- <BasisNote basis={part.basis} />
- <span>· {part.source.tool_name}</span>
+ {part.basis.kind === "unresolved" ? (
+ <span data-card-basis="unresolved">From {part.basis.source}</span>
+ ) : (
+ <BasisNote basis={part.basis} />
+ )}
+ {!VIEW_TOOLS.has(part.source.tool_name) && part.basis.source !== part.source.tool_name && (
+ <span>· {part.source.tool_name}</span>
+ )}
{coverage && (
<span data-view-coverage={coverage.metric}>
· {COVERAGE_LABEL[coverage.metric] ?? coverage.metric} {Math.round(coverage.ratio * 100)}%
@@ -205,12 +281,22 @@ function legendItems(view: ChartView): Array<{ label: string; fill: string; valu
if (view.chart_type === "donut") {
const key = view.series[0];
if (key === undefined) return [];
+ const labels = axisLabels(view.data.rows.map((row) => row[view.x] ?? null));
return view.data.rows.map((row, i) => ({
- label: cellText(row[view.x] ?? null),
- fill: seriesFill(i),
+ label: labels[i]!,
+ fill: donutFill(i),
value: row[key] ?? null,
}));
}
+ if (view.chart_type === "treemap") return treemapColors(view).legend;
+ if (view.chart_type === "heatmap") {
+ const { low, high } = heatRange(view);
+ if (low === null || high === null) return [];
+ return [
+ { label: `${low} (lightest)`, fill: HEAT_STEPS[0].fill },
+ { label: `${high} (darkest)`, fill: HEAT_STEPS[HEAT_STEPS.length - 1]!.fill },
+ ];
+ }
if (view.series.length < 2) return [];
const labels = new Map(view.data.columns.map((c) => [c.key, c.label]));
return drawnSeries(view).map((key, i) => ({ label: labels.get(key) ?? key, fill: seriesFill(i) }));
@@ -218,13 +304,14 @@ function legendItems(view: ChartView): Array<{ label: string; fill: string; valu
function ChartLegend({ view }: { view: ChartView }) {
const items = legendItems(view);
- const undrawn = view.chart_type === "donut" ? 0 : view.series.length - drawnSeries(view).length;
+ const whole = ["donut", "treemap", "heatmap"].includes(view.chart_type);
+ const undrawn = whole ? 0 : view.series.length - drawnSeries(view).length;
if (items.length === 0) return null;
return (
<ul className="flex flex-wrap gap-x-4 gap-y-1 text-xs text-[var(--color-text-secondary)]">
{items.map((item, i) => (
<li key={i} className="inline-flex items-center gap-1.5">
- {view.chart_type === "line" ? (
+ {view.chart_type === "line" || view.chart_type === "area" ? (
<svg aria-hidden width="16" height="6" className="shrink-0">
<line x1="0" y1="3" x2="16" y2="3" stroke={item.fill} strokeWidth="2" strokeDasharray={lineDash(i)} />
</svg>
@@ -251,10 +338,13 @@ function ChartLegend({ view }: { view: ChartView }) {
}
function ChartPlot({ view }: { view: ChartView }) {
+ if (view.chart_type === "treemap") return <TreemapPlot view={view} />;
+ if (view.chart_type === "heatmap") return <HeatmapPlot view={view} />;
const series = drawnSeries(view);
const labels = new Map(view.data.columns.map((c) => [c.key, c.label]));
- const rows = view.data.rows.map((row) => {
- const point: Record<string, string | number | null> = { [X_KEY]: cellText(row[view.x] ?? null) };
+ const xLabels = axisLabels(view.data.rows.map((row) => row[view.x] ?? null));
+ const rows = view.data.rows.map((row, i) => {
+ const point: Record<string, string | number | null> = { [X_KEY]: xLabels[i]! };
for (const key of series) {
const value = row[key];
point[key] = typeof value === "number" ? value : null;
@@ -286,7 +376,7 @@ function ChartPlot({ view }: { view: ChartView }) {
isAnimationActive={false}
>
{rows.map((_, i) => (
- <Cell key={i} fill={seriesFill(i)} />
+ <Cell key={i} fill={donutFill(i)} />
))}
</Pie>
{tooltip}
@@ -338,6 +428,35 @@ function ChartPlot({ view }: { view: ChartView }) {
);
}
+ if (view.chart_type === "area") {
+ return (
+ <div style={{ height: PLOT_PX }}>
+ <ResponsiveContainer width="100%" height="100%">
+ <AreaChart data={rows} margin={{ top: 8, right: 12, bottom: 0, left: -12 }}>
+ <CartesianGrid stroke="var(--color-border-default)" vertical={false} />
+ <XAxis dataKey={X_KEY} tick={AXIS_TICK} axisLine={false} tickLine={false} tickFormatter={(v: string) => short(v, 14)} />
+ <YAxis tick={AXIS_TICK} axisLine={false} tickLine={false} />
+ {tooltip}
+ {series.map((key, i) => (
+ <Area
+ key={key}
+ type="monotone"
+ dataKey={key}
+ stroke={seriesFill(i)}
+ strokeDasharray={lineDash(i)}
+ strokeWidth={2}
+ fill={seriesFill(i)}
+ fillOpacity={0.18}
+ connectNulls={false}
+ isAnimationActive={false}
+ />
+ ))}
+ </AreaChart>
+ </ResponsiveContainer>
+ </div>
+ );
+ }
+
if (view.chart_type === "line") {
return (
<div style={{ height: PLOT_PX }}>
@@ -367,8 +486,33 @@ function ChartPlot({ view }: { view: ChartView }) {
}
// Bars run horizontally: their categories are components and paths, which
- // read along a row and not under a column.
+ // read along a row and not under a column. Over dates a bar is a column,
+ // so time runs left to right as it does on a line.
const stacked = view.chart_type === "stacked_bar";
+ if (view.chart_type !== "horizontal_bar" && isTimeAxis(view)) {
+ return (
+ <div style={{ height: PLOT_PX }}>
+ <ResponsiveContainer width="100%" height="100%">
+ <BarChart data={rows} margin={{ top: 8, right: 12, bottom: 0, left: -12 }}>
+ <CartesianGrid stroke="var(--color-border-default)" vertical={false} />
+ <XAxis dataKey={X_KEY} tick={AXIS_TICK} axisLine={false} tickLine={false} tickFormatter={(v: string) => short(v, 14)} />
+ <YAxis tick={AXIS_TICK} axisLine={false} tickLine={false} />
+ {tooltip}
+ {series.map((key, i) => (
+ <Bar
+ key={key}
+ dataKey={key}
+ fill={seriesFill(i)}
+ {...(stacked ? { stackId: "parts", stroke: "var(--color-bg-surface)", strokeWidth: 1 } : {})}
+ maxBarSize={28}
+ isAnimationActive={false}
+ />
+ ))}
+ </BarChart>
+ </ResponsiveContainer>
+ </div>
+ );
+ }
return (
<div style={{ height: Math.max(96, rows.length * BAR_ROW_PX + 32) }}>
<ResponsiveContainer width="100%" height="100%">
@@ -403,6 +547,246 @@ function ChartPlot({ view }: { view: ChartView }) {
);
}
+const TIME = /^\d{4}-\d{2}(-\d{2})?([T ]\d{2}:\d{2})?/;
+
+/** True when every x cell is a date, so the chart reads left to right in time. */
+function isTimeAxis(view: ChartView): boolean {
+ const cells = view.data.rows.map((row) => row[view.x]);
+ return cells.length > 0 && cells.every((cell) => typeof cell === "string" && TIME.test(cell));
+}
+
+function numbersIn(view: ChartView, keys: string[]): number[] {
+ return view.data.rows.flatMap((row) => keys.map((k) => row[k]).filter((v): v is number => typeof v === "number"));
+}
+
+function heatRange(view: ChartView): { low: number | null; high: number | null } {
+ const values = numbersIn(view, view.series);
+ return values.length ? { low: Math.min(...values), high: Math.max(...values) } : { low: null, high: null };
+}
+
+function heatStep(value: number, low: number, high: number): (typeof HEAT_STEPS)[number] {
+ const span = high - low;
+ const at = span > 0 ? Math.min(HEAT_STEPS.length - 1, Math.floor(((value - low) / span) * HEAT_STEPS.length)) : HEAT_STEPS.length - 1;
+ return HEAT_STEPS[at]!;
+}
+
+/**
+ * A grid of rows by `x` and one column per series; every cell shows its value.
+ * It is a table to assistive tech too (rows, headers, cells), since the
+ * values sit in the cells and not only in the colour.
+ */
+function HeatmapPlot({ view }: { view: ChartView }) {
+ const labels = new Map(view.data.columns.map((c) => [c.key, c.label]));
+ const xLabels = axisLabels(view.data.rows.map((row) => row[view.x] ?? null));
+ const { low, high } = heatRange(view);
+ return (
+ <div className="max-w-full overflow-x-auto">
+ <div
+ role="table"
+ aria-label={view.title}
+ className="grid gap-px text-[11px] tabular-nums"
+ style={{ gridTemplateColumns: `minmax(6rem, 14rem) repeat(${view.series.length}, minmax(3rem, 1fr))` }}
+ >
+ <div role="row" className="contents">
+ <span role="columnheader" className="truncate px-1 pb-1 text-[var(--color-text-tertiary)]">
+ {labels.get(view.x) ?? view.x}
+ </span>
+ {view.series.map((key) => (
+ <span
+ key={key}
+ role="columnheader"
+ className="truncate px-1 pb-1 text-center text-[var(--color-text-tertiary)]"
+ title={labels.get(key)}
+ >
+ {short(labels.get(key) ?? key, 14)}
+ </span>
+ ))}
+ </div>
+ {view.data.rows.map((row, i) => (
+ <HeatRow key={i} label={xLabels[i]!} row={row} series={view.series} low={low} high={high} />
+ ))}
+ </div>
+ </div>
+ );
+}
+
+function HeatRow({
+ label,
+ row,
+ series,
+ low,
+ high,
+}: {
+ label: string;
+ row: Record<string, ViewCell>;
+ series: string[];
+ low: number | null;
+ high: number | null;
+}) {
+ return (
+ <div role="row" className="contents">
+ <span role="rowheader" className="truncate py-1 pr-2 text-[var(--color-text-secondary)]" title={label}>
+ {short(label, 30)}
+ </span>
+ {series.map((key) => {
+ const value = row[key];
+ if (typeof value !== "number" || low === null || high === null) {
+ return (
+ <span key={key} role="cell" className="rounded-sm bg-[var(--color-bg-inset)]">
+ <span className="sr-only">none</span>
+ </span>
+ );
+ }
+ const step = heatStep(value, low, high);
+ return (
+ <span
+ key={key}
+ role="cell"
+ data-heat-cell=""
+ className="rounded-sm px-1 py-1 text-center"
+ style={{ background: step.fill, color: step.ink ? "var(--color-bg-surface)" : "var(--color-text-primary)" }}
+ >
+ {value}
+ </span>
+ );
+ })}
+ </div>
+ );
+}
+
+interface TreemapLeaf {
+ name: string;
+ size: number;
+ color: string;
+ path: string;
+ /** What the fill stands for ("at risk", "7.2"), named on the cell, not only coloured. */
+ tone: string | null;
+}
+interface TreemapBranch {
+ name: string;
+ children: Array<TreemapBranch | TreemapLeaf>;
+}
+
+/**
+ * Each row's colour and the legend for it: health bands (as names, or a 0 to
+ * 10 health score) take the health ramp; other text takes the share steps in
+ * order of first appearance; other numbers take the heat steps.
+ */
+function treemapColors(view: ChartView): { fills: string[]; legend: Array<{ label: string; fill: string }> } {
+ const plain = "var(--color-share-3)";
+ const key = view.color;
+ if (!key) return { fills: view.data.rows.map(() => plain), legend: [] };
+ const cells = view.data.rows.map((row) => row[key] ?? null);
+ const label = view.data.columns.find((c) => c.key === key)?.label ?? key;
+ const numbers = cells.filter((c): c is number => typeof c === "number");
+ const isHealth = /health/i.test(`${key} ${label}`) && numbers.every((n) => n >= 0 && n <= 10);
+ const names = cells.map((c) =>
+ typeof c === "number" ? (isHealth ? bandOf(c) : null) : c === null ? null : cellText(c).replace(/_/g, " ").toLowerCase(),
+ );
+ if (names.every((n) => n === null || n in BAND_FILLS) && names.some((n) => n !== null)) {
+ const present = Object.keys(BAND_FILLS).filter((band) => names.includes(band));
+ return {
+ fills: names.map((n) => (n ? BAND_FILLS[n]! : "var(--color-node-neutral)")),
+ legend: present.map((band) => ({ label: band, fill: BAND_FILLS[band]! })),
+ };
+ }
+ if (numbers.length === cells.filter((c) => c !== null).length && numbers.length > 0) {
+ const low = Math.min(...numbers);
+ const high = Math.max(...numbers);
+ return {
+ fills: cells.map((c) => (typeof c === "number" ? heatStep(c, low, high).fill : "var(--color-node-neutral)")),
+ legend: [
+ { label: `${label} ${low} (lightest)`, fill: HEAT_STEPS[0].fill },
+ { label: `${label} ${high} (darkest)`, fill: HEAT_STEPS[HEAT_STEPS.length - 1]!.fill },
+ ],
+ };
+ }
+ const order = [...new Set(names.filter((n): n is string => n !== null))];
+ const fillOf = (n: string | null) => (n === null ? "var(--color-node-neutral)" : seriesFill(order.indexOf(n)));
+ return {
+ fills: names.map(fillOf),
+ legend: order.slice(0, SERIES_FILLS.length).map((n) => ({ label: n, fill: fillOf(n) })),
+ };
+}
+
+const TREEMAP_BOX = { width: 160, height: 100 };
+const HALO = "0 0 2px var(--color-bg-surface), 0 0 3px var(--color-bg-surface)";
+
+/** Cells sized by the one series, nested by `groups`, laid out once in percentages. */
+function TreemapPlot({ view }: { view: ChartView }) {
+ const sizeKey = view.series[0];
+ if (sizeKey === undefined) return null;
+ const { fills } = treemapColors(view);
+ const xLabels = axisLabels(view.data.rows.map((row) => row[view.x] ?? null));
+ const root: TreemapBranch = { name: "", children: [] };
+ view.data.rows.forEach((row, i) => {
+ const size = row[sizeKey];
+ if (typeof size !== "number" || size <= 0) return;
+ let node = root;
+ for (const group of view.groups ?? []) {
+ const name = cellText(row[group] ?? null) || "none";
+ let next = node.children.find((c): c is TreemapBranch => "children" in c && c.name === name);
+ if (!next) {
+ next = { name, children: [] };
+ node.children.push(next);
+ }
+ node = next;
+ }
+ const tone = view.color ? cellText(row[view.color] ?? null) || null : null;
+ node.children.push({ name: xLabels[i]!, size, color: fills[i]!, path: cellText(row[view.x] ?? null), tone });
+ });
+ const laid = treemap<TreemapBranch | TreemapLeaf>()
+ .size([TREEMAP_BOX.width, TREEMAP_BOX.height])
+ .paddingInner(0.4)
+ .paddingTop((node) => (node.depth > 0 && node.children ? 3 : 0))(
+ hierarchy<TreemapBranch | TreemapLeaf>(root, (d) => ("children" in d ? d.children : undefined))
+ .sum((d) => ("size" in d ? d.size : 0))
+ .sort((a, b) => (b.value ?? 0) - (a.value ?? 0)),
+ );
+ const box = (n: HierarchyRectangularNode<TreemapBranch | TreemapLeaf>) => ({
+ left: `${(n.x0 / TREEMAP_BOX.width) * 100}%`,
+ top: `${(n.y0 / TREEMAP_BOX.height) * 100}%`,
+ width: `${((n.x1 - n.x0) / TREEMAP_BOX.width) * 100}%`,
+ height: `${((n.y1 - n.y0) / TREEMAP_BOX.height) * 100}%`,
+ });
+ return (
+ <div className="relative w-full overflow-hidden rounded-md" style={{ height: 260 }}>
+ {laid.descendants().map((node, i) => {
+ if (node.depth === 0) return null;
+ const d = node.data;
+ if ("children" in d) {
+ return (
+ <div
+ key={`g${i}`}
+ data-treemap-group=""
+ className="absolute truncate border border-[var(--color-border-default)] px-1 text-[10px] leading-3 text-[var(--color-text-tertiary)]"
+ style={box(node)}
+ title={`${d.name}: ${node.value}`}
+ >
+ {d.name}
+ </div>
+ );
+ }
+ const wide = node.x1 - node.x0 > 14 && node.y1 - node.y0 > 6;
+ const tall = wide && node.y1 - node.y0 > 12;
+ return (
+ <div
+ key={`l${i}`}
+ data-treemap-cell=""
+ className="absolute overflow-hidden px-1 text-[10px] leading-3 text-[var(--color-text-primary)]"
+ // A card-coloured halo keeps the label readable on any fill.
+ style={{ ...box(node), background: d.color, textShadow: HALO }}
+ title={`${d.path}: ${d.size}${d.tone ? `, ${d.tone}` : ""}`}
+ >
+ {wide ? short(d.name, 24) : null}
+ {tall && d.tone ? <span className="block">{d.tone}</span> : null}
+ </div>
+ );
+ })}
+ </div>
+ );
+}
+
function PartFrame({
part,
domId,
@@ -436,8 +820,9 @@ function ChartPart({ view, buildRefHref, domId }: PartProps & { view: ChartView
return (
<PartFrame part={view} domId={domId}>
<ChartLegend view={view} />
- {/* The chart is a picture of the table below; the summary is its text. */}
- <div aria-hidden>
+ {/* The chart is a picture of the table below; the summary is its text. A
+ heatmap is a table itself, with its values in its cells. */}
+ <div aria-hidden={view.chart_type === "heatmap" ? undefined : true}>
<ChartPlot view={view} />
</div>
<button
diff --git a/packages/ui/styles/globals.css b/packages/ui/styles/globals.css
index 6cb6cf0a0..995f534a8 100644
--- a/packages/ui/styles/globals.css
+++ b/packages/ui/styles/globals.css
@@ -134,6 +134,15 @@
--color-share-4: color-mix(in srgb, var(--color-text-primary) 54%, var(--color-bg-inset));
--color-share-5: color-mix(in srgb, var(--color-text-primary) 47%, var(--color-bg-inset));
--color-share-tail: color-mix(in srgb, var(--color-text-primary) 20%, var(--color-bg-inset));
+ /* Heat steps — a heatmap cell's fill, light to dark: ink stepped into the
+ card. Steps 1-3 carry ink text, 4-5 card-coloured text; each pairing
+ clears 4.5:1 in both themes (contrast-check.py). Per theme for the same
+ reason as the share steps. */
+ --color-heat-1: color-mix(in srgb, var(--color-text-primary) 6%, var(--color-bg-surface));
+ --color-heat-2: color-mix(in srgb, var(--color-text-primary) 14%, var(--color-bg-surface));
+ --color-heat-3: color-mix(in srgb, var(--color-text-primary) 26%, var(--color-bg-surface));
+ --color-heat-4: color-mix(in srgb, var(--color-text-primary) 62%, var(--color-bg-surface));
+ --color-heat-5: color-mix(in srgb, var(--color-text-primary) 82%, var(--color-bg-surface));
/* Supporting cast beside an accent series. Same idea, no hue. */
--color-neutral-1: color-mix(in srgb, var(--color-text-tertiary) 62%, var(--color-bg-inset));
--color-neutral-2: color-mix(in srgb, var(--color-text-tertiary) 40%, var(--color-bg-inset));
@@ -509,6 +518,11 @@
--color-share-4: color-mix(in srgb, var(--color-text-primary) 48%, var(--color-bg-inset));
--color-share-5: color-mix(in srgb, var(--color-text-primary) 40%, var(--color-bg-inset));
--color-share-tail: color-mix(in srgb, var(--color-text-primary) 18%, var(--color-bg-inset));
+ --color-heat-1: color-mix(in srgb, var(--color-text-primary) 6%, var(--color-bg-surface));
+ --color-heat-2: color-mix(in srgb, var(--color-text-primary) 14%, var(--color-bg-surface));
+ --color-heat-3: color-mix(in srgb, var(--color-text-primary) 26%, var(--color-bg-surface));
+ --color-heat-4: color-mix(in srgb, var(--color-text-primary) 62%, var(--color-bg-surface));
+ --color-heat-5: color-mix(in srgb, var(--color-text-primary) 82%, var(--color-bg-surface));
--color-neutral-1: color-mix(in srgb, var(--color-text-tertiary) 70%, var(--color-bg-inset));
--color-neutral-2: color-mix(in srgb, var(--color-text-tertiary) 45%, var(--color-bg-inset));
--color-neutral-3: color-mix(in srgb, var(--color-text-tertiary) 26%, var(--color-bg-inset));
diff --git a/packages/web/src/lib/chat/to-chat-ui-messages.ts b/packages/web/src/lib/chat/to-chat-ui-messages.ts
index 476c0fee8..9aa582f1d 100644
--- a/packages/web/src/lib/chat/to-chat-ui-messages.ts
+++ b/packages/web/src/lib/chat/to-chat-ui-messages.ts
@@ -2,7 +2,7 @@ import type { ChatMessageResponse } from "@/lib/api/types";
import type { ChatUIMessage } from "@repowise-dev/types/chat";
import { getLegacyChatArtifactType } from "@repowise-dev/ui/chat";
import { parseEvidenceCards } from "@repowise-dev/api-client/cards";
-import { SHOW_VIEW_TOOL, parseViewParts } from "@repowise-dev/api-client/views";
+import { VIEW_TOOLS, parseViewParts } from "@repowise-dev/api-client/views";
/** Stored cards are untrusted wire data; only the ones that validate render. */
function storedCards(message: ChatMessageResponse): Pick<ChatUIMessage, "cards"> {
@@ -42,8 +42,8 @@ export function toChatUiMessages(
arguments: toolCall.arguments ?? {},
result: toolCall.result,
summary: toolCall.summary,
- // A show_view receipt is not evidence; the view itself renders inline.
- ...(toolCall.name === SHOW_VIEW_TOOL
+ // A view tool's receipt is not evidence; the view itself renders inline.
+ ...(VIEW_TOOLS.has(toolCall.name)
? {}
: toolCall.artifact
? { artifact: toolCall.artifact }
diff --git a/packages/web/src/lib/hooks/use-chat.ts b/packages/web/src/lib/hooks/use-chat.ts
index a2e8cc823..b332304e5 100644
--- a/packages/web/src/lib/hooks/use-chat.ts
+++ b/packages/web/src/lib/hooks/use-chat.ts
@@ -9,7 +9,7 @@ import type {
ChatUIToolCall as ChatToolCall,
ChatUIMessage as ChatMessage,
} from "@repowise-dev/types/chat";
-import { SHOW_VIEW_TOOL, parseViewParts } from "@repowise-dev/api-client/views";
+import { VIEW_TOOLS, parseViewParts } from "@repowise-dev/api-client/views";
import { toFriendlyMessage } from "@repowise-dev/ui/lib/errors";
import { toChatUiMessages } from "@/lib/chat/to-chat-ui-messages";
@@ -274,8 +274,8 @@ export function useChat(repoId: string) {
...tc,
result: data,
summary: ev.summary,
- // A show_view receipt is not evidence; the view itself renders inline.
- ...(ev.tool_name === SHOW_VIEW_TOOL ? {} : { artifact: ev.artifact }),
+ // A view tool's receipt is not evidence; the view itself renders inline.
+ ...(VIEW_TOOLS.has(ev.tool_name) ? {} : { artifact: ev.artifact }),
status: failed ? ("error" as const) : ("done" as const),
}
: tc,
diff --git a/tests/unit/server/mcp/test_chat_datasets.py b/tests/unit/server/mcp/test_chat_datasets.py
new file mode 100644
index 000000000..646b34e01
--- /dev/null
+++ b/tests/unit/server/mcp/test_chat_datasets.py
@@ -0,0 +1,353 @@
+"""Chart datasets read off a fixture index, and the chat-only ``chart`` tool over them."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import UTC, datetime
+
+import pytest
+
+from repowise.core.persistence.models import (
+ Change,
+ CoverageFile,
+ HealthFileMetric,
+ HealthSnapshot,
+ KnowledgeGraphLayer,
+)
+from repowise.server import chat_datasets
+from repowise.server.chat_chart import chart_schema, run_chart
+from repowise.server.chat_datasets.files import directories, unique_suffixes
+from repowise.server.chat_views import _ATTRIBUTION, _PERSON, _RISK_SCORE, TurnViews
+from repowise.server.schemas.views import ViewPartList
+
+
[email protected](autouse=True)
+def _fresh_cache():
+ chat_datasets.clear_cache()
+ yield
+ chat_datasets.clear_cache()
+
+
+async def chart_index(session, setup_mcp, health_data: str) -> str:
+ rid = health_data
+ session.add(
+ CoverageFile(
+ repository_id=rid,
+ file_path="src/auth/service.py",
+ source_format="lcov",
+ line_coverage_pct=50.0,
+ total_coverable_lines=100,
+ covered_line_count=50,
+ )
+ )
+ session.add(
+ CoverageFile(
+ repository_id=rid,
+ file_path="src/db/models.py",
+ source_format="lcov",
+ line_coverage_pct=100.0,
+ total_coverable_lines=300,
+ covered_line_count=300,
+ )
+ )
+ for i, (day, category) in enumerate([(5, "fix"), (6, "fix"), (14, "feature")]):
+ session.add(
+ Change(
+ repository_id=rid,
+ change_id=f"c{i}",
+ identity_kind="sha",
+ identity_value=f"{i:040d}",
+ shape="commit",
+ head_sha=f"{i:040d}",
+ merged_at=datetime(2026, 10, day, 12, tzinfo=UTC),
+ category=category,
+ files_changed=i + 1,
+ )
+ )
+ for taken_at, average in [(datetime(2026, 10, 1), 7.5), (datetime(2026, 10, 8), 7.9)]:
+ session.add(
+ HealthSnapshot(
+ id=uuid.uuid4().hex,
+ repository_id=rid,
+ taken_at=taken_at,
+ average_health=average,
+ hotspot_health=6.0,
+ )
+ )
+ session.add(
+ KnowledgeGraphLayer(
+ repository_id=rid,
+ layer_id="layer:service",
+ name="Service",
+ node_ids_json=json.dumps(["file:src/auth/service.py", "file:src/db/models.py"]),
+ display_order=0,
+ )
+ )
+ await session.commit()
+ return rid
+
+
+async def _rows(name: str) -> list[dict]:
+ return (await chat_datasets.load_rows(name, None)).rows
+
+
+# ---------------------------------------------------------------------------
+# Datasets
+# ---------------------------------------------------------------------------
+
+
+async def test_files_join_health_git_and_coverage(chart_index):
+ files = {r["path"]: r for r in await _rows("files")}
+ auth = files["src/auth/service.py"]
+ assert auth["health_score"] == 4.5 and auth["health_band"] == "needs work"
+ assert auth["commits_90d"] == 8 and auth["package"] == "auth"
+ assert auth["coverage_pct"] == 50.0 and auth["coverable_lines"] == 100
+ assert files["src/db/models.py"]["health_band"] == "excellent"
+
+
+async def test_rows_are_cached_per_index_state(chart_index):
+ first = await chat_datasets.load_rows("files", None)
+ second = await chat_datasets.load_rows("files", None)
+ assert not first.cached and second.cached
+ assert second.rows is first.rows
+
+
+async def test_findings_dead_code_coverage_history_and_layers(chart_index):
+ findings = await _rows("findings")
+ assert {f["kind"] for f in findings} >= {"complex_method", "io_in_loop"}
+ assert {f["package"] for f in findings} == {"auth"}
+ dead = {d["path"]: d for d in await _rows("dead_code")}
+ assert dead["src/legacy/old_auth.py"]["tier"] == "high"
+ coverage = await _rows("coverage")
+ assert sum(c["covered_lines"] for c in coverage) == 350
+ changes = await _rows("changes")
+ assert [c["week"] for c in changes] == ["2026-10-05", "2026-10-05", "2026-10-12"]
+ assert [t["average_health"] for t in await _rows("health_trend")] == [7.5, 7.9]
+ assert await _rows("layers") == [{"layer": "Service", "files": 2, "order": 1}]
+
+
+def test_no_dataset_field_names_a_person_a_risk_score_or_attribution():
+ for name in chat_datasets.dataset_names():
+ for key in chat_datasets.get_dataset(name).fields:
+ assert not _PERSON.search(key), (name, key)
+ assert not _RISK_SCORE.search(key), (name, key)
+ assert not _ATTRIBUTION.search(key), (name, key)
+
+
+def test_labels_are_the_shortest_unique_suffix():
+ labels = unique_suffixes(["a/update_cmd/command.py", "a/init_cmd/command.py", "b/x.py"])
+ assert labels == {
+ "a/update_cmd/command.py": "update_cmd/command.py",
+ "a/init_cmd/command.py": "init_cmd/command.py",
+ "b/x.py": "x.py",
+ }
+
+
+def test_directories_look_past_wrapper_levels():
+ packages = {
+ **{f"packages/core/src/repowise/core/{d}/f{i}.py": "packages/core" for d in ("a", "b") for i in range(5)},
+ "packages/core/alembic/env.py": "packages/core",
+ "README.md": "(root)",
+ }
+ dirs = directories(packages)
+ assert dirs["packages/core/src/repowise/core/a/f0.py"] == "packages/core/src/repowise/core/a"
+ assert dirs["packages/core/alembic/env.py"] == "packages/core/alembic"
+ assert dirs["README.md"] == "(root)"
+
+
+# ---------------------------------------------------------------------------
+# The chart tool
+# ---------------------------------------------------------------------------
+
+
+async def test_chart_draws_a_dataset_in_one_call_with_exact_figures(chart_index):
+ views = TurnViews()
+ receipt = await run_chart({"dataset": "files", "x": "health_band", "kind": "donut"}, None, views)
+ assert receipt["chart_type"] == "donut" and receipt["view_id"] == "v1"
+ assert receipt["figures"]["total"] == 2
+ assert {s["pct"] for s in receipt["figures"]["shares"]} == {50.0}
+ part = views.parts[0]
+ assert part["source"]["tool_name"] == "chart"
+ ViewPartList.model_validate(views.parts)
+
+
+async def test_chart_weights_coverage_by_coverable_lines(chart_index):
+ views = TurnViews()
+ receipt = await run_chart(
+ {"dataset": "coverage", "x": "package", "y": "coverage_pct", "aggregate": "avg"}, None, views
+ )
+ # (50 * 100 + 100 * 300) / 400: the line-weighted share, not the mean of 50 and 100.
+ assert receipt["figures"]["overall"] == {"Average coverage pct": 87.5}
+ assert "weighted by coverable_lines" in receipt["notes"][0]
+ plain = await run_chart(
+ {"dataset": "coverage", "x": "package", "y": "coverage_pct", "aggregate": "avg", "weight": "none"},
+ None,
+ views,
+ )
+ assert plain["figures"]["overall"] == {"Average coverage pct": 75.0}
+
+
+async def test_chart_counts_changes_by_week_and_category_as_a_heatmap(chart_index):
+ views = TurnViews()
+ receipt = await run_chart(
+ {"dataset": "changes", "x": "week", "series": "category", "kind": "heatmap"}, None, views
+ )
+ assert receipt["chart_type"] == "heatmap"
+ rows = views.parts[0]["data"]["rows"]
+ assert rows == [{"week": "2026-10-05", "s1": 2, "s2": 0}, {"week": "2026-10-12", "s1": 0, "s2": 1}]
+
+
+async def test_chart_errors_carry_a_spec_that_draws(chart_index):
+ views = TurnViews()
+ result = await run_chart({"dataset": "files", "x": "healthiness", "y": "nloc"}, None, views)
+ assert result["error_code"] == "bad_spec"
+ suggested = result["suggested_spec"]
+ assert suggested["dataset"] == "files"
+ assert "error" not in await run_chart(suggested, None, views)
+
+
+async def test_chart_refuses_people_and_unknown_datasets(chart_index):
+ views = TurnViews()
+ people = await run_chart({"dataset": "files", "x": "primary_owner"}, None, views)
+ assert people["error_code"] in ("person_grouping", "bad_spec")
+ assert views.parts == []
+ unknown = await run_chart({"dataset": "owners", "x": "a"}, None, views)
+ assert unknown["error_code"] == "unknown_dataset"
+
+
+async def test_chart_with_only_a_dataset_describes_its_fields(chart_index):
+ found = await run_chart({"dataset": "files"}, None, TurnViews())
+ (entry,) = found["datasets"]
+ assert "health_score" in entry["fields"] and entry["example"]
+
+
+def test_the_schema_lists_every_dataset_and_its_fields():
+ schema = chart_schema()["function"]
+ assert schema["parameters"]["properties"]["dataset"]["enum"] == chat_datasets.dataset_names()
+ assert "files: path, file, package" in schema["description"]
+
+
+# ---------------------------------------------------------------------------
+# Parity, weeks, freshness and the cache
+# ---------------------------------------------------------------------------
+
+
+async def test_the_repo_average_health_is_get_healths(chart_index, session):
+ from repowise.core.analysis.health.scoring import nloc_weighted_score
+ from repowise.core.persistence.crud import get_health_metrics
+ from repowise.server.mcp_server import get_health
+
+ # A file with no lines still weighs 1, as nloc_weighted_score floors it.
+ await session.execute(
+ HealthFileMetric.__table__.update()
+ .where(HealthFileMetric.file_path == "src/db/models.py")
+ .values(nloc=0)
+ )
+ await session.commit()
+ receipt = await run_chart(
+ {"dataset": "files", "x": "package", "y": "health_score", "aggregate": "avg"},
+ None,
+ TurnViews(),
+ )
+ overall = receipt["figures"]["overall"]["Average health score"]
+ metrics = await get_health_metrics(session, chart_index)
+ assert overall == round(nloc_weighted_score(metrics), 2)
+ assert overall == (await get_health(only=["kpis"]))["kpis"]["average_health"]
+
+
+async def test_empty_weeks_count_zero(chart_index, session):
+ session.add(
+ Change(
+ repository_id=chart_index,
+ change_id="late",
+ identity_kind="sha",
+ identity_value="9" * 40,
+ shape="commit",
+ head_sha="9" * 40,
+ merged_at=datetime(2026, 10, 27, 12, tzinfo=UTC),
+ category="fix",
+ )
+ )
+ await session.commit()
+ views = TurnViews()
+ await run_chart({"dataset": "changes", "x": "week"}, None, views)
+ rows = views.parts[0]["data"]["rows"]
+ assert [(r["week"], r["count"]) for r in rows] == [
+ ("2026-10-05", 2),
+ ("2026-10-12", 1),
+ ("2026-10-19", 0),
+ ("2026-10-26", 1),
+ ]
+
+
+async def test_freshness_is_read_on_every_call(chart_index, monkeypatch):
+ import repowise.server.mcp_server._meta as meta_mod
+
+ await chat_datasets.load_rows("files", None)
+ monkeypatch.setattr(
+ meta_mod, "build_meta", lambda **_: {"indexed_commit": "abc1234", "stale_warning": "behind"}
+ )
+ again = await chat_datasets.load_rows("files", None)
+ assert again.cached and again.stale and again.as_of == "abc1234"
+
+
+def test_the_cache_drops_a_repos_older_state_and_evicts_the_oldest(monkeypatch):
+ from repowise.server.chat_datasets import _cache, _store
+
+ monkeypatch.setattr(chat_datasets, "_CACHE_LIMIT", 3)
+ _store(("r1", "s1", "files"), [])
+ _store(("r2", "s1", "files"), [])
+ _store(("r1", "s2", "files"), [])
+ # r1's first state is gone; r2 keeps its own.
+ assert list(_cache) == [("r2", "s1", "files"), ("r1", "s2", "files")]
+ _store(("r3", "s1", "files"), [])
+ _store(("r4", "s1", "files"), [])
+ assert list(_cache) == [("r1", "s2", "files"), ("r3", "s1", "files"), ("r4", "s1", "files")]
+
+
+def probe_dataset():
+ calls: list[int] = []
+ state = {"fail": False}
+
+ async def load(ctx):
+ import asyncio
+
+ calls.append(1)
+ await asyncio.sleep(0.01)
+ if state["fail"]:
+ raise RuntimeError("index unreadable")
+ return [{"k": "a"}]
+
+ chat_datasets.register_dataset(
+ "probe",
+ description="test",
+ fields={"k": chat_datasets.DatasetField("text", "a key")},
+ basis=("inferred", "test"),
+ example={"x": "k"},
+ )(load)
+ yield calls, state
+ chat_datasets.datasets._impls.pop("probe")
+
+
+async def test_concurrent_loads_read_once(chart_index, probe_dataset):
+ import asyncio
+
+ calls, _ = probe_dataset
+ results = await asyncio.gather(*(chat_datasets.load_rows("probe", None) for _ in range(5)))
+ assert len(calls) == 1
+ assert all(r.rows == [{"k": "a"}] for r in results)
+ assert chat_datasets._locks == {}
+
+
+async def test_a_failed_load_is_not_cached_and_the_tool_says_so(chart_index, probe_dataset):
+ calls, state = probe_dataset
+ state["fail"] = True
+ result = await run_chart({"dataset": "probe", "x": "k"}, None, TurnViews())
+ assert result["error_code"] == "tool_failed" and "index unreadable" in result["error"]
+ assert chat_datasets._locks == {}
+ state["fail"] = False
+ assert "error" not in await run_chart({"dataset": "probe", "x": "k"}, None, TurnViews())
+ assert len(calls) == 2
diff --git a/tests/unit/server/test_chat_session.py b/tests/unit/server/test_chat_session.py
index 8774f9017..5ee8110f6 100644
--- a/tests/unit/server/test_chat_session.py
+++ b/tests/unit/server/test_chat_session.py
@@ -817,6 +817,79 @@ async def test_find_suspects_is_offered_on_the_local_backend_and_runs(store, mon
assert SUSPECTS_TOOL not in narrow.calls[0]["tools"]
+# ---------------------------------------------------------------------------
+# chart: chat-only, local backend, one call to a stored view
+# ---------------------------------------------------------------------------
+
+
+class _FakeLocal:
+ """A local backend over FakeTools; built lazily so the import stays in the test."""
+
+ @staticmethod
+ def make():
+ from repowise.server.chat_tools import LocalToolBackend
+
+ class FakeLocal(LocalToolBackend):
+ def __init__(self) -> None:
+ super().__init__("/tmp/demo", repo_alias="demo")
+ self.inner = FakeTools()
+
+ def catalog_for(self, policy, principal):
+ return self.inner.catalog_for(policy, principal)
+
+ async def execute(self, name, arguments):
+ return await self.inner.execute(name, arguments)
+
+ return FakeLocal()
+
+
+async def test_chart_draws_a_dataset_and_the_next_turn_redraws_it(store, monkeypatch):
+ import repowise.server.chat_chart as chat_chart_mod
+ from repowise.server.chat_datasets import DatasetRows
+ from repowise.server.chat_references import CHART_TOOL
+
+ rows = [{"health_band": band} for band in ("good", "good", "fair")]
+
+ async def fake_rows(name, repo):
+ assert (name, repo) == ("files", "demo")
+ return DatasetRows(rows=rows, as_of="4c1e31fe3a9b", stale=False)
+
+ monkeypatch.setattr(chat_chart_mod, "load_rows", fake_rows)
+ spec = {"dataset": "files", "x": "health_band", "kind": "pie"}
+ provider = ScriptedProvider([[_tool("t1", CHART_TOOL, spec)], [_text("two thirds are good")]])
+ session = await _open(store, provider, tools=_FakeLocal.make())
+ events = await _collect(session.stream("health bands as a donut"))
+
+ assert CHART_TOOL in provider.calls[0]["tools"]
+ view = next(e for e in events if e["type"] == "view")["view"]
+ assert view["chart_type"] == "donut" and view["source"]["tool_name"] == CHART_TOOL
+ receipt = json.loads(provider.calls[1]["messages"][-1]["content"])
+ assert receipt["figures"]["total"] == 3 and "kind 'pie' read as 'donut'" in receipt["notes"]
+ stored = (await store.messages(session.id))[-1].content
+ assert [v["chart_type"] for v in stored["views"]] == ["donut"]
+
+ redraw = {"artifact_id": "v1", "view": "chart", "options": {"kind": "table"}}
+ again = ScriptedProvider([[_tool("t2", SHOW_VIEW_TOOL, redraw)], [_text("as a table")]])
+ result = await (
+ await _open(store, again, tools=_FakeLocal.make(), conversation_id=session.id)
+ ).send("show that as a table")
+ assert [v["kind"] for v in result.views] == ["table"]
+ assert result.views[0]["rows"] == view["data"]["rows"]
+
+
+async def test_chart_is_offered_only_on_the_local_backend(store):
+ from repowise.server.chat_references import CHART_TOOL
+
+ remote = ScriptedProvider([[_text("x")]])
+ await (await _open(store, remote)).send("q")
+ assert CHART_TOOL not in remote.calls[0]["tools"]
+
+ narrow = ScriptedProvider([[_text("x")]])
+ policy = SessionPolicy(tool_allowlist=frozenset({"get_risk", SHOW_VIEW_TOOL}))
+ await (await _open(store, narrow, tools=_FakeLocal.make(), policy=policy)).send("q")
+ assert CHART_TOOL not in narrow.calls[0]["tools"]
+
+
# ---------------------------------------------------------------------------
# show_view references across the conversation
# ---------------------------------------------------------------------------
diff --git a/tests/unit/server/test_chat_view_spec.py b/tests/unit/server/test_chat_spec.py
similarity index 57%
rename from tests/unit/server/test_chat_view_spec.py
rename to tests/unit/server/test_chat_spec.py
index ee0e0f989..8d5351d4e 100644
--- a/tests/unit/server/test_chat_view_spec.py
+++ b/tests/unit/server/test_chat_spec.py
@@ -1,4 +1,4 @@
-"""The ``chart`` view spec: parsing, field checks, filters, grouping, top + Other and the kind choice."""
+"""The chart spec: parsing, field checks, filters, grouping, top + Other and the kind choice."""
from __future__ import annotations
@@ -6,12 +6,12 @@ from typing import Any
import pytest
-from repowise.server.chat_view_spec import (
+from repowise.server.chat_spec import (
OTHER_LABEL,
SpecError,
- check_fields,
default_title,
field_types,
+ fit,
parse_spec,
transform,
)
@@ -31,8 +31,7 @@ SIX = [*FINDINGS, {"file_path": "f.ts", "kind": "unused_export", "lines": 1, "co
def _run(rows: list[dict[str, Any]] = FINDINGS, **options: Any):
spec = parse_spec(options)
types = field_types(rows)
- check_fields(spec, types)
- return transform(spec, rows, types)
+ return transform(fit(spec, rows, types), rows, types)
def _column(result, key: str) -> list:
@@ -72,18 +71,14 @@ def test_an_unknown_field_suggests_close_matches_and_lists_the_fields():
({"x": "kind", "group_by": "seen"}, "same axis"),
({"x": "kind", "y": "kind"}, "x cannot also be a y field"),
({"x": "kind", "y": "lines", "aggregate": "median"}, "not one of"),
- ({"x": "kind", "y": "lines", "aggregate": "count"}, "drop y"),
({"x": "kind", "aggregate": "sum"}, "needs y"),
- ({"x": "kind", "y": "lines", "group_by": "kind"}, "group_by needs aggregate"),
({"x": "kind", "y": ["lines", "confidence"], "series": "seen"}, "y takes one field"),
({"x": "kind", "filter": [{"field": "lines", "op": "between", "value": 1}]}, "op 'between'"),
({"x": "kind", "filter": [{"field": "kind", "op": "in", "value": "a"}]}, "non-empty list"),
({"x": "kind", "filter": [{"field": "lines", "op": "gt", "value": True}]}, "number or text"),
({"x": "kind", "top": 0}, "top must be"),
- ({"x": "kind", "top": 100, "other": True}, "from 1 to 99"),
- ({"x": "kind", "other": True}, "needs top"),
- ({"x": "kind", "y": "lines", "aggregate": "avg", "top": 2, "other": True}, "count or sum"),
- ({"x": "kind", "kind": "pie"}, "kind 'pie'"),
+ ({"x": "kind", "kind": "radar"}, "kind 'radar'"),
+ ({"x": "kind", "other": "maybe"}, "other must be"),
({"x": "kind", "sort": {"field": "kind", "order": "up"}}, "asc"),
({"x": "kind", "title": ""}, "title must be text"),
],
@@ -97,8 +92,7 @@ def test_a_malformed_spec_says_what_to_change(options, message):
@pytest.mark.parametrize(
("options", "message"),
[
- ({"x": "kind", "y": "file_path", "aggregate": "sum"}, "y fields must be numeric"),
- ({"x": "kind", "y": "lines", "kind": "scatter"}, "scatter needs a numeric x"),
+ ({"x": "kind", "y": "file_path", "aggregate": "sum"}, "it must be numeric"),
({"x": "kind", "sort": {"field": "lines"}}, "must be one of ['kind', 'count']"),
({"x": "kind", "filter": [{"field": "owner", "value": 1}]}, "filter field 'owner'"),
],
@@ -129,7 +123,6 @@ def test_a_spec_that_does_not_fit_the_rows_is_refused(options, message):
({"field": "seen", "op": "gte", "value": "2026-03-09"}, 3),
# A null and a type mismatch never pass an ordering filter.
({"field": "confidence", "op": "lt", "value": 1}, 4),
- ({"field": "lines", "op": "gt", "value": "3"}, 0),
],
)
def test_each_filter_op(flt, kept):
@@ -178,21 +171,30 @@ def test_series_splits_a_count_into_one_column_per_value():
assert _column(result, "seen") == ["2026-03-02", "2026-03-09", "2026-03-16"]
-def test_too_many_series_values_is_refused():
- rows = [{"x": "a", "s": f"v{i}"} for i in range(9)]
+def test_too_many_series_values_fold_the_smallest_into_other():
+ rows = [{"x": "a", "s": f"v{i}"} for i in range(9)] + [{"x": "a", "s": "v0"}]
+ result = _run(rows, x="x", series="s")
+ assert len(result.series) == 8
+ assert result.columns[-1][1] == OTHER_LABEL
+ assert result.rows[0]["s8"] == 2 and result.rows[0]["s1"] == 2
+ assert any("added up as Other" in n for n in result.notes)
+ # An average cannot fold, so it is still refused.
+ many = [{"x": "a", "s": f"v{i}", "v": i} for i in range(9)]
with pytest.raises(SpecError, match="at most 8"):
- _run(rows, x="x", series="s")
+ _run(many, x="x", y="v", series="s", aggregate="avg")
-def test_unaggregated_series_with_repeats_asks_for_an_aggregate():
+def test_unaggregated_series_with_repeats_is_summed_and_said():
rows = [{"x": "a", "s": "p", "v": 1}, {"x": "a", "s": "p", "v": 2}]
- with pytest.raises(SpecError, match="add aggregate"):
- _run(rows, x="x", y="v", series="s")
+ result = _run(rows, x="x", y="v", series="s")
+ assert result.rows == [{"x": "a", "s1": 3}]
+ assert any("combined by sum" in n for n in result.notes)
-def test_a_repeated_x_without_aggregate_asks_for_one_outside_a_scatter():
- with pytest.raises(SpecError, match="x 'kind' repeats"):
- _run(x="kind", y="lines")
+def test_a_repeated_x_without_aggregate_is_combined_outside_a_scatter():
+ result = _run(x="kind", y="lines")
+ assert _column(result, "lines") == [120, 21, 0]
+ assert any("combined by sum" in n for n in result.notes)
# Points of a scatter may share an x.
rows = [{"a": 1, "b": 2}, {"a": 1, "b": 3}]
assert len(_run(rows, x="a", y="b").rows) == 2
@@ -302,15 +304,148 @@ def test_a_scatter_keeps_one_row_per_point_with_its_label():
@pytest.mark.parametrize(
- ("options", "message"),
+ ("options", "drawn", "note"),
+ [
+ ({"x": "kind", "kind": "stacked_bar"}, "bar", "pass series"),
+ ({"x": "kind", "y": "lines", "aggregate": "avg", "kind": "donut"}, "bar", "does not add up"),
+ ({"x": "kind", "y": "lines", "kind": "scatter"}, "bar", "numeric x"),
+ ({"x": "kind", "kind": "line"}, "line", "no order"),
+ ],
+)
+def test_an_asked_kind_the_data_cannot_take_draws_the_nearest_and_says_why(options, drawn, note):
+ result = _run(SIX, **options)
+ assert result.chart_type == drawn
+ assert note in result.kind_note
+
+
+ "kind",
+ ["bar", "horizontal_bar", "line", "area", "donut", "scatter", "treemap", "heatmap", "table"],
+)
+def test_every_asked_kind_is_drawn_when_the_data_fits(kind):
+ rows = [{"k": f"k{i}", "n": i + 1, "m": 2 * i, "t": f"2026-03-{i + 1:02d}"} for i in range(4)]
+ options = {
+ "scatter": {"x": "n", "y": "m"},
+ "line": {"x": "t", "y": "n"},
+ "area": {"x": "t", "y": "n"},
+ "heatmap": {"x": "k", "series": "t", "aggregate": "count"},
+ }.get(kind, {"x": "k", "y": "n", "aggregate": "sum"})
+ result = _run(rows, kind=kind, **options)
+ assert result.chart_type == kind and result.kind_note is None
+
+
+def test_stacked_bar_draws_when_series_splits_a_count():
+ assert _run(SIX, x="kind", series="seen", kind="stacked_bar").chart_type == "stacked_bar"
+
+
+def test_a_donut_folds_past_eight_parts_into_other():
+ rows = [{"k": f"k{i}"} for i in range(12) for _ in range(i + 1)]
+ result = _run(rows, x="k", kind="donut")
+ assert result.chart_type == "donut" and len(result.rows) == 8
+ assert result.rows[-1]["k"] == f"{OTHER_LABEL} (5 more)"
+ assert result.figures["total"] == sum(range(1, 13))
+ assert any("added up as Other" in n for n in result.notes)
+
+
+# ---------------------------------------------------------------------------
+# Repairs, composite x, weights, treemaps, figures
+# ---------------------------------------------------------------------------
+
+
+ ("options", "check"),
[
- ({"x": "file_path", "kind": "donut"}, "top: 4 with other: true"),
- ({"x": "kind", "kind": "stacked_bar"}, "pass series"),
+ ({"x": "kind", "kind": "pie"}, lambda r: r.chart_type == "donut"),
+ ({"x": "kind", "y": "lines", "aggregate": "count"}, lambda r: r.series == ["count"]),
+ ({"x": "kind", "top": 2, "other": "Other"}, lambda r: r.other),
+ ({"x": "kind", "other": True}, lambda r: r.other is False and len(r.rows) == 3),
+ ({"x": "file_path", "y": "lines", "top": 2, "other": True}, lambda r: r.other),
+ (
+ {"x": "kind", "y": "lines", "aggregate": "avg", "top": 2, "other": True},
+ lambda r: not r.other,
+ ),
+ ({"x": "kind", "aggregate": "mean", "y": "lines"}, lambda r: r.rows[0]["lines"] == 120.0),
+ ({"x": "kind", "top": "2"}, lambda r: len(r.rows) == 2),
+ ({"x": "kind", "top": 500}, lambda r: len(r.rows) == 3),
+ ({"x": "kind", "sort": "asc"}, lambda r: _column(r, "count") == [1, 1, 3]),
+ ({"x": "Kind"}, lambda r: r.x == "kind"),
+ ({"x": "kind", "y": "count"}, lambda r: r.series == ["count"]),
+ (
+ {"x": "kind", "filter": {"field": "lines", "op": "gt", "value": "7"}},
+ lambda r: r.matched == 2,
+ ),
],
)
-def test_an_asked_kind_the_data_cannot_take_is_refused_with_a_fix(options, message):
- with pytest.raises(SpecError, match=message):
- _run(SIX, **options)
+def test_obvious_slips_are_repaired(options, check):
+ assert check(_run(**options))
+
+
+def test_a_repair_is_reported():
+ assert _run(x="kind", kind="pie").notes == ["kind 'pie' read as 'donut'"]
+
+
+def test_a_bool_filter_value_written_as_text_matches_the_bool():
+ rows = [{"ok": True, "k": "a"}, {"ok": False, "k": "b"}]
+ assert _run(rows, x="k", filter=[{"field": "ok", "value": "true"}]).matched == 1
+
+
+def test_composite_x_joins_fields_with_an_arrow():
+ rows = [{"a": "core", "b": "web", "w": 3}, {"a": "cli", "b": "core", "w": 5}]
+ result = _run(rows, x=["a", "b"], y="w", sort={"field": "a_b", "order": "asc"})
+ assert _column(result, "a_b") == ["cli → core", "core → web"]
+ assert result.columns[0] == ("a_b", "A → B")
+
+
+class _Meta:
+ def __init__(self, aggregates, weight=None):
+ self.aggregates, self.weight = aggregates, weight
+
+
+def test_declared_weights_and_aggregates_shape_an_average():
+ rows = [{"pkg": "p", "cov": 100.0, "lines": 1}, {"pkg": "p", "cov": 0.0, "lines": 3}]
+ meta = {"cov": _Meta(("avg", "min", "max"), weight="lines"), "lines": _Meta(("sum",))}
+ types = field_types(rows)
+ spec = fit(parse_spec({"x": "pkg", "y": "cov", "aggregate": "sum"}), rows, types, meta)
+ result = transform(spec, rows, types)
+ # A sum of percentages is no measure: it is averaged, weighted by lines, and said.
+ assert result.rows == [{"pkg": "p", "cov": 25.0}]
+ assert result.figures["overall"] == {"Average cov": 25.0}
+ assert any("weighted by lines" in n for n in result.notes)
+
+
+def test_a_treemap_of_an_average_is_sized_by_its_weight_and_coloured_by_it():
+ rows = [{"d": "a", "s": 9.0, "n": 10}, {"d": "a", "s": 5.0, "n": 30}, {"d": "b", "s": 7.0, "n": 5}]
+ result = _run(rows, x="d", y="s", aggregate="avg", weight="n", kind="treemap")
+ assert result.chart_type == "treemap" and result.series == ["n"]
+ assert result.rows[0] == {"d": "a", "n": 40, "s": 6.0}
+ assert any("sized by n" in note for note in result.notes)
+
+
+def test_points_sort_by_a_field_they_do_not_plot():
+ result = _run(x="lines", y="confidence", sort={"field": "seen", "order": "desc"}, top=2)
+ assert _column(result, "file_path") == ["d.ts", "e.ts"]
+ assert all("__sort" not in row for row in result.rows)
+
+
+def test_a_treemap_nests_by_the_hierarchy_and_colours_by_a_field():
+ rows = [
+ {"package": "core", "directory": "core/a", "file": "x.py", "nloc": 10, "score": 9.0},
+ {"package": "core", "directory": "core/a", "file": "y.py", "nloc": 30, "score": 5.0},
+ {"package": "web", "directory": "web/src", "file": "z.ts", "nloc": 5, "score": 7.0},
+ ]
+ types = field_types(rows)
+ options = {"x": "directory", "y": "nloc", "aggregate": "sum", "kind": "treemap", "color": "score"}
+ spec = fit(parse_spec(options), rows, types, hierarchy=("package", "directory", "file"))
+ result = transform(spec, rows, types)
+ assert result.chart_type == "treemap" and result.groups == ["package"]
+ assert result.rows[0] == {"directory": "core/a", "nloc": 40, "package": "core", "score": 7.0}
+ assert ("score", "Average score") in result.columns
+
+
+def test_figures_carry_totals_and_shares_so_nobody_divides():
+ result = _run(x="kind")
+ assert result.figures["total"] == 5
+ assert result.figures["shares"][0] == {"x": "unused_export", "value": 3, "pct": 60.0}
def test_default_titles_name_the_measure_and_axes():
@@ -320,3 +455,17 @@ def test_default_titles_name_the_measure_and_axes():
== "Total lines by kind and seen"
)
assert default_title(parse_spec({"x": "lines", "y": "confidence"})) == "Confidence by lines"
+
+
+def test_a_time_series_receipt_previews_its_newest_rows_and_its_first():
+ rows = [{"day": f"2026-03-{i + 1:02d}", "v": i} for i in range(20)]
+ result = _run(rows, x="day", y="v")
+ assert result.figures["rows"][-1] == {"day": "2026-03-20", "v": 19}
+ assert result.figures["first_row"] == {"day": "2026-03-01", "v": 0}
+ assert result.figures["rows_note"] == "the newest 15 of 20 drawn rows"
+
+
+def test_a_donut_of_one_part_says_so():
+ result = _run([{"k": "a"}, {"k": "a"}], x="k", kind="donut")
+ assert result.chart_type == "bar"
+ assert "there is only 1 part" in result.kind_note
diff --git a/tests/unit/server/test_chat_views.py b/tests/unit/server/test_chat_views.py
index 6f7d6c710..482dc5ba6 100644
--- a/tests/unit/server/test_chat_views.py
+++ b/tests/unit/server/test_chat_views.py
@@ -113,6 +113,7 @@ def _artifact(data: dict, artifact_type: str, tool: str, basis: str = "inferred"
def _build(data: dict, artifact_type: str, tool: str, view: str, **options: Any) -> dict:
part = build_view(_artifact(data, artifact_type, tool), view, options, part_id="v1")
+ part.pop("receipt", None)
ViewPartList.model_validate([part])
kind = "TableView" if part["kind"] == "table" else "ChartView"
assert set(part) <= set(FIELDS[kind])
@@ -768,10 +769,37 @@ def test_chart_summary_says_when_the_tool_returned_only_part_of_a_list():
def test_chart_errors_list_the_fields_without_people():
- _, result = _show_chart(HEALTH, rows="high_leverage_files", x="max_cnn")
+ _, result = _show_chart(HEALTH, rows="high_leverage_files", x="max_ccnx_value")
assert result["error_code"] == "bad_spec"
assert "'max_ccn'" in result["error"]
assert result["fields"] == {"file_path": "text", "score": "number", "max_ccn": "number"}
+ # No near miss and no example: guessing a field would chart another measure.
+ assert "suggested_spec" not in result
+
+
+def test_a_suggestion_says_what_it_gave_up():
+ _, result = _show_chart(
+ HEALTH,
+ rows="high_leverage_files",
+ x="file_path",
+ y="score",
+ filter=[{"field": "max_ccn", "op": "gt", "value": 1000}],
+ )
+ assert result["error_code"] == "no_data"
+ assert result["suggested_spec"] == {"rows": "high_leverage_files", "x": "file_path", "y": "score"}
+ assert result["adjustments"] == ["filter dropped, so every row is charted"]
+
+
+def test_a_risk_score_is_refused_before_any_suggestion():
+ _, result = _show_chart(RISK, rows="global_hotspots", x="file_path", y="hotspot_scroe")
+ assert result["error_code"] == "risk_score_series"
+ assert "suggested_spec" not in result
+
+
+def test_a_near_miss_field_name_is_read_as_the_field_and_said():
+ _, result = _show_chart(HEALTH, rows="high_leverage_files", x="max_cnn", y="score")
+ assert "error" not in result
+ assert "field 'max_cnn' read as 'max_ccn'" in result["notes"]
@pytest.mark.parametrize(
@@ -815,3 +843,65 @@ def test_chart_series_split_is_still_risk_guarded_by_its_measure():
data = {"rows": [{"file_path": "a", "tier": "x", "risk_score": 1}]}
_, result = _show_chart(data, x="file_path", y="risk_score", series="tier", aggregate="sum")
assert result["error_code"] == "risk_score_series"
+
+
+# ---------------------------------------------------------------------------
+# Named views take a kind; maps chart; errors carry a fix
+# ---------------------------------------------------------------------------
+
+
+def _show(data: dict, artifact_type: str, tool: str, view: str, **options: Any) -> tuple[TurnViews, dict]:
+ turn = TurnViews()
+ stamped = turn.record(tool, {}, data, artifact_type=artifact_type)
+ return turn, turn.show({"artifact_id": stamped[ARTIFACT_ID_FIELD], "view": view, "options": options})
+
+
+ ("data", "artifact_type", "tool", "view"),
+ [
+ (HEALTH, "health", "get_health", "health.bands"),
+ (_overview_changes(), "overview", "get_overview", "changes.by_category"),
+ ],
+)
+def test_a_named_view_draws_as_a_donut_and_its_receipt_has_the_shares(data, artifact_type, tool, view):
+ turn, receipt = _show(data, artifact_type, tool, view, kind="donut")
+ assert receipt["chart_type"] == "donut" and turn.parts[0]["chart_type"] == "donut"
+ shares = receipt["figures"]["shares"]
+ assert sum(s["value"] for s in shares) == receipt["figures"]["total"]
+ ViewPartList.model_validate(turn.parts)
+
+
+def test_a_named_view_keeps_its_kind_when_the_asked_one_does_not_fit_and_says_so():
+ turn, receipt = _show(HEALTH, "health", "get_health", "health.bands", kind="scatter")
+ assert turn.parts[0]["chart_type"] == "bar"
+ assert "not scatter" in receipt["kind_note"]
+ _, table = _show(HEALTH, "health", "get_health", "health.trend", kind="table")
+ assert table["kind"] == "table"
+
+
+def test_a_map_of_numbers_charts_as_key_and_value_rows():
+ turn, receipt = _show_chart(
+ _overview_changes(), rows="changes.by_category", x="key", y="value", kind="donut"
+ )
+ assert receipt["chart_type"] == "donut"
+ assert turn.parts[0]["data"]["rows"] == [{"key": "feature", "value": 3}, {"key": "fix", "value": 1}]
+
+
+def test_table_columns_it_cannot_show_come_back_with_options_that_work():
+ _, result = _show(HEALTH, "health", "get_health", "table", path="high_leverage_files", columns=["file_path", "fix_count"])
+ assert result["error_code"] == "bad_arguments"
+ assert result["suggested_options"]["columns"] == ["file_path"]
+
+
+def test_a_view_of_this_conversation_redraws_as_another_kind():
+ turn, _ = _show(HEALTH, "health", "get_health", "health.bands")
+ redrawn = turn.show({"artifact_id": "v1", "view": "chart", "options": {"kind": "donut"}})
+ assert redrawn["chart_type"] == "donut" and redrawn["redrawn_from"] == "v1"
+ refused = turn.show({"artifact_id": "v1", "view": "chart", "options": {"kind": "scatter"}})
+ assert refused["error_code"] == "invalid_view"
+ assert "call chart" in refused["error"]
+
+
+def test_a_tool_with_no_declared_basis_names_itself_not_unresolved():
+ turn, _ = _show_chart({"rows": [{"k": "a"}, {"k": "b"}]}, x="k")
+ assert turn.parts[0]["basis"]["source"] == "get_health"
diff --git a/tests/unit/server/test_view_parts_contract.py b/tests/unit/server/test_view_parts_contract.py
index 4f1b8693e..8b9908eb0 100644
--- a/tests/unit/server/test_view_parts_contract.py
+++ b/tests/unit/server/test_view_parts_contract.py
@@ -59,6 +59,7 @@ def test_a_scatter_x_is_a_finite_number_as_typescript_checks(x: Any) -> None:
def test_the_vocabulary_and_limits_are_shared() -> None:
assert {
"schema_version": views.VIEW_SCHEMA_VERSION,
+ "schema_versions": list(views.VIEW_SCHEMA_VERSIONS),
"max_wire_number": evidence.MAX_WIRE_NUMBER,
"view_kinds": list(views.VIEW_KINDS),
"chart_types": list(views.CHART_TYPES),
diff --git a/tests/unit/test_no_hotspot_health_copies.py b/tests/unit/test_no_hotspot_health_copies.py
index c527b9572..a28a83131 100644
--- a/tests/unit/test_no_hotspot_health_copies.py
+++ b/tests/unit/test_no_hotspot_health_copies.py
@@ -60,7 +60,8 @@ _PLUMBING: dict[str, str] = {
"repowise/cli/commands/health_cmd/command.py": "prints the KPI dict it was handed",
"repowise/core/generation/editor_files/data.py": "the CodeHealthBlock field",
"repowise/server/routers/_repo_summary.py": "serves the latest snapshot column on /repos/summary",
- "repowise/server/chat_views.py": "charts the trend snapshots get_health already returned",
+ "repowise/server/chat_view_builders.py": "charts the trend snapshots get_health already returned",
+ "repowise/server/chat_datasets/history.py": "lists the snapshot scalars get_health trends read",
}