Rename _container-info to source

Author: davidkopp

SPECIFICATION.md

@@ -64,7 +64,7 @@ The tool outputs structured JSON with packages aggregated by scope (project/syst
 
 ```json
 {
-  "_container-info": { "name": "nginx-container", "image": "nginx:latest", "hash": "sha256:..." },
+  "source": { "type": "container", "name": "nginx-container", "image": "nginx:latest", "hash": "sha256:..." },
   "project": {
     "packages": [
       { "name": "numpy", "version": "1.3.3", "type": "pip" }
@@ -87,7 +87,7 @@ For complete JSON schema documentation, field definitions, and examples, see [do
 - **System Packages**: All system-scoped packages aggregated in `system.packages[]` array
 - **Package Type**: Each package includes `type` field (`pip`, `npm`, `dpkg`, `apk`, `maven`)
 - **Metadata**: Package manager metadata stored in `project.{manager}` sections (location, hash)
-- **Container Info**: Docker metadata included as `_container-info` when applicable
+- **Source Info**: Environment metadata included as `source` when applicable (includes `type` field for container/host)
 
 ## Implementation Constraints
 

TODOS.md

@@ -1,6 +1,7 @@
 # TODOS
 
 - Publish package to PyPI
+- Add host_info_detector (similar to docker_info_detector)
 - Add CLI flag to select a subset of detectors (see how Syft does it: <https://github.com/anchore/syft/wiki/package-cataloger-selection>)
 - Extend the set of supported package managers with the common ones for Go, PHP and Java
 - Add Dockerfile

dependency_resolver/core/orchestrator.py

@@ -71,7 +71,8 @@ def resolve_dependencies(
                     if detector_name == "docker-info":
                         packages, metadata = detector.get_dependencies(executor, working_dir)
                         if metadata:  # Only include if we got container info
-                            result["_container-info"] = metadata
+                            metadata["type"] = "container"
+                            result["source"] = metadata
                         if self.debug:
                             print(f"Found container info for {detector_name}")
                     else:

dependency_resolver/detectors/docker_info_detector.py

@@ -10,6 +10,7 @@ class DockerInfoDetector(PackageManagerDetector):
 
     def is_usable(self, executor: EnvironmentExecutor, working_dir: Optional[str] = None) -> bool:
         """Check if this is a Docker environment."""
+        _ = working_dir  # Unused parameter, required by interface
         return isinstance(executor, DockerExecutor)
 
     def get_dependencies(
@@ -20,13 +21,14 @@ def get_dependencies(
         Note: This detector returns metadata rather than packages, but conforms to the interface.
         The orchestrator handles this specially.
         """
+        _ = working_dir  # Unused parameter, required by interface
         if not isinstance(executor, DockerExecutor):
             return [], {}
 
         container_info = executor.get_container_info()
 
         # Return simplified container info structure as metadata
-        # The orchestrator will handle this specially for _container-info section
+        # The orchestrator will handle this specially for source section
         result = {
             "name": container_info["name"],
             "image": container_info["image"],
@@ -42,4 +44,6 @@ def get_dependencies(
 
     def has_system_scope(self, executor: EnvironmentExecutor, working_dir: Optional[str] = None) -> bool:
         """Docker container info has container scope, not system scope."""
+        _ = executor  # Unused parameter, required by interface
+        _ = working_dir  # Unused parameter, required by interface
         return False

docs/technical/detectors/docker_info_detector.md

@@ -20,15 +20,16 @@ Unlike other detectors, Docker Info uses a flattened output structure:
 
 ```json
 {
-  "_container-info": {
+  "source": {
+    "type": "container",
     "name": "container-name",
     "image": "nginx:latest",
     "hash": "sha256:abc123def456..."
   }
 }
 ```
 
-This simplified format reflects that container metadata is fundamentally different from package dependencies.
+This simplified format reflects that source metadata is fundamentally different from package dependencies. The `type` field distinguishes between container and host sources.
 
 ## Implementation Details
 
@@ -86,7 +87,7 @@ Container images don't use location-based hashing since:
 
 ### Container Scope
 
-Docker container info has `container` scope in the orchestrator logic, but outputs directly as `_container-info` to distinguish it from package managers.
+Docker container info has `container` scope in the orchestrator logic, but outputs directly as `source` with `type: "container"` to distinguish it from package managers.
 
 ### Executor Context
 
@@ -122,7 +123,8 @@ The detector returns a tuple: `(packages, metadata)` but is handled specially by
 
 ```json
 {
-  "_container-info": {
+  "source": {
+    "type": "container",
     "name": "my-nginx-container",
     "image": "nginx:latest",
     "hash": "sha256:2cd1d97f893f70cee86a38b7160c30e5750f3ed6ad86c598884ca9c6a563a501"
@@ -136,6 +138,7 @@ The detector returns a tuple: `(packages, metadata)` but is handled specially by
 
 ```json
 {
+  "type": "container",
   "name": "my-container",
   "image": "unknown",
   "hash": "unknown",

docs/usage/output-format.md

@@ -8,7 +8,7 @@ The dependency-resolver outputs a unified JSON structure that aggregates all pac
 
 ```json
 {
-  "_container-info": { ... },
+  "source": { ... },
   "project": {
     "packages": [...],
     "pip": { ... },
@@ -20,13 +20,14 @@ The dependency-resolver outputs a unified JSON structure that aggregates all pac
 }
 ```
 
-## Container Information
+## Source Information
 
-When analyzing Docker containers, the `_container-info` section provides metadata:
+When analyzing environments, the `source` section provides metadata about where the scan was performed:
 
 ```json
 {
-  "_container-info": {
+  "source": {
+    "type": "container",
     "name": "nginx-container",
     "image": "nginx:latest",
     "hash": "sha256:2cd1d97f893f..."
@@ -36,9 +37,10 @@ When analyzing Docker containers, the `_container-info` section provides metadat
 
 ### Fields
 
-- `name` - Container name
-- `image` - Docker image used
-- `hash` - Container image hash
+- `type` - Source type (`"container"` for Docker containers, `"host"` for host scans)
+- `name` - Container name (for container sources)
+- `image` - Docker image used (for container sources)
+- `hash` - Container image hash (for container sources)
 
 ## Package Sections
 
@@ -166,7 +168,8 @@ Here's a complete example showing the new unified structure:
 
 ```json
 {
-  "_container-info": {
+  "source": {
+    "type": "container",
     "name": "web-app",
     "image": "python:3.12-slim",
     "hash": "sha256:a1b2c3d4e5f6..."

tests/common/docker_test_base.py

@@ -109,18 +109,31 @@ def print_verbose_results(self, title: str, result: Dict[str, Any]) -> None:
         print("=" * 60)
 
     def validate_basic_structure(self, result: Dict[str, Any], detector_type: str) -> None:
-        """Validate basic structure of new scope-based results."""
+        """Validate basic structure of dependency resolver results.
+
+        Validates both package scopes (project/system) and metadata sections (source).
+        Handles both full analysis results and metadata-only results.
+        """
         assert isinstance(result, dict), "Result should be a dictionary"
 
-        # Should have either project or system scope (or both)
-        valid_scopes = ["project", "system", "_container-info"]
-        found_scopes = [scope for scope in result.keys() if scope in valid_scopes]
-        assert len(found_scopes) > 0, f"Expected at least one scope in result keys: {list(result.keys())}"
+        # Should have either package scopes (project/system) or source metadata
+        package_scopes = ["project", "system"]
+        metadata_sections = ["source"]
+        all_valid_sections = package_scopes + metadata_sections
+
+        found_package_scopes = [scope for scope in result.keys() if scope in package_scopes]
+        found_metadata_sections = [section for section in result.keys() if section in metadata_sections]
+        found_valid_sections = [section for section in result.keys() if section in all_valid_sections]
+
+        assert (
+            len(found_valid_sections) > 0
+        ), f"Expected at least one valid section in result keys: {list(result.keys())}"
 
-        # Validate packages were found for the expected detector type
-        packages_found = False
-        for scope_name in ["project", "system"]:
-            if scope_name in result:
+        # Validate packages were found for the expected detector type (unless only metadata)
+        if found_package_scopes:
+            # If we have package scopes, validate that the expected detector type is present
+            packages_found = False
+            for scope_name in found_package_scopes:
                 scope_result = result[scope_name]
                 assert isinstance(scope_result, dict), f"{scope_name} should be a dictionary"
                 assert "packages" in scope_result, f"{scope_name} should contain 'packages'"
@@ -134,7 +147,16 @@ def validate_basic_structure(self, result: Dict[str, Any], detector_type: str) -
                         packages_found = True
                         break
 
-        assert packages_found, f"Should have found packages of type '{detector_type}' in result"
+            assert packages_found, f"Should have found packages of type '{detector_type}' in result"
+        elif found_metadata_sections:
+            # If only metadata sections, validate source structure (e.g., container-info-only mode)
+            source_result = result["source"]
+            assert isinstance(source_result, dict), "source should be a dictionary"
+            assert "type" in source_result, "source should contain 'type'"
+            assert source_result["type"] in [
+                "container",
+                "host",
+            ], f"source type should be 'container' or 'host': {source_result['type']}"
 
     def validate_dependency_structure(self, packages: list, sample_count: int = 5) -> None:
         """Validate structure of package entries in the new format."""

tests/detectors/docker_info/README.md

@@ -22,7 +22,7 @@ This directory contains tests for the Docker Info detector, which extracts metad
 
 - ✅ Container metadata extraction (name, image, hash)
 - ✅ Both full analysis and container-info-only modes
-- ✅ Simplified JSON output format (`_container-info`)
+- ✅ Simplified JSON output format (`source` with `type: "container"`)
 - ✅ Error handling and graceful degradation
 
 ### Integration Tests
@@ -62,7 +62,8 @@ pytest tests/detectors/docker_info/test_docker_info_detection.py::TestDockerInfo
 
 ```json
 {
-  "_container-info": {
+  "source": {
+    "type": "container",
     "name": "container-id",
     "image": "nginx:alpine",
     "hash": "sha256:abc123..."
@@ -74,13 +75,18 @@ pytest tests/detectors/docker_info/test_docker_info_detection.py::TestDockerInfo
 
 ```json
 {
-  "_container-info": {
+  "source": {
+    "type": "container",
     "name": "container-id",
     "image": "nginx:alpine",
     "hash": "sha256:abc123..."
   },
-  "dpkg": { ... },
-  "apk": { ... }
+  "system": {
+    "packages": [...]
+  },
+  "project": {
+    "packages": [...]
+  }
 }
 ```
 

tests/detectors/docker_info/test_docker_info_detection.py

@@ -96,14 +96,14 @@ def _validate_container_info_in_full_result(self, result: Dict[str, Any]) -> Non
         """Validate that container info is present in full analysis result."""
         assert isinstance(result, dict), "Result should be a dictionary"
 
-        # Check for _container-info
-        assert "_container-info" in result, f"Expected '_container-info' in result keys: {list(result.keys())}"
+        # Check for source
+        assert "source" in result, f"Expected 'source' in result keys: {list(result.keys())}"
 
-        container_info = result["_container-info"]
+        container_info = result["source"]
         self._validate_container_info_structure(container_info)
 
         # Should also have other detectors
-        other_detectors = [key for key in result.keys() if key != "_container-info"]
+        other_detectors = [key for key in result.keys() if key != "source"]
         assert len(other_detectors) > 0, "Should have other detectors in full analysis"
 
         print(f"✓ Container info included in full analysis with {len(other_detectors)} other detectors")
@@ -112,11 +112,11 @@ def _validate_container_info_only_result(self, result: Dict[str, Any]) -> None:
         """Validate container-info-only result structure."""
         assert isinstance(result, dict), "Result should be a dictionary"
 
-        # Should only have _container-info
-        assert "_container-info" in result, f"Expected '_container-info' in result keys: {list(result.keys())}"
+        # Should only have source
+        assert "source" in result, f"Expected 'source' in result keys: {list(result.keys())}"
         assert len(result) == 1, f"Container-info-only should have exactly 1 key, got: {list(result.keys())}"
 
-        container_info = result["_container-info"]
+        container_info = result["source"]
         self._validate_container_info_structure(container_info)
 
         print("✓ Container-info-only mode working correctly")
@@ -126,10 +126,13 @@ def _validate_container_info_structure(self, container_info: Dict[str, Any]) ->
         assert isinstance(container_info, dict), "Container info should be a dictionary"
 
         # Required fields
-        required_fields = ["name", "image", "hash"]
+        required_fields = ["type", "name", "image", "hash"]
         for field in required_fields:
             assert field in container_info, f"Container info should have '{field}': {container_info}"
 
+        # Validate type field
+        assert container_info["type"] == "container", f"Type should be 'container': {container_info['type']}"
+
         name = container_info["name"]
         image = container_info["image"]
         hash_value = container_info["hash"]
@@ -171,15 +174,17 @@ def test_orchestrator_only_container_info_mode(self) -> None:
             # Test only_container_info mode
             result = orchestrator.resolve_dependencies(executor, only_container_info=True)
 
-            # Should only contain _container-info
+            # Should only contain source
             assert isinstance(result, dict)
-            assert "_container-info" in result
+            assert "source" in result
             assert len(result) == 1
 
-            container_info = result["_container-info"]
+            container_info = result["source"]
+            assert "type" in container_info
             assert "name" in container_info
             assert "image" in container_info
             assert "hash" in container_info
+            assert container_info["type"] == "container"
 
         finally:
             if container_id:

tests/integration/test_programmatic_interface.py

@@ -260,7 +260,9 @@ def test_resolve_docker_dependencies_as_dict_with_all_args(
 
         mock_orchestrator_instance = MagicMock()
         mock_orchestrator.return_value = mock_orchestrator_instance
-        mock_dependencies = {"_container-info": {"name": "my-container", "image": "ubuntu:20.04", "hash": "abc123"}}
+        mock_dependencies = {
+            "source": {"type": "container", "name": "my-container", "image": "ubuntu:20.04", "hash": "abc123"}
+        }
         mock_orchestrator_instance.resolve_dependencies.return_value = mock_dependencies
 
         # Call function with all arguments