fix(arg-parsing): accept underscores in Sentry slugs (#770) (#771)

## Summary

Fixes #770. The CLI was converting underscores to dashes in
`normalizeSlug()` on the assumption that "Sentry slugs never contain
underscores". That assumption is wrong — the Sentry platform accepts
underscores in project slugs at creation time, and rewriting them at the
CLI layer made it impossible for affected customers to look up their own
projects.

## Verification

Live API test against a real org before the fix:

```
$ sentry api --method POST /teams/byk-test/byk-test/projects/ \
    --field slug=test_underscore_slug \
    --field name=test_underscore_project \
    --field platform=javascript
# → 200 OK, slug preserved exactly as "test_underscore_slug"

$ sentry api /projects/byk-test/test_underscore_slug/
# → 200 OK, round-trips cleanly
```

Before (the bug):

```
$ sentry issue list byk-test/test_underscore_slug
[arg-parsing]  WARN  Normalized slug to 'byk-test/test-underscore-slug' (Sentry slugs use dashes, never underscores)
Error: Project 'test-underscore-slug' not found in organization 'byk-test'.
```

After this PR (running the dev build against the same project):

```
$ bun run dev issue list byk-test/test_underscore_slug
No issues found.
```

Space normalization still works as before:

```
$ bun run dev issue list "BYK Test/My Project"
[arg-parsing]  WARN  Normalized slug to 'byk-test/my-project' (Sentry slugs use lowercase with dashes, not spaces)
```

## History (for reviewers)

- The underscore rule was introduced in #363 as typo-correction for one
specific customer (`selfbase_admin_backend`), never verified against the
platform.
- #757 folded underscore and space handling into a combined `[_ ]+`
regex. The reporter on #770 correctly spotted that regex — but the root
cause predates that PR.
- The legacy `sentry-cli` (Rust) accepts underscored slugs, so the new
CLI diverging on this is a regression from the user's perspective.

## Changes

- `normalizeSlug()`: only normalize when the input contains a space.
Underscored input is returned unchanged (`normalized: false`).
- Remove the `NormalizeReason` discriminator. With underscores gone,
only the "spaces" path remains, so `reason` collapses to `normalized:
true` (and the warning message becomes a single string).
- `ParsedOrgProject`: drop the `reason?` field from all three variants.
- `trace-target.ts`: no source change required — already only read
`.slug` and `.normalized`.
- Tests: replace underscore-normalization tests with
underscore-preservation tests. Mixed inputs like `my_org/My Project` now
correctly yield `{ org: "my_org", project: "my-project" }`. Delete the
three command-level underscore-warning tests (the code path no longer
exists; unit-level space coverage is sufficient).

## Verification

- `bun run typecheck` — clean
- `bun run lint` — clean (pre-existing warning in `markdown.ts`
unrelated)
- `bun run test:unit` — 5036 / 5036 pass
- `bun run test:isolated` — 138 / 138 pass
- `bun run check:errors`, `bun run check:deps` — clean
- Manual end-to-end repro against real Sentry org (above).

Net diff: −110 lines.

Author: BYK

src/lib/arg-parsing.ts

@@ -18,92 +18,56 @@ import { isAllDigits } from "./utils.js";
 // Slug normalization
 // ---------------------------------------------------------------------------
 
-/** Describes what was normalized in a slug — used for targeted warning messages. */
-export type NormalizeReason = "underscores" | "spaces" | "both";
-
 /**
- * Normalize a Sentry slug by replacing underscores and spaces with dashes.
+ * Normalize a Sentry slug by converting display-name-style input to slug form.
  *
- * Sentry enforces that slugs use lowercase letters, numbers, and dashes.
- * Users frequently type underscores by mistake or paste display names
- * (e.g., `"My Project"` instead of `"my-project"`).
+ * Sentry slugs are always lowercase and use dashes as separators. Users
+ * sometimes paste display names like `"My Project"` instead of
+ * `"my-project"`; without normalization, `validateResourceId` would reject
+ * those outright for containing spaces. Normalization gives us a chance to
+ * recover the intent before validation runs.
  *
- * Normalization rules:
- * 1. Underscores → dashes (existing)
- * 2. Spaces → dashes, with lowercase (spaces imply a display name)
- * 3. Consecutive dashes collapsed (`"My  Project"` → `"my-project"`)
- * 4. Leading/trailing dashes trimmed
+ * Normalization rules (applied only when spaces are present):
+ * 1. Lowercase the entire string
+ * 2. Collapse runs of spaces into a single dash
+ * 3. Trim leading/trailing dashes (from leading/trailing whitespace)
  *
- * Lowercasing is only applied when spaces are present. Pure underscore
- * normalization preserves casing for backward compatibility.
+ * Underscores are **not** normalized — Sentry accepts underscores in project
+ * slugs at creation time, so rewriting them here would silently break
+ * lookups for any customer who has one (see #770). Since underscores are
+ * not in `validateResourceId`'s forbidden set either, they flow through
+ * untouched.
  *
  * @param slug - Raw slug string from CLI input
- * @returns Normalized slug, whether normalization was applied, and reason
+ * @returns Normalized slug and whether normalization was applied
  *
  * @example
- * normalizeSlug("selfbase_admin_backend")  // { slug: "selfbase-admin-backend", normalized: true, reason: "underscores" }
- * normalizeSlug("My Project")              // { slug: "my-project", normalized: true, reason: "spaces" }
- * normalizeSlug("My_Project Name")         // { slug: "my-project-name", normalized: true, reason: "both" }
+ * normalizeSlug("My Project")              // { slug: "my-project", normalized: true }
+ * normalizeSlug("My  Project")             // { slug: "my-project", normalized: true }
+ * normalizeSlug("selfbase_admin_backend")  // { slug: "selfbase_admin_backend", normalized: false }
  * normalizeSlug("my-project")              // { slug: "my-project", normalized: false }
  */
 export function normalizeSlug(slug: string): {
   slug: string;
   normalized: boolean;
-  reason?: NormalizeReason;
 } {
-  const hasUnderscores = slug.includes("_");
-  const hasSpaces = slug.includes(" ");
-
-  if (!(hasUnderscores || hasSpaces)) {
+  if (!slug.includes(" ")) {
     return { slug, normalized: false };
   }
 
-  let result = slug;
-
-  // When spaces are present, lowercase the entire slug.
-  // Spaces imply a display name like "My Project" — slugs are always lowercase.
-  if (hasSpaces) {
-    result = result.toLowerCase();
-  }
-
-  // Replace runs of underscores/spaces with a single dash.
-  // Using [_ ]+ collapses "My  Project" and "a__b" in one pass.
-  result = result.replace(/[_ ]+/g, "-");
-
-  // Trim leading/trailing dashes (from " My Project " → "-my-project-")
-  result = result.replace(/^-+|-+$/g, "");
+  // Spaces imply a display name — slugs are always lowercase.
+  // Collapse runs of spaces into a single dash, then trim any edge dashes
+  // introduced by leading/trailing whitespace in the input.
+  const result = slug
+    .toLowerCase()
+    .replace(/ +/g, "-")
+    .replace(/^-+|-+$/g, "");
 
-  let reason: NormalizeReason;
-  if (hasUnderscores && hasSpaces) {
-    reason = "both";
-  } else if (hasSpaces) {
-    reason = "spaces";
-  } else {
-    reason = "underscores";
-  }
-
-  return { slug: result, normalized: true, reason };
+  return { slug: result, normalized: true };
 }
 
 const log = logger.withTag("arg-parsing");
 
-/**
- * Combine two normalization reasons into the most descriptive one.
- * Used when org and project slugs have different normalizations.
- */
-function combineReasons(
-  a?: NormalizeReason,
-  b?: NormalizeReason
-): NormalizeReason {
-  if (a === "both" || b === "both") {
-    return "both";
-  }
-  if (a && b && a !== b) {
-    return "both";
-  }
-  return a ?? b ?? "underscores";
-}
-
 /**
  * Emit a warning when slug normalization changed the input.
  * Called internally by {@link parseOrgProjectArg} — callers do not need to
@@ -127,21 +91,9 @@ function warnNormalized(
       return;
   }
 
-  let explanation: string;
-  switch (parsed.reason) {
-    case "spaces":
-      explanation = "Sentry slugs use lowercase with dashes, not spaces";
-      break;
-    case "both":
-      explanation =
-        "Sentry slugs use lowercase with dashes, not spaces or underscores";
-      break;
-    default:
-      explanation = "Sentry slugs use dashes, never underscores";
-      break;
-  }
-
-  log.warn(`Normalized slug to '${slug}' (${explanation})`);
+  log.warn(
+    `Normalized slug to '${slug}' (Sentry slugs use lowercase with dashes, not spaces)`
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -438,8 +390,9 @@ export const ProjectSpecificationType = {
  * Parsed result from an org/project positional argument.
  * Discriminated union based on the `type` field.
  *
- * When `normalized` is true, the slug was auto-corrected (underscores → dashes,
- * spaces → dashes with lowercasing). `reason` describes what was normalized.
+ * When `normalized` is true, the slug was auto-corrected from display-name
+ * form (spaces → dashes with lowercasing). Underscores are preserved — Sentry
+ * allows underscored project slugs and the CLI must not rewrite them.
  */
 export type ParsedOrgProject =
   | {
@@ -448,24 +401,18 @@ export type ParsedOrgProject =
       project: string;
       /** True if any slug was normalized */
       normalized?: boolean;
-      /** What was normalized — used for targeted warning messages */
-      reason?: NormalizeReason;
     }
   | {
       type: typeof ProjectSpecificationType.OrgAll;
       org: string;
       /** True if org slug was normalized */
       normalized?: boolean;
-      /** What was normalized — used for targeted warning messages */
-      reason?: NormalizeReason;
     }
   | {
       type: typeof ProjectSpecificationType.ProjectSearch;
       projectSlug: string;
       /** True if project slug was normalized */
       normalized?: boolean;
-      /** What was normalized — used for targeted warning messages */
-      reason?: NormalizeReason;
     }
   | { type: typeof ProjectSpecificationType.AutoDetect };
 
@@ -599,7 +546,7 @@ function parseSlashOrgProject(input: string): ParsedOrgProject {
     return {
       type: "project-search",
       projectSlug: np.slug,
-      ...(np.normalized && { normalized: true, reason: np.reason }),
+      ...(np.normalized && { normalized: true }),
     };
   }
 
@@ -612,7 +559,7 @@ function parseSlashOrgProject(input: string): ParsedOrgProject {
     return {
       type: "org-all",
       org: no.slug,
-      ...(no.normalized && { normalized: true, reason: no.reason }),
+      ...(no.normalized && { normalized: true }),
     };
   }
 
@@ -621,12 +568,11 @@ function parseSlashOrgProject(input: string): ParsedOrgProject {
   const np = normalizeSlug(rawProject);
   validateResourceId(np.slug, "project slug");
   const normalized = no.normalized || np.normalized;
-  const reason = normalized ? combineReasons(no.reason, np.reason) : undefined;
   return {
     type: "explicit",
     org: no.slug,
     project: np.slug,
-    ...(normalized && { normalized: true, reason }),
+    ...(normalized && { normalized: true }),
   };
 }
 
@@ -676,7 +622,7 @@ export function parseOrgProjectArg(arg: string | undefined): ParsedOrgProject {
     parsed = {
       type: "project-search",
       projectSlug: np.slug,
-      ...(np.normalized && { normalized: true, reason: np.reason }),
+      ...(np.normalized && { normalized: true }),
     };
   }
 

src/lib/trace-target.ts

@@ -47,7 +47,7 @@ export type ParsedTraceTarget =
       traceId: string;
       org: string;
       project: string;
-      /** True if any slug was normalized (underscores → dashes) */
+      /** True if any slug was normalized (spaces → dashes with lowercasing) */
       normalized?: boolean;
     }
   | {
@@ -267,7 +267,9 @@ export function targetArgToTraceTarget(
 export function warnIfNormalized(parsed: ParsedTraceTarget, tag: string): void {
   if ("normalized" in parsed && parsed.normalized) {
     const log = logger.withTag(tag);
-    log.warn("Normalized slug (Sentry slugs use dashes, not underscores)");
+    log.warn(
+      "Normalized slug (Sentry slugs use lowercase with dashes, not spaces)"
+    );
   }
 }
 

test/commands/event/view.test.ts

@@ -888,31 +888,6 @@ describe("viewCommand.func", () => {
     getLatestEventSpy.mockRestore();
   });
 
-  test("logs normalized slug warning when underscores present", async () => {
-    getEventSpy.mockResolvedValue(sampleEvent);
-    getSpanTreeLinesSpy.mockResolvedValue({
-      lines: [],
-      spans: null,
-      traceId: null,
-      success: false,
-    });
-    setOrgRegion("test-org", DEFAULT_SENTRY_URL);
-
-    const { context } = createMockContext();
-    const func = await viewCommand.loader();
-    // Underscores in the slug trigger normalized warning
-    await func.call(
-      context,
-      { json: true, web: false, spans: 0 },
-      "test_org/test_proj",
-      VALID_EVENT_ID
-    );
-
-    // parseOrgProjectArg normalizes "test_org/test_proj" → "test-org/test-proj"
-    // and sets normalized=true, triggering the warning path (line 343-345)
-    expect(getEventSpy).toHaveBeenCalled();
-  });
-
   test("throws ValidationError for flag-like event ID (--h)", async () => {
     const { context } = createMockContext();
     const func = await viewCommand.loader();

test/commands/init.test.ts

@@ -350,7 +350,8 @@ describe("init command func", () => {
     });
 
     test("org slug with whitespace is normalized (not rejected)", async () => {
-      // Spaces in slugs are normalized to dashes (like underscore normalization)
+      // Spaces in slugs are normalized to dashes — the "display name"
+      // recovery path (e.g., "My Org" → "my-org").
       const ctx = makeContext();
       await func.call(ctx, DEFAULT_FLAGS, "acme corp/");
       expect(capturedArgs?.org).toBe("acme-corp");

test/commands/log/view.test.ts

@@ -459,23 +459,6 @@ describe("viewCommand.func", () => {
     ).rejects.toThrow(ValidationError);
   });
 
-  test("logs normalized slug warning when underscores present", async () => {
-    getLogsSpy.mockResolvedValue([sampleLog]);
-    setOrgRegion("test-org", DEFAULT_SENTRY_URL);
-
-    const { context } = createMockContext();
-    const func = await viewCommand.loader();
-    // Underscores in the slug trigger normalized warning (line 161-163)
-    await func.call(
-      context,
-      { json: true, web: false },
-      "test_org/test_proj",
-      "968c763c740cfda8b6728f27fb9e9b01"
-    );
-
-    expect(getLogsSpy).toHaveBeenCalled();
-  });
-
   test("resolves project-search target via resolveProjectBySlug", async () => {
     findProjectsBySlugSpy.mockResolvedValue({
       projects: [

test/commands/trace/view.func.test.ts

@@ -348,24 +348,6 @@ describe("viewCommand.func", () => {
     expect(getDetailedTraceSpy).toHaveBeenCalled();
   });
 
-  test("logs normalized slug warning when underscores present", async () => {
-    getDetailedTraceSpy.mockResolvedValue(sampleSpans);
-
-    const { context } = createMockContext();
-    const func = await viewCommand.loader();
-    // Underscores in the slug trigger normalized warning (line 172-173)
-    await func.call(
-      context,
-      { json: true, web: false, spans: 100 },
-      "test_org/test_project",
-      "aaaa1111bbbb2222cccc3333dddd4444"
-    );
-
-    // parseOrgProjectArg normalizes "test_org/test_project" → "test-org/test-project"
-    // and sets normalized=true, triggering the log.warn (line 173)
-    expect(getDetailedTraceSpy).toHaveBeenCalled();
-  });
-
   test("logs suggestion when first arg looks like issue short ID", async () => {
     // "CAM-82X" as first arg matches issue short ID pattern.
     // parseOrgProjectArg("CAM-82X") → project-search, so we mock findProjectsBySlug.

test/lib/arg-parsing.property.test.ts

@@ -398,29 +398,44 @@ describe("normalizeSlug properties", () => {
     );
   });
 
-  test("normalized is true iff input contained underscores or spaces", async () => {
+  test("normalized is true iff input contained a space", async () => {
+    // Underscores are intentionally preserved (see #770) — only spaces
+    // trigger normalization.
     await fcAssert(
       property(displayNameLikeArb, (input) => {
         const result = normalizeSlug(input);
-        expect(result.normalized).toBe(
-          input.includes("_") || input.includes(" ")
-        );
+        expect(result.normalized).toBe(input.includes(" "));
       }),
       { numRuns: DEFAULT_NUM_RUNS }
     );
   });
 
-  test("result slug never contains underscores or spaces", async () => {
+  test("result slug never contains spaces", async () => {
     await fcAssert(
       property(displayNameLikeArb, (input) => {
         const result = normalizeSlug(input);
-        expect(result.slug.includes("_")).toBe(false);
         expect(result.slug.includes(" ")).toBe(false);
       }),
       { numRuns: DEFAULT_NUM_RUNS }
     );
   });
 
+  test("underscores in input survive to output unchanged in count", async () => {
+    // Each underscore in the input must appear in the output — normalization
+    // never rewrites underscores. Using a comparison on count makes the
+    // property robust to other transforms (lowercasing, space→dash) that
+    // may or may not happen depending on whether spaces are present.
+    await fcAssert(
+      property(displayNameLikeArb, (input) => {
+        const result = normalizeSlug(input);
+        const inputUnderscores = (input.match(/_/g) ?? []).length;
+        const outputUnderscores = (result.slug.match(/_/g) ?? []).length;
+        expect(outputUnderscores).toBe(inputUnderscores);
+      }),
+      { numRuns: DEFAULT_NUM_RUNS }
+    );
+  });
+
   test("result slug length is <= input length", async () => {
     await fcAssert(
       property(displayNameLikeArb, (input) => {
@@ -447,7 +462,7 @@ describe("normalizeSlug properties", () => {
       property(withSpaceArb, (input) => {
         const result = normalizeSlug(input);
         expect(result.slug).toBe(result.slug.toLowerCase());
-        expect(result.reason).toMatch(/^(spaces|both)$/);
+        expect(result.normalized).toBe(true);
       }),
       { numRuns: DEFAULT_NUM_RUNS }
     );