[main] Update dependencies from dotnet/arcade

[main] Update dependencies from dotnet/dnceng

…`target-directory` (dotnet#5340)

<!-- Link the GitHub or AzDO issue this pull request is associated with.
Please copy and paste the full URL rather than using the
dotnet/arcade-services# syntax -->
dotnet#5221

---------

Co-authored-by: Copilot <[email protected]>
Co-authored-by: Přemek Vysoký <[email protected]>

…ty attribute changes (dotnet#5346)

- [x] Review PR dotnet#5067 and dotnet#5209 changes to understand what was
implemented
- [x] Add section on Version.Details.props file
- [x] Document the SkipProperty attribute in Version.Details.xml
- [x] Document header generation behavior for repos with only
SkipProperty dependencies
- [x] Add examples showing proper configuration
- [x] Update index and references throughout the document
- [x] Build and test to ensure no syntax errors in documentation
- [x] Address review feedback: Remove "When to use SkipProperty" section
- [x] Address review feedback: Simplify migration steps

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



<details>

<summary>Original prompt</summary>

> 
> ----
> 
> *This section details on the original issue you should resolve*
> 
> <issue_title>Update Darc.md documentation for Version.Details.props
and SkipProperty attribute changes</issue_title>
> <issue_description>Update the Darc.md documentation to reflect changes
implemented in the following PRs:
> - dotnet#5067
> - dotnet#5209
> 
> Key points to address:
> 
> 1. **Version.Details.props File**
>    - Describe the addition of the new `Version.Details.props` file.
>    - Document that if `Version.Details.props` exists, it will be used.
>    - Explain when and how this file is generated or consumed.
> 
> 2. **SkipProperty Attribute in Version.Details.xml**
> - Introduce and document the `SkipProperty` attribute that can be
added in `Version.Details.xml`.
>    - Describe its purpose and how it affects dependency management.
> 
> 3. **Other Relevant Changes**
> - Summarize any additional relevant changes from the referenced PRs,
such as header generation behavior for repos with only `SkipProperty`
dependencies.
> 
> Ensure examples and configuration/process details are clear for users
maintaining or integrating with Darc-managed
repositories.</issue_description>
> 
> ## Comments on the Issue (you are @copilot in this section)
> 
> <comments>
> </comments>
> 


</details>
Fixes dotnet#5345

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

💡 You can make Copilot smarter by setting up custom instructions,
customizing its development environment and configuring Model Context
Protocol (MCP) servers. Learn more [Copilot coding agent
tips](https://gh.io/copilot-coding-agent-tips) in the docs.

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: dkurepa <[email protected]>
Co-authored-by: Přemek Vysoký <[email protected]>

<!-- Link the GitHub or AzDO issue this pull request is associated with.
Please copy and paste the full URL rather than using the
dotnet/arcade-services# syntax -->
dotnet#5221 fixes a bug
introduced in dotnet#5340 where
there's an NRE if there are no excluded assets

…ng Maestro subscription updates (dotnet#5343)

## Summary

Adds a `--subscription` parameter to the `darc update-dependencies`
command that enables users to locally simulate the effect of a specific
Maestro subscription. This makes it easier to debug, validate, and
reason about dependency updates as they would occur in Maestro.

Fixes dotnet#2540

## Implementation Approach

The implementation fetches subscription metadata from BAR and populates
the command options based on the subscription settings (channel, source
repository, target directory, excluded assets). It also fetches the
latest build from the source repository on the subscription's channel
(unless a build ID is provided), and uses that specific build ID. This
allows the existing update logic to handle the dependency updates,
ensuring consistency and reducing code duplication.

## Changes

### New Functionality

When using `--subscription <maestro-subscription-id>`, the command now:

1. **Fetches subscription metadata** from the BAR API (source repo,
target repo/branch, channel, target-directory, excluded assets)
2. **Validates subscription type** - rejects source-enabled
subscriptions (VMR code flow)
3. **Fetches the latest build** from the source repository on the
subscription's channel (unless `--id` is provided)
4. **Allows parameter overrides**:
- `--id` can be provided to use a specific build instead of the latest
- `--excluded-assets` can be provided to override subscription's
excluded assets
5. **Populates command options** based on subscription settings and any
overrides
6. **Reuses existing update logic** to apply updates consistently with
the rest of the codebase
7. **Respects subscription settings**:
- Uses the specific build from the subscription's source repo and
channel (or provided build ID)
   - Filters to the subscription's source repository
- Only updates/places assets within the subscription's target directory
   - Uses subscription's excluded assets (or provided override)
8. **Provides detailed output** showing:
   - Subscription metadata (source, target, channel, filters)
- Selected or provided build information (build number, BAR ID, commit
SHA)
   - Standard update output from existing code path

### Validation

The implementation includes comprehensive validation - all throw
`DarcException` consistently:
- Subscription ID must be a valid GUID
- Subscription must be a dependency flow subscription (not
source-enabled/VMR code flow)
- Cannot be combined with conflicting parameters: `--channel`,
`--packages-folder`, `--name`/`--version`, `--source-repo`,
`--coherency-only`, `--target-directory`
- **Can be combined with**: `--id` (to override build),
`--excluded-assets` (to override filters)
- Clear exceptions when subscription is not found or no build is
available

### Example Usage

```bash
# Preview what a subscription would do
darc update-dependencies --subscription 12345678-1234-1234-1234-123456789012 --dry-run

# Apply the subscription's updates locally
darc update-dependencies --subscription 12345678-1234-1234-1234-123456789012

# Test subscription with a different build
darc update-dependencies --subscription 12345678-1234-1234-1234-123456789012 --id 987654

# Test subscription with different excluded assets
darc update-dependencies --subscription 12345678-1234-1234-1234-123456789012 --excluded-assets "Test.*"
```

**Example output:**
```
Simulating subscription '12345678-1234-1234-1234-123456789012':
  Source: https://github.com/dotnet/arcade (channel: .NET Tools - Latest)
  Target: https://github.com/dotnet/runtime#main
  Target directory: src/libraries
  Latest build: 20240315.1 (BAR ID: 2345678)
  Build commit: abc123def456...

    Updating 'Microsoft.DotNet.Arcade.Sdk': '8.0.0-beta.24150.1' => '8.0.0-beta.24165.2' (from build '20240315.1' of 'https://github.com/dotnet/arcade')
    Checking for coherency updates...
```

## Documentation

Added comprehensive documentation to `docs/Darc.md`:
- New scenario section explaining the subscription simulation feature
- Updated command reference with subscription parameter details
- Usage examples and expected output

## Testing

- All existing unit tests continue to pass (117 passed)
- Build succeeds with no errors or warnings
- Manual validation confirms proper error handling and output
- Refactored to reuse existing code path for consistency
- Parameter overrides (--id, --excluded-assets) work correctly

## Architecture

The implementation follows the feedback to reuse existing code rather
than duplicating logic. The `PopulateOptionsFromSubscriptionAsync`
method:
1. Validates parameters (throws exceptions for invalid input or
conflicts)
2. Fetches subscription metadata
3. Validates subscription type (dependency flow only)
4. Fetches the latest build from the source repo on the subscription's
channel (if --id not provided)
5. Populates `_options` with subscription settings and build ID
(respecting any overrides)
6. Returns to the existing update code path

This approach ensures consistency with the rest of the codebase and
reduces maintenance burden while allowing flexibility through parameter
overrides.

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



<details>

<summary>Original prompt</summary>

> 
> ----
> 
> *This section details on the original issue you should resolve*
> 
> <issue_title>Enhance `darc update-dependencies` with --subscription
parameter to simulate Maestro subscription updates</issue_title>
> <issue_description>### Summary
> 
> Proposal to add a `--subscription <maestro-subscription-id>` option to
the `darc update-dependencies` command. This would enable users to
locally simulate the effect of a specific Maestro subscription, making
it easier to debug, validate, and reason about dependency updates as
they would occur in Maestro.
> 
> ### Motivation
> Currently, `darc update-dependencies` supports applying updates from a
channel, but does not allow users to replicate what a particular
subscription would do. This is problematic when multiple subscriptions
(from different channels, with different rules) target a single
repository, and there is a need to locally test or troubleshoot the
outcome of a subscription update.
> 
> ### Proposed Behavior
> - Add a `--subscription <maestro-subscription-id>` parameter to the
command.
> - When provided:
> 1. Fetch the subscription metadata (source repo, target repo/branch,
channel, target-directory, excluded assets).
> 2. Determine the build that Maestro would apply for the subscription
(using Maestro's selection logic).
> 3. Apply dependency updates locally based on that build, instead of a
channel-wide update.
> 4. Respect the subscription's target-directory (only update or place
assets within that subtree) and excluded assets (skip those).
>     5. Support using the existing dry-run/verbose option to show:
>         - Which build was selected (id, repo, commit)
> - Which assets would be updated, and which are skipped (with reasons)
> 6. Provide clear errors if the subscription id is invalid, no build
can be resolved, or assets don't map to current dependencies.
> 
> ### Notes
> - This does not modify the subscription or Maestro service state—it's
a local simulation.
> - Goal: To make it easier for engineers to reproduce, validate, and
debug Maestro subscription outcome locally.
> 
> ### Related Issue
> - [A way to do darc update-dependencies locally as subscriptions
would](dotnet#2540)
(background and motivation)
> </issue_description>
> 
> ## Comments on the Issue (you are @copilot in this section)
> 
> <comments>
> </comments>
> 


</details>
Fixes dotnet#5342

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

💡 You can make Copilot smarter by setting up custom instructions,
customizing its development environment and configuring Model Context
Protocol (MCP) servers. Learn more [Copilot coding agent
tips](https://gh.io/copilot-coding-agent-tips) in the docs.

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: dkurepa <[email protected]>
Co-authored-by: Přemek Vysoký <[email protected]>

<!-- Link the GitHub or AzDO issue this pull request is associated with.
Please copy and paste the full URL rather than using the
dotnet/arcade-services# syntax -->
dotnet#5134