@principal-ai/principal-view-cli 0.3.8 → 0.4.0

package/dist/commands/narrative/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/commands/narrative/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAepC,wBAAgB,qBAAqB,IAAI,OAAO,CA0K/C"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/commands/narrative/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBpC,wBAAgB,qBAAqB,IAAI,OAAO,CA6N/C"}

package/dist/commands/narrative/validate.js

@@ -2,14 +2,15 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { resolve, dirname } from 'node:path';
 import { readFileSync } from 'node:fs';
-import { NarrativeValidator } from '@principal-ai/principal-view-core';
-import { loadNarrative, resolvePath } from './utils.js';
+import { NarrativeValidator, computeAggregates } from '@principal-ai/principal-view-core';
+import { loadNarrative, resolvePath, loadExecution, executionToEvents } from './utils.js';
 export function createValidateCommand() {
     const command = new Command('validate');
     command
         .description('Validate narrative template syntax, schema, and references')
         .argument('<file>', 'Path to .narrative.json file')
         .option('--canvas <path>', 'Override canvas file path for validation')
+        .option('--execution <path>', 'Execution file (.otel.json) for validating attribute references')
         .option('--json', 'Output violations as JSON')
         .option('-q, --quiet', 'Only show errors, suppress warnings')
         .option('-d, --dir <path>', 'Project directory (default: cwd)')
@@ -40,6 +41,33 @@ export function createValidateCommand() {
                     canvas = undefined;
                 }
             }
+            // Load execution data if provided
+            let executionData;
+            if (options.execution) {
+                try {
+                    const executionPath = resolvePath(options.execution, baseDir);
+                    const execution = await loadExecution(executionPath);
+                    const events = executionToEvents(execution);
+                    const aggregates = computeAggregates(events);
+                    // Build event-specific attribute map
+                    const eventAttributes = new Map();
+                    for (const event of events) {
+                        if (!eventAttributes.has(event.name)) {
+                            eventAttributes.set(event.name, {});
+                        }
+                        const attrs = eventAttributes.get(event.name);
+                        // Merge attributes from this event occurrence
+                        if (event.attributes) {
+                            Object.assign(attrs, event.attributes);
+                        }
+                    }
+                    executionData = { aggregates, eventAttributes };
+                }
+                catch (error) {
+                    console.error(chalk.yellow('Warning:'), `Failed to load execution file: ${error.message}`);
+                    console.error(chalk.gray('  Attribute validation will be skipped'));
+                }
+            }
             // Create validator
             const validator = new NarrativeValidator();
             // Validate
@@ -49,6 +77,7 @@ export function createValidateCommand() {
                 canvasPath,
                 canvas,
                 basePath: baseDir,
+                executionData,
             };
             const result = await validator.validate(context);
             // Filter violations if quiet mode
@@ -77,6 +106,7 @@ export function createValidateCommand() {
                         warnings: warnings.length,
                         scenarioCount: narrative.scenarios.length,
                         hasDefault: narrative.scenarios.some((s) => s.condition.default),
+                        attributeValidation: executionData ? 'enabled' : 'skipped',
                     },
                 };
                 console.log(JSON.stringify(output, null, 2));
@@ -133,6 +163,12 @@ export function createValidateCommand() {
                 if (canvasPath) {
                     console.log(chalk.gray(`  • Canvas: ${narrative.canvas || canvasPath}`));
                 }
+                if (executionData) {
+                    console.log(chalk.gray('  • Attribute validation:'), chalk.green('enabled'));
+                }
+                else {
+                    console.log(chalk.gray('  • Attribute validation:'), chalk.gray('skipped (use --execution to enable)'));
+                }
                 console.log();
             }
             // Exit with error code if validation failed

package/dist/index.cjs

@@ -8971,9 +8971,9 @@ var require_out4 = __commonJS({
   }
 });
 
-// node_modules/globby/node_modules/ignore/index.js
+// node_modules/ignore/index.js
 var require_ignore = __commonJS({
-  "node_modules/globby/node_modules/ignore/index.js"(exports2, module2) {
+  "node_modules/ignore/index.js"(exports2, module2) {
     function makeArray(subject) {
       return Array.isArray(subject) ? subject : [subject];
     }
@@ -241233,6 +241233,21 @@ function computeAggregates(events) {
 
 // node_modules/@principal-ai/principal-view-core/dist/narrative/template-parser.js
 var import_handlebars = __toESM(require_lib());
+import_handlebars.default.registerHelper("eq", (a, b) => a === b);
+import_handlebars.default.registerHelper("ne", (a, b) => a !== b);
+import_handlebars.default.registerHelper("lt", (a, b) => a < b);
+import_handlebars.default.registerHelper("gt", (a, b) => a > b);
+import_handlebars.default.registerHelper("lte", (a, b) => a <= b);
+import_handlebars.default.registerHelper("gte", (a, b) => a >= b);
+import_handlebars.default.registerHelper("and", (...args) => {
+  const values = args.slice(0, -1);
+  return values.every(Boolean);
+});
+import_handlebars.default.registerHelper("or", (...args) => {
+  const values = args.slice(0, -1);
+  return values.some(Boolean);
+});
+import_handlebars.default.registerHelper("not", (a) => !a);
 function parseTemplate(template, context) {
   try {
     const handlebarTemplate = import_handlebars.default.compile(template, { noEscape: true });
@@ -242112,12 +242127,137 @@ var NarrativeValidator = class {
     return violations;
   }
   /**
-   * Check attribute references (warning level)
+   * Check attribute references against execution data
+   *
+   * Validates that:
+   * - Attributes referenced in templates exist in execution data
+   * - Object attributes are accessed via properties (not used directly)
+   * - Attribute names are correct (catches typos)
    */
-  checkAttributeReferences(_context) {
+  checkAttributeReferences(context) {
     const violations = [];
+    const { narrative, narrativePath, executionData } = context;
+    if (!executionData) {
+      return violations;
+    }
+    const { aggregates, eventAttributes } = executionData;
+    for (const scenario of narrative.scenarios) {
+      const scenarioPath = `scenarios[${scenario.id}]`;
+      if (scenario.template.introduction) {
+        const attrs = this.extractAttributeReferences(scenario.template.introduction);
+        violations.push(...this.validateAttributes(
+          attrs,
+          aggregates,
+          null,
+          // introduction doesn't have specific event context
+          narrativePath,
+          `${scenarioPath}.template.introduction`
+        ));
+      }
+      if (scenario.template.events) {
+        for (const [eventName, eventTemplate] of Object.entries(scenario.template.events)) {
+          const attrs = this.extractAttributeReferences(eventTemplate);
+          const eventAttrs = eventAttributes.get(eventName);
+          violations.push(...this.validateAttributes(attrs, aggregates, eventAttrs || null, narrativePath, `${scenarioPath}.template.events.${eventName}`, eventName));
+        }
+      }
+      if (scenario.template.summary) {
+        const attrs = this.extractAttributeReferences(scenario.template.summary);
+        violations.push(...this.validateAttributes(
+          attrs,
+          aggregates,
+          null,
+          // summary uses global aggregates
+          narrativePath,
+          `${scenarioPath}.template.summary`
+        ));
+      }
+    }
     return violations;
   }
+  /**
+   * Validate a list of attribute references against available data
+   *
+   * @param attributes - Attribute paths to validate
+   * @param aggregates - Global aggregate attributes
+   * @param eventAttributes - Event-specific attributes (if validating event template)
+   * @param file - File path for violation reporting
+   * @param path - JSON path for violation reporting
+   * @param eventName - Event name (if validating event template)
+   * @returns Array of violations found
+   */
+  validateAttributes(attributes, aggregates, eventAttributes, file, path4, eventName) {
+    const violations = [];
+    for (const attr of attributes) {
+      const globalValue = aggregates[attr];
+      const eventValue = eventAttributes?.[attr];
+      if (globalValue === void 0 && eventValue === void 0) {
+        const allKeys = [
+          ...Object.keys(aggregates),
+          ...eventAttributes ? Object.keys(eventAttributes) : []
+        ];
+        const similar = this.findSimilarAttributes(attr, allKeys);
+        violations.push({
+          ruleId: "narrative-attribute-undefined",
+          severity: "warn",
+          file,
+          path: path4,
+          message: eventName ? `Attribute "{{${attr}}}" not found in event "${eventName}" or global aggregates` : `Attribute "{{${attr}}}" not found in execution data`,
+          impact: 'Template will render as empty or "undefined"',
+          suggestion: similar.length > 0 ? `Did you mean: ${similar.join(", ")}?` : void 0,
+          fixable: false
+        });
+        continue;
+      }
+      const value = eventValue !== void 0 ? eventValue : globalValue;
+      if (this.isObjectType(value)) {
+        const objectKeys = Object.keys(value);
+        const suggestions = objectKeys.slice(0, 3).map((k) => `{{${attr}.${k}}}`);
+        violations.push({
+          ruleId: "narrative-attribute-object",
+          severity: "warn",
+          file,
+          path: path4,
+          message: `Attribute "{{${attr}}}" is an object and will render as "[object Object]"`,
+          impact: 'Template will show "[object Object]" instead of useful data',
+          suggestion: `Access a property instead: ${suggestions.join(", ")}`,
+          fixable: false
+        });
+      }
+    }
+    return violations;
+  }
+  /**
+   * Find similar attribute names for helpful suggestions
+   *
+   * Uses simple string similarity (Levenshtein-like) to find typos
+   *
+   * @param target - The attribute being searched for
+   * @param available - Available attribute names
+   * @returns Array of similar attribute names (max 3)
+   */
+  findSimilarAttributes(target, available) {
+    const similar = [];
+    for (const attr of available) {
+      if (attr.startsWith(target) || target.startsWith(attr)) {
+        similar.push({ attr, score: 10 });
+        continue;
+      }
+      if (attr.includes(target) || target.includes(attr)) {
+        similar.push({ attr, score: 5 });
+        continue;
+      }
+      const targetParts = target.split(".");
+      const attrParts = attr.split(".");
+      if (targetParts.length === attrParts.length) {
+        const matchingParts = targetParts.filter((p, i) => p === attrParts[i]).length;
+        if (matchingParts > 0) {
+          similar.push({ attr, score: matchingParts });
+        }
+      }
+    }
+    return similar.sort((a, b) => b.score - a.score).slice(0, 3).map((s) => s.attr);
+  }
   /**
    * Check formatting options
    */
@@ -242219,6 +242359,71 @@ var NarrativeValidator = class {
     }
     return match[1];
   }
+  /**
+   * Extract attribute references from Handlebars template
+   *
+   * Parses template strings like:
+   * - "{{source}}" -> ["source"]
+   * - "{{source.url}}" -> ["source.url"]
+   * - "{{#if options.global}}" -> ["options.global"]
+   * - "{{#if (eq install.mode 'symlink')}}" -> ["install.mode"]
+   *
+   * @param template - Handlebars template string
+   * @returns Array of attribute paths referenced in the template
+   */
+  extractAttributeReferences(template) {
+    const attributes = /* @__PURE__ */ new Set();
+    const expressionPattern = /\{\{([^}]+)\}\}/g;
+    let match;
+    while ((match = expressionPattern.exec(template)) !== null) {
+      const expression = match[1].trim();
+      if (expression.startsWith("/")) {
+        continue;
+      }
+      if (expression.startsWith("#")) {
+        const helperMatch = expression.match(/^#\w+\s+(.+)$/);
+        if (helperMatch) {
+          this.extractAttributesFromExpression(helperMatch[1], attributes);
+        }
+        continue;
+      }
+      this.extractAttributesFromExpression(expression, attributes);
+    }
+    return Array.from(attributes);
+  }
+  /**
+   * Extract attribute references from a single Handlebars expression
+   *
+   * Handles:
+   * - Simple references: source.url
+   * - Helper calls: (eq install.mode 'symlink')
+   * - Nested expressions
+   *
+   * @param expression - The expression to parse
+   * @param attributes - Set to add found attributes to
+   */
+  extractAttributesFromExpression(expression, attributes) {
+    const cleaned = expression.replace(/^\(|\)$/g, "").trim();
+    const parts = cleaned.split(/\s+/);
+    for (const part of parts) {
+      if (part.match(/^(if|unless|each|with|eq|ne|lt|gt|lte|gte|and|or|not)$/) || part.match(/^['"].*['"]$/) || part.match(/^\d+$/) || part.match(/^(true|false|null|undefined)$/)) {
+        continue;
+      }
+      const cleanPart = part.replace(/['"()]/g, "");
+      if (cleanPart && cleanPart.match(/^[a-zA-Z_][a-zA-Z0-9_.]*$/)) {
+        attributes.add(cleanPart);
+      }
+    }
+  }
+  /**
+   * Check if an attribute is an object type
+   *
+   * @param value - The attribute value to check
+   * @returns true if value is a plain object (not array, not null)
+   */
+  isObjectType(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date);
+  }
 };
 function createNarrativeValidator() {
   return new NarrativeValidator();
@@ -249024,7 +249229,7 @@ function capitalize(str3) {
 // src/commands/narrative/validate.ts
 function createValidateCommand2() {
   const command = new Command("validate");
-  command.description("Validate narrative template syntax, schema, and references").argument("<file>", "Path to .narrative.json file").option("--canvas <path>", "Override canvas file path for validation").option("--json", "Output violations as JSON").option("-q, --quiet", "Only show errors, suppress warnings").option("-d, --dir <path>", "Project directory (default: cwd)").action(async (file, options) => {
+  command.description("Validate narrative template syntax, schema, and references").argument("<file>", "Path to .narrative.json file").option("--canvas <path>", "Override canvas file path for validation").option("--execution <path>", "Execution file (.otel.json) for validating attribute references").option("--json", "Output violations as JSON").option("-q, --quiet", "Only show errors, suppress warnings").option("-d, --dir <path>", "Project directory (default: cwd)").action(async (file, options) => {
     try {
       const baseDir = options.dir || process.cwd();
       const narrativePath = resolvePath(file, baseDir);
@@ -249045,13 +249250,40 @@ function createValidateCommand2() {
           canvas = void 0;
         }
       }
+      let executionData;
+      if (options.execution) {
+        try {
+          const executionPath = resolvePath(options.execution, baseDir);
+          const execution = await loadExecution(executionPath);
+          const events = executionToEvents(execution);
+          const aggregates = computeAggregates(events);
+          const eventAttributes = /* @__PURE__ */ new Map();
+          for (const event of events) {
+            if (!eventAttributes.has(event.name)) {
+              eventAttributes.set(event.name, {});
+            }
+            const attrs = eventAttributes.get(event.name);
+            if (event.attributes) {
+              Object.assign(attrs, event.attributes);
+            }
+          }
+          executionData = { aggregates, eventAttributes };
+        } catch (error) {
+          console.error(
+            source_default.yellow("Warning:"),
+            `Failed to load execution file: ${error.message}`
+          );
+          console.error(source_default.gray("  Attribute validation will be skipped"));
+        }
+      }
       const validator = new NarrativeValidator();
       const context = {
         narrative,
         narrativePath,
         canvasPath,
         canvas,
-        basePath: baseDir
+        basePath: baseDir,
+        executionData
       };
       const result = await validator.validate(context);
       const violations = options.quiet ? result.violations.filter((v) => v.severity === "error") : result.violations;
@@ -249075,7 +249307,8 @@ function createValidateCommand2() {
             errors: errors.length,
             warnings: warnings.length,
             scenarioCount: narrative.scenarios.length,
-            hasDefault: narrative.scenarios.some((s) => s.condition.default)
+            hasDefault: narrative.scenarios.some((s) => s.condition.default),
+            attributeValidation: executionData ? "enabled" : "skipped"
           }
         };
         console.log(JSON.stringify(output, null, 2));
@@ -249140,6 +249373,17 @@ ${icon} ${severity}: ${violation.message}`);
         if (canvasPath) {
           console.log(source_default.gray(`  \u2022 Canvas: ${narrative.canvas || canvasPath}`));
         }
+        if (executionData) {
+          console.log(
+            source_default.gray("  \u2022 Attribute validation:"),
+            source_default.green("enabled")
+          );
+        } else {
+          console.log(
+            source_default.gray("  \u2022 Attribute validation:"),
+            source_default.gray("skipped (use --execution to enable)")
+          );
+        }
         console.log();
       }
       if (errors.length > 0) {