oh-markdown-tool 0.1.0__py3-none-any.whl

oh_markdown_tool/__init__.py

@@ -0,0 +1,34 @@
+"""Markdown document tool for structural editing and formatting."""
+
+__version__ = "0.1.0"
+
+from .numbering import NumberingIssue, RenumberResult, SectionNumberer, ValidationResult
+from .parser import MarkdownParser, ParseResult, Section
+from .toc import (
+    TocAction,
+    TocManager,
+    TocRemoveResult,
+    TocUpdateResult,
+    TocValidationResult,
+)
+from .tool import MarkdownAction, MarkdownDocumentTool, MarkdownExecutor, MarkdownObservation
+
+__all__ = [
+    "__version__",
+    "MarkdownParser",
+    "ParseResult",
+    "Section",
+    "SectionNumberer",
+    "NumberingIssue",
+    "RenumberResult",
+    "ValidationResult",
+    "MarkdownDocumentTool",
+    "MarkdownAction",
+    "MarkdownObservation",
+    "MarkdownExecutor",
+    "TocAction",
+    "TocManager",
+    "TocUpdateResult",
+    "TocRemoveResult",
+    "TocValidationResult",
+]

oh_markdown_tool/formatter.py

@@ -0,0 +1,158 @@
+"""Markdown formatting operations using mdformat and pymarkdownlnt."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import mdformat
+from pymarkdown.api import PyMarkdownApi
+
+
+@dataclass
+class LintIssue:
+    """A single markdown lint issue."""
+
+    line: int
+    column: int
+    rule_id: str
+    rule_name: str
+    message: str
+    extra_info: str | None = None
+
+
+@dataclass
+class LintResult:
+    """Result of linting a markdown document."""
+
+    issues: list[LintIssue]
+
+    @property
+    def has_issues(self) -> bool:
+        """Return True if there are any lint issues."""
+        return len(self.issues) > 0
+
+
+@dataclass
+class FixResult:
+    """Result of auto-fixing markdown issues."""
+
+    was_fixed: bool
+    content: str
+    issues_remaining: list[LintIssue]
+
+    @property
+    def has_remaining_issues(self) -> bool:
+        """Return True if there are issues that couldn't be auto-fixed."""
+        return len(self.issues_remaining) > 0
+
+
+@dataclass
+class RewrapResult:
+    """Result of rewrapping a markdown document."""
+
+    content: str
+    was_modified: bool
+
+
+class MarkdownFormatter:
+    """Formats markdown documents using mdformat and pymarkdownlnt.
+
+    Provides three operations:
+    - rewrap: Normalize paragraph line lengths (preserves code blocks, tables, lists)
+    - lint: Scan for markdown issues and report them
+    - fix: Auto-fix markdown issues where possible
+    """
+
+    def __init__(self):
+        """Initialize the formatter."""
+        self._api = PyMarkdownApi()
+
+    def rewrap(self, content: str, width: int = 80) -> RewrapResult:
+        """Rewrap paragraphs to specified width.
+
+        Uses mdformat to parse the markdown AST and only wrap paragraph text,
+        leaving structural elements (code blocks, tables, lists) intact.
+
+        Args:
+            content: Markdown content to rewrap.
+            width: Maximum line width (default 80).
+
+        Returns:
+            RewrapResult with the rewrapped content.
+        """
+        result = mdformat.text(content, options={"wrap": width})
+        return RewrapResult(
+            content=result,
+            was_modified=result != content,
+        )
+
+    def lint(self, content: str) -> LintResult:
+        """Scan content for markdown issues.
+
+        Uses pymarkdownlnt to check for common markdown issues like:
+        - MD009: Trailing spaces
+        - MD012: Multiple consecutive blank lines
+        - MD013: Line length (if not rewrapped first)
+        - And many more...
+
+        Args:
+            content: Markdown content to lint.
+
+        Returns:
+            LintResult with list of issues found.
+        """
+        if not content:
+            return LintResult(issues=[])
+
+        result = self._api.scan_string(content)
+        issues = [
+            LintIssue(
+                line=failure.line_number,
+                column=failure.column_number,
+                rule_id=failure.rule_id,
+                rule_name=failure.rule_name,
+                message=failure.rule_description,
+                extra_info=failure.extra_error_information or None,
+            )
+            for failure in result.scan_failures
+        ]
+        return LintResult(issues=issues)
+
+    def fix(self, content: str) -> FixResult:
+        """Auto-fix markdown issues where possible.
+
+        Uses pymarkdownlnt's fix mode to automatically correct issues.
+        Not all issues can be auto-fixed - the result includes any
+        remaining issues that require manual attention.
+
+        Args:
+            content: Markdown content to fix.
+
+        Returns:
+            FixResult with fixed content and any remaining issues.
+        """
+        if not content:
+            return FixResult(was_fixed=False, content="", issues_remaining=[])
+
+        fix_result = self._api.fix_string(content)
+        fixed_content = fix_result.fixed_file if fix_result.was_fixed else content
+
+        # Scan the fixed content to find remaining issues
+        scan_result = self._api.scan_string(fixed_content)
+        remaining_issues = [
+            LintIssue(
+                line=failure.line_number,
+                column=failure.column_number,
+                rule_id=failure.rule_id,
+                rule_name=failure.rule_name,
+                message=failure.rule_description,
+                extra_info=failure.extra_error_information or None,
+            )
+            for failure in scan_result.scan_failures
+        ]
+
+        return FixResult(
+            was_fixed=fix_result.was_fixed,
+            content=fixed_content,
+            issues_remaining=remaining_issues,
+        )

oh_markdown_tool/numbering.py

@@ -0,0 +1,384 @@
+"""Section numbering validation and management for markdown documents."""
+
+import re
+from dataclasses import dataclass
+
+from .parser import MarkdownParser, Section
+
+
+@dataclass
+class NumberingIssue:
+    """Represents a section numbering issue."""
+
+    section_title: str
+    expected: str
+    actual: str | None
+    line_number: int
+    issue_type: str  # 'missing_number', 'wrong_number', 'invalid_format'
+
+    @property
+    def message(self) -> str:
+        """Generate a descriptive message for this issue."""
+        if self.issue_type == "missing_number":
+            return f"Section '{self.section_title}' is missing a number (expected: {self.expected})"
+        if self.issue_type == "wrong_number":
+            return f"Section '{self.section_title}' has wrong number '{self.actual}' (expected: {self.expected})"
+        if self.issue_type == "invalid_format":
+            return f"Section '{self.section_title}' has invalid number format '{self.actual}'"
+        return f"Section '{self.section_title}' has numbering issue: {self.issue_type}"
+
+
+@dataclass
+class ValidationResult:
+    """Result of section numbering validation."""
+
+    valid: bool
+    issues: list[NumberingIssue]
+    recommendations: list[str]
+
+
+@dataclass
+class RenumberResult:
+    """Result of renumbering operation."""
+
+    content: str
+    sections_renumbered: int
+    was_modified: bool
+    toc_skipped: bool
+
+
+class SectionNumberer:
+    """Handles section numbering validation, normalization, and renumbering."""
+
+    def __init__(self):
+        self.toc_section: Section | None = None
+
+    def validate(
+        self, sections: list[Section], toc_section: Section | None = None
+    ) -> ValidationResult:
+        """
+        Validate section numbering consistency.
+
+        Args:
+            sections: List of top-level sections from parser
+            toc_section: TOC section to skip during validation
+
+        Returns:
+            ValidationResult with issues and recommendations
+        """
+        self.toc_section = toc_section
+        issues: list[NumberingIssue] = []
+
+        # Get all sections in document order, excluding TOC
+        all_sections = self._get_numbered_sections(sections)
+
+        # Validate numbering sequence
+        expected_numbers = self._generate_expected_numbers(all_sections)
+
+        for section, expected in zip(all_sections, expected_numbers, strict=True):
+            if section.number != expected:
+                issue_type = "missing_number" if section.number is None else "wrong_number"
+                issues.append(
+                    NumberingIssue(
+                        section_title=section.title,
+                        expected=expected,
+                        actual=section.number,
+                        line_number=section.start_line + 1,  # Convert to 1-based
+                        issue_type=issue_type,
+                    )
+                )
+
+        # Generate recommendations
+        recommendations = self._generate_recommendations(issues)
+
+        return ValidationResult(
+            valid=len(issues) == 0, issues=issues, recommendations=recommendations
+        )
+
+    def normalize(self, sections: list[Section]) -> list[Section]:
+        """
+        Normalize section numbering to be sequential and properly nested.
+
+        Args:
+            sections: List of sections to normalize
+
+        Returns:
+            List of sections with corrected numbering
+        """
+        # Get all sections excluding TOC
+        all_sections = self._get_numbered_sections(sections)
+
+        # Generate correct numbers
+        expected_numbers = self._generate_expected_numbers(all_sections)
+
+        # Update section numbers
+        for section, expected_number in zip(all_sections, expected_numbers, strict=True):
+            section.number = expected_number
+
+        return sections
+
+    def renumber(
+        self, sections: list[Section], toc_section: Section | None = None
+    ) -> dict[str, object]:
+        """Renumber all sections sequentially, skipping TOC.
+
+        This is the low-level API that operates on Section objects.
+        For most use cases, prefer renumber_content() which handles
+        the full parse → renumber → reconstruct flow.
+
+        Args:
+            sections: List of sections to renumber
+            toc_section: TOC section to skip
+
+        Returns:
+            Dictionary with renumbering results
+        """
+        self.toc_section = toc_section
+
+        # Count sections before renumbering
+        all_sections = self._get_numbered_sections(sections)
+        sections_before = len([s for s in all_sections if s.number is not None])
+
+        # Normalize numbering
+        self.normalize(sections)
+
+        # Count sections after renumbering
+        sections_after = len([s for s in all_sections if s.number is not None])
+
+        return {
+            "result": "success",
+            "sections_renumbered": sections_after,
+            "toc_skipped": toc_section is not None,
+            "sections_before": sections_before,
+            "sections_after": sections_after,
+        }
+
+    def renumber_content(self, content: str) -> RenumberResult:
+        """Renumber all sections in a document and return the updated content.
+
+        This is the primary method for renumbering - it handles parsing,
+        renumbering, and reconstructing the document in one operation.
+
+        Args:
+            content: The markdown document content.
+
+        Returns:
+            RenumberResult with updated content and statistics.
+        """
+        parser = MarkdownParser()
+        result = parser.parse_content(content)
+
+        self.toc_section = result.toc_section
+        all_sections = self._get_numbered_sections(result.sections)
+
+        # Normalize numbering (updates Section objects in place)
+        self.normalize(result.sections)
+
+        # Reconstruct document with updated headings
+        updated_content = self._reconstruct_document(content, parser.get_all_sections())
+
+        return RenumberResult(
+            content=updated_content,
+            sections_renumbered=len(all_sections),
+            was_modified=updated_content != content,
+            toc_skipped=result.toc_section is not None,
+        )
+
+    def format_heading(self, section: Section) -> str:
+        """Format a section heading with proper number formatting.
+
+        Level 2 sections get a trailing period (e.g., "## 1. Title")
+        Level 3+ sections don't (e.g., "### 1.1 Title")
+
+        Args:
+            section: The section to format.
+
+        Returns:
+            The formatted heading line.
+        """
+        hashes = "#" * section.level
+        if section.number:
+            if section.level == 2:
+                return f"{hashes} {section.number}. {section.title}"
+            return f"{hashes} {section.number} {section.title}"
+        return f"{hashes} {section.title}"
+
+    def _reconstruct_document(self, content: str, sections: list[Section]) -> str:
+        """Reconstruct document with updated section numbering.
+
+        Args:
+            content: The original document content.
+            sections: All sections with updated numbering.
+
+        Returns:
+            The document with updated section numbers.
+        """
+        lines = content.splitlines()
+        heading_pattern = re.compile(r"^(#{1,6})\s+(.+)$")
+
+        for section in sections:
+            if section.start_line < len(lines):
+                line = lines[section.start_line]
+                if heading_pattern.match(line.strip()):
+                    lines[section.start_line] = self.format_heading(section)
+
+        result = "\n".join(lines)
+        # Preserve trailing newline if original had one
+        if content.endswith("\n") and not result.endswith("\n"):
+            result += "\n"
+        return result
+
+    def _get_numbered_sections(self, sections: list[Section]) -> list[Section]:
+        """Get all sections that should be numbered, excluding TOC."""
+        numbered_sections = []
+
+        for section in sections:
+            # Skip TOC section
+            if self.toc_section and section == self.toc_section:
+                continue
+
+            # Add this section and all its children
+            numbered_sections.extend(section.get_all_sections())
+
+        # Filter out TOC if it appears in children
+        if self.toc_section:
+            numbered_sections = [s for s in numbered_sections if s != self.toc_section]
+
+        return numbered_sections
+
+    def _generate_expected_numbers(self, sections: list[Section]) -> list[str]:
+        """Generate expected section numbers based on hierarchy."""
+        if not sections:
+            return []
+
+        expected_numbers = []
+        counters: dict[int, int] = {}  # level -> counter
+
+        for section in sections:
+            level = section.level
+
+            # Initialize counter for this level if not exists
+            if level not in counters:
+                counters[level] = 0
+
+            # Increment counter for this level
+            counters[level] += 1
+
+            # Reset counters for deeper levels
+            counters = {lvl: cnt for lvl, cnt in counters.items() if lvl <= level}
+
+            # Build number string
+            number_parts = []
+            for lvl in sorted(counters.keys()):
+                if lvl <= level:
+                    number_parts.append(str(counters[lvl]))
+
+            expected_numbers.append(".".join(number_parts))
+
+        return expected_numbers
+
+    def _generate_recommendations(self, issues: list[NumberingIssue]) -> list[str]:
+        """Generate recommendations based on validation issues."""
+        recommendations = []
+
+        if not issues:
+            return recommendations
+
+        # Check for numbering issues
+        has_numbering_issues = any(
+            issue.issue_type in ["missing_number", "wrong_number"] for issue in issues
+        )
+
+        if has_numbering_issues:
+            recommendations.append("Run 'renumber' to fix section numbering.")
+
+        # Check for format issues
+        has_format_issues = any(issue.issue_type == "invalid_format" for issue in issues)
+
+        if has_format_issues:
+            recommendations.append("Fix section number formatting manually.")
+
+        return recommendations
+
+    def get_section_number_at_level(self, number: str, target_level: int) -> str:
+        """
+        Extract section number at a specific level.
+
+        Args:
+            number: Full section number (e.g., "1.2.3")
+            target_level: Level to extract (1-based)
+
+        Returns:
+            Section number at the specified level
+        """
+        if not number:
+            return ""
+
+        parts = number.split(".")
+        if target_level <= len(parts):
+            return ".".join(parts[:target_level])
+
+        return number
+
+    def increment_section_number(self, number: str) -> str:
+        """
+        Increment the last part of a section number.
+
+        Args:
+            number: Section number to increment (e.g., "1.2.3")
+
+        Returns:
+            Incremented section number (e.g., "1.2.4")
+        """
+        if not number:
+            return "1"
+
+        parts = number.split(".")
+        if parts:
+            try:
+                last_part = int(parts[-1])
+                parts[-1] = str(last_part + 1)
+                return ".".join(parts)
+            except ValueError:
+                # If last part is not a number, append .1
+                return f"{number}.1"
+
+        return "1"
+
+    def get_parent_number(self, number: str) -> str:
+        """
+        Get the parent section number.
+
+        Args:
+            number: Section number (e.g., "1.2.3")
+
+        Returns:
+            Parent section number (e.g., "1.2")
+        """
+        if not number:
+            return ""
+
+        parts = number.split(".")
+        if len(parts) > 1:
+            return ".".join(parts[:-1])
+
+        return ""
+
+    def is_valid_number_format(self, number: str) -> bool:
+        """
+        Check if a section number has valid format.
+
+        Args:
+            number: Section number to validate
+
+        Returns:
+            True if format is valid
+        """
+        if not number:
+            return False
+
+        parts = number.split(".")
+        if not parts:
+            return False
+
+        return all(part.isdigit() and int(part) > 0 for part in parts)