Merge branch 'auto/gardenlinux/4811' of ssh://github.com/gardenlinux/docs-ng into auto/gardenlinux/4811

Author: yeoldegrove

.github/workflows/tests-skip.yml

@@ -0,0 +1,30 @@
+name: Tests (skip)
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - 'src/**'
+      - 'tests/**'
+      - 'requirements.txt'
+      - 'Makefile'
+      - '.github/workflows/tests.yml'
+      - '.github/workflows/tests-skip.yml'
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - 'src/**'
+      - 'tests/**'
+      - 'requirements.txt'
+      - 'Makefile'
+      - '.github/workflows/tests.yml'
+      - '.github/workflows/tests-skip.yml'
+
+jobs:
+  pytest:
+    name: pytest (unit + integration)
+    runs-on: ubuntu-24.04
+    steps:
+      - run: |
+          echo "No changes under src/, tests/, requirements.txt, or Makefile."
+          echo "Skipping test run; reporting success so a required check is satisfied."

.github/workflows/tests.yml

@@ -0,0 +1,42 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - 'requirements.txt'
+      - 'Makefile'
+      - '.github/workflows/tests.yml'
+      - '.github/workflows/tests-skip.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - 'requirements.txt'
+      - 'Makefile'
+      - '.github/workflows/tests.yml'
+      - '.github/workflows/tests-skip.yml'
+
+jobs:
+  pytest:
+    name: pytest (unit + integration)
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # pin@v6.2.0
+        with:
+          python-version: "3.13"
+
+      - name: Install Python dependencies
+        run: |
+          pip install git+https://github.com/gardenlinux/glrd.git@v4.1.0
+          pip install git+https://github.com/gardenlinux/python-gardenlinux-lib.git@0.10.20
+          pip install -r requirements.txt
+
+      - name: Run tests
+        run: make test

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help run dev build preview aggregate aggregate-repo test-aggregate-local clean clean-projects clean-aggregated-git test test-unit test-integration check spelling linkcheck woke
+.PHONY: help run build preview aggregate aggregate-repo test-aggregate-local clean clean-projects clean-aggregated-git test test-unit test-integration check spelling linkcheck woke
 
 help:
 	@echo "Garden Linux Documentation Hub - Available targets:"
@@ -9,9 +9,9 @@ help:
 	@echo "    preview                - Preview production build locally"
 	@echo ""
 	@echo "  Testing:"
-	@echo "    test                   - Run full test suite (38 tests: unit + integration)"
-	@echo "    test-unit              - Run unit tests only (35 tests)"
-	@echo "    test-integration       - Run integration tests only (3 tests)"
+	@echo "    test                   - Run full test suite (unit + integration)"
+	@echo "    test-unit              - Run unit tests only"
+	@echo "    test-integration       - Run integration tests only"
 	@echo ""
 	@echo "  Quality Checks:"
 	@echo "    check                  - Run all quality checks (spelling, links, inclusive language)"
@@ -35,9 +35,9 @@ install:
 	pnpm install
 	pip install git+https://github.com/gardenlinux/glrd.git@v4.1.0
 	pip install git+https://github.com/gardenlinux/python-gardenlinux-lib.git@0.10.20
-	pip install -r requirements.txt	
+	pip install -r requirements.txt
 
-dev:
+run:
 	pnpm run docs:dev
 
 build: install clean aggregate

docs/contributing/documentation/working-locally.md

@@ -75,7 +75,7 @@ This copies documentation from local repositories without using git.
 ### Step 4: Start the Development Server
 
 ```bash
-make dev
+make run
 ```
 
 The documentation site will be available at `http://localhost:5173`.
@@ -146,7 +146,7 @@ If you encounter issues, try a clean build:
 ```bash
 make clean
 make aggregate
-make dev
+make run
 ```
 
 ### Check Dependencies

repos-config.json

@@ -6,7 +6,7 @@
       "docs_path": "docs",
       "target_path": "projects/gardenlinux",
       "ref": "docs/pxe_iso",
-      "commit": "686463497e643a9b1e5427252a46cc80e3915c01",
+      "commit": "b729180904c47be25baeb95ce5105e1f9ad8efba",
       "root_files": [
         "CONTRIBUTING.md",
         "SECURITY.md",

src/README.md

@@ -273,7 +273,7 @@ def main() -> int:
 
     print("\nNext steps:")
     print("  1. Review the changes in docs/projects/")
-    print("  2. Run 'make dev' or 'pnpm run docs:dev' to preview")
+    print("  2. Run 'make run' or 'pnpm run docs:dev' to preview")
     print("  3. Commit the changes if satisfied")
 
     return 0 if fail_count == 0 else 1

src/aggregate.py

@@ -7,6 +7,22 @@
 from aggregation import DocsFetcher, RepoConfig, process_all_markdown
 
 
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+def _make_output_dir(tmp_path: Path) -> Path:
+    """Create and return a fresh output directory under tmp_path."""
+    output_dir = tmp_path / "output"
+    output_dir.mkdir(exist_ok=True)
+    return output_dir
+
+
+def _make_fetcher(project_root: Path) -> DocsFetcher:
+    """Return a DocsFetcher anchored at project_root."""
+    return DocsFetcher(project_root)
+
+
 class TestDocsFetcher:
     """Integration tests for DocsFetcher."""
 
@@ -31,14 +47,11 @@ def test_fetch_local_with_temp_dir(self, tmp_path):
             url=f"file://{repo_path}",
             docs_path="docs",
             target_path="projects/test-repo",
+            ref="",
         )
 
-        # Fetch the docs
-        output_dir = tmp_path / "output"
-        output_dir.mkdir()
-        
-        fetcher = DocsFetcher(tmp_path)
-        result = fetcher.fetch(repo, output_dir)
+        output_dir = _make_output_dir(tmp_path)
+        result = _make_fetcher(tmp_path).fetch(repo, output_dir)
 
         # Verify success
         assert result.success is True
@@ -52,6 +65,87 @@ def test_fetch_local_with_temp_dir(self, tmp_path):
         # Verify content
         assert "Test Documentation" in (output_dir / "index.md").read_text()
 
+    def test_fetch_local_missing_docs_path(self, tmp_path, capsys):
+        """Test that a missing docs_path results in success=True, no files copied, and a warning."""
+        repo_path = tmp_path / "mock-repo"
+        repo_path.mkdir(parents=True)
+        # Intentionally do NOT create a 'docs' directory
+
+        repo = RepoConfig(
+            name="test-repo",
+            url=f"file://{repo_path}",
+            docs_path="docs",  # Does not exist
+            target_path="projects/test-repo",
+            ref="",
+        )
+
+        output_dir = _make_output_dir(tmp_path)
+        result = _make_fetcher(tmp_path).fetch(repo, output_dir)
+
+        # Fetch should still report success (warning is printed but not fatal)
+        assert result.success is True
+        # Output directory should be empty (nothing was copied)
+        assert list(output_dir.iterdir()) == []
+        # A warning about the missing docs_path must have been emitted to stdout
+        captured = capsys.readouterr()
+        assert "Warning" in captured.out
+        assert "docs" in captured.out
+
+    def test_fetch_local_with_root_files_glob(self, tmp_path):
+        """Test that root_files with a glob pattern copies only matched files."""
+        repo_path = tmp_path / "mock-repo"
+        features_dir = repo_path / "features" / "foo"
+        features_dir.mkdir(parents=True)
+        (features_dir / "bar.md").write_text("# Feature Bar")
+        (features_dir / "baz.md").write_text("# Feature Baz")
+        # A file that should NOT match the glob
+        (repo_path / "CHANGELOG.md").write_text("# Changes")
+
+        repo = RepoConfig(
+            name="test-repo",
+            url=f"file://{repo_path}",
+            docs_path="nonexistent-docs",  # No standard docs; only root_files
+            target_path="projects/test-repo",
+            ref="",
+            root_files=["features/foo/*.md"],
+        )
+
+        output_dir = _make_output_dir(tmp_path)
+        result = _make_fetcher(tmp_path).fetch(repo, output_dir)
+
+        assert result.success is True
+        # Glob-matched files should be present at their relative paths
+        assert (output_dir / "features" / "foo" / "bar.md").exists()
+        assert (output_dir / "features" / "foo" / "baz.md").exists()
+        # Non-matching file should NOT be present
+        assert not (output_dir / "CHANGELOG.md").exists()
+
+    def test_fetch_local_resolves_relative_path(self, tmp_path):
+        """Test that a relative file:// URL is resolved against project_root."""
+        # Simulate a sibling-directory layout: project_root and mock-repo are siblings
+        project_root = tmp_path / "docs-ng"
+        project_root.mkdir()
+
+        repo_path = tmp_path / "mock-repo"
+        docs_path = repo_path / "docs"
+        docs_path.mkdir(parents=True)
+        (docs_path / "index.md").write_text("# Hello from relative repo")
+
+        repo = RepoConfig(
+            name="relative-repo",
+            url="file://../mock-repo",
+            docs_path="docs",
+            target_path="projects/relative-repo",
+            ref="",
+        )
+
+        output_dir = _make_output_dir(tmp_path)
+        result = _make_fetcher(project_root).fetch(repo, output_dir)
+
+        assert result.success is True
+        assert (output_dir / "index.md").exists()
+        assert "Hello from relative repo" in (output_dir / "index.md").read_text()
+
 
 class TestMarkdownProcessing:
     """Integration tests for markdown processing."""

tests/integration/test_aggregation.py

@@ -144,6 +144,7 @@ def test_save_multiple_repos(self, tmp_path):
                 url="file://../repo2",
                 docs_path="docs",
                 target_path="projects/repo2",
+                ref="",
             ),
         ]
         config_file = tmp_path / "config.json"
@@ -223,3 +224,103 @@ def test_round_trip(self, tmp_path):
         assert loaded_repos[0].url == original_repos[0].url
         assert loaded_repos[0].commit == original_repos[0].commit
         assert loaded_repos[0].root_files == original_repos[0].root_files
+
+    def test_load_config_rejects_invalid_scheme(self, tmp_path):
+        """Test that a repo with an invalid URL scheme causes SystemExit via validate()."""
+        config_data = {
+            "repos": [
+                {
+                    "name": "bad",
+                    "url": "ftp://example.com/repo",
+                    "docs_path": "docs",
+                    "target_path": "projects/bad",
+                    "ref": "main",
+                }
+            ]
+        }
+        config_file = tmp_path / "config.json"
+        config_file.write_text(json.dumps(config_data))
+
+        with pytest.raises(SystemExit):
+            load_config(str(config_file))
+
+    def test_save_preserves_structure_dict(self, tmp_path):
+        """Test that a dict structure survives a save/load round trip."""
+        structure_map = {"old_dir": "new_dir", "another": "different"}
+        repos = [
+            RepoConfig(
+                name="test-repo",
+                url="https://github.com/test/repo",
+                docs_path="docs",
+                target_path="projects/test",
+                ref="main",
+                structure=structure_map,
+            )
+        ]
+        config_file = tmp_path / "config.json"
+
+        save_config(str(config_file), repos)
+        loaded_repos = load_config(str(config_file))
+
+        assert loaded_repos[0].structure == structure_map
+
+    def test_save_omits_default_structure_flat(self, tmp_path):
+        """Test that structure='flat' is not written to the JSON output."""
+        repos = [
+            RepoConfig(
+                name="test-repo",
+                url="https://github.com/test/repo",
+                docs_path="docs",
+                target_path="projects/test",
+                ref="main",
+            )
+        ]
+        config_file = tmp_path / "config.json"
+
+        save_config(str(config_file), repos)
+
+        with open(config_file) as f:
+            data = json.load(f)
+
+        assert "structure" not in data["repos"][0]
+
+    def test_save_preserves_target_map_and_special_files(self, tmp_path):
+        """Test that target_map and special_files survive a save/load round trip."""
+        repos = [
+            RepoConfig(
+                name="test-repo",
+                url="https://github.com/test/repo",
+                docs_path="docs",
+                target_path="projects/test",
+                ref="main",
+                target_map={"src/api.md": "api/index.md"},
+                special_files={"CHANGELOG.md": "reference/"},
+            )
+        ]
+        config_file = tmp_path / "config.json"
+
+        save_config(str(config_file), repos)
+        loaded_repos = load_config(str(config_file))
+
+        assert loaded_repos[0].target_map == {"src/api.md": "api/index.md"}
+        assert loaded_repos[0].special_files == {"CHANGELOG.md": "reference/"}
+
+    def test_save_local_repo_omits_empty_ref(self, tmp_path):
+        """Test that local repos with ref='' do not emit a 'ref' key in JSON."""
+        repos = [
+            RepoConfig(
+                name="local-repo",
+                url="file://../some-repo",
+                docs_path="docs",
+                target_path="projects/some-repo",
+                ref="",
+            )
+        ]
+        config_file = tmp_path / "config.json"
+
+        save_config(str(config_file), repos)
+
+        with open(config_file) as f:
+            data = json.load(f)
+
+        assert "ref" not in data["repos"][0]