powerbi-to-sigma

Verifying a change locally

Run both test directories — this plugin keeps suites in scripts/ AND tests/:

cd plugins/powerbi-to-sigma/skills/powerbi-to-sigma
for t in scripts/test-*.rb tests/*.rb; do ruby "$t" >/dev/null 2>&1 || echo "FAIL $t"; done
for t in scripts/test-*.py tests/test-*.py; do python3 "$t" >/dev/null 2>&1 || echo "FAIL $t"; done

Globbing only scripts/test-*.rb reports an accurate-looking count while skipping tests/test-grounding.rb — that omission once merged a change that left main red on 7 assertions. scripts/test-suite-registration.rb enforces that every suite in both directories is also registered in CI, so a new suite cannot be added and silently never run.

Power BI → Sigma

Windows / first run — run the environment doctor before anything else: bash scripts/doctor.sh (macOS/Linux/Git Bash) or powershell -ExecutionPolicy Bypass -File scripts\doctor.ps1 (Windows). It checks Ruby/Python/Node/bash and flags the Python "Store stub" + CRLF with exact fixes. Details: refs/environment.md.

⛔ STEP 1 — THE ONE PATH (do not improvise a workbook)

This conversion runs through one orchestrator that builds every chart and verifies each one's data against Power BI before it's done:

ruby scripts/migrate-powerbi.rb --tmsl <model.bim> --pbir <report-bundle.json> --connection <id> --out <WORK>

• You need the model (TMSL) + report layout (PBIR) first. Get them by CONNECTING to Power BI — do NOT ask the user to hand them over and do NOT proceed without them. Run the device-code login (no Entra app):

  python scripts/fabric-extract.py --report "<report name>" [--workspace "<ws id|name>"] \
    --out-dir <WORK> --report-out-dir <WORK> --report-bundle <WORK>/report-bundle.json
  

  It prints a device code + https://microsoft.com/devicelogin — tell the user to open that URL and enter the code (one sign-in; token caches). Then run the orchestrator with the extracted --tmsl/--pbir. Full recipe: refs/connection.md.
• COMPOSITE / live-connected reports → prefer the local .pbix (the orchestrator PROMPTS for it). Many reports are Power BI composite models (local tables + a reference to a shared/remote dataset) or are thin reports live-connected to a shared dataset. For these, getDefinition of the report's bound model is INCOMPLETE (it misses the report-local measures/calc tables, or isn't a resolvable standalone model), and Power BI blocks export-to-.pbix for live-connected reports, so device-auth can't download it. The COMPLETE model is in the author's local .pbix. The orchestrator DETECTS this (Fabric-path TMSL shows DirectQuery/entity/remote-dataset references) and STOPS with an OPEN QUESTION (exit 10) asking for the local .pbix — do not silently build a DM from the incomplete model. Ask the user for the file and re-run with --pbix (offline tell in a .pbix: its Connections member's RemoteArtifacts). Only pass --allow-incomplete-model if the user knowingly accepts the partial model.
• FULLY-LOCAL .pbix (no Fabric / no tenant / not published). When the user has only a local .pbix on disk, skip the CONNECT/EXTRACT steps entirely — run the orchestrator with --pbix and it extracts BOTH halves locally (Phase 0):

  ruby scripts/migrate-powerbi.rb --pbix <file.pbix> --connection <id> --database <DB> --schema <SCHEMA> --out <WORK>
  

  • Model: scripts/extract-model-pbix.py reads the .pbix's binary VertiPaq DataModel with pbixray and emits a TMSL model.bim (same shape --tmsl eats), including DAX calculated tables (pbixray.dax_tables) as calculated partitions rather than fake warehouse tables. pbixray must be installed — its xpress9/xmhuffman deps ship broken sdists and must be built from source; one-time setup in refs/local-pbix.md. Without pbixray the model half exits with a clear install hint (the report half and the Fabric --tmsl path are unaffected).
  • Report: scripts/extract-report-classic.py --pbix <file> unzips the Report/Layout member (a single UTF-16LE classic sections[] doc) — no Fabric. It also accepts --report-layout <file> for an already-extracted Layout.
  • Import-mode .pbix with no live warehouse to point at? Land the frozen data first (see the Import-mode → Snowflake data-landing skill), then pass that connection/db/schema here.
• NEVER hand-author a workbook JSON and curl-POST it to /v2/workbooks, and never lay out empty "placeholder" pages. That bypasses the DAX conversion, chart build, and parity gate and ships an EMPTY workbook (invented page names, no elements) — the #1 way this migration fails. If you cannot extract the model (no Fabric access / not published), STOP and tell the user you need to connect to Power BI (device-code) or that the report must be published — do not fall back to a hand-built shell.
• "Done" is not "pages exist." The migration is complete only when ruby scripts/verify-complete.rb --workdir <WORK> prints ✅ DONE — i.e. the assert-phase6-ran parity gate passed with real chart elements. An empty or placeholder workbook is never done, no matter how it looks.
• Small/older models (e.g. running on Haiku): if the report is large or complex, say so and confirm scope with the user before building — don't silently degrade to a partial shell.