ddr-docs 0.2.0

CLI-first FileMaker DDR extraction and analysis toolkit

ddr-docs

ddr-docs is a CLI-first Python toolkit for turning FileMaker DDR XML into structured docs, JSON artifacts, and analysis outputs that work well for humans, agents, and downstream tooling.

FM2Web still includes a desktop/Tauri app, but the Python package and CLI are the primary interface in this repo.

Install

Recommended: pipx

Install the CLI in its own environment:

pipx install ddr-docs

If you want the analyzer-powered commands too, install the analyzer extra:

pipx install 'ddr-docs[analyzer]'

Standard pip

Inside a virtualenv:

python -m pip install ddr-docs
# or, with analyzer commands
python -m pip install 'ddr-docs[analyzer]'

From a local checkout

python -m pip install -e .
# or
python -m pip install -e '.[analyzer,dev]'

Quick start

1) Generate extracted docs from a DDR XML file

ddr-docs generate /path/to/file.ddr.xml -o ./out/ddr-run

That produces a run directory with JSON, Markdown, diagrams, reports, and a manifest.

2) Run the agent-friendly end-to-end analysis flow

ddr-docs analyze full-analysis \
  --input /path/to/file.ddr.xml \
  --output-dir ./out/full-analysis \
  --sqlite-path ./out/full-analysis/fm2web.sqlite3

This runs extraction, ingests into SQLite, then writes analysis JSON under analysis/, including:

• analysis/user_flows_entry_points.json
• analysis/user_flows_journeys/*.json
• analysis/cruft_summary.json
• analysis/feature_clusters.json
• analysis/analysis_manifest.json

CLI overview

ddr-docs --help
ddr-docs generate --help
ddr-docs analyze --help
ddr-docs analyze full-analysis --help

ddr-docs generate

Core extraction pipeline.

ddr-docs generate /path/to/file.ddr.xml \
  --output ./out/run \
  --persist-sqlite \
  --sqlite-path ./out/run/fm2web.sqlite3

Useful options:

• --output/-o, output run directory
• --domain, comma-separated extraction domains
• --start-from, restart from a later pipeline stage
• --stop-after, stop at a specific stage
• --persist-sqlite, write extracted artifacts into SQLite
• --sqlite-path, choose the SQLite path
• --no-index, skip search index generation
• --strict, fail on validation/parsing issues

ddr-docs analyze full-analysis

This is the highest-leverage command when you want one run that leaves behind structured artifacts for review, automation, or agent workflows.

ddr-docs analyze full-analysis \
  --input /path/to/file.ddr.xml \
  --output-dir ./out/full-analysis \
  --sqlite-path ./out/full-analysis/fm2web.sqlite3 \
  --journey-depth 6

Behavior:

1. runs the extraction pipeline
2. ingests the run into SQLite
3. generates journey/entry-point analysis
4. generates cruft analysis
5. generates feature-cluster analysis
6. writes an analysis manifest summarizing outputs

Key options:

• --input, DDR XML source file
• --output-dir/-o, target run directory
• --sqlite-path, explicit SQLite database path
• --embeddings/--no-embeddings, control embedding generation
• --journey-depth, traversal depth for journey mapping
• --verbose, print step-by-step progress

Seeding one or more layout entry points

By default, full-analysis auto-detects entry points from menu scripts and layouts.

If you already know the layouts you want to analyze, provide one or more --entry-point-layout flags:

ddr-docs analyze full-analysis \
  --input /path/to/file.ddr.xml \
  --output-dir ./out/mobile-analysis \
  --entry-point-layout 'Home iPhone' \
  --entry-point-layout 'Settings iPhone'

Repeatable flags are the preferred interface.

For backward compatibility, comma-separated values still work too:

ddr-docs analyze full-analysis \
  --input /path/to/file.ddr.xml \
  --output-dir ./out/mobile-analysis \
  --entry-point-layout 'Home iPhone, Settings iPhone'

When --entry-point-layout is provided, those requested layouts override auto-detected journey entry points. Matching layouts are recorded in analysis/user_flows_entry_points.json, and journeys are generated for the resolved layouts.

Other analysis commands

List analyzer surfaces:

ddr-docs analyze --help

Examples:

ddr-docs analyze journeys --sqlite-path ./out/run/fm2web.sqlite3
ddr-docs analyze journeys --sqlite-path ./out/run/fm2web.sqlite3 --from 'Home'
ddr-docs analyze cruft --extracted-docs ./out/run/json
ddr-docs analyze features --sqlite-path ./out/run/fm2web.sqlite3
ddr-docs analyze flows --sqlite-path ./out/run/fm2web.sqlite3 --field 'Contacts::Email'

Output structure

Typical run output includes:

• json/, canonical extraction artifacts
• docs/, rendered Markdown docs
• diagrams/, relationship diagrams
• index/, search index artifacts
• reports/, coverage and warning reports
• manifest.json, run metadata
• analysis/, higher-level analysis JSON from full-analysis

Desktop app, still available

The repo also contains a Tauri desktop app in desktop/ for local/offline usage. That is now secondary to the Python package and CLI.

If you specifically need the desktop app, see:

• desktop/
• desktop/BACKEND_BUNDLE.md

Development

Run focused tests:

python -m pytest tests/test_cli_full_analysis.py tests/test_cli_optional_deps.py

Build package artifacts locally:

python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*

Repository layout

• ddr_docs/, CLI and extraction pipeline
• analyzer/, SQLite-backed analysis services and API
• desktop/, optional Tauri desktop app
• ui/, Streamlit UI
• tests/, automated tests

License

MIT