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.

fix(health): label six performance findings that showed raw ids (#4354)

Raghav Chamadiyaa95808663bbf
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.md
index 6fa141a46..57842e4d4 100644
--- a/docs/architecture/code-health.md
+++ b/docs/architecture/code-health.md
@@ -180,7 +180,7 @@ the defect weight (§6.1), "maint" the maintainability and "perf" the performanc
| `list_insert_zero_in_loop` | Performance | `list.insert(0, x)` in a loop | Medium; Python | perf 0.6 |
| `pd_concat_in_loop` | Performance | `pd.concat` accumulating in a loop | Medium; Python | perf 0.6 |
| `pandas_iterrows_in_loop` | Performance | `df.iterrows()` | Medium; Python | perf 0.6 |
-| `json_parse_in_loop` | Performance | JSON parse or stringify per iteration | Low; JavaScript, TypeScript | perf 0.4 |
+| `json_parse_in_loop` | Performance | A `JSON.parse(JSON.stringify(x))` deep clone per iteration | Low; JavaScript, TypeScript | perf 0.4 |
| `array_spread_in_reduce` | Performance | `[...acc]` inside `reduce` | Medium; JavaScript, TypeScript | perf 0.5 |
| `goroutine_in_unbounded_loop` | Performance | A goroutine per range element | Medium; Go | perf 0.4 |
diff --git a/packages/core/src/repowise/core/analysis/health/README.md b/packages/core/src/repowise/core/analysis/health/README.md
index 22c97bf9a..465740196 100644
--- a/packages/core/src/repowise/core/analysis/health/README.md
+++ b/packages/core/src/repowise/core/analysis/health/README.md
@@ -175,7 +175,9 @@ extension points.
- **New marker.** Drop a file under `biomarkers/`, implement
`Biomarker.detect(ctx) -> list[BiomarkerResult]`, register in
`biomarkers/registry.py`, add a suggestion in `suggestions.py`, add the
- category mapping in `scoring._BIOMARKER_CATEGORY`.
+ category mapping in `scoring._BIOMARKER_CATEGORY`. Add its label in
+ `biomarker_labels.py` (then run `scripts/generate_biomarker_labels.py`) and
+ its entry in the web glossary `packages/ui/src/health/biomarker-glossary.ts`.
- **New complexity language.** Add a `LanguageNodeMap` entry to
`complexity/languages.py`. No new `.scm` files needed.
- **New coverage format.** Drop a parser under `coverage/` and register it
diff --git a/packages/core/src/repowise/core/analysis/health/biomarker_labels.py b/packages/core/src/repowise/core/analysis/health/biomarker_labels.py
index 52281052e..11c3a8f36 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarker_labels.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarker_labels.py
@@ -57,6 +57,12 @@ BIOMARKER_LABELS: dict[str, str] = {
"hot_path_sync_io": "Blocking I/O on a hot path",
"blocking_io_under_lock": "Blocking I/O under a lock",
"nested_loop_quadratic": "Quadratic nested loop",
+ "list_insert_zero_in_loop": "Insert at list front in loop",
+ "pd_concat_in_loop": "Pandas concat in loop",
+ "pandas_iterrows_in_loop": "Row-by-row DataFrame loop",
+ "json_parse_in_loop": "JSON deep clone in loop",
+ "array_spread_in_reduce": "Accumulator spread in reduce",
+ "goroutine_in_unbounded_loop": "Unbounded goroutines in loop",
"sql_high_complexity": "Complex SQL routine",
"sql_select_star": "SELECT * in a view",
"sql_update_delete_without_where": "UPDATE/DELETE without WHERE",
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/json_parse_in_loop.py b/packages/core/src/repowise/core/analysis/health/biomarkers/json_parse_in_loop.py
index cb563b23f..2d2b442ec 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/json_parse_in_loop.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/json_parse_in_loop.py
@@ -1,11 +1,10 @@
-"""JSON-parse/stringify-in-loop — serialize/deserialize every iteration.
-
-``JSON.parse`` / ``JSON.stringify`` inside a loop re-serializes each pass; the
-``JSON.parse(JSON.stringify(x))`` deep-clone in a loop is the canonical waste
-(use ``structuredClone`` or hoist the parse). A ``performance`` dimension signal,
-shipped advisory: per-iteration parsing of *distinct* payloads is sometimes
-necessary work, so the centrality ranker downranks the cold sites. This detector
-lifts the hits into findings.
+"""JSON-deep-clone-in-loop: ``JSON.parse(JSON.stringify(x))`` every iteration.
+
+The round-trip clone serializes and re-parses the whole value each pass (use
+``structuredClone`` or clone once outside the loop). The TS/JS dialect fires only
+on that clone: a bare ``JSON.parse`` or ``JSON.stringify`` per iteration usually
+converts a distinct payload, which is necessary work. A ``performance`` dimension
+signal, shipped advisory. This detector lifts the hits into findings.
"""
from __future__ import annotations
@@ -34,8 +33,8 @@ class JsonParseInLoopDetector:
line_end=hit.line,
details=hit.loop_facts(),
reason=(
- "JSON.parse/stringify runs every loop iteration; hoist the "
- "serialization or use structuredClone for deep copies"
+ "a JSON.parse(JSON.stringify(...)) deep clone runs every loop "
+ "iteration; use structuredClone or clone once outside the loop"
),
)
)
diff --git a/packages/core/src/repowise/core/analysis/health/suggestions.py b/packages/core/src/repowise/core/analysis/health/suggestions.py
index 3b695d299..50597b526 100644
--- a/packages/core/src/repowise/core/analysis/health/suggestions.py
+++ b/packages/core/src/repowise/core/analysis/health/suggestions.py
@@ -250,8 +250,8 @@ _TEMPLATES: dict[str, str] = {
"iteration."
),
"json_parse_in_loop": (
- "Parse once. Hoist the parse or stringify out of the loop, and replace a "
- "JSON round-trip clone with structuredClone."
+ "Clone without the JSON round-trip. Use structuredClone, or clone once "
+ "outside the loop if every iteration copies the same value."
),
"membership_test_against_list_in_loop": (
"Look up in a set. Build a set from the list once before the loop and "
diff --git a/packages/ui/__tests__/health/biomarker-glossary.test.ts b/packages/ui/__tests__/health/biomarker-glossary.test.ts
index 84b2f1836..eed6d1eb4 100644
--- a/packages/ui/__tests__/health/biomarker-glossary.test.ts
+++ b/packages/ui/__tests__/health/biomarker-glossary.test.ts
@@ -13,7 +13,12 @@
*/
import { describe, expect, it } from "vitest";
-import { CATEGORY_CAP, biomarkerLabel, isKnownBiomarker } from "../../src/health/biomarker-glossary.js";
+import {
+ CATEGORY_CAP,
+ PERFORMANCE_HOME_BIOMARKERS,
+ biomarkerLabel,
+ isKnownBiomarker,
+} from "../../src/health/biomarker-glossary.js";
describe("CATEGORY_CAP parity", () => {
it("pins the performance cap to scoring.py's _PERFORMANCE_CATEGORY_CAPS", () => {
@@ -33,3 +38,10 @@ describe("isKnownBiomarker", () => {
expect(isKnownBiomarker("constructor")).toBe(false);
});
});
+
+describe("performance glossary", () => {
+ it("describes every performance biomarker", () => {
+ const missing = [...PERFORMANCE_HOME_BIOMARKERS].filter((name) => !isKnownBiomarker(name));
+ expect(missing).toEqual([]);
+ });
+});
diff --git a/packages/ui/src/health/biomarker-glossary.ts b/packages/ui/src/health/biomarker-glossary.ts
index 92c5943bb..057f523d5 100644
--- a/packages/ui/src/health/biomarker-glossary.ts
+++ b/packages/ui/src/health/biomarker-glossary.ts
@@ -344,6 +344,42 @@ export const BIOMARKER_GLOSSARY: Record<string, BiomarkerInfo> = {
description:
"A data-dependent loop nested inside another (O(n^2)) in a hot, central function. Advisory / informational — surfaced only where centrality ranking says it is worth a look; check the inner bound or use a set/map lookup if it is a search.",
},
+ list_insert_zero_in_loop: {
+ label: BIOMARKER_LABELS.list_insert_zero_in_loop,
+ category: "performance",
+ description:
+ "A Python .insert(0, x) call (a literal 0) inside a loop. On a list, each front insert shifts every element already in it, so the loop is O(n^2). Not flagged when the receiver is reassigned in the loop body or is assigned a deque in the file. A name match: the receiver is not proven to be a list. Use collections.deque.appendleft, or append and reverse once after the loop.",
+ },
+ pd_concat_in_loop: {
+ label: BIOMARKER_LABELS.pd_concat_in_loop,
+ category: "performance",
+ description:
+ "A pd.concat (or pandas.concat) call inside a loop. When the loop grows one frame this way, each call copies everything accumulated so far, which is O(n^2). Whether the result is accumulated is not checked. Collect the pieces in a list and call pd.concat once after the loop.",
+ },
+ pandas_iterrows_in_loop: {
+ label: BIOMARKER_LABELS.pandas_iterrows_in_loop,
+ category: "performance",
+ description:
+ "A for loop driven by df.iterrows() in a file that imports pandas. iterrows builds a new Series for every row, far slower than a vectorized column operation. Vectorize the work, or use itertuples() when row access is unavoidable. A name match: a non-pandas iterrows method in such a file is flagged too.",
+ },
+ json_parse_in_loop: {
+ label: BIOMARKER_LABELS.json_parse_in_loop,
+ category: "performance",
+ description:
+ "A JSON.parse(JSON.stringify(x)) deep clone inside a loop, which serializes and re-parses the whole value every iteration. Use structuredClone, or clone once outside the loop. A bare JSON.parse or JSON.stringify per iteration is not flagged, since each pass usually handles a different payload.",
+ },
+ array_spread_in_reduce: {
+ label: BIOMARKER_LABELS.array_spread_in_reduce,
+ category: "performance",
+ description:
+ "A .reduce call whose inline callback spreads its first parameter, the accumulator, into a new array or object literal ([...acc, x] or {...acc, k: v}). Every step copies everything gathered so far, so the fold is O(n^2). Push into the accumulator (or set the key) and return it.",
+ },
+ goroutine_in_unbounded_loop: {
+ label: BIOMARKER_LABELS.goroutine_in_unbounded_loop,
+ category: "performance",
+ description:
+ "A Go `go` statement directly inside a two-variable for k, v := range loop: one goroutine per element, with nothing bounding how many run at once. Not flagged in a single-variable range, a bare for {} or a condition loop, or when a send to a local buffered channel directly before the spawn, received inside the goroutine, bounds it. Use a worker pool, a semaphore channel or an errgroup with a limit.",
+ },
sql_high_complexity: {
label: BIOMARKER_LABELS.sql_high_complexity,
category: "sql",
diff --git a/packages/ui/src/health/generated/biomarker-labels.ts b/packages/ui/src/health/generated/biomarker-labels.ts
index 6db614e0e..488598c4d 100644
--- a/packages/ui/src/health/generated/biomarker-labels.ts
+++ b/packages/ui/src/health/generated/biomarker-labels.ts
@@ -51,6 +51,12 @@ export const BIOMARKER_LABELS = {
hot_path_sync_io: "Blocking I/O on a hot path",
blocking_io_under_lock: "Blocking I/O under a lock",
nested_loop_quadratic: "Quadratic nested loop",
+ list_insert_zero_in_loop: "Insert at list front in loop",
+ pd_concat_in_loop: "Pandas concat in loop",
+ pandas_iterrows_in_loop: "Row-by-row DataFrame loop",
+ json_parse_in_loop: "JSON deep clone in loop",
+ array_spread_in_reduce: "Accumulator spread in reduce",
+ goroutine_in_unbounded_loop: "Unbounded goroutines in loop",
sql_high_complexity: "Complex SQL routine",
sql_select_star: "SELECT * in a view",
sql_update_delete_without_where: "UPDATE/DELETE without WHERE",
diff --git a/tests/unit/health/test_generated_biomarker_labels.py b/tests/unit/health/test_generated_biomarker_labels.py
index 269a9b7e9..fe640243d 100644
--- a/tests/unit/health/test_generated_biomarker_labels.py
+++ b/tests/unit/health/test_generated_biomarker_labels.py
@@ -36,3 +36,11 @@ def test_an_unknown_marker_reads_with_spaces() -> None:
assert biomarker_label("primitive_obsession") == "Long parameter list"
assert biomarker_label("made_up_marker") == "made up marker"
+
+
+def test_every_registered_detector_has_a_label() -> None:
+ from repowise.core.analysis.health.biomarker_labels import BIOMARKER_LABELS
+ from repowise.core.analysis.health.biomarkers.registry import registered_biomarkers
+
+ unlabelled = [b.name for b in registered_biomarkers() if b.name not in BIOMARKER_LABELS]
+ assert unlabelled == [], f"add a label to biomarker_labels.py for: {unlabelled}"