major refactor
This commit is contained in:
+16
@@ -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
|
||||
@@ -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`
|
||||
|
||||
---
|
||||
@@ -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
@@ -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"
|
||||
|
||||
@@ -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
@@ -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:
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
"""Tests package."""
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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"
|
||||
@@ -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
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user