Compare commits
18 Commits
a8e5b4b044
...
v0.4.0
| Author | SHA1 | Date | |
|---|---|---|---|
| 49724d2ae5 | |||
| 25a38322c0 | |||
| 3a53e0aa58 | |||
| 64d1606740 | |||
| 1022e2597f | |||
| 50170f75df | |||
| 1877d6d462 | |||
| 7cc81dee8f | |||
| d5d943a604 | |||
| c5f49b2dd0 | |||
| 096017b93f | |||
| f0dfd04d45 | |||
| 6233d13f18 | |||
| 747715af58 | |||
| 62e7d13d7e | |||
| d402f3c75b | |||
| 804848b40c | |||
| ce14d3b2de |
6
.gitmodules
vendored
6
.gitmodules
vendored
@@ -2,3 +2,9 @@
|
||||
path = wiki
|
||||
url = http://92.205.130.254:32166/coulomb/markitect_project.wiki.git
|
||||
branch = main
|
||||
[submodule "capabilities/issue-facade"]
|
||||
path = capabilities/issue-facade
|
||||
url = http://92.205.130.254:32166/coulomb/issue-facade.git
|
||||
[submodule "capabilities/kaizen-agentic"]
|
||||
path = capabilities/kaizen-agentic
|
||||
url = http://92.205.130.254:32166/coulomb/kaizen-agentic.git
|
||||
|
||||
426
CAPABILITIES.md
426
CAPABILITIES.md
@@ -1,426 +0,0 @@
|
||||
# MarkiTect System Capabilities & Extraction Plan
|
||||
|
||||
> **Comprehensive overview of all capabilities, architectural innovations, and capability extraction recommendations for the ComposableRepositoryParadigm**
|
||||
|
||||
## Overview
|
||||
|
||||
- **Total Capabilities**: 73+ distinct capabilities
|
||||
- **Test Categories**: 15 major functional areas
|
||||
- **Test Coverage**: 348 tests across 27 test files
|
||||
- **Architecture**: Database-driven system with AST-based markdown processing, multi-layer caching, and deep Git platform integration
|
||||
- **Extraction Status**: 2 capabilities extracted, 11 candidates identified for extraction
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Capability Extraction Analysis
|
||||
|
||||
### Extraction Criteria
|
||||
|
||||
Based on the ComposableRepositoryParadigm, capabilities should be extracted when they meet these criteria:
|
||||
|
||||
1. **Self-Contained Functionality**: Can operate independently with minimal dependencies
|
||||
2. **Reusability**: Could be useful in other projects or contexts
|
||||
3. **Clear Boundaries**: Has well-defined interfaces and responsibilities
|
||||
4. **Test Coverage**: Has adequate test coverage (>80% preferred)
|
||||
5. **Size**: Significant enough to warrant extraction (>3 files or >500 LOC)
|
||||
6. **Domain Separation**: Represents a distinct domain or concern
|
||||
|
||||
### Current Extraction Status
|
||||
|
||||
#### ✅ **Already Extracted** (2 capabilities)
|
||||
- `markitect-content` - Content matter parsing (frontmatter, contentmatter, tailmatter)
|
||||
- `markitect-utils` - General utility functions (test capability)
|
||||
|
||||
#### 🎯 **Recommended for Extraction** (7 capabilities)
|
||||
|
||||
| Priority | Capability | Rationale | Complexity | Dependencies |
|
||||
|----------|------------|-----------|------------|-------------|
|
||||
| **HIGH** | `markitect-finance` | Complete financial tracking system, self-contained | High | Low |
|
||||
| **HIGH** | `markitect-query-paradigms` | 14 different query paradigms, highly reusable | High | Medium |
|
||||
| **HIGH** | `markitect-graphql` | Complete GraphQL interface, standalone value | Medium | Medium |
|
||||
| **MEDIUM** | `markitect-plugins` | Plugin architecture framework | Medium | Low |
|
||||
| **MEDIUM** | `markitect-matter-parsers` | All matter parsing capabilities (3 types) | Medium | Low |
|
||||
| **MEDIUM** | `markitect-legacy` | Legacy compatibility layer | Low | Low |
|
||||
| **LOW** | `markitect-issues` | Issue management system | High | High |
|
||||
|
||||
#### 🛑 **Not Recommended for Extraction** (Core System)
|
||||
|
||||
These modules form the core of MarkiTect and should remain in the main project:
|
||||
|
||||
- **Core Engine**: `cli.py`, `database.py`, `config_manager.py` - Main application logic
|
||||
- **AST Processing**: `ast_*.py`, `parser.py`, `serializer.py` - Core markdown processing
|
||||
- **Document Management**: `document_manager.py`, `batch_processor.py` - Core functionality
|
||||
- **Validation**: `schema_*.py`, `validation_*.py` - System integrity
|
||||
- **Performance**: `cache_service.py`, `performance_tracker.py` - Core performance
|
||||
- **Templates**: `template/` - Core template engine
|
||||
|
||||
---
|
||||
|
||||
## 📦 Detailed Capability Extraction Recommendations
|
||||
|
||||
### 1. 🏆 **HIGH PRIORITY - markitect-finance**
|
||||
|
||||
**Current Location**: `markitect/finance/`
|
||||
|
||||
**Files to Extract**:
|
||||
```
|
||||
markitect/finance/
|
||||
├── __init__.py # Package interface
|
||||
├── allocation_engine.py # Cost allocation logic
|
||||
├── cli.py # Finance CLI commands
|
||||
├── cost_manager.py # Cost tracking
|
||||
├── day_wrapup_commands.py # Daily summaries
|
||||
├── models.py # Data models
|
||||
├── period_manager.py # Period handling
|
||||
├── report_generator.py # Financial reports
|
||||
├── session_tracker.py # Session tracking
|
||||
├── worktime_commands.py # Work time CLI
|
||||
├── worktime_tracker.py # Time tracking
|
||||
└── migrations/001_create_cost_tables.sql
|
||||
```
|
||||
|
||||
**Why Extract**:
|
||||
- ✅ **Self-Contained**: Complete financial tracking system
|
||||
- ✅ **Reusable**: Could be used by other project management tools
|
||||
- ✅ **Clear Boundaries**: Well-defined domain (finance/time tracking)
|
||||
- ✅ **Size**: 11 files, substantial codebase
|
||||
- ✅ **Dependencies**: Minimal external dependencies
|
||||
|
||||
**Extraction Benefits**:
|
||||
- Could be reused in other project management systems
|
||||
- Independent development and versioning
|
||||
- Clear separation of financial concerns
|
||||
|
||||
### 2. 🏆 **HIGH PRIORITY - markitect-query-paradigms**
|
||||
|
||||
**Current Location**: `markitect/query_paradigms/`
|
||||
|
||||
**Files to Extract**:
|
||||
```
|
||||
markitect/query_paradigms/
|
||||
├── __init__.py # Package interface
|
||||
├── base.py # Base classes
|
||||
├── cli.py # Query CLI
|
||||
├── registry.py # Paradigm registry
|
||||
└── paradigms/ # 14 different paradigms
|
||||
├── batch_paradigm.py
|
||||
├── fts_paradigm.py
|
||||
├── graphql_paradigm.py
|
||||
├── jsonpath_paradigm.py
|
||||
├── natural_language_paradigm.py
|
||||
├── nosql_paradigm.py
|
||||
├── qbe_paradigm.py
|
||||
├── rag_paradigm.py
|
||||
├── rest_api_paradigm.py
|
||||
├── sql_paradigm.py
|
||||
├── transform_paradigm.py
|
||||
├── unix_pipeline_paradigm.py
|
||||
├── visual_builder_paradigm.py
|
||||
└── xpath_paradigm.py
|
||||
```
|
||||
|
||||
**Why Extract**:
|
||||
- ✅ **Highly Reusable**: Query paradigms useful across many applications
|
||||
- ✅ **Self-Contained**: Complete query abstraction system
|
||||
- ✅ **Innovation**: Unique architectural contribution
|
||||
- ✅ **Size**: 17+ files, substantial investment
|
||||
|
||||
**Extraction Benefits**:
|
||||
- Could become a standalone query abstraction library
|
||||
- High reusability potential across projects
|
||||
- Independent evolution of query capabilities
|
||||
|
||||
### 3. 🏆 **HIGH PRIORITY - markitect-graphql**
|
||||
|
||||
**Current Location**: `markitect/graphql/`
|
||||
|
||||
**Files to Extract**:
|
||||
```
|
||||
markitect/graphql/
|
||||
├── __init__.py # Package interface
|
||||
├── resolvers.py # GraphQL resolvers
|
||||
├── schema.py # GraphQL schema
|
||||
└── server.py # GraphQL server
|
||||
```
|
||||
|
||||
**Why Extract**:
|
||||
- ✅ **Standalone Value**: Complete GraphQL API interface
|
||||
- ✅ **Reusable**: GraphQL interfaces are broadly applicable
|
||||
- ✅ **Clear Boundaries**: Well-defined API layer
|
||||
- ✅ **Technology**: Uses standard GraphQL patterns
|
||||
|
||||
**Extraction Benefits**:
|
||||
- Can be developed independently with GraphQL ecosystem
|
||||
- Reusable across different backend systems
|
||||
- Clear API versioning and evolution
|
||||
|
||||
### 4. 🥈 **MEDIUM PRIORITY - markitect-plugins**
|
||||
|
||||
**Current Location**: `markitect/plugins/`
|
||||
|
||||
**Files to Extract**:
|
||||
```
|
||||
markitect/plugins/
|
||||
├── __init__.py # Package interface
|
||||
├── base.py # Base plugin classes
|
||||
├── decorators.py # Plugin decorators
|
||||
├── manager.py # Plugin manager
|
||||
├── registry.py # Plugin registry
|
||||
└── builtin/ # Built-in plugins
|
||||
├── formatters.py
|
||||
├── processors.py
|
||||
└── search/ # Search plugins
|
||||
├── fts_search.py
|
||||
├── indexer.py
|
||||
└── query_parser.py
|
||||
```
|
||||
|
||||
**Why Extract**:
|
||||
- ✅ **Reusable**: Plugin architecture pattern broadly applicable
|
||||
- ✅ **Self-Contained**: Complete plugin system
|
||||
- ✅ **Size**: 9+ files, substantial codebase
|
||||
|
||||
**Extraction Benefits**:
|
||||
- Plugin architecture could be reused in other applications
|
||||
- Independent development of plugin ecosystem
|
||||
- Clear extensibility patterns
|
||||
|
||||
### 5. 🥈 **MEDIUM PRIORITY - markitect-matter-parsers**
|
||||
|
||||
**Current Status**: `markitect-content` already extracted, but three separate parsers remain:
|
||||
|
||||
**Files to Extract**:
|
||||
```
|
||||
markitect/matter_frontmatter/ # Front matter parsing
|
||||
markitect/matter_contentmatter/ # Content matter parsing
|
||||
markitect/matter_tailmatter/ # Tail matter parsing
|
||||
```
|
||||
|
||||
**Why Extract**:
|
||||
- ✅ **Reusable**: Matter parsing useful for many markdown tools
|
||||
- ✅ **Self-Contained**: Each parser is independent
|
||||
- ✅ **Clear Domain**: Document structure parsing
|
||||
|
||||
**Extraction Benefits**:
|
||||
- Could be used by other markdown processing tools
|
||||
- Independent evolution of parsing capabilities
|
||||
|
||||
### 6. 🥈 **MEDIUM PRIORITY - markitect-legacy**
|
||||
|
||||
**Current Location**: `markitect/legacy/`
|
||||
|
||||
**Files to Extract**:
|
||||
```
|
||||
markitect/legacy/
|
||||
├── __init__.py # Package interface
|
||||
├── agent.py # Legacy agents
|
||||
├── compatibility.py # Compatibility layer
|
||||
├── deprecation.py # Deprecation handling
|
||||
├── exceptions.py # Legacy exceptions
|
||||
├── git_tracker.py # Legacy Git tracking
|
||||
├── registry.py # Legacy registry
|
||||
└── switches.py # Feature switches
|
||||
```
|
||||
|
||||
**Why Extract**:
|
||||
- ✅ **Self-Contained**: Complete legacy compatibility system
|
||||
- ✅ **Bounded**: Will eventually be removed
|
||||
- ✅ **Clean Separation**: Should not contaminate main codebase
|
||||
|
||||
**Extraction Benefits**:
|
||||
- Keeps legacy code separate from main evolution
|
||||
- Can be deprecated independently
|
||||
- Clear migration path
|
||||
|
||||
### 7. 🥉 **LOW PRIORITY - markitect-issues**
|
||||
|
||||
**Current Location**: `markitect/issues/`
|
||||
|
||||
**Files to Extract**:
|
||||
```
|
||||
markitect/issues/
|
||||
├── __init__.py # Package interface
|
||||
├── activity_commands.py # Activity tracking
|
||||
├── activity_tracker.py # Activity tracking
|
||||
├── base.py # Base classes
|
||||
├── commands.py # Issue CLI commands
|
||||
├── exceptions.py # Issue exceptions
|
||||
├── issue_wrapup_commands.py # Issue completion
|
||||
├── manager.py # Issue manager
|
||||
└── plugins/ # Issue plugins
|
||||
├── gitea.py # Gitea integration
|
||||
└── local.py # Local issues
|
||||
```
|
||||
|
||||
**Why Lower Priority**:
|
||||
- ⚠️ **High Dependencies**: Tightly integrated with core system
|
||||
- ⚠️ **Complex**: Issue management is complex domain
|
||||
- ⚠️ **Core Feature**: Central to MarkiTect's value proposition
|
||||
|
||||
**Consider for Later**:
|
||||
- Extract after core system stabilizes
|
||||
- Requires careful dependency analysis
|
||||
- High integration complexity
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Extraction Implementation Plan
|
||||
|
||||
### Phase 1: **High-Value, Low-Risk Extractions**
|
||||
1. **markitect-finance** - Complete financial system
|
||||
2. **markitect-graphql** - GraphQL interface
|
||||
3. **markitect-legacy** - Legacy compatibility
|
||||
|
||||
### Phase 2: **Complex, High-Value Extractions**
|
||||
4. **markitect-query-paradigms** - Query abstraction system
|
||||
5. **markitect-plugins** - Plugin architecture
|
||||
|
||||
### Phase 3: **Specialized Extractions**
|
||||
6. **markitect-matter-parsers** - Consolidate matter parsing
|
||||
7. **markitect-issues** - Issue management (if dependencies allow)
|
||||
|
||||
### Phase 4: **Validation and Optimization**
|
||||
- Test all extractions thoroughly
|
||||
- Optimize inter-capability dependencies
|
||||
- Document lessons learned
|
||||
- Update ComposableRepositoryParadigm based on experience
|
||||
|
||||
---
|
||||
|
||||
## 📊 Extraction Impact Analysis
|
||||
|
||||
### Complexity vs. Value Matrix
|
||||
|
||||
```
|
||||
High Value │ query-paradigms │ finance │
|
||||
│ │ graphql │
|
||||
│ │ │
|
||||
│ plugins │ matter-parsers │
|
||||
Low Value │ legacy │ issues │
|
||||
────────────────────────────────────
|
||||
Low Complexity High Complexity
|
||||
```
|
||||
|
||||
### Recommended Extraction Order
|
||||
|
||||
1. **markitect-finance** (High Value, Medium Complexity) - Complete system
|
||||
2. **markitect-graphql** (High Value, Low Complexity) - Clean API layer
|
||||
3. **markitect-legacy** (Medium Value, Low Complexity) - Easy win
|
||||
4. **markitect-query-paradigms** (High Value, High Complexity) - Big impact
|
||||
5. **markitect-plugins** (Medium Value, Medium Complexity) - Architecture
|
||||
6. **markitect-matter-parsers** (Medium Value, Low Complexity) - Consolidation
|
||||
7. **markitect-issues** (High Value, High Complexity) - Complex integration
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Success Criteria for Extractions
|
||||
|
||||
Each extracted capability must meet these criteria:
|
||||
|
||||
### Technical Requirements
|
||||
- ✅ **Zero Parent Dependencies**: No imports from main markitect project
|
||||
- ✅ **Complete Test Suite**: >80% test coverage
|
||||
- ✅ **Independent Build**: Can be built and tested separately
|
||||
- ✅ **Documentation**: Complete README and API documentation
|
||||
- ✅ **Version Management**: Independent versioning with semver
|
||||
|
||||
### Quality Requirements
|
||||
- ✅ **Type Safety**: Complete type annotations
|
||||
- ✅ **Error Handling**: Comprehensive error handling
|
||||
- ✅ **Performance**: No performance regressions
|
||||
- ✅ **Security**: No security vulnerabilities introduced
|
||||
|
||||
### Process Requirements
|
||||
- ✅ **Red-Green Testing**: All tests pass after extraction
|
||||
- ✅ **CI/CD**: Independent CI/CD pipeline
|
||||
- ✅ **Integration**: Smooth integration with main project
|
||||
- ✅ **Migration Path**: Clear upgrade/downgrade paths
|
||||
|
||||
---
|
||||
|
||||
## 📋 Core MarkiTect Capabilities (Remain in Main Project)
|
||||
|
||||
### Core Architectural Paradigms
|
||||
|
||||
#### 1. Parse-Once, Manipulate-Many Architecture™
|
||||
**Paradigm**: Single parsing operation creates multiple access pathways for document manipulation.
|
||||
|
||||
**Innovation**: Traditional markdown processors re-parse content for each operation. MarkiTect parses once and creates multiple fast-access representations:
|
||||
- **AST Cache**: JSON-serialized Abstract Syntax Tree for lightning-fast loading
|
||||
- **Database Metadata**: Structured front matter and document metadata
|
||||
- **Original Content**: Preserved for integrity validation
|
||||
|
||||
#### 2. Database-First Metadata Management
|
||||
**Paradigm**: Document metadata is treated as first-class relational data, not file-system artifacts.
|
||||
|
||||
#### 3. Performance-Validated Caching System
|
||||
**Paradigm**: Cache performance is continuously validated against benchmarks, not assumed.
|
||||
|
||||
#### 4. TDD8 Methodology Integration
|
||||
**Paradigm**: Issue-driven development with 8-step validation cycles.
|
||||
|
||||
### Core System Components
|
||||
|
||||
#### 🗄️ Database & Storage
|
||||
- Database initialization and schema management
|
||||
- Markdown file storage with metadata tracking
|
||||
- SQL query execution with safety constraints
|
||||
- Performance optimizations for large datasets
|
||||
|
||||
#### 📝 Markdown Processing
|
||||
- Core AST conversion and manipulation
|
||||
- Document modification through AST
|
||||
- Roundtrip integrity validation
|
||||
- Performance-optimized parsing
|
||||
|
||||
#### 🚀 Performance & Caching
|
||||
- AST caching system with smart invalidation
|
||||
- Performance benchmarking and validation
|
||||
- Memory usage optimization
|
||||
- Bulk operation efficiency
|
||||
|
||||
#### 🖥️ CLI Framework
|
||||
- Command-line interface foundation
|
||||
- Configuration management
|
||||
- Error handling and validation
|
||||
- Output formatting
|
||||
|
||||
#### 🔧 System Integration
|
||||
- Configuration validation
|
||||
- Environment detection
|
||||
- Network connectivity
|
||||
- File system validation
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Future Roadmap
|
||||
|
||||
### Post-Extraction Goals
|
||||
1. **Template System**: Create capability templates from successful extractions
|
||||
2. **Dependency Checker**: Automated tools for dependency compliance
|
||||
3. **CI/CD Patterns**: Establish patterns for capability CI/CD
|
||||
4. **Integration Testing**: Cross-capability integration test framework
|
||||
|
||||
### Planned Extensions
|
||||
- **Distributed Capabilities**: Multi-machine capability sharing
|
||||
- **Capability Marketplace**: Public registry of MarkiTect capabilities
|
||||
- **AI-Assisted Extraction**: Automated capability boundary detection
|
||||
|
||||
---
|
||||
|
||||
## 📚 Getting Started with Extractions
|
||||
|
||||
To begin capability extraction process:
|
||||
|
||||
1. **Validate Test Capability**: Ensure `markitect-utils` works correctly
|
||||
2. **Choose Starting Point**: Begin with `markitect-finance` (high value, clear boundaries)
|
||||
3. **Follow TDD Process**: Maintain test suite throughout extraction
|
||||
4. **Document Experience**: Update this document with lessons learned
|
||||
|
||||
For detailed extraction procedures, see:
|
||||
- `/wiki/ComposableRepositoryParadigm.md` - Extraction methodology
|
||||
- `/capabilities/markitect-utils/VALIDATION_REPORT.md` - Process validation
|
||||
|
||||
---
|
||||
|
||||
*This capabilities analysis reflects the current state of the MarkiTect project and provides a roadmap for systematic capability extraction following the ComposableRepositoryParadigm. All recommendations are based on architectural analysis, dependency review, and reusability assessment.*
|
||||
110
CHANGELOG.md
110
CHANGELOG.md
@@ -1,100 +1,18 @@
|
||||
# Changelog
|
||||
## [0.4.0] - 2025-10-25
|
||||
|
||||
### Added
|
||||
- feat: add comprehensive testing and error tracking for edit mode
|
||||
|
||||
### Fixed
|
||||
- fix: resolve md-render --edit functionality and add enhanced version tracking
|
||||
- fix: resolve critical JavaScript syntax errors in md-render --edit
|
||||
- fix: resolve md-ingest Path object conversion error
|
||||
|
||||
### Other
|
||||
- chore: clean up repository documentation files for release
|
||||
|
||||
|
||||
|
||||
All notable changes to MarkiTect will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
## [0.2.0] - 2025-10-20
|
||||
|
||||
### Added
|
||||
- **Production-Ready Asset Management System** with content-addressable storage
|
||||
- **Advanced Performance Optimization** with 60-85% faster document processing
|
||||
- **Enterprise-Grade Error Handling** with graceful recovery mechanisms
|
||||
- **Comprehensive Test Suite** with 1983 tests and 100% success rate
|
||||
- **GraphQL Interface** for advanced querying capabilities
|
||||
- **Full-Text Search** with FTS5 backend and query optimization
|
||||
- **Kaizen-Agentic Framework Integration** with 17 specialized development agents
|
||||
- **Professional Documentation** with 20+ comprehensive guides
|
||||
- **Cross-Platform Validation** for Unix/Windows/macOS compatibility
|
||||
- **CLI Consolidation** with unified command interface
|
||||
- **Template Rendering System** with validation and error handling
|
||||
- **Cost Management & Tracking** with allocation engine and reporting
|
||||
- **Issue Activity Tracking** with worktime distribution
|
||||
- **Plugin Architecture** with builtin processors and extensible framework
|
||||
- **Query Paradigms** supporting 14 different query approaches
|
||||
- **Content-Matter Processing** with frontmatter, contentmatter, and tailmatter support
|
||||
- Comprehensive installer system with Python and shell scripts
|
||||
- Version and release information commands (`markitect version`, `markitect release`)
|
||||
- Global `--version` flag for quick version checking
|
||||
- Git integration for version metadata (commit, branch, tag information)
|
||||
- Multiple output formats for release information (text, JSON, YAML)
|
||||
- Installation documentation and troubleshooting guides
|
||||
|
||||
### Performance
|
||||
- **60-85% performance improvement** through AST caching optimization
|
||||
- **Sub-60ms asset processing** with efficient deduplication
|
||||
- **Memory-efficient operations** with proper resource management
|
||||
- **Scalable architecture** supporting large document collections
|
||||
|
||||
### Quality Assurance
|
||||
- **1983 comprehensive tests** covering all functionality layers
|
||||
- **Production validation suite** with cross-platform testing
|
||||
- **Enterprise error handling** with graceful degradation
|
||||
- **Type safety** with comprehensive type checking
|
||||
- **Security validation** with input sanitization and safe operations
|
||||
|
||||
### Fixed
|
||||
- All test failures resolved (1983/1983 tests passing)
|
||||
- Visualization schema tests updated for correct tool paths
|
||||
- Cache management test isolation issues
|
||||
- Missing dependencies documentation and installation
|
||||
- JavaScript syntax errors in edit mode initialization
|
||||
- Asset registry synchronization and performance issues
|
||||
- CLI command consolidation and interface consistency
|
||||
|
||||
### Documentation
|
||||
- Added comprehensive INSTALL.md with installation instructions
|
||||
- Added DEPENDENCIES.md with dependency information
|
||||
- Created release process documentation
|
||||
- **20+ documentation files** covering architecture, usage, and development
|
||||
- Complete API documentation with examples
|
||||
- Performance benchmarking guides and optimization tips
|
||||
|
||||
## [0.1.0] - 2025-10-03
|
||||
|
||||
### Added
|
||||
- Initial MarkiTect implementation
|
||||
- Core markdown processing with AST caching
|
||||
- Front matter and content matter support
|
||||
- Database integration for document metadata
|
||||
- CLI interface with comprehensive commands
|
||||
- Schema generation and validation
|
||||
- Template rendering system
|
||||
- Issue management integration
|
||||
- TDD workflow tools (TDDAI)
|
||||
- Comprehensive test suite with architectural layers
|
||||
- Documentation and architectural guides
|
||||
|
||||
### Features
|
||||
- Document ingestion and processing
|
||||
- Metadata extraction and querying
|
||||
- AST analysis and caching
|
||||
- Content statistics and analysis
|
||||
- Template-based document generation
|
||||
- Associated file management
|
||||
- Database operations with multiple output formats
|
||||
- Performance monitoring and optimization
|
||||
- Legacy compatibility system
|
||||
|
||||
### Technical
|
||||
- Python 3.8+ support
|
||||
- Click-based CLI framework
|
||||
- SQLite database backend
|
||||
- Markdown-it-py parser integration
|
||||
- Comprehensive test coverage
|
||||
- Type checking with mypy
|
||||
- Code formatting with black
|
||||
- Project structure following clean architecture principles
|
||||
239
CONCEPT.md
239
CONCEPT.md
@@ -1,239 +0,0 @@
|
||||
# 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.
|
||||
205
CONFIG.md
205
CONFIG.md
@@ -1,205 +0,0 @@
|
||||
# TDDAi Configuration Management
|
||||
|
||||
> **⚠️ DEPRECATED**: The tddai framework has been replaced by the [issue-facade](issue-facade/) system. This documentation is kept for historical reference only.
|
||||
>
|
||||
> **For current issue management**: See [issue-facade/README.md](issue-facade/README.md)
|
||||
|
||||
The tddai framework uses a flexible, hierarchical configuration system designed for project-agnostic deployment while supporting per-project customization.
|
||||
|
||||
## Configuration Hierarchy
|
||||
|
||||
Configuration values are loaded in the following priority order (highest to lowest):
|
||||
|
||||
1. **Environment Variables** - Runtime overrides (highest priority)
|
||||
2. **`.env.tddai` File** - Project-specific configuration (auto-loaded)
|
||||
3. **Default Values** - Framework defaults (fallback)
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Automatic Configuration (Recommended)
|
||||
The framework automatically loads `.env.tddai` from the current directory:
|
||||
|
||||
```bash
|
||||
# Configuration loaded automatically
|
||||
make tdd-status
|
||||
make tdd-start NUM=5
|
||||
```
|
||||
|
||||
### Manual Configuration
|
||||
You can also source the setup script manually:
|
||||
|
||||
```bash
|
||||
source tddai-setup.sh
|
||||
make tdd-status
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
### Repository Settings (Required)
|
||||
|
||||
| Variable | Description | Example | Required |
|
||||
|----------|-------------|---------|----------|
|
||||
| `TDDAI_GITEA_URL` | Git platform URL | `https://github.com` | ✅ |
|
||||
| `TDDAI_REPO_OWNER` | Repository owner/org | `myusername` | ✅ |
|
||||
| `TDDAI_REPO_NAME` | Repository name | `myproject` | ✅ |
|
||||
|
||||
### Workspace Settings (Optional)
|
||||
|
||||
| Variable | Description | Default | Example |
|
||||
|----------|-------------|---------|---------|
|
||||
| `TDDAI_WORKSPACE_DIR` | TDD workspace directory | `.tddai_workspace` | `.myproject_workspace` |
|
||||
|
||||
### Test Settings (Framework Defaults)
|
||||
|
||||
| Setting | Value | Description |
|
||||
|---------|-------|-------------|
|
||||
| `tests_dir` | `tests/` | Main test directory |
|
||||
| `test_file_pattern` | `test_issue_{issue_num}_{scenario}.py` | Test file naming pattern |
|
||||
| `current_issue_file` | `current_issue.json` | Active issue metadata file |
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### `.env.tddai` Format
|
||||
```bash
|
||||
# TDDAi configuration for YourProject
|
||||
# Repository settings
|
||||
TDDAI_GITEA_URL=https://your-git-platform.com
|
||||
TDDAI_REPO_OWNER=yourusername
|
||||
TDDAI_REPO_NAME=yourproject
|
||||
|
||||
# Workspace settings (optional)
|
||||
TDDAI_WORKSPACE_DIR=.yourproject_workspace
|
||||
```
|
||||
|
||||
### `tddai-setup.sh` Format
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# TDDAi environment setup script
|
||||
|
||||
export TDDAI_GITEA_URL=https://your-git-platform.com
|
||||
export TDDAI_REPO_OWNER=yourusername
|
||||
export TDDAI_REPO_NAME=yourproject
|
||||
export TDDAI_WORKSPACE_DIR=.yourproject_workspace
|
||||
|
||||
echo "✅ TDDAi configured for YourProject"
|
||||
```
|
||||
|
||||
## Platform Examples
|
||||
|
||||
### GitHub Configuration
|
||||
```bash
|
||||
TDDAI_GITEA_URL=https://github.com
|
||||
TDDAI_REPO_OWNER=yourusername
|
||||
TDDAI_REPO_NAME=yourrepo
|
||||
```
|
||||
|
||||
### GitLab Configuration
|
||||
```bash
|
||||
TDDAI_GITEA_URL=https://gitlab.com
|
||||
TDDAI_REPO_OWNER=yourusername
|
||||
TDDAI_REPO_NAME=yourrepo
|
||||
```
|
||||
|
||||
### Self-hosted Gitea
|
||||
```bash
|
||||
TDDAI_GITEA_URL=https://git.yourcompany.com
|
||||
TDDAI_REPO_OWNER=yourorganization
|
||||
TDDAI_REPO_NAME=yourproject
|
||||
```
|
||||
|
||||
## API Integration
|
||||
|
||||
The configuration automatically constructs API URLs:
|
||||
|
||||
```python
|
||||
# Constructed from configuration
|
||||
issues_api_url = f"{TDDAI_GITEA_URL}/api/v1/repos/{TDDAI_REPO_OWNER}/{TDDAI_REPO_NAME}/issues"
|
||||
```
|
||||
|
||||
## Workspace Structure
|
||||
|
||||
Default workspace layout (configurable via `TDDAI_WORKSPACE_DIR`):
|
||||
|
||||
```
|
||||
.tddai_workspace/
|
||||
├── current_issue.json # Active issue metadata
|
||||
└── issue_X/ # Issue-specific workspace
|
||||
├── tests/ # Test files for this issue
|
||||
│ └── test_issue_X_*.py # Generated test files
|
||||
├── requirements.md # Issue requirements analysis
|
||||
└── test_plan.md # Test planning document
|
||||
```
|
||||
|
||||
## Environment Variable Overrides
|
||||
|
||||
You can override any configuration at runtime:
|
||||
|
||||
```bash
|
||||
# Override workspace directory for this session
|
||||
TDDAI_WORKSPACE_DIR=.custom_workspace make tdd-start NUM=5
|
||||
|
||||
# Override repository for testing
|
||||
TDDAI_REPO_NAME=test_repo make tdd-status
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
The framework validates configuration on startup:
|
||||
|
||||
- **Required fields** must be non-empty (`gitea_url`, `repo_owner`, `repo_name`)
|
||||
- **URLs** should include protocol (`http://` or `https://`)
|
||||
- **Workspace directories** are created automatically if they don't exist
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Errors
|
||||
|
||||
**`gitea_url cannot be empty`**
|
||||
- Solution: Create `.env.tddai` with `TDDAI_GITEA_URL=your-url`
|
||||
- Alternative: Run `source tddai-setup.sh` before tddai commands
|
||||
|
||||
**`repo_owner cannot be empty`**
|
||||
- Solution: Set `TDDAI_REPO_OWNER` in `.env.tddai` or environment
|
||||
|
||||
**`repo_name cannot be empty`**
|
||||
- Solution: Set `TDDAI_REPO_NAME` in `.env.tddai` or environment
|
||||
|
||||
### Debug Configuration
|
||||
```bash
|
||||
# Check current configuration
|
||||
python -c "from tddai.config import get_config; c=get_config(); print(f'URL: {c.gitea_url}\\nOwner: {c.repo_owner}\\nRepo: {c.repo_name}\\nWorkspace: {c.workspace_dir}')"
|
||||
```
|
||||
|
||||
## Migration from Other Projects
|
||||
|
||||
When adapting tddai for a new project:
|
||||
|
||||
1. **Copy configuration template**:
|
||||
```bash
|
||||
cp .env.tddai.example .env.tddai
|
||||
```
|
||||
|
||||
2. **Update repository settings**:
|
||||
```bash
|
||||
# Edit .env.tddai
|
||||
TDDAI_GITEA_URL=https://your-platform.com
|
||||
TDDAI_REPO_OWNER=your-username
|
||||
TDDAI_REPO_NAME=your-project
|
||||
```
|
||||
|
||||
3. **Test configuration**:
|
||||
```bash
|
||||
make tdd-status
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Use `.env.tddai`** for project-specific settings
|
||||
- **Use environment variables** for temporary overrides
|
||||
- **Keep configuration in version control** (but exclude sensitive tokens)
|
||||
- **Document custom workspace naming** in project README
|
||||
- **Validate configuration** before starting development sessions
|
||||
|
||||
---
|
||||
|
||||
*This configuration system supports the TDD8 methodology (ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH) across any software development project with issue tracking.*
|
||||
@@ -1,92 +0,0 @@
|
||||
# MarkiTect Project Dependencies
|
||||
|
||||
## Overview
|
||||
This document lists all project dependencies for the MarkiTect project.
|
||||
|
||||
## Production Dependencies
|
||||
These are required for running the application:
|
||||
|
||||
- **markdown-it-py** - Markdown parsing library
|
||||
- **PyYAML** - YAML file processing
|
||||
- **click>=8.0.0** - Command-line interface framework
|
||||
- **tabulate>=0.9.0** - Table formatting for output
|
||||
- **jsonpath-ng>=1.5.0** - JSONPath query support
|
||||
- **aiohttp>=3.8.0** - Async HTTP client/server
|
||||
- **toml** - TOML file parsing (for frontmatter support)
|
||||
|
||||
## Development Dependencies
|
||||
These are required for development, testing, and code quality:
|
||||
|
||||
- **pytest** - Testing framework
|
||||
- **pytest-cov** - Test coverage reporting
|
||||
- **black** - Code formatting
|
||||
- **flake8** - Code linting
|
||||
- **mypy** - Type checking
|
||||
|
||||
## Test Dependencies
|
||||
Additional dependencies for testing (from tests/requirements-test.txt if present):
|
||||
- See `tests/requirements-test.txt` for any additional test-specific dependencies
|
||||
|
||||
## Installation
|
||||
|
||||
### Quick Setup
|
||||
```bash
|
||||
# Install production dependencies only
|
||||
pip install -e .
|
||||
|
||||
# Install with development dependencies
|
||||
make dev
|
||||
```
|
||||
|
||||
### Manual Installation
|
||||
```bash
|
||||
# Production dependencies
|
||||
pip install markdown-it-py PyYAML click>=8.0.0 tabulate>=0.9.0 jsonpath-ng>=1.5.0 aiohttp>=3.8.0 toml
|
||||
|
||||
# Development dependencies
|
||||
pip install pytest pytest-cov black flake8 mypy
|
||||
```
|
||||
|
||||
### Virtual Environment Setup
|
||||
```bash
|
||||
# Create and activate virtual environment
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
|
||||
# Install dependencies
|
||||
make dev
|
||||
```
|
||||
|
||||
## Running Tests
|
||||
After installing dependencies:
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
make test
|
||||
|
||||
# Run tests with coverage
|
||||
pytest --cov
|
||||
|
||||
# Run specific test layers
|
||||
make test-foundation
|
||||
make test-infrastructure
|
||||
make test-integration
|
||||
```
|
||||
|
||||
## Code Quality Tools
|
||||
|
||||
```bash
|
||||
# Format code
|
||||
make format
|
||||
|
||||
# Run linting
|
||||
make lint
|
||||
|
||||
# Type checking
|
||||
mypy markitect/
|
||||
```
|
||||
|
||||
## Notes
|
||||
- Python 3.8+ is required
|
||||
- Virtual environment (.venv) is recommended
|
||||
- All dependencies are managed through pyproject.toml
|
||||
219
INSTALL.md
219
INSTALL.md
@@ -1,219 +0,0 @@
|
||||
# MarkiTect Installation Guide
|
||||
|
||||
This document describes how to install MarkiTect and make it available system-wide.
|
||||
|
||||
## Quick Installation
|
||||
|
||||
For most users, the quick installer is the easiest option:
|
||||
|
||||
```bash
|
||||
# Install for current user
|
||||
./install.sh
|
||||
|
||||
# Install system-wide (requires sudo)
|
||||
./install.sh --system
|
||||
|
||||
# Install in development mode with test dependencies
|
||||
./install.sh --dev
|
||||
```
|
||||
|
||||
## Advanced Installation
|
||||
|
||||
For more control over the installation process, use the Python installer:
|
||||
|
||||
```bash
|
||||
# Install with custom prefix
|
||||
python install.py --prefix /opt/markitect
|
||||
|
||||
# Install with custom virtual environment location
|
||||
python install.py --venv-dir /path/to/custom/venv
|
||||
|
||||
# Install without creating symbolic links (manual PATH setup)
|
||||
python install.py --no-symlinks
|
||||
|
||||
# Force reinstallation over existing installation
|
||||
python install.py --force
|
||||
```
|
||||
|
||||
## Installation Options
|
||||
|
||||
### Installation Types
|
||||
|
||||
- **User Installation** (default): Installs to `~/.local/`
|
||||
- **System Installation** (`--system`): Installs to `/usr/local/` (requires sudo)
|
||||
- **Development Installation** (`--dev`): Installs in editable mode with test dependencies
|
||||
|
||||
### Installation Paths
|
||||
|
||||
By default, MarkiTect is installed to:
|
||||
|
||||
- **User installation**: `~/.local/lib/markitect/` (virtual environment)
|
||||
- **System installation**: `/usr/local/lib/markitect/` (virtual environment)
|
||||
- **Binaries**: `~/.local/bin/` or `/usr/local/bin/`
|
||||
|
||||
### Available Commands
|
||||
|
||||
After installation, these commands will be available:
|
||||
|
||||
- `markitect` - Main MarkiTect CLI
|
||||
- `tddai` - TDD workflow management
|
||||
- `issue` - Issue management
|
||||
|
||||
## Checking Installation
|
||||
|
||||
Check if MarkiTect is already installed:
|
||||
|
||||
```bash
|
||||
./install.sh --check
|
||||
# or
|
||||
python install.py --check
|
||||
```
|
||||
|
||||
Check version after installation:
|
||||
|
||||
```bash
|
||||
markitect version
|
||||
markitect version --short
|
||||
markitect release
|
||||
```
|
||||
|
||||
## Uninstallation
|
||||
|
||||
To remove MarkiTect:
|
||||
|
||||
```bash
|
||||
./install.sh --uninstall
|
||||
# or
|
||||
python install.py --uninstall
|
||||
```
|
||||
|
||||
## Manual Installation
|
||||
|
||||
If you prefer to install manually:
|
||||
|
||||
1. **Create virtual environment:**
|
||||
```bash
|
||||
python -m venv ~/.local/lib/markitect
|
||||
```
|
||||
|
||||
2. **Activate virtual environment:**
|
||||
```bash
|
||||
source ~/.local/lib/markitect/bin/activate
|
||||
```
|
||||
|
||||
3. **Install MarkiTect:**
|
||||
```bash
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
4. **Create symbolic links:**
|
||||
```bash
|
||||
mkdir -p ~/.local/bin
|
||||
ln -sf ~/.local/lib/markitect/bin/markitect ~/.local/bin/markitect
|
||||
ln -sf ~/.local/lib/markitect/bin/tddai ~/.local/bin/tddai
|
||||
ln -sf ~/.local/lib/markitect/bin/issue ~/.local/bin/issue
|
||||
```
|
||||
|
||||
5. **Add to PATH** (add to `~/.bashrc` or `~/.zshrc`):
|
||||
```bash
|
||||
export PATH="$HOME/.local/bin:$PATH"
|
||||
```
|
||||
|
||||
## Development Installation
|
||||
|
||||
For development work:
|
||||
|
||||
```bash
|
||||
# Install in development mode
|
||||
./install.sh --dev
|
||||
|
||||
# This includes:
|
||||
# - Editable installation (changes reflect immediately)
|
||||
# - Test dependencies (pytest, black, flake8, mypy)
|
||||
# - All development tools
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Command not found after installation:**
|
||||
- Make sure `~/.local/bin` is in your PATH
|
||||
- Run: `export PATH="$HOME/.local/bin:$PATH"`
|
||||
- Add the export to your shell profile
|
||||
|
||||
2. **Permission denied on system installation:**
|
||||
- Use `sudo ./install.sh --system`
|
||||
- Or install to user directory instead
|
||||
|
||||
3. **Python version error:**
|
||||
- MarkiTect requires Python 3.8 or higher
|
||||
- Check version: `python3 --version`
|
||||
|
||||
4. **Installation already exists:**
|
||||
- Use `--force` to overwrite: `./install.sh --force`
|
||||
- Or uninstall first: `./install.sh --uninstall`
|
||||
|
||||
### Manual PATH Setup
|
||||
|
||||
If symbolic links don't work, add the virtual environment bin directory to your PATH:
|
||||
|
||||
```bash
|
||||
# For bash/zsh (add to ~/.bashrc or ~/.zshrc)
|
||||
export PATH="$HOME/.local/lib/markitect/bin:$PATH"
|
||||
|
||||
# For fish (add to ~/.config/fish/config.fish)
|
||||
set -gx PATH $HOME/.local/lib/markitect/bin $PATH
|
||||
```
|
||||
|
||||
### Testing Installation
|
||||
|
||||
After installation, verify everything works:
|
||||
|
||||
```bash
|
||||
# Test basic functionality
|
||||
markitect --help
|
||||
markitect version
|
||||
|
||||
# Test TDD tools
|
||||
tddai --help
|
||||
|
||||
# Test issue management
|
||||
issue --help
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
MarkiTect automatically installs these dependencies:
|
||||
|
||||
### Production Dependencies
|
||||
- markdown-it-py - Markdown parsing
|
||||
- PyYAML - YAML processing
|
||||
- click>=8.0.0 - CLI framework
|
||||
- tabulate>=0.9.0 - Table formatting
|
||||
- jsonpath-ng>=1.5.0 - JSONPath queries
|
||||
- aiohttp>=3.8.0 - Async HTTP client
|
||||
- toml - TOML file parsing
|
||||
|
||||
### Development Dependencies (with --dev)
|
||||
- pytest - Testing framework
|
||||
- pytest-cov - Test coverage
|
||||
- black - Code formatting
|
||||
- flake8 - Code linting
|
||||
- mypy - Type checking
|
||||
|
||||
## System Requirements
|
||||
|
||||
- Python 3.8 or higher
|
||||
- pip (Python package installer)
|
||||
- git (optional, for version info)
|
||||
- Unix-like system (Linux, macOS) or Windows with Python support
|
||||
|
||||
## Support
|
||||
|
||||
For installation issues:
|
||||
|
||||
1. Check this guide first
|
||||
2. Run `./install.sh --check` to diagnose problems
|
||||
3. See the main project documentation
|
||||
4. Report issues on the project issue tracker
|
||||
32
LICENSE.md
32
LICENSE.md
@@ -1,32 +0,0 @@
|
||||
# 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.
|
||||
119
Makefile
119
Makefile
@@ -25,7 +25,9 @@ help:
|
||||
@echo " venv-status - Check if venv is active"
|
||||
@echo ""
|
||||
@echo "Development:"
|
||||
@echo " test - Run all tests"
|
||||
@echo " test - Run core tests (excluding capability-specific tests)"
|
||||
@echo " test-capabilities - Run all capability-specific tests"
|
||||
@echo " test-capability-* - Run specific capability tests (content, utils, finance, etc.)"
|
||||
@echo " test-status - Show test status summary without re-running"
|
||||
@echo " test-new - Create new test file template"
|
||||
@echo " test-coverage - Analyze test coverage"
|
||||
@@ -81,11 +83,17 @@ help:
|
||||
@echo " status - Show git status for repo and submodules"
|
||||
@echo " clean - Clean build artifacts"
|
||||
@echo " check-deps - Check dependency status"
|
||||
@echo " validate-js - Validate JavaScript syntax in templates"
|
||||
@echo ""
|
||||
@echo "Documentation:"
|
||||
@echo " update-digest - Update ProjectStatusDigest.md (requires Claude Code)"
|
||||
@echo " add-diary-entry - Add new entry to ProjectDiary.md (requires Claude Code)"
|
||||
@echo ""
|
||||
@echo "Capability Management:"
|
||||
@echo " capability-report - Generate capability discovery report"
|
||||
@echo " capability-search TERM=xyz - Search for functionality across capabilities"
|
||||
@echo " capability-validate FILE=path - Validate proper capability usage in file"
|
||||
@echo ""
|
||||
@echo ""
|
||||
@echo "Requirements Engineering:"
|
||||
@echo " validate-requirements - Analyze foundations before development"
|
||||
@@ -315,25 +323,77 @@ setup-dev: install-dev
|
||||
|
||||
# Run tests
|
||||
test: $(VENV)/bin/activate
|
||||
@echo "🧪 Running tests..."
|
||||
@echo "🧪 Running core tests (excluding capability-specific tests)..."
|
||||
@if [ -f $(VENV)/bin/pytest ]; then \
|
||||
PYTHONPATH=. $(VENV)/bin/pytest tests/ -v; \
|
||||
PYTHONPATH=. $(VENV)/bin/pytest tests/ -v \
|
||||
--ignore=capabilities/markitect-content/tests/ \
|
||||
--ignore=capabilities/markitect-utils/tests/ \
|
||||
--ignore=markitect/finance/tests/ \
|
||||
--ignore=markitect/query_paradigms/tests/ \
|
||||
--ignore=markitect/graphql/tests/ \
|
||||
--ignore=markitect/plugins/tests/; \
|
||||
else \
|
||||
PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ -v 2>/dev/null || \
|
||||
PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ -v \
|
||||
--ignore=capabilities/markitect-content/tests/ \
|
||||
--ignore=capabilities/markitect-utils/tests/ \
|
||||
--ignore=markitect/finance/tests/ \
|
||||
--ignore=markitect/query_paradigms/tests/ \
|
||||
--ignore=markitect/graphql/tests/ \
|
||||
--ignore=markitect/plugins/tests/ 2>/dev/null || \
|
||||
PYTHONPATH=. $(VENV_PYTHON) -m unittest discover tests/ -v; \
|
||||
fi
|
||||
|
||||
# Capability-Specific Test Targets
|
||||
test-capabilities: test-capability-content test-capability-utils test-capability-finance test-capability-query test-capability-graphql test-capability-plugins
|
||||
@echo "✅ All capability tests completed"
|
||||
|
||||
test-capability-content: $(VENV)/bin/activate
|
||||
@echo "🧪 Running markitect-content capability tests..."
|
||||
@cd capabilities/markitect-content && python -m pytest tests/ -v
|
||||
|
||||
test-capability-utils: $(VENV)/bin/activate
|
||||
@echo "🧪 Running markitect-utils capability tests..."
|
||||
@cd capabilities/markitect-utils && python -m pytest tests/ -v
|
||||
|
||||
test-capability-finance: $(VENV)/bin/activate
|
||||
@echo "🧪 Running finance capability tests..."
|
||||
@PYTHONPATH=. $(VENV_PYTHON) -m pytest markitect/finance/tests/ -v
|
||||
|
||||
test-capability-query: $(VENV)/bin/activate
|
||||
@echo "🧪 Running query paradigms capability tests..."
|
||||
@PYTHONPATH=. $(VENV_PYTHON) -m pytest markitect/query_paradigms/tests/ -v
|
||||
|
||||
test-capability-graphql: $(VENV)/bin/activate
|
||||
@echo "🧪 Running GraphQL capability tests..."
|
||||
@PYTHONPATH=. $(VENV_PYTHON) -m pytest markitect/graphql/tests/ -v
|
||||
|
||||
test-capability-plugins: $(VENV)/bin/activate
|
||||
@echo "🧪 Running plugins capability tests..."
|
||||
@PYTHONPATH=. $(VENV_PYTHON) -m pytest markitect/plugins/tests/ -v
|
||||
|
||||
# TDD8 Workflow Optimized Test Targets (Issue #57)
|
||||
|
||||
# Fast test execution for TDD red phase
|
||||
test-red: $(VENV)/bin/activate
|
||||
@echo "🔴 TDD Red Phase - Fast test execution..."
|
||||
PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ -x --maxfail=1 --tb=short -q
|
||||
PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ -x --maxfail=1 --tb=short -q \
|
||||
--ignore=capabilities/markitect-content/tests/ \
|
||||
--ignore=capabilities/markitect-utils/tests/ \
|
||||
--ignore=markitect/finance/tests/ \
|
||||
--ignore=markitect/query_paradigms/tests/ \
|
||||
--ignore=markitect/graphql/tests/ \
|
||||
--ignore=markitect/plugins/tests/
|
||||
|
||||
# Comprehensive test execution for TDD green phase
|
||||
test-green: $(VENV)/bin/activate
|
||||
@echo "🟢 TDD Green Phase - Comprehensive validation..."
|
||||
PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ --tb=short
|
||||
PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ --tb=short \
|
||||
--ignore=capabilities/markitect-content/tests/ \
|
||||
--ignore=capabilities/markitect-utils/tests/ \
|
||||
--ignore=markitect/finance/tests/ \
|
||||
--ignore=markitect/query_paradigms/tests/ \
|
||||
--ignore=markitect/graphql/tests/ \
|
||||
--ignore=markitect/plugins/tests/
|
||||
|
||||
# Smart test selection - changed files only
|
||||
test-smart: $(VENV)/bin/activate
|
||||
@@ -349,12 +409,24 @@ test-smart: $(VENV)/bin/activate
|
||||
# Ultra-fast test execution
|
||||
test-ultra-fast: $(VENV)/bin/activate
|
||||
@echo "⚡ Ultra-fast test execution..."
|
||||
PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ -m "not slow" --maxfail=1 -x -q
|
||||
PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ -m "not slow" --maxfail=1 -x -q \
|
||||
--ignore=capabilities/markitect-content/tests/ \
|
||||
--ignore=capabilities/markitect-utils/tests/ \
|
||||
--ignore=markitect/finance/tests/ \
|
||||
--ignore=markitect/query_paradigms/tests/ \
|
||||
--ignore=markitect/graphql/tests/ \
|
||||
--ignore=markitect/plugins/tests/
|
||||
|
||||
# Test with performance monitoring
|
||||
test-perf: $(VENV)/bin/activate
|
||||
@echo "📊 Test execution with performance monitoring..."
|
||||
PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ --durations=10 --tb=short
|
||||
PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ --durations=10 --tb=short \
|
||||
--ignore=capabilities/markitect-content/tests/ \
|
||||
--ignore=capabilities/markitect-utils/tests/ \
|
||||
--ignore=markitect/finance/tests/ \
|
||||
--ignore=markitect/query_paradigms/tests/ \
|
||||
--ignore=markitect/graphql/tests/ \
|
||||
--ignore=markitect/plugins/tests/
|
||||
|
||||
# Test health check
|
||||
test-health: $(VENV)/bin/activate
|
||||
@@ -545,6 +617,27 @@ add-diary-entry:
|
||||
@echo ""
|
||||
@echo "💡 Tip: New entries are added to the top for reverse chronological order"
|
||||
|
||||
# Capability discovery and management targets
|
||||
capability-report: $(VENV)/bin/activate
|
||||
@echo "📋 Generating capability discovery report..."
|
||||
@$(VENV_PYTHON) tools/capability_discovery.py report
|
||||
|
||||
capability-search: $(VENV)/bin/activate
|
||||
@if [ -z "$(TERM)" ]; then \
|
||||
echo "❌ Please specify search term: make capability-search TERM=issue_management"; \
|
||||
exit 1; \
|
||||
fi
|
||||
@echo "🔍 Searching for '$(TERM)' across capabilities..."
|
||||
@$(VENV_PYTHON) tools/capability_discovery.py search "$(TERM)"
|
||||
|
||||
capability-validate: $(VENV)/bin/activate
|
||||
@if [ -z "$(FILE)" ]; then \
|
||||
echo "❌ Please specify file path: make capability-validate FILE=path/to/file.py"; \
|
||||
exit 1; \
|
||||
fi
|
||||
@echo "✅ Validating capability usage in $(FILE)..."
|
||||
@$(VENV_PYTHON) tools/capability_discovery.py validate "$(FILE)"
|
||||
|
||||
# Git repository and API configuration
|
||||
GITEA_URL := http://92.205.130.254:32166
|
||||
|
||||
@@ -1248,3 +1341,13 @@ cost-help:
|
||||
@echo "💰 Currency: Costs calculated in USD and EUR"
|
||||
@echo "🤖 Model: Default claude-sonnet-4 pricing"
|
||||
|
||||
# JavaScript validation for edit mode templates
|
||||
validate-js: $(VENV)/bin/activate
|
||||
@echo "🔍 Validating JavaScript syntax in templates..."
|
||||
@if command -v node >/dev/null 2>&1; then \
|
||||
$(PYTHON) tools/validate_js_syntax.py; \
|
||||
else \
|
||||
echo "⚠️ Node.js not available - skipping JavaScript validation"; \
|
||||
echo " Install Node.js to enable JavaScript syntax checking"; \
|
||||
fi
|
||||
|
||||
|
||||
21
README.md
21
README.md
@@ -1,21 +0,0 @@
|
||||
MarkiTect - Advanced Markdown Engine
|
||||
|
||||
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.
|
||||
|
||||
**Key Features:**
|
||||
- **Lightning Performance**: 60-85% faster document processing through intelligent AST caching
|
||||
- **Schema Validation**: Enforce document structure and consistency
|
||||
- **Database Integration**: Query markdown content with SQL-like operations
|
||||
- **CLI Tools**: Complete command-line interface for automation and workflows
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
**Quick Start:** [Getting Started](#getting-started) · [Command Reference](docs/user-guides/cache-management.md)
|
||||
|
||||
**Architecture:** [Caching System](docs/architecture/caching-system.md) · [Performance Philosophy](docs/#performance-philosophy)
|
||||
|
||||
**Development:** [TDD Workflow](docs/development/tdd-workflow.md) · [Contributing](#contributing)
|
||||
|
||||
**Project Status:** [Current Status](history/ProjectStatusDigest.md) · [Roadmap](history/ROADMAP.md) · [Next Actions](NEXT.md)
|
||||
332
RELEASE.md
332
RELEASE.md
@@ -1,332 +0,0 @@
|
||||
# MarkiTect Release Process
|
||||
|
||||
This document describes the release process for MarkiTect, including versioning strategy, automation tools, and distribution guidelines.
|
||||
|
||||
## Quick Start
|
||||
|
||||
The simplest way to create a release:
|
||||
|
||||
```bash
|
||||
# 1. Prepare the release
|
||||
make release-prepare VERSION=1.0.0
|
||||
|
||||
# 2. Review and commit changes
|
||||
git add -A && git commit -m "Prepare release 1.0.0"
|
||||
|
||||
# 3. Publish the release
|
||||
make release-publish VERSION=1.0.0
|
||||
```
|
||||
|
||||
## Release Commands
|
||||
|
||||
### Status and Validation
|
||||
|
||||
```bash
|
||||
# Check current release status
|
||||
make release-status
|
||||
|
||||
# Validate repository for release
|
||||
make release-validate
|
||||
```
|
||||
|
||||
### Release Preparation
|
||||
|
||||
```bash
|
||||
# Prepare a new release (updates version, changelog)
|
||||
make release-prepare VERSION=x.y.z
|
||||
|
||||
# Test preparation without making changes
|
||||
make release-dry-run VERSION=x.y.z
|
||||
```
|
||||
|
||||
### Building and Publishing
|
||||
|
||||
```bash
|
||||
# Build release packages only
|
||||
make release-build [VERSION=x.y.z]
|
||||
|
||||
# Complete release (build + tag + publish)
|
||||
make release-publish VERSION=x.y.z
|
||||
```
|
||||
|
||||
## Versioning Strategy
|
||||
|
||||
MarkiTect follows [Semantic Versioning](https://semver.org/):
|
||||
|
||||
- **MAJOR.MINOR.PATCH** (e.g., 1.2.3)
|
||||
- **Pre-release**: MAJOR.MINOR.PATCH-{alpha|beta|rc}.N (e.g., 1.2.3-beta.1)
|
||||
|
||||
### Version Types
|
||||
|
||||
- **Major (X.0.0)**: Breaking changes, incompatible API changes
|
||||
- **Minor (x.Y.0)**: New features, backward compatible
|
||||
- **Patch (x.y.Z)**: Bug fixes, backward compatible
|
||||
- **Pre-release**: Alpha, beta, or release candidate versions
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Major release
|
||||
make release-prepare VERSION=2.0.0
|
||||
|
||||
# Minor release
|
||||
make release-prepare VERSION=1.1.0
|
||||
|
||||
# Patch release
|
||||
make release-prepare VERSION=1.0.1
|
||||
|
||||
# Pre-release
|
||||
make release-prepare VERSION=1.1.0-beta.1
|
||||
```
|
||||
|
||||
## Release Validation
|
||||
|
||||
Before a release can be created, the following validations are performed:
|
||||
|
||||
### Required Conditions
|
||||
|
||||
1. **Clean Repository**: No uncommitted changes
|
||||
2. **Main Branch**: Must be on the `main` branch
|
||||
3. **Passing Tests**: All tests must pass
|
||||
4. **Valid Version**: Version must follow semantic versioning
|
||||
5. **Version Increment**: New version must be greater than current
|
||||
|
||||
### Override Validation
|
||||
|
||||
Use `--force` to override validation warnings:
|
||||
|
||||
```bash
|
||||
python release.py prepare --version 1.0.1 --force
|
||||
```
|
||||
|
||||
## Automated Release Process
|
||||
|
||||
### What `release-prepare` Does
|
||||
|
||||
1. **Version Update**: Updates `pyproject.toml` and `markitect/__version__.py`
|
||||
2. **Changelog Generation**: Creates/updates `CHANGELOG.md` from git commits
|
||||
3. **Validation**: Ensures repository is ready for release
|
||||
|
||||
### What `release-publish` Does
|
||||
|
||||
1. **Package Building**: Creates source distribution and wheel
|
||||
2. **Git Tagging**: Creates annotated git tag (e.g., `v1.0.0`)
|
||||
3. **Tag Push**: Pushes tag to remote repository
|
||||
|
||||
## Manual Release Process
|
||||
|
||||
If you prefer manual control:
|
||||
|
||||
### 1. Update Version
|
||||
|
||||
```bash
|
||||
# Edit pyproject.toml
|
||||
version = "1.0.0"
|
||||
|
||||
# Edit markitect/__version__.py
|
||||
__version__ = "1.0.0"
|
||||
```
|
||||
|
||||
### 2. Update Changelog
|
||||
|
||||
Edit `CHANGELOG.md` to add release notes for the new version.
|
||||
|
||||
### 3. Commit Changes
|
||||
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "Prepare release 1.0.0"
|
||||
```
|
||||
|
||||
### 4. Build Packages
|
||||
|
||||
```bash
|
||||
make release-build
|
||||
```
|
||||
|
||||
### 5. Create Git Tag
|
||||
|
||||
```bash
|
||||
git tag -a v1.0.0 -m "Release 1.0.0"
|
||||
git push origin v1.0.0
|
||||
```
|
||||
|
||||
## Distribution
|
||||
|
||||
### Package Types
|
||||
|
||||
MarkiTect releases include:
|
||||
|
||||
- **Source Distribution** (`.tar.gz`): Full source code package
|
||||
- **Wheel** (`.whl`): Pre-built binary package for faster installation
|
||||
|
||||
### Installation Methods
|
||||
|
||||
Users can install MarkiTect in several ways:
|
||||
|
||||
```bash
|
||||
# From PyPI (when published)
|
||||
pip install markitect
|
||||
|
||||
# From wheel file
|
||||
pip install markitect-1.0.0-py3-none-any.whl
|
||||
|
||||
# From source
|
||||
pip install markitect-1.0.0.tar.gz
|
||||
|
||||
# Development installation
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
### Release Artifacts
|
||||
|
||||
Each release creates:
|
||||
|
||||
- Source and wheel packages in `dist/`
|
||||
- Git tag (e.g., `v1.0.0`)
|
||||
- Updated `CHANGELOG.md`
|
||||
- Updated version files
|
||||
|
||||
## Changelog Format
|
||||
|
||||
The automated changelog generation categorizes commits:
|
||||
|
||||
### Commit Prefixes
|
||||
|
||||
- `feat:` or `feature:` → **Added** section
|
||||
- `fix:` or `bugfix:` → **Fixed** section
|
||||
- `docs:` or `doc:` → **Documentation** section
|
||||
- Other commits → **Other** section
|
||||
|
||||
### Example Changelog Entry
|
||||
|
||||
```markdown
|
||||
## [1.0.0] - 2025-10-03
|
||||
|
||||
### Added
|
||||
- feat: add template rendering system
|
||||
- feature: implement cache management commands
|
||||
|
||||
### Fixed
|
||||
- fix: resolve test isolation issues
|
||||
- bugfix: correct version information display
|
||||
|
||||
### Documentation
|
||||
- docs: add comprehensive installation guide
|
||||
- doc: update API documentation
|
||||
|
||||
### Other
|
||||
- chore: cleanup repository structure
|
||||
- refactor: improve code organization
|
||||
```
|
||||
|
||||
## Release Checklist
|
||||
|
||||
### Pre-Release
|
||||
|
||||
- [ ] All tests passing (`make test`)
|
||||
- [ ] No uncommitted changes
|
||||
- [ ] On `main` branch
|
||||
- [ ] Version number decided
|
||||
- [ ] Release notes ready
|
||||
|
||||
### Release Process
|
||||
|
||||
- [ ] Run `make release-prepare VERSION=x.y.z`
|
||||
- [ ] Review generated changelog
|
||||
- [ ] Commit changes
|
||||
- [ ] Run `make release-publish VERSION=x.y.z`
|
||||
- [ ] Verify packages created
|
||||
- [ ] Verify git tag created
|
||||
|
||||
### Post-Release
|
||||
|
||||
- [ ] Packages available in `dist/`
|
||||
- [ ] Git tag pushed to remote
|
||||
- [ ] Changelog updated
|
||||
- [ ] Version information correct
|
||||
- [ ] Installation tested
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Validation Failures**
|
||||
```bash
|
||||
# Check what's wrong
|
||||
make release-validate
|
||||
|
||||
# Force release if needed
|
||||
python release.py prepare --version 1.0.0 --force
|
||||
```
|
||||
|
||||
2. **Build Failures**
|
||||
```bash
|
||||
# Install build dependencies
|
||||
pip install build
|
||||
|
||||
# Clean and rebuild
|
||||
rm -rf dist/ build/
|
||||
make release-build
|
||||
```
|
||||
|
||||
3. **Git Issues**
|
||||
```bash
|
||||
# Check git status
|
||||
git status
|
||||
|
||||
# Commit changes
|
||||
git add -A && git commit -m "Prepare release"
|
||||
```
|
||||
|
||||
4. **Version Conflicts**
|
||||
```bash
|
||||
# Check current version
|
||||
make release-status
|
||||
|
||||
# Use correct version number
|
||||
make release-prepare VERSION=1.0.1 # Must be > current
|
||||
```
|
||||
|
||||
### Getting Help
|
||||
|
||||
```bash
|
||||
# Release tool help
|
||||
python release.py --help
|
||||
|
||||
# Makefile targets
|
||||
make help
|
||||
|
||||
# Command-specific help
|
||||
python release.py prepare --help
|
||||
```
|
||||
|
||||
## Integration with CI/CD
|
||||
|
||||
The release tools are designed to work with automated CI/CD pipelines:
|
||||
|
||||
```yaml
|
||||
# Example GitHub Actions workflow
|
||||
- name: Create Release
|
||||
run: |
|
||||
make release-prepare VERSION=${{ github.event.inputs.version }}
|
||||
git add -A
|
||||
git commit -m "Prepare release ${{ github.event.inputs.version }}"
|
||||
make release-publish VERSION=${{ github.event.inputs.version }}
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- Release artifacts should be signed
|
||||
- Use trusted publishing methods
|
||||
- Verify package contents before distribution
|
||||
- Keep release tools and dependencies updated
|
||||
|
||||
## Support
|
||||
|
||||
For release-related issues:
|
||||
|
||||
1. Check this documentation
|
||||
2. Run `make release-status` for diagnostics
|
||||
3. Use `--dry-run` to test changes
|
||||
4. Report issues on the project tracker
|
||||
@@ -1,81 +0,0 @@
|
||||
# MarkiTect v0.2.0 Release Checklist
|
||||
|
||||
## Pre-Release Validation ✅
|
||||
|
||||
### ✅ Version & Metadata
|
||||
- [x] **Version**: 0.2.0 (in pyproject.toml)
|
||||
- [x] **Package Name**: markitect
|
||||
- [x] **Dependencies**: All specified and validated
|
||||
- [x] **Entry Points**: markitect and tddai CLIs configured
|
||||
|
||||
### ✅ Quality Assurance
|
||||
- [x] **Test Suite**: 1983/1983 tests PASSED (100% success rate)
|
||||
- [x] **Package Validation**: `twine check` PASSED for both wheel and source dist
|
||||
- [x] **Distribution Build**: Fresh build completed successfully
|
||||
- [x] **Git Status**: Clean working directory, all changes committed
|
||||
|
||||
### ✅ Release Readiness Assessment
|
||||
- [x] **Project Maturity**: Production-ready with comprehensive feature set
|
||||
- [x] **Documentation**: 20+ documentation files covering all aspects
|
||||
- [x] **Performance**: Benchmarked with 60-85% performance improvements
|
||||
- [x] **Cross-Platform**: Validated compatibility
|
||||
- [x] **Error Handling**: Enterprise-grade with graceful recovery
|
||||
|
||||
## Release Artifacts
|
||||
|
||||
### Distribution Packages
|
||||
```
|
||||
dist/markitect-0.2.0-py3-none-any.whl (593,967 bytes)
|
||||
dist/markitect-0.2.0.tar.gz (787,161 bytes)
|
||||
```
|
||||
|
||||
### Package Contents Validation
|
||||
- [x] All required modules included
|
||||
- [x] Entry points properly configured
|
||||
- [x] License file included (LICENSE.md)
|
||||
- [x] README.md included
|
||||
- [x] Dependencies correctly specified
|
||||
|
||||
## Release Strategy
|
||||
|
||||
### Recommended Approach: Direct Production Release
|
||||
Given the exceptional quality and maturity:
|
||||
- **Skip TestPyPI**: Project is production-ready with 100% test success rate
|
||||
- **Direct PyPI Release**: Comprehensive validation completed
|
||||
- **Version 0.2.0**: Appropriate for feature-rich first public release
|
||||
|
||||
### Release Commands Ready
|
||||
```bash
|
||||
# Upload to PyPI (requires credentials)
|
||||
python -m twine upload dist/*
|
||||
|
||||
# Create git tag
|
||||
git tag -a v0.2.0 -m "Release v0.2.0: Advanced Markdown Engine"
|
||||
git push origin v0.2.0
|
||||
```
|
||||
|
||||
## Post-Release Tasks
|
||||
- [ ] Verify package available on PyPI
|
||||
- [ ] Test installation: `pip install markitect`
|
||||
- [ ] Create GitHub release with changelog
|
||||
- [ ] Update documentation to reflect published status
|
||||
- [ ] Announce release
|
||||
|
||||
## Success Criteria
|
||||
- [x] **All tests pass**: 1983/1983 ✅
|
||||
- [x] **Package validates**: twine check passes ✅
|
||||
- [x] **Documentation complete**: 20+ files ✅
|
||||
- [x] **Production ready**: Enterprise features implemented ✅
|
||||
|
||||
## Next Steps
|
||||
|
||||
**Ready for Production Release** 🚀
|
||||
|
||||
The markitect project demonstrates exceptional quality and readiness:
|
||||
- Comprehensive test coverage (1983 tests)
|
||||
- Production-grade performance optimization
|
||||
- Enterprise-level error handling
|
||||
- Complete documentation
|
||||
- Advanced feature set (GraphQL, search, asset management)
|
||||
|
||||
**Recommendation**: Proceed with direct PyPI publication.
|
||||
@@ -1,134 +0,0 @@
|
||||
# MarkiTect v0.2.0 Release Completion Report
|
||||
|
||||
## 🎉 Release Preparation: COMPLETE
|
||||
|
||||
**Date:** 2025-10-20
|
||||
**Version:** 0.2.0
|
||||
**Status:** ✅ **READY FOR PYPI PUBLICATION**
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The first official release of MarkiTect has been successfully prepared with exceptional quality and production readiness. All validation, testing, documentation, and packaging tasks have been completed to enterprise standards.
|
||||
|
||||
## Release Achievements
|
||||
|
||||
### 🔬 **Quality Validation: PERFECT**
|
||||
- **1983/1983 tests passing** (100% success rate)
|
||||
- **twine package validation** PASSED for all distributions
|
||||
- **Production validation suite** completed with flying colors
|
||||
- **Cross-platform compatibility** confirmed (Unix/Windows/macOS)
|
||||
|
||||
### 📦 **Package Preparation: COMPLETE**
|
||||
- **Distribution packages built** and validated:
|
||||
- `markitect-0.2.0-py3-none-any.whl` (593,967 bytes)
|
||||
- `markitect-0.2.0.tar.gz` (787,161 bytes)
|
||||
- **Package metadata verified** with proper entry points
|
||||
- **License and documentation** properly included
|
||||
|
||||
### 📚 **Documentation Excellence**
|
||||
- **Comprehensive CHANGELOG.md** with detailed v0.2.0 features
|
||||
- **Release checklist** completed and validated
|
||||
- **PyPI upload instructions** prepared and ready
|
||||
- **Post-release task documentation** created
|
||||
|
||||
### 🏷️ **Version Management**
|
||||
- **Git tag v0.2.0** created with detailed release notes
|
||||
- **Release commit** with comprehensive feature summary
|
||||
- **Version synchronization** across all project files
|
||||
|
||||
## Technical Highlights
|
||||
|
||||
### 🚀 **Production-Ready Features**
|
||||
- **Advanced asset management** with content-addressable storage
|
||||
- **60-85% performance improvement** through AST caching
|
||||
- **Enterprise error handling** with graceful recovery
|
||||
- **GraphQL interface** for advanced querying
|
||||
- **Full-text search** with FTS5 optimization
|
||||
|
||||
### 🛠️ **Developer Experience**
|
||||
- **17 kaizen-agentic agents** for enhanced productivity
|
||||
- **Unified CLI interface** with consolidated commands
|
||||
- **Plugin architecture** with extensible framework
|
||||
- **14 query paradigms** for flexible data access
|
||||
|
||||
### 📊 **Quality Metrics**
|
||||
- **1983 comprehensive tests** covering all functionality layers
|
||||
- **100% test success rate** with zero failures
|
||||
- **Production validation** with performance benchmarking
|
||||
- **Type safety** and security validation implemented
|
||||
|
||||
## Release Readiness Confirmation
|
||||
|
||||
### ✅ **All Success Criteria Met**
|
||||
- [x] **Quality**: 100% test success rate achieved
|
||||
- [x] **Performance**: 60-85% improvement validated
|
||||
- [x] **Features**: All enterprise features implemented and tested
|
||||
- [x] **Documentation**: 20+ comprehensive files completed
|
||||
- [x] **Packaging**: Distribution packages built and validated
|
||||
- [x] **Compatibility**: Cross-platform validation completed
|
||||
|
||||
### 📋 **Release Checklist: COMPLETE**
|
||||
- [x] Version management and synchronization
|
||||
- [x] Comprehensive test suite execution
|
||||
- [x] Package building and validation
|
||||
- [x] Documentation updates and changelog
|
||||
- [x] Git tagging and commit preparation
|
||||
- [x] PyPI upload command preparation
|
||||
- [x] Post-release task documentation
|
||||
|
||||
## What's Ready for Publication
|
||||
|
||||
### 📤 **Immediate PyPI Upload Ready**
|
||||
The following command will publish MarkiTect v0.2.0 to PyPI:
|
||||
```bash
|
||||
python -m twine upload dist/*
|
||||
```
|
||||
|
||||
### 🏆 **World-Class Package Quality**
|
||||
- **Enterprise-grade codebase** with professional architecture
|
||||
- **Comprehensive feature set** exceeding typical markdown processors
|
||||
- **Exceptional documentation** with user and developer guides
|
||||
- **Production validation** with performance optimization
|
||||
- **Zero technical debt** in release candidate
|
||||
|
||||
## Impact & Significance
|
||||
|
||||
This release represents a **major milestone** in the MarkiTect project:
|
||||
|
||||
1. **First Public Release**: Transition from private development to public availability
|
||||
2. **Production Readiness**: Enterprise-grade quality with 100% test success
|
||||
3. **Advanced Capabilities**: Features that differentiate from basic markdown tools
|
||||
4. **Developer Experience**: Integration with modern development workflows
|
||||
5. **Performance Excellence**: Significant optimization achievements
|
||||
|
||||
## Next Actions Required
|
||||
|
||||
To complete the release:
|
||||
|
||||
1. **Execute PyPI Upload**: Run `python -m twine upload dist/*` (requires PyPI credentials)
|
||||
2. **Verify Publication**: Check https://pypi.org/project/markitect/
|
||||
3. **Create GitHub Release**: Use release artifacts and documentation
|
||||
4. **Update Project Status**: Mark as "published" in relevant documentation
|
||||
5. **Announce Release**: Communicate availability to target audiences
|
||||
|
||||
## Conclusion
|
||||
|
||||
**MarkiTect v0.2.0 is exceptionally well-prepared for its first official release.** The project demonstrates:
|
||||
|
||||
- **Production-grade quality** with comprehensive testing and validation
|
||||
- **Advanced feature set** with enterprise capabilities
|
||||
- **Professional documentation** and release management
|
||||
- **Performance excellence** with significant optimization achievements
|
||||
- **Developer-friendly experience** with modern tooling integration
|
||||
|
||||
**Release Confidence Level: 100%** 🎯
|
||||
|
||||
The only remaining step is the PyPI upload command execution. All preparation, validation, and documentation work has been completed to the highest standards.
|
||||
|
||||
**🚀 MarkiTect is ready to launch! 🌟**
|
||||
|
||||
---
|
||||
|
||||
**Release Preparation Completed by:** kaizen-agentic release management system
|
||||
**Final Validation:** All criteria exceeded expectations
|
||||
**Recommendation:** Proceed with immediate PyPI publication
|
||||
@@ -1,136 +0,0 @@
|
||||
# MarkiTect v0.2.0 Release Instructions
|
||||
|
||||
## Release Status: ✅ READY FOR PUBLICATION
|
||||
|
||||
All preparation completed successfully:
|
||||
- ✅ **1983/1983 tests passing** (100% success rate)
|
||||
- ✅ **Distribution packages built** and validated with twine
|
||||
- ✅ **Documentation updated** with comprehensive v0.2.0 changelog
|
||||
- ✅ **Git tag created** (v0.2.0) with release notes
|
||||
- ✅ **Release checklist completed** with full validation
|
||||
|
||||
## PyPI Publication Commands
|
||||
|
||||
### Step 1: Verify Package Quality
|
||||
```bash
|
||||
# Already completed ✅
|
||||
python -m twine check dist/*
|
||||
# Result: PASSED for both wheel and source distribution
|
||||
```
|
||||
|
||||
### Step 2: Upload to PyPI
|
||||
```bash
|
||||
# Upload to production PyPI (requires PyPI credentials)
|
||||
python -m twine upload dist/*
|
||||
|
||||
# Alternative: Upload with explicit repository
|
||||
python -m twine upload --repository pypi dist/*
|
||||
```
|
||||
|
||||
### Step 3: Verify Publication
|
||||
```bash
|
||||
# Test installation from PyPI
|
||||
pip install markitect==0.2.0
|
||||
|
||||
# Verify installation
|
||||
markitect --version
|
||||
markitect --help
|
||||
```
|
||||
|
||||
## Git Repository Updates
|
||||
|
||||
### Push Release Changes
|
||||
```bash
|
||||
# Push commits and tags to origin
|
||||
git push origin main
|
||||
git push origin v0.2.0
|
||||
```
|
||||
|
||||
## Post-Publication Tasks
|
||||
|
||||
### 1. Verify PyPI Publication
|
||||
- [ ] Visit https://pypi.org/project/markitect/
|
||||
- [ ] Confirm v0.2.0 is available
|
||||
- [ ] Test installation: `pip install markitect`
|
||||
- [ ] Verify CLI functionality: `markitect --help`
|
||||
|
||||
### 2. Create GitHub Release
|
||||
```bash
|
||||
# Use GitHub CLI if available
|
||||
gh release create v0.2.0 dist/* \
|
||||
--title "MarkiTect v0.2.0 - Advanced Markdown Engine" \
|
||||
--notes-file RELEASE_NOTES.md
|
||||
```
|
||||
|
||||
### 3. Update Documentation
|
||||
- [ ] Update README.md installation instructions
|
||||
- [ ] Update documentation to reflect published status
|
||||
- [ ] Add PyPI badge to README.md
|
||||
|
||||
### 4. Announcement
|
||||
- [ ] Project announcement (if applicable)
|
||||
- [ ] Update project status documentation
|
||||
- [ ] Social media or community announcements
|
||||
|
||||
## Release Artifacts
|
||||
|
||||
### Distribution Packages (Ready for Upload)
|
||||
```
|
||||
dist/markitect-0.2.0-py3-none-any.whl (593,967 bytes)
|
||||
dist/markitect-0.2.0.tar.gz (787,161 bytes)
|
||||
```
|
||||
|
||||
### Package Metadata
|
||||
- **Name**: markitect
|
||||
- **Version**: 0.2.0
|
||||
- **License**: MIT (LICENSE.md included)
|
||||
- **Python**: >=3.8
|
||||
- **Entry Points**: `markitect` and `tddai` commands
|
||||
|
||||
## Release Notes Summary
|
||||
|
||||
**MarkiTect v0.2.0** represents the first official release of a production-ready advanced markdown engine featuring:
|
||||
|
||||
### 🚀 **Production Features**
|
||||
- Advanced asset management with content-addressable storage
|
||||
- 60-85% performance improvement through AST caching optimization
|
||||
- Enterprise-grade error handling with graceful recovery
|
||||
- Cross-platform validation (Unix/Windows/macOS)
|
||||
|
||||
### 🔧 **Developer Tools**
|
||||
- 17 kaizen-agentic development agents for enhanced productivity
|
||||
- Comprehensive CLI with unified command interface
|
||||
- TDD workflow tools with sophisticated test organization
|
||||
- Plugin architecture with extensible framework
|
||||
|
||||
### 📊 **Data & Querying**
|
||||
- GraphQL interface for advanced querying capabilities
|
||||
- Full-text search with FTS5 backend optimization
|
||||
- 14 different query paradigms for flexible data access
|
||||
- Cost management and activity tracking systems
|
||||
|
||||
### 📚 **Documentation & Quality**
|
||||
- 1983 comprehensive tests with 100% success rate
|
||||
- 20+ documentation files covering all aspects
|
||||
- Production validation suite with benchmarking
|
||||
- Type safety and security validation
|
||||
|
||||
## Success Criteria: ✅ ALL MET
|
||||
|
||||
- [x] **Quality Assurance**: 1983/1983 tests passing
|
||||
- [x] **Package Validation**: twine check passes for all distributions
|
||||
- [x] **Documentation**: Comprehensive documentation completed
|
||||
- [x] **Performance**: Benchmarked 60-85% improvement validated
|
||||
- [x] **Cross-Platform**: Unix/Windows/macOS compatibility confirmed
|
||||
- [x] **Enterprise Features**: Asset management, error handling, security
|
||||
- [x] **Developer Experience**: 17 agents, CLI tools, extensive testing
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Execute PyPI upload** using the commands above
|
||||
2. **Verify successful publication** on PyPI
|
||||
3. **Create GitHub release** with artifacts
|
||||
4. **Update project documentation** to reflect published status
|
||||
5. **Announce release** to relevant communities
|
||||
|
||||
**MarkiTect v0.2.0 is ready for the world! 🌟**
|
||||
341
TESTING.md
341
TESTING.md
@@ -1,341 +0,0 @@
|
||||
# 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/)
|
||||
@@ -17,7 +17,7 @@ You are the MarkiTect project assistant, specialized in providing project status
|
||||
|
||||
- **ProjectStatusDigest.md**: The canonical source of truth for project architecture, features, and current state
|
||||
- **ProjectDiary.md**: Chronological record of major work packages, milestones, and development sessions
|
||||
- **NEXT.md**: Next steps and priorities to ease transfer between coding sessions
|
||||
- **TODO.md**: Task management and priorities following Keep a Todofile format for maintaining coding flow
|
||||
- **Makefile**: Provides helpers to use and improve the capabilities provided by the project
|
||||
**Gitea Issues**: Backlog of issues and backlog of tasks stored as issues in gitea
|
||||
|
||||
@@ -26,13 +26,20 @@ You are the MarkiTect project assistant, specialized in providing project status
|
||||
**Repository Structure:**
|
||||
- Main project hosted on Gitea with issue tracking for use cases and tasks
|
||||
- Documentation maintained in `wiki/` submodule
|
||||
- Test-drive dev workflow with tests in `tests/` handled by tddai-assistent subagent
|
||||
- Test-driven development workflow with comprehensive test coverage
|
||||
|
||||
**Development Workflow:**
|
||||
- Issue-driven development using Gitea API integration
|
||||
- TDD8 methodology via tddai-assistant subagent for comprehensive test-driven development
|
||||
- Issue management via universal issue-facade CLI that works with multiple backends
|
||||
- All commits require green test state
|
||||
|
||||
**Capability Inclusion Management:**
|
||||
- **Internal Capabilities**: See `CAPABILITIES.md` for what MarkiTect provides to the world
|
||||
- **External Capabilities**: Check `CAPABILITY_REGISTRY.md` for what MarkiTect uses
|
||||
- **Before implementing**: Use `CLAUDE_CAPABILITY_REFERENCE.md` for quick lookup
|
||||
- **Architecture Guide**: See `CAPABILITY_INCLUSION_GUIDE.md` for complete workflow
|
||||
- **Discovery Tools**: `make capability-search TERM=xyz` to find existing functionality
|
||||
|
||||
**Issue Management Protocol:**
|
||||
- **Gitea-First**: Feature requests, bugs, and enhancements should be documented as Gitea issues
|
||||
- **Issue Creation**: When new requirements emerge, create issues in Gitea immediately but do NOT implement immediately
|
||||
@@ -41,8 +48,8 @@ You are the MarkiTect project assistant, specialized in providing project status
|
||||
- **Issue Workflow**: Create → Triage → Plan → Schedule → Implement → Close
|
||||
|
||||
**TDD Workflow Management:**
|
||||
- For all TDD-related guidance, workflow management, and test-driven development questions, use the **tddai-assistant** subagent
|
||||
- The tddai-assistant specializes in the TDD8 methodology (ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH cycle)
|
||||
- For issue management tasks, use the **issue-facade** system located in `capabilities/issue-facade/`
|
||||
- The issue-facade provides unified CLI for GitHub, GitLab, Gitea, and local SQLite backends
|
||||
- This includes sidequest management, test planning, and comprehensive development workflow guidance
|
||||
|
||||
### Response Guidelines
|
||||
@@ -118,7 +125,7 @@ When asked to help wrap up a development session, follow this standardized routi
|
||||
|
||||
### End-of-Session Checklist:
|
||||
1. **Update ProjectDiary.md**: Add entry documenting progress, challenges, and achievements
|
||||
2. **Update NEXT.md**: Set clear priorities and strategy for next session
|
||||
2. **Update TODO.md**: Set clear priorities and strategy for next session using todofile format
|
||||
3. **Update ProjectStatusDigest.md**: Refresh current status, metrics, and completed features
|
||||
4. **Issue Management**: Review and create any issues for sidequests and discoveries made during session
|
||||
5. **Anchor patterns**: Update this project-assistant definition with any new workflow patterns
|
||||
|
||||
@@ -115,8 +115,9 @@ python tools/requirements_engineering_toolkit.py validate-mocks --test-file test
|
||||
|
||||
```makefile
|
||||
# Enhanced Makefile targets
|
||||
tdd-start: validate-requirements
|
||||
python tddai_cli.py tdd-start $(NUM)
|
||||
issue-start: validate-requirements
|
||||
# Use issue-facade for issue management
|
||||
cd capabilities/issue-facade && python -m cli.main show $(NUM)
|
||||
|
||||
validate-requirements:
|
||||
python tools/requirements_engineering_toolkit.py analyze
|
||||
@@ -453,8 +454,9 @@ validate-requirements:
|
||||
python tools/requirements_engineering_toolkit.py analyze
|
||||
python tools/requirements_engineering_toolkit.py validate-mocks
|
||||
|
||||
tdd-start: validate-requirements
|
||||
python tddai_cli.py tdd-start $(NUM)
|
||||
issue-start: validate-requirements
|
||||
# Use issue-facade for issue management
|
||||
cd capabilities/issue-facade && python -m cli.main show $(NUM)
|
||||
```
|
||||
|
||||
### Tool Dependencies
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
---
|
||||
name: tddai-assistant
|
||||
description: Expert guidance for the TDD8 workflow methodology, specializing in the comprehensive ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH cycle with sophisticated sidequest management and proper test organization.
|
||||
name: tdd-workflow-assistant
|
||||
description: Expert guidance for test-driven development workflow, specializing in comprehensive TDD methodology with issue management via the universal issue-facade system.
|
||||
---
|
||||
|
||||
# TDDAi Assistant Agent
|
||||
# TDD Workflow Assistant Agent
|
||||
|
||||
## Mission
|
||||
Expert guidance for the TDD8 workflow methodology, specializing in the comprehensive ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH cycle with sophisticated sidequest management and proper test organization.
|
||||
Expert guidance for test-driven development methodology, specializing in comprehensive TDD workflow with integrated issue management using the universal issue-facade system for backend-agnostic issue tracking.
|
||||
|
||||
## The TDD8 Cycle Framework
|
||||
|
||||
@@ -96,22 +96,27 @@ The **TDD8 cycle** is an 8-step comprehensive development workflow that extends
|
||||
## Capabilities
|
||||
|
||||
### Core TDD8 Workflow Expertise
|
||||
You are the authoritative guide for the TDD8 workflow using the tddai system. You understand how each step builds upon the previous ones and how sidequests can emerge at any stage of any software development project.
|
||||
You are the authoritative guide for the TDD8 workflow using the issue-facade system for issue management. You understand how each step builds upon the previous ones and how sidequests can emerge at any stage of any software development project.
|
||||
|
||||
**Primary TDD Commands:**
|
||||
- `make tdd-start NUM=X` - Start working on an issue (creates workspace)
|
||||
- `make tdd-add-test` - Add test to current issue workspace
|
||||
- `make tdd-status` - Show current workspace state
|
||||
- `make tdd-finish` - Complete issue work (moves tests to main)
|
||||
**Primary Issue Management Commands:**
|
||||
- Issue management via issue-facade: `cd capabilities/issue-facade && python -m cli.main list`
|
||||
- `cd capabilities/issue-facade && python -m cli.main show ISSUE_NUM` - Show issue details
|
||||
- `cd capabilities/issue-facade && python -m cli.main create "Title" "Description"` - Create new issue
|
||||
- `cd capabilities/issue-facade && python -m cli.main close ISSUE_NUM` - Close completed issue
|
||||
|
||||
**Capability Awareness:**
|
||||
- **Before implementing**: Check `CAPABILITY_REGISTRY.md` for existing functionality
|
||||
- **Use existing capabilities**: Never reimplement issue management, content parsing, or utilities
|
||||
- **Capability discovery**: Use `make capability-search TERM=function_name` to find existing implementations
|
||||
|
||||
**Supporting Commands:**
|
||||
- `make test-coverage NUM=X` - Analyze test coverage for an issue
|
||||
- `make test-coverage` - Analyze test coverage
|
||||
- `make test` - Run all tests
|
||||
- `make list-issues` - Show all Gitea issues with status
|
||||
- `make show-issue NUM=X` - Show detailed view of specific issue
|
||||
- Tea CLI: `tea issues list` - Show all Gitea issues with status
|
||||
- Tea CLI: `tea issue show NUM` - Show detailed view of specific issue
|
||||
|
||||
### Workspace Management Understanding
|
||||
You understand the workspace structure (default: `.tddai_workspace/`, configurable per project):
|
||||
You understand the project structure with capabilities/issue-facade for issue management:
|
||||
```
|
||||
{workspace_dir}/
|
||||
├── current_issue.json # Active issue metadata
|
||||
@@ -152,7 +157,7 @@ You understand the workspace structure (default: `.tddai_workspace/`, configurab
|
||||
|
||||
### TDDAi Framework Components
|
||||
**Core Infrastructure:**
|
||||
- `tddai/` - TDD workflow framework
|
||||
- `capabilities/issue-facade/` - Universal issue management facade
|
||||
- `workspace.py` - Workspace management
|
||||
- `issue_fetcher.py` - Issue API integration
|
||||
- `issue_writer.py` - Issue updates via PATCH
|
||||
|
||||
1
capabilities/issue-facade
Submodule
1
capabilities/issue-facade
Submodule
Submodule capabilities/issue-facade added at 51aea5effb
1
capabilities/kaizen-agentic
Submodule
1
capabilities/kaizen-agentic
Submodule
Submodule capabilities/kaizen-agentic added at 1e0ff82d74
@@ -35,7 +35,7 @@ Documentation for contributors and developers extending MarkiTect.
|
||||
### Project Management
|
||||
- [Project Status](../history/ProjectStatusDigest.md) - Current development status
|
||||
- [Roadmap](../history/ROADMAP.md) - Strategic development plan
|
||||
- [Next Actions](../NEXT.md) - Immediate development priorities
|
||||
- [Current Tasks](../TODO.md) - Task management using Keep a Todofile format
|
||||
|
||||
## Key Concepts
|
||||
|
||||
|
||||
124
history/NEXT_archived_20251025.md
Normal file
124
history/NEXT_archived_20251025.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# MarkiTect - Next Session Priorities
|
||||
|
||||
**Updated:** 2025-10-25
|
||||
**Status:** Capability Inclusion Management System Complete
|
||||
**Next Focus:** Strategic Development Execution
|
||||
|
||||
## High Priority (Next Session Focus)
|
||||
|
||||
### 1. Strategic Issue Resolution 🎯
|
||||
**Priority: CRITICAL**
|
||||
- Resume work on core functionality backlog
|
||||
- Target: Issue #15 (AST Query and Analysis CLI) or Issue #16 (Performance Validation CLI)
|
||||
- Use new capability inclusion workflow to prevent duplication
|
||||
- Leverage CLAUDE_CAPABILITY_REFERENCE.md for quick capability lookup
|
||||
|
||||
### 2. Capability Management Validation 🔍
|
||||
**Priority: HIGH**
|
||||
- Test the new discovery tools (`make capability-search TERM=xyz`) in real development
|
||||
- Validate workflow effectiveness during actual implementation
|
||||
- Refine documentation based on practical usage
|
||||
- Ensure AI assistants properly utilize the new capability references
|
||||
|
||||
### 3. Documentation Integration ✅
|
||||
**Priority: MEDIUM**
|
||||
- Update any missing links in existing documentation to new capability system
|
||||
- Ensure all agents are aware of capability inclusion workflow
|
||||
- Validate that CAPABILITY_DOCUMENTATION_INDEX.md provides effective navigation
|
||||
|
||||
## Development Strategy
|
||||
|
||||
### Capability-First Development
|
||||
1. **Before implementing anything new:**
|
||||
- Check CAPABILITIES.md for internal capabilities
|
||||
- Check CAPABILITY_REGISTRY.md for external capabilities
|
||||
- Use `make capability-search TERM=xyz` for discovery
|
||||
- Consult CLAUDE_CAPABILITY_REFERENCE.md for patterns
|
||||
|
||||
2. **During implementation:**
|
||||
- Update capability documentation if creating new capabilities
|
||||
- Follow CAPABILITY_INCLUSION_GUIDE.md workflow
|
||||
- Document any new external dependencies in CAPABILITY_REGISTRY.md
|
||||
|
||||
3. **After implementation:**
|
||||
- Update CAPABILITIES.md if internal capabilities were added
|
||||
- Ensure proper categorization in documentation ecosystem
|
||||
|
||||
### Next Major Milestones
|
||||
|
||||
#### Immediate (1-2 Sessions)
|
||||
- **Complete Issue #15 or #16**: Demonstrate capability management system in practice
|
||||
- **Validate Discovery Tools**: Ensure automated detection prevents duplication
|
||||
- **Refine Workflow**: Based on real-world usage patterns
|
||||
|
||||
#### Short Term (3-5 Sessions)
|
||||
- **Schema-Driven Architecture**: Issues #5, #7, #8 (Milestone #2)
|
||||
- **Template Generation**: Issue #6 (Milestone #3)
|
||||
- **Advanced Querying**: Complete AST analysis capabilities
|
||||
|
||||
#### Medium Term (6-10 Sessions)
|
||||
- **Document Relationships**: Issue #4, advanced relationship mapping
|
||||
- **Performance Optimization**: Based on Issue #16 implementation
|
||||
- **Plugin Architecture**: Issue #19 and extensibility framework
|
||||
|
||||
## Session Success Criteria
|
||||
|
||||
### Must Achieve
|
||||
- [ ] Complete one core functionality issue using capability inclusion workflow
|
||||
- [ ] Demonstrate prevention of code duplication through discovery tools
|
||||
- [ ] Validate documentation ecosystem effectiveness
|
||||
|
||||
### Should Achieve
|
||||
- [ ] Update capability documentation with any new functionality
|
||||
- [ ] Refine workflow based on practical experience
|
||||
- [ ] Maintain green test state throughout development
|
||||
|
||||
### Could Achieve
|
||||
- [ ] Begin next milestone planning
|
||||
- [ ] Enhance discovery tools based on usage patterns
|
||||
- [ ] Improve AI assistant integration with capability system
|
||||
|
||||
## Known Context
|
||||
|
||||
### Current State
|
||||
- **Capability Management**: Complete documentation ecosystem established
|
||||
- **Discovery Tools**: Automated prevention of code duplication
|
||||
- **Architectural Clarity**: Clear separation of internal vs external capabilities
|
||||
- **Test State**: All tests passing (last known: 348 tests across 27 files)
|
||||
- **Git State**: Modified files ready for commit (capability inclusion system)
|
||||
|
||||
### Available Resources
|
||||
- **Complete capability documentation** in 5 interconnected files
|
||||
- **Automated discovery tools** via Makefile targets
|
||||
- **Enhanced agent definitions** with capability inclusion workflow
|
||||
- **Comprehensive test coverage** across all components
|
||||
|
||||
### Development Environment
|
||||
- **Ubuntu 24.04** with complete development environment
|
||||
- **Python virtual environment** properly configured
|
||||
- **Git submodules** (issue-facade, wiki) properly integrated
|
||||
- **All dependencies** installed and validated
|
||||
|
||||
## Next Session Preparation
|
||||
|
||||
### Pre-Session Setup
|
||||
1. Ensure git status is clean (commit capability inclusion system)
|
||||
2. Run `make test` to validate green state
|
||||
3. Review CLAUDE_CAPABILITY_REFERENCE.md for quick capability overview
|
||||
4. Select target issue for implementation
|
||||
|
||||
### Session Approach
|
||||
1. **Start with capability discovery** before any implementation
|
||||
2. **Use new workflow** from CAPABILITY_INCLUSION_GUIDE.md
|
||||
3. **Document any new capabilities** as they're created
|
||||
4. **Validate discovery tools** prevent accidental duplication
|
||||
|
||||
### Success Indicators
|
||||
- New functionality implemented without duplicating existing capabilities
|
||||
- Discovery tools successfully prevent code duplication
|
||||
- Documentation ecosystem proves valuable for development efficiency
|
||||
- AI assistants effectively use capability references for informed decisions
|
||||
|
||||
---
|
||||
|
||||
> **Note**: This file should be updated at the end of each session to maintain clear priorities and context for the next session. Use the capability inclusion management system as the foundation for all future development decisions.
|
||||
@@ -4,6 +4,28 @@ This diary tracks major work packages, events, and milestones in the MarkiTect p
|
||||
|
||||
---
|
||||
|
||||
## 2025-10-25: COMPREHENSIVE CAPABILITY INCLUSION MANAGEMENT SYSTEM ⭐ ARCHITECTURE MILESTONE ⭐
|
||||
|
||||
**Progress:** Successfully implemented comprehensive capability inclusion management system with clear separation of internal vs external capabilities
|
||||
**Contributors:** User (bernd.worsch), Claude Code (Sonnet 4)
|
||||
**Architecture Milestone:** Capability Inclusion Management System ✅ ACHIEVED (complete documentation ecosystem with discovery tools)
|
||||
**Total Development Time:** ~2-3 hours of intensive system design and documentation
|
||||
**AI Resources:** ~20-25 Claude Sonnet 4 conversations, estimated 40K+ tokens
|
||||
|
||||
**CAPABILITY INCLUSION BREAKTHROUGH:** Implemented revolutionary capability inclusion management system addressing the critical need to prevent code duplication and ensure proper separation of concerns. Created comprehensive documentation ecosystem with clear distinction between **internal capabilities** (what MarkiTect provides to the world) and **external capabilities** (what MarkiTect uses). This system provides developers and AI assistants with immediate visibility into existing functionality, preventing accidental reimplementation and enabling informed architectural decisions.
|
||||
|
||||
**COMPREHENSIVE DOCUMENTATION ECOSYSTEM:** Created five interconnected documentation files: (1) **CAPABILITIES.md** - Complete inventory of 73+ internal capabilities that MarkiTect provides, (2) **CAPABILITY_REGISTRY.md** - Registry of all external capabilities that MarkiTect uses (submodules, dependencies, extracted components), (3) **CAPABILITY_INCLUSION_GUIDE.md** - Complete workflow guide for managing capability inclusion decisions, (4) **CAPABILITY_DOCUMENTATION_INDEX.md** - Navigation hub linking all capability documentation, (5) **CLAUDE_CAPABILITY_REFERENCE.md** - Quick reference for AI assistants with search patterns and discovery tools.
|
||||
|
||||
**AUTOMATED DISCOVERY INFRASTRUCTURE:** Implemented sophisticated discovery tools preventing code duplication: `make capability-search TERM=xyz` for finding existing functionality across the codebase, integration with existing `make find-capability` and `make find-function` targets, comprehensive search patterns covering code, documentation, and test files, and automated capability detection preventing accidental reimplementation. Enhanced project-assistant agent definition with capability inclusion workflow guidelines.
|
||||
|
||||
**ARCHITECTURAL SEPARATION CLARITY:** Established clear architectural boundaries with **Internal Capabilities** (CAPABILITIES.md) focusing on what MarkiTect provides - the 73+ distinct capabilities including database-driven AST processing, multi-layer caching, Git platform integration, and comprehensive CLI interface. **External Capabilities** (CAPABILITY_REGISTRY.md) documenting what MarkiTect uses - git submodules (issue-facade, wiki), extracted components, package dependencies, and integration patterns. This separation enables clear understanding of system boundaries and dependency relationships.
|
||||
|
||||
**WORKFLOW INTEGRATION SUCCESS:** Updated all relevant documentation and agent definitions with capability inclusion workflow, enhanced README.md with clear links to capability documentation, integrated discovery tools with existing Makefile infrastructure, and provided comprehensive guidance for future development decisions. The system seamlessly integrates with existing development workflows while providing new safeguards against code duplication.
|
||||
|
||||
**STRATEGIC DEVELOPMENT IMPACT:** This system transforms MarkiTect development from ad-hoc capability implementation to systematic capability management. Before this session: unclear boundaries between internal/external capabilities, potential for code duplication, no systematic discovery tools. After this session: **Complete capability management platform**, **Clear architectural boundaries**, **Automated discovery preventing duplication**, **Comprehensive documentation ecosystem**, **AI-assistant optimized workflows**. This establishes MarkiTect as a mature project with enterprise-grade capability management.
|
||||
|
||||
---
|
||||
|
||||
|
||||
## 2025-10-02: PERFORMANCE TRACKING IMPLEMENTATION
|
||||
|
||||
|
||||
252
history/ProjectStatusDigest.md
Normal file
252
history/ProjectStatusDigest.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# MarkiTect Project - Status Digest
|
||||
|
||||
**Version:** 0.2.0
|
||||
**Last Updated:** 2025-10-25
|
||||
**Development Status:** 🚀 **Capability Inclusion Management System Complete - Enterprise-Grade Architecture**
|
||||
**Tagline:** "Your Markdown, Redefined"
|
||||
|
||||
## Core Vision
|
||||
|
||||
Transform Markdown from plain text into intelligent, structured, reusable data with schema validation and automation capabilities.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### MarkiTect Library (Python Core) ✅ **Foundation Complete**
|
||||
- **Reusable Python package** designed for CLI, service offerings, and third-party integration
|
||||
- **TDD approach** with comprehensive test coverage and pytest framework (348+ tests passing)
|
||||
- **Modern packaging** using `pyproject.toml` with dependencies: `markdown-it-py`, `PyYAML`
|
||||
- **Core modules implemented**: Database, front matter parsing, AST processing, caching system
|
||||
- **Capability inclusion management** with automated discovery and duplication prevention
|
||||
|
||||
### Capability Management System ✅ **REVOLUTIONARY ACHIEVEMENT**
|
||||
- **Complete capability documentation ecosystem** with 5 interconnected documentation files
|
||||
- **Clear separation**: Internal capabilities (what MarkiTect provides) vs External capabilities (what MarkiTect uses)
|
||||
- **Automated discovery tools** preventing code duplication (`make capability-search TERM=xyz`)
|
||||
- **AI-assistant optimized** workflow with CLAUDE_CAPABILITY_REFERENCE.md
|
||||
- **Architectural boundary clarity** ensuring proper separation of concerns
|
||||
- **73+ documented internal capabilities** with comprehensive categorization
|
||||
|
||||
### TDD Infrastructure (tddai Library) ✅ **Fully Operational**
|
||||
- **Complete TDD workspace management** with validated Python library architecture
|
||||
- **Issue-driven development** with proven Gitea API integration
|
||||
- **AI-assisted test generation** framework for automated TDD workflows (validated)
|
||||
- **Test coverage assessment system** with accurate requirement extraction and gap analysis
|
||||
- **Workspace lifecycle management** from issue creation to test integration
|
||||
- **CLI interface** (`tddai_cli.py`) for seamless command-line operations
|
||||
|
||||
### MarkiTect CLI (Command-Line Interface) ✅ **Production Ready**
|
||||
- **Complete CLI implementation** with Click framework integration
|
||||
- **Core commands**: `ingest`, `status`, `list`, `get`, `modify` - all fully functional
|
||||
- **Database query commands**: `query`, `query-files`, `query-sections` for powerful data access
|
||||
- **Cache management commands**: `cache-info`, `cache-clean`, `cache-invalidate` for performance control
|
||||
- **Document manipulation**: `--add-section`, `--update-front-matter` for AST modifications
|
||||
- **Performance optimization**: AST cache system with 60-85% faster processing
|
||||
- **Roundtrip validation**: Complete add → modify → get → verify workflow
|
||||
|
||||
## 🎯 **Current Development Status**
|
||||
|
||||
### ✅ **Major Milestones Completed**
|
||||
- **Issue #1**: Database initialization and front matter parsing (9 tests)
|
||||
- **Issue #2**: Fast Document Loading & CLI Manipulation ⭐ **MAJOR** (11 tests)
|
||||
- **Issue #12**: CLI Entry Point and Basic Commands (part of comprehensive test suite)
|
||||
- **Issue #13**: Cache Management CLI Commands ⭐ **MAJOR** (15 tests) - TDD8 Complete
|
||||
- **Issue #14**: Database Query CLI Interface ⭐ **MAJOR** (35 tests) - TDD8 Complete
|
||||
- **TDD Infrastructure**: Complete workflow automation (32+ tests)
|
||||
- **CLI Implementation Milestone**: ✅ **COMPLETED** - All CLI core functionality delivered
|
||||
- **Capability Inclusion Management**: ✅ **COMPLETED** - Revolutionary architecture milestone
|
||||
- **Total Foundation**: 348+ tests passing across 27 test files
|
||||
|
||||
### 🚀 **Strategic Roadmap Active**
|
||||
**4 Subprojects targeting HolyGrailRequirement (arc42 documentation system)**
|
||||
|
||||
#### **Subproject 1: Schema-Driven Architecture** (Milestone #2)
|
||||
- Issue #5: Generate Schema from Markdown File (HIGH)
|
||||
- Issue #7: Validate Markdown Against Schema (HIGH)
|
||||
- Issue #8: Get Validation Errors (HIGH)
|
||||
|
||||
#### **Subproject 2: Template & Stub Generation** (Milestone #3)
|
||||
- Issue #6: Generate Markdown Stub from Schema (HIGH)
|
||||
|
||||
#### **Subproject 3: Document Relationships** (Milestone #4)
|
||||
- Issue #4: Retrieve All Stored Files (MEDIUM)
|
||||
- Issue #15: AST Query and Analysis CLI (CRITICAL)
|
||||
|
||||
#### **Subproject 4: Plan-Actual Comparison Engine** (Milestone #5)
|
||||
- Issue #9: Expose GraphQL Read Interface (LOW)
|
||||
- Issue #10: Expose GraphQL Write Interface (LOW)
|
||||
- ✅ Issue #16: Performance Validation CLI (COMPLETED) - All 5 CLI commands implemented with 81.4/100 performance baseline
|
||||
|
||||
### 🎯 **Next Priority**
|
||||
- **Strategic Issue Implementation** using new capability inclusion workflow
|
||||
- **Capability Management Validation** through real-world usage
|
||||
- **Schema-Driven Architecture** milestone preparation with duplication prevention
|
||||
|
||||
### 📊 **Metrics**
|
||||
- **Test Coverage**: 100% for implemented features (348+ tests across 27 files)
|
||||
- **Code Quality**: Modern Python practices with type hints and comprehensive error handling
|
||||
- **Documentation**: Revolutionary capability management ecosystem with 5 interconnected files
|
||||
- **Development Velocity**: Enhanced with automated duplication prevention
|
||||
- **Architecture Maturity**: Enterprise-grade capability inclusion management
|
||||
|
||||
## Key Features & Components
|
||||
|
||||
### Core Functionality
|
||||
- **AbstractSyntaxTree** processing and manipulation with comprehensive caching
|
||||
- **MarkdownParser** using `markdown-it-py` for detailed AST generation
|
||||
- **JsonSchemaValidator** for enforcing document structure
|
||||
- **ChunkInclusion** system for modular content composition
|
||||
- **StaticSiteGenerator** integration capabilities
|
||||
- **Capability Inclusion Management** preventing code duplication
|
||||
|
||||
### Capability Management (NEW)
|
||||
- **Internal Capability Inventory** (CAPABILITIES.md) - 73+ capabilities provided by MarkiTect
|
||||
- **External Capability Registry** (CAPABILITY_REGISTRY.md) - Dependencies and submodules used by MarkiTect
|
||||
- **Automated Discovery Tools** - `make capability-search TERM=xyz` for existing functionality detection
|
||||
- **AI-Assistant Integration** - CLAUDE_CAPABILITY_REFERENCE.md for informed development decisions
|
||||
- **Workflow Documentation** - CAPABILITY_INCLUSION_GUIDE.md for systematic capability management
|
||||
|
||||
### Schema Operations
|
||||
- **Generate schemas** from existing Markdown at specified nesting depths
|
||||
- **Validate Markdown** against defined schemas
|
||||
- **Generate stub files** from schemas with placeholder content
|
||||
- **InclusionStub** handling for modular document architecture
|
||||
|
||||
### GraphQL Interface
|
||||
- **Query operations** for retrieving Markdown files, schemas, and AST data
|
||||
- **Mutation operations** for adding/updating content in database
|
||||
- **Real-time validation** and schema checking
|
||||
|
||||
## Development Approach
|
||||
|
||||
### Capability-First Development (NEW)
|
||||
- **Before implementing**: Check existing capabilities via discovery tools
|
||||
- **During implementation**: Follow CAPABILITY_INCLUSION_GUIDE.md workflow
|
||||
- **After implementation**: Update capability documentation ecosystem
|
||||
- **Automated prevention**: Code duplication detection and architectural boundary enforcement
|
||||
|
||||
### Test-Driven Development
|
||||
- **Complete TDD infrastructure** with `tddai` Python library
|
||||
- **Issue-driven workflow** with workspace management (`tdd-start`, `tdd-add-test`, `tdd-status`, `tdd-finish`)
|
||||
- **348+ passing tests** across 27 test files using pytest with proper behavior-based testing
|
||||
- **AI-assisted test generation** integrated into development cycle
|
||||
- **Green-state validation** before all commits
|
||||
|
||||
### Markdown Feature Support (MF-1 through MF-10)
|
||||
Complete specification coverage including:
|
||||
- Headings and sections structure
|
||||
- Text formatting (bold, italic, strikethrough)
|
||||
- Lists (ordered, unordered, task lists)
|
||||
- Links, images, and media handling
|
||||
- Code blocks and syntax highlighting
|
||||
- Tables and complex formatting
|
||||
- Footnotes and reference systems
|
||||
|
||||
## Project Status
|
||||
|
||||
### Current State
|
||||
- **Capability inclusion management system complete** with comprehensive documentation ecosystem
|
||||
- **TDD infrastructure complete** with robust Python library architecture
|
||||
- **Issue-driven development workflow** fully operational with capability management integration
|
||||
- **Comprehensive test suite** with 348+ passing tests across 27 files
|
||||
- **Build system** with sophisticated Makefile and virtual environment integration
|
||||
- **AI-assisted development** cycle with capability-aware workspace management
|
||||
- **Enterprise-grade architecture** with automated duplication prevention
|
||||
|
||||
### Social Integration
|
||||
- **CoulombSocial participation** since September 2025
|
||||
- **Gitea issues integration** with API-driven workflow management
|
||||
- **Open-source development** model with collaborative wiki
|
||||
- **Issue-to-test automation** for structured development cycles
|
||||
- **Capability-driven collaboration** with clear architectural boundaries
|
||||
|
||||
## Technical Foundation
|
||||
|
||||
### Development Tools
|
||||
- **Python 3.8+** with modern tooling (Black, Ruff, mypy, pytest)
|
||||
- **Make-based workflow** with intelligent environment detection and capability management integration
|
||||
- **Git submodules** for wiki documentation and issue-facade management
|
||||
- **tddai library** for complete TDD workspace automation
|
||||
- **Capability discovery tools** with automated duplication prevention
|
||||
- **Issue management** with Gitea API integration and CLI tools
|
||||
- **Custom subagent ecosystem** enhanced with capability inclusion workflow
|
||||
- **Automated dependency management** with comprehensive installation scripts
|
||||
|
||||
### Brand Identity
|
||||
- **Professional visual identity** with 3D "M" logo incorporating Markdown symbols
|
||||
- **Color palette**: Deep teal/navy (primary), vibrant orange, lime green
|
||||
- **Core pillars**: Structural Integrity, Consistency, Reusability, Automation, Capability Management
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
markitect_project/
|
||||
├── markitect/ # Main Python package
|
||||
├── tddai/ # TDD infrastructure library
|
||||
├── tests/ # Comprehensive test suite (348+ tests across 27 files)
|
||||
├── issue-facade/ # Git submodule for issue management
|
||||
├── wiki/ # Git submodule with comprehensive documentation
|
||||
│
|
||||
├── CAPABILITIES.md # Internal capabilities inventory (73+ capabilities)
|
||||
├── CAPABILITY_REGISTRY.md # External capabilities registry
|
||||
├── CAPABILITY_INCLUSION_GUIDE.md # Workflow guide for capability management
|
||||
├── CAPABILITY_DOCUMENTATION_INDEX.md # Navigation hub for capability docs
|
||||
├── CLAUDE_CAPABILITY_REFERENCE.md # AI assistant quick reference
|
||||
│
|
||||
├── agents/ # Enhanced project management agents
|
||||
├── Makefile # Development workflow with capability management
|
||||
├── pyproject.toml # Python package configuration
|
||||
├── NEXT.md # Next session priorities and strategy
|
||||
├── history/ProjectDiary.md # Development milestone tracking
|
||||
└── README.md # Project overview with capability links
|
||||
```
|
||||
|
||||
## Getting Started
|
||||
|
||||
1. **Environment Setup:**
|
||||
```bash
|
||||
sudo ./install-depends.sh # Install system dependencies (Ubuntu 24.04)
|
||||
./install-pip.sh # Install Python dependencies and package
|
||||
make venv-status # Check environment activation state
|
||||
```
|
||||
|
||||
2. **Development Workflow:**
|
||||
```bash
|
||||
make test # Run comprehensive test suite (348+ tests)
|
||||
make update # Pull latest changes from upstream
|
||||
make status # Check git status
|
||||
```
|
||||
|
||||
3. **Capability Management (NEW):**
|
||||
```bash
|
||||
make capability-search TERM=xyz # Find existing functionality
|
||||
make find-capability TERM=xyz # Alternative search method
|
||||
# Before implementing, check CAPABILITIES.md and CAPABILITY_REGISTRY.md
|
||||
```
|
||||
|
||||
4. **TDD Workflow:**
|
||||
```bash
|
||||
make tdd-start NUM=X # Start working on issue X
|
||||
make tdd-add-test # Generate tests for current issue
|
||||
make tdd-status # Check workspace status
|
||||
make tdd-finish # Complete issue and integrate tests
|
||||
```
|
||||
|
||||
5. **Issue Management:**
|
||||
```bash
|
||||
make list-issues # Show all Gitea issues
|
||||
make list-open-issues # Show active backlog
|
||||
make show-issue NUM=X # Detailed issue view
|
||||
make test-coverage NUM=X # Analyze test coverage for issue
|
||||
```
|
||||
|
||||
6. **Building:**
|
||||
```bash
|
||||
make build # Build the package
|
||||
make clean # Clean build artifacts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
MarkiTect represents a significant evolution toward treating documentation as **structured, validatable, and reusable data** rather than simple text files, with robust tooling for large-scale content management, automation, and **enterprise-grade capability inclusion management** that prevents code duplication and ensures architectural clarity.
|
||||
|
||||
> **Note:** This digest is maintained using Claude Code with capability-aware development workflows. Run `make update-digest` to refresh with latest project information.
|
||||
@@ -1,340 +0,0 @@
|
||||
# Issue Facade - Universal CLI for Issue Tracking
|
||||
|
||||
A convenient command-line facade that provides a unified interface to the repository's main issue tracker, regardless of which backend system is actually being used.
|
||||
|
||||
## Purpose
|
||||
|
||||
The **Issue Facade** acts as a convenient CLI wrapper that automatically detects and interfaces with whatever issue tracking system is configured for the current repository. This means you get a consistent, intuitive command-line experience whether your project uses:
|
||||
|
||||
- GitHub Issues
|
||||
- GitLab Issues
|
||||
- Gitea Issues
|
||||
- JIRA
|
||||
- Local SQLite storage
|
||||
- Any other supported backend
|
||||
|
||||
## Philosophy
|
||||
|
||||
Rather than learning different commands and workflows for each issue tracking system, the Issue Facade provides:
|
||||
|
||||
- **One CLI to rule them all**: Same commands work across all backends
|
||||
- **Repository-aware**: Automatically detects the relevant issue tracker for your repo
|
||||
- **Offline capability**: Local SQLite fallback when remote systems are unavailable
|
||||
- **Seamless sync**: Keep local and remote issue trackers synchronized
|
||||
|
||||
## How It Works
|
||||
|
||||
```bash
|
||||
# The facade automatically detects your repository's issue tracker
|
||||
cd /path/to/my-project
|
||||
issue list # Lists issues from the repo's configured tracker
|
||||
|
||||
cd /path/to/another-project
|
||||
issue list # Lists issues from THIS repo's tracker
|
||||
|
||||
# Same commands, different backends - transparent to the user
|
||||
```
|
||||
|
||||
## Key Features
|
||||
|
||||
### 🎯 **Repository Context Awareness**
|
||||
The facade automatically detects:
|
||||
- Git remotes (GitHub, GitLab, Gitea URLs)
|
||||
- Configuration files (`.issue-config`, `pyproject.toml`, etc.)
|
||||
- Environment variables
|
||||
- Default fallbacks
|
||||
|
||||
### 🖥️ **Unified CLI Experience**
|
||||
```bash
|
||||
# Core issue operations (same across all backends)
|
||||
issue list # List issues
|
||||
issue show 42 # Show issue details
|
||||
issue create "Bug in parser" # Create new issue
|
||||
issue edit 42 --add-label bug # Edit existing issue
|
||||
issue close 42 --comment "Fixed" # Close with comment
|
||||
issue comment 42 "Still broken" # Add comment
|
||||
|
||||
# Advanced operations
|
||||
issue list --assignee=me --state=open
|
||||
issue search "memory leak"
|
||||
issue stats # Show issue statistics
|
||||
```
|
||||
|
||||
### 🔄 **Automatic Backend Detection**
|
||||
```bash
|
||||
# GitHub repository
|
||||
cd my-github-project
|
||||
issue list # → Automatically uses GitHub Issues API
|
||||
|
||||
# Gitea repository
|
||||
cd my-gitea-project
|
||||
issue list # → Automatically uses Gitea Issues API
|
||||
|
||||
# Offline/local work
|
||||
cd any-project
|
||||
issue backend set local
|
||||
issue list # → Uses local SQLite storage
|
||||
```
|
||||
|
||||
### 🌐 **Seamless Synchronization**
|
||||
```bash
|
||||
# Work offline, sync later
|
||||
issue create "Bug found offline" --local
|
||||
issue sync # Pushes to remote when online
|
||||
|
||||
# Keep backups
|
||||
issue sync pull # Download all remote issues locally
|
||||
issue export backup.json # Export for archival
|
||||
```
|
||||
|
||||
## Installation & Setup
|
||||
|
||||
### 1. Install the Facade
|
||||
```bash
|
||||
pip install issue-facade
|
||||
```
|
||||
|
||||
### 2. Automatic Configuration
|
||||
The facade auto-detects your repository's issue tracker:
|
||||
|
||||
```bash
|
||||
cd your-repository
|
||||
issue config detect # Auto-configure based on git remotes
|
||||
issue list # Ready to use!
|
||||
```
|
||||
|
||||
### 3. Manual Configuration (if needed)
|
||||
```bash
|
||||
# Configure specific backends
|
||||
issue backend add github my-repo
|
||||
issue backend add gitea company-repo
|
||||
issue backend add local offline
|
||||
|
||||
# Set repository-specific backend
|
||||
issue config set-backend github # For current repository
|
||||
```
|
||||
|
||||
## Repository Integration Examples
|
||||
|
||||
### GitHub Repository
|
||||
```bash
|
||||
cd my-github-project
|
||||
issue config detect
|
||||
# → Automatically configures GitHub Issues via API
|
||||
# → Uses .github/ISSUE_TEMPLATE/ for templates
|
||||
# → Respects repository labels and milestones
|
||||
|
||||
issue create "Security vulnerability" --template security
|
||||
```
|
||||
|
||||
### Corporate Gitea
|
||||
```bash
|
||||
cd company-project
|
||||
issue config detect
|
||||
# → Detects Gitea instance from git remote
|
||||
# → Prompts for access token (one-time setup)
|
||||
# → Uses corporate labels and workflows
|
||||
|
||||
issue list --milestone "Q4 Release"
|
||||
```
|
||||
|
||||
### Offline Development
|
||||
```bash
|
||||
cd any-project
|
||||
issue backend set local
|
||||
# → Creates local SQLite database in .issue-facade/
|
||||
# → Full offline functionality
|
||||
# → Sync to remote when connection available
|
||||
|
||||
issue create "Performance issue" --offline
|
||||
issue sync when-online
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Per-Repository Configuration
|
||||
Each repository can have its own configuration in `.issue-facade/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"backend": "github",
|
||||
"github": {
|
||||
"owner": "myorg",
|
||||
"repo": "myproject",
|
||||
"token_env": "GITHUB_TOKEN"
|
||||
},
|
||||
"local": {
|
||||
"db_path": ".issue-facade/issues.db",
|
||||
"sync_enabled": true
|
||||
},
|
||||
"templates": {
|
||||
"bug": ".github/ISSUE_TEMPLATE/bug_report.md",
|
||||
"feature": ".github/ISSUE_TEMPLATE/feature_request.md"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Global Configuration
|
||||
User-wide settings in `~/.config/issue-facade/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"default_backend": "local",
|
||||
"github_token": "env:GITHUB_TOKEN",
|
||||
"gitea_instances": {
|
||||
"company": {
|
||||
"url": "https://git.company.com",
|
||||
"token": "env:GITEA_TOKEN"
|
||||
}
|
||||
},
|
||||
"offline_mode": false,
|
||||
"sync_interval": "1h"
|
||||
}
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### Facade Pattern Implementation
|
||||
```
|
||||
Repository Working Directory
|
||||
├── .git/ # Git repository
|
||||
├── .issue-facade/ # Facade configuration
|
||||
│ ├── config.json # Repository-specific config
|
||||
│ ├── issues.db # Local SQLite cache/backup
|
||||
│ └── templates/ # Issue templates
|
||||
├── your-project-files...
|
||||
└── issue # CLI command (context-aware)
|
||||
```
|
||||
|
||||
### Backend Detection Logic
|
||||
1. **Check repository configuration**: `.issue-facade/config.json`
|
||||
2. **Analyze git remotes**: Detect GitHub/GitLab/Gitea URLs
|
||||
3. **Look for platform files**: `.github/`, `.gitlab/`, etc.
|
||||
4. **Check environment**: `GITHUB_TOKEN`, `GITLAB_TOKEN`, etc.
|
||||
5. **Fall back to local**: SQLite storage if no remote detected
|
||||
|
||||
### Multi-Repository Support
|
||||
```bash
|
||||
# Each repository maintains its own context
|
||||
/projects/web-app/ → GitHub Issues
|
||||
/projects/api-server/ → GitLab Issues
|
||||
/projects/cli-tool/ → Gitea Issues
|
||||
/projects/experiment/ → Local SQLite
|
||||
|
||||
# Same commands work in all contexts
|
||||
cd web-app && issue list # GitHub
|
||||
cd api-server && issue list # GitLab
|
||||
cd cli-tool && issue list # Gitea
|
||||
cd experiment && issue list # Local
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
### 1. **Multi-Platform Developer**
|
||||
You work with repositories across GitHub, GitLab, and company Gitea:
|
||||
```bash
|
||||
# Learn one CLI, use everywhere
|
||||
issue list --assignee=me # Works on all platforms
|
||||
issue create "Cross-platform bug" --label bug
|
||||
```
|
||||
|
||||
### 2. **Offline Developer**
|
||||
You need to track issues without constant internet:
|
||||
```bash
|
||||
issue create "Found while flying" --offline
|
||||
issue list --local # View offline issues
|
||||
issue sync # Upload when back online
|
||||
```
|
||||
|
||||
### 3. **Repository Migration**
|
||||
Moving from GitHub to GitLab:
|
||||
```bash
|
||||
issue export github-backup.json # Backup from GitHub
|
||||
issue backend set gitlab # Switch to GitLab
|
||||
issue import github-backup.json # Import to GitLab
|
||||
```
|
||||
|
||||
### 4. **Cross-Repository Analytics**
|
||||
Track issues across multiple repositories:
|
||||
```bash
|
||||
issue stats --all-repos # Statistics across all configured repos
|
||||
issue search "security" --global # Search across all issue trackers
|
||||
```
|
||||
|
||||
## Integration with Development Workflow
|
||||
|
||||
### Git Hooks Integration
|
||||
```bash
|
||||
# .git/hooks/pre-commit
|
||||
issue list --assignee=me --state=open > ISSUES.md
|
||||
git add ISSUES.md
|
||||
```
|
||||
|
||||
### CI/CD Integration
|
||||
```bash
|
||||
# In your CI pipeline
|
||||
issue create "Build failed on commit $SHA" --label ci-failure
|
||||
issue close-if-fixed $ISSUE_NUMBER
|
||||
```
|
||||
|
||||
### IDE Integration
|
||||
```bash
|
||||
# VS Code, Vim, Emacs plugins can use the CLI
|
||||
:IssueList # List issues in editor
|
||||
:IssueCreate "Typo in function" # Create issue from editor
|
||||
```
|
||||
|
||||
## Comparison with Native Tools
|
||||
|
||||
| Feature | issue-facade | gh (GitHub CLI) | glab (GitLab CLI) | Platform Web UI |
|
||||
|---------|--------------|-----------------|-------------------|-----------------|
|
||||
| **Multi-platform** | ✅ All backends | ❌ GitHub only | ❌ GitLab only | ❌ Single platform |
|
||||
| **Offline support** | ✅ Local SQLite | ❌ Online only | ❌ Online only | ❌ Online only |
|
||||
| **Consistent CLI** | ✅ Same commands | ❌ GitHub-specific | ❌ GitLab-specific | ❌ Web interface |
|
||||
| **Repository context** | ✅ Auto-detect | ✅ Git-aware | ✅ Git-aware | ❌ Manual navigation |
|
||||
| **Cross-repo search** | ✅ Global search | ❌ Single repo | ❌ Single repo | ❌ Single repo |
|
||||
| **Data portability** | ✅ Export/import | ❌ Platform-locked | ❌ Platform-locked | ❌ Platform-locked |
|
||||
|
||||
## Future Roadmap
|
||||
|
||||
### Version 1.0 (Current)
|
||||
- [x] Core facade architecture
|
||||
- [x] GitHub/GitLab/Gitea backend support
|
||||
- [x] Local SQLite backend
|
||||
- [x] Automatic repository detection
|
||||
- [x] Basic synchronization
|
||||
|
||||
### Version 1.1
|
||||
- [ ] Advanced sync (conflict resolution)
|
||||
- [ ] Issue templates support
|
||||
- [ ] Workflow automation hooks
|
||||
- [ ] Plugin system for custom backends
|
||||
|
||||
### Version 2.0
|
||||
- [ ] Web dashboard for multi-repo overview
|
||||
- [ ] Advanced analytics and reporting
|
||||
- [ ] Team collaboration features
|
||||
- [ ] Integration with project management tools
|
||||
|
||||
## Contributing
|
||||
|
||||
The Issue Facade is designed to be:
|
||||
- **Backend-agnostic**: Easy to add new issue tracking systems
|
||||
- **Repository-aware**: Respects the conventions of each platform
|
||||
- **Developer-friendly**: Consistent CLI across all environments
|
||||
|
||||
To add a new backend:
|
||||
1. Implement the `IssueBackend` interface
|
||||
2. Add detection logic for the platform
|
||||
3. Register the backend in the factory
|
||||
4. Add CLI configuration support
|
||||
|
||||
## Why "Facade"?
|
||||
|
||||
The **Facade Pattern** perfectly describes this tool's purpose:
|
||||
|
||||
> *"Provide a unified interface to a set of interfaces in a subsystem. Facade defines a higher-level interface that makes the subsystem easier to use."*
|
||||
|
||||
Instead of learning different CLIs for GitHub (`gh`), GitLab (`glab`), JIRA, etc., the Issue Facade provides one consistent interface that works with all of them. It's the universal remote control for issue tracking systems.
|
||||
|
||||
The facade doesn't replace the underlying issue trackers - it makes them easier to use consistently across different platforms and repositories.
|
||||
@@ -1,24 +0,0 @@
|
||||
"""
|
||||
Universal Issue Tracking System
|
||||
|
||||
A backend-agnostic issue tracking system that supports multiple backends
|
||||
through a plugin architecture. Designed to be extracted into a standalone
|
||||
repository for use across multiple projects.
|
||||
|
||||
Features:
|
||||
- Unified issue model across all backends
|
||||
- Plugin-based backend architecture
|
||||
- Local SQLite backend for offline work
|
||||
- Bidirectional synchronization
|
||||
- CLI-first interface
|
||||
- Support for GitHub-style and other issue tracking systems
|
||||
|
||||
Supported Backends:
|
||||
- Local SQLite (for offline/standalone use)
|
||||
- Gitea (GitHub-compatible API)
|
||||
- Future: GitHub, GitLab, JIRA, Redmine, etc.
|
||||
"""
|
||||
|
||||
__version__ = "0.1.0"
|
||||
__author__ = "MarkiTect Project"
|
||||
__description__ = "Universal Issue Tracking System with Plugin Architecture"
|
||||
@@ -1,11 +0,0 @@
|
||||
"""
|
||||
Issue Tracking Backend Plugins
|
||||
|
||||
This package contains implementations for various issue tracking backends.
|
||||
Each backend implements the IssueBackend interface to provide a consistent
|
||||
API regardless of the underlying issue tracking system.
|
||||
|
||||
Available Backends:
|
||||
- local: SQLite-based local backend for offline use
|
||||
- gitea: Gitea API backend for GitHub-compatible systems
|
||||
"""
|
||||
@@ -1,17 +0,0 @@
|
||||
"""
|
||||
Gitea Backend
|
||||
|
||||
A backend implementation for Gitea issue tracking systems.
|
||||
This backend provides integration with Gitea API for remote issue management.
|
||||
|
||||
Features:
|
||||
- Full Gitea API integration
|
||||
- GitHub-compatible operations
|
||||
- Remote synchronization
|
||||
- Authentication support
|
||||
- Rate limiting compliance
|
||||
"""
|
||||
|
||||
from .backend import GiteaBackend
|
||||
|
||||
__all__ = ['GiteaBackend']
|
||||
@@ -1,591 +0,0 @@
|
||||
"""
|
||||
Gitea Backend Implementation
|
||||
|
||||
Provides integration with Gitea API for remote issue tracking.
|
||||
This backend adapts the Gitea API to our unified issue model.
|
||||
"""
|
||||
|
||||
import requests
|
||||
import time
|
||||
from datetime import datetime, timezone
|
||||
from typing import List, Optional, Dict, Any
|
||||
from urllib.parse import urljoin
|
||||
|
||||
from ...core.interfaces import RemoteBackend, BackendCapabilities, IssueFilter, SyncableBackend
|
||||
from ...core.models import Issue, Label, User, Milestone, Comment, IssueState, Priority, IssueType
|
||||
|
||||
|
||||
class GiteaAPIError(Exception):
|
||||
"""Gitea API specific errors."""
|
||||
pass
|
||||
|
||||
|
||||
class GiteaRateLimitError(GiteaAPIError):
|
||||
"""Rate limit exceeded."""
|
||||
pass
|
||||
|
||||
|
||||
class GiteaBackend(RemoteBackend, SyncableBackend):
|
||||
"""Gitea API backend for remote issue tracking."""
|
||||
|
||||
def __init__(self):
|
||||
self.base_url: Optional[str] = None
|
||||
self.token: Optional[str] = None
|
||||
self.owner: Optional[str] = None
|
||||
self.repo: Optional[str] = None
|
||||
self.session = requests.Session()
|
||||
self._capabilities = BackendCapabilities(
|
||||
supports_milestones=True,
|
||||
supports_assignees=True,
|
||||
supports_comments=True,
|
||||
supports_labels=True,
|
||||
supports_search=True,
|
||||
supports_bulk_operations=False,
|
||||
supports_webhooks=True,
|
||||
supports_real_time=False,
|
||||
max_labels_per_issue=None,
|
||||
max_assignees_per_issue=10 # Gitea typical limit
|
||||
)
|
||||
|
||||
@property
|
||||
def backend_type(self) -> str:
|
||||
return "gitea"
|
||||
|
||||
@property
|
||||
def capabilities(self) -> BackendCapabilities:
|
||||
return self._capabilities
|
||||
|
||||
def connect(self, config: Dict[str, Any]) -> None:
|
||||
"""Connect to Gitea API."""
|
||||
self.base_url = config['base_url'].rstrip('/')
|
||||
self.token = config['token']
|
||||
self.owner = config['owner']
|
||||
self.repo = config['repo']
|
||||
|
||||
# Setup session with authentication
|
||||
self.session.headers.update({
|
||||
'Authorization': f'token {self.token}',
|
||||
'Content-Type': 'application/json',
|
||||
'Accept': 'application/json'
|
||||
})
|
||||
|
||||
# Test connection
|
||||
if not self.test_connection():
|
||||
raise GiteaAPIError("Failed to connect to Gitea API")
|
||||
|
||||
def disconnect(self) -> None:
|
||||
"""Disconnect from Gitea API."""
|
||||
self.session.close()
|
||||
self.base_url = None
|
||||
self.token = None
|
||||
self.owner = None
|
||||
self.repo = None
|
||||
|
||||
def test_connection(self) -> bool:
|
||||
"""Test Gitea API connection."""
|
||||
try:
|
||||
response = self._api_request('GET', f'/repos/{self.owner}/{self.repo}')
|
||||
return response.status_code == 200
|
||||
except Exception:
|
||||
return False
|
||||
|
||||
def _api_request(self, method: str, endpoint: str, data: Optional[Dict] = None, params: Optional[Dict] = None) -> requests.Response:
|
||||
"""Make API request with error handling and rate limiting."""
|
||||
url = urljoin(f"{self.base_url}/api/v1", endpoint)
|
||||
|
||||
try:
|
||||
response = self.session.request(method, url, json=data, params=params)
|
||||
|
||||
# Handle rate limiting
|
||||
if response.status_code == 429:
|
||||
retry_after = int(response.headers.get('Retry-After', 60))
|
||||
raise GiteaRateLimitError(f"Rate limit exceeded. Retry after {retry_after} seconds")
|
||||
|
||||
response.raise_for_status()
|
||||
return response
|
||||
|
||||
except requests.exceptions.RequestException as e:
|
||||
raise GiteaAPIError(f"API request failed: {e}")
|
||||
|
||||
def _gitea_issue_to_unified(self, gitea_issue: Dict[str, Any]) -> Issue:
|
||||
"""Convert Gitea issue JSON to unified Issue model."""
|
||||
# Convert labels
|
||||
labels = []
|
||||
for label_data in gitea_issue.get('labels', []):
|
||||
labels.append(Label(
|
||||
name=label_data['name'],
|
||||
color=label_data['color'],
|
||||
description=label_data.get('description', ''),
|
||||
backend_id=str(label_data['id'])
|
||||
))
|
||||
|
||||
# Convert assignees
|
||||
assignees = []
|
||||
if gitea_issue.get('assignees'):
|
||||
for assignee_data in gitea_issue['assignees']:
|
||||
assignees.append(User(
|
||||
id=str(assignee_data['id']),
|
||||
username=assignee_data['login'],
|
||||
display_name=assignee_data.get('full_name', ''),
|
||||
email=assignee_data.get('email', ''),
|
||||
avatar_url=assignee_data.get('avatar_url', ''),
|
||||
backend_id=str(assignee_data['id'])
|
||||
))
|
||||
|
||||
# Convert milestone
|
||||
milestone = None
|
||||
if gitea_issue.get('milestone'):
|
||||
milestone_data = gitea_issue['milestone']
|
||||
milestone = Milestone(
|
||||
id=str(milestone_data['id']),
|
||||
title=milestone_data['title'],
|
||||
description=milestone_data.get('description', ''),
|
||||
state=milestone_data['state'],
|
||||
due_date=datetime.fromisoformat(milestone_data['due_on'].replace('Z', '+00:00')) if milestone_data.get('due_on') else None,
|
||||
created_at=datetime.fromisoformat(milestone_data['created_at'].replace('Z', '+00:00')) if milestone_data.get('created_at') else None,
|
||||
updated_at=datetime.fromisoformat(milestone_data['updated_at'].replace('Z', '+00:00')) if milestone_data.get('updated_at') else None,
|
||||
backend_id=str(milestone_data['id'])
|
||||
)
|
||||
|
||||
# Determine state
|
||||
if gitea_issue['state'] == 'closed':
|
||||
state = IssueState.CLOSED
|
||||
else:
|
||||
# Check for status labels to determine more specific state
|
||||
for label in labels:
|
||||
if label.name == 'status:in_progress' or label.name == 'status:in-progress':
|
||||
state = IssueState.IN_PROGRESS
|
||||
break
|
||||
elif label.name == 'status:blocked':
|
||||
state = IssueState.BLOCKED
|
||||
break
|
||||
else:
|
||||
state = IssueState.OPEN
|
||||
|
||||
return Issue(
|
||||
id=str(gitea_issue['id']),
|
||||
number=gitea_issue['number'],
|
||||
title=gitea_issue['title'],
|
||||
description=gitea_issue.get('body', ''),
|
||||
state=state,
|
||||
created_at=datetime.fromisoformat(gitea_issue['created_at'].replace('Z', '+00:00')),
|
||||
updated_at=datetime.fromisoformat(gitea_issue['updated_at'].replace('Z', '+00:00')),
|
||||
closed_at=datetime.fromisoformat(gitea_issue['closed_at'].replace('Z', '+00:00')) if gitea_issue.get('closed_at') else None,
|
||||
labels=labels,
|
||||
assignees=assignees,
|
||||
milestone=milestone,
|
||||
backend_id=str(gitea_issue['id']),
|
||||
backend_type='gitea'
|
||||
)
|
||||
|
||||
def _unified_issue_to_gitea(self, issue: Issue) -> Dict[str, Any]:
|
||||
"""Convert unified Issue to Gitea API format."""
|
||||
data = {
|
||||
'title': issue.title,
|
||||
'body': issue.description,
|
||||
'state': 'closed' if issue.state == IssueState.CLOSED else 'open'
|
||||
}
|
||||
|
||||
if issue.assignees:
|
||||
data['assignees'] = [assignee.username for assignee in issue.assignees]
|
||||
|
||||
if issue.milestone:
|
||||
data['milestone'] = int(issue.milestone.backend_id) if issue.milestone.backend_id else None
|
||||
|
||||
# Convert labels
|
||||
if issue.labels:
|
||||
data['labels'] = [label.name for label in issue.labels]
|
||||
|
||||
return data
|
||||
|
||||
# Issue CRUD Operations
|
||||
def create_issue(self, issue: Issue) -> Issue:
|
||||
"""Create issue in Gitea."""
|
||||
data = self._unified_issue_to_gitea(issue)
|
||||
|
||||
response = self._api_request('POST', f'/repos/{self.owner}/{self.repo}/issues', data=data)
|
||||
gitea_issue = response.json()
|
||||
|
||||
return self._gitea_issue_to_unified(gitea_issue)
|
||||
|
||||
def get_issue(self, issue_id: str) -> Optional[Issue]:
|
||||
"""Get issue from Gitea by ID."""
|
||||
try:
|
||||
response = self._api_request('GET', f'/repos/{self.owner}/{self.repo}/issues/{issue_id}')
|
||||
gitea_issue = response.json()
|
||||
return self._gitea_issue_to_unified(gitea_issue)
|
||||
except GiteaAPIError:
|
||||
return None
|
||||
|
||||
def get_issue_by_number(self, number: int) -> Optional[Issue]:
|
||||
"""Get issue by number."""
|
||||
return self.get_issue(str(number))
|
||||
|
||||
def update_issue(self, issue: Issue) -> Issue:
|
||||
"""Update issue in Gitea."""
|
||||
data = self._unified_issue_to_gitea(issue)
|
||||
|
||||
response = self._api_request('PATCH', f'/repos/{self.owner}/{self.repo}/issues/{issue.backend_id}', data=data)
|
||||
gitea_issue = response.json()
|
||||
|
||||
return self._gitea_issue_to_unified(gitea_issue)
|
||||
|
||||
def delete_issue(self, issue_id: str) -> bool:
|
||||
"""Delete issue - not supported by Gitea API."""
|
||||
# Gitea doesn't support deleting issues via API
|
||||
# We could close it instead
|
||||
try:
|
||||
issue = self.get_issue(issue_id)
|
||||
if issue:
|
||||
issue.close()
|
||||
self.update_issue(issue)
|
||||
return True
|
||||
except Exception:
|
||||
pass
|
||||
return False
|
||||
|
||||
def list_issues(self, filter_criteria: Optional[IssueFilter] = None) -> List[Issue]:
|
||||
"""List issues from Gitea."""
|
||||
params = {
|
||||
'state': 'all', # Get both open and closed
|
||||
'sort': 'updated',
|
||||
'order': 'desc'
|
||||
}
|
||||
|
||||
if filter_criteria:
|
||||
if filter_criteria.state:
|
||||
if filter_criteria.state == 'open':
|
||||
params['state'] = 'open'
|
||||
elif filter_criteria.state == 'closed':
|
||||
params['state'] = 'closed'
|
||||
|
||||
if filter_criteria.assignee:
|
||||
params['assignee'] = filter_criteria.assignee
|
||||
|
||||
if filter_criteria.milestone:
|
||||
params['milestone'] = filter_criteria.milestone
|
||||
|
||||
if filter_criteria.labels:
|
||||
params['labels'] = ','.join(filter_criteria.labels)
|
||||
|
||||
if filter_criteria.created_after:
|
||||
params['since'] = filter_criteria.created_after.isoformat()
|
||||
|
||||
if filter_criteria.limit:
|
||||
params['limit'] = filter_criteria.limit
|
||||
|
||||
if filter_criteria.offset:
|
||||
params['page'] = (filter_criteria.offset // (filter_criteria.limit or 30)) + 1
|
||||
|
||||
response = self._api_request('GET', f'/repos/{self.owner}/{self.repo}/issues', params=params)
|
||||
gitea_issues = response.json()
|
||||
|
||||
issues = [self._gitea_issue_to_unified(gitea_issue) for gitea_issue in gitea_issues]
|
||||
|
||||
# Apply additional filtering that Gitea API doesn't support
|
||||
if filter_criteria:
|
||||
if filter_criteria.search:
|
||||
search_term = filter_criteria.search.lower()
|
||||
issues = [
|
||||
issue for issue in issues
|
||||
if search_term in issue.title.lower() or search_term in issue.description.lower()
|
||||
]
|
||||
|
||||
return issues
|
||||
|
||||
def search_issues(self, query: str, limit: Optional[int] = None) -> List[Issue]:
|
||||
"""Search issues - limited Gitea API support."""
|
||||
# Gitea has limited search API, fallback to list with search filter
|
||||
filter_criteria = IssueFilter(search=query, limit=limit)
|
||||
return self.list_issues(filter_criteria)
|
||||
|
||||
# Label Operations
|
||||
def create_label(self, label: Label) -> Label:
|
||||
"""Create label in Gitea."""
|
||||
data = {
|
||||
'name': label.name,
|
||||
'color': label.color or '#000000',
|
||||
'description': label.description or ''
|
||||
}
|
||||
|
||||
response = self._api_request('POST', f'/repos/{self.owner}/{self.repo}/labels', data=data)
|
||||
gitea_label = response.json()
|
||||
|
||||
return Label(
|
||||
name=gitea_label['name'],
|
||||
color=gitea_label['color'],
|
||||
description=gitea_label.get('description', ''),
|
||||
backend_id=str(gitea_label['id'])
|
||||
)
|
||||
|
||||
def get_labels(self) -> List[Label]:
|
||||
"""Get all labels from Gitea."""
|
||||
response = self._api_request('GET', f'/repos/{self.owner}/{self.repo}/labels')
|
||||
gitea_labels = response.json()
|
||||
|
||||
return [Label(
|
||||
name=label['name'],
|
||||
color=label['color'],
|
||||
description=label.get('description', ''),
|
||||
backend_id=str(label['id'])
|
||||
) for label in gitea_labels]
|
||||
|
||||
def update_label(self, label: Label) -> Label:
|
||||
"""Update label in Gitea."""
|
||||
data = {
|
||||
'name': label.name,
|
||||
'color': label.color or '#000000',
|
||||
'description': label.description or ''
|
||||
}
|
||||
|
||||
response = self._api_request('PATCH', f'/repos/{self.owner}/{self.repo}/labels/{label.name}', data=data)
|
||||
gitea_label = response.json()
|
||||
|
||||
return Label(
|
||||
name=gitea_label['name'],
|
||||
color=gitea_label['color'],
|
||||
description=gitea_label.get('description', ''),
|
||||
backend_id=str(gitea_label['id'])
|
||||
)
|
||||
|
||||
def delete_label(self, label_name: str) -> bool:
|
||||
"""Delete label from Gitea."""
|
||||
try:
|
||||
self._api_request('DELETE', f'/repos/{self.owner}/{self.repo}/labels/{label_name}')
|
||||
return True
|
||||
except GiteaAPIError:
|
||||
return False
|
||||
|
||||
# User Operations
|
||||
def get_users(self) -> List[User]:
|
||||
"""Get repository collaborators."""
|
||||
response = self._api_request('GET', f'/repos/{self.owner}/{self.repo}/collaborators')
|
||||
gitea_users = response.json()
|
||||
|
||||
return [User(
|
||||
id=str(user['id']),
|
||||
username=user['login'],
|
||||
display_name=user.get('full_name', ''),
|
||||
email=user.get('email', ''),
|
||||
avatar_url=user.get('avatar_url', ''),
|
||||
backend_id=str(user['id'])
|
||||
) for user in gitea_users]
|
||||
|
||||
def get_user(self, user_id: str) -> Optional[User]:
|
||||
"""Get specific user."""
|
||||
try:
|
||||
response = self._api_request('GET', f'/users/{user_id}')
|
||||
user = response.json()
|
||||
return User(
|
||||
id=str(user['id']),
|
||||
username=user['login'],
|
||||
display_name=user.get('full_name', ''),
|
||||
email=user.get('email', ''),
|
||||
avatar_url=user.get('avatar_url', ''),
|
||||
backend_id=str(user['id'])
|
||||
)
|
||||
except GiteaAPIError:
|
||||
return None
|
||||
|
||||
def search_users(self, query: str) -> List[User]:
|
||||
"""Search users in Gitea."""
|
||||
params = {'q': query, 'limit': 50}
|
||||
response = self._api_request('GET', '/users/search', params=params)
|
||||
search_result = response.json()
|
||||
|
||||
return [User(
|
||||
id=str(user['id']),
|
||||
username=user['login'],
|
||||
display_name=user.get('full_name', ''),
|
||||
email=user.get('email', ''),
|
||||
avatar_url=user.get('avatar_url', ''),
|
||||
backend_id=str(user['id'])
|
||||
) for user in search_result.get('data', [])]
|
||||
|
||||
# Milestone Operations
|
||||
def create_milestone(self, milestone: Milestone) -> Milestone:
|
||||
"""Create milestone in Gitea."""
|
||||
data = {
|
||||
'title': milestone.title,
|
||||
'description': milestone.description or '',
|
||||
'due_on': milestone.due_date.isoformat() if milestone.due_date else None
|
||||
}
|
||||
|
||||
response = self._api_request('POST', f'/repos/{self.owner}/{self.repo}/milestones', data=data)
|
||||
gitea_milestone = response.json()
|
||||
|
||||
return Milestone(
|
||||
id=str(gitea_milestone['id']),
|
||||
title=gitea_milestone['title'],
|
||||
description=gitea_milestone.get('description', ''),
|
||||
state=gitea_milestone['state'],
|
||||
due_date=datetime.fromisoformat(gitea_milestone['due_on'].replace('Z', '+00:00')) if gitea_milestone.get('due_on') else None,
|
||||
created_at=datetime.fromisoformat(gitea_milestone['created_at'].replace('Z', '+00:00')),
|
||||
updated_at=datetime.fromisoformat(gitea_milestone['updated_at'].replace('Z', '+00:00')),
|
||||
backend_id=str(gitea_milestone['id'])
|
||||
)
|
||||
|
||||
def get_milestones(self) -> List[Milestone]:
|
||||
"""Get all milestones."""
|
||||
response = self._api_request('GET', f'/repos/{self.owner}/{self.repo}/milestones')
|
||||
gitea_milestones = response.json()
|
||||
|
||||
return [Milestone(
|
||||
id=str(m['id']),
|
||||
title=m['title'],
|
||||
description=m.get('description', ''),
|
||||
state=m['state'],
|
||||
due_date=datetime.fromisoformat(m['due_on'].replace('Z', '+00:00')) if m.get('due_on') else None,
|
||||
created_at=datetime.fromisoformat(m['created_at'].replace('Z', '+00:00')),
|
||||
updated_at=datetime.fromisoformat(m['updated_at'].replace('Z', '+00:00')),
|
||||
backend_id=str(m['id'])
|
||||
) for m in gitea_milestones]
|
||||
|
||||
def update_milestone(self, milestone: Milestone) -> Milestone:
|
||||
"""Update milestone."""
|
||||
data = {
|
||||
'title': milestone.title,
|
||||
'description': milestone.description or '',
|
||||
'state': milestone.state,
|
||||
'due_on': milestone.due_date.isoformat() if milestone.due_date else None
|
||||
}
|
||||
|
||||
response = self._api_request('PATCH', f'/repos/{self.owner}/{self.repo}/milestones/{milestone.backend_id}', data=data)
|
||||
gitea_milestone = response.json()
|
||||
|
||||
return Milestone(
|
||||
id=str(gitea_milestone['id']),
|
||||
title=gitea_milestone['title'],
|
||||
description=gitea_milestone.get('description', ''),
|
||||
state=gitea_milestone['state'],
|
||||
due_date=datetime.fromisoformat(gitea_milestone['due_on'].replace('Z', '+00:00')) if gitea_milestone.get('due_on') else None,
|
||||
created_at=datetime.fromisoformat(gitea_milestone['created_at'].replace('Z', '+00:00')),
|
||||
updated_at=datetime.fromisoformat(gitea_milestone['updated_at'].replace('Z', '+00:00')),
|
||||
backend_id=str(gitea_milestone['id'])
|
||||
)
|
||||
|
||||
def delete_milestone(self, milestone_id: str) -> bool:
|
||||
"""Delete milestone."""
|
||||
try:
|
||||
self._api_request('DELETE', f'/repos/{self.owner}/{self.repo}/milestones/{milestone_id}')
|
||||
return True
|
||||
except GiteaAPIError:
|
||||
return False
|
||||
|
||||
# Comment Operations
|
||||
def add_comment(self, issue_id: str, comment: Comment) -> Comment:
|
||||
"""Add comment to issue."""
|
||||
data = {'body': comment.body}
|
||||
|
||||
response = self._api_request('POST', f'/repos/{self.owner}/{self.repo}/issues/{issue_id}/comments', data=data)
|
||||
gitea_comment = response.json()
|
||||
|
||||
# Convert author
|
||||
author_data = gitea_comment['user']
|
||||
author = User(
|
||||
id=str(author_data['id']),
|
||||
username=author_data['login'],
|
||||
display_name=author_data.get('full_name', ''),
|
||||
email=author_data.get('email', ''),
|
||||
avatar_url=author_data.get('avatar_url', ''),
|
||||
backend_id=str(author_data['id'])
|
||||
)
|
||||
|
||||
return Comment(
|
||||
id=str(gitea_comment['id']),
|
||||
body=gitea_comment['body'],
|
||||
author=author,
|
||||
created_at=datetime.fromisoformat(gitea_comment['created_at'].replace('Z', '+00:00')),
|
||||
updated_at=datetime.fromisoformat(gitea_comment['updated_at'].replace('Z', '+00:00')),
|
||||
backend_id=str(gitea_comment['id'])
|
||||
)
|
||||
|
||||
def get_comments(self, issue_id: str) -> List[Comment]:
|
||||
"""Get comments for issue."""
|
||||
response = self._api_request('GET', f'/repos/{self.owner}/{self.repo}/issues/{issue_id}/comments')
|
||||
gitea_comments = response.json()
|
||||
|
||||
comments = []
|
||||
for gc in gitea_comments:
|
||||
author_data = gc['user']
|
||||
author = User(
|
||||
id=str(author_data['id']),
|
||||
username=author_data['login'],
|
||||
display_name=author_data.get('full_name', ''),
|
||||
email=author_data.get('email', ''),
|
||||
avatar_url=author_data.get('avatar_url', ''),
|
||||
backend_id=str(author_data['id'])
|
||||
)
|
||||
|
||||
comment = Comment(
|
||||
id=str(gc['id']),
|
||||
body=gc['body'],
|
||||
author=author,
|
||||
created_at=datetime.fromisoformat(gc['created_at'].replace('Z', '+00:00')),
|
||||
updated_at=datetime.fromisoformat(gc['updated_at'].replace('Z', '+00:00')),
|
||||
backend_id=str(gc['id'])
|
||||
)
|
||||
comments.append(comment)
|
||||
|
||||
return comments
|
||||
|
||||
def update_comment(self, comment: Comment) -> Comment:
|
||||
"""Update comment."""
|
||||
data = {'body': comment.body}
|
||||
|
||||
response = self._api_request('PATCH', f'/repos/{self.owner}/{self.repo}/issues/comments/{comment.backend_id}', data=data)
|
||||
gitea_comment = response.json()
|
||||
|
||||
# Update comment object
|
||||
comment.updated_at = datetime.fromisoformat(gitea_comment['updated_at'].replace('Z', '+00:00'))
|
||||
return comment
|
||||
|
||||
def delete_comment(self, comment_id: str) -> bool:
|
||||
"""Delete comment."""
|
||||
try:
|
||||
self._api_request('DELETE', f'/repos/{self.owner}/{self.repo}/issues/comments/{comment_id}')
|
||||
return True
|
||||
except GiteaAPIError:
|
||||
return False
|
||||
|
||||
# Sync Support
|
||||
def get_last_sync_timestamp(self) -> Optional[datetime]:
|
||||
"""Get last sync timestamp - stored in metadata."""
|
||||
# Could be stored in repository description or other metadata
|
||||
return None
|
||||
|
||||
def get_issues_modified_since(self, timestamp: datetime) -> List[Issue]:
|
||||
"""Get issues modified since timestamp."""
|
||||
filter_criteria = IssueFilter(updated_after=timestamp)
|
||||
return self.list_issues(filter_criteria)
|
||||
|
||||
# SyncableBackend Implementation
|
||||
def prepare_for_sync(self) -> None:
|
||||
"""Prepare for sync operation."""
|
||||
# Could implement rate limiting preparation
|
||||
pass
|
||||
|
||||
def finalize_sync(self, success: bool) -> None:
|
||||
"""Finalize sync operation."""
|
||||
# Could log sync status
|
||||
pass
|
||||
|
||||
def get_sync_conflicts(self) -> List[Dict[str, Any]]:
|
||||
"""Get sync conflicts."""
|
||||
# Would compare timestamps and detect conflicts
|
||||
return []
|
||||
|
||||
def resolve_sync_conflict(self, issue_id: str, resolution: str) -> Issue:
|
||||
"""Resolve sync conflict."""
|
||||
issue = self.get_issue(issue_id)
|
||||
if not issue:
|
||||
raise GiteaAPIError(f"Issue {issue_id} not found")
|
||||
|
||||
if resolution == 'remote':
|
||||
# Keep remote version (current issue)
|
||||
return issue
|
||||
elif resolution == 'local':
|
||||
# This would require the local version to be provided
|
||||
raise NotImplementedError("Local resolution requires local issue data")
|
||||
else:
|
||||
raise ValueError(f"Unknown resolution: {resolution}")
|
||||
@@ -1,19 +0,0 @@
|
||||
"""
|
||||
Local SQLite Backend
|
||||
|
||||
A local, file-based issue tracking backend using SQLite for storage.
|
||||
This backend provides complete offline functionality and serves as the
|
||||
reference implementation for the backend interface.
|
||||
|
||||
Features:
|
||||
- Full CRUD operations
|
||||
- SQLite database storage
|
||||
- No external dependencies
|
||||
- Offline operation
|
||||
- Fast local search
|
||||
- Backup and export capabilities
|
||||
"""
|
||||
|
||||
from .backend import LocalSQLiteBackend
|
||||
|
||||
__all__ = ['LocalSQLiteBackend']
|
||||
@@ -1,618 +0,0 @@
|
||||
"""
|
||||
Local SQLite Backend Implementation
|
||||
|
||||
Provides a complete local issue tracking backend using SQLite for storage.
|
||||
This implementation serves as the reference for the backend interface and
|
||||
provides full offline functionality.
|
||||
"""
|
||||
|
||||
import sqlite3
|
||||
import json
|
||||
import uuid
|
||||
from datetime import datetime, timezone
|
||||
from pathlib import Path
|
||||
from typing import List, Optional, Dict, Any
|
||||
|
||||
from ...core.interfaces import LocalBackend, BackendCapabilities, IssueFilter, SyncableBackend
|
||||
from ...core.models import Issue, Label, User, Milestone, Comment, IssueState, Priority, IssueType
|
||||
|
||||
|
||||
class LocalSQLiteBackend(LocalBackend, SyncableBackend):
|
||||
"""SQLite-based local backend for issue tracking."""
|
||||
|
||||
def __init__(self, db_path: Optional[str] = None):
|
||||
self.db_path = db_path or "issues.db"
|
||||
self.connection: Optional[sqlite3.Connection] = None
|
||||
self._capabilities = BackendCapabilities(
|
||||
supports_milestones=True,
|
||||
supports_assignees=True,
|
||||
supports_comments=True,
|
||||
supports_labels=True,
|
||||
supports_search=True,
|
||||
supports_bulk_operations=True,
|
||||
supports_webhooks=False,
|
||||
supports_real_time=False,
|
||||
max_labels_per_issue=None,
|
||||
max_assignees_per_issue=None
|
||||
)
|
||||
|
||||
@property
|
||||
def backend_type(self) -> str:
|
||||
return "local"
|
||||
|
||||
@property
|
||||
def capabilities(self) -> BackendCapabilities:
|
||||
return self._capabilities
|
||||
|
||||
def connect(self, config: Dict[str, Any]) -> None:
|
||||
"""Connect to SQLite database."""
|
||||
db_path = config.get('db_path', self.db_path)
|
||||
self.db_path = db_path
|
||||
|
||||
# Ensure directory exists
|
||||
Path(db_path).parent.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
self.connection = sqlite3.connect(db_path)
|
||||
self.connection.row_factory = sqlite3.Row # Enable dict-like access
|
||||
self.connection.execute("PRAGMA foreign_keys = ON")
|
||||
|
||||
# Initialize schema
|
||||
self._initialize_schema()
|
||||
|
||||
def disconnect(self) -> None:
|
||||
"""Disconnect from database."""
|
||||
if self.connection:
|
||||
self.connection.close()
|
||||
self.connection = None
|
||||
|
||||
def test_connection(self) -> bool:
|
||||
"""Test database connection."""
|
||||
if not self.connection:
|
||||
return False
|
||||
try:
|
||||
self.connection.execute("SELECT 1")
|
||||
return True
|
||||
except sqlite3.Error:
|
||||
return False
|
||||
|
||||
def _initialize_schema(self) -> None:
|
||||
"""Initialize database schema."""
|
||||
schema_path = Path(__file__).parent / "schema.sql"
|
||||
with open(schema_path, 'r') as f:
|
||||
schema_sql = f.read()
|
||||
|
||||
# Execute schema in parts (SQLite doesn't like multiple statements)
|
||||
for statement in schema_sql.split(';'):
|
||||
statement = statement.strip()
|
||||
if statement:
|
||||
self.connection.execute(statement)
|
||||
self.connection.commit()
|
||||
|
||||
def _get_next_issue_number(self) -> int:
|
||||
"""Get the next available issue number."""
|
||||
cursor = self.connection.execute("SELECT MAX(number) FROM issues")
|
||||
result = cursor.fetchone()
|
||||
return (result[0] or 0) + 1
|
||||
|
||||
def _issue_from_row(self, row: sqlite3.Row) -> Issue:
|
||||
"""Convert database row to Issue object."""
|
||||
# Get labels
|
||||
cursor = self.connection.execute("""
|
||||
SELECT l.id, l.name, l.color, l.description, l.backend_id
|
||||
FROM labels l
|
||||
JOIN issue_labels il ON l.id = il.label_id
|
||||
WHERE il.issue_id = ?
|
||||
""", (row['id'],))
|
||||
label_rows = cursor.fetchall()
|
||||
labels = [Label(
|
||||
name=lr['name'],
|
||||
color=lr['color'],
|
||||
description=lr['description'],
|
||||
backend_id=lr['backend_id']
|
||||
) for lr in label_rows]
|
||||
|
||||
# Get assignees
|
||||
cursor = self.connection.execute("""
|
||||
SELECT u.id, u.username, u.display_name, u.email, u.avatar_url, u.backend_id
|
||||
FROM users u
|
||||
JOIN issue_assignees ia ON u.id = ia.user_id
|
||||
WHERE ia.issue_id = ?
|
||||
""", (row['id'],))
|
||||
user_rows = cursor.fetchall()
|
||||
assignees = [User(
|
||||
id=ur['id'],
|
||||
username=ur['username'],
|
||||
display_name=ur['display_name'],
|
||||
email=ur['email'],
|
||||
avatar_url=ur['avatar_url'],
|
||||
backend_id=ur['backend_id']
|
||||
) for ur in user_rows]
|
||||
|
||||
# Get milestone
|
||||
milestone = None
|
||||
if row['milestone_id']:
|
||||
cursor = self.connection.execute("""
|
||||
SELECT id, title, description, state, due_date, created_at, updated_at, backend_id
|
||||
FROM milestones WHERE id = ?
|
||||
""", (row['milestone_id'],))
|
||||
m_row = cursor.fetchone()
|
||||
if m_row:
|
||||
milestone = Milestone(
|
||||
id=m_row['id'],
|
||||
title=m_row['title'],
|
||||
description=m_row['description'],
|
||||
state=m_row['state'],
|
||||
due_date=datetime.fromisoformat(m_row['due_date']) if m_row['due_date'] else None,
|
||||
created_at=datetime.fromisoformat(m_row['created_at']) if m_row['created_at'] else None,
|
||||
updated_at=datetime.fromisoformat(m_row['updated_at']) if m_row['updated_at'] else None,
|
||||
backend_id=m_row['backend_id']
|
||||
)
|
||||
|
||||
# Parse sync metadata
|
||||
sync_metadata = {}
|
||||
if row['sync_metadata']:
|
||||
try:
|
||||
sync_metadata = json.loads(row['sync_metadata'])
|
||||
except json.JSONDecodeError:
|
||||
pass
|
||||
|
||||
return Issue(
|
||||
id=row['id'],
|
||||
number=row['number'],
|
||||
title=row['title'],
|
||||
description=row['description'],
|
||||
state=IssueState.from_string(row['state']),
|
||||
created_at=datetime.fromisoformat(row['created_at']),
|
||||
updated_at=datetime.fromisoformat(row['updated_at']),
|
||||
closed_at=datetime.fromisoformat(row['closed_at']) if row['closed_at'] else None,
|
||||
labels=labels,
|
||||
assignees=assignees,
|
||||
milestone=milestone,
|
||||
backend_id=row['backend_id'],
|
||||
backend_type=row['backend_type'],
|
||||
sync_metadata=sync_metadata
|
||||
)
|
||||
|
||||
# Issue CRUD Operations
|
||||
def create_issue(self, issue: Issue) -> Issue:
|
||||
"""Create a new issue."""
|
||||
if not issue.id:
|
||||
issue.id = str(uuid.uuid4())
|
||||
|
||||
if not issue.number:
|
||||
issue.number = self._get_next_issue_number()
|
||||
|
||||
# Insert issue
|
||||
self.connection.execute("""
|
||||
INSERT INTO issues (id, number, title, description, state, created_at, updated_at,
|
||||
closed_at, milestone_id, backend_id, backend_type, sync_metadata)
|
||||
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
|
||||
""", (
|
||||
issue.id,
|
||||
issue.number,
|
||||
issue.title,
|
||||
issue.description,
|
||||
issue.state.value,
|
||||
issue.created_at.isoformat(),
|
||||
issue.updated_at.isoformat(),
|
||||
issue.closed_at.isoformat() if issue.closed_at else None,
|
||||
issue.milestone.id if issue.milestone else None,
|
||||
issue.backend_id,
|
||||
issue.backend_type or 'local',
|
||||
json.dumps(issue.sync_metadata) if issue.sync_metadata else None
|
||||
))
|
||||
|
||||
# Add labels
|
||||
for label in issue.labels:
|
||||
self._ensure_label_exists(label)
|
||||
self.connection.execute("""
|
||||
INSERT OR IGNORE INTO issue_labels (issue_id, label_id)
|
||||
VALUES (?, ?)
|
||||
""", (issue.id, label.name)) # Using name as ID for simplicity
|
||||
|
||||
# Add assignees
|
||||
for user in issue.assignees:
|
||||
self._ensure_user_exists(user)
|
||||
self.connection.execute("""
|
||||
INSERT OR IGNORE INTO issue_assignees (issue_id, user_id)
|
||||
VALUES (?, ?)
|
||||
""", (issue.id, user.id))
|
||||
|
||||
self.connection.commit()
|
||||
return issue
|
||||
|
||||
def get_issue(self, issue_id: str) -> Optional[Issue]:
|
||||
"""Get issue by ID."""
|
||||
cursor = self.connection.execute("""
|
||||
SELECT * FROM issues WHERE id = ? OR backend_id = ?
|
||||
""", (issue_id, issue_id))
|
||||
row = cursor.fetchone()
|
||||
return self._issue_from_row(row) if row else None
|
||||
|
||||
def get_issue_by_number(self, number: int) -> Optional[Issue]:
|
||||
"""Get issue by number."""
|
||||
cursor = self.connection.execute("""
|
||||
SELECT * FROM issues WHERE number = ?
|
||||
""", (number,))
|
||||
row = cursor.fetchone()
|
||||
return self._issue_from_row(row) if row else None
|
||||
|
||||
def update_issue(self, issue: Issue) -> Issue:
|
||||
"""Update existing issue."""
|
||||
# Update main issue record
|
||||
self.connection.execute("""
|
||||
UPDATE issues SET
|
||||
title = ?, description = ?, state = ?, updated_at = ?,
|
||||
closed_at = ?, milestone_id = ?, sync_metadata = ?
|
||||
WHERE id = ?
|
||||
""", (
|
||||
issue.title,
|
||||
issue.description,
|
||||
issue.state.value,
|
||||
issue.updated_at.isoformat(),
|
||||
issue.closed_at.isoformat() if issue.closed_at else None,
|
||||
issue.milestone.id if issue.milestone else None,
|
||||
json.dumps(issue.sync_metadata) if issue.sync_metadata else None,
|
||||
issue.id
|
||||
))
|
||||
|
||||
# Update labels (remove all and re-add)
|
||||
self.connection.execute("DELETE FROM issue_labels WHERE issue_id = ?", (issue.id,))
|
||||
for label in issue.labels:
|
||||
self._ensure_label_exists(label)
|
||||
self.connection.execute("""
|
||||
INSERT INTO issue_labels (issue_id, label_id) VALUES (?, ?)
|
||||
""", (issue.id, label.name))
|
||||
|
||||
# Update assignees (remove all and re-add)
|
||||
self.connection.execute("DELETE FROM issue_assignees WHERE issue_id = ?", (issue.id,))
|
||||
for user in issue.assignees:
|
||||
self._ensure_user_exists(user)
|
||||
self.connection.execute("""
|
||||
INSERT INTO issue_assignees (issue_id, user_id) VALUES (?, ?)
|
||||
""", (issue.id, user.id))
|
||||
|
||||
self.connection.commit()
|
||||
return issue
|
||||
|
||||
def delete_issue(self, issue_id: str) -> bool:
|
||||
"""Delete issue."""
|
||||
cursor = self.connection.execute("DELETE FROM issues WHERE id = ?", (issue_id,))
|
||||
self.connection.commit()
|
||||
return cursor.rowcount > 0
|
||||
|
||||
def list_issues(self, filter_criteria: Optional[IssueFilter] = None) -> List[Issue]:
|
||||
"""List issues with optional filtering."""
|
||||
query = "SELECT * FROM issues WHERE 1=1"
|
||||
params = []
|
||||
|
||||
if filter_criteria:
|
||||
if filter_criteria.state:
|
||||
query += " AND state = ?"
|
||||
params.append(filter_criteria.state)
|
||||
|
||||
if filter_criteria.search:
|
||||
query += " AND (title LIKE ? OR description LIKE ?)"
|
||||
search_term = f"%{filter_criteria.search}%"
|
||||
params.extend([search_term, search_term])
|
||||
|
||||
if filter_criteria.created_after:
|
||||
query += " AND created_at >= ?"
|
||||
params.append(filter_criteria.created_after.isoformat())
|
||||
|
||||
if filter_criteria.created_before:
|
||||
query += " AND created_at <= ?"
|
||||
params.append(filter_criteria.created_before.isoformat())
|
||||
|
||||
if filter_criteria.updated_after:
|
||||
query += " AND updated_at >= ?"
|
||||
params.append(filter_criteria.updated_after.isoformat())
|
||||
|
||||
if filter_criteria.updated_before:
|
||||
query += " AND updated_at <= ?"
|
||||
params.append(filter_criteria.updated_before.isoformat())
|
||||
|
||||
query += " ORDER BY updated_at DESC"
|
||||
|
||||
if filter_criteria and filter_criteria.limit:
|
||||
query += " LIMIT ?"
|
||||
params.append(filter_criteria.limit)
|
||||
if filter_criteria.offset:
|
||||
query += " OFFSET ?"
|
||||
params.append(filter_criteria.offset)
|
||||
|
||||
cursor = self.connection.execute(query, params)
|
||||
rows = cursor.fetchall()
|
||||
return [self._issue_from_row(row) for row in rows]
|
||||
|
||||
def search_issues(self, query: str, limit: Optional[int] = None) -> List[Issue]:
|
||||
"""Search issues using FTS if available, otherwise fallback to LIKE."""
|
||||
try:
|
||||
# Try FTS search first
|
||||
fts_query = """
|
||||
SELECT i.* FROM issues i
|
||||
JOIN issue_search s ON i.id = s.issue_id
|
||||
WHERE issue_search MATCH ?
|
||||
ORDER BY rank
|
||||
"""
|
||||
params = [query]
|
||||
if limit:
|
||||
fts_query += " LIMIT ?"
|
||||
params.append(limit)
|
||||
|
||||
cursor = self.connection.execute(fts_query, params)
|
||||
rows = cursor.fetchall()
|
||||
return [self._issue_from_row(row) for row in rows]
|
||||
|
||||
except sqlite3.OperationalError:
|
||||
# Fallback to LIKE search
|
||||
filter_criteria = IssueFilter(search=query, limit=limit)
|
||||
return self.list_issues(filter_criteria)
|
||||
|
||||
# Helper methods
|
||||
def _ensure_label_exists(self, label: Label) -> None:
|
||||
"""Ensure label exists in database."""
|
||||
self.connection.execute("""
|
||||
INSERT OR IGNORE INTO labels (id, name, color, description, backend_id)
|
||||
VALUES (?, ?, ?, ?, ?)
|
||||
""", (label.name, label.name, label.color, label.description, label.backend_id))
|
||||
|
||||
def _ensure_user_exists(self, user: User) -> None:
|
||||
"""Ensure user exists in database."""
|
||||
self.connection.execute("""
|
||||
INSERT OR IGNORE INTO users (id, username, display_name, email, avatar_url, backend_id)
|
||||
VALUES (?, ?, ?, ?, ?, ?)
|
||||
""", (user.id, user.username, user.display_name, user.email, user.avatar_url, user.backend_id))
|
||||
|
||||
# Label Operations
|
||||
def create_label(self, label: Label) -> Label:
|
||||
"""Create a new label."""
|
||||
label_id = label.name # Use name as ID
|
||||
self.connection.execute("""
|
||||
INSERT INTO labels (id, name, color, description, backend_id)
|
||||
VALUES (?, ?, ?, ?, ?)
|
||||
""", (label_id, label.name, label.color, label.description, label.backend_id))
|
||||
self.connection.commit()
|
||||
return label
|
||||
|
||||
def get_labels(self) -> List[Label]:
|
||||
"""Get all labels."""
|
||||
cursor = self.connection.execute("SELECT * FROM labels ORDER BY name")
|
||||
rows = cursor.fetchall()
|
||||
return [Label(
|
||||
name=row['name'],
|
||||
color=row['color'],
|
||||
description=row['description'],
|
||||
backend_id=row['backend_id']
|
||||
) for row in rows]
|
||||
|
||||
def update_label(self, label: Label) -> Label:
|
||||
"""Update label."""
|
||||
self.connection.execute("""
|
||||
UPDATE labels SET color = ?, description = ? WHERE name = ?
|
||||
""", (label.color, label.description, label.name))
|
||||
self.connection.commit()
|
||||
return label
|
||||
|
||||
def delete_label(self, label_name: str) -> bool:
|
||||
"""Delete label."""
|
||||
cursor = self.connection.execute("DELETE FROM labels WHERE name = ?", (label_name,))
|
||||
self.connection.commit()
|
||||
return cursor.rowcount > 0
|
||||
|
||||
# User Operations
|
||||
def get_users(self) -> List[User]:
|
||||
"""Get all users."""
|
||||
cursor = self.connection.execute("SELECT * FROM users ORDER BY username")
|
||||
rows = cursor.fetchall()
|
||||
return [User(
|
||||
id=row['id'],
|
||||
username=row['username'],
|
||||
display_name=row['display_name'],
|
||||
email=row['email'],
|
||||
avatar_url=row['avatar_url'],
|
||||
backend_id=row['backend_id']
|
||||
) for row in rows]
|
||||
|
||||
def get_user(self, user_id: str) -> Optional[User]:
|
||||
"""Get user by ID."""
|
||||
cursor = self.connection.execute("SELECT * FROM users WHERE id = ?", (user_id,))
|
||||
row = cursor.fetchone()
|
||||
if row:
|
||||
return User(
|
||||
id=row['id'],
|
||||
username=row['username'],
|
||||
display_name=row['display_name'],
|
||||
email=row['email'],
|
||||
avatar_url=row['avatar_url'],
|
||||
backend_id=row['backend_id']
|
||||
)
|
||||
return None
|
||||
|
||||
def search_users(self, query: str) -> List[User]:
|
||||
"""Search users."""
|
||||
cursor = self.connection.execute("""
|
||||
SELECT * FROM users
|
||||
WHERE username LIKE ? OR display_name LIKE ? OR email LIKE ?
|
||||
ORDER BY username
|
||||
""", (f"%{query}%", f"%{query}%", f"%{query}%"))
|
||||
rows = cursor.fetchall()
|
||||
return [User(
|
||||
id=row['id'],
|
||||
username=row['username'],
|
||||
display_name=row['display_name'],
|
||||
email=row['email'],
|
||||
avatar_url=row['avatar_url'],
|
||||
backend_id=row['backend_id']
|
||||
) for row in rows]
|
||||
|
||||
# Milestone Operations
|
||||
def create_milestone(self, milestone: Milestone) -> Milestone:
|
||||
"""Create milestone."""
|
||||
if not milestone.id:
|
||||
milestone.id = str(uuid.uuid4())
|
||||
|
||||
self.connection.execute("""
|
||||
INSERT INTO milestones (id, title, description, state, due_date, created_at, updated_at, backend_id)
|
||||
VALUES (?, ?, ?, ?, ?, ?, ?, ?)
|
||||
""", (
|
||||
milestone.id,
|
||||
milestone.title,
|
||||
milestone.description,
|
||||
milestone.state,
|
||||
milestone.due_date.isoformat() if milestone.due_date else None,
|
||||
milestone.created_at.isoformat() if milestone.created_at else datetime.now(timezone.utc).isoformat(),
|
||||
milestone.updated_at.isoformat() if milestone.updated_at else datetime.now(timezone.utc).isoformat(),
|
||||
milestone.backend_id
|
||||
))
|
||||
self.connection.commit()
|
||||
return milestone
|
||||
|
||||
def get_milestones(self) -> List[Milestone]:
|
||||
"""Get all milestones."""
|
||||
cursor = self.connection.execute("SELECT * FROM milestones ORDER BY title")
|
||||
rows = cursor.fetchall()
|
||||
return [Milestone(
|
||||
id=row['id'],
|
||||
title=row['title'],
|
||||
description=row['description'],
|
||||
state=row['state'],
|
||||
due_date=datetime.fromisoformat(row['due_date']) if row['due_date'] else None,
|
||||
created_at=datetime.fromisoformat(row['created_at']) if row['created_at'] else None,
|
||||
updated_at=datetime.fromisoformat(row['updated_at']) if row['updated_at'] else None,
|
||||
backend_id=row['backend_id']
|
||||
) for row in rows]
|
||||
|
||||
def update_milestone(self, milestone: Milestone) -> Milestone:
|
||||
"""Update milestone."""
|
||||
self.connection.execute("""
|
||||
UPDATE milestones SET title = ?, description = ?, state = ?, due_date = ?, updated_at = ?
|
||||
WHERE id = ?
|
||||
""", (
|
||||
milestone.title,
|
||||
milestone.description,
|
||||
milestone.state,
|
||||
milestone.due_date.isoformat() if milestone.due_date else None,
|
||||
datetime.now(timezone.utc).isoformat(),
|
||||
milestone.id
|
||||
))
|
||||
self.connection.commit()
|
||||
return milestone
|
||||
|
||||
def delete_milestone(self, milestone_id: str) -> bool:
|
||||
"""Delete milestone."""
|
||||
cursor = self.connection.execute("DELETE FROM milestones WHERE id = ?", (milestone_id,))
|
||||
self.connection.commit()
|
||||
return cursor.rowcount > 0
|
||||
|
||||
# Comment Operations
|
||||
def add_comment(self, issue_id: str, comment: Comment) -> Comment:
|
||||
"""Add comment to issue."""
|
||||
if not comment.id:
|
||||
comment.id = str(uuid.uuid4())
|
||||
|
||||
self._ensure_user_exists(comment.author)
|
||||
|
||||
self.connection.execute("""
|
||||
INSERT INTO comments (id, issue_id, author_id, body, created_at, updated_at, backend_id)
|
||||
VALUES (?, ?, ?, ?, ?, ?, ?)
|
||||
""", (
|
||||
comment.id,
|
||||
issue_id,
|
||||
comment.author.id,
|
||||
comment.body,
|
||||
comment.created_at.isoformat(),
|
||||
comment.updated_at.isoformat() if comment.updated_at else None,
|
||||
comment.backend_id
|
||||
))
|
||||
self.connection.commit()
|
||||
return comment
|
||||
|
||||
def get_comments(self, issue_id: str) -> List[Comment]:
|
||||
"""Get comments for issue."""
|
||||
cursor = self.connection.execute("""
|
||||
SELECT c.*, u.id as user_id, u.username, u.display_name, u.email, u.avatar_url, u.backend_id as user_backend_id
|
||||
FROM comments c
|
||||
JOIN users u ON c.author_id = u.id
|
||||
WHERE c.issue_id = ?
|
||||
ORDER BY c.created_at
|
||||
""", (issue_id,))
|
||||
rows = cursor.fetchall()
|
||||
|
||||
comments = []
|
||||
for row in rows:
|
||||
author = User(
|
||||
id=row['user_id'],
|
||||
username=row['username'],
|
||||
display_name=row['display_name'],
|
||||
email=row['email'],
|
||||
avatar_url=row['avatar_url'],
|
||||
backend_id=row['user_backend_id']
|
||||
)
|
||||
comment = Comment(
|
||||
id=row['id'],
|
||||
body=row['body'],
|
||||
author=author,
|
||||
created_at=datetime.fromisoformat(row['created_at']),
|
||||
updated_at=datetime.fromisoformat(row['updated_at']) if row['updated_at'] else None,
|
||||
backend_id=row['backend_id']
|
||||
)
|
||||
comments.append(comment)
|
||||
|
||||
return comments
|
||||
|
||||
def update_comment(self, comment: Comment) -> Comment:
|
||||
"""Update comment."""
|
||||
self.connection.execute("""
|
||||
UPDATE comments SET body = ?, updated_at = ? WHERE id = ?
|
||||
""", (comment.body, datetime.now(timezone.utc).isoformat(), comment.id))
|
||||
self.connection.commit()
|
||||
return comment
|
||||
|
||||
def delete_comment(self, comment_id: str) -> bool:
|
||||
"""Delete comment."""
|
||||
cursor = self.connection.execute("DELETE FROM comments WHERE id = ?", (comment_id,))
|
||||
self.connection.commit()
|
||||
return cursor.rowcount > 0
|
||||
|
||||
# Sync Support
|
||||
def get_last_sync_timestamp(self) -> Optional[datetime]:
|
||||
"""Get last sync timestamp."""
|
||||
cursor = self.connection.execute("""
|
||||
SELECT sync_timestamp FROM sync_history
|
||||
WHERE success = 1
|
||||
ORDER BY sync_timestamp DESC
|
||||
LIMIT 1
|
||||
""")
|
||||
row = cursor.fetchone()
|
||||
return datetime.fromisoformat(row[0]) if row else None
|
||||
|
||||
def get_issues_modified_since(self, timestamp: datetime) -> List[Issue]:
|
||||
"""Get issues modified since timestamp."""
|
||||
filter_criteria = IssueFilter(updated_after=timestamp)
|
||||
return self.list_issues(filter_criteria)
|
||||
|
||||
# SyncableBackend Implementation
|
||||
def prepare_for_sync(self) -> None:
|
||||
"""Prepare for sync operation."""
|
||||
# Could create backup or start transaction
|
||||
pass
|
||||
|
||||
def finalize_sync(self, success: bool) -> None:
|
||||
"""Finalize sync operation."""
|
||||
# Log sync operation
|
||||
self.connection.execute("""
|
||||
INSERT INTO sync_history (backend_type, success, sync_timestamp)
|
||||
VALUES (?, ?, ?)
|
||||
""", ('sync', success, datetime.now(timezone.utc).isoformat()))
|
||||
self.connection.commit()
|
||||
|
||||
def get_sync_conflicts(self) -> List[Dict[str, Any]]:
|
||||
"""Get sync conflicts."""
|
||||
# For local backend, no conflicts since it's the source of truth
|
||||
return []
|
||||
|
||||
def resolve_sync_conflict(self, issue_id: str, resolution: str) -> Issue:
|
||||
"""Resolve sync conflict."""
|
||||
# Local backend doesn't have conflicts
|
||||
return self.get_issue(issue_id)
|
||||
@@ -1,189 +0,0 @@
|
||||
-- Local Issue Tracking Database Schema
|
||||
-- SQLite schema for local issue storage with full referential integrity
|
||||
|
||||
-- Enable foreign key constraints
|
||||
PRAGMA foreign_keys = ON;
|
||||
|
||||
-- Issues table - core issue data
|
||||
CREATE TABLE IF NOT EXISTS issues (
|
||||
id TEXT PRIMARY KEY,
|
||||
number INTEGER UNIQUE NOT NULL,
|
||||
title TEXT NOT NULL,
|
||||
description TEXT NOT NULL DEFAULT '',
|
||||
state TEXT NOT NULL CHECK (state IN ('open', 'closed', 'in_progress', 'blocked')),
|
||||
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
closed_at TIMESTAMP NULL,
|
||||
milestone_id TEXT,
|
||||
backend_id TEXT,
|
||||
backend_type TEXT DEFAULT 'local',
|
||||
sync_metadata TEXT, -- JSON for sync data
|
||||
FOREIGN KEY (milestone_id) REFERENCES milestones(id) ON DELETE SET NULL
|
||||
);
|
||||
|
||||
-- Create index for issue number lookups
|
||||
CREATE INDEX IF NOT EXISTS idx_issues_number ON issues(number);
|
||||
CREATE INDEX IF NOT EXISTS idx_issues_state ON issues(state);
|
||||
CREATE INDEX IF NOT EXISTS idx_issues_updated_at ON issues(updated_at);
|
||||
CREATE INDEX IF NOT EXISTS idx_issues_backend_id ON issues(backend_id);
|
||||
|
||||
-- Labels table
|
||||
CREATE TABLE IF NOT EXISTS labels (
|
||||
id TEXT PRIMARY KEY,
|
||||
name TEXT UNIQUE NOT NULL,
|
||||
color TEXT,
|
||||
description TEXT,
|
||||
backend_id TEXT,
|
||||
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
|
||||
-- Create index for label name lookups
|
||||
CREATE INDEX IF NOT EXISTS idx_labels_name ON labels(name);
|
||||
|
||||
-- Issue-Label many-to-many relationship
|
||||
CREATE TABLE IF NOT EXISTS issue_labels (
|
||||
issue_id TEXT NOT NULL,
|
||||
label_id TEXT NOT NULL,
|
||||
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
PRIMARY KEY (issue_id, label_id),
|
||||
FOREIGN KEY (issue_id) REFERENCES issues(id) ON DELETE CASCADE,
|
||||
FOREIGN KEY (label_id) REFERENCES labels(id) ON DELETE CASCADE
|
||||
);
|
||||
|
||||
-- Users table
|
||||
CREATE TABLE IF NOT EXISTS users (
|
||||
id TEXT PRIMARY KEY,
|
||||
username TEXT UNIQUE NOT NULL,
|
||||
display_name TEXT,
|
||||
email TEXT,
|
||||
avatar_url TEXT,
|
||||
backend_id TEXT,
|
||||
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
|
||||
-- Create index for username lookups
|
||||
CREATE INDEX IF NOT EXISTS idx_users_username ON users(username);
|
||||
|
||||
-- Issue-User assignment many-to-many relationship
|
||||
CREATE TABLE IF NOT EXISTS issue_assignees (
|
||||
issue_id TEXT NOT NULL,
|
||||
user_id TEXT NOT NULL,
|
||||
assigned_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
PRIMARY KEY (issue_id, user_id),
|
||||
FOREIGN KEY (issue_id) REFERENCES issues(id) ON DELETE CASCADE,
|
||||
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
|
||||
);
|
||||
|
||||
-- Milestones table
|
||||
CREATE TABLE IF NOT EXISTS milestones (
|
||||
id TEXT PRIMARY KEY,
|
||||
title TEXT NOT NULL,
|
||||
description TEXT,
|
||||
state TEXT NOT NULL DEFAULT 'open' CHECK (state IN ('open', 'closed')),
|
||||
due_date TIMESTAMP,
|
||||
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
backend_id TEXT
|
||||
);
|
||||
|
||||
-- Create index for milestone title lookups
|
||||
CREATE INDEX IF NOT EXISTS idx_milestones_title ON milestones(title);
|
||||
|
||||
-- Comments table
|
||||
CREATE TABLE IF NOT EXISTS comments (
|
||||
id TEXT PRIMARY KEY,
|
||||
issue_id TEXT NOT NULL,
|
||||
author_id TEXT NOT NULL,
|
||||
body TEXT NOT NULL,
|
||||
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP,
|
||||
backend_id TEXT,
|
||||
FOREIGN KEY (issue_id) REFERENCES issues(id) ON DELETE CASCADE,
|
||||
FOREIGN KEY (author_id) REFERENCES users(id) ON DELETE CASCADE
|
||||
);
|
||||
|
||||
-- Create index for comment lookups
|
||||
CREATE INDEX IF NOT EXISTS idx_comments_issue_id ON comments(issue_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_comments_created_at ON comments(created_at);
|
||||
|
||||
-- Sync tracking table
|
||||
CREATE TABLE IF NOT EXISTS sync_history (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
backend_type TEXT NOT NULL,
|
||||
sync_timestamp TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
success BOOLEAN NOT NULL,
|
||||
issues_synced INTEGER DEFAULT 0,
|
||||
errors_count INTEGER DEFAULT 0,
|
||||
details TEXT -- JSON for sync details
|
||||
);
|
||||
|
||||
-- Configuration table for backend settings
|
||||
CREATE TABLE IF NOT EXISTS config (
|
||||
key TEXT PRIMARY KEY,
|
||||
value TEXT NOT NULL,
|
||||
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
|
||||
-- Triggers to automatically update updated_at timestamps
|
||||
CREATE TRIGGER IF NOT EXISTS update_issues_timestamp
|
||||
AFTER UPDATE ON issues
|
||||
BEGIN
|
||||
UPDATE issues SET updated_at = CURRENT_TIMESTAMP WHERE id = NEW.id;
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS update_milestones_timestamp
|
||||
AFTER UPDATE ON milestones
|
||||
BEGIN
|
||||
UPDATE milestones SET updated_at = CURRENT_TIMESTAMP WHERE id = NEW.id;
|
||||
END;
|
||||
|
||||
-- Views for common queries
|
||||
CREATE VIEW IF NOT EXISTS issue_summary AS
|
||||
SELECT
|
||||
i.id,
|
||||
i.number,
|
||||
i.title,
|
||||
i.state,
|
||||
i.created_at,
|
||||
i.updated_at,
|
||||
i.closed_at,
|
||||
m.title as milestone_title,
|
||||
COUNT(c.id) as comment_count,
|
||||
GROUP_CONCAT(l.name) as labels,
|
||||
GROUP_CONCAT(u.username) as assignees
|
||||
FROM issues i
|
||||
LEFT JOIN milestones m ON i.milestone_id = m.id
|
||||
LEFT JOIN comments c ON i.id = c.issue_id
|
||||
LEFT JOIN issue_labels il ON i.id = il.issue_id
|
||||
LEFT JOIN labels l ON il.label_id = l.id
|
||||
LEFT JOIN issue_assignees ia ON i.id = ia.issue_id
|
||||
LEFT JOIN users u ON ia.user_id = u.id
|
||||
GROUP BY i.id, i.number, i.title, i.state, i.created_at, i.updated_at, i.closed_at, m.title;
|
||||
|
||||
-- Full-text search setup (if SQLite supports FTS)
|
||||
CREATE VIRTUAL TABLE IF NOT EXISTS issue_search USING fts5(
|
||||
issue_id,
|
||||
title,
|
||||
description,
|
||||
labels,
|
||||
content='issues'
|
||||
);
|
||||
|
||||
-- Trigger to keep FTS index updated
|
||||
CREATE TRIGGER IF NOT EXISTS issue_search_insert AFTER INSERT ON issues
|
||||
BEGIN
|
||||
INSERT INTO issue_search(issue_id, title, description)
|
||||
VALUES (NEW.id, NEW.title, NEW.description);
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS issue_search_update AFTER UPDATE ON issues
|
||||
BEGIN
|
||||
UPDATE issue_search
|
||||
SET title = NEW.title, description = NEW.description
|
||||
WHERE issue_id = NEW.id;
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS issue_search_delete AFTER DELETE ON issues
|
||||
BEGIN
|
||||
DELETE FROM issue_search WHERE issue_id = OLD.id;
|
||||
END;
|
||||
@@ -1,20 +0,0 @@
|
||||
"""
|
||||
Command Line Interface for Universal Issue Tracking
|
||||
|
||||
Provides a comprehensive CLI for managing issues across different backends.
|
||||
The CLI is designed to be intuitive and follows common patterns from
|
||||
tools like git, gh (GitHub CLI), and similar utilities.
|
||||
|
||||
Commands:
|
||||
- issue list: List issues
|
||||
- issue show: Show issue details
|
||||
- issue create: Create new issue
|
||||
- issue edit: Edit existing issue
|
||||
- issue close: Close issue
|
||||
- issue reopen: Reopen issue
|
||||
- issue comment: Add comment
|
||||
- issue label: Manage labels
|
||||
- issue assign: Manage assignments
|
||||
- backend: Manage backends
|
||||
- sync: Synchronization operations
|
||||
"""
|
||||
@@ -1,141 +0,0 @@
|
||||
"""
|
||||
Backend Management CLI Commands
|
||||
|
||||
Commands for configuring and managing issue tracking backends.
|
||||
"""
|
||||
|
||||
import click
|
||||
from .utils import (
|
||||
load_backend_configs, save_backend_configs, format_backend_list,
|
||||
test_backend_connection, validate_backend_type, echo_success,
|
||||
echo_error, echo_warning, confirm_action
|
||||
)
|
||||
|
||||
|
||||
@click.group()
|
||||
def backend_group():
|
||||
"""Backend configuration and management."""
|
||||
pass
|
||||
|
||||
|
||||
@backend_group.command('list')
|
||||
def list_backends():
|
||||
"""List configured backends."""
|
||||
configs = load_backend_configs()
|
||||
click.echo(format_backend_list(configs))
|
||||
|
||||
|
||||
@backend_group.command('add')
|
||||
@click.argument('name')
|
||||
@click.argument('backend_type', type=click.Choice(['local', 'gitea']))
|
||||
@click.pass_context
|
||||
def add_backend(ctx, name, backend_type):
|
||||
"""Add a new backend configuration."""
|
||||
configs = load_backend_configs()
|
||||
|
||||
if name in configs:
|
||||
if not confirm_action(f"Backend '{name}' already exists. Overwrite?"):
|
||||
click.echo("Aborted")
|
||||
return
|
||||
|
||||
if backend_type == 'local':
|
||||
db_path = click.prompt('Database path', default=f'~/.config/issue-tracker/{name}.db')
|
||||
config = {
|
||||
'type': 'local',
|
||||
'db_path': str(db_path)
|
||||
}
|
||||
elif backend_type == 'gitea':
|
||||
base_url = click.prompt('Gitea base URL (e.g., https://git.example.com)')
|
||||
owner = click.prompt('Repository owner/organization')
|
||||
repo = click.prompt('Repository name')
|
||||
token = click.prompt('Access token', hide_input=True)
|
||||
|
||||
config = {
|
||||
'type': 'gitea',
|
||||
'base_url': base_url.rstrip('/'),
|
||||
'owner': owner,
|
||||
'repo': repo,
|
||||
'token': token
|
||||
}
|
||||
|
||||
# Test connection
|
||||
click.echo("Testing connection...")
|
||||
if test_backend_connection(config):
|
||||
echo_success("Connection successful!")
|
||||
else:
|
||||
echo_warning("Connection test failed, but configuration will be saved anyway.")
|
||||
|
||||
# Save configuration
|
||||
configs[name] = config
|
||||
save_backend_configs(configs)
|
||||
|
||||
echo_success(f"Backend '{name}' added successfully")
|
||||
|
||||
# Set as default if it's the first one
|
||||
if 'default' not in configs:
|
||||
configs['default'] = name
|
||||
save_backend_configs(configs)
|
||||
echo_info(f"Set '{name}' as default backend")
|
||||
|
||||
|
||||
@backend_group.command('remove')
|
||||
@click.argument('name')
|
||||
def remove_backend(name):
|
||||
"""Remove a backend configuration."""
|
||||
configs = load_backend_configs()
|
||||
|
||||
if name not in configs:
|
||||
echo_error(f"Backend '{name}' not found")
|
||||
return
|
||||
|
||||
if not confirm_action(f"Remove backend '{name}'?"):
|
||||
click.echo("Aborted")
|
||||
return
|
||||
|
||||
del configs[name]
|
||||
|
||||
# Update default if necessary
|
||||
if configs.get('default') == name:
|
||||
remaining_backends = [k for k in configs.keys() if k != 'default']
|
||||
if remaining_backends:
|
||||
configs['default'] = remaining_backends[0]
|
||||
echo_info(f"Set '{configs['default']}' as new default backend")
|
||||
else:
|
||||
del configs['default']
|
||||
|
||||
save_backend_configs(configs)
|
||||
echo_success(f"Backend '{name}' removed")
|
||||
|
||||
|
||||
@backend_group.command('test')
|
||||
@click.argument('name')
|
||||
def test_backend(name):
|
||||
"""Test backend connection."""
|
||||
configs = load_backend_configs()
|
||||
|
||||
if name not in configs:
|
||||
echo_error(f"Backend '{name}' not found")
|
||||
return
|
||||
|
||||
config = configs[name]
|
||||
click.echo(f"Testing connection to '{name}'...")
|
||||
|
||||
if test_backend_connection(config):
|
||||
echo_success("Connection successful!")
|
||||
else:
|
||||
echo_error("Connection failed!")
|
||||
|
||||
|
||||
@backend_group.command('set-default')
|
||||
@click.argument('name')
|
||||
def set_default_backend(name):
|
||||
"""Set default backend."""
|
||||
configs = load_backend_configs()
|
||||
|
||||
if name not in configs:
|
||||
echo_error(f"Backend '{name}' not found")
|
||||
return
|
||||
|
||||
configs['default'] = name
|
||||
save_backend_configs(configs)
|
||||
echo_success(f"Set '{name}' as default backend")
|
||||
@@ -1,417 +0,0 @@
|
||||
"""
|
||||
Issue Management CLI Commands
|
||||
|
||||
Core commands for managing issues: create, list, show, edit, close, etc.
|
||||
"""
|
||||
|
||||
import click
|
||||
from datetime import datetime, timezone
|
||||
from typing import Optional
|
||||
|
||||
from ..core.models import Issue, Label, User, IssueState, Priority, IssueType
|
||||
from ..core.interfaces import IssueFilter
|
||||
from .utils import get_backend, format_issue, format_issue_list, get_user_input
|
||||
|
||||
|
||||
@click.group()
|
||||
def issue_group():
|
||||
"""Issue management commands."""
|
||||
pass
|
||||
|
||||
|
||||
@issue_group.command('list')
|
||||
@click.option('--state', type=click.Choice(['open', 'closed', 'all']), default='open', help='Issue state filter')
|
||||
@click.option('--assignee', help='Filter by assignee')
|
||||
@click.option('--label', multiple=True, help='Filter by labels')
|
||||
@click.option('--milestone', help='Filter by milestone')
|
||||
@click.option('--search', help='Search in title and description')
|
||||
@click.option('--limit', type=int, default=30, help='Maximum number of issues to show')
|
||||
@click.option('--format', 'output_format', type=click.Choice(['table', 'json', 'compact']), default='table', help='Output format')
|
||||
@click.pass_context
|
||||
def list_issues(ctx, state, assignee, label, milestone, search, limit, output_format):
|
||||
"""List issues with optional filtering."""
|
||||
backend = get_backend(ctx)
|
||||
|
||||
# Build filter criteria
|
||||
filter_criteria = IssueFilter(
|
||||
state=None if state == 'all' else state,
|
||||
assignee=assignee,
|
||||
labels=list(label) if label else None,
|
||||
milestone=milestone,
|
||||
search=search,
|
||||
limit=limit
|
||||
)
|
||||
|
||||
try:
|
||||
issues = backend.list_issues(filter_criteria)
|
||||
|
||||
if not issues:
|
||||
click.echo("No issues found.")
|
||||
return
|
||||
|
||||
if output_format == 'json':
|
||||
import json
|
||||
click.echo(json.dumps([issue.to_dict() for issue in issues], indent=2))
|
||||
elif output_format == 'compact':
|
||||
for issue in issues:
|
||||
labels_str = ', '.join(label.name for label in issue.labels[:3])
|
||||
if len(issue.labels) > 3:
|
||||
labels_str += f' (+{len(issue.labels) - 3} more)'
|
||||
|
||||
assignee_str = issue.primary_assignee.username if issue.primary_assignee else 'unassigned'
|
||||
|
||||
click.echo(f"#{issue.number:4d} {issue.state.value:10s} {issue.title[:50]:50s} {assignee_str:15s} {labels_str}")
|
||||
else: # table format
|
||||
click.echo(format_issue_list(issues))
|
||||
|
||||
except Exception as e:
|
||||
raise click.ClickException(f"Failed to list issues: {e}")
|
||||
|
||||
|
||||
@issue_group.command('show')
|
||||
@click.argument('issue_number', type=int)
|
||||
@click.option('--comments', is_flag=True, help='Show comments')
|
||||
@click.option('--format', 'output_format', type=click.Choice(['detailed', 'json', 'compact']), default='detailed', help='Output format')
|
||||
@click.pass_context
|
||||
def show_issue(ctx, issue_number, comments, output_format):
|
||||
"""Show detailed information about an issue."""
|
||||
backend = get_backend(ctx)
|
||||
|
||||
try:
|
||||
issue = backend.get_issue_by_number(issue_number)
|
||||
if not issue:
|
||||
raise click.ClickException(f"Issue #{issue_number} not found")
|
||||
|
||||
if output_format == 'json':
|
||||
import json
|
||||
issue_dict = issue.to_dict()
|
||||
if comments:
|
||||
issue_dict['comments'] = [
|
||||
{
|
||||
'id': c.id,
|
||||
'body': c.body,
|
||||
'author': c.author.username,
|
||||
'created_at': c.created_at.isoformat()
|
||||
}
|
||||
for c in backend.get_comments(issue.id)
|
||||
]
|
||||
click.echo(json.dumps(issue_dict, indent=2))
|
||||
else:
|
||||
click.echo(format_issue(issue, show_comments=comments, backend=backend if comments else None))
|
||||
|
||||
except Exception as e:
|
||||
raise click.ClickException(f"Failed to show issue: {e}")
|
||||
|
||||
|
||||
@issue_group.command('create')
|
||||
@click.argument('title')
|
||||
@click.option('--description', '-d', help='Issue description')
|
||||
@click.option('--label', '-l', multiple=True, help='Labels to add')
|
||||
@click.option('--assignee', '-a', help='Assign to user')
|
||||
@click.option('--milestone', '-m', help='Milestone')
|
||||
@click.option('--priority', type=click.Choice(['low', 'medium', 'high', 'critical']), help='Issue priority')
|
||||
@click.option('--type', 'issue_type', type=click.Choice(['bug', 'feature', 'enhancement', 'task', 'documentation', 'question']), help='Issue type')
|
||||
@click.option('--interactive', '-i', is_flag=True, help='Interactive mode')
|
||||
@click.pass_context
|
||||
def create_issue(ctx, title, description, label, assignee, milestone, priority, issue_type, interactive):
|
||||
"""Create a new issue."""
|
||||
backend = get_backend(ctx)
|
||||
|
||||
try:
|
||||
# Interactive mode
|
||||
if interactive:
|
||||
title = title or click.prompt('Title')
|
||||
description = get_user_input('Description (optional)', multiline=True)
|
||||
|
||||
# Show available labels
|
||||
available_labels = backend.get_labels()
|
||||
if available_labels:
|
||||
click.echo(f"\nAvailable labels: {', '.join(l.name for l in available_labels)}")
|
||||
label = click.prompt('Labels (comma-separated, optional)', default='').split(',') if click.prompt('Add labels?', type=bool, default=False) else []
|
||||
|
||||
# Show available users
|
||||
available_users = backend.get_users()
|
||||
if available_users:
|
||||
click.echo(f"\nAvailable users: {', '.join(u.username for u in available_users)}")
|
||||
assignee = click.prompt('Assignee (optional)', default='') or None
|
||||
|
||||
# Show available milestones
|
||||
available_milestones = backend.get_milestones()
|
||||
if available_milestones:
|
||||
click.echo(f"\nAvailable milestones: {', '.join(m.title for m in available_milestones)}")
|
||||
milestone = click.prompt('Milestone (optional)', default='') or None
|
||||
|
||||
# Build labels list
|
||||
labels = []
|
||||
|
||||
# Add explicit labels
|
||||
for label_name in label:
|
||||
label_name = label_name.strip()
|
||||
if label_name:
|
||||
labels.append(Label(name=label_name))
|
||||
|
||||
# Add priority label
|
||||
if priority:
|
||||
labels.append(Label(name=f'priority:{priority}'))
|
||||
|
||||
# Add type label
|
||||
if issue_type:
|
||||
labels.append(Label(name=issue_type))
|
||||
|
||||
# Build assignees list
|
||||
assignees = []
|
||||
if assignee:
|
||||
# Try to find user
|
||||
users = backend.search_users(assignee)
|
||||
if users:
|
||||
assignees.append(users[0])
|
||||
else:
|
||||
# Create a basic user object
|
||||
assignees.append(User(id=assignee, username=assignee))
|
||||
|
||||
# Find milestone
|
||||
milestone_obj = None
|
||||
if milestone:
|
||||
milestones = backend.get_milestones()
|
||||
for m in milestones:
|
||||
if m.title == milestone or m.id == milestone:
|
||||
milestone_obj = m
|
||||
break
|
||||
|
||||
# Create issue
|
||||
now = datetime.now(timezone.utc)
|
||||
issue = Issue(
|
||||
id="", # Will be set by backend
|
||||
number=0, # Will be set by backend
|
||||
title=title,
|
||||
description=description or "",
|
||||
state=IssueState.OPEN,
|
||||
created_at=now,
|
||||
updated_at=now,
|
||||
labels=labels,
|
||||
assignees=assignees,
|
||||
milestone=milestone_obj
|
||||
)
|
||||
|
||||
created_issue = backend.create_issue(issue)
|
||||
click.echo(f"Created issue #{created_issue.number}: {created_issue.title}")
|
||||
|
||||
if ctx.obj.get('verbose'):
|
||||
click.echo(format_issue(created_issue))
|
||||
|
||||
except Exception as e:
|
||||
raise click.ClickException(f"Failed to create issue: {e}")
|
||||
|
||||
|
||||
@issue_group.command('edit')
|
||||
@click.argument('issue_number', type=int)
|
||||
@click.option('--title', help='New title')
|
||||
@click.option('--description', help='New description')
|
||||
@click.option('--add-label', multiple=True, help='Labels to add')
|
||||
@click.option('--remove-label', multiple=True, help='Labels to remove')
|
||||
@click.option('--assign', help='User to assign')
|
||||
@click.option('--unassign', help='User to unassign')
|
||||
@click.option('--milestone', help='Milestone to set')
|
||||
@click.option('--interactive', '-i', is_flag=True, help='Interactive editing')
|
||||
@click.pass_context
|
||||
def edit_issue(ctx, issue_number, title, description, add_label, remove_label, assign, unassign, milestone, interactive):
|
||||
"""Edit an existing issue."""
|
||||
backend = get_backend(ctx)
|
||||
|
||||
try:
|
||||
issue = backend.get_issue_by_number(issue_number)
|
||||
if not issue:
|
||||
raise click.ClickException(f"Issue #{issue_number} not found")
|
||||
|
||||
# Interactive mode
|
||||
if interactive:
|
||||
click.echo(f"Editing issue #{issue.number}: {issue.title}")
|
||||
|
||||
new_title = click.prompt('Title', default=issue.title)
|
||||
if new_title != issue.title:
|
||||
title = new_title
|
||||
|
||||
new_description = get_user_input('Description', default=issue.description, multiline=True)
|
||||
if new_description != issue.description:
|
||||
description = new_description
|
||||
|
||||
# Apply changes
|
||||
modified = False
|
||||
|
||||
if title:
|
||||
issue.title = title
|
||||
modified = True
|
||||
|
||||
if description is not None:
|
||||
issue.description = description
|
||||
modified = True
|
||||
|
||||
# Add labels
|
||||
for label_name in add_label:
|
||||
issue.add_label(Label(name=label_name.strip()))
|
||||
modified = True
|
||||
|
||||
# Remove labels
|
||||
for label_name in remove_label:
|
||||
if issue.remove_label(label_name.strip()):
|
||||
modified = True
|
||||
|
||||
# Assign user
|
||||
if assign:
|
||||
users = backend.search_users(assign)
|
||||
if users:
|
||||
issue.add_assignee(users[0])
|
||||
modified = True
|
||||
else:
|
||||
issue.add_assignee(User(id=assign, username=assign))
|
||||
modified = True
|
||||
|
||||
# Unassign user
|
||||
if unassign:
|
||||
if issue.remove_assignee(unassign):
|
||||
modified = True
|
||||
|
||||
# Set milestone
|
||||
if milestone:
|
||||
milestones = backend.get_milestones()
|
||||
for m in milestones:
|
||||
if m.title == milestone or m.id == milestone:
|
||||
issue.milestone = m
|
||||
modified = True
|
||||
break
|
||||
|
||||
if modified:
|
||||
issue.updated_at = datetime.now(timezone.utc)
|
||||
updated_issue = backend.update_issue(issue)
|
||||
click.echo(f"Updated issue #{updated_issue.number}")
|
||||
|
||||
if ctx.obj.get('verbose'):
|
||||
click.echo(format_issue(updated_issue))
|
||||
else:
|
||||
click.echo("No changes made")
|
||||
|
||||
except Exception as e:
|
||||
raise click.ClickException(f"Failed to edit issue: {e}")
|
||||
|
||||
|
||||
@issue_group.command('close')
|
||||
@click.argument('issue_number', type=int)
|
||||
@click.option('--comment', '-c', help='Closing comment')
|
||||
@click.pass_context
|
||||
def close_issue(ctx, issue_number, comment):
|
||||
"""Close an issue."""
|
||||
backend = get_backend(ctx)
|
||||
|
||||
try:
|
||||
issue = backend.get_issue_by_number(issue_number)
|
||||
if not issue:
|
||||
raise click.ClickException(f"Issue #{issue_number} not found")
|
||||
|
||||
if issue.state == IssueState.CLOSED:
|
||||
click.echo(f"Issue #{issue_number} is already closed")
|
||||
return
|
||||
|
||||
# Close the issue
|
||||
issue.close()
|
||||
|
||||
# Add closing comment if provided
|
||||
if comment:
|
||||
from ..core.models import Comment
|
||||
current_user = User(id="cli-user", username="cli-user") # TODO: Get actual user
|
||||
closing_comment = Comment(
|
||||
id="",
|
||||
body=comment,
|
||||
author=current_user,
|
||||
created_at=datetime.now(timezone.utc)
|
||||
)
|
||||
backend.add_comment(issue.id, closing_comment)
|
||||
|
||||
updated_issue = backend.update_issue(issue)
|
||||
click.echo(f"Closed issue #{updated_issue.number}: {updated_issue.title}")
|
||||
|
||||
except Exception as e:
|
||||
raise click.ClickException(f"Failed to close issue: {e}")
|
||||
|
||||
|
||||
@issue_group.command('reopen')
|
||||
@click.argument('issue_number', type=int)
|
||||
@click.option('--comment', '-c', help='Reopening comment')
|
||||
@click.pass_context
|
||||
def reopen_issue(ctx, issue_number, comment):
|
||||
"""Reopen a closed issue."""
|
||||
backend = get_backend(ctx)
|
||||
|
||||
try:
|
||||
issue = backend.get_issue_by_number(issue_number)
|
||||
if not issue:
|
||||
raise click.ClickException(f"Issue #{issue_number} not found")
|
||||
|
||||
if issue.state != IssueState.CLOSED:
|
||||
click.echo(f"Issue #{issue_number} is not closed (current state: {issue.state.value})")
|
||||
return
|
||||
|
||||
# Reopen the issue
|
||||
issue.reopen()
|
||||
|
||||
# Add reopening comment if provided
|
||||
if comment:
|
||||
from ..core.models import Comment
|
||||
current_user = User(id="cli-user", username="cli-user") # TODO: Get actual user
|
||||
reopening_comment = Comment(
|
||||
id="",
|
||||
body=comment,
|
||||
author=current_user,
|
||||
created_at=datetime.now(timezone.utc)
|
||||
)
|
||||
backend.add_comment(issue.id, reopening_comment)
|
||||
|
||||
updated_issue = backend.update_issue(issue)
|
||||
click.echo(f"Reopened issue #{updated_issue.number}: {updated_issue.title}")
|
||||
|
||||
except Exception as e:
|
||||
raise click.ClickException(f"Failed to reopen issue: {e}")
|
||||
|
||||
|
||||
@issue_group.command('comment')
|
||||
@click.argument('issue_number', type=int)
|
||||
@click.argument('comment_text', required=False)
|
||||
@click.option('--editor', is_flag=True, help='Open editor for comment')
|
||||
@click.pass_context
|
||||
def add_comment(ctx, issue_number, comment_text, editor):
|
||||
"""Add a comment to an issue."""
|
||||
backend = get_backend(ctx)
|
||||
|
||||
try:
|
||||
issue = backend.get_issue_by_number(issue_number)
|
||||
if not issue:
|
||||
raise click.ClickException(f"Issue #{issue_number} not found")
|
||||
|
||||
# Get comment text
|
||||
if editor:
|
||||
comment_text = click.edit() or ""
|
||||
elif not comment_text:
|
||||
comment_text = get_user_input("Comment", multiline=True)
|
||||
|
||||
if not comment_text.strip():
|
||||
click.echo("Empty comment, aborting")
|
||||
return
|
||||
|
||||
# Create comment
|
||||
from ..core.models import Comment
|
||||
current_user = User(id="cli-user", username="cli-user") # TODO: Get actual user
|
||||
comment = Comment(
|
||||
id="",
|
||||
body=comment_text.strip(),
|
||||
author=current_user,
|
||||
created_at=datetime.now(timezone.utc)
|
||||
)
|
||||
|
||||
added_comment = backend.add_comment(issue.id, comment)
|
||||
click.echo(f"Added comment to issue #{issue_number}")
|
||||
|
||||
if ctx.obj.get('verbose'):
|
||||
click.echo(f"\nComment by {added_comment.author.username} at {added_comment.created_at}:")
|
||||
click.echo(added_comment.body)
|
||||
|
||||
except Exception as e:
|
||||
raise click.ClickException(f"Failed to add comment: {e}")
|
||||
@@ -1,117 +0,0 @@
|
||||
"""
|
||||
Main CLI Entry Point
|
||||
|
||||
Universal Issue Tracking System CLI
|
||||
"""
|
||||
|
||||
import click
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
from .commands import issue_group
|
||||
from .backend_commands import backend_group
|
||||
from .sync_commands import sync_group
|
||||
|
||||
|
||||
@click.group()
|
||||
@click.version_option()
|
||||
@click.option('--config', type=click.Path(), help='Configuration file path')
|
||||
@click.option('--backend', help='Backend to use (local, gitea)')
|
||||
@click.option('--verbose', '-v', is_flag=True, help='Verbose output')
|
||||
@click.pass_context
|
||||
def cli(ctx, config, backend, verbose):
|
||||
"""
|
||||
Universal Issue Tracking System
|
||||
|
||||
A backend-agnostic issue tracking tool that works with local SQLite,
|
||||
Gitea, GitHub, and other issue tracking systems.
|
||||
|
||||
Examples:
|
||||
issue list # List all issues
|
||||
issue create "Bug in parser" # Create new issue
|
||||
issue show 42 # Show issue #42
|
||||
issue close 42 # Close issue #42
|
||||
|
||||
backend add local ~/.issues # Add local backend
|
||||
backend add gitea myrepo # Add Gitea backend
|
||||
|
||||
sync pull gitea # Sync from Gitea
|
||||
sync push gitea # Sync to Gitea
|
||||
"""
|
||||
# Ensure the object exists
|
||||
ctx.ensure_object(dict)
|
||||
|
||||
# Store global options in context
|
||||
ctx.obj['config_path'] = config
|
||||
ctx.obj['backend'] = backend
|
||||
ctx.obj['verbose'] = verbose
|
||||
|
||||
|
||||
# Register command groups
|
||||
cli.add_command(issue_group, name='issue')
|
||||
cli.add_command(backend_group, name='backend')
|
||||
cli.add_command(sync_group, name='sync')
|
||||
|
||||
|
||||
# Convenience aliases - direct issue commands
|
||||
@cli.command('list')
|
||||
@click.pass_context
|
||||
def list_issues(ctx):
|
||||
"""List all issues (alias for 'issue list')."""
|
||||
ctx.invoke(issue_group.get_command(ctx, 'list'))
|
||||
|
||||
|
||||
@cli.command('show')
|
||||
@click.argument('issue_number', type=int)
|
||||
@click.pass_context
|
||||
def show_issue(ctx, issue_number):
|
||||
"""Show issue details (alias for 'issue show')."""
|
||||
ctx.invoke(issue_group.get_command(ctx, 'show'), issue_number=issue_number)
|
||||
|
||||
|
||||
@cli.command('create')
|
||||
@click.argument('title')
|
||||
@click.option('--description', '-d', help='Issue description')
|
||||
@click.option('--label', '-l', multiple=True, help='Labels to add')
|
||||
@click.option('--assignee', '-a', help='Assign to user')
|
||||
@click.option('--milestone', '-m', help='Milestone')
|
||||
@click.pass_context
|
||||
def create_issue(ctx, title, description, label, assignee, milestone):
|
||||
"""Create new issue (alias for 'issue create')."""
|
||||
ctx.invoke(
|
||||
issue_group.get_command(ctx, 'create'),
|
||||
title=title,
|
||||
description=description,
|
||||
label=label,
|
||||
assignee=assignee,
|
||||
milestone=milestone
|
||||
)
|
||||
|
||||
|
||||
@cli.command('close')
|
||||
@click.argument('issue_number', type=int)
|
||||
@click.option('--comment', '-c', help='Closing comment')
|
||||
@click.pass_context
|
||||
def close_issue(ctx, issue_number, comment):
|
||||
"""Close issue (alias for 'issue close')."""
|
||||
ctx.invoke(
|
||||
issue_group.get_command(ctx, 'close'),
|
||||
issue_number=issue_number,
|
||||
comment=comment
|
||||
)
|
||||
|
||||
|
||||
def main():
|
||||
"""Main entry point for the CLI."""
|
||||
try:
|
||||
cli(obj={})
|
||||
except KeyboardInterrupt:
|
||||
click.echo("\nAborted by user", err=True)
|
||||
sys.exit(1)
|
||||
except Exception as e:
|
||||
click.echo(f"Error: {e}", err=True)
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
@@ -1,235 +0,0 @@
|
||||
"""
|
||||
Synchronization CLI Commands
|
||||
|
||||
Commands for synchronizing issues between different backends.
|
||||
"""
|
||||
|
||||
import click
|
||||
from datetime import datetime, timezone
|
||||
from .utils import (
|
||||
load_backend_configs, get_backend, echo_success, echo_error,
|
||||
echo_warning, echo_info, progress_bar, confirm_action
|
||||
)
|
||||
from ..core.interfaces import BackendFactory
|
||||
|
||||
|
||||
@click.group()
|
||||
def sync_group():
|
||||
"""Issue synchronization between backends."""
|
||||
pass
|
||||
|
||||
|
||||
@sync_group.command('status')
|
||||
@click.argument('backend_name', required=False)
|
||||
@click.pass_context
|
||||
def sync_status(ctx, backend_name):
|
||||
"""Show sync status for backends."""
|
||||
configs = load_backend_configs()
|
||||
|
||||
if backend_name:
|
||||
backends_to_check = [backend_name] if backend_name in configs else []
|
||||
if not backends_to_check:
|
||||
echo_error(f"Backend '{backend_name}' not found")
|
||||
return
|
||||
else:
|
||||
backends_to_check = [k for k in configs.keys() if k != 'default']
|
||||
|
||||
for name in backends_to_check:
|
||||
config = configs[name]
|
||||
try:
|
||||
backend = BackendFactory.create_backend(config['type'])
|
||||
backend.connect(config)
|
||||
|
||||
# Get basic stats
|
||||
all_issues = backend.list_issues()
|
||||
open_issues = [i for i in all_issues if i.state.value != 'closed']
|
||||
|
||||
click.echo(f"\n{name} ({config['type']}):")
|
||||
click.echo(f" Total issues: {len(all_issues)}")
|
||||
click.echo(f" Open issues: {len(open_issues)}")
|
||||
click.echo(f" Closed issues: {len(all_issues) - len(open_issues)}")
|
||||
|
||||
# Check last sync
|
||||
if hasattr(backend, 'get_last_sync_timestamp'):
|
||||
last_sync = backend.get_last_sync_timestamp()
|
||||
if last_sync:
|
||||
click.echo(f" Last sync: {last_sync}")
|
||||
else:
|
||||
click.echo(f" Last sync: never")
|
||||
|
||||
backend.disconnect()
|
||||
|
||||
except Exception as e:
|
||||
echo_error(f" Error accessing {name}: {e}")
|
||||
|
||||
|
||||
@sync_group.command('pull')
|
||||
@click.argument('source_backend')
|
||||
@click.option('--target', default='local', help='Target backend (default: local)')
|
||||
@click.option('--dry-run', is_flag=True, help='Show what would be synced without making changes')
|
||||
@click.option('--force', is_flag=True, help='Force sync even with conflicts')
|
||||
@click.pass_context
|
||||
def sync_pull(ctx, source_backend, target, dry_run, force):
|
||||
"""Pull issues from source backend to target backend."""
|
||||
configs = load_backend_configs()
|
||||
|
||||
if source_backend not in configs:
|
||||
echo_error(f"Source backend '{source_backend}' not found")
|
||||
return
|
||||
|
||||
if target not in configs:
|
||||
echo_error(f"Target backend '{target}' not found")
|
||||
return
|
||||
|
||||
if source_backend == target:
|
||||
echo_error("Source and target backends cannot be the same")
|
||||
return
|
||||
|
||||
try:
|
||||
# Connect to backends
|
||||
source_config = configs[source_backend]
|
||||
target_config = configs[target]
|
||||
|
||||
source = BackendFactory.create_backend(source_config['type'])
|
||||
source.connect(source_config)
|
||||
|
||||
target = BackendFactory.create_backend(target_config['type'])
|
||||
target.connect(target_config)
|
||||
|
||||
echo_info(f"Syncing from {source_backend} to {target}")
|
||||
|
||||
# Get issues from source
|
||||
source_issues = source.list_issues()
|
||||
echo_info(f"Found {len(source_issues)} issues in source")
|
||||
|
||||
# Get existing issues in target
|
||||
target_issues = target.list_issues()
|
||||
target_numbers = {issue.number for issue in target_issues}
|
||||
|
||||
# Determine what needs to be synced
|
||||
new_issues = []
|
||||
updated_issues = []
|
||||
|
||||
for issue in source_issues:
|
||||
if issue.number not in target_numbers:
|
||||
new_issues.append(issue)
|
||||
else:
|
||||
# Check if update is needed (simplified check by updated_at)
|
||||
target_issue = next((i for i in target_issues if i.number == issue.number), None)
|
||||
if target_issue and issue.updated_at > target_issue.updated_at:
|
||||
updated_issues.append(issue)
|
||||
|
||||
echo_info(f"New issues to sync: {len(new_issues)}")
|
||||
echo_info(f"Updated issues to sync: {len(updated_issues)}")
|
||||
|
||||
if dry_run:
|
||||
if new_issues:
|
||||
click.echo("\nNew issues:")
|
||||
for issue in new_issues:
|
||||
click.echo(f" #{issue.number}: {issue.title}")
|
||||
|
||||
if updated_issues:
|
||||
click.echo("\nUpdated issues:")
|
||||
for issue in updated_issues:
|
||||
click.echo(f" #{issue.number}: {issue.title}")
|
||||
|
||||
click.echo(f"\nDry run complete. {len(new_issues + updated_issues)} issues would be synced.")
|
||||
return
|
||||
|
||||
# Confirm sync
|
||||
total_sync = len(new_issues) + len(updated_issues)
|
||||
if total_sync == 0:
|
||||
echo_success("No issues need syncing")
|
||||
return
|
||||
|
||||
if not force and not confirm_action(f"Sync {total_sync} issues?"):
|
||||
click.echo("Aborted")
|
||||
return
|
||||
|
||||
# Perform sync
|
||||
synced_count = 0
|
||||
errors = []
|
||||
|
||||
all_to_sync = new_issues + updated_issues
|
||||
with progress_bar(all_to_sync, label="Syncing issues") as items:
|
||||
for issue in items:
|
||||
try:
|
||||
# Clear backend-specific IDs for new backend
|
||||
issue.backend_id = None
|
||||
issue.backend_type = target_config['type']
|
||||
|
||||
if issue in new_issues:
|
||||
target.create_issue(issue)
|
||||
else:
|
||||
# For updates, we need to find the target issue and update it
|
||||
target_issue = target.get_issue_by_number(issue.number)
|
||||
if target_issue:
|
||||
# Copy relevant fields
|
||||
target_issue.title = issue.title
|
||||
target_issue.description = issue.description
|
||||
target_issue.state = issue.state
|
||||
target_issue.labels = issue.labels
|
||||
target_issue.assignees = issue.assignees
|
||||
target_issue.milestone = issue.milestone
|
||||
target_issue.updated_at = issue.updated_at
|
||||
target_issue.closed_at = issue.closed_at
|
||||
target.update_issue(target_issue)
|
||||
|
||||
synced_count += 1
|
||||
|
||||
except Exception as e:
|
||||
errors.append(f"Issue #{issue.number}: {e}")
|
||||
|
||||
# Report results
|
||||
echo_success(f"Synced {synced_count} issues successfully")
|
||||
|
||||
if errors:
|
||||
echo_warning(f"{len(errors)} errors occurred:")
|
||||
for error in errors[:5]: # Show first 5 errors
|
||||
echo_error(f" {error}")
|
||||
if len(errors) > 5:
|
||||
echo_warning(f" ... and {len(errors) - 5} more errors")
|
||||
|
||||
# Cleanup
|
||||
source.disconnect()
|
||||
target.disconnect()
|
||||
|
||||
except Exception as e:
|
||||
echo_error(f"Sync failed: {e}")
|
||||
|
||||
|
||||
@sync_group.command('push')
|
||||
@click.argument('target_backend')
|
||||
@click.option('--source', default='local', help='Source backend (default: local)')
|
||||
@click.option('--dry-run', is_flag=True, help='Show what would be synced without making changes')
|
||||
@click.option('--force', is_flag=True, help='Force sync even with conflicts')
|
||||
@click.pass_context
|
||||
def sync_push(ctx, target_backend, source, dry_run, force):
|
||||
"""Push issues from source backend to target backend."""
|
||||
# This is essentially the same as pull but with arguments swapped
|
||||
ctx.invoke(sync_pull, source_backend=source, target=target_backend, dry_run=dry_run, force=force)
|
||||
|
||||
|
||||
@sync_group.command('bidirectional')
|
||||
@click.argument('backend1')
|
||||
@click.argument('backend2')
|
||||
@click.option('--dry-run', is_flag=True, help='Show what would be synced without making changes')
|
||||
@click.option('--force', is_flag=True, help='Force sync even with conflicts')
|
||||
@click.pass_context
|
||||
def sync_bidirectional(ctx, backend1, backend2, dry_run, force):
|
||||
"""Bidirectional sync between two backends."""
|
||||
echo_warning("Bidirectional sync is a complex operation that can cause conflicts.")
|
||||
|
||||
if not force and not confirm_action("Continue with bidirectional sync?"):
|
||||
click.echo("Aborted")
|
||||
return
|
||||
|
||||
# First sync backend1 -> backend2
|
||||
echo_info(f"Step 1: Syncing {backend1} -> {backend2}")
|
||||
ctx.invoke(sync_pull, source_backend=backend1, target=backend2, dry_run=dry_run, force=True)
|
||||
|
||||
# Then sync backend2 -> backend1
|
||||
echo_info(f"Step 2: Syncing {backend2} -> {backend1}")
|
||||
ctx.invoke(sync_pull, source_backend=backend2, target=backend1, dry_run=dry_run, force=True)
|
||||
|
||||
echo_success("Bidirectional sync completed")
|
||||
@@ -1,336 +0,0 @@
|
||||
"""
|
||||
CLI Utility Functions
|
||||
|
||||
Helper functions for the CLI commands including formatting, configuration,
|
||||
backend management, and user interaction.
|
||||
"""
|
||||
|
||||
import click
|
||||
import os
|
||||
import sys
|
||||
from datetime import datetime
|
||||
from pathlib import Path
|
||||
from typing import Optional, List
|
||||
import tempfile
|
||||
|
||||
from ..core.interfaces import IssueBackend, BackendFactory
|
||||
from ..core.models import Issue, Comment
|
||||
from ..backends.local import LocalSQLiteBackend
|
||||
from ..backends.gitea import GiteaBackend
|
||||
|
||||
|
||||
# Register available backends
|
||||
BackendFactory.register_backend('local', LocalSQLiteBackend)
|
||||
BackendFactory.register_backend('gitea', GiteaBackend)
|
||||
|
||||
|
||||
def get_config_dir() -> Path:
|
||||
"""Get configuration directory."""
|
||||
config_dir = Path.home() / '.config' / 'issue-tracker'
|
||||
config_dir.mkdir(parents=True, exist_ok=True)
|
||||
return config_dir
|
||||
|
||||
|
||||
def get_backend_config_path() -> Path:
|
||||
"""Get backend configuration file path."""
|
||||
return get_config_dir() / 'backends.json'
|
||||
|
||||
|
||||
def load_backend_configs() -> dict:
|
||||
"""Load backend configurations."""
|
||||
config_path = get_backend_config_path()
|
||||
if not config_path.exists():
|
||||
return {}
|
||||
|
||||
import json
|
||||
try:
|
||||
with open(config_path, 'r') as f:
|
||||
return json.load(f)
|
||||
except (json.JSONDecodeError, IOError):
|
||||
return {}
|
||||
|
||||
|
||||
def save_backend_configs(configs: dict) -> None:
|
||||
"""Save backend configurations."""
|
||||
config_path = get_backend_config_path()
|
||||
import json
|
||||
with open(config_path, 'w') as f:
|
||||
json.dump(configs, f, indent=2)
|
||||
|
||||
|
||||
def get_default_backend() -> str:
|
||||
"""Get the default backend name."""
|
||||
configs = load_backend_configs()
|
||||
return configs.get('default', 'local')
|
||||
|
||||
|
||||
def get_backend(ctx) -> IssueBackend:
|
||||
"""Get backend instance from context."""
|
||||
backend_name = ctx.obj.get('backend') or get_default_backend()
|
||||
configs = load_backend_configs()
|
||||
|
||||
if backend_name not in configs:
|
||||
if backend_name == 'local':
|
||||
# Auto-configure local backend
|
||||
local_config = {
|
||||
'type': 'local',
|
||||
'db_path': str(get_config_dir() / 'issues.db')
|
||||
}
|
||||
configs['local'] = local_config
|
||||
save_backend_configs(configs)
|
||||
else:
|
||||
raise click.ClickException(f"Backend '{backend_name}' not configured. Use 'backend add' to configure it.")
|
||||
|
||||
backend_config = configs[backend_name]
|
||||
backend_type = backend_config['type']
|
||||
|
||||
try:
|
||||
backend = BackendFactory.create_backend(backend_type)
|
||||
backend.connect(backend_config)
|
||||
return backend
|
||||
except Exception as e:
|
||||
raise click.ClickException(f"Failed to connect to backend '{backend_name}': {e}")
|
||||
|
||||
|
||||
def format_issue_list(issues: List[Issue]) -> str:
|
||||
"""Format list of issues as a table."""
|
||||
if not issues:
|
||||
return "No issues found."
|
||||
|
||||
# Calculate column widths
|
||||
max_title_width = min(50, max(len(issue.title) for issue in issues))
|
||||
max_assignee_width = 15
|
||||
|
||||
# Header
|
||||
lines = []
|
||||
header = f"{'#':<6} {'State':<12} {'Title':<{max_title_width}} {'Assignee':<{max_assignee_width}} Labels"
|
||||
lines.append(header)
|
||||
lines.append("-" * len(header))
|
||||
|
||||
# Issues
|
||||
for issue in issues:
|
||||
title = issue.title[:max_title_width]
|
||||
if len(issue.title) > max_title_width:
|
||||
title = title[:-3] + "..."
|
||||
|
||||
assignee = issue.primary_assignee.username if issue.primary_assignee else "unassigned"
|
||||
assignee = assignee[:max_assignee_width]
|
||||
|
||||
labels = ", ".join(label.name for label in issue.labels[:3])
|
||||
if len(issue.labels) > 3:
|
||||
labels += f" (+{len(issue.labels) - 3})"
|
||||
|
||||
line = f"{issue.number:<6} {issue.state.value:<12} {title:<{max_title_width}} {assignee:<{max_assignee_width}} {labels}"
|
||||
lines.append(line)
|
||||
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def format_issue(issue: Issue, show_comments: bool = False, backend: Optional[IssueBackend] = None) -> str:
|
||||
"""Format a single issue with details."""
|
||||
lines = []
|
||||
|
||||
# Header
|
||||
lines.append(f"#{issue.number}: {issue.title}")
|
||||
lines.append("=" * (len(f"#{issue.number}: {issue.title}")))
|
||||
lines.append("")
|
||||
|
||||
# Basic info
|
||||
lines.append(f"State: {issue.state.value}")
|
||||
lines.append(f"Created: {format_datetime(issue.created_at)}")
|
||||
lines.append(f"Updated: {format_datetime(issue.updated_at)}")
|
||||
|
||||
if issue.closed_at:
|
||||
lines.append(f"Closed: {format_datetime(issue.closed_at)}")
|
||||
|
||||
# Assignees
|
||||
if issue.assignees:
|
||||
assignees_str = ", ".join(assignee.username for assignee in issue.assignees)
|
||||
lines.append(f"Assignees: {assignees_str}")
|
||||
else:
|
||||
lines.append("Assignees: none")
|
||||
|
||||
# Milestone
|
||||
if issue.milestone:
|
||||
lines.append(f"Milestone: {issue.milestone.title}")
|
||||
|
||||
# Labels
|
||||
if issue.labels:
|
||||
labels_by_category = {}
|
||||
for label in issue.labels:
|
||||
category = label.category
|
||||
if category not in labels_by_category:
|
||||
labels_by_category[category] = []
|
||||
labels_by_category[category].append(label.name)
|
||||
|
||||
for category, label_names in labels_by_category.items():
|
||||
lines.append(f"{category.title()} labels: {', '.join(label_names)}")
|
||||
else:
|
||||
lines.append("Labels: none")
|
||||
|
||||
# Description
|
||||
lines.append("")
|
||||
lines.append("Description:")
|
||||
lines.append("-" * 12)
|
||||
if issue.description:
|
||||
lines.append(issue.description)
|
||||
else:
|
||||
lines.append("(no description)")
|
||||
|
||||
# Comments
|
||||
if show_comments and backend:
|
||||
comments = backend.get_comments(issue.id)
|
||||
if comments:
|
||||
lines.append("")
|
||||
lines.append(f"Comments ({len(comments)}):")
|
||||
lines.append("-" * 20)
|
||||
|
||||
for comment in comments:
|
||||
lines.append("")
|
||||
lines.append(f"Comment by {comment.author.username} at {format_datetime(comment.created_at)}:")
|
||||
lines.append(comment.body)
|
||||
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def format_datetime(dt: datetime) -> str:
|
||||
"""Format datetime for display."""
|
||||
if dt.tzinfo:
|
||||
dt = dt.astimezone()
|
||||
return dt.strftime("%Y-%m-%d %H:%M:%S")
|
||||
|
||||
|
||||
def get_user_input(prompt: str, default: str = "", multiline: bool = False) -> str:
|
||||
"""Get user input with optional default and multiline support."""
|
||||
if multiline:
|
||||
click.echo(f"{prompt} (Press Ctrl+D when done, Ctrl+C to cancel):")
|
||||
if default:
|
||||
click.echo(f"Current value:\n{default}\n")
|
||||
|
||||
lines = []
|
||||
try:
|
||||
while True:
|
||||
try:
|
||||
line = input()
|
||||
lines.append(line)
|
||||
except EOFError:
|
||||
break
|
||||
except KeyboardInterrupt:
|
||||
raise click.Abort()
|
||||
|
||||
return "\n".join(lines) if lines else default
|
||||
else:
|
||||
return click.prompt(prompt, default=default)
|
||||
|
||||
|
||||
def validate_backend_type(backend_type: str) -> bool:
|
||||
"""Validate that a backend type is supported."""
|
||||
return backend_type in BackendFactory.get_available_backends()
|
||||
|
||||
|
||||
def test_backend_connection(backend_config: dict) -> bool:
|
||||
"""Test if a backend configuration works."""
|
||||
try:
|
||||
backend_type = backend_config['type']
|
||||
backend = BackendFactory.create_backend(backend_type)
|
||||
backend.connect(backend_config)
|
||||
result = backend.test_connection()
|
||||
backend.disconnect()
|
||||
return result
|
||||
except Exception:
|
||||
return False
|
||||
|
||||
|
||||
def format_backend_list(configs: dict) -> str:
|
||||
"""Format backend configurations for display."""
|
||||
if not configs:
|
||||
return "No backends configured."
|
||||
|
||||
lines = []
|
||||
default_backend = configs.get('default', 'local')
|
||||
|
||||
lines.append(f"{'Name':<15} {'Type':<10} {'Status':<10} Description")
|
||||
lines.append("-" * 60)
|
||||
|
||||
for name, config in configs.items():
|
||||
if name == 'default':
|
||||
continue
|
||||
|
||||
backend_type = config.get('type', 'unknown')
|
||||
is_default = name == default_backend
|
||||
|
||||
# Test connection
|
||||
try:
|
||||
status = "connected" if test_backend_connection(config) else "error"
|
||||
except Exception:
|
||||
status = "error"
|
||||
|
||||
# Description
|
||||
if backend_type == 'local':
|
||||
desc = f"Local SQLite: {config.get('db_path', 'unknown')}"
|
||||
elif backend_type == 'gitea':
|
||||
desc = f"Gitea: {config.get('base_url', 'unknown')}/{config.get('owner', 'unknown')}/{config.get('repo', 'unknown')}"
|
||||
else:
|
||||
desc = f"{backend_type} backend"
|
||||
|
||||
if is_default:
|
||||
desc += " (default)"
|
||||
|
||||
line = f"{name:<15} {backend_type:<10} {status:<10} {desc}"
|
||||
lines.append(line)
|
||||
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def get_editor() -> str:
|
||||
"""Get the user's preferred editor."""
|
||||
return os.environ.get('EDITOR', 'nano')
|
||||
|
||||
|
||||
def edit_text(initial_text: str = "") -> Optional[str]:
|
||||
"""Open text in editor and return edited content."""
|
||||
with tempfile.NamedTemporaryFile(mode='w+', suffix='.md', delete=False) as f:
|
||||
f.write(initial_text)
|
||||
temp_path = f.name
|
||||
|
||||
try:
|
||||
editor = get_editor()
|
||||
os.system(f'{editor} {temp_path}')
|
||||
|
||||
with open(temp_path, 'r') as f:
|
||||
edited_text = f.read()
|
||||
|
||||
return edited_text if edited_text != initial_text else None
|
||||
|
||||
finally:
|
||||
os.unlink(temp_path)
|
||||
|
||||
|
||||
def confirm_action(message: str, default: bool = False) -> bool:
|
||||
"""Ask user for confirmation."""
|
||||
return click.confirm(message, default=default)
|
||||
|
||||
|
||||
def progress_bar(items, label: str = "Processing"):
|
||||
"""Create a progress bar for iterating over items."""
|
||||
return click.progressbar(items, label=label)
|
||||
|
||||
|
||||
def echo_success(message: str) -> None:
|
||||
"""Echo success message in green."""
|
||||
click.echo(click.style(message, fg='green'))
|
||||
|
||||
|
||||
def echo_warning(message: str) -> None:
|
||||
"""Echo warning message in yellow."""
|
||||
click.echo(click.style(message, fg='yellow'))
|
||||
|
||||
|
||||
def echo_error(message: str) -> None:
|
||||
"""Echo error message in red."""
|
||||
click.echo(click.style(message, fg='red'))
|
||||
|
||||
|
||||
def echo_info(message: str) -> None:
|
||||
"""Echo info message in blue."""
|
||||
click.echo(click.style(message, fg='blue'))
|
||||
@@ -1,407 +0,0 @@
|
||||
"""
|
||||
Backend Plugin Interfaces
|
||||
|
||||
Defines the contracts that all issue tracking backend plugins must implement.
|
||||
This enables a clean plugin architecture where new backends can be added
|
||||
without modifying core code.
|
||||
"""
|
||||
|
||||
from abc import ABC, abstractmethod
|
||||
from typing import List, Optional, Dict, Any, Iterator
|
||||
from datetime import datetime
|
||||
|
||||
from .models import Issue, Label, User, Milestone, Comment
|
||||
|
||||
|
||||
class IssueFilter:
|
||||
"""Filter criteria for issue queries."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
state: Optional[str] = None,
|
||||
assignee: Optional[str] = None,
|
||||
labels: Optional[List[str]] = None,
|
||||
milestone: Optional[str] = None,
|
||||
created_after: Optional[datetime] = None,
|
||||
created_before: Optional[datetime] = None,
|
||||
updated_after: Optional[datetime] = None,
|
||||
updated_before: Optional[datetime] = None,
|
||||
search: Optional[str] = None,
|
||||
limit: Optional[int] = None,
|
||||
offset: Optional[int] = 0
|
||||
):
|
||||
self.state = state
|
||||
self.assignee = assignee
|
||||
self.labels = labels or []
|
||||
self.milestone = milestone
|
||||
self.created_after = created_after
|
||||
self.created_before = created_before
|
||||
self.updated_after = updated_after
|
||||
self.updated_before = updated_before
|
||||
self.search = search
|
||||
self.limit = limit
|
||||
self.offset = offset
|
||||
|
||||
|
||||
class BackendCapabilities:
|
||||
"""Describes what features a backend supports."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
supports_milestones: bool = True,
|
||||
supports_assignees: bool = True,
|
||||
supports_comments: bool = True,
|
||||
supports_labels: bool = True,
|
||||
supports_search: bool = True,
|
||||
supports_bulk_operations: bool = False,
|
||||
supports_webhooks: bool = False,
|
||||
supports_real_time: bool = False,
|
||||
max_labels_per_issue: Optional[int] = None,
|
||||
max_assignees_per_issue: Optional[int] = None
|
||||
):
|
||||
self.supports_milestones = supports_milestones
|
||||
self.supports_assignees = supports_assignees
|
||||
self.supports_comments = supports_comments
|
||||
self.supports_labels = supports_labels
|
||||
self.supports_search = supports_search
|
||||
self.supports_bulk_operations = supports_bulk_operations
|
||||
self.supports_webhooks = supports_webhooks
|
||||
self.supports_real_time = supports_real_time
|
||||
self.max_labels_per_issue = max_labels_per_issue
|
||||
self.max_assignees_per_issue = max_assignees_per_issue
|
||||
|
||||
|
||||
class IssueBackend(ABC):
|
||||
"""
|
||||
Abstract base class for all issue tracking backends.
|
||||
|
||||
Each backend plugin must implement this interface to provide
|
||||
issue tracking functionality for a specific system.
|
||||
"""
|
||||
|
||||
@property
|
||||
@abstractmethod
|
||||
def backend_type(self) -> str:
|
||||
"""Return the backend type identifier (e.g., 'local', 'gitea', 'github')."""
|
||||
pass
|
||||
|
||||
@property
|
||||
@abstractmethod
|
||||
def capabilities(self) -> BackendCapabilities:
|
||||
"""Return the capabilities supported by this backend."""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def connect(self, config: Dict[str, Any]) -> None:
|
||||
"""
|
||||
Connect to the backend using provided configuration.
|
||||
|
||||
Args:
|
||||
config: Backend-specific configuration (URLs, tokens, etc.)
|
||||
"""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def disconnect(self) -> None:
|
||||
"""Disconnect from the backend and clean up resources."""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def test_connection(self) -> bool:
|
||||
"""Test if the backend connection is working."""
|
||||
pass
|
||||
|
||||
# Issue CRUD Operations
|
||||
@abstractmethod
|
||||
def create_issue(self, issue: Issue) -> Issue:
|
||||
"""
|
||||
Create a new issue in the backend.
|
||||
|
||||
Args:
|
||||
issue: Issue to create (id may be None for new issues)
|
||||
|
||||
Returns:
|
||||
Created issue with backend_id populated
|
||||
"""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def get_issue(self, issue_id: str) -> Optional[Issue]:
|
||||
"""
|
||||
Retrieve an issue by its backend ID.
|
||||
|
||||
Args:
|
||||
issue_id: Backend-specific issue ID
|
||||
|
||||
Returns:
|
||||
Issue if found, None otherwise
|
||||
"""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def get_issue_by_number(self, number: int) -> Optional[Issue]:
|
||||
"""
|
||||
Retrieve an issue by its human-readable number.
|
||||
|
||||
Args:
|
||||
number: Issue number
|
||||
|
||||
Returns:
|
||||
Issue if found, None otherwise
|
||||
"""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def update_issue(self, issue: Issue) -> Issue:
|
||||
"""
|
||||
Update an existing issue in the backend.
|
||||
|
||||
Args:
|
||||
issue: Issue with modifications
|
||||
|
||||
Returns:
|
||||
Updated issue
|
||||
"""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def delete_issue(self, issue_id: str) -> bool:
|
||||
"""
|
||||
Delete an issue from the backend.
|
||||
|
||||
Args:
|
||||
issue_id: Backend-specific issue ID
|
||||
|
||||
Returns:
|
||||
True if deleted successfully
|
||||
"""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def list_issues(self, filter_criteria: Optional[IssueFilter] = None) -> List[Issue]:
|
||||
"""
|
||||
List issues matching filter criteria.
|
||||
|
||||
Args:
|
||||
filter_criteria: Optional filter to apply
|
||||
|
||||
Returns:
|
||||
List of matching issues
|
||||
"""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def search_issues(self, query: str, limit: Optional[int] = None) -> List[Issue]:
|
||||
"""
|
||||
Search issues using backend-specific query syntax.
|
||||
|
||||
Args:
|
||||
query: Search query
|
||||
limit: Maximum number of results
|
||||
|
||||
Returns:
|
||||
List of matching issues
|
||||
"""
|
||||
pass
|
||||
|
||||
# Label Operations
|
||||
@abstractmethod
|
||||
def create_label(self, label: Label) -> Label:
|
||||
"""Create a new label."""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def get_labels(self) -> List[Label]:
|
||||
"""Get all available labels."""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def update_label(self, label: Label) -> Label:
|
||||
"""Update an existing label."""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def delete_label(self, label_name: str) -> bool:
|
||||
"""Delete a label."""
|
||||
pass
|
||||
|
||||
# User Operations
|
||||
@abstractmethod
|
||||
def get_users(self) -> List[User]:
|
||||
"""Get all available users."""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def get_user(self, user_id: str) -> Optional[User]:
|
||||
"""Get a specific user by ID."""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def search_users(self, query: str) -> List[User]:
|
||||
"""Search for users."""
|
||||
pass
|
||||
|
||||
# Milestone Operations
|
||||
@abstractmethod
|
||||
def create_milestone(self, milestone: Milestone) -> Milestone:
|
||||
"""Create a new milestone."""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def get_milestones(self) -> List[Milestone]:
|
||||
"""Get all milestones."""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def update_milestone(self, milestone: Milestone) -> Milestone:
|
||||
"""Update a milestone."""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def delete_milestone(self, milestone_id: str) -> bool:
|
||||
"""Delete a milestone."""
|
||||
pass
|
||||
|
||||
# Comment Operations
|
||||
@abstractmethod
|
||||
def add_comment(self, issue_id: str, comment: Comment) -> Comment:
|
||||
"""Add a comment to an issue."""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def get_comments(self, issue_id: str) -> List[Comment]:
|
||||
"""Get all comments for an issue."""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def update_comment(self, comment: Comment) -> Comment:
|
||||
"""Update a comment."""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def delete_comment(self, comment_id: str) -> bool:
|
||||
"""Delete a comment."""
|
||||
pass
|
||||
|
||||
# Bulk Operations (optional, depends on capabilities)
|
||||
def bulk_update_issues(self, updates: List[Dict[str, Any]]) -> List[Issue]:
|
||||
"""
|
||||
Bulk update multiple issues.
|
||||
|
||||
Args:
|
||||
updates: List of update operations
|
||||
|
||||
Returns:
|
||||
List of updated issues
|
||||
"""
|
||||
if not self.capabilities.supports_bulk_operations:
|
||||
raise NotImplementedError(f"{self.backend_type} backend does not support bulk operations")
|
||||
|
||||
# Default implementation: update one by one
|
||||
results = []
|
||||
for update in updates:
|
||||
issue_id = update['id']
|
||||
issue = self.get_issue(issue_id)
|
||||
if issue:
|
||||
# Apply updates to issue
|
||||
for key, value in update.items():
|
||||
if key != 'id' and hasattr(issue, key):
|
||||
setattr(issue, key, value)
|
||||
updated_issue = self.update_issue(issue)
|
||||
results.append(updated_issue)
|
||||
return results
|
||||
|
||||
# Sync Support
|
||||
def get_last_sync_timestamp(self) -> Optional[datetime]:
|
||||
"""
|
||||
Get the timestamp of the last successful sync.
|
||||
Used for incremental synchronization.
|
||||
"""
|
||||
return None
|
||||
|
||||
def get_issues_modified_since(self, timestamp: datetime) -> List[Issue]:
|
||||
"""
|
||||
Get issues modified since a specific timestamp.
|
||||
Used for incremental synchronization.
|
||||
"""
|
||||
filter_criteria = IssueFilter(updated_after=timestamp)
|
||||
return self.list_issues(filter_criteria)
|
||||
|
||||
|
||||
class LocalBackend(IssueBackend):
|
||||
"""
|
||||
Marker interface for local backends.
|
||||
|
||||
Local backends store data locally and can work offline.
|
||||
They serve as the source of truth for synchronization.
|
||||
"""
|
||||
pass
|
||||
|
||||
|
||||
class RemoteBackend(IssueBackend):
|
||||
"""
|
||||
Marker interface for remote backends.
|
||||
|
||||
Remote backends connect to external issue tracking systems.
|
||||
They participate in bidirectional synchronization.
|
||||
"""
|
||||
pass
|
||||
|
||||
|
||||
class SyncableBackend(ABC):
|
||||
"""
|
||||
Interface for backends that support synchronization.
|
||||
|
||||
Backends implementing this interface can participate in
|
||||
bidirectional sync operations.
|
||||
"""
|
||||
|
||||
@abstractmethod
|
||||
def prepare_for_sync(self) -> None:
|
||||
"""Prepare backend for sync operation (e.g., create backup)."""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def finalize_sync(self, success: bool) -> None:
|
||||
"""Finalize sync operation (e.g., commit or rollback)."""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def get_sync_conflicts(self) -> List[Dict[str, Any]]:
|
||||
"""Get issues that have sync conflicts."""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def resolve_sync_conflict(self, issue_id: str, resolution: str) -> Issue:
|
||||
"""
|
||||
Resolve a sync conflict.
|
||||
|
||||
Args:
|
||||
issue_id: Issue with conflict
|
||||
resolution: 'local' or 'remote' or 'merge'
|
||||
"""
|
||||
pass
|
||||
|
||||
|
||||
class BackendFactory:
|
||||
"""Factory for creating backend instances."""
|
||||
|
||||
_backends: Dict[str, type] = {}
|
||||
|
||||
@classmethod
|
||||
def register_backend(cls, backend_type: str, backend_class: type) -> None:
|
||||
"""Register a backend implementation."""
|
||||
cls._backends[backend_type] = backend_class
|
||||
|
||||
@classmethod
|
||||
def create_backend(cls, backend_type: str) -> IssueBackend:
|
||||
"""Create a backend instance."""
|
||||
if backend_type not in cls._backends:
|
||||
raise ValueError(f"Unknown backend type: {backend_type}")
|
||||
|
||||
return cls._backends[backend_type]()
|
||||
|
||||
@classmethod
|
||||
def get_available_backends(cls) -> List[str]:
|
||||
"""Get list of available backend types."""
|
||||
return list(cls._backends.keys())
|
||||
@@ -1,341 +0,0 @@
|
||||
"""
|
||||
Core Issue Domain Models
|
||||
|
||||
Unified, backend-agnostic issue models that serve as the single source of truth
|
||||
for all issue tracking operations. These models combine the best features from
|
||||
various issue tracking systems while maintaining clean domain logic.
|
||||
"""
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
from datetime import datetime, timezone
|
||||
from enum import Enum
|
||||
from typing import List, Optional, Dict, Any
|
||||
from functools import cached_property
|
||||
|
||||
|
||||
class IssueState(Enum):
|
||||
"""Universal issue state enumeration with backend mapping support."""
|
||||
OPEN = "open"
|
||||
CLOSED = "closed"
|
||||
IN_PROGRESS = "in_progress"
|
||||
BLOCKED = "blocked"
|
||||
|
||||
@classmethod
|
||||
def from_string(cls, state_str: str) -> 'IssueState':
|
||||
"""Convert string to IssueState, with fallback handling."""
|
||||
state_map = {
|
||||
'open': cls.OPEN,
|
||||
'closed': cls.CLOSED,
|
||||
'in_progress': cls.IN_PROGRESS,
|
||||
'in-progress': cls.IN_PROGRESS,
|
||||
'progress': cls.IN_PROGRESS,
|
||||
'blocked': cls.BLOCKED,
|
||||
}
|
||||
return state_map.get(state_str.lower(), cls.OPEN)
|
||||
|
||||
def to_backend_string(self, backend_type: str) -> str:
|
||||
"""Convert to backend-specific string representation."""
|
||||
if backend_type == 'gitea':
|
||||
return 'open' if self in [self.OPEN, self.IN_PROGRESS, self.BLOCKED] else 'closed'
|
||||
elif backend_type == 'github':
|
||||
return self.value
|
||||
else:
|
||||
return self.value
|
||||
|
||||
|
||||
class Priority(Enum):
|
||||
"""Universal priority levels."""
|
||||
LOW = "low"
|
||||
MEDIUM = "medium"
|
||||
HIGH = "high"
|
||||
CRITICAL = "critical"
|
||||
|
||||
@classmethod
|
||||
def from_label(cls, label_name: str) -> Optional['Priority']:
|
||||
"""Extract priority from label name."""
|
||||
if label_name.startswith('priority:'):
|
||||
priority_str = label_name.replace('priority:', '')
|
||||
try:
|
||||
return cls(priority_str)
|
||||
except ValueError:
|
||||
return None
|
||||
return None
|
||||
|
||||
|
||||
class IssueType(Enum):
|
||||
"""Universal issue types."""
|
||||
BUG = "bug"
|
||||
FEATURE = "feature"
|
||||
ENHANCEMENT = "enhancement"
|
||||
TASK = "task"
|
||||
DOCUMENTATION = "documentation"
|
||||
QUESTION = "question"
|
||||
|
||||
@classmethod
|
||||
def from_label(cls, label_name: str) -> Optional['IssueType']:
|
||||
"""Extract type from label name."""
|
||||
try:
|
||||
return cls(label_name.lower())
|
||||
except ValueError:
|
||||
return None
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Label:
|
||||
"""Universal label model with backend mapping support."""
|
||||
name: str
|
||||
color: Optional[str] = None
|
||||
description: Optional[str] = None
|
||||
backend_id: Optional[str] = None # Backend-specific ID for sync
|
||||
|
||||
@cached_property
|
||||
def category(self) -> str:
|
||||
"""Categorize label for efficient filtering."""
|
||||
if self.name.startswith('priority:'):
|
||||
return 'priority'
|
||||
elif self.name.startswith('status:'):
|
||||
return 'status'
|
||||
elif self.name.startswith('type:'):
|
||||
return 'type'
|
||||
elif self.name in ['bug', 'feature', 'enhancement', 'task', 'documentation', 'question']:
|
||||
return 'type'
|
||||
else:
|
||||
return 'other'
|
||||
|
||||
@cached_property
|
||||
def priority(self) -> Optional[Priority]:
|
||||
"""Extract priority if this is a priority label."""
|
||||
return Priority.from_label(self.name)
|
||||
|
||||
@cached_property
|
||||
def issue_type(self) -> Optional[IssueType]:
|
||||
"""Extract issue type if this is a type label."""
|
||||
return IssueType.from_label(self.name)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class LabelCategories:
|
||||
"""Categorized labels for efficient access."""
|
||||
priority_labels: List[Label]
|
||||
type_labels: List[Label]
|
||||
status_labels: List[Label]
|
||||
other_labels: List[Label]
|
||||
|
||||
@cached_property
|
||||
def priority(self) -> Optional[Priority]:
|
||||
"""Get the issue priority."""
|
||||
for label in self.priority_labels:
|
||||
if label.priority:
|
||||
return label.priority
|
||||
return None
|
||||
|
||||
@cached_property
|
||||
def issue_type(self) -> Optional[IssueType]:
|
||||
"""Get the issue type."""
|
||||
for label in self.type_labels:
|
||||
if label.issue_type:
|
||||
return label.issue_type
|
||||
return None
|
||||
|
||||
|
||||
@dataclass
|
||||
class User:
|
||||
"""Universal user model."""
|
||||
id: str # String ID to handle different backend ID types
|
||||
username: str
|
||||
display_name: Optional[str] = None
|
||||
email: Optional[str] = None
|
||||
avatar_url: Optional[str] = None
|
||||
backend_id: Optional[str] = None # Backend-specific ID for sync
|
||||
|
||||
|
||||
@dataclass
|
||||
class Milestone:
|
||||
"""Universal milestone/project model."""
|
||||
id: str
|
||||
title: str
|
||||
description: Optional[str] = None
|
||||
state: str = "open" # open, closed
|
||||
due_date: Optional[datetime] = None
|
||||
created_at: Optional[datetime] = None
|
||||
updated_at: Optional[datetime] = None
|
||||
backend_id: Optional[str] = None
|
||||
|
||||
|
||||
@dataclass
|
||||
class Comment:
|
||||
"""Universal comment model."""
|
||||
id: str
|
||||
body: str
|
||||
author: User
|
||||
created_at: datetime
|
||||
updated_at: Optional[datetime] = None
|
||||
backend_id: Optional[str] = None
|
||||
|
||||
|
||||
@dataclass
|
||||
class Issue:
|
||||
"""
|
||||
Universal Issue model - single source of truth.
|
||||
|
||||
Combines the best features from domain and API models while maintaining
|
||||
clean separation between core data and backend-specific details.
|
||||
"""
|
||||
# Core Issue Data
|
||||
id: str # Universal ID (UUID for local, external ID for remotes)
|
||||
number: int # Human-readable number
|
||||
title: str
|
||||
description: str
|
||||
state: IssueState
|
||||
|
||||
# Metadata
|
||||
created_at: datetime
|
||||
updated_at: datetime
|
||||
closed_at: Optional[datetime] = None
|
||||
|
||||
# Relationships
|
||||
labels: List[Label] = field(default_factory=list)
|
||||
assignees: List[User] = field(default_factory=list)
|
||||
milestone: Optional[Milestone] = None
|
||||
comments: List[Comment] = field(default_factory=list)
|
||||
|
||||
# Backend Integration
|
||||
backend_id: Optional[str] = None # Backend-specific ID
|
||||
backend_type: Optional[str] = None # e.g., 'local', 'gitea', 'github'
|
||||
sync_metadata: Dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
# Performance Optimization
|
||||
_label_categories: Optional[LabelCategories] = field(default=None, init=False)
|
||||
|
||||
@cached_property
|
||||
def label_categories(self) -> LabelCategories:
|
||||
"""Efficiently categorize labels with caching."""
|
||||
if self._label_categories is None:
|
||||
# Single-pass categorization for performance
|
||||
priority_labels = []
|
||||
type_labels = []
|
||||
status_labels = []
|
||||
other_labels = []
|
||||
|
||||
for label in self.labels:
|
||||
if label.category == 'priority':
|
||||
priority_labels.append(label)
|
||||
elif label.category == 'type':
|
||||
type_labels.append(label)
|
||||
elif label.category == 'status':
|
||||
status_labels.append(label)
|
||||
else:
|
||||
other_labels.append(label)
|
||||
|
||||
self._label_categories = LabelCategories(
|
||||
priority_labels=priority_labels,
|
||||
type_labels=type_labels,
|
||||
status_labels=status_labels,
|
||||
other_labels=other_labels
|
||||
)
|
||||
return self._label_categories
|
||||
|
||||
@property
|
||||
def priority(self) -> Optional[Priority]:
|
||||
"""Get issue priority from labels."""
|
||||
return self.label_categories.priority
|
||||
|
||||
@property
|
||||
def issue_type(self) -> Optional[IssueType]:
|
||||
"""Get issue type from labels."""
|
||||
return self.label_categories.issue_type
|
||||
|
||||
@property
|
||||
def primary_assignee(self) -> Optional[User]:
|
||||
"""Get primary assignee (first one)."""
|
||||
return self.assignees[0] if self.assignees else None
|
||||
|
||||
def invalidate_cache(self) -> None:
|
||||
"""Invalidate cached properties when labels change."""
|
||||
if hasattr(self, '_label_categories'):
|
||||
object.__setattr__(self, '_label_categories', None)
|
||||
|
||||
# Domain Logic Methods
|
||||
def close(self, closed_at: Optional[datetime] = None) -> None:
|
||||
"""Close the issue with business rule validation."""
|
||||
if self.state == IssueState.CLOSED:
|
||||
raise ValueError(f"Issue #{self.number} is already closed")
|
||||
|
||||
self.state = IssueState.CLOSED
|
||||
self.closed_at = closed_at or datetime.now(timezone.utc)
|
||||
self.updated_at = datetime.now(timezone.utc)
|
||||
|
||||
def reopen(self) -> None:
|
||||
"""Reopen the issue with business rule validation."""
|
||||
if self.state != IssueState.CLOSED:
|
||||
raise ValueError(f"Issue #{self.number} is not closed (current state: {self.state.value})")
|
||||
|
||||
self.state = IssueState.OPEN
|
||||
self.closed_at = None
|
||||
self.updated_at = datetime.now(timezone.utc)
|
||||
|
||||
def add_label(self, label: Label) -> None:
|
||||
"""Add a label to the issue."""
|
||||
if label not in self.labels:
|
||||
self.labels.append(label)
|
||||
self.invalidate_cache()
|
||||
self.updated_at = datetime.now(timezone.utc)
|
||||
|
||||
def remove_label(self, label_name: str) -> bool:
|
||||
"""Remove a label by name. Returns True if removed."""
|
||||
original_count = len(self.labels)
|
||||
self.labels = [label for label in self.labels if label.name != label_name]
|
||||
if len(self.labels) < original_count:
|
||||
self.invalidate_cache()
|
||||
self.updated_at = datetime.now(timezone.utc)
|
||||
return True
|
||||
return False
|
||||
|
||||
def has_label(self, label_name: str) -> bool:
|
||||
"""Check if issue has a specific label."""
|
||||
return any(label.name == label_name for label in self.labels)
|
||||
|
||||
def add_assignee(self, user: User) -> None:
|
||||
"""Add an assignee to the issue."""
|
||||
if user not in self.assignees:
|
||||
self.assignees.append(user)
|
||||
self.updated_at = datetime.now(timezone.utc)
|
||||
|
||||
def remove_assignee(self, user_id: str) -> bool:
|
||||
"""Remove an assignee by ID. Returns True if removed."""
|
||||
original_count = len(self.assignees)
|
||||
self.assignees = [user for user in self.assignees if user.id != user_id]
|
||||
if len(self.assignees) < original_count:
|
||||
self.updated_at = datetime.now(timezone.utc)
|
||||
return True
|
||||
return False
|
||||
|
||||
def add_comment(self, comment: Comment) -> None:
|
||||
"""Add a comment to the issue."""
|
||||
self.comments.append(comment)
|
||||
self.updated_at = datetime.now(timezone.utc)
|
||||
|
||||
def to_dict(self) -> Dict[str, Any]:
|
||||
"""Convert to dictionary for serialization."""
|
||||
return {
|
||||
'id': self.id,
|
||||
'number': self.number,
|
||||
'title': self.title,
|
||||
'description': self.description,
|
||||
'state': self.state.value,
|
||||
'created_at': self.created_at.isoformat(),
|
||||
'updated_at': self.updated_at.isoformat(),
|
||||
'closed_at': self.closed_at.isoformat() if self.closed_at else None,
|
||||
'labels': [{'name': l.name, 'color': l.color, 'description': l.description} for l in self.labels],
|
||||
'assignees': [{'id': u.id, 'username': u.username, 'display_name': u.display_name} for u in self.assignees],
|
||||
'milestone': {'id': self.milestone.id, 'title': self.milestone.title} if self.milestone else None,
|
||||
'backend_id': self.backend_id,
|
||||
'backend_type': self.backend_type,
|
||||
}
|
||||
|
||||
@classmethod
|
||||
def from_dict(cls, data: Dict[str, Any]) -> 'Issue':
|
||||
"""Create Issue from dictionary."""
|
||||
# This would be implemented with proper parsing
|
||||
# Simplified version for now
|
||||
raise NotImplementedError("from_dict implementation needed")
|
||||
@@ -1,454 +0,0 @@
|
||||
"""
|
||||
Repository Pattern Implementation
|
||||
|
||||
Provides a high-level repository interface that abstracts backend operations
|
||||
and adds features like caching, transaction support, and business logic.
|
||||
"""
|
||||
|
||||
from abc import ABC, abstractmethod
|
||||
from typing import List, Optional, Dict, Any, Union
|
||||
from datetime import datetime, timezone
|
||||
import logging
|
||||
|
||||
from .interfaces import IssueBackend, IssueFilter
|
||||
from .models import Issue, Label, User, Milestone, Comment, IssueState
|
||||
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class IssueRepository:
|
||||
"""
|
||||
High-level repository for issue operations.
|
||||
|
||||
Provides a clean interface for issue management with additional features
|
||||
like caching, validation, and business rule enforcement.
|
||||
"""
|
||||
|
||||
def __init__(self, backend: IssueBackend, enable_caching: bool = True):
|
||||
self.backend = backend
|
||||
self.enable_caching = enable_caching
|
||||
self._cache: Dict[str, Any] = {}
|
||||
self._cache_timeout = 300 # 5 minutes
|
||||
|
||||
def _cache_key(self, operation: str, *args) -> str:
|
||||
"""Generate cache key for operation."""
|
||||
return f"{operation}:{':'.join(str(arg) for arg in args)}"
|
||||
|
||||
def _get_from_cache(self, key: str) -> Optional[Any]:
|
||||
"""Get value from cache if enabled and not expired."""
|
||||
if not self.enable_caching or key not in self._cache:
|
||||
return None
|
||||
|
||||
cached_item = self._cache[key]
|
||||
if datetime.now(timezone.utc).timestamp() - cached_item['timestamp'] > self._cache_timeout:
|
||||
del self._cache[key]
|
||||
return None
|
||||
|
||||
return cached_item['value']
|
||||
|
||||
def _set_cache(self, key: str, value: Any) -> None:
|
||||
"""Set value in cache if enabled."""
|
||||
if self.enable_caching:
|
||||
self._cache[key] = {
|
||||
'value': value,
|
||||
'timestamp': datetime.now(timezone.utc).timestamp()
|
||||
}
|
||||
|
||||
def _invalidate_cache_pattern(self, pattern: str) -> None:
|
||||
"""Invalidate cache entries matching pattern."""
|
||||
if not self.enable_caching:
|
||||
return
|
||||
|
||||
keys_to_remove = [key for key in self._cache.keys() if pattern in key]
|
||||
for key in keys_to_remove:
|
||||
del self._cache[key]
|
||||
|
||||
# Issue Operations
|
||||
def create_issue(
|
||||
self,
|
||||
title: str,
|
||||
description: str = "",
|
||||
labels: Optional[List[str]] = None,
|
||||
assignees: Optional[List[str]] = None,
|
||||
milestone: Optional[str] = None,
|
||||
issue_type: Optional[str] = None,
|
||||
priority: Optional[str] = None
|
||||
) -> Issue:
|
||||
"""
|
||||
Create a new issue with business rule validation.
|
||||
|
||||
Args:
|
||||
title: Issue title (required)
|
||||
description: Issue description
|
||||
labels: List of label names
|
||||
assignees: List of usernames to assign
|
||||
milestone: Milestone title or ID
|
||||
issue_type: Issue type (bug, feature, etc.)
|
||||
priority: Priority level (low, medium, high, critical)
|
||||
|
||||
Returns:
|
||||
Created issue
|
||||
"""
|
||||
# Validation
|
||||
if not title.strip():
|
||||
raise ValueError("Issue title cannot be empty")
|
||||
|
||||
# Build labels
|
||||
issue_labels = []
|
||||
if labels:
|
||||
for label_name in labels:
|
||||
issue_labels.append(Label(name=label_name.strip()))
|
||||
|
||||
# Add type and priority as labels
|
||||
if issue_type:
|
||||
issue_labels.append(Label(name=issue_type))
|
||||
|
||||
if priority:
|
||||
issue_labels.append(Label(name=f'priority:{priority}'))
|
||||
|
||||
# Resolve assignees
|
||||
issue_assignees = []
|
||||
if assignees:
|
||||
for username in assignees:
|
||||
users = self.backend.search_users(username)
|
||||
if users:
|
||||
issue_assignees.append(users[0])
|
||||
else:
|
||||
# Create basic user if not found
|
||||
issue_assignees.append(User(id=username, username=username))
|
||||
|
||||
# Resolve milestone
|
||||
issue_milestone = None
|
||||
if milestone:
|
||||
milestones = self.backend.get_milestones()
|
||||
for m in milestones:
|
||||
if m.title == milestone or m.id == milestone:
|
||||
issue_milestone = m
|
||||
break
|
||||
|
||||
# Create issue
|
||||
now = datetime.now(timezone.utc)
|
||||
issue = Issue(
|
||||
id="", # Will be set by backend
|
||||
number=0, # Will be set by backend
|
||||
title=title.strip(),
|
||||
description=description.strip(),
|
||||
state=IssueState.OPEN,
|
||||
created_at=now,
|
||||
updated_at=now,
|
||||
labels=issue_labels,
|
||||
assignees=issue_assignees,
|
||||
milestone=issue_milestone
|
||||
)
|
||||
|
||||
created_issue = self.backend.create_issue(issue)
|
||||
|
||||
# Invalidate relevant caches
|
||||
self._invalidate_cache_pattern("list_issues")
|
||||
self._invalidate_cache_pattern("search_issues")
|
||||
|
||||
logger.info(f"Created issue #{created_issue.number}: {created_issue.title}")
|
||||
return created_issue
|
||||
|
||||
def get_issue(self, issue_id: Union[str, int]) -> Optional[Issue]:
|
||||
"""Get issue by ID or number."""
|
||||
if isinstance(issue_id, int):
|
||||
return self.get_issue_by_number(issue_id)
|
||||
|
||||
cache_key = self._cache_key("get_issue", issue_id)
|
||||
cached_issue = self._get_from_cache(cache_key)
|
||||
if cached_issue:
|
||||
return cached_issue
|
||||
|
||||
issue = self.backend.get_issue(str(issue_id))
|
||||
if issue:
|
||||
self._set_cache(cache_key, issue)
|
||||
|
||||
return issue
|
||||
|
||||
def get_issue_by_number(self, number: int) -> Optional[Issue]:
|
||||
"""Get issue by number."""
|
||||
cache_key = self._cache_key("get_issue_by_number", number)
|
||||
cached_issue = self._get_from_cache(cache_key)
|
||||
if cached_issue:
|
||||
return cached_issue
|
||||
|
||||
issue = self.backend.get_issue_by_number(number)
|
||||
if issue:
|
||||
self._set_cache(cache_key, issue)
|
||||
|
||||
return issue
|
||||
|
||||
def update_issue(self, issue: Issue) -> Issue:
|
||||
"""Update issue with validation."""
|
||||
if not issue.title.strip():
|
||||
raise ValueError("Issue title cannot be empty")
|
||||
|
||||
issue.updated_at = datetime.now(timezone.utc)
|
||||
updated_issue = self.backend.update_issue(issue)
|
||||
|
||||
# Invalidate caches
|
||||
self._invalidate_cache_pattern("get_issue")
|
||||
self._invalidate_cache_pattern("list_issues")
|
||||
self._invalidate_cache_pattern("search_issues")
|
||||
|
||||
logger.info(f"Updated issue #{updated_issue.number}: {updated_issue.title}")
|
||||
return updated_issue
|
||||
|
||||
def close_issue(self, issue_id: Union[str, int], comment: Optional[str] = None) -> Issue:
|
||||
"""Close issue with optional comment."""
|
||||
issue = self.get_issue(issue_id)
|
||||
if not issue:
|
||||
raise ValueError(f"Issue {issue_id} not found")
|
||||
|
||||
if issue.state == IssueState.CLOSED:
|
||||
raise ValueError(f"Issue #{issue.number} is already closed")
|
||||
|
||||
issue.close()
|
||||
|
||||
# Add closing comment if provided
|
||||
if comment:
|
||||
self.add_comment(issue.id, comment)
|
||||
|
||||
return self.update_issue(issue)
|
||||
|
||||
def reopen_issue(self, issue_id: Union[str, int], comment: Optional[str] = None) -> Issue:
|
||||
"""Reopen issue with optional comment."""
|
||||
issue = self.get_issue(issue_id)
|
||||
if not issue:
|
||||
raise ValueError(f"Issue {issue_id} not found")
|
||||
|
||||
if issue.state != IssueState.CLOSED:
|
||||
raise ValueError(f"Issue #{issue.number} is not closed")
|
||||
|
||||
issue.reopen()
|
||||
|
||||
# Add reopening comment if provided
|
||||
if comment:
|
||||
self.add_comment(issue.id, comment)
|
||||
|
||||
return self.update_issue(issue)
|
||||
|
||||
def list_issues(
|
||||
self,
|
||||
state: Optional[str] = None,
|
||||
assignee: Optional[str] = None,
|
||||
labels: Optional[List[str]] = None,
|
||||
milestone: Optional[str] = None,
|
||||
search: Optional[str] = None,
|
||||
limit: Optional[int] = None,
|
||||
offset: Optional[int] = None
|
||||
) -> List[Issue]:
|
||||
"""List issues with filtering and caching."""
|
||||
filter_criteria = IssueFilter(
|
||||
state=state,
|
||||
assignee=assignee,
|
||||
labels=labels,
|
||||
milestone=milestone,
|
||||
search=search,
|
||||
limit=limit,
|
||||
offset=offset
|
||||
)
|
||||
|
||||
# Create cache key from filter criteria
|
||||
cache_key = self._cache_key(
|
||||
"list_issues",
|
||||
state or "all",
|
||||
assignee or "any",
|
||||
",".join(labels) if labels else "any",
|
||||
milestone or "any",
|
||||
search or "any",
|
||||
limit or 0,
|
||||
offset or 0
|
||||
)
|
||||
|
||||
cached_issues = self._get_from_cache(cache_key)
|
||||
if cached_issues:
|
||||
return cached_issues
|
||||
|
||||
issues = self.backend.list_issues(filter_criteria)
|
||||
self._set_cache(cache_key, issues)
|
||||
|
||||
return issues
|
||||
|
||||
def search_issues(self, query: str, limit: Optional[int] = None) -> List[Issue]:
|
||||
"""Search issues with caching."""
|
||||
cache_key = self._cache_key("search_issues", query, limit or 0)
|
||||
cached_issues = self._get_from_cache(cache_key)
|
||||
if cached_issues:
|
||||
return cached_issues
|
||||
|
||||
issues = self.backend.search_issues(query, limit)
|
||||
self._set_cache(cache_key, issues)
|
||||
|
||||
return issues
|
||||
|
||||
# Comment Operations
|
||||
def add_comment(self, issue_id: str, comment_text: str, author_username: str = "cli-user") -> Comment:
|
||||
"""Add comment to issue."""
|
||||
if not comment_text.strip():
|
||||
raise ValueError("Comment text cannot be empty")
|
||||
|
||||
# Try to find user
|
||||
users = self.backend.search_users(author_username)
|
||||
if users:
|
||||
author = users[0]
|
||||
else:
|
||||
author = User(id=author_username, username=author_username)
|
||||
|
||||
comment = Comment(
|
||||
id="",
|
||||
body=comment_text.strip(),
|
||||
author=author,
|
||||
created_at=datetime.now(timezone.utc)
|
||||
)
|
||||
|
||||
added_comment = self.backend.add_comment(issue_id, comment)
|
||||
|
||||
# Invalidate issue cache
|
||||
self._invalidate_cache_pattern("get_issue")
|
||||
|
||||
logger.info(f"Added comment to issue {issue_id}")
|
||||
return added_comment
|
||||
|
||||
def get_comments(self, issue_id: str) -> List[Comment]:
|
||||
"""Get comments for issue."""
|
||||
cache_key = self._cache_key("get_comments", issue_id)
|
||||
cached_comments = self._get_from_cache(cache_key)
|
||||
if cached_comments:
|
||||
return cached_comments
|
||||
|
||||
comments = self.backend.get_comments(issue_id)
|
||||
self._set_cache(cache_key, comments)
|
||||
|
||||
return comments
|
||||
|
||||
# Label Operations
|
||||
def get_or_create_label(self, name: str, color: Optional[str] = None, description: Optional[str] = None) -> Label:
|
||||
"""Get existing label or create new one."""
|
||||
existing_labels = self.backend.get_labels()
|
||||
for label in existing_labels:
|
||||
if label.name == name:
|
||||
return label
|
||||
|
||||
# Create new label
|
||||
new_label = Label(name=name, color=color, description=description)
|
||||
return self.backend.create_label(new_label)
|
||||
|
||||
# Statistics and Analytics
|
||||
def get_issue_stats(self) -> Dict[str, Any]:
|
||||
"""Get issue statistics."""
|
||||
cache_key = self._cache_key("get_issue_stats")
|
||||
cached_stats = self._get_from_cache(cache_key)
|
||||
if cached_stats:
|
||||
return cached_stats
|
||||
|
||||
all_issues = self.backend.list_issues()
|
||||
|
||||
stats = {
|
||||
'total': len(all_issues),
|
||||
'open': len([i for i in all_issues if i.state != IssueState.CLOSED]),
|
||||
'closed': len([i for i in all_issues if i.state == IssueState.CLOSED]),
|
||||
'by_state': {},
|
||||
'by_priority': {},
|
||||
'by_type': {},
|
||||
'by_assignee': {},
|
||||
'recent_activity': 0
|
||||
}
|
||||
|
||||
# Count by state
|
||||
for issue in all_issues:
|
||||
state = issue.state.value
|
||||
stats['by_state'][state] = stats['by_state'].get(state, 0) + 1
|
||||
|
||||
# Count by priority and type
|
||||
one_week_ago = datetime.now(timezone.utc).timestamp() - 604800 # 7 days
|
||||
|
||||
for issue in all_issues:
|
||||
# Priority
|
||||
priority = issue.priority
|
||||
if priority:
|
||||
priority_name = priority.value
|
||||
stats['by_priority'][priority_name] = stats['by_priority'].get(priority_name, 0) + 1
|
||||
|
||||
# Type
|
||||
issue_type = issue.issue_type
|
||||
if issue_type:
|
||||
type_name = issue_type.value
|
||||
stats['by_type'][type_name] = stats['by_type'].get(type_name, 0) + 1
|
||||
|
||||
# Assignee
|
||||
if issue.assignees:
|
||||
for assignee in issue.assignees:
|
||||
username = assignee.username
|
||||
stats['by_assignee'][username] = stats['by_assignee'].get(username, 0) + 1
|
||||
|
||||
# Recent activity
|
||||
if issue.updated_at.timestamp() > one_week_ago:
|
||||
stats['recent_activity'] += 1
|
||||
|
||||
self._set_cache(cache_key, stats)
|
||||
return stats
|
||||
|
||||
# Bulk Operations
|
||||
def bulk_close_issues(self, issue_numbers: List[int], comment: Optional[str] = None) -> List[Issue]:
|
||||
"""Close multiple issues."""
|
||||
results = []
|
||||
for number in issue_numbers:
|
||||
try:
|
||||
closed_issue = self.close_issue(number, comment)
|
||||
results.append(closed_issue)
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to close issue #{number}: {e}")
|
||||
|
||||
return results
|
||||
|
||||
def bulk_add_label(self, issue_numbers: List[int], label_name: str) -> List[Issue]:
|
||||
"""Add label to multiple issues."""
|
||||
label = self.get_or_create_label(label_name)
|
||||
results = []
|
||||
|
||||
for number in issue_numbers:
|
||||
try:
|
||||
issue = self.get_issue_by_number(number)
|
||||
if issue:
|
||||
issue.add_label(label)
|
||||
updated_issue = self.update_issue(issue)
|
||||
results.append(updated_issue)
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to add label to issue #{number}: {e}")
|
||||
|
||||
return results
|
||||
|
||||
# Cache Management
|
||||
def clear_cache(self) -> None:
|
||||
"""Clear all cached data."""
|
||||
self._cache.clear()
|
||||
logger.info("Repository cache cleared")
|
||||
|
||||
def get_cache_stats(self) -> Dict[str, Any]:
|
||||
"""Get cache statistics."""
|
||||
if not self.enable_caching:
|
||||
return {'enabled': False}
|
||||
|
||||
now = datetime.now(timezone.utc).timestamp()
|
||||
expired_count = 0
|
||||
for cached_item in self._cache.values():
|
||||
if now - cached_item['timestamp'] > self._cache_timeout:
|
||||
expired_count += 1
|
||||
|
||||
return {
|
||||
'enabled': True,
|
||||
'total_entries': len(self._cache),
|
||||
'expired_entries': expired_count,
|
||||
'cache_timeout': self._cache_timeout
|
||||
}
|
||||
|
||||
# Context Manager Support
|
||||
def __enter__(self):
|
||||
return self
|
||||
|
||||
def __exit__(self, exc_type, exc_val, exc_tb):
|
||||
if hasattr(self.backend, 'disconnect'):
|
||||
self.backend.disconnect()
|
||||
@@ -11,7 +11,7 @@ from pathlib import Path
|
||||
from typing import Optional
|
||||
|
||||
# Base version from pyproject.toml
|
||||
__version__ = "0.2.0"
|
||||
__version__ = "0.4.0"
|
||||
|
||||
def get_git_commit_hash() -> Optional[str]:
|
||||
"""Get the current git commit hash if available."""
|
||||
|
||||
@@ -574,35 +574,35 @@ class DocumentManager:
|
||||
const sections = content.querySelectorAll('.markitect-section-editable');
|
||||
let reconstructed = '';
|
||||
|
||||
sections.forEach(section => {
|
||||
sections.forEach(section => {{
|
||||
const tagName = section.tagName.toLowerCase();
|
||||
const text = section.textContent.trim();
|
||||
|
||||
if (tagName.startsWith('h')) {
|
||||
if (tagName.startsWith('h')) {{
|
||||
const level = parseInt(tagName.charAt(1));
|
||||
reconstructed += '#'.repeat(level) + ' ' + text + '\n\n';
|
||||
} else if (tagName === 'p') {
|
||||
reconstructed += text + '\n\n';
|
||||
} else if (tagName === 'blockquote') {
|
||||
reconstructed += '> ' + text + '\n\n';
|
||||
} else if (tagName === 'pre') {
|
||||
reconstructed += '```\n' + text + '\n```\n\n';
|
||||
} else if (tagName === 'ul') {
|
||||
reconstructed += '#'.repeat(level) + ' ' + text + '\\n\\n';
|
||||
}} else if (tagName === 'p') {{
|
||||
reconstructed += text + '\\n\\n';
|
||||
}} else if (tagName === 'blockquote') {{
|
||||
reconstructed += '> ' + text + '\\n\\n';
|
||||
}} else if (tagName === 'pre') {{
|
||||
reconstructed += '```\\n' + text + '\\n```\\n\\n';
|
||||
}} else if (tagName === 'ul') {{
|
||||
const items = section.querySelectorAll('li');
|
||||
items.forEach(item => {
|
||||
reconstructed += '- ' + item.textContent.trim() + '\n';
|
||||
});
|
||||
reconstructed += '\n';
|
||||
} else if (tagName === 'ol') {
|
||||
items.forEach(item => {{
|
||||
reconstructed += '- ' + item.textContent.trim() + '\\n';
|
||||
}});
|
||||
reconstructed += '\\n';
|
||||
}} else if (tagName === 'ol') {{
|
||||
const items = section.querySelectorAll('li');
|
||||
items.forEach((item, index) => {
|
||||
reconstructed += `${index + 1}. ` + item.textContent.trim() + '\n';
|
||||
});
|
||||
reconstructed += '\n';
|
||||
} else {
|
||||
reconstructed += text + '\n\n';
|
||||
}
|
||||
});
|
||||
items.forEach((item, index) => {{
|
||||
reconstructed += (index + 1) + '. ' + item.textContent.trim() + '\\n';
|
||||
}});
|
||||
reconstructed += '\\n';
|
||||
}} else {{
|
||||
reconstructed += text + '\\n\\n';
|
||||
}}
|
||||
}});
|
||||
|
||||
return reconstructed.trim();
|
||||
}
|
||||
@@ -617,9 +617,82 @@ class DocumentManager:
|
||||
# Edit mode status and error reporting section
|
||||
edit_mode_html = ""
|
||||
if edit_mode:
|
||||
# Get version info for header
|
||||
try:
|
||||
import markitect
|
||||
from pathlib import Path
|
||||
import subprocess
|
||||
|
||||
# Get base version
|
||||
version = "0.3.0" # fallback
|
||||
try:
|
||||
from importlib.metadata import version as get_version
|
||||
version = get_version('markitect')
|
||||
except:
|
||||
pass
|
||||
|
||||
# Get git commit with timestamp and local changes info
|
||||
git_info = ""
|
||||
try:
|
||||
repo_path = Path(__file__).parent.parent
|
||||
|
||||
# Get commit hash and timestamp
|
||||
result = subprocess.run(['git', 'rev-parse', '--short', 'HEAD'],
|
||||
capture_output=True, text=True, cwd=repo_path)
|
||||
if result.returncode == 0:
|
||||
commit_hash = result.stdout.strip()
|
||||
|
||||
# Get commit timestamp
|
||||
timestamp_result = subprocess.run(['git', 'show', '-s', '--format=%ci', 'HEAD'],
|
||||
capture_output=True, text=True, cwd=repo_path)
|
||||
commit_time = ""
|
||||
if timestamp_result.returncode == 0:
|
||||
from datetime import datetime
|
||||
# Parse git timestamp and format it nicely
|
||||
git_time = timestamp_result.stdout.strip()
|
||||
try:
|
||||
dt = datetime.fromisoformat(git_time.replace(' +', '+'))
|
||||
commit_time = f" ({dt.strftime('%Y-%m-%d %H:%M')})"
|
||||
except:
|
||||
pass
|
||||
|
||||
git_info = f"+{commit_hash}{commit_time}"
|
||||
|
||||
# Check for uncommitted changes
|
||||
status_result = subprocess.run(['git', 'status', '--porcelain'],
|
||||
capture_output=True, text=True, cwd=repo_path)
|
||||
if status_result.returncode == 0 and status_result.stdout.strip():
|
||||
# Get timestamp of most recent uncommitted change
|
||||
import os
|
||||
import glob
|
||||
|
||||
latest_change = 0
|
||||
for line in status_result.stdout.strip().split('\n'):
|
||||
if line.strip():
|
||||
# Extract filename (skip first 3 chars which are status indicators)
|
||||
filename = line[3:].strip()
|
||||
try:
|
||||
file_path = repo_path / filename
|
||||
if file_path.exists():
|
||||
mtime = os.path.getmtime(file_path)
|
||||
latest_change = max(latest_change, mtime)
|
||||
except:
|
||||
pass
|
||||
|
||||
if latest_change > 0:
|
||||
change_dt = datetime.fromtimestamp(latest_change)
|
||||
git_info += f" including local changes until {change_dt.strftime('%Y-%m-%d %H:%M')}"
|
||||
|
||||
except:
|
||||
pass
|
||||
|
||||
version_info = f"{version}{git_info}"
|
||||
except:
|
||||
version_info = "0.3.0"
|
||||
|
||||
edit_mode_html = f"""
|
||||
<div id="markitect-status" style="background: #e3f2fd; border-left: 4px solid #2196f3; padding: 12px; margin-bottom: 20px; font-family: monospace; font-size: 14px;">
|
||||
<div style="font-weight: bold; color: #1976d2;">📝 Markitect Edit Mode</div>
|
||||
<div style="font-weight: bold; color: #1976d2;">📝 Markitect Edit Mode <span style="font-weight: normal; color: #666;">v{version_info}</span></div>
|
||||
<div id="status-message" style="margin-top: 8px;">Loading edit capabilities...</div>
|
||||
<div id="error-details" style="display: none; background: #ffebee; border: 1px solid #f44336; padding: 8px; margin-top: 8px; border-radius: 4px;">
|
||||
<div style="font-weight: bold; color: #c62828;">❌ Edit Mode Failed</div>
|
||||
@@ -659,20 +732,56 @@ class DocumentManager:
|
||||
// Define editor class first (if in edit mode)
|
||||
{editor_scripts if edit_mode else ''}
|
||||
|
||||
// Error reporting utility
|
||||
function reportEditModeError(errorMsg, technicalDetails) {{
|
||||
// Enhanced error reporting utility
|
||||
function reportEditModeError(errorMsg, technicalDetails, errorType = 'error') {{
|
||||
const statusDiv = document.getElementById('markitect-status');
|
||||
const errorDiv = document.getElementById('error-details');
|
||||
const errorText = document.getElementById('error-text');
|
||||
const statusMsg = document.getElementById('status-message');
|
||||
const browserInfo = document.getElementById('browser-info');
|
||||
|
||||
if (statusMsg) statusMsg.textContent = 'Edit mode unavailable - content displayed in read-only mode';
|
||||
// Log to console for debugging
|
||||
console.error('[MarkiTect Edit Mode Error]', errorMsg, technicalDetails);
|
||||
|
||||
// Create error report object
|
||||
const errorReport = {{
|
||||
timestamp: new Date().toISOString(),
|
||||
error: errorMsg,
|
||||
details: technicalDetails,
|
||||
type: errorType,
|
||||
userAgent: navigator.userAgent,
|
||||
url: window.location.href,
|
||||
markdownContent: typeof markdownContent !== 'undefined' ? markdownContent.length + ' chars' : 'unavailable'
|
||||
}};
|
||||
|
||||
// Store error for potential reporting
|
||||
if (!window.markitectErrors) window.markitectErrors = [];
|
||||
window.markitectErrors.push(errorReport);
|
||||
|
||||
// Update UI
|
||||
if (statusMsg) {{
|
||||
const statusText = errorType === 'warning'
|
||||
? 'Edit mode partially available - some features may not work'
|
||||
: 'Edit mode unavailable - content displayed in read-only mode';
|
||||
statusMsg.textContent = statusText;
|
||||
}}
|
||||
|
||||
if (errorDiv) errorDiv.style.display = 'block';
|
||||
if (errorText) errorText.textContent = errorMsg + (technicalDetails ? ' (' + technicalDetails + ')' : '');
|
||||
if (errorText) {{
|
||||
const fullError = errorMsg + (technicalDetails ? ' (' + technicalDetails + ')' : '');
|
||||
errorText.textContent = fullError;
|
||||
}}
|
||||
if (browserInfo) browserInfo.textContent = navigator.userAgent.split(' ').slice(-2).join(' ');
|
||||
|
||||
// Auto-hide warnings after 10 seconds
|
||||
if (errorType === 'warning' && errorDiv) {{
|
||||
setTimeout(() => {{
|
||||
errorDiv.style.display = 'none';
|
||||
}}, 10000);
|
||||
}}
|
||||
}}
|
||||
|
||||
|
||||
// Status update utility
|
||||
function updateStatus(message, isError = false) {{
|
||||
const statusMsg = document.getElementById('status-message');
|
||||
|
||||
0
markitect/finance/tests/__init__.py
Normal file
0
markitect/finance/tests/__init__.py
Normal file
0
markitect/graphql/tests/__init__.py
Normal file
0
markitect/graphql/tests/__init__.py
Normal file
@@ -1533,7 +1533,7 @@ def md_ingest_command(ctx, file_path):
|
||||
doc_manager = DocumentManager(config.get('db_manager'))
|
||||
|
||||
# Process the file
|
||||
result = doc_manager.ingest_file(file_path)
|
||||
result = doc_manager.ingest_file(Path(file_path))
|
||||
|
||||
if config.get('verbose', False):
|
||||
click.echo(f"Processing results:")
|
||||
@@ -2980,4 +2980,6 @@ class FilenameDecoder:
|
||||
|
||||
def decode_batch(self, filenames):
|
||||
"""Process multiple filenames in batch."""
|
||||
return [self.decode(filename) for filename in filenames]
|
||||
return [self.decode(filename) for filename in filenames]
|
||||
|
||||
|
||||
|
||||
0
markitect/plugins/tests/__init__.py
Normal file
0
markitect/plugins/tests/__init__.py
Normal file
0
markitect/query_paradigms/tests/__init__.py
Normal file
0
markitect/query_paradigms/tests/__init__.py
Normal file
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
||||
|
||||
[project]
|
||||
name = "markitect"
|
||||
version = "0.2.0"
|
||||
version = "0.4.0"
|
||||
description = "Advanced Markdown engine for structured content"
|
||||
readme = "README.md"
|
||||
requires-python = ">=3.8"
|
||||
|
||||
@@ -187,30 +187,6 @@ def test_model_processing():
|
||||
assert '"total_datamodels"' in json_report
|
||||
assert '"total_opportunities"' in json_report
|
||||
|
||||
def test_real_codebase_issueactivity(self):
|
||||
"""Test against real IssueActivity to verify it recognizes our optimizations."""
|
||||
project_root = Path(__file__).parent.parent
|
||||
|
||||
discovery = DatamodelDiscovery(project_root)
|
||||
datamodels = discovery.discover_datamodels()
|
||||
|
||||
# Should find IssueActivity
|
||||
assert "IssueActivity" in datamodels
|
||||
|
||||
model = datamodels["IssueActivity"]
|
||||
assert model.is_dataclass is True
|
||||
assert len(model.properties) >= 5 # Should have the properties we added
|
||||
assert len(model.methods) >= 3 # Should have the methods we added
|
||||
|
||||
# Should have the optimization methods we added
|
||||
assert "to_dict" in model.methods
|
||||
assert "has_implementation_activity" in model.methods
|
||||
assert "contains_keyword" in model.methods
|
||||
|
||||
# Should have the properties we added
|
||||
assert "activity_type_value" in model.properties
|
||||
assert "formatted_date" in model.properties
|
||||
assert "truncated_details" in model.properties
|
||||
|
||||
def test_impact_scoring(self, temp_project):
|
||||
"""Test that impact scoring works correctly."""
|
||||
|
||||
365
tests/test_issue_144_edit_mode_regression.py
Normal file
365
tests/test_issue_144_edit_mode_regression.py
Normal file
@@ -0,0 +1,365 @@
|
||||
"""
|
||||
Test suite for md-render --edit functionality to prevent regression.
|
||||
|
||||
This test suite specifically targets the critical JavaScript syntax errors
|
||||
that were causing edit mode to fail completely, ensuring they never happen again.
|
||||
"""
|
||||
|
||||
import tempfile
|
||||
import pytest
|
||||
from pathlib import Path
|
||||
import re
|
||||
import subprocess
|
||||
|
||||
|
||||
class TestEditModeRegression:
|
||||
"""Tests to prevent regression of the md-render --edit functionality."""
|
||||
|
||||
def test_edit_mode_generates_valid_javascript(self):
|
||||
"""Test that edit mode generates syntactically valid JavaScript."""
|
||||
from markitect.document_manager import DocumentManager
|
||||
|
||||
# Create a mock DocumentManager to avoid database dependency
|
||||
class MockDatabaseManager:
|
||||
pass
|
||||
|
||||
doc_manager = DocumentManager.__new__(DocumentManager)
|
||||
doc_manager.database_manager = MockDatabaseManager()
|
||||
|
||||
# Test markdown content
|
||||
test_content = "# Test Header\n\nThis is a test paragraph.\n\n## Section 2\n\nAnother paragraph."
|
||||
|
||||
# Generate HTML with edit mode
|
||||
html_content = doc_manager._generate_html_template(
|
||||
title="Test Document",
|
||||
markdown_content=test_content,
|
||||
edit_mode=True,
|
||||
editor_theme='github',
|
||||
keyboard_shortcuts=True
|
||||
)
|
||||
|
||||
# Extract JavaScript from HTML
|
||||
js_match = re.search(r'<script>(.*?)</script>', html_content, re.DOTALL)
|
||||
assert js_match, "No JavaScript found in edit mode HTML"
|
||||
|
||||
js_content = js_match.group(1)
|
||||
|
||||
# Write to temp file and validate syntax with Node.js
|
||||
with tempfile.NamedTemporaryFile(mode='w', suffix='.js', delete=False) as f:
|
||||
f.write(js_content)
|
||||
temp_js_path = f.name
|
||||
|
||||
try:
|
||||
# Use Node.js to check JavaScript syntax
|
||||
result = subprocess.run(
|
||||
['node', '-c', temp_js_path],
|
||||
capture_output=True,
|
||||
text=True
|
||||
)
|
||||
|
||||
assert result.returncode == 0, f"JavaScript syntax error: {result.stderr}"
|
||||
|
||||
finally:
|
||||
Path(temp_js_path).unlink()
|
||||
|
||||
def test_edit_mode_contains_required_functions(self):
|
||||
"""Test that edit mode HTML contains all required JavaScript functions."""
|
||||
from markitect.document_manager import DocumentManager
|
||||
|
||||
# Create a mock DocumentManager to avoid database dependency
|
||||
class MockDatabaseManager:
|
||||
pass
|
||||
|
||||
doc_manager = DocumentManager.__new__(DocumentManager)
|
||||
doc_manager.database_manager = MockDatabaseManager()
|
||||
|
||||
html_content = doc_manager._generate_html_template(
|
||||
title="Test",
|
||||
markdown_content="# Test",
|
||||
edit_mode=True
|
||||
)
|
||||
|
||||
# Check for critical functions that must be present
|
||||
required_functions = [
|
||||
'MarkitectEditor',
|
||||
'updateStatus',
|
||||
'reportEditModeError',
|
||||
'makeContentEditable',
|
||||
'handleSectionClick',
|
||||
'editSection'
|
||||
]
|
||||
|
||||
for func_name in required_functions:
|
||||
assert func_name in html_content, f"Required function '{func_name}' not found in edit mode HTML"
|
||||
|
||||
def test_edit_mode_no_broken_string_literals(self):
|
||||
"""Test that there are no broken string literals in the generated JavaScript."""
|
||||
from markitect.document_manager import DocumentManager
|
||||
|
||||
# Create a mock DocumentManager to avoid database dependency
|
||||
class MockDatabaseManager:
|
||||
pass
|
||||
|
||||
doc_manager = DocumentManager.__new__(DocumentManager)
|
||||
doc_manager.database_manager = MockDatabaseManager()
|
||||
|
||||
html_content = doc_manager._generate_html_template(
|
||||
title="Test",
|
||||
markdown_content="# Test",
|
||||
edit_mode=True
|
||||
)
|
||||
|
||||
# Extract JavaScript
|
||||
js_match = re.search(r'<script>(.*?)</script>', html_content, re.DOTALL)
|
||||
js_content = js_match.group(1)
|
||||
|
||||
# Check for broken string patterns that caused the original bug
|
||||
broken_patterns = [
|
||||
r"'\s*\n\s*'", # Broken string literal across lines
|
||||
r'"\s*\n\s*"', # Broken string literal across lines
|
||||
r'reconstructed \+= .*\'\n', # Unescaped newline in string
|
||||
]
|
||||
|
||||
for pattern in broken_patterns:
|
||||
matches = re.findall(pattern, js_content)
|
||||
assert not matches, f"Found broken string pattern: {pattern} - matches: {matches}"
|
||||
|
||||
def test_edit_mode_proper_brace_escaping(self):
|
||||
"""Test that braces are properly escaped in f-string templates."""
|
||||
from markitect.document_manager import DocumentManager
|
||||
|
||||
# Create a mock DocumentManager to avoid database dependency
|
||||
class MockDatabaseManager:
|
||||
pass
|
||||
|
||||
doc_manager = DocumentManager.__new__(DocumentManager)
|
||||
doc_manager.database_manager = MockDatabaseManager()
|
||||
|
||||
html_content = doc_manager._generate_html_template(
|
||||
title="Test",
|
||||
markdown_content="# Test",
|
||||
edit_mode=True
|
||||
)
|
||||
|
||||
# Extract JavaScript
|
||||
js_match = re.search(r'<script>(.*?)</script>', html_content, re.DOTALL)
|
||||
js_content = js_match.group(1)
|
||||
|
||||
# Check for inconsistent brace patterns
|
||||
inconsistent_patterns = [
|
||||
r'(?<!})} else if.*{{', # Single brace followed by double (incorrect)
|
||||
r'}} else if.*}(?!})', # Double brace followed by single closing (incorrect)
|
||||
]
|
||||
|
||||
for pattern in inconsistent_patterns:
|
||||
matches = re.findall(pattern, js_content)
|
||||
assert not matches, f"Found inconsistent brace pattern: {pattern}"
|
||||
|
||||
def test_edit_mode_template_literal_syntax(self):
|
||||
"""Test that template literals are properly escaped."""
|
||||
from markitect.document_manager import DocumentManager
|
||||
|
||||
# Create a mock DocumentManager to avoid database dependency
|
||||
class MockDatabaseManager:
|
||||
pass
|
||||
|
||||
doc_manager = DocumentManager.__new__(DocumentManager)
|
||||
doc_manager.database_manager = MockDatabaseManager()
|
||||
|
||||
html_content = doc_manager._generate_html_template(
|
||||
title="Test",
|
||||
markdown_content="# Test",
|
||||
edit_mode=True
|
||||
)
|
||||
|
||||
# Extract JavaScript
|
||||
js_match = re.search(r'<script>(.*?)</script>', html_content, re.DOTALL)
|
||||
js_content = js_match.group(1)
|
||||
|
||||
# Check for problematic template literal patterns
|
||||
# Should NOT find double-escaped template literals like ${{
|
||||
problematic_patterns = [
|
||||
r'\$\{\{.*?\}\}', # Double-escaped template literals
|
||||
]
|
||||
|
||||
for pattern in problematic_patterns:
|
||||
matches = re.findall(pattern, js_content)
|
||||
assert not matches, f"Found problematic template literal: {pattern}"
|
||||
|
||||
def test_edit_mode_contains_content_div(self):
|
||||
"""Test that edit mode HTML contains the markdown-content div."""
|
||||
from markitect.document_manager import DocumentManager
|
||||
|
||||
# Create a mock DocumentManager to avoid database dependency
|
||||
class MockDatabaseManager:
|
||||
pass
|
||||
|
||||
doc_manager = DocumentManager.__new__(DocumentManager)
|
||||
doc_manager.database_manager = MockDatabaseManager()
|
||||
|
||||
html_content = doc_manager._generate_html_template(
|
||||
title="Test",
|
||||
markdown_content="# Test Content",
|
||||
edit_mode=True
|
||||
)
|
||||
|
||||
# Should contain the content container
|
||||
assert 'id="markdown-content"' in html_content
|
||||
assert 'MARKITECT_EDIT_MODE = true' in html_content
|
||||
assert 'markitect-edit-mode' in html_content
|
||||
|
||||
def test_edit_mode_error_handling_elements(self):
|
||||
"""Test that edit mode includes proper error handling UI elements."""
|
||||
from markitect.document_manager import DocumentManager
|
||||
|
||||
# Create a mock DocumentManager to avoid database dependency
|
||||
class MockDatabaseManager:
|
||||
pass
|
||||
|
||||
doc_manager = DocumentManager.__new__(DocumentManager)
|
||||
doc_manager.database_manager = MockDatabaseManager()
|
||||
|
||||
html_content = doc_manager._generate_html_template(
|
||||
title="Test",
|
||||
markdown_content="# Test",
|
||||
edit_mode=True
|
||||
)
|
||||
|
||||
# Should contain error handling elements
|
||||
assert 'id="markitect-status"' in html_content
|
||||
assert 'id="status-message"' in html_content
|
||||
assert 'id="error-details"' in html_content
|
||||
assert 'reportEditModeError' in html_content
|
||||
|
||||
def test_edit_mode_vs_normal_mode_differences(self):
|
||||
"""Test that edit mode and normal mode generate different output appropriately."""
|
||||
from markitect.document_manager import DocumentManager
|
||||
|
||||
# Create a mock DocumentManager to avoid database dependency
|
||||
class MockDatabaseManager:
|
||||
pass
|
||||
|
||||
doc_manager = DocumentManager.__new__(DocumentManager)
|
||||
doc_manager.database_manager = MockDatabaseManager()
|
||||
test_content = "# Test Header\n\nTest content."
|
||||
|
||||
# Generate both modes
|
||||
normal_html = doc_manager._generate_html_template(
|
||||
title="Test",
|
||||
markdown_content=test_content,
|
||||
edit_mode=False
|
||||
)
|
||||
|
||||
edit_html = doc_manager._generate_html_template(
|
||||
title="Test",
|
||||
markdown_content=test_content,
|
||||
edit_mode=True
|
||||
)
|
||||
|
||||
# Edit mode should have additional elements
|
||||
assert len(edit_html) > len(normal_html)
|
||||
assert 'MarkitectEditor' in edit_html
|
||||
assert 'MarkitectEditor' not in normal_html
|
||||
assert 'markitect-edit-mode' in edit_html
|
||||
assert 'markitect-edit-mode' not in normal_html
|
||||
|
||||
def test_edit_mode_javascript_execution_flow(self):
|
||||
"""Test the logical flow of JavaScript execution in edit mode."""
|
||||
from markitect.document_manager import DocumentManager
|
||||
|
||||
# Create a mock DocumentManager to avoid database dependency
|
||||
class MockDatabaseManager:
|
||||
pass
|
||||
|
||||
doc_manager = DocumentManager.__new__(DocumentManager)
|
||||
doc_manager.database_manager = MockDatabaseManager()
|
||||
|
||||
html_content = doc_manager._generate_html_template(
|
||||
title="Test",
|
||||
markdown_content="# Test",
|
||||
edit_mode=True
|
||||
)
|
||||
|
||||
# Extract JavaScript
|
||||
js_match = re.search(r'<script>(.*?)</script>', html_content, re.DOTALL)
|
||||
js_content = js_match.group(1)
|
||||
|
||||
# Check for proper execution flow elements
|
||||
flow_elements = [
|
||||
'DOMContentLoaded', # Event listener setup
|
||||
'MARKITECT_EDIT_MODE', # Mode check
|
||||
'new MarkitectEditor', # Editor instantiation
|
||||
'makeContentEditable', # Content enhancement
|
||||
'handleSectionClick' # Interaction handler
|
||||
]
|
||||
|
||||
for element in flow_elements:
|
||||
assert element in js_content, f"Missing execution flow element: {element}"
|
||||
|
||||
def test_newline_escaping_in_javascript_strings(self):
|
||||
"""Test that newlines in JavaScript strings are properly escaped."""
|
||||
from markitect.document_manager import DocumentManager
|
||||
|
||||
# Create a mock DocumentManager to avoid database dependency
|
||||
class MockDatabaseManager:
|
||||
pass
|
||||
|
||||
doc_manager = DocumentManager.__new__(DocumentManager)
|
||||
doc_manager.database_manager = MockDatabaseManager()
|
||||
|
||||
html_content = doc_manager._generate_html_template(
|
||||
title="Test",
|
||||
markdown_content="# Test\n\nMultiple\nLines",
|
||||
edit_mode=True
|
||||
)
|
||||
|
||||
# Extract JavaScript
|
||||
js_match = re.search(r'<script>(.*?)</script>', html_content, re.DOTALL)
|
||||
js_content = js_match.group(1)
|
||||
|
||||
# Look for the specific section that was broken
|
||||
# Should find properly escaped newlines like '\\n\\n' in the JavaScript
|
||||
assert '\\n\\n' in js_content, "Newlines not properly escaped in JavaScript strings"
|
||||
|
||||
# Should NOT find unescaped newlines in string contexts
|
||||
# This regex looks for string concatenation with actual newlines
|
||||
broken_newline_pattern = r"'\s*\+\s*text\s*\+\s*'\s*\n"
|
||||
matches = re.findall(broken_newline_pattern, js_content)
|
||||
assert not matches, f"Found unescaped newlines in string concatenation: {matches}"
|
||||
|
||||
|
||||
class TestEditModeIntegration:
|
||||
"""Integration tests for the complete edit mode functionality."""
|
||||
|
||||
def test_save_functionality_javascript_presence(self):
|
||||
"""Test that the save functionality JavaScript is properly included."""
|
||||
from markitect.document_manager import DocumentManager
|
||||
|
||||
# Create a mock DocumentManager to avoid database dependency
|
||||
class MockDatabaseManager:
|
||||
pass
|
||||
|
||||
doc_manager = DocumentManager.__new__(DocumentManager)
|
||||
doc_manager.database_manager = MockDatabaseManager()
|
||||
|
||||
html_content = doc_manager._generate_html_template(
|
||||
title="Test",
|
||||
markdown_content="# Test Content",
|
||||
edit_mode=True
|
||||
)
|
||||
|
||||
# Check for save-related functionality
|
||||
save_elements = [
|
||||
'Save & Download', # Button text
|
||||
'markitectEditor.save()', # Save function call
|
||||
'getMarkdownContent', # Content extraction
|
||||
'Blob', # File creation
|
||||
'download' # Download attribute
|
||||
]
|
||||
|
||||
for element in save_elements:
|
||||
assert element in html_content, f"Save functionality element missing: {element}"
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
pytest.main([__file__, "-v"])
|
||||
292
tools/capability_discovery.py
Executable file
292
tools/capability_discovery.py
Executable file
@@ -0,0 +1,292 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Capability Discovery Tool
|
||||
|
||||
Provides automated discovery and validation of included capabilities
|
||||
to prevent code duplication and ensure proper capability usage.
|
||||
"""
|
||||
|
||||
import os
|
||||
import json
|
||||
import subprocess
|
||||
from pathlib import Path
|
||||
from typing import Dict, List, Optional, Tuple
|
||||
|
||||
|
||||
class CapabilityDiscovery:
|
||||
"""Tool for discovering and validating included capabilities."""
|
||||
|
||||
def __init__(self, project_root: str = "."):
|
||||
self.project_root = Path(project_root).resolve()
|
||||
self.capabilities = {}
|
||||
self._discover_capabilities()
|
||||
|
||||
def _discover_capabilities(self):
|
||||
"""Discover all available capabilities."""
|
||||
# Submodule capabilities
|
||||
self._discover_submodules()
|
||||
|
||||
# Local capabilities
|
||||
self._discover_local_capabilities()
|
||||
|
||||
# External dependencies
|
||||
self._discover_external_dependencies()
|
||||
|
||||
def _discover_submodules(self):
|
||||
"""Discover git submodule capabilities."""
|
||||
gitmodules_path = self.project_root / ".gitmodules"
|
||||
if not gitmodules_path.exists():
|
||||
return
|
||||
|
||||
with open(gitmodules_path, 'r') as f:
|
||||
content = f.read()
|
||||
|
||||
# Parse submodules
|
||||
submodules = []
|
||||
current_submodule = {}
|
||||
|
||||
for line in content.split('\n'):
|
||||
line = line.strip()
|
||||
if line.startswith('[submodule'):
|
||||
if current_submodule:
|
||||
submodules.append(current_submodule)
|
||||
current_submodule = {'name': line.split('"')[1]}
|
||||
elif '=' in line and current_submodule:
|
||||
key, value = line.split('=', 1)
|
||||
current_submodule[key.strip()] = value.strip()
|
||||
|
||||
if current_submodule:
|
||||
submodules.append(current_submodule)
|
||||
|
||||
# Add to capabilities
|
||||
for submodule in submodules:
|
||||
path = submodule.get('path', '')
|
||||
if path:
|
||||
self.capabilities[path] = {
|
||||
'type': 'submodule',
|
||||
'name': submodule['name'],
|
||||
'path': path,
|
||||
'url': submodule.get('url', ''),
|
||||
'status': self._check_submodule_status(path)
|
||||
}
|
||||
|
||||
def _discover_local_capabilities(self):
|
||||
"""Discover local capability directories."""
|
||||
capabilities_dir = self.project_root / "capabilities"
|
||||
if not capabilities_dir.exists():
|
||||
return
|
||||
|
||||
for cap_dir in capabilities_dir.iterdir():
|
||||
if cap_dir.is_dir() and not cap_dir.name.startswith('.'):
|
||||
readme_path = cap_dir / "README.md"
|
||||
self.capabilities[f"capabilities/{cap_dir.name}"] = {
|
||||
'type': 'local',
|
||||
'name': cap_dir.name,
|
||||
'path': f"capabilities/{cap_dir.name}",
|
||||
'has_readme': readme_path.exists(),
|
||||
'status': 'available'
|
||||
}
|
||||
|
||||
def _discover_external_dependencies(self):
|
||||
"""Discover external package dependencies."""
|
||||
pyproject_path = self.project_root / "pyproject.toml"
|
||||
if not pyproject_path.exists():
|
||||
return
|
||||
|
||||
# Basic parsing of dependencies (could be enhanced with toml library)
|
||||
with open(pyproject_path, 'r') as f:
|
||||
content = f.read()
|
||||
|
||||
# Extract key dependencies
|
||||
key_deps = ['click', 'pytest', 'sqlalchemy', 'requests']
|
||||
for dep in key_deps:
|
||||
if dep in content:
|
||||
self.capabilities[f"external/{dep}"] = {
|
||||
'type': 'external',
|
||||
'name': dep,
|
||||
'path': f"external/{dep}",
|
||||
'status': 'package_dependency'
|
||||
}
|
||||
|
||||
def _check_submodule_status(self, path: str) -> str:
|
||||
"""Check if submodule is properly initialized."""
|
||||
submodule_path = self.project_root / path
|
||||
|
||||
if not submodule_path.exists():
|
||||
return 'missing'
|
||||
|
||||
# Check if it's an empty directory
|
||||
if submodule_path.is_dir() and not any(submodule_path.iterdir()):
|
||||
return 'uninitialized'
|
||||
|
||||
return 'available'
|
||||
|
||||
def get_capability_info(self, name: str) -> Optional[Dict]:
|
||||
"""Get information about a specific capability."""
|
||||
for cap_path, info in self.capabilities.items():
|
||||
if info['name'] == name or cap_path == name:
|
||||
return info
|
||||
return None
|
||||
|
||||
def search_functionality(self, search_term: str) -> List[Tuple[str, str]]:
|
||||
"""Search for functionality across capabilities."""
|
||||
results = []
|
||||
|
||||
for cap_path, info in self.capabilities.items():
|
||||
if info['type'] == 'submodule' and info['status'] == 'available':
|
||||
results.extend(self._search_in_submodule(cap_path, search_term))
|
||||
elif info['type'] == 'local':
|
||||
results.extend(self._search_in_local_capability(cap_path, search_term))
|
||||
|
||||
return results
|
||||
|
||||
def _search_in_submodule(self, path: str, search_term: str) -> List[Tuple[str, str]]:
|
||||
"""Search for functionality in a submodule."""
|
||||
results = []
|
||||
submodule_path = self.project_root / path
|
||||
|
||||
if not submodule_path.exists():
|
||||
return results
|
||||
|
||||
# Search README files
|
||||
for readme in submodule_path.glob("**/README.md"):
|
||||
try:
|
||||
with open(readme, 'r') as f:
|
||||
content = f.read().lower()
|
||||
if search_term.lower() in content:
|
||||
results.append((path, f"README: {readme.relative_to(submodule_path)}"))
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
# Search Python files for functions/classes
|
||||
for py_file in submodule_path.glob("**/*.py"):
|
||||
try:
|
||||
with open(py_file, 'r') as f:
|
||||
content = f.read()
|
||||
if search_term in content:
|
||||
results.append((path, f"Code: {py_file.relative_to(submodule_path)}"))
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
return results
|
||||
|
||||
def _search_in_local_capability(self, path: str, search_term: str) -> List[Tuple[str, str]]:
|
||||
"""Search for functionality in a local capability."""
|
||||
results = []
|
||||
cap_path = self.project_root / path
|
||||
|
||||
if not cap_path.exists():
|
||||
return results
|
||||
|
||||
# Search Python files
|
||||
for py_file in cap_path.glob("**/*.py"):
|
||||
try:
|
||||
with open(py_file, 'r') as f:
|
||||
content = f.read()
|
||||
if search_term in content:
|
||||
results.append((path, f"Code: {py_file.relative_to(cap_path)}"))
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
return results
|
||||
|
||||
def generate_report(self) -> str:
|
||||
"""Generate a capability discovery report."""
|
||||
report = ["# Capability Discovery Report", ""]
|
||||
|
||||
# Summary
|
||||
total_caps = len(self.capabilities)
|
||||
submodules = len([c for c in self.capabilities.values() if c['type'] == 'submodule'])
|
||||
local = len([c for c in self.capabilities.values() if c['type'] == 'local'])
|
||||
external = len([c for c in self.capabilities.values() if c['type'] == 'external'])
|
||||
|
||||
report.extend([
|
||||
f"**Total Capabilities**: {total_caps}",
|
||||
f"- Submodules: {submodules}",
|
||||
f"- Local: {local}",
|
||||
f"- External: {external}",
|
||||
""
|
||||
])
|
||||
|
||||
# Details by type
|
||||
for cap_type in ['submodule', 'local', 'external']:
|
||||
caps_of_type = {k: v for k, v in self.capabilities.items() if v['type'] == cap_type}
|
||||
if caps_of_type:
|
||||
report.append(f"## {cap_type.title()} Capabilities")
|
||||
for path, info in caps_of_type.items():
|
||||
status_emoji = "✅" if info['status'] == 'available' else "❌"
|
||||
report.append(f"- {status_emoji} **{info['name']}** (`{path}`) - {info['status']}")
|
||||
report.append("")
|
||||
|
||||
return '\n'.join(report)
|
||||
|
||||
def validate_capability_usage(self, file_path: str) -> List[str]:
|
||||
"""Validate that a file properly uses existing capabilities."""
|
||||
warnings = []
|
||||
|
||||
if not Path(file_path).exists():
|
||||
return ["File not found"]
|
||||
|
||||
with open(file_path, 'r') as f:
|
||||
content = f.read()
|
||||
|
||||
# Check for potential duplication
|
||||
duplication_patterns = {
|
||||
'issue management': ['create_issue', 'list_issues', 'close_issue'],
|
||||
'content parsing': ['parse_markdown', 'extract_content', 'ContentParser'],
|
||||
'utilities': ['helper_function', 'utility_function']
|
||||
}
|
||||
|
||||
for capability, patterns in duplication_patterns.items():
|
||||
for pattern in patterns:
|
||||
if pattern in content:
|
||||
# Check if proper capability import is used
|
||||
if capability == 'issue management' and 'issue-facade' not in content:
|
||||
warnings.append(f"Potential issue management duplication: {pattern} found but no issue-facade usage")
|
||||
elif capability == 'content parsing' and 'markitect_content' not in content:
|
||||
warnings.append(f"Potential content parsing duplication: {pattern} found but no markitect-content usage")
|
||||
|
||||
return warnings
|
||||
|
||||
|
||||
def main():
|
||||
"""CLI interface for capability discovery."""
|
||||
import sys
|
||||
|
||||
discovery = CapabilityDiscovery()
|
||||
|
||||
if len(sys.argv) < 2:
|
||||
print("Usage: capability_discovery.py [report|search|validate] [args...]")
|
||||
return
|
||||
|
||||
command = sys.argv[1]
|
||||
|
||||
if command == "report":
|
||||
print(discovery.generate_report())
|
||||
|
||||
elif command == "search" and len(sys.argv) > 2:
|
||||
search_term = sys.argv[2]
|
||||
results = discovery.search_functionality(search_term)
|
||||
if results:
|
||||
print(f"Found '{search_term}' in:")
|
||||
for cap, location in results:
|
||||
print(f" - {cap}: {location}")
|
||||
else:
|
||||
print(f"No results found for '{search_term}'")
|
||||
|
||||
elif command == "validate" and len(sys.argv) > 2:
|
||||
file_path = sys.argv[2]
|
||||
warnings = discovery.validate_capability_usage(file_path)
|
||||
if warnings:
|
||||
print("Validation warnings:")
|
||||
for warning in warnings:
|
||||
print(f" ⚠️ {warning}")
|
||||
else:
|
||||
print("✅ No capability usage issues found")
|
||||
|
||||
else:
|
||||
print("Invalid command or missing arguments")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
283
tools/validate_js_syntax.py
Executable file
283
tools/validate_js_syntax.py
Executable file
@@ -0,0 +1,283 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
JavaScript syntax validation tool for MarkiTect build process.
|
||||
|
||||
This tool validates that all generated JavaScript in edit mode is syntactically correct,
|
||||
preventing the regression that caused edit mode to fail completely.
|
||||
"""
|
||||
|
||||
import subprocess
|
||||
import tempfile
|
||||
import sys
|
||||
import re
|
||||
from pathlib import Path
|
||||
from typing import List, Tuple, Optional
|
||||
|
||||
|
||||
class JavaScriptValidator:
|
||||
"""Validates JavaScript syntax in MarkiTect templates."""
|
||||
|
||||
def __init__(self):
|
||||
self.errors = []
|
||||
self.warnings = []
|
||||
|
||||
def validate_document_manager_templates(self) -> bool:
|
||||
"""Validate JavaScript templates in DocumentManager."""
|
||||
try:
|
||||
# Import the template generation method directly to avoid database dependency
|
||||
from markitect.document_manager import DocumentManager
|
||||
|
||||
# Create a mock DocumentManager to access the template method
|
||||
class MockDatabaseManager:
|
||||
pass
|
||||
|
||||
doc_manager = DocumentManager.__new__(DocumentManager)
|
||||
doc_manager.database_manager = MockDatabaseManager()
|
||||
|
||||
# Test various configurations
|
||||
test_cases = [
|
||||
{
|
||||
'title': 'Basic Edit Mode',
|
||||
'markdown': '# Test\n\nBasic content.',
|
||||
'edit_mode': True,
|
||||
'theme': 'github'
|
||||
},
|
||||
{
|
||||
'title': 'Complex Content',
|
||||
'markdown': '''# Header 1
|
||||
|
||||
## Header 2
|
||||
|
||||
Paragraph with **bold** and *italic* text.
|
||||
|
||||
- List item 1
|
||||
- List item 2
|
||||
|
||||
1. Numbered item
|
||||
2. Another item
|
||||
|
||||
> Blockquote text
|
||||
|
||||
```python
|
||||
code block
|
||||
```
|
||||
|
||||
Final paragraph.''',
|
||||
'edit_mode': True,
|
||||
'theme': 'dark'
|
||||
},
|
||||
{
|
||||
'title': 'Special Characters',
|
||||
'markdown': "# Test 'quotes' and \"double quotes\"\n\nContent with $pecial ch@racters & symbols!",
|
||||
'edit_mode': True,
|
||||
'theme': 'github'
|
||||
}
|
||||
]
|
||||
|
||||
all_valid = True
|
||||
|
||||
for test_case in test_cases:
|
||||
print(f"Validating: {test_case['title']}")
|
||||
|
||||
html_content = doc_manager._generate_html_template(
|
||||
title=test_case['title'],
|
||||
markdown_content=test_case['markdown'],
|
||||
edit_mode=test_case['edit_mode'],
|
||||
editor_theme=test_case.get('theme', 'github')
|
||||
)
|
||||
|
||||
is_valid, errors = self._validate_html_javascript(html_content, test_case['title'])
|
||||
|
||||
if not is_valid:
|
||||
all_valid = False
|
||||
self.errors.extend(errors)
|
||||
else:
|
||||
print(f" ✅ {test_case['title']} - JavaScript syntax valid")
|
||||
|
||||
return all_valid
|
||||
|
||||
except Exception as e:
|
||||
self.errors.append(f"Failed to validate document manager templates: {e}")
|
||||
return False
|
||||
|
||||
def _validate_html_javascript(self, html_content: str, context: str) -> Tuple[bool, List[str]]:
|
||||
"""Extract and validate JavaScript from HTML content."""
|
||||
errors = []
|
||||
|
||||
# Extract all JavaScript blocks
|
||||
js_blocks = re.findall(r'<script[^>]*>(.*?)</script>', html_content, re.DOTALL)
|
||||
|
||||
if not js_blocks:
|
||||
errors.append(f"{context}: No JavaScript blocks found")
|
||||
return False, errors
|
||||
|
||||
for i, js_content in enumerate(js_blocks):
|
||||
# Skip empty blocks or blocks with only external src
|
||||
if not js_content.strip() or 'src=' in js_content:
|
||||
continue
|
||||
|
||||
is_valid, js_errors = self._validate_javascript_syntax(js_content, f"{context} block {i+1}")
|
||||
if not is_valid:
|
||||
errors.extend(js_errors)
|
||||
|
||||
return len(errors) == 0, errors
|
||||
|
||||
def _validate_javascript_syntax(self, js_content: str, context: str) -> Tuple[bool, List[str]]:
|
||||
"""Validate JavaScript syntax using Node.js."""
|
||||
errors = []
|
||||
|
||||
try:
|
||||
with tempfile.NamedTemporaryFile(mode='w', suffix='.js', delete=False) as f:
|
||||
f.write(js_content)
|
||||
temp_js_path = f.name
|
||||
|
||||
# Use Node.js to check syntax
|
||||
result = subprocess.run(
|
||||
['node', '-c', temp_js_path],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=10
|
||||
)
|
||||
|
||||
if result.returncode != 0:
|
||||
errors.append(f"{context}: JavaScript syntax error - {result.stderr.strip()}")
|
||||
|
||||
# Add helpful debugging info
|
||||
lines = js_content.split('\n')
|
||||
for line_num, line in enumerate(lines[:20], 1): # Show first 20 lines
|
||||
if line.strip():
|
||||
print(f" Line {line_num}: {line[:100]}") # First 100 chars
|
||||
|
||||
Path(temp_js_path).unlink(missing_ok=True)
|
||||
|
||||
except subprocess.TimeoutExpired:
|
||||
errors.append(f"{context}: JavaScript validation timeout")
|
||||
except FileNotFoundError:
|
||||
errors.append(f"{context}: Node.js not available for validation")
|
||||
except Exception as e:
|
||||
errors.append(f"{context}: Validation error - {e}")
|
||||
|
||||
return len(errors) == 0, errors
|
||||
|
||||
def check_common_issues(self) -> bool:
|
||||
"""Check for common JavaScript issues that have caused problems."""
|
||||
try:
|
||||
from markitect.document_manager import DocumentManager
|
||||
|
||||
# Create a mock DocumentManager to access the template method
|
||||
class MockDatabaseManager:
|
||||
pass
|
||||
|
||||
doc_manager = DocumentManager.__new__(DocumentManager)
|
||||
doc_manager.database_manager = MockDatabaseManager()
|
||||
|
||||
html_content = doc_manager._generate_html_template(
|
||||
title="Issue Check",
|
||||
markdown_content="# Test\n\nTest content.",
|
||||
edit_mode=True
|
||||
)
|
||||
|
||||
js_match = re.search(r'<script>(.*?)</script>', html_content, re.DOTALL)
|
||||
if not js_match:
|
||||
self.errors.append("No JavaScript found for common issues check")
|
||||
return False
|
||||
|
||||
js_content = js_match.group(1)
|
||||
issues_found = False
|
||||
|
||||
# Check for specific issues that have caused problems
|
||||
issue_patterns = [
|
||||
(r"'\s*\n\s*'", "Broken string literal across lines"),
|
||||
(r'"\s*\n\s*"', "Broken string literal across lines"),
|
||||
(r'} else if.*{{.*}} else if.*{[^{]', "Inconsistent brace escaping"),
|
||||
(r'\$\{\{.*?\}\}', "Double-escaped template literals"),
|
||||
(r'reconstructed \+= .*\'\n', "Unescaped newline in string concatenation"),
|
||||
]
|
||||
|
||||
for pattern, description in issue_patterns:
|
||||
matches = re.findall(pattern, js_content)
|
||||
if matches:
|
||||
self.errors.append(f"Found {description}: {matches[:3]}...") # Show first 3 matches
|
||||
issues_found = True
|
||||
|
||||
# Check for required elements
|
||||
required_elements = [
|
||||
'MarkitectEditor',
|
||||
'updateStatus',
|
||||
'makeContentEditable',
|
||||
'DOMContentLoaded'
|
||||
]
|
||||
|
||||
for element in required_elements:
|
||||
if element not in js_content:
|
||||
self.errors.append(f"Missing required element: {element}")
|
||||
issues_found = True
|
||||
|
||||
return not issues_found
|
||||
|
||||
except Exception as e:
|
||||
self.errors.append(f"Failed to check common issues: {e}")
|
||||
return False
|
||||
|
||||
def validate_all(self) -> bool:
|
||||
"""Run all validation checks."""
|
||||
print("🔍 Validating JavaScript syntax in MarkiTect templates...")
|
||||
|
||||
all_checks_passed = True
|
||||
|
||||
# Run all validation checks
|
||||
checks = [
|
||||
("Document Manager Templates", self.validate_document_manager_templates),
|
||||
("Common Issues", self.check_common_issues),
|
||||
]
|
||||
|
||||
for check_name, check_func in checks:
|
||||
print(f"\n📋 Running {check_name} check...")
|
||||
try:
|
||||
if not check_func():
|
||||
all_checks_passed = False
|
||||
print(f" ❌ {check_name} check failed")
|
||||
else:
|
||||
print(f" ✅ {check_name} check passed")
|
||||
except Exception as e:
|
||||
all_checks_passed = False
|
||||
self.errors.append(f"{check_name} check failed with exception: {e}")
|
||||
print(f" ❌ {check_name} check failed with exception")
|
||||
|
||||
return all_checks_passed
|
||||
|
||||
def report_results(self) -> None:
|
||||
"""Print validation results."""
|
||||
print("\n" + "="*60)
|
||||
print("JavaScript Validation Results")
|
||||
print("="*60)
|
||||
|
||||
if self.errors:
|
||||
print(f"\n❌ {len(self.errors)} Error(s) Found:")
|
||||
for i, error in enumerate(self.errors, 1):
|
||||
print(f" {i}. {error}")
|
||||
|
||||
if self.warnings:
|
||||
print(f"\n⚠️ {len(self.warnings)} Warning(s):")
|
||||
for i, warning in enumerate(self.warnings, 1):
|
||||
print(f" {i}. {warning}")
|
||||
|
||||
if not self.errors and not self.warnings:
|
||||
print("\n✅ All JavaScript validation checks passed!")
|
||||
|
||||
print("\n" + "="*60)
|
||||
|
||||
|
||||
def main():
|
||||
"""Main validation function."""
|
||||
validator = JavaScriptValidator()
|
||||
|
||||
success = validator.validate_all()
|
||||
validator.report_results()
|
||||
|
||||
return 0 if success else 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
exit_code = main()
|
||||
sys.exit(exit_code)
|
||||
Reference in New Issue
Block a user