madomeda/STRUCTURE.md

title, created, status, priority, published, tags, reviewers

title	created	status	priority	published	tags	reviewers
Madomeda Project Structure	2025-10-23T18:33:48+02:00	draft	5	false

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:

{
  "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

# 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