@ngocsangairvds/vsaf 4.0.6 → 4.0.8

package/skills/vds-skill/vds-scripts/vds_cli/tests/unit/test_confluence_sync.py

@@ -0,0 +1,315 @@
+"""Unit tests for confluence_sync module."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import pytest
+from vds_cli.confluence_sync import (
+    ConfluenceHubConfig,
+    PageConfig,
+    RepoConfig,
+    _get_hub_page_id,
+    load_confluence_config,
+    render_page_body,
+    run_confluence_sync,
+    sync_page,
+)
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def sample_config() -> ConfluenceHubConfig:
+    return ConfluenceHubConfig(
+        parent_page_id="57250660",
+        space_key="TTCN24",
+        bitbucket_project="WHO",
+        bitbucket_base_url="http://bitbucket.digital.vn",
+        bitbucket_server="internal",
+        repos=[
+            RepoConfig(
+                slug="vds-scripts",
+                name="vds-scripts",
+                active=True,
+                description="Core scripts",
+            ),
+        ],
+        pages=[
+            PageConfig(
+                title="WHO-Project Ecosystem Documentation",
+                page_id="98997962",
+                page_type="navigation_hub",
+                description="Top-level nav",
+                template="navigation_hub",
+            ),
+            PageConfig(
+                title="Ecosystem Installation Guide",
+                page_id="98997963",
+                page_type="hybrid_guide",
+                description="Setup guide",
+                template="installation_guide",
+            ),
+            PageConfig(
+                title="vds-scripts Quick Reference",
+                page_id="98997964",
+                page_type="quick_reference",
+                description="CLI surface",
+                template="quick_reference",
+                source_files=["AGENTS.md"],
+                bitbucket_links=[
+                    {"path": "docs/ref.md", "label": "Ref"},
+                ],
+            ),
+            PageConfig(
+                title="vds-skills Quick Reference",
+                page_id="98997965",
+                page_type="quick_reference",
+                description="Skill registry",
+                template="quick_reference",
+                repo="vds-skills",
+                source_files=["AGENTS.md"],
+            ),
+            PageConfig(
+                title="Documentation Health Dashboard",
+                page_id="98997968",
+                page_type="generated_dashboard",
+                description="Health status",
+                template="health_dashboard",
+            ),
+            PageConfig(
+                title="Orphan Page",
+                page_id=None,
+                page_type="quick_reference",
+                description="No page id yet",
+                template="quick_reference",
+            ),
+        ],
+    )
+
+
+@pytest.fixture
+def valid_confluence_yaml() -> str:
+    return """
+parent_page_id: "57250660"
+space_key: "TTCN24"
+bitbucket:
+  project: "WHO"
+  base_url: "http://bitbucket.digital.vn"
+  server: "internal"
+repos:
+  - slug: vds-scripts
+    name: vds-scripts
+    active: true
+    description: Core scripts
+pages:
+  - title: WHO-Project Ecosystem Documentation
+    page_id: "98997962"
+    type: navigation_hub
+    description: Top-level nav
+    template: navigation_hub
+"""
+
+
+# ---------------------------------------------------------------------------
+# Config loading
+# ---------------------------------------------------------------------------
+
+
+def test_load_confluence_config_parses_yaml(tmp_path: Path, valid_confluence_yaml: str) -> None:
+    (tmp_path / "docs").mkdir(parents=True)
+    (tmp_path / "docs" / ".confluence.yaml").write_text(valid_confluence_yaml, encoding="utf-8")
+
+    config = load_confluence_config(tmp_path)
+
+    assert config.parent_page_id == "57250660"
+    assert config.space_key == "TTCN24"
+    assert config.bitbucket_project == "WHO"
+    assert config.bitbucket_base_url == "http://bitbucket.digital.vn"
+    assert config.bitbucket_server == "internal"
+    assert len(config.repos) == 1
+    assert config.repos[0].slug == "vds-scripts"
+    assert config.repos[0].active is True
+    assert len(config.pages) == 1
+    assert config.pages[0].title == "WHO-Project Ecosystem Documentation"
+    assert config.pages[0].page_id == "98997962"
+    assert config.pages[0].page_type == "navigation_hub"
+
+
+def test_load_confluence_config_missing_file_raises(tmp_path: Path) -> None:
+    with pytest.raises(ValueError, match="Confluence config not found"):
+        load_confluence_config(tmp_path)
+
+
+# ---------------------------------------------------------------------------
+# Template rendering
+# ---------------------------------------------------------------------------
+
+
+def test_render_navigation_hub(sample_config: ConfluenceHubConfig) -> None:
+    page = sample_config.pages[0]
+    body = render_page_body(sample_config, page)
+
+    assert "<h1>WHO-Project Ecosystem Documentation</h1>" in body
+    assert "vds-scripts" in body
+    assert "Core scripts" in body
+    assert "http://bitbucket.digital.vn/projects/WHO" in body
+
+
+def test_render_installation_guide(sample_config: ConfluenceHubConfig) -> None:
+    page = sample_config.pages[1]
+    body = render_page_body(sample_config, page)
+
+    assert "<h1>Ecosystem Installation Guide</h1>" in body
+    assert "git clone" in body
+    assert "worktree_uv.sh sync" in body
+
+
+def test_render_quick_reference_vds_scripts_fallback(sample_config: ConfluenceHubConfig) -> None:
+    """vds-scripts quick_reference uses fallback content (no sibling worktree load)."""
+    page = sample_config.pages[2]
+    body = render_page_body(sample_config, page, repo_root=Path("/fake"))
+
+    assert "<h1>vds-scripts Quick Reference</h1>" in body
+    assert "CLI surface" in body
+    assert "See linked Bitbucket documentation" in body
+    assert "Ref" in body
+
+
+def test_render_quick_reference_vds_skills_from_sibling_worktree(
+    tmp_path: Path, sample_config: ConfluenceHubConfig
+) -> None:
+    """vds-skills quick_reference loads markdown from sibling worktree when present."""
+    page = sample_config.pages[3]
+    # Create sibling worktree structure: tmp_path is repo_root, parent is worktrees/
+    worktrees = tmp_path.parent
+    wt_skills = worktrees / "confluence-hub-skills" / "docs" / "confluence"
+    wt_skills.mkdir(parents=True)
+    (wt_skills / "vds-skills-quick-ref.md").write_text("# Skills\n\n- skill A\n", encoding="utf-8")
+
+    body = render_page_body(sample_config, page, repo_root=tmp_path)
+
+    assert "<h1>vds-skills Quick Reference</h1>" in body
+    assert "Skill registry" in body
+    assert "skill A" in body
+
+
+def test_render_quick_reference_vds_skills_fallback_when_worktree_missing(
+    tmp_path: Path, sample_config: ConfluenceHubConfig
+) -> None:
+    """vds-skills quick_reference falls back when sibling worktree file is absent."""
+    page = sample_config.pages[3]
+    # Ensure no stale sibling worktree from a prior test under the same pytest tmp root
+    wt_dir = tmp_path.parent / "confluence-hub-skills"
+    if wt_dir.exists():
+        shutil.rmtree(wt_dir)
+
+    body = render_page_body(sample_config, page, repo_root=tmp_path)
+
+    assert "<h1>vds-skills Quick Reference</h1>" in body
+    assert "See linked Bitbucket documentation" in body
+
+
+def test_render_health_dashboard(sample_config: ConfluenceHubConfig) -> None:
+    page = sample_config.pages[4]
+    body = render_page_body(sample_config, page)
+
+    assert "<h1>Documentation Health Dashboard</h1>" in body
+    assert "Validation Results" in body
+    assert "Ownership Model" in body
+
+
+def test_render_unknown_template_fallback(sample_config: ConfluenceHubConfig) -> None:
+    page = PageConfig(
+        title="Custom Page",
+        page_id="999",
+        page_type="custom",
+        description="A custom page",
+        template="unknown_template",
+    )
+    body = render_page_body(sample_config, page)
+
+    assert "<h1>Custom Page</h1>" in body
+    assert "A custom page" in body
+
+
+# ---------------------------------------------------------------------------
+# Hub page id helper
+# ---------------------------------------------------------------------------
+
+
+def test_get_hub_page_id_returns_navigation_hub_id(sample_config: ConfluenceHubConfig) -> None:
+    assert _get_hub_page_id(sample_config) == "98997962"
+
+
+def test_get_hub_page_id_fallback_to_parent_when_no_hub(sample_config: ConfluenceHubConfig) -> None:
+    config_no_hub = ConfluenceHubConfig(
+        parent_page_id="111",
+        space_key="S",
+        bitbucket_project="P",
+        bitbucket_base_url="http://bb",
+        bitbucket_server="internal",
+        repos=[],
+        pages=[
+            PageConfig(
+                title="Other",
+                page_id="222",
+                page_type="quick_reference",
+                description="desc",
+                template="quick_reference",
+            ),
+        ],
+    )
+    assert _get_hub_page_id(config_no_hub) == "111"
+
+
+# ---------------------------------------------------------------------------
+# Sync page (dry-run and error paths)
+# ---------------------------------------------------------------------------
+
+
+def test_sync_page_dry_run_returns_dict_without_api_calls(sample_config: ConfluenceHubConfig, capsys) -> None:
+    page = sample_config.pages[0]
+    result = sync_page(sample_config, page, dry_run=True, repo_root=None)
+
+    assert result == {"dry_run": True, "title": page.title}
+    captured = capsys.readouterr()
+    assert "DRY-RUN" in captured.out
+    assert page.title in captured.out
+
+
+def test_sync_page_skipped_when_no_page_id_and_no_create(sample_config: ConfluenceHubConfig, capsys) -> None:
+    page = sample_config.pages[5]  # Orphan Page with no page_id
+    result = sync_page(sample_config, page, dry_run=False, create_missing=False)
+
+    assert result == {"skipped": True, "title": page.title}
+    captured = capsys.readouterr()
+    assert "Skipped" in captured.out
+
+
+# ---------------------------------------------------------------------------
+# Full orchestration
+# ---------------------------------------------------------------------------
+
+
+def test_run_confluence_sync_filters_by_page_title(tmp_path: Path, valid_confluence_yaml: str) -> None:
+    (tmp_path / "docs").mkdir(parents=True)
+    (tmp_path / "docs" / ".confluence.yaml").write_text(valid_confluence_yaml, encoding="utf-8")
+
+    results = run_confluence_sync(tmp_path, dry_run=True, page_title="WHO-Project Ecosystem Documentation")
+
+    assert len(results) == 1
+    assert results[0]["title"] == "WHO-Project Ecosystem Documentation"
+
+
+def test_run_confluence_sync_processes_all_pages_when_no_filter(tmp_path: Path, valid_confluence_yaml: str) -> None:
+    (tmp_path / "docs").mkdir(parents=True)
+    (tmp_path / "docs" / ".confluence.yaml").write_text(valid_confluence_yaml, encoding="utf-8")
+
+    results = run_confluence_sync(tmp_path, dry_run=True)
+
+    assert len(results) == 1
+    assert results[0]["dry_run"] is True

package/skills/vds-skill/vds-scripts/vds_cli/tests/unit/test_confluence_sync_wave7.py

@@ -0,0 +1,375 @@
+"""Unit tests for confluence_sync Wave 7 additions (DOC-V2-017..022)."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+from vds_cli.confluence_sync import (
+    ConfluenceHubConfig,
+    DocEntry,
+    PageConfig,
+    check_bitbucket_links,
+    check_word_count,
+    render_inventory_table,
+    render_page_body,
+    render_team_view,
+    scan_docs_tree,
+)
+
+# ---------------------------------------------------------------------------
+# DOC-V2-017: check_word_count
+# ---------------------------------------------------------------------------
+
+
+def test_check_word_count_under_threshold_logs_nothing(caplog):
+    body = "word " * 500  # 500 words
+    with caplog.at_level(logging.WARNING):
+        count = check_word_count(body, max_words=800)
+    assert count == 500
+    assert "exceeds" not in caplog.text
+
+
+def test_check_word_count_over_threshold_logs_warning(caplog):
+    body = "word " * 900  # 900 words
+    with caplog.at_level(logging.WARNING):
+        count = check_word_count(body, max_words=800)
+    assert count == 900
+    assert "exceeds" in caplog.text
+    assert "900" in caplog.text
+
+
+def test_check_word_count_custom_max():
+    body = "a b c d e"
+    assert check_word_count(body, max_words=10) == 5
+
+
+# ---------------------------------------------------------------------------
+# DOC-V2-018: scan_docs_tree
+# ---------------------------------------------------------------------------
+
+
+def test_scan_docs_tree_empty_when_no_docs_dir(tmp_path: Path) -> None:
+    result = scan_docs_tree(tmp_path)
+    assert result == []
+
+
+def test_scan_docs_tree_reads_diataxis_header(tmp_path: Path) -> None:
+    docs = tmp_path / "docs" / "agents" / "how-to"
+    docs.mkdir(parents=True)
+    (docs / "setup.md").write_text("# Setup Guide\n\n<!-- diátaxis: how-to -->\n\nDo this.\n", encoding="utf-8")
+
+    entries = scan_docs_tree(tmp_path)
+    assert len(entries) == 1
+    assert entries[0].title == "Setup Guide"
+    assert entries[0].quadrant == "how-to"
+    assert entries[0].repo == tmp_path.name
+
+
+def test_scan_docs_tree_reads_team_tag(tmp_path: Path) -> None:
+    docs = tmp_path / "docs" / "agents" / "reference"
+    docs.mkdir(parents=True)
+    (docs / "api.md").write_text(
+        "# API Ref\n\n<!-- diátaxis: reference -->\n<!-- team: core -->\n\nDetails.\n",
+        encoding="utf-8",
+    )
+
+    entries = scan_docs_tree(tmp_path)
+    assert len(entries) == 1
+    assert entries[0].quadrant == "reference"
+    assert entries[0].team_tag == "core"
+
+
+def test_scan_docs_tree_uncategorized_when_no_header(tmp_path: Path) -> None:
+    docs = tmp_path / "docs" / "agents" / "explanation"
+    docs.mkdir(parents=True)
+    (docs / "overview.md").write_text("# Overview\n\nSome text.\n", encoding="utf-8")
+
+    entries = scan_docs_tree(tmp_path)
+    assert entries[0].quadrant == "uncategorized"
+
+
+def test_scan_docs_tree_sorts_by_quadrant_then_title(tmp_path: Path) -> None:
+    docs = tmp_path / "docs" / "agents"
+    docs.mkdir(parents=True)
+    (docs / "b.md").write_text("# B\n\n<!-- diátaxis: tutorial -->\n", encoding="utf-8")
+    (docs / "a.md").write_text("# A\n\n<!-- diátaxis: tutorial -->\n", encoding="utf-8")
+    (docs / "z.md").write_text("# Z\n\n<!-- diátaxis: how-to -->\n", encoding="utf-8")
+
+    entries = scan_docs_tree(tmp_path)
+    titles = [e.title for e in entries]
+    assert titles == ["Z", "A", "B"]
+
+
+# ---------------------------------------------------------------------------
+# DOC-V2-018: render_inventory_table
+# ---------------------------------------------------------------------------
+
+
+def test_render_inventory_table_empty() -> None:
+    result = render_inventory_table([])
+    assert "No documents found" in result
+
+
+def test_render_inventory_table_generates_xhtml() -> None:
+    docs = [
+        DocEntry(
+            path=Path("docs/agents/how-to/setup.md"),
+            title="Setup Guide",
+            quadrant="how-to",
+            line_count=42,
+            last_modified=0.0,
+            repo="vds-scripts",
+        ),
+        DocEntry(
+            path=Path("docs/agents/reference/api.md"),
+            title="API Reference",
+            quadrant="reference",
+            line_count=100,
+            last_modified=0.0,
+            repo="vds-scripts",
+        ),
+    ]
+    result = render_inventory_table(docs)
+    assert result.startswith("<table>")
+    assert result.endswith("</table>")
+    assert "Setup Guide" in result
+    assert "API Reference" in result
+    assert "how-to" in result
+    assert "reference" in result
+    assert "42" in result
+    assert "100" in result
+
+
+# ---------------------------------------------------------------------------
+# DOC-V2-020: render_team_view
+# ---------------------------------------------------------------------------
+
+
+def test_render_team_view_empty_when_no_match() -> None:
+    docs = [
+        DocEntry(
+            path=Path("a.md"),
+            title="A",
+            quadrant="how-to",
+            line_count=10,
+            last_modified=0.0,
+            repo="r",
+            team_tag="other",
+        ),
+    ]
+    result = render_team_view("core", docs)
+    assert "No documents found" in result
+
+
+def test_render_team_view_filters_by_team() -> None:
+    docs = [
+        DocEntry(
+            path=Path("core.md"),
+            title="Core Doc",
+            quadrant="how-to",
+            line_count=20,
+            last_modified=0.0,
+            repo="r",
+            team_tag="core",
+        ),
+        DocEntry(
+            path=Path("other.md"),
+            title="Other Doc",
+            quadrant="reference",
+            line_count=30,
+            last_modified=0.0,
+            repo="r",
+            team_tag="other",
+        ),
+    ]
+    result = render_team_view("core", docs)
+    assert "Core Doc" in result
+    assert "Other Doc" not in result
+    assert "<table>" in result
+
+
+def test_render_team_view_case_insensitive() -> None:
+    docs = [
+        DocEntry(
+            path=Path("a.md"),
+            title="A",
+            quadrant="how-to",
+            line_count=10,
+            last_modified=0.0,
+            repo="r",
+            team_tag="CORE",
+        ),
+    ]
+    result = render_team_view("core", docs)
+    assert "A" in result
+
+
+# ---------------------------------------------------------------------------
+# DOC-V2-022: check_bitbucket_links
+# ---------------------------------------------------------------------------
+
+
+def test_check_bitbucket_links_all_ok() -> None:
+    config = ConfluenceHubConfig(
+        parent_page_id="1",
+        space_key="S",
+        bitbucket_project="WHO",
+        bitbucket_base_url="http://bb",
+        bitbucket_server="internal",
+        repos=[],
+        pages=[
+            PageConfig(
+                title="Page",
+                page_id="2",
+                page_type="quick_reference",
+                description="desc",
+                template="quick_reference",
+                repo="vds-scripts",
+                bitbucket_links=[{"path": "README.md", "label": "Readme"}],
+            ),
+        ],
+    )
+
+    mock_response = MagicMock()
+    mock_response.getcode.return_value = 200
+    mock_response.__enter__.return_value = mock_response
+    mock_response.__exit__.return_value = False
+
+    with patch("urllib.request.urlopen", return_value=mock_response):
+        results = check_bitbucket_links(config)
+
+    assert len(results) == 1
+    assert results[0]["status"] == "ok"
+    assert results[0]["status_code"] == 200
+
+
+def test_check_bitbucket_links_broken() -> None:
+    config = ConfluenceHubConfig(
+        parent_page_id="1",
+        space_key="S",
+        bitbucket_project="WHO",
+        bitbucket_base_url="http://bb",
+        bitbucket_server="internal",
+        repos=[],
+        pages=[
+            PageConfig(
+                title="Page",
+                page_id="2",
+                page_type="quick_reference",
+                description="desc",
+                template="quick_reference",
+                repo="vds-scripts",
+                bitbucket_links=[{"path": "MISSING.md", "label": "Missing"}],
+            ),
+        ],
+    )
+
+    with patch("urllib.request.urlopen", side_effect=Exception("404")):
+        results = check_bitbucket_links(config)
+
+    assert len(results) == 1
+    assert results[0]["status"] == "broken"
+    assert results[0]["status_code"] is None
+
+
+# ---------------------------------------------------------------------------
+# Template rendering: doc_inventory + team_view
+# ---------------------------------------------------------------------------
+
+
+def test_render_page_body_doc_inventory(tmp_path: Path) -> None:
+    docs = tmp_path / "docs" / "agents" / "how-to"
+    docs.mkdir(parents=True)
+    (docs / "setup.md").write_text("# Setup\n\n<!-- diátaxis: how-to -->\n\nSteps.\n", encoding="utf-8")
+
+    config = ConfluenceHubConfig(
+        parent_page_id="1",
+        space_key="S",
+        bitbucket_project="WHO",
+        bitbucket_base_url="http://bb",
+        bitbucket_server="internal",
+        repos=[],
+        pages=[],
+    )
+    page = PageConfig(
+        title="Inventory",
+        page_id="2",
+        page_type="doc_inventory",
+        description="Auto inventory",
+        template="doc_inventory",
+    )
+
+    body = render_page_body(config, page, repo_root=tmp_path)
+    assert "<h1>Documentation Inventory</h1>" in body
+    assert "how-to" in body
+    assert "Setup" in body
+
+
+def test_render_page_body_team_view(tmp_path: Path) -> None:
+    docs = tmp_path / "docs" / "agents"
+    docs.mkdir(parents=True)
+    (docs / "core.md").write_text(
+        "# Core Doc\n\n<!-- diátaxis: how-to -->\n<!-- team: core -->\n\nText.\n",
+        encoding="utf-8",
+    )
+
+    config = ConfluenceHubConfig(
+        parent_page_id="1",
+        space_key="S",
+        bitbucket_project="WHO",
+        bitbucket_base_url="http://bb",
+        bitbucket_server="internal",
+        repos=[],
+        pages=[],
+    )
+    page = PageConfig(
+        title="Team View: Core",
+        page_id="2",
+        page_type="team_view",
+        description="Team scope: core",
+        template="team_view",
+    )
+
+    body = render_page_body(config, page, repo_root=tmp_path)
+    assert "<h1>Team View: core</h1>" in body
+    assert "Core Doc" in body
+
+
+# ---------------------------------------------------------------------------
+# Integration: run_confluence_sync with validate_links
+# ---------------------------------------------------------------------------
+
+
+def test_run_confluence_sync_validate_links_flag(tmp_path: Path) -> None:
+    from vds_cli.confluence_sync import run_confluence_sync
+
+    yaml_text = """
+parent_page_id: "57250660"
+space_key: "TTCN24"
+bitbucket:
+  project: "WHO"
+  base_url: "http://bb"
+  server: "internal"
+repos: []
+pages:
+  - title: Test Page
+    page_id: "999"
+    type: quick_reference
+    description: desc
+    template: quick_reference
+"""
+    (tmp_path / "docs").mkdir(parents=True)
+    (tmp_path / "docs" / ".confluence.yaml").write_text(yaml_text, encoding="utf-8")
+
+    mock_response = MagicMock()
+    mock_response.getcode.return_value = 200
+    mock_response.__enter__.return_value = mock_response
+    mock_response.__exit__.return_value = False
+
+    with patch("urllib.request.urlopen", return_value=mock_response):
+        results = run_confluence_sync(tmp_path, dry_run=True, validate_links=True)
+
+    assert len(results) == 1
+    assert results[0]["dry_run"] is True