Limit npm scans to shipped production dependency trees

Tighten npm scanning so it follows the production dependency tree that ships
with each dep instead of drifting into nested manifests and dev-only trees.

Changes:
- scan only dep-root package.json files under deps/
- skip nested package.json files by default
- use npm install/audit with --omit=dev
- prefer existing node_modules or package-lock.json when available
- fall back to install + audit when package-lock-only audit reports ENOLOCK
- improve diagnostics for npm install/audit failures

Add regression coverage for the new package discovery and lockfile/install
behaviour.

Author: santigimeno

dep_checker/npm_audit.py

@@ -1,9 +1,9 @@
 """NPM package vulnerability checker using npm audit
 
 This module handles npm package vulnerability scanning by:
-1. Finding all package.json files in the repository
-2. Running npm install --production in each directory
-3. Running npm audit --json to get vulnerability data
+1. Finding dep-root package.json files in the repository
+2. Reusing package-lock.json when present, otherwise installing non-dev dependencies
+3. Running npm audit against the prod dependency tree
 4. Parsing results into Vulnerability objects
 """
 
@@ -55,7 +55,7 @@ def __init__(self, repo_path: Path, timeout: int = 300):
         self.failed_packages: List[str] = []
 
     def find_package_json_files(self) -> List[Path]:
-        """Find all package.json files in the deps/ folder only, excluding specified folders"""
+        """Find dep-root package.json files in deps/, excluding nested package manifests."""
         package_json_files = []
         excluded_count = 0
 
@@ -86,8 +86,17 @@ def find_package_json_files(self) -> List[Path]:
                         logger.debug(f"Excluding {package_json} (matches exclusion: {exclude_path})")
                         break
 
-                if not is_excluded:
-                    package_json_files.append(package_json)
+                if is_excluded:
+                    continue
+
+                relative_to_deps = package_json.relative_to(deps_path)
+                dep_root = deps_path / relative_to_deps.parts[0] / "package.json"
+                if package_json != dep_root:
+                    # ponytail: only audit dep roots; add a nested allowlist if a shipped package ever lives deeper.
+                    logger.debug(f"Skipping nested package.json {package_json}")
+                    continue
+
+                package_json_files.append(package_json)
 
             logger.info(f"Found {len(package_json_files)} package.json files in deps/ folder")
             if excluded_count > 0:
@@ -98,8 +107,21 @@ def find_package_json_files(self) -> List[Path]:
             logger.error(f"Error finding package.json files in deps/ folder: {e}")
             return []
 
+    def has_package_lock(self, package_dir: Path) -> bool:
+        return (package_dir / "package-lock.json").exists()
+
+    def has_node_modules(self, package_dir: Path) -> bool:
+        return (package_dir / "node_modules").is_dir()
+
+    def is_missing_lockfile_error(self, audit_data: Optional[Dict]) -> bool:
+        if not isinstance(audit_data, dict):
+            return False
+        error = audit_data.get("error")
+        return isinstance(error, dict) and error.get("code") == "ENOLOCK"
+
+
     def run_npm_install(self, package_dir: Path) -> bool:
-        """Install production dependencies needed for an audit without lifecycle scripts."""
+        """Install non-dev dependencies needed for an audit when no lockfile is present."""
         try:
             logger.info(f"Running npm install in {package_dir}")
             # Check if npm is available
@@ -119,8 +141,8 @@ def run_npm_install(self, package_dir: Path) -> bool:
             # construct npm's dependency tree for an audit.
             result = subprocess.run(
                 [
-                    "npm", "install", "--production", "--ignore-scripts",
-                    "--no-audit", "--no-fund", "--silent",
+                    "npm", "install", "--omit=dev", "--ignore-scripts",
+                    "--no-audit", "--no-fund",
                 ],
                 cwd=package_dir,
                 capture_output=True,
@@ -145,12 +167,18 @@ def run_npm_install(self, package_dir: Path) -> bool:
             logger.error(f"Error running npm install in {package_dir}: {e}")
             return False
 
-    def run_npm_audit(self, package_dir: Path) -> Optional[Dict]:
-        """Run npm audit --json in the given directory"""
+    def run_npm_audit(
+        self, package_dir: Path, package_lock_only: bool = False
+    ) -> Optional[Dict]:
+        """Run npm audit against the production dependency tree in the given directory."""
         try:
             logger.info(f"Running npm audit in {package_dir}")
+            command = ["npm", "audit", "--omit=dev"]
+            if package_lock_only:
+                command.append("--package-lock-only")
+            command.append("--json")
             result = subprocess.run(
-                ["npm", "audit", "--json"],
+                command,
                 cwd=package_dir,
                 capture_output=True,
                 text=True,
@@ -331,6 +359,16 @@ def parse_audit_results(
 
         except Exception as e:
             logger.error(f"Error parsing audit results from {package_dir}: {e}")
+            if isinstance(audit_data, dict):
+                keys = sorted(audit_data.keys())
+                logger.error(f"npm audit JSON top-level keys for {package_dir}: {keys}")
+                if "error" in audit_data:
+                    logger.error(f"npm audit JSON error payload for {package_dir}: {audit_data['error']}")
+                metadata = audit_data.get("metadata")
+                if metadata is not None:
+                    logger.error(f"npm audit JSON metadata for {package_dir}: {metadata}")
+            else:
+                logger.error(f"npm audit JSON type for {package_dir}: {type(audit_data).__name__}")
             return None
 
     def check_npm_vulnerabilities(self, vulnerability_class) -> List:
@@ -347,14 +385,25 @@ def check_npm_vulnerabilities(self, vulnerability_class) -> List:
             logger.info(f"Processing {package_json}")
 
             try:
-                # Run npm install
-                if not self.run_npm_install(package_dir):
+                has_package_lock = self.has_package_lock(package_dir)
+                has_node_modules = self.has_node_modules(package_dir)
+                package_lock_only = has_package_lock and not has_node_modules
+
+                if not has_node_modules and not has_package_lock and not self.run_npm_install(package_dir):
                     logger.warning(f"Skipping npm audit for {package_dir} due to install failure")
                     self.failed_packages.append(f"{package_dir}: npm install failed")
                     continue
-                
-                # Run npm audit
-                audit_data = self.run_npm_audit(package_dir)
+
+                audit_data = self.run_npm_audit(package_dir, package_lock_only=package_lock_only)
+                if package_lock_only and self.is_missing_lockfile_error(audit_data):
+                    logger.warning(
+                        f"npm audit reported ENOLOCK for {package_dir}; falling back to npm install + npm audit"
+                    )
+                    if not self.run_npm_install(package_dir):
+                        logger.warning(f"Skipping npm audit for {package_dir} due to install failure")
+                        self.failed_packages.append(f"{package_dir}: npm install failed")
+                        continue
+                    audit_data = self.run_npm_audit(package_dir, package_lock_only=False)
                 if audit_data is None:
                     logger.warning(f"Skipping vulnerability parsing for {package_dir} due to audit failure")
                     self.failed_packages.append(f"{package_dir}: npm audit failed")