Merge branch 'main' into patch-1

Author: thompson-tomo

.editorconfig

@@ -463,6 +463,9 @@ dotnet_diagnostic.SA1623.severity = none
 # https://github.com/DotNetAnalyzers/StyleCopAnalyzers
 ##########################################
 
+dotnet_diagnostic.SA1009.severity = none
+dotnet_diagnostic.SA1111.severity = none
+
 # https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1600.md
 # Elements should be documented
 dotnet_diagnostic.SA1600.severity = suggestion
@@ -697,6 +700,12 @@ dotnet_diagnostic.CA1851.severity = suggestion
 # CA1861: Avoid constant arrays as arguments
 dotnet_diagnostic.CA1861.severity = suggestion
 
+# IDE0240: Nullable directive is redundant
+dotnet_diagnostic.IDE0240.severity = suggestion
+
+# IDE0241: Nullable directive is unnecessary
+dotnet_diagnostic.IDE0241.severity = suggestion
+
 # Workaround for https://github.com/dotnet/roslyn-analyzers/issues/5628
 [Program.cs]
 dotnet_diagnostic.ca1812.severity = none

.github/copilot-instructions.md

@@ -0,0 +1,167 @@
+# Component Detection - AI Coding Agent Instructions
+
+## Project Overview
+Component Detection is a **package scanning tool** that detects open-source dependencies across 15+ ecosystems (npm, NuGet, Maven, Go, etc.) and outputs a **dependency graph**. It's designed for build-time scanning and can be used as a library or CLI tool.
+
+## Architecture
+
+### Core Concepts
+- **Detectors**: Ecosystem-specific parsers that discover and parse manifest files (e.g., `package.json`, `requirements.txt`)
+- **Component Recorders**: Immutable graph stores that track detected components and their relationships
+- **Typed Components**: Strongly-typed models for each ecosystem (e.g., `NpmComponent`, `PipComponent`) in `src/Microsoft.ComponentDetection.Contracts/TypedComponent/`
+
+### Project Structure
+```
+src/
+├── Microsoft.ComponentDetection/           # CLI entry point (Program.cs)
+├── Microsoft.ComponentDetection.Orchestrator/  # Command execution, DI setup, detector coordination
+├── Microsoft.ComponentDetection.Contracts/     # Interfaces (IComponentDetector, IComponentRecorder) and TypedComponent models
+├── Microsoft.ComponentDetection.Common/        # Shared utilities (file I/O, Docker, CLI invocation)
+└── Microsoft.ComponentDetection.Detectors/     # Per-ecosystem detector implementations (npm/, pip/, nuget/, etc.)
+```
+
+### Detector Lifecycle Stages
+All new detectors start as **IDefaultOffComponentDetector** (must be explicitly enabled via `DetectorArgs`). Maintainers promote through:
+1. **DefaultOff** → 2. **IExperimentalDetector** (enabled but output not captured) → 3. **Default** (fully integrated)
+
+### Dependency Injection
+All services register via `ServiceCollectionExtensions.AddComponentDetection()` in Orchestrator using standard .NET DI. Detectors use constructor injection for dependencies.
+
+## Creating a New Detector
+
+### Required Steps
+1. **Define Component Type** (if new ecosystem):
+   - Add enum to `DetectorClass` and `ComponentType` in Contracts
+   - Create `YourEcosystemComponent : TypedComponent` with required properties
+   - Use `ValidateRequiredInput()` for mandatory fields
+
+2. **Implement Detector**:
+   ```csharp
+   public class YourDetector : FileComponentDetector, IDefaultOffComponentDetector
+   {
+       public YourDetector(
+           IComponentStreamEnumerableFactory componentStreamEnumerableFactory,
+           IObservableDirectoryWalkerFactory walkerFactory,
+           ILogger<YourDetector> logger)
+       {
+           this.ComponentStreamEnumerableFactory = componentStreamEnumerableFactory;
+           this.Scanner = walkerFactory;
+           this.Logger = logger;
+       }
+
+       public override string Id => "YourEcosystem";
+       public override IEnumerable<string> Categories => [DetectorClass.YourCategory];
+       public override IEnumerable<ComponentType> SupportedComponentTypes => [ComponentType.YourType];
+       public override IEnumerable<string> SearchPatterns => ["manifest.lock"]; // Glob patterns
+
+       protected override Task OnFileFoundAsync(ProcessRequest request, IDictionary<string, string> detectorArgs)
+       {
+           var recorder = request.SingleFileComponentRecorder;
+           // Parse file, create components, call recorder.RegisterUsage()
+       }
+   }
+   ```
+
+3. **Register Detector in DI**:
+   Add to `ServiceCollectionExtensions.AddComponentDetection()` in Orchestrator:
+   ```csharp
+   services.AddSingleton<IComponentDetector, YourDetector>();
+   ```
+
+4. **Register Components in Code**:
+   ```csharp
+   var component = new DetectedComponent(new YourComponent("name", "1.0.0"));
+   recorder.RegisterUsage(
+       component,
+       isExplicitReferencedDependency: true,  // Direct dependency?
+       parentComponentId: parentId,           // For graph edges (can be null)
+       isDevelopmentDependency: false         // Build-only dependency?
+   );
+   ```
+
+### Detector Lifecycle Methods
+- `OnPrepareDetection()` - **Optional**: Pre-processing (e.g., filter files before parsing)
+- `OnFileFoundAsync()` - **Required**: Main parsing logic for matched files
+- `OnDetectionFinished()` - **Optional**: Cleanup (e.g., delete temp files)
+
+### Testing Pattern
+```csharp
+[TestClass]
+public class YourDetectorTests : BaseDetectorTest<YourDetector>
+{
+    [TestMethod]
+    public async Task TestBasicDetection()
+    {
+        var fileContent = "name: pkg\nversion: 1.0.0";
+        var (scanResult, componentRecorder) = await this.DetectorTestUtility
+            .WithFile("manifest.lock", fileContent, ["manifest.lock"])
+            .ExecuteDetectorAsync();
+
+        scanResult.ResultCode.Should().Be(ProcessingResultCode.Success);
+        var components = componentRecorder.GetDetectedComponents();
+        components.Should().HaveCount(1);
+    }
+}
+```
+
+Use minimal file content needed to exercise specific scenarios. Avoid testing multiple features in one test.
+
+### End-to-End Verification
+Add test resources to `test/Microsoft.ComponentDetection.VerificationTests/resources/[ecosystem]/` with real-world examples that fully exercise your detector. These run in CI to prevent regressions.
+
+## Development Workflows
+
+### Build & Run
+```bash
+# Build
+dotnet build
+
+# Run scan with new detector (replace YourDetectorId)
+dotnet run --project src/Microsoft.ComponentDetection/Microsoft.ComponentDetection.csproj scan \
+  --Verbosity Verbose \
+  --SourceDirectory /path/to/scan \
+  --DetectorArgs YourDetectorId=EnableIfDefaultOff
+```
+
+### Testing
+```bash
+# Run all tests
+dotnet test
+
+# Run specific test project
+dotnet test test/Microsoft.ComponentDetection.Detectors.Tests/
+```
+
+### Debug Mode
+Add `--Debug` flag to wait for debugger attachment on startup (prints PID).
+
+## Key Patterns
+
+### File Discovery
+Detectors specify `SearchPatterns` (glob patterns like `*.csproj` or `package-lock.json`). The orchestrator handles file traversal; detectors receive matched files via `ProcessRequest.ComponentStream`.
+
+### Graph Construction
+- Use `RegisterUsage()` to add nodes and edges
+- `isExplicitReferencedDependency: true` marks direct dependencies (like packages in `package.json`)
+- `parentComponentId` creates parent-child edges (omit for flat graphs)
+- Some ecosystems don't support graphs (e.g., Go modules) - register components without parents
+
+### Component Immutability
+`TypedComponent` classes must be immutable (no setters). Validation happens in constructors via `ValidateRequiredInput()`.
+
+### Directory Exclusion
+Detectors can filter directories in `OnPrepareDetection()`. Example: npm detector ignores `node_modules` if a root lockfile exists.
+
+## Common Pitfalls
+
+- **Don't** implement `IComponentDetector` directly unless doing one-shot scanning (like Linux detector). Use `FileComponentDetector` for manifest-based detection.
+- **Don't** guess parent relationships - only create edges if the manifest explicitly defines them.
+- **Don't** use setters on `TypedComponent` - pass required values to constructor.
+- **Always** test with `DetectorTestUtility` pattern, not manual `ComponentRecorder` setup.
+- **Remember** new detectors must implement `IDefaultOffComponentDetector` until promoted by maintainers.
+
+## References
+- Detector implementation examples: `src/Microsoft.ComponentDetection.Detectors/npm/`, `pip/`, `nuget/`
+- Creating detectors: `docs/creating-a-new-detector.md`
+- CLI arguments: `docs/detector-arguments.md`
+- Test utilities: `test/Microsoft.ComponentDetection.TestsUtilities/DetectorTestUtility.cs`

.github/workflows/build.yml

@@ -20,13 +20,19 @@ jobs:
       MINVERBUILDMETADATA: build.${{github.run_number}}
 
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
+        with:
+          egress-policy: audit
+
       - name: Checkout repository
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
+          persist-credentials: false
           fetch-depth: 0
 
       - name: Setup .NET
-        uses: actions/setup-dotnet@3951f0dfe7a07e2313ec93c75700083e2005cbab # v4.3.0
+        uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5.2.0
 
       - name: Restore packages
         run: dotnet restore
@@ -35,9 +41,11 @@ jobs:
         run: dotnet build --no-restore --configuration Debug
 
       - name: Run tests
-        run: dotnet test --no-build --configuration Debug --collect:"Code Coverage;Format=cobertura;CoverageFileName=coverage.cobertura.xml"
+        # The '--' separator forwards options to the Microsoft Testing Platform runner.
+        # After upgrading to .NET 10 SDK, these can be passed directly without '--'.
+        run: dotnet test --no-build --configuration Debug -- --coverage --coverage-output-format cobertura
 
       - name: Upload coverage reports to Codecov
-        uses: codecov/codecov-action@18283e04ce6e62d37312384ff67231eb8fd56d24 # v5.4.3
+        uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de # v5.5.2
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/codeql-analysis.yml

@@ -2,11 +2,11 @@ name: "CodeQL"
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
   pull_request:
-    branches: [ main ]
+    branches: [main]
   schedule:
-    - cron: '27 10 * * 1'
+    - cron: "27 10 * * 1"
 
 permissions:
   contents: read
@@ -21,18 +21,24 @@ jobs:
       security-events: write
 
     steps:
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-      with:
+      - name: Harden Runner
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
           fetch-depth: 0
 
-    - name: Initialize CodeQL
-      uses: github/codeql-action/init@ff0a06e83cb2de871e5a09832bc6a81e7276941f # v3.28.18
-      with:
-        languages: 'csharp'
-        debug: true
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@0d579ffd059c29b07949a3cce3983f0780820c98 # v4.32.6
+        with:
+          languages: "csharp"
+          debug: true
 
-    - name: Autobuild
-      uses: github/codeql-action/autobuild@ff0a06e83cb2de871e5a09832bc6a81e7276941f # v3.28.18
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@0d579ffd059c29b07949a3cce3983f0780820c98 # v4.32.6
 
-    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@ff0a06e83cb2de871e5a09832bc6a81e7276941f # v3.28.18
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@0d579ffd059c29b07949a3cce3983f0780820c98 # v4.32.6

.github/workflows/detector-version-bump-reminder.yml

@@ -2,15 +2,20 @@ name: "Detector version bump reminder"
 on:
   push:
     paths:
-      - 'src/Microsoft.ComponentDetection.Detectors/**'
-      
+      - "src/Microsoft.ComponentDetection.Detectors/**"
+
 permissions:
   pull-requests: write
 
 jobs:
   comment:
     runs-on: ubuntu-latest
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
+        with:
+          egress-policy: audit
+
       - uses: mshick/add-pr-comment@b8f338c590a895d50bcbfa6c5859251edc8952fc # v2
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
@@ -20,5 +25,5 @@ jobs:
             * The detector detects more or fewer components than before
             * The detector generates different parent/child graph relationships than before
             * The detector generates different `devDependencies` values than before
-            
+
             If none of the above scenarios apply, feel free to ignore this comment 🙂

.github/workflows/gen-docs.yml

@@ -1,38 +1,43 @@
-name: 'Generate docs'
+name: "Generate docs"
 
 on:
   push:
     branches:
       - main
     paths:
-      - 'src/Microsoft.ComponentDetection.Orchestrator/ArgumentSets/*.cs'
+      - "src/Microsoft.ComponentDetection.Orchestrator/ArgumentSets/*.cs"
 
 permissions:
   contents: read
 
 jobs:
   gen-docs:
     permissions:
-      contents: write  # for stefanzweifel/git-auto-commit-action to push code in repo
+      contents: write # for stefanzweifel/git-auto-commit-action to push code in repo
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - name: Harden Runner
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
         with:
-          fetch-depth: 0
+          egress-policy: audit
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0 # zizmor: ignore[artipacked] git-auto-commit-action needs credentials to push
 
       - name: Setup .NET Core
-        uses: actions/setup-dotnet@3951f0dfe7a07e2313ec93c75700083e2005cbab # v4.3.0
+        uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5.2.0
 
       - name: Generate docs
         run: |
           touch version.json
           touch version_dev.json
-          
+
           # Run CLI
           dotnet run -p src/Microsoft.ComponentDetection help scan 2> help.txt || true
           cat <<EOF > docs/detector-arguments.md
           # Detector arguments
-          
+
           \`\`\`shell
           dotnet run -p './src/Microsoft.ComponentDetection' help scan
           \`\`\`
@@ -43,7 +48,7 @@ jobs:
           EOF
 
       - name: Commit
-        uses: stefanzweifel/git-auto-commit-action@8621497c8c39c72f3e2a999a26b4ca1b5058a842 # v5.0.1
+        uses: stefanzweifel/git-auto-commit-action@04702edda442b2e678b25b537cec683a1493fcb9 # v7.1.0
         with:
-          commit_message: 'Update docs'
-          file_pattern: '*.md'
+          commit_message: "Update docs"
+          file_pattern: "*.md"