Remove test file

2025-10-23 18:33:48 +02:00
parent 0463d73ef9
commit 8c4f612e4b
33 changed files with 2718 additions and 25 deletions
@@ -0,0 +1,152 @@
+# Madomeda Project Structure
+
+## Overview
+Madomeda is a Python tool for managing markdown frontmatter in git repositories with rule-based normalization, template-driven generation, and optional LLM assistance.
+
+## Project Structure
+
+```
+madomeda/
+├── madomeda.py              # Main entry point
+├── requirements.txt         # Python dependencies
+├── .env                     # LLM configuration
+├── README.md               # Project documentation
+├── USAGE.md                # Usage examples
+│
+├── core/                   # Core modules
+│   ├── __init__.py
+│   ├── database.py         # SQLite database management
+│   ├── repository.py       # Git repository operations
+│   ├── frontmatter.py      # YAML frontmatter parsing
+│   ├── rules.py            # Rule engine
+│   ├── template.py         # Template management
+│   ├── llm.py             # LLM integration
+│   ├── changelog.py        # Changelog management
+│   └── processor.py        # Main processing logic
+│
+├── templates/              # Frontmatter templates
+│   └── default.json        # Default template
+│
+├── rules/                  # Rule definitions
+│   ├── tags_normalization.json
+│   ├── tag_to_tags.json
+│   └── lowercase_keys.json
+│
+├── prompts/                # LLM prompts
+│   └── default.txt         # Default system prompt
+│
+├── madomeda.db            # SQLite database (gitignored)
+└── madomeda_changelog.txt  # Change log
+
+```
+
+## Key Features
+
+### 1. Git Integration
+- Tracks markdown files via git ls-files
+- Extracts commit history (authors, dates, hashes)
+- Ignores hidden files/folders (starting with '.')
+- Respects --ignore-paths arguments
+
+### 2. Database Management
+- SQLite database (`madomeda.db`)
+- Tables: files, frontmatter, commits, tags
+- Tracks conformance status
+- Stores all frontmatter versions
+
+### 3. Rule Engine
+Rules are JSON files in the `rules/` folder:
+- **tags_normalization**: Converts tags to lowercase_with_underscores
+- **tag_to_tags**: Renames 'tag' key to 'tags'
+- **lowercase_keys**: All frontmatter keys must be lowercase
+
+### 4. Template System
+Templates define frontmatter structure with value strategies:
+- `heur`: Use heuristics (git history, document analysis)
+- `orig`: Use original frontmatter value
+- `ai <prompt>`: Use LLM with specified prompt
+
+Strategy priority: Options are tried left-to-right until one returns a value.
+
+Example template:
+```json
+{
+  "title": "heur|orig",
+  "created": "heur|orig",
+  "changed": "heur|orig",
+  "authors": "heur|orig",
+  "version": "heur|orig",
+  "tags": "heur|orig|ai default"
+}
+```
+
+### 5. LLM Integration
+- OpenAI-compatible API support
+- Structured output via JSON schema
+- Configurable via .env file
+- Fallback if API unavailable
+
+### 6. Heuristic Values
+- `title`: Extracted from # heading or filename
+- `created`: First commit date (ISO 8601)
+- `changed`: Latest commit date (ISO 8601)
+- `authors`: List of all contributors
+- `version`: Latest commit tag if exists, else short hash (7 chars)
+- `tags`: Normalized from original
+
+### 7. Changelog
+Format:
+```
+YYYY-MM-DD HH:MM:SS (commit: <hash>)
+  path/file.md - frontmatter updated
+  ...
+
+```
+
+## Command-Line Arguments
+
+- `--dir PATH`: Repository directory (default: current)
+- `--template NAME`: Template to use (default: 'default')
+- `--ignore-paths PATH...`: Paths to exclude
+- `--whatif`: Dry run mode
+- `--no-confirm`: Skip confirmation prompts
+- `--force`: Recreate all frontmatter
+
+## Processing Flow
+
+1. **Discovery**: Find tracked .md files via git
+2. **Parse**: Extract existing frontmatter
+3. **Store**: Save to database with timestamp
+4. **Git History**: Extract commit information
+5. **Normalize**: Apply rules to frontmatter
+6. **Check Conformance**: Compare with template
+7. **Build**: Generate new frontmatter from template
+8. **Warn**: Alert on metadata loss
+9. **Update**: Write to file and database
+10. **Log**: Record change in changelog
+
+## Installation
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Configure LLM (optional)
+# Edit .env with your OpenAI-compatible API settings
+
+# Run on current directory
+python madomeda.py --whatif
+```
+
+## Dependencies
+
+- PyYAML: YAML parsing
+- python-dotenv: Environment configuration
+- openai: LLM integration (optional)
+
+## Notes
+
+- Database and .env are gitignored
+- Rules/templates/prompts created automatically on first run
+- Empty tag lists are preserved (for template conformance)
+- Unicode output replaced with ASCII for Windows compatibility