mdflow

AI Cost Tracking

What it extracts

Generated outputs

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

Mermaid validation

[mdflow] ⚠ 1 error(s) output/SUMR_section_flow.mermaid
  ✗ [BACKTICK_IN_LABEL] Backtick inside node label (line 5): ...
[mdflow] → 1 validation ticket(s) written to TODO.md

Quality tooling

# Run full quality loop (prefact scan → ruff → pytest → LLM fix on fail)
task quality          # alias: pyqual run

# Scan for code issues (duplicate imports, wildcard imports, …)
task prefact          # alias: prefact scan -p .

# Auto-fix detected issues
task prefact-fix      # alias: prefact fix -p .

Testing

Unit tests

pytest tests/ -v

E2E / CLI tests (TestQL)

# All scenarios
task testql-run

# Smoke only (help, subcommands)
task testql-smoke

# Full E2E (analyze, scan, diagram, semcod projects, mermaid validation)
task testql-e2e

# Single scenario
testql run testql-scenarios/02_cli_analyze_e2e.testql.toon.yaml

Architecture

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

Examples

Basic

Advanced

API / Extensibility

semcod workspace

python examples/semcod/toon_comparison.py
python examples/semcod/scan_semcod_workspace.py

Supported TOON sections

Extension points

License

Dependency maintenance