coop-dax-review

Offline, advisory DAX/model standards linter for our Power BI semantic models. It parses TMDL (and legacy .bim) models, builds a model catalog, checks measures and model structure against docs/standards.md (our DAX standards + Microsoft/Tabular best practices), and surfaces anything that doesn't match. It never edits or blocks — it only reports. Human reports (a sectioned, colorized terminal report, Markdown, or a self-contained branded HTML file) and machine JSON for the company analytics agent.

Sibling tool to coop-sql-review — same architecture and contracts.

Part of the Cooptimize coop suite — if your team uses coop-agent, coop install installs this plus the sibling tools (coop-sql-review, coop-data-doc); coop update keeps them current.

Install

pipx install coop-dax-review        # from PyPI

Use pipx, not system pip, so the tool stays isolated from other CLIs (ms-fabric-cli, azure-cli) it might otherwise fight over shared pins. For local development (Python 3.10–3.13; avoid 3.14 — its venvs mis-handle editable installs):

python3 -m venv .venv && .venv/bin/python -m pip install -e ".[dev]"

Usage

coop-dax-review check [MODEL_PATHS...] [--format text|json|markdown|html|sarif] [-o FILE]
                      [--html FILE] [--md FILE] [--sarif FILE] [--open/--no-open]
                      [--color/--no-color] [--log-file FILE] [--baseline FILE]
                      [--write-baseline FILE] [--save-ignores]
                      [--min-severity error|warning|info] [--strict]
coop-dax-review rules                 # list every rule (id, severity, tier, agent?)
coop-dax-review explain <RULE-ID>     # a rule's rationale + standards excerpt (--format json)
coop-dax-review upgrade [--check]     # show the command to update (never self-applies; alias: update)
coop-dax-review --version

• MODEL_PATHS point at a PBIP/TMDL model folder (*.SemanticModel/definition/...), any folder of .tmdl files, or a legacy .bim file. Directories are searched recursively; defaults to ..
• Run it with no paths in a terminal and it offers a checkbox picker of the subfolders to check (all selected by default — press ENTER to scan everything).
• Advisory: exit code is always 0. --strict is the opt-in CI gate — exit 2 when any finding remains at/above --min-severity, or when no models were found/checked at all (so a typo'd path can't pass silently). A zero-model run still renders the full report (with models_checked: 0 and a scan_empty diagnostic per searched path).
• --standards <path> overrides the bundled standards (e.g. point it at a canonical company standards file). Its sha256 travels in the JSON so the agent knows which standards a report used.
• A config file can disable rules, override severities, and tune thresholds — all with no rebuild. It is found, first hit wins, via: --config; the COOP_DAX_REVIEW_CONFIG environment variable (point a whole CI pipeline at one config); a coop-dax-review.yml (preferred) or rules.yml (the deprecated shared name — every coop-*-review tool reads it, so two tools in one monorepo would fight over it) in the current directory or any parent up to the repo root; else beside the standards file. A broken config (bad YAML, wrong shape, a non-UTF-8 save) is a friendly one-line error naming the file, and a --config or env-var path that doesn't exist is an error too (a typo can't silently drop your overrides). For example, raise what counts as a "non-trivial" measure:

  rules:
    DAX-VAR-RETURN:
      params: { min_functions: 5 }   # also: DAX-COMPLEX-NO-HEADER.min_vars,
                                      # DAX-DISPLAY-FOLDERS.min_measures, DAX-SIMPLE-FUNCTIONS.min_calculates
  

coop-dax-review check ./MyModel.SemanticModel
coop-dax-review check . --format json --strict --min-severity warning
coop-dax-review check . --format html              # writes a report file and opens it in your browser
coop-dax-review check . --format markdown -o report.md

The default --format text is a sectioned terminal report: a banner, one section per model with ERROR/WARN/INFO severity badges, and a SUMMARY panel — including a Findings by rule count table (count desc) so you can see at a glance which rules dominate and tune or disable them in rules.yml; the Markdown and HTML reports carry the same table. It's colorized automatically when you're at a terminal and falls back to plain text when piped or redirected (override with --color/--no-color; NO_COLOR is respected). On a large legacy estate (50+ findings, no baseline in play) a one-line stderr hint points at --write-baseline ratcheting.

--format html produces a self-contained, branded HTML report (inline CSS + embedded logo, no network). It is always written to a file — coop-dax-review-report.html by default, or wherever -o points — and the path is printed and opened in your browser (pass --no-open to skip the open, e.g. in CI). upgrade/update print the exact command to run yourself (pipx upgrade coop-dax-review, etc.) rather than self-applying, since a package manager can't replace the tool while it is running; upgrade --check reports whether an update is available and stops there.

Want a report file and the usual console/JSON output in one run? --html FILE, --md FILE, and --sarif FILE are extra sinks: they write a self-contained HTML, Markdown, and/or SARIF report to the paths you name in addition to whatever --format prints, and never open a browser. Handy for CI — e.g. keep the JSON contract on stdout while dropping a human-readable HTML artifact alongside it:

coop-dax-review check . --format json --html report.html --md report.md

Annotate a pull request in CI (GitHub / Azure DevOps). --format sarif emits a standard SARIF 2.1.0 report that GitHub code scanning (and Azure DevOps) turn into inline PR annotations on the exact TMDL/.bim lines. Findings map to their rule/severity, agent-review items surface as non-blocking notes, and genuinely malformed DAX (a syntax_error diagnostic) annotates as an error. A ready-to-paste GitHub Actions step:

    - name: DAX standards review
      run: coop-dax-review check models/ --format sarif -o coop-dax-review.sarif
    - name: Upload SARIF
      uses: github/codeql-action/upload-sarif@v3
      with:
        sarif_file: coop-dax-review.sarif

The tool stays advisory (exit 0) unless you add --strict, so the SARIF annotations appear without failing the build — add --strict if you want the build to go red on remaining findings.

What it checks

Run coop-dax-review rules for the live list. Deterministic rules (reported as findings):

Agent-judgment rules — the tool detects the construct but emits to the JSON agent_review list (never an auto-finding), because the call needs intent the linter can't infer:

See RULES.md for the full taxonomy. docs/standards.md §14–§20 are adopted Microsoft/Tabular best practices (DIVIDE, format strings, key column types, hidden FKs, key summarizeBy, display folders, explicit measures), and §22–§25 add EARLIER→VAR, dead inactive relationships, IFERROR-wrapping, and measure descriptions; docs/standards-proposed-additions.md is the original candidate list.

DAX syntax errors

Beyond the standards rules, check runs a cheap structural validation over every measure body and every calculated-column expression and reports genuinely malformed DAX — the kind that would import broken into Power BI — as error-severity syntax_error diagnostics. It catches: unbalanced parentheses, unbalanced brackets, an unterminated string literal ("..." with no closing quote), an unterminated block comment (/* ... with no */), and an empty measure body. Parens/brackets/quotes that live inside an identifier ([Net (USD)]), a string, or a comment are never counted, so compliant DAX is never flagged. This is drift detection, not a grammar: the standards rules still run on whatever parsed. Because a syntax_error is error-severity, it flips the JSON verdict to not-clean and fails --strict (exit 2) — so a broken measure never passes CI as clean.

Tune it two ways:

• rules.yml knob — syntax_errors: error (default) | warning (demote but keep it visible in the JSON) | off (drop entirely):

  syntax_errors: warning
  

• Inline — silence a single occurrence with a syntax (or bare *) ignore on the finding's line or the line above it. A rule-scoped ignore does not cover a syntax error:

  // coop-dax-review:ignore syntax
  

Suppressing findings (adopting on an existing model)

Three deterministic, never-blocking ways to silence findings you've already triaged. All three apply to regular findings and to agent_review items (the judgment-call prompts in the JSON), so a triaged item stays silenced everywhere:

• Inline — drop a comment on a finding's line (or the line directly above it):

  // coop-dax-review:ignore DAX-VAR-RETURN reason: legacy measure, rewrite scheduled
  

  List several rule ids (ignore DAX-A, DAX-B), or use a bare ignore / * to silence every rule on that line. The reason: text is for humans; it's ignored by the parser.

• rules.yml ignore list — a human-readable, fingerprint-matched suppression list that lives in the one config file (like a baseline, but readable and hand-editable). Add an ignore: block:

  ignore:
    - fingerprint: 4ad6aeb79867
      rule: DAX-BIDI-RELATIONSHIP        # rule / where / note are for humans; matching is by fingerprint
      where: Sales/FactSales[ProductId] -> DimCustomer[CustomerId]
      note: intentional many-to-many, reviewed 2026-07
  

  You don't have to hand-copy fingerprints: run check --save-ignores and, at an interactive terminal, you get a checkbox of this run's findings grouped by rule × model (a header per group, an "ignore all N" row for multi-finding groups, individual findings nested — all unchecked, opt in to the ones you want gone); the picks are appended to the config file this run read (so a team config beside the standards file, or one found in a parent directory, is updated in place rather than shadowed by a new ./rules.yml). A coop-dax-review.yml or rules.yml in your current directory (or any parent up to the repo root) is auto-discovered with no --config flag, so the loop is just "run, --save-ignores, re-run". An ignore entry that no longer matches any finding (you fixed it) is reported as a diagnostic so the list self-cleans.

• Baseline (ratchet) — record today's findings and surface only new ones going forward:

  coop-dax-review check . --write-baseline dax-baseline.json   # once, to capture the status quo
  coop-dax-review check . --baseline dax-baseline.json         # thereafter: only new findings appear
  

  Each finding has a stable fingerprint (in the JSON) — independent of line numbers and of file paths, so a baseline written on one machine or from one directory still matches from another — and the baseline is a sorted list of those. A baseline entry that no longer matches any finding (you fixed it) is reported as a diagnostic so the file self-cleans (--write-baseline to prune).

  One-time migration (schema_version 3): the fingerprint identity changed in this release (a stable core for the volatile-message rules + an occurrence ordinal — coordinated with coop-sql-review's schema 4, one family rule). Delete and regenerate any baseline files and rules.yml ignore: lists written by earlier versions once: coop-dax-review check <models> --write-baseline baseline.json and re-run coop-dax-review check <models> --save-ignores. Until then, old entries are reported loudly as stale diagnostics on every run — nothing goes silently missing.

Agent JSON contract

{
  "tool": "coop-dax-review", "schema_version": 3, "version": "x.y.z",
  "standards": {"path": "...", "sha256": "..."},
  "models_checked": 2,
  "verdict": {"clean": false, "highest_severity": "warning"},
  "findings": [{"rule_id":"...","severity":"warning","model":"Sales","file":"...","line":12,
                "object":"[Sales: Revenue YTD]","message":"...","standard_ref":"§3","fingerprint":"4ad6aeb79867"}],
  "summary": {"error":0,"warning":2,"info":4},
  "agent_review": [{"rule_id":"...","model":"Sales","file":"...","line":40,"object":"[...]","note":"...","standard_ref":"§5","fingerprint":"..."}],
  "diagnostics": [{"severity":"warning","category":"parse_failed","file":"...","message":"..."}]
}

schema_version lets a consumer pin the shape; verdict/models_checked give a quick machine verdict + coverage signal; each finding's fingerprint is a stable id for tracking across runs.

Project docs

• SPEC.md — architecture, CLI, agent contract, milestones.
• RULES.md — every standard mapped to a concrete check (deterministic vs agent-judgment).
• docs/standards.md — the canonical DAX standards the linter checks against (bundled as package data).
• AGENTS.md — orientation for coding agents (and humans) working in this repo; CLAUDE.md imports it.