refactor(formatters): extract render_list helper and normalize quiet-key handling

docs-astro/src/data/commands.json

@@ -58,7 +58,7 @@
           "name": "stats",
           "id": "stats",
           "help": "Show per-pass breakdown, top draws, largest resources.",
-          "usage": "rdc stats [--json] [--no-header] [--jsonl] [-q]"
+          "usage": "rdc stats [--no-header] [--json] [--jsonl] [-q]"
         },
         {
           "name": "events",
@@ -88,13 +88,13 @@
           "name": "log",
           "id": "log",
           "help": "Show debug/validation messages from the capture.",
-          "usage": "rdc log [--level CHOICE] [--eid INTEGER] [--json] [--no-header] [--jsonl] [-q]"
+          "usage": "rdc log [--level CHOICE] [--eid INTEGER] [--no-header] [--json] [--jsonl] [-q]"
         },
         {
           "name": "counters",
           "id": "counters",
           "help": "Query GPU performance counters.",
-          "usage": "rdc counters [--list] [--eid INTEGER] [--name TEXT] [--json] [--no-header] [--jsonl] [-q]"
+          "usage": "rdc counters [--list] [--eid INTEGER] [--name TEXT] [--no-header] [--json] [--jsonl] [-q]"
         }
       ]
     },
@@ -113,7 +113,7 @@
           "name": "bindings",
           "id": "bindings",
           "help": "Show bound resources per shader stage.",
-          "usage": "rdc bindings [EID] [--binding INTEGER] [--set INTEGER] [--json] [--no-header] [--jsonl] [-q]"
+          "usage": "rdc bindings [EID] [--binding INTEGER] [--set INTEGER] [--no-header] [--json] [--jsonl] [-q]"
         }
       ]
     },
@@ -126,7 +126,7 @@
           "name": "resources",
           "id": "resources",
           "help": "List all resources.",
-          "usage": "rdc resources [--json] [--type TEXT] [--name TEXT] [--sort CHOICE] [--no-header] [--jsonl] [-q]"
+          "usage": "rdc resources [--type TEXT] [--name TEXT] [--sort CHOICE] [--no-header] [--json] [--jsonl] [-q]"
         },
         {
           "name": "resource",
@@ -138,7 +138,7 @@
           "name": "usage",
           "id": "usage",
           "help": "Show resource usage (which events read/write a resource).",
-          "usage": "rdc usage [RESOURCE-ID] [--all] [--type TEXT] [--usage TEXT] [--json] [--no-header] [--jsonl] [-q]"
+          "usage": "rdc usage [RESOURCE-ID] [--all] [--type TEXT] [--usage TEXT] [--no-header] [--json] [--jsonl] [-q]"
         },
         {
           "name": "shader",
@@ -150,7 +150,7 @@
           "name": "shaders",
           "id": "shaders",
           "help": "List unique shaders in capture.",
-          "usage": "rdc shaders [--stage CHOICE] [--sort CHOICE] [--json] [--no-header] [--jsonl] [-q]"
+          "usage": "rdc shaders [--stage CHOICE] [--sort CHOICE] [--no-header] [--json] [--jsonl] [-q]"
         },
         {
           "name": "shader-map",
@@ -168,7 +168,7 @@
           "name": "passes",
           "id": "passes",
           "help": "List render passes.",
-          "usage": "rdc passes [--json] [--deps] [--dot] [--graph] [--table] [--no-header] [--jsonl] [-q]"
+          "usage": "rdc passes [--deps] [--dot] [--graph] [--table] [--no-header] [--json] [--jsonl] [-q]"
         },
         {
           "name": "pass",
@@ -236,7 +236,7 @@
           "name": "pixel",
           "id": "pixel",
           "help": "Query pixel history at (X, Y) for the current or specified event.",
-          "usage": "rdc pixel <X> <Y> [EID] [--target INTEGER] [--sample INTEGER] [--json] [--no-header] [--jsonl] [-q]"
+          "usage": "rdc pixel <X> <Y> [EID] [--target INTEGER] [--sample INTEGER] [--no-header] [--json] [--jsonl] [-q]"
         },
         {
           "name": "pick-pixel",

docs-astro/src/data/replay.json

@@ -6,19 +6,19 @@
     },
     {
       "cmd": "rdc info",
-      "output": "capture:      hello_triangle.rdc\napi:          Vulkan\nevent_count:  14\ndriver:       NVIDIA 565.57.01"
+      "output": "Capture:        hello_triangle.rdc\nAPI:            Vulkan\nEvents:         6\nDraw Calls:     1 (0 indexed, 1 non-indexed, 0 dispatches)\nClears:         0\nCopies:         0"
     },
     {
       "cmd": "rdc draws",
-      "output": "EID\tMARKER\tTRIANGLES\n11\tDrawIndexed\t1"
+      "output": "EID\tTYPE\tTRIANGLES\tINSTANCES\tPASS\tMARKER\n11\tDraw\t12\t1\tColour Pass #1 (1 Target + Depth)\t-"
     },
     {
       "cmd": "rdc pipeline 11",
-      "output": "type:       Graphics\ngfx_pipe:   51\ntopology:   TriangleList\nvs_shader:  111\nps_shader:  112"
+      "output": "EID\tAPI\tTOPOLOGY\tGFX_PIPE\tCOMP_PIPE\n11\tVulkan\tTriangleList\t114\t0"
     },
     {
       "cmd": "rdc search \"main\"",
-      "output": "SHADER\tSTAGE\tLINE\tCONTENT\n111\tvs\t3\tvoid main() {\n112\tps\t4\tvoid main() {"
+      "output": "shader:111[vs]:12:EntryPoint(Vertex, main, \"main\", {\nshader:111[vs]:43:void main() {\nshader:112[ps]:12:EntryPoint(Fragment, main, \"main\", {\nshader:112[ps]:18:ExecutionMode(main, OriginUpperLeft);\nshader:112[ps]:32:void main() {"
     },
     {
       "cmd": "rdc close",
@@ -32,23 +32,23 @@
     },
     {
       "cmd": "rdc tree / --depth 1",
-      "output": "/\n  draws/\n  passes/\n  resources/\n  shaders/\n  info\n  log\n  stats"
+      "output": "//\n|-- capabilities\n|-- info\n|-- stats\n|-- log\n|-- events/\n|-- draws/\n|-- passes/\n|-- resources/\n|-- textures/\n|-- buffers/\n|-- shaders/\n|-- counters/\n\\-- current@"
     },
     {
       "cmd": "rdc ls /draws/11",
-      "output": "NAME\tKIND\npipeline/\tdir\nshader/\tdir\ncbuffer/\tdir\nvbuffer\tleaf\nibuffer\tleaf\ndescriptors\tleaf"
+      "output": "pipeline\nshader\nbindings\ntargets\npostvs\ncbuffer\nvbuffer\nibuffer\ndescriptors\npixel"
     },
     {
       "cmd": "rdc cat /draws/11/pipeline/topology",
-      "output": "TriangleList"
+      "output": "eid:      11\ntopology: TriangleList"
     },
     {
       "cmd": "rdc resources -q | wc -l",
-      "output": "6"
+      "output": "46"
     },
     {
       "cmd": "rdc draws --json | jq \".[0].triangles\"",
-      "output": "1"
+      "output": "12"
     },
     {
       "cmd": "rdc close",
@@ -62,19 +62,19 @@
     },
     {
       "cmd": "rdc pick-pixel 300 300 11",
-      "output": "r=0.0000  g=0.5000  b=0.0000  a=1.0000"
+      "output": "r=0.3373  g=0.3373  b=0.3373  a=0.5216"
     },
     {
       "cmd": "rdc pixel 300 300 11",
-      "output": "EID\tTEST\tR\tG\tB\tA\n11\tPassed\t0.0000\t0.5000\t0.0000\t1.0000"
+      "output": "EID\tFRAG\tDEPTH\tPASSED\tFLAGS\n6\t0\t-\tyes\t-\n11\t0\t0.9581\tyes\t-"
     },
     {
       "cmd": "rdc debug pixel 11 300 300",
-      "output": "result: r=0.0000 g=0.5000 b=0.0000 a=1.0000\nshader: 112 (ps)"
+      "output": "stage:   ps\neid:     11\nsteps:   80\ninputs:  _99 = [-107374176.0 -107374176.0 -107374176.0 -107374176.0]\noutputs:  = [0.0]"
     },
     {
       "cmd": "rdc debug pixel 11 300 300 --trace",
-      "output": "STEP\tLINE\tINST\tVAR\tVALUE\n0\t4\t0\tcolor\t(0.0, 1.0, 0.0, 1.0)\n1\t5\t1\toutColor\t(0.0, 0.5, 0.0, 1.0)"
+      "output": "STEP\tINSTR\tFILE\tLINE\tVAR\tTYPE\tVALUE\n0\t78\t-\t0\t_99\tfloat\t-107374176.0 -107374176.0 -107374176.0 -107374176.0\n1\t79\t-\t0\t_79\tfloat\t-0.015102430246770382 -0.3927634656429291 4.36358118057251\n2\t80\t-\t0\t_80\tfloat\t0.01510667521506548 -8.669495582580566e-05 0.0010061264038085938\n3\t81\t-\t0\t\tfloat\t0.0\n3\t81\t-\t0\t_76\tfloat\t0.01510667521506548 -8.669495582580566e-05 0.0010061264038085938\n4\t82\t-\t0\t\tfloat\t0.0\n4\t82\t-\t0\t_82\tfloat\t-0.015102430246770382 -0.3927634656429291 4.36358118057251\n... (138 more)"
     },
     {
       "cmd": "rdc close",
@@ -88,15 +88,15 @@
     },
     {
       "cmd": "rdc draws --json",
-      "output": "[{\"eid\": 11, \"marker\": \"DrawIndexed\", \"triangles\": 1}]"
+      "output": "[\n  {\n    \"eid\": 11,\n    \"type\": \"Draw\",\n    \"triangles\": 12,\n    \"instances\": 1,\n    \"pass\": \"Colour Pass #1 (1 Target + Depth)\",\n    \"marker\": \"-\"\n  }\n]"
     },
     {
       "cmd": "rdc assert-count draws --expect 1 --op eq",
-      "output": "PASS: draws == 1"
+      "output": "pass: draws = 1 (expected eq 1)"
     },
     {
       "cmd": "rdc assert-count events --expect 5 --op ge",
-      "output": "PASS: events >= 5 (actual: 14)"
+      "output": "pass: events = 6 (expected ge 5)"
     },
     {
       "cmd": "rdc close",
@@ -106,11 +106,11 @@
   [
     {
       "cmd": "rdc diff before.rdc after.rdc --draws",
-      "output": "--- before.rdc draws\n+++ after.rdc draws\n  DrawIndexed(11): 1 tri\n+ DrawIndexed(14): 256 tri"
+      "output": "STATUS\tEID_A\tEID_B\tMARKER\tTYPE\tTRI_A\tTRI_B\tINST_A\tINST_B\tCONFIDENCE\n=\t11\t11\t-\tDraw\t12\t12\t1\t1\tmedium"
     },
     {
       "cmd": "rdc diff before.rdc after.rdc --stats",
-      "output": "METRIC\tBEFORE\tAFTER\tDELTA\ndraws\t1\t2\t+1\ntriangles\t1\t257\t+256\nresources\t6\t8\t+2"
+      "output": "STATUS\tPASS\tDRAWS_A\tDRAWS_B\tDRAWS_DELTA\tTRI_A\tTRI_B\tTRI_DELTA\tDISP_A\tDISP_B\tDISP_DELTA\n=\tvkCmdBeginRenderPass(C=Clear, D=Clear)\t1\t1\t0\t12\t12\t0\t0\t0\t0"
     }
   ]
 ]

src/rdc/_skills/references/commands-quick-ref.md

@@ -162,8 +162,8 @@ Show bound resources per shader stage.
 |------|------|------|---------|
 | `--binding` | Filter by binding index. | integer |  |
 | `--set` | Filter by descriptor set index. | integer |  |
-| `--json` | Output JSON. | flag |  |
 | `--no-header` | Omit TSV header | flag |  |
+| `--json` | JSON output | flag |  |
 | `--jsonl` | JSONL output | flag |  |
 | `-q, --quiet` | Print primary key column only | flag |  |
 
@@ -350,8 +350,8 @@ Query GPU performance counters.
 | `--list` | List available counters. | flag |  |
 | `--eid` | Filter to specific event ID. | integer |  |
 | `--name` | Filter counters by name substring. | text |  |
-| `--json` | JSON output. | flag |  |
 | `--no-header` | Omit TSV header | flag |  |
+| `--json` | JSON output | flag |  |
 | `--jsonl` | JSONL output | flag |  |
 | `-q, --quiet` | Print primary key column only | flag |  |
 
@@ -490,7 +490,7 @@ List draw calls.
 | `--no-header` | Omit TSV header | flag |  |
 | `--json` | JSON output | flag |  |
 | `--jsonl` | JSONL output | flag |  |
-| `-q, --quiet` | Only EID column | flag |  |
+| `-q, --quiet` | Print primary key column only | flag |  |
 
 ## `rdc event`
 
@@ -523,7 +523,7 @@ List all events.
 | `--no-header` | Omit TSV header | flag |  |
 | `--json` | JSON output | flag |  |
 | `--jsonl` | JSONL output | flag |  |
-| `-q, --quiet` | Only EID column | flag |  |
+| `-q, --quiet` | Print primary key column only | flag |  |
 
 ## `rdc goto`
 
@@ -576,8 +576,8 @@ Show debug/validation messages from the capture.
 |------|------|------|---------|
 | `--level` | Filter by severity. | choice |  |
 | `--eid` | Filter by event ID. | integer |  |
-| `--json` | JSON output | flag |  |
 | `--no-header` | Omit TSV header | flag |  |
+| `--json` | JSON output | flag |  |
 | `--jsonl` | JSONL output | flag |  |
 | `-q, --quiet` | Print primary key column only | flag |  |
 
@@ -670,12 +670,12 @@ List render passes.
 
 | Flag | Help | Type | Default |
 |------|------|------|---------|
-| `--json` | Output JSON. | flag |  |
 | `--deps` | Show pass dependency DAG. | flag |  |
 | `--dot` | Graphviz DOT output (requires --deps). | flag |  |
 | `--graph` | Human-readable graph (requires --deps). | flag |  |
 | `--table` | Per-pass I/O table (requires --deps). | flag |  |
 | `--no-header` | Omit TSV header | flag |  |
+| `--json` | JSON output | flag |  |
 | `--jsonl` | JSONL output | flag |  |
 | `-q, --quiet` | Print primary key column only | flag |  |
 
@@ -733,8 +733,8 @@ Query pixel history at (X, Y) for the current or specified event.
 |------|------|------|---------|
 | `--target` | Color target index (default 0) | integer | 0 |
 | `--sample` | MSAA sample index (default 0) | integer | 0 |
-| `--json` | JSON output | flag |  |
 | `--no-header` | Omit TSV header | flag |  |
+| `--json` | JSON output | flag |  |
 | `--jsonl` | JSONL output | flag |  |
 | `-q, --quiet` | Print primary key column only | flag |  |
 
@@ -854,11 +854,11 @@ List all resources.
 
 | Flag | Help | Type | Default |
 |------|------|------|---------|
-| `--json` | Output JSON. | flag |  |
 | `--type` | Filter by resource type (exact, case-insensitive). | text |  |
 | `--name` | Filter by name substring (case-insensitive). | text |  |
 | `--sort` | Sort order. | choice | id |
 | `--no-header` | Omit TSV header | flag |  |
+| `--json` | JSON output | flag |  |
 | `--jsonl` | JSONL output | flag |  |
 | `-q, --quiet` | Print primary key column only | flag |  |
 
@@ -1045,10 +1045,10 @@ Output EID-to-shader mapping as TSV.
 
 | Flag | Help | Type | Default |
 |------|------|------|---------|
-| `--no-header` | Omit TSV header row. | flag |  |
-| `--json` | JSON output. | flag |  |
-| `--jsonl` | JSONL output. | flag |  |
-| `-q, --quiet` | Print EID column only. | flag |  |
+| `--no-header` | Omit TSV header | flag |  |
+| `--json` | JSON output | flag |  |
+| `--jsonl` | JSONL output | flag |  |
+| `-q, --quiet` | Print primary key column only | flag |  |
 
 ## `rdc shader-replace`
 
@@ -1105,8 +1105,8 @@ List unique shaders in capture.
 |------|------|------|---------|
 | `--stage` | Filter by shader stage. | choice |  |
 | `--sort` | Sort order. | choice | name |
-| `--json` | Output JSON. | flag |  |
 | `--no-header` | Omit TSV header | flag |  |
+| `--json` | JSON output | flag |  |
 | `--jsonl` | JSONL output | flag |  |
 | `-q, --quiet` | Print primary key column only | flag |  |
 
@@ -1135,8 +1135,8 @@ Show per-pass breakdown, top draws, largest resources.
 
 | Flag | Help | Type | Default |
 |------|------|------|---------|
-| `--json` | JSON output | flag |  |
 | `--no-header` | Omit TSV header | flag |  |
+| `--json` | JSON output | flag |  |
 | `--jsonl` | JSONL output | flag |  |
 | `-q, --quiet` | Print primary key column only | flag |  |
 
@@ -1240,7 +1240,7 @@ Show resource usage (which events read/write a resource).
 | `--all` | Show all resources usage matrix. | flag |  |
 | `--type` | Filter by resource type. | text |  |
 | `--usage` | Filter by usage type. | text |  |
-| `--json` | JSON output. | flag |  |
 | `--no-header` | Omit TSV header | flag |  |
+| `--json` | JSON output | flag |  |
 | `--jsonl` | JSONL output | flag |  |
 | `-q, --quiet` | Print primary key column only | flag |  |

src/rdc/commands/counters.py

@@ -2,14 +2,13 @@
 
 from __future__ import annotations
 
-import sys
 from typing import Any
 
 import click
 
 from rdc.commands._helpers import call, complete_eid
-from rdc.formatters.json_fmt import write_json, write_jsonl
-from rdc.formatters.options import list_output_options
+from rdc.formatters.json_fmt import write_json
+from rdc.formatters.options import list_output_options, render_list
 from rdc.formatters.tsv import write_tsv
 
 
@@ -23,7 +22,6 @@
     help="Filter to specific event ID.",
 )
 @click.option("--name", "name_filter", default=None, help="Filter counters by name substring.")
-@click.option("--json", "use_json", is_flag=True, help="JSON output.")
 @list_output_options
 def counters_cmd(
     show_list: bool,
@@ -45,15 +43,20 @@ def counters_cmd(
             write_json(result)
             return
         counters = result.get("counters", [])
-        if use_jsonl:
-            write_jsonl(counters)
-        elif quiet:
-            for c in counters:
-                sys.stdout.write(str(c["id"]) + "\n")
-        else:
+
+        def _list_table() -> None:
             tsv_rows = [[c["id"], c["name"], c["unit"], c["type"], c["category"]] for c in counters]
             hdr = ["ID", "NAME", "UNIT", "TYPE", "CATEGORY"]
             write_tsv(tsv_rows, header=hdr, no_header=no_header)
+
+        render_list(
+            counters,
+            use_json=False,
+            use_jsonl=use_jsonl,
+            quiet=quiet,
+            quiet_key="id",
+            table=_list_table,
+        )
         return
 
     params: dict[str, Any] = {}
@@ -66,11 +69,16 @@ def counters_cmd(
         write_json(result)
         return
     rows = result.get("rows", [])
-    if use_jsonl:
-        write_jsonl(rows)
-    elif quiet:
-        for r in rows:
-            sys.stdout.write(str(r["eid"]) + "\n")
-    else:
+
+    def _fetch_table() -> None:
         tsv_rows = [[r["eid"], r["counter"], r["value"], r["unit"]] for r in rows]
         write_tsv(tsv_rows, header=["EID", "COUNTER", "VALUE", "UNIT"], no_header=no_header)
+
+    render_list(
+        rows,
+        use_json=False,
+        use_jsonl=use_jsonl,
+        quiet=quiet,
+        quiet_key="eid",
+        table=_fetch_table,
+    )