fix(config): append numeric bound hints to ceiling/floor validation errors (#84852)

tanshanshan · tanshanshan · claude · web-flow · commit 8a8f9dc8cb77 · 2026-05-21T17:44:29.000+08:00
* fix(config): append numeric bound hints to ceiling/floor validation errors When a config value exceeds a schema-enforced ceiling or falls below a floor, the error message now includes the constraint explicitly: - Inclusive: `(maximum: 20)` / `(minimum: 0)` - Exclusive: `(must be less than 5)` / `(must be greater than 0)` This matches the clarity that enum/union rejections already get via `(allowed: …)` hints, and avoids the misleading "minimum: 0" wording that previous attempts produced for `.positive()` / `.gt(0)` rejections. Only numeric-origin `too_big`/`too_small` issues are enriched; string, array, and file-size origins are left unchanged. Fixes #52500 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * test(config): update maxFileBytes test for numeric bound hint The test snapshot for `logging.maxFileBytes: 0` rejection now includes the `(must be greater than 0)` hint appended by the numeric bound enrichment added in the previous commit. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(config): guard nullable record in appendNumericBoundHint call ClawSweeper P1: `record` from `toIssueRecord()` can be null, but `appendNumericBoundHint` expects a non-null `UnknownIssueRecord`. Guard with a ternary so the original message is returned when record is null (which only happens for malformed/empty issues that already produce generic "Invalid input" messages). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: tanshanshan <tanshanshan@users.noreply.github.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
diff --git a/src/config/logging-max-file-bytes.test.ts b/src/config/logging-max-file-bytes.test.ts
@@ -22,7 +22,7 @@ describe("logging.maxFileBytes config", () => {
       expect(res.issues).toEqual([
         {
           path: "logging.maxFileBytes",
-          message: "Too small: expected number to be >0",
+          message: "Too small: expected number to be >0 (must be greater than 0)",
         },
       ]);
     }
diff --git a/src/config/validation.allowed-values.test.ts b/src/config/validation.allowed-values.test.ts
@@ -146,3 +146,45 @@ describe("config validation allowed-values metadata", () => {
     }
   });
 });
+
+describe("config validation numeric bound hints", () => {
+  it("appends maximum for inclusive too_big numeric bound", () => {
+    const issue = mapFirstIssue(
+      z.object({ maxPingPongTurns: z.number().int().min(0).max(20).optional() }),
+      { maxPingPongTurns: 50 },
+    );
+    expect(issue.path).toBe("maxPingPongTurns");
+    expect(issue.message).toContain("(maximum: 20)");
+    expect(issue.allowedValues).toBeUndefined();
+  });
+
+  it("appends 'must be less than' for exclusive too_big numeric bound", () => {
+    const issue = mapFirstIssue(z.object({ rate: z.number().lt(5) }), { rate: 5 });
+    expect(issue.path).toBe("rate");
+    expect(issue.message).toContain("(must be less than 5)");
+    expect(issue.message).not.toContain("(maximum: 5)");
+  });
+
+  it("appends 'must be greater than' for exclusive too_small numeric bound (positive/gt)", () => {
+    const issue = mapFirstIssue(z.object({ count: z.number().positive() }), { count: 0 });
+    expect(issue.path).toBe("count");
+    expect(issue.message).toContain("(must be greater than 0)");
+    expect(issue.message).not.toContain("(minimum: 0)");
+  });
+
+  it("appends minimum for inclusive too_small numeric bound", () => {
+    const issue = mapFirstIssue(z.object({ retries: z.number().min(0) }), { retries: -1 });
+    expect(issue.path).toBe("retries");
+    expect(issue.message).toContain("(minimum: 0)");
+  });
+
+  it("does not append numeric bound hints for non-number origins (string)", () => {
+    const issue = mapFirstIssue(z.object({ name: z.string().max(10) }), {
+      name: "abcdefghijklmnop",
+    });
+    expect(issue.path).toBe("name");
+    expect(issue.message).not.toContain("(maximum:");
+    expect(issue.message).not.toContain("(must be less than");
+    expect(issue.allowedValues).toBeUndefined();
+  });
+});
diff --git a/src/config/validation.ts b/src/config/validation.ts
@@ -317,6 +317,31 @@ function collectAllowedValuesFromCustomIssue(record: UnknownIssueRecord): Allowe
   return collectAllowedValuesFromBundledChannelSchemaPath(toConfigPathSegments(record.path));
 }
 
+function appendNumericBoundHint(message: string, record: UnknownIssueRecord): string {
+  const origin = typeof record.origin === "string" ? record.origin : "";
+  if (origin !== "number") {
+    return message;
+  }
+  const inclusive = record.inclusive === true;
+  if (record.code === "too_big") {
+    const maximum = typeof record.maximum === "number" ? record.maximum : undefined;
+    if (maximum !== undefined) {
+      return inclusive
+        ? `${message} (maximum: ${maximum})`
+        : `${message} (must be less than ${maximum})`;
+    }
+  }
+  if (record.code === "too_small") {
+    const minimum = typeof record.minimum === "number" ? record.minimum : undefined;
+    if (minimum !== undefined) {
+      return inclusive
+        ? `${message} (minimum: ${minimum})`
+        : `${message} (must be greater than ${minimum})`;
+    }
+  }
+  return message;
+}
+
 function collectAllowedValuesFromIssue(issue: unknown): AllowedValuesCollection {
   const record = toIssueRecord(issue);
   if (!record) {
@@ -581,6 +606,11 @@ function mapZodIssueToConfigIssue(issue: unknown): ConfigValidationIssue {
   const path = formatConfigPath(toConfigPathSegments(record?.path));
   const message = typeof record?.message === "string" ? record.message : "Invalid input";
 
+  // Numeric ceiling/floor hints (too_big / too_small with numeric origin).
+  // Append a parenthesized bound alongside Zod's native message,
+  // matching the clarity that enum/union rejections get via (allowed: …).
+  const enrichedMessage = record ? appendNumericBoundHint(message, record) : message;
+
   const allowedValuesSummary = summarizeAllowedValues(collectAllowedValuesFromUnknownIssue(issue));
 
   // Bindings use a plain union because legacy route bindings may omit `type`.
@@ -599,12 +629,12 @@ function mapZodIssueToConfigIssue(issue: unknown): ConfigValidationIssue {
   }
 
   if (!allowedValuesSummary) {
-    return { path, message };
+    return { path, message: enrichedMessage };
   }
 
   return {
     path,
-    message: appendAllowedValuesHint(message, allowedValuesSummary),
+    message: appendAllowedValuesHint(enrichedMessage, allowedValuesSummary),
     allowedValues: allowedValuesSummary.values,
     allowedValuesHiddenCount: allowedValuesSummary.hiddenCount,
   };

Original file line number	Diff line number	Diff line change
`@@ -22,7 +22,7 @@ describe("logging.maxFileBytes config", () => {`
`22`	`22`	`expect(res.issues).toEqual([`
`23`	`23`	`{`
`24`	`24`	`path: "logging.maxFileBytes",`
`25`		`- message: "Too small: expected number to be >0",`
	`25`	`+ message: "Too small: expected number to be >0 (must be greater than 0)",`
`26`	`26`	`},`
`27`	`27`	`]);`
`28`	`28`	`}`