Merge branch 'main' into support-overridden-attributes

Author: natemcmaster

.config/dotnet-tools.json

@@ -7,6 +7,12 @@
       "commands": [
         "dotnet-format"
       ]
+    },
+    "docfx": {
+      "version": "2.78.4",
+      "commands": [
+        "docfx"
+      ]
     }
   }
 }

.github/dependabot.yml

@@ -0,0 +1,46 @@
+version: 2
+updates:
+  # NuGet packages - patch updates only for LTS stability
+  - package-ecosystem: "nuget"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    ignore:
+      # Only allow patch updates (ignore minor and major)
+      - dependency-name: "*"
+        update-types:
+          - "version-update:semver-major"
+          - "version-update:semver-minor"
+    groups:
+      nuget-patch:
+        patterns:
+          - "*"
+
+  # Sample and test projects - allow all updates (latest versions)
+  - package-ecosystem: "nuget"
+    directories:
+      - "/docs/samples"
+      - "/test"
+    schedule:
+      interval: "monthly"
+    groups:
+      microsoft-extensions:
+        patterns:
+          - "Microsoft.Extensions.*"
+      test-dependencies:
+        patterns:
+          - "Microsoft.NET.Test.Sdk"
+          - "xunit*"
+          - "coverlet*"
+          - "Moq"
+          - "FluentAssertions"
+
+  # GitHub Actions - monthly updates
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "quarterly"
+    groups:
+      github-actions:
+        patterns:
+          - "*"

.github/workflows/ci.yml

@@ -33,23 +33,24 @@ jobs:
       package_version: ${{ steps.build_script.outputs.package_version }}
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Setup .NET
-        uses: actions/setup-dotnet@v4
+        uses: actions/setup-dotnet@v5
         with:
           dotnet-version: |
-            6.0.x
-            8.0.x
+            8.x
+            9.x
+            10.x
       - name: Run build script
         id: build_script
         run: ./build.ps1 -ci
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v6
         if: ${{ matrix.os == 'windows-latest' }}
         with:
           name: packages
           path: artifacts/
           if-no-files-found: error
-      - uses: codecov/codecov-action@v4
+      - uses: codecov/codecov-action@v5
         with:
           name: unittests-${{ matrix.os }}
           fail_ci_if_error: true
@@ -66,7 +67,7 @@ jobs:
         uses: NuGet/setup-nuget@v2
         with:
           nuget-version: latest
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v7
         with:
           name: packages
           path: packages

.github/workflows/docs.yml

@@ -17,16 +17,17 @@ on:
 
 jobs:
   generate_docs:
-    runs-on: windows-latest
+    runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v6
     - name: Setup .NET
-      uses: actions/setup-dotnet@v3
+      uses: actions/setup-dotnet@v5
       with:
         dotnet-version: |
-          6.0.x
-          8.0.x
+          8.x
+          9.x
+          10.x
     - name: Run docs generation
       run: ./docs/generate.ps1
 

.github/workflows/stale.yml

@@ -13,7 +13,7 @@ jobs:
   stale:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@v5
+      - uses: actions/stale@v10
         with:
           debug-only: ${{ github.event.inputs.debug-only == 'true' }}
           days-before-stale: 365

CLAUDE.md

@@ -0,0 +1,107 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/claude-code) when working with this repository.
+
+## Project Overview
+
+**McMaster.Extensions.CommandLineUtils** is a .NET library for building command-line applications. It simplifies parsing command-line arguments, validating user inputs, and generating help text. This is a fork of Microsoft.Extensions.CommandLineUtils.
+
+- **Package:** `McMaster.Extensions.CommandLineUtils` on NuGet
+- **Targets:** .NET 6.0+
+- **Status:** Stable/maintenance mode (no major features planned)
+- **License:** Apache 2.0
+
+## Build Commands
+
+```bash
+# Full build with tests (recommended)
+./build.ps1
+
+# CI mode (enforces formatting checks)
+./build.ps1 -ci
+
+# Build only
+dotnet build
+
+# Run tests
+dotnet test
+
+# Build sample projects
+dotnet build docs/samples/samples.sln
+
+# Generate documentation locally
+./docs/generate.ps1
+./docs/generate.ps1 -Serve  # with local preview
+```
+
+Build outputs (NuGet packages) go to `/artifacts/`.
+
+## Project Structure
+
+```
+src/
+  CommandLineUtils/           # Main library
+    Attributes/               # Attribute-based API ([Option], [Argument], etc.)
+    Conventions/              # Convention system for processing attributes
+    Validation/               # Validation framework
+    IO/                       # Console I/O abstractions (IConsole)
+    HelpText/                 # Help text generation
+    Internal/                 # Parsing engine, value parsers
+    Utilities/                # ArgumentEscaper, Prompt, DotNetExe
+  Hosting.CommandLine/        # Microsoft.Extensions.Hosting integration
+
+test/
+  CommandLineUtils.Tests/     # xUnit tests for main library
+  Hosting.CommandLine.Tests/  # xUnit tests for hosting package
+
+docs/
+  samples/                    # 20+ example projects demonstrating various patterns
+```
+
+## Two APIs
+
+**1. Attribute-based API:**
+```csharp
+public class Program
+{
+    public static int Main(string[] args)
+        => CommandLineApplication.Execute<Program>(args);
+
+    [Option(Description = "The subject")]
+    public string Subject { get; } = "world";
+
+    private void OnExecute() { /* command logic */ }
+}
+```
+
+**2. Builder API:**
+```csharp
+var app = new CommandLineApplication();
+app.HelpOption();
+var subject = app.Option("-s|--subject <SUBJECT>", "desc", CommandOptionType.SingleValue);
+app.OnExecute(() => { /* command logic */ });
+return app.Execute(args);
+```
+
+## Key Patterns
+
+- **Conventions:** Extensible `IConvention` implementations process attributes and wire up behavior
+- **Validation:** Three approaches - attribute validators (`[Required]`, `[FileExists]`), fluent API (`.IsRequired()`, `.Accepts()`), and `OnValidate()` methods
+- **Console abstraction:** `IConsole` interface enables testing; use `PhysicalConsole` for real I/O
+- **Response files:** Support for `@filename` syntax to read arguments from files
+
+## Code Style
+
+- 4-space indentation
+- Nullable reference types enabled
+- Warnings treated as errors
+- Code style enforced in build (`EnforceCodeStyleInBuild=true`)
+- Format check: `dotnet tool run dotnet-format`
+
+## Testing
+
+Uses xUnit with FluentAssertions and Moq. Convention tests inherit from `ConventionTestBase` and use `Create<T>()` factory method.
+
+```bash
+dotnet test --collect:"XPlat Code Coverage"
+```

build.ps1

@@ -16,10 +16,6 @@ if (!$Configuration) {
     $Configuration = if ($ci) { 'Release' } else { 'Debug' }
 }
 
-if (-not (Test-Path variable:\IsCoreCLR)) {
-    $IsWindows = $true
-}
-
 $artifacts = "$PSScriptRoot/artifacts/"
 
 Remove-Item -Recurse $artifacts -ErrorAction Ignore
@@ -36,14 +32,6 @@ exec dotnet tool run dotnet-format -- -v detailed @formatArgs "$PSScriptRoot/doc
 exec dotnet build --configuration $Configuration '-warnaserror:CS1591'
 exec dotnet pack --no-build --configuration $Configuration -o $artifacts
 exec dotnet build --configuration $Configuration "$PSScriptRoot/docs/samples/samples.sln"
-
-[string[]] $testArgs=@()
-if (-not $IsWindows) {
-    $testArgs += '-p:TestFullFramework=false'
-}
-
-exec dotnet test --no-build --configuration $Configuration `
-    --collect:"XPlat Code Coverage" `
-    @testArgs
+exec dotnet test --no-build --configuration $Configuration --collect:"XPlat Code Coverage"
 
 write-host -f green 'BUILD SUCCEEDED'