@principal-ai/subsystems-core 0.29.0 → 0.31.0

package/dist/dashboard/DashboardValidator.js

@@ -1,775 +0,0 @@
-"use strict";
-/**
- * Dashboard File Validator
- *
- * Validates dashboard definition files (.dashboard.json) that define metrics,
- * layout, and data sources for observability dashboards.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createDashboardValidator = exports.DashboardValidator = void 0;
-// Valid metric types
-const VALID_METRIC_TYPES = ['counter', 'gauge', 'histogram'];
-// Valid derivations
-const VALID_DERIVATIONS = [
-    'count',
-    'rate',
-    'sum',
-    'avg',
-    'min',
-    'max',
-    'duration',
-    'error_rate',
-    'success_rate',
-    'percentage',
-    'p50',
-    'p95',
-    'p99',
-];
-// Valid time groups
-const VALID_TIME_GROUPS = ['minute', 'hour', 'day', 'week', 'month'];
-// Valid display components
-const VALID_DISPLAY_COMPONENTS = [
-    'MetricCard',
-    'LineChart',
-    'BarChart',
-    'StackedBarChart',
-    'PieChart',
-    'GaugeChart',
-    'Histogram',
-    'DataTable',
-];
-/**
- * Validator for dashboard definition files
- */
-class DashboardValidator {
-    /**
-     * Validate dashboard definition structure
-     */
-    validate(data, filePath, context) {
-        const errors = [];
-        const warnings = [];
-        // Check if data is an object
-        if (!data || typeof data !== 'object') {
-            errors.push({
-                path: filePath || 'root',
-                message: 'Dashboard data must be an object',
-                severity: 'error',
-                suggestion: 'Expected format: { "id": "...", "name": "...", "metrics": [...], "layout": {...} }',
-            });
-            return { valid: false, errors, warnings };
-        }
-        // Check if it's an array (common mistake)
-        if (Array.isArray(data)) {
-            errors.push({
-                path: filePath || 'root',
-                message: 'Dashboard data should be an object, not an array',
-                severity: 'error',
-            });
-            return { valid: false, errors, warnings };
-        }
-        const dashboard = data;
-        // Validate required fields
-        if (!dashboard.id) {
-            errors.push({
-                path: 'id',
-                message: 'Missing required "id" field',
-                severity: 'error',
-                suggestion: 'Add a unique kebab-case identifier, e.g., "service-health"',
-            });
-        }
-        else if (typeof dashboard.id !== 'string') {
-            errors.push({
-                path: 'id',
-                message: '"id" must be a string',
-                severity: 'error',
-            });
-        }
-        else if (!/^[a-z0-9-]+$/.test(dashboard.id)) {
-            warnings.push({
-                path: 'id',
-                message: 'Dashboard "id" should be kebab-case (lowercase with hyphens)',
-                severity: 'warning',
-                suggestion: `Consider renaming to "${dashboard.id.toLowerCase().replace(/[^a-z0-9]+/g, '-')}"`,
-            });
-        }
-        if (!dashboard.name) {
-            errors.push({
-                path: 'name',
-                message: 'Missing required "name" field',
-                severity: 'error',
-                suggestion: 'Add a human-readable name, e.g., "Service Health Dashboard"',
-            });
-        }
-        else if (typeof dashboard.name !== 'string') {
-            errors.push({
-                path: 'name',
-                message: '"name" must be a string',
-                severity: 'error',
-            });
-        }
-        // Validate optional description
-        if (dashboard.description !== undefined && typeof dashboard.description !== 'string') {
-            errors.push({
-                path: 'description',
-                message: '"description" must be a string',
-                severity: 'error',
-            });
-        }
-        // Validate metrics array
-        if (!dashboard.metrics) {
-            errors.push({
-                path: 'metrics',
-                message: 'Missing required "metrics" array',
-                severity: 'error',
-                suggestion: 'Add at least one metric definition',
-            });
-        }
-        else if (!Array.isArray(dashboard.metrics)) {
-            errors.push({
-                path: 'metrics',
-                message: '"metrics" must be an array',
-                severity: 'error',
-            });
-        }
-        else if (dashboard.metrics.length === 0) {
-            warnings.push({
-                path: 'metrics',
-                message: 'Dashboard has no metrics defined',
-                severity: 'warning',
-                suggestion: 'Add at least one metric to make the dashboard useful',
-            });
-        }
-        else {
-            // Validate each metric
-            const metricIds = new Set();
-            dashboard.metrics.forEach((metric, index) => {
-                this.validateMetric(metric, index, errors, warnings, context);
-                // Check for duplicate metric IDs
-                if (metric.id) {
-                    if (metricIds.has(metric.id)) {
-                        errors.push({
-                            path: `metrics[${index}].id`,
-                            message: `Duplicate metric ID: "${metric.id}"`,
-                            severity: 'error',
-                            suggestion: 'Each metric must have a unique ID',
-                        });
-                    }
-                    metricIds.add(metric.id);
-                }
-            });
-        }
-        // Validate layout
-        if (!dashboard.layout) {
-            errors.push({
-                path: 'layout',
-                message: 'Missing required "layout" object',
-                severity: 'error',
-                suggestion: 'Add layout with columns and rows',
-            });
-        }
-        else if (typeof dashboard.layout !== 'object' || Array.isArray(dashboard.layout)) {
-            errors.push({
-                path: 'layout',
-                message: '"layout" must be an object',
-                severity: 'error',
-            });
-        }
-        else {
-            // Get metric IDs for panel validation
-            const metricIds = new Set((dashboard.metrics || [])
-                .filter((m) => !!m && typeof m === 'object' && !!m.id)
-                .map((m) => m.id));
-            this.validateLayout(dashboard.layout, errors, warnings, metricIds);
-        }
-        return {
-            valid: errors.length === 0,
-            errors,
-            warnings,
-        };
-    }
-    /**
-     * Validate a single metric definition
-     */
-    validateMetric(metric, index, errors, warnings, context) {
-        const metricPath = `metrics[${index}]`;
-        if (!metric || typeof metric !== 'object') {
-            errors.push({
-                path: metricPath,
-                message: 'Metric must be an object',
-                severity: 'error',
-            });
-            return;
-        }
-        const m = metric;
-        // Required: id
-        if (!m.id) {
-            errors.push({
-                path: `${metricPath}.id`,
-                message: 'Metric is missing required "id" field',
-                severity: 'error',
-                suggestion: `Add unique ID like "metric-${index + 1}"`,
-            });
-        }
-        else if (typeof m.id !== 'string') {
-            errors.push({
-                path: `${metricPath}.id`,
-                message: 'Metric "id" must be a string',
-                severity: 'error',
-            });
-        }
-        else if (!/^[a-z0-9-]+$/.test(m.id)) {
-            warnings.push({
-                path: `${metricPath}.id`,
-                message: 'Metric "id" should be kebab-case',
-                severity: 'warning',
-            });
-        }
-        // Required: name
-        if (!m.name) {
-            errors.push({
-                path: `${metricPath}.name`,
-                message: 'Metric is missing required "name" field',
-                severity: 'error',
-            });
-        }
-        else if (typeof m.name !== 'string') {
-            errors.push({
-                path: `${metricPath}.name`,
-                message: 'Metric "name" must be a string',
-                severity: 'error',
-            });
-        }
-        // Required: type
-        if (!m.type) {
-            errors.push({
-                path: `${metricPath}.type`,
-                message: 'Metric is missing required "type" field',
-                severity: 'error',
-                suggestion: `Valid types: ${VALID_METRIC_TYPES.join(', ')}`,
-            });
-        }
-        else if (!VALID_METRIC_TYPES.includes(m.type)) {
-            errors.push({
-                path: `${metricPath}.type`,
-                message: `Invalid metric type: "${m.type}"`,
-                severity: 'error',
-                suggestion: `Valid types: ${VALID_METRIC_TYPES.join(', ')}`,
-            });
-        }
-        // Required: sources
-        if (!m.sources) {
-            errors.push({
-                path: `${metricPath}.sources`,
-                message: 'Metric is missing required "sources" array',
-                severity: 'error',
-                suggestion: 'Add at least one source linking to a storyboard/workflow',
-            });
-        }
-        else if (!Array.isArray(m.sources)) {
-            errors.push({
-                path: `${metricPath}.sources`,
-                message: 'Metric "sources" must be an array',
-                severity: 'error',
-            });
-        }
-        else if (m.sources.length === 0) {
-            errors.push({
-                path: `${metricPath}.sources`,
-                message: 'Metric must have at least one source',
-                severity: 'error',
-            });
-        }
-        else {
-            m.sources.forEach((source, sourceIndex) => {
-                this.validateSource(source, `${metricPath}.sources[${sourceIndex}]`, errors, warnings, context);
-            });
-        }
-        // Required: query
-        if (!m.query) {
-            errors.push({
-                path: `${metricPath}.query`,
-                message: 'Metric is missing required "query" object',
-                severity: 'error',
-            });
-        }
-        else if (typeof m.query !== 'object' || Array.isArray(m.query)) {
-            errors.push({
-                path: `${metricPath}.query`,
-                message: 'Metric "query" must be an object',
-                severity: 'error',
-            });
-        }
-        else {
-            this.validateQuery(m.query, `${metricPath}.query`, errors, warnings);
-        }
-        // Optional: thresholds
-        if (m.thresholds !== undefined) {
-            if (typeof m.thresholds !== 'object' || Array.isArray(m.thresholds)) {
-                errors.push({
-                    path: `${metricPath}.thresholds`,
-                    message: '"thresholds" must be an object',
-                    severity: 'error',
-                });
-            }
-            else {
-                if (m.thresholds.warning !== undefined && typeof m.thresholds.warning !== 'number') {
-                    errors.push({
-                        path: `${metricPath}.thresholds.warning`,
-                        message: 'Threshold "warning" must be a number',
-                        severity: 'error',
-                    });
-                }
-                if (m.thresholds.critical !== undefined && typeof m.thresholds.critical !== 'number') {
-                    errors.push({
-                        path: `${metricPath}.thresholds.critical`,
-                        message: 'Threshold "critical" must be a number',
-                        severity: 'error',
-                    });
-                }
-            }
-        }
-        // Optional: display
-        if (m.display !== undefined) {
-            this.validateDisplay(m.display, `${metricPath}.display`, errors, warnings);
-        }
-        // Check for _mockData (informational)
-        if (!m._mockData) {
-            warnings.push({
-                path: `${metricPath}._mockData`,
-                message: 'No mock data provided for prototyping',
-                severity: 'warning',
-                suggestion: 'Add _mockData to prototype the dashboard before live OTEL data',
-            });
-        }
-    }
-    /**
-     * Validate a metric source
-     */
-    validateSource(source, path, errors, warnings, context) {
-        if (!source || typeof source !== 'object') {
-            errors.push({
-                path,
-                message: 'Source must be an object',
-                severity: 'error',
-            });
-            return;
-        }
-        const s = source;
-        // Required: storyboard
-        if (!s.storyboard) {
-            errors.push({
-                path: `${path}.storyboard`,
-                message: 'Source is missing required "storyboard" field',
-                severity: 'error',
-            });
-        }
-        else if (typeof s.storyboard !== 'string') {
-            errors.push({
-                path: `${path}.storyboard`,
-                message: 'Source "storyboard" must be a string',
-                severity: 'error',
-            });
-        }
-        else if (context?.storyboards && !context.storyboards.includes(s.storyboard)) {
-            errors.push({
-                path: `${path}.storyboard`,
-                message: `Unknown storyboard: "${s.storyboard}"`,
-                severity: 'error',
-                suggestion: `Known storyboards: ${context.storyboards.join(', ')}`,
-            });
-        }
-        // Required: workflow
-        if (!s.workflow) {
-            errors.push({
-                path: `${path}.workflow`,
-                message: 'Source is missing required "workflow" field',
-                severity: 'error',
-            });
-        }
-        else if (typeof s.workflow !== 'string') {
-            errors.push({
-                path: `${path}.workflow`,
-                message: 'Source "workflow" must be a string',
-                severity: 'error',
-            });
-        }
-        else if (context?.workflows &&
-            s.storyboard &&
-            context.workflows[s.storyboard] &&
-            !context.workflows[s.storyboard].includes(s.workflow)) {
-            errors.push({
-                path: `${path}.workflow`,
-                message: `Unknown workflow "${s.workflow}" in storyboard "${s.storyboard}"`,
-                severity: 'error',
-                suggestion: context.workflows[s.storyboard].length > 0
-                    ? `Known workflows in "${s.storyboard}": ${context.workflows[s.storyboard].join(', ')}`
-                    : `No workflows found in storyboard "${s.storyboard}"`,
-            });
-        }
-        // Optional: type
-        if (s.type !== undefined && s.type !== 'event' && s.type !== 'span') {
-            errors.push({
-                path: `${path}.type`,
-                message: 'Source "type" must be "event" or "span"',
-                severity: 'error',
-            });
-        }
-        // Optional: nodes
-        if (s.nodes !== undefined) {
-            if (!Array.isArray(s.nodes)) {
-                errors.push({
-                    path: `${path}.nodes`,
-                    message: 'Source "nodes" must be an array of strings',
-                    severity: 'error',
-                });
-            }
-            else {
-                s.nodes.forEach((node, i) => {
-                    if (typeof node !== 'string') {
-                        errors.push({
-                            path: `${path}.nodes[${i}]`,
-                            message: 'Node must be a string',
-                            severity: 'error',
-                        });
-                    }
-                });
-            }
-        }
-        // Optional: event
-        if (s.event !== undefined && typeof s.event !== 'string') {
-            errors.push({
-                path: `${path}.event`,
-                message: 'Source "event" must be a string',
-                severity: 'error',
-            });
-        }
-    }
-    /**
-     * Validate a metric query
-     */
-    validateQuery(query, path, errors, warnings) {
-        const q = query;
-        // Required: derivation
-        if (!q.derivation) {
-            errors.push({
-                path: `${path}.derivation`,
-                message: 'Query is missing required "derivation" field',
-                severity: 'error',
-                suggestion: `Valid derivations: ${VALID_DERIVATIONS.join(', ')}`,
-            });
-        }
-        else if (!VALID_DERIVATIONS.includes(q.derivation)) {
-            errors.push({
-                path: `${path}.derivation`,
-                message: `Invalid derivation: "${q.derivation}"`,
-                severity: 'error',
-                suggestion: `Valid derivations: ${VALID_DERIVATIONS.join(', ')}`,
-            });
-        }
-        // Optional: timeGroup
-        if (q.timeGroup !== undefined && !VALID_TIME_GROUPS.includes(q.timeGroup)) {
-            errors.push({
-                path: `${path}.timeGroup`,
-                message: `Invalid timeGroup: "${q.timeGroup}"`,
-                severity: 'error',
-                suggestion: `Valid time groups: ${VALID_TIME_GROUPS.join(', ')}`,
-            });
-        }
-        // Optional: groupBy
-        if (q.groupBy !== undefined) {
-            if (!Array.isArray(q.groupBy)) {
-                errors.push({
-                    path: `${path}.groupBy`,
-                    message: '"groupBy" must be an array of strings',
-                    severity: 'error',
-                });
-            }
-            else {
-                q.groupBy.forEach((field, i) => {
-                    if (typeof field !== 'string') {
-                        errors.push({
-                            path: `${path}.groupBy[${i}]`,
-                            message: 'groupBy field must be a string',
-                            severity: 'error',
-                        });
-                    }
-                });
-            }
-        }
-        // Optional: window
-        if (q.window !== undefined && typeof q.window !== 'string') {
-            errors.push({
-                path: `${path}.window`,
-                message: '"window" must be a string (e.g., "1h", "24h")',
-                severity: 'error',
-            });
-        }
-    }
-    /**
-     * Validate metric display options
-     */
-    validateDisplay(display, path, errors, warnings) {
-        if (typeof display !== 'object' || Array.isArray(display)) {
-            errors.push({
-                path,
-                message: '"display" must be an object',
-                severity: 'error',
-            });
-            return;
-        }
-        const d = display;
-        // Optional: component
-        if (d.component !== undefined && !VALID_DISPLAY_COMPONENTS.includes(d.component)) {
-            errors.push({
-                path: `${path}.component`,
-                message: `Invalid display component: "${d.component}"`,
-                severity: 'error',
-                suggestion: `Valid components: ${VALID_DISPLAY_COMPONENTS.join(', ')}`,
-            });
-        }
-        // Optional: size
-        if (d.size !== undefined && !['small', 'medium', 'large'].includes(d.size)) {
-            errors.push({
-                path: `${path}.size`,
-                message: `Invalid size: "${d.size}"`,
-                severity: 'error',
-                suggestion: 'Valid sizes: small, medium, large',
-            });
-        }
-    }
-    /**
-     * Validate dashboard layout
-     */
-    validateLayout(layout, errors, warnings, metricIds) {
-        const l = layout;
-        // Optional: columns
-        if (l.columns !== undefined) {
-            if (typeof l.columns !== 'number' || l.columns < 1) {
-                errors.push({
-                    path: 'layout.columns',
-                    message: '"columns" must be a positive number',
-                    severity: 'error',
-                });
-            }
-        }
-        // Required: rows
-        if (!l.rows) {
-            errors.push({
-                path: 'layout.rows',
-                message: 'Layout is missing required "rows" array',
-                severity: 'error',
-            });
-        }
-        else if (!Array.isArray(l.rows)) {
-            errors.push({
-                path: 'layout.rows',
-                message: '"rows" must be an array',
-                severity: 'error',
-            });
-        }
-        else if (l.rows.length === 0) {
-            warnings.push({
-                path: 'layout.rows',
-                message: 'Layout has no rows defined',
-                severity: 'warning',
-            });
-        }
-        else {
-            const referencedMetricIds = new Set();
-            l.rows.forEach((row, rowIndex) => {
-                this.validateRow(row, rowIndex, errors, warnings, metricIds, referencedMetricIds);
-            });
-            // Check for orphaned metrics (defined but not in layout)
-            metricIds.forEach((id) => {
-                if (!referencedMetricIds.has(id)) {
-                    warnings.push({
-                        path: `layout`,
-                        message: `Metric "${id}" is defined but not placed in any layout row`,
-                        severity: 'warning',
-                        suggestion: 'Add a panel referencing this metric or remove the metric definition',
-                    });
-                }
-            });
-        }
-    }
-    /**
-     * Validate a layout row
-     */
-    validateRow(row, rowIndex, errors, warnings, metricIds, referencedMetricIds) {
-        const rowPath = `layout.rows[${rowIndex}]`;
-        if (!row || typeof row !== 'object') {
-            errors.push({
-                path: rowPath,
-                message: 'Row must be an object',
-                severity: 'error',
-            });
-            return;
-        }
-        const r = row;
-        // Optional: title
-        if (r.title !== undefined && typeof r.title !== 'string') {
-            errors.push({
-                path: `${rowPath}.title`,
-                message: 'Row "title" must be a string',
-                severity: 'error',
-            });
-        }
-        // Required: panels
-        if (!r.panels) {
-            errors.push({
-                path: `${rowPath}.panels`,
-                message: 'Row is missing required "panels" array',
-                severity: 'error',
-            });
-        }
-        else if (!Array.isArray(r.panels)) {
-            errors.push({
-                path: `${rowPath}.panels`,
-                message: '"panels" must be an array',
-                severity: 'error',
-            });
-        }
-        else if (r.panels.length === 0) {
-            warnings.push({
-                path: `${rowPath}.panels`,
-                message: 'Row has no panels',
-                severity: 'warning',
-            });
-        }
-        else {
-            r.panels.forEach((panel, panelIndex) => {
-                this.validatePanel(panel, `${rowPath}.panels[${panelIndex}]`, errors, warnings, metricIds, referencedMetricIds);
-            });
-        }
-    }
-    /**
-     * Validate a panel placement
-     */
-    validatePanel(panel, path, errors, warnings, metricIds, referencedMetricIds) {
-        if (!panel || typeof panel !== 'object') {
-            errors.push({
-                path,
-                message: 'Panel must be an object',
-                severity: 'error',
-            });
-            return;
-        }
-        const p = panel;
-        // Required: id
-        if (!p.id) {
-            errors.push({
-                path: `${path}.id`,
-                message: 'Panel is missing required "id" field',
-                severity: 'error',
-                suggestion: 'Reference a metric ID defined in the metrics array',
-            });
-        }
-        else if (typeof p.id !== 'string') {
-            errors.push({
-                path: `${path}.id`,
-                message: 'Panel "id" must be a string',
-                severity: 'error',
-            });
-        }
-        else {
-            referencedMetricIds.add(p.id);
-            if (!metricIds.has(p.id)) {
-                errors.push({
-                    path: `${path}.id`,
-                    message: `Panel references unknown metric: "${p.id}"`,
-                    severity: 'error',
-                    suggestion: `Available metrics: ${Array.from(metricIds).join(', ') || '(none defined)'}`,
-                });
-            }
-        }
-        // Optional: span
-        if (p.span !== undefined) {
-            if (typeof p.span !== 'number' || p.span < 1) {
-                errors.push({
-                    path: `${path}.span`,
-                    message: '"span" must be a positive number',
-                    severity: 'error',
-                });
-            }
-        }
-        // Optional: spanMobile
-        if (p.spanMobile !== undefined) {
-            if (typeof p.spanMobile !== 'number' || p.spanMobile < 1) {
-                errors.push({
-                    path: `${path}.spanMobile`,
-                    message: '"spanMobile" must be a positive number',
-                    severity: 'error',
-                });
-            }
-        }
-        else if (p.span !== undefined) {
-            warnings.push({
-                path: `${path}`,
-                message: 'Panel has span but no spanMobile for responsive layout',
-                severity: 'warning',
-                suggestion: 'Add spanMobile: 12 for full-width on mobile',
-            });
-        }
-        // Optional: minHeight
-        if (p.minHeight !== undefined && typeof p.minHeight !== 'number') {
-            errors.push({
-                path: `${path}.minHeight`,
-                message: '"minHeight" must be a number',
-                severity: 'error',
-            });
-        }
-    }
-    /**
-     * Validate and throw if invalid
-     */
-    validateOrThrow(data, filePath, context) {
-        const result = this.validate(data, filePath, context);
-        if (!result.valid) {
-            const errorMessages = result.errors.map((e) => `${e.path}: ${e.message}${e.suggestion ? ` (${e.suggestion})` : ''}`);
-            throw new Error(`Invalid dashboard data:\n${errorMessages.join('\n')}`);
-        }
-        return data;
-    }
-    /**
-     * Format validation result as human-readable report
-     */
-    formatReport(result) {
-        const lines = [];
-        if (result.valid && result.warnings.length === 0) {
-            lines.push('✓ Dashboard definition is valid');
-            return lines.join('\n');
-        }
-        if (result.errors.length > 0) {
-            lines.push('Validation errors:\n');
-            result.errors.forEach((error) => {
-                lines.push(`  ${error.path}`);
-                lines.push(`    ${error.message}`);
-                if (error.suggestion) {
-                    lines.push(`    → ${error.suggestion}`);
-                }
-                lines.push('');
-            });
-        }
-        if (result.warnings.length > 0) {
-            lines.push('Warnings:\n');
-            result.warnings.forEach((warning) => {
-                lines.push(`  ${warning.path}`);
-                lines.push(`    ${warning.message}`);
-                if (warning.suggestion) {
-                    lines.push(`    → ${warning.suggestion}`);
-                }
-                lines.push('');
-            });
-        }
-        return lines.join('\n');
-    }
-}
-exports.DashboardValidator = DashboardValidator;
-/**
- * Create a new dashboard validator instance
- */
-function createDashboardValidator() {
-    return new DashboardValidator();
-}
-exports.createDashboardValidator = createDashboardValidator;
-//# sourceMappingURL=DashboardValidator.js.map