Compare commits
18 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| ff6b807f3b | |||
| 6447c617fd | |||
| 5337b26d5e | |||
| 87e970bbee | |||
| eced5cbae4 | |||
| 6e60e5f13d | |||
| 93655512d0 | |||
| 74ee2760e2 | |||
| aefece1fe7 | |||
| ce7ce0470f | |||
| 6df6430b72 | |||
| ed27dee5a0 | |||
| 49724d2ae5 | |||
| 25a38322c0 | |||
| 3a53e0aa58 | |||
| 64d1606740 | |||
| 1022e2597f | |||
| 50170f75df |
430
CAPABILITIES.md
430
CAPABILITIES.md
@@ -1,430 +0,0 @@
|
||||
# MarkiTect Internal Capabilities Inventory
|
||||
|
||||
> **Comprehensive overview of all capabilities PROVIDED BY MarkiTect - what this repository offers to the world**
|
||||
|
||||
## Overview
|
||||
|
||||
This document catalogs all **internal capabilities** that MarkiTect provides - the functionality that this repository offers to users and other projects. These are capabilities that MarkiTect **provides**, not **uses**.
|
||||
|
||||
- **Total Internal 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 to external, 11 candidates identified for extraction
|
||||
|
||||
> **Note**: For capabilities that MarkiTect **uses** (external dependencies), see `CAPABILITY_REGISTRY.md`. For complete architecture understanding, see `CAPABILITY_INCLUSION_GUIDE.md`.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 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.*
|
||||
@@ -1,127 +0,0 @@
|
||||
# Capability Documentation Index
|
||||
|
||||
> **Master index to all capability-related documentation in MarkiTect**
|
||||
|
||||
## 📋 **Quick Navigation**
|
||||
|
||||
| Document | Purpose | Scope |
|
||||
|----------|---------|-------|
|
||||
| **[CAPABILITIES.md](CAPABILITIES.md)** | **Internal Capabilities** | What MarkiTect **provides** to the world |
|
||||
| **[CAPABILITY_REGISTRY.md](CAPABILITY_REGISTRY.md)** | **External Capabilities** | What MarkiTect **uses** from others |
|
||||
| **[CLAUDE_CAPABILITY_REFERENCE.md](CLAUDE_CAPABILITY_REFERENCE.md)** | **Quick Reference** | Prevent duplication, guide usage |
|
||||
| **[CAPABILITY_INCLUSION_GUIDE.md](CAPABILITY_INCLUSION_GUIDE.md)** | **Architecture Guide** | Complete workflow and patterns |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **When to Use Which Document**
|
||||
|
||||
### I want to understand what MarkiTect can do
|
||||
→ **Read**: [CAPABILITIES.md](CAPABILITIES.md)
|
||||
- 73+ internal capabilities provided by MarkiTect
|
||||
- Core processing, CLI, templates, caching, validation
|
||||
- Extraction candidates and recommendations
|
||||
|
||||
### I want to see what MarkiTect depends on
|
||||
→ **Read**: [CAPABILITY_REGISTRY.md](CAPABILITY_REGISTRY.md)
|
||||
- External capabilities: submodules, local, packages
|
||||
- Issue management (issue-facade), documentation (wiki)
|
||||
- Content processing, utilities, dependencies
|
||||
|
||||
### I'm implementing something and want to avoid duplication
|
||||
→ **Read**: [CLAUDE_CAPABILITY_REFERENCE.md](CLAUDE_CAPABILITY_REFERENCE.md)
|
||||
- Quick lookup patterns
|
||||
- "Use X for Y" guidance
|
||||
- Anti-duplication rules
|
||||
|
||||
### I want to understand the capability architecture
|
||||
→ **Read**: [CAPABILITY_INCLUSION_GUIDE.md](CAPABILITY_INCLUSION_GUIDE.md)
|
||||
- Internal vs external organization
|
||||
- Inclusion workflow and patterns
|
||||
- Management operations and best practices
|
||||
|
||||
---
|
||||
|
||||
## 🔍 **Discovery and Management Tools**
|
||||
|
||||
### Command-Line Tools
|
||||
```bash
|
||||
# Generate capability report
|
||||
make capability-report
|
||||
|
||||
# Search for existing functionality
|
||||
make capability-search TERM=issue_management
|
||||
|
||||
# Validate proper capability usage
|
||||
make capability-validate FILE=my_code.py
|
||||
```
|
||||
|
||||
### Programmatic Discovery
|
||||
```bash
|
||||
# Run capability discovery tool directly
|
||||
python tools/capability_discovery.py report
|
||||
python tools/capability_discovery.py search "function_name"
|
||||
python tools/capability_discovery.py validate "file_path"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ **Capability Architecture Overview**
|
||||
|
||||
```
|
||||
MarkiTect Repository
|
||||
├── [Internal Capabilities] # CAPABILITIES.md
|
||||
│ ├── markitect/database/ # Database operations
|
||||
│ ├── markitect/template/ # Template processing
|
||||
│ ├── markitect/cli/ # CLI framework
|
||||
│ └── ... (70+ more) # Core MarkiTect functionality
|
||||
│
|
||||
└── [External Capabilities] # CAPABILITY_REGISTRY.md
|
||||
├── issue-facade/ # Submodule: Issue tracking
|
||||
├── wiki/ # Submodule: Documentation
|
||||
├── capabilities/ # Local extracted capabilities
|
||||
│ ├── markitect-content/ # Content processing
|
||||
│ └── markitect-utils/ # Utility functions
|
||||
└── [Package Dependencies] # click, pytest, etc.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 **Current Status Summary**
|
||||
|
||||
### Internal Capabilities (PROVIDED BY MarkiTect)
|
||||
- **Total**: 73+ documented capabilities
|
||||
- **Categories**: Core processing, CLI, templates, validation, export/import
|
||||
- **Test Coverage**: 348 tests across 27 test files
|
||||
- **Extraction Pipeline**: 2 extracted, 11 candidates identified
|
||||
|
||||
### External Capabilities (USED BY MarkiTect)
|
||||
- **Submodules**: 2 (issue-facade, wiki)
|
||||
- **Local**: 2 (markitect-content, markitect-utils)
|
||||
- **Packages**: Multiple (click, pytest, sqlalchemy, etc.)
|
||||
- **Management**: Automated discovery and validation tools
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **Best Practices Quick Reference**
|
||||
|
||||
### For Developers
|
||||
1. **Check External First**: Always consult `CAPABILITY_REGISTRY.md` before implementing
|
||||
2. **Use Discovery Tools**: `make capability-search` before coding
|
||||
3. **Follow Patterns**: Use established integration patterns
|
||||
4. **Update Documentation**: Keep registries current
|
||||
|
||||
### For Claude
|
||||
1. **Registry First**: Check `CAPABILITY_REGISTRY.md` before any implementation
|
||||
2. **Quick Lookup**: Use `CLAUDE_CAPABILITY_REFERENCE.md` for instant guidance
|
||||
3. **Respect Boundaries**: Don't duplicate external capability functionality
|
||||
4. **Discovery Commands**: Use `make capability-search TERM=xyz` to find existing
|
||||
|
||||
### For Architecture
|
||||
1. **Clear Separation**: Internal (provides) vs External (uses)
|
||||
2. **Extraction Pipeline**: Internal → Local → Submodule → Package
|
||||
3. **Documentation**: Keep all four documents synchronized
|
||||
4. **Validation**: Regular checks for duplication and proper usage
|
||||
|
||||
---
|
||||
|
||||
**💡 Remember**: This index helps you navigate the capability ecosystem efficiently. Start here to find the right documentation for your needs!
|
||||
@@ -1,267 +0,0 @@
|
||||
# Capability Inclusion Guide
|
||||
|
||||
> **Complete guide to understanding and managing capability inclusion in the MarkiTect project**
|
||||
|
||||
## Overview
|
||||
|
||||
MarkiTect uses a **Capability Inclusion Pattern** where functionality is organized into distinct capabilities that can be:
|
||||
- **Internal**: Provided by this repository (core MarkiTect functionality)
|
||||
- **External**: Used by this repository (submodules, dependencies, extracted capabilities)
|
||||
|
||||
This approach enables clear separation of concerns, easy extension/bugfixing, and prevents code duplication.
|
||||
|
||||
---
|
||||
|
||||
## 📋 **Documentation Structure**
|
||||
|
||||
### Core Documentation Files
|
||||
|
||||
1. **`CAPABILITIES.md`** - **Internal Capability Inventory**
|
||||
- **Purpose**: Comprehensive analysis of all capabilities provided BY this repository
|
||||
- **Content**: 73+ internal capabilities, test coverage, extraction recommendations
|
||||
- **Scope**: What MarkiTect provides to the world
|
||||
|
||||
2. **`CAPABILITY_REGISTRY.md`** - **External Capability Registry**
|
||||
- **Purpose**: Registry of all capabilities USED BY this repository
|
||||
- **Content**: Submodules, local extracted capabilities, external dependencies
|
||||
- **Scope**: What MarkiTect consumes from other sources
|
||||
|
||||
3. **`CLAUDE_CAPABILITY_REFERENCE.md`** - **Quick Usage Reference**
|
||||
- **Purpose**: Prevent code duplication by guiding Claude to existing capabilities
|
||||
- **Content**: Quick lookup patterns and anti-duplication rules
|
||||
- **Scope**: Operational guidance for development
|
||||
|
||||
4. **`CAPABILITY_INCLUSION_GUIDE.md`** - **This Document**
|
||||
- **Purpose**: Explains the overall capability inclusion architecture
|
||||
- **Content**: Workflow, patterns, internal vs external organization
|
||||
- **Scope**: Architectural understanding and management
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ **Capability Organization Architecture**
|
||||
|
||||
### Internal Capabilities (Provided BY MarkiTect)
|
||||
|
||||
**Location**: Throughout the main codebase
|
||||
**Purpose**: Core functionality that MarkiTect provides to the world
|
||||
**Management**: Documented in `CAPABILITIES.md`
|
||||
|
||||
#### Categories:
|
||||
- **Core Processing**: AST-based markdown processing, database operations
|
||||
- **CLI Commands**: Command-line interface functionality
|
||||
- **Template Engine**: Document template processing
|
||||
- **Caching System**: Multi-layer performance caching
|
||||
- **Schema Validation**: Document structure validation
|
||||
- **Export/Import**: Data transformation capabilities
|
||||
|
||||
#### Extraction Candidates:
|
||||
- Capabilities that could be useful to other projects
|
||||
- Self-contained functionality with clear boundaries
|
||||
- Well-tested components (>80% coverage preferred)
|
||||
|
||||
**Example Internal Capability:**
|
||||
```
|
||||
markitect/database/ # Database operations capability
|
||||
markitect/template/ # Template processing capability
|
||||
markitect/cli/ # CLI framework capability
|
||||
```
|
||||
|
||||
### External Capabilities (Used BY MarkiTect)
|
||||
|
||||
**Location**: Various inclusion patterns
|
||||
**Purpose**: Functionality MarkiTect depends on from external sources
|
||||
**Management**: Documented in `CAPABILITY_REGISTRY.md`
|
||||
|
||||
#### 1. **Submodule Capabilities** (Independent Repositories)
|
||||
- **Pattern**: Git submodules pointing to external repositories
|
||||
- **Benefits**: Independent versioning, separate development, easy updates
|
||||
- **Examples**: `capabilities/issue-facade/`, `wiki/`
|
||||
|
||||
#### 2. **Local Extracted Capabilities** (Previously Internal, Now Separated)
|
||||
- **Pattern**: Moved to `capabilities/` directory but still in this repo
|
||||
- **Benefits**: Clear separation, preparation for future extraction
|
||||
- **Examples**: `capabilities/markitect-content/`, `capabilities/markitect-utils/`
|
||||
|
||||
#### 3. **Package Dependencies** (Third-Party Libraries)
|
||||
- **Pattern**: Standard pip dependencies in `pyproject.toml`
|
||||
- **Benefits**: Mature, maintained, standard integration
|
||||
- **Examples**: `click`, `pytest`, `sqlalchemy`
|
||||
|
||||
---
|
||||
|
||||
## 🔄 **Capability Inclusion Workflow**
|
||||
|
||||
### Phase 1: Internal Development
|
||||
```
|
||||
Developer creates functionality → Internal capability (in main codebase)
|
||||
```
|
||||
|
||||
### Phase 2: Extraction Evaluation
|
||||
```
|
||||
Capability matures → Evaluate extraction criteria → Decide extraction pattern
|
||||
```
|
||||
|
||||
### Phase 3: Capability Inclusion
|
||||
```
|
||||
Extract capability → Choose inclusion pattern → Update registries
|
||||
```
|
||||
|
||||
### Inclusion Pattern Decision Tree:
|
||||
|
||||
1. **Will other projects use this capability?**
|
||||
- **Yes** → Consider **Submodule Capability** (extract to separate repo)
|
||||
- **No** → Consider **Local Capability** (move to `capabilities/`)
|
||||
|
||||
2. **Does it need independent versioning/development?**
|
||||
- **Yes** → **Submodule Capability**
|
||||
- **No** → **Local Capability**
|
||||
|
||||
3. **Is it a mature third-party solution?**
|
||||
- **Yes** → **Package Dependency**
|
||||
- **No** → Custom solution needed
|
||||
|
||||
### Example Extraction Journey:
|
||||
```
|
||||
Internal → markitect/issues/ (internal issue management)
|
||||
Evaluation → Self-contained, reusable, independent development needed
|
||||
Extraction → coulomb/issue-facade (separate repository)
|
||||
Inclusion → capabilities/issue-facade/ (submodule capability)
|
||||
Registration → CAPABILITY_REGISTRY.md updated
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 **Current Capability Landscape**
|
||||
|
||||
### Internal Capabilities (73+ documented in CAPABILITIES.md)
|
||||
```
|
||||
markitect/ # Core repository
|
||||
├── database/ # Database operations
|
||||
├── template/ # Template processing
|
||||
├── cli/ # CLI framework
|
||||
├── packaging/ # Document packaging
|
||||
├── finance/ # Cost tracking
|
||||
└── [... 68+ more capabilities]
|
||||
```
|
||||
|
||||
### External Capabilities (5 documented in CAPABILITY_REGISTRY.md)
|
||||
```
|
||||
capabilities/
|
||||
├── issue-facade/ # Submodule: Universal issue tracking
|
||||
├── kaizen-agentic/ # Submodule: AI agent framework
|
||||
├── markitect-content/ # Local: Content processing
|
||||
└── markitect-utils/ # Local: Utility functions
|
||||
wiki/ # Submodule: Documentation
|
||||
[External dependencies: click, pytest, sqlalchemy, ...]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ **Management Operations**
|
||||
|
||||
### Discovery and Validation
|
||||
```bash
|
||||
# Discover all external capabilities
|
||||
make capability-report
|
||||
|
||||
# Search for existing functionality
|
||||
make capability-search TERM=issue_management
|
||||
|
||||
# Validate proper usage
|
||||
make capability-validate FILE=my_code.py
|
||||
```
|
||||
|
||||
### Adding New External Capabilities
|
||||
|
||||
#### Submodule Capability:
|
||||
```bash
|
||||
git submodule add <repo-url> <local-path>
|
||||
# Update CAPABILITY_REGISTRY.md
|
||||
```
|
||||
|
||||
#### Local Capability:
|
||||
```bash
|
||||
mkdir capabilities/new-capability
|
||||
# Move code, create README.md
|
||||
# Update CAPABILITY_REGISTRY.md
|
||||
```
|
||||
|
||||
#### Package Dependency:
|
||||
```bash
|
||||
# Update pyproject.toml
|
||||
# Update CAPABILITY_REGISTRY.md
|
||||
```
|
||||
|
||||
### Updating Capabilities
|
||||
|
||||
#### Submodules:
|
||||
```bash
|
||||
git submodule update --remote <submodule-path>
|
||||
```
|
||||
|
||||
#### Local Capabilities:
|
||||
```bash
|
||||
# Direct code updates in capabilities/
|
||||
```
|
||||
|
||||
#### Package Dependencies:
|
||||
```bash
|
||||
pip install --upgrade <package>
|
||||
# Update pyproject.toml version constraints
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **Best Practices**
|
||||
|
||||
### For Internal Capabilities (CAPABILITIES.md):
|
||||
- **Document thoroughly**: Clear description, interfaces, test coverage
|
||||
- **Evaluate extraction**: Regular review against extraction criteria
|
||||
- **Maintain quality**: Adequate test coverage, clear boundaries
|
||||
- **Consider reusability**: Could other projects benefit from this?
|
||||
|
||||
### For External Capabilities (CAPABILITY_REGISTRY.md):
|
||||
- **Registry first**: Always check before implementing new functionality
|
||||
- **Respect interfaces**: Use documented APIs, don't bypass capabilities
|
||||
- **Update documentation**: Keep registry current with capability changes
|
||||
- **Clear boundaries**: Don't duplicate external capability functionality
|
||||
|
||||
### For Claude and Developers:
|
||||
- **Check before code**: Always consult `CAPABILITY_REGISTRY.md` first
|
||||
- **Use discovery tools**: `make capability-search` before implementing
|
||||
- **Follow patterns**: Use established integration patterns
|
||||
- **Update registries**: Document new capabilities immediately
|
||||
|
||||
---
|
||||
|
||||
## 🔮 **Future Evolution**
|
||||
|
||||
### Extraction Pipeline:
|
||||
```
|
||||
Internal Capability → Evaluation → Local Capability → Submodule Capability
|
||||
```
|
||||
|
||||
### Maturity Progression:
|
||||
1. **Internal**: New functionality developed in main codebase
|
||||
2. **Local**: Stable functionality moved to `capabilities/` for separation
|
||||
3. **Submodule**: Mature functionality extracted to independent repository
|
||||
4. **Package**: Published capabilities available via pip/pypi
|
||||
|
||||
### Success Metrics:
|
||||
- **Zero duplication**: No accidental reimplementation of existing capabilities
|
||||
- **Clear boundaries**: Well-defined interfaces between internal and external
|
||||
- **Easy extension**: Simple to enhance or fix external capabilities
|
||||
- **Efficient discovery**: Fast identification of existing functionality
|
||||
|
||||
---
|
||||
|
||||
## 📚 **Quick Reference**
|
||||
|
||||
| Need | Check | Use |
|
||||
|------|--------|-----|
|
||||
| Internal MarkiTect functionality | `CAPABILITIES.md` | Import from main codebase |
|
||||
| External functionality | `CAPABILITY_REGISTRY.md` | Use documented interface |
|
||||
| Prevent duplication | `CLAUDE_CAPABILITY_REFERENCE.md` | Follow anti-duplication rules |
|
||||
| Understand architecture | `CAPABILITY_INCLUSION_GUIDE.md` | This document |
|
||||
|
||||
**Remember**: Internal capabilities are what MarkiTect **provides**, external capabilities are what MarkiTect **uses**.
|
||||
@@ -1,219 +0,0 @@
|
||||
# MarkiTect External Capability Registry
|
||||
|
||||
> **Registry of all capabilities USED BY MarkiTect (external dependencies, submodules, extracted components)**
|
||||
|
||||
## Overview
|
||||
|
||||
This registry documents all **external capabilities** that MarkiTect depends on - functionality that MarkiTect **uses** rather than **provides**. This includes git submodules, extracted local capabilities, and package dependencies.
|
||||
|
||||
> **Note**: For capabilities that MarkiTect **provides** to the world, see `CAPABILITIES.md`. For complete architecture understanding, see `CAPABILITY_INCLUSION_GUIDE.md`.
|
||||
|
||||
## Capability Inclusion Patterns
|
||||
|
||||
### 1. **Submodule Capabilities** (External Repositories)
|
||||
Full repositories included as git submodules for independent development and versioning.
|
||||
|
||||
### 2. **Local Capabilities** (Extracted Components)
|
||||
Self-contained capabilities extracted from the main codebase but maintained locally.
|
||||
|
||||
### 3. **External Dependencies** (Package Dependencies)
|
||||
Third-party packages providing specific capabilities via pip/pypi.
|
||||
|
||||
---
|
||||
|
||||
## 🔍 **ACTIVE CAPABILITIES REGISTRY**
|
||||
|
||||
### Universal Issue Management
|
||||
- **Type**: Submodule Capability
|
||||
- **Location**: `capabilities/issue-facade/`
|
||||
- **Repository**: `coulomb/issue-facade`
|
||||
- **Purpose**: Backend-agnostic issue tracking with unified CLI
|
||||
- **Interfaces**:
|
||||
- CLI: `cd capabilities/issue-facade && python -m cli.main [command]`
|
||||
- API: Core models, backends (local SQLite, Gitea, GitHub, GitLab)
|
||||
- **Usage Guidelines**:
|
||||
- ✅ **USE**: For all issue management tasks
|
||||
- ❌ **DON'T**: Implement custom issue tracking, duplicate CLI commands
|
||||
- 🔧 **Integration**: Reference submodule for issue operations
|
||||
|
||||
### Kaizen-Agentic Framework
|
||||
- **Type**: Submodule Capability
|
||||
- **Location**: `capabilities/kaizen-agentic/`
|
||||
- **Repository**: `coulomb/kaizen-agentic`
|
||||
- **Purpose**: Advanced AI agent framework for autonomous development workflows
|
||||
- **Interfaces**:
|
||||
- CLI: `cd capabilities/kaizen-agentic && make [command]`
|
||||
- Framework: Agent definitions, workflow automation, development patterns
|
||||
- **Usage Guidelines**:
|
||||
- ✅ **USE**: For AI agent definitions and autonomous workflows
|
||||
- ❌ **DON'T**: Implement custom agent frameworks, duplicate AI patterns
|
||||
- 🔧 **Integration**: Reference framework for agent-driven development
|
||||
|
||||
### Content Processing Capability
|
||||
- **Type**: Local Capability
|
||||
- **Location**: `capabilities/markitect-content/`
|
||||
- **Purpose**: MarkdownMatters content parsing without frontmatter/tailmatter
|
||||
- **Interfaces**:
|
||||
- `ContentParser` class for content extraction
|
||||
- `ContentStats` for document statistics
|
||||
- CLI commands for content operations
|
||||
- **Usage Guidelines**:
|
||||
- ✅ **USE**: For content extraction and analysis
|
||||
- ❌ **DON'T**: Reimplement markdown content parsing
|
||||
- 🔧 **Integration**: Import from `capabilities.markitect_content`
|
||||
|
||||
### Utility Functions Capability
|
||||
- **Type**: Local Capability
|
||||
- **Location**: `capabilities/markitect-utils/`
|
||||
- **Purpose**: Common utility functions and helpers
|
||||
- **Interfaces**: Shared utilities and helper functions
|
||||
- **Usage Guidelines**:
|
||||
- ✅ **USE**: For common operations and utilities
|
||||
- ❌ **DON'T**: Duplicate utility functions
|
||||
- 🔧 **Integration**: Import from `capabilities.markitect_utils`
|
||||
|
||||
### Documentation and Knowledge Base
|
||||
- **Type**: Submodule Capability
|
||||
- **Location**: `wiki/`
|
||||
- **Repository**: `coulomb/markitect_project.wiki`
|
||||
- **Purpose**: Comprehensive project documentation and knowledge base
|
||||
- **Interfaces**: Markdown documentation files
|
||||
- **Usage Guidelines**:
|
||||
- ✅ **USE**: For project documentation, architectural decisions
|
||||
- ❌ **DON'T**: Create duplicate documentation
|
||||
- 🔧 **Integration**: Reference wiki for authoritative documentation
|
||||
|
||||
---
|
||||
|
||||
## 🚫 **CAPABILITY CONFLICT PREVENTION**
|
||||
|
||||
### Before Implementing New Functionality:
|
||||
|
||||
1. **Check This Registry**: Verify no existing capability provides the functionality
|
||||
2. **Search Submodules**: Check `issue-facade/`, `wiki/` for existing solutions
|
||||
3. **Check Local Capabilities**: Review `capabilities/` directory
|
||||
4. **Consult Documentation**: Check capability READMEs for interface details
|
||||
|
||||
### Implementation Guidelines:
|
||||
|
||||
- **Extend, Don't Duplicate**: If functionality exists, extend or interface with it
|
||||
- **Clear Boundaries**: New code should complement, not replace, existing capabilities
|
||||
- **Interface Respect**: Use documented interfaces rather than reimplementing
|
||||
- **Separation of Concerns**: Maintain clear boundaries between core MarkiTect and capabilities
|
||||
|
||||
---
|
||||
|
||||
## 🔧 **INTEGRATION PATTERNS**
|
||||
|
||||
### Submodule Integration
|
||||
```bash
|
||||
# Issue management
|
||||
cd capabilities/issue-facade && python -m cli.main list
|
||||
|
||||
# AI agent framework
|
||||
cd capabilities/kaizen-agentic && make [command]
|
||||
|
||||
# Documentation updates
|
||||
cd wiki && git pull origin main
|
||||
```
|
||||
|
||||
### Local Capability Integration
|
||||
```python
|
||||
# Content processing
|
||||
from capabilities.markitect_content import ContentParser
|
||||
parser = ContentParser()
|
||||
|
||||
# Utilities
|
||||
from capabilities.markitect_utils import helper_function
|
||||
```
|
||||
|
||||
### External Dependency Integration
|
||||
```python
|
||||
# Standard package imports
|
||||
import click # CLI framework
|
||||
import pytest # Testing framework
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 **CLAUDE USAGE GUIDELINES**
|
||||
|
||||
### When Asked to Implement Functionality:
|
||||
|
||||
1. **First**: Check this registry for existing capabilities
|
||||
2. **If Exists**: Use/extend the existing capability rather than reimplementing
|
||||
3. **If Missing**: Implement new functionality with clear separation from existing capabilities
|
||||
4. **Document**: Update this registry when adding new capabilities
|
||||
|
||||
### Capability Respect Rules:
|
||||
|
||||
- **Issue Management**: Always use `issue-facade` submodule, never implement custom issue tracking
|
||||
- **Content Processing**: Use `markitect-content` capability for MarkdownMatters parsing
|
||||
- **Documentation**: Reference `wiki` submodule for authoritative project information
|
||||
- **Utilities**: Check `markitect-utils` before creating new utility functions
|
||||
|
||||
### Integration Commands:
|
||||
- **Issue Operations**: `cd capabilities/issue-facade && python -m cli.main [command]`
|
||||
- **AI Agent Framework**: `cd capabilities/kaizen-agentic && make [command]`
|
||||
- **Content Analysis**: Import from `capabilities.markitect_content`
|
||||
- **Utility Functions**: Import from `capabilities.markitect_utils`
|
||||
- **Documentation**: Reference files in `wiki/`
|
||||
|
||||
---
|
||||
|
||||
## 🔄 **CAPABILITY LIFECYCLE MANAGEMENT**
|
||||
|
||||
### Adding New Capabilities
|
||||
|
||||
1. **Evaluate**: Does this warrant capability extraction?
|
||||
2. **Choose Pattern**: Submodule (external repo) vs Local capability vs External dependency
|
||||
3. **Implement**: Follow capability inclusion patterns
|
||||
4. **Document**: Update this registry with interface details
|
||||
5. **Update Agents**: Inform specialized agents of new capability
|
||||
|
||||
### Updating Existing Capabilities
|
||||
|
||||
1. **Submodules**: Update submodule reference (`git submodule update`)
|
||||
2. **Local Capabilities**: Update local code and interfaces
|
||||
3. **External Dependencies**: Update package versions in `pyproject.toml`
|
||||
4. **Registry**: Update interface documentation if changed
|
||||
|
||||
### Removing Capabilities
|
||||
|
||||
1. **Deprecation Notice**: Document deprecation timeline
|
||||
2. **Migration Path**: Provide alternative solutions
|
||||
3. **Remove References**: Update all code using the capability
|
||||
4. **Clean Registry**: Remove from this registry
|
||||
5. **Update Documentation**: Update all relevant documentation
|
||||
|
||||
---
|
||||
|
||||
## 📊 **CAPABILITY METRICS**
|
||||
|
||||
- **Total Capabilities**: 5 active capabilities
|
||||
- **Submodule Capabilities**: 3 (issue-facade, kaizen-agentic, wiki)
|
||||
- **Local Capabilities**: 2 (markitect-content, markitect-utils)
|
||||
- **External Dependencies**: Multiple (see pyproject.toml)
|
||||
- **Coverage**: Issue management, AI agent framework, content processing, utilities, documentation
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **SUCCESS CRITERIA**
|
||||
|
||||
### For Developers:
|
||||
- [ ] Zero accidental functionality duplication
|
||||
- [ ] Clear interface boundaries respected
|
||||
- [ ] Efficient capability discovery and usage
|
||||
- [ ] Proper separation of concerns maintained
|
||||
|
||||
### For Claude:
|
||||
- [ ] Registry consulted before implementing new functionality
|
||||
- [ ] Existing capabilities used when available
|
||||
- [ ] Clear understanding of capability boundaries
|
||||
- [ ] Proper integration patterns followed
|
||||
|
||||
### For the Project:
|
||||
- [ ] Modular architecture maintained
|
||||
- [ ] Easy capability extension and bugfixing
|
||||
- [ ] Clean separation between core and capabilities
|
||||
- [ ] Scalable capability inclusion patterns
|
||||
165
CHANGELOG.md
165
CHANGELOG.md
@@ -1,123 +1,50 @@
|
||||
# Changelog
|
||||
## [0.5.0] - 2025-10-26
|
||||
|
||||
### Added
|
||||
- **Clean TDD-Driven Editor Architecture**: Complete rewrite with object-oriented JavaScript architecture featuring Section, SectionManager, and DOMRenderer classes
|
||||
- **Enhanced Test Framework**: Comprehensive testing framework with clean separation of concerns for robust development
|
||||
- **Multiple Concurrent Section Editing**: Support for editing multiple sections simultaneously with intelligent management
|
||||
- **Intelligent Section Splitting**: Advanced heading detection and section management capabilities
|
||||
- **Four-Layer Content Management**: Sophisticated content state management (original, current, pending, editing layers)
|
||||
- **Enhanced Status Dialog**: Repository info display showing version, git commit status, and actual save filename
|
||||
- **Elegant Slide-in Control Panel**: Floating control panel for edit mode with improved UX
|
||||
- **Intelligent Auto-sizing Textarea**: Optimal editing experience with smart textarea resizing
|
||||
- **Enhanced Empty Line Preservation**: Better markdown structure preservation with automatic paragraph separation
|
||||
|
||||
### Fixed
|
||||
- **Textarea Sizing and Font Preservation**: Resolved sizing issues and maintained consistent font rendering
|
||||
- **Markdown Structure Preservation**: Fixed roundtrip formatting issues in save functionality
|
||||
- **Section Duplication Prevention**: Eliminated duplicate sections when saving edited content
|
||||
- **Section Position Preservation**: Prevented unwanted section jumping during editing
|
||||
- **CSS Embedding Issues**: Resolved import errors in HTML template generation
|
||||
- **Control Panel UX**: Hidden control ribbon when panel is expanded for cleaner interface
|
||||
|
||||
### Changed
|
||||
- **Action Semantics**: Proper implementation of Accept, Cancel, and Reset operations
|
||||
- **Global Reset Functionality**: Enhanced reset capabilities across the editor
|
||||
- **Makefile Organization**: Reorganized installation targets for better user experience
|
||||
|
||||
### Technical Improvements
|
||||
- Complete legacy editor system replacement
|
||||
- Test-driven development approach implementation
|
||||
- Enhanced UI/UX with better section positioning
|
||||
- Improved content management workflow
|
||||
|
||||
## [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.3.0] - 2025-10-25
|
||||
|
||||
### Added
|
||||
- **Kaizen-Agentic Framework Integration** as external capability submodule
|
||||
- **Test Reorganization by Capability** with separated test targets for better modularity
|
||||
- **Comprehensive Capability Inclusion Management System** with automated discovery tools
|
||||
- **Todofile System Implementation** - Modern task management replacing NEXT.md
|
||||
- **Historical File Organization** - Legacy files moved to history directory for better project structure
|
||||
|
||||
### Changed
|
||||
- **Capability Directory Reorganization** - moved all external dependencies to `capabilities/` directory
|
||||
- **Issue Management Migration** - replaced local issue system with external `issue-facade` submodule
|
||||
- **Project Structure Optimization** - established clear separation between capabilities and core documentation
|
||||
- **Test Architecture Enhancement** - separated capability-specific tests from core system tests
|
||||
- **Makefile Test Targets** - added granular test execution with `make test-capabilities` and capability-specific targets
|
||||
|
||||
### Improved
|
||||
- **Logical Organization** - capabilities/ for external dependencies, wiki/ for project documentation at root
|
||||
- **Test Performance** - core tests now exclude capability tests for faster execution
|
||||
- **Development Workflow** - clear separation between internal and external capabilities
|
||||
- **Documentation Ecosystem** - complete capability documentation with CAPABILITIES.md and CAPABILITY_REGISTRY.md
|
||||
- **Code Organization** - Archive of legacy files to maintain clean working directory
|
||||
|
||||
## [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
|
||||
@@ -1,135 +0,0 @@
|
||||
# Claude Capability Reference - Quick Lookup
|
||||
|
||||
> **Essential reference for Claude to prevent code duplication and ensure proper capability usage**
|
||||
|
||||
## 🚨 **BEFORE IMPLEMENTING: CHECK EXISTING CAPABILITIES**
|
||||
|
||||
### Issue Management ➜ USE `issue-facade/`
|
||||
```bash
|
||||
# ✅ DO: Use existing issue facade
|
||||
cd issue-facade && python -m cli.main list
|
||||
cd issue-facade && python -m cli.main show 42
|
||||
cd issue-facade && python -m cli.main create "Title" "Description"
|
||||
|
||||
# ❌ DON'T: Implement custom issue tracking
|
||||
# ❌ DON'T: Create new CLI commands for issues
|
||||
# ❌ DON'T: Build custom Gitea/GitHub API clients
|
||||
```
|
||||
|
||||
### Content Processing ➜ USE `capabilities/markitect-content/`
|
||||
```python
|
||||
# ✅ DO: Use existing content capability
|
||||
from capabilities.markitect_content import ContentParser, ContentStats
|
||||
parser = ContentParser()
|
||||
stats = ContentStats()
|
||||
|
||||
# ❌ DON'T: Reimplement markdown parsing
|
||||
# ❌ DON'T: Create new content statistics functions
|
||||
# ❌ DON'T: Duplicate frontmatter/tailmatter handling
|
||||
```
|
||||
|
||||
### Utilities ➜ USE `capabilities/markitect-utils/`
|
||||
```python
|
||||
# ✅ DO: Use existing utilities
|
||||
from capabilities.markitect_utils import utility_function
|
||||
|
||||
# ❌ DON'T: Recreate common utility functions
|
||||
# ❌ DON'T: Duplicate helper functions
|
||||
```
|
||||
|
||||
### Documentation ➜ USE `wiki/`
|
||||
```markdown
|
||||
# ✅ DO: Reference existing documentation
|
||||
See wiki/ComposableRepositoryParadigm.md
|
||||
See wiki/MarkdownMatters.md
|
||||
|
||||
# ❌ DON'T: Create duplicate documentation
|
||||
# ❌ DON'T: Rewrite architectural decisions
|
||||
```
|
||||
|
||||
## 🔍 **CAPABILITY DISCOVERY COMMANDS**
|
||||
|
||||
### Quick Capability Check
|
||||
```bash
|
||||
# Check all capabilities
|
||||
ls -la capabilities/ # Local capabilities
|
||||
ls -la issue-facade/ # Issue management capability
|
||||
ls -la wiki/ # Documentation capability
|
||||
cat CAPABILITY_REGISTRY.md # Full registry
|
||||
|
||||
# Verify functionality exists
|
||||
grep -r "function_name" capabilities/
|
||||
grep -r "class_name" issue-facade/
|
||||
```
|
||||
|
||||
### Interface Documentation
|
||||
- **Issue Facade**: `issue-facade/README.md`
|
||||
- **Content Processing**: `capabilities/markitect-content/README.md`
|
||||
- **Utilities**: `capabilities/markitect-utils/README.md`
|
||||
- **Documentation**: `wiki/` (multiple files)
|
||||
|
||||
## ⚡ **QUICK DECISION TREE**
|
||||
|
||||
1. **Need Issue Management?** ➜ Use `issue-facade/`
|
||||
2. **Need Content Parsing?** ➜ Use `capabilities/markitect-content/`
|
||||
3. **Need Utility Functions?** ➜ Check `capabilities/markitect-utils/`
|
||||
4. **Need Documentation?** ➜ Reference `wiki/`
|
||||
5. **Something New?** ➜ Check `CAPABILITY_REGISTRY.md` first
|
||||
|
||||
## 🎯 **CLAUDE IMPLEMENTATION RULES**
|
||||
|
||||
### Rule 1: Registry First
|
||||
- **Always check** `CAPABILITY_REGISTRY.md` before implementing
|
||||
- **Search existing** capabilities for similar functionality
|
||||
- **Extend, don't duplicate** existing capabilities
|
||||
|
||||
### Rule 2: Use Documented Interfaces
|
||||
- **Follow interface patterns** documented in capability READMEs
|
||||
- **Use provided CLI commands** rather than reimplementing
|
||||
- **Import from documented modules** rather than copying code
|
||||
|
||||
### Rule 3: Maintain Separation
|
||||
- **Core MarkiTect**: Focus on markdown processing and database operations
|
||||
- **Capabilities**: Use for specialized functionality (issues, content, utils)
|
||||
- **Clear boundaries**: Don't mix core and capability concerns
|
||||
|
||||
### Rule 4: Update Registry
|
||||
- **When adding capabilities**: Update `CAPABILITY_REGISTRY.md`
|
||||
- **When changing interfaces**: Update documentation
|
||||
- **When removing capabilities**: Clean up references
|
||||
|
||||
## 📋 **COMMON INTEGRATION PATTERNS**
|
||||
|
||||
### Submodule Usage
|
||||
```bash
|
||||
# Issue management via submodule
|
||||
cd issue-facade && python -m cli.main [command]
|
||||
|
||||
# Update submodule
|
||||
git submodule update --remote issue-facade
|
||||
```
|
||||
|
||||
### Local Capability Usage
|
||||
```python
|
||||
# Content processing
|
||||
from capabilities.markitect_content import ContentParser
|
||||
|
||||
# Utilities
|
||||
from capabilities.markitect_utils import helper_function
|
||||
```
|
||||
|
||||
### Error Prevention
|
||||
```python
|
||||
# ❌ BAD: Duplicating functionality
|
||||
def create_issue(title, body):
|
||||
# Custom implementation
|
||||
|
||||
# ✅ GOOD: Using existing capability
|
||||
import subprocess
|
||||
result = subprocess.run(['python', '-m', 'cli.main', 'create', title, body],
|
||||
cwd='issue-facade')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**💡 Remember: When in doubt, check the registry first!**
|
||||
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.
|
||||
80
Makefile
80
Makefile
@@ -1,7 +1,7 @@
|
||||
# MarkiTect - Advanced Markdown Engine
|
||||
# Makefile for common development tasks
|
||||
|
||||
.PHONY: help setup install-dev install-home install-home-venv install-deps install-deps-force install-deps-venv install-system list-deps setup-dev test build clean update status lint format check-deps venv-status update-digest add-diary-entry test-status test-new test-coverage test-arch test-foundation test-infrastructure test-integration test-domain test-service test-application test-presentation test-quick test-layers test-random test-random-seed test-random-repeat test-install-randomly test-clean test-tdd test-changed test-module test-cache-clean test-efficient cli-help release-status release-validate release-prepare release-build release-publish release-dry-run chaos-validate chaos-matrix chaos-inject chaos-report cost-help
|
||||
.PHONY: help setup install install-dev uninstall install-home install-home-venv install-user-deps install-force-deps install-deps-venv install-system-deps list-deps setup-dev test build clean update status lint format check-deps venv-status update-digest add-diary-entry test-status test-new test-coverage test-arch test-foundation test-infrastructure test-integration test-domain test-service test-application test-presentation test-quick test-layers test-random test-random-seed test-random-repeat test-install-randomly test-clean test-tdd test-changed test-module test-cache-clean test-efficient cli-help release-status release-validate release-prepare release-build release-publish release-dry-run chaos-validate chaos-matrix chaos-inject chaos-report cost-help
|
||||
|
||||
# Default target
|
||||
help:
|
||||
@@ -13,17 +13,17 @@ help:
|
||||
@echo ""
|
||||
@echo "Setup & Installation:"
|
||||
@echo " setup - Initial project setup (venv + install-dev)"
|
||||
@echo " install - Install markitect globally (recommended)"
|
||||
@echo " install-dev - Install package in development mode"
|
||||
@echo " install-home - Install markitect binary to ~/bin/"
|
||||
@echo " install-deps - Install dependencies (tries user-local first)"
|
||||
@echo " install-deps-force - Force install with --break-system-packages"
|
||||
@echo " install-deps-venv - Install to user virtual environment"
|
||||
@echo " install-home-venv - Install binary using user virtual environment"
|
||||
@echo " install-system - Install system dependencies via apt (requires sudo)"
|
||||
@echo " uninstall - Remove global markitect installation"
|
||||
@echo " list-deps - List required dependencies for markitect"
|
||||
@echo " setup-dev - Install with development dependencies"
|
||||
@echo " venv-status - Check if venv is active"
|
||||
@echo ""
|
||||
@echo "Advanced Installation:"
|
||||
@echo " install-user-deps - Install dependencies to user location only"
|
||||
@echo " install-system-deps - Install dependencies via system packages (sudo)"
|
||||
@echo " install-force-deps - Force install with --break-system-packages"
|
||||
@echo ""
|
||||
@echo "Development:"
|
||||
@echo " test - Run core tests (excluding capability-specific tests)"
|
||||
@echo " test-capabilities - Run all capability-specific tests"
|
||||
@@ -83,6 +83,7 @@ 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)"
|
||||
@@ -140,6 +141,40 @@ $(VENV)/bin/activate:
|
||||
$(PYTHON) -m venv $(VENV)
|
||||
$(VENV_PIP) install --upgrade pip setuptools wheel
|
||||
|
||||
# Install markitect globally (recommended approach)
|
||||
install:
|
||||
@echo "🚀 Installing MarkiTect globally..."
|
||||
@echo "📦 Creating user virtual environment with dependencies..."
|
||||
@$(MAKE) --no-print-directory install-deps-venv
|
||||
@echo "🏠 Installing markitect binary to ~/bin/..."
|
||||
@$(MAKE) --no-print-directory install-home-venv
|
||||
@echo ""
|
||||
@echo "✅ MarkiTect installed successfully!"
|
||||
@echo "💡 Make sure ~/bin is in your PATH:"
|
||||
@echo " export PATH=\"$$HOME/bin:$$PATH\""
|
||||
@echo ""
|
||||
@echo "🧪 Test installation:"
|
||||
@echo " markitect version"
|
||||
|
||||
# Remove global markitect installation
|
||||
uninstall:
|
||||
@echo "🗑️ Removing MarkiTect global installation..."
|
||||
@if [ -f "$$HOME/bin/markitect" ]; then \
|
||||
echo " Removing binary: $$HOME/bin/markitect"; \
|
||||
rm "$$HOME/bin/markitect"; \
|
||||
echo " ✅ Binary removed"; \
|
||||
else \
|
||||
echo " ℹ️ Binary not found at $$HOME/bin/markitect"; \
|
||||
fi
|
||||
@if [ -d "$$HOME/.local/markitect-venv" ]; then \
|
||||
echo " Removing virtual environment: $$HOME/.local/markitect-venv"; \
|
||||
rm -rf "$$HOME/.local/markitect-venv"; \
|
||||
echo " ✅ Virtual environment removed"; \
|
||||
else \
|
||||
echo " ℹ️ Virtual environment not found"; \
|
||||
fi
|
||||
@echo "✅ MarkiTect uninstalled successfully!"
|
||||
|
||||
# Install package in development mode
|
||||
install-dev: $(VENV)/bin/activate
|
||||
@echo "📦 Installing MarkiTect in development mode..."
|
||||
@@ -214,13 +249,14 @@ list-deps:
|
||||
@echo " toml - TOML configuration parsing"
|
||||
@echo ""
|
||||
@echo "🔧 Installation options:"
|
||||
@echo " make install-deps - Install user-local (recommended)"
|
||||
@echo " make install-system - Install via apt + pip --user (requires sudo)"
|
||||
@echo " make install - Install globally (recommended)"
|
||||
@echo " make install-user-deps - Install user-local dependencies only"
|
||||
@echo " make install-system-deps - Install via apt + pip --user (requires sudo)"
|
||||
@echo " pip3 install --user [packages] - Manual user-local installation"
|
||||
@echo " pip install -e . - Install from project directory (dev mode)"
|
||||
|
||||
# Install user-local dependencies for markitect (no sudo needed)
|
||||
install-deps:
|
||||
install-user-deps:
|
||||
@echo "📦 Installing MarkiTect dependencies (user-local)..."
|
||||
@echo "🐍 Target Python: $$(which python3) (version: $$(python3 --version))"
|
||||
@echo "📍 pip3 location: $$(which pip3)"
|
||||
@@ -232,12 +268,12 @@ install-deps:
|
||||
echo "❌ User-local installation failed (externally-managed-environment)"; \
|
||||
echo ""; \
|
||||
echo "🔧 Alternative solutions:"; \
|
||||
echo " 1. Use system packages: make install-system"; \
|
||||
echo " 2. Override restriction: make install-deps-force"; \
|
||||
echo " 1. Use system packages: make install-system-deps"; \
|
||||
echo " 2. Override restriction: make install-force-deps"; \
|
||||
echo " 3. Create user venv: make install-deps-venv"; \
|
||||
echo " 4. Use development setup: make setup"; \
|
||||
echo ""; \
|
||||
echo "💡 Recommended: Try 'make install-system' first"; \
|
||||
echo "💡 Recommended: Try 'make install' for complete setup"; \
|
||||
exit 1; \
|
||||
fi
|
||||
@echo "🧪 Testing import..."
|
||||
@@ -245,7 +281,7 @@ install-deps:
|
||||
@echo "💡 You can now use 'markitect' command if it's in your PATH"
|
||||
|
||||
# Force install user-local dependencies (overrides externally-managed restriction)
|
||||
install-deps-force:
|
||||
install-force-deps:
|
||||
@echo "📦 Force installing MarkiTect dependencies (overriding restrictions)..."
|
||||
@echo "⚠️ This uses --break-system-packages flag"
|
||||
@echo " Only use if you understand the implications"
|
||||
@@ -286,7 +322,7 @@ install-deps-venv:
|
||||
@echo "💡 To use this, run 'make install-home-venv' instead of 'make install-home'"
|
||||
|
||||
# Install system dependencies via apt (requires sudo)
|
||||
install-system:
|
||||
install-system-deps:
|
||||
@echo "📦 Installing MarkiTect dependencies via apt..."
|
||||
@echo "⚠️ This requires sudo and installs system packages"
|
||||
@echo ""
|
||||
@@ -312,7 +348,7 @@ install-system:
|
||||
echo "💡 You can now use 'markitect' command if it's in your PATH"; \
|
||||
else \
|
||||
echo "❌ Installation cancelled"; \
|
||||
echo "💡 Alternative: Use 'make install-deps' for user-local installation"; \
|
||||
echo "💡 Alternative: Use 'make install' for automated setup"; \
|
||||
fi
|
||||
|
||||
# Install with development dependencies
|
||||
@@ -1340,3 +1376,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) · [Capability Inclusion](CAPABILITY_INCLUSION_GUIDE.md)
|
||||
|
||||
**Development:** [TDD Workflow](docs/development/tdd-workflow.md) · [Contributing](#contributing) · [Capabilities Overview](CAPABILITIES.md)
|
||||
|
||||
**Project Status:** [Current Status](history/ProjectStatusDigest.md) · [Roadmap](history/ROADMAP.md) · [Current Tasks](TODO.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/)
|
||||
101
TODO.md
101
TODO.md
@@ -1,101 +0,0 @@
|
||||
# Todofile
|
||||
|
||||
This is a "to do next" file, particularly useful to keep the human and a coding assistant in sync.
|
||||
|
||||
The format is based on [Keep a Todofile V0.0.1](https://coulomb.social/open/KeepaTodofile).
|
||||
|
||||
The structure organizes **future tasks** by their impact, just as a changelog organizes past changes by their impact.
|
||||
|
||||
***
|
||||
|
||||
## [Unreleased] - *Active Vibe-Coding State* 💡
|
||||
|
||||
This section is for tasks currently being discussed with or worked on by the coding assistant. These are the ephemeral, flow-of-thought tasks.
|
||||
|
||||
* **To Add:**
|
||||
* Complete AST Query and Analysis CLI implementation (Issue #15)
|
||||
* Performance Validation CLI implementation (Issue #16)
|
||||
* Enhanced discovery tools validation and refinement
|
||||
* **To Refactor:**
|
||||
* Update any missing links in existing documentation to new capability system
|
||||
* Refine capability discovery workflow based on practical usage
|
||||
* Enhance AI assistant integration with capability system
|
||||
* **To Fix:**
|
||||
* Validate that CAPABILITY_DOCUMENTATION_INDEX.md provides effective navigation
|
||||
* Ensure all agents are aware of capability inclusion workflow
|
||||
* Test automated detection prevention of code duplication
|
||||
* **To Remove:**
|
||||
* Retire NEXT.md file after successful todofile migration
|
||||
* Clean up any outdated task management references
|
||||
|
||||
***
|
||||
|
||||
## [0.3.0] - Strategic Development Execution - *Next Planned Increment*
|
||||
|
||||
This version represents the next set of concrete, planned features focusing on strategic issue resolution and capability validation.
|
||||
|
||||
### To Add
|
||||
* **AST Query and Analysis CLI** - Complete implementation of Issue #15 with full AST parsing and analysis capabilities
|
||||
* **Performance Validation CLI** - Complete implementation of Issue #16 with comprehensive performance testing and metrics
|
||||
* **Enhanced Discovery Tools** - Improve `make capability-search TERM=xyz` based on real-world usage patterns
|
||||
* **Capability Integration Validation** - Test framework for ensuring capability inclusion workflow effectiveness
|
||||
|
||||
### To Refactor
|
||||
* **Documentation Ecosystem** - Update any missing links to new capability system components
|
||||
* **AI Assistant Integration** - Enhance capability reference utilization for informed decision-making
|
||||
* **Workflow Optimization** - Refine capability-first development process based on practical experience
|
||||
|
||||
### To Fix
|
||||
* **Documentation Navigation** - Ensure CAPABILITY_DOCUMENTATION_INDEX.md provides effective project navigation
|
||||
* **Agent Workflow Integration** - Validate all agents properly utilize capability inclusion workflow
|
||||
* **Duplication Prevention** - Test and improve automated detection systems
|
||||
|
||||
### To Secure
|
||||
* **Capability Validation** - Ensure capability inclusion system maintains security best practices
|
||||
* **Dependency Management** - Validate external capability references and security implications
|
||||
|
||||
### To Remove
|
||||
* **Legacy Task Management** - Retire NEXT.md approach in favor of standardized todofile system
|
||||
* **Outdated Documentation References** - Clean up any references to deprecated task management approaches
|
||||
|
||||
***
|
||||
|
||||
## [COMPLETED] - *Capability Inclusion Management System - Version 0.2.0*
|
||||
|
||||
### ✅ Completed: To Add
|
||||
* **Complete capability documentation ecosystem** - DONE
|
||||
- CAPABILITIES.md for internal capabilities with detailed descriptions
|
||||
- CAPABILITY_REGISTRY.md for external capabilities and dependencies
|
||||
- CAPABILITY_DOCUMENTATION_INDEX.md for navigation and discovery
|
||||
- CLAUDE_CAPABILITY_REFERENCE.md for AI assistant quick reference
|
||||
- CAPABILITY_INCLUSION_GUIDE.md for workflow and best practices
|
||||
* **Automated discovery tools** - DONE
|
||||
- `make capability-search TERM=xyz` for capability discovery
|
||||
- Prevention of code duplication through automated detection
|
||||
- Enhanced agent definitions with capability inclusion workflow
|
||||
* **Architectural clarity** - DONE
|
||||
- Clear separation of internal vs external capabilities
|
||||
- Comprehensive categorization system
|
||||
- Detailed capability documentation with examples
|
||||
|
||||
### ✅ Completed: To Refactor
|
||||
* **Agent definitions** - DONE
|
||||
- Enhanced all agents with capability inclusion workflow awareness
|
||||
- Updated agent instructions to utilize capability references
|
||||
- Improved AI assistant integration patterns
|
||||
|
||||
### ✅ Completed: To Fix
|
||||
* **Documentation ecosystem integration** - DONE
|
||||
- All capability files properly interconnected
|
||||
- Navigation system functional and comprehensive
|
||||
- Discovery tools working effectively
|
||||
|
||||
### ✅ Completed: To Secure
|
||||
* **Capability validation system** - DONE
|
||||
- Proper validation of capability inclusion workflow
|
||||
- Security considerations for external capability references
|
||||
|
||||
### ✅ Completed: To Remove
|
||||
* **Code duplication risks** - DONE
|
||||
- Implemented prevention mechanisms
|
||||
- Automated detection and discovery systems
|
||||
@@ -1,81 +0,0 @@
|
||||
# MarkiTect Todofile System
|
||||
|
||||
## Overview
|
||||
|
||||
MarkiTect uses the **Keep a Todofile V0.0.1** format for task management and development coordination. This replaces the previous NEXT.md approach with a standardized todofile system that provides better structure for maintaining coding flow and AI assistant coordination.
|
||||
|
||||
## Location and Format
|
||||
|
||||
- **Main Todofile**: `TODO.md` in the project root
|
||||
- **Format**: [Keep a Todofile V0.0.1](https://coulomb.social/open/KeepaTodofile)
|
||||
- **Agent Support**: Managed by the `agent-keepaTodofile` agent in the kaizen-agentic framework
|
||||
|
||||
## Structure
|
||||
|
||||
The todofile is organized by **impact type** rather than arbitrary priority:
|
||||
|
||||
### [Unreleased] - Active Vibe-Coding State 💡
|
||||
- **To Add**: New features, capabilities, or functionality
|
||||
- **To Refactor**: Code improvements and restructuring
|
||||
- **To Fix**: Bug fixes and error corrections
|
||||
- **To Remove**: Features or code to eliminate
|
||||
|
||||
### [Version] - Planned Increments
|
||||
Organized by planned version/milestone with the same impact categories:
|
||||
- **To Add**: Planned new functionality
|
||||
- **To Fix**: Scheduled bug fixes
|
||||
- **To Refactor**: Planned code improvements
|
||||
- **To Deprecate**: Features marked for future removal
|
||||
- **To Secure**: Security improvements
|
||||
- **To Remove**: Planned removals
|
||||
|
||||
## Integration with Project Workflow
|
||||
|
||||
### Task Management
|
||||
- Use `TODO.md` for active development tasks and immediate next steps
|
||||
- Link to Gitea issues for longer-term planning: `Related to issue #123`
|
||||
- Update during development sessions to maintain context
|
||||
|
||||
### AI Assistant Coordination
|
||||
- The todofile serves as a **shared source of truth** between human developers and AI assistants
|
||||
- Helps maintain context during interruptions and session transfers
|
||||
- Enables consistent progress tracking and decision-making
|
||||
|
||||
### Development Best Practices
|
||||
1. **Update Regularly**: Maintain current state during active development
|
||||
2. **Focus on Immediate**: Keep [Unreleased] section for current work
|
||||
3. **Plan Versions**: Use version sections for commit boundaries
|
||||
4. **Archive Completed**: Move completed items to archive sections
|
||||
5. **Link Issues**: Connect todofile items to Gitea issues for full context
|
||||
|
||||
## Agent Integration
|
||||
|
||||
The `agent-keepaTodofile` agent provides specialized support for:
|
||||
- Creating and maintaining TODO.md files following the official format
|
||||
- Organizing tasks by impact type (Add, Fix, Refactor, etc.)
|
||||
- Integrating with issue tracking and TDD workflows
|
||||
- Maintaining coding flow and context preservation
|
||||
- Converting between task management formats
|
||||
|
||||
## Migration from NEXT.md
|
||||
|
||||
The previous NEXT.md file has been archived to `history/NEXT_archived_YYYYMMDD.md`. All relevant content has been migrated to the new TODO.md format while preserving:
|
||||
- Strategic development priorities
|
||||
- Capability management workflows
|
||||
- Session success criteria
|
||||
- Development milestones
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Agent Definition**: `agents/agent-keepaTodofile.md` - Specialized todofile management agent
|
||||
- **Context Documentation**: `capabilities/kaizen-agentic/context/KeepaTodofile.md` - Detailed format specification
|
||||
- **Capability Integration**: `CAPABILITY_INCLUSION_GUIDE.md` - How todofile fits with capability discovery
|
||||
- **Project Management**: `agents/agent-project-management.md` - Overall project coordination
|
||||
|
||||
## Benefits
|
||||
|
||||
1. **Standardized Format**: Follows established Keep a Todofile conventions
|
||||
2. **Better Organization**: Impact-based categorization aligns with changelog structure
|
||||
3. **AI Assistant Ready**: Designed for human-AI collaboration in coding sessions
|
||||
4. **Context Preservation**: Maintains coding flow across interruptions
|
||||
5. **Integration Ready**: Works with existing issue management and TDD workflows
|
||||
@@ -11,7 +11,7 @@ from pathlib import Path
|
||||
from typing import Optional
|
||||
|
||||
# Base version from pyproject.toml
|
||||
__version__ = "0.3.0"
|
||||
__version__ = "0.5.0"
|
||||
|
||||
def get_git_commit_hash() -> Optional[str]:
|
||||
"""Get the current git commit hash if available."""
|
||||
|
||||
1430
markitect/clean_document_manager.py
Normal file
1430
markitect/clean_document_manager.py
Normal file
File diff suppressed because it is too large
Load Diff
@@ -101,7 +101,7 @@ def detect_execution_mode():
|
||||
def should_use_associated_files():
|
||||
"""Determine if commands should use associated files behavior."""
|
||||
return detect_execution_mode() == 'interactive'
|
||||
from .document_manager import DocumentManager
|
||||
# DocumentManager removed - using CleanDocumentManager directly in commands
|
||||
from .serializer import ASTSerializer
|
||||
from .cache_service import CacheDirectoryService
|
||||
from .ast_service import ASTService
|
||||
|
||||
@@ -355,6 +355,7 @@ class DocumentManager:
|
||||
edit_mode: bool = False, editor_theme: str = 'github', keyboard_shortcuts: bool = True) -> str:
|
||||
"""Generate HTML template with embedded markdown and client-side rendering."""
|
||||
import json
|
||||
from pathlib import Path
|
||||
|
||||
# Escape the markdown content for JavaScript
|
||||
js_markdown_content = json.dumps(markdown_content)
|
||||
@@ -395,35 +396,267 @@ class DocumentManager:
|
||||
body_classes = ' class="markitect-edit-mode"'
|
||||
editor_css = """
|
||||
<style>
|
||||
.markitect-floating-header {
|
||||
/* Floating Control Panel - Slide-in from right */
|
||||
.markitect-control-panel {
|
||||
position: fixed;
|
||||
top: 0;
|
||||
left: 0;
|
||||
right: 0;
|
||||
background: rgba(255, 255, 255, 0.95);
|
||||
border-bottom: 1px solid #ddd;
|
||||
padding: 10px;
|
||||
top: 20px;
|
||||
right: -320px;
|
||||
width: 320px;
|
||||
background: rgba(255, 255, 255, 0.98);
|
||||
border: 1px solid #e0e0e0;
|
||||
border-radius: 12px 0 0 12px;
|
||||
box-shadow: -4px 0 20px rgba(0, 0, 0, 0.15);
|
||||
z-index: 1000;
|
||||
backdrop-filter: blur(5px);
|
||||
backdrop-filter: blur(10px);
|
||||
transition: right 0.3s cubic-bezier(0.4, 0, 0.2, 1);
|
||||
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
|
||||
}
|
||||
|
||||
.markitect-control-panel.expanded {
|
||||
right: 0;
|
||||
}
|
||||
|
||||
.markitect-control-panel.expanded .markitect-control-ribbon {
|
||||
opacity: 0;
|
||||
pointer-events: none;
|
||||
}
|
||||
|
||||
/* Control ribbon - always visible */
|
||||
.markitect-control-ribbon {
|
||||
position: absolute;
|
||||
left: -40px;
|
||||
top: 0;
|
||||
width: 40px;
|
||||
height: 100%;
|
||||
background: linear-gradient(135deg, #2196f3, #1976d2);
|
||||
border-radius: 8px 0 0 8px;
|
||||
cursor: pointer;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
color: white;
|
||||
font-size: 18px;
|
||||
transition: all 0.3s ease, opacity 0.3s ease;
|
||||
opacity: 1;
|
||||
pointer-events: auto;
|
||||
}
|
||||
|
||||
.markitect-control-ribbon:hover {
|
||||
background: linear-gradient(135deg, #1976d2, #1565c0);
|
||||
transform: translateX(-2px);
|
||||
}
|
||||
|
||||
/* Panel content */
|
||||
.markitect-panel-header {
|
||||
background: linear-gradient(135deg, #2196f3, #1976d2);
|
||||
color: white;
|
||||
padding: 16px 20px;
|
||||
border-radius: 12px 0 0 0;
|
||||
position: relative;
|
||||
}
|
||||
|
||||
.markitect-panel-title {
|
||||
font-weight: 600;
|
||||
font-size: 16px;
|
||||
margin: 0 0 4px 0;
|
||||
}
|
||||
|
||||
.markitect-panel-version {
|
||||
font-size: 12px;
|
||||
opacity: 0.9;
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.markitect-panel-close {
|
||||
position: absolute;
|
||||
top: 12px;
|
||||
right: 16px;
|
||||
background: none;
|
||||
border: none;
|
||||
color: white;
|
||||
cursor: pointer;
|
||||
font-size: 20px;
|
||||
padding: 4px;
|
||||
border-radius: 4px;
|
||||
transition: background 0.2s;
|
||||
}
|
||||
|
||||
.markitect-panel-close:hover {
|
||||
background: rgba(255, 255, 255, 0.2);
|
||||
}
|
||||
|
||||
.markitect-panel-body {
|
||||
padding: 20px;
|
||||
}
|
||||
|
||||
.markitect-status-section {
|
||||
margin-bottom: 20px;
|
||||
}
|
||||
|
||||
.markitect-status-indicator {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
padding: 12px;
|
||||
background: #f8f9fa;
|
||||
border-radius: 8px;
|
||||
margin-bottom: 12px;
|
||||
border-left: 4px solid #4caf50;
|
||||
}
|
||||
|
||||
.markitect-status-indicator.loading {
|
||||
border-left-color: #ff9800;
|
||||
}
|
||||
|
||||
.markitect-status-indicator.error {
|
||||
border-left-color: #f44336;
|
||||
background: #ffebee;
|
||||
}
|
||||
|
||||
.markitect-status-icon {
|
||||
margin-right: 8px;
|
||||
font-size: 16px;
|
||||
}
|
||||
|
||||
.markitect-status-text {
|
||||
flex: 1;
|
||||
font-size: 14px;
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.markitect-controls-section {
|
||||
border-top: 1px solid #e0e0e0;
|
||||
padding-top: 20px;
|
||||
}
|
||||
|
||||
.markitect-controls-grid {
|
||||
display: grid;
|
||||
grid-template-columns: 1fr 1fr;
|
||||
gap: 10px;
|
||||
margin-bottom: 16px;
|
||||
}
|
||||
|
||||
.markitect-control-btn {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
padding: 12px 16px;
|
||||
background: #2196f3;
|
||||
color: white;
|
||||
border: none;
|
||||
border-radius: 8px;
|
||||
cursor: pointer;
|
||||
font-size: 14px;
|
||||
font-weight: 500;
|
||||
transition: all 0.2s;
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
.markitect-control-btn:hover {
|
||||
background: #1976d2;
|
||||
transform: translateY(-1px);
|
||||
}
|
||||
|
||||
.markitect-control-btn.secondary {
|
||||
background: #757575;
|
||||
}
|
||||
|
||||
.markitect-control-btn.secondary:hover {
|
||||
background: #616161;
|
||||
}
|
||||
|
||||
.markitect-control-btn .icon {
|
||||
margin-right: 6px;
|
||||
}
|
||||
|
||||
.markitect-save-info {
|
||||
font-size: 12px;
|
||||
color: #666;
|
||||
background: #f5f5f5;
|
||||
padding: 8px 12px;
|
||||
border-radius: 6px;
|
||||
margin-top: 10px;
|
||||
}
|
||||
|
||||
.markitect-error-details {
|
||||
display: none;
|
||||
background: #ffebee;
|
||||
border: 1px solid #f44336;
|
||||
border-radius: 8px;
|
||||
padding: 12px;
|
||||
margin-top: 12px;
|
||||
}
|
||||
|
||||
.markitect-error-title {
|
||||
font-weight: bold;
|
||||
color: #c62828;
|
||||
margin: 0 0 8px 0;
|
||||
}
|
||||
|
||||
.markitect-error-text {
|
||||
color: #666;
|
||||
font-size: 14px;
|
||||
margin: 0 0 8px 0;
|
||||
}
|
||||
|
||||
.markitect-error-help {
|
||||
font-size: 12px;
|
||||
color: #666;
|
||||
}
|
||||
|
||||
/* Content editing styles */
|
||||
.markitect-section-editable {
|
||||
border: 1px dashed transparent;
|
||||
padding: 8px;
|
||||
margin: 4px 0;
|
||||
border-radius: 4px;
|
||||
cursor: pointer;
|
||||
transition: all 0.2s ease;
|
||||
}
|
||||
|
||||
.markitect-section-editable:hover {
|
||||
border-color: #007acc;
|
||||
background: rgba(0, 122, 204, 0.05);
|
||||
}
|
||||
|
||||
.markitect-section-editable[data-edited] {
|
||||
border-color: rgba(76, 175, 80, 0.3);
|
||||
background: rgba(76, 175, 80, 0.02);
|
||||
}
|
||||
|
||||
.markitect-section-editable[data-edited]:hover {
|
||||
border-color: #4caf50;
|
||||
background: rgba(76, 175, 80, 0.08);
|
||||
}
|
||||
|
||||
.edit-mode textarea {
|
||||
width: 100%;
|
||||
min-height: 100px;
|
||||
font-family: monospace;
|
||||
min-height: 60px;
|
||||
max-height: 360px;
|
||||
font-family: 'SF Mono', 'Monaco', 'Cascadia Code', 'Roboto Mono', monospace;
|
||||
border: 2px solid #007acc;
|
||||
border-radius: 4px;
|
||||
padding: 8px;
|
||||
border-radius: 6px;
|
||||
padding: 12px;
|
||||
font-size: inherit; /* Will be overridden by JavaScript */
|
||||
line-height: inherit; /* Will be overridden by JavaScript */
|
||||
resize: both; /* Allow both horizontal and vertical resize */
|
||||
overflow: auto;
|
||||
box-sizing: border-box;
|
||||
transition: height 0.15s ease;
|
||||
min-width: 200px; /* Ensure minimum width */
|
||||
}
|
||||
|
||||
.edit-mode textarea:focus {
|
||||
outline: none;
|
||||
border-color: #1976d2;
|
||||
box-shadow: 0 0 0 3px rgba(25, 118, 210, 0.1);
|
||||
}
|
||||
|
||||
/* Responsive adjustments */
|
||||
@media (max-width: 768px) {
|
||||
.markitect-control-panel {
|
||||
width: 280px;
|
||||
right: -280px;
|
||||
}
|
||||
}
|
||||
</style>"""
|
||||
|
||||
@@ -439,24 +672,25 @@ class DocumentManager:
|
||||
editor_scripts = """
|
||||
class MarkitectEditor {
|
||||
constructor() {
|
||||
this.hasEdits = false; // Track if any edits have been made
|
||||
this.initializeEditor();
|
||||
this.setupKeyboardShortcuts();
|
||||
}
|
||||
|
||||
initializeEditor() {
|
||||
const header = document.createElement('div');
|
||||
header.className = 'markitect-floating-header';
|
||||
header.innerHTML = `
|
||||
<button onclick="markitectEditor.save()" title="Download edited file with timestamp">💾 Save & Download</button>
|
||||
<button onclick="markitectEditor.togglePreview()" title="Toggle preview mode">👁️ Preview</button>
|
||||
<span id="save-status" style="margin-left: 15px; font-size: 0.9em;">Ready</span>
|
||||
<span style="margin-left: 15px; font-size: 0.8em; color: #666;">
|
||||
Saves as: filename-edited-YYYY-MM-DD-HH-MM-SS.md
|
||||
</span>
|
||||
`;
|
||||
document.body.insertBefore(header, document.body.firstChild);
|
||||
|
||||
// Control panel is already in HTML, just make content editable
|
||||
this.makeContentEditable();
|
||||
|
||||
// Auto-expand control panel briefly to show it's available
|
||||
setTimeout(() => {
|
||||
const panel = document.getElementById('markitect-control-panel');
|
||||
if (panel) {
|
||||
panel.classList.add('expanded');
|
||||
setTimeout(() => {
|
||||
panel.classList.remove('expanded');
|
||||
}, 2000); // Show for 2 seconds then minimize
|
||||
}
|
||||
}, 1000);
|
||||
}
|
||||
|
||||
makeContentEditable() {
|
||||
@@ -468,10 +702,30 @@ class DocumentManager:
|
||||
}
|
||||
|
||||
markSections(element) {
|
||||
// Clear existing section markers (except edited ones)
|
||||
const existingSections = element.querySelectorAll('.markitect-section-editable:not([data-edited])');
|
||||
existingSections.forEach(section => {
|
||||
section.classList.remove('markitect-section-editable');
|
||||
section.removeAttribute('data-section');
|
||||
});
|
||||
|
||||
// Mark new sections (skip elements inside edited wrappers)
|
||||
const sections = element.querySelectorAll('h1, h2, h3, h4, h5, h6, p, blockquote, pre, ul, ol');
|
||||
sections.forEach((section, index) => {
|
||||
let sectionIndex = 0;
|
||||
|
||||
sections.forEach((section) => {
|
||||
// Skip if this element is inside an edited wrapper
|
||||
if (section.closest('[data-edited]')) {
|
||||
return;
|
||||
}
|
||||
|
||||
// Skip if already marked as edited wrapper
|
||||
if (section.hasAttribute('data-edited')) {
|
||||
return;
|
||||
}
|
||||
|
||||
section.classList.add('markitect-section-editable');
|
||||
section.setAttribute('data-section', index);
|
||||
section.setAttribute('data-section', sectionIndex++);
|
||||
});
|
||||
}
|
||||
|
||||
@@ -488,9 +742,90 @@ class DocumentManager:
|
||||
textarea.value = this.htmlToMarkdown(originalContent);
|
||||
textarea.className = 'edit-mode';
|
||||
|
||||
// Get original element font size and style
|
||||
const computedStyle = window.getComputedStyle(section);
|
||||
const originalFontSize = computedStyle.fontSize;
|
||||
const originalLineHeight = computedStyle.lineHeight;
|
||||
|
||||
// Apply matching font size to textarea
|
||||
textarea.style.fontSize = originalFontSize;
|
||||
if (originalLineHeight !== 'normal') {
|
||||
textarea.style.lineHeight = originalLineHeight;
|
||||
}
|
||||
|
||||
// Auto-sizing function
|
||||
const autoResize = () => {
|
||||
// Temporarily disable transition for accurate measurement
|
||||
const transition = textarea.style.transition;
|
||||
textarea.style.transition = 'none';
|
||||
|
||||
// Reset height to measure scrollHeight
|
||||
textarea.style.height = 'auto';
|
||||
|
||||
// Calculate based on actual content with more reasonable constraints
|
||||
const contentHeight = textarea.scrollHeight;
|
||||
const padding = 24; // 12px top + 12px bottom
|
||||
|
||||
// More reasonable sizing: min 2 lines, max 15 lines
|
||||
const lineCount = textarea.value.split('\\n').length;
|
||||
const minHeight = Math.max(60, lineCount * 24 + padding); // ~24px per line
|
||||
const maxHeight = 360; // Maximum height constraint
|
||||
|
||||
const newHeight = Math.max(60, Math.min(maxHeight, Math.max(minHeight, contentHeight + 4)));
|
||||
textarea.style.height = newHeight + 'px';
|
||||
|
||||
// Re-enable transition
|
||||
textarea.style.transition = transition;
|
||||
};
|
||||
|
||||
// Auto-resize on input and paste
|
||||
textarea.addEventListener('input', autoResize);
|
||||
textarea.addEventListener('paste', () => setTimeout(autoResize, 10));
|
||||
|
||||
// Initial sizing after DOM update
|
||||
setTimeout(autoResize, 20);
|
||||
|
||||
textarea.addEventListener('blur', () => {
|
||||
section.innerHTML = marked.parse(textarea.value);
|
||||
this.markSections(section.parentElement);
|
||||
this.hasEdits = true; // Mark that edits have been made
|
||||
|
||||
// Check if the content contains paragraph breaks that should create separate sections
|
||||
const content = textarea.value.trim();
|
||||
const paragraphs = content.split(/\\n\\s*\\n/).filter(p => p.trim());
|
||||
|
||||
if (paragraphs.length > 1) {
|
||||
// Multiple paragraphs - create separate sections
|
||||
const parentNode = section.parentNode;
|
||||
const sectionIndex = section.getAttribute('data-section');
|
||||
const nextSibling = section.nextSibling; // Remember position
|
||||
|
||||
// Remove the original section
|
||||
parentNode.removeChild(section);
|
||||
|
||||
// Create separate sections for each paragraph and insert at correct position
|
||||
paragraphs.forEach((paragraph, index) => {
|
||||
const wrapper = document.createElement('div');
|
||||
wrapper.innerHTML = marked.parse(paragraph.trim());
|
||||
wrapper.classList.add('markitect-section-editable');
|
||||
wrapper.setAttribute('data-section', sectionIndex + '_' + index);
|
||||
wrapper.setAttribute('data-edited', 'true');
|
||||
|
||||
// Insert at the correct position (before nextSibling)
|
||||
parentNode.insertBefore(wrapper, nextSibling);
|
||||
});
|
||||
} else {
|
||||
// Single content block - create one wrapper
|
||||
const wrapper = document.createElement('div');
|
||||
wrapper.innerHTML = marked.parse(content);
|
||||
wrapper.classList.add('markitect-section-editable');
|
||||
wrapper.setAttribute('data-section', section.getAttribute('data-section'));
|
||||
wrapper.setAttribute('data-edited', 'true');
|
||||
|
||||
// Replace the section with the wrapper
|
||||
section.parentNode.replaceChild(wrapper, section);
|
||||
}
|
||||
|
||||
// Re-mark sections in the entire document, but skip edited wrappers
|
||||
this.markSections(document.getElementById('markdown-content'));
|
||||
});
|
||||
|
||||
section.innerHTML = '';
|
||||
@@ -499,8 +834,76 @@ class DocumentManager:
|
||||
}
|
||||
|
||||
htmlToMarkdown(html) {
|
||||
// Simple HTML to Markdown conversion
|
||||
return html.replace(/<[^>]*>/g, '').trim();
|
||||
// Create a temporary element to parse the HTML
|
||||
const temp = document.createElement('div');
|
||||
temp.innerHTML = html;
|
||||
|
||||
// Better HTML to Markdown conversion that preserves structure
|
||||
let markdown = '';
|
||||
|
||||
const processNode = (node) => {
|
||||
if (node.nodeType === Node.TEXT_NODE) {
|
||||
return node.textContent;
|
||||
}
|
||||
|
||||
if (node.nodeType === Node.ELEMENT_NODE) {
|
||||
const tagName = node.tagName.toLowerCase();
|
||||
|
||||
switch (tagName) {
|
||||
case 'h1': return '# ' + node.textContent;
|
||||
case 'h2': return '## ' + node.textContent;
|
||||
case 'h3': return '### ' + node.textContent;
|
||||
case 'h4': return '#### ' + node.textContent;
|
||||
case 'h5': return '##### ' + node.textContent;
|
||||
case 'h6': return '###### ' + node.textContent;
|
||||
case 'p':
|
||||
// Handle paragraphs with potential inline formatting
|
||||
const childText = Array.from(node.childNodes).map(processNode).join('');
|
||||
return childText;
|
||||
case 'strong': case 'b':
|
||||
return '**' + node.textContent + '**';
|
||||
case 'em': case 'i':
|
||||
return '*' + node.textContent + '*';
|
||||
case 'code':
|
||||
return '`' + node.textContent + '`';
|
||||
case 'pre':
|
||||
// Handle code blocks
|
||||
const codeContent = node.textContent;
|
||||
return '```\\n' + codeContent + '\\n```';
|
||||
case 'blockquote':
|
||||
const quoteLines = node.textContent.split('\\n');
|
||||
return quoteLines.map(line => '> ' + line).join('\\n');
|
||||
case 'ul':
|
||||
// Handle unordered lists
|
||||
const ulItems = Array.from(node.querySelectorAll('li'));
|
||||
return ulItems.map(li => '- ' + li.textContent).join('\\n');
|
||||
case 'ol':
|
||||
// Handle ordered lists
|
||||
const olItems = Array.from(node.querySelectorAll('li'));
|
||||
return olItems.map((li, index) => (index + 1) + '. ' + li.textContent).join('\\n');
|
||||
case 'br':
|
||||
return '\\n';
|
||||
default:
|
||||
return node.textContent;
|
||||
}
|
||||
}
|
||||
|
||||
return '';
|
||||
};
|
||||
|
||||
// Process each child node and add appropriate spacing
|
||||
const nodes = Array.from(temp.childNodes);
|
||||
nodes.forEach((node, index) => {
|
||||
const result = processNode(node);
|
||||
if (result.trim()) {
|
||||
if (index > 0 && markdown.trim()) {
|
||||
markdown += '\\n\\n';
|
||||
}
|
||||
markdown += result;
|
||||
}
|
||||
});
|
||||
|
||||
return markdown.trim();
|
||||
}
|
||||
|
||||
setupKeyboardShortcuts() {
|
||||
@@ -563,6 +966,11 @@ class DocumentManager:
|
||||
}
|
||||
|
||||
getMarkdownContent() {
|
||||
// If no edits have been made, return the original markdown content
|
||||
if (!this.hasEdits) {
|
||||
return markdownContent;
|
||||
}
|
||||
|
||||
// Reconstruct markdown content from the current state of sections
|
||||
const content = document.getElementById('markdown-content');
|
||||
if (!content) {
|
||||
@@ -574,35 +982,72 @@ class DocumentManager:
|
||||
const sections = content.querySelectorAll('.markitect-section-editable');
|
||||
let reconstructed = '';
|
||||
|
||||
sections.forEach(section => {
|
||||
const tagName = section.tagName.toLowerCase();
|
||||
const text = section.textContent.trim();
|
||||
sections.forEach(section => {{
|
||||
// Handle edited wrappers differently
|
||||
if (section.hasAttribute('data-edited')) {{
|
||||
// For edited sections, convert the child elements back to markdown
|
||||
const childElements = section.children;
|
||||
for (let i = 0; i < childElements.length; i++) {{
|
||||
const child = childElements[i];
|
||||
const tagName = child.tagName.toLowerCase();
|
||||
const text = child.textContent.trim();
|
||||
|
||||
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') {
|
||||
const items = section.querySelectorAll('li');
|
||||
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';
|
||||
}
|
||||
});
|
||||
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') {{
|
||||
const items = child.querySelectorAll('li');
|
||||
items.forEach(item => {{
|
||||
reconstructed += '- ' + item.textContent.trim() + '\\n';
|
||||
}});
|
||||
reconstructed += '\\n';
|
||||
}} else if (tagName === 'ol') {{
|
||||
const items = child.querySelectorAll('li');
|
||||
items.forEach((item, index) => {{
|
||||
reconstructed += (index + 1) + '. ' + item.textContent.trim() + '\\n';
|
||||
}});
|
||||
reconstructed += '\\n';
|
||||
}} else {{
|
||||
reconstructed += text + '\\n\\n';
|
||||
}}
|
||||
}}
|
||||
}} else {{
|
||||
// Handle regular sections
|
||||
const tagName = section.tagName.toLowerCase();
|
||||
const text = section.textContent.trim();
|
||||
|
||||
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') {{
|
||||
const items = section.querySelectorAll('li');
|
||||
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';
|
||||
}}
|
||||
}}
|
||||
}});
|
||||
|
||||
return reconstructed.trim();
|
||||
}
|
||||
@@ -612,26 +1057,155 @@ class DocumentManager:
|
||||
}
|
||||
}
|
||||
|
||||
let markitectEditor;"""
|
||||
let markitectEditor;
|
||||
|
||||
// Control panel toggle functionality
|
||||
function toggleControlPanel() {
|
||||
const panel = document.getElementById('markitect-control-panel');
|
||||
if (panel) {
|
||||
panel.classList.toggle('expanded');
|
||||
}
|
||||
}
|
||||
|
||||
// Auto-close panel when clicking outside
|
||||
document.addEventListener('click', function(event) {
|
||||
const panel = document.getElementById('markitect-control-panel');
|
||||
if (panel && panel.classList.contains('expanded')) {
|
||||
if (!panel.contains(event.target)) {
|
||||
panel.classList.remove('expanded');
|
||||
}
|
||||
}
|
||||
});"""
|
||||
|
||||
# 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 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>
|
||||
<div id="error-text" style="margin-top: 4px; color: #666;"></div>
|
||||
<details style="margin-top: 8px;">
|
||||
<summary style="cursor: pointer; color: #1976d2;">🐛 Help us fix this issue</summary>
|
||||
<div style="margin-top: 8px; font-size: 12px; color: #666;">
|
||||
Please report this error with your browser info:
|
||||
<br>📋 Browser: <span id="browser-info"></span>
|
||||
<br>🔗 Create issue: <a href="https://github.com/anthropics/markitect/issues/new" target="_blank" style="color: #1976d2;">GitHub Issues</a>
|
||||
<!-- Floating Control Panel -->
|
||||
<div id="markitect-control-panel" class="markitect-control-panel">
|
||||
<!-- Control Ribbon - Always Visible -->
|
||||
<div class="markitect-control-ribbon" onclick="toggleControlPanel()" title="MarkiTect Editor Controls">
|
||||
📝
|
||||
</div>
|
||||
|
||||
<!-- Panel Header -->
|
||||
<div class="markitect-panel-header">
|
||||
<h3 class="markitect-panel-title">📝 MarkiTect Editor</h3>
|
||||
<p class="markitect-panel-version">v{version_info}</p>
|
||||
<button class="markitect-panel-close" onclick="toggleControlPanel()" title="Close panel">×</button>
|
||||
</div>
|
||||
|
||||
<!-- Panel Body -->
|
||||
<div class="markitect-panel-body">
|
||||
<!-- Status Section -->
|
||||
<div class="markitect-status-section">
|
||||
<div id="status-indicator" class="markitect-status-indicator loading">
|
||||
<span class="markitect-status-icon">⏳</span>
|
||||
<div class="markitect-status-text" id="status-message">Loading edit capabilities...</div>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<!-- Error Details (hidden by default) -->
|
||||
<div id="error-details" class="markitect-error-details">
|
||||
<div class="markitect-error-title">❌ Edit Mode Failed</div>
|
||||
<div class="markitect-error-text" id="error-text"></div>
|
||||
<div class="markitect-error-help">
|
||||
📋 Browser: <span id="browser-info"></span><br>
|
||||
🔗 <a href="https://github.com/anthropics/markitect/issues/new" target="_blank" style="color: #1976d2;">Report Issue</a>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Controls Section -->
|
||||
<div class="markitect-controls-section">
|
||||
<div class="markitect-controls-grid">
|
||||
<button class="markitect-control-btn" onclick="markitectEditor.save()" title="Download edited content">
|
||||
<span class="icon">💾</span>
|
||||
Save & Download
|
||||
</button>
|
||||
<button class="markitect-control-btn secondary" onclick="markitectEditor.togglePreview()" title="Toggle preview mode">
|
||||
<span class="icon">👁️</span>
|
||||
Preview
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<div class="markitect-save-info">
|
||||
<div id="save-status">Ready to save</div>
|
||||
<div style="margin-top: 4px; opacity: 0.8;">Saves as: filename-edited-YYYY-MM-DD-HH-MM-SS.md</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>"""
|
||||
|
||||
@@ -659,26 +1233,80 @@ 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');
|
||||
const statusIndicator = document.getElementById('status-indicator');
|
||||
const statusIcon = document.querySelector('.markitect-status-icon');
|
||||
|
||||
if (statusMsg) {{
|
||||
statusMsg.textContent = message;
|
||||
statusMsg.style.color = isError ? '#c62828' : '#1976d2';
|
||||
}}
|
||||
|
||||
if (statusIndicator) {{
|
||||
// Remove all status classes
|
||||
statusIndicator.classList.remove('loading', 'error');
|
||||
|
||||
if (isError) {{
|
||||
statusIndicator.classList.add('error');
|
||||
if (statusIcon) statusIcon.textContent = '❌';
|
||||
}} else if (message.includes('Loading') || message.includes('Initializing')) {{
|
||||
statusIndicator.classList.add('loading');
|
||||
if (statusIcon) statusIcon.textContent = '⏳';
|
||||
}} else {{
|
||||
// Success state
|
||||
if (statusIcon) statusIcon.textContent = '✅';
|
||||
}}
|
||||
}}
|
||||
}}
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ from typing import Dict, Any
|
||||
|
||||
from markitect.plugins.base import CommandPlugin, PluginMetadata, PluginType
|
||||
from markitect.plugins.decorators import register_plugin
|
||||
from markitect.document_manager import DocumentManager
|
||||
# DocumentManager removed - using CleanDocumentManager directly
|
||||
from markitect.serializer import ASTSerializer
|
||||
|
||||
|
||||
@@ -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:")
|
||||
@@ -1659,7 +1659,7 @@ def md_list_command(ctx, output_format, names_only):
|
||||
@click.option('--css', type=click.Path(),
|
||||
help='Custom CSS file to include')
|
||||
@click.option('--edit', is_flag=True,
|
||||
help='Open in live edit mode with preview')
|
||||
help='Open in interactive edit mode with stable section editing')
|
||||
@click.option('--editor-theme', default='github',
|
||||
type=click.Choice(['github', 'monokai', 'tomorrow', 'dark']),
|
||||
help='Editor theme for live edit mode (default: github)')
|
||||
@@ -1704,17 +1704,20 @@ def md_render_command(ctx, input_file, output, template, css, edit, editor_theme
|
||||
ensure_publication_directory(pub_dir)
|
||||
output_path = pub_dir / get_output_filename(input_path)
|
||||
|
||||
# Initialize document manager
|
||||
doc_manager = DocumentManager(config.get('db_manager'))
|
||||
# Initialize clean document manager
|
||||
from markitect.clean_document_manager import CleanDocumentManager
|
||||
doc_manager = CleanDocumentManager(config.get('db_manager'))
|
||||
|
||||
# Render the file
|
||||
if edit:
|
||||
# Live edit mode - generate HTML with editing capabilities
|
||||
# Edit mode - generate HTML with editing capabilities
|
||||
result = doc_manager.render_file(input_file, str(output_path),
|
||||
template=template, css=css,
|
||||
edit_mode=True, editor_theme=editor_theme,
|
||||
edit_mode=True,
|
||||
editor_theme=editor_theme,
|
||||
keyboard_shortcuts=keyboard_shortcuts)
|
||||
click.echo(f"✓ Rendered with editing capabilities to: {output_path}")
|
||||
|
||||
click.echo(f"✓ Rendered with interactive editing capabilities to: {output_path}")
|
||||
|
||||
if config.get('verbose', False):
|
||||
click.echo(f"Editor theme: {editor_theme}")
|
||||
@@ -2980,4 +2983,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]
|
||||
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
||||
|
||||
[project]
|
||||
name = "markitect"
|
||||
version = "0.3.0"
|
||||
version = "0.5.0"
|
||||
description = "Advanced Markdown engine for structured content"
|
||||
readme = "README.md"
|
||||
requires-python = ">=3.8"
|
||||
|
||||
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-control-panel"' 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"])
|
||||
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