fix(typescript,python,csharp,java,php,ruby,unity,mcp): derive valid member names for underscore-digit enum values

.changesets/1790962042-cf634029.yaml

@@ -0,0 +1,18 @@
+id: 1790962042-cf634029
+features:
+    - enums
+targets:
+    - csharp
+    - javav2
+    - mcp-typescript
+    - mockserver
+    - php
+    - pythonv2
+    - ruby
+    - typescriptv2
+    - unity
+type: fix
+bump: patch
+description: derive valid enum member names for values that start with an underscore followed by digits; TypeScript and MCP TypeScript add a `numericEnumMemberNames` option that spells out digits-only values such as `_1` as `One` for new SDKs and keeps the numeric key for existing SDKs with union enums (native enums always spell digits out), Java applies the same derivation to `x-speakeasy-enums` overrides and OAuth2 scope names and detects member collisions on the emitted upper-snake name, the mockserver detects them on the emitted field name, values that share a derived name receive suffixes that are checked against every other member name in the enum, and `x-speakeasy-enums` override names are disambiguated as a group the same way
+author: AshGodfrey
+date: "2026-10-02"

templates/templates/csharp/includes/sanitization.ts

@@ -621,45 +621,46 @@ function getEnumName(value: string): string {
   }
 
   name = sanitizeName(name);
-  return caser().ToPascal(name);
+  name = caser().ToPascal(name);
+  if (/^[0-9]/.test(name)) {
+    name = caser().ToPascal(sanitizeName(name));
+  }
+  return name;
 }
 
 registerTemplateFunc("getEnumName", getEnumName);
 
 // @ts-ignore
 function getEnumNamesFromValues(values: string[]): string[] {
-  const enumNames = [];
-
-  const names = {};
-  if (!values) return enumNames;
-  values.forEach((value) => {
-    const name = getEnumName(value);
-    if (!names[name]) {
-      names[name] = 0;
-    }
+  if (!values) return [];
+  return disambiguateEnumNames(values, getEnumName).map((name) =>
+    sanitizeFieldName(name),
+  );
+}
 
-    names[name] += 1;
-  });
+function disambiguateEnumNames(
+  values: string[],
+  deriveName: (value: string) => string,
+): string[] {
+  const baseNames = values.map(deriveName);
+  const counts = new Map<string, number>();
+  for (const name of baseNames) {
+    counts.set(name, (counts.get(name) || 0) + 1);
+  }
 
-  const seen = {};
-  values.forEach((value) => {
-    let name = getEnumName(value);
-    if (names[name] > 1) {
-      let candidate = `${name}${caser().ToPascal(getCasing(value))}`;
-      if (seen[candidate]) {
-        let suffix = seen[candidate];
-        seen[candidate] += 1;
-        candidate = `${candidate}${suffix}`;
-      } else {
-        seen[candidate] = 1;
-      }
+  const used = new Set(baseNames.filter((name) => counts.get(name) === 1));
+  return values.map((value, i) => {
+    let name = baseNames[i];
+    if (counts.get(name) > 1) {
+      const candidate = `${name}${caser().ToPascal(getCasing(value))}`;
       name = candidate;
+      for (let suffix = 1; used.has(name); suffix++) {
+        name = `${candidate}${suffix}`;
+      }
+      used.add(name);
     }
-
-    enumNames.push(sanitizeFieldName(name));
+    return name;
   });
-
-  return enumNames;
 }
 
 registerTemplateFunc("getEnumNamesFromValues", getEnumNamesFromValues);

templates/templates/csharp/includes/templating.ts

@@ -859,7 +859,7 @@ function templateFloatValue(
 function getEnumNames(t: TypeDef): string[] {
   let names;
   if (t.Enum?.Names.length > 0) {
-    names = t.Enum.Names.map((n) => getEnumName(n));
+    names = disambiguateEnumNames(t.Enum.Names, getEnumName);
   } else {
     names = getEnumNamesFromValues(t.Enum?.Values);
   }

templates/templates/javav2/includes/enums.ts

@@ -70,7 +70,7 @@ function sanitizeEnumValue(value: any, type: GojaEnum<DataType>): string {
 
 function getEnumNames(t: TypeDef): string[] {
   if (t.Enum?.Names.length > 0) {
-    return t.Enum.Names.map((n) => getEnumName(n));
+    return disambiguateEnumNames(t.Enum.Names, getEnumName);
   } else {
     return getEnumNamesFromValues(t.Enum?.Values);
   }

templates/templates/javav2/includes/sanitization.ts

@@ -773,37 +773,44 @@ function findFieldExample(example: any, field: FieldDef): any {
 
 // @ts-ignore
 function getEnumNamesFromValues(values: string[]): string[] {
-  let enumNames = [];
-
-  let names = {};
-  for (const value of values) {
-    let name = getEnumName(value);
-    if (!names[name]) {
-      names[name] = 0;
-    }
+  // Count collisions on the emitted upper-snake member, not the intermediate
+  // Pascal name: `_1ST` and `1ST` derive `OneSt` and `OneST`, which differ,
+  // but both become `ONE_ST` once snake-cased.
+  return disambiguateEnumNames(
+    values,
+    (value) => sanitizeEnumMember(getEnumName(value)),
+    (value) =>
+      sanitizeEnumMember(
+        `${getEnumName(value)}${caser().ToPascal(getCasing(value))}`,
+      ),
+  );
+}
 
-    names[name] += 1;
+function disambiguateEnumNames(
+  values: string[],
+  deriveName: (value: string) => string,
+  deriveCandidate: (value: string, name: string) => string = (value, name) =>
+    `${name}${caser().ToPascal(getCasing(value))}`,
+): string[] {
+  const baseNames = values.map(deriveName);
+  const counts = new Map<string, number>();
+  for (const name of baseNames) {
+    counts.set(name, (counts.get(name) || 0) + 1);
   }
 
-  let seen = {};
-  for (const value of values) {
-    let name = getEnumName(value);
-    if (names[name] > 1) {
-      let candidate = `${name}${caser().ToPascal(getCasing(value))}`;
-      if (seen[candidate]) {
-        let suffix = seen[candidate];
-        seen[candidate] += 1;
-        candidate = `${candidate}${suffix}`;
-      } else {
-        seen[candidate] = 1;
-      }
+  const used = new Set(baseNames.filter((name) => counts.get(name) === 1));
+  return values.map((value, i) => {
+    let name = baseNames[i];
+    if (counts.get(name) > 1) {
+      const candidate = deriveCandidate(value, name);
       name = candidate;
+      for (let suffix = 1; used.has(name); suffix++) {
+        name = `${candidate}${suffix}`;
+      }
+      used.add(name);
     }
-
-    enumNames.push(sanitizeEnumMember(name));
-  }
-
-  return enumNames;
+    return name;
+  });
 }
 
 // Java-specific scope dedup that produces PascalCase names
@@ -854,9 +861,12 @@ function getEnumName(value: string): string {
     name = "Unknown";
   }
 
-  name = sanitizeName(name);
+  name = caser().ToPascal(sanitizeName(name));
+  if (/^[0-9]/.test(name)) {
+    name = caser().ToPascal(sanitizeName(name));
+  }
 
-  return caser().ToPascal(name);
+  return name;
 }
 
 // @ts-ignore

templates/templates/mcp-typescript/config.ts

@@ -422,6 +422,15 @@ function getConfigFields(
       ValidationRegex: /^(true|false)$/.source,
       ValidationMessage: "true or false only",
     },
+    numericEnumMemberNames: {
+      Name: "numericEnumMemberNames",
+      Required: false,
+      DefaultValue: newSDK ? "words" : "legacy",
+      Description:
+        'Member names for enum values that are only digits once a leading underscore is removed, such as `_1` or `_2024`. "words" spells the number out (`One`, `TwoThousandAndTwentyFour`); "legacy" (deprecated) keeps the numeric key (`1`, `2024`). Values with letters after the digits (`_1ST`) always become words.',
+      ValidationRegex: /^(words|legacy)$/.source,
+      ValidationMessage: "words or legacy only",
+    },
     validateResponse: {
       Name: "validateResponse",
       Required: false,

templates/templates/mcp-typescript/includes/sanitization.ts

@@ -164,7 +164,11 @@ function sanitizeEnumName(value: string): string {
 
   name = sanitizeName(name);
 
-  return caser().ToPascal(name);
+  name = caser().ToPascal(name);
+  if (/^[0-9]/.test(name) && !keepsNumericEnumMemberName(name)) {
+    name = caser().ToPascal(sanitizeName(name));
+  }
+  return name;
 }
 
 // @ts-ignore
@@ -401,18 +405,36 @@ function getEnumName(value) {
 
   name = sanitizeName(name);
 
-  return caser().ToPascal(name);
+  name = caser().ToPascal(name);
+  if (/^[0-9]/.test(name) && !keepsNumericEnumMemberName(name)) {
+    name = caser().ToPascal(sanitizeName(name));
+  }
+  return name;
 }
 
 registerTemplateFunc("getEnumName", getEnumName);
 
+// Matches a cased name that is a valid numeric literal property key in strict
+// mode: a decimal integer with an optional exponent, or a hex, binary or octal
+// literal. Leading zeros (`007`, `08`) are excluded because strict mode rejects
+// them, so those values are spelled out even under `legacy`.
+const numericLiteralKey =
+  /^(?:(?:0|[1-9][0-9]*)(?:[eE][0-9]+)?|0[xX][0-9a-fA-F]+|0[bB][01]+|0[oO][0-7]+)$/;
+
+function keepsNumericEnumMemberName(name: string): boolean {
+  return (
+    context.Global.Config.NumericEnumMemberNames === "legacy" &&
+    numericLiteralKey.test(name)
+  );
+}
+
 // @ts-ignore
 function getEnumNames(t: TypeDef): string[] {
   if (t.Enum?.Names.length > 0) {
     if (context.Global.Config.FixEnumNameSanitization === true) {
       return t.Enum.Names.map((n) => sanitizeName(n.trim() || "Unknown"));
     }
-    return t.Enum.Names.map((n) => getEnumName(n));
+    return getEnumNamesFromValues(t.Enum.Names);
   }
 
   return getEnumNamesFromValues(t.Enum?.Values);

templates/templates/mcp-typescript/includes/types.ts

@@ -116,28 +116,32 @@ function enumLiteralFromValue(
 }
 
 function getEnumNamesFromValues(values: string[]): string[] {
-  let enumNames = [];
-
-  let names = {};
-  for (const value of values) {
-    let name = sanitizeEnumName(value);
-    if (!names[name]) {
-      names[name] = 0;
-    }
+  return disambiguateEnumNames(values, sanitizeEnumName);
+}
 
-    names[name] += 1;
+function disambiguateEnumNames(
+  values: string[],
+  deriveName: (value: string) => string,
+): string[] {
+  const baseNames = values.map(deriveName);
+  const counts = new Map<string, number>();
+  for (const name of baseNames) {
+    counts.set(name, (counts.get(name) || 0) + 1);
   }
 
-  for (const value of values) {
-    let name = sanitizeEnumName(value);
-    if (names[name] > 1) {
-      name = `${name}${caser().ToPascal(getCasing(value))}`;
+  const used = new Set(baseNames.filter((name) => counts.get(name) === 1));
+  return values.map((value, i) => {
+    let name = baseNames[i];
+    if (counts.get(name) > 1) {
+      const candidate = `${name}${caser().ToPascal(getCasing(value))}`;
+      name = candidate;
+      for (let suffix = 1; used.has(name); suffix++) {
+        name = `${candidate}${suffix}`;
+      }
+      used.add(name);
     }
-
-    enumNames.push(name);
-  }
-
-  return enumNames;
+    return name;
+  });
 }
 
 function getEnumDataType(typeDef: TypeDef): "string" | "number" {

templates/templates/mockserver/includes/sanitization.ts

@@ -750,28 +750,43 @@ function templateFloatValue(
 
 // @ts-ignore
 function getEnumNamesFromValues(values: string[]): string[] {
-  let enumNames = [];
-
-  let names = {};
-  for (const value of values) {
-    let name = getEnumName(value);
-    if (!names[name]) {
-      names[name] = 0;
-    }
+  // Count collisions on the emitted field name, not the cased name:
+  // `_1ST` and `1ST` case to `1St` and `OneSt`, which differ, but both
+  // become `OneSt` once sanitizeFieldName rewrites the leading digit.
+  return disambiguateEnumNames(
+    values,
+    (value) => sanitizeFieldName(getEnumName(value)),
+    (value) =>
+      sanitizeFieldName(
+        `${getEnumName(value)}${caser().ToGoPascal(getCasing(value))}`,
+      ),
+  );
+}
 
-    names[name] += 1;
+function disambiguateEnumNames(
+  values: string[],
+  deriveName: (value: string) => string,
+  deriveCandidate: (value: string, name: string) => string,
+): string[] {
+  const baseNames = values.map(deriveName);
+  const counts = new Map<string, number>();
+  for (const name of baseNames) {
+    counts.set(name, (counts.get(name) || 0) + 1);
   }
 
-  for (const value of values) {
-    let name = getEnumName(value);
-    if (names[name] > 1) {
-      name = `${name}${caser().ToGoPascal(getCasing(value))}`;
+  const used = new Set(baseNames.filter((name) => counts.get(name) === 1));
+  return values.map((value, i) => {
+    let name = baseNames[i];
+    if (counts.get(name) > 1) {
+      const candidate = deriveCandidate(value, name);
+      name = candidate;
+      for (let suffix = 1; used.has(name); suffix++) {
+        name = `${candidate}${suffix}`;
+      }
+      used.add(name);
     }
-
-    enumNames.push(sanitizeFieldName(name));
-  }
-
-  return enumNames;
+    return name;
+  });
 }
 
 // @ts-ignore

templates/templates/php/includes/enums.ts

@@ -55,7 +55,7 @@ function sanitizeEnumValue(value: any, type: GojaEnum<DataType>): string {
 
 function getEnumNames(t: TypeDef): string[] {
   if (t.Enum?.Names.length > 0) {
-    return t.Enum.Names.map((n) => getEnumName(n));
+    return getEnumNamesFromValues(t.Enum.Names);
   } else {
     return getEnumNamesFromValues(t.Enum.Values);
   }