markitect-main/DEPENDENCIES.md

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
• Capability Dependencies
• Development Dependencies
• JavaScript Dependencies
• Dependency Criticality Matrix
• 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:

[project.dependencies]
release-management = {path = "../markitect-main/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