fix(scripts): align feature number range

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: marcelsafin

scripts/bash/create-new-feature.sh

@@ -202,6 +202,25 @@ if [ "$USE_TIMESTAMP" = true ]; then
     FEATURE_NUM=$(date +%Y%m%d-%H%M%S)
     BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
 else
+    # Bash arithmetic is signed 64-bit; reject digit strings that would wrap.
+    if [[ "$BRANCH_NUMBER" =~ ^[0-9]+$ ]]; then
+        MAX_FEATURE_NUMBER=9223372036854775807
+        NORMALIZED_BRANCH_NUMBER="${BRANCH_NUMBER#"${BRANCH_NUMBER%%[!0]*}"}"
+        [ -n "$NORMALIZED_BRANCH_NUMBER" ] || NORMALIZED_BRANCH_NUMBER=0
+        NUMBER_TOO_LARGE=false
+        if [ ${#NORMALIZED_BRANCH_NUMBER} -gt ${#MAX_FEATURE_NUMBER} ]; then
+            NUMBER_TOO_LARGE=true
+        elif [ ${#NORMALIZED_BRANCH_NUMBER} -eq ${#MAX_FEATURE_NUMBER} ]; then
+            # Equal-length digit strings must be compared without arithmetic overflow.
+            # shellcheck disable=SC2071
+            [[ "$NORMALIZED_BRANCH_NUMBER" > "$MAX_FEATURE_NUMBER" ]] && NUMBER_TOO_LARGE=true
+        fi
+        if $NUMBER_TOO_LARGE; then
+            echo "Error: --number must be between 0 and $MAX_FEATURE_NUMBER, got '$BRANCH_NUMBER'" >&2
+            exit 1
+        fi
+    fi
+
     # Determine branch number from existing feature directories
     if [ -z "$BRANCH_NUMBER" ]; then
         HIGHEST=$(get_highest_from_specs "$SPECS_DIR")

scripts/powershell/create-new-feature.ps1

@@ -142,10 +142,11 @@ if ($ShortName) {
     $branchSuffix = Get-BranchName -Description $featureDesc
 }
 
-# Warn if -Number and -Timestamp are both specified. Use ContainsKey (not
-# `-ne 0`) so an explicit `-Number 0` is also detected, matching the bash twin's
-# `[ -n "$BRANCH_NUMBER" ]` check.
-if ($Timestamp -and $PSBoundParameters.ContainsKey('Number')) {
+# Treat an explicit empty string as omitted, matching the bash and Python twins.
+$hasNumber = $PSBoundParameters.ContainsKey('Number') -and $Number -ne ''
+
+# Warn if -Number and -Timestamp are both specified.
+if ($Timestamp -and $hasNumber) {
     Write-Warning "[specify] Warning: -Number is ignored when -Timestamp is used"
     $Number = ''
 }
@@ -159,7 +160,7 @@ if ($Timestamp) {
     # when -Number was not supplied; an explicit value (including 0) is honored,
     # matching the bash twin's `[ -z "$BRANCH_NUMBER" ]` check.
     [long]$resolvedNumber = 0
-    if (-not $PSBoundParameters.ContainsKey('Number')) {
+    if (-not $hasNumber) {
         $resolvedNumber = (Get-HighestNumberFromSpecs -SpecsDir $specsDir) + 1
     } elseif ($Number -notmatch '^[0-9]+$' -or -not [long]::TryParse($Number, [ref]$resolvedNumber)) {
         Write-Error "Error: -Number must be an unsigned integer, got '$Number'"

scripts/python/create_new_feature.py

@@ -32,6 +32,7 @@ def _json_line(payload: object) -> str:
 )
 
 _MAX_BRANCH_LENGTH = 244
+_MAX_FEATURE_NUMBER = 2**63 - 1
 
 
 def _usage(argv0: str) -> str:
@@ -219,6 +220,13 @@ def main(argv: list[str] | None = None) -> int:
                 )
                 return 1
             number = int(normalized_number, 10)
+            if number > _MAX_FEATURE_NUMBER:
+                print(
+                    "Error: --number must be between 0 and "
+                    f"{_MAX_FEATURE_NUMBER}, got '{branch_number}'",
+                    file=sys.stderr,
+                )
+                return 1
         else:
             number = _get_highest_from_specs(specs_dir) + 1
         feature_num = f"{number:03d}"

tests/test_create_new_feature_python_parity.py

@@ -402,3 +402,63 @@ def test_all_variants_reject_signed_number(repo: Path, number: str) -> None:
     )
 
     assert bash.returncode == ps.returncode == py.returncode == 1
+
+
+@requires_bash
+@pytest.mark.skipif(not HAS_POWERSHELL, reason="no PowerShell available")
+@pytest.mark.parametrize("timestamp", [False, True], ids=["numbered", "timestamp"])
+def test_all_variants_treat_empty_number_as_omitted(
+    repo: Path, timestamp: bool
+) -> None:
+    bash_args = ["--json", "--dry-run", "--number", ""]
+    ps_args = ["-Json", "-DryRun", "-Number", ""]
+    py_args = ["--json", "--dry-run", "--number", ""]
+    if timestamp:
+        bash_args.append("--timestamp")
+        ps_args.append("-Timestamp")
+        py_args.append("--timestamp")
+    bash_args.append("x")
+    ps_args.append("x")
+    py_args.append("x")
+
+    bash = run(bash_cmd(repo, SCRIPT, *bash_args), repo)
+    ps = run(ps_cmd(repo, SCRIPT, *ps_args), repo)
+    py = run(py_cmd(repo, SCRIPT, *py_args), repo)
+
+    assert bash.returncode == ps.returncode == py.returncode == 0
+    assert bash.stderr == ps.stderr == py.stderr == ""
+    if not timestamp:
+        assert json_stdout(bash) == json_stdout(ps) == json_stdout(py)
+
+
+@requires_bash
+@pytest.mark.skipif(not HAS_POWERSHELL, reason="no PowerShell available")
+@pytest.mark.parametrize(
+    ("number", "returncode"),
+    [
+        (str(2**63 - 1), 0),
+        (str(2**63), 1),
+    ],
+    ids=["int64_max", "int64_overflow"],
+)
+def test_all_variants_share_int64_number_range(
+    repo: Path, number: str, returncode: int
+) -> None:
+    bash = run(
+        bash_cmd(repo, SCRIPT, "--json", "--dry-run", "--number", number, "x"),
+        repo,
+    )
+    ps = run(
+        ps_cmd(repo, SCRIPT, "-Json", "-DryRun", "-Number", number, "x"),
+        repo,
+    )
+    py = run(
+        py_cmd(repo, SCRIPT, "--json", "--dry-run", "--number", number, "x"),
+        repo,
+    )
+
+    assert bash.returncode == ps.returncode == py.returncode == returncode
+    if returncode == 0:
+        assert json_stdout(bash) == json_stdout(ps) == json_stdout(py)
+    else:
+        assert bash.stdout == ps.stdout == py.stdout == ""