coulomb/markitect-main
2
0
Fork 0
Code Issues 60 Pull Requests Actions 1 Projects 12 Releases 1 Wiki Activity

feat: Complete Issue #74 - Create missing baseline documentation files

Browse Source 
Add essential baseline documentation following DRY principles:

📄 Files Created:
• LICENSE.md - MIT License with clear usage guidelines
• TESTING.md - Comprehensive testing guide and best practices
• CONCEPT.md - Core concepts, terminology, and architectural principles

🎯 Documentation Foundation:
• Establishes proper documentation baseline
• Follows consistent markdown formatting
• Reduces DRY violations through organized content
• Provides clear project concepts and testing procedures

✅ Acceptance Criteria Met:
• All three baseline files created with appropriate content
• Files follow consistent formatting and structure
• Content avoids duplication with existing documentation
• Ready for integration with organized docs structure

Part of Issue #49 documentation organization initiative.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2025-10-02 22:16:54 +02:00
parent dbe8ba0da5
commit bddebbe005
3 changed files with 612 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

239
CONCEPT.md Normal file
View File

@@ -0,0 +1,239 @@
# MarkiTect Concepts and Terminology
This document defines the core concepts, terminology, and architectural principles that drive the MarkiTect project.
## Project Vision
**"Your Markdown, Redefined"**
MarkiTect transforms markdown from plain text into intelligent, structured data with performance optimization, schema validation, and relational querying capabilities. Stop treating documentation as text files—start managing it as a database.
## Core Concepts
### Document Processing Philosophy
#### Intelligent Document Management
- **AST-First Processing**: Every document is parsed into an Abstract Syntax Tree for structured manipulation
- **Database-Driven Storage**: Documents are stored with relational metadata, not just as flat files
- **Performance-Optimized**: Intelligent caching reduces processing time by 60-85%
#### Schema-Driven Development
- **Document Schemas**: Define and enforce document structure and consistency
- **Template Systems**: Generate documents from templates with variable substitution
- **Validation Framework**: Ensure content meets predefined standards
### Key Terminology
#### Core Components
**MarkiTect Engine**
: The central processing system that parses, validates, and transforms markdown documents
**AST (Abstract Syntax Tree)**
: Structured representation of a markdown document's content and formatting
**Document Schema**
: JSON-based definition of document structure, frontmatter requirements, and content rules
**Template Engine**
: System for generating documents from templates with variable substitution (`{{variable}}` syntax)
**Performance Index**
: Weighted 0-100 scale measuring system performance across template, database, and ingestion operations
#### Data Structures
**Frontmatter**
: YAML/TOML metadata at the beginning of markdown documents containing structured information
**Contentmatter**
: Key-value pairs embedded within document content using MultiMarkdown syntax
**Tailmatter**
: QA checklists and editorial metadata at the end of documents for quality management
**Document Metadata**
: Relational data extracted from documents and stored in the database for querying
#### Processing Concepts
**Zero-Parsing Access**
: Ability to query document metadata without re-parsing the entire document
**Intelligent Caching**
: AST caching system that dramatically improves performance on subsequent document operations
**Relational Document Metadata**
: Document properties stored in a queryable database format rather than as flat text
## Architectural Principles
### Clean Architecture Foundation
#### Layered Design
```
┌─────────────────────────┐
│ Presentation Layer │ ← CLI, Web Interface
├─────────────────────────┤
│ Application Layer │ ← Use Cases, Workflows
├─────────────────────────┤
│ Domain Layer │ ← Business Logic
├─────────────────────────┤
│ Infrastructure Layer │ ← Database, File System
└─────────────────────────┘
```
#### Dependency Rules
- **Inward Dependencies**: Outer layers depend on inner layers, never the reverse
- **Business Logic Isolation**: Core domain logic is independent of external concerns
- **Interface Segregation**: Clean interfaces between layers
### Performance Philosophy
#### Optimization Strategy
1. **Cache-First**: Intelligent AST caching for repeated operations
2. **Lazy Loading**: Process only what's needed, when needed
3. **Batch Operations**: Efficient processing of multiple documents
4. **Memory Management**: Careful resource utilization and cleanup
#### Performance Metrics
- **Template Rendering**: Target >1000 operations/second
- **Database Operations**: Target >100 operations/second
- **Document Ingestion**: Target >1000 operations/second
- **Memory Usage**: Keep under 50MB baseline
### Quality Assurance
#### Testing Strategy
- **TDD8 Methodology**: Test-Driven Development with 8-step cycle
- **Comprehensive Coverage**: Unit, integration, and end-to-end testing
- **Performance Validation**: Automated benchmarking and regression detection
- **Quality Gates**: Automated checks preventing quality degradation
#### Documentation Standards
- **DRY Principle**: Don't Repeat Yourself - avoid documentation duplication
- **Arc42 Framework**: Structured architecture documentation when complexity warrants
- **Living Documentation**: Documentation that evolves with the code
## Business Concepts
### Use Cases
#### Document Automation
- **Invoice Generation**: Automated creation of business invoices from templates
- **Report Pipelines**: Batch processing of document collections
- **Content Management**: Structured content workflow management
#### Content Analysis
- **Metadata Extraction**: Automated extraction of document properties
- **Content Validation**: Enforcement of document standards and requirements
- **Relationship Mapping**: Understanding connections between documents
#### Performance Management
- **Regression Detection**: Automated identification of performance degradation
- **Optimization Tracking**: Measurement of improvement initiatives
- **Baseline Management**: Establishment and maintenance of performance standards
### Value Propositions
#### Primary USPs (Unique Selling Points)
1. **Relational Document Metadata**: Documents as queryable database entities
2. **Zero-Parsing Content Access**: Instant access to document information
3. **Performance-First Design**: Dramatically faster than traditional markdown processors
#### Enterprise Benefits
- **Consistency**: Schema validation ensures document standardization
- **Efficiency**: Automated workflows reduce manual document management
- **Scalability**: Performance optimization supports large document collections
- **Quality**: Built-in validation and testing ensure reliability
## Technical Concepts
### Data Flow Architecture
#### Document Ingestion Pipeline
```
Markdown → Parser → AST → Metadata → Database
↓ ↓ ↓ ↓ ↓
Cache Validate Schema Extract Store
```
#### Query Processing
```
Query → Database → Metadata → Reconstruct → Results
↓ ↓ ↓ ↓ ↓
Index Optimize Filter Transform Format
```
### Integration Patterns
#### CLI-First Design
- **Command-Line Interface**: Primary interaction method for automation
- **Scriptable Operations**: All functionality accessible via CLI commands
- **Pipeline Integration**: Designed for CI/CD and automated workflows
#### Database Integration
- **SQLite Backend**: Lightweight, embedded database for metadata storage
- **Relational Queries**: SQL-like operations on document collections
- **ACID Compliance**: Reliable data consistency and transaction safety
### Extension Points
#### Plugin Architecture
- **Modular Design**: Core functionality extended through plugins
- **Template Engines**: Multiple template processing backends
- **Output Formats**: Extensible document generation formats
#### External Integration
- **API Endpoints**: RESTful interfaces for external systems
- **Webhook Support**: Event-driven integration capabilities
- **Import/Export**: Data exchange with external tools and formats
## Development Concepts
### Workflow Methodology
#### TDD8 Cycle
1. **ISSUE**: Define problem and requirements
2. **TEST**: Write tests before implementation
3. **RED**: Ensure tests fail initially
4. **GREEN**: Implement minimum viable solution
5. **REFACTOR**: Improve code quality and design
6. **DOCUMENT**: Update documentation and examples
7. **REFINE**: Performance optimization and polish
8. **PUBLISH**: Release and communicate changes
#### Quality Standards
- **Code Coverage**: Minimum 80% test coverage
- **Performance Benchmarks**: All operations must meet performance targets
- **Documentation Currency**: Documentation updated with every feature change
- **Backward Compatibility**: Changes preserve existing functionality
### Maintenance Philosophy
#### Sustainable Development
- **Technical Debt Management**: Regular refactoring and code quality improvement
- **Performance Monitoring**: Continuous tracking of system performance
- **User Experience Focus**: Features designed from user workflow perspective
- **Community Engagement**: Open source collaboration and contribution
#### Future-Proofing
- **Modular Architecture**: Easy addition of new features and capabilities
- **Standard Compliance**: Adherence to markdown and web standards
- **Scalability Design**: Architecture supports growth in users and document volume
- **Technology Evolution**: Designed to adapt to changing technology landscape
## Glossary
**Arc42**: Architecture documentation framework for technical communication
**AST**: Abstract Syntax Tree - structured representation of document content
**CLI**: Command-Line Interface - text-based user interface
**DRY**: Don't Repeat Yourself - principle of reducing duplication
**TDD**: Test-Driven Development - testing methodology
**TOML**: Tom's Obvious Minimal Language - configuration file format
**USP**: Unique Selling Point - distinctive business advantage
**YAML**: YAML Ain't Markup Language - human-readable data serialization
---
This document serves as the foundation for understanding MarkiTect's design philosophy, technical approach, and business value proposition. It should be consulted when making architectural decisions or explaining the project to new contributors.

32
LICENSE.md Normal file
View File

@@ -0,0 +1,32 @@
# MIT License
Copyright (c) 2025 MarkiTect Project
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
## Additional Information
This project uses the MIT License to promote open source collaboration while protecting contributors. The MIT License is:
- **Permissive**: Allows commercial and private use
- **Simple**: Easy to understand and implement
- **Compatible**: Works well with other open source licenses
- **Widely Adopted**: Recognized and trusted in the open source community
For questions about licensing or commercial use, please contact the project maintainers.

341
TESTING.md Normal file
View File

@@ -0,0 +1,341 @@
# Testing Guide
This document provides comprehensive guidelines for testing the MarkiTect project.
## Overview
MarkiTect uses a multi-layered testing approach with pytest as the primary testing framework. Our testing strategy ensures code quality, reliability, and maintainability across all components.
## Testing Framework
- **Primary Framework**: pytest
- **Configuration**: `pytest.ini`
- **Test Directory**: `tests/`
- **Python Versions**: 3.8+
## Test Structure
```
tests/
├── conftest.py # Shared test configuration and fixtures
├── e2e/ # End-to-end tests
├── fixtures/ # Test data and fixtures
├── integration/ # Integration tests
├── unit/ # Unit tests (by component)
├── test_*.py # Individual test modules
└── __pycache__/ # Python cache (auto-generated)
```
## Running Tests
### Quick Start
```bash
# Run all tests
pytest
# Run tests with verbose output
pytest -v
# Run specific test file
pytest tests/test_cli.py
# Run tests matching pattern
pytest -k "test_database"
# Run with coverage
pytest --cov=markitect --cov-report=html
```
### Test Categories
#### Unit Tests
```bash
# Run unit tests only
pytest tests/unit/
# Example: Test specific component
pytest tests/test_database.py
pytest tests/test_template_engine.py
```
#### Integration Tests
```bash
# Run integration tests
pytest tests/integration/
# Example: Test CLI integration
pytest tests/test_cli_integration.py
```
#### End-to-End Tests
```bash
# Run E2E tests
pytest tests/e2e/
```
## Test Configuration
### pytest.ini Configuration
- **Strict markers**: Enforces defined test markers
- **Verbose output**: Detailed test results
- **Duration tracking**: Shows slowest 10 tests
- **Fail fast**: Stops after 3 failures
### Custom Markers
```bash
# Performance tests
pytest -m performance
# Slow tests (run separately)
pytest -m slow
# Database tests
pytest -m database
```
## Writing Tests
### Test Naming Conventions
- Test files: `test_*.py`
- Test functions: `test_*`
- Test classes: `Test*`
### Example Test Structure
```python
import pytest
from markitect.core import MarkiTect
class TestMarkiTect:
"""Test suite for core MarkiTect functionality."""
def test_basic_functionality(self):
"""Test basic operation."""
# Arrange
markitect = MarkiTect()
# Act
result = markitect.process("# Test")
# Assert
assert result is not None
@pytest.mark.slow
def test_performance_intensive(self):
"""Test that requires significant time."""
pass
```
### Fixtures and Test Data
```python
# conftest.py
@pytest.fixture
def sample_markdown():
"""Provide sample markdown for testing."""
return "# Sample\n\nTest content"
@pytest.fixture
def temp_database():
"""Provide temporary test database."""
# Setup
db = create_test_db()
yield db
# Cleanup
db.close()
```
## Test Types and Guidelines
### Unit Tests
- **Scope**: Single function/method
- **Dependencies**: Mocked/isolated
- **Speed**: Fast (<100ms)
- **Location**: `tests/unit/`
### Integration Tests
- **Scope**: Component interaction
- **Dependencies**: Real dependencies within system
- **Speed**: Medium (100ms-2s)
- **Location**: `tests/integration/`
### End-to-End Tests
- **Scope**: Full system workflows
- **Dependencies**: Complete system
- **Speed**: Slow (>2s)
- **Location**: `tests/e2e/`
## Performance Testing
### Benchmarking
```bash
# Run performance benchmarks
markitect perf-benchmark --test-type all
# Validate performance thresholds
markitect perf-validate --threshold-ops 100
```
### Performance Tests in pytest
```python
@pytest.mark.performance
def test_large_document_processing():
"""Ensure large documents process within time limits."""
start_time = time.time()
# ... test logic ...
duration = time.time() - start_time
assert duration < 5.0 # Max 5 seconds
```
## Database Testing
### Test Database Setup
- Uses temporary SQLite databases
- Automatic cleanup after tests
- Isolated transactions per test
```python
@pytest.fixture
def test_db():
"""Provide isolated test database."""
from markitect.database import DatabaseManager
db = DatabaseManager(":memory:") # In-memory database
yield db
db.close()
```
## CLI Testing
### Testing CLI Commands
```python
from click.testing import CliRunner
from markitect.cli import cli
def test_cli_help():
"""Test CLI help command."""
runner = CliRunner()
result = runner.invoke(cli, ['--help'])
assert result.exit_code == 0
assert 'MarkiTect' in result.output
```
## Continuous Integration
### GitHub Actions
- Automatic test execution on push/PR
- Multiple Python versions tested
- Coverage reports generated
- Configuration: `.github/workflows/test.yml`
### Quality Gates
- All tests must pass
- Coverage minimum: 80%
- No failing static analysis checks
## Test Data Management
### Fixtures Directory
```
tests/fixtures/
├── sample_documents/ # Test markdown files
├── expected_outputs/ # Expected test results
├── schemas/ # Test schemas
└── data/ # Test data files
```
### Test Data Guidelines
- Keep test data minimal but representative
- Use meaningful names
- Include edge cases
- Document complex test scenarios
## Debugging Tests
### Common Debugging Commands
```bash
# Run single test with detailed output
pytest tests/test_module.py::test_function -vvv
# Drop into debugger on failure
pytest --pdb
# Stop on first failure
pytest -x
# Show local variables in tracebacks
pytest --tb=long -l
```
### Logging in Tests
```python
import logging
import pytest
def test_with_logging(caplog):
"""Test that captures log output."""
with caplog.at_level(logging.INFO):
# ... test code that logs ...
assert "Expected message" in caplog.text
```
## Best Practices
### Test Organization
1. **One concept per test**: Each test should verify one specific behavior
2. **Clear naming**: Test names should describe what is being tested
3. **Arrange-Act-Assert**: Structure tests clearly
4. **Independent tests**: Tests should not depend on each other
### Test Maintenance
1. **Keep tests simple**: Complex tests are hard to maintain
2. **Regular cleanup**: Remove obsolete tests
3. **Update documentation**: Keep this guide current
4. **Review coverage**: Aim for high but meaningful coverage
### Performance Considerations
1. **Fast feedback**: Unit tests should be very fast
2. **Parallel execution**: Tests should support parallel running
3. **Resource cleanup**: Always clean up resources
4. **Mocking**: Mock external dependencies appropriately
## Troubleshooting
### Common Issues
#### Import Errors
```bash
# Ensure PYTHONPATH is set correctly
export PYTHONPATH=.
pytest
```
#### Database Conflicts
```bash
# Clean test database
rm -f test_markitect.db
pytest
```
#### Slow Tests
```bash
# Profile test execution
pytest --durations=0
```
## Contributing
When contributing tests:
1. **Follow naming conventions**
2. **Add appropriate markers**
3. **Include docstrings**
4. **Test edge cases**
5. **Update this documentation if needed**
For more information about contributing, see the project's contribution guidelines.
## Resources
- [pytest Documentation](https://docs.pytest.org/)
- [Python Testing Best Practices](https://realpython.com/python-testing/)
- [Project Architecture Documentation](docs/architecture/)
- [Development Guidelines](docs/development/)