Add #:sdk support for .NET file-based apps - #755

Extend file-based app handling beyond #:package so MSBuild SDK
packages declared with #:sdk (for example Cake.Sdk@6.0.0) are
discovered, reported, and upgraded from the .cs source file.

Analysis
- Parse #:package and #:sdk directives from file-based app sources
- Prefer directive-based dependencies over restore-graph expansion
  (report SDK over transient SDK dependencies)
- Support variable-backed directives via #:property, including
  $(SdkId)@$(SdkVersion) and $(SdkId)@literal-version forms
- Dedupe discovered references by preferring variable-backed entries

Upgrade
- Update #:property for variable-backed #:package and #:sdk
- Rewrite literal #:sdk lines in-place; block literal direct rewrites
  when expressions contain $(...)
- Return failure when no directive or property file was changed
- Omit -f/--framework for dotnet add on .cs paths (newer SDKs reject it)

Implementation
- Add FileBasedAppReference model and compile-time regex sources
- Extend VariableTrackingService and ProjectAnalysisService
- Harden DotNetPackageService upgrade routing and error reporting

Tests and CI
- Add test-projects/file-based-app-sdk fixture
- Add unit, integration, and end-to-end coverage for SDK directives
- Add file-based-app-sdk smoke test to the SDK 10.0.300 CI job

Docs
- Document #:sdk usage in README and FAQ
- Point file-based app upgrade FAQ to dotnet/sdk (dotnet/cli is archived)

UpdatePackageVariable Step 2 previously always wrote the package
reference file and set msbuildUpdated even when no matching elements
were found or regex replacements made no changes. That could return
true while nothing was modified, conflicting with the bool contract
and masking no-op upgrades.

Compare packageRefContent before and after replacements; write and
set msbuildUpdated only when the file content actually differs.

Address review feedback for #:sdk / #:package support by improving
update safety, reducing duplicate I/O, and restoring a backward-
compatible ProjectAnalysisService API.

VariableTrackingService:
- Scan file-based apps in a single pass via GetOrScanFileBasedApp,
  sharing results between DiscoverFileBasedAppReferences and
  DiscoverPackageVariables (with a dedicated scan cache)
- Still collect parent *.props property definitions during the scan
- Replace only the version token in UpdateFileBasedAppDirectReference
  so trailing inline comments and other suffix text are preserved
- Broaden update failure warnings to include ElementType
- Reuse already-read file content when resolving #:property values
  during directive updates (CollectFileBasedAppPropertyDefinitionsForUpdate)
- Invalidate both variable and file-based scan caches on changes

ProjectAnalysisService:
- Reintroduce constructors without IVariableTrackingService,
  delegating to VariableTrackingService(fileSystem) for compatibility

Tests:
- Add Update_FileBasedAppDirectSdk_PreservesTrailingContentOnDirectiveLine

Address PR feedback for #:sdk / #:package handling: pinned versions
should resolve as exact ranges, #:property forward references must
work when directives appear before definitions, and failed upgrades
should explain what form of directive was expected.

VariableTrackingService:
- Scan file-based apps in two passes: collect all #:property values
  first, then parse #:package/#:sdk directives (fixes forward refs)
- Use exact inclusive VersionRange (min=max) for directive references
  instead of minimum-only ranges
- Avoid nullable annotations outside a nullable context on out params

FileBasedAppReference:
- Enable nullable reference types for this file
- Mark ResolvedVersion/VersionRange as required; VariableInfo as nullable
- Add CreateExactVersionRange helper for pinned directive versions

DotNetPackageService:
- Include actionable hints in file-based app update failure messages
  (literal #:sdk form, #:property path, variable update failures)

Tests:
- Assert exact version ranges on discovered references
- Add Discover_FileBasedApp_SdkBeforePropertyDefinitions_ResolvesForwardReferences
- Assert improved failure output for property-reference SDK directives

Address PR feedback for file-based app upgrade behavior, reference
discovery, and xUnit test attribute visibility.

DotNetPackageService:
- When UpdatePackageVariable or UpdateFileBasedAppDirectReference
  returns false, verify the #:property or directive already matches
  the requested version before failing
- Treat unchanged file-based app content as a successful upgrade

VariableTrackingService:
- Deduplicate DiscoverFileBasedAppReferences by (Kind, Name) so the
  same id in both #:package and #:sdk is not collapsed

EndToEndTests:
- Move RequiresFileBasedAppSdkAttribute to namespace scope with
  explicit FactAttribute documentation for test discovery
- Hoist DotNetSdkDetector alongside the attribute

Tests:
- Add no-op success coverage for variable-backed and literal #:sdk paths
- Add Discover_FileBasedAppReferences_PreservesDistinctPackageAndSdkWithSameName
- Assert file-based app failure hints on RunStatus.Errors, not Output

When a file-based app declares the same id in both #:package and #:sdk,
ProjectAnalysisService previously keyed TargetFramework.Dependencies
only by reference.Name, so one directive silently overwrote the other.

FileBasedAppReferenceHelper:
- Add GetDependencyDictionaryKey to produce kind-specific keys
  ({name}#package vs {name}#sdk) while keeping Dependency.Name as the
  NuGet package id

ProjectAnalysisService:
- Store file-based app references under kind-specific dictionary keys
- Remove graph-only dependencies by Dependency.Name rather than key,
  so stripping still works with the new key scheme

Tests:
- Add GetDependencyDictionaryKey_DistinguishesPackageAndSdkWithSameName

Directive references (#:package / #:sdk) were stored with an exact
[X, X] version range, so ResolvePackageVersions could never resolve a
newer version and outdated SDKs were never reported. Use a
minimum-inclusive, open-upper-bound range instead.

ApplyFileBasedAppDirectives kept the dependency-graph entry for any
package also declared as a directive and then added a second entry under
the name#package key, duplicating the dependency. Remove all
non-transitive graph entries before re-adding the authoritative directive
references. The two issues previously masked each other: the exact range
suppressed the duplicate package entry.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…s, path normalization

- TryParsePackageDirective now strips trailing content (e.g. inline
  '// pinned' comments) so directives like '#:sdk Cake.Sdk@6.0.0 // pinned'
  are discovered/analyzed, matching UpdateFileBasedAppDirectReference which
  already preserves trailing content on upgrade.
- File-based '#:property' update regexes now use RegexOptions.IgnoreCase so a
  '#:property sdkversion=...' referenced as $(SdkVersion) updates correctly,
  consistent with the case-insensitive propertyDefinitions lookup.
- ApplyFileBasedAppDirectives now uses the normalized analyzedProjectPath so
  directive discovery and its cache key off the same path as restore/asset
  loading even when the caller passes a relative path.
- Adds tests for trailing-comment discovery and case-insensitive property update.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>