Add global package detection support for npm

Author: davidkopp

docs/technical/architecture/adr/0006-multi-location-detection.md

@@ -104,8 +104,8 @@ We will implement **conditional output structure** for multi-location detection:
 ## Implementation Notes
 
 - **pip detector**: First implementation targeting venv + system detection
+- **npm detector**: Implemented for local + global package detection
 - **Test Infrastructure**: Updated to handle both output formats generically
 - **Documentation**: Updated to explain conditional structure behavior
-- **Future Detectors**: npm could implement similar pattern for global vs. local node_modules
 
 This approach solves the multi-location problem while minimizing breaking changes and maintaining clear traceability of package origins.

docs/technical/detectors/npm_detector.md

@@ -2,35 +2,37 @@
 
 ## Purpose & Scope
 
-The NPM detector identifies Node.js packages managed by `npm` in project environments. It provides structured package information with intelligent package manager detection to avoid conflicts with other Node.js package managers (yarn, pnpm, bun).
+The NPM detector identifies Node.js packages managed by `npm` in both project and system environments. It supports multi-location detection to capture project dependencies and globally installed packages simultaneously.
 
 ## Key Features
 
+### Multi-Location Detection
+
+Detects npm packages in multiple locations:
+
+- **Local dependencies**: Project-level packages via `npm list --json --depth=0`
+- **Global packages**: System-level packages via `npm list -g --json --depth=0`
+- **Mixed output**: Returns both when present in same environment
+
 ### Smart Package Manager Detection
 
-The detector avoids conflicts with other Node.js package managers by checking for lock files:
+For local projects, avoids conflicts with other Node.js package managers:
 
 **Exclusion checks:**
 
-- `yarn.lock` exists → Skip (defer to yarn)
-- `pnpm-lock.yaml` exists → Skip (defer to pnpm)
-- `bun.lockb` exists → Skip (defer to bun)
+- `yarn.lock` exists → Skip local detection (defer to yarn)
+- `pnpm-lock.yaml` exists → Skip local detection (defer to pnpm)
+- `bun.lockb` exists → Skip local detection (defer to bun)
 
 **Inclusion checks:**
 
-- `package.json` or `package-lock.json` exists
+- `package.json`, `node_modules`, or `package-lock.json` exists
 - No conflicting lock files present
 
-### Project Context Detection
-
-Determines scope based on project indicators:
-
-- **Project scope**: When `package.json` or `node_modules` exists
-- **System scope**: When no project indicators found
+## Commands Used
 
-## Command Used
-
-- **Package listing**: `npm list --json --depth=0` for structured JSON output of direct dependencies only
+- **Local packages**: `npm list --json --depth=0`
+- **Global packages**: `npm list -g --json --depth=0`
 
 ## Hash Generation
 
@@ -45,7 +47,7 @@ Individual package-level hashes are **not implemented** for npm dependencies. Th
 
 ### Directory Content Hashing
 
-For project-scoped dependencies, generates location-based hashes by scanning the project directory while excluding:
+Generates location-based hashes for both project and system locations while excluding:
 
 - npm cache directories (`node_modules/.cache`)
 - Log files (`*.log`)
@@ -54,32 +56,54 @@ For project-scoped dependencies, generates location-based hashes by scanning the
 
 ## Output Format
 
-**Project Scope** (with location hash):
-
-- Includes `scope: "project"`, project location, and content hash
-- Contains only direct dependencies from the project
-
-**System Scope** (no location/hash):
-
-- Includes `scope: "system"`
-- Contains system-wide npm packages
+**Single Location** (project or system):
+
+```json
+{
+  "scope": "project" | "system",
+  "location": "/path/to/location",
+  "hash": "abc123...",
+  "dependencies": {...}
+}
+```
+
+**Mixed Locations** (both project and global):
+
+```json
+{
+  "scope": "mixed",
+  "locations": {
+    "/path/to/project": {
+      "scope": "project",
+      "hash": "abc123...",
+      "dependencies": {...}
+    },
+    "/usr/lib/node_modules": {
+      "scope": "system",
+      "hash": "def456...",
+      "dependencies": {...}
+    }
+  }
+}
+```
 
 ## Benefits
 
+- **Complete visibility**: Captures both project and global npm packages
 - **Conflict avoidance**: Prevents npm from running in yarn/pnpm/bun projects
-- **Project isolation**: Distinguishes project dependencies from system packages
+- **Multi-location support**: Follows pip_detector pattern for consistency
 - **Structured data**: JSON output provides reliable programmatic parsing
-- **Direct dependencies focus**: Captures only project's direct dependencies
+- **Direct dependencies focus**: Captures only direct dependencies (depth=0)
 
 ## Limitations
 
-- **npm-specific**: Limited to npm package manager only
 - **Direct dependencies only**: Excludes transitive dependencies
 - **npm dependency**: Requires npm to be installed and functional
+- **Global detection**: Only detects packages via `npm list -g` (not manual installations)
 
 ## Use Cases
 
-- Node.js project dependency analysis
+- Node.js project dependency analysis in containers with global tools
 - Package manager conflict avoidance in multi-tool environments
-- Direct dependency tracking and version monitoring
+- Direct dependency tracking across project and system scopes
 - Build reproducibility through location hashing

docs/usage/output-format.md

@@ -87,7 +87,7 @@ Project-specific package managers (pip, npm) output:
 
 ### Mixed-Scope Packages (Multi-Location Detection)
 
-When a detector finds packages in multiple locations (currently only pip supports this):
+When a detector finds packages in multiple locations (e.g. pip and npm support this):
 
 ```json
 {

energy_dependency_inspector/detectors/npm_detector.py

@@ -14,48 +14,115 @@ def __init__(self, debug: bool = False):
         self.debug = debug
 
     def is_usable(self, executor: EnvironmentExecutor, working_dir: Optional[str] = None) -> bool:
-        """Check if npm is usable and the project uses npm (not yarn/pnpm)."""
+        """Check if npm is usable in the environment."""
         _, _, exit_code = executor.execute_command("npm --version", working_dir)
-        if exit_code != 0:
-            return False
+        return exit_code == 0
+
+    def get_dependencies(
+        self, executor: EnvironmentExecutor, working_dir: Optional[str] = None, skip_hash_collection: bool = False
+    ) -> dict[str, Any]:
+        """Extract npm dependencies with versions from multiple locations.
 
-        # Check if project uses npm by looking for npm-specific files in the working directory
+        Uses 'npm list --json --depth=0' for local packages and
+        'npm list -g --json --depth=0' for global packages.
+        Returns single location structure or nested structure for mixed locations.
+        See docs/technical/detectors/npm_detector.md
+        """
+        # Collect dependencies from both local and global locations
+        local_result = self._get_local_dependencies(executor, working_dir, skip_hash_collection)
+        global_result = self._get_global_dependencies(executor, working_dir, skip_hash_collection)
+
+        # Determine output structure based on what was found
+        if local_result and global_result:
+            # Mixed case - use nested structure
+            locations = {}
+
+            # Add local location
+            local_location_data = {"scope": "project", "dependencies": local_result["dependencies"]}
+            if "hash" in local_result:
+                local_location_data["hash"] = local_result["hash"]
+            locations[local_result["location"]] = local_location_data
+
+            # Add global location
+            global_location_data = {"scope": "system", "dependencies": global_result["dependencies"]}
+            if "hash" in global_result:
+                global_location_data["hash"] = global_result["hash"]
+            locations[global_result["location"]] = global_location_data
+
+            return {"scope": "mixed", "locations": locations}
+        elif local_result:
+            # Only local - use single location structure
+            return local_result
+        elif global_result:
+            # Only global - use single location structure
+            return global_result
+        else:
+            # No packages found - return empty result
+            if working_dir:
+                location = self._resolve_absolute_path(executor, working_dir)
+                return {"scope": "project", "location": location, "dependencies": {}}
+            else:
+                return {"scope": "system", "location": "/usr/lib/node_modules", "dependencies": {}}
+
+    def _get_local_dependencies(
+        self, executor: EnvironmentExecutor, working_dir: Optional[str] = None, skip_hash_collection: bool = False
+    ) -> dict[str, Any] | None:
+        """Get dependencies from local npm project if it exists."""
         search_dir = working_dir or "."
 
-        # Check package.json first (most common case)
-        if executor.path_exists(f"{search_dir}/package.json"):
-            # Only check exclusions if package.json exists
+        # Check if this is a local npm project (not yarn/pnpm/bun)
+        has_package_json = executor.path_exists(f"{search_dir}/package.json")
+        has_node_modules = executor.path_exists(f"{search_dir}/node_modules")
+        has_package_lock = executor.path_exists(f"{search_dir}/package-lock.json")
+
+        # Exclude if using other package managers
+        if has_package_json:
             exclusions = ["yarn.lock", "pnpm-lock.yaml", "bun.lockb"]
             for exclusion in exclusions:
                 if executor.path_exists(f"{search_dir}/{exclusion}"):
-                    return False
-            return True
+                    return None
 
-        # Fallback to package-lock.json
-        return executor.path_exists(f"{search_dir}/package-lock.json")
+        # Only proceed if we have signs of a local npm project
+        if not (has_package_json or has_node_modules or has_package_lock):
+            return None
 
-    def get_dependencies(
-        self, executor: EnvironmentExecutor, working_dir: Optional[str] = None, skip_hash_collection: bool = False
-    ) -> dict[str, Any]:
-        """Extract npm dependencies with versions.
-
-        Uses 'npm list --json --depth=0' for structured package information.
-        See docs/technical/detectors/npm_detector.md
-        """
         stdout, _, exit_code = executor.execute_command("npm list --json --depth=0", working_dir)
+        if exit_code != 0:
+            return None
+
+        dependencies = {}
+        try:
+            npm_data = json.loads(stdout)
+            npm_dependencies = npm_data.get("dependencies", {})
+
+            for package_name, package_info in npm_dependencies.items():
+                version = package_info.get("version", "unknown")
+                dependencies[package_name] = {"version": version}
 
-        location = self._get_npm_location(executor, working_dir)
-        scope = "system" if self._is_system_location(location) else "project"
-        dependencies: dict[str, dict[str, str]] = {}
+        except (json.JSONDecodeError, AttributeError):
+            pass
+
+        if not dependencies:
+            return None
 
-        # Build result with desired field order: scope, location, hash, dependencies
-        result: dict[str, Any] = {"scope": scope}
-        result["location"] = location
+        # Get local project location
+        location = self._get_local_npm_location(executor, working_dir)
+
+        result: dict[str, Any] = {"scope": "project", "location": location}
+        if not skip_hash_collection:
+            result["hash"] = self._generate_location_hash(executor, location)
+        result["dependencies"] = dependencies
+        return result
 
+    def _get_global_dependencies(
+        self, executor: EnvironmentExecutor, working_dir: Optional[str] = None, skip_hash_collection: bool = False
+    ) -> dict[str, Any] | None:
+        """Get dependencies from global npm installation."""
+        stdout, _, exit_code = executor.execute_command("npm list -g --json --depth=0", working_dir)
         if exit_code != 0:
-            result["dependencies"] = dependencies
-            return result
+            return None
 
+        dependencies = {}
         try:
             npm_data = json.loads(stdout)
             npm_dependencies = npm_data.get("dependencies", {})
@@ -67,24 +134,24 @@ def get_dependencies(
         except (json.JSONDecodeError, AttributeError):
             pass
 
-        # Generate location-based hash if appropriate
-        if dependencies and not skip_hash_collection:
-            result["hash"] = self._generate_location_hash(executor, location)
+        if not dependencies:
+            return None
 
-        result["dependencies"] = dependencies
+        # Get global npm location
+        location = self._get_global_npm_location(executor)
 
+        result: dict[str, Any] = {"scope": "system", "location": location}
+        if not skip_hash_collection:
+            result["hash"] = self._generate_location_hash(executor, location)
+        result["dependencies"] = dependencies
         return result
 
     def _is_system_location(self, location: str) -> bool:
-        """Check if a location represents a system-wide npm installation.
+        """Check if a location represents a system-wide npm installation."""
+        return location.startswith(("/usr/lib/node_modules", "/usr/local/lib/node_modules"))
 
-        For npm, system scope means no local package.json or node_modules found.
-        This is determined by the special 'system' marker returned by _get_npm_location.
-        """
-        return location == "system"
-
-    def _get_npm_location(self, executor: EnvironmentExecutor, working_dir: Optional[str] = None) -> str:
-        """Get the actual location path of the npm project or global installation."""
+    def _get_local_npm_location(self, executor: EnvironmentExecutor, working_dir: Optional[str] = None) -> str:
+        """Get the actual location path of the local npm project."""
         search_dir = working_dir or "."
 
         package_json_path = f"{search_dir}/package.json"
@@ -95,13 +162,19 @@ def _get_npm_location(self, executor: EnvironmentExecutor, working_dir: Optional
         if executor.path_exists(node_modules_path):
             return self._resolve_absolute_path(executor, search_dir)
 
-        # Fallback: get npm global location when no local project found
+        # Fallback to current directory
+        return self._resolve_absolute_path(executor, search_dir)
+
+    def _get_global_npm_location(self, executor: EnvironmentExecutor) -> str:
+        """Get the actual location path of the global npm installation."""
+        # Get npm prefix (e.g., /usr)
         stdout, _, exit_code = executor.execute_command("npm config get prefix")
         if exit_code == 0 and stdout.strip():
-            return stdout.strip()
+            prefix = stdout.strip()
+            return f"{prefix}/lib/node_modules"
 
-        # Final fallback: return "system" marker for system scope identification
-        return "system"
+        # Fallback: return default global location
+        return "/usr/lib/node_modules"
 
     def _resolve_absolute_path(self, executor: EnvironmentExecutor, path: str) -> str:
         """Resolve absolute path within the executor's context."""