powerbi-pbip-forensics 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. powerbi_pbip_forensics-1.0.0/LICENSE +11 -0
  2. powerbi_pbip_forensics-1.0.0/PKG-INFO +573 -0
  3. powerbi_pbip_forensics-1.0.0/README.md +530 -0
  4. powerbi_pbip_forensics-1.0.0/pyproject.toml +103 -0
  5. powerbi_pbip_forensics-1.0.0/setup.cfg +4 -0
  6. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/__init__.py +5 -0
  7. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/__main__.py +3 -0
  8. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/__init__.py +1 -0
  9. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/audit.py +55 -0
  10. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/dax_rules.py +232 -0
  11. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/diff.py +212 -0
  12. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/filters.py +165 -0
  13. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/inventory.py +82 -0
  14. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/model_rules.py +212 -0
  15. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/performance.py +162 -0
  16. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/semantic.py +245 -0
  17. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/stage_model.py +30 -0
  18. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/stage_visual.py +122 -0
  19. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/analyzers/visual_rules.py +191 -0
  20. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/automation.py +92 -0
  21. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/cli.py +305 -0
  22. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/discovery/__init__.py +1 -0
  23. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/discovery/detector.py +68 -0
  24. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/entrypoints/__init__.py +1 -0
  25. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/entrypoints/common.py +62 -0
  26. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/entrypoints/ep_diff.py +27 -0
  27. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/entrypoints/ep_full_audit.py +28 -0
  28. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/entrypoints/ep_inspect.py +30 -0
  29. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/entrypoints/ep_model_audit.py +27 -0
  30. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/entrypoints/ep_perf_log.py +39 -0
  31. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/entrypoints/ep_report.py +46 -0
  32. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/entrypoints/ep_visual_deps.py +48 -0
  33. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/findings/__init__.py +1 -0
  34. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/findings/catalog.py +107 -0
  35. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/findings/issues.py +41 -0
  36. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/findings/summary.py +21 -0
  37. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/graph/__init__.py +1 -0
  38. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/graph/model_graph.py +256 -0
  39. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/models.py +255 -0
  40. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/parsers/__init__.py +1 -0
  41. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/parsers/dax.py +234 -0
  42. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/parsers/model_loader.py +147 -0
  43. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/parsers/pbir.py +298 -0
  44. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/parsers/tmdl.py +367 -0
  45. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/py.typed +0 -0
  46. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/reporting/__init__.py +1 -0
  47. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/reporting/html_report.py +619 -0
  48. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/reporting/insights.py +291 -0
  49. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/reporting/merge.py +60 -0
  50. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/reporting/render.py +260 -0
  51. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/security/__init__.py +1 -0
  52. powerbi_pbip_forensics-1.0.0/src/pbip_forensics/security/safety.py +161 -0
  53. powerbi_pbip_forensics-1.0.0/src/powerbi_pbip_forensics.egg-info/PKG-INFO +573 -0
  54. powerbi_pbip_forensics-1.0.0/src/powerbi_pbip_forensics.egg-info/SOURCES.txt +56 -0
  55. powerbi_pbip_forensics-1.0.0/src/powerbi_pbip_forensics.egg-info/dependency_links.txt +1 -0
  56. powerbi_pbip_forensics-1.0.0/src/powerbi_pbip_forensics.egg-info/entry_points.txt +2 -0
  57. powerbi_pbip_forensics-1.0.0/src/powerbi_pbip_forensics.egg-info/requires.txt +10 -0
  58. powerbi_pbip_forensics-1.0.0/src/powerbi_pbip_forensics.egg-info/top_level.txt +1 -0
@@ -0,0 +1,11 @@
1
+ Power BI PBIP Forensics
2
+ Copyright (c) 2026 Vinicius de Souza Santos. All rights reserved.
3
+
4
+ This software and its documentation are proprietary and confidential.
5
+ No license, express or implied, is granted to use, copy, modify, distribute,
6
+ sublicense or sell this software, except under a separate written agreement
7
+ with the copyright holder or under the terms of a marketplace listing
8
+ explicitly published by the copyright holder.
9
+
10
+ The licensing model for commercial distribution has not been decided yet.
11
+ See docs/licensing-options.md.
@@ -0,0 +1,573 @@
1
+ Metadata-Version: 2.4
2
+ Name: powerbi-pbip-forensics
3
+ Version: 1.0.0
4
+ Summary: Evidence-based static forensics for Power BI PBIP/PBIR/TMDL projects and Performance Analyzer logs.
5
+ Author: Vinicius de Souza Santos
6
+ License-Expression: LicenseRef-Proprietary
7
+ Project-URL: Homepage, https://github.com/ViniciusKanh/powerbi-pbip-forensics
8
+ Project-URL: Repository, https://github.com/ViniciusKanh/powerbi-pbip-forensics
9
+ Project-URL: Documentation, https://github.com/ViniciusKanh/powerbi-pbip-forensics#readme
10
+ Project-URL: Changelog, https://github.com/ViniciusKanh/powerbi-pbip-forensics/blob/main/CHANGELOG.md
11
+ Project-URL: Issues, https://github.com/ViniciusKanh/powerbi-pbip-forensics/issues
12
+ Keywords: power-bi,pbip,pbir,tmdl,dax,audit,forensics
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Environment :: Console
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Intended Audience :: Information Technology
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Operating System :: OS Independent
22
+ Classifier: Operating System :: Microsoft :: Windows
23
+ Classifier: Operating System :: POSIX :: Linux
24
+ Classifier: Operating System :: MacOS
25
+ Classifier: Topic :: Software Development :: Quality Assurance
26
+ Classifier: Topic :: Office/Business
27
+ Classifier: Natural Language :: English
28
+ Classifier: Natural Language :: Portuguese (Brazilian)
29
+ Classifier: Typing :: Typed
30
+ Requires-Python: >=3.11
31
+ Description-Content-Type: text/markdown
32
+ License-File: LICENSE
33
+ Provides-Extra: dev
34
+ Requires-Dist: pytest>=8; extra == "dev"
35
+ Requires-Dist: pytest-cov>=5; extra == "dev"
36
+ Requires-Dist: ruff>=0.5; extra == "dev"
37
+ Requires-Dist: mypy>=1.10; extra == "dev"
38
+ Requires-Dist: build>=1.2; extra == "dev"
39
+ Requires-Dist: twine>=5.1; extra == "dev"
40
+ Requires-Dist: setuptools>=77; extra == "dev"
41
+ Requires-Dist: wheel>=0.43; extra == "dev"
42
+ Dynamic: license-file
43
+
44
+ <div align="center">
45
+
46
+ <img src="docs/assets/logo-512.png" alt="Power BI PBIP Forensics" width="200">
47
+
48
+ # Power BI PBIP Forensics
49
+
50
+ ### Ask your AI agent *why* your Power BI report behaves the way it does, and get answers backed by evidence from your project files.
51
+
52
+ ![Version](https://img.shields.io/badge/version-1.0.0-0B5ED7)
53
+ ![Python](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)
54
+ ![Tests](https://img.shields.io/badge/tests-101%20passing-2EA44F)
55
+ ![Rules](https://img.shields.io/badge/diagnostic%20rules-39-0B5ED7)
56
+ ![Dependencies](https://img.shields.io/badge/dependencies-none-2EA44F)
57
+ ![Mode](https://img.shields.io/badge/mode-read--only%20%7C%20offline-F2A900)
58
+ ![License](https://img.shields.io/badge/license-proprietary-6C757D)
59
+
60
+ [What it does](#-what-it-does) •
61
+ [Report tour](#-report-tour) •
62
+ [How the skill works](#-how-the-skill-works) •
63
+ [Quick start](#-quick-start) •
64
+ [Ask it](#-what-you-can-ask) •
65
+ [Engine](#%EF%B8%8F-inside-the-engine) •
66
+ [Scripts](#-skill-scripts) •
67
+ [Safety](#%EF%B8%8F-safety-and-privacy) •
68
+ [Developers](#-for-developers)
69
+
70
+ <br>
71
+
72
+ <img src="docs/assets/report-dark.png" alt="Audit report overview in dark mode" width="900">
73
+
74
+ <sub>Interactive HTML report generated from the bundled synthetic project (`examples/synthetic_project`).</sub>
75
+
76
+ </div>
77
+
78
+ ---
79
+
80
+ ## 🔎 What it does
81
+
82
+ **Power BI PBIP Forensics** is an AI agent skill, with a Python engine behind it, that audits Power BI projects
83
+ saved in the **PBIP** format. It reads the report definition (**PBIR**) and the semantic model (**TMDL** or
84
+ `model.bim`) as text, builds the relationship graph and the DAX dependency graph, and explains:
85
+
86
+ - 🔗 **Filters that do not propagate**: inactive relationships, one-way relationships blocking the path, disconnected tables, ambiguous paths.
87
+ - 🧮 **DAX problems**: missing references, circular dependencies, `ALL`/`REMOVEFILTERS` overriding slicers, totals that differ from the visible rows, costly patterns.
88
+ - 📊 **Broken visuals**: fields that no longer exist in the model, tables combined without a relationship, page filters that cannot reach the measures.
89
+ - 🧹 **Cleanup opportunities**: unused measures and columns, measures without a format, visible foreign keys, auto date tables, overloaded pages.
90
+ - 🐢 **Slow visuals**: ranked from a Performance Analyzer export (*preview*).
91
+ - 🔀 **Change impact**: what changed between two versions, and which measures and visuals to retest.
92
+
93
+ It is written for **two audiences at once**: a business user gets a health score, a plain-language summary and a
94
+ short list of what to fix first; a BI developer gets file paths, line numbers, evidence and a way to verify each
95
+ finding.
96
+
97
+ Every finding states:
98
+
99
+ | | |
100
+ |---|---|
101
+ | **Where** | File path, line and object |
102
+ | **Why** | The evidence that triggered it |
103
+ | **How sure** | `confirmed` · `potential` · `inconclusive` |
104
+ | **What to do** | A suggested fix |
105
+ | **How to verify** | A check you can run in Power BI Desktop |
106
+
107
+ ## 🖼️ Report tour
108
+
109
+ One command produces a single self-contained HTML file (no internet needed, light and dark themes, works on
110
+ mobile), plus Markdown and JSON versions. All screenshots below come from the bundled synthetic project.
111
+
112
+ ### 1. Health score and plain-language summary
113
+
114
+ Six gauges score the data model, DAX measures, report & visuals, performance and project files. The score is an
115
+ **indicative** summary of the findings, and its formula is printed in the report. Below the gauges, a short
116
+ summary explains the situation without jargon.
117
+
118
+ <img src="docs/assets/report-scores.png" alt="Health score gauges and plain-language summary" width="900">
119
+
120
+ ### 2. What to do first
121
+
122
+ Findings are grouped by rule and turned into actions, ranked by severity and effort (**quick win**, **medium
123
+ effort**, **structural**). Each card links to the detailed findings.
124
+
125
+ <img src="docs/assets/report-quick-wins.png" alt="Prioritised action cards" width="900">
126
+
127
+ ### 3. Findings with evidence
128
+
129
+ Filter by severity, status, category or rule, or search by text. Each finding opens to show the source file, the
130
+ evidence, the impact, a recommendation and how to verify it.
131
+
132
+ <img src="docs/assets/report-findings.png" alt="Expanded finding with evidence" width="900">
133
+
134
+ ### 4. Model map
135
+
136
+ The relationship diagram is laid out in layers: dimensions, bridges, facts and disconnected tables. Inactive
137
+ relationships are dashed, bidirectional ones are orange and **ambiguous filter paths are red**. Auto date tables
138
+ are hidden to keep the map readable.
139
+
140
+ <img src="docs/assets/report-model-map.png" alt="Semantic model relationship map" width="900">
141
+
142
+ ### 5. Measures
143
+
144
+ The most complex measures (functions, iterators, nesting, dependency depth), the central measures that the rest
145
+ of the model depends on, and how measures are spread across display folders.
146
+
147
+ <img src="docs/assets/report-measures.png" alt="Measure complexity and hub statistics" width="900">
148
+
149
+ ### 6. Pages and performance
150
+
151
+ One card per page shows visuals, slicers, filters, measures, custom visuals, broken bindings and the tables used.
152
+ When a Performance Analyzer export is available, visuals are ranked by measured time split into DAX query,
153
+ visual display and other.
154
+
155
+ <img src="docs/assets/report-pages.png" alt="Page cards" width="900">
156
+ <img src="docs/assets/report-performance.png" alt="Performance Analyzer ranking" width="900">
157
+
158
+ The report also includes a rules overview, change impact, root-cause hypotheses, recommended actions, limitations
159
+ and the full inventory (tables, columns, measures, relationships and data-source connectors).
160
+
161
+ ## 🤖 How the skill works
162
+
163
+ The skill is a folder with a `SKILL.md` (instructions for the agent), seven standalone Python scripts,
164
+ references and answer templates. You talk to the agent; the agent decides which scripts to run.
165
+
166
+ ```mermaid
167
+ sequenceDiagram
168
+ actor U as You
169
+ participant A as AI agent
170
+ participant S as Skill scripts (local)
171
+ participant P as PBIP folder (read-only)
172
+ U->>A: "Why does this table show unrelated accounts?"
173
+ A->>A: Reads SKILL.md and picks the scripts
174
+ A->>U: Asks permission to read the project folder
175
+ A->>S: pbip_visual_deps.py --from-table Customer --to-table Account
176
+ S->>P: Reads .pbip, PBIR and TMDL files as text
177
+ S-->>A: JSON with findings, evidence and limits
178
+ A-->>U: Answer: evidence, ranked hypotheses, how to verify, limitations
179
+ A->>S: pbip_full_audit.py (when asked for a full audit)
180
+ S-->>U: audit-report.html · .md · findings.json
181
+ ```
182
+
183
+ 1. **Trigger.** You ask a question about a Power BI project, or ask for an audit.
184
+ 2. **Scope.** The agent asks which folder it may read and writes outputs to a separate folder.
185
+ 3. **Analysis.** The agent runs only the scripts the question needs: inventory, model audit, visual
186
+ dependencies, performance log, diff, or the one-shot full audit.
187
+ 4. **Answer.** The agent keeps **script evidence** separate from **its own reasoning**, ranks hypotheses by
188
+ confidence, tells you how to verify each one in Power BI Desktop, and states the limits of a static analysis
189
+ (template: [`templates/investigation-response.md`](agensi/powerbi-pbip-forensics/templates/investigation-response.md)).
190
+ 5. **Report.** For audits, it produces the interactive HTML report shown above.
191
+
192
+ Nothing is executed from the project: DAX, M and JSON are parsed as data. Nothing leaves your machine.
193
+
194
+ ## 🚀 Quick start
195
+
196
+ > **Requirements:** Python **3.11+** (standard library only) and a report saved as a Power BI project
197
+ > (*File → Save as → Power BI project (.pbip)*). Binary `.pbix` files are not supported.
198
+
199
+ ### Option A: as an agent skill
200
+
201
+ 1. Get the skill: buy it on **Agensi**, or use the folder `agensi/powerbi-pbip-forensics/` from this repository.
202
+ 2. Install it where your agent loads skills. For **Claude Code**:
203
+
204
+ ```powershell
205
+ # Windows (PowerShell)
206
+ Copy-Item -Recurse .\agensi\powerbi-pbip-forensics "$env:USERPROFILE\.claude\skills\powerbi-pbip-forensics"
207
+ ```
208
+
209
+ ```bash
210
+ # Linux / macOS
211
+ cp -r agensi/powerbi-pbip-forensics ~/.claude/skills/powerbi-pbip-forensics
212
+ ```
213
+
214
+ For other agents, point them to `SKILL.md`. Any agent that can read Markdown and run local Python scripts can
215
+ use the skill.
216
+ 3. Open your agent in the folder that contains your `.pbip` project and ask a question (see below).
217
+
218
+ ### Option B: one-click audit (Windows)
219
+
220
+ Drag your PBIP project folder onto **`pbip-audit.cmd`**, or run:
221
+
222
+ ```powershell
223
+ .\pbip-audit.cmd "C:\BI\MyProject"
224
+ ```
225
+
226
+ It skips backup folders, auto-detects a Performance Analyzer export inside the project, writes the report to
227
+ `C:\BI\MyProject-forensics\` and opens the HTML report. The equivalent engine command is
228
+ `py -m pbip_forensics run --project <folder> --open --lang pt-BR` (with `PYTHONPATH=src`).
229
+
230
+ ### Option C: run the scripts yourself
231
+
232
+ ```powershell
233
+ $S = ".\agensi\powerbi-pbip-forensics\scripts"
234
+ $P = "C:\BI\MyProject" # your PBIP folder (read-only)
235
+ $O = "C:\BI\audit" # output folder, must be outside the project
236
+
237
+ py $S\pbip_full_audit.py --project $P --output $O --lang pt-BR # everything + HTML report
238
+ py $S\pbip_visual_deps.py --project $P --from-table Customer --to-table Account --output $O
239
+ ```
240
+
241
+ Open `C:\BI\audit\audit-report.html`. Use `--lang pt-BR` for Brazilian Portuguese headings and summaries.
242
+
243
+ ## 📦 Install the CLI (Python package)
244
+
245
+ > **Requirements:** Python **3.11, 3.12 or 3.13** on Windows, Linux or macOS. The engine uses only the
246
+ > standard library at runtime — installing the CLI pulls in no third-party dependencies.
247
+
248
+ <details>
249
+ <summary><b>Install from a wheel (recommended — offline-friendly)</b></summary>
250
+
251
+ Build artifacts are **not** published on PyPI yet (see [Future publication](#-future-publication-not-done-yet)
252
+ below). Until then, install directly from a built wheel — built locally with `python -m build` (see
253
+ [For developers](#-for-developers)), or one you were given by the author:
254
+
255
+ ```powershell
256
+ # Windows (PowerShell)
257
+ py -3 -m venv .venv
258
+ .\.venv\Scripts\pip install .\dist\powerbi_pbip_forensics-1.0.0-py3-none-any.whl
259
+ .\.venv\Scripts\pbip-forensics --version
260
+ ```
261
+
262
+ ```bash
263
+ # Linux / macOS
264
+ python3 -m venv .venv
265
+ ./.venv/bin/pip install ./dist/powerbi_pbip_forensics-1.0.0-py3-none-any.whl
266
+ ./.venv/bin/pbip-forensics --version
267
+ ```
268
+
269
+ A virtual environment is not required — `pip install --user <wheel>` or `pipx install <wheel>` also work —
270
+ but it keeps the install isolated and easy to remove (`pipx` additionally puts `pbip-forensics` on your
271
+ `PATH` automatically).
272
+ </details>
273
+
274
+ <details>
275
+ <summary><b>Install from a private index</b></summary>
276
+
277
+ If you host the wheel on a private index or simple-repository (Artifactory, Azure Artifacts, a private
278
+ `devpi`, a signed URL to cloud storage, etc.):
279
+
280
+ ```bash
281
+ pip install powerbi-pbip-forensics --index-url https://<your-private-index>/simple/
282
+ ```
283
+ </details>
284
+
285
+ <details>
286
+ <summary><b>Basic commands</b></summary>
287
+
288
+ ```bash
289
+ pbip-forensics --version
290
+ pbip-forensics --help
291
+ pbip-forensics run --project "C:\BI\MyProject" --open --lang pt-BR
292
+ pbip-forensics scan --project "C:\BI\MyProject"
293
+ pbip-forensics audit --project "C:\BI\MyProject" --output .\reports --format all --fail-on HIGH
294
+ pbip-forensics performance --input .\reports\performance.json
295
+ pbip-forensics diff --before "C:\BI\MyProject" --after "C:\BI\MyProject_v2"
296
+ pbip-forensics investigate --project "C:\BI\MyProject" --from-table Customer --to-table Account
297
+ pbip-forensics report --input .\reports\findings.json --format html
298
+ python -m pbip_forensics --version # equivalent module entry point, no PATH needed
299
+ ```
300
+
301
+ `--project` is read-only and is never modified. `--output` must point **outside** the audited project (the
302
+ tool refuses to write inside it). `--fail-on {CRITICAL,HIGH,MEDIUM,LOW,INFO}` makes `audit`/`run` return exit
303
+ code `1` when a finding at or above that severity exists — wire this into CI to gate a pipeline on Power BI
304
+ quality. See [Exit codes](#exit-codes) below.
305
+ </details>
306
+
307
+ <details>
308
+ <summary><b>Update / uninstall / check version</b></summary>
309
+
310
+ ```bash
311
+ pip install --force-reinstall ./dist/powerbi_pbip_forensics-<new-version>-py3-none-any.whl # update
312
+ pip uninstall powerbi-pbip-forensics # uninstall
313
+ pip show powerbi-pbip-forensics # installed version
314
+ pbip-forensics --version # CLI version
315
+ ```
316
+ </details>
317
+
318
+ <details>
319
+ <summary><a name="exit-codes"></a><b>Exit codes</b></summary>
320
+
321
+ | Code | Meaning |
322
+ |---|---|
323
+ | 0 | Success (no finding reached `--fail-on`, or `--fail-on` not set) |
324
+ | 1 | At least one finding at/above the `--fail-on` severity |
325
+ | 2 | Invalid input (bad path, bad JSON, missing required option) |
326
+ | 3 | A configured limit was exceeded (file count, file size) |
327
+ | 4 | Refused by security policy (output inside the audited project, sensitive file, out-of-scope path) |
328
+ | 5 | Invalid Performance Analyzer log |
329
+ | 10 | Internal error (re-run with `--debug` for the traceback) |
330
+ </details>
331
+
332
+ <details>
333
+ <summary><b>CI/CD integration</b></summary>
334
+
335
+ ```yaml
336
+ # Example: GitHub Actions step that fails the pipeline on HIGH+ findings
337
+ - name: Audit Power BI project
338
+ run: |
339
+ pip install ./dist/powerbi_pbip_forensics-1.0.0-py3-none-any.whl
340
+ pbip-forensics audit --project "$GITHUB_WORKSPACE/MyProject.Report/.." \
341
+ --output "$RUNNER_TEMP/pbip-audit" --format all --fail-on HIGH
342
+ ```
343
+
344
+ The tool never reaches the network and never phones home (see [Safety and privacy](#🛡%EF%B8%8F-safety-and-privacy));
345
+ exit codes make it CI-friendly without extra tooling. For how *this repository's own* CI is set up (lint,
346
+ type-check, tests, build, no publishing), see
347
+ [`.github/workflows/python-package-ci.yml`](.github/workflows/python-package-ci.yml).
348
+ </details>
349
+
350
+ <details>
351
+ <summary><b>Privacy policy, license and limitations</b></summary>
352
+
353
+ - **Privacy:** static, local, read-only analysis. DAX/M/JSON are parsed as text, never executed. No
354
+ telemetry, no network calls, no data leaves your machine. See
355
+ [🛡️ Safety and privacy](#🛡%EF%B8%8F-safety-and-privacy) below and
356
+ [`src/pbip_forensics/security/safety.py`](src/pbip_forensics/security/safety.py).
357
+ - **License:** proprietary (`LicenseRef-Proprietary`); installing or receiving the package does not grant
358
+ any right to use, copy or redistribute it beyond what [LICENSE](LICENSE) allows. See
359
+ [📄 License](#-license) and [docs/licensing-options.md](docs/licensing-options.md).
360
+ - **Limitations:** static analysis only, with documented gaps in filter-propagation, DAX coverage and
361
+ format support. See [docs/limitations.md](docs/limitations.md) before relying on a finding for a
362
+ production decision.
363
+
364
+ </details>
365
+
366
+ <details>
367
+ <summary><a name="-future-publication-not-done-yet"></a><b>Future publication (not done yet)</b></summary>
368
+
369
+ `powerbi-pbip-forensics` is **not currently published** on PyPI or TestPyPI, and no publish has been run as
370
+ part of preparing this CLI. The `Private :: Do Not Upload` classifier in `pyproject.toml` is a deliberate
371
+ safeguard: PyPI refuses any upload carrying it, so an accidental `twine upload` cannot leak the package.
372
+ Publishing requires removing that classifier and explicit author authorization — see
373
+ [docs/licensing-options.md](docs/licensing-options.md) for the licensing decision that must be made first,
374
+ and the project's internal build report for the step-by-step TestPyPI/PyPI procedure once authorized.
375
+ </details>
376
+
377
+ ## 💬 What you can ask
378
+
379
+ | You ask the agent | It checks |
380
+ |---|---|
381
+ | *"Audit this project before I publish it."* | All rules, health score, prioritised actions, full HTML report |
382
+ | *"Why is the Customer Accounts table showing accounts unrelated to the selected customer?"* | Relationship paths hop by hop, inactive or one-way relationships, visual bindings |
383
+ | *"Why does **Total Revenue** ignore my slicer?"* | `ALL` / `REMOVEFILTERS` / `CROSSFILTER` in the measure and its dependencies |
384
+ | *"My total is different from the sum of the rows. What should I check?"* | Non-additive patterns (`IF` on measures, `DISTINCTCOUNT`, `HASONEVALUE`), many-to-many relationships |
385
+ | *"What can I delete to make the model lighter?"* | Unused measures and columns, auto date tables, isolated tables |
386
+ | *"Which visuals are slowing this page down?"* | Measured DAX query, visual display and *Other* times from your Performance Analyzer export |
387
+ | *"Compare `v1` and `v2`. What do I need to retest?"* | Changed measures, columns and relationships, and every dependent measure and visual |
388
+
389
+ ### Example answer
390
+
391
+ Real script output from `examples/synthetic_project`:
392
+
393
+ ```text
394
+ VIS006 HIGH potential Unrelated tables combined in 'Customer Accounts' (tableEx): 'Account' and 'Customer'
395
+ No active relationship path between them in either direction
396
+ → ContosoRetail.Report/definition/pages/overview01/visuals/v_table_accounts/visual.json
397
+
398
+ MOD002 LOW potential Inactive relationship not activated by any measure: Account -> Customer
399
+ 'Account'[CustomerKey] (many) -> 'Customer'[CustomerKey] (one) · isActive: false
400
+ → ContosoRetail.SemanticModel/definition/relationships.tmdl:27
401
+
402
+ Investigation Customer → Account
403
+ BLOCKED PATH: 'Customer' -> 'Account' via 'Account'[CustomerKey] -> 'Customer'[CustomerKey] [INACTIVE]
404
+ #1 [high confidence] Inactive relationship on the only path from 'Customer' to 'Account'.
405
+ Verify: confirm isActive=false in Model view; test a measure with USERELATIONSHIP(...).
406
+ ```
407
+
408
+ ## ⚙️ Inside the engine
409
+
410
+ ```mermaid
411
+ flowchart LR
412
+ A[PBIP folder<br/>read-only] --> B[Discovery<br/>.pbip · .Report · .SemanticModel]
413
+ B --> C[Parsers<br/>PBIR · TMDL · model.bim]
414
+ C --> D[DAX tokenizer<br/>call tree · references]
415
+ C --> E[Relationship graph<br/>paths · cycles · roles]
416
+ D --> F[39 rules<br/>MOD · DAX · VIS · COL · PERF]
417
+ E --> F
418
+ G[Performance Analyzer<br/>export .json] --> F
419
+ F --> H[Findings with evidence<br/>+ ranked hypotheses]
420
+ H --> I[Insights<br/>scores · summary · actions · model map]
421
+ I --> J[Report<br/>HTML · Markdown · JSON]
422
+ ```
423
+
424
+ - **Real parsing, not guessing.** The TMDL parser follows indentation, so it handles multi-line expressions,
425
+ triple-backtick blocks, quoted names, hierarchies and sort-by columns. The DAX tokenizer respects strings,
426
+ comments and `[references]`. PBIR fields follow Microsoft's published JSON schemas, including fields used only
427
+ in conditional formatting.
428
+ - **Graph algorithms.** Filter paths are direction-aware. Blocked paths are explained hop by hop. Ambiguous loops
429
+ are separated from harmless ones, and measure cycles are found with Tarjan's algorithm.
430
+ - **False-positive safeguards.** Lookup and parameter tables, measures that link tables, role-playing dates and
431
+ formatting-only references are recognised. Each rule's safeguard is documented.
432
+ - **Honest statuses.** `confirmed` means proven by the files or measured in a log. `potential` means a risk to
433
+ verify. `inconclusive` means the engine could not interpret it. No invented percentages, values or timings.
434
+
435
+ | Rule family | What it covers |
436
+ |---|---|
437
+ | `PRS` / `SEC` | Parsing problems, missing files, unsupported formats, items skipped by the safety policy |
438
+ | `MOD001`–`MOD010` | Broken, inactive, bidirectional, many-to-many and ambiguous relationships; disconnected tables; key type mismatch; auto date tables; visible foreign keys |
439
+ | `DAX001`–`DAX014` | Missing references, circular dependencies, costly `FILTER`/iterators/context transition, filter overrides, non-additive totals, `/` without `DIVIDE`, unused or unformatted measures |
440
+ | `VIS001`–`VIS008` | Broken bindings, uninterpretable visuals, filters that cannot reach measures, unrelated tables in a grid, overloaded pages |
441
+ | `COL001` | Columns with no detected use |
442
+ | `PERF001` | Visuals over the measured time thresholds |
443
+
444
+ Full rule list with severities and safeguards: [docs/diagnostic-rules.md](docs/diagnostic-rules.md).
445
+
446
+ **Health score formula:** `score = 100 × exp(−Σ weight(severity) × factor(status) / 40)`, with weights CRITICAL 20,
447
+ HIGH 8, MEDIUM 3, LOW 1, INFO 0 and factors confirmed 1, potential 0.5, inconclusive 0.25. The overall score is the
448
+ mean of the measured areas. It summarises the findings; it is not a quality certificate.
449
+
450
+ ## 🧰 Skill scripts
451
+
452
+ Each script is **standalone**: one file, Python standard library only, no network. It reads only the paths you
453
+ pass, writes only to `--output`, and works on Windows, Linux and macOS.
454
+
455
+ | Script | Purpose | Main arguments |
456
+ |---|---|---|
457
+ | `pbip_full_audit.py` | **One-shot**: all analyses + interactive HTML/Markdown/JSON report | `--project` `--output` `--lang` |
458
+ | `pbip_inspect.py` | Inventory of reports, pages, visuals, tables, measures, relationships and data-source connectors | `--project` |
459
+ | `pbip_model_audit.py` | Relationship and model structure checks plus DAX static analysis | `--project` |
460
+ | `pbip_visual_deps.py` | Page → Visual → Field → Table map, broken bindings, filter investigation | `--project` `--from-table` `--to-table` `--measure` `--visual` |
461
+ | `pbip_perf_log.py` | Ranks visuals by measured duration *(preview)* | `--input` `--medium-ms` `--high-ms` |
462
+ | `pbip_diff.py` | Changes between two versions and their impact | `--before` `--after` |
463
+ | `pbip_report.py` | Merges the JSON outputs into Markdown, HTML and JSON | `--input …` `--format` `--lang en\|pt-BR` |
464
+
465
+ **Exit codes:** `0` OK · `2` invalid input · `3` size limit exceeded · `4` refused by the safety policy ·
466
+ `5` invalid performance log · `10` internal error.
467
+
468
+ ## 🛡️ Safety and privacy
469
+
470
+ - **Read-only.** The project is never modified, and reports must be written outside it.
471
+ - **Scope-locked.** Only the folder you authorize is read. Symbolic links that point outside it are not followed.
472
+ - **No secrets.** `.env`, keys, certificates, `localSettings.json` and `cache.abf` are never opened. Only connector
473
+ names (for example `Sql.Database`) are reported, never connection strings or credentials.
474
+ - **No execution.** DAX, M and JSON are parsed as data and never evaluated.
475
+ - **No network.** Everything runs locally and offline; the HTML report has no external resources.
476
+ - **Untrusted content.** Text inside the project, such as measure names and descriptions, is treated as data and
477
+ never as instructions. HTML output is escaped.
478
+
479
+ ## ⚠️ Limitations
480
+
481
+ - **Static analysis.** No DAX is executed and no data is read, so the skill never claims values or totals.
482
+ - **Formats.** PBIX/PBIT are not supported. Support for the older PBIR-Legacy report format is best-effort.
483
+ - **Usage scope.** Unused measures/columns are reported only when every bound report is PBIR and fully
484
+ interpretable; RLS roles, other reports and external tools are not visible. Confirm with lineage before removing.
485
+ - **Not modelled:** calculation groups, row-level security, `TREATAS` virtual relationships, and visual
486
+ interactions or bookmarks.
487
+ - **Performance Analyzer (preview).** Validated with synthetic exports only.
488
+ - **Language.** Finding texts are in English. Headings, scores, summaries and action titles are available in
489
+ English and Brazilian Portuguese.
490
+
491
+ Details: [docs/limitations.md](docs/limitations.md).
492
+
493
+ ---
494
+
495
+ ## 👩‍💻 For developers
496
+
497
+ <details>
498
+ <summary><b>Engine CLI</b></summary>
499
+
500
+ ```bash
501
+ pip install -e ".[dev]"
502
+ pbip-forensics run --project ./examples/synthetic_project [--lang pt-BR] [--open]
503
+ pbip-forensics scan --project ./examples/synthetic_project
504
+ pbip-forensics audit --project ./examples/synthetic_project --output ./reports [--performance perf.json] [--fail-on HIGH]
505
+ pbip-forensics investigate --project ./examples/synthetic_project --from-table Customer --to-table Account
506
+ pbip-forensics performance --input ./examples/sample_performance/performance.json
507
+ pbip-forensics diff --before ./examples/synthetic_project --after ./examples/synthetic_project_v2
508
+ pbip-forensics report --input ./reports/findings.json --format html
509
+ ```
510
+
511
+ `--fail-on` returns exit code 1 when there are findings at or above the given severity, which is useful in CI.
512
+ </details>
513
+
514
+ <details>
515
+ <summary><b>Repository layout</b></summary>
516
+
517
+ ```text
518
+ src/pbip_forensics/ engine: security · discovery · parsers · graph · analyzers · findings · reporting · cli
519
+ agensi/powerbi-pbip-forensics/ the skill: SKILL.md · scripts/ (generated) · references/ · templates/
520
+ tools/ build_skill · package_agensi · make_fixtures · run_demo · gen_docs · script_metrics
521
+ tests/ unit · integration (including isolated script parity) · packaging (wheel/sdist install) · fixtures
522
+ examples/ synthetic projects · sample Performance Analyzer log · sample reports
523
+ docs/ architecture · formats · rules · limitations · validation · packaging & publishing · Agensi docs · assets
524
+ ```
525
+ </details>
526
+
527
+ <details>
528
+ <summary><b>Tests and packaging</b></summary>
529
+
530
+ ```bash
531
+ python -m pytest -o addopts="" -q # 112 tests (101 engine/skill + 11 packaging)
532
+ python -m pytest -q -m "not packaging" # fast subset, skips the real build+install tests
533
+ ruff check src tests tools && mypy
534
+ python tools/build_skill.py # regenerate standalone scripts from the engine
535
+ python tools/gen_docs.py # regenerate the rule catalog docs
536
+ python tools/package_agensi.py # build and validate dist/powerbi-pbip-forensics-v1.0.0.zip
537
+
538
+ python -m build # build the pip wheel + sdist into dist/
539
+ python -m twine check dist/*.whl dist/*.tar.gz # validate package metadata
540
+ ```
541
+
542
+ Each generated skill script is also run alone, under `python -I`, and its output is compared with the
543
+ engine's (see [docs/validation-results.md](docs/validation-results.md)). The `tests/packaging/` suite builds
544
+ the real wheel/sdist and installs each in a fresh, isolated virtual environment to prove the CLI works with
545
+ no `PYTHONPATH` and no repository path on `sys.path` (see
546
+ [docs/python-packaging.md](docs/python-packaging.md) for the full packaging and future-publication notes).
547
+ </details>
548
+
549
+ ### Documentation
550
+
551
+ | | |
552
+ |---|---|
553
+ | [Architecture](docs/architecture.md) | Modules, data flow, skill bundling |
554
+ | [Supported formats](docs/supported-formats.md) | PBIP / PBIR / TMDL / TMSL / Performance Analyzer fields and versions |
555
+ | [Diagnostic rules](docs/diagnostic-rules.md) | Every rule, its severity, status and false-positive safeguards |
556
+ | [Limitations](docs/limitations.md) | What is out of scope |
557
+ | [Validation results](docs/validation-results.md) | Measured tests, coverage, timing, parity |
558
+ | [SKILL.md](agensi/powerbi-pbip-forensics/SKILL.md) | Operational instructions for agents |
559
+ | [Publishing on Agensi](docs/PUBLISH_AGENSI.md) | Submission and post-publication test |
560
+ | [Python packaging & publishing](docs/python-packaging.md) | Wheel/sdist build, CI, and the TestPyPI/PyPI procedure (not yet executed) |
561
+ | [Changelog](CHANGELOG.md) | Release history |
562
+
563
+ ## 📄 License
564
+
565
+ Copyright © 2026 **Vinicius de Souza Santos**. All rights reserved. This is proprietary software, and access to
566
+ this repository does not grant any right to use, copy or redistribute it. See [LICENSE](LICENSE).
567
+
568
+ Power BI, PBIP, PBIR, TMDL and DAX are Microsoft technologies. This project is not affiliated with or endorsed by
569
+ Microsoft.
570
+
571
+ <div align="center">
572
+ <sub>Made by <a href="https://github.com/ViniciusKanh">Vinicius de Souza Santos</a> · v1.0.0</sub>
573
+ </div>