@aws/ml-container-creator 0.2.5 → 0.2.6

package/src/lib/validation-report.js

@@ -0,0 +1,133 @@
+/**
+ * Structured validation report that categorizes findings by severity and source.
+ * Supports text (color-coded) and JSON output formats.
+ *
+ * Requirements: 11.1, 11.2, 11.3, 11.4, 11.5
+ */
+export default class ValidationReport {
+    constructor() {
+        this.schemaErrors = [];
+        this.crossCuttingErrors = [];
+        this.advisoryFindings = [];
+        this.warnings = [];
+        this.metadata = {};
+    }
+
+    /**
+     * Add a finding to the appropriate category based on finding.source.
+     * Smart-mode findings are labeled advisory unless confidence is 'definitive' and severity is 'error'.
+     * @param {Object} finding - A Finding object with source, severity, confidence, etc.
+     */
+    addFinding(finding) {
+        const source = finding.source || '';
+
+        if (source === 'cross-cutting') {
+            this.crossCuttingErrors.push(finding);
+        } else if (source === 'smart-mode' || source.startsWith('smart:')) {
+            // Smart-mode findings are advisory UNLESS confidence is definitive AND severity is error
+            if (finding.confidence === 'definitive' && finding.severity === 'error') {
+                this.schemaErrors.push(finding);
+            } else {
+                this.advisoryFindings.push(finding);
+            }
+        } else if (finding.confidence === 'medium' || finding.confidence === 'low') {
+            this.advisoryFindings.push(finding);
+        } else if (finding.severity === 'warning') {
+            this.warnings.push(finding);
+        } else {
+            this.schemaErrors.push(finding);
+        }
+    }
+
+    /**
+     * Render report as formatted text with color-coded severity grouping by operation.
+     * @returns {string}
+     */
+    toText() {
+        const lines = [];
+
+        const groupByOperation = (findings) => {
+            const groups = {};
+            for (const f of findings) {
+                const key = f.operation || 'general';
+                if (!groups[key]) groups[key] = [];
+                groups[key].push(f);
+            }
+            return groups;
+        };
+
+        if (this.schemaErrors.length > 0) {
+            lines.push('\x1b[31m── Schema Errors ──\x1b[0m');
+            const groups = groupByOperation(this.schemaErrors);
+            for (const [op, findings] of Object.entries(groups)) {
+                lines.push(`  ${op}:`);
+                for (const f of findings) {
+                    lines.push(`    \x1b[31m✗\x1b[0m ${f.fieldPath}: ${f.invalidValue} (${f.remediationHint || ''})`);
+                }
+            }
+        }
+
+        if (this.crossCuttingErrors.length > 0) {
+            lines.push('\x1b[31m── Cross-Cutting Errors ──\x1b[0m');
+            const groups = groupByOperation(this.crossCuttingErrors);
+            for (const [op, findings] of Object.entries(groups)) {
+                lines.push(`  ${op}:`);
+                for (const f of findings) {
+                    lines.push(`    \x1b[31m✗\x1b[0m ${f.fieldPath}: ${f.remediationHint || ''}`);
+                }
+            }
+        }
+
+        if (this.advisoryFindings.length > 0) {
+            lines.push('\x1b[36m── Advisory Findings ──\x1b[0m');
+            const groups = groupByOperation(this.advisoryFindings);
+            for (const [op, findings] of Object.entries(groups)) {
+                lines.push(`  ${op}:`);
+                for (const f of findings) {
+                    lines.push(`    \x1b[36mℹ\x1b[0m ${f.fieldPath}: ${f.remediationHint || ''}`);
+                }
+            }
+        }
+
+        if (this.warnings.length > 0) {
+            lines.push('\x1b[33m── Warnings ──\x1b[0m');
+            for (const f of this.warnings) {
+                lines.push(`  \x1b[33m⚠\x1b[0m ${f.fieldPath || f.operation || ''}: ${f.remediationHint || ''}`);
+            }
+        }
+
+        const summary = this.getSummary();
+        lines.push('');
+        lines.push(`Summary: ${summary.errors} error(s), ${summary.warnings} warning(s), ${summary.advisory} advisory, ${summary.fieldsValidated} fields validated`);
+
+        return lines.join('\n');
+    }
+
+    /**
+     * Render report as JSON with full structured object.
+     * @returns {Object}
+     */
+    toJSON() {
+        return {
+            schemaErrors: this.schemaErrors,
+            crossCuttingErrors: this.crossCuttingErrors,
+            advisoryFindings: this.advisoryFindings,
+            warnings: this.warnings,
+            metadata: this.metadata,
+            summary: this.getSummary()
+        };
+    }
+
+    /**
+     * Get summary counts.
+     * @returns {{ errors: number, warnings: number, advisory: number, fieldsValidated: number }}
+     */
+    getSummary() {
+        return {
+            errors: this.schemaErrors.length + this.crossCuttingErrors.length,
+            warnings: this.warnings.length,
+            advisory: this.advisoryFindings.length,
+            fieldsValidated: this.metadata.fieldsValidated || 0
+        };
+    }
+}

package/src/lib/validators/base-validator.js

@@ -0,0 +1,36 @@
+/**
+ * Base class for all validation plugins.
+ * Custom validators extend this class and implement the validate method.
+ *
+ * Requirements: 12.1, 12.3, 12.6
+ */
+export default class BaseValidator {
+    /**
+     * Plugin name for source attribution in findings.
+     * @type {string}
+     */
+    get name() {
+        return 'base';
+    }
+
+    /**
+     * When this validator runs: 'static', 'smart', or 'both'.
+     * Static-only plugins run always; smart-only plugins run only when --smart is passed.
+     * @type {'static'|'smart'|'both'}
+     */
+    get mode() {
+        return 'static';
+    }
+
+    /**
+     * Validate the context and return findings.
+     * @param {Object} context - Full validation context (ValidationContext)
+     * @param {Object} options
+     * @param {Array} options.priorFindings - Findings from earlier validators
+     * @param {Array} options.serviceModels - Parsed service models
+     * @returns {Promise<Array>} Array of Finding objects
+     */
+    async validate(_context, _options) {
+        return [];
+    }
+}

package/src/lib/validators/catalog-validator.js

@@ -0,0 +1,177 @@
+/**
+ * Catalog enum validator.
+ * Validates that catalog entries (e.g., model-servers.json) contain valid
+ * enum values according to the AWS service model.
+ *
+ * Unlike other validators that check API payloads, this validator reads
+ * catalog files and validates their fields against the service model enums.
+ *
+ * Requirements: 14.1, 14.2, 14.3
+ */
+import BaseValidator from './base-validator.js';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const DEFAULT_CATALOG_PATH = resolve(__dirname, '../../../servers/lib/catalogs/model-servers.json');
+
+/**
+ * Map of catalog field names to their corresponding SageMaker service model shape names.
+ */
+const CATALOG_ENUM_FIELDS = [
+    { field: 'inferenceAmiVersion', shapeName: 'InferenceAmiVersion' }
+];
+
+export default class CatalogValidator extends BaseValidator {
+    get name() {
+        return 'catalog';
+    }
+
+    get mode() {
+        return 'static';
+    }
+
+    /**
+     * Validate catalog enum fields against the service model.
+     * @param {Object} context - ValidationContext (may be empty for catalog-only validation)
+     * @param {Object} options
+     * @param {Array} options.serviceModels - Parsed ServiceModelIndex objects
+     * @param {string} [options.catalogPath] - Path to model-servers.json (defaults to well-known location)
+     * @param {Object} [options.catalogData] - Pre-loaded catalog data (for testing)
+     * @returns {Promise<Array>} Array of Finding objects
+     */
+    async validate(context, options) {
+        const findings = [];
+        const serviceModels = options.serviceModels || [];
+
+        if (serviceModels.length === 0) {
+            return findings;
+        }
+
+        // Load catalog data
+        let catalogData;
+        let catalogFilePath;
+
+        if (options.catalogData) {
+            catalogData = options.catalogData;
+            catalogFilePath = options.catalogPath || 'servers/lib/catalogs/model-servers.json';
+        } else {
+            catalogFilePath = options.catalogPath || DEFAULT_CATALOG_PATH;
+
+            if (!existsSync(catalogFilePath)) {
+                return findings;
+            }
+
+            try {
+                catalogData = JSON.parse(readFileSync(catalogFilePath, 'utf8'));
+            } catch {
+                return findings;
+            }
+        }
+
+        // Build enum lookup from service models
+        const enumMap = this._buildEnumMap(serviceModels);
+
+        // Validate each server group and its entries
+        for (const [serverKey, entries] of Object.entries(catalogData)) {
+            if (!Array.isArray(entries)) continue;
+
+            for (let i = 0; i < entries.length; i++) {
+                const entry = entries[i];
+                const entryKey = `${serverKey}[${i}]`;
+                const entryLabel = entry.tag || entry.image || `index ${i}`;
+
+                this._validateEntry(
+                    entry, entryKey, entryLabel, catalogFilePath, enumMap, findings
+                );
+            }
+        }
+
+        return findings;
+    }
+
+    /**
+     * Build a map of field names to their valid enum values from service models.
+     * @param {Array} serviceModels - Parsed ServiceModelIndex objects
+     * @returns {Map<string, string[]>} field name → valid enum values
+     */
+    _buildEnumMap(serviceModels) {
+        const enumMap = new Map();
+
+        for (const { field, shapeName } of CATALOG_ENUM_FIELDS) {
+            for (const model of serviceModels) {
+                const shape = model.shapes.get(shapeName);
+                if (shape && shape.enum && shape.enum.length > 0) {
+                    enumMap.set(field, [...shape.enum]);
+                    break;
+                }
+            }
+        }
+
+        return enumMap;
+    }
+
+    /**
+     * Validate a single catalog entry's enum fields.
+     * @param {Object} entry - Catalog entry object
+     * @param {string} entryKey - Key identifying the entry (e.g., "vllm[0]")
+     * @param {string} entryLabel - Human-readable label for the entry
+     * @param {string} catalogFilePath - Path to the catalog file
+     * @param {Map<string, string[]>} enumMap - field name → valid enum values
+     * @param {Array} findings - Accumulator for findings
+     */
+    _validateEntry(entry, entryKey, entryLabel, catalogFilePath, enumMap, findings) {
+        // Check top-level fields
+        for (const [field, validValues] of enumMap) {
+            if (entry[field] !== undefined) {
+                this._checkEnumValue(
+                    entry[field], field, entryKey, catalogFilePath, validValues, findings
+                );
+            }
+        }
+
+        // Check nested defaults object
+        if (entry.defaults && typeof entry.defaults === 'object') {
+            for (const [field, validValues] of enumMap) {
+                if (entry.defaults[field] !== undefined) {
+                    this._checkEnumValue(
+                        entry.defaults[field], field, entryKey, catalogFilePath, validValues, findings
+                    );
+                }
+            }
+        }
+    }
+
+    /**
+     * Check a single enum value and add a finding if invalid.
+     * @param {string} value - The value to check
+     * @param {string} fieldName - The field name
+     * @param {string} entryKey - The entry key (e.g., "vllm[0]")
+     * @param {string} catalogFilePath - Path to the catalog file
+     * @param {string[]} validValues - Array of valid enum values
+     * @param {Array} findings - Accumulator for findings
+     */
+    _checkEnumValue(value, fieldName, entryKey, catalogFilePath, validValues, findings) {
+        if (typeof value !== 'string') return;
+
+        if (!validValues.includes(value)) {
+            findings.push({
+                service: 'sagemaker',
+                operation: 'catalog-validation',
+                fieldPath: `${entryKey}.${fieldName}`,
+                invalidValue: value,
+                constraint: { type: 'enum', values: validValues },
+                severity: 'error',
+                confidence: 'definitive',
+                source: this.name,
+                catalogFile: catalogFilePath,
+                entryKey,
+                fieldName,
+                remediationHint: `Value "${value}" is not a valid ${fieldName}. Allowed values: ${validValues.join(', ')}. Run \`bootstrap sync-schemas\` to update the enum set.`
+            });
+        }
+    }
+}

package/src/lib/validators/enum-validator.js

@@ -0,0 +1,120 @@
+/**
+ * Enum constraint validator.
+ * Validates that payload field values are within the allowed enum set
+ * defined in the AWS service model.
+ *
+ * Requirements: 4.1, 4.2, 4.3, 4.5
+ */
+import BaseValidator from './base-validator.js';
+
+export default class EnumValidator extends BaseValidator {
+    get name() {
+        return 'enum';
+    }
+
+    get mode() {
+        return 'static';
+    }
+
+    /**
+     * Validate enum constraints for all payload fields.
+     * @param {Object} context - ValidationContext from PayloadBuilder
+     * @param {Object} options
+     * @param {Array} options.serviceModels - Parsed ServiceModelIndex objects
+     * @param {Array} options.priorFindings - Findings from earlier validators
+     * @returns {Promise<Array>} Array of Finding objects
+     */
+    async validate(context, options) {
+        const findings = [];
+        const serviceModels = options.serviceModels || [];
+
+        for (const [operationKey, payload] of Object.entries(context.payloads || {})) {
+            const [service, operation] = operationKey.split(':');
+
+            for (const model of serviceModels) {
+                const op = model.operations.get(operation);
+                if (!op || !op.input) continue;
+
+                const inputShape = model.shapes.get(op.input);
+                if (!inputShape || inputShape.type !== 'structure') continue;
+
+                this._validateStructure(
+                    payload, inputShape, model, service, operation, '', findings
+                );
+            }
+        }
+
+        return findings;
+    }
+
+    /**
+     * Recursively validate enum constraints in a structure.
+     * @param {Object} payload - The payload object to validate
+     * @param {Object} shape - The structure shape definition
+     * @param {Object} model - The ServiceModelIndex
+     * @param {string} service - Service name
+     * @param {string} operation - Operation name
+     * @param {string} parentPath - Dot-notation path prefix
+     * @param {Array} findings - Accumulator for findings
+     */
+    _validateStructure(payload, shape, model, service, operation, parentPath, findings) {
+        if (!payload || typeof payload !== 'object' || !shape.members) return;
+
+        for (const [fieldName, value] of Object.entries(payload)) {
+            const memberDef = shape.members.get
+                ? shape.members.get(fieldName)
+                : shape.members[fieldName];
+            if (!memberDef) continue;
+
+            const fieldPath = parentPath ? `${parentPath}.${fieldName}` : fieldName;
+            const fieldShape = model.shapes.get(memberDef.shape);
+            if (!fieldShape) continue;
+
+            if (fieldShape.type === 'string' && fieldShape.enum && fieldShape.enum.length > 0) {
+                if (typeof value === 'string' && !fieldShape.enum.includes(value)) {
+                    findings.push({
+                        service,
+                        operation,
+                        fieldPath,
+                        invalidValue: value,
+                        constraint: { type: 'enum', values: [...fieldShape.enum] },
+                        severity: 'error',
+                        confidence: 'definitive',
+                        source: this.name,
+                        remediationHint: `Value "${value}" is not valid. Allowed values: ${fieldShape.enum.join(', ')}. Run \`bootstrap sync-schemas\` to update the enum set.`
+                    });
+                }
+            } else if (fieldShape.type === 'structure') {
+                this._validateStructure(
+                    value, fieldShape, model, service, operation, fieldPath, findings
+                );
+            } else if (fieldShape.type === 'list' && Array.isArray(value) && fieldShape.member) {
+                const elementShape = model.shapes.get(fieldShape.member.shape);
+                if (elementShape && elementShape.type === 'structure') {
+                    for (let i = 0; i < value.length; i++) {
+                        this._validateStructure(
+                            value[i], elementShape, model, service, operation,
+                            `${fieldPath}[${i}]`, findings
+                        );
+                    }
+                } else if (elementShape && elementShape.type === 'string' && elementShape.enum) {
+                    for (let i = 0; i < value.length; i++) {
+                        if (typeof value[i] === 'string' && !elementShape.enum.includes(value[i])) {
+                            findings.push({
+                                service,
+                                operation,
+                                fieldPath: `${fieldPath}[${i}]`,
+                                invalidValue: value[i],
+                                constraint: { type: 'enum', values: [...elementShape.enum] },
+                                severity: 'error',
+                                confidence: 'definitive',
+                                source: this.name,
+                                remediationHint: `Value "${value[i]}" is not valid. Allowed values: ${elementShape.enum.join(', ')}. Run \`bootstrap sync-schemas\` to update the enum set.`
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+}

package/src/lib/validators/required-field-validator.js

@@ -0,0 +1,150 @@
+/**
+ * Required field validator.
+ * Validates that all required fields in an operation's input shape
+ * are present and non-empty in the payload.
+ *
+ * Requirements: 5.1, 5.2, 5.3
+ */
+import BaseValidator from './base-validator.js';
+
+export default class RequiredFieldValidator extends BaseValidator {
+    get name() {
+        return 'required-field';
+    }
+
+    get mode() {
+        return 'static';
+    }
+
+    /**
+     * Validate required field presence for all payload operations.
+     * @param {Object} context - ValidationContext from PayloadBuilder
+     * @param {Object} options
+     * @param {Array} options.serviceModels - Parsed ServiceModelIndex objects
+     * @param {Array} options.priorFindings - Findings from earlier validators
+     * @returns {Promise<Array>} Array of Finding objects
+     */
+    async validate(context, options) {
+        const findings = [];
+        const serviceModels = options.serviceModels || [];
+
+        for (const [operationKey, payload] of Object.entries(context.payloads || {})) {
+            const [service, operation] = operationKey.split(':');
+
+            for (const model of serviceModels) {
+                const op = model.operations.get(operation);
+                if (!op || !op.input) continue;
+
+                const inputShape = model.shapes.get(op.input);
+                if (!inputShape || inputShape.type !== 'structure') continue;
+
+                this._validateRequiredFields(
+                    payload, inputShape, model, service, operation, '', findings
+                );
+            }
+        }
+
+        return findings;
+    }
+
+    /**
+     * Recursively validate required fields in a structure.
+     * @param {Object} payload - The payload object to validate
+     * @param {Object} shape - The structure shape definition
+     * @param {Object} model - The ServiceModelIndex
+     * @param {string} service - Service name
+     * @param {string} operation - Operation name
+     * @param {string} parentPath - Dot-notation path prefix
+     * @param {Array} findings - Accumulator for findings
+     */
+    _validateRequiredFields(payload, shape, model, service, operation, parentPath, findings) {
+        if (!shape || shape.type !== 'structure') return;
+
+        const requiredFields = shape.required || [];
+
+        for (const fieldName of requiredFields) {
+            const fieldPath = parentPath ? `${parentPath}.${fieldName}` : fieldName;
+            const memberDef = shape.members.get
+                ? shape.members.get(fieldName)
+                : shape.members[fieldName];
+
+            const value = payload ? payload[fieldName] : undefined;
+
+            if (value === undefined || value === null || value === '') {
+                const description = memberDef && memberDef.documentation
+                    ? memberDef.documentation
+                    : `Required field for ${operation}`;
+
+                findings.push({
+                    service,
+                    operation,
+                    fieldPath,
+                    invalidValue: value === undefined ? 'undefined' : value === null ? 'null' : '(empty string)',
+                    constraint: { type: 'required', field: fieldName },
+                    severity: 'error',
+                    confidence: 'definitive',
+                    source: this.name,
+                    remediationHint: `Required field "${fieldName}" is missing or empty in ${operation}. ${description}`
+                });
+            } else if (typeof value === 'object' && !Array.isArray(value) && memberDef) {
+                // Recursively validate nested structures
+                const nestedShape = model.shapes.get(memberDef.shape);
+                if (nestedShape && nestedShape.type === 'structure') {
+                    this._validateRequiredFields(
+                        value, nestedShape, model, service, operation, fieldPath, findings
+                    );
+                }
+            }
+        }
+
+        // Also recursively validate nested structures that are present (even if optional)
+        if (payload && typeof payload === 'object' && shape.members) {
+            for (const [fieldName, value] of Object.entries(payload)) {
+                if (value === null || value === undefined) continue;
+                if (typeof value !== 'object' || Array.isArray(value)) continue;
+
+                const memberDef = shape.members.get
+                    ? shape.members.get(fieldName)
+                    : shape.members[fieldName];
+                if (!memberDef) continue;
+
+                const nestedShape = model.shapes.get(memberDef.shape);
+                if (!nestedShape || nestedShape.type !== 'structure') continue;
+
+                // Skip if already validated as a required field above
+                if (requiredFields.includes(fieldName)) continue;
+
+                const fieldPath = parentPath ? `${parentPath}.${fieldName}` : fieldName;
+                this._validateRequiredFields(
+                    value, nestedShape, model, service, operation, fieldPath, findings
+                );
+            }
+        }
+
+        // Recursively validate list elements that are structures
+        if (payload && typeof payload === 'object' && shape.members) {
+            for (const [fieldName, value] of Object.entries(payload)) {
+                if (!Array.isArray(value)) continue;
+
+                const memberDef = shape.members.get
+                    ? shape.members.get(fieldName)
+                    : shape.members[fieldName];
+                if (!memberDef) continue;
+
+                const listShape = model.shapes.get(memberDef.shape);
+                if (!listShape || listShape.type !== 'list' || !listShape.member) continue;
+
+                const elementShape = model.shapes.get(listShape.member.shape);
+                if (!elementShape || elementShape.type !== 'structure') continue;
+
+                const fieldPath = parentPath ? `${parentPath}.${fieldName}` : fieldName;
+                for (let i = 0; i < value.length; i++) {
+                    this._validateRequiredFields(
+                        value[i], elementShape, model, service, operation,
+                        `${fieldPath}[${i}]`, findings
+                    );
+                }
+            }
+        }
+    }
+}