docs: Added dependencies documentation

2026-01-23 13:25:12 +01:00
parent 72519bf83d
commit 6ebcc0f60e
1 changed files with 552 additions and 0 deletions
--- a/DEPENDENCIES.md
+++ b/DEPENDENCIES.md
@@ -0,0 +1,552 @@
+# Dependencies
+
+This document catalogs all dependencies used in the markitect project, describing how each library and tool is utilized. This helps coordinate dependencies with sister projects like referitect and maintain consistency across the ecosystem.
+
+## Table of Contents
+
+- [Core Dependencies](#core-dependencies)
+- [Capability Dependencies](#capability-dependencies)
+- [Development Dependencies](#development-dependencies)
+- [JavaScript Dependencies](#javascript-dependencies)
+- [Dependency Criticality Matrix](#dependency-criticality-matrix)
+- [Coordination Guidelines for Sister Projects](#coordination-guidelines-for-sister-projects)
+
+---
+
+## Core Dependencies
+
+These dependencies are required for markitect's core functionality.
+
+### markdown-it-py
+**Version:** Latest
+**Criticality:** CRITICAL
+**Purpose:** Core markdown parsing engine
+
+**Usage:**
+- Converts markdown content to Abstract Syntax Trees (AST)
+- Enables table parsing with `.enable(['table'])`
+- Uses CommonMark parser with token conversion
+- Foundation for all markdown processing operations
+
+**Files:** `markitect/parser.py`
+
+**Why this matters:** This is the primary markdown parser. Sister projects should use the same parser for consistent AST structure and compatibility.
+
+---
+
+### PyYAML
+**Version:** Latest
+**Criticality:** CRITICAL
+**Purpose:** YAML configuration parsing and serialization
+
+**Usage:**
+- Parses YAML frontmatter from markdown documents
+- Loads configuration files for themes and workspaces
+- Supports YAML-based schema definitions
+- Safe loading of untrusted YAML data (`yaml.safe_load()`)
+- Configuration serialization and deserialization
+
+**Files:**
+- `markitect/cli.py`
+- `markitect/schema_loader.py`
+- `markitect/matter_frontmatter/parser.py`
+- `markitect/config_manager.py`
+- `markitect/production/configuration.py`
+- `markitect/serializer.py`
+- Multiple capability files
+
+**Why this matters:** YAML is the primary configuration format. Consistent YAML handling ensures config compatibility across projects.
+
+---
+
+### click
+**Version:** >=8.0.0
+**Criticality:** CRITICAL
+**Purpose:** Command-line interface framework
+
+**Usage:**
+- Primary CLI framework for all command-line commands
+- Command groups, options, and decorators for `markitect` CLI
+- Table output formatting (combined with tabulate)
+- Command organization and help system
+- Error handling and context management
+- Profile management, finance tracking, release management, issue tracking commands
+
+**Files:** 63 files including:
+- `markitect/cli.py` (main CLI)
+- `markitect/cli_utils.py`
+- `markitect/asset_commands.py`
+- `markitect/profile/commands.py`
+- `markitect/finance/cli.py`
+- `capabilities/release-management/src/release_management/cli/main.py`
+- `capabilities/kaizen-agentic/src/kaizen_agentic/cli.py`
+- Issue tracker CLI commands
+
+**Why this matters:** Click provides consistent CLI UX. Sister projects using Click will have familiar command patterns and help output.
+
+---
+
+### tabulate
+**Version:** >=0.9.0
+**Criticality:** HIGH
+**Purpose:** ASCII table formatting for CLI output
+
+**Usage:**
+- Formats database query results as ASCII tables
+- Provides multiple table formats: grid, simple, fancy
+- Used in CLI output for:
+  - Database command results
+  - Performance metrics display
+  - Status reports
+  - File listings
+  - Financial tracking output
+
+**Files:**
+- `markitect/cli.py`
+- `markitect/cli_utils.py`
+- `markitect/plugins/builtin/markdown_commands.py`
+- `markitect/finance/cli.py`
+- `markitect/finance/worktime_commands.py`
+
+**Why this matters:** Consistent table formatting across all CLI tools provides professional, readable output.
+
+---
+
+### jsonpath-ng
+**Version:** >=1.5.0
+**Criticality:** MEDIUM
+**Purpose:** JSONPath querying for AST navigation
+
+**Usage:**
+- XPath-like navigation through AST structures
+- Query parsing with `jsonpath-ng.parse()`
+- Fallback simple dot-notation implementation if import fails
+- Advanced query paradigm for structural queries
+- Supports filters, recursive descent, array wildcards
+
+**Files:**
+- `markitect/query_paradigms/paradigms/jsonpath_paradigm.py`
+- `markitect/ast_service.py`
+- `markitect/graphql/resolvers.py`
+
+**Why this matters:** Provides advanced AST querying. Optional but useful for complex document transformations.
+
+---
+
+### aiohttp
+**Version:** >=3.8.0
+**Criticality:** MEDIUM
+**Purpose:** Async HTTP client for API interactions
+
+**Usage:**
+- HTTP session management with connection pooling
+- Async/await pattern support for concurrent requests
+- TCP connection optimization (limit, per-host limits)
+- Timeout and keepalive configuration
+- Authentication header management for API calls
+- Gitea API integration
+- Health check mechanisms
+- Proper resource cleanup with async context managers
+
+**Files:**
+- `infrastructure/connection_manager.py`
+
+**Why this matters:** Enables performant async I/O for API operations. Critical for scalable network operations.
+
+---
+
+### toml
+**Version:** Latest
+**Criticality:** LOW-MEDIUM
+**Purpose:** TOML configuration format parsing
+
+**Usage:**
+- Parses TOML-formatted frontmatter in markdown files
+- Alternative to YAML for configuration syntax
+- Format detection: tries TOML if content has '=' and brackets
+- Graceful fallback to YAML if TOML parsing fails
+
+**Files:**
+- `markitect/matter_frontmatter/parser.py`
+- `capabilities/release-management/src/release_management/summary/generator.py`
+- `capabilities/release-management/src/release_management/utils/validation.py`
+- `capabilities/release-management/src/release_management/registries/factory.py`
+
+**Why this matters:** Provides TOML support for users preferring TOML over YAML. Optional with fallback mechanisms.
+
+---
+
+### setuptools-scm
+**Version:** >=8.0.0
+**Criticality:** CRITICAL
+**Purpose:** Git-based version management
+
+**Usage:**
+- Automatic version derivation from git tags
+- Generates `_version.py` file during build
+- Supports semantic versioning (python-simplified-semver scheme)
+- Git tag format: `v*` (matches v0.11.0, v1.0.0, etc.)
+- No local version suffix in scheme
+- Used by release-management for version operations
+
+**Files:**
+- `markitect/__version__.py`
+- `capabilities/release-management/src/release_management/utils/version.py`
+- `capabilities/release-management/src/release_management/cli/main.py`
+- `capabilities/release-management/src/release_management/utils/validation.py`
+- `capabilities/release-management/src/release_management/core/builder.py`
+
+**Why this matters:** Single source of truth for versioning. Critical for coordinated releases across sister projects.
+
+---
+
+## Capability Dependencies
+
+Dependencies specific to optional capabilities. These extend markitect's functionality.
+
+### markitect-utils
+**Location:** `capabilities/markitect-utils`
+**Dependencies:** None (intentionally dependency-free)
+**Purpose:** Utility functions capability for testing ComposableRepositoryParadigm
+
+---
+
+### markitect-content
+**Location:** `capabilities/markitect-content`
+**Dependencies:**
+- `click>=8.0.0` - CLI commands for content parsing and statistics
+
+**Purpose:** Content parsing and statistics capability
+
+---
+
+### kaizen-agentic
+**Location:** `capabilities/kaizen-agentic`
+**Dependencies:**
+- `pyyaml>=6.0` - Agent configuration files
+- `click>=8.0.0` - CLI interface
+- `pydantic>=2.0.0` - Data validation for agent configs
+
+**Purpose:** AI agent development framework with continuous improvement patterns
+
+**Key Usage:**
+- Agent configuration via YAML
+- CLI for agent management (`kaizen-agentic` command)
+- Pydantic models for validated agent configurations
+
+---
+
+### release-management
+**Location:** `capabilities/release-management`
+**Dependencies:**
+- `click>=8.0.0` - CLI commands
+- `requests>=2.25.0` - Gitea package registry API
+- `setuptools-scm>=8.0.0` - Version management
+- `build>=0.8.0` - Python package building
+- `packaging>=21.0` - Version parsing and comparison
+- `pyyaml>=6.0` - Configuration files
+- `pydantic>=2.0.0` - Configuration validation
+
+**Purpose:** Comprehensive release management for Python projects
+
+**Key Usage:**
+- Package building (wheel, sdist)
+- Git tag creation and management
+- Gitea package registry publishing
+- Version validation and semantic versioning
+- Release configuration via YAML
+
+**Entry Points:** `release`, `release-manager` commands
+
+---
+
+### testdrive-jsui
+**Location:** `capabilities/testdrive-jsui`
+**Dependencies:**
+- `pytest>=7.0.0` - Test framework
+- `pytest-xvfb>=3.0.0` - Headless browser testing
+- `selenium>=4.0.0` - Browser automation
+- `pathlib2>=2.3.0` (Python <3.4) - Path handling
+
+**Purpose:** JavaScript UI testing framework capability
+
+**Key Usage:**
+- Browser-based testing infrastructure
+- Headless browser execution
+- Selenium WebDriver integration
+- JavaScript test execution from Python
+
+**Note:** Primarily a JavaScript library with Python adapter. See JavaScript Dependencies section.
+
+---
+
+### issue-facade (universal-issue-tracker)
+**Location:** `_issue-tracking/issue-facade`
+**Dependencies:**
+- `click>=8.0.0` - CLI framework
+- `requests>=2.25.0` - Remote backend API calls (Gitea, GitHub)
+- `python-dateutil>=2.8.0` - Date/time parsing
+
+**Purpose:** Backend-agnostic issue tracking with plugin architecture
+
+**Key Usage:**
+- Unified CLI for multiple issue backends (Gitea, GitHub, local SQLite)
+- REST API integration
+- Date parsing for issue timestamps
+- Synchronization between local and remote backends
+
+**Entry Points:** `issue`, `issue-tracker` commands
+
+---
+
+## Development Dependencies
+
+These dependencies are only required during development and testing.
+
+### Testing Frameworks
+- `pytest>=6.0.0` - Primary test framework
+- `pytest-cov>=2.0` - Coverage reporting
+- `pytest-mock>=3.0` - Mocking utilities
+- `pytest-randomly>=3.10.0` - Randomized test execution (kaizen-agentic)
+- `pytest-asyncio>=0.21.0` - Async test support (testdrive-jsui)
+- `pytest-timeout>=2.1.0` - Test timeout handling (testdrive-jsui)
+
+### Code Quality
+- `black>=22.0.0` - Code formatting (88 char line length)
+- `isort>=5.0` - Import sorting
+- `flake8>=5.0.0` - Linting (100 char max line length)
+- `mypy>=1.0.0` - Static type checking
+- `pre-commit>=2.0` - Git hooks
+
+### Build Tools
+- `setuptools>=64` - Python package building
+- `wheel` - Wheel package format
+- `build>=0.8.0` - PEP 517 build frontend
+
+### Documentation
+- `sphinx>=4.0` - Documentation generation (issue-facade)
+- `sphinx-rtd-theme>=1.0` - Read the Docs theme
+- `sphinx-click>=3.0` - Click command documentation
+
+---
+
+## JavaScript Dependencies
+
+These dependencies support browser-side functionality and JavaScript testing.
+
+### Runtime JavaScript Dependencies (Browser)
+
+#### marked.js
+**Version:** ^11.0.0 || ^12.0.0 || ^13.0.0 (peer dependency)
+**Criticality:** MEDIUM
+**Purpose:** Client-side markdown parsing
+
+**Usage:**
+- Real-time markdown rendering in browser
+- Loaded via CDN: `https://cdn.jsdelivr.net/npm/marked/marked.min.js`
+- Provides fallback if CDN fails
+- HTML generation from markdown content with `marked.parse()`
+
+**Files:**
+- `markitect/templates/edit-mode.html`
+- `markitect/templates/edit-mode-fixed.html`
+- `markitect/templates/document.html`
+
+**Why this matters:** Enables interactive markdown editing in browser. Sister projects with browser UI should use the same version for consistency.
+
+---
+
+### Node.js Development Dependencies
+
+Located in `capabilities/testdrive-jsui/package.json`:
+
+#### Build Tools
+- `rollup@^4.53.5` - Module bundler
+- `@rollup/plugin-babel@^6.1.0` - Babel transpilation
+- `@rollup/plugin-commonjs@^29.0.0` - CommonJS support
+- `@rollup/plugin-node-resolve@^16.0.3` - Node module resolution
+- `@rollup/plugin-terser@^0.4.4` - Code minification
+- `rollup-plugin-postcss@^4.0.2` - CSS processing
+
+#### Testing
+- `jest@^29.7.0` - JavaScript test framework
+- `jest-environment-jsdom@^29.7.0` - DOM environment for tests
+- `babel-jest@^29.7.0` - Babel integration for Jest
+- `jsdom@^23.0.0` - DOM implementation for Node.js
+
+#### Linting and Formatting
+- `eslint@^8.57.0` - JavaScript linter
+- `eslint-config-standard@^17.1.0` - Standard style guide
+- `eslint-plugin-jest@^27.6.0` - Jest-specific rules
+
+#### CSS Processing
+- `postcss@^8.5.6` - CSS transformation
+- `postcss-import@^16.1.1` - CSS import handling
+- `autoprefixer@^10.4.23` - Vendor prefix automation
+- `cssnano@^7.1.2` - CSS minification
+
+#### Transpilation
+- `@babel/core@^7.23.0` - JavaScript compiler
+- `@babel/preset-env@^7.23.0` - Smart presets for target environments
+
+---
+
+## Dependency Criticality Matrix
+
+| Criticality | Dependencies | Impact if Missing |
+|:---|:---|:---|
+| **CRITICAL** | markdown-it-py, PyYAML, click, setuptools-scm | Project cannot function |
+| **HIGH** | tabulate | CLI output severely degraded |
+| **MEDIUM** | jsonpath-ng, aiohttp, pydantic, requests, marked.js | Features unavailable, fallbacks exist |
+| **LOW-MEDIUM** | toml | Optional format support |
+| **DEV-ONLY** | pytest, black, flake8, mypy, jest, eslint | Development/testing affected only |
+
+---
+
+## Coordination Guidelines for Sister Projects
+
+When developing referitect or other sister projects, follow these guidelines to maintain ecosystem consistency:
+
+### Mandatory Alignment
+These dependencies MUST match versions for compatibility:
+
+1. **markdown-it-py** - Ensures consistent AST structure across projects
+2. **PyYAML** - Enables shared configuration formats
+3. **setuptools-scm** - Coordinated versioning strategy
+4. **click** - Consistent CLI patterns and user experience
+
+### Recommended Alignment
+These dependencies SHOULD match for consistency:
+
+1. **tabulate** - Uniform table output across CLIs
+2. **pydantic** - Shared data validation patterns
+3. **marked.js** - Consistent browser-side rendering
+4. **black/flake8/mypy** - Unified code quality standards
+
+### Optional Dependencies
+Projects may choose different versions or alternatives:
+
+1. **jsonpath-ng** - If advanced querying not needed
+2. **aiohttp** vs. **requests** - Choose based on sync/async needs
+3. **toml** - If TOML support not required
+4. **selenium/pytest-xvfb** - If browser testing not needed
+
+### Version Pinning Strategy
+
+**Core dependencies:** Pin to minor versions (e.g., `click>=8.0.0`)
+- Allows patch updates for security fixes
+- Prevents breaking changes from major updates
+
+**Development dependencies:** Pin to specific versions in lockfile
+- Ensures reproducible development environments
+- Update deliberately during maintenance windows
+
+**Build dependencies:** Pin to exact versions (e.g., `setuptools>=64`)
+- Ensures reproducible builds
+- Critical for release management
+
+### Capability Reuse
+
+Sister projects can reuse these capabilities directly:
+
+1. **release-management** - Use for package publishing
+2. **kaizen-agentic** - Share agent development patterns
+3. **issue-facade** - Unified issue tracking across projects
+4. **testdrive-jsui** - Browser-based markdown editor
+
+Install capabilities via local file references:
+```toml
+[project.dependencies]
+release-management = {path = "../markitect_project/capabilities/release-management"}
+```
+
+### Shared Infrastructure
+
+Both projects can share:
+
+1. **Configuration schemas** - YAML/TOML format definitions
+2. **CLI patterns** - Click command structure
+3. **AST utilities** - Markdown parsing and transformation
+4. **Testing infrastructure** - pytest configuration and fixtures
+
+### Dependency Updates
+
+When updating shared dependencies:
+
+1. Update in markitect first
+2. Test thoroughly
+3. Document breaking changes in CHANGELOG.md
+4. Coordinate update in referitect
+5. Update this DEPENDENCIES.md file
+
+---
+
+## Dependency Graph
+
+```
+markitect (core)
+├── markdown-it-py (AST generation)
+├── PyYAML (config parsing)
+├── click (CLI framework)
+│   └── tabulate (table output)
+├── jsonpath-ng (AST querying)
+├── aiohttp (async HTTP)
+├── toml (TOML parsing)
+└── setuptools-scm (versioning)
+
+capabilities/
+├── markitect-utils (no deps)
+├── markitect-content
+│   └── click
+├── kaizen-agentic
+│   ├── pyyaml
+│   ├── click
+│   └── pydantic
+├── release-management
+│   ├── click
+│   ├── requests
+│   ├── setuptools-scm
+│   ├── build
+│   ├── packaging
+│   ├── pyyaml
+│   └── pydantic
+├── testdrive-jsui
+│   ├── pytest
+│   ├── pytest-xvfb
+│   ├── selenium
+│   └── JavaScript deps:
+│       ├── marked (peer)
+│       ├── jest (dev)
+│       ├── rollup (dev)
+│       └── eslint (dev)
+└── issue-facade
+    ├── click
+    ├── requests
+    └── python-dateutil
+```
+
+---
+
+## License Compatibility
+
+All dependencies use OSI-approved licenses compatible with MIT:
+
+- **MIT License:** markdown-it-py, click, tabulate, jsonpath-ng, aiohttp, pydantic, marked.js, jest, rollup
+- **Apache 2.0:** requests, setuptools-scm
+- **BSD License:** PyYAML, selenium
+- **PSF License:** python-dateutil (Python Software Foundation)
+
+No GPL or copyleft licenses used - all dependencies are permissively licensed.
+
+---
+
+## Version History
+
+- **v0.11.0** (2026-01-07): Initial DEPENDENCIES.md creation for referitect coordination
+- Future updates will track dependency changes and version bumps
+
+---
+
+**Maintained by:** MarkiTect Project Team
+**Last Updated:** 2026-01-07
+**For Questions:** See main README.md or open an issue