@aifabrix/builder 2.49.1 → 2.50.0

package/lib/utils/test-target-cli-options.js

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview CLI normalization for manifest version target and test sync policy (456.17).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const SYNC_MODES = new Set(['auto', 'never', 'force']);
+const VERSION_KEYWORDS = new Set(['latest', 'running']);
+
+/**
+ * @param {string|undefined|null} raw
+ * @param {string} [defaultValue='latest']
+ * @returns {string}
+ */
+function normalizeVersionTarget(raw, defaultValue = 'latest') {
+  const value = String(raw ?? defaultValue).trim();
+  if (!value) {
+    throw new Error('--version is required (latest, running, or explicit version id).');
+  }
+  const lower = value.toLowerCase();
+  if (VERSION_KEYWORDS.has(lower)) {
+    return lower;
+  }
+  if (!/^[a-zA-Z0-9._-]+$/.test(value)) {
+    throw new Error(
+      '--version must be latest, running, or an explicit version id (letters, numbers, ., _, -).'
+    );
+  }
+  return value;
+}
+
+/**
+ * @param {string|undefined|null} raw
+ * @param {string} [defaultValue='auto']
+ * @returns {string}
+ */
+function normalizeSyncMode(raw, defaultValue = 'auto') {
+  const value = String(raw ?? defaultValue).trim().toLowerCase();
+  if (!SYNC_MODES.has(value)) {
+    throw new Error('--sync-mode must be auto, never, or force.');
+  }
+  return value;
+}
+
+/**
+ * Merge versionTarget and syncMode from CLI options into e2eOptions for ValidationRunRequest.
+ *
+ * @param {Object} cliOptions - Commander-parsed options
+ * @param {Object} [e2eOptions={}]
+ * @returns {Object}
+ */
+function mergeTestTargetIntoE2eOptions(cliOptions, e2eOptions = {}) {
+  const merged = { ...e2eOptions };
+  if (cliOptions && cliOptions.version !== undefined && cliOptions.version !== null) {
+    merged.versionTarget = normalizeVersionTarget(cliOptions.version);
+  } else {
+    merged.versionTarget = normalizeVersionTarget(undefined, 'latest');
+  }
+  if (cliOptions && cliOptions.syncMode !== undefined && cliOptions.syncMode !== null) {
+    merged.syncMode = normalizeSyncMode(cliOptions.syncMode);
+  } else {
+    merged.syncMode = normalizeSyncMode(undefined, 'auto');
+  }
+  return merged;
+}
+
+module.exports = {
+  SYNC_MODES,
+  VERSION_KEYWORDS,
+  normalizeVersionTarget,
+  normalizeSyncMode,
+  mergeTestTargetIntoE2eOptions
+};

package/lib/utils/upload-sync-options.js

@@ -19,11 +19,15 @@ function buildMinimalUploadSyncOptions(options = {}) {
     verbose: false,
     silentResolve: true,
     syncMode: true,
+    skipDataSync: true,
     suppressPipelineSpinner: options.suppressPipelineSpinner === true
   };
   if (options.force === true) {
     out.force = true;
   }
+  if (options.suppressSummary === true) {
+    out.suppressSummary = true;
+  }
   return out;
 }
 

package/lib/utils/validation-run-request.js

@@ -4,6 +4,8 @@
  * @version 2.0.0
  */
 
+const { mergeTestTargetIntoE2eOptions, normalizeVersionTarget } = require('./test-target-cli-options');
+
 /**
  * Whether the unified validation request should set includeDebug (any `--debug` or `--debug <level>`).
  * @param {*} debugOpt - Commander `options.debug`
@@ -60,7 +62,7 @@ function buildE2eOptionsFromCli(options = {}) {
   if (options.e2eOptionsExtra && typeof options.e2eOptionsExtra === 'object') {
     Object.assign(e2e, options.e2eOptionsExtra);
   }
-  return e2e;
+  return mergeTestTargetIntoE2eOptions(options, e2e);
 }
 
 /**
@@ -73,6 +75,8 @@ function buildE2eOptionsFromCli(options = {}) {
  * @param {boolean} [params.asyncRun]
  * @param {boolean} [params.includeDebug]
  * @param {boolean} [params.explain]
+ * @param {boolean} [params.explainCertification]
+ * @param {boolean} [params.explainMetrics]
  * @param {Object} [params.e2eOptions] - Merged with buildE2eOptionsFromCli when both used by caller
  * @returns {import('../api/types/validation-run.types').ValidationRunRequestBody}
  */
@@ -85,6 +89,8 @@ function buildExternalDataSourceValidationRequest(params) {
     asyncRun,
     includeDebug,
     explain,
+    explainCertification,
+    explainMetrics,
     e2eOptions
   } = params;
   if (!systemKey || !datasourceKey || !runType) {
@@ -101,6 +107,8 @@ function buildExternalDataSourceValidationRequest(params) {
   if (asyncRun === true) body.asyncRun = true;
   if (includeDebug === true) body.includeDebug = true;
   if (explain === true) body.explain = true;
+  if (explainCertification === true) body.explainCertification = true;
+  if (explainMetrics === true) body.explainMetrics = true;
   if (e2eOptions && typeof e2eOptions === 'object' && Object.keys(e2eOptions).length > 0) {
     body.e2eOptions = e2eOptions;
   }
@@ -110,5 +118,6 @@ function buildExternalDataSourceValidationRequest(params) {
 module.exports = {
   includeDebugForRequest,
   buildE2eOptionsFromCli,
-  buildExternalDataSourceValidationRequest
+  buildExternalDataSourceValidationRequest,
+  normalizeVersionTarget
 };

package/lib/validation/external-manifest-validator.js

@@ -17,6 +17,7 @@ const { formatValidationErrors } = require('../utils/error-formatter');
 const { validateFieldReferences } = require('../datasource/field-reference-validator');
 const { validateAbac } = require('../datasource/abac-validator');
 const { validateManifestRuntimeConfiguration } = require('./runtime-configuration-rules');
+const { validateAppContractSurface } = require('./openapi-contract-surface-validator');
 
 /**
  * Load and normalize external-system + external-datasource schema objects for manifest AJV.
@@ -223,6 +224,7 @@ function validateDatasourceSystemKeyAlignment(manifest, errors) {
  * @async
  * @function validateControllerManifest
  * @param {Object} manifest - Controller manifest object
+ * @param {Object} [options] - Optional context (appPath for contract-surface checks)
  * @returns {Promise<Object>} Validation result
  * @throws {Error} If validation fails critically
  *
@@ -230,7 +232,7 @@ function validateDatasourceSystemKeyAlignment(manifest, errors) {
  * const result = await validateControllerManifest(manifest);
  * // Returns: { valid: true, errors: [], warnings: [] }
  */
-async function validateControllerManifest(manifest) {
+async function validateControllerManifest(manifest, options = {}) {
   if (!manifest || typeof manifest !== 'object') {
     return {
       valid: false,
@@ -249,6 +251,14 @@ async function validateControllerManifest(manifest) {
   validateDatasources(manifest, ajv, externalDatasourceSchema, errors, warnings);
   validateDatasourceSystemKeyAlignment(manifest, errors);
   errors.push(...validateManifestRuntimeConfiguration(manifest));
+  if (manifest.type === 'external' && Array.isArray(manifest.dataSources) && manifest.system?.key) {
+    const appPath = options.appPath;
+    if (typeof appPath === 'string' && appPath) {
+      const contract = validateAppContractSurface(appPath, manifest.system.key, manifest.dataSources);
+      errors.push(...contract.errors);
+      warnings.push(...contract.warnings);
+    }
+  }
   validateConditionalRequirements(manifest, errors, warnings);
   validateRequiredFields(manifest, errors);
 

package/lib/validation/openapi-contract-surface-validator.js

@@ -0,0 +1,426 @@
+/**
+ * Validate that OpenAPI / MCP contract surfaces are meaningful (not dataplane stubs).
+ *
+ * @fileoverview Contract surface validation for orchestration vs record datasources
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { buildOpenApiSpec } = require('../programmatic/openapi-spec');
+const {
+  documentKeyToLocalOpenApiPath,
+  isProgrammaticOrchestrationSystem,
+  specHasComponentSchemas
+} = require('../commands/repair-openapi-export');
+const {
+  validateVendorOperationContract,
+  findVendorOperation,
+  validateOrchestrationDatasourceContracts
+} = require('./openapi-contract-vendor-validation');
+
+const JSON_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'head', 'options']);
+
+/**
+ * @param {Object} ds
+ * @returns {boolean}
+ */
+function isServiceContractDatasource(ds) {
+  const entity = String(ds?.entityType || '').trim().toLowerCase();
+  return entity === 'servicecontract';
+}
+
+/**
+ * @param {Object} ds
+ * @returns {boolean}
+ */
+function isCompositionNoneDatasource(ds) {
+  return String(ds?.entityType || '').trim().toLowerCase() === 'none';
+}
+
+/**
+ * @param {Object} ds
+ * @returns {boolean}
+ */
+function hasVendorOpenapiOnManifest(ds) {
+  const openapi = ds?.openapi;
+  if (!openapi || typeof openapi !== 'object' || openapi.enabled === false) {
+    return false;
+  }
+  const operations = openapi.operations;
+  if (operations && typeof operations === 'object' && Object.keys(operations).length > 0) {
+    return true;
+  }
+  const documentKey =
+    typeof openapi.documentKey === 'string' ? openapi.documentKey.trim() : '';
+  return Boolean(documentKey) || openapi.enabled === true;
+}
+
+/**
+ * @deprecated use isServiceContractDatasource — kept for tests importing legacy name
+ * @param {Object} ds
+ * @returns {boolean}
+ */
+function isOrchestrationDatasource(ds) {
+  return isServiceContractDatasource(ds);
+}
+
+/**
+ * @param {Object|undefined} op
+ * @returns {boolean}
+ */
+function operationHasRequestOrResponseSchema(op) {
+  if (!op || typeof op !== 'object') {
+    return false;
+  }
+  if (op.requestBody) {
+    return true;
+  }
+  const responses = op.responses;
+  if (!responses || typeof responses !== 'object') {
+    return false;
+  }
+  for (const response of Object.values(responses)) {
+    if (response && typeof response === 'object' && response.content) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * @param {Object|undefined} paths
+ * @returns {boolean}
+ */
+function pathsHaveRequestOrResponseSchemas(paths) {
+  if (!paths || typeof paths !== 'object') {
+    return false;
+  }
+  for (const pathItem of Object.values(paths)) {
+    if (!pathItem || typeof pathItem !== 'object') {
+      continue;
+    }
+    for (const [method, op] of Object.entries(pathItem)) {
+      if (!JSON_METHODS.has(method)) {
+        continue;
+      }
+      if (operationHasRequestOrResponseSchema(op)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * @param {unknown} spec
+ * @returns {boolean}
+ */
+function isThinOpenApiSpec(spec) {
+  if (!spec || typeof spec !== 'object') {
+    return true;
+  }
+  if (specHasComponentSchemas(spec)) {
+    return false;
+  }
+  return !pathsHaveRequestOrResponseSchemas(spec.paths);
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Object|null}
+ */
+function readJsonIfExists(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} appPath
+ * @param {string} systemKey
+ * @param {string} documentKey
+ * @returns {{ spec: Object|null, localPath: string, fromMemory: boolean }}
+ */
+function resolveVendorOpenApiSpec(appPath, systemKey, documentKey) {
+  const localPath = documentKeyToLocalOpenApiPath(appPath, systemKey, documentKey);
+  const fromDisk = readJsonIfExists(localPath);
+  if (fromDisk) {
+    return { spec: fromDisk, localPath, fromMemory: false };
+  }
+  if (isProgrammaticOrchestrationSystem(systemKey)) {
+    const spec = buildOpenApiSpec();
+    return { spec, localPath, fromMemory: true };
+  }
+  return { spec: null, localPath, fromMemory: false };
+}
+
+/**
+ * @param {Object} ds
+ * @param {string} prefix
+ * @returns {string[]}
+ */
+function collectServiceContractFieldMappingErrors(ds, prefix) {
+  const fieldMappings = ds.fieldMappings;
+  const attributes =
+    fieldMappings && typeof fieldMappings === 'object' ? fieldMappings.attributes : null;
+  const hasAttributes =
+    attributes && typeof attributes === 'object' && Object.keys(attributes).length > 0;
+  if (hasAttributes) {
+    return [];
+  }
+  return [
+    `${prefix}serviceContract requires fieldMappings.attributes — public contract must be testable`
+  ];
+}
+
+/**
+ * @param {Object} ds
+ * @param {string} prefix
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+function collectServiceContractExposedIssues(ds, prefix) {
+  const errors = [];
+  const warnings = [];
+  const exposed = ds.exposed;
+  const schema = exposed && typeof exposed === 'object' ? exposed.schema : null;
+  if (!schema || typeof schema !== 'object' || Object.keys(schema).length === 0) {
+    errors.push(`${prefix}serviceContract requires exposed.schema for MCP/REST contract`);
+  }
+  const profiles = exposed && typeof exposed === 'object' ? exposed.profiles : null;
+  if (!profiles || typeof profiles !== 'object' || Object.keys(profiles).length === 0) {
+    warnings.push(`${prefix}serviceContract missing exposed.profiles — add default envelope`);
+  }
+  return { errors, warnings };
+}
+
+/**
+ * @param {Object} ds
+ * @param {string} prefix
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+function validateServiceContractDatasourceContracts(ds, prefix) {
+  const errors = collectServiceContractFieldMappingErrors(ds, prefix);
+  const exposed = collectServiceContractExposedIssues(ds, prefix);
+  errors.push(...exposed.errors);
+  return { errors, warnings: exposed.warnings };
+}
+
+/**
+ * @param {Object} ds
+ * @param {string} prefix
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+function validateRecordDatasourceContracts(ds, prefix) {
+  const errors = [];
+  const warnings = [];
+  const caps = ds.capabilities;
+  const capList = Array.isArray(caps) ? caps.map((c) => String(c).toLowerCase()) : [];
+  const needsExposed = capList.some((c) => ['create', 'update', 'list', 'get'].includes(c));
+  const fieldMappings = ds.fieldMappings;
+  const attributes =
+    fieldMappings && typeof fieldMappings === 'object' ? fieldMappings.attributes : null;
+  const hasAttributes =
+    attributes && typeof attributes === 'object' && Object.keys(attributes).length > 0;
+  if (!hasAttributes) {
+    errors.push(
+      `${prefix}fieldMappings.attributes is missing or empty — record entities need mapped fields for sync and MCP schemas`
+    );
+  }
+  const exposed = ds.exposed;
+  const profiles = exposed && typeof exposed === 'object' ? exposed.profiles : null;
+  const hasProfiles =
+    profiles && typeof profiles === 'object' && Object.keys(profiles).length > 0;
+  if (needsExposed && !hasProfiles) {
+    errors.push(
+      `${prefix}exposed.profiles is missing or empty — record entities need exposed schema profiles for MCP/OpenAPI`
+    );
+  }
+  return { errors, warnings };
+}
+
+/**
+ * @param {Object} ds
+ * @param {string} prefix
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+function validateNoneDatasourceContract(ds, prefix) {
+  const errors = [];
+  const warnings = [];
+  if (hasVendorOpenapiOnManifest(ds)) {
+    warnings.push(
+      `${prefix}entityType none must not bind vendor OpenAPI — run repair to migrate to serviceContract`
+    );
+  }
+  return { errors, warnings };
+}
+
+/**
+ * @param {string} documentKey
+ * @param {string} prefix
+ * @param {string} appPath
+ * @param {string} systemKey
+ * @param {Map<string, Object|null>} vendorCache
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+function resolveCachedVendorSpec(documentKey, prefix, appPath, systemKey, vendorCache) {
+  const errors = [];
+  const warnings = [];
+  const resolved = resolveVendorOpenApiSpec(appPath, systemKey, documentKey);
+  vendorCache.set(documentKey, resolved.spec);
+  if (!resolved.spec) {
+    errors.push(
+      `${prefix}missing vendor OpenAPI at ${resolved.localPath} — run: aifabrix repair ${systemKey} --api`
+    );
+    return { errors, warnings, spec: null };
+  }
+  if (isThinOpenApiSpec(resolved.spec)) {
+    errors.push(
+      `${prefix}vendor OpenAPI "${documentKey}" is a thin stub (no component schemas / body schemas) — run: aifabrix repair ${systemKey} --api`
+    );
+    return { errors, warnings, spec: null };
+  }
+  if (resolved.fromMemory) {
+    warnings.push(
+      `${prefix}vendor OpenAPI "${documentKey}" not on disk; validated from in-memory programmatic spec — run: aifabrix repair ${systemKey} --api to materialize openapi/`
+    );
+  }
+  return { errors, warnings, spec: resolved.spec };
+}
+
+/**
+ * @param {Object} ds
+ * @param {string} prefix
+ * @param {string} appPath
+ * @param {string} systemKey
+ * @param {Map<string, Object|null>} vendorCache
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+function validateServiceContractVendorOpenApi(ds, prefix, appPath, systemKey, vendorCache) {
+  const errors = [];
+  const warnings = [];
+  const documentKey =
+    typeof ds.openapi?.documentKey === 'string' ? ds.openapi.documentKey.trim() : '';
+  if (!documentKey) {
+    errors.push(`${prefix}serviceContract with OpenAPI upstream requires openapi.documentKey`);
+    return { errors, warnings };
+  }
+  if (!vendorCache.has(documentKey)) {
+    const cached = resolveCachedVendorSpec(documentKey, prefix, appPath, systemKey, vendorCache);
+    errors.push(...cached.errors);
+    warnings.push(...cached.warnings);
+    if (!cached.spec) {
+      return { errors, warnings };
+    }
+  }
+  const vendorSpec = vendorCache.get(documentKey);
+  const orch = validateOrchestrationDatasourceContracts(ds, vendorSpec, prefix);
+  errors.push(...orch.errors);
+  warnings.push(...orch.warnings);
+  return { errors, warnings };
+}
+
+/**
+ * @param {Object} ds
+ * @param {string} appPath
+ * @param {string} systemKey
+ * @param {Map<string, Object|null>} vendorCache
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+function validateDatasourceContractSurface(ds, appPath, systemKey, vendorCache) {
+  const prefix = `Datasource "${ds.key || '(unknown)'}": `;
+  if (isCompositionNoneDatasource(ds)) {
+    return validateNoneDatasourceContract(ds, prefix);
+  }
+  if (isServiceContractDatasource(ds)) {
+    const sc = validateServiceContractDatasourceContracts(ds, prefix);
+    const vendor = validateServiceContractVendorOpenApi(
+      ds,
+      prefix,
+      appPath,
+      systemKey,
+      vendorCache
+    );
+    return {
+      errors: [...sc.errors, ...vendor.errors],
+      warnings: [...sc.warnings, ...vendor.warnings]
+    };
+  }
+  return validateRecordDatasourceContracts(ds, prefix);
+}
+
+/**
+ * @param {string} appPath
+ * @param {string} systemKey
+ * @param {Object[]} datasources
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+function validateAppContractSurface(appPath, systemKey, datasources) {
+  const errors = [];
+  const warnings = [];
+  const vendorCache = new Map();
+  for (const ds of datasources || []) {
+    if (!ds || typeof ds !== 'object') {
+      continue;
+    }
+    const result = validateDatasourceContractSurface(ds, appPath, systemKey, vendorCache);
+    errors.push(...result.errors);
+    warnings.push(...result.warnings);
+  }
+  return { errors, warnings };
+}
+
+/**
+ * @param {string} filePath
+ * @returns {{ appPath: string, systemKey: string }|null}
+ */
+function inferIntegrationContextFromPath(filePath) {
+  const normalized = path.normalize(filePath);
+  const parts = normalized.split(path.sep);
+  const integrationIdx = parts.lastIndexOf('integration');
+  if (integrationIdx < 0 || integrationIdx + 1 >= parts.length) {
+    return null;
+  }
+  const systemKey = parts[integrationIdx + 1];
+  const appPath = parts.slice(0, integrationIdx + 2).join(path.sep);
+  return { appPath, systemKey };
+}
+
+/**
+ * @param {Object} parsedDatasource
+ * @param {string} filePath
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+function validateDatasourceFileContractSurface(parsedDatasource, filePath) {
+  const ctx = inferIntegrationContextFromPath(filePath);
+  if (!ctx) {
+    return { errors: [], warnings: [] };
+  }
+  return validateDatasourceContractSurface(
+    parsedDatasource,
+    ctx.appPath,
+    ctx.systemKey,
+    new Map()
+  );
+}
+
+module.exports = {
+  isOrchestrationDatasource,
+  isServiceContractDatasource,
+  isCompositionNoneDatasource,
+  hasVendorOpenapiOnManifest,
+  isThinOpenApiSpec,
+  validateAppContractSurface,
+  validateDatasourceFileContractSurface,
+  validateVendorOperationContract,
+  validateServiceContractDatasourceContracts,
+  findVendorOperation
+};