refactor: address second round of human review feedback

- Use SortValue type alias in ListFlags instead of inline literal union
- Fix MAX_LIMIT JSDoc: removed incorrect claim about internal pagination
  (listSpans passes per_page directly, no client-side pagination)
- Add default params to validateLimit(value, min=1, max=1000)
- Change limit brief to (<=) format

Author: BYK

src/commands/span/list.ts

@@ -34,27 +34,25 @@ import {
 } from "../../lib/resolve-target.js";
 import { validateTraceId } from "../../lib/trace-id.js";
 
+type SortValue = "date" | "duration";
+
 type ListFlags = {
   readonly limit: number;
   readonly query?: string;
-  readonly sort: "date" | "duration";
+  readonly sort: SortValue;
   readonly json: boolean;
   readonly fresh: boolean;
   readonly fields?: string[];
 };
 
-type SortValue = "date" | "duration";
-
 /** Accepted values for the --sort flag (matches trace list) */
 const VALID_SORT_VALUES: SortValue[] = ["date", "duration"];
 
 /**
  * CLI-side upper bound for --limit.
  *
- * The Sentry Events API (spans dataset) accepts `per_page` up to 100 per
- * request, but the CLI allows requesting up to 1000 as a convenience —
- * the API client paginates internally when needed. This matches the cap
- * used by `issue list`, `trace list`, and `log list`.
+ * Passed directly as `per_page` to the Sentry Events API (spans dataset).
+ * Matches the cap used by `issue list`, `trace list`, and `log list`.
  */
 const MAX_LIMIT = 1000;
 
@@ -114,7 +112,7 @@ export function parsePositionalArgs(args: string[]): {
  * Parse --limit flag, delegating range validation to shared utility.
  */
 function parseLimit(value: string): number {
-  return validateLimit(value, 1, MAX_LIMIT);
+  return validateLimit(value, 1, MAX_LIMIT); // min=1 is validateLimit's default, explicit for clarity
 }
 
 /**
@@ -210,7 +208,7 @@ export const listCommand = buildCommand({
       limit: {
         kind: "parsed",
         parse: parseLimit,
-        brief: `Number of spans (1-${MAX_LIMIT})`,
+        brief: `Number of spans (<=${MAX_LIMIT})`,
         default: String(DEFAULT_LIMIT),
       },
       query: {

src/lib/arg-parsing.ts

@@ -176,7 +176,7 @@ export function detectSwappedTrialArgs(
  * validateLimit("0", 1, 1000)   // throws
  * validateLimit("abc", 1, 1000) // throws
  */
-export function validateLimit(value: string, min: number, max: number): number {
+export function validateLimit(value: string, min = 1, max = 1000): number {
   const num = Number.parseInt(value, 10);
   if (Number.isNaN(num) || num < min || num > max) {
     throw new Error(`--limit must be between ${min} and ${max}`);