github.com/spf13/pflag v1.0.10: FlagSet.MarkDeprecated

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify FlagSet.MarkDeprecated in pkg:golang/github.com/spf13/pflag@v1.0.10
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/spf13/pflag@v1.0.10
Demonstrate these symbols/APIs:
  - FlagSet.MarkDeprecated

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:505678712bca24e09328c8da26573780cd02f616520b39ae251111078b1726a7","contract":["FlagSet.MarkDeprecated returns an error when called on a nonexistent flag","FlagSet.MarkDeprecated marks an existing flag with the given deprecation message and sets Hidden to true","FlagSet.MarkDeprecated hides the deprecated flag from FlagUsages output","FlagSet.MarkDeprecated causes FlagSet to print the deprecation warning to its output when the deprecated flag is parsed"],"goal":"verify FlagSet.MarkDeprecated in pkg:golang/github.com/spf13/pflag@v1.0.10","kind":"HOW","packages":["pkg:golang/github.com/spf13/pflag@v1.0.10"],"schemaVersion":1,"symbols":["FlagSet.MarkDeprecated"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/spf13/pflag@v1.0.10"],"schemaVersion":1,"subject":"pkg:golang/github.com/spf13/pflag@v1.0.10","symbols":["FlagSet.MarkDeprecated"],"verifierAdapter":"golang@1"}

module example.com/pflag-deprecated-sample

go 1.22

require github.com/spf13/pflag v1.0.10 // indirect

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

package main

import (
	"fmt"
	"os"

	"github.com/spf13/pflag"
)

func main() {
	flags := pflag.NewFlagSet("demo", pflag.ContinueOnError)

	var configPath string
	flags.StringVar(&configPath, "config", "default.yaml", "Path to configuration file")

	var legacyConfig string
	flags.StringVar(&legacyConfig, "legacy-config", "", "Old configuration path (deprecated)")

	// Mark the legacy flag as deprecated
	if err := flags.MarkDeprecated("legacy-config", "please use --config instead"); err != nil {
		fmt.Fprintf(os.Stderr, "Error marking flag as deprecated: %v\n", err)
		os.Exit(1)
	}

	if err := flags.Parse(os.Args[1:]); err != nil {
		fmt.Fprintf(os.Stderr, "Parse error: %v\n", err)
		os.Exit(1)
	}

	fmt.Printf("Config: %s\n", configPath)
}

{
  "schemaVersion": 1,
  "goal": "verify FlagSet.MarkDeprecated in pkg:golang/github.com/spf13/pflag@v1.0.10",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/spf13/pflag@v1.0.10"
  ],
  "symbols": [
    "FlagSet.MarkDeprecated"
  ]
}

package main

import (
	"bytes"
	"fmt"
	"os"
	"strings"

	"github.com/spf13/pflag"
)

func main() {
	var failures []string

	// Assertion 1: FlagSet.MarkDeprecated returns an error on nonexistent flag
	{
		fs := pflag.NewFlagSet("test", pflag.ContinueOnError)
		err := fs.MarkDeprecated("nonexistent", "use something else")
		if err == nil {
			failures = append(failures, "expected MarkDeprecated on nonexistent flag to return error, got nil")
		}
	}

	// Assertion 2: FlagSet.MarkDeprecated succeeds on existing flag and sets Deprecated message
	{
		fs := pflag.NewFlagSet("test", pflag.ContinueOnError)
		var val string
		fs.StringVar(&val, "old-opt", "", "Old option description")
		err := fs.MarkDeprecated("old-opt", "please use --new-opt instead")
		if err != nil {
			failures = append(failures, fmt.Sprintf("MarkDeprecated failed unexpectedly: %v", err))
		}

		fl := fs.Lookup("old-opt")
		if fl == nil {
			failures = append(failures, "flag old-opt was not found in FlagSet")
		} else {
			if fl.Deprecated != "please use --new-opt instead" {
				failures = append(failures, fmt.Sprintf("expected Deprecated message 'please use --new-opt instead', got %q", fl.Deprecated))
			}
			if !fl.Hidden {
				failures = append(failures, "expected deprecated flag to have Hidden=true")
			}
		}
	}

	// Assertion 3: Deprecated flag is hidden from FlagUsages output
	{
		fs := pflag.NewFlagSet("test", pflag.ContinueOnError)
		var val1, val2 string
		fs.StringVar(&val1, "active", "def", "Active flag description")
		fs.StringVar(&val2, "deprecated-flag", "", "Deprecated flag description")
		if err := fs.MarkDeprecated("deprecated-flag", "use active"); err != nil {
			failures = append(failures, fmt.Sprintf("MarkDeprecated error: %v", err))
		}

		usages := fs.FlagUsages()
		if strings.Contains(usages, "deprecated-flag") {
			failures = append(failures, "expected FlagUsages to hide deprecated flag, but found it in usages output")
		}
		if !strings.Contains(usages, "active") {
			failures = append(failures, "expected FlagUsages to include active flag, but missing")
		}
	}

	// Assertion 4: Parsing deprecated flag emits deprecation warning to FlagSet output
	{
		fs := pflag.NewFlagSet("test", pflag.ContinueOnError)
		var outBuf bytes.Buffer
		fs.SetOutput(&outBuf)

		var legacyVal string
		fs.StringVar(&legacyVal, "legacy", "", "Legacy option")
		if err := fs.MarkDeprecated("legacy", "please use --modern instead"); err != nil {
			failures = append(failures, fmt.Sprintf("MarkDeprecated error: %v", err))
		}

		if err := fs.Parse([]string{"--legacy", "test-val"}); err != nil {
			failures = append(failures, fmt.Sprintf("Parse error: %v", err))
		}

		if legacyVal != "test-val" {
			failures = append(failures, fmt.Sprintf("expected legacyVal to be 'test-val', got %q", legacyVal))
		}

		output := outBuf.String()
		if !strings.Contains(output, "Flag --legacy has been deprecated, please use --modern instead") {
			failures = append(failures, fmt.Sprintf("expected deprecation message in output, got %q", output))
		}
	}

	if len(failures) > 0 {
		fmt.Fprintf(os.Stderr, "Contract verification failed with %d error(s):\n", len(failures))
		for i, f := range failures {
			fmt.Fprintf(os.Stderr, "  %d. %s\n", i+1, f)
		}
		os.Exit(1)
	}

	fmt.Println("All FlagSet.MarkDeprecated contract assertions passed.")
}