fix path mangling in config docs

Signed-off-by: Alex Goodman <[email protected]>

Author: wagoodman

content/docs/reference/grype/configuration.md

@@ -235,7 +235,7 @@ timestamp: true
 
 db:
   # location to write the vulnerability database cache (env: GRYPE_DB_CACHE_DIR)
-  cache-dir: "~.cache~grype~db"
+  cache-dir: "~/.cache/grype/db"
 
   # URL of the vulnerability database (env: GRYPE_DB_UPDATE_URL)
   update-url: "https://grype.anchore.io/databases"

content/docs/reference/syft/configuration.md

@@ -206,7 +206,7 @@ golang:
   search-local-mod-cache-licenses:
 
   # specify an explicit go mod cache directory, if unset this defaults to $GOPATH/pkg/mod or $HOME/go/pkg/mod (env: SYFT_GOLANG_LOCAL_MOD_CACHE_DIR)
-  local-mod-cache-dir: "~go~pkg~mod"
+  local-mod-cache-dir: "~/go/pkg/mod"
 
   # search for go package licences in the vendor folder on the system running Syft, note that this is outside the
   # container filesystem and potentially outside the root of a local directory scan (env: SYFT_GOLANG_SEARCH_LOCAL_VENDOR_LICENSES)
@@ -253,7 +253,7 @@ java:
 
   # override the default location of the local Maven repository.
   # the default is the subdirectory '.m2/repository' in your home directory (env: SYFT_JAVA_MAVEN_LOCAL_REPOSITORY_DIR)
-  maven-local-repository-dir: "~.m2~repository"
+  maven-local-repository-dir: "~/.m2/repository"
 
   # maven repository to use, defaults to Maven central (env: SYFT_JAVA_MAVEN_URL)
   maven-url: "https://repo1.maven.org/maven2"
@@ -358,7 +358,7 @@ unknowns:
 
 cache:
   # root directory to cache any downloaded content; empty string will use an in-memory cache (env: SYFT_CACHE_DIR)
-  dir: "~.cache~syft"
+  dir: "~/.cache/syft"
 
   # time to live for cached data; setting this to 0 will disable caching entirely (env: SYFT_CACHE_TTL)
   ttl: "7d"

data/grype/config/output.txt

@@ -207,7 +207,7 @@ timestamp: true
 
 db:
   # location to write the vulnerability database cache (env: GRYPE_DB_CACHE_DIR)
-  cache-dir: '~.cache~grype~db'
+  cache-dir: '~/.cache/grype/db'
 
   # URL of the vulnerability database (env: GRYPE_DB_UPDATE_URL)
   update-url: 'https://grype.anchore.io/databases'

data/syft/config/output.txt

@@ -178,7 +178,7 @@ golang:
   search-local-mod-cache-licenses:
 
   # specify an explicit go mod cache directory, if unset this defaults to $GOPATH/pkg/mod or $HOME/go/pkg/mod (env: SYFT_GOLANG_LOCAL_MOD_CACHE_DIR)
-  local-mod-cache-dir: '~go~pkg~mod'
+  local-mod-cache-dir: '~/go/pkg/mod'
 
   # search for go package licences in the vendor folder on the system running Syft, note that this is outside the
   # container filesystem and potentially outside the root of a local directory scan (env: SYFT_GOLANG_SEARCH_LOCAL_VENDOR_LICENSES)
@@ -225,7 +225,7 @@ java:
 
   # override the default location of the local Maven repository.
   # the default is the subdirectory '.m2/repository' in your home directory (env: SYFT_JAVA_MAVEN_LOCAL_REPOSITORY_DIR)
-  maven-local-repository-dir: '~.m2~repository'
+  maven-local-repository-dir: '~/.m2/repository'
 
   # maven repository to use, defaults to Maven central (env: SYFT_JAVA_MAVEN_URL)
   maven-url: 'https://repo1.maven.org/maven2'
@@ -330,7 +330,7 @@ unknowns:
 
 cache:
   # root directory to cache any downloaded content; empty string will use an in-memory cache (env: SYFT_CACHE_DIR)
-  dir: '~.cache~syft'
+  dir: '~/.cache/syft'
 
   # time to live for cached data; setting this to 0 will disable caching entirely (env: SYFT_CACHE_TTL)
   ttl: '7d'

src/generate_reference_config_docs.py

@@ -234,6 +234,7 @@ def get_config_output(image: str, tool_name: str, update: bool = False) -> str |
         return cached.strip()
 
     # run command
+    # note: HOME is set by default in syft.run() to avoid path mangling
     stdout, stderr, returncode = syft.run(
         syft_image=image,
         args=["config"],

src/utils/syft.py

@@ -49,10 +49,15 @@ def run(
     """
     docker_cmd = ["docker", "run", "--pull", "always", "--rm"]
 
-    # add environment variables
+    # always set HOME to avoid path mangling in config output
+    # (e.g., ~/go/pkg/mod becomes ~go~pkg~mod without HOME set)
+    default_env_vars = {"HOME": "/root"}
     if env_vars:
-        for key, value in env_vars.items():
-            docker_cmd.extend(["-e", f"{key}={value}"])
+        default_env_vars.update(env_vars)
+
+    # add environment variables
+    for key, value in default_env_vars.items():
+        docker_cmd.extend(["-e", f"{key}={value}"])
 
     # add volume mounts
     if volumes:

tests/unit/test_generate_reference_config_docs.py

@@ -0,0 +1,204 @@
+import re
+from dataclasses import replace
+from pathlib import Path
+
+import pytest
+
+from generate_reference_config_docs import generate_markdown_content
+from utils.config import paths
+
+
+@pytest.fixture
+def syft_config_cache(tmp_path: Path, monkeypatch) -> Path:
+    """Create a mock cache directory with sample syft config output."""
+    cache_dir = tmp_path / "data" / "syft" / "config"
+    cache_dir.mkdir(parents=True)
+
+    # sample config output with correct paths (as would be generated with HOME=/root)
+    config_output = """log:
+  quiet: false
+  level: 'warn'
+
+golang:
+  local-mod-cache-dir: '~/go/pkg/mod'
+
+java:
+  maven-local-repository-dir: '~/.m2/repository'
+
+cache:
+  dir: '~/.cache/syft'
+"""
+    (cache_dir / "output.txt").write_text(config_output)
+
+    # create version cache
+    version_dir = tmp_path / "data" / "syft" / "version"
+    version_dir.mkdir(parents=True)
+    (version_dir / "output.txt").write_text("1.0.0\n")
+
+    # create a new Paths instance with modified reference_cache_dir
+    new_paths = replace(paths, reference_cache_dir=tmp_path / "data")
+    monkeypatch.setattr("utils.config.paths", new_paths)
+    monkeypatch.setattr("generate_reference_config_docs.config.paths", new_paths)
+
+    return cache_dir
+
+
+@pytest.fixture
+def grype_config_cache(tmp_path: Path, monkeypatch) -> Path:
+    """Create a mock cache directory with sample grype config output."""
+    cache_dir = tmp_path / "data" / "grype" / "config"
+    cache_dir.mkdir(parents=True)
+
+    # sample config output with correct paths
+    config_output = """log:
+  quiet: false
+  level: 'warn'
+
+db:
+  cache-dir: '~/.cache/grype/db'
+"""
+    (cache_dir / "output.txt").write_text(config_output)
+
+    # create version cache
+    version_dir = tmp_path / "data" / "grype" / "version"
+    version_dir.mkdir(parents=True)
+    (version_dir / "output.txt").write_text("0.80.0\n")
+
+    # create a new Paths instance with modified reference_cache_dir
+    new_paths = replace(paths, reference_cache_dir=tmp_path / "data")
+    monkeypatch.setattr("utils.config.paths", new_paths)
+    monkeypatch.setattr("generate_reference_config_docs.config.paths", new_paths)
+
+    return cache_dir
+
+
+class TestPathMangling:
+    """Tests to ensure configuration paths are not mangled."""
+
+    def test_syft_config_paths_not_mangled(self, syft_config_cache: Path) -> None:
+        """Verify syft config output contains properly formatted paths."""
+        content = generate_markdown_content(
+            image="anchore/syft:latest",
+            app_name="syft",
+            tool_name="syft",
+            update=False,
+        )
+
+        # check that proper paths are present
+        assert "~/go/pkg/mod" in content, "Go module cache path should use ~/ not ~"
+        assert "~/.m2/repository" in content, "Maven repository path should use ~/."
+        assert "~/.cache/syft" in content, "Cache dir path should use ~/."
+
+        # check that mangled paths are NOT present
+        assert "~go~pkg~mod" not in content, "Go path should not be mangled"
+        assert "~.m2~repository" not in content, "Maven path should not be mangled"
+        assert "~.cache~syft" not in content, "Cache path should not be mangled"
+
+    def test_grype_config_paths_not_mangled(self, grype_config_cache: Path) -> None:
+        """Verify grype config output contains properly formatted paths."""
+        content = generate_markdown_content(
+            image="anchore/grype:latest",
+            app_name="grype",
+            tool_name="grype",
+            update=False,
+        )
+
+        # check that proper paths are present
+        assert "~/.cache/grype/db" in content, "Cache dir path should use ~/."
+
+        # check that mangled paths are NOT present
+        assert "~.cache~grype~db" not in content, "Cache path should not be mangled"
+
+    @pytest.mark.parametrize(
+        "mangled_pattern,description",
+        [
+            (
+                r"~[^/\s]+~[^/\s]+~",
+                "tilde-separated path components (like ~.cache~syft)",
+            ),
+            (r"'~[a-z0-9]+~", "path starting with tilde followed by word and tilde"),
+        ],
+    )
+    def test_no_mangled_path_patterns(
+        self, syft_config_cache: Path, mangled_pattern: str, description: str
+    ) -> None:
+        """Check for common mangled path patterns in syft config output."""
+        content = generate_markdown_content(
+            image="anchore/syft:latest",
+            app_name="syft",
+            tool_name="syft",
+            update=False,
+        )
+
+        matches = re.findall(mangled_pattern, content)
+        assert not matches, f"Found {description}: {matches}"
+
+
+class TestConfigGeneration:
+    """Tests for config generation functionality."""
+
+    def test_syft_config_contains_yaml_block(self, syft_config_cache: Path) -> None:
+        """Verify generated content contains YAML code block."""
+        content = generate_markdown_content(
+            image="anchore/syft:latest",
+            app_name="syft",
+            tool_name="syft",
+            update=False,
+        )
+
+        assert "```yaml" in content
+        assert "```" in content
+        assert "log:" in content
+
+    def test_grype_config_contains_yaml_block(self, grype_config_cache: Path) -> None:
+        """Verify generated content contains YAML code block."""
+        content = generate_markdown_content(
+            image="anchore/grype:latest",
+            app_name="grype",
+            tool_name="grype",
+            update=False,
+        )
+
+        assert "```yaml" in content
+        assert "```" in content
+        assert "log:" in content
+
+    def test_syft_config_contains_version_info(self, syft_config_cache: Path) -> None:
+        """Verify generated content includes version information."""
+        content = generate_markdown_content(
+            image="anchore/syft:latest",
+            app_name="syft",
+            tool_name="syft",
+            update=False,
+        )
+
+        # version info is included even if it's "unknown" from cache miss
+        assert "Syft version" in content
+        assert "{{< alert" in content
+
+    def test_grype_config_contains_version_info(self, grype_config_cache: Path) -> None:
+        """Verify generated content includes version information."""
+        content = generate_markdown_content(
+            image="anchore/grype:latest",
+            app_name="grype",
+            tool_name="grype",
+            update=False,
+        )
+
+        # version info is included even if it's "unknown" from cache miss
+        assert "Grype version" in content
+        assert "{{< alert" in content
+
+    def test_config_contains_search_locations(self, syft_config_cache: Path) -> None:
+        """Verify generated content includes config search locations."""
+        content = generate_markdown_content(
+            image="anchore/syft:latest",
+            app_name="syft",
+            tool_name="syft",
+            update=False,
+        )
+
+        assert "./.syft.yaml" in content
+        assert "./.syft/config.yaml" in content
+        assert "~/.syft.yaml" in content
+        assert "$XDG_CONFIG_HOME/syft/config.yaml" in content