Test User
162 lines
4.7 KiB
Markdown
162 lines
4.7 KiB
Markdown
---
|
|
title: Madomeda Project Structure
|
|
created: '2025-10-23T18:33:48+02:00'
|
|
status: draft
|
|
priority: 5
|
|
published: false
|
|
tags: []
|
|
reviewers: []
|
|
---
|
|
# 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
|