major refactor

This commit is contained in:
nvaldez
2026-09-23 11:38:16 +02:00
parent f1e52b648e
commit 8eb3a8fd0c
12 changed files with 2782 additions and 35 deletions
+16
View File
@@ -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
+351
View File
@@ -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 <env_name> --python <version>
# With cleanup flag
source bootstrap --env <env_name> -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 <env_name>
```
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`
---
+305 -21
View File
@@ -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 <repository-url>
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 <directory>
# Manage wiki content with Librarian
fiona-assistant librarian [directory]
# List files with mdoctor
fiona-assistant mdoctor <directory>
# 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 <command>` or `python -m fiona <command>`
### Direct Tool Access
Each tool can also be called directly:
To see all available commands:
```bash
fiona-assistant --help
```
# 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.
+17 -1
View File
@@ -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"
+560
View File
@@ -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)
+1 -1
View File
@@ -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:
+1
View File
@@ -0,0 +1 @@
"""Tests package."""
+134 -1
View File
@@ -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()
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
+489
View File
@@ -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
+574
View File
@@ -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"
+183
View File
@@ -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]
+151 -11
View File
@@ -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 == []
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