@luquimbo/bi-superpowers 3.1.1 → 4.1.0

package/src/content/skills/report-design/scripts/ensure-pbi-cli.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# ensure-pbi-cli.sh — idempotent installer for pbi-cli-tool + pywin32
+# Run from any directory. Requires Python 3.10+ and pip on PATH.
+# Exit code 0 = ready, 1 = install failed
+
+set -e
+
+check_python() {
+  python --version 2>/dev/null | grep -qE "Python 3\.(1[0-9]|[2-9][0-9])" && return 0
+  python3 --version 2>/dev/null | grep -qE "Python 3\.(1[0-9]|[2-9][0-9])" && return 0
+  echo "❌ Python 3.10+ required. Install from Microsoft Store or python.org."
+  exit 1
+}
+
+check_pipx() {
+  pipx --version 2>/dev/null && return 0
+  python -m pipx --version 2>/dev/null && return 0
+  echo "📦 Installing pipx..."
+  pip install --user pipx 2>/dev/null || python -m pip install --user pipx
+  python -m pipx ensurepath
+  echo "⚠ Close and reopen your terminal, then re-run this script."
+  exit 1
+}
+
+check_pbi() {
+  pbi --version 2>/dev/null && return 0
+  echo "📦 Installing pbi-cli-tool..."
+  python -m pipx install pbi-cli-tool
+}
+
+inject_pywin32() {
+  python -m pipx inject pbi-cli-tool pywin32 2>/dev/null || true
+}
+
+echo "Checking pbi-cli-tool environment..."
+check_python
+check_pipx
+check_pbi
+inject_pywin32
+echo "✅ pbi-cli-tool is ready."
+pbi --version

package/src/content/skills/report-design/scripts/validate-pbir.js

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+/**
+ * validate-pbir.js — allowlist-driven PBIR validator.
+ *
+ * Complements `pbi report validate` (which does schema sanity) by enforcing
+ * the native-visuals allowlist maintained in create-visual.js. Catches:
+ *
+ *   - visualType that's not a native PBIR type (e.g. `stackedBarChart`,
+ *     typos) — Desktop renders these as "objeto visual personalizado" but
+ *     the CLI validate passes them. This is the exact bug F1 that motivated
+ *     the migration away from the CLI.
+ *
+ *   - bindings on roles that the type doesn't declare (e.g. `--bind size`
+ *     on a funnelChart) — CLI validate doesn't catch these either.
+ *
+ *   - missing required roles (e.g. a barChart with no Category).
+ *
+ *   - visualContainer schema drift (wrong $schema URL or missing `name`).
+ *
+ * Usage:
+ *   node validate-pbir.js <reportPath>
+ *   node validate-pbir.js --json <reportPath>    # machine-readable output
+ *
+ * Exit codes:
+ *   0  valid
+ *   1  validation errors found
+ *   2  I/O error (bad path, corrupt JSON)
+ *
+ * NOT a replacement for `pbi report validate` — run both. This validator
+ * trusts that the .Report folder is structurally correct (has definition/,
+ * pages/, etc.) and focuses on visual-level correctness that the CLI misses.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { NATIVE_VISUAL_TYPES, KNOWN_NON_NATIVE_TYPES } = require('./create-visual.js');
+
+const EXPECTED_VISUAL_SCHEMA =
+  'https://developer.microsoft.com/json-schemas/fabric/item/report/definition/visualContainer/2.7.0/schema.json';
+
+function fail(msg, code = 2) {
+  process.stderr.write(`validate-pbir: ${msg}\n`);
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const out = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--json') out.json = true;
+    else if (a === '-h' || a === '--help') out.help = true;
+    else if (a.startsWith('-')) fail(`unknown flag: ${a}`, 2);
+    else positional.push(a);
+  }
+  out.reportPath = positional[0];
+  return out;
+}
+
+function printHelp() {
+  process.stdout.write(
+    [
+      'Usage: validate-pbir.js [--json] <reportPath>',
+      '',
+      'Arguments:',
+      '  reportPath   Path to a .Report folder',
+      '',
+      'Options:',
+      '  --json       Emit JSON instead of human-readable output',
+      '  -h, --help   Show this help',
+      '',
+      'Exit codes:',
+      '  0  valid',
+      '  1  validation errors found',
+      '  2  I/O error',
+      '',
+    ].join('\n')
+  );
+}
+
+function listPages(reportPath) {
+  const pagesDir = path.join(reportPath, 'definition', 'pages');
+  if (!fs.existsSync(pagesDir)) {
+    fail(`pages directory not found: ${pagesDir}`, 2);
+  }
+  const out = [];
+  for (const entry of fs.readdirSync(pagesDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const pageJsonPath = path.join(pagesDir, entry.name, 'page.json');
+    if (!fs.existsSync(pageJsonPath)) continue;
+    out.push({ name: entry.name, dir: path.join(pagesDir, entry.name) });
+  }
+  return out;
+}
+
+function listVisuals(pageDir) {
+  const visualsDir = path.join(pageDir, 'visuals');
+  if (!fs.existsSync(visualsDir)) return [];
+  const out = [];
+  for (const entry of fs.readdirSync(visualsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const visualJsonPath = path.join(visualsDir, entry.name, 'visual.json');
+    if (!fs.existsSync(visualJsonPath)) continue;
+    out.push({ name: entry.name, path: visualJsonPath });
+  }
+  return out;
+}
+
+function readJsonSafe(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    return { data: JSON.parse(raw), err: null };
+  } catch (err) {
+    return { data: null, err };
+  }
+}
+
+// Extracts the set of roles that have at least one projection bound.
+function boundRoles(visualData) {
+  const qs = visualData && visualData.visual && visualData.visual.query && visualData.visual.query.queryState;
+  if (!qs || typeof qs !== 'object') return new Set();
+  const bound = new Set();
+  for (const [role, spec] of Object.entries(qs)) {
+    const projections = spec && spec.projections;
+    if (Array.isArray(projections) && projections.length > 0) bound.add(role);
+  }
+  return bound;
+}
+
+function validateVisual(visual) {
+  const errors = [];
+  const { data, path: filePath } = visual;
+
+  // Schema URL check.
+  if (data.$schema !== EXPECTED_VISUAL_SCHEMA) {
+    errors.push({
+      severity: 'warn',
+      rule: 'schema-url',
+      message: `unexpected $schema (got ${data.$schema || 'none'})`,
+    });
+  }
+
+  // `name` must exist and match the folder.
+  if (typeof data.name !== 'string' || !data.name) {
+    errors.push({ severity: 'error', rule: 'name', message: 'missing "name"' });
+  }
+
+  const vt = data.visual && data.visual.visualType;
+  if (!vt) {
+    errors.push({ severity: 'error', rule: 'visual-type', message: 'missing visualType' });
+    return errors;
+  }
+
+  // Allowlist: known non-native (like stackedBarChart).
+  if (KNOWN_NON_NATIVE_TYPES[vt]) {
+    errors.push({
+      severity: 'error',
+      rule: 'non-native-type',
+      visualType: vt,
+      message: KNOWN_NON_NATIVE_TYPES[vt],
+    });
+    return errors;
+  }
+
+  const def = NATIVE_VISUAL_TYPES[vt];
+  if (!def) {
+    errors.push({
+      severity: 'error',
+      rule: 'unknown-type',
+      visualType: vt,
+      message: `visualType "${vt}" is not in the native allowlist. Run create-visual.js --list-types for the canonical list.`,
+    });
+    return errors;
+  }
+
+  // Check required roles are bound (skip for textbox — no roles).
+  if (vt !== 'textbox') {
+    const bound = boundRoles(data);
+    for (const [role, spec] of Object.entries(def.roles)) {
+      if (spec.required && !bound.has(role)) {
+        errors.push({
+          severity: 'error',
+          rule: 'missing-required-role',
+          visualType: vt,
+          role,
+          message: `required role "${role}" has no projections (visualType: ${vt})`,
+        });
+      }
+    }
+
+    // Check that every bound role is valid for this type.
+    for (const role of bound) {
+      if (!(role in def.roles)) {
+        errors.push({
+          severity: 'error',
+          rule: 'invalid-role',
+          visualType: vt,
+          role,
+          message: `role "${role}" is not valid for visualType ${vt}. Valid: ${Object.keys(def.roles).join(', ') || '(none)'}`,
+        });
+      }
+    }
+  }
+
+  return errors;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printHelp();
+    return;
+  }
+  if (!args.reportPath) fail('reportPath is required. Run --help for usage.', 2);
+
+  const reportPath = path.resolve(args.reportPath);
+  if (!fs.existsSync(reportPath)) fail(`not found: ${reportPath}`, 2);
+
+  const pages = listPages(reportPath);
+  const results = {
+    reportPath,
+    pagesChecked: pages.length,
+    visualsChecked: 0,
+    errors: [],
+  };
+
+  for (const page of pages) {
+    const visuals = listVisuals(page.dir);
+    // Track visual.name per page so we can flag duplicates. PBI Desktop
+    // does not reject a duplicate-name pair on load, but downstream tooling
+    // that references visuals by name (filters, bookmarks, selections) gets
+    // ambiguous — validate-pbir treats it as a hard error.
+    const namesSeenOnPage = new Map();
+    for (const v of visuals) {
+      results.visualsChecked += 1;
+      const { data, err } = readJsonSafe(v.path);
+      if (err) {
+        results.errors.push({
+          page: page.name,
+          visual: v.name,
+          severity: 'error',
+          rule: 'bad-json',
+          message: `could not parse visual.json: ${err.message}`,
+        });
+        continue;
+      }
+
+      // Duplicate-name check (page-scoped).
+      const declaredName = data && typeof data.name === 'string' ? data.name : null;
+      if (declaredName) {
+        if (namesSeenOnPage.has(declaredName)) {
+          results.errors.push({
+            page: page.name,
+            visual: v.name,
+            severity: 'error',
+            rule: 'duplicate-name',
+            message: `visual name "${declaredName}" is also used by "${namesSeenOnPage.get(declaredName)}" on this page`,
+          });
+        } else {
+          namesSeenOnPage.set(declaredName, v.name);
+        }
+      }
+
+      const visualErrors = validateVisual({ data, path: v.path });
+      for (const e of visualErrors) {
+        results.errors.push({
+          page: page.name,
+          visual: v.name,
+          ...e,
+        });
+      }
+    }
+  }
+
+  const errorCount = results.errors.filter((e) => e.severity === 'error').length;
+  const warnCount = results.errors.filter((e) => e.severity === 'warn').length;
+  const valid = errorCount === 0;
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify({ ...results, valid, errorCount, warnCount }, null, 2) + '\n');
+  } else {
+    const W = 77; // inner width between the | borders
+    const padRow = (label, value) => {
+      const text = `${label}: ${value}`;
+      return `| ${text}${' '.repeat(Math.max(0, W - text.length - 1))}|`;
+    };
+    const border = `+${'-'.repeat(W)}+`;
+    process.stdout.write(border + '\n');
+    process.stdout.write(padRow('valid', valid ? 'True' : 'False') + '\n');
+    process.stdout.write(padRow('pages_checked', String(results.pagesChecked)) + '\n');
+    process.stdout.write(padRow('visuals_checked', String(results.visualsChecked)) + '\n');
+    process.stdout.write(padRow('errors', String(errorCount)) + '\n');
+    process.stdout.write(padRow('warnings', String(warnCount)) + '\n');
+    process.stdout.write(border + '\n');
+    if (results.errors.length) {
+      process.stdout.write('\nIssues:\n');
+      for (const e of results.errors) {
+        const icon = e.severity === 'error' ? '✗' : '⚠';
+        const loc = `${e.page}/${e.visual}`;
+        process.stdout.write(`  ${icon} [${e.rule}] ${loc}: ${e.message}\n`);
+      }
+      process.stdout.write('\n');
+    }
+  }
+
+  process.exit(valid ? 0 : 1);
+}
+
+module.exports = {
+  validateVisual,
+  boundRoles,
+  listPages,
+  listVisuals,
+  parseArgs,
+};
+
+if (require.main === module) {
+  main();
+}