refactor(tui): compress verbose comments in the tool args module

Author: Gustav-Simonsson

src/tui/tool-args.ts

@@ -1,10 +1,10 @@
 /**
- * Human-readable tool arguments for the transcript. A call shows what it *is*
- * — a path, a command, the shape of a view — and keeps the structured form
- * behind the expand key.
+ * Human-readable tool arguments for the transcript: what a call shows — a
+ * path, a command, the shape of a view — with the structured form kept behind
+ * the expand key.
  *
- * Wording comes from `tui/tool-formatter` and the view tree from `tui/view`;
- * this module only maps them onto the palette and row model.
+ * Wording comes from `tui/tool-formatter`; the view tree from `tui/view`.
+ * This module only maps them onto the palette and row model.
  */
 
 import { isMcpToolName } from "../mcp/tool-name.js";
@@ -18,18 +18,17 @@ import { UI } from "./theme.js";
 
 /**
  * A summarised call: the collapsed line, and the body the expand key reveals.
- * An empty summary means the verb already names the call; an absent detail
- * means there is nothing behind the summary worth an arrow.
+ * Empty summary: the verb already names the call. Absent detail: nothing
+ * behind the summary worth an arrow.
  */
 export interface ToolArgsView {
   readonly summary: string;
   readonly detail?: readonly StyledBodyLine[];
 }
 
 /**
- * View roles in the Corbits palette. Warning and danger both land on action
- * orange — there is no red in the brand system, and no decision marker
- * competes on these rows.
+ * View roles in the Corbits palette. Warning and danger share action orange
+ * — the brand has no red, and no decision marker competes on these rows.
  */
 const ROLE_FG: Partial<Record<SemanticRole, string>> = {
   accent: UI.inFlightBright,
@@ -65,8 +64,8 @@ function parseObject(raw: string): Record<string, unknown> | null {
   return parsed as Record<string, unknown>;
 }
 
-/** The view tree a call carries, whole-args or under a `view` key. Validated
- * rather than duck-typed: renderers trust the shape. */
+/** The view tree a call carries, whole-args or under a `view` key.
+ * Validated, not duck-typed: renderers trust the shape. */
 function viewArgument(args: Record<string, unknown>): ViewNode | null {
   const candidate = "view" in args ? args.view : args;
   const result = validateView(candidate);
@@ -118,9 +117,9 @@ function isScalar(value: unknown): boolean {
 }
 
 /**
- * Scalar (or scalar-array) args as `key  value` pairs with newlines intact —
- * a shell command or spawn prompt is written to be read as text, and
- * pretty-printed JSON would escape its line breaks.
+ * Scalar (or scalar-array) args as `key  value` pairs with newlines intact:
+ * a shell command reads as text, and pretty-printed JSON would escape its
+ * line breaks.
  *
  * Nested objects recurse one level so a task brief expands as fields; deeper
  * nesting collapses to a compact token.
@@ -170,7 +169,7 @@ function fieldDetail(
       continue;
     }
     if (typeof value === "object" && value !== null && !Array.isArray(value)) {
-      // One level of nesting is enough for a spawn brief; deeper stays compact.
+      // One nesting level is enough for a spawn brief.
       if (indent === 0) {
         lines.push([{ text: `${pad}${key}:`, fg: UI.textDim }]);
         lines.push(
@@ -184,7 +183,7 @@ function fieldDetail(
       }
       continue;
     }
-    // Arrays of objects, etc. — compact rather than a wall of JSON.
+    // Arrays of objects: compact, not a wall of JSON.
     lines.push([
       { text: `${pad}${key}: `, fg: UI.textDim },
       {
@@ -207,10 +206,10 @@ function jsonDetail(value: unknown): readonly StyledBodyLine[] {
 const INLINE_MAX = 60;
 
 /**
- * Argument a call is *about*, most-meaningful first. A row's subject is one
- * value — the query, the command, the URL — because a transcript is scanned,
- * and a serialised list would spend the row on a second argument cut off
- * mid-word ("numR…"). Everything else is behind the arrow.
+ * Argument a call is *about*, most-meaningful first. A transcript is
+ * scanned, so the subject is one value — the query, the command, the URL —
+ * not a serialised list that would cut the next argument mid-word. The rest
+ * stays behind the arrow.
  */
 const SUBJECT_KEYS = [
   "command",
@@ -233,8 +232,7 @@ function flatten(value: string): string {
 }
 
 /** The one argument worth painting, or null when nothing scalar stands out.
- * Falls back to the first scalar so an unknown tool still reads as a
- * subject. */
+ * Falls back to the first scalar so an unknown tool still has a subject. */
 function primarySubject(args: Record<string, unknown>): string | null {
   for (const key of SUBJECT_KEYS) {
     const value = args[key];
@@ -250,8 +248,8 @@ function primarySubject(args: Record<string, unknown>): string | null {
     : flatten(first[1] as string).slice(0, SUBJECT_MAX);
 }
 
-/** Whether the formatter fell back to serialising the whole argument object.
- * Its per-tool cases never lead with `key: ` and are better subjects. */
+/** Whether the formatter serialised the whole argument object: its per-tool
+ * cases never lead with `key: ` and make better subjects. */
 function isArgumentList(
   args: Record<string, unknown>,
   summary: string,
@@ -267,13 +265,13 @@ function subjectFor(
 ): string {
   const { summary } = summarizeToolArgs(name, raw);
   // An empty formatter summary is not a subject — fall through so a task
-  // without description still paints its prompt rather than raw JSON.
+  // without a description paints its prompt, not raw JSON.
   if (summary.length > 0 && !isArgumentList(args, summary)) return summary;
   return primarySubject(args) ?? summary;
 }
 
-/** The summary/detail pair for a call's arguments, or null when short literal
- * args read better as themselves than with an expand hint. */
+/** The summary/detail pair for a call's arguments, or null when short
+ * literal args read better as themselves. */
 export function toolArgsView(
   name: string,
   rawArgs: string,
@@ -289,8 +287,8 @@ export function toolArgsView(
     }
   }
 
-  // An MCP call's verb is already the whole sentence; its args are a query,
-  // not a subject — they belong behind the expand key or nowhere.
+  // An MCP call's verb is the whole sentence; its args are a query, not a
+  // subject — they belong behind the expand key or nowhere.
   if (args !== null && isMcpToolName(name)) {
     return withDetail("", fieldDetail(args));
   }
@@ -304,7 +302,7 @@ export function toolArgsView(
   }
   const subject = subjectFor(name, raw, args);
   // Object args always get a summarised view — even with an empty subject the
-  // verb names the call. A null return is what used to dump raw JSON.
+  // verb names the call.
   return withDetail(subject, fieldDetail(args));
 }
 
@@ -323,7 +321,7 @@ function withDetail(
     )
     .join("\n")
     .trim();
-  // A one-argument call whose subject *is* that argument reveals nothing but
+  // A one-argument call whose subject is that argument reveals nothing but
   // the key it was named by; no arrow.
   const bare = plain.includes("\n")
     ? plain