mdflow 0.1.5

Markdown dependency analyzer — extract all dependencies, generate diagrams and charts

mdflow

AI Cost Tracking

• 🤖 LLM usage: $0.6000 (4 commits)
• 👤 Human dev: ~$200 (2.0h @ $100/h, 30min dedup)

Generated on 2026-05-03 using openrouter/qwen/qwen3-coder-next

---

Markdown dependency analyzer — extract all dependencies, generate diagrams and charts.

mdflow parses Markdown files and extracts every possible structural element: headings, links, fenced code blocks (including markpact:* embedded file references), list items, TOON/YAML quality sections, and document metadata. It then generates Mermaid diagrams, HTML reports, and Markdown summaries.

---

What it extracts

Element	Details
Headings	Full H1–H6 hierarchy, anchor slugs
Links	[text](href) — classified as internal / external / anchor / image
Code blocks	Language, content, line range, markpact:type path=... metadata
List items	Depth, parent heading, clean text
TOON sections	ALERTS, REFACTOR, HOTSPOTS, HEALTH, NEXT, RISKS, PIPELINES…
Document metadata	## Metadata key/value lists
Cross-doc dependencies	Links between files, markpact embedded file paths

---

Generated outputs

Output	Description
{stem}_report.html	Self-contained HTML report with all diagrams (Mermaid.js)
{stem}_report.md	Markdown summary with inline Mermaid
{stem}_heading_mindmap.mermaid	Mindmap of heading hierarchy
{stem}_section_flow.mermaid	Section flowchart with code/link annotations
{stem}_code_pie.mermaid	Pie chart of code blocks by language
{stem}_markpact_graph.mermaid	Graph of embedded file references
{stem}_alerts_graph.mermaid	TOON alerts & refactor tasks flowchart
{stem}_workflow.mermaid	DOQL workflow steps diagram
dependency_graph.html	Cross-document dependency graph (directory scan)

---

Installation

# Clone or copy the mdflow/ directory, then:
pip install -e .
# No mandatory dependencies — pure stdlib.

---

Usage

Python API

from mdflow import MdFlow

flow = MdFlow()

# ── Single file ───────────────────────────────────────────────
doc = flow.parse("SUMR.md")

print(doc.title)                        # "Ze źródeł"
print(len(doc.headings))               # 24
print([ts.name for ts in doc.toon_sections])  # ['HEALTH', 'REFACTOR', ...]
print(doc.metadata)                    # {'name': 'redsl', 'version': '1.2.45', ...}

# Access markpact embedded file references
for cb in doc.markpact_blocks:
    print(f"markpact:{cb.markpact_type}  path={cb.markpact_path}")

# Get TOON quality metrics
metrics = flow.toon_metrics(doc)
print(metrics["health"])               # {'cc_mean': 20.0, 'critical': 7}
print(metrics["refactors"][:3])        # list of refactor tasks

# Get all Mermaid diagrams as strings (no files written)
diagrams = flow.diagrams(doc)
print(diagrams["section_flow"])        # flowchart TD ...

# Generate reports to disk
flow.report(doc, "output/")            # writes HTML + MD + .mermaid files

# ── Directory scan ────────────────────────────────────────────
docs, graph = flow.scan("docs/", "output/")
print(f"{len(docs)} files, {len(graph.edges)} dependency edges")

CLI

# Analyze a single file
mdflow analyze SUMR.md --output output/

# Select formats
mdflow analyze SUMR.md --format html,md

# Scan a directory
mdflow scan docs/ --output output/

# Print a specific Mermaid diagram to stdout
mdflow diagram SUMR.md --diagram section_flow
mdflow diagram SUMR.md --diagram list        # list available diagrams

# Write diagram to file
mdflow diagram SUMR.md --diagram alerts_graph -o alerts.mermaid

Examples

The examples/ directory is organized by complexity and use case:

Basic

• 01_parse_single_file.py — Parse and inspect a single document
• 02_generate_reports.py — Generate HTML, Markdown, and Mermaid reports
• 03_diagrams_as_strings.py — Get diagrams as strings (no file I/O)
• 04_cli_basics.sh — CLI commands: analyze, scan, diagram

Advanced

• 01_directory_scan.py — Scan a directory and build dependency graphs
• 02_toon_analysis.py — Extract TOON quality metrics (HEALTH, ALERTS, REFACTOR, ...)
• 03_custom_diagram_pipeline.py — Build custom HTML with selected diagrams

API / Extensibility

• 01_low_level_parser.py — Use MdParser directly for fine-grained control
• 02_custom_analyzer.py — Build your own analyzer on top of MdDocument

Sample data files in examples/data/ are cross-linked so directory-scan examples produce realistic dependency graphs.

Run any example from the project root:

python examples/basic/01_parse_single_file.py
python examples/advanced/01_directory_scan.py
python examples/api/02_custom_analyzer.py

See examples/README.md for full details.

---

Architecture

mdflow/
├── __init__.py         ← MdFlow façade (high-level API)
├── models.py           ← Data classes: MdDocument, DependencyGraph, …
├── parser.py           ← Core Markdown parser (stdlib only)
├── analyzers/
│   └── __init__.py     ← DependencyAnalyzer, StructureAnalyzer,
│                          CodeInventoryAnalyzer, ToonAnalyzer
├── generators/
│   ├── __init__.py
│   ├── mermaid.py      ← All Mermaid diagram generators
│   ├── html.py         ← Self-contained HTML report
│   └── markdown.py     ← Markdown summary report
└── cli.py              ← argparse CLI entry point

---

Supported TOON sections

mdflow recognises these TOON section names inside toon / yaml code blocks and in blocks tagged markpact:analysis:

ALERTS · REFACTOR · HOTSPOTS · HEALTH · NEXT · RISKS · PIPELINES · DUPLICATES · WARNINGS · MODULES · EVOLUTION · COUPLING

---

Extension points

• Custom extractor: subclass or monkey-patch MdParser
• Custom diagram: call flow.diagrams(doc) and extend the mermaid module
• Graphviz output: install graphviz Python package and use DependencyGraph data directly

---

License

Licensed under Apache-2.0.