mkdocs2confluence 0.5.27__tar.gz → 0.6.0__tar.gz

{mkdocs2confluence-0.5.27/src/mkdocs2confluence.egg-info → mkdocs2confluence-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.5.27
+Version: 0.6.0
 Summary: Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more
 Author: Anders Hybertz
 License: GPL-3.0-or-later
@@ -40,6 +40,7 @@ Dynamic: license-file
 
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/mkdocs2confluence)](https://pypi.org/project/mkdocs2confluence/)
 [![Latest Release](https://img.shields.io/github/v/release/jeckyl2010/mkdocs2confluence)](https://github.com/jeckyl2010/mkdocs2confluence/releases/latest)
 [![CI](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/ci.yml/badge.svg)](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/ci.yml)
 [![Release](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/release.yml/badge.svg)](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/release.yml)
@@ -132,7 +133,7 @@ The `--html` flag renders Confluence macros as visual HTML panels so you can rev
 Compile all pages listed in `nav:` and publish them to Confluence Cloud.
 
 ```
-mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--report FILE]
+mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--report FILE] [--prune]
 ```
 
 | Flag | Default | Description |
@@ -142,6 +143,7 @@ mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--re
 | `--section PATH` | *(whole nav)* | Publish only a nav subtree (e.g. `Guide` or `Guide/Setup`) |
 | `--dry-run` | off | Print the publish plan without making any API calls |
 | `--report FILE` | *(none)* | Write a JSON publish report to `FILE` |
+| `--prune` | off | Delete managed Confluence pages no longer in `nav:` (see [Orphan pruning](#orphan-pruning)) |
 
 #### Configuration
 
@@ -169,6 +171,20 @@ The API token is read from (in priority order):
 - Pages with `ready: false` in their YAML front matter are **skipped**, even if listed in the nav.
 - Section nodes (nav groups without a page) become empty parent pages in Confluence, mirroring the nav hierarchy.
 - All locally linked assets are uploaded as Confluence page attachments automatically.
+- **Smart update detection** — before calling the Confluence update API, mk2conf compares a `sha256` hash of the compiled output against the hash stored from the previous run (kept as a hidden Confluence page property `mk2conf-content-hash`). Pages whose content has not changed are skipped entirely — no version bump, no watcher notification.
+- **Orphan pruning** — every page created by mk2conf is stamped with a hidden `mk2conf-managed` property. Pass `--prune` to automatically delete managed pages that have been removed from `nav:`. Manually-created Confluence pages are never deleted.
+
+#### Orphan pruning
+
+```bash
+mk2conf publish --prune
+```
+
+After each publish run, `--prune` fetches all descendants of the configured `parent_page_id`, diffs them against the pages just published, and deletes any managed orphans — i.e. pages that carry the `mk2conf-managed` stamp but are no longer in the MkDocs nav.
+
+> **Safety:** Only pages stamped by mk2conf are eligible for deletion. Any page created directly in Confluence will never be touched, even if it sits inside the managed hierarchy.
+>
+> **Partial runs:** `--prune` is silently ignored when `--page` or `--section` is used, because a partial publish would only cover a subset of the nav and would incorrectly identify out-of-scope pages as orphans.
 
 #### Mermaid rendering
 
@@ -319,7 +335,7 @@ Any unrecognised block is preserved as a visible `warning` macro — no content
 
 ## Roadmap
 
-- [ ] **Delete orphaned pages** — detect and remove Confluence pages that were previously published but have since been removed from `nav:`.
+- [x] **Delete orphaned pages** — `--prune` detects and removes managed Confluence pages that have been removed from `nav:`. Manually-created pages are never deleted.
 
 ---
 

{mkdocs2confluence-0.5.27 → mkdocs2confluence-0.6.0}/README.md

@@ -2,6 +2,7 @@
 
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/mkdocs2confluence)](https://pypi.org/project/mkdocs2confluence/)
 [![Latest Release](https://img.shields.io/github/v/release/jeckyl2010/mkdocs2confluence)](https://github.com/jeckyl2010/mkdocs2confluence/releases/latest)
 [![CI](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/ci.yml/badge.svg)](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/ci.yml)
 [![Release](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/release.yml/badge.svg)](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/release.yml)
@@ -94,7 +95,7 @@ The `--html` flag renders Confluence macros as visual HTML panels so you can rev
 Compile all pages listed in `nav:` and publish them to Confluence Cloud.
 
 ```
-mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--report FILE]
+mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--report FILE] [--prune]
 ```
 
 | Flag | Default | Description |
@@ -104,6 +105,7 @@ mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--re
 | `--section PATH` | *(whole nav)* | Publish only a nav subtree (e.g. `Guide` or `Guide/Setup`) |
 | `--dry-run` | off | Print the publish plan without making any API calls |
 | `--report FILE` | *(none)* | Write a JSON publish report to `FILE` |
+| `--prune` | off | Delete managed Confluence pages no longer in `nav:` (see [Orphan pruning](#orphan-pruning)) |
 
 #### Configuration
 
@@ -131,6 +133,20 @@ The API token is read from (in priority order):
 - Pages with `ready: false` in their YAML front matter are **skipped**, even if listed in the nav.
 - Section nodes (nav groups without a page) become empty parent pages in Confluence, mirroring the nav hierarchy.
 - All locally linked assets are uploaded as Confluence page attachments automatically.
+- **Smart update detection** — before calling the Confluence update API, mk2conf compares a `sha256` hash of the compiled output against the hash stored from the previous run (kept as a hidden Confluence page property `mk2conf-content-hash`). Pages whose content has not changed are skipped entirely — no version bump, no watcher notification.
+- **Orphan pruning** — every page created by mk2conf is stamped with a hidden `mk2conf-managed` property. Pass `--prune` to automatically delete managed pages that have been removed from `nav:`. Manually-created Confluence pages are never deleted.
+
+#### Orphan pruning
+
+```bash
+mk2conf publish --prune
+```
+
+After each publish run, `--prune` fetches all descendants of the configured `parent_page_id`, diffs them against the pages just published, and deletes any managed orphans — i.e. pages that carry the `mk2conf-managed` stamp but are no longer in the MkDocs nav.
+
+> **Safety:** Only pages stamped by mk2conf are eligible for deletion. Any page created directly in Confluence will never be touched, even if it sits inside the managed hierarchy.
+>
+> **Partial runs:** `--prune` is silently ignored when `--page` or `--section` is used, because a partial publish would only cover a subset of the nav and would incorrectly identify out-of-scope pages as orphans.
 
 #### Mermaid rendering
 
@@ -281,7 +297,7 @@ Any unrecognised block is preserved as a visible `warning` macro — no content
 
 ## Roadmap
 
-- [ ] **Delete orphaned pages** — detect and remove Confluence pages that were previously published but have since been removed from `nav:`.
+- [x] **Delete orphaned pages** — `--prune` detects and removes managed Confluence pages that have been removed from `nav:`. Manually-created pages are never deleted.
 
 ---
 

{mkdocs2confluence-0.5.27 → mkdocs2confluence-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs2confluence"
-version = "0.5.27"
+version = "0.6.0"
 description = "Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more"
 readme = "README.md"
 license = { text = "GPL-3.0-or-later" }

{mkdocs2confluence-0.5.27 → mkdocs2confluence-0.6.0/src/mkdocs2confluence.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.5.27
+Version: 0.6.0
 Summary: Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more
 Author: Anders Hybertz
 License: GPL-3.0-or-later
@@ -40,6 +40,7 @@ Dynamic: license-file
 
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/mkdocs2confluence)](https://pypi.org/project/mkdocs2confluence/)
 [![Latest Release](https://img.shields.io/github/v/release/jeckyl2010/mkdocs2confluence)](https://github.com/jeckyl2010/mkdocs2confluence/releases/latest)
 [![CI](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/ci.yml/badge.svg)](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/ci.yml)
 [![Release](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/release.yml/badge.svg)](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/release.yml)
@@ -132,7 +133,7 @@ The `--html` flag renders Confluence macros as visual HTML panels so you can rev
 Compile all pages listed in `nav:` and publish them to Confluence Cloud.
 
 ```
-mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--report FILE]
+mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--report FILE] [--prune]
 ```
 
 | Flag | Default | Description |
@@ -142,6 +143,7 @@ mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--re
 | `--section PATH` | *(whole nav)* | Publish only a nav subtree (e.g. `Guide` or `Guide/Setup`) |
 | `--dry-run` | off | Print the publish plan without making any API calls |
 | `--report FILE` | *(none)* | Write a JSON publish report to `FILE` |
+| `--prune` | off | Delete managed Confluence pages no longer in `nav:` (see [Orphan pruning](#orphan-pruning)) |
 
 #### Configuration
 
@@ -169,6 +171,20 @@ The API token is read from (in priority order):
 - Pages with `ready: false` in their YAML front matter are **skipped**, even if listed in the nav.
 - Section nodes (nav groups without a page) become empty parent pages in Confluence, mirroring the nav hierarchy.
 - All locally linked assets are uploaded as Confluence page attachments automatically.
+- **Smart update detection** — before calling the Confluence update API, mk2conf compares a `sha256` hash of the compiled output against the hash stored from the previous run (kept as a hidden Confluence page property `mk2conf-content-hash`). Pages whose content has not changed are skipped entirely — no version bump, no watcher notification.
+- **Orphan pruning** — every page created by mk2conf is stamped with a hidden `mk2conf-managed` property. Pass `--prune` to automatically delete managed pages that have been removed from `nav:`. Manually-created Confluence pages are never deleted.
+
+#### Orphan pruning
+
+```bash
+mk2conf publish --prune
+```
+
+After each publish run, `--prune` fetches all descendants of the configured `parent_page_id`, diffs them against the pages just published, and deletes any managed orphans — i.e. pages that carry the `mk2conf-managed` stamp but are no longer in the MkDocs nav.
+
+> **Safety:** Only pages stamped by mk2conf are eligible for deletion. Any page created directly in Confluence will never be touched, even if it sits inside the managed hierarchy.
+>
+> **Partial runs:** `--prune` is silently ignored when `--page` or `--section` is used, because a partial publish would only cover a subset of the nav and would incorrectly identify out-of-scope pages as orphans.
 
 #### Mermaid rendering
 
@@ -319,7 +335,7 @@ Any unrecognised block is preserved as a visible `warning` macro — no content
 
 ## Roadmap
 
-- [ ] **Delete orphaned pages** — detect and remove Confluence pages that were previously published but have since been removed from `nav:`.
+- [x] **Delete orphaned pages** — `--prune` detects and removes managed Confluence pages that have been removed from `nav:`. Manually-created pages are never deleted.
 
 ---
 

{mkdocs2confluence-0.5.27 → mkdocs2confluence-0.6.0}/src/mkdocs_to_confluence/__init__.py

@@ -3,6 +3,6 @@
 from importlib.metadata import PackageNotFoundError, version
 
 try:
-    __version__ = version("mkdocs-to-confluence")
+    __version__ = version("mkdocs2confluence")
 except PackageNotFoundError:
     __version__ = "unknown"

{mkdocs2confluence-0.5.27 → mkdocs2confluence-0.6.0}/src/mkdocs_to_confluence/cli.py

@@ -115,6 +115,15 @@ def _build_parser() -> argparse.ArgumentParser:
         default=None,
         help="Write a JSON publish report to FILE after the run.",
     )
+    publish.add_argument(
+        "--prune",
+        action="store_true",
+        help=(
+            "Delete managed Confluence pages that are no longer in the MkDocs nav. "
+            "Only pages stamped by mk2conf are eligible — manually-created pages are never deleted. "
+            "Ignored when --page or --section is used."
+        ),
+    )
 
     return parser
 
@@ -308,10 +317,14 @@ def _cmd_publish(args: argparse.Namespace) -> None:
                 )
                 sys.exit(1)
             plan = plan_publish(nav_nodes, client, config, conf_config, space_id=space_id)
+            # --prune is silently disabled for partial publishes (--page / --section)
+            # because published_ids would only cover the subset, not the full nav.
+            partial = bool(getattr(args, "page", None) or getattr(args, "section", None))
             report = execute_publish(
                 plan, client, dry_run=False, space_id=space_id,
                 docs_dir=config.docs_dir, full_width=conf_config.full_width,
                 root_page_id=conf_config.parent_page_id,
+                prune=getattr(args, "prune", False) and not partial,
             )
     except ConfluenceError as exc:
         print(f"error: {exc}", file=sys.stderr)

{mkdocs2confluence-0.5.27 → mkdocs2confluence-0.6.0}/src/mkdocs_to_confluence/publisher/client.py

@@ -9,12 +9,20 @@ from __future__ import annotations
 import base64
 from pathlib import Path
 from typing import Any, cast
+from urllib.parse import parse_qs, urlparse
 
 import httpx
 
 from mkdocs_to_confluence.loader.config import ConfluenceConfig
 
 
+def _extract_cursor(next_url: str) -> str:
+    """Extract the ``cursor`` query parameter from a pagination ``next`` URL."""
+    qs = parse_qs(urlparse(next_url).query)
+    cursors = qs.get("cursor", [])
+    return cursors[0] if cursors else ""
+
+
 class ConfluenceError(RuntimeError):
     """Raised when the Confluence API returns an unexpected response."""
 
@@ -409,3 +417,59 @@ class ConfluenceClient:
             headers={"X-Atlassian-Token": "no-check"},
         )
         self._raise_for_status(resp, f"upload_attachment({filename!r})")
+
+    # ── Orphan detection ───────────────────────────────────────────────────────
+
+    def stamp_managed(self, page_id: str) -> None:
+        """Mark *page_id* as managed by mk2conf via a v2 content property.
+
+        The property ``mk2conf-managed`` is set to ``true`` on first publish and
+        never updated.  It is used by :meth:`is_managed` to distinguish pages
+        created by mk2conf from manually-created Confluence pages.
+
+        Errors are swallowed — this is a best-effort stamp and must never block
+        a publish.
+        """
+        url = self._v2(f"/pages/{page_id}/properties/mk2conf-managed")
+        get_resp = self._http.get(url)
+        if get_resp.status_code == 200:
+            return  # already stamped
+        self._http.post(
+            self._v2(f"/pages/{page_id}/properties"),
+            json={"key": "mk2conf-managed", "value": True},
+        )
+
+    def get_descendant_ids(self, page_id: str) -> list[str]:
+        """Return all descendant page IDs under *page_id* at all depths.
+
+        Uses ``GET /wiki/api/v2/pages/{id}/descendants?depth=all``.
+        Paginates automatically via cursor.  Returns page IDs only — callers
+        that need to filter by managed status use :meth:`is_managed`.
+        """
+        ids: list[str] = []
+        url = self._v2(f"/pages/{page_id}/descendants")
+        params: dict[str, str | int] = {"depth": "all", "limit": 250}
+        while True:
+            resp = self._http.get(url, params=params)
+            self._raise_for_status(resp, f"get_descendant_ids({page_id!r})")
+            data = resp.json()
+            for item in data.get("results", []):
+                if item.get("type") == "page":
+                    ids.append(str(item["id"]))
+            next_url = data.get("_links", {}).get("next")
+            if not next_url:
+                break
+            # next_url is an absolute path — extract cursor and re-request
+            url = self._v2(f"/pages/{page_id}/descendants")
+            params = {"depth": "all", "limit": 250, "cursor": _extract_cursor(next_url)}
+        return ids
+
+    def is_managed(self, page_id: str) -> bool:
+        """Return ``True`` if *page_id* has the ``mk2conf-managed`` property."""
+        resp = self._http.get(self._v2(f"/pages/{page_id}/properties/mk2conf-managed"))
+        return resp.status_code == 200
+
+    def delete_page(self, page_id: str) -> None:
+        """Permanently delete *page_id* from Confluence."""
+        resp = self._http.delete(self._v2(f"/pages/{page_id}"))
+        self._raise_for_status(resp, f"delete_page({page_id!r})")

{mkdocs2confluence-0.5.27 → mkdocs2confluence-0.6.0}/src/mkdocs_to_confluence/publisher/pipeline.py

@@ -88,6 +88,7 @@ class PublishReport:
     skipped: int = 0
     assets_uploaded: int = 0
     assets_skipped: int = 0
+    pruned: int = 0
     errors: list[tuple[str, str]] = field(default_factory=list)
 
     @property
@@ -99,6 +100,8 @@ class PublishReport:
             f"Published:  {self.created} created, {self.updated} updated, {self.skipped} skipped",
             f"Assets:     {self.assets_uploaded} uploaded, {self.assets_skipped} skipped",
         ]
+        if self.pruned:
+            lines.append(f"Pruned:     {self.pruned} orphaned page(s) deleted")
         if self.errors:
             lines.append(f"Errors:     {len(self.errors)}")
             for title, msg in self.errors:
@@ -463,6 +466,7 @@ def execute_publish(
     docs_dir: Path,
     full_width: bool = True,
     root_page_id: str | None = None,
+    prune: bool = False,
 ) -> PublishReport:
     """Execute the publish plan.
 
@@ -563,6 +567,10 @@ def execute_publish(
                 )
                 action.page_id = str(page["id"])
                 report.created += 1
+                try:
+                    client.stamp_managed(action.page_id)
+                except Exception:
+                    pass  # non-fatal
             elif action.action == "update":
                 assert action.page_id is not None
                 assert action.version is not None
@@ -598,6 +606,10 @@ def execute_publish(
                     )
                     action.page_id = str(page["id"])
                     report.created += 1
+                    try:
+                        client.stamp_managed(action.page_id)
+                    except Exception:
+                        pass  # non-fatal
         except Exception as exc:
             report.errors.append((action.title, str(exc)))
             # Do NOT `continue` — all post-execute blocks below are guarded by
@@ -645,4 +657,41 @@ def execute_publish(
             for name, msg in asset_errors:
                 report.errors.append((f"{action.title} / {name}", msg))
 
+    if prune and root_page_id:
+        published_ids = {a.page_id for a in plan if a.page_id}
+        _prune_orphans(client, root_page_id, published_ids, report)
+
     return report
+
+
+def _prune_orphans(
+    client: ConfluenceClient,
+    root_page_id: str,
+    published_ids: set[str],
+    report: PublishReport,
+) -> None:
+    """Delete managed descendant pages that are no longer in the publish plan.
+
+    Only pages that carry the ``mk2conf-managed`` property are eligible for
+    deletion — manually-created Confluence pages are left untouched.
+    """
+    try:
+        all_descendants = client.get_descendant_ids(root_page_id)
+    except Exception as exc:
+        print(f"  [warn] prune: could not fetch descendants — {exc}")
+        return
+
+    orphan_candidates = [pid for pid in all_descendants if pid not in published_ids]
+    if not orphan_candidates:
+        return
+
+    print(f"\nPruning: checking {len(orphan_candidates)} orphan candidate(s)...")
+    for page_id in orphan_candidates:
+        try:
+            if not client.is_managed(page_id):
+                continue
+            client.delete_page(page_id)
+            report.pruned += 1
+            print(f"  deleted orphan page {page_id}")
+        except Exception as exc:
+            print(f"  [warn] prune: failed to delete page {page_id} — {exc}")

{mkdocs2confluence-0.5.27 → mkdocs2confluence-0.6.0}/tests/test_publish_client.py

@@ -490,3 +490,101 @@ def test_upload_attachment_error_raises(tmp_path: Path) -> None:
         client._client = httpx.Client(transport=transport)  # type: ignore[assignment]
         with pytest.raises(ConfluenceError, match="403"):
             client.upload_attachment("99", img, "img.png")
+
+
+# ── Orphan detection ───────────────────────────────────────────────────────────
+
+
+def test_stamp_managed_posts_when_absent() -> None:
+    transport = _MockTransport(
+        httpx.Response(404, text="not found"),  # GET — absent
+        httpx.Response(200, json={}),           # POST — create
+    )
+    config = _make_config()
+    with ConfluenceClient(config) as client:
+        client._client = httpx.Client(transport=transport)  # type: ignore[assignment]
+        client.stamp_managed("42")
+    assert transport.requests[0].method == "GET"
+    assert "/properties/mk2conf-managed" in str(transport.requests[0].url)
+    assert transport.requests[1].method == "POST"
+    body = json.loads(transport.requests[1].content)
+    assert body["key"] == "mk2conf-managed"
+    assert body["value"] is True
+
+
+def test_stamp_managed_skips_when_already_stamped() -> None:
+    transport = _MockTransport(httpx.Response(200, json={"key": "mk2conf-managed", "value": True}))
+    config = _make_config()
+    with ConfluenceClient(config) as client:
+        client._client = httpx.Client(transport=transport)  # type: ignore[assignment]
+        client.stamp_managed("42")
+    assert len(transport.requests) == 1  # only the GET, no POST
+
+
+def test_get_descendant_ids_returns_page_ids() -> None:
+    payload = {
+        "results": [
+            {"id": "10", "type": "page"},
+            {"id": "11", "type": "page"},
+        ],
+        "_links": {},
+    }
+    transport = _MockTransport(_json_response(payload))
+    config = _make_config()
+    with ConfluenceClient(config) as client:
+        client._client = httpx.Client(transport=transport)  # type: ignore[assignment]
+        ids = client.get_descendant_ids("99")
+    assert ids == ["10", "11"]
+
+
+def test_get_descendant_ids_paginates() -> None:
+    page1 = {
+        "results": [{"id": "10", "type": "page"}],
+        "_links": {"next": "/wiki/api/v2/pages/99/descendants?cursor=abc&depth=all"},
+    }
+    page2 = {
+        "results": [{"id": "11", "type": "page"}],
+        "_links": {},
+    }
+    transport = _MockTransport(_json_response(page1), _json_response(page2))
+    config = _make_config()
+    with ConfluenceClient(config) as client:
+        client._client = httpx.Client(transport=transport)  # type: ignore[assignment]
+        ids = client.get_descendant_ids("99")
+    assert ids == ["10", "11"]
+    assert len(transport.requests) == 2
+
+
+def test_is_managed_returns_true_when_present() -> None:
+    transport = _MockTransport(httpx.Response(200, json={"key": "mk2conf-managed", "value": True}))
+    config = _make_config()
+    with ConfluenceClient(config) as client:
+        client._client = httpx.Client(transport=transport)  # type: ignore[assignment]
+        assert client.is_managed("42") is True
+
+
+def test_is_managed_returns_false_when_absent() -> None:
+    transport = _MockTransport(httpx.Response(404, text="not found"))
+    config = _make_config()
+    with ConfluenceClient(config) as client:
+        client._client = httpx.Client(transport=transport)  # type: ignore[assignment]
+        assert client.is_managed("42") is False
+
+
+def test_delete_page_sends_delete_request() -> None:
+    transport = _MockTransport(httpx.Response(204, text=""))
+    config = _make_config()
+    with ConfluenceClient(config) as client:
+        client._client = httpx.Client(transport=transport)  # type: ignore[assignment]
+        client.delete_page("42")
+    assert transport.requests[0].method == "DELETE"
+    assert "/pages/42" in str(transport.requests[0].url)
+
+
+def test_delete_page_raises_on_error() -> None:
+    transport = _MockTransport(httpx.Response(403, text="forbidden"))
+    config = _make_config()
+    with ConfluenceClient(config) as client:
+        client._client = httpx.Client(transport=transport)  # type: ignore[assignment]
+        with pytest.raises(ConfluenceError):
+            client.delete_page("42")

{mkdocs2confluence-0.5.27 → mkdocs2confluence-0.6.0}/tests/test_publish_pipeline.py

@@ -998,3 +998,139 @@ class TestExecutePublish:
         assert section_action.page_id is not None
         assert section_action.page_id != "old-space-stale-id"
         assert child_action.parent_id == section_action.page_id
+
+
+class TestPruneOrphans:
+    """Tests for orphaned page detection and pruning."""
+
+    def test_prune_deletes_managed_orphan(self, tmp_path: Path) -> None:
+        """A managed descendant not in published_ids must be deleted."""
+        from mkdocs_to_confluence.publisher.pipeline import execute_publish
+
+        docs_dir = tmp_path / "docs"
+        docs_dir.mkdir()
+        page = _make_page_node("My Page", tmp_path, docs_dir)
+        action = PageAction(node=page, title="My Page", action="create", parent_id="ROOT")
+
+        client = _make_execute_client()
+        client.get_descendant_ids.return_value = ["orphan-99"]
+        client.is_managed.return_value = True
+
+        report = execute_publish(
+            [action], client, space_id="~42", docs_dir=docs_dir,
+            root_page_id="ROOT", prune=True,
+        )
+
+        client.delete_page.assert_called_once_with("orphan-99")
+        assert report.pruned == 1
+
+    def test_prune_skips_unmanaged_orphan(self, tmp_path: Path) -> None:
+        """A manually-created page (no mk2conf-managed stamp) must not be deleted."""
+        from mkdocs_to_confluence.publisher.pipeline import execute_publish
+
+        docs_dir = tmp_path / "docs"
+        docs_dir.mkdir()
+        page = _make_page_node("My Page", tmp_path, docs_dir)
+        action = PageAction(node=page, title="My Page", action="create", parent_id="ROOT")
+
+        client = _make_execute_client()
+        client.get_descendant_ids.return_value = ["manual-page-55"]
+        client.is_managed.return_value = False
+
+        report = execute_publish(
+            [action], client, space_id="~42", docs_dir=docs_dir,
+            root_page_id="ROOT", prune=True,
+        )
+
+        client.delete_page.assert_not_called()
+        assert report.pruned == 0
+
+    def test_prune_skips_published_pages(self, tmp_path: Path) -> None:
+        """Published pages that are descendants must not be deleted."""
+        from mkdocs_to_confluence.publisher.pipeline import execute_publish
+
+        docs_dir = tmp_path / "docs"
+        docs_dir.mkdir()
+        page = _make_page_node("My Page", tmp_path, docs_dir)
+        action = PageAction(node=page, title="My Page", action="create", parent_id="ROOT")
+
+        client = _make_execute_client()
+        # The newly created page has an id set by create_page side_effect (101)
+        # We simulate get_descendant_ids returning that same id
+        client.get_descendant_ids.return_value = ["101"]
+
+        report = execute_publish(
+            [action], client, space_id="~42", docs_dir=docs_dir,
+            root_page_id="ROOT", prune=True,
+        )
+
+        client.is_managed.assert_not_called()
+        client.delete_page.assert_not_called()
+        assert report.pruned == 0
+
+    def test_prune_disabled_by_default(self, tmp_path: Path) -> None:
+        """Without prune=True, descendant IDs are never fetched."""
+        from mkdocs_to_confluence.publisher.pipeline import execute_publish
+
+        docs_dir = tmp_path / "docs"
+        docs_dir.mkdir()
+        page = _make_page_node("My Page", tmp_path, docs_dir)
+        action = PageAction(node=page, title="My Page", action="create", parent_id="ROOT")
+
+        client = _make_execute_client()
+
+        execute_publish(
+            [action], client, space_id="~42", docs_dir=docs_dir,
+            root_page_id="ROOT",
+        )
+
+        client.get_descendant_ids.assert_not_called()
+
+    def test_prune_disabled_when_no_root_page_id(self, tmp_path: Path) -> None:
+        """prune=True without root_page_id does nothing."""
+        from mkdocs_to_confluence.publisher.pipeline import execute_publish
+
+        docs_dir = tmp_path / "docs"
+        docs_dir.mkdir()
+        page = _make_page_node("My Page", tmp_path, docs_dir)
+        action = PageAction(node=page, title="My Page", action="create", parent_id=None)
+
+        client = _make_execute_client()
+
+        execute_publish(
+            [action], client, space_id="~42", docs_dir=docs_dir,
+            prune=True,  # no root_page_id
+        )
+
+        client.get_descendant_ids.assert_not_called()
+
+    def test_stamp_managed_called_on_create(self, tmp_path: Path) -> None:
+        """stamp_managed must be called for each newly created page."""
+        from mkdocs_to_confluence.publisher.pipeline import execute_publish
+
+        docs_dir = tmp_path / "docs"
+        docs_dir.mkdir()
+        page = _make_page_node("My Page", tmp_path, docs_dir)
+        action = PageAction(node=page, title="My Page", action="create", parent_id="ROOT")
+
+        client = _make_execute_client()
+
+        execute_publish(
+            [action], client, space_id="~42", docs_dir=docs_dir, root_page_id="ROOT",
+        )
+
+        client.stamp_managed.assert_called_once()
+
+    def test_report_str_shows_pruned_count(self) -> None:
+        from mkdocs_to_confluence.publisher.pipeline import PublishReport
+
+        r = PublishReport(created=2, updated=1, skipped=0, pruned=3)
+        out = str(r)
+        assert "3 orphaned page(s) deleted" in out
+
+    def test_report_str_omits_pruned_when_zero(self) -> None:
+        from mkdocs_to_confluence.publisher.pipeline import PublishReport
+
+        r = PublishReport(created=2, updated=1, skipped=0, pruned=0)
+        out = str(r)
+        assert "Pruned" not in out