@luquimbo/bi-superpowers 4.1.1 → 4.1.3

package/src/content/skills/report-design/references/native-visuals.md

@@ -311,7 +311,7 @@ Si PBI Desktop introduce un visualType nuevo (o encontrás uno nativo que falta
 
 ## Features de `visual.json` que `create-visual.js` NO soporta todavía
 
-Descubiertos al regenerar la smoke-test "Galería de Visuales" end-to-end con el script (backlog item 2, cycle v4.1). No bloquean el authoring — la shape que emite el script pasa `pbi report validate` y `validate-pbir.js` — pero sí dejan regresiones visuales si el `visual.json` hand-written aprovechaba alguno de estos features:
+Descubiertos al regenerar la smoke-test "Galería de Visuales" end-to-end con el script. No bloquean el authoring — la shape que emite el script pasa `pbi report validate` y `validate-pbir.js` — pero sí dejan regresiones visuales si el `visual.json` hand-written aprovechaba alguno de estos features:
 
 1. **`query.sortDefinition`** — sort explícito por medida/columna con dirección. `create-visual.js` no lo emite, así que un visual "ranking" tipo barChart ordenado descendente por una medida pierde el orden en la regeneración. **Workaround**: ordenar en Desktop manualmente después del `.pbip` abrir, o hand-extender el `visual.json` con `sortDefinition` post-creación. **Fix futuro**: `--sort-by "Role:Field" --sort-dir descending` en `create-visual.js`.
 
@@ -319,7 +319,7 @@ Descubiertos al regenerar la smoke-test "Galería de Visuales" end-to-end con el
 
 3. **`queryState.<Role>.projections[].active`** — las columnas siempre salen con `active: true`, las medidas nunca. Si un visual hand-written tenía `active: true` en una medida (para indicar que la medida es la "default Y") o `active: false` en una columna (hidden projection), el script normaliza. Rara vez significativo para el render pero cambia el shape JSON.
 
-4. **Formato condicional**: colores signados (positivo verde / negativo rojo), gradientes en matriz, data bars en tabla. Ninguno de estos expresa shape via `create-visual.js`. Quedó deferido a v4.1+ en `SKILL.md` PHASE 4.3.
+4. **Formato condicional**: colores signados (positivo verde / negativo rojo), gradientes en matriz, data bars en tabla. Ninguno de estos expresa shape via `create-visual.js`; tratarlos como diseño previsto hasta que exista una implementación PBIR testeada.
 
 Cualquier cambio en el script que cubra estos gaps debe: (a) agregar el flag a `parseArgs`, (b) cubrirlo con tests en `create-visual.test.js`, (c) documentarlo en este archivo, (d) regenerar la Galería para que ejercite el feature.
 

package/src/content/skills/report-design/references/slicer.md

@@ -86,4 +86,4 @@ cat > "<reportPath>/definition/pages/<pageName>/visuals/<visualName>/visual.json
 EOF
 ```
 
-A reusable helper script (`scripts/write-slicer.sh`) is a v4.1 candidate; v4.0.0 ships with the heredoc pattern.
+Prefer `scripts/create-visual.js --type slicer` for new slicers. Keep the heredoc pattern above only as a fallback when the helper script is unavailable.

package/src/content/skills/report-design/references/textbox.md

@@ -98,4 +98,4 @@ cat > "<reportPath>/definition/pages/<pageName>/visuals/<visualName>/visual.json
 EOF
 ```
 
-A reusable helper script (`scripts/write-textbox.sh`) is a v4.1 candidate; v4.0.0 ships with the heredoc pattern.
+Prefer `scripts/create-visual.js --type textbox` for new textboxes. Keep the heredoc pattern above only as a fallback when the helper script is unavailable.

package/src/content/skills/report-design/scripts/create-visual.js

@@ -679,6 +679,66 @@ function nextInt(existing, key) {
   return max + 1;
 }
 
+function validateVisualName(name) {
+  if (typeof name !== 'string' || name.trim() === '') {
+    fail('--name must be a non-empty visual folder name');
+  }
+
+  if (name !== name.trim()) {
+    fail(`--name must not have leading or trailing whitespace (got: ${JSON.stringify(name)})`);
+  }
+
+  if (
+    name === '.' ||
+    name === '..' ||
+    /[\\/]/.test(name) ||
+    path.basename(name) !== name ||
+    path.win32.basename(name) !== name ||
+    path.posix.basename(name) !== name
+  ) {
+    fail(`--name must be a single visual folder name, not a path (got: ${JSON.stringify(name)})`);
+  }
+
+  if (/[\u0000-\u001f<>:"|?*]/.test(name)) {
+    fail(`--name contains characters that are not valid in a Windows folder name (got: ${JSON.stringify(name)})`);
+  }
+}
+
+function validateNumericOptions(args) {
+  const numericOptions = [
+    ['x', '--x'],
+    ['y', '--y'],
+    ['z', '-z'],
+    ['width', '--width'],
+    ['height', '--height'],
+    ['tabOrder', '--tab-order'],
+  ];
+
+  for (const [key, flag] of numericOptions) {
+    if (args[key] != null && !Number.isFinite(args[key])) {
+      fail(`${flag} must be a finite number`);
+    }
+  }
+
+  for (const [key, flag] of [
+    ['width', '--width'],
+    ['height', '--height'],
+  ]) {
+    if (args[key] != null && args[key] <= 0) {
+      fail(`${flag} must be greater than 0`);
+    }
+  }
+}
+
+function assertPathInside(childPath, parentPath, label) {
+  const parent = path.resolve(parentPath);
+  const child = path.resolve(childPath);
+  const relative = path.relative(parent, child);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    fail(`${label} resolved outside the expected directory: ${child}`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // main()
 // ---------------------------------------------------------------------------
@@ -698,6 +758,7 @@ function main() {
   if (!args.reportPath) fail('--report-path is required');
   if (!args.page) fail('--page is required');
   if (!args.type) fail('--type is required (use --list-types to see options)');
+  validateNumericOptions(args);
 
   // ---- type validation with friendly errors for known non-native aliases
   if (KNOWN_NON_NATIVE_TYPES[args.type]) {
@@ -727,8 +788,11 @@ function main() {
     } while (existing.some((v) => v.name === candidate));
     name = candidate;
   }
+  validateVisualName(name);
 
-  const visualDir = path.join(pageDir, 'visuals', name);
+  const visualsDir = path.join(pageDir, 'visuals');
+  const visualDir = path.join(visualsDir, name);
+  assertPathInside(visualDir, visualsDir, '--name');
   const visualJsonPath = path.join(visualDir, 'visual.json');
   if (fs.existsSync(visualJsonPath)) {
     fail(

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

@@ -130,6 +130,33 @@ function boundRoles(visualData) {
   return bound;
 }
 
+function validatePosition(position) {
+  const errors = [];
+  const requiredFields = ['x', 'y', 'z', 'height', 'width', 'tabOrder'];
+
+  if (!position || typeof position !== 'object') {
+    return requiredFields.map((field) => ({
+      severity: 'error',
+      rule: 'position-number',
+      field,
+      message: `position.${field} must be a finite number`,
+    }));
+  }
+
+  for (const field of requiredFields) {
+    if (!Number.isFinite(position[field])) {
+      errors.push({
+        severity: 'error',
+        rule: 'position-number',
+        field,
+        message: `position.${field} must be a finite number`,
+      });
+    }
+  }
+
+  return errors;
+}
+
 function validateVisual(visual) {
   const errors = [];
   const { data, path: filePath } = visual;
@@ -148,6 +175,8 @@ function validateVisual(visual) {
     errors.push({ severity: 'error', rule: 'name', message: 'missing "name"' });
   }
 
+  errors.push(...validatePosition(data.position));
+
   const vt = data.visual && data.visual.visualType;
   if (!vt) {
     errors.push({ severity: 'error', rule: 'visual-type', message: 'missing visualType' });