refactor: extract parseDualModeArgs from duplicated disambiguation logic

Both parseSpanListArgs (span/list.ts) and parseLogListArgs (log/list.ts)
had near-identical control flow for detecting whether positional args
contain a trace ID. Extracted the shared logic into parseDualModeArgs()
in trace-target.ts, parameterized by the usage hint string.

Both commands now delegate to this shared utility via thin wrappers.

Addresses BugBot review feedback about duplicated argument disambiguation.

Author: BYK

src/commands/log/list.ts

@@ -34,10 +34,8 @@ import {
 import { logger } from "../../lib/logger.js";
 import { withProgress } from "../../lib/polling.js";
 import { resolveOrgProjectFromArg } from "../../lib/resolve-target.js";
-import { isTraceId } from "../../lib/trace-id.js";
 import {
-  type ParsedTraceTarget,
-  parseTraceTarget,
+  parseDualModeArgs,
   resolveTraceOrg,
   warnIfNormalized,
 } from "../../lib/trace-target.js";
@@ -144,69 +142,16 @@ type FetchResult = {
 // Positional argument disambiguation
 // ---------------------------------------------------------------------------
 
-/**
- * Parsed result from log list positional arguments.
- *
- * Discriminated on `mode`:
- * - `"project"` — standard project-scoped log listing (existing path)
- * - `"trace"` — trace-filtered log listing via trace-logs endpoint
- */
-type ParsedLogArgs =
-  | { mode: "project"; target?: string }
-  | { mode: "trace"; parsed: ParsedTraceTarget };
-
 /**
  * Disambiguate log list positional arguments.
  *
- * Detects trace mode by checking whether any argument segment looks like
- * a 32-char hex trace ID:
- *
- * - **Single arg**: checks the tail segment (last part after `/`, or the
- *   entire arg). `<trace-id>`, `<org>/<trace-id>`, `<org>/<project>/<trace-id>`.
- * - **Two+ args**: checks the last positional (`<org> <trace-id>` or
- *   `<org>/<project> <trace-id>` space-separated forms).
- * - **No match**: treats the argument as a project target.
- *
- * When trace mode is detected, delegates to {@link parseTraceTarget} for
- * full parsing and validation.
- *
- * @param args - Positional arguments from CLI
- * @returns Parsed args with mode discrimination
+ * Thin wrapper around {@link parseDualModeArgs} that binds the
+ * trace-mode usage hint for log list.
  */
-function parseLogListArgs(args: string[]): ParsedLogArgs {
-  if (args.length === 0) {
-    return { mode: "project" };
-  }
-
-  const first = args[0];
-  if (first === undefined) {
-    return { mode: "project" };
-  }
-
-  // Two+ args: check if the last arg is a trace ID (space-separated form)
-  // e.g., `sentry log list my-org abc123...` or `sentry log list my-org/proj abc123...`
-  if (args.length >= 2) {
-    const last = args.at(-1);
-    if (last && isTraceId(last)) {
-      return {
-        mode: "trace",
-        parsed: parseTraceTarget(args, TRACE_USAGE_HINT),
-      };
-    }
-  }
-
-  // Single arg: check the tail segment (last part after `/`, or the entire arg)
-  const lastSlash = first.lastIndexOf("/");
-  const tail = lastSlash === -1 ? first : first.slice(lastSlash + 1);
-
-  if (isTraceId(tail)) {
-    return {
-      mode: "trace",
-      parsed: parseTraceTarget(args, TRACE_USAGE_HINT),
-    };
-  }
-
-  return { mode: "project", target: first };
+function parseLogListArgs(
+  args: string[]
+): ReturnType<typeof parseDualModeArgs> {
+  return parseDualModeArgs(args, TRACE_USAGE_HINT);
 }
 
 /** Default time period for project-scoped log queries */

src/commands/span/list.ts

@@ -37,10 +37,9 @@ import {
 } from "../../lib/list-command.js";
 import { withProgress } from "../../lib/polling.js";
 import { resolveOrgProjectFromArg } from "../../lib/resolve-target.js";
-import { isTraceId } from "../../lib/trace-id.js";
 import {
   type ParsedTraceTarget,
-  parseTraceTarget,
+  parseDualModeArgs,
   resolveTraceOrgProject,
   warnIfNormalized,
 } from "../../lib/trace-target.js";
@@ -109,70 +108,16 @@ export function parseSort(value: string): SpanSortValue {
   return value as SpanSortValue;
 }
 
-// ---------------------------------------------------------------------------
-// Positional argument disambiguation
-// ---------------------------------------------------------------------------
-
-/**
- * Parsed result from span list positional arguments.
- *
- * Discriminated on `mode`:
- * - `"project"` — project-scoped span listing (no trace ID)
- * - `"trace"` — trace-scoped span listing (trace ID provided)
- */
-type ParsedSpanListArgs =
-  | { mode: "project"; target?: string }
-  | { mode: "trace"; parsed: ParsedTraceTarget };
-
 /**
  * Disambiguate span list positional arguments.
  *
- * Detects trace mode by checking whether any argument segment looks like
- * a 32-char hex trace ID:
- *
- * - **No args**: project mode (auto-detect org/project)
- * - **Single arg**: checks the tail segment (last part after `/`). If it
- *   looks like a trace ID → trace mode. Otherwise → project target.
- * - **Two+ args**: checks the last positional. If it's a trace ID → trace
- *   mode (space-separated form). Otherwise → project target (first arg only).
- *
- * @param args - Positional arguments from CLI
- * @returns Parsed args with mode discrimination
+ * Thin wrapper around {@link parseDualModeArgs} that binds the
+ * trace-mode usage hint for span list.
  */
-export function parseSpanListArgs(args: string[]): ParsedSpanListArgs {
-  if (args.length === 0) {
-    return { mode: "project" };
-  }
-
-  const first = args[0];
-  if (first === undefined) {
-    return { mode: "project" };
-  }
-
-  // Two+ args: check if the last arg is a trace ID (space-separated form)
-  // e.g., `sentry span list my-project abc123...`
-  if (args.length >= 2) {
-    const last = args.at(-1);
-    if (last && isTraceId(last)) {
-      return {
-        mode: "trace",
-        parsed: parseTraceTarget(args, TRACE_USAGE_HINT),
-      };
-    }
-  }
-
-  // Single arg: check the tail segment (last part after "/", or entire arg)
-  const segments = first.split("/");
-  const tail = segments.at(-1) ?? first;
-  if (isTraceId(tail)) {
-    return {
-      mode: "trace",
-      parsed: parseTraceTarget(args, TRACE_USAGE_HINT),
-    };
-  }
-
-  // Not a trace ID → treat as project target
-  return { mode: "project", target: first };
+export function parseSpanListArgs(
+  args: string[]
+): ReturnType<typeof parseDualModeArgs> {
+  return parseDualModeArgs(args, TRACE_USAGE_HINT);
 }
 
 // ---------------------------------------------------------------------------

src/lib/trace-target.ts

@@ -24,7 +24,7 @@ import {
   resolveOrgAndProject,
   resolveProjectBySlug,
 } from "./resolve-target.js";
-import { validateTraceId } from "./trace-id.js";
+import { isTraceId, validateTraceId } from "./trace-id.js";
 
 /** Match `[<prefix>]<trail>` in usageHint — captures bracket content + trailing placeholder */
 const USAGE_TARGET_RE = /\[.*\]<[^>]+>/;
@@ -397,3 +397,79 @@ export async function resolveTraceOrg(
     }
   }
 }
+
+// ---------------------------------------------------------------------------
+// Dual-mode argument disambiguation (project vs trace)
+// ---------------------------------------------------------------------------
+
+/**
+ * Result from dual-mode argument disambiguation.
+ *
+ * Used by commands that support both project-scoped listing (no trace ID)
+ * and trace-scoped listing (trace ID provided), like `span list` and
+ * `log list`.
+ *
+ * Discriminated on `mode`:
+ * - `"project"` — no trace ID detected; `target` is the optional org/project arg
+ * - `"trace"` — a 32-char hex trace ID was found; `parsed` contains the full target
+ */
+export type ParsedDualModeArgs =
+  | { mode: "project"; target?: string }
+  | { mode: "trace"; parsed: ParsedTraceTarget };
+
+/**
+ * Disambiguate positional arguments for dual-mode list commands.
+ *
+ * Detects trace mode by checking whether any argument segment looks like
+ * a 32-char hex trace ID via {@link isTraceId}:
+ *
+ * - **No args**: project mode (auto-detect org/project)
+ * - **Two+ args**: checks the last positional. If it's a trace ID → trace
+ *   mode (space-separated form like `<project> <trace-id>`).
+ * - **Single arg**: checks the tail segment (last part after `/`). If it
+ *   looks like a trace ID → trace mode. Otherwise → project target.
+ *
+ * When trace mode is detected, delegates to {@link parseTraceTarget} for
+ * full parsing and validation.
+ *
+ * @param args - Positional arguments from CLI
+ * @param traceUsageHint - Usage hint for trace-mode error messages
+ * @returns Parsed args with mode discrimination
+ */
+export function parseDualModeArgs(
+  args: string[],
+  traceUsageHint: string
+): ParsedDualModeArgs {
+  if (args.length === 0) {
+    return { mode: "project" };
+  }
+
+  const first = args[0];
+  if (first === undefined) {
+    return { mode: "project" };
+  }
+
+  // Two+ args: check if the last arg is a trace ID (space-separated form)
+  if (args.length >= 2) {
+    const last = args.at(-1);
+    if (last && isTraceId(last)) {
+      return {
+        mode: "trace",
+        parsed: parseTraceTarget(args, traceUsageHint),
+      };
+    }
+  }
+
+  // Single arg: check the tail segment (last part after "/", or entire arg)
+  const lastSlash = first.lastIndexOf("/");
+  const tail = lastSlash === -1 ? first : first.slice(lastSlash + 1);
+  if (isTraceId(tail)) {
+    return {
+      mode: "trace",
+      parsed: parseTraceTarget(args, traceUsageHint),
+    };
+  }
+
+  // Not a trace ID → treat as project target
+  return { mode: "project", target: first };
+}