pbi-enterprise-cli 0.1.0.dev0__py3-none-any.whl

pbi_cli/commands/dax.py

@@ -0,0 +1,174 @@
+"""pbi dax — DAX query, validate, and test commands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+import yaml  # type: ignore[import-untyped]
+from rich.console import Console
+
+from pbi_cli.commands._shared import get_backend, output_json_or_table
+
+console = Console()
+
+
+@click.group()
+def dax() -> None:
+    """Execute, validate, and unit-test DAX expressions."""
+
+
+@dax.command("query")
+@click.argument("expression")
+@click.pass_context
+def dax_query(ctx: click.Context, expression: str) -> None:
+    """Execute a DAX query and return results."""
+    backend = get_backend(ctx)
+    results = backend.dax_query(expression)
+    output_json_or_table(results, ctx, title="DAX Results")
+
+
+@dax.command("validate")
+@click.argument("expression")
+@click.pass_context
+def dax_validate(ctx: click.Context, expression: str) -> None:
+    """Validate a DAX expression syntax without executing."""
+    backend = get_backend(ctx)
+    result = backend.dax_validate(expression)
+    if result.get("valid"):
+        console.print("[green]Valid DAX expression.[/green]")
+    else:
+        console.print(f"[red]Invalid:[/red] {result.get('error', 'Unknown error')}")
+
+
+@dax.command("test")
+@click.option(
+    "--suite", required=True, type=click.Path(exists=True), help="Path to YAML test suite."
+)
+@click.pass_context
+def dax_test(ctx: click.Context, suite: str) -> None:
+    """Run DAX unit tests from a YAML fixture file."""
+    import math
+
+    data = yaml.safe_load(Path(suite).read_text(encoding="utf-8"))
+    tests = data.get("tests", [])
+    console.print(f"[cyan]Running suite:[/cyan] {suite} ({len(tests)} tests)\n")
+    backend = get_backend(ctx)
+    passed = 0
+    failed = 0
+
+    for test in tests:
+        name = test["name"]
+        dax_expr = test.get("dax", "").strip()
+        asserts = test.get("assert", [])
+        try:
+            rows = backend.dax_query(dax_expr)
+        except Exception as exc:
+            console.print(f"  [red]FAIL[/red] {name}")
+            console.print(f"       Query error: {exc}")
+            failed += 1
+            continue
+
+        test_failed = False
+        fail_reasons: list[str] = []
+
+        for assertion in asserts:
+            # row_count: exact number of rows
+            if "row_count" in assertion:
+                expected_count = assertion["row_count"]
+                if len(rows) != expected_count:
+                    fail_reasons.append(f"row_count: expected {expected_count}, got {len(rows)}")
+                    test_failed = True
+
+            # min_rows
+            if "min_rows" in assertion:
+                if len(rows) < assertion["min_rows"]:
+                    fail_reasons.append(
+                        f"min_rows: expected >= {assertion['min_rows']}, got {len(rows)}"
+                    )
+                    test_failed = True
+
+            # max_rows
+            if "max_rows" in assertion:
+                if len(rows) > assertion["max_rows"]:
+                    fail_reasons.append(
+                        f"max_rows: expected <= {assertion['max_rows']}, got {len(rows)}"
+                    )
+                    test_failed = True
+
+            col = assertion.get("column")
+            row_idx = assertion.get("row", 0)
+
+            if col and rows:
+                # Get column values (rows is list of dicts)
+                col_values = [r.get(col) for r in rows if col in r]
+
+                # not_blank
+                if assertion.get("not_blank"):
+                    blanks = [
+                        v
+                        for v in col_values
+                        if v is None or (isinstance(v, float) and math.isnan(v))
+                    ]
+                    if blanks:
+                        fail_reasons.append(
+                            f"not_blank: column '{col}' has {len(blanks)} blank values"
+                        )
+                        test_failed = True
+
+                # all_rows_between
+                if "all_rows_between" in assertion:
+                    lo, hi = assertion["all_rows_between"]
+                    out_of_range = [
+                        v
+                        for v in col_values
+                        if v is not None and not math.isnan(float(v)) and not (lo <= float(v) <= hi)
+                    ]
+                    if out_of_range:
+                        fail_reasons.append(
+                            f"all_rows_between [{lo},{hi}]: {len(out_of_range)} values out of range"
+                        )
+                        test_failed = True
+
+                # expected: value at specific row
+                if "expected" in assertion and row_idx < len(rows):
+                    actual = rows[row_idx].get(col)
+                    expected = assertion["expected"]
+                    tolerance = assertion.get("tolerance", 0)
+                    if actual is None:
+                        fail_reasons.append(f"expected {expected} in '{col}'[{row_idx}], got None")
+                        test_failed = True
+                    elif tolerance:
+                        tol_abs = abs(expected) * tolerance if tolerance < 1 else tolerance
+                        if abs(float(actual) - expected) > tol_abs:
+                            fail_reasons.append(
+                                f"expected {expected} ± {tol_abs} in '{col}'[{row_idx}], got {actual}"  # noqa: E501
+                            )
+                            test_failed = True
+                    elif actual != expected:
+                        fail_reasons.append(
+                            f"expected {expected!r} in '{col}'[{row_idx}], got {actual!r}"
+                        )
+                        test_failed = True
+
+                # expected_string
+                if "expected_string" in assertion and row_idx < len(rows):
+                    actual = rows[row_idx].get(col)
+                    if str(actual) != assertion["expected_string"]:
+                        fail_reasons.append(
+                            f"expected '{assertion['expected_string']}' in '{col}'[{row_idx}], got '{actual}'"  # noqa: E501
+                        )
+                        test_failed = True
+
+        if test_failed:
+            console.print(f"  [red]FAIL[/red] {name}")
+            for reason in fail_reasons:
+                console.print(f"       {reason}")
+            failed += 1
+        else:
+            console.print(f"  [green]PASS[/green] {name}")
+            passed += 1
+
+    console.print(f"\n[bold]{passed} passed, {failed} failed[/bold] out of {len(tests)} tests")
+    if failed:
+        raise SystemExit(1)

pbi_cli/commands/deploy.py

@@ -0,0 +1,193 @@
+"""pbi deploy — deployment pipeline commands (Epic E)."""
+
+from __future__ import annotations
+
+import click
+from rich.console import Console
+
+from pbi_cli.commands._shared import dry_run_echo, get_backend, output_json_or_table
+
+console = Console()
+
+
+@click.group()
+def deploy() -> None:
+    """Deploy and promote models via XMLA: push, diff, promote, snapshot."""
+
+
+@deploy.command("push")
+@click.option("--workspace", required=True, help="Target workspace name.")
+@click.option("--xmla", default=None, help="XMLA endpoint URL (overrides config).")
+@click.pass_context
+def deploy_push(ctx: click.Context, workspace: str, xmla: str | None) -> None:
+    """Export TMDL and deploy to a workspace via XMLA with transaction safety.
+
+    \b
+    Prerequisites:
+      pip install pbi-enterprise-cli[server]
+      Set XMLA endpoint in ~/.pbi-cli/config.toml:
+        [xmla]
+        endpoint = "powerbi://api.powerbi.com/v1.0/myorg/MyWorkspace"
+
+    \b
+    Example:
+      pbi deploy push --workspace "Production"
+    """
+    console.print(f"[cyan]Deploying to:[/cyan] {workspace}")
+    if dry_run_echo(ctx, f"push model to workspace '{workspace}' via XMLA"):
+        return
+
+    endpoint = xmla or _get_xmla_endpoint()
+    if not endpoint:
+        console.print(
+            "[yellow]XMLA endpoint not configured.[/yellow]\n"
+            "Set it in [bold]~/.pbi-cli/config.toml[/bold]:\n"
+            "  [xmla]\n"
+            '  endpoint = "powerbi://api.powerbi.com/v1.0/myorg/MyWorkspace"'
+        )
+        console.print(
+            "\n[yellow]XMLA backend required (v6.0). Install pbi-enterprise-cli[server].[/yellow]"
+        )
+        return
+
+    console.print(f"  Endpoint: {endpoint}")
+    console.print("[yellow]XMLA push not yet implemented — endpoint resolved.[/yellow]")
+    console.print("Use 'pbi deploy snapshot' to save a local snapshot first.")
+
+
+@deploy.command("diff")
+@click.option("--workspace", default=None, help="Workspace to compare against (XMLA).")
+@click.option("--snapshot", default=None, help="Local TMDL snapshot directory to compare against.")
+@click.pass_context
+def deploy_diff(ctx: click.Context, workspace: str | None, snapshot: str | None) -> None:
+    """Compare local model against deployed model or a local snapshot.
+
+    \b
+    Examples:
+      pbi deploy diff --snapshot ./snapshots/2025-01-01
+      pbi deploy diff --workspace "Staging"
+    """
+    if snapshot:
+        # Use local model_diff (already implemented in TOM backend)
+        backend = get_backend(ctx)
+        result = backend.model_diff(snapshot_path=snapshot)
+        if not result.get("has_changes"):
+            console.print("[green]No changes detected[/green] — model matches snapshot.")
+            return
+        output_json_or_table(result, ctx, title="Model Diff vs Snapshot")
+        console.print(
+            f"[yellow]Changes:[/yellow] "
+            f"{len(result['added'])} added, "
+            f"{len(result['removed'])} removed, "
+            f"{len(result['changed'])} modified"
+        )
+    elif workspace:
+        console.print(f"[cyan]Diffing against workspace:[/cyan] {workspace}")
+        endpoint = _get_xmla_endpoint()
+        if not endpoint:
+            console.print(
+                "[yellow]XMLA endpoint not configured — cannot diff against workspace.[/yellow]"
+            )
+            console.print("Use --snapshot to diff against a local TMDL snapshot instead.")
+            return
+        console.print("[yellow]XMLA diff not yet implemented (XMLA backend required).[/yellow]")
+        console.print(
+            "Tip: Use 'pbi deploy snapshot' to capture a baseline, then 'pbi deploy diff --snapshot'."  # noqa: E501
+        )
+    else:
+        raise click.UsageError("Provide --snapshot or --workspace.")
+
+
+@deploy.command("snapshot")
+@click.option(
+    "--output",
+    default=None,
+    help="Output directory for the TMDL snapshot (default: ./snapshots/<timestamp>).",
+)
+@click.pass_context
+def deploy_snapshot(ctx: click.Context, output: str | None) -> None:
+    """Export the current model as a TMDL snapshot to a local directory.
+
+    Snapshots can be compared with 'pbi deploy diff --snapshot' or 'pbi model diff --snapshot'.
+
+    \b
+    Example:
+      pbi deploy snapshot --output ./snapshots/before-refactor
+    """
+    import datetime
+    from pathlib import Path
+
+    if output is None:
+        ts = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+        output = str(Path(".") / "snapshots" / ts)
+
+    out_path = Path(output)
+    if dry_run_echo(ctx, f"export TMDL snapshot to '{out_path}'"):
+        return
+
+    backend = get_backend(ctx)
+    try:
+        out_path.mkdir(parents=True, exist_ok=True)
+        backend.tmdl_export(str(out_path))
+        file_count = len(list(out_path.rglob("*.tmdl")))
+        console.print(f"[green]Snapshot saved:[/green] {out_path}")
+        console.print(f"  Files: {file_count} .tmdl file(s)")
+        console.print("\nCompare later with:")
+        console.print(f"  pbi deploy diff --snapshot {out_path}")
+        console.print(f"  pbi model diff --snapshot {out_path}")
+    except Exception as e:
+        console.print(f"[red]Snapshot failed:[/red] {e}")
+        console.print("Ensure Power BI Desktop is running with the model open.")
+        raise SystemExit(1)
+
+
+@deploy.command("promote")
+@click.option("--from", "from_workspace", required=True, help="Source workspace.")
+@click.option("--to", "to_workspace", required=True, help="Target workspace.")
+@click.pass_context
+def deploy_promote(ctx: click.Context, from_workspace: str, to_workspace: str) -> None:
+    """Parameterised promotion: swap connections, update partitions, deploy.
+
+    \b
+    Example:
+      pbi deploy promote --from Staging --to Production
+    """
+    console.print(f"[cyan]Promoting:[/cyan] {from_workspace} -> {to_workspace}")
+    if dry_run_echo(ctx, f"promote model from '{from_workspace}' to '{to_workspace}'"):
+        return
+
+    endpoint = _get_xmla_endpoint()
+    if not endpoint:
+        console.print(
+            "[yellow]XMLA endpoint not configured.[/yellow]\n"
+            "Set it in [bold]~/.pbi-cli/config.toml[/bold]:\n"
+            "  [xmla]\n"
+            '  endpoint = "powerbi://api.powerbi.com/v1.0/myorg/MyWorkspace"'
+        )
+    console.print("[yellow]Promotion (XMLA backend required — v6.0).[/yellow]")
+    console.print("Steps that will run when XMLA is connected:")
+    console.print("  1. Export TMDL from source workspace")
+    console.print("  2. Swap connection strings (dev -> prod data sources)")
+    console.print("  3. Update partition queries")
+    console.print("  4. Deploy to target workspace via XMLA transaction")
+
+
+def _get_xmla_endpoint() -> str | None:
+    """Read XMLA endpoint from ~/.pbi-cli/config.toml if available."""
+    try:
+        from pathlib import Path
+
+        config_path = Path.home() / ".pbi-cli" / "config.toml"
+        if not config_path.exists():
+            return None
+        try:
+            import tomllib  # Python 3.11+
+        except ImportError:
+            try:
+                import tomli as tomllib  # type: ignore[no-redef]
+            except ImportError:
+                return None
+        data = tomllib.loads(config_path.read_text(encoding="utf-8"))
+        return data.get("xmla", {}).get("endpoint")
+    except Exception:
+        return None

pbi_cli/commands/docs.py

@@ -0,0 +1,57 @@
+"""pbi docs — data dictionary generation and audit log (Epic D)."""
+
+from __future__ import annotations
+
+import click
+from rich.console import Console
+
+from pbi_cli.commands._shared import get_backend, output_json_or_table
+
+console = Console()
+
+
+@click.group()
+def docs() -> None:
+    """Generate data dictionaries, documentation, and view the audit log."""
+
+
+@docs.command("generate")
+@click.option("--format", "fmt", type=click.Choice(["markdown", "confluence"]), default="markdown")
+@click.option("--output", default=None, help="Output file path.")
+@click.pass_context
+def docs_generate(ctx: click.Context, fmt: str, output: str | None) -> None:
+    """Generate a full data dictionary for the model."""
+    backend = get_backend(ctx)
+    if fmt == "markdown":
+        from pbi_cli.docs_gen.markdown import MarkdownDocsGenerator
+
+        gen = MarkdownDocsGenerator(backend)
+    else:
+        from pbi_cli.docs_gen.confluence import ConfluenceDocsGenerator
+
+        gen = ConfluenceDocsGenerator(backend)  # type: ignore[assignment]
+    content = gen.generate()
+    if output:
+        from pathlib import Path
+
+        Path(output).write_text(content, encoding="utf-8")
+        console.print(f"[green]Written:[/green] {output}")
+    else:
+        console.print(content)
+
+
+@docs.command("audit-log")
+@click.option("--limit", default=50, show_default=True, help="Number of recent entries to show.")
+@click.pass_context
+def docs_audit_log(ctx: click.Context, limit: int) -> None:
+    """Display the audit log of all write operations (~/.pbi-cli/audit.jsonl)."""
+    from pbi_cli._audit import read_audit_log
+
+    entries = read_audit_log(limit=limit)
+    if not entries:
+        console.print("[yellow]Audit log is empty.[/yellow]")
+        console.print(
+            "Write operations (measure add/update/delete, scaffold, deploy) are logged automatically."  # noqa: E501
+        )
+        return
+    output_json_or_table(entries, ctx, title="Audit Log")

pbi_cli/commands/filter_cmd.py

@@ -0,0 +1,235 @@
+"""pbi filter — add relative-date, TopN, and basic filters to report pages."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from pbi_cli.commands._shared import dry_run_echo, output_json_or_table
+
+console = Console()
+
+
+@click.group("filter")
+def filter_cmd() -> None:
+    """Add and manage filters on report pages (relative-date, TopN, basic value)."""
+
+
+def _page_json_path(pbip: str, page: str) -> Path:
+    from pbi_cli.backends.pbir_backend import PbirBackend
+
+    b = PbirBackend(pbip)
+    pages = b.page_list()
+    match = next((p for p in pages if p["displayName"] == page), None)
+    if not match:
+        raise click.ClickException(f"Page '{page}' not found.")
+    report_dir = b._report_dir  # type: ignore[attr-defined]
+    assert report_dir is not None
+    pages_dir = report_dir / "definition" / "pages"
+    for page_dir in pages_dir.iterdir():
+        pj = page_dir / "page.json"
+        if pj.exists():
+            data = json.loads(pj.read_text(encoding="utf-8"))
+            if data.get("displayName") == page or data.get("name") == match["name"]:
+                return pj
+    raise click.ClickException(f"page.json not found for page '{page}'.")
+
+
+def _append_filter(page_json: Path, filter_obj: dict) -> None:
+    data = json.loads(page_json.read_text(encoding="utf-8"))
+    filters = data.setdefault("filters", [])
+    filters.append(filter_obj)
+    page_json.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+
+@filter_cmd.command("list")
+@click.option("--pbip", required=True)
+@click.option("--page", required=True)
+@click.pass_context
+def filter_list(ctx: click.Context, pbip: str, page: str) -> None:
+    """List all filters applied to a report page."""
+    pj = _page_json_path(pbip, page)
+    data = json.loads(pj.read_text(encoding="utf-8"))
+    filters = data.get("filters", [])
+    if not filters:
+        console.print(f"[yellow]No filters on page '{page}'.[/yellow]")
+        return
+    output_json_or_table(filters, ctx, title=f"Filters on '{page}'")
+
+
+@filter_cmd.command("add-relative-date")
+@click.option("--pbip", required=True)
+@click.option("--page", required=True, help="Page to apply filter to.")
+@click.option("--table", required=True, help="Table containing the date column.")
+@click.option("--column", required=True, help="Date column name.")
+@click.option("--last", type=int, required=True, help="Number of time units (e.g. 30).")
+@click.option(
+    "--unit",
+    type=click.Choice(["Days", "Weeks", "Months", "Quarters", "Years"]),
+    default="Days",
+    show_default=True,
+)
+@click.pass_context
+def filter_add_relative_date(
+    ctx: click.Context,
+    pbip: str,
+    page: str,
+    table: str,
+    column: str,
+    last: int,
+    unit: str,
+) -> None:
+    """Add a relative-date filter to a page (e.g. 'last 30 days').
+
+    \b
+    Example:
+      pbi filter add-relative-date --pbip MyReport --page "Sales" \\
+        --table Calendar --column Date --last 30 --unit Days
+    """
+    if dry_run_echo(ctx, f"add relative-date filter: last {last} {unit} on {table}[{column}]"):
+        return
+
+    filter_obj = {
+        "type": "RelativeDate",
+        "field": {
+            "Column": {
+                "Expression": {"SourceRef": {"Entity": table}},
+                "Property": column,
+            }
+        },
+        "operator": "InTheLast",
+        "timeUnitsCount": last,
+        "timeUnitType": unit,
+    }
+
+    pj = _page_json_path(pbip, page)
+    _append_filter(pj, filter_obj)
+    console.print(
+        f"[green]Filter added:[/green] last {last} {unit} on {table}[{column}] -> page '{page}'"
+    )
+
+
+@filter_cmd.command("add-topn")
+@click.option("--pbip", required=True)
+@click.option("--page", required=True, help="Page to apply filter to.")
+@click.option("--table", required=True, help="Table containing the category field.")
+@click.option("--column", required=True, help="Column to filter (e.g. Product).")
+@click.option("--n", type=int, required=True, help="Number of top items to keep.")
+@click.option("--by-table", required=True, help="Table containing the measure to order by.")
+@click.option("--by-measure", required=True, help="Measure name to order by (e.g. Total Sales).")
+@click.option("--direction", type=click.Choice(["Top", "Bottom"]), default="Top", show_default=True)
+@click.pass_context
+def filter_add_topn(
+    ctx: click.Context,
+    pbip: str,
+    page: str,
+    table: str,
+    column: str,
+    n: int,
+    by_table: str,
+    by_measure: str,
+    direction: str,
+) -> None:
+    """Add a TopN filter to keep only the top (or bottom) N items by a measure.
+
+    \b
+    Example:
+      pbi filter add-topn --pbip MyReport --page "Sales" \\
+        --table Products --column Product --n 10 \\
+        --by-table Sales --by-measure "Total Sales"
+    """
+    if dry_run_echo(ctx, f"add TopN filter: {direction} {n} {table}[{column}] by {by_measure}"):
+        return
+
+    operator = "TopCount" if direction == "Top" else "BottomCount"
+    filter_obj = {
+        "type": "TopN",
+        "field": {
+            "Column": {
+                "Expression": {"SourceRef": {"Entity": table}},
+                "Property": column,
+            }
+        },
+        "operator": operator,
+        "itemCount": {"Literal": {"Value": str(n)}},
+        "orderByField": {
+            "Measure": {
+                "Expression": {"SourceRef": {"Entity": by_table}},
+                "Property": by_measure,
+            }
+        },
+    }
+
+    pj = _page_json_path(pbip, page)
+    _append_filter(pj, filter_obj)
+    console.print(
+        f"[green]Filter added:[/green] {direction} {n} {table}[{column}] by '{by_measure}' -> page '{page}'"  # noqa: E501
+    )
+
+
+@filter_cmd.command("add-value")
+@click.option("--pbip", required=True)
+@click.option("--page", required=True)
+@click.option("--table", required=True)
+@click.option("--column", required=True)
+@click.option("--values", required=True, help="Comma-separated list of values to include.")
+@click.pass_context
+def filter_add_value(
+    ctx: click.Context,
+    pbip: str,
+    page: str,
+    table: str,
+    column: str,
+    values: str,
+) -> None:
+    """Add a basic value-in filter to a page.
+
+    \b
+    Example:
+      pbi filter add-value --pbip MyReport --page "Sales" \\
+        --table financials --column Segment --values "Enterprise,Government"
+    """
+    if dry_run_echo(ctx, f"add value filter: {table}[{column}] in [{values}]"):
+        return
+
+    value_list = [v.strip() for v in values.split(",") if v.strip()]
+    filter_conditions = [
+        {"operator": "Is", "value": {"Literal": {"Value": f"'{v}'"}}} for v in value_list
+    ]
+
+    filter_obj = {
+        "type": "BasicFilter",
+        "field": {
+            "Column": {
+                "Expression": {"SourceRef": {"Entity": table}},
+                "Property": column,
+            }
+        },
+        "operator": "In",
+        "values": filter_conditions,
+    }
+
+    pj = _page_json_path(pbip, page)
+    _append_filter(pj, filter_obj)
+    console.print(
+        f"[green]Filter added:[/green] {table}[{column}] in {value_list} -> page '{page}'"
+    )
+
+
+@filter_cmd.command("clear")
+@click.option("--pbip", required=True)
+@click.option("--page", required=True)
+@click.pass_context
+def filter_clear(ctx: click.Context, pbip: str, page: str) -> None:
+    """Remove all filters from a report page."""
+    if dry_run_echo(ctx, f"clear all filters from page '{page}'"):
+        return
+    pj = _page_json_path(pbip, page)
+    data = json.loads(pj.read_text(encoding="utf-8"))
+    count = len(data.get("filters", []))
+    data["filters"] = []
+    pj.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    console.print(f"[green]Cleared[/green] {count} filter(s) from page '{page}'.")