From 72195d0aa5fb2f3a22e1c6650df9687f8721ed9f Mon Sep 17 00:00:00 2001 From: Bernd Worsch Date: Mon, 22 Sep 2025 00:37:04 +0200 Subject: [PATCH] docs: Add ProjectStatusDigest.md with automated update target MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create comprehensive project status digest documentation - Add make update-digest target with Claude Code prerequisite check - Include current architecture, features, and development approach - Document repository structure and getting started guide - Add digest update workflow for version releases 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- Makefile | 21 ++++++- ProjectStatusDigest.md | 130 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 150 insertions(+), 1 deletion(-) create mode 100644 ProjectStatusDigest.md diff --git a/Makefile b/Makefile index cb9f7d44..ae9522c5 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,7 @@ # MarkiTect - Advanced Markdown Engine # Makefile for common development tasks -.PHONY: help setup install test build clean update status dev lint format check-deps venv-status +.PHONY: help setup install test build clean update status dev lint format check-deps venv-status update-digest # Default target help: @@ -28,6 +28,9 @@ help: @echo " status - Show git status for repo and submodules" @echo " clean - Clean build artifacts" @echo " check-deps - Check dependency status" + @echo "" + @echo "Documentation:" + @echo " update-digest - Update ProjectStatusDigest.md (requires Claude Code)" # Python and virtual environment setup PYTHON := python3 @@ -155,3 +158,19 @@ check-deps: $(VENV)/bin/activate @echo "" @echo "Project dependencies:" $(VENV_PIP) check + +# Update project status digest (requires Claude Code) +update-digest: + @echo "🔍 Checking for Claude Code availability..." + @if ! command -v claude >/dev/null 2>&1; then \ + echo "❌ Claude Code not found in PATH"; \ + echo " This target requires Claude Code CLI to be installed"; \ + echo " Visit: https://claude.ai/code for installation instructions"; \ + exit 1; \ + fi + @echo "✅ Claude Code found" + @echo "📝 Updating ProjectStatusDigest.md..." + @echo " Please ask Claude Code to update the project digest based on current state" + @echo " Command: 'Please update ProjectStatusDigest.md with the current project state'" + @echo "" + @echo "💡 Tip: You can also manually edit ProjectStatusDigest.md if needed" diff --git a/ProjectStatusDigest.md b/ProjectStatusDigest.md new file mode 100644 index 00000000..6986e687 --- /dev/null +++ b/ProjectStatusDigest.md @@ -0,0 +1,130 @@ +# MarkiTect Project - Status Digest + +**Version:** 0.1.0 +**Last Updated:** 2025-09-22 +**Tagline:** "Your Markdown, Redefined" + +## Core Vision + +Transform Markdown from plain text into intelligent, structured, reusable data with schema validation and automation capabilities. + +## Architecture Overview + +### MarkiTect Library (Python Core) +- **Reusable Python package** designed for CLI, service offerings, and third-party integration +- **TDD approach** with comprehensive test coverage +- **Modern packaging** using `pyproject.toml` and semantic versioning +- **Minimal dependencies** with `markdown-it-py` as primary parser + +### MarkiTect CLI (Command-Line Interface) +- **SQLite database** for temporary, in-memory operations +- **GraphQL API** using `graphene` library for read/write operations +- **SQLAlchemy ORM** for data modeling (MarkdownFile, SchemaFile, AST content) +- **JSON Schema validation** using `jsonschema` library + +## Key Features & Components + +### Core Functionality +- **AbstractSyntaxTree** processing and manipulation +- **MarkdownParser** using `markdown-it-py` for detailed AST generation +- **JsonSchemaValidator** for enforcing document structure +- **ChunkInclusion** system for modular content composition +- **StaticSiteGenerator** integration capabilities + +### Schema Operations +- **Generate schemas** from existing Markdown at specified nesting depths +- **Validate Markdown** against defined schemas +- **Generate stub files** from schemas with placeholder content +- **InclusionStub** handling for modular document architecture + +### GraphQL Interface +- **Query operations** for retrieving Markdown files, schemas, and AST data +- **Mutation operations** for adding/updating content in database +- **Real-time validation** and schema checking + +## Development Approach + +### Test-Driven Development +- Comprehensive **TDD guide** integrated into project workflow +- **Test-first approach** for all new features +- **High coverage** requirements for public APIs +- **Integration tests** for key workflows + +### Markdown Feature Support (MF-1 through MF-10) +Complete specification coverage including: +- Headings and sections structure +- Text formatting (bold, italic, strikethrough) +- Lists (ordered, unordered, task lists) +- Links, images, and media handling +- Code blocks and syntax highlighting +- Tables and complex formatting +- Footnotes and reference systems + +## Project Status + +### Current State +- **Early development phase** with foundational parser implemented +- **Comprehensive documentation** and architecture planning complete +- **Build system** with sophisticated Makefile for development workflow +- **Virtual environment management** with activation detection + +### Social Integration +- **CoulombSocial participation** since September 2025 +- **GitLab issues integration** for use case tracking +- **Open-source development** model with collaborative wiki + +## Technical Foundation + +### Development Tools +- **Python 3.8+** with modern tooling (Black, Ruff, mypy) +- **Make-based workflow** with intelligent environment detection +- **Git submodules** for wiki documentation management +- **Automated testing** and CI/CD pipeline planning + +### Brand Identity +- **Professional visual identity** with 3D "M" logo incorporating Markdown symbols +- **Color palette**: Deep teal/navy (primary), vibrant orange, lime green +- **Core pillars**: Structural Integrity, Consistency, Reusability, Automation + +## Repository Structure + +``` +markitect_project/ +├── markitect/ # Main Python package +│ ├── __init__.py +│ └── parser.py # Core parsing functionality +├── tests/ # Test suite +│ └── test_parser.py # Parser tests +├── wiki/ # Git submodule with comprehensive documentation +├── Makefile # Development workflow automation +├── pyproject.toml # Python package configuration +├── ProjectStatusDigest.md # This document +└── README.md # Project overview +``` + +## Getting Started + +1. **Environment Setup:** + ```bash + make setup # Create venv and install dependencies + make venv-status # Check environment activation state + ``` + +2. **Development Workflow:** + ```bash + make test # Run test suite + make update # Pull latest changes from upstream + make status # Check git status + ``` + +3. **Building:** + ```bash + make build # Build the package + make clean # Clean build artifacts + ``` + +--- + +MarkiTect represents a significant evolution toward treating documentation as **structured, validatable, and reusable data** rather than simple text files, with robust tooling for large-scale content management and automation. + +> **Note:** This digest is maintained using Claude Code. Run `make update-digest` to refresh with latest project information. \ No newline at end of file