kash-shell 0.3.17__py3-none-any.whl → 0.3.18__py3-none-any.whl

kash/utils/text_handling/markdown_utils.py

@@ -1,4 +1,5 @@
 import re
+from pathlib import Path
 from textwrap import dedent
 from typing import Any, TypeAlias
 
@@ -72,21 +73,40 @@ def _tree_links(element, include_internal=False):
     return links
 
 
-def extract_links(file_path: str, include_internal=False) -> list[str]:
+def extract_links(content: str, include_internal=False) -> list[str]:
+    """
+    Extract all links from Markdown content.
+
+    Raises:
+        marko.ParseError: If the markdown content contains invalid syntax that cannot be parsed.
+    """
+    document = marko.parse(content)
+    return _tree_links(document, include_internal)
+
+
+def extract_file_links(file_path: Path, include_internal=False) -> list[str]:
     """
     Extract all links from a Markdown file. Future: Include textual and section context.
+
+    Returns an empty list if there are parsing errors.
     """
+    import logging
 
-    with open(file_path) as file:
-        content = file.read()
-        document = marko.parse(content)
-        return _tree_links(document, include_internal)
+    try:
+        content = file_path.read_text()
+        return extract_links(content, include_internal)
+    except Exception as e:
+        logging.warning(f"Failed to extract links from {file_path}: {e}")
+        return []
 
 
 def extract_first_header(content: str) -> str | None:
     """
     Extract the first header from markdown content if present.
     Also drops any formatting, so the result can be used as a document title.
+
+    Raises:
+        marko.ParseError: If the markdown content contains invalid syntax that cannot be parsed.
     """
     document = marko.parse(content)
 
@@ -105,27 +125,77 @@ def _extract_text(element: Any) -> str:
         return ""
 
 
-def _tree_bullet_points(element: marko.block.Document) -> list[str]:
+def _extract_list_item_markdown(element: Any) -> str:
+    """
+    Extract markdown from a list item, preserving all formatting.
+    """
+    from marko.block import BlankLine, List, Paragraph
+    from marko.inline import CodeSpan, Emphasis, Link, StrongEmphasis
+
+    if isinstance(element, str):
+        return element
+    elif isinstance(element, List):
+        # Skip nested lists
+        return ""
+    elif isinstance(element, BlankLine):
+        # Preserve paragraph breaks
+        return "\n\n"
+    elif isinstance(element, Paragraph):
+        # Extract content from paragraph
+        return "".join(_extract_list_item_markdown(child) for child in element.children)
+    elif isinstance(element, CodeSpan):
+        return f"`{''.join(_extract_list_item_markdown(child) for child in element.children)}`"
+    elif isinstance(element, Emphasis):
+        return f"*{''.join(_extract_list_item_markdown(child) for child in element.children)}*"
+    elif isinstance(element, StrongEmphasis):
+        return f"**{''.join(_extract_list_item_markdown(child) for child in element.children)}**"
+    elif isinstance(element, Link):
+        text = "".join(_extract_list_item_markdown(child) for child in element.children)
+        return f"[{text}]({element.dest})"
+    elif hasattr(element, "children"):
+        return "".join(_extract_list_item_markdown(child) for child in element.children)
+    else:
+        return ""
+
+
+def extract_bullet_points(content: str, *, strict: bool = False) -> list[str]:
+    """
+    Extract list item values from a Markdown file, preserving all original formatting.
+
+    If no bullet points are found and `strict` is False, returns the entire content
+    as a single item (treating plain text as if it were the first bullet point).
+    If `strict` is True, only actual list items are returned.
+
+    Raises:
+        ValueError: If `strict` is True and no bullet points are found.
+        marko.ParseError: If the markdown content contains invalid syntax that cannot be parsed.
+    """
+    document = marko.parse(content)
     bullet_points: list[str] = []
 
     def _find_bullet_points(element):
         if isinstance(element, ListItem):
-            bullet_points.append(_extract_text(element).strip())
+            # Extract markdown from this list item, preserving formatting
+            bullet_points.append(_extract_list_item_markdown(element).strip())
+            # Then recursively process any nested lists within this item
+            if hasattr(element, "children"):
+                for child in element.children:
+                    _find_bullet_points(child)
         elif hasattr(element, "children"):
             for child in element.children:
                 _find_bullet_points(child)
 
-    _find_bullet_points(element)
-    return bullet_points
-
+    _find_bullet_points(document)
 
-def extract_bullet_points(content: str) -> list[str]:
-    """
-    Extract list item values from a Markdown file.
-    """
+    # If no bullet points found
+    if not bullet_points:
+        if strict:
+            raise ValueError("No bullet points found in content")
+        elif content.strip():
+            # Not strict mode, treat as plain text
+            return [content.strip()]
 
-    document = marko.parse(content)
-    return _tree_bullet_points(document)
+    return bullet_points
 
 
 def _type_from_heading(heading: Heading) -> HTag:
@@ -180,6 +250,10 @@ def extract_headings(text: str) -> list[tuple[HTag, str]]:
     Returns a list of (tag, text) tuples:
     [("h1", "Main Title"), ("h2", "Subtitle")]
     where `#` corresponds to `h1`, `##` to `h2`, etc.
+
+    Raises:
+        marko.ParseError: If the markdown content contains invalid syntax that cannot be parsed.
+        ValueError: If a heading with an unsupported level is encountered.
     """
     document = marko.parse(text)
     headings_list: list[tuple[HTag, str]] = []
@@ -202,6 +276,10 @@ def extract_headings(text: str) -> list[tuple[HTag, str]]:
 def first_heading(text: str, *, allowed_tags: tuple[HTag, ...] = ("h1", "h2")) -> str | None:
     """
     Find the text of the first heading. Returns first h1 if present, otherwise first h2, etc.
+
+    Raises:
+        marko.ParseError: If the markdown content contains invalid syntax that cannot be parsed.
+        ValueError: If a heading with an unsupported level is encountered.
     """
     headings = extract_headings(text)
     for goal_tag in allowed_tags:
@@ -302,3 +380,333 @@ def test_extract_headings_and_first_header() -> None:
     formatted_header_md = "## *Formatted* _Header_ [link](#anchor)"
     assert extract_headings(formatted_header_md) == [("h2", "Formatted Header link")]
     assert first_heading(formatted_header_md, allowed_tags=("h2",)) == "Formatted Header link"
+
+
+def test_extract_bullet_points() -> None:
+    # Empty content
+    assert extract_bullet_points("") == []
+
+    # No lists (strict mode)
+    try:
+        extract_bullet_points("Just some text without lists.", strict=True)
+        raise AssertionError("Expected ValueError for strict mode with no bullet points")
+    except ValueError as e:
+        assert "No bullet points found" in str(e)
+    # No lists (non-strict mode - should return as single item)
+    assert extract_bullet_points("Just some text without lists.") == [
+        "Just some text without lists."
+    ]
+
+    # Simple unordered list
+    content = dedent("""
+        - First item
+        - Second item
+        - Third item
+        """)
+    expected = ["First item", "Second item", "Third item"]
+    assert extract_bullet_points(content) == expected
+
+    # Simple ordered list
+    content = dedent("""
+        1. First item
+        2. Second item
+        3. Third item
+        """)
+    expected = ["First item", "Second item", "Third item"]
+    assert extract_bullet_points(content) == expected
+
+    # Mixed list types (asterisk and dash)
+    content = dedent("""
+        * Item with asterisk
+        - Item with dash
+        + Item with plus
+        """)
+    expected = ["Item with asterisk", "Item with dash", "Item with plus"]
+    assert extract_bullet_points(content) == expected
+
+    # List items with formatting
+    content = dedent("""
+        - **Bold item**
+        - *Italic item*
+        - `Code item`
+        - [Link item](http://example.com)
+        - Item with _multiple_ **formats** and `code`
+        """)
+    expected = [
+        "**Bold item**",
+        "*Italic item*",
+        "`Code item`",
+        "[Link item](http://example.com)",
+        "Item with *multiple* **formats** and `code`",
+    ]
+    assert extract_bullet_points(content) == expected
+
+    # Nested lists
+    content = dedent("""
+        - Top level item 1
+          - Nested item 1.1
+          - Nested item 1.2
+        - Top level item 2
+          1. Nested ordered 2.1
+          2. Nested ordered 2.2
+        """)
+    expected = [
+        "Top level item 1",
+        "Nested item 1.1",
+        "Nested item 1.2",
+        "Top level item 2",
+        "Nested ordered 2.1",
+        "Nested ordered 2.2",
+    ]
+    assert extract_bullet_points(content) == expected
+
+    # Multi-line list items
+    content = dedent("""
+        - First item that spans
+          multiple lines with content
+        - Second item
+          that also spans multiple
+          lines
+        """)
+    expected = [
+        "First item that spans\nmultiple lines with content",
+        "Second item\nthat also spans multiple\nlines",
+    ]
+    assert extract_bullet_points(content) == expected
+
+    # Lists mixed with other content
+    content = dedent("""
+        # Header
+
+        Some text before the list.
+
+        - First item
+        - Second item
+
+        More text after the list.
+
+        1. Another list item
+        2. Final item
+
+        Conclusion text.
+        """)
+    expected = ["First item", "Second item", "Another list item", "Final item"]
+    assert extract_bullet_points(content) == expected
+
+    # List items with complex content
+    content = dedent("""
+        - Item with **bold** and *italic* and `inline code`
+        - Item with [external link](https://example.com) and [internal link](#section)
+        - Item with line breaks
+          and continued text
+        """)
+    expected = [
+        "Item with **bold** and *italic* and `inline code`",
+        "Item with [external link](https://example.com) and [internal link](#section)",
+        "Item with line breaks\nand continued text",
+    ]
+    assert extract_bullet_points(content) == expected
+
+    # Edge case: empty list items
+    content = dedent("""
+        - 
+        - Non-empty item
+        -   
+        """)
+    expected = ["", "Non-empty item", ""]
+    assert extract_bullet_points(content) == expected
+
+    # Plain text handling (default behavior - not strict)
+    plain_text = "This is just plain text without any lists."
+    expected = ["This is just plain text without any lists."]
+    assert extract_bullet_points(plain_text) == expected
+    assert extract_bullet_points(plain_text, strict=False) == expected
+
+    # Plain text handling (strict mode)
+    try:
+        extract_bullet_points(plain_text, strict=True)
+        raise AssertionError("Expected ValueError for strict mode with no bullet points")
+    except ValueError as e:
+        assert "No bullet points found" in str(e)
+
+    # Multi-line plain text handling
+    multiline_plain = dedent("""
+        This is a paragraph
+        with multiple lines
+        and no bullets.""").strip()
+    expected_multiline = ["This is a paragraph\nwith multiple lines\nand no bullets."]
+    assert extract_bullet_points(multiline_plain) == expected_multiline
+    try:
+        extract_bullet_points(multiline_plain, strict=True)
+        raise AssertionError("Expected ValueError for strict mode with no bullet points")
+    except ValueError as e:
+        assert "No bullet points found" in str(e)
+
+    # Mixed content with no lists in strict mode
+    mixed_no_lists = dedent("""
+        # Header
+        Some text here.
+        **Bold text** and *italic*.
+        """)
+    try:
+        extract_bullet_points(mixed_no_lists, strict=True)
+        raise AssertionError("Expected ValueError for strict mode with no bullet points")
+    except ValueError as e:
+        assert "No bullet points found" in str(e)
+    # Non-strict should return the content as single item
+    assert len(extract_bullet_points(mixed_no_lists, strict=False)) == 1
+
+
+def test_extract_bullet_points_key_scenarios() -> None:
+    """Test key scenarios: plain text, multi-paragraph lists, and links in bullet text."""
+
+    # Plain text handling (the fundamental case)
+    plain_text = "This is just plain text without any markdown formatting."
+    assert extract_bullet_points(plain_text) == [plain_text]
+
+    # Multi-paragraph plain text
+    multiline_plain = dedent("""
+        This is a paragraph
+        with multiple lines
+        and no bullets at all.""").strip()
+    assert extract_bullet_points(multiline_plain) == [multiline_plain]
+
+    # Multi-paragraph bulleted lists with complex formatting
+    multi_paragraph_content = dedent("""
+        - First bullet point with **bold text** and a [link](https://example.com)
+          
+          This is a continuation paragraph within the same bullet point.
+          It spans multiple lines and includes *italic text*.
+
+        - Second bullet point with `inline code` and another [internal link](#section)
+          
+          Another paragraph here with more content.
+          Including **bold** and *italic* formatting.
+
+        - Third simple bullet
+        """)
+    expected_multi = [
+        "First bullet point with **bold text** and a [link](https://example.com)\n\nThis is a continuation paragraph within the same bullet point.\nIt spans multiple lines and includes *italic text*.",
+        "Second bullet point with `inline code` and another [internal link](#section)\n\nAnother paragraph here with more content.\nIncluding **bold** and *italic* formatting.",
+        "Third simple bullet",
+    ]
+    result_multi = extract_bullet_points(multi_paragraph_content)
+    assert result_multi == expected_multi
+
+    # Links inside bullet text (various types)
+    links_content = dedent("""
+        - Check out [this external link](https://google.com) for more info
+        - Visit [our docs](https://docs.example.com/api) and [FAQ](https://example.com/faq)
+        - Internal reference: [see section below](#implementation)
+        - Mixed: [external](https://test.com) and [internal](#ref) in one bullet
+        - Email link: [contact us](mailto:test@example.com)
+        - Link with **bold text**: [**Important Link**](https://critical.com)
+        """)
+    expected_links = [
+        "Check out [this external link](https://google.com) for more info",
+        "Visit [our docs](https://docs.example.com/api) and [FAQ](https://example.com/faq)",
+        "Internal reference: [see section below](#implementation)",
+        "Mixed: [external](https://test.com) and [internal](#ref) in one bullet",
+        "Email link: [contact us](mailto:test@example.com)",
+        "Link with **bold text**: [**Important Link**](https://critical.com)",
+    ]
+    result_links = extract_bullet_points(links_content)
+    assert result_links == expected_links
+
+    # Complex formatting combinations
+    complex_content = dedent("""
+        - **Bold** start with [link](https://example.com) and `code` end
+        - *Italic* with `inline code` and [another link](https://test.com) here
+        - Mixed: **bold _nested italic_** and `code with [link inside](https://nested.com)`
+        """)
+    expected_complex = [
+        "**Bold** start with [link](https://example.com) and `code` end",
+        "*Italic* with `inline code` and [another link](https://test.com) here",
+        "Mixed: **bold *nested italic*** and `code with [link inside](https://nested.com)`",
+    ]
+    result_complex = extract_bullet_points(complex_content)
+    assert result_complex == expected_complex
+
+
+def test_markdown_structure_parsing() -> None:
+    """Test that demonstrates how markdown structure is parsed and preserved."""
+
+    # Test markdown structure preservation in list items
+    content = dedent("""
+        - First bullet with **bold text**
+
+          This is a continuation paragraph with *italic text*.
+          It spans multiple lines.
+
+          Another paragraph in the same list item.
+
+        - Second bullet with `code` and [link](https://example.com)
+        """)
+
+    result = extract_bullet_points(content)
+
+    # Verify we get exactly 2 bullet points
+    assert len(result) == 2
+
+    # Verify first bullet preserves all formatting and paragraph structure
+    expected_first = "First bullet with **bold text**\n\nThis is a continuation paragraph with *italic text*.\nIt spans multiple lines.\n\nAnother paragraph in the same list item."
+    assert result[0] == expected_first
+
+    # Verify second bullet preserves formatting
+    expected_second = "Second bullet with `code` and [link](https://example.com)"
+    assert result[1] == expected_second
+
+    # Test nested formatting combinations
+    nested_content = dedent("""
+        - Item with **bold containing *italic* text** and `code`
+        - Link with formatting: [**Bold Link Text**](https://example.com)
+        - Code with special chars: `function(param="value")`
+        """)
+
+    nested_result = extract_bullet_points(nested_content)
+    assert len(nested_result) == 3
+    assert nested_result[0] == "Item with **bold containing *italic* text** and `code`"
+    assert nested_result[1] == "Link with formatting: [**Bold Link Text**](https://example.com)"
+    assert nested_result[2] == 'Code with special chars: `function(param="value")`'
+
+
+def test_markdown_utils_exceptions() -> None:
+    """Test exception handling for markdown utility functions."""
+    import tempfile
+
+    # Test extract_file_links with non-existent file
+    result = extract_file_links(Path("/non/existent/file.md"))
+    assert result == []  # Should return empty list for any error
+
+    # Test extract_file_links with empty file (should work fine)
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as tmp:
+        tmp.write("")
+        tmp_path = Path(tmp.name)
+
+    try:
+        result = extract_file_links(tmp_path)
+        assert result == []  # Empty file has no links
+    finally:
+        tmp_path.unlink()
+
+    # Test with invalid markdown formatting (markdown is very permissive)
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as tmp:
+        tmp.write("[incomplete link\n# Header\n- List item")
+        tmp_path = Path(tmp.name)
+
+    try:
+        result = extract_file_links(tmp_path)
+        # Should still work - marko is very permissive with markdown
+        assert isinstance(result, list)
+    finally:
+        tmp_path.unlink()
+
+    # Test extract_links with string content
+    content = "Check out [this link](https://example.com) and [internal](#section)"
+    result = extract_links(content)
+    assert "https://example.com" in result
+    assert "#section" not in result  # Internal links excluded by default
+
+    result_with_internal = extract_links(content, include_internal=True)
+    assert "https://example.com" in result_with_internal
+    assert "#section" in result_with_internal