kb2md 0.1.0__tar.gz

kb2md-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+*.whl
+*.tar.gz
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+
+# Output
+output/
+
+# Coverage
+.coverage
+htmlcov/
+
+# Misc
+.DS_Store

kb2md-0.1.0/.superpowers/sdd/.gitignore

@@ -0,0 +1 @@
+*

kb2md-0.1.0/.superpowers/sdd/final-fix-report.md

@@ -0,0 +1,59 @@
+# Final Fix Report
+
+## What Was Fixed
+
+### 1. mypy strict errors with BeautifulSoup types
+- Added `[[tool.mypy.overrides]]` for `bs4` with `follow_imports = "skip"` in `pyproject.toml`.
+- Removed four now-unused `# type: ignore[arg-type]` / `# type: ignore[assignment]` comments in `src/kb2md/converter.py` that were masking `cell.get()` and `temp_grid` errors.
+- Because `types-beautifulsoup4` returns wider unions (`Tag | NavigableString`) that `follow_imports = "skip"` does not fully suppress for installed stub packages, added minimal `isinstance(..., Tag)` narrowing in three places and one targeted `# type: ignore[no-untyped-call]` for `soup.new_string()`. Core conversion logic is unchanged.
+
+### 2. CLI config commands mutually exclusive with `page_ref`
+- In `src/kb2md/cli.py`, `_handle_default_url_args()` now rejects `--set-default-url` and `--get-default-url` when `args.page_ref` is present, logging a clear error and returning `1`.
+- Added `test_main_set_default_url_with_page_ref` and `test_main_get_default_url_with_page_ref` in `tests/test_cli.py`.
+
+### 3. Config write errors not handled
+- In `src/kb2md/config.py`, `set_default_url()` now wraps `CONFIG_DIR.mkdir()` and `CONFIG_FILE.write_text()` in `try/except OSError`, logs the failure, and raises `RuntimeError("Could not save default URL to ...")`.
+- Added `test_set_default_url_raises_on_write_error` in `tests/test_config.py`.
+
+### 4. Subpage downloader duplicate children
+- In `src/kb2md/subpage.py`, each `child_id` is now marked visited (or skipped if already visited) **before** `confluence_to_markdown()` is called in the child loop.
+- Removed the early return at the top of `_download_children()` so a child reached through multiple parents still processes its own descendants; deduplication is enforced by the visited set.
+- Added `test_download_subpages_deduplicates_shared_children` and `test_download_subpages_deduplicates_duplicate_siblings` in `tests/test_subpage.py`.
+
+## Test Results
+
+```
+pytest --cov=src --cov-report=term-missing tests/
+89 passed
+Total coverage: 85.41% (required 80.0%)
+```
+
+All existing tests continue to pass and coverage remains above the required threshold.
+
+## Static Analysis Results
+
+| Tool   | Result |
+|--------|--------|
+| black  | passed (`black --check src tests`) |
+| ruff   | passed (`ruff check src tests`) |
+| mypy   | passed (`mypy src`) with `types-beautifulsoup4` installed |
+| bandit | passed (`bandit -r src/`) |
+
+## Files Changed
+
+- `pyproject.toml`
+- `src/kb2md/cli.py`
+- `src/kb2md/config.py`
+- `src/kb2md/converter.py`
+- `src/kb2md/subpage.py`
+- `tests/test_cli.py`
+- `tests/test_config.py`
+- `tests/test_subpage.py`
+
+## Commits Created
+
+- `c411594` fix: address final review issues
+
+## Remaining Concerns
+
+None. The four Important issues are resolved, all tests pass, and all configured static-analysis tools are green.

kb2md-0.1.0/.superpowers/sdd/progress.md

@@ -0,0 +1,9 @@
+Task 1: complete (commits fa1705f..92e9601, review clean)
+Task 2: complete (commits 92e9601..fe5d151, review clean)
+Task 3: complete (commits fe5d151..449f7a0, review clean)
+Task 4: complete (commits 449f7a0..f984a36, review clean)
+Task 5: complete (commits f984a36..2a4b57f, review clean)
+Task 6: complete (commits 2a4b57f..7b6d1c0, review clean)
+Task 7: complete (commits 7b6d1c0..4bdefe0, review clean after fixes)
+Task 8: complete (commits 4bdefe0..690ccc9, review clean)
+Task 9: complete (commits 690ccc9..ba1f9d1, review clean)

kb2md-0.1.0/.superpowers/sdd/review-2a4b57f..7b6d1c0.diff

@@ -0,0 +1,208 @@
+# Review package: 2a4b57f..7b6d1c0
+
+## Commits
+7b6d1c0 refactor: address review feedback for subpage downloader
+43ff655 feat: add subpage and recursive subpage download
+
+## Files changed
+ src/kb2md/converter.py |  2 +-
+ src/kb2md/subpage.py   | 67 +++++++++++++++++++++++++++++++++++++
+ tests/test_subpage.py  | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++
+ 3 files changed, 157 insertions(+), 1 deletion(-)
+
+## Diff
+diff --git a/src/kb2md/converter.py b/src/kb2md/converter.py
+index 5373d9e..dc104a7 100644
+--- a/src/kb2md/converter.py
++++ b/src/kb2md/converter.py
+@@ -39,21 +39,21 @@ class ConfluenceToMarkdown:
+         if use_chrome_cookies:
+             try:
+                 self.chrome_cookies = chrome_cookies(confluence_url)
+                 LOGGER.info("Successfully loaded Chrome cookies")
+             except Exception as e:
+                 LOGGER.warning("Could not load Chrome cookies: %s", e)
+                 self.chrome_cookies = None
+         else:
+             self.chrome_cookies = None
+ 
+-    def confluence_to_markdown(self, page_id: int, output_dir: str = "./output") -> Path:
++    def confluence_to_markdown(self, page_id: int, output_dir: str | Path = "./output") -> Path:
+         """
+         将Confluence页面转换为Markdown
+         """
+         LOGGER.info("Starting conversion for page ID: %s", page_id)
+ 
+         # 创建输出目录
+         output_path = Path(output_dir)
+         output_path.mkdir(exist_ok=True)
+         attachments_dir = output_path / f"{page_id}_attach"
+         attachments_dir.mkdir(exist_ok=True)
+diff --git a/src/kb2md/subpage.py b/src/kb2md/subpage.py
+new file mode 100644
+index 0000000..54e9f3b
+--- /dev/null
++++ b/src/kb2md/subpage.py
+@@ -0,0 +1,67 @@
++"""Subpage download logic for kb2md."""
++
++import logging
++from pathlib import Path
++
++from kb2md.converter import ConfluenceToMarkdown
++
++LOGGER = logging.getLogger(__name__)
++
++
++class SubpageDownloader:
++    """Download child pages of a Confluence page."""
++
++    def __init__(self, converter: ConfluenceToMarkdown):
++        self.converter = converter
++
++    def download_subpages(self, page_id: int, output_dir: Path, recursive: bool = False) -> None:
++        """Download subpages of ``page_id`` into ``output_dir``.
++
++        Direct children are placed in ``{page_id}_page/``.
++        When ``recursive`` is True, descendants are placed in nested
++        ``{child_id}_page/`` directories to preserve hierarchy.
++        """
++        visited: set[str] = set()
++        self._download_children(page_id, output_dir, recursive, visited)
++
++    def _download_children(
++        self,
++        page_id: int,
++        output_dir: Path,
++        recursive: bool,
++        visited: set[str],
++    ) -> None:
++        page_id_str = str(page_id)
++        if page_id_str in visited:
++            return
++        visited.add(page_id_str)
++
++        try:
++            response = self.converter.confluence.get_page_child_by_type(
++                page_id, type="page", start=0, limit=500
++            )
++        except Exception as e:
++            LOGGER.error("Failed to fetch children of page %s: %s", page_id, e)
++            return
++
++        children = response.get("results", [])
++        if not children:
++            LOGGER.info("No subpages found for page %s", page_id)
++            return
++
++        subpage_dir = output_dir / f"{page_id}_page"
++        subpage_dir.mkdir(parents=True, exist_ok=True)
++
++        for child in children:
++            child_id = int(child["id"])
++            if str(child_id) in visited:
++                continue
++            try:
++                self.converter.confluence_to_markdown(child_id, output_dir=subpage_dir)
++                LOGGER.info("Downloaded subpage %s into %s", child_id, subpage_dir)
++            except Exception as e:
++                LOGGER.warning("Failed to download subpage %s: %s", child_id, e)
++                continue
++
++            if recursive:
++                self._download_children(child_id, subpage_dir, recursive, visited)
+diff --git a/tests/test_subpage.py b/tests/test_subpage.py
+new file mode 100644
+index 0000000..b6b17f3
+--- /dev/null
++++ b/tests/test_subpage.py
+@@ -0,0 +1,89 @@
++from pathlib import Path
++from typing import Any
++from unittest.mock import MagicMock, call
++
++import pytest
++
++from kb2md.converter import ConfluenceToMarkdown
++from kb2md.subpage import SubpageDownloader
++
++
++@pytest.fixture
++def mock_converter(tmp_path: Path) -> MagicMock:
++    converter = MagicMock(spec=ConfluenceToMarkdown)
++    converter.confluence = MagicMock()
++    converter.confluence_to_markdown.side_effect = lambda pid, output_dir: (
++        Path(output_dir) / f"page[{pid}].md"
++    )
++    return converter
++
++
++def test_download_direct_subpages(mock_converter: MagicMock, tmp_path: Path) -> None:
++    mock_converter.confluence.get_page_child_by_type.return_value = {
++        "results": [
++            {"id": "111"},
++            {"id": "222"},
++        ]
++    }
++
++    downloader = SubpageDownloader(mock_converter)
++    downloader.download_subpages(100, tmp_path, recursive=False)
++
++    mock_converter.confluence.get_page_child_by_type.assert_called_once_with(
++        100, type="page", start=0, limit=500
++    )
++    assert mock_converter.confluence_to_markdown.call_count == 2
++    calls = [
++        call(111, output_dir=tmp_path / "100_page"),
++        call(222, output_dir=tmp_path / "100_page"),
++    ]
++    mock_converter.confluence_to_markdown.assert_has_calls(calls, any_order=True)
++
++
++def test_download_recursive_subpages(mock_converter: MagicMock, tmp_path: Path) -> None:
++    # Root has child 111, child 111 has child 222
++    def child_results(page_id: int, **kwargs: Any) -> dict[str, list[dict[str, str]]]:
++        if page_id == 100:
++            return {"results": [{"id": "111"}]}
++        if page_id == 111:
++            return {"results": [{"id": "222"}]}
++        return {"results": []}
++
++    mock_converter.confluence.get_page_child_by_type.side_effect = child_results
++
++    downloader = SubpageDownloader(mock_converter)
++    downloader.download_subpages(100, tmp_path, recursive=True)
++
++    # 100 -> 111 -> 222
++    assert mock_converter.confluence_to_markdown.call_count == 2
++    mock_converter.confluence_to_markdown.assert_any_call(111, output_dir=tmp_path / "100_page")
++    mock_converter.confluence_to_markdown.assert_any_call(
++        222, output_dir=tmp_path / "100_page" / "111_page"
++    )
++
++
++def test_download_subpages_no_children(mock_converter: MagicMock, tmp_path: Path) -> None:
++    mock_converter.confluence.get_page_child_by_type.return_value = {"results": []}
++
++    downloader = SubpageDownloader(mock_converter)
++    downloader.download_subpages(100, tmp_path, recursive=False)
++
++    mock_converter.confluence_to_markdown.assert_not_called()
++
++
++def test_download_subpages_avoids_cycles(mock_converter: MagicMock, tmp_path: Path) -> None:
++    # 100 -> 111 -> 100 (cycle)
++    def child_results(page_id: int, **kwargs: Any) -> dict[str, list[dict[str, str]]]:
++        if page_id == 100:
++            return {"results": [{"id": "111"}]}
++        if page_id == 111:
++            return {"results": [{"id": "100"}]}
++        return {"results": []}
++
++    mock_converter.confluence.get_page_child_by_type.side_effect = child_results
++
++    downloader = SubpageDownloader(mock_converter)
++    downloader.download_subpages(100, tmp_path, recursive=True)
++
++    # Should only download 111 once, not revisit 100
++    assert mock_converter.confluence_to_markdown.call_count == 1