github.com/spf13/pflag v1.0.10: FlagSet parses interspersed flags and positional arguments by default and preserves unparsed flags as positional arguments when SetInterspersed is false

# Pflag SetInterspersed Argument Parsing

## Prior Known Solutions
Querying known solutions for `github.com/spf13/pflag` returned:
- `sha256:c9dd90f107cef94c692f4dacfe5493d77b1416bcc38e116f18a0e4fc768304dc` (handling of wrapped `ErrHelp` under `ExitOnError`)
- `sha256:cc2c397664e089bf5638765dcfb834232cd669f9970283902c9b8947b773b043` (`NoOptDefVal` behavior with space-separated arguments)

This sample targets a different behavior: `FlagSet.SetInterspersed` controlling whether flag parsing stops at the first positional argument or allows flags to be interspersed anywhere in the argument slice.

## Pinned Release
- Package: `github.com/spf13/pflag`
- Version: `v1.0.10`

## Observed Behavior
1. By default, `pflag.FlagSet` has interspersed parsing enabled. Flags specified after positional arguments (e.g., `pos1 --flag value pos2`) are parsed, and non-flag arguments are collected in `FlagSet.Args()`.
2. Calling `FlagSet.SetInterspersed(false)` disables interspersed mode and enforces POSIX-style parsing: flag parsing stops immediately when the first non-flag positional argument is encountered.
3. Any flags appearing after the first positional argument remain unparsed (flag variables retain their default values, and `FlagSet.Changed()` returns `false`), while all remaining arguments from that point forward are preserved as positional arguments in `FlagSet.Args()`.

{"case":{"caseId":"case:sha256:deaad881697bf719aad08b8384e0c08d4c6df0302a90b2c15fa2b2373e667cac","contract":["FlagSet parses flags interspersed with positional arguments by default and collects non-flag arguments in Args.","Calling FlagSet.SetInterspersed(false) stops flag parsing upon reaching the first positional argument, retaining subsequent flags unparsed in Args."],"goal":"FlagSet parses interspersed flags and positional arguments by default and preserves unparsed flags as positional arguments when SetInterspersed is false","kind":"HOW","packages":["pkg:golang/github.com/spf13/pflag@v1.0.10"],"schemaVersion":1,"symbols":["FlagSet.SetInterspersed","FlagSet.Parse","FlagSet.Args"]},"contractCommand":["go","test","./..."],"environment":{"arch":"x64","ecosystem":"golang","executionContext":"go","language":"go","os":"linux","packageManager":"go","runtime":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/spf13/pflag@v1.0.10"],"schemaVersion":1,"symbols":["FlagSet.SetInterspersed","FlagSet.Parse","FlagSet.Args"],"verifierAdapter":"golang@1"}

module example.com/pflag-interspersed

go 1.22

require github.com/spf13/pflag v1.0.10

github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=

package main

import (
	"reflect"
	"testing"

	"github.com/spf13/pflag"
)

func TestDefaultInterspersedFlagParsing(t *testing.T) {
	fs := pflag.NewFlagSet("test_interspersed", pflag.ContinueOnError)
	name := fs.String("name", "default_name", "user name")
	verbose := fs.BoolP("verbose", "v", false, "verbose output")
	count := fs.Int("count", 0, "item count")

	args := []string{"pos1", "--name=custom", "pos2", "-v", "--count", "5", "pos3"}
	if err := fs.Parse(args); err != nil {
		t.Fatalf("unexpected parse error: %v", err)
	}

	if *name != "custom" {
		t.Fatalf("expected name 'custom', got %q", *name)
	}
	if !fs.Changed("name") {
		t.Fatalf("expected name to be marked as changed")
	}

	if *verbose != true {
		t.Fatalf("expected verbose true, got false")
	}
	if !fs.Changed("verbose") {
		t.Fatalf("expected verbose to be marked as changed")
	}

	if *count != 5 {
		t.Fatalf("expected count 5, got %d", *count)
	}
	if !fs.Changed("count") {
		t.Fatalf("expected count to be marked as changed")
	}

	expectedArgs := []string{"pos1", "pos2", "pos3"}
	if !reflect.DeepEqual(fs.Args(), expectedArgs) {
		t.Fatalf("expected positional args %v, got %v", expectedArgs, fs.Args())
	}
	if fs.NArg() != 3 {
		t.Fatalf("expected NArg() to be 3, got %d", fs.NArg())
	}
	if fs.Arg(0) != "pos1" || fs.Arg(1) != "pos2" || fs.Arg(2) != "pos3" {
		t.Fatalf("unexpected individual args: %q, %q, %q", fs.Arg(0), fs.Arg(1), fs.Arg(2))
	}
}

func TestSetInterspersedFalseStopsAtFirstPositional(t *testing.T) {
	fs := pflag.NewFlagSet("test_strict_posix", pflag.ContinueOnError)
	name := fs.String("name", "default_name", "user name")
	verbose := fs.BoolP("verbose", "v", false, "verbose output")
	count := fs.Int("count", 0, "item count")

	fs.SetInterspersed(false)

	args := []string{"--name=custom", "pos1", "-v", "--count=5", "pos2"}
	if err := fs.Parse(args); err != nil {
		t.Fatalf("unexpected parse error: %v", err)
	}

	if *name != "custom" {
		t.Fatalf("expected name 'custom', got %q", *name)
	}
	if !fs.Changed("name") {
		t.Fatalf("expected name to be marked as changed")
	}

	// Flags after the first non-flag positional argument must not be parsed
	if *verbose != false {
		t.Fatalf("expected verbose false (unparsed), got true")
	}
	if fs.Changed("verbose") {
		t.Fatalf("expected verbose not changed")
	}

	if *count != 0 {
		t.Fatalf("expected count 0 (unparsed), got %d", *count)
	}
	if fs.Changed("count") {
		t.Fatalf("expected count not changed")
	}

	expectedArgs := []string{"pos1", "-v", "--count=5", "pos2"}
	if !reflect.DeepEqual(fs.Args(), expectedArgs) {
		t.Fatalf("expected positional args %v, got %v", expectedArgs, fs.Args())
	}
	if fs.NArg() != 4 {
		t.Fatalf("expected NArg() to be 4, got %d", fs.NArg())
	}
}

func TestSetInterspersedFalseWithLeadingPositional(t *testing.T) {
	fs := pflag.NewFlagSet("test_leading_pos", pflag.ContinueOnError)
	name := fs.String("name", "default_name", "user name")
	fs.SetInterspersed(false)

	args := []string{"command", "--name=custom"}
	if err := fs.Parse(args); err != nil {
		t.Fatalf("unexpected parse error: %v", err)
	}

	if *name != "default_name" {
		t.Fatalf("expected name 'default_name', got %q", *name)
	}
	if fs.Changed("name") {
		t.Fatalf("expected name not changed")
	}

	expectedArgs := []string{"command", "--name=custom"}
	if !reflect.DeepEqual(fs.Args(), expectedArgs) {
		t.Fatalf("expected positional args %v, got %v", expectedArgs, fs.Args())
	}
}