@principal-ai/principal-view-cli 0.3.3 → 0.3.4

package/dist/commands/validate.js

@@ -0,0 +1,1065 @@
+/**
+ * Validate command - Validate .canvas configuration files
+ */
+import { Command } from 'commander';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import chalk from 'chalk';
+import { globby } from 'globby';
+import yaml from 'js-yaml';
+/**
+ * Load the library.yaml file from the .principal-views directory
+ */
+function loadLibrary(principalViewsDir) {
+    const libraryFiles = ['library.yaml', 'library.yml', 'library.json'];
+    for (const fileName of libraryFiles) {
+        const libraryPath = resolve(principalViewsDir, fileName);
+        if (existsSync(libraryPath)) {
+            try {
+                const content = readFileSync(libraryPath, 'utf8');
+                const library = fileName.endsWith('.json') ? JSON.parse(content) : yaml.load(content);
+                if (library && typeof library === 'object') {
+                    return {
+                        nodeComponents: library.nodeComponents ||
+                            {},
+                        edgeComponents: library.edgeComponents ||
+                            {},
+                        raw: library,
+                        path: libraryPath,
+                    };
+                }
+            }
+            catch {
+                // Library exists but failed to parse - return empty to avoid false positives
+                return { nodeComponents: {}, edgeComponents: {}, raw: {}, path: libraryPath };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Validate library.yaml file for unknown fields
+ */
+function validateLibrary(library) {
+    const issues = [];
+    const lib = library.raw;
+    // Check root level fields
+    checkUnknownFields(lib, ALLOWED_LIBRARY_FIELDS.root, '', issues);
+    // Validate nodeComponents
+    if (lib.nodeComponents && typeof lib.nodeComponents === 'object') {
+        for (const [compId, compDef] of Object.entries(lib.nodeComponents)) {
+            if (compDef && typeof compDef === 'object') {
+                const comp = compDef;
+                checkUnknownFields(comp, ALLOWED_LIBRARY_FIELDS.nodeComponent, `nodeComponents.${compId}`, issues);
+                // Validate icon name format (must be PascalCase for Lucide icons)
+                validateIconName(comp.icon, `nodeComponents.${compId}.icon`, issues);
+                // Check nested fields
+                if (comp.size && typeof comp.size === 'object') {
+                    checkUnknownFields(comp.size, ALLOWED_LIBRARY_FIELDS.nodeComponentSize, `nodeComponents.${compId}.size`, issues);
+                }
+                if (comp.states && typeof comp.states === 'object') {
+                    for (const [stateId, stateDef] of Object.entries(comp.states)) {
+                        if (stateDef && typeof stateDef === 'object') {
+                            checkUnknownFields(stateDef, ALLOWED_LIBRARY_FIELDS.nodeComponentState, `nodeComponents.${compId}.states.${stateId}`, issues);
+                            // Validate state icon name format
+                            const state = stateDef;
+                            validateIconName(state.icon, `nodeComponents.${compId}.states.${stateId}.icon`, issues);
+                        }
+                    }
+                }
+                if (comp.dataSchema && typeof comp.dataSchema === 'object') {
+                    for (const [fieldName, fieldDef] of Object.entries(comp.dataSchema)) {
+                        if (fieldDef && typeof fieldDef === 'object') {
+                            checkUnknownFields(fieldDef, ALLOWED_LIBRARY_FIELDS.nodeComponentDataSchemaField, `nodeComponents.${compId}.dataSchema.${fieldName}`, issues);
+                        }
+                    }
+                }
+                if (comp.layout && typeof comp.layout === 'object') {
+                    checkUnknownFields(comp.layout, ALLOWED_LIBRARY_FIELDS.nodeComponentLayout, `nodeComponents.${compId}.layout`, issues);
+                }
+                if (Array.isArray(comp.actions)) {
+                    comp.actions.forEach((action, actionIndex) => {
+                        if (action && typeof action === 'object') {
+                            checkUnknownFields(action, ALLOWED_LIBRARY_FIELDS.nodeComponentAction, `nodeComponents.${compId}.actions[${actionIndex}]`, issues);
+                        }
+                    });
+                }
+            }
+        }
+    }
+    // Validate edgeComponents
+    if (lib.edgeComponents && typeof lib.edgeComponents === 'object') {
+        for (const [compId, compDef] of Object.entries(lib.edgeComponents)) {
+            if (compDef && typeof compDef === 'object') {
+                const comp = compDef;
+                checkUnknownFields(comp, ALLOWED_LIBRARY_FIELDS.edgeComponent, `edgeComponents.${compId}`, issues);
+                // Check nested fields
+                if (comp.animation && typeof comp.animation === 'object') {
+                    checkUnknownFields(comp.animation, ALLOWED_LIBRARY_FIELDS.edgeComponentAnimation, `edgeComponents.${compId}.animation`, issues);
+                }
+                if (comp.label && typeof comp.label === 'object') {
+                    checkUnknownFields(comp.label, ALLOWED_LIBRARY_FIELDS.edgeComponentLabel, `edgeComponents.${compId}.label`, issues);
+                }
+            }
+        }
+    }
+    // Validate connectionRules
+    if (Array.isArray(lib.connectionRules)) {
+        lib.connectionRules.forEach((rule, ruleIndex) => {
+            if (rule && typeof rule === 'object') {
+                const r = rule;
+                checkUnknownFields(r, ALLOWED_LIBRARY_FIELDS.connectionRule, `connectionRules[${ruleIndex}]`, issues);
+                if (r.constraints && typeof r.constraints === 'object') {
+                    checkUnknownFields(r.constraints, ALLOWED_LIBRARY_FIELDS.connectionRuleConstraints, `connectionRules[${ruleIndex}].constraints`, issues);
+                }
+            }
+        });
+    }
+    return issues;
+}
+/**
+ * Standard JSON Canvas node types that don't require pv metadata
+ */
+const STANDARD_CANVAS_TYPES = ['text', 'group', 'file', 'link'];
+// ============================================================================
+// Icon Validation
+// ============================================================================
+/**
+ * Convert kebab-case to PascalCase
+ * e.g., "file-text" -> "FileText", "alert-circle" -> "AlertCircle"
+ */
+function kebabToPascalCase(str) {
+    return str
+        .split('-')
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+        .join('');
+}
+/**
+ * Check if a string looks like kebab-case (has hyphens and lowercase)
+ */
+function isKebabCase(str) {
+    return str.includes('-') && str === str.toLowerCase();
+}
+/**
+ * Validate an icon name and return issues if invalid
+ * Icons should be in PascalCase (e.g., "FileText", "Database", "AlertCircle")
+ */
+function validateIconName(iconValue, path, issues) {
+    if (typeof iconValue !== 'string' || !iconValue) {
+        return; // No icon specified, that's fine
+    }
+    // Check if it looks like kebab-case
+    if (isKebabCase(iconValue)) {
+        const suggested = kebabToPascalCase(iconValue);
+        issues.push({
+            type: 'error',
+            message: `Invalid icon name "${iconValue}" - icons must be in PascalCase`,
+            path,
+            suggestion: `Use "${suggested}" instead of "${iconValue}"`,
+        });
+        return;
+    }
+    // Check if first character is lowercase (common mistake)
+    if (iconValue[0] === iconValue[0].toLowerCase() && iconValue[0] !== iconValue[0].toUpperCase()) {
+        const suggested = iconValue.charAt(0).toUpperCase() + iconValue.slice(1);
+        issues.push({
+            type: 'error',
+            message: `Invalid icon name "${iconValue}" - icons must start with uppercase`,
+            path,
+            suggestion: `Use "${suggested}" instead of "${iconValue}"`,
+        });
+    }
+}
+// ============================================================================
+// Allowed Fields Definitions
+// ============================================================================
+/**
+ * Allowed fields for canvas validation
+ */
+const ALLOWED_CANVAS_FIELDS = {
+    root: ['nodes', 'edges', 'pv'],
+    pv: [
+        'version',
+        'name',
+        'description',
+        'nodeTypes',
+        'edgeTypes',
+        'pathConfig',
+        'display',
+        'scope',
+        'audit',
+    ],
+    pvPathConfig: [
+        'projectRoot',
+        'captureSource',
+        'enableActionPatterns',
+        'logLevel',
+        'ignoreUnsourced',
+    ],
+    pvDisplay: ['layout', 'theme', 'animations'],
+    pvDisplayTheme: ['primary', 'success', 'warning', 'danger', 'info'],
+    pvDisplayAnimations: ['enabled', 'speed'],
+    pvNodeType: ['label', 'description', 'color', 'icon', 'shape'],
+    pvEdgeType: [
+        'label',
+        'style',
+        'color',
+        'width',
+        'directed',
+        'animation',
+        'labelConfig',
+        'activatedBy',
+    ],
+    pvEdgeTypeAnimation: ['type', 'duration', 'color'],
+    pvEdgeTypeLabelConfig: ['field', 'position'],
+    // Base node fields from JSON Canvas spec
+    nodeBase: ['id', 'type', 'x', 'y', 'width', 'height', 'color', 'pv'],
+    // Type-specific node fields
+    nodeText: ['text'],
+    nodeFile: ['file', 'subpath'],
+    nodeLink: ['url'],
+    nodeGroup: ['label', 'background', 'backgroundStyle'],
+    // Node pv extension
+    nodePv: [
+        'nodeType',
+        'name',
+        'description',
+        'otel',
+        'event',
+        'shape',
+        'icon',
+        'fill',
+        'stroke',
+        'states',
+        'sources',
+        'resourceMatch',
+        'actions',
+        'dataSchema',
+        'layout',
+    ],
+    nodePvOtel: ['kind', 'category', 'isNew'],
+    nodePvState: ['color', 'icon', 'label'],
+    nodePvAction: ['pattern', 'event', 'state', 'metadata', 'triggerEdges'],
+    nodePvDataSchemaField: ['type', 'required', 'displayInLabel'],
+    nodePvLayout: ['layer', 'cluster'],
+    // Edge fields
+    edge: [
+        'id',
+        'fromNode',
+        'toNode',
+        'fromSide',
+        'toSide',
+        'fromEnd',
+        'toEnd',
+        'color',
+        'label',
+        'pv',
+    ],
+    edgePv: ['edgeType', 'style', 'width', 'animation', 'activatedBy'],
+    edgePvAnimation: ['type', 'duration', 'color'],
+    edgePvActivatedBy: ['action', 'animation', 'direction', 'duration'],
+};
+/**
+ * Allowed fields for library validation
+ */
+const ALLOWED_LIBRARY_FIELDS = {
+    root: ['version', 'name', 'description', 'nodeComponents', 'edgeComponents', 'connectionRules'],
+    nodeComponent: [
+        'description',
+        'tags',
+        'defaultLabel',
+        'shape',
+        'icon',
+        'color',
+        'size',
+        'states',
+        'sources',
+        'resourceMatch',
+        'actions',
+        'dataSchema',
+        'layout',
+    ],
+    nodeComponentSize: ['width', 'height'],
+    nodeComponentState: ['color', 'icon', 'label'],
+    nodeComponentAction: ['pattern', 'event', 'state', 'metadata', 'triggerEdges'],
+    nodeComponentDataSchemaField: ['type', 'required', 'displayInLabel', 'label', 'displayInInfo'],
+    nodeComponentLayout: ['layer', 'cluster'],
+    edgeComponent: [
+        'description',
+        'tags',
+        'style',
+        'color',
+        'width',
+        'directed',
+        'animation',
+        'label',
+    ],
+    edgeComponentAnimation: ['type', 'duration', 'color'],
+    edgeComponentLabel: ['field', 'position'],
+    connectionRule: ['from', 'to', 'via', 'constraints'],
+    connectionRuleConstraints: ['maxInstances', 'bidirectional', 'exclusive'],
+};
+/**
+ * Check for unknown fields and return validation issues
+ */
+function checkUnknownFields(obj, allowedFields, path, issues) {
+    for (const field of Object.keys(obj)) {
+        if (!allowedFields.includes(field)) {
+            const suggestion = findSimilarField(field, allowedFields);
+            issues.push({
+                type: 'error',
+                message: `Unknown field "${field}"${path ? ` in ${path}` : ' at root level'}`,
+                path: path ? `${path}.${field}` : field,
+                suggestion: suggestion
+                    ? `Did you mean "${suggestion}"? Allowed fields: ${allowedFields.join(', ')}`
+                    : `Allowed fields: ${allowedFields.join(', ')}`,
+            });
+        }
+    }
+}
+/**
+ * Find a similar field name for suggestions
+ */
+function findSimilarField(field, allowedFields) {
+    const fieldLower = field.toLowerCase();
+    for (const allowed of allowedFields) {
+        const allowedLower = allowed.toLowerCase();
+        if (fieldLower.includes(allowedLower) || allowedLower.includes(fieldLower)) {
+            return allowed;
+        }
+        // Check for small edit distance
+        if (Math.abs(field.length - allowed.length) <= 2) {
+            let differences = 0;
+            const minLen = Math.min(fieldLower.length, allowedLower.length);
+            for (let i = 0; i < minLen; i++) {
+                if (fieldLower[i] !== allowedLower[i])
+                    differences++;
+            }
+            differences += Math.abs(field.length - allowed.length);
+            if (differences <= 2)
+                return allowed;
+        }
+    }
+    return null;
+}
+/**
+ * Check if a canvas has OTEL-related features
+ * Returns true if the canvas contains any of:
+ * 1. Nodes with pv.otel extension (kind, category)
+ * 2. Event schema (pv.event with validation)
+ * 3. Canvas scope/audit config (OTEL log routing)
+ * 4. Resource matching for OTEL logs
+ */
+function hasOtelFeatures(canvas) {
+    if (!canvas || typeof canvas !== 'object') {
+        return false;
+    }
+    const c = canvas;
+    // Check for canvas-level scope or audit config
+    if (c.pv && typeof c.pv === 'object') {
+        const pv = c.pv;
+        if (pv.scope !== undefined || pv.audit !== undefined) {
+            return true;
+        }
+    }
+    // Check nodes for OTEL features
+    if (Array.isArray(c.nodes)) {
+        for (const node of c.nodes) {
+            if (node && typeof node === 'object') {
+                const n = node;
+                if (n.pv && typeof n.pv === 'object') {
+                    const nodePv = n.pv;
+                    // Check for pv.otel extension
+                    if (nodePv.otel !== undefined) {
+                        return true;
+                    }
+                    // Check for event schema (pv.event)
+                    if (nodePv.event !== undefined) {
+                        return true;
+                    }
+                    // Check for resourceMatch (OTEL log routing)
+                    if (nodePv.resourceMatch !== undefined) {
+                        return true;
+                    }
+                }
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Validate an ExtendedCanvas object with strict validation
+ *
+ * Strict validation ensures:
+ * - All required fields are present
+ * - Custom node types have proper pv metadata
+ * - Edge types reference defined types in pv.edgeTypes or library.edgeComponents
+ * - Node types reference defined types in pv.nodeTypes or library.nodeComponents
+ * - Canvas has pv extension with name and version
+ * - OTEL nodes have source file references and the files exist
+ */
+function validateCanvas(canvas, filePath, library, repositoryPath) {
+    const issues = [];
+    if (!canvas || typeof canvas !== 'object') {
+        issues.push({ type: 'error', message: 'Canvas must be an object' });
+        return issues;
+    }
+    const c = canvas;
+    // Check unknown fields at canvas root level
+    checkUnknownFields(c, ALLOWED_CANVAS_FIELDS.root, '', issues);
+    // Collect library-defined types
+    const libraryNodeTypes = library ? Object.keys(library.nodeComponents) : [];
+    const libraryEdgeTypes = library ? Object.keys(library.edgeComponents) : [];
+    // Check pv extension (REQUIRED for strict validation)
+    let canvasEdgeTypes = [];
+    let canvasNodeTypes = [];
+    if (c.pv === undefined) {
+        issues.push({
+            type: 'error',
+            message: 'Canvas must have a "pv" extension with name and version',
+            path: 'pv',
+            suggestion: 'Add: "pv": { "name": "My Graph", "version": "1.0.0" }',
+        });
+    }
+    else if (typeof c.pv !== 'object') {
+        issues.push({ type: 'error', message: '"pv" extension must be an object' });
+    }
+    else {
+        const pv = c.pv;
+        // Check unknown fields in pv extension
+        checkUnknownFields(pv, ALLOWED_CANVAS_FIELDS.pv, 'pv', issues);
+        if (typeof pv.version !== 'string' || !pv.version) {
+            issues.push({
+                type: 'error',
+                message: 'pv.version is required',
+                path: 'pv.version',
+                suggestion: 'Add: "version": "1.0.0"',
+            });
+        }
+        if (typeof pv.name !== 'string' || !pv.name) {
+            issues.push({
+                type: 'error',
+                message: 'pv.name is required',
+                path: 'pv.name',
+                suggestion: 'Add: "name": "My Graph"',
+            });
+        }
+        // Validate pv.pathConfig if present
+        if (pv.pathConfig && typeof pv.pathConfig === 'object') {
+            checkUnknownFields(pv.pathConfig, ALLOWED_CANVAS_FIELDS.pvPathConfig, 'pv.pathConfig', issues);
+        }
+        // Validate pv.display if present
+        if (pv.display && typeof pv.display === 'object') {
+            const display = pv.display;
+            checkUnknownFields(display, ALLOWED_CANVAS_FIELDS.pvDisplay, 'pv.display', issues);
+            if (display.theme && typeof display.theme === 'object') {
+                checkUnknownFields(display.theme, ALLOWED_CANVAS_FIELDS.pvDisplayTheme, 'pv.display.theme', issues);
+            }
+            if (display.animations && typeof display.animations === 'object') {
+                checkUnknownFields(display.animations, ALLOWED_CANVAS_FIELDS.pvDisplayAnimations, 'pv.display.animations', issues);
+            }
+        }
+        // Collect and validate defined node types
+        if (pv.nodeTypes && typeof pv.nodeTypes === 'object') {
+            canvasNodeTypes = Object.keys(pv.nodeTypes);
+            for (const [typeId, typeDef] of Object.entries(pv.nodeTypes)) {
+                if (typeDef && typeof typeDef === 'object') {
+                    checkUnknownFields(typeDef, ALLOWED_CANVAS_FIELDS.pvNodeType, `pv.nodeTypes.${typeId}`, issues);
+                    // Validate icon name format
+                    const nodeType = typeDef;
+                    validateIconName(nodeType.icon, `pv.nodeTypes.${typeId}.icon`, issues);
+                }
+            }
+        }
+        // Collect and validate defined edge types
+        if (pv.edgeTypes && typeof pv.edgeTypes === 'object') {
+            canvasEdgeTypes = Object.keys(pv.edgeTypes);
+            for (const [typeId, typeDef] of Object.entries(pv.edgeTypes)) {
+                if (typeDef && typeof typeDef === 'object') {
+                    const edgeTypeDef = typeDef;
+                    checkUnknownFields(edgeTypeDef, ALLOWED_CANVAS_FIELDS.pvEdgeType, `pv.edgeTypes.${typeId}`, issues);
+                    if (edgeTypeDef.animation && typeof edgeTypeDef.animation === 'object') {
+                        checkUnknownFields(edgeTypeDef.animation, ALLOWED_CANVAS_FIELDS.pvEdgeTypeAnimation, `pv.edgeTypes.${typeId}.animation`, issues);
+                    }
+                    if (edgeTypeDef.labelConfig && typeof edgeTypeDef.labelConfig === 'object') {
+                        checkUnknownFields(edgeTypeDef.labelConfig, ALLOWED_CANVAS_FIELDS.pvEdgeTypeLabelConfig, `pv.edgeTypes.${typeId}.labelConfig`, issues);
+                    }
+                }
+            }
+        }
+    }
+    // Combined types from canvas + library
+    const allDefinedNodeTypes = [...new Set([...canvasNodeTypes, ...libraryNodeTypes])];
+    const allDefinedEdgeTypes = [...new Set([...canvasEdgeTypes, ...libraryEdgeTypes])];
+    // Check nodes
+    if (!Array.isArray(c.nodes)) {
+        issues.push({ type: 'error', message: 'Canvas must have a "nodes" array' });
+    }
+    else {
+        c.nodes.forEach((node, index) => {
+            if (!node || typeof node !== 'object') {
+                issues.push({
+                    type: 'error',
+                    message: `Node at index ${index} must be an object`,
+                    path: `nodes[${index}]`,
+                });
+                return;
+            }
+            const n = node;
+            const nodePath = `nodes[${index}]`;
+            const nodeLabel = n.id || index;
+            // Check unknown fields on node based on type
+            const nodeType = n.type;
+            let allowedNodeFields = [...ALLOWED_CANVAS_FIELDS.nodeBase];
+            if (nodeType === 'text') {
+                allowedNodeFields = [...allowedNodeFields, ...ALLOWED_CANVAS_FIELDS.nodeText];
+            }
+            else if (nodeType === 'file') {
+                allowedNodeFields = [...allowedNodeFields, ...ALLOWED_CANVAS_FIELDS.nodeFile];
+            }
+            else if (nodeType === 'link') {
+                allowedNodeFields = [...allowedNodeFields, ...ALLOWED_CANVAS_FIELDS.nodeLink];
+            }
+            else if (nodeType === 'group') {
+                allowedNodeFields = [...allowedNodeFields, ...ALLOWED_CANVAS_FIELDS.nodeGroup];
+            }
+            // Custom types can have any base fields
+            checkUnknownFields(n, allowedNodeFields, nodePath, issues);
+            if (typeof n.id !== 'string' || !n.id) {
+                issues.push({
+                    type: 'error',
+                    message: `Node at index ${index} must have a string "id"`,
+                    path: `${nodePath}.id`,
+                });
+            }
+            if (typeof n.type !== 'string') {
+                issues.push({
+                    type: 'error',
+                    message: `Node "${nodeLabel}" must have a string "type"`,
+                    path: `${nodePath}.type`,
+                });
+            }
+            if (typeof n.x !== 'number') {
+                issues.push({
+                    type: 'error',
+                    message: `Node "${nodeLabel}" must have a numeric "x" position`,
+                    path: `${nodePath}.x`,
+                });
+            }
+            if (typeof n.y !== 'number') {
+                issues.push({
+                    type: 'error',
+                    message: `Node "${nodeLabel}" must have a numeric "y" position`,
+                    path: `${nodePath}.y`,
+                });
+            }
+            // Width and height are now REQUIRED (was warning)
+            if (typeof n.width !== 'number') {
+                issues.push({
+                    type: 'error',
+                    message: `Node "${nodeLabel}" must have a numeric "width"`,
+                    path: `${nodePath}.width`,
+                });
+            }
+            if (typeof n.height !== 'number') {
+                issues.push({
+                    type: 'error',
+                    message: `Node "${nodeLabel}" must have a numeric "height"`,
+                    path: `${nodePath}.height`,
+                });
+            }
+            // Validate required fields for standard canvas types
+            if (nodeType === 'text' && (typeof n.text !== 'string' || !n.text)) {
+                issues.push({
+                    type: 'error',
+                    message: `Node "${nodeLabel}" has type "text" but is missing required "text" field`,
+                    path: `${nodePath}.text`,
+                    suggestion: 'Add a "text" field with markdown content, or change the node type',
+                });
+            }
+            if (nodeType === 'file' && (typeof n.file !== 'string' || !n.file)) {
+                issues.push({
+                    type: 'error',
+                    message: `Node "${nodeLabel}" has type "file" but is missing required "file" field`,
+                    path: `${nodePath}.file`,
+                    suggestion: 'Add a "file" field with a file path, or change the node type',
+                });
+            }
+            if (nodeType === 'link' && (typeof n.url !== 'string' || !n.url)) {
+                issues.push({
+                    type: 'error',
+                    message: `Node "${nodeLabel}" has type "link" but is missing required "url" field`,
+                    path: `${nodePath}.url`,
+                    suggestion: 'Add a "url" field with a URL, or change the node type',
+                });
+            }
+            // Validate node type - must be a standard JSON Canvas type
+            const isStandardType = STANDARD_CANVAS_TYPES.includes(nodeType);
+            if (!isStandardType) {
+                issues.push({
+                    type: 'error',
+                    message: `Node "${n.id || index}" uses invalid type "${nodeType}"`,
+                    path: `nodes[${index}].type`,
+                    suggestion: `Use a standard JSON Canvas type (${STANDARD_CANVAS_TYPES.join(', ')}). For custom shapes, use type: "text" with pv.shape: "${nodeType}"`,
+                });
+            }
+            // Validate node pv extension fields
+            if (n.pv && typeof n.pv === 'object') {
+                const nodePv = n.pv;
+                // Check unknown fields in node pv extension
+                checkUnknownFields(nodePv, ALLOWED_CANVAS_FIELDS.nodePv, `${nodePath}.pv`, issues);
+                // Validate icon name format (must be PascalCase for Lucide icons)
+                validateIconName(nodePv.icon, `${nodePath}.pv.icon`, issues);
+                // Check nested pv fields
+                if (nodePv.states && typeof nodePv.states === 'object') {
+                    for (const [stateId, stateDef] of Object.entries(nodePv.states)) {
+                        if (stateDef && typeof stateDef === 'object') {
+                            checkUnknownFields(stateDef, ALLOWED_CANVAS_FIELDS.nodePvState, `${nodePath}.pv.states.${stateId}`, issues);
+                            // Validate state icon name format
+                            const state = stateDef;
+                            validateIconName(state.icon, `${nodePath}.pv.states.${stateId}.icon`, issues);
+                        }
+                    }
+                }
+                if (nodePv.dataSchema && typeof nodePv.dataSchema === 'object') {
+                    for (const [fieldName, fieldDef] of Object.entries(nodePv.dataSchema)) {
+                        if (fieldDef && typeof fieldDef === 'object') {
+                            checkUnknownFields(fieldDef, ALLOWED_CANVAS_FIELDS.nodePvDataSchemaField, `${nodePath}.pv.dataSchema.${fieldName}`, issues);
+                        }
+                    }
+                }
+                if (nodePv.layout && typeof nodePv.layout === 'object') {
+                    checkUnknownFields(nodePv.layout, ALLOWED_CANVAS_FIELDS.nodePvLayout, `${nodePath}.pv.layout`, issues);
+                }
+                if (nodePv.otel && typeof nodePv.otel === 'object') {
+                    checkUnknownFields(nodePv.otel, ALLOWED_CANVAS_FIELDS.nodePvOtel, `${nodePath}.pv.otel`, issues);
+                }
+                // For .otel.canvas files: require event field on nodes with pv extension (except groups)
+                if (filePath.endsWith('.otel.canvas') && nodeType !== 'group') {
+                    if (nodePv.event === undefined) {
+                        issues.push({
+                            type: 'error',
+                            message: `Node "${nodeLabel}" in .otel.canvas file must have "pv.event" field`,
+                            path: `${nodePath}.pv.event`,
+                            suggestion: 'Add event name, e.g.: "event": "user.login" or "event": "order.created"',
+                        });
+                    }
+                }
+                // Validate source file references for OTEL event nodes
+                const hasOtelFeatures = nodePv.otel !== undefined || nodePv.event !== undefined;
+                if (hasOtelFeatures) {
+                    // OTEL nodes must have at least one source file reference
+                    if (!Array.isArray(nodePv.sources) || nodePv.sources.length === 0) {
+                        issues.push({
+                            type: 'error',
+                            message: `Node "${nodeLabel}" has OTEL features but is missing required "pv.sources" field`,
+                            path: `${nodePath}.pv.sources`,
+                            suggestion: 'Add at least one source file reference, e.g.: "sources": ["src/services/MyService.ts"]',
+                        });
+                    }
+                    // For .otel.canvas files: nodes with event must have pv.otel for UI rendering
+                    if (filePath.endsWith('.otel.canvas') && nodePv.event !== undefined && nodePv.otel === undefined) {
+                        issues.push({
+                            type: 'error',
+                            message: `Node "${nodeLabel}" in .otel.canvas file has event but is missing "pv.otel" field required for UI badges`,
+                            path: `${nodePath}.pv.otel`,
+                            suggestion: 'Add OTEL metadata for UI rendering, e.g.: "otel": { "kind": "event", "category": "lifecycle", "isNew": true }',
+                        });
+                    }
+                }
+                // Validate source file paths
+                if (Array.isArray(nodePv.sources)) {
+                    nodePv.sources.forEach((source, sourceIndex) => {
+                        if (typeof source === 'string') {
+                            // Check for glob patterns
+                            if (/[*?[\]{}]/.test(source)) {
+                                issues.push({
+                                    type: 'error',
+                                    message: `Node "${nodeLabel}" has glob pattern in sources: ${source}`,
+                                    path: `${nodePath}.pv.sources[${sourceIndex}]`,
+                                    suggestion: 'Use exact file paths only. Glob patterns (*, ?, [], {}) are not supported in sources.',
+                                });
+                            }
+                            // Check for line number suffix (e.g., "file.ts:123")
+                            if (/:\d+$/.test(source)) {
+                                issues.push({
+                                    type: 'error',
+                                    message: `Node "${nodeLabel}" has line number suffix in sources: ${source}`,
+                                    path: `${nodePath}.pv.sources[${sourceIndex}]`,
+                                    suggestion: 'Remove line number suffix. Use exact file paths only (e.g., "src/file.ts" not "src/file.ts:123").',
+                                });
+                            }
+                            // Validate that source file exists (if repository path is provided)
+                            if (repositoryPath) {
+                                const fullPath = resolve(repositoryPath, source);
+                                if (!existsSync(fullPath)) {
+                                    issues.push({
+                                        type: 'error',
+                                        message: `Node "${nodeLabel}" references non-existent source file: ${source}`,
+                                        path: `${nodePath}.pv.sources[${sourceIndex}]`,
+                                        suggestion: `Verify the file path is correct relative to repository root: ${repositoryPath}`,
+                                    });
+                                }
+                            }
+                        }
+                    });
+                }
+                if (Array.isArray(nodePv.actions)) {
+                    nodePv.actions.forEach((action, actionIndex) => {
+                        if (action && typeof action === 'object') {
+                            checkUnknownFields(action, ALLOWED_CANVAS_FIELDS.nodePvAction, `${nodePath}.pv.actions[${actionIndex}]`, issues);
+                        }
+                    });
+                }
+                // Validate pv.nodeType references a defined nodeType
+                if (typeof nodePv.nodeType === 'string' && nodePv.nodeType) {
+                    if (allDefinedNodeTypes.length === 0) {
+                        issues.push({
+                            type: 'error',
+                            message: `Node "${nodeLabel}" uses nodeType "${nodePv.nodeType}" but no node types are defined`,
+                            path: `${nodePath}.pv.nodeType`,
+                            suggestion: 'Define node types in canvas pv.nodeTypes or library.yaml nodeComponents',
+                        });
+                    }
+                    else if (!allDefinedNodeTypes.includes(nodePv.nodeType)) {
+                        // Build a helpful suggestion showing where types can be defined
+                        const sources = [];
+                        if (canvasNodeTypes.length > 0) {
+                            sources.push(`canvas pv.nodeTypes: ${canvasNodeTypes.join(', ')}`);
+                        }
+                        if (libraryNodeTypes.length > 0) {
+                            sources.push(`library.yaml nodeComponents: ${libraryNodeTypes.join(', ')}`);
+                        }
+                        const suggestion = sources.length > 0
+                            ? `Available types from ${sources.join(' | ')}`
+                            : 'Define node types in canvas pv.nodeTypes or library.yaml nodeComponents';
+                        issues.push({
+                            type: 'error',
+                            message: `Node "${nodeLabel}" uses undefined nodeType "${nodePv.nodeType}"`,
+                            path: `${nodePath}.pv.nodeType`,
+                            suggestion,
+                        });
+                    }
+                }
+            }
+        });
+    }
+    // Check edges (optional but validated strictly if present)
+    if (c.edges !== undefined && !Array.isArray(c.edges)) {
+        issues.push({ type: 'error', message: '"edges" must be an array if present' });
+    }
+    else if (Array.isArray(c.edges)) {
+        const nodeIds = new Set(c.nodes?.map((n) => n.id) || []);
+        c.edges.forEach((edge, index) => {
+            if (!edge || typeof edge !== 'object') {
+                issues.push({
+                    type: 'error',
+                    message: `Edge at index ${index} must be an object`,
+                    path: `edges[${index}]`,
+                });
+                return;
+            }
+            const e = edge;
+            const edgePath = `edges[${index}]`;
+            const edgeLabel = e.id || index;
+            // Check unknown fields on edge
+            checkUnknownFields(e, ALLOWED_CANVAS_FIELDS.edge, edgePath, issues);
+            if (typeof e.id !== 'string' || !e.id) {
+                issues.push({
+                    type: 'error',
+                    message: `Edge at index ${index} must have a string "id"`,
+                    path: `${edgePath}.id`,
+                });
+            }
+            if (typeof e.fromNode !== 'string') {
+                issues.push({
+                    type: 'error',
+                    message: `Edge "${edgeLabel}" must have a string "fromNode"`,
+                    path: `${edgePath}.fromNode`,
+                });
+            }
+            else if (!nodeIds.has(e.fromNode)) {
+                issues.push({
+                    type: 'error',
+                    message: `Edge "${edgeLabel}" references unknown node "${e.fromNode}"`,
+                    path: `${edgePath}.fromNode`,
+                });
+            }
+            if (typeof e.toNode !== 'string') {
+                issues.push({
+                    type: 'error',
+                    message: `Edge "${edgeLabel}" must have a string "toNode"`,
+                    path: `${edgePath}.toNode`,
+                });
+            }
+            else if (!nodeIds.has(e.toNode)) {
+                issues.push({
+                    type: 'error',
+                    message: `Edge "${edgeLabel}" references unknown node "${e.toNode}"`,
+                    path: `${edgePath}.toNode`,
+                });
+            }
+            // Validate fromSide and toSide are present and valid
+            const VALID_SIDES = ['top', 'right', 'bottom', 'left'];
+            if (typeof e.fromSide !== 'string') {
+                issues.push({
+                    type: 'error',
+                    message: `Edge "${edgeLabel}" must have a "fromSide" field`,
+                    path: `${edgePath}.fromSide`,
+                    suggestion: `Specify which side of the source node the edge starts from: ${VALID_SIDES.join(', ')}`,
+                });
+            }
+            else if (!VALID_SIDES.includes(e.fromSide)) {
+                issues.push({
+                    type: 'error',
+                    message: `Edge "${edgeLabel}" has invalid fromSide "${e.fromSide}"`,
+                    path: `${edgePath}.fromSide`,
+                    suggestion: `Valid values: ${VALID_SIDES.join(', ')}`,
+                });
+            }
+            if (typeof e.toSide !== 'string') {
+                issues.push({
+                    type: 'error',
+                    message: `Edge "${edgeLabel}" must have a "toSide" field`,
+                    path: `${edgePath}.toSide`,
+                    suggestion: `Specify which side of the target node the edge connects to: ${VALID_SIDES.join(', ')}`,
+                });
+            }
+            else if (!VALID_SIDES.includes(e.toSide)) {
+                issues.push({
+                    type: 'error',
+                    message: `Edge "${edgeLabel}" has invalid toSide "${e.toSide}"`,
+                    path: `${edgePath}.toSide`,
+                    suggestion: `Valid values: ${VALID_SIDES.join(', ')}`,
+                });
+            }
+            // Validate pv extension is present with edgeType
+            if (!e.pv || typeof e.pv !== 'object') {
+                issues.push({
+                    type: 'error',
+                    message: `Edge "${edgeLabel}" must have a "pv" extension with edgeType`,
+                    path: `${edgePath}.pv`,
+                    suggestion: 'Add: "pv": { "edgeType": "your-edge-type" }',
+                });
+            }
+            else {
+                const edgePv = e.pv;
+                if (typeof edgePv.edgeType !== 'string' || !edgePv.edgeType) {
+                    issues.push({
+                        type: 'error',
+                        message: `Edge "${edgeLabel}" must have a "pv.edgeType" field`,
+                        path: `${edgePath}.pv.edgeType`,
+                        suggestion: allDefinedEdgeTypes.length > 0
+                            ? `Available types: ${allDefinedEdgeTypes.join(', ')}`
+                            : 'Define edge types in canvas pv.edgeTypes or library.yaml edgeComponents',
+                    });
+                }
+            }
+            // Validate edge pv extension fields
+            if (e.pv && typeof e.pv === 'object') {
+                const edgePv = e.pv;
+                // Check unknown fields in edge pv extension
+                checkUnknownFields(edgePv, ALLOWED_CANVAS_FIELDS.edgePv, `${edgePath}.pv`, issues);
+                // Check nested edge pv fields
+                if (edgePv.animation && typeof edgePv.animation === 'object') {
+                    checkUnknownFields(edgePv.animation, ALLOWED_CANVAS_FIELDS.edgePvAnimation, `${edgePath}.pv.animation`, issues);
+                }
+                if (Array.isArray(edgePv.activatedBy)) {
+                    edgePv.activatedBy.forEach((trigger, triggerIndex) => {
+                        if (trigger && typeof trigger === 'object') {
+                            checkUnknownFields(trigger, ALLOWED_CANVAS_FIELDS.edgePvActivatedBy, `${edgePath}.pv.activatedBy[${triggerIndex}]`, issues);
+                        }
+                    });
+                }
+                // Validate edge type references
+                if (edgePv.edgeType && typeof edgePv.edgeType === 'string') {
+                    if (allDefinedEdgeTypes.length === 0) {
+                        issues.push({
+                            type: 'error',
+                            message: `Edge "${edgeLabel}" uses edgeType "${edgePv.edgeType}" but no edge types are defined`,
+                            path: `${edgePath}.pv.edgeType`,
+                            suggestion: 'Define edge types in canvas pv.edgeTypes or library.yaml edgeComponents',
+                        });
+                    }
+                    else if (!allDefinedEdgeTypes.includes(edgePv.edgeType)) {
+                        // Build a helpful suggestion showing where types can be defined
+                        const sources = [];
+                        if (canvasEdgeTypes.length > 0) {
+                            sources.push(`canvas pv.edgeTypes: ${canvasEdgeTypes.join(', ')}`);
+                        }
+                        if (libraryEdgeTypes.length > 0) {
+                            sources.push(`library.yaml edgeComponents: ${libraryEdgeTypes.join(', ')}`);
+                        }
+                        const suggestion = sources.length > 0
+                            ? `Available types from ${sources.join(' | ')}`
+                            : 'Define edge types in canvas pv.edgeTypes or library.yaml edgeComponents';
+                        issues.push({
+                            type: 'error',
+                            message: `Edge "${edgeLabel}" uses undefined edgeType "${edgePv.edgeType}"`,
+                            path: `${edgePath}.pv.edgeType`,
+                            suggestion,
+                        });
+                    }
+                }
+            }
+        });
+    }
+    // Validate OTEL canvas naming convention
+    const hasOtel = hasOtelFeatures(canvas);
+    const isOtelCanvas = filePath.endsWith('.otel.canvas');
+    if (hasOtel && !isOtelCanvas) {
+        issues.push({
+            type: 'error',
+            message: 'Canvas contains OTEL features but does not use .otel.canvas naming convention',
+            suggestion: 'Rename file to use .otel.canvas extension (e.g., "graph-name.otel.canvas")',
+        });
+    }
+    else if (!hasOtel && isOtelCanvas) {
+        issues.push({
+            type: 'warning',
+            message: 'Canvas uses .otel.canvas naming but does not contain any OTEL features',
+            suggestion: 'Either add OTEL features (pv.otel, pv.events, pv.scope, pv.audit, resourceMatch) or rename to .canvas',
+        });
+    }
+    return issues;
+}
+/**
+ * Validate a single .canvas file
+ */
+function validateFile(filePath, library, repositoryPath) {
+    const absolutePath = resolve(filePath);
+    const relativePath = relative(process.cwd(), absolutePath);
+    if (!existsSync(absolutePath)) {
+        return {
+            file: relativePath,
+            isValid: false,
+            issues: [{ type: 'error', message: `File not found: ${filePath}` }],
+        };
+    }
+    try {
+        const content = readFileSync(absolutePath, 'utf8');
+        const canvas = JSON.parse(content);
+        const issues = validateCanvas(canvas, relativePath, library, repositoryPath);
+        const hasErrors = issues.some((i) => i.type === 'error');
+        return {
+            file: relativePath,
+            isValid: !hasErrors,
+            issues,
+            canvas: hasErrors ? undefined : canvas,
+        };
+    }
+    catch (error) {
+        return {
+            file: relativePath,
+            isValid: false,
+            issues: [{ type: 'error', message: `Failed to parse JSON: ${error.message}` }],
+        };
+    }
+}
+export function createValidateCommand() {
+    const command = new Command('validate');
+    command
+        .description('Validate .canvas configuration files')
+        .argument('[files...]', 'Files or glob patterns to validate (defaults to .principal-views/*.canvas)')
+        .option('-q, --quiet', 'Only output errors')
+        .option('--json', 'Output results as JSON')
+        .option('-r, --repository <path>', 'Repository root path for validating source file references (defaults to current directory)')
+        .action(async (files, options) => {
+        try {
+            // Default to .principal-views/*.canvas if no files specified
+            const patterns = files.length > 0 ? files : ['.principal-views/*.canvas'];
+            // Find all matching files
+            const matchedFiles = await globby(patterns, {
+                expandDirectories: false,
+            });
+            if (matchedFiles.length === 0) {
+                if (options.json) {
+                    console.log(JSON.stringify({ files: [], summary: { total: 0, valid: 0, invalid: 0 } }));
+                }
+                else {
+                    console.log(chalk.yellow('No .canvas files found matching the specified patterns.'));
+                    console.log(chalk.dim(`Patterns searched: ${patterns.join(', ')}`));
+                    console.log(chalk.dim('\nTo create a new .principal-views folder, run: npx @principal-ai/principal-view-cli init'));
+                }
+                return;
+            }
+            // Load library from .principal-views directory (used for type validation)
+            const principalViewsDir = resolve(process.cwd(), '.principal-views');
+            const library = loadLibrary(principalViewsDir);
+            // Determine repository path for source file validation
+            const repositoryPath = options.repository
+                ? resolve(options.repository)
+                : process.cwd();
+            // Validate library if present
+            let libraryResult = null;
+            if (library && Object.keys(library.raw).length > 0) {
+                const libraryIssues = validateLibrary(library);
+                const libraryHasErrors = libraryIssues.some((i) => i.type === 'error');
+                libraryResult = {
+                    file: relative(process.cwd(), library.path),
+                    isValid: !libraryHasErrors,
+                    issues: libraryIssues,
+                };
+            }
+            // Validate all canvas files
+            const results = matchedFiles.map((f) => validateFile(f, library, repositoryPath));
+            // Combine results
+            const allResults = libraryResult ? [libraryResult, ...results] : results;
+            const validCount = allResults.filter((r) => r.isValid).length;
+            const invalidCount = allResults.length - validCount;
+            // Output results
+            if (options.json) {
+                console.log(JSON.stringify({
+                    files: allResults,
+                    summary: { total: allResults.length, valid: validCount, invalid: invalidCount },
+                }, null, 2));
+            }
+            else {
+                if (!options.quiet) {
+                    const fileCount = libraryResult
+                        ? `${results.length} canvas file(s) + library`
+                        : `${results.length} canvas file(s)`;
+                    console.log(chalk.bold(`\nValidating ${fileCount}...\n`));
+                }
+                for (const result of allResults) {
+                    if (result.isValid) {
+                        if (!options.quiet) {
+                            console.log(chalk.green(`✓ ${result.file}`));
+                            const warnings = result.issues.filter((i) => i.type === 'warning');
+                            if (warnings.length > 0) {
+                                warnings.forEach((w) => {
+                                    console.log(chalk.yellow(`  ⚠ ${w.message}`));
+                                });
+                            }
+                        }
+                    }
+                    else {
+                        console.log(chalk.red(`✗ ${result.file}`));
+                        result.issues.forEach((issue) => {
+                            const icon = issue.type === 'error' ? '✗' : '⚠';
+                            const color = issue.type === 'error' ? chalk.red : chalk.yellow;
+                            console.log(color(`  ${icon} ${issue.message}`));
+                            if (issue.suggestion) {
+                                console.log(chalk.dim(`    → ${issue.suggestion}`));
+                            }
+                        });
+                    }
+                }
+                // Summary
+                console.log('');
+                if (invalidCount === 0) {
+                    console.log(chalk.green(`✓ All ${validCount} file(s) are valid`));
+                }
+                else {
+                    console.log(chalk.red(`✗ ${invalidCount} of ${allResults.length} file(s) failed validation`));
+                    process.exit(1);
+                }
+            }
+        }
+        catch (error) {
+            console.error(chalk.red('Error:'), error.message);
+            process.exit(1);
+        }
+    });
+    return command;
+}