This release is a pre-release and may not be stable for production use.
fmddr
A CLI and library for analyzing FileMaker DDRs (Database Design Reports).
fmddr parses a DDR XML once into a SQLite index, then answers structural and
cross-reference queries in milliseconds. The output is JSON-first and stable,
so an agent — or a script, or a developer at the terminal — can drive analysis
at the same depth a GUI tool offers, without the GUI.
Install
Requires Python 3.11+ and repo access.
# Isolated CLI install (recommended):
uv tool install git+ssh://git@github.com/proofsh/fmddr.git
# or:
pipx install git+ssh://git@github.com/proofsh/fmddr.git
fmddr --version
From source (for development)
git clone git@github.com:proofsh/fmddr.git
cd fmddr
pip install -e .[dev] # adds pytest, ruff, build
pip install -e .[lxml] # adds libxml2-bound parser (optional)
Building a wheel locally
pip install build
python -m build
# → dist/fmddr-<version>-py3-none-any.whl
Quickstart
# 1. Explode the DDR into a per-object XML tree (grep/diff friendly).
fmddr split path/to/Profile.xml --out ./xmls-split
# 2. Build the SQLite index (the "ingest" step).
# Works on a single DDR (`type="Report"`) or a `Summary.xml` that links
# multiple files together — both produce one queryable index.
fmddr index path/to/Profile.xml --out ./profile.fmddr.db
fmddr index path/to/Summary.xml --out ./solution.fmddr.db
# 3. Query.
fmddr stats --db ./profile.fmddr.db
fmddr table fields "Production Run" -o table
fmddr field script-refs "Production Run::ProductionRunStatus"
fmddr script chain "Save Case Request" --depth 2 --format mermaid
fmddr cf called-by "FindWordPartsInText"
fmddr impact field "Customer::__UID"
fmddr unused --kind script
fmddr search "Customer*" --kind script
When stdout is a TTY, results render as Rich tables. Pipe to a file or another
process and you get JSON. Override with -o {json,jsonl,table,markdown,csv,tsv}.
Why
A FileMaker file with thousands of fields, scripts, and layouts is hard to refactor safely. Every change requires structural reasoning:
- What scripts touch this field, and at which step?
- Which layouts show it, and which objects on those layouts?
- What does this script call, and who calls it?
- If this field is removed, what breaks?
- Where is this custom function used?
- Which steps run risky
ExecuteSQLorEvaluate? - What's dead code? What's an orphan reference?
fmddr answers each of these in a one-line shell command with structured
output, so an agent can run thousands of these queries during a refactor —
programmatically, with stable output an LLM can parse.
Performance
On a 491 MB DDR from a long-running production file:
- Index build: ~7 s (one-time, streams through the XML)
- 257 tables / 10,403 fields / 1,877 scripts / 189,026 steps
- 873 layouts / 70,564 layout refs / 3,083 TOs / 2,758 relationships
- 123 custom functions / 503 value lists / 8,810 predicate refs
- Queries return in <50 ms
Streaming iterparse + element-clearing keeps memory bounded regardless of DDR
size. SQLite with journal_mode=MEMORY, synchronous=OFF during build, plus
VACUUM + PRAGMA optimize at end.
Command reference
Ingest
| Command | Purpose |
|---|---|
fmddr split <ddr> |
Per-object file tree — scripts as .fmscript text (default; --script-format xml|both for DDR XML), everything else XML |
fmddr index <ddr> / <Summary.xml> |
Build the SQLite index (single file or multi-file) |
fmddr stats |
Counts and metadata recorded in the index |
fmddr file list |
Files ingested into this index, with per-file counts |
fmddr open |
Interactive sqlite3 shell against the index |
Tables and fields
| Command | Purpose |
|---|---|
fmddr table list |
All base tables with field counts |
fmddr table show <name|id> |
Table metadata (records, calc/unstored counts) |
fmddr table fields <name|id> [--type ...] [--unstored] |
Fields on a table, optionally filtered |
fmddr field show <Table::Field|id> |
Field metadata (calc text, AutoEnter, storage flags) |
fmddr field references <token> [--kind ...] |
All references, denormalized |
fmddr field script-refs <token> |
One row per (script, step) that names the field |
fmddr field on-layouts <token> |
Distinct layouts that show the field |
fmddr field field-refs <token> |
Other fields whose calcs name this field |
fmddr field where <token> |
Counts grouped by owner_kind |
Scripts and steps
| Command | Purpose |
|---|---|
fmddr script list [--folder ...] [--name ...] |
All scripts, optionally filtered |
fmddr script show <token> |
Script header + step count |
fmddr script steps <token> [--type ...] [--has ...] |
Steps; --has execute_sql|evaluate|get_script_parameter|get_script_result |
fmddr script calls <token> |
Scripts called from this script |
fmddr script called-by <token> |
Everything that calls this script |
fmddr script fields <token> |
Distinct fields touched anywhere in this script |
fmddr script elements <token> |
Every distinct (field, script, layout, CF) referenced |
fmddr script calcs <token> |
Every step's text |
fmddr script chain <token> --depth N --format mermaid|dot |
BFS call-chain diagram (Mermaid / Graphviz / JSON) |
fmddr script grep <token> <regex> |
Regex search step text within a script |
fmddr step show "<Script>:<index>" |
Full step detail (FMP step id, has_* flags, var name, text) |
fmddr step refs "<Script>:<index>" |
All fields/scripts/layouts/CFs this single step references |
fmddr risky-steps --has <flag> [--limit N] |
Cross-script audit of risky steps (execute_sql etc.) |
Layouts
| Command | Purpose |
|---|---|
fmddr layout list [--folder ...] |
All layouts |
fmddr layout show <token> |
Layout header |
fmddr layout objects <token> [--type ...] |
Objects on the layout (Field/Button/Portal/TabControl/...) |
fmddr layout fields <token> |
Distinct fields shown on the layout |
fmddr layout scripts <token> |
Scripts referenced (buttons + ScriptTriggers) |
Custom functions
| Command | Purpose |
|---|---|
fmddr cf list |
All custom functions |
fmddr cf show <token> |
CF metadata + body |
fmddr cf calls <token> |
Other CFs this CF calls |
fmddr cf fields <token> |
Fields referenced inside this CF body |
fmddr cf called-by <token> |
Everywhere this CF is used |
Relationship graph
| Command | Purpose |
|---|---|
fmddr graph relationships |
All relationships |
fmddr graph tos [--base-table ...] |
Table occurrences, optionally filtered |
fmddr graph predicates <relationship_id> |
Join predicates for a relationship |
fmddr graph path <from-TO> <to-TO> [--max-hops N] |
Shortest TO→TO path through relationships |
Higher-order
| Command | Purpose |
|---|---|
fmddr impact field <token> |
What breaks if this field is removed |
fmddr impact script <token> [--depth N] |
Transitive script callers |
fmddr unused --kind <field|script|layout|custom_function|value_list|table_occurrence> |
Dead code candidates |
fmddr orphans |
Refs whose target rows don't exist |
fmddr cleanup-candidates |
Names matching debt patterns (BACKUP/COPY/OLD/TEMP/...) |
Search
| Command | Purpose |
|---|---|
fmddr search <fts5-query> [--kind ...] [--limit N] |
FTS5 over names of every kind |
Clipboard (macOS + Windows)
Copy an object straight from the SQLite index (no split-tree required) and paste into FileMaker — or hand-edit a split-tree XML file first if you want the file-on-disk workflow.
| Command | Purpose |
|---|---|
fmddr copy --script "<name>" |
Look up the script in the index and copy as <fmxmlsnippet> |
fmddr copy --table "<name>" |
Same for a base table |
fmddr copy --cf "<name>" |
Same for a custom function (per-CF; split-tree only emits a whole catalog) |
fmddr copy --vl "<name>" |
Same for a value list (per-VL; split-tree only emits a whole catalog) |
fmddr copy --script "<name>" --steps all|5-12 |
Copy script steps (all or a subset) as a ScriptStep — paste into a script |
fmddr copy <split-xml-path> |
File-path mode: validate + wrap + push (split-tree workflow) |
fmddr paste [--type Script|Table|...] |
Read the FM clipboard object — a Script/ScriptStep becomes .fmscript text; other objects emit <fmxmlsnippet> XML (--xml forces XML) |
fmddr validate --script "<name>" (or --table, --cf, --vl) |
Run pre-clipboard guards against the indexed object |
fmddr validate <split-xml-path> |
File-path mode: guards against a split-tree file |
fmddr clipboard formats |
List FM-recognized clipboard formats currently present |
Index-backed mode requires an index built with --keep-xml (the
default since 0.9). Supports <Script>, <BaseTable>,
<CustomFunction>, and <ValueList> roots in v1. Per-<Layout>
copy is not implemented: FileMaker has no whole-Layout clipboard
format (only LayoutObject for individual objects within a layout).
See docs/guides/clipboard.
Compile (script text → clipboard)
Write FileMaker script steps as plain text — exactly as Script
Workspace displays them — and compile to a pasteable
<fmxmlsnippet>. Field, script, and layout names are resolved to
FileMaker internal ids via the index, so agents never hand-write ids
or per-step XML shapes.
$ cat fix.fmscript
Set Variable [ $ids ; Value: ExecuteSQL ( "SELECT id FROM x" ; "" ; "" ) ]
If [ ValueCount ( $ids ) > 0 ]
Set Field [ Customer::Status ; "active" ]
End If
$ fmddr compile fix.fmscript --copy # → clipboard, paste into Script Workspace
| Command | Purpose |
|---|---|
fmddr compile [file|-] |
Compile text (file or stdin) to a ScriptStep snippet |
fmddr compile … --script-name "<name>" |
Emit a whole-Script snippet (pasting creates a new script) |
fmddr compile … --copy |
Push the snippet to the macOS clipboard as a FileMaker object |
fmddr compile … --validate-only |
Parse + resolve + validate, no snippet |
fmddr compile … --out file.xml |
Write the snippet XML to a file |
fmddr compile … --no-index |
Skip name→id resolution (FM re-resolves by name on paste; also what a missing index degrades to, with a warning) |
fmddr paste is the inverse of compile: copy a script (or a selection
of steps) in FileMaker and it reconstructs the Script Workspace display
text — editable, diffable, and re-compilable.
$ fmddr paste > fix.fmscript # reads the FileMaker clipboard (macOS)
$ fmddr paste some-copy.xml # or clipboard XML from a file / '-'
A Script or ScriptStep object becomes .fmscript text; any other object
(Table, Field, Custom Function, Value List, Layout Object) has no text
grammar, so its pretty-printed FileMaker XML is emitted instead (--xml
forces XML for scripts too). Raw text goes to stdout / --out; -o json
gives the structured envelope the VS Code extension consumes.
A VS Code extension for .fmscript files lives in
editors/vscode/ — syntax highlighting generated
from the compiler's step registry, validation squiggles via
fmddr compile --validate-only, quick fixes from did-you-mean
suggestions, a Compile-to-FileMaker-Clipboard command, and its inverse,
Paste-from-FileMaker-Clipboard (bring a copied script into the editor as
.fmscript). Build with
cd editors/vscode && npm ci && npm run package.
Grammar notes: one step per line; multi-line calculations continue
until brackets balance; // prefix disables a step; # starts a
comment; indentation is ignored (block nesting derives from
If/Loop/End If sequence). 88 step types have a text grammar (≥99% of
real-world steps by frequency); the rest — steps whose display text
can't reconstruct their config, like Send Mail, Import/Export
Records, Print, or finds with saved requests — fail with
E_UNSUPPORTED_STEP and can be passed through verbatim with the
escape hatch: @xml <Step …>…</Step> (or a fenced @xml <<< … >>>
block). Errors are structured JSON with 1-based line numbers and
did-you-mean suggestions.
Global flags
--db <path> Override default DB location (also $FMDDR_DB)
-o, --output {json,jsonl,table,markdown,csv,tsv} Force output format
--version Show version and exit
DB lookup order: --db flag → $FMDDR_DB → unique *.fmddr.db in CWD → error.
Exit codes
| Code | Meaning |
|---|---|
| 0 | OK |
| 1 | Not found (no field/script/layout matched) |
| 2 | Ambiguous (qualify with Table::Field or --by-id) |
| 64 | Bad usage |
| 70 | Internal error |
Output envelope
Every command emits a stable JSON shape:
{
"kind": "field.script-refs",
"version": 1,
"ddr": {"path": "...", "sha256": "...", "indexed_at": "..."},
"query": {"field": {"id": 8712, "name": "ProductionRunStatus", "table": "Production Run"}},
"result": [
{
"script_id": 1245, "script_name": "Save Case Request", "folder": "case-management",
"step_index": 82, "fm_line": 83, "step_type_name": "Perform Script",
"step_text": "Perform Script [ \"Send Alert Notification\" ... ]",
"via_to_id": 207, "via_to_name": "Production Run"
}
],
"result_count": 1,
"truncated": false
}
kind is the agent contract — agents can dispatch on it without parsing free
text. version: 1 allows future schema bumps without breaking older callers.
Tests double as runnable examples
tests/test_demo_questions.py runs through 22 representative analyses against
a synthetic mini DDR fixture. Run it with -s to see the formatted output for
each one:
pytest tests/test_demo_questions.py -s
When this file passes, the library answers all of them.
Architecture
src/fmddr/
├── cli.py # Typer entry point (thin shell)
├── parser/
│ ├── stream.py # UTF-16 → UTF-8 decode + iterparse driver
│ ├── split.py # Per-object XML tree explosion
│ └── refs.py # The uniform Chunk[FieldRef|CustomFunctionRef] walker
├── index/
│ ├── schema.sql # Canonical SQLite DDL
│ └── build.py # Streaming insert with executemany batches + staged ref resolution
├── query/
│ ├── tables.py # base_table + field queries
│ ├── fields.py # Field reference drills
│ ├── scripts.py # script + step + steps/refs/calls/elements/calcs
│ ├── layouts.py # layouts + objects + fields + scripts
│ ├── cf.py # Custom function queries
│ ├── graph.py # TOs + relationships + predicates + path
│ ├── impact.py # impact / unused / orphans / script-chain
│ ├── search.py # FTS5 + script grep
│ └── resolvers.py # name|id → (kind, id) with ambiguity handling
├── format/
│ └── output.py # Stable envelope + multi-format rendering
└── db.py # Connection helpers + meta envelope info
The reference graph is the heart: field_ref, script_ref, layout_ref,
custom_function_ref, value_list_ref, table_ref — every "where used /
depends on" question reduces to a one- or two-hop SQL query.
Docs site
A full Astro/Starlight docs site lives in docs/:
cd docs
npm install
npm run dev # http://localhost:4321
npm run build # static site → docs/dist/, deployable anywhere
License
MIT
Metadata
Release files for fmddr 1.0.0b14
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| fmddr-1.0.0b14.tar.gz | 439.3 kB | Without provenance | Details for fmddr-1.0.0b14.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| fmddr-1.0.0b14-py3-none-any.whl | Python 3 | none | any | Details for fmddr-1.0.0b14-py3-none-any.whl |
Total release size: 804.2 kB
Release files / fmddr-1.0.0b14.tar.gz
| Download URL | fmddr-1.0.0b14.tar.gz |
|---|---|
| Size | 439.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2593f811bf3e0cee72684fd0974cee4073f8b59c4d6307c13b23d5e2b182f637
|
|
BLAKE2b-256 checksum How to use checksums |
614b69a1b9b281dd99e79821bbf6e68a3c66df61b24878a404e60aec62d5809a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.13
|
Release files / fmddr-1.0.0b14-py3-none-any.whl
| Download URL | fmddr-1.0.0b14-py3-none-any.whl |
|---|---|
| Size | 364.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a4524a00920ee711b77a094717e3328920a088672e70c64bf1c3db4cfa45984e
|
|
BLAKE2b-256 checksum How to use checksums |
eb35034bff8b2fcef83cb8e64873b101a778d26b46266b9d1aa7208e4e12e70e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.13
|
Security for fmddr 1.0.0b14
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.