@aws/ml-container-creator 0.2.5 → 0.3.0

package/src/lib/validate-runner.js

@@ -0,0 +1,216 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Validation runner — the Node.js module invoked by do/validate.
+ * Loads config, constructs payloads, runs SchemaValidationEngine, and prints a report.
+ *
+ * - Prints structured report (text format by default)
+ * - Exits with code 1 if errors found, 0 if clean
+ * - Includes service model version date and fields validated count on success
+ * - Supports --smart flag for future MCP validator integration
+ *
+ * Requirements: 9.2, 9.3, 9.4
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import PayloadBuilder from './payload-builder.js';
+import SchemaValidationEngine from './schema-validation-engine.js';
+import ServiceModelParser from './service-model-parser.js';
+import CrossCuttingChecker from './cross-cutting-checker.js';
+import HuggingFaceClient from './huggingface-client.js';
+import { getRegistryPath, loadManifest } from './schema-sync.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Parse a do/config shell file into a key-value object.
+ * Extracts lines matching: export KEY="value" or export KEY=value
+ *
+ * @param {string} configPath - Path to the do/config file
+ * @returns {Object} Parsed configuration values
+ */
+export function parseDoConfig(configPath) {
+    if (!existsSync(configPath)) {
+        return null;
+    }
+
+    const content = readFileSync(configPath, 'utf8');
+    const config = {};
+
+    for (const line of content.split('\n')) {
+        const match = line.match(/^export\s+([A-Z_][A-Z0-9_]*)=["']?([^"'\n]*)["']?/);
+        if (match) {
+            const [, key, value] = match;
+            config[key] = value;
+        }
+    }
+
+    return config;
+}
+
+/**
+ * Run the full validation pipeline.
+ *
+ * @param {Object} options
+ * @param {string} [options.configDir] - Path to the do/ directory containing config
+ * @param {string} [options.format] - Output format: 'text' (default) or 'json'
+ * @param {boolean} [options.smart] - Enable smart-mode validators
+ * @param {string} [options.registryPath] - Override schema registry path
+ * @param {Object} [options.config] - Pre-parsed config (overrides configDir loading)
+ * @returns {Promise<number>} Exit code (0 = pass, 1 = fail, 2 = cannot run)
+ */
+export async function run(options = {}) {
+    const format = options.format || 'text';
+    const smart = options.smart || false;
+    const registryPath = options.registryPath || getRegistryPath();
+
+    // Check schema registry exists
+    if (!existsSync(registryPath) || !existsSync(path.join(registryPath, 'manifest.json'))) {
+        console.log('⚠️  Schema registry not found.');
+        console.log('   Run: ml-container-creator bootstrap sync-schemas');
+        process.exit(2);
+        return 2;
+    }
+
+    // Load config
+    let config = options.config;
+    if (!config && options.configDir) {
+        const configPath = path.join(options.configDir, 'config');
+        config = parseDoConfig(configPath);
+        if (!config) {
+            console.log('❌ Could not load do/config');
+            process.exit(2);
+            return 2;
+        }
+    }
+
+    if (!config) {
+        console.log('❌ No configuration provided');
+        process.exit(2);
+        return 2;
+    }
+
+    const deploymentTarget = config.DEPLOYMENT_TARGET || 'realtime-inference';
+
+    // Construct payloads
+    const builder = new PayloadBuilder();
+    const context = builder.build(config, deploymentTarget);
+
+    // Load and parse service models from registry
+    const parser = new ServiceModelParser();
+    const serviceModels = [];
+    try {
+        const entries = readdirSync(registryPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const modelPath = path.join(registryPath, entry.name, 'service-2.json');
+                if (existsSync(modelPath)) {
+                    const rawModel = JSON.parse(readFileSync(modelPath, 'utf8'));
+                    serviceModels.push(parser.parse(rawModel));
+                }
+            }
+        }
+    } catch {
+        console.log('⚠️  Could not load service models from registry');
+        process.exit(2);
+        return 2;
+    }
+
+    // Run validation engine
+    const engine = new SchemaValidationEngine({
+        registryPath,
+        smartMode: smart,
+        serviceModels
+    });
+
+    const report = await engine.validate(context);
+
+    // Run model architecture compatibility check (Requirement 5.1-5.2)
+    if (config.MODEL_NAME) {
+        try {
+            const catalogPath = path.resolve(__dirname, '../../servers/lib/catalogs/model-servers.json');
+            if (existsSync(catalogPath)) {
+                const modelServersCatalog = JSON.parse(readFileSync(catalogPath, 'utf8'));
+
+                // Fetch model's config.json from HuggingFace to get model_type
+                const hfClient = new HuggingFaceClient({ timeout: 10000 });
+                const modelConfig = await hfClient.fetchModelConfig(config.MODEL_NAME);
+                const modelType = modelConfig?.model_type || null;
+
+                if (modelType) {
+                    // Extract baseImageVersion from BASE_IMAGE (e.g., "vllm/vllm-openai:v0.10.1" → "v0.10.1")
+                    const baseImage = config.BASE_IMAGE || '';
+                    const baseImageVersion = baseImage.includes(':') ? baseImage.split(':').pop() : '';
+                    // Strip leading 'v' to match catalog's framework_version format (e.g., "v0.10.1" → "0.10.1")
+                    const frameworkVersion = baseImageVersion.replace(/^v/, '');
+
+                    const modelServer = config.MODEL_SERVER || '';
+
+                    // Build context fields for the architecture checker
+                    const archContext = {
+                        config: {
+                            modelType,
+                            modelServer,
+                            baseImageVersion: frameworkVersion
+                        }
+                    };
+
+                    const checker = new CrossCuttingChecker();
+                    const archFindings = checker.checkModelArchitectureCompatibility(archContext, modelServersCatalog);
+                    for (const finding of archFindings) {
+                        report.addFinding(finding);
+                    }
+                }
+            }
+        } catch {
+            // Graceful degradation: if architecture check fails, continue without it
+        }
+    }
+
+    const summary = report.getSummary();
+
+    // Load manifest for version info
+    const manifest = loadManifest(registryPath);
+
+    // Output report
+    if (format === 'json') {
+        report.metadata.serviceModelVersionDate = manifest?.lastSynced || null;
+        const output = report.toJSON();
+        console.log(JSON.stringify(output, null, 2));
+    } else {
+        // Print static results immediately
+        const text = report.toText();
+        console.log(text);
+
+        // On success, print version info
+        if (summary.errors === 0) {
+            const versionDate = manifest?.lastSynced
+                ? new Date(manifest.lastSynced).toISOString().split('T')[0]
+                : 'unknown';
+            console.log('');
+            console.log('✅ Validation passed');
+            console.log(`   Service model version: ${versionDate}`);
+            console.log(`   Fields validated: ${summary.fieldsValidated}`);
+        }
+
+        // If smart mode and results are streaming, display them after static
+        if (smart && summary.advisory > 0) {
+            console.log('');
+            console.log('── Smart-mode findings ──');
+            for (const finding of report.advisoryFindings) {
+                console.log(`  ℹ ${finding.fieldPath || finding.operation}: ${finding.remediationHint || ''}`);
+            }
+        }
+    }
+
+    // Exit code
+    const exitCode = summary.errors > 0 ? 1 : 0;
+    process.exit(exitCode);
+    return exitCode;
+}
+
+export default { run, parseDoConfig };

package/src/lib/validation-report.js

@@ -0,0 +1,140 @@
+/**
+ * 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') {
+            // Cross-cutting findings with medium/low confidence are advisory, not errors
+            if (finding.confidence === 'medium' || finding.confidence === 'low') {
+                this.advisoryFindings.push(finding);
+            } else if (finding.severity === 'warning') {
+                this.warnings.push(finding);
+            } else {
+                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.`
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+}