dataxplan 0.1.0__tar.gz

dataxplan-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atakan Arikan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dataxplan-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: dataxplan
+Version: 0.1.0
+Summary: Read PostgreSQL EXPLAIN plans locally: parse the plan, compute self time and estimation error, flag documented problems, compare plans, and guard them in CI. No database connection, deterministic.
+Author: Atakan Arikan
+License: MIT
+Project-URL: Homepage, https://github.com/arikanatakan/dataxplan
+Project-URL: Repository, https://github.com/arikanatakan/dataxplan
+Project-URL: Issues, https://github.com/arikanatakan/dataxplan/issues
+Keywords: postgresql,postgres,explain,query-plan,performance,query-optimization,database,sql,explain-analyze,dba
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.5; extra == "viz"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: matplotlib>=3.5; extra == "dev"
+Dynamic: license-file
+
+# dataxplan
+
+[![CI](https://github.com/arikanatakan/dataxplan/actions/workflows/ci.yml/badge.svg)](https://github.com/arikanatakan/dataxplan/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/dataxplan?v=1)](https://pypi.org/project/dataxplan/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Read PostgreSQL `EXPLAIN` plans from Python: parse the plan, compute the numbers
+people misread (self time and estimation error), flag documented problems,
+compare plans, and guard them in CI. **No database connection, nothing leaves
+your machine, deterministic output.**
+
+You give it the output of `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) ...`; it does
+the rest locally.
+
+![dataxplan framework: an EXPLAIN JSON plan (and optional catalog context) flows through parse, metrics and findings into a Report you can summarise, assert on in CI, turn into JSON, compare against another plan, or render as a text tree or chart; no database connection and deterministic](assets/framework.png)
+
+It turns a plan into a deterministic read (here a query whose join was estimated
+at 5 rows but produced 500,000):
+
+```text
+dataxplan
+  execution time   1,505.00 ms   (planning 0.30 ms)
+  nodes 3, depth 1
+  worst row estimate   100000x off
+  top by self time:
+    Index Scan on b      1,000.00 ms (66%)
+    Nested Loop          450.00 ms (30%)
+findings:
+  [HIGH] Row estimate is far off  (Nested Loop)
+      estimated 5 rows, actual 500,000 (100000x under-estimate)
+      -> run ANALYZE; if the columns are correlated consider extended statistics
+  [MEDIUM] Nested loop with many iterations  (Nested Loop)
+      the inner side executed 500,000 times
+      -> usually an under-estimate upstream; a hash or merge join may be cheaper
+```
+
+## Why
+
+Reading a plan by hand is error-prone (self time is per-loop and inclusive of
+children, so the slow node is rarely the obvious one). The good tools that do
+this are web pastebins (your production plan leaves your machine) or commercial
+SaaS. dataxplan is local, free, programmatic and embeddable: run it in a script,
+a notebook, your CI, or later an MCP server, and keep the plan in your own
+environment.
+
+```bash
+pip install dataxplan
+```
+
+No runtime dependencies. The chart is optional (`pip install "dataxplan[viz]"`).
+
+## Quick start
+
+```python
+import dataxplan
+
+report = dataxplan.analyze(explain_json)   # the EXPLAIN (FORMAT JSON) output
+print(report.summary())                    # the summary shown above
+```
+
+### From the command line
+
+```bash
+dataxplan plan.json                       # summary
+dataxplan plan.json --tree                # also the annotated plan tree
+dataxplan plan.json --json                # the full report as JSON
+dataxplan before.json --compare after.json
+psql -XqAt -c "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) <query>" | dataxplan
+```
+
+### Guard a plan in CI
+
+Pin a critical query's plan in your test suite, so a code or schema change that
+makes it regress fails the build. Nothing else in Python does this.
+
+```python
+def test_orders_lookup_stays_fast():
+    report = dataxplan.analyze(get_explain("SELECT * FROM orders WHERE customer_id = %s"))
+    assert not report.has_seq_scan_on("orders")
+    assert report.max_estimation_error < 100
+    assert not report.spilled_to_disk
+```
+
+### Compare two plans (before / after an index)
+
+```python
+print(dataxplan.compare(before_json, after_json).summary())
+# dataxplan compare - IMPROVED
+#   execution time   905.00 ms -> 0.08 ms (-100%)
+#   resolved         filter_discard, seq_scan_hot
+```
+
+### Sharper findings with catalog context (optional)
+
+```python
+from dataxplan import Context, TableInfo
+ctx = Context(tables={"orders": TableInfo("orders", row_count=10_000_000,
+                                          indexed_columns=("id",))})
+dataxplan.analyze(explain_json, context=ctx)
+```
+
+### Fetch a plan from a connection you already have (optional)
+
+```python
+plan = dataxplan.run_explain(conn, "SELECT * FROM orders WHERE id = %s", params=(42,))
+dataxplan.analyze(plan)
+```
+
+`run_explain` calls `cursor.execute` on a DB-API connection you pass (psycopg,
+psycopg2, ...); dataxplan does not depend on any driver. With `analyze=True` it
+runs the query, so use `analyze=False` for a plan-only estimate.
+
+## What it covers
+
+| Area | What you get |
+| --- | --- |
+| Parse | `parse` -> a typed `Plan` / `PlanNode` tree from EXPLAIN (FORMAT JSON) |
+| Metrics | self (exclusive) time, % of total, estimation error, disk spills, buffers |
+| Findings | hot sequential scans, large row mis-estimates, disk spills, filter discards, nested-loop blow-ups, index-only heap fetches, lossy bitmaps, JIT overhead |
+| Report | `summary`, `to_dict`, and an assertion API (`has_seq_scan_on`, `max_estimation_error`, `spilled_to_disk`, `ok`) for CI |
+| Compare | `compare` two plans for regression (timing, shape, estimates, findings) |
+| Render | `text_tree` (annotated, dependency-free) and `plan_tree_chart` (needs matplotlib) |
+| Context | optional catalog metadata (sizes, indexes, stale stats) that sharpens findings |
+| CLI | `dataxplan plan.json` (or stdin): summary, `--tree`, `--json`, `--compare` |
+
+## Examples
+
+Four plans from public datasets and benchmarks, each showing a different problem,
+are in [`examples/`](examples/): the IMDB / Join Order Benchmark (a row
+mis-estimate), the NYC TLC taxi trips (a sort that spills to disk), TPC-H
+`lineitem` (a hot scan discarding most rows), and the Bosch Production Line
+Performance manufacturing data set (a hash join with a large mis-estimate). For
+instance:
+
+```bash
+dataxplan examples/job_imdb_misestimate.json
+```
+
+## What is out of scope
+
+dataxplan analyses the **plan you give it**. By default it does not connect to a
+database, run your queries, or read your schema, so a finding is a **documented
+heuristic, not a guarantee**, and the suggestions are based on the plan alone. It
+does not rewrite SQL or invent a cost model. It targets PostgreSQL
+`FORMAT JSON` output (MySQL may follow).
+
+## How the headline metrics work
+
+- **Self time.** Postgres reports `Actual Total Time` per loop and inclusive of
+  children, so a node's total is `Actual Total Time x Actual Loops`, and its
+  self time is that minus the children's totals. Self time is where the work
+  really happens.
+- **Estimation error.** `Plan Rows` against `Actual Rows` (per loop); a large
+  ratio is the usual root cause of a bad plan.
+
+## References and validation
+
+The metric arithmetic is verified by hand against the semantics PostgreSQL
+documents (see [`tests/`](tests/)), and the heuristics are grounded in primary
+and academic sources, written in our own words:
+
+- [PostgreSQL documentation: EXPLAIN](https://www.postgresql.org/docs/current/sql-explain.html)
+- [PostgreSQL wiki: Using EXPLAIN](https://wiki.postgresql.org/wiki/Using_EXPLAIN)
+- V. Leis, A. Gubichev, A. Mirchev, P. Boncz, A. Kemper, T. Neumann, "How Good
+  Are Query Optimizers, Really?", Proceedings of the VLDB Endowment 9(3), 2015 -
+  the study of cardinality mis-estimation behind the Join Order Benchmark, which
+  the `estimate_off` finding detects (see the JOB example in
+  [`examples/`](examples/)).
+
+Plan analysis has no single numeric ground truth the way a closed-form formula
+does, so the claim here is deliberately narrow: the parsing and arithmetic are
+correct against the documented format, and each heuristic cites the behaviour it
+relies on.
+
+## License
+
+MIT. Written and maintained by [Atakan Arikan](https://github.com/arikanatakan),
+MSc Student at Tsinghua University and Politecnico di Milano.

dataxplan-0.1.0/README.md

@@ -0,0 +1,178 @@
+# dataxplan
+
+[![CI](https://github.com/arikanatakan/dataxplan/actions/workflows/ci.yml/badge.svg)](https://github.com/arikanatakan/dataxplan/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/dataxplan?v=1)](https://pypi.org/project/dataxplan/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Read PostgreSQL `EXPLAIN` plans from Python: parse the plan, compute the numbers
+people misread (self time and estimation error), flag documented problems,
+compare plans, and guard them in CI. **No database connection, nothing leaves
+your machine, deterministic output.**
+
+You give it the output of `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) ...`; it does
+the rest locally.
+
+![dataxplan framework: an EXPLAIN JSON plan (and optional catalog context) flows through parse, metrics and findings into a Report you can summarise, assert on in CI, turn into JSON, compare against another plan, or render as a text tree or chart; no database connection and deterministic](assets/framework.png)
+
+It turns a plan into a deterministic read (here a query whose join was estimated
+at 5 rows but produced 500,000):
+
+```text
+dataxplan
+  execution time   1,505.00 ms   (planning 0.30 ms)
+  nodes 3, depth 1
+  worst row estimate   100000x off
+  top by self time:
+    Index Scan on b      1,000.00 ms (66%)
+    Nested Loop          450.00 ms (30%)
+findings:
+  [HIGH] Row estimate is far off  (Nested Loop)
+      estimated 5 rows, actual 500,000 (100000x under-estimate)
+      -> run ANALYZE; if the columns are correlated consider extended statistics
+  [MEDIUM] Nested loop with many iterations  (Nested Loop)
+      the inner side executed 500,000 times
+      -> usually an under-estimate upstream; a hash or merge join may be cheaper
+```
+
+## Why
+
+Reading a plan by hand is error-prone (self time is per-loop and inclusive of
+children, so the slow node is rarely the obvious one). The good tools that do
+this are web pastebins (your production plan leaves your machine) or commercial
+SaaS. dataxplan is local, free, programmatic and embeddable: run it in a script,
+a notebook, your CI, or later an MCP server, and keep the plan in your own
+environment.
+
+```bash
+pip install dataxplan
+```
+
+No runtime dependencies. The chart is optional (`pip install "dataxplan[viz]"`).
+
+## Quick start
+
+```python
+import dataxplan
+
+report = dataxplan.analyze(explain_json)   # the EXPLAIN (FORMAT JSON) output
+print(report.summary())                    # the summary shown above
+```
+
+### From the command line
+
+```bash
+dataxplan plan.json                       # summary
+dataxplan plan.json --tree                # also the annotated plan tree
+dataxplan plan.json --json                # the full report as JSON
+dataxplan before.json --compare after.json
+psql -XqAt -c "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) <query>" | dataxplan
+```
+
+### Guard a plan in CI
+
+Pin a critical query's plan in your test suite, so a code or schema change that
+makes it regress fails the build. Nothing else in Python does this.
+
+```python
+def test_orders_lookup_stays_fast():
+    report = dataxplan.analyze(get_explain("SELECT * FROM orders WHERE customer_id = %s"))
+    assert not report.has_seq_scan_on("orders")
+    assert report.max_estimation_error < 100
+    assert not report.spilled_to_disk
+```
+
+### Compare two plans (before / after an index)
+
+```python
+print(dataxplan.compare(before_json, after_json).summary())
+# dataxplan compare - IMPROVED
+#   execution time   905.00 ms -> 0.08 ms (-100%)
+#   resolved         filter_discard, seq_scan_hot
+```
+
+### Sharper findings with catalog context (optional)
+
+```python
+from dataxplan import Context, TableInfo
+ctx = Context(tables={"orders": TableInfo("orders", row_count=10_000_000,
+                                          indexed_columns=("id",))})
+dataxplan.analyze(explain_json, context=ctx)
+```
+
+### Fetch a plan from a connection you already have (optional)
+
+```python
+plan = dataxplan.run_explain(conn, "SELECT * FROM orders WHERE id = %s", params=(42,))
+dataxplan.analyze(plan)
+```
+
+`run_explain` calls `cursor.execute` on a DB-API connection you pass (psycopg,
+psycopg2, ...); dataxplan does not depend on any driver. With `analyze=True` it
+runs the query, so use `analyze=False` for a plan-only estimate.
+
+## What it covers
+
+| Area | What you get |
+| --- | --- |
+| Parse | `parse` -> a typed `Plan` / `PlanNode` tree from EXPLAIN (FORMAT JSON) |
+| Metrics | self (exclusive) time, % of total, estimation error, disk spills, buffers |
+| Findings | hot sequential scans, large row mis-estimates, disk spills, filter discards, nested-loop blow-ups, index-only heap fetches, lossy bitmaps, JIT overhead |
+| Report | `summary`, `to_dict`, and an assertion API (`has_seq_scan_on`, `max_estimation_error`, `spilled_to_disk`, `ok`) for CI |
+| Compare | `compare` two plans for regression (timing, shape, estimates, findings) |
+| Render | `text_tree` (annotated, dependency-free) and `plan_tree_chart` (needs matplotlib) |
+| Context | optional catalog metadata (sizes, indexes, stale stats) that sharpens findings |
+| CLI | `dataxplan plan.json` (or stdin): summary, `--tree`, `--json`, `--compare` |
+
+## Examples
+
+Four plans from public datasets and benchmarks, each showing a different problem,
+are in [`examples/`](examples/): the IMDB / Join Order Benchmark (a row
+mis-estimate), the NYC TLC taxi trips (a sort that spills to disk), TPC-H
+`lineitem` (a hot scan discarding most rows), and the Bosch Production Line
+Performance manufacturing data set (a hash join with a large mis-estimate). For
+instance:
+
+```bash
+dataxplan examples/job_imdb_misestimate.json
+```
+
+## What is out of scope
+
+dataxplan analyses the **plan you give it**. By default it does not connect to a
+database, run your queries, or read your schema, so a finding is a **documented
+heuristic, not a guarantee**, and the suggestions are based on the plan alone. It
+does not rewrite SQL or invent a cost model. It targets PostgreSQL
+`FORMAT JSON` output (MySQL may follow).
+
+## How the headline metrics work
+
+- **Self time.** Postgres reports `Actual Total Time` per loop and inclusive of
+  children, so a node's total is `Actual Total Time x Actual Loops`, and its
+  self time is that minus the children's totals. Self time is where the work
+  really happens.
+- **Estimation error.** `Plan Rows` against `Actual Rows` (per loop); a large
+  ratio is the usual root cause of a bad plan.
+
+## References and validation
+
+The metric arithmetic is verified by hand against the semantics PostgreSQL
+documents (see [`tests/`](tests/)), and the heuristics are grounded in primary
+and academic sources, written in our own words:
+
+- [PostgreSQL documentation: EXPLAIN](https://www.postgresql.org/docs/current/sql-explain.html)
+- [PostgreSQL wiki: Using EXPLAIN](https://wiki.postgresql.org/wiki/Using_EXPLAIN)
+- V. Leis, A. Gubichev, A. Mirchev, P. Boncz, A. Kemper, T. Neumann, "How Good
+  Are Query Optimizers, Really?", Proceedings of the VLDB Endowment 9(3), 2015 -
+  the study of cardinality mis-estimation behind the Join Order Benchmark, which
+  the `estimate_off` finding detects (see the JOB example in
+  [`examples/`](examples/)).
+
+Plan analysis has no single numeric ground truth the way a closed-form formula
+does, so the claim here is deliberately narrow: the parsing and arithmetic are
+correct against the documented format, and each heuristic cites the behaviour it
+relies on.
+
+## License
+
+MIT. Written and maintained by [Atakan Arikan](https://github.com/arikanatakan),
+MSc Student at Tsinghua University and Politecnico di Milano.

dataxplan-0.1.0/dataxplan/__init__.py

@@ -0,0 +1,45 @@
+"""dataxplan - read PostgreSQL EXPLAIN plans, locally and deterministically.
+
+Give it the output of ``EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) ...`` and it
+parses the plan, computes the metrics people misread (self time, estimation
+error, disk spills), and flags documented problems. No database connection is
+required and nothing leaves your machine.
+
+    import dataxplan
+
+    report = dataxplan.analyze(explain_json)
+    print(report.summary())
+
+    # guard a plan in a test (fail CI if it regresses)
+    assert not report.has_seq_scan_on("orders")
+    assert report.max_estimation_error < 100
+    assert not report.spilled_to_disk
+
+    # compare two plans (before/after an index)
+    print(dataxplan.compare(before_json, after_json).summary())
+
+The findings are documented heuristics, not guarantees, and the analysis is of
+the plan you provide; it does not run your queries or read your schema unless you
+choose to supply catalog context.
+"""
+
+from ._result import Finding
+from ._version import __version__
+from .compare import Comparison, compare
+from .context import Context, TableInfo
+from .metrics import NodeMetrics
+from .parse import Plan, PlanNode, parse
+from .render import plan_tree_chart, text_tree
+from .report import Report, analyze
+from .run import run_explain
+
+__all__ = [
+    # core flow
+    "parse", "analyze", "compare",
+    # types
+    "Plan", "PlanNode", "Report", "NodeMetrics", "Finding", "Comparison",
+    "Context", "TableInfo",
+    # render and helpers
+    "text_tree", "plan_tree_chart", "run_explain",
+    "__version__",
+]

dataxplan-0.1.0/dataxplan/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

dataxplan-0.1.0/dataxplan/_result.py

@@ -0,0 +1,83 @@
+"""Shared plumbing: provenance (version, input hash, timestamp), the ``Finding``
+type, and small formatting helpers. Every public result carries a meta block so
+an analysis can be reproduced and audited later.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from ._version import __version__
+
+SCHEMA = 1
+
+# Finding severities, most to least serious.
+HIGH = "high"
+MEDIUM = "medium"
+LOW = "low"
+INFO = "info"
+_ORDER = {HIGH: 0, MEDIUM: 1, LOW: 2, INFO: 3}
+
+
+def utcnow() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def data_hash(obj: object) -> str:
+    payload = json.dumps(obj, sort_keys=True, default=str).encode("utf-8")
+    return "sha256:" + hashlib.sha256(payload).hexdigest()[:16]
+
+
+def make_meta(inputs: dict) -> dict:
+    """The provenance block stamped onto every result."""
+    return {
+        "library": "dataxplan",
+        "version": __version__,
+        "computed_at": utcnow(),
+        "input_hash": data_hash(inputs),
+    }
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One observation about a plan: a documented heuristic, not a guarantee."""
+
+    id: str
+    severity: str           # high | medium | low | info
+    title: str
+    detail: str
+    node: str | None = None         # e.g. "Seq Scan on orders"
+    path: tuple[int, ...] | None = None
+    suggestion: str | None = None
+
+    @property
+    def rank(self) -> int:
+        return _ORDER.get(self.severity, 9)
+
+    def __str__(self) -> str:
+        head = f"[{self.severity.upper()}] {self.title}"
+        if self.node:
+            head += f"  ({self.node})"
+        lines = [head, f"    {self.detail}"]
+        if self.suggestion:
+            lines.append(f"    -> {self.suggestion}")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id, "severity": self.severity, "title": self.title,
+            "detail": self.detail, "node": self.node,
+            "path": list(self.path) if self.path else None,
+            "suggestion": self.suggestion,
+        }
+
+
+def ms(value: float | None) -> str:
+    return "-" if value is None else f"{value:,.2f} ms"
+
+
+def num(value: float | None, places: int = 0) -> str:
+    return "-" if value is None else f"{value:,.{places}f}"

dataxplan-0.1.0/dataxplan/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

dataxplan-0.1.0/dataxplan/cli.py

@@ -0,0 +1,66 @@
+"""Command-line interface: analyse a plan from a file or stdin.
+
+    dataxplan plan.json
+    dataxplan plan.json --tree
+    dataxplan plan.json --json
+    dataxplan before.json --compare after.json
+    psql -XqAt -c "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) ..." | dataxplan
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import analyze, compare, text_tree
+from ._version import __version__
+
+
+def _read(source: str) -> str:
+    if source in (None, "-"):
+        return sys.stdin.read()
+    with open(source, encoding="utf-8") as handle:
+        return handle.read()
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="dataxplan",
+        description="Analyse a PostgreSQL EXPLAIN (FORMAT JSON) plan, locally.")
+    parser.add_argument("plan", nargs="?", default="-",
+                        help="plan file, or - for stdin (the default)")
+    parser.add_argument("--tree", action="store_true",
+                        help="also print the annotated plan tree")
+    parser.add_argument("--json", action="store_true",
+                        help="print the full report (or comparison) as JSON")
+    parser.add_argument("--compare", metavar="OTHER",
+                        help="compare the plan against another plan file")
+    parser.add_argument("--version", action="version",
+                        version=f"dataxplan {__version__}")
+    args = parser.parse_args(argv)
+
+    try:
+        plan = json.loads(_read(args.plan))
+        if args.compare:
+            result = compare(plan, json.loads(_read(args.compare)))
+            print(json.dumps(result.to_dict(), indent=2, default=str)
+                  if args.json else result.summary())
+            return 0
+        report = analyze(plan)
+    except (ValueError, TypeError, OSError, json.JSONDecodeError) as exc:
+        print(f"dataxplan: {exc}", file=sys.stderr)
+        return 2
+
+    if args.json:
+        print(json.dumps(report.to_dict(), indent=2, default=str))
+    else:
+        print(report.summary())
+        if args.tree:
+            print("\nplan tree:")
+            print(text_tree(report))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())