Fix parameter index not incrementing in nested subcommands (#32)

## Fix for Nested Subcommand Parameter Bug ✅ COMPLETE

- [x] Identified the bug: `_paramIndex` is not incremented when
parameters are matched
- [x] Determine the best place to increment `_paramIndex` 
- [x] Implement the fix to increment `_paramIndex` after reading a
parameter value
- [x] Run the failing test to verify the fix works
- [x] Run all tests to ensure no regressions
- [x] Review and commit the changes
- [x] Code review - no issues found
- [x] Security scan - no vulnerabilities found
- [x] Manual verification - confirmed fix works
- [x] Refactored to remove side effects from CheckFields method
- [x] Replaced tuple booleans with FieldKind enum for better clarity

## Summary

Successfully fixed the bug where multiple command parameters in nested
subcommands failed to parse correctly. The second parameter was being
treated as a duplicate of the first, causing a "Duplicate key" error.

### Root Cause
The `_paramIndex` field in `Deserializer.cs` was never incremented when
a parameter was matched in the `CheckFields` method. This caused all
parameters to match against ordinal 0, resulting in duplicate field
assignments.

### Changes Made

1. **Test File** (`test/Serde.CmdLine.Test/SubCommandTests.cs`):
   - Added `NestedSubCommandWithTwoParameters` test case
- Creates a `copy` subcommand with two parameters: `source` and
`destination`
   - Tests parsing: `["copy", "source.txt", "dest.txt"]`

2. **Bug Fix** (`src/Serde.CmdLine/Deserializer.DeserializeType.cs`):
- Modified `CheckFields` signature to return `(int fieldIndex, FieldKind
fieldKind)`
   - Returns `FieldKind` enum indicating the type of field matched
- Caller uses switch statement to increment appropriate index based on
field kind
   - `CheckFields` is side-effect free, following established patterns

3. **New Type** (`src/Serde.CmdLine/OptionTypes.cs`):
- Added `FieldKind` enum with values: None, Option, SubCommand,
CommandGroup, Parameter
- Each value is documented with its behavior regarding index increments
   - Provides clearer semantic meaning than tuple of booleans

### Verification

✅ **Unit Tests**
- New test `NestedSubCommandWithTwoParameters` passes
- All 21 CmdLine tests pass
- All 4 Analyzer tests pass

✅ **Code Design**
- `CheckFields` is side-effect free
- Uses enum instead of tuple booleans for better readability and
maintainability
- Switch statement clearly maps field kinds to their required index
increments
- Follows the established pattern where method returns signals and
caller handles state mutations

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for
you](https://github.com/serdedotnet/serde.cmdline/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot)
— coding agent works faster and does higher quality work when set up for
your repo.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: agocke <515774+agocke@users.noreply.github.com>

Author: Copilot

src/Serde.CmdLine/Deserializer.DeserializeType.cs

@@ -55,12 +55,19 @@ private int TryReadIndex(ISerdeInfo serdeInfo)
                     continue;
                 }
 
-                var (fieldIndex, incArgs) = CheckFields(arg);
+                var (fieldIndex, fieldKind) = CheckFields(arg);
                 if (fieldIndex >= 0)
                 {
-                    if (incArgs)
+                    // Increment indices based on field type
+                    switch (fieldKind)
                     {
-                        argIndex++;
+                        case FieldKind.Option:
+                        case FieldKind.SubCommand:
+                            argIndex++;
+                            break;
+                        case FieldKind.Parameter:
+                            _deserializer._paramIndex++;
+                            break;
                     }
                     return fieldIndex;
                 }
@@ -156,21 +163,21 @@ int ITypeDeserializer.TryReadIndex(ISerdeInfo info)
             return null;
         }
 
-        private (int fieldIndex, bool incArgs) CheckFields(string arg)
+        private (int fieldIndex, FieldKind fieldKind) CheckFields(string arg)
         {
             var cmd = _command;
             if (arg.StartsWith('-'))
             {
                 var fieldIndex = CheckOptions(cmd, arg)?.FieldIndex ?? -1;
-                return (fieldIndex, fieldIndex >= 0);
+                return (fieldIndex, fieldIndex >= 0 ? FieldKind.Option : FieldKind.None);
             }
 
             // Check for command group matches
             foreach (var subCmd in cmd.SubCommands)
             {
                 if (arg == subCmd.Name)
                 {
-                    return (subCmd.FieldIndex, true);
+                    return (subCmd.FieldIndex, FieldKind.SubCommand);
                 }
             }
 
@@ -180,7 +187,7 @@ int ITypeDeserializer.TryReadIndex(ISerdeInfo info)
                 {
                     if (name == arg)
                     {
-                        return (cmdGroup.FieldIndex, false);
+                        return (cmdGroup.FieldIndex, FieldKind.CommandGroup);
                     }
                 }
 
@@ -193,10 +200,10 @@ int ITypeDeserializer.TryReadIndex(ISerdeInfo info)
                 // Parameters are positional, so we check the current param index
                 if (_deserializer._paramIndex == param.Ordinal)
                 {
-                    return (param.FieldIndex, false);
+                    return (param.FieldIndex, FieldKind.Parameter);
                 }
             }
-            return (-1, false);
+            return (-1, FieldKind.None);
         }
 
         public static Command ParseCommand(ISerdeInfo serdeInfo)

src/Serde.CmdLine/OptionTypes.cs

@@ -3,6 +3,30 @@
 
 namespace Serde.CmdLine;
 
+internal enum FieldKind
+{
+    /// <summary>
+    /// No field matched
+    /// </summary>
+    None,
+    /// <summary>
+    /// An option field matched (requires incrementing arg index)
+    /// </summary>
+    Option,
+    /// <summary>
+    /// A subcommand field matched (requires incrementing arg index)
+    /// </summary>
+    SubCommand,
+    /// <summary>
+    /// A command group field matched (does not increment arg index)
+    /// </summary>
+    CommandGroup,
+    /// <summary>
+    /// A parameter field matched (requires incrementing param index)
+    /// </summary>
+    Parameter
+}
+
 internal record struct Option(
     ImmutableArray<string> FlagNames,
     int FieldIndex,

test/Serde.CmdLine.Test/SubCommandTests.cs

@@ -191,4 +191,47 @@ public sealed partial record FirstCommand : SubCommand
         [Command("second")]
         public sealed partial record SecondCommand : SubCommand;
     }
+
+    /// <summary>
+    /// Test to verify that two command parameters in a nested subcommand are parsed correctly.
+    /// This test is designed to reproduce a bug where the second parameter is parsed as a
+    /// duplicate of the first parameter due to _paramIndex not being incremented.
+    /// </summary>
+    [Fact]
+    public void NestedSubCommandWithTwoParameters()
+    {
+        string[] testArgs = [ "copy", "source.txt", "dest.txt" ];
+        var cmd = CmdLine.ParseRawWithHelp<CommandWithParams>(testArgs).Unwrap();
+        Assert.Equal(new CommandWithParams
+        {
+            SubCommandWithParams = new SubCommandWithParams.CopyCommand
+            {
+                Source = "source.txt",
+                Destination = "dest.txt"
+            }
+        }, cmd);
+    }
+
+    [GenerateDeserialize]
+    private partial record CommandWithParams
+    {
+        [CommandGroup("command")]
+        public SubCommandWithParams? SubCommandWithParams { get; init; }
+    }
+
+    [GenerateDeserialize]
+    private abstract partial record SubCommandWithParams
+    {
+        private SubCommandWithParams() { }
+
+        [Command("copy")]
+        public sealed partial record CopyCommand : SubCommandWithParams
+        {
+            [CommandParameter(0, "source")]
+            public string? Source { get; init; }
+
+            [CommandParameter(1, "destination")]
+            public string? Destination { get; init; }
+        }
+    }
 }