markitecture 0.1.15__py3-none-any.whl

markitecture/__init__.py

@@ -0,0 +1,41 @@
+from importlib.metadata import version
+
+from markitecture import metrics
+
+from .errors import (
+    FileOperationError,
+    FileReadError,
+    FileWriteError,
+    InvalidPathError,
+    MarkitectureBaseError,
+    ParseError,
+)
+from .generators.configs.mkdocs_yaml import MkDocsConfig
+from .metrics.svg_generator import MetricsSvgGenerator
+from .processing.reflink_converter import (
+    ReferenceLinkConverter,
+    ReferencePlacement,
+)
+from .processing.text_splitter import MarkdownTextSplitter
+from .utils.file_handler import FileHandler
+from .utils.printer import RichPrinter
+
+__version__ = version("markitecture")
+
+__all__: list[str] = [
+    "FileHandler",
+    "FileOperationError",
+    "FileReadError",
+    "FileWriteError",
+    "InvalidPathError",
+    "MarkdownTextSplitter",
+    "MarkitectureBaseError",
+    "MetricsSvgGenerator",
+    "MkDocsConfig",
+    "ParseError",
+    "ReferenceLinkConverter",
+    "ReferencePlacement",
+    "RichPrinter",
+    "__version__",
+    "metrics",
+]

markitecture/__main__.py

@@ -0,0 +1,4 @@
+from markitecture.cli.app import run_cli
+
+if __name__ == "__main__":
+    run_cli()

markitecture/cli/__init__.py

@@ -0,0 +1,3 @@
+from markitecture.cli.app import run_cli
+
+__all__ = ["run_cli"]

markitecture/cli/app.py

@@ -0,0 +1,38 @@
+from markitecture.settings.config import MarkitectureApp
+from markitecture.utils.printer import RichPrinter
+
+_printer = RichPrinter()
+
+
+def run_cli() -> None:
+    """
+    Main entry point for the CLI. Routes commands to their appropriate handlers.
+    """
+    from markitecture import __version__
+
+    try:
+        settings = MarkitectureApp()
+        if settings.version:
+            _printer.print_version(__version__)
+            return
+
+        if settings.config:
+            settings.config.cli_cmd()
+        elif settings.check_links:
+            settings.check_links.cli_cmd()
+        elif settings.reference_links:
+            settings.reference_links.cli_cmd()
+        elif settings.metrics:
+            settings.metrics.cli_cmd()
+        elif settings.mkdocs:
+            settings.mkdocs.cli_cmd()
+        elif settings.split:
+            settings.split.cli_cmd()
+        else:
+            _printer.print_error(
+                "No command provided. Use `--help` for more information."
+            )
+
+    except Exception as e:
+        _printer.print_error(f"An error occurred: {e!r}")
+        raise e

markitecture/cli/commands/__init__.py

@@ -0,0 +1,21 @@
+"""
+Command implementations for the Markitecture CLI.
+
+This module contains all available commands that can be executed through the CLI.
+Each command is implemented as a separate class inheriting from BaseCommand.
+"""
+
+from .config import ConfigCommand
+from .links import CheckLinksCommand, ReferenceLinksCommand
+from .metrics import MetricsCommand
+from .mkdocs import MkDocsCommand
+from .split import SplitCommand
+
+__all__ = [
+    "CheckLinksCommand",
+    "ConfigCommand",
+    "MetricsCommand",
+    "MkDocsCommand",
+    "ReferenceLinksCommand",
+    "SplitCommand",
+]

markitecture/cli/commands/config.py

@@ -0,0 +1,84 @@
+"""CLI command for managing configurations via YAML files."""
+
+from pathlib import Path
+
+import yaml
+from pydantic import AliasChoices, BaseModel, Field, field_validator
+
+from markitecture.settings.validators import convert_to_path
+from markitecture.utils.printer import RichPrinter
+
+_printer = RichPrinter()
+
+
+class ConfigCommand(BaseModel):
+    """
+    CLI command for managing configurations via YAML files.
+    """
+
+    config_path: Path = Field(
+        default=Path("markitect.yml"),
+        description="Path to the configuration file.",
+        validation_alias=AliasChoices("p", "path"),
+    )
+    generate: bool = Field(
+        default=False,
+        description="Generate a default configuration file.",
+        validation_alias=AliasChoices("g", "generate"),
+    )
+    show: bool = Field(
+        default=False,
+        description="Display the current configuration settings.",
+        validation_alias=AliasChoices("s", "show"),
+    )
+
+    validate_fields = field_validator("config_path")(convert_to_path)
+
+    def cli_cmd(self) -> None:
+        """Execute the configuration command."""
+        if self.generate:
+            self.generate_config()
+
+        if self.show:
+            self.show_config()
+
+    def generate_config(self) -> None:
+        """Generates a default configuration file."""
+        from markitecture.cli.app import MarkitectureApp
+
+        _printer.print_info(
+            f"Generating default configuration file at {self.config_path}"
+        )
+        settings = MarkitectureApp()
+        settings_dict = settings.model_dump(mode="json")
+
+        with self.config_path.open("w", encoding="utf-8") as file:
+            yaml.dump(
+                settings_dict,
+                file,
+                default_flow_style=False,
+                sort_keys=False,
+            )
+        _printer.print_success(
+            f"Markitecture configuration file generated at: {self.config_path}"
+        )
+
+    def show_config(self) -> None:
+        """Displays the current configuration settings."""
+        if self.config_path.exists():
+            _printer.print_debug(f"Reading configuration file: {self.config_path}")
+
+            try:
+                with self.config_path.open(encoding="utf-8") as file:
+                    settings = yaml.safe_load(file)
+            except yaml.YAMLError as e:
+                _printer.print_error(f"Error reading configuration file: {e}")
+                return
+
+            _printer.print_key_value_table("Configuration Settings", settings)
+
+        else:
+            _printer.print_error(
+                f"No configuration file found at {self.config_path}. "
+                "Use '--generate' to create one."
+            )

markitecture/cli/commands/links.py

@@ -0,0 +1,146 @@
+"""Commands for checking and converting markdown links."""
+
+import re
+from pathlib import Path
+
+from pydantic import AliasChoices, BaseModel, Field
+
+from markitecture.processing.link_validator import LinkValidator
+from markitecture.processing.reflink_converter import (
+    ReferenceLinkConverter,
+    ReferencePlacement,
+)
+from markitecture.settings.validators import ExistingFilePath
+from markitecture.utils.printer import RichPrinter
+
+_printer = RichPrinter()
+
+
+class CheckLinksCommand(BaseModel):
+    """
+    Validate all links in a markdown file.
+    """
+
+    input_file: ExistingFilePath = Field(
+        ...,
+        description="Path to the markdown file.",
+        validation_alias=AliasChoices("i", "input"),
+    )
+    report_path: Path = Field(
+        default=Path(".markitecture/link_health.txt"),
+        description="Path to save the report.",
+        validation_alias=AliasChoices("rp", "report-path"),
+    )
+    max_workers: int = Field(
+        default=5,
+        ge=1,
+        le=10,
+        description="Number of concurrent link checks.",
+        validation_alias=AliasChoices("mw", "max-workers"),
+    )
+    timeout: int = Field(
+        default=10,
+        ge=1,
+        le=180,
+        description="Timeout for link validation in seconds.",
+        validation_alias=AliasChoices("t", "timeout"),
+    )
+
+    def cli_cmd(self) -> None:
+        """Execute the check links command."""
+        _printer.print_info(
+            f"Scanning markdown file {self.input_file} for broken links..."
+        )
+
+        checker = LinkValidator(timeout=self.timeout, max_workers=self.max_workers)
+        results = checker.check_markdown_file(str(self.input_file))
+        if not results:
+            _printer.print_info("No links found.")
+            return
+
+        broken_links = 0
+        rows = []
+        for result in results:
+            status = "✓" if result["status"] == "ok" else "𝗫"
+            error = result["error"] if result["error"] else ""
+            rows.append([status, str(result["line"]), result["url"], error])
+            if result["error"]:
+                broken_links += 1
+
+        _printer.print_table(
+            "Markdown Link Check Results",
+            ["Status", "Line", "Link", "Error"],
+            rows,
+        )
+        _printer.print_success(
+            f"Summary: {broken_links} broken links out of {len(results)} total links.\n"
+        )
+
+
+class ReferenceLinksCommand(BaseModel):
+    """Convert inline markdown links to reference-style links."""
+
+    input_file: ExistingFilePath = Field(
+        ...,
+        description="Path to the markdown file.",
+        validation_alias=AliasChoices("i", "input"),
+    )
+    output_file: Path | str = Field(
+        default=Path("reflinks_output.md"),
+        description="Path to save updated document.",
+        validation_alias=AliasChoices("o", "output"),
+    )
+    placement: ReferencePlacement = Field(
+        default=ReferencePlacement.END,
+        description="Where to place reference links (end/section).",
+        validation_alias=AliasChoices("p", "placement"),
+    )
+
+    def cli_cmd(self) -> None:
+        """Execute the reference link conversion."""
+        _printer.print_title("Reference Link Conversion")
+        _printer.print_info("Configuration:")
+        _printer.print_key_value_table(
+            "Settings",
+            {
+                "Input File": str(self.input_file),
+                "Output File": str(self.output_file),
+                "Placement": self.placement.value,
+            },
+        )
+
+        try:
+            # Initialize converter
+            converter = ReferenceLinkConverter()
+            content = Path(self.input_file).read_text()
+
+            # Extract initial metrics
+            initial_links = len(re.findall(r"\[([^\]]+)\]\(([^\)]+)\)", content))
+            _printer.print_info(f"Found {initial_links} inline links to convert")
+
+            # Process file
+            _printer.print_debug("Starting conversion process...")
+            converter.process_file(
+                self.input_file,
+                self.output_file or self.input_file,
+                self.placement,
+            )
+
+            # Get final metrics
+            result = Path(self.output_file).read_text()
+            final_refs = len(re.findall(r"^\[[^\]]+\]:", result, re.MULTILINE))
+
+            # Summary
+            _printer.print_success("\nConversion Summary:")
+            _printer.print_key_value_table(
+                "Results",
+                {
+                    "Links Processed": str(initial_links),
+                    "References Created": str(final_refs),
+                    "Output Location": str(self.output_file),
+                },
+            )
+
+        except Exception as e:
+            _printer.print_error(f"Error during conversion: {e!s}")
+            raise

markitecture/cli/commands/metrics.py

@@ -0,0 +1,193 @@
+from pathlib import Path
+
+from pydantic import AliasChoices, BaseModel, Field
+
+from markitecture.metrics.analyzer import ReadabilityAnalyzer, ReadabilityMetrics
+from markitecture.metrics.svg_generator import (
+    BadgeStyle,
+    MetricsSvgGenerator,
+)
+from markitecture.settings.validators import ExistingFilePath
+from markitecture.utils.file_handler import FileHandler
+from markitecture.utils.printer import RichPrinter
+
+_printer = RichPrinter()
+
+
+class MetricsCommand(BaseModel):
+    """
+    Generate reading time estimates and complexity metrics for markdown files.
+    """
+
+    input: ExistingFilePath = Field(
+        ...,
+        description="Path to the markdown file.",
+        validation_alias=AliasChoices("i", "input"),
+    )
+    output: Path | None = Field(
+        default=None,
+        description=f"Path to save the SVG badge. If not specified, creates {input}_metrics.svg",
+        validation_alias=AliasChoices("o", "output"),
+    )
+    output_dir: Path | None = Field(
+        default=None,
+        description="Directory to save all badge styles when using --style all",
+        validation_alias=AliasChoices("d", "dir", "output-dir"),
+    )
+    insert: bool = Field(
+        default=True,
+        description="Insert metrics badge into the document.",
+        validation_alias=AliasChoices("ins", "insert"),
+    )
+    position: str = Field(
+        default="top",
+        description="Position to insert badge (top/bottom).",
+        validation_alias=AliasChoices("p", "pos", "position"),
+    )
+    style: BadgeStyle | str = Field(
+        default=BadgeStyle.MODERN,
+        description="Badge style (modern/compact/detailed/minimal/retro) or 'all' for all styles",
+        validation_alias=AliasChoices("s", "style"),
+    )
+
+    def _generate_single_badge(
+        self,
+        metrics: ReadabilityMetrics,
+        style: BadgeStyle,
+        content: str,
+        output_path: Path,
+    ) -> None:
+        """Generate a single badge style."""
+        generator = MetricsSvgGenerator()
+        svg_content = generator.generate_svg(metrics, style)
+
+        # Save badge
+        Path(output_path).write_text(svg_content, encoding="utf-8")
+        _printer.print_info(f"Generated {style.value} style badge: {output_path}")
+
+        # Insert if requested and this is the primary style
+        if self.insert and style == self.style:
+            doc_content = content
+            svg_ref = f"![Reading Metrics]({output_path})"
+            if self.position.lower() == "top":
+                doc_content = f"{svg_ref}\n\n{content}"
+            else:
+                doc_content = f"{content}\n\n{svg_ref}"
+            Path(self.input).write_text(doc_content, encoding="utf-8")
+            _printer.print_info(f"Metrics badge added to document at: {self.position}")
+
+    def _generate_all_badges(self, metrics: ReadabilityAnalyzer, content: str) -> None:
+        """Generate badges in all available styles."""
+        # Create output directory if needed
+        output_dir = self.output_dir or Path(self.input).parent / "metrics_badges"
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        # Generate each style
+        for style in BadgeStyle:
+            output_path = output_dir / f"metrics_{style.value}.svg"
+            self._generate_single_badge(metrics, style, content, output_path)
+
+        _printer.print_info(f"\nAll badge styles generated in: {output_dir}")
+
+        # Generate preview HTML
+        preview_path = output_dir / "preview.html"
+        self._generate_preview_page(metrics, output_dir, preview_path)
+        _printer.print_info(f"Preview page generated: {preview_path}")
+
+    def _generate_preview_page(
+        self, metrics: ReadabilityMetrics, badge_dir: Path, output_path: Path
+    ) -> None:
+        """Generate HTML preview page showing all badge styles."""
+        html = f"""<!DOCTYPE html>
+<html>
+<head>
+    <title>Metrics Badge Styles - {self.input.name}</title>
+    <style>
+        body {{
+            font-family: Arial, sans-serif;
+            max-width: 800px;
+            margin: 40px auto;
+            padding: 0 20px;
+            background: #f5f5f5;
+        }}
+        .badge-container {{
+            background: white;
+            border-radius: 8px;
+            padding: 20px;
+            margin: 20px 0;
+            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+        }}
+        h1 {{
+            color: #333;
+            border-bottom: 2px solid #eee;
+            padding-bottom: 10px;
+        }}
+        h2 {{
+            color: #666;
+            margin-top: 30px;
+        }}
+        .badge {{
+            margin: 20px 0;
+        }}
+        .style-name {{
+            color: #888;
+            font-size: 0.9em;
+            margin-bottom: 10px;
+        }}
+    </style>
+</head>
+<body>
+    <h1>Metrics Badge Styles</h1>
+    <p>Document: <strong>{self.input.name}</strong></p>
+"""
+
+        # Add each badge
+        for style in BadgeStyle:
+            badge_path = f"metrics_{style.value}.svg"
+            html += f'''
+    <div class="badge-container">
+        <div class="style-name">{style.value.title()} Style</div>
+        <div class="badge">
+            <img src="{badge_path}" alt="Metrics Badge - {style.value} Style">
+        </div>
+    </div>'''
+
+        html += """
+</body>
+</html>"""
+
+        output_path.write_text(html, encoding="utf-8")
+
+    def cli_cmd(self) -> None:
+        """Execute the metrics generation command."""
+        _printer.print_info(f"Analyzing document metrics for: {self.input}")
+
+        # Read content and generate metrics
+        content = FileHandler().read(self.input)
+        analyzer = ReadabilityAnalyzer()
+        metrics = analyzer.analyze_document(content)
+
+        # Generate badges based on style option
+        if self.style == "all":
+            self._generate_all_badges(metrics, content)
+        else:
+            output_path = self.output or Path(f"{self.input.stem}_metrics.svg")
+            self._generate_single_badge(
+                metrics, BadgeStyle(self.style), content, output_path
+            )
+
+        # Display metrics summary
+        _printer.print_title("Document Metrics Summary")
+        _printer.print_key_value_table(
+            "Metrics",
+            {
+                "Reading Time": f"{metrics.reading_time_mins} minutes",
+                "Word Count": f"{metrics.word_count:,}",
+                "Complexity Score": f"{metrics.complexity_score}%",
+                "Average Words/Sentence": f"{metrics.avg_words_per_sentence:.1f}",
+                "Headings": f"{metrics.heading_count}",
+                "Code Blocks": f"{metrics.code_block_count}",
+                "Links": f"{metrics.link_count}",
+                "Images": f"{metrics.image_count}",
+            },
+        )

markitecture/cli/commands/mkdocs.py

@@ -0,0 +1,39 @@
+from pathlib import Path
+
+from pydantic import AliasChoices, BaseModel, Field, field_validator
+
+from markitecture.generators.configs.mkdocs_yaml import MkDocsConfig
+from markitecture.settings.validators import convert_to_path
+from markitecture.utils.printer import RichPrinter
+
+_printer = RichPrinter()
+
+
+class MkDocsCommand(BaseModel):
+    """
+    Generate a basic MkDocs configuration.
+    """
+
+    docs_dir: Path = Field(
+        default=Path(".markitecture/docs"),
+        description="Path to the documentation directory.",
+        validation_alias=AliasChoices("d", "dir", "docs-dir"),
+    )
+    site_name: str = Field(
+        default="MkDocs Static Site Documentation",
+        description="Name of the MkDocs site.",
+        validation_alias=AliasChoices("name", "site-name"),
+    )
+
+    validate_fields = field_validator("docs_dir")(convert_to_path)
+
+    def cli_cmd(self) -> None:
+        """Execute MkDocs configuration generation."""
+        _printer.print_info(
+            f"Generating MkDocs static site config for: {self.docs_dir}"
+        )
+        MkDocsConfig(
+            docs_dir=self.docs_dir,
+            site_name=self.site_name,
+        ).generate_config()
+        _printer.print_info(f"MkDocs config generated and saved to: {self.docs_dir}.")

markitecture/cli/commands/split.py

@@ -0,0 +1,48 @@
+from pathlib import Path
+
+from pydantic import AliasChoices, BaseModel, Field
+
+from markitecture.settings.validators import ExistingFilePath
+from markitecture.utils.file_handler import FileHandler
+from markitecture.utils.printer import RichPrinter
+
+_printer = RichPrinter()
+
+
+class SplitCommand(BaseModel):
+    """
+    Split a markdown file into sections based on headings.
+    """
+
+    input_file: ExistingFilePath = Field(
+        ...,
+        description="Path to the input markdown file.",
+        validation_alias=AliasChoices("i", "input"),
+    )
+    output_dir: Path = Field(
+        default=Path(".markitecture/docs"),
+        description="Directory to save split files.",
+        validation_alias=AliasChoices("o", "output"),
+    )
+    heading_level: str = Field(
+        default="##",
+        description="Heading level to split on (e.g., '#', '##').",
+        validation_alias=AliasChoices("hl", "heading", "level", "heading-level"),
+    )
+    case_sensitive: bool = Field(
+        default=False,
+        description="Enable case-sensitive heading matching.",
+        validation_alias=AliasChoices("cs", "case-sensitive"),
+    )
+
+    def cli_cmd(self) -> None:
+        """Execute the split command."""
+        from markitecture.processing.text_splitter import MarkdownTextSplitter
+
+        _printer.print_info(f"Splitting Markdown file: {self.input_file}")
+        _printer.print_info(f"Splitting on heading level: {self.heading_level}")
+        splitter = MarkdownTextSplitter()
+        content = FileHandler().read(self.input_file)
+        # splitter.settings = self.model_dump()
+        splitter.process_file(content)
+        _printer.print_info(f"Split completed. Files saved to: {self.output_dir}")

markitecture/errors.py

@@ -0,0 +1,64 @@
+"""Custom exceptions for the markitecture package."""
+
+from __future__ import annotations
+
+from typing import Any
+
+# ----- Base ----- #
+
+
+class MarkitectureBaseError(Exception):
+    """Base exception for markitecture errors."""
+
+    ...
+
+
+class ParseError(MarkitectureBaseError):
+    """Raised when parsing markdown content fails."""
+
+    ...
+
+
+class FileOperationError(MarkitectureBaseError):
+    """Raised when file operations fail."""
+
+    ...
+
+
+# ----- CLI ----- #
+
+
+class CLIError(MarkitectureBaseError):
+    """Exceptions related to the CLI."""
+
+    def __init__(self, message: str, *args: Any) -> None:
+        super().__init__(f"Invalid option provided to CLI: {message}", *args)
+
+
+# ----- File IO ----- #
+
+
+class FileSystemError(MarkitectureBaseError):
+    """Exceptions related to file system operations."""
+
+    def __init__(self, message: str, path: str, *args: Any) -> None:
+        self.file_path = path
+        super().__init__(f"{message}: {path}", *args)
+
+
+class FileReadError(FileSystemError):
+    """Could not read file."""
+
+    ...
+
+
+class FileWriteError(FileSystemError):
+    """Could not write file."""
+
+    ...
+
+
+class InvalidPathError(FileSystemError):
+    """Invalid path provided."""
+
+    ...

markitecture/generators/__init__.py

@@ -0,0 +1,3 @@
+from markitecture.generators.configs.mkdocs_yaml import MkDocsConfig
+
+__all__: list[str] = ["MkDocsConfig"]