fix(scripts): eliminate false positives in dependency pinning npm pattern (#273)

## Description

Replace regex-based pattern matching with JSON parsing for package.json
validation, targeting only actual dependency sections. The previous
regex approach incorrectly flagged metadata fields like `name`,
`version`, `description`, and `repository` URLs as unpinned
dependencies.

- Add `Get-NpmDependencyViolations` function that parses package.json as
structured JSON and checks only `dependencies`, `devDependencies`,
`peerDependencies`, and `optionalDependencies` sections
- Update npm pattern config to use `ValidationFunc` dispatcher instead
of `VersionPatterns` regex approach
- Add ValidationFunc dispatch logic to `Get-DependencyViolation` for
type-specific validation functions
- Update `Test-ShellDownloadSecurity` to use consistent `FileInfo`
hashtable parameter
- Create test fixtures for metadata-only and with-dependencies npm
scenarios
- Add Pester tests covering JSON parsing, dependency extraction, and
version pattern matching

## Related Issue(s)

Fixes #267

## Type of Change

Select all that apply:

**Code & Documentation:**

- [x] Bug fix (non-breaking change fixing an issue)
- [ ] New feature (non-breaking change adding functionality)
- [ ] Breaking change (fix or feature causing existing functionality to
change)
- [ ] Documentation update

**Infrastructure & Configuration:**

- [ ] GitHub Actions workflow
- [ ] Linting configuration (markdown, PowerShell, etc.)
- [ ] Security configuration
- [ ] DevContainer configuration
- [ ] Dependency update

**AI Artifacts:**

- [ ] Reviewed contribution with `prompt-builder` agent and addressed
all feedback
- [ ] Copilot instructions (`.github/instructions/*.instructions.md`)
- [ ] Copilot prompt (`.github/prompts/*.prompt.md`)
- [ ] Copilot agent (`.github/agents/*.agent.md`)

> **Note for AI Artifact Contributors**:
>
> - **Agents**: Research, indexing/referencing other project (using
standard VS Code GitHub Copilot/MCP tools), planning, and general
implementation agents likely already exist. Review `.github/agents/`
before creating new ones.
> - **Model Versions**: Only contributions targeting the **latest
Anthropic and OpenAI models** will be accepted. Older model versions
(e.g., GPT-3.5, Claude 3) will be rejected.
> - See [Agents Not
Accepted](../docs/contributing/custom-agents.md#agents-not-accepted) and
[Model Version
Requirements](../docs/contributing/ai-artifacts-common.md#model-version-requirements).

**Other:**

- [x] Script/automation (`.ps1`, `.sh`, `.py`)
- [ ] Other (please describe):

## Sample Prompts (for AI Artifact Contributions)

<!-- Not applicable - no AI artifacts in this PR -->

## Testing

- PSScriptAnalyzer: All files passed with 0 issues
- Pester: 33 tests passed (including 4 new tests for
`Get-NpmDependencyViolations`)
- Full dependency scan: 100% compliance, 0 violations

## Checklist

### Required Checks

- [x] Documentation is updated (if applicable)
- [x] Files follow existing naming conventions
- [x] Changes are backwards compatible (if applicable)
- [x] Tests added for new functionality (if applicable)

### AI Artifact Contributions

<!-- Not applicable - no AI artifacts in this PR -->

### Required Automated Checks

The following validation commands must pass before merging:

- [ ] Markdown linting: `npm run lint:md`
- [ ] Spell checking: `npm run spell-check`
- [ ] Frontmatter validation: `npm run lint:frontmatter`
- [ ] Link validation: `npm run lint:md-links`
- [x] PowerShell analysis: `npm run lint:ps`

## Security Considerations

- [x] This PR does not contain any sensitive or NDA information
- [x] Any new dependencies have been reviewed for security issues
- [x] Security-related scripts follow the principle of least privilege

## Additional Notes

The `ValidationFunc` dispatcher pattern enables type-specific validation
functions without relying on regex patterns. This approach provides
better accuracy for structured file formats like JSON and can be
extended to other dependency types in the future.

🔧 - Generated by Copilot

Author: WilliamBerryiii

scripts/security/Test-DependencyPinning.ps1

@@ -131,16 +131,10 @@ $DependencyPatterns = @{
     }
 
     'npm'            = @{
-        FilePatterns    = @('**/package.json', '**/package-lock.json')
-        VersionPatterns = @(
-            @{
-                Pattern     = '"([^"]+)":\s*"([^@][^"]*)"'
-                Groups      = @{ Package = 1; Version = 2 }
-                Description = 'NPM dependencies in package.json'
-            }
-        )
-        SHAPattern      = '^[a-fA-F0-9]{40}$'
-        RemediationUrl  = 'https://registry.npmjs.org/{0}/{1}'
+        FilePatterns   = @('**/package.json')
+        ValidationFunc = 'Get-NpmDependencyViolations'
+        SHAPattern     = '^[a-fA-F0-9]{40}$'
+        RemediationUrl = 'https://registry.npmjs.org/{0}/{1}'
     }
 
     'pip'              = @{
@@ -211,15 +205,17 @@ function Test-ShellDownloadSecurity {
         have corresponding checksum verification (sha256sum/shasum) within the
         following lines.
 
-    .PARAMETER FilePath
-        Path to the shell script file to scan.
+    .PARAMETER FileInfo
+        Hashtable with Path, Type, and RelativePath keys from Get-FilesToScan.
     #>
     [CmdletBinding()]
     param(
         [Parameter(Mandatory)]
-        [string]$FilePath
+        [hashtable]$FileInfo
     )
 
+    $FilePath = $FileInfo.Path
+
     if (-not (Test-Path $FilePath)) {
         return @()
     }
@@ -246,14 +242,89 @@ function Test-ShellDownloadSecurity {
             }
 
             if (-not $hasChecksum) {
-                $violations += [PSCustomObject]@{
-                    File      = $FilePath
-                    Line      = $i + 1
-                    Pattern   = $line.Trim()
-                    Issue     = 'Download without checksum verification'
-                    Severity  = 'warning'
-                    Ecosystem = 'shell-downloads'
-                }
+                $violation = [DependencyViolation]::new()
+                $violation.File = $FileInfo.RelativePath
+                $violation.Line = $i + 1
+                $violation.Type = $FileInfo.Type
+                $violation.Name = $line.Trim()
+                $violation.Severity = 'warning'
+                $violation.Description = 'Download without checksum verification'
+                $violation.Metadata = @{ Pattern = $line.Trim() }
+                $violations += $violation
+            }
+        }
+    }
+
+    return $violations
+}
+
+function Get-NpmDependencyViolations {
+    <#
+    .SYNOPSIS
+        Analyzes package.json files for unpinned npm dependencies.
+    .DESCRIPTION
+        Parses package.json as JSON and checks only actual dependency sections
+        (dependencies, devDependencies, peerDependencies, optionalDependencies)
+        for SHA-pinned versions. Ignores metadata fields like name, version,
+        description, contributes, scripts, repository, etc.
+    .PARAMETER FileInfo
+        Hashtable with Path, Type, and RelativePath keys from Get-FilesToScan.
+    .OUTPUTS
+        Array of PSCustomObjects representing dependency violations.
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [hashtable]$FileInfo
+    )
+
+    $filePath = $FileInfo.Path
+    $relativePath = $FileInfo.RelativePath
+    $type = $FileInfo.Type
+    $violations = @()
+
+    if (-not (Test-Path -Path $filePath -PathType Leaf)) {
+        return $violations
+    }
+
+    try {
+        $content = Get-Content -Path $filePath -Raw -ErrorAction Stop
+        $packageJson = $content | ConvertFrom-Json -ErrorAction Stop
+    }
+    catch {
+        Write-Warning "Failed to parse $relativePath as JSON: $_"
+        return $violations
+    }
+
+    $dependencySections = @('dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies')
+
+    foreach ($section in $dependencySections) {
+        $deps = $packageJson.$section
+        if ($null -eq $deps) {
+            continue
+        }
+
+        foreach ($prop in $deps.PSObject.Properties) {
+            $packageName = $prop.Name
+            $version = $prop.Value
+
+            if ([string]::IsNullOrWhiteSpace($version)) {
+                continue
+            }
+
+            $isPinned = Test-SHAPinning -Version $version -Type $type
+
+            if (-not $isPinned) {
+                $violation = [DependencyViolation]::new()
+                $violation.File = $relativePath
+                $violation.Line = 0
+                $violation.Type = $type
+                $violation.Name = $packageName
+                $violation.Version = $version
+                $violation.Severity = 'warning'
+                $violation.Description = "Unpinned npm dependency in $section"
+                $violation.Metadata = @{ Section = $section }
+                $violations += $violation
             }
         }
     }
@@ -365,6 +436,41 @@ function Get-DependencyViolation {
         return $violations
     }
 
+    # Check if this type uses a validation function instead of regex patterns
+    if ($null -ne $DependencyPatterns[$fileType].ValidationFunc) {
+        $funcName = $DependencyPatterns[$fileType].ValidationFunc
+        $rawViolations = & $funcName -FileInfo $FileInfo
+
+        if ($null -eq $rawViolations) {
+            return @()
+        }
+
+        foreach ($v in $rawViolations) {
+            if ($null -eq $v) {
+                continue
+            }
+
+            if (-not ($v -is [DependencyViolation])) {
+                $actualType = $v.GetType().FullName
+                throw "Validation function '$funcName' must return [DependencyViolation] objects, got '$actualType'."
+            }
+
+            if (-not $v.File) {
+                $v.File = $FileInfo.RelativePath
+            }
+
+            if ($v.Line -lt 1) {
+                $v.Line = 0
+            }
+
+            if (-not $v.Type) {
+                $v.Type = $fileType
+            }
+        }
+
+        return $rawViolations
+    }
+
     try {
         $content = Get-Content -Path $filePath -Raw
         $lines = Get-Content -Path $filePath

scripts/tests/Fixtures/Npm/empty-version-package.json

@@ -0,0 +1,9 @@
+{
+  "name": "empty-version-test",
+  "version": "1.0.0",
+  "dependencies": {
+    "valid-package": "^1.0.0",
+    "empty-version": "",
+    "whitespace-version": "   "
+  }
+}

scripts/tests/Fixtures/Npm/invalid-json-package.json

@@ -0,0 +1,4 @@
+{
+  "name": "invalid-json-test"
+  "version": "1.0.0"
+}

scripts/tests/Fixtures/Npm/metadata-only-package.json

@@ -0,0 +1,35 @@
+{
+  "name": "test-package",
+  "version": "1.0.0",
+  "description": "Test package with only metadata fields",
+  "author": "Test Author",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/test/test-package.git"
+  },
+  "bugs": {
+    "url": "https://github.com/test/test-package/issues"
+  },
+  "homepage": "https://github.com/test/test-package#readme",
+  "keywords": [
+    "test",
+    "fixture"
+  ],
+  "scripts": {
+    "build": "echo 'build'",
+    "test": "echo 'test'"
+  },
+  "main": "index.js",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "contributes": {
+    "commands": [
+      {
+        "command": "test.command",
+        "title": "Test Command"
+      }
+    ]
+  }
+}

scripts/tests/Fixtures/Npm/with-dependencies-package.json

@@ -0,0 +1,23 @@
+{
+  "name": "test-package-with-deps",
+  "version": "2.0.0",
+  "description": "Test package with actual dependencies",
+  "dependencies": {
+    "lodash": "^4.17.21",
+    "express": "~4.18.2"
+  },
+  "devDependencies": {
+    "jest": "29.7.0",
+    "typescript": "*"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0"
+  },
+  "optionalDependencies": {
+    "fsevents": "^2.3.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest"
+  }
+}