Comments name what the code does, not plan tasks, spec sections or review rounds

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: si1verwind17

skills/visualizing-codebases/scripts/vizcode/examples.py

@@ -7,7 +7,7 @@
 
 LABEL = "example values, not computed"
 ENTRY_KINDS = ("request", "event", "stream", "batch")          # a relation of these kinds ending at a method
-TRACE_KINDS = ("calls", "request", "event", "stream", "batch", "db-read", "db-write", "ext-call", "hand-off")   # spec §3.3
+TRACE_KINDS = ("calls", "request", "event", "stream", "batch", "db-read", "db-write", "ext-call", "hand-off")
 HOPS = 2
 CONTAINER_KINDS = ("service", "library", "package", "file", "class")
 STALE_HINT = "stale — rewrite its value against the code, or delete it when its {gone} is gone; then delete the flag"
@@ -159,7 +159,7 @@ def add(method_id: str, why: str) -> None:
 
 
 def shape_errors(examples: dict) -> list[str]:
-    """meaning.json's `examples` shape, before assembling: {types: {class id: {value: {...}}},
+    """Meaning.json's `examples` shape, before assembling: {types: {class id: {value: {...}}},
     entries: [{node, key, request, response?}]}."""
     out: list[str] = []
     types, entries = examples.get("types", {}), examples.get("entries", [])
@@ -180,7 +180,7 @@ def shape_errors(examples: dict) -> list[str]:
 
 
 def check(cmap: dict) -> list[str]:
-    """assemble.py's refusals for an assembled map's examples, as a fix list (format.md § Examples)."""
+    """Assemble.py's refusals for an assembled map's examples, as a fix list (format.md § Examples)."""
     nodes = {n["id"]: n for n in cmap.get("nodes", [])}
     ex = cmap.get("examples") or empty()
     errors: list[str] = []

skills/visualizing-codebases/viewer/dist/audit.mjs

@@ -1,4 +1,4 @@
-// audit-inputs: 81590b0af12330570b0cb561b06373932c9ba6eb4f3f7583d570f95777de3e35
+// audit-inputs: acb22615e21e93ffcdb51da2dd67881203b52b38e4f6a8bdfb205072c41e3e85
 import { readFileSync } from "node:fs";
 // src/model/model.ts
 var SITE = "site";
@@ -213,7 +213,7 @@ var Model = class {
 	}
 	chains = /* @__PURE__ */ new Map();
 	/** One bundle per pair of items on this floor, plus relations leaving the floor. `layered`: the lines kept out of
-	*  the base layer (spec §15), each tagged with the extra layer that draws it (a line in two layers is listed once per
+	*  the base layer, each tagged with the extra layer that draws it (a line in two layers is listed once per
 	*  layer, so count or collect its key once); `bundles` never holds them. Worked out once per floor and code-links
 	*  flag (the map never changes under a Model) and shared: callers must not mutate the result. */
 	bundles(container, opts = {}) {
@@ -3397,7 +3397,7 @@ var band = (l) => ({
 	w: l.x1 - l.x0,
 	h: 3
 });
-/** `base`: given, this is a layer's pass (spec §15): the lines already laid on this floor, which `bundles` route over. Their tiles on top are
+/** `base`: given, this is a layer's pass: the lines already laid on this floor, which `bundles` route over. Their tiles on top are
 *  held by a line no layer line may ride: a layer line goes round them where it can and under them where it must, never
 *  along them; they are read, never changed. */
 function routeTiles(tf, bundles, base) {
@@ -5863,7 +5863,7 @@ var perView = (plan, check) => views(plan).flatMap(([view, routes]) => check(rou
 	detail: v.detail + view
 })));
 var perRoute = (plan, check) => perView(plan, (routes) => routes.filter((r) => r.pieces.length).flatMap(check));
-/** Every check over one floor's plan, in the order of the check table (spec §3). */
+/** Every check over one floor's plan, in the order of the check table. */
 function checks(model, c, plan, measured) {
 	const { tf } = plan, { bundles } = model.bundles(c);
 	return [

tests/regressions/test_review_fixes.py

@@ -1,4 +1,4 @@
-"""Regression tests for the final-review findings (symlinks, subdirectories, excludes,
+"""Regression tests (symlinks, subdirectories, excludes,
 route idioms, commit drift, defaulted libraries, output-dir paths)."""
 import copy
 import json

tests/scanner/test_annotated.py

@@ -129,7 +129,7 @@ def test_spring_exact_routes(make_repo):
         ("ANY", "/orders/any", f"{CTRL}#any/0", 16), ("ANY", "/v1/orders/any", f"{CTRL}#any/0", 16),
         ("DELETE", "/orders/{id}", f"{CTRL}#remove/0", 20), ("DELETE", "/v1/orders/{id}", f"{CTRL}#remove/0", 20)]
     assert {(r["framework"], r["source"]) for r in s["facts"][f]["routes"]} == {("spring-mvc", "stack.yaml")}
-    # Review Focus 2: a verb method without a class prefix gives the method path alone
+    # a verb method without a class prefix gives the method path alone
     assert routes_of(s, "src/main/java/io/demo/shop/Health.java") == [
         ("GET", "/health", "io.demo.shop.Health#health/0", 6)]
     # a class prefix with no verb methods gives nothing; no `when` import, no routes
@@ -138,7 +138,7 @@ def test_spring_exact_routes(make_repo):
 
 
 def test_annotated_non_literal_path_skipped(make_repo):
-    """Review Focus 1: `@GetMapping(PATH)` gives no route, no crash, and the report counts the other matches."""
+    """`@GetMapping(PATH)` gives no route, no crash, and the report counts the other matches."""
     repo = make_repo(SPRING_SRC)
     with_stack(repo, SPRING)
     s = structure.build(repo, "docs/viz-code")

tests/stack/test_packs_js.py

@@ -99,7 +99,7 @@ def test_express_mounts_sinks_tables(express_repo):
 
 
 def test_express_negatives(make_repo):
-    """Review Focus 3: `map.get("x")`, a one-argument `app.get('title')` (a setting), a template path and a
+    """`map.get("x")`, a one-argument `app.get('title')` (a setting), a template path and a
     member of another name are not routes; nothing matches without the `express` import."""
     src = ("const app = makeApp();\nconst map = new Map();\nmap.get('/x', 1);\napp.get('title');\n"
            "app.get(`/t/${id}`, h);\nmyapp.get('/m', h);\napp.get('/real', h);\napp.use('/v2', r);\n"
@@ -244,7 +244,7 @@ def shape(lang, items):
 
 @pytest.mark.parametrize("lang", ["typescript", "javascript"])
 def test_every_js_pack_regex_entry_has_when(lang):
-    """Review Focus 3: a pack regex without `when` would fire on any file of the language."""
+    """A pack regex without `when` would fire on any file of the language."""
     st = stack.default()
     for p in (*st.patterns, *st.tables):
         if p.lang == lang and p.source == "pack":

tests/stack/test_packs_jvm.py

@@ -42,7 +42,7 @@ def test_spring_sinks_and_tables(spring_repo):
 
 
 def test_spring_beside_jaxrs(spring_repo):
-    """Review Focus 5: both frameworks count in the pattern report; a method both annotate is one route."""
+    """Both frameworks count in the pattern report; a method both annotate is one route."""
     s = structure.build(spring_repo, "docs/viz-code")
     stock = "legacy::io.demo.shop.legacy.StockResource"
     assert routes(s, f"{LEGACY}/StockResource.java") == [
@@ -142,7 +142,7 @@ def test_ktor_routes_mounts_tables(ktor_repo):
 
 
 def test_ktor_regex_negatives(make_repo):
-    """Review Focus 3: Ktor's route and mount patterns fire only under `io.ktor.server.routing`, and never on a
+    """Ktor's route and mount patterns fire only under `io.ktor.server.routing`, and never on a
     member call (`client.get("/x") { }`, `m.get("/x")`) or a string template path."""
     src = ("package a\n\nfun f(client: Any, m: Map<String, Int>) {\n    client.get(\"/remote\") { }\n"
            "    m.get(\"/k\")\n    get(\"/x\") { }\n    route(\"/v2\") { }\n}\n")
@@ -207,14 +207,14 @@ def test_python_tables():
 
 @pytest.mark.parametrize("lang", ["java", "kotlin"])
 def test_every_pack_regex_route_has_when(lang):
-    """Review Focus 3: a pack regex route without `when` would fire on any file of the language."""
+    """A pack regex route without `when` would fire on any file of the language."""
     for p in stack.default().patterns:
         if p.lang == lang and p.source == "pack":
             assert p.when, p.name
 
 
 def test_pack_names_do_not_block_a_stack_yaml(tmp_path):
-    """A stack.yaml written before the packs (Task 1's example names) still loads."""
+    """A stack.yaml written before the packs (the old example names) still loads."""
     st = stack.load(write(tmp_path, "java:\n  routes:\n    - name: spring-mvc\n      form: annotated\n"
                                     "      verbs: {GetMapping: GET}\n  tables:\n    - {name: jpa-table, regex: '(?P<table>x)'}\n"))
     assert {p.name for p in st.patterns if p.lang == "java"} >= {"spring-mvc", "spring-web"}
@@ -232,7 +232,7 @@ def test_table_dedupe_across_patterns(make_repo):
         ("Order", 4, "quill"), ("Item", 4, "quill")]
 
 
-# Carried fixes (Task 3 review): stack.yaml replaces a pack entry by name; framework wiring ignored by its pack;
+# stack.yaml replaces a pack entry by name; framework wiring ignored by its pack;
 # a stack.yaml pattern a pack pattern duplicates is reported as such; pack gaps; dedupe order per group
 
 def test_stack_yaml_entry_replaces_the_pack_entry_of_that_name(make_repo):

tests/stack/test_packs_other.py

@@ -95,7 +95,7 @@ def test_go_gin_echo_chi():
 
 
 def test_go_negatives():
-    """Review Focus 3: look-alikes and missing imports give no route, mount or table."""
+    """Look-alikes and missing imports give no route, mount or table."""
     http = ('q := r.URL.Query()\nq.Get("id")\nresp, _ := client.R().Get("/orders")\nh.Handle(event)\n'
             'mux.HandleFunc("orders", h)\nmux.HandleFunc(path, h)\n')
     assert found("go", http, ["net/http"]) == []
@@ -180,7 +180,7 @@ def test_aspnet_minimal_api_and_tables():
 
 
 def test_csharp_negatives():
-    """Review Focus 3."""
+    """Look-alikes give nothing."""
     # minimal APIs run without `when` (implicit usings: Program.cs names nothing); the look-alikes give nothing
     src = ('app.MapGet("/ping", h);\nconfig.Map("/x");\ndict.MapGetter("/y", h);\nvar g = app.MapGroup("/g");\n'
            'cfg.MapGet("/one");\nm.MapGet(path, h);\nm.MapPost($"/i/{x}", h);\nMapGet("/bare", h);\n'
@@ -251,7 +251,7 @@ def test_axum_forms_and_actix():
 
 
 def test_rust_negatives():
-    """Review Focus 3."""
+    """Look-alikes give nothing."""
     src = ('.route("/a", get(h))\n.nest("/n", r)\n#[get("/x")]\nfn x() {}\nweb::scope("/v1")\n'
            'map.route("k")\n#[test]\nfn t() {}\n')
     assert found("rust", src, ["std::collections"]) == [] and found_mounts("rust", src, ["serde"]) == []
@@ -303,7 +303,7 @@ def test_rails_routes(make_repo):
 
 
 def test_ruby_negatives_and_tables():
-    """Review Focus 3: Rails needs `to: "c#a"`; Sinatra needs its import and a block; tables need ActiveRecord."""
+    """Rails needs `to: "c#a"`; Sinatra needs its import and a block; tables need ActiveRecord."""
     src = ('get "/x"\nget "/y", to: redirect("/z")\nget "/w", to: "nohash"\nclient.get "/v", to: "a#b"\n'
            'cache.get("/k") do\nend\n')
     assert found("ruby", src, []) == []
@@ -413,7 +413,7 @@ def test_expand_entry_shape():
 
 
 def test_php_negatives_and_tables():
-    """Review Focus 3."""
+    """Look-alikes give nothing."""
     # a routes file may call the global `Route` alias without a `use`: the Route patterns run without `when`
     route = "Route::get('/x', [C::class, 'a']);\nRoute::match(['get'], '/m', h);\n" \
             "Route::middleware(['auth'])->prefix('v1');\n"
@@ -454,7 +454,7 @@ def test_php_import_kinds():
 
 @pytest.mark.parametrize("lang", ["go", "csharp", "rust", "ruby", "php"])
 def test_every_pack_regex_entry_has_when(lang):
-    """Review Focus 3: a pack regex without `when` fires on any file of the language. The exceptions are files
+    """A pack regex without `when` fires on any file of the language. The exceptions are files
     that import nothing, each with a tight regex and look-alike tests: Rails routes and resources, C#
     minimal APIs (implicit usings), Laravel routes (the global `Route` alias), Rails models (`self.table_name`)
     and gorm models (`TableName`)."""

viewer/src/App.svelte

@@ -52,7 +52,7 @@
     saveCodeLinks(safeStorage(), codeLinks);
     scene?.setCodeLinks(codeLinks);
   }
-  // layers (spec §15): the floor's extra layers (one per heavily used item, named by its code), the one shown (the
+  // layers: the floor's extra layers (one per heavily used item, named by its code), the one shown (the
   // scene's, reset to the base on a floor change), the line kinds it draws (the legend's line rows follow it) and the
   // list's state
   let layers = $derived(model ? floorLayers(model, container) : []);
@@ -74,7 +74,7 @@
     scene?.keepCentre();
     requestAnimationFrame(() => scene?.resize());
   }
-  // the trace pane (spec §3): what it traces, where it is drawn, the divider's place and whether it fills the screen
+  // the trace pane: what it traces, where it is drawn, the divider's place and whether it fills the screen
   // the trace graph is built on the first trace, not on load: this line alone reads it, and only once `trace` is set
   let graph = $derived(model ? new TraceGraph(model) : null);
   let trace = $state.raw<TraceState | null>(null);
@@ -197,7 +197,7 @@
   let resizeWatch: ResizeObserver | null = null;
   let tracePane = $state<{ escape: () => boolean }>();   // the pane's own Esc: its pin form, then its detail panel
 
-  /** Start a trace on `focus` (spec §3.1, S1, A2): any map node or floor group, or a line (`line`); the pane opens below
+  /** Start a trace on `focus`: any map node or floor group, or a line (`line`); the pane opens below
    *  the floor; the floor keeps its zoom, and the selection is cleared so the floor and the pane show one subject. */
   function startTrace(focus: string, direction: PinDirection = "both", line?: LineStart) {
     if (!model || (!line && !traceable(model, focus))) return;
@@ -206,7 +206,7 @@
   }
 
   /** The pane's own new state: its direction, depth and folds keep the floor as it is; Trace from here, a new focus,
-   *  clears the selection as startTrace does (S1). */
+   *  clears the selection as startTrace does. */
   function retrace(st: TraceState) {
     const refocus = st.focus !== trace?.focus;
     trace = st;
@@ -223,7 +223,7 @@
 
   /** What the inspector shows (audit row 64): with the pane open, the item the floor's blue mark is on (the pointed
    *  row's node, else the trace's focus; a line's trace, its line while this floor has it) — shown, not selected, so the
-   *  floor and the pane keep one subject (S1, A1); with the pane closed, the selection (nothing: the floor). */
+   *  floor and the pane keep one subject; with the pane closed, the selection (nothing: the floor). */
   let shown = $derived<Target>(trace && model
     ? traceSubject(model, trace, point, (k) => {
         const b = model!.bundles(container);

viewer/src/audit/run.ts

@@ -26,7 +26,7 @@ const perView = (plan: FloorPlan, check: (routes: TileRoute[]) => Violation[]) =
 const perRoute = (plan: FloorPlan, check: (r: TileRoute) => Violation[]) =>
   perView(plan, (routes) => routes.filter((r) => r.pieces.length).flatMap(check));
 
-/** Every check over one floor's plan, in the order of the check table (spec §3). */
+/** Every check over one floor's plan, in the order of the check table. */
 function checks(model: Model, c: string, plan: FloorPlan, measured: () => FloorMeasures): [CheckId, () => Violation[]][] {
   const { tf } = plan, { bundles } = model.bundles(c);
   return [

viewer/src/factory/clear.ts

@@ -105,7 +105,7 @@ export const BADGE_FONT = 10.5;
  *  0.62 em wide here, plus 4 px padding each side): the drawn badge is never larger, so its spot holds it. */
 export const badgeSize = (n: number) => ({ w: Math.ceil(`used by ${n}`.length * BADGE_FONT * 0.62) + 8, h: 14 });
 
-/** Where a `used by N` badge stands beside its machine (spec §15) and how far it may grow: its box at scale `k` has
+/** Where a `used by N` badge stands beside its machine and how far it may grow: its box at scale `k` has
  *  its corner at (`ax` + `ox`·w·k, `ay` + `oy`·h·k), so the anchor (`ax`, `ay`) stays put and the badge grows away
  *  from the box (`ox` 0 grows right, -1 left; `oy` 0 grows down, -1 up, -0.5 both ways, centred). `side` is the side of
  *  the box it stands on. `maxK` is the largest scale (up to MAX_K) whose box is clear of every obstacle, so the badge