@principal-ai/principal-view-cli 0.1.19 → 0.1.21

package/dist/commands/validate.js

@@ -17,13 +17,13 @@ function loadLibrary(principalViewsDir) {
         if (existsSync(libraryPath)) {
             try {
                 const content = readFileSync(libraryPath, 'utf8');
-                const library = fileName.endsWith('.json')
-                    ? JSON.parse(content)
-                    : yaml.load(content);
+                const library = fileName.endsWith('.json') ? JSON.parse(content) : yaml.load(content);
                 if (library && typeof library === 'object') {
                     return {
-                        nodeComponents: library.nodeComponents || {},
-                        edgeComponents: library.edgeComponents || {},
+                        nodeComponents: library.nodeComponents ||
+                            {},
+                        edgeComponents: library.edgeComponents ||
+                            {},
                         raw: library,
                         path: libraryPath,
                     };
@@ -51,6 +51,8 @@ function validateLibrary(library) {
             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);
@@ -59,6 +61,9 @@ function validateLibrary(library) {
                     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);
                         }
                     }
                 }
@@ -121,6 +126,55 @@ const STANDARD_CANVAS_TYPES = ['text', 'group', 'file', 'link'];
  */
 const VALID_NODE_SHAPES = ['circle', 'rectangle', 'hexagon', 'diamond', 'custom'];
 // ============================================================================
+// 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
 // ============================================================================
 /**
@@ -129,12 +183,27 @@ const VALID_NODE_SHAPES = ['circle', 'rectangle', 'hexagon', 'diamond', 'custom'
 const ALLOWED_CANVAS_FIELDS = {
     root: ['nodes', 'edges', 'pv'],
     pv: ['version', 'name', 'description', 'nodeTypes', 'edgeTypes', 'pathConfig', 'display'],
-    pvPathConfig: ['projectRoot', 'captureSource', 'enableActionPatterns', 'logLevel', 'ignoreUnsourced'],
+    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'],
+    pvEdgeType: [
+        'label',
+        'style',
+        'color',
+        'width',
+        'directed',
+        'animation',
+        'labelConfig',
+        'activatedBy',
+    ],
     pvEdgeTypeAnimation: ['type', 'duration', 'color'],
     pvEdgeTypeLabelConfig: ['field', 'position'],
     // Base node fields from JSON Canvas spec
@@ -145,13 +214,36 @@ const ALLOWED_CANVAS_FIELDS = {
     nodeLink: ['url'],
     nodeGroup: ['label', 'background', 'backgroundStyle'],
     // Node pv extension
-    nodePv: ['nodeType', 'description', 'shape', 'icon', 'fill', 'stroke', 'states', 'sources', 'actions', 'dataSchema', 'layout'],
+    nodePv: [
+        'nodeType',
+        'description',
+        'shape',
+        'icon',
+        'fill',
+        'stroke',
+        'states',
+        'sources',
+        'actions',
+        'dataSchema',
+        'layout',
+    ],
     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'],
+    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'],
@@ -161,13 +253,35 @@ const ALLOWED_CANVAS_FIELDS = {
  */
 const ALLOWED_LIBRARY_FIELDS = {
     root: ['version', 'name', 'description', 'nodeComponents', 'edgeComponents', 'connectionRules'],
-    nodeComponent: ['description', 'tags', 'defaultLabel', 'shape', 'icon', 'color', 'size', 'states', 'sources', 'actions', 'dataSchema', 'layout'],
+    nodeComponent: [
+        'description',
+        'tags',
+        'defaultLabel',
+        'shape',
+        'icon',
+        'color',
+        'size',
+        'states',
+        'sources',
+        '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'],
+    edgeComponent: [
+        'description',
+        'tags',
+        'style',
+        'color',
+        'width',
+        'directed',
+        'animation',
+        'label',
+    ],
     edgeComponentAnimation: ['type', 'duration', 'color'],
     edgeComponentLabel: ['field', 'position'],
     connectionRule: ['from', 'to', 'via', 'constraints'],
@@ -293,6 +407,9 @@ function validateCanvas(canvas, filePath, library) {
             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);
                 }
             }
         }
@@ -323,7 +440,11 @@ function validateCanvas(canvas, filePath, library) {
     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}]` });
+                issues.push({
+                    type: 'error',
+                    message: `Node at index ${index} must be an object`,
+                    path: `nodes[${index}]`,
+                });
                 return;
             }
             const n = node;
@@ -347,23 +468,72 @@ function validateCanvas(canvas, filePath, library) {
             // 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` });
+                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` });
+                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` });
+                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` });
+                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` });
+                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` });
+                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 standard canvas type OR have pv metadata
             const isStandardType = STANDARD_CANVAS_TYPES.includes(nodeType);
@@ -386,7 +556,8 @@ function validateCanvas(canvas, filePath, library) {
                             path: `nodes[${index}].pv.nodeType`,
                         });
                     }
-                    if (typeof nodePv.shape !== 'string' || !VALID_NODE_SHAPES.includes(nodePv.shape)) {
+                    if (typeof nodePv.shape !== 'string' ||
+                        !VALID_NODE_SHAPES.includes(nodePv.shape)) {
                         issues.push({
                             type: 'error',
                             message: `Node "${n.id || index}" must have a valid "pv.shape"`,
@@ -401,11 +572,16 @@ function validateCanvas(canvas, filePath, library) {
                 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);
                         }
                     }
                 }
@@ -464,10 +640,14 @@ function validateCanvas(canvas, filePath, library) {
         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) || []);
+        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}]` });
+                issues.push({
+                    type: 'error',
+                    message: `Edge at index ${index} must be an object`,
+                    path: `edges[${index}]`,
+                });
                 return;
             }
             const e = edge;
@@ -476,19 +656,73 @@ function validateCanvas(canvas, filePath, library) {
             // 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` });
+                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` });
+                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` });
+                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` });
+                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` });
+                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 edge pv extension fields
             if (e.pv && typeof e.pv === 'object') {
@@ -558,7 +792,7 @@ function validateFile(filePath, library) {
         const content = readFileSync(absolutePath, 'utf8');
         const canvas = JSON.parse(content);
         const issues = validateCanvas(canvas, relativePath, library);
-        const hasErrors = issues.some(i => i.type === 'error');
+        const hasErrors = issues.some((i) => i.type === 'error');
         return {
             file: relativePath,
             isValid: !hasErrors,
@@ -607,7 +841,7 @@ export function createValidateCommand() {
             let libraryResult = null;
             if (library && Object.keys(library.raw).length > 0) {
                 const libraryIssues = validateLibrary(library);
-                const libraryHasErrors = libraryIssues.some(i => i.type === 'error');
+                const libraryHasErrors = libraryIssues.some((i) => i.type === 'error');
                 libraryResult = {
                     file: relative(process.cwd(), library.path),
                     isValid: !libraryHasErrors,
@@ -615,10 +849,10 @@ export function createValidateCommand() {
                 };
             }
             // Validate all canvas files
-            const results = matchedFiles.map(f => validateFile(f, library));
+            const results = matchedFiles.map((f) => validateFile(f, library));
             // Combine results
             const allResults = libraryResult ? [libraryResult, ...results] : results;
-            const validCount = allResults.filter(r => r.isValid).length;
+            const validCount = allResults.filter((r) => r.isValid).length;
             const invalidCount = allResults.length - validCount;
             // Output results
             if (options.json) {
@@ -629,16 +863,18 @@ export function createValidateCommand() {
             }
             else {
                 if (!options.quiet) {
-                    const fileCount = libraryResult ? `${results.length} canvas file(s) + library` : `${results.length} canvas file(s)`;
+                    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');
+                            const warnings = result.issues.filter((i) => i.type === 'warning');
                             if (warnings.length > 0) {
-                                warnings.forEach(w => {
+                                warnings.forEach((w) => {
                                     console.log(chalk.yellow(`  ⚠ ${w.message}`));
                                 });
                             }
@@ -646,7 +882,7 @@ export function createValidateCommand() {
                     }
                     else {
                         console.log(chalk.red(`✗ ${result.file}`));
-                        result.issues.forEach(issue => {
+                        result.issues.forEach((issue) => {
                             const icon = issue.type === 'error' ? '✗' : '⚠';
                             const color = issue.type === 'error' ? chalk.red : chalk.yellow;
                             console.log(color(`  ${icon} ${issue.message}`));