From 8eb3a8fd0ca55fea521372a477256cd55a3ced50 Mon Sep 17 00:00:00 2001 From: nvaldez Date: Wed, 23 Sep 2026 11:38:16 +0200 Subject: [PATCH] major refactor --- .coveragerc | 16 + AGENTS.md | 351 +++++++++++++++++++ README.md | 326 ++++++++++++++++-- pyproject.toml | 18 +- src/librarian/md_frontmatter.py | 560 ++++++++++++++++++++++++++++++ src/run_tests.py | 2 +- src/tests/__init__.py | 1 + src/tests/test_fiona_main.py | 135 +++++++- src/tests/test_generate_toc.py | 489 ++++++++++++++++++++++++++ src/tests/test_md_frontmatter.py | 574 +++++++++++++++++++++++++++++++ src/tests/test_mdoctor.py | 183 ++++++++++ src/tests/test_python_ruff.py | 162 ++++++++- 12 files changed, 2782 insertions(+), 35 deletions(-) create mode 100644 .coveragerc create mode 100644 AGENTS.md create mode 100644 src/librarian/md_frontmatter.py create mode 100644 src/tests/__init__.py create mode 100644 src/tests/test_generate_toc.py create mode 100644 src/tests/test_md_frontmatter.py diff --git a/.coveragerc b/.coveragerc new file mode 100644 index 0000000..63dda69 --- /dev/null +++ b/.coveragerc @@ -0,0 +1,16 @@ +[run] +source = src +omit = + src/tests/* + */tests/* + */test_*.py + +[report] +exclude_lines = + pragma: no cover + def __repr__ + raise AssertionError + raise NotImplementedError + if __name__ == .__main__.: + if TYPE_CHECKING: + @abstractmethod diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..359c0e8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,351 @@ +--- +name: Fiona-Assistant Agent Rules +version: 1.0.0 +title: LLM Agent Rules +type: summary +created: 2025-09-23 +updated: 2025-09-23 +tags: [agents, rules, guidelines, llm, ai] +sources: [] +--- + +# Fiona-Assistant LLM Agent Rules + +## Overview + +This document defines the rules and guidelines for LLM Agents (including AI assistants, hives, and automated tools) when interacting with the Fiona-Assistant repository. + +--- + +## Environment Setup (MANDATORY) + +### Rule 1: Always Use Bootstrap for Environment +> **BEFORE any testing or development work, you MUST source the bootstrap script** + +```bash +# Bare minimum - always run this first +source bootstrap + +# For a specific environment name +source bootstrap --env fiona_env + +# With Python version +source bootstrap --env --python + +# With cleanup flag +source bootstrap --env -c +``` + +**Rationale**: The bootstrap script sets up the Python virtual environment, installs dependencies, and ensures a consistent development environment. All testing and development MUST happen within this environment. + +**Violation**: Operating outside the bootstrapped environment may lead to dependency conflicts, incorrect Python versions, or missing packages. + +--- + +## Python Development Rules + +### Rule 2: Load Python TDD Skill for Python Tasks +> **When modifying or creating Python scripts, the Python TDD Skill MUST be loaded** + +``` +SKILL: python-tdd +PATH: llm-wiki/utils/skills/python-tdd/SKILL.md +``` + +**Required Practices from Python TDD Skill:** +- Strictly follow **Test-Driven Development (TDD)** - Red-Green-Refactor cycle +- Use **pytest** for testing +- Follow **OOP principles** and **SOLID** design patterns +- Write **minimal, maintainable code** (KISS, DRY, YAGNI) +- Use **type hints** for all public functions +- Write **Google-style or NumPy-style docstrings** +- Use **PEP 8** compliance (snake_case, 4-space indents) +- **100% test coverage** for critical paths + +**Applicability**: Any task involving Python code, including: +- Creating new Python modules +- Modifying existing Python scripts +- Debugging Python code +- Refactoring Python code + +**Exception**: Read-only operations (listing files, viewing code) do not require the TDD skill. + +--- + +## Repository Structure Rules + +### Rule 3: Respect Directory Boundaries + +The repository has the following structure with specific permissions: + +``` +fiona-assistant/ +├── llm-wiki/ # Wiki content (see llm-wiki/AGENTS.md) +│ ├── personal/ # READ-ONLY - Never modify +│ ├── ingest/ # Input zone - parse files here +│ ├── wiki/ # READ-WRITE - synthesized content +│ │ ├── concepts/ # Processed concept notes +│ │ ├── raw/ # READ-ONLY - archived sources +│ │ │ ├── articles/ +│ │ │ ├── papers/ +│ │ │ ├── transcripts/ +│ │ │ └── assets/ +│ │ ├── index.md # Master index - update on changes +│ │ └── log.md # Action log - append all actions +│ └── utils/ # Utility scripts +│ +├── src/ # Source code +│ ├── fiona/ # Main CLI package +│ ├── librarian/ # Wiki content management +│ ├── mdoctor/ # Markdown diagnosis +│ ├── python_ruff/ # Python code linting +│ ├── tests/ # Unit tests +│ └── ... +│ +├── pyproject.toml # Project configuration +├── bootstrap # Environment setup +└── README.md # Project documentation +``` + +**General Rules:** +- `/personal/` directories are **STRICTLY READ-ONLY** - Never create, edit, or delete +- `/raw/` directories are **READ-ONLY** - Never edit archived source materials +- `/wiki/concepts/` is **READ-WRITE** - Place synthesized content here +- `/ingest/` is for **input processing** - Parse files dropped here +- **Always update** `llm-wiki/wiki/index.md` when adding new concepts +- **Always append** to `llm-wiki/wiki/log.md` for every action + +--- + +## Testing Rules + +### Rule 4: Testing Requirements + +**All code changes MUST be tested** following TDD principles: + +1. **Write failing tests first** (Red phase) +2. **Write minimal code to pass** (Green phase) +3. **Refactor** while keeping tests passing + +**Test Execution:** +```bash +# Run all tests +python src/run_tests.py + +# Run with pytest directly +python -m pytest + +# Run with coverage +python -m pytest --cov=src + +# Run specific test file +python -m pytest src/tests/test_md_frontmatter.py -v +``` + +**Test File Structure:** +- Test files must be named `test_*.py` or `*_test.py` +- Tests must be in a `tests/` directory +- Each module should have its own test file +- Test functions must start with `test_` + +**Coverage Requirement:** +- Aim for **100% coverage** on critical code paths +- Minimum **80% coverage** for all production code +- Use `pytest-cov` for coverage reporting + +--- + +## Code Quality Rules + +### Rule 5: Linting and Formatting + +**Before committing any Python code:** + +```bash +# Lint markdown files +mdoctor chklint src/ + +# Lint Python files +python-ruff chklint src/ + +# Or use fiona-assistant CLI +fiona-assistant mdoctor chklint src/ +fiona-assistant python-ruff chklint src/ +``` + +**Requirements:** +- All Python code must pass **Ruff** linting +- All markdown files must pass **PyMarkdown** linting +- No linting errors may be committed to the repository + +--- + +## Version Control Rules + +### Rule 6: Git Operations + +**Commit Messages:** +- Use **semantic commit** format +- Prefix with type: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:` +- Keep messages concise and descriptive + +**Examples:** +```bash +git commit -m "feat: add md_frontmatter module for version control" +git commit -m "fix: handle empty frontmatter delimiters in parser" +git commit -m "test: add TDD tests for name/version extraction" +``` + +**Required before PR:** +- [ ] All tests pass +- [ ] All linting passes +- [ ] Code coverage maintained or improved +- [ ] Documentation updated + +--- + +## Workflow Rules + +### Rule 7: Development Workflow + +**Standard Workflow:** + +1. **Setup Environment** (MANDATORY) + ```bash + source bootstrap --env + ``` + +2. **Load Appropriate Skill** (if applicable) + - Python tasks: Load `python-tdd` skill + - Wiki tasks: Load `llm-wiki` skill + +3. **Follow TDD for Code Changes** + - Write tests first + - Implement minimal code + - Refactor + +4. **Validate** + - Run tests + - Run linters + +5. **Document** + - Update docstrings + - Update README if needed + +--- + +## Frontmatter Rules + +### Rule 8: MD File Frontmatter + +**All markdown files in llm-wiki/ MUST have YAML frontmatter** with: + +```yaml +--- +name: Document Name +version: 1.0.0 +title: Page Title +created: YYYY-MM-DD +updated: YYYY-MM-DD +type: concept | entity | comparison | query | summary +--- +``` + +**Version Tracking:** +- The `version` field is used for **source control** and change detection +- Always increment version when making significant changes +- Use semantic versioning (MAJOR.MINOR.PATCH) + +--- + +## Error Handling Rules + +### Rule 9: Report, Don't Fail Silently + +**When errors occur:** +- **DO** raise appropriate exceptions with clear messages +- **DO** validate inputs before processing +- **DON'T** silently ignore errors +- **DON'T** return None/empty without explanation + +--- + +## Communication Rules + +### Rule 10: AI/Human Friendly Output + +**All tool outputs MUST be formatted for easy parsing by both humans and AI.** + +**Requirements:** +- Use consistent indentation (2 or 4 spaces) +- Use clear section headers +- Include summaries at the end +- Use tables for structured data when appropriate + +--- + +## Priority Rules + +### Rule 11: Task Prioritization + +When multiple tasks are possible, prioritize in this order: + +1. **User's explicit request** (highest priority) +2. **TDD requirements** (tests before implementation) +3. **Code quality** (linting, formatting) +4. **Documentation** (docstrings, README) +5. **Refactoring** (improving existing code) +6. **New features** (lowest priority) + +--- + +## Anti-Patterns + +### Rule 12: Things to Never Do + +- Never modify `/personal/` or `/raw/` directories +- Never commit code without tests +- Never commit code that fails linting +- Never ignore AGENTS.md rules without explicit user override +- Never assume user intent - always ask for clarification +- Never make changes without a clear purpose +- Never leave broken tests in the repository + +--- + +## Override Rules + +### Rule 13: When Rules Can Be Broken + +These rules **CAN** be overridden by: + +1. **Explicit user instruction** (e.g., "skip tests this time") +2. **Higher-priority AGENTS.md** in a subdirectory +3. **Emergency fixes** for critical issues + +--- + +## Quick Reference + +| Task | Required Action | +|------|----------------| +| Any Python work | Load python-tdd skill | +| Before testing | `source bootstrap` | +| Modifying code | Write tests first (TDD) | +| Before commit | Run tests + linters | +| Wiki changes | Update index.md + log.md | +| Frontmatter | Include name, version, title, dates | +| Errors | Raise exceptions, don't fail silently | + +--- + +## Enforcement + +**These rules are ENFORCED at the system level** and will be checked. + +**Violations will be:** +1. Reported to the user +2. Blocked if possible +3. Logged in `llm-wiki/wiki/log.md` + +--- \ No newline at end of file diff --git a/README.md b/README.md index 2bc16b7..edc3a40 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,328 @@ # Fiona-Assistant -Tools for managing the LLM wiki. +**LLM Wiki Tool Helper for LLM Agents/Hives** -## Development +Fiona-Assistant is a command-line toolkit designed to manage, organize, and maintain LLM wiki content with minimal AI token dependence. It combines script-based automation with structured workflows to help LLM Agents and Hives efficiently manage documentation, markdown files, and code quality. -### Setup +--- -1. Create and activate the virtual environment: +## Overview + +### Purpose +Fiona-Assistant serves as a **standalone MD/scripts/docs organizer** and **LLM wiki management helper** that: + +- **Reduces AI Token Usage**: Uses deterministic scripts and tools to handle wiki management tasks that don't require LLM intelligence +- **Maintains Wiki Structure**: Enforces consistent organization of markdown files, concepts, and raw source materials +- **Validates Content Quality**: Provides linting and diagnosis tools for markdown and Python code +- **Enables Script-Based Workflows**: Automates repetitive wiki maintenance tasks through CLI commands + +### Core Philosophy +> Use scripts for deterministic tasks, reserve AI tokens for creative and analytical work + +The toolkit is designed to be **AI-friendly** - outputs are formatted in consistent, parseable structures that LLMs can easily read and process. + +--- + +## Features + +### Tool Suite + +| Tool | Purpose | Key Capabilities | +|------|---------|------------------| +| **Librarian** | Wiki content management | List files, scan directories, organize MD content | +| **MDoctor** | Markdown diagnosis | Lint markdown files using PyMarkdown, detect formatting issues | +| **Python-Ruff** | Code quality | Lint Python files using Ruff, enforce code standards | +| **Generate-TOC** | Table of contents | Auto-generate nested TOC from markdown headers | + +### Wiki Structure Support +Fiona-Assistant understands and maintains the [LLM Wiki directory structure](./llm-wiki/AGENTS.md): + +``` +llm-wiki/ +├── ingest/ # Input zone: files to be processed +├── raw/ # Archived source materials (read-only) +│ ├── articles/ +│ ├── papers/ +│ ├── transcripts/ +│ └── assets/ +├── wiki/ # Processed content +│ └── concepts/ # Synthesized concept notes +├── personal/ # User notes (read-only for agents) +└── utils/ # Utility scripts +``` + +--- + +## Installation + +### Quick Install (Production) + +```bash +python -m pip install fiona-assistant +``` + +### Development Setup + +- **Clone the repository:** + ```bash + git clone + cd fiona-assistant + ``` + +- **Create and activate the virtual environment:** ```bash source bootstrap --env fiona_env -c ``` > Make sure `fiona_env` is activated as pyenv before proceeding -### Testing +--- + +## Usage + +### Main CLI + +Fiona-Assistant provides a unified CLI with multiple subcommands: -Run tests with pytest: ```bash -python src/run_tests.py +# Show all available commands +fiona-assistant --help + +# Run via Python module +python -m fiona --help ``` -### Usage +#### Available Commands -Run the fiona-assistant CLI with subcommands: ```bash -# Test command (via module) -python -m fiona test - -# Or via entry point +# Run tests fiona-assistant test -# List files with librarian -fiona-assistant librarian +# Manage wiki content with Librarian +fiona-assistant librarian [directory] -# List files with mdoctor -fiona-assistant mdoctor +# Diagnose markdown files with MDoctor +fiona-assistant mdoctor [chklint] [directory] + +# Lint Python code with Ruff +fiona-assistant python-ruff [chklint] [directory] ``` -> Note: Use `fiona-assistant ` or `python -m fiona ` +### Direct Tool Access + +Each tool can also be called directly: -To see all available commands: ```bash -fiona-assistant --help -``` \ No newline at end of file +# Librarian - List all files in a directory +librarian [directory] + +# MDoctor - Check markdown lint violations +mdoctor chklint [directory] + +# MDoctor - List all files + +# Python-Ruff - Check Python code quality +python-ruff chklint [directory] + +# Generate table of contents for markdown files +generate-toc [directory] [options] +``` + +--- + +## Workflow Examples + +### Wiki Ingestion Workflow + +```bash +# 1. Drop raw files into ingest directory +# (Manual or automated process) + +# 2. List files ready for processing +librarian llm-wiki/ingest + +# 3. Validate markdown quality before processing +mdoctor chklint llm-wiki/ingest + +# 4. Move processed files to raw archive +# (Agent/orchestration task) +``` + +### Content Maintenance Workflow + +```bash +# Check all markdown files in wiki for lint violations +mdoctor chklint llm-wiki/wiki + +# Generate table of contents for concept notes +generate-toc llm-wiki/wiki/concepts --recursive-toc + +# Validate Python code in the project +python-ruff chklint src/ + +# List all markdown files for inventory +librarian llm-wiki/ +``` + +### Standalone Document Organization + +```bash +# Organize any directory of markdown files +librarian /path/to/docs/ + +# Validate markdown formatting +mdoctor chklint /path/to/docs/ + +# Create nested table of contents +generate-toc /path/to/docs/ --recursive-toc +``` + +--- + +## Output Format + +All tools produce **AI-friendly output** with consistent formatting: + +### MDoctor Output Format +``` +PyMarkdownLint Violations +TARGET: /path/to/directory + +- DEFINITIONS: + - md001: Heading levels should only increment by one, Heading levels should only increment by one level at a time + - md013: Line length, Line length + +- FILE: file1.md + - 10:5 md013 + - 20:3 md001 + +- SUMMARY: + - Total files with violations: 1 + - Total violations: 2 +``` + +### Python-Ruff Output Format +``` +Ruff Violations +TARGET: /path/to/directory + +Definitions: + - F401: `*` import used, but not imported + - E501: Line too long + +- FILE: script.py + - 15:10 F401 + - 25:80 E501 + +- SUMMARY: + - Total files with violations: 1 + - Total violations: 2 +``` + +--- + +## Project Structure + +``` +fiona-assistant/ +├── llm-wiki/ # Wiki content and structure definition +│ ├── AGENTS.md # Agent rules and directory permissions +│ ├── ingest/ # Input zone for new content +│ ├── raw/ # Archived source materials +│ ├── wiki/ # Processed concept notes +│ └── utils/ # Utility scripts +│ +├── src/ +│ ├── fiona/ # Main CLI entry point +│ │ └── __main__.py # Unified command dispatcher +│ │ +│ ├── librarian/ # Wiki content management +│ │ ├── __init__.py +│ │ ├── librarian.py # File scanning and listing +│ │ └── generate_toc.py # Table of contents generator +│ │ +│ ├── mdoctor/ # Markdown diagnosis +│ │ ├── __init__.py +│ │ └── mdoctor.py # PyMarkdown lint wrapper +│ │ +│ ├── python_ruff/ # Python code linting +│ │ ├── __init__.py +│ │ └── python_ruff.py # Ruff lint wrapper +│ │ +│ ├── tests/ # Unit tests +│ │ ├── test_fiona_main.py +│ │ ├── test_librarian.py +│ │ ├── test_mdoctor.py +│ │ └── test_python_ruff.py +│ │ +│ ├── run_tests.py # Test runner +│ └── README.md # Development documentation +│ +├── pyproject.toml # Project configuration +├── bootstrap # Environment setup script +├── LICENSE # GPL-3.0-only +└── README.md # This file +``` + +--- + +## Testing + +### Run Tests + +```bash +# Run all tests +python src/run_tests.py + +# Or use pytest directly +python -m pytest + +# Run with coverage +python -m pytest --cov=src +``` + +--- + +## License + +GPL-3.0-only + +--- + +## Key Concepts + +### For LLM Agents +- **Deterministic Operations**: Use Fiona-Assistant for file listing, linting, and organization +- **Token Efficiency**: Reserve LLM context for synthesis, analysis, and creative tasks +- **Structured Output**: All tool outputs are formatted for easy parsing by LLMs + +### For Human Users +- **CLI-First**: All functionality available through command-line interface +- **Composable Tools**: Combine tools in scripts for automated workflows +- **Clear Structure**: Maintains consistent wiki organization standards + +--- + +## Related Documentation + +- [LLM Wiki Agent Rules](./llm-wiki/AGENTS.md) - Directory permissions and workflow rules +- [Development Setup](./src/README.md) - Detailed development information +- [Project TODO](./todo.md) - Roadmap and planned features + +--- + +## Quick Reference Card + +| Task | Command | +|------|---------| +| Show help | `fiona-assistant --help` | +| List files | `fiona-assistant librarian /path/to/dir` | +| Check MD lint | `fiona-assistant mdoctor chklint /path/to/dir` | +| Check Python lint | `fiona-assistant python-ruff chklint /path/to/dir` | +| Generate TOC | `generate-toc /path/to/dir --recursive-toc` | +| Run tests | `python src/run_tests.py` | +| Install | `pip install fiona-assistant` | +| Dev install | `pip install -e .` | + +--- + +> **Note**: All paths are relative to the current working directory unless specified as absolute paths. \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 8b0aa1f..c9d0ecb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -18,7 +18,8 @@ classifiers = [ # Core dependencies (required for runtime) dependencies = [ "pymarkdownlnt>=0.9.0", - "ruff" + "ruff>=0.16.8", + "pyyaml>=6.0.3" ] # Optional dependencies groups @@ -39,6 +40,21 @@ include = ["fiona", "librarian", "mdoctor"] [tool.pytest.ini_options] testpaths = ["src/tests"] +[tool.coverage.run] +source = ["src"] +omit = ["src/tests/*", "*/tests/*", "*/test_*.py"] + +[tool.coverage.report] +exclude_lines = [ + "pragma: no cover", + "def __repr__", + "raise AssertionError", + "raise NotImplementedError", + "if __name__ == .__main__.:", + "if TYPE_CHECKING:", + "@abstractmethod", +] + # Define console scripts entry points [project.scripts] fiona-assistant = "fiona.__main__:main" diff --git a/src/librarian/md_frontmatter.py b/src/librarian/md_frontmatter.py new file mode 100644 index 0000000..f3344c7 --- /dev/null +++ b/src/librarian/md_frontmatter.py @@ -0,0 +1,560 @@ +"""MD Frontmatter module. + +This module handles parsing and managing YAML frontmatter in markdown files +for version control and source tracking. Primary focus is on name and version +fields for source controlling later. + +The module provides functionality to: +- Extract and parse YAML frontmatter from markdown content +- Get and update name and version fields for source control +- Validate required fields in frontmatter +- Handle both content strings and file paths +""" + +from __future__ import annotations + +import pathlib +import re +from typing import Any + +import yaml + + +# ============================================================================= +# Exceptions +# ============================================================================= + +class FrontmatterError(Exception): + """Exception raised for frontmatter parsing errors.""" + pass + + +class RequiredFieldError(Exception): + """Exception raised when required frontmatter fields are missing.""" + pass + + +# ============================================================================= +# Constants +# ============================================================================= + +# Default required fields for wiki pages +DEFAULT_REQUIRED_FIELDS = ["title", "created", "updated", "type"] + +# Pattern to match frontmatter delimiters +# This pattern matches --- at start, then any content (including empty), then --- +# Handles: ---\ncontent\n--- or ---\n--- or ---\n\n--- +FRONTMATTER_PATTERN = re.compile(r'^---\s*\n([\s\S]*?)(?:\n---\s*($|\n)|---\s*($|\n))') + +# Pattern to match a single --- delimiter line +DELIMITER_PATTERN = re.compile(r'^---\s*$', re.MULTILINE) + + +# ============================================================================= +# Helper Functions +# ============================================================================= + +def extract_frontmatter_string(content: str) -> str | None: + """Extract the frontmatter string from markdown content. + + Args: + content: The markdown content to extract frontmatter from. + + Returns: + The YAML frontmatter content between the --- delimiters. + Returns empty string for empty frontmatter, or None if no frontmatter exists. + + Example: + >>> content = "---\ntitle: Test\n---\n# Content" + >>> extract_frontmatter_string(content) + 'title: Test' + """ + if not content or not content.strip(): + return None + + match = FRONTMATTER_PATTERN.search(content) + if match: + frontmatter_str = match.group(1) + # Return empty string if frontmatter is empty (just delimiters) + if frontmatter_str.strip(): + return frontmatter_str + # Check if we matched just empty delimiters + elif frontmatter_str == "": + return "" + + return None + + +def parse_yaml(yaml_str: str) -> dict: + """Parse a YAML string into a dictionary. + + Args: + yaml_str: The YAML string to parse. + + Returns: + Dictionary containing the parsed YAML data. + + Raises: + FrontmatterError: If YAML parsing fails. + """ + try: + # Use safe_load to parse YAML, then convert all values to strings + # to ensure dates and other types are preserved as strings + result = yaml.safe_load(yaml_str) + if result is None: + return {} + + # Convert all values to strings to preserve original format + # But keep booleans and None as-is + def convert_to_strings(obj): + if isinstance(obj, dict): + return {k: convert_to_strings(v) for k, v in obj.items()} + elif isinstance(obj, list): + return [convert_to_strings(item) for item in obj] + elif isinstance(obj, bool): + return obj + elif obj is None: + return None + else: + return str(obj) + + return convert_to_strings(result) + except yaml.YAMLError as e: + raise FrontmatterError(f"Failed to parse YAML: {e}") + + +def parse_frontmatter(content: str | pathlib.Path) -> dict: + """Parse frontmatter from markdown content or file. + + Args: + content: Markdown content string or path to a markdown file. + + Returns: + Dictionary containing the parsed frontmatter data. + Returns empty dict if no frontmatter exists. + + Raises: + FrontmatterError: If YAML parsing fails. + + Example: + >>> content = "---\nname: Test\nversion: 1.0.0\n---\n# Content" + >>> parse_frontmatter(content) + {'name': 'Test', 'version': '1.0.0'} + """ + if isinstance(content, pathlib.Path): + content = content.read_text(encoding='utf-8') + + frontmatter_str = extract_frontmatter_string(content) + if frontmatter_str is None: + return {} + + return parse_yaml(frontmatter_str) + + +def validate_required_fields( + frontmatter: dict, + required_fields: list[str] | None = None +) -> bool: + """Validate that required fields are present in frontmatter. + + Args: + frontmatter: Dictionary containing frontmatter data. + required_fields: List of required field names. If None, uses DEFAULT_REQUIRED_FIELDS. + + Returns: + True if all required fields are present. + + Raises: + RequiredFieldError: If any required fields are missing. + + Example: + >>> frontmatter = {'name': 'Test', 'version': '1.0.0'} + >>> validate_required_fields(frontmatter, required_fields=['name', 'version']) + True + """ + if required_fields is None: + required_fields = DEFAULT_REQUIRED_FIELDS + + missing_fields = [field for field in required_fields if field not in frontmatter] + + if missing_fields: + raise RequiredFieldError( + f"Missing required fields: {', '.join(missing_fields)}" + ) + + return True + + +def extract_content_body(content: str | pathlib.Path) -> str: + """Extract the markdown content body without frontmatter. + + Args: + content: Markdown content string or path to a markdown file. + + Returns: + The content body without frontmatter delimiters. + + Example: + >>> content = "---\ntitle: Test\n---\n# Content" + >>> extract_content_body(content) + '# Content' + """ + if isinstance(content, pathlib.Path): + content = content.read_text(encoding='utf-8') + + match = FRONTMATTER_PATTERN.search(content) + if match: + # Return everything after the closing --- + start_pos = match.end() + return content[start_pos:] + + return content + + +def has_frontmatter(content: str | pathlib.Path) -> bool: + """Check if markdown content has frontmatter. + + Args: + content: Markdown content string or path to a markdown file. + + Returns: + True if frontmatter exists, False otherwise. + """ + if isinstance(content, pathlib.Path): + content = content.read_text(encoding='utf-8') + + return extract_frontmatter_string(content) is not None + + +# ============================================================================= +# Primary Functions (for source control) +# ============================================================================= + +def extract_name_and_version( + content: str | pathlib.Path, + required: bool = True +) -> tuple[str, str]: + """Extract name and version from markdown frontmatter. + + This is the PRIMARY function for source controlling. + + Args: + content: Markdown content string or path to a markdown file. + required: If True, raises RequiredFieldError if name or version is missing. + + Returns: + Tuple of (name, version) strings. + + Raises: + RequiredFieldError: If name or version is missing and required=True. + FrontmatterError: If frontmatter cannot be parsed. + + Example: + >>> content = "---\nname: MyDoc\nversion: 1.0.0\n---\n# Content" + >>> extract_name_and_version(content) + ('MyDoc', '1.0.0') + """ + frontmatter = parse_frontmatter(content) + + if not frontmatter: + if required: + raise RequiredFieldError("No frontmatter found in content") + return (None, None) + + name = frontmatter.get("name") + version = frontmatter.get("version") + + if required: + missing = [] + if name is None: + missing.append("name") + if version is None: + missing.append("version") + + if missing: + raise RequiredFieldError( + f"Missing required fields for source control: {', '.join(missing)}" + ) + + return (name, version) + + +def get_file_version( + content: str | pathlib.Path, + required: bool = True +) -> str: + """Get the version field from markdown frontmatter. + + This is a PRIMARY function for source controlling. + + Args: + content: Markdown content string or path to a markdown file. + required: If True, raises RequiredFieldError if version is missing. + + Returns: + The version string. + + Raises: + RequiredFieldError: If version is missing and required=True. + + Example: + >>> content = "---\nversion: 1.0.0\n---\n# Content" + >>> get_file_version(content) + '1.0.0' + """ + frontmatter = parse_frontmatter(content) + + version = frontmatter.get("version") + + if required and version is None: + raise RequiredFieldError("version field is required for source control") + + return version + + +def _replace_version_in_frontmatter( + frontmatter_str: str, + new_version: str +) -> str: + """Replace version in frontmatter string. + + Args: + frontmatter_str: The YAML frontmatter string. + new_version: The new version string to set. + + Returns: + Updated frontmatter string with new version. + """ + # Parse the YAML + frontmatter_data = parse_yaml(frontmatter_str) + frontmatter_data["version"] = new_version + + # Convert back to YAML string + return yaml.dump(frontmatter_data, default_flow_style=False, sort_keys=False).rstrip() + + +def update_version( + content: str | pathlib.Path, + new_version: str, + in_place: bool = False +) -> str | None: + """Update the version in markdown frontmatter. + + Args: + content: Markdown content string or path to a markdown file. + new_version: The new version string to set. + in_place: If True and content is a Path, updates the file in place. + Returns None in this case. + + Returns: + The updated content string, or None if in_place=True and content is a Path. + + Raises: + FrontmatterError: If frontmatter cannot be parsed or no frontmatter exists. + + Example: + >>> content = "---\nversion: 1.0.0\n---\n# Content" + >>> update_version(content, "2.0.0") + '---\nversion: 2.0.0\n---\n# Content' + """ + is_path = isinstance(content, pathlib.Path) + + if is_path: + content_str = content.read_text(encoding='utf-8') + else: + content_str = content + + # Extract frontmatter + frontmatter_str = extract_frontmatter_string(content_str) + if frontmatter_str is None: + raise FrontmatterError("No frontmatter found to update") + + # Update version in frontmatter + updated_frontmatter = _replace_version_in_frontmatter(frontmatter_str, new_version) + + # Reconstruct full content + match = FRONTMATTER_PATTERN.search(content_str) + if match: + before = content_str[:match.start()] + after = content_str[match.end():] + updated_content = f"{before}---\n{updated_frontmatter}\n---\n{after}" + else: + # This shouldn't happen since we checked for frontmatter, but fallback + updated_content = f"---\n{updated_frontmatter}\n---\n{content_str}" + + if is_path and in_place: + content.write_text(updated_content, encoding='utf-8') + return None + + return updated_content + + +# ============================================================================= +# FrontmatterParser Class +# ============================================================================= + +class FrontmatterParser: + """Main class for parsing and managing markdown frontmatter. + + This class provides a convenient interface for working with frontmatter + in markdown files, with special focus on name and version for source control. + + Example: + >>> parser = FrontmatterParser() + >>> frontmatter = parser.parse_file(pathlib.Path("document.md")) + >>> name, version = parser.get_name_and_version(frontmatter) + >>> parser.update_version("document.md", "2.0.0", in_place=True) + """ + + def __init__(self, required_fields: list[str] | None = None): + """Initialize the parser. + + Args: + required_fields: List of required field names for validation. + If None, uses DEFAULT_REQUIRED_FIELDS. + """ + self.required_fields = required_fields or DEFAULT_REQUIRED_FIELDS + + def parse_content(self, content: str) -> dict: + """Parse frontmatter from content string. + + Args: + content: Markdown content string. + + Returns: + Dictionary containing the parsed frontmatter data. + """ + return parse_frontmatter(content) + + def parse_file(self, filepath: pathlib.Path) -> dict: + """Parse frontmatter from a file. + + Args: + filepath: Path to a markdown file. + + Returns: + Dictionary containing the parsed frontmatter data. + """ + return parse_frontmatter(filepath) + + def validate_file(self, filepath: pathlib.Path) -> bool: + """Validate that a file has required frontmatter fields. + + Args: + filepath: Path to a markdown file. + + Returns: + True if all required fields are present. + + Raises: + RequiredFieldError: If required fields are missing. + """ + frontmatter = self.parse_file(filepath) + return validate_required_fields(frontmatter, self.required_fields) + + def validate_content(self, content: str) -> bool: + """Validate that content has required frontmatter fields. + + Args: + content: Markdown content string. + + Returns: + True if all required fields are present. + + Raises: + RequiredFieldError: If required fields are missing. + """ + frontmatter = self.parse_content(content) + return validate_required_fields(frontmatter, self.required_fields) + + def extract_content_body(self, content: str | pathlib.Path) -> str: + """Extract the content body without frontmatter. + + Args: + content: Markdown content string or path to a markdown file. + + Returns: + The content body without frontmatter. + """ + return extract_content_body(content) + + def has_frontmatter(self, content: str | pathlib.Path) -> bool: + """Check if content has frontmatter. + + Args: + content: Markdown content string or path to a markdown file. + + Returns: + True if frontmatter exists. + """ + return has_frontmatter(content) + + def get_metadata(self, content: str | pathlib.Path) -> dict: + """Extract all frontmatter metadata. + + Args: + content: Markdown content string or path to a markdown file. + + Returns: + Dictionary containing all frontmatter fields. + """ + return parse_frontmatter(content) + + def get_name_and_version( + self, + content: str | pathlib.Path, + required: bool = True + ) -> tuple[str, str]: + """Extract name and version from frontmatter. + + This is a PRIMARY method for source controlling. + + Args: + content: Markdown content string or path to a markdown file. + required: If True, raises error if name or version is missing. + + Returns: + Tuple of (name, version) strings. + + Raises: + RequiredFieldError: If name or version is missing and required=True. + """ + return extract_name_and_version(content, required=required) + + def get_version(self, content: str | pathlib.Path, required: bool = True) -> str: + """Get the version field from frontmatter. + + This is a PRIMARY method for source controlling. + + Args: + content: Markdown content string or path to a markdown file. + required: If True, raises error if version is missing. + + Returns: + The version string. + + Raises: + RequiredFieldError: If version is missing and required=True. + """ + return get_file_version(content, required=required) + + def update_version( + self, + content: str | pathlib.Path, + new_version: str, + in_place: bool = False + ) -> str | None: + """Update the version in frontmatter. + + Args: + content: Markdown content string or path to a markdown file. + new_version: The new version string to set. + in_place: If True and content is a Path, updates file in place. + + Returns: + The updated content string, or None if in_place=True. + + Raises: + FrontmatterError: If frontmatter cannot be parsed or no frontmatter exists. + """ + return update_version(content, new_version, in_place=in_place) diff --git a/src/run_tests.py b/src/run_tests.py index 3981e08..8343065 100644 --- a/src/run_tests.py +++ b/src/run_tests.py @@ -84,7 +84,7 @@ class TestRunner: if verbose: cmd.append("-v") if with_coverage: - cmd.extend(["--cov=src", "--cov-report=term"]) + cmd.extend(["--cov=src", "--cov-config=.coveragerc", "--cov-report=term"]) try: diff --git a/src/tests/__init__.py b/src/tests/__init__.py new file mode 100644 index 0000000..46816dd --- /dev/null +++ b/src/tests/__init__.py @@ -0,0 +1 @@ +"""Tests package.""" diff --git a/src/tests/test_fiona_main.py b/src/tests/test_fiona_main.py index 27b353e..3396310 100644 --- a/src/tests/test_fiona_main.py +++ b/src/tests/test_fiona_main.py @@ -64,4 +64,137 @@ class TestFionaMain: # Help should exit with code 0 assert exc_info.value.code == 0 captured = capsys.readouterr() - assert "usage" in captured.out.lower() \ No newline at end of file + assert "usage" in captured.out.lower() + + def test_main_mdoctor_default(self, capsys): + """Test main() with mdoctor command and default arguments.""" + import os + import tempfile + + with tempfile.TemporaryDirectory() as temp_dir: + original_dir = os.getcwd() + os.chdir(temp_dir) + + # Create a test markdown file + with open("test.md", 'w') as f: + f.write("# Test\n") + + try: + with patch('sys.argv', ['fiona-assistant', 'mdoctor']): + main() + + captured = capsys.readouterr() + # mdoctor chklint should run and output something + assert "PyMarkdownLint" in captured.out or "test.md" in captured.out + finally: + os.chdir(original_dir) + + def test_main_mdoctor_with_args(self, capsys): + """Test main() with mdoctor command and custom args.""" + import os + import tempfile + + with tempfile.TemporaryDirectory() as temp_dir: + original_dir = os.getcwd() + os.chdir(temp_dir) + + # Create a test markdown file + with open("test.md", 'w') as f: + f.write("# Test\n") + + try: + with patch('sys.argv', ['fiona-assistant', 'mdoctor', 'chklint', temp_dir]): + main() + + captured = capsys.readouterr() + assert "test.md" in captured.out or "PyMarkdownLint" in captured.out + finally: + os.chdir(original_dir) + + def test_main_python_ruff_default(self, capsys): + """Test main() with python-ruff command and default arguments.""" + import os + import tempfile + + with tempfile.TemporaryDirectory() as temp_dir: + original_dir = os.getcwd() + os.chdir(temp_dir) + + # Create a test python file + with open("test.py", 'w') as f: + f.write("x = 1\n") + + try: + with patch('sys.argv', ['fiona-assistant', 'python-ruff']): + main() + + captured = capsys.readouterr() + # Should output something about Ruff + assert "Ruff" in captured.out or "test.py" in captured.out + finally: + os.chdir(original_dir) + + def test_main_python_ruff_with_args(self, capsys): + """Test main() with python-ruff command and custom args.""" + import os + import tempfile + + with tempfile.TemporaryDirectory() as temp_dir: + original_dir = os.getcwd() + os.chdir(temp_dir) + + # Create a test python file + with open("test.py", 'w') as f: + f.write("x = 1\n") + + try: + with patch('sys.argv', ['fiona-assistant', 'python-ruff', 'chklint', temp_dir]): + main() + + captured = capsys.readouterr() + assert "Ruff" in captured.out or "test.py" in captured.out + finally: + os.chdir(original_dir) + + def test_main_librarian_with_directory(self, capsys): + """Test main() with librarian command and specific directory.""" + import os + import tempfile + + with tempfile.TemporaryDirectory() as temp_dir: + original_dir = os.getcwd() + + # Create a test file in temp_dir + with open(os.path.join(temp_dir, "test.txt"), 'w') as f: + f.write("content") + + try: + with patch('sys.argv', ['fiona-assistant', 'librarian', temp_dir]): + main() + + captured = capsys.readouterr() + assert "Found 1 files" in captured.out + finally: + os.chdir(original_dir) + + def test_main_test_command(self, capsys): + """Test main() with test command.""" + with patch('sys.argv', ['fiona-assistant', 'test']): + # The test command just prints or does something + # We're testing that it doesn't crash + try: + main() + except SystemExit: + # It's ok if it exits + pass + except Exception as e: + # It should not raise other exceptions + pytest.fail(f"Unexpected exception: {e}") + + def test_main_no_args(self, capsys): + """Test main() with no arguments.""" + with patch('sys.argv', ['fiona-assistant']): + main() + + captured = capsys.readouterr() + assert "Fiona-Assistant: Hello!" in captured.out \ No newline at end of file diff --git a/src/tests/test_generate_toc.py b/src/tests/test_generate_toc.py new file mode 100644 index 0000000..2367a09 --- /dev/null +++ b/src/tests/test_generate_toc.py @@ -0,0 +1,489 @@ +"""Tests for generate_toc module. + +This module tests the table of contents generation functionality +for markdown files. +""" + +import pathlib +import re +import tempfile + +import pytest + +from librarian.generate_toc import ( + TOC_NAME, + build_toc, + collect_md, + excluded, + read_headers, + slugify, + target_folders, +) + + +# ============================================================================= +# Fixtures +# ============================================================================= + +@pytest.fixture +def temp_dir_with_md_files(): + """Create a temporary directory with markdown files.""" + with tempfile.TemporaryDirectory() as tmpdir: + tmpdir = pathlib.Path(tmpdir) + + # Create some markdown files + (tmpdir / "file1.md").write_text("# Header 1\n## Subheader 1\n") + (tmpdir / "file2.md").write_text("# Header 2\n") + + # Create subdirectory with files + subdir = tmpdir / "subdir" + subdir.mkdir() + (subdir / "file3.md").write_text("# Header 3\n## Subheader 3\n") + + yield tmpdir + + +@pytest.fixture +def temp_dir_with_code_fences(): + """Create a temporary directory with markdown files containing code fences.""" + with tempfile.TemporaryDirectory() as tmpdir: + tmpdir = pathlib.Path(tmpdir) + + content = """# Main Header + +```python +def hello(): + pass +``` + +## Code Block Header + +~~~bash +echo "test" +~~~ + +# After Fence Header +""" + (tmpdir / "with_fences.md").write_text(content) + + yield tmpdir + + +@pytest.fixture +def temp_dir_with_hidden_files(): + """Create a temporary directory with hidden markdown files.""" + with tempfile.TemporaryDirectory() as tmpdir: + tmpdir = pathlib.Path(tmpdir) + + (tmpdir / ".hidden.md").write_text("# Hidden Header\n") + (tmpdir / "visible.md").write_text("# Visible Header\n") + + subdir = tmpdir / ".hidden_dir" + subdir.mkdir() + (subdir / "file.md").write_text("# Hidden Dir File\n") + + yield tmpdir + + +# ============================================================================= +# Test: slugify +# ============================================================================= + +class TestSlugify: + """Tests for slugify function.""" + + def test_slugify_simple_text(self): + """Should convert simple text to slug.""" + result = slugify("Hello World") + assert result == "hello-world" + + def test_slugify_with_special_chars(self): + """Should remove special characters.""" + result = slugify("Hello, World!") + assert result == "hello-world" + + def test_slugify_with_underscores(self): + """Should preserve underscores.""" + result = slugify("Hello_World") + assert result == "hello_world" + + def test_slugify_with_hyphens(self): + """Should preserve hyphens.""" + result = slugify("Hello-World") + assert result == "hello-world" + + def test_slugify_multiple_spaces(self): + """Should collapse multiple spaces.""" + result = slugify("Hello World") + assert result == "hello-world" + + def test_slugify_lowercase(self): + """Should convert to lowercase.""" + result = slugify("HELLO WORLD") + assert result == "hello-world" + + def test_slugify_with_numbers(self): + """Should preserve numbers.""" + result = slugify("Chapter 1: Introduction") + assert result == "chapter-1-introduction" + + def test_slugify_empty_string(self): + """Should handle empty string.""" + result = slugify("") + assert result == "" + + def test_slugify_with_hash_symbols(self): + """Should remove hash symbols from header text.""" + result = slugify("Title #1") + assert result == "title-1" + + +# ============================================================================= +# Test: excluded +# ============================================================================= + +class TestExcluded: + """Tests for excluded function.""" + + def test_excluded_no_patterns(self): + """Should return False when no patterns.""" + result = excluded("test.md", []) + assert result is False + + def test_excluded_matching_pattern(self): + """Should return True when pattern matches.""" + patterns = [re.compile(r"test")] + result = excluded("test.md", patterns) + assert result is True + + def test_excluded_non_matching_pattern(self): + """Should return False when pattern doesn't match.""" + patterns = [re.compile(r"other")] + result = excluded("test.md", patterns) + assert result is False + + def test_excluded_multiple_patterns(self): + """Should return True if any pattern matches.""" + patterns = [re.compile(r"foo"), re.compile(r"bar")] + result = excluded("bar.md", patterns) + assert result is True + + +# ============================================================================= +# Test: read_headers +# ============================================================================= + +class TestReadHeaders: + """Tests for read_headers function.""" + + def test_read_headers_basic(self, temp_dir_with_md_files): + """Should read headers from markdown file.""" + filepath = temp_dir_with_md_files / "file1.md" + headers = read_headers(filepath) + + assert len(headers) == 2 + assert headers[0] == (1, "Header 1") + assert headers[1] == (2, "Subheader 1") + + def test_read_headers_with_code_fences(self, temp_dir_with_code_fences): + """Should skip headers inside code fences.""" + filepath = temp_dir_with_code_fences / "with_fences.md" + headers = read_headers(filepath) + + # Should have: Main Header, Code Block Header, After Fence Header + # Should NOT have: def hello() or echo "test" + header_texts = [text for _, text in headers] + + assert "Main Header" in header_texts + assert "Code Block Header" in header_texts + assert "After Fence Header" in header_texts + assert "def hello()" not in header_texts + + def test_read_headers_empty_file(self): + """Should return empty list for file with no headers.""" + with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f: + f.write("No headers here\n") + f.flush() + filepath = pathlib.Path(f.name) + + try: + headers = read_headers(filepath) + assert headers == [] + finally: + filepath.unlink() + + def test_read_headers_various_levels(self): + """Should handle various header levels.""" + with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f: + f.write("# Level 1\n## Level 2\n### Level 3\n#### Level 4\n##### Level 5\n###### Level 6\n") + f.flush() + filepath = pathlib.Path(f.name) + + try: + headers = read_headers(filepath) + assert len(headers) == 6 + for i, (level, _) in enumerate(headers): + assert level == i + 1 + finally: + filepath.unlink() + + +# ============================================================================= +# Test: collect_md +# ============================================================================= + +class TestCollectMd: + """Tests for collect_md function.""" + + def test_collect_md_recursive(self, temp_dir_with_md_files): + """Should collect markdown files recursively.""" + files = collect_md(temp_dir_with_md_files, [], recursive=True) + + assert "file1.md" in files + assert "file2.md" in files + assert "subdir/file3.md" in files + assert len(files) == 3 + + def test_collect_md_non_recursive(self, temp_dir_with_md_files): + """Should collect only top-level markdown files.""" + files = collect_md(temp_dir_with_md_files, [], recursive=False) + + assert "file1.md" in files + assert "file2.md" in files + assert "subdir/file3.md" not in files + assert len(files) == 2 + + def test_collect_md_exclude_toc(self, temp_dir_with_md_files): + """Should exclude table_of_contents.md.""" + # Create a toc file + toc_file = temp_dir_with_md_files / TOC_NAME + toc_file.write_text("# TOC\n") + + files = collect_md(temp_dir_with_md_files, [], recursive=True) + + assert TOC_NAME not in files + + def test_collect_md_exclude_hidden(self, temp_dir_with_hidden_files): + """Should exclude hidden files and directories.""" + files = collect_md(temp_dir_with_hidden_files, [], recursive=True) + + assert ".hidden.md" not in files + assert "visible.md" in files + assert len(files) == 1 + + def test_collect_md_with_exclude_pattern(self, temp_dir_with_md_files): + """Should exclude files matching pattern.""" + patterns = [re.compile(r"file1")] + files = collect_md(temp_dir_with_md_files, patterns, recursive=True) + + assert "file1.md" not in files + assert "file2.md" in files + assert "subdir/file3.md" in files + + def test_collect_md_empty_directory(self): + """Should return empty list for directory with no md files.""" + with tempfile.TemporaryDirectory() as tmpdir: + files = collect_md(pathlib.Path(tmpdir), [], recursive=True) + assert files == [] + + +# ============================================================================= +# Test: build_toc +# ============================================================================= + +class TestBuildToc: + """Tests for build_toc function.""" + + def test_build_toc_single_file(self, temp_dir_with_md_files): + """Should build TOC for single file.""" + folder = temp_dir_with_md_files + files = ["file1.md"] + + result = build_toc(folder, files) + + assert "# Table of Contents" in result + assert "- [file1.md](file1.md)" in result + + def test_build_toc_with_headers(self, temp_dir_with_md_files): + """Should include headers in TOC.""" + folder = temp_dir_with_md_files + files = ["file1.md"] + + result = build_toc(folder, files) + + assert "# Table of Contents" in result + assert "- [file1.md](file1.md)" in result + assert "Header 1" in result + assert "Subheader 1" in result + + def test_build_toc_nested_folders(self, temp_dir_with_md_files): + """Should handle nested folder structure.""" + folder = temp_dir_with_md_files + files = ["file1.md", "subdir/file3.md"] + + result = build_toc(folder, files) + + assert "# Table of Contents" in result + assert "- subdir" in result + assert "- [file3.md](subdir/file3.md)" in result + + def test_build_toc_empty_files(self): + """Should handle empty file list.""" + folder = pathlib.Path("/test") + files = [] + + result = build_toc(folder, files) + + assert result == "# Table of Contents\n\n" + + +# ============================================================================= +# Test: target_folders +# ============================================================================= + +class TestTargetFolders: + """Tests for target_folders function.""" + + def test_target_folders_single(self): + """Should return single folder when not every.""" + root = pathlib.Path("/test") + folders = target_folders(root, [], every=False) + + assert len(folders) == 1 + assert folders[0] == root + + def test_target_folders_every(self): + """Should return all folders when every=True.""" + with tempfile.TemporaryDirectory() as tmpdir: + tmpdir = pathlib.Path(tmpdir) + + # Create nested directories + (tmpdir / "sub1").mkdir() + (tmpdir / "sub1" / "sub2").mkdir() + + folders = target_folders(tmpdir, [], every=True) + + assert len(folders) >= 3 + assert tmpdir in folders + assert (tmpdir / "sub1") in folders + assert (tmpdir / "sub1" / "sub2") in folders + + def test_target_folders_with_exclude_pattern(self): + """Should exclude folders matching pattern.""" + with tempfile.TemporaryDirectory() as tmpdir: + tmpdir = pathlib.Path(tmpdir) + + (tmpdir / "include").mkdir() + (tmpdir / "exclude_me").mkdir() + + patterns = [re.compile(r"exclude")] + folders = target_folders(tmpdir, patterns, every=True) + + folder_names = [f.name for f in folders] + assert "include" in folder_names + assert "exclude_me" not in folder_names + + +# ============================================================================= +# Test: main function (Integration) +# ============================================================================= + +class TestMain: + """Integration tests for main function.""" + + def test_main_default_directory(self, temp_dir_with_md_files, monkeypatch): + """Should generate TOC in default directory.""" + # Change to temp directory + import os + monkeypatch.chdir(temp_dir_with_md_files) + + # Run main with default arguments + from librarian.generate_toc import main + import sys + original_argv = sys.argv + try: + sys.argv = ["generate_toc"] + main() + + # Check that TOC was created + toc_file = temp_dir_with_md_files / TOC_NAME + assert toc_file.exists() + + content = toc_file.read_text() + assert "# Table of Contents" in content + finally: + sys.argv = original_argv + + def test_main_with_directory_arg(self, temp_dir_with_md_files): + """Should generate TOC in specified directory.""" + from librarian.generate_toc import main + import sys + original_argv = sys.argv + + try: + sys.argv = ["generate_toc", str(temp_dir_with_md_files)] + main() + + # Check that TOC was created + toc_file = temp_dir_with_md_files / TOC_NAME + assert toc_file.exists() + finally: + sys.argv = original_argv + + def test_main_recursive_toc(self, temp_dir_with_md_files): + """Should generate TOC in every subfolder with -r flag.""" + from librarian.generate_toc import main + import sys + original_argv = sys.argv + + try: + sys.argv = ["generate_toc", str(temp_dir_with_md_files), "-r"] + main() + + # Check TOC in main directory + assert (temp_dir_with_md_files / TOC_NAME).exists() + + # Check TOC in subdirectory + subdir = temp_dir_with_md_files / "subdir" + assert (subdir / TOC_NAME).exists() + finally: + sys.argv = original_argv + + def test_main_non_recursive(self, temp_dir_with_md_files): + """Should not include subdirectories with -n flag.""" + from librarian.generate_toc import main + import sys + original_argv = sys.argv + + try: + sys.argv = ["generate_toc", str(temp_dir_with_md_files), "-n"] + main() + + # Check TOC in main directory + assert (temp_dir_with_md_files / TOC_NAME).exists() + + # Check NO TOC in subdirectory + subdir = temp_dir_with_md_files / "subdir" + assert not (subdir / TOC_NAME).exists() + finally: + sys.argv = original_argv + + def test_main_with_exclude(self, temp_dir_with_md_files): + """Should exclude files matching pattern.""" + from librarian.generate_toc import main + import sys + original_argv = sys.argv + + try: + sys.argv = ["generate_toc", str(temp_dir_with_md_files), "-e", "file1"] + main() + + toc_file = temp_dir_with_md_files / TOC_NAME + content = toc_file.read_text() + + # file1.md should not be in TOC + assert "file1.md" not in content + # file2.md should be in TOC + assert "file2.md" in content + finally: + sys.argv = original_argv diff --git a/src/tests/test_md_frontmatter.py b/src/tests/test_md_frontmatter.py new file mode 100644 index 0000000..e2a698f --- /dev/null +++ b/src/tests/test_md_frontmatter.py @@ -0,0 +1,574 @@ +"""Tests for MD Frontmatter module. + +This module handles parsing and managing YAML frontmatter in markdown files +for version control and source tracking. Primary focus is on name and version +fields for source controlling later. +""" + +import pathlib +import tempfile + +import pytest + +from librarian.md_frontmatter import ( + FrontmatterError, + FrontmatterParser, + RequiredFieldError, + extract_frontmatter_string, + extract_name_and_version, + get_file_version, + parse_frontmatter, + update_version, + validate_required_fields, +) + + +# ============================================================================= +# Fixtures +# ============================================================================= + +@pytest.fixture +def valid_frontmatter_content(): + """Sample markdown content with valid frontmatter including name and version.""" + return """--- +name: Test Document +version: 1.0.0 +title: Test Page +created: 2025-09-20 +updated: 2025-09-21 +type: concept +sources: [raw/articles/test.md] +tags: [test, example] +--- + +# Page Content +This is the page content. +""" + + +@pytest.fixture +def minimal_frontmatter_content(): + """Sample markdown content with minimal required frontmatter including name and version.""" + return """--- +name: Minimal Document +version: 0.1.0 +title: Minimal Page +created: 2025-09-20 +updated: 2025-09-20 +type: concept +--- + +# Content here +""" + + +@pytest.fixture +def frontmatter_without_name(): + """Sample markdown content missing name field.""" + return """--- +version: 1.0.0 +title: Nameless Page +created: 2025-09-20 +updated: 2025-09-20 +type: concept +--- + +# Content here +""" + + +@pytest.fixture +def frontmatter_without_version(): + """Sample markdown content missing version field.""" + return """--- +name: Versionless Document +title: Versionless Page +created: 2025-09-20 +updated: 2025-09-20 +type: concept +--- + +# Content here +""" + + +@pytest.fixture +def missing_required_frontmatter_content(): + """Sample markdown content missing required fields.""" + return """--- +title: Incomplete Page +created: 2025-09-20 +--- + +# Content here +""" + + +@pytest.fixture +def no_frontmatter_content(): + """Sample markdown content without frontmatter.""" + return """# Page Title + +This is content without frontmatter. +""" + + +@pytest.fixture +def invalid_yaml_frontmatter_content(): + """Sample markdown content with invalid YAML in frontmatter.""" + return """--- +name: Invalid Page +version: 1.0.0 +invalid_yaml: [unclosed bracket +type: concept +--- + +# Content here +""" + + +@pytest.fixture +def frontmatter_with_optional_fields(): + """Sample markdown content with optional quality signal fields.""" + return """--- +name: Quality Document +version: 2.0.0-beta +title: Quality Page +created: 2025-09-20 +updated: 2025-09-21 +type: concept +confidence: high +contested: false +contradictions: [other-page] +sources: [raw/articles/test.md] +tags: [test] +--- + +# Content +""" + + +@pytest.fixture +def temp_md_file(valid_frontmatter_content): + """Create a temporary markdown file with frontmatter.""" + with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f: + f.write(valid_frontmatter_content) + f.flush() + yield pathlib.Path(f.name) + pathlib.Path(f.name).unlink(missing_ok=True) + + +# ============================================================================= +# Test: extract_frontmatter_string +# ============================================================================= + +class TestExtractFrontmatterString: + """Tests for extract_frontmatter_string function.""" + + def test_extract_valid_frontmatter(self, valid_frontmatter_content): + """Should extract frontmatter string (YAML content only) from content with frontmatter.""" + result = extract_frontmatter_string(valid_frontmatter_content) + + assert "name: Test Document" in result + assert "version: 1.0.0" in result + assert "created: 2025-09-20" in result + assert "---" not in result # Should not include delimiters + assert "# Page Content" not in result + + def test_extract_minimal_frontmatter(self, minimal_frontmatter_content): + """Should extract minimal frontmatter.""" + result = extract_frontmatter_string(minimal_frontmatter_content) + + assert "name: Minimal Document" in result + assert "version: 0.1.0" in result + assert "# Content here" not in result + + def test_extract_no_frontmatter_returns_none(self, no_frontmatter_content): + """Should return None when no frontmatter exists.""" + result = extract_frontmatter_string(no_frontmatter_content) + assert result is None + + def test_extract_empty_content_returns_none(self): + """Should return None for empty content.""" + result = extract_frontmatter_string("") + assert result is None + + def test_extract_content_with_only_delimiters(self): + """Should return empty string for content with only --- delimiters.""" + content = "---\n---\n" + result = extract_frontmatter_string(content) + assert result == "" + + +# ============================================================================= +# Test: parse_frontmatter +# ============================================================================= + +class TestParseFrontmatter: + """Tests for parse_frontmatter function.""" + + def test_parse_valid_frontmatter(self, valid_frontmatter_content): + """Should parse valid frontmatter into dictionary.""" + result = parse_frontmatter(valid_frontmatter_content) + + assert isinstance(result, dict) + assert result["name"] == "Test Document" + assert result["version"] == "1.0.0" + assert result["title"] == "Test Page" + assert result["created"] == "2025-09-20" + assert result["updated"] == "2025-09-21" + assert result["type"] == "concept" + assert result["sources"] == ["raw/articles/test.md"] + assert result["tags"] == ["test", "example"] + + def test_parse_minimal_frontmatter(self, minimal_frontmatter_content): + """Should parse minimal frontmatter.""" + result = parse_frontmatter(minimal_frontmatter_content) + + assert result["name"] == "Minimal Document" + assert result["version"] == "0.1.0" + assert result["title"] == "Minimal Page" + + def test_parse_no_frontmatter_returns_empty_dict(self, no_frontmatter_content): + """Should return empty dict when no frontmatter exists.""" + result = parse_frontmatter(no_frontmatter_content) + assert result == {} + + def test_parse_invalid_yaml_raises_error(self, invalid_yaml_frontmatter_content): + """Should raise FrontmatterError for invalid YAML.""" + with pytest.raises(FrontmatterError) as exc_info: + parse_frontmatter(invalid_yaml_frontmatter_content) + + assert "Failed to parse YAML" in str(exc_info.value) + + def test_parse_frontmatter_with_optional_fields(self, frontmatter_with_optional_fields): + """Should parse optional fields correctly.""" + result = parse_frontmatter(frontmatter_with_optional_fields) + + assert result["name"] == "Quality Document" + assert result["version"] == "2.0.0-beta" + assert result["confidence"] == "high" + assert result["contested"] is False + + +# ============================================================================= +# Test: extract_name_and_version (PRIMARY FEATURE) +# ============================================================================= + +class TestExtractNameAndVersion: + """Tests for extract_name_and_version function - PRIMARY for source control.""" + + def test_extract_name_and_version_from_valid(self, valid_frontmatter_content): + """Should extract name and version from valid frontmatter.""" + name, version = extract_name_and_version(valid_frontmatter_content) + + assert name == "Test Document" + assert version == "1.0.0" + + def test_extract_name_and_version_from_minimal(self, minimal_frontmatter_content): + """Should extract name and version from minimal frontmatter.""" + name, version = extract_name_and_version(minimal_frontmatter_content) + + assert name == "Minimal Document" + assert version == "0.1.0" + + def test_extract_name_and_version_from_optional_fields(self, frontmatter_with_optional_fields): + """Should extract name and version with pre-release version.""" + name, version = extract_name_and_version(frontmatter_with_optional_fields) + + assert name == "Quality Document" + assert version == "2.0.0-beta" + + def test_extract_name_and_version_missing_name(self, frontmatter_without_name): + """Should raise error when name is missing.""" + with pytest.raises(RequiredFieldError) as exc_info: + extract_name_and_version(frontmatter_without_name) + + assert "name" in str(exc_info.value).lower() + + def test_extract_name_and_version_missing_version(self, frontmatter_without_version): + """Should raise error when version is missing.""" + with pytest.raises(RequiredFieldError) as exc_info: + extract_name_and_version(frontmatter_without_version) + + assert "version" in str(exc_info.value).lower() + + def test_extract_name_and_version_no_frontmatter(self, no_frontmatter_content): + """Should raise error when no frontmatter exists.""" + with pytest.raises(RequiredFieldError): + extract_name_and_version(no_frontmatter_content) + + def test_extract_name_and_version_from_file(self, temp_md_file): + """Should extract name and version from file path.""" + name, version = extract_name_and_version(temp_md_file) + + assert name == "Test Document" + assert version == "1.0.0" + + +# ============================================================================= +# Test: get_file_version (PRIMARY FEATURE) +# ============================================================================= + +class TestGetFileVersion: + """Tests for get_file_version function - PRIMARY for source control.""" + + def test_get_file_version_from_content(self, valid_frontmatter_content): + """Should get version from content.""" + version = get_file_version(valid_frontmatter_content) + assert version == "1.0.0" + + def test_get_file_version_from_file(self, temp_md_file): + """Should get version from file path.""" + version = get_file_version(temp_md_file) + assert version == "1.0.0" + + def test_get_file_version_missing_version(self, frontmatter_without_version): + """Should raise error when version is missing.""" + with pytest.raises(RequiredFieldError) as exc_info: + get_file_version(frontmatter_without_version) + + assert "version" in str(exc_info.value).lower() + + def test_get_file_version_no_frontmatter(self, no_frontmatter_content): + """Should raise error when no frontmatter exists.""" + with pytest.raises(RequiredFieldError): + get_file_version(no_frontmatter_content) + + +# ============================================================================= +# Test: update_version +# ============================================================================= + +class TestUpdateVersion: + """Tests for update_version function.""" + + def test_update_version_in_content(self, valid_frontmatter_content): + """Should update version in content and return new content.""" + new_content = update_version(valid_frontmatter_content, "2.0.0") + + frontmatter = parse_frontmatter(new_content) + assert frontmatter["version"] == "2.0.0" + assert frontmatter["name"] == "Test Document" + assert "# Page Content" in new_content + + def test_update_version_preserves_content(self, valid_frontmatter_content): + """Should preserve all content except version.""" + new_content = update_version(valid_frontmatter_content, "99.99.99") + + assert "# Page Content" in new_content + assert "This is the page content." in new_content + assert "title: Test Page" in new_content + + def test_update_version_in_file(self, temp_md_file): + """Should update version in file.""" + update_version(temp_md_file, "3.0.0", in_place=True) + + frontmatter = parse_frontmatter(temp_md_file) + assert frontmatter["version"] == "3.0.0" + + def test_update_version_no_frontmatter_raises_error(self, no_frontmatter_content): + """Should raise error when trying to update version on content without frontmatter.""" + with pytest.raises(FrontmatterError): + update_version(no_frontmatter_content, "1.0.0") + + +# ============================================================================= +# Test: validate_required_fields +# ============================================================================= + +class TestValidateRequiredFields: + """Tests for validate_required_fields function.""" + + def test_validate_all_required_fields_present(self, valid_frontmatter_content): + """Should pass when all required fields are present.""" + frontmatter = parse_frontmatter(valid_frontmatter_content) + result = validate_required_fields(frontmatter) + assert result is True + + def test_validate_missing_required_field_raises_error(self, missing_required_frontmatter_content): + """Should raise RequiredFieldError when required fields are missing.""" + frontmatter = parse_frontmatter(missing_required_frontmatter_content) + + with pytest.raises(RequiredFieldError) as exc_info: + validate_required_fields(frontmatter) + + assert "Missing required fields" in str(exc_info.value) + assert "updated" in str(exc_info.value) + assert "type" in str(exc_info.value) + + def test_validate_empty_frontmatter_missing_all(self): + """Should report all missing fields for empty frontmatter.""" + frontmatter = {} + + with pytest.raises(RequiredFieldError) as exc_info: + validate_required_fields(frontmatter) + + error_msg = str(exc_info.value) + assert "title" in error_msg + assert "created" in error_msg + assert "updated" in error_msg + assert "type" in error_msg + + def test_validate_with_custom_required_fields(self, valid_frontmatter_content): + """Should allow custom required field list.""" + frontmatter = parse_frontmatter(valid_frontmatter_content) + result = validate_required_fields(frontmatter, required_fields=["name", "version"]) + assert result is True + + +# ============================================================================= +# Test: FrontmatterParser class +# ============================================================================= + +class TestFrontmatterParser: + """Tests for FrontmatterParser class.""" + + def test_parse_file(self, temp_md_file): + """Should parse frontmatter from a file path.""" + parser = FrontmatterParser() + result = parser.parse_file(temp_md_file) + + assert result["name"] == "Test Document" + assert result["version"] == "1.0.0" + assert result["title"] == "Test Page" + assert result["type"] == "concept" + + def test_parse_content(self, valid_frontmatter_content): + """Should parse frontmatter from content string.""" + parser = FrontmatterParser() + result = parser.parse_content(valid_frontmatter_content) + + assert result["name"] == "Test Document" + assert result["version"] == "1.0.0" + + def test_validate_file(self, temp_md_file): + """Should validate frontmatter in a file.""" + parser = FrontmatterParser() + result = parser.validate_file(temp_md_file) + assert result is True + + def test_validate_file_missing_fields(self, temp_md_file, missing_required_frontmatter_content): + """Should raise error when validating file with missing fields.""" + with temp_md_file.open('w') as f: + f.write(missing_required_frontmatter_content) + + parser = FrontmatterParser() + + with pytest.raises(RequiredFieldError): + parser.validate_file(temp_md_file) + + def test_extract_content_body(self, valid_frontmatter_content): + """Should extract content body without frontmatter.""" + parser = FrontmatterParser() + body = parser.extract_content_body(valid_frontmatter_content) + + assert "# Page Content" in body + assert "---" not in body + assert "name: Test Document" not in body + + def test_extract_content_body_no_frontmatter(self, no_frontmatter_content): + """Should return full content when no frontmatter exists.""" + parser = FrontmatterParser() + body = parser.extract_content_body(no_frontmatter_content) + assert body == no_frontmatter_content + + def test_get_metadata(self, valid_frontmatter_content): + """Should extract version control metadata.""" + parser = FrontmatterParser() + metadata = parser.get_metadata(valid_frontmatter_content) + + assert "name" in metadata + assert "version" in metadata + assert "title" in metadata + assert "created" in metadata + assert "updated" in metadata + assert "type" in metadata + + def test_has_frontmatter_true(self, valid_frontmatter_content): + """Should return True for content with frontmatter.""" + parser = FrontmatterParser() + assert parser.has_frontmatter(valid_frontmatter_content) is True + + def test_has_frontmatter_false(self, no_frontmatter_content): + """Should return False for content without frontmatter.""" + parser = FrontmatterParser() + assert parser.has_frontmatter(no_frontmatter_content) is False + + def test_get_name_and_version(self, valid_frontmatter_content): + """Should extract name and version from content.""" + parser = FrontmatterParser() + name, version = parser.get_name_and_version(valid_frontmatter_content) + + assert name == "Test Document" + assert version == "1.0.0" + + def test_get_version(self, valid_frontmatter_content): + """Should extract version from content.""" + parser = FrontmatterParser() + version = parser.get_version(valid_frontmatter_content) + + assert version == "1.0.0" + + def test_update_version(self, valid_frontmatter_content): + """Should update version in content.""" + parser = FrontmatterParser() + new_content = parser.update_version(valid_frontmatter_content, "5.0.0") + + frontmatter = parse_frontmatter(new_content) + assert frontmatter["version"] == "5.0.0" + + +# ============================================================================= +# Integration Tests +# ============================================================================= + +class TestIntegration: + """Integration tests for frontmatter handling with focus on name and version.""" + + def test_full_workflow(self, valid_frontmatter_content): + """Test complete workflow: extract, parse, validate.""" + frontmatter_str = extract_frontmatter_string(valid_frontmatter_content) + assert frontmatter_str is not None + + frontmatter = parse_frontmatter(valid_frontmatter_content) + assert isinstance(frontmatter, dict) + + assert validate_required_fields(frontmatter) is True + + name, version = extract_name_and_version(valid_frontmatter_content) + assert name == "Test Document" + assert version == "1.0.0" + + def test_parser_class_full_workflow(self, temp_md_file): + """Test FrontmatterParser end-to-end with name/version focus.""" + parser = FrontmatterParser() + + frontmatter = parser.parse_file(temp_md_file) + assert frontmatter["name"] == "Test Document" + assert frontmatter["version"] == "1.0.0" + + assert parser.validate_file(temp_md_file) is True + + body = parser.extract_content_body(temp_md_file.read_text()) + assert "# Page Content" in body + + name, version = parser.get_name_and_version(temp_md_file) + assert name == "Test Document" + assert version == "1.0.0" + + def test_version_tracking_workflow(self, temp_md_file): + """Test version tracking workflow - PRIMARY use case.""" + parser = FrontmatterParser() + + current_version = parser.get_version(temp_md_file) + assert current_version == "1.0.0" + + parser.update_version(temp_md_file, "2.0.0", in_place=True) + + new_version = parser.get_version(temp_md_file) + assert new_version == "2.0.0" + + name, version = parser.get_name_and_version(temp_md_file) + assert name == "Test Document" + assert version == "2.0.0" diff --git a/src/tests/test_mdoctor.py b/src/tests/test_mdoctor.py index 29bb6a1..ca9e7fd 100644 --- a/src/tests/test_mdoctor.py +++ b/src/tests/test_mdoctor.py @@ -1,6 +1,7 @@ """Tests for the MDoctor tool.""" import os +import pathlib import tempfile from unittest.mock import patch @@ -83,3 +84,185 @@ class TestMDoctorMain: assert exc_info.value.code == 1 captured = capsys.readouterr() assert "not a valid directory" in captured.err + + def test_main_list_valid_directory(self, capsys): + """Test main() with list subcommand and valid directory.""" + import tempfile + import os + + with tempfile.TemporaryDirectory() as temp_dir: + # Create a test file + test_file = os.path.join(temp_dir, "test.txt") + with open(test_file, 'w') as f: + f.write("test content") + + with patch('sys.argv', ['mdoctor', 'list', temp_dir]): + main() + + captured = capsys.readouterr() + assert "Found" in captured.out + assert "files" in captured.out + + def test_main_chklint_valid_directory(self, capsys): + """Test main() with chklint subcommand and valid directory.""" + import tempfile + import os + + with tempfile.TemporaryDirectory() as temp_dir: + # Create a test markdown file with valid content + test_file = os.path.join(temp_dir, "test.md") + with open(test_file, 'w') as f: + f.write("# Test Header\n\nContent here\n") + + with patch('sys.argv', ['mdoctor', 'chklint', temp_dir]): + main() + + captured = capsys.readouterr() + # Should output the violations report + assert "PyMarkdownLint Violations" in captured.out or "TARGET" in captured.out + + def test_main_chklint_with_violations(self, capsys): + """Test main() with chklint on file that has violations.""" + import tempfile + import os + + with tempfile.TemporaryDirectory() as temp_dir: + # Create a test markdown file with violation (no blank line around header) + test_file = os.path.join(temp_dir, "test.md") + with open(test_file, 'w') as f: + f.write("#Header without space\nContent here\n") + + with patch('sys.argv', ['mdoctor', 'chklint', temp_dir]): + main() + + captured = capsys.readouterr() + # Should detect violations + assert "Violation" in captured.out or "MD022" in captured.out or "errors" in captured.out.lower() + + def test_main_default_no_args(self, capsys): + """Test main() with no arguments defaults to chklint.""" + import tempfile + import os + + with tempfile.TemporaryDirectory() as temp_dir: + # Create a test markdown file + test_file = os.path.join(temp_dir, "test.md") + with open(test_file, 'w') as f: + f.write("# Test\n") + + # Change to temp directory + original_dir = os.getcwd() + os.chdir(temp_dir) + + try: + with patch('sys.argv', ['mdoctor']): + main() + + captured = capsys.readouterr() + assert "PyMarkdownLint" in captured.out or "TARGET" in captured.out + finally: + os.chdir(original_dir) + + +class TestMDoctorMethods: + """Tests for MDoctor class methods.""" + + def test_list_all_md_files(self, mdoctor): + """Test list_all_md_files method.""" + import tempfile + import os + + with tempfile.TemporaryDirectory() as temp_dir: + # Create some markdown files + for i in range(3): + with open(os.path.join(temp_dir, f"file{i}.md"), 'w') as f: + f.write(f"# File {i}") + + files = mdoctor.list_all_md_files(temp_dir) + + assert len(files) == 3 + # Check that all files are present (as Path objects) + file_names = [pathlib.Path(f).name for f in files] + assert all(f"file{i}.md" in file_names for i in range(3)) + + def test_scan_file_programmatically(self, mdoctor): + """Test scan_file_programmatically method.""" + import tempfile + import os + + with tempfile.TemporaryDirectory() as temp_dir: + # Create a markdown file + test_file = os.path.join(temp_dir, "test.md") + with open(test_file, 'w') as f: + f.write("# Test\n") + + violations = mdoctor.scan_file_programmatically(test_file) + + # Should return a list of violations (may be empty for valid file) + assert isinstance(violations, list) + + def test_check_markdown_lint(self, mdoctor): + """Test check_markdown_lint method.""" + import tempfile + import os + + with tempfile.TemporaryDirectory() as temp_dir: + # Create a markdown file + test_file = os.path.join(temp_dir, "test.md") + with open(test_file, 'w') as f: + f.write("# Test\n") + + result = mdoctor.check_markdown_lint(temp_dir) + + # Should return a string with the formatted violations + assert isinstance(result, str) + + def test_format_violations_empty(self, mdoctor): + """Test format_violations with empty violations.""" + result = mdoctor.format_violations({ + "files": {}, + "descriptions": {}, + "meta": {"file_count": 0, "total_violations": 0} + }) + + assert "DEFINITIONS:" in result + assert "SUMMARY:" in result + assert "Total files with violations: 0" in result + + def test_compress_violations_with_extra(self, mdoctor): + """Test compress_violations with extra info.""" + violations = [ + { + 'scan_file': 'file1.md', + 'line': 1, + 'column': 1, + 'rule_id': 'MD100', + 'rule_name': 'test_rule', + 'description': 'test description', + 'extra': 'extra info' + } + ] + + result = mdoctor.compress_violations(violations, put_extra=True) + + assert "file1.md" in result["files"] + assert "extra info" in result["files"]["file1.md"][0] + + def test_compress_violations_without_extra(self, mdoctor): + """Test compress_violations without extra info.""" + violations = [ + { + 'scan_file': 'file1.md', + 'line': 1, + 'column': 1, + 'rule_id': 'MD100', + 'rule_name': 'test_rule', + 'description': 'test description', + 'extra': 'extra info' + } + ] + + result = mdoctor.compress_violations(violations, put_extra=False) + + assert "file1.md" in result["files"] + assert "extra info" not in result["files"]["file1.md"][0] diff --git a/src/tests/test_python_ruff.py b/src/tests/test_python_ruff.py index aa971a2..d32a734 100644 --- a/src/tests/test_python_ruff.py +++ b/src/tests/test_python_ruff.py @@ -1,17 +1,30 @@ +"""Tests for Python Ruff module.""" +import os +import pathlib +import tempfile +from unittest.mock import patch +import pytest + +from python_ruff.python_ruff import PythonRuff class TestPythonRuff: + """Tests for PythonRuff class.""" + + @pytest.fixture + def pyruff(self): + """Fixture that provides a PythonRuff instance.""" + return PythonRuff() + def test_lint_detects_unused_import(self, pyruff, tmp_path): - # Arrange: Create a temporary python file with a known Ruff violation (F401) + """Test lint detects unused import.""" test_file = tmp_path / "bad_code.py" test_file.write_text("import sys\n\ndef hello():\n print('world')\n") - # Act violations = pyruff.lint(str(test_file)) - # Assert assert len(violations) > 0 first_violation = violations[0] @@ -19,14 +32,141 @@ class TestPythonRuff: assert "Import block is un-sorted or un-formatted" in first_violation["message"] assert first_violation["location"]["row"] == 1 + def test_lint_clean_file(self, pyruff, tmp_path): + """Test lint returns list for clean file.""" + clean_file = tmp_path / "clean_code.py" + clean_file.write_text("def hello():\n print('world')\n") - #def test_lint_with_ruff_json_clean_file(tmp_path): - # # Arrange: Create a valid Python file without violations - # clean_file = tmp_path / "clean_code.py" - # clean_file.write_text("def hello():\n print('world')\n") + violations = pyruff.lint(str(clean_file)) + + assert isinstance(violations, list) - # # Act - # violations = lint_with_ruff_json(str(clean_file)) + def test_lint_with_fix(self, pyruff, tmp_path): + """Test lint with fix option.""" + test_file = tmp_path / "test.py" + test_file.write_text("import os\nimport sys\n\ndef hello():\n print('world')\n") - # # Assert - # assert violations == [] \ No newline at end of file + violations = pyruff.lint(str(test_file), fix=False) + + assert isinstance(violations, list) + + def test_compress_violations(self, pyruff): + """Test compress_violations method.""" + violations = [ + { + "filename": "/path/to/file.py", + "location": {"row": 1, "column": 10}, + "code": "F401", + "message": "`os` imported but unused" + }, + { + "filename": "/path/to/file.py", + "location": {"row": 2, "column": 15}, + "code": "F401", + "message": "`sys` imported but unused" + } + ] + + target = pathlib.Path("/path/to") + result = pyruff.compress_violations(violations, target) + + assert isinstance(result, dict) + assert "file.py" in result + assert len(result["file.py"]) == 2 + + def test_compress_violations_with_string(self, pyruff): + """Test compress_violations with string input.""" + violations_json = '[{"filename": "/path/to/file.py", "location": {"row": 1, "column": 10}, "code": "F401", "message": "test"}]' + + target = pathlib.Path("/path/to") + result = pyruff.compress_violations(violations_json, target) + + assert isinstance(result, dict) + assert "file.py" in result + + def test_format_violations(self, pyruff): + """Test format_violations method.""" + compressed = { + "file.py": [ + {"line": 1, "column": 10, "code": "F401", "message": "unused import"} + ] + } + + result = pyruff.format_violations(compressed, target_path="/path/to") + + assert isinstance(result, str) + assert "Ruff Violations" in result + assert "F401" in result + assert "unused import" in result + assert "SUMMARY:" in result + + def test_format_violations_empty(self, pyruff): + """Test format_violations with empty input.""" + result = pyruff.format_violations({}, target_path="/path/to") + + assert "Ruff Violations" in result + assert "No violations found" in result + + def test_check_ruff(self, pyruff, tmp_path): + """Test check_ruff method.""" + test_file = tmp_path / "test.py" + test_file.write_text("def hello():\n print('world')\n") + + result = pyruff.check_ruff(str(tmp_path)) + + assert isinstance(result, str) + assert "Ruff Violations" in result + + def test_check_ruff_with_violations(self, pyruff, tmp_path): + """Test check_ruff with file that has violations.""" + test_file = tmp_path / "test.py" + test_file.write_text("import os\nimport sys\n\ndef hello():\n print('world')\n") + + result = pyruff.check_ruff(str(tmp_path)) + + assert isinstance(result, str) + assert "Ruff Violations" in result or "F401" in result or "I001" in result + + +class TestPythonRuffMain: + """Tests for python_ruff.main() function.""" + + def test_main_default(self, capsys): + """Test main() with default arguments.""" + from python_ruff.python_ruff import main + + with tempfile.TemporaryDirectory() as temp_dir: + test_file = os.path.join(temp_dir, "test.py") + with open(test_file, 'w') as f: + f.write("def hello():\n print('world')\n") + + with patch('sys.argv', ['python-ruff']): + main() + + captured = capsys.readouterr() + assert "Ruff Violations" in captured.out + + def test_main_with_directory(self, capsys): + """Test main() with directory argument.""" + from python_ruff.python_ruff import main + + with tempfile.TemporaryDirectory() as temp_dir: + test_file = os.path.join(temp_dir, "test.py") + with open(test_file, 'w') as f: + f.write("def hello():\n print('world')\n") + + with patch('sys.argv', ['python-ruff', 'chklint', temp_dir]): + main() + + captured = capsys.readouterr() + assert "Ruff Violations" in captured.out + + def test_main_invalid_directory(self, capsys): + """Test main() with invalid directory.""" + from python_ruff.python_ruff import main + + with patch('sys.argv', ['python-ruff', 'chklint', '/nonexistent/directory']): + main() + + captured = capsys.readouterr() + assert captured.out is not None or captured.err is not None