@aifabrix/builder 2.44.5 → 2.44.6

package/lib/datasource/capability/basic-exposure.js

@@ -0,0 +1,76 @@
+/**
+ * Build a minimal exposed.profiles row from metadataSchema (primitives + required fields).
+ *
+ * @fileoverview Minimal exposed.profiles row from metadataSchema (used by applyCapabilityCopy when basicExposure)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const PRIMITIVE = new Set(['string', 'number', 'integer', 'boolean']);
+
+/**
+ * @param {object} prop - JSON Schema property
+ * @returns {boolean}
+ */
+function isPrimitiveSchemaProperty(prop) {
+  if (!prop || typeof prop !== 'object') {
+    return false;
+  }
+  const t = prop.type;
+  if (typeof t === 'string') {
+    return PRIMITIVE.has(t);
+  }
+  if (Array.isArray(t)) {
+    return t.some((x) => PRIMITIVE.has(x));
+  }
+  return false;
+}
+
+/**
+ * Attribute names for a minimal array-style profile: required primitives + all primitive properties.
+ *
+ * @param {object} parsed - Datasource JSON
+ * @returns {string[]} Sorted unique attribute names
+ */
+function listBasicExposureAttributes(parsed) {
+  const ms = parsed.metadataSchema;
+  const properties = ms && typeof ms === 'object' ? ms.properties : null;
+  if (!properties || typeof properties !== 'object') {
+    return [];
+  }
+  const required = Array.isArray(ms.required) ? ms.required : [];
+  const names = new Set();
+  for (const key of required) {
+    if (properties[key] && isPrimitiveSchemaProperty(properties[key])) {
+      names.add(key);
+    }
+  }
+  for (const [key, prop] of Object.entries(properties)) {
+    if (isPrimitiveSchemaProperty(prop)) {
+      names.add(key);
+    }
+  }
+  return [...names].sort();
+}
+
+/**
+ * @param {object} parsed - Datasource JSON
+ * @returns {string[]}
+ * @throws {Error} When nothing can be derived
+ */
+function buildBasicExposureProfileArray(parsed) {
+  const attrs = listBasicExposureAttributes(parsed);
+  if (attrs.length === 0) {
+    throw new Error(
+      'Cannot build basic exposure: metadataSchema.properties has no primitive fields (or missing metadataSchema). ' +
+        'Add primitive fields to metadataSchema, copy an existing exposed.profiles.<from> via capability copy, or choose another target key.'
+    );
+  }
+  return attrs;
+}
+
+module.exports = {
+  buildBasicExposureProfileArray,
+  listBasicExposureAttributes,
+  isPrimitiveSchemaProperty
+};

package/lib/datasource/capability/capability-diff-slice.js

@@ -0,0 +1,41 @@
+/**
+ * Extract a comparable subtree for `capability diff`.
+ *
+ * @fileoverview capability slice extraction for diff
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { deepClone } = require('./copy-operations');
+
+/**
+ * @param {object} doc - Parsed datasource JSON
+ * @param {string} capabilityKey - Normalized capability key
+ * @param {string} [profileKey] - Optional exposed.profiles key
+ * @returns {object} Stable-shape slice for compareObjects
+ */
+function extractCapabilitySliceForDiff(doc, capabilityKey, profileKey) {
+  const cap = capabilityKey;
+  const listed =
+    Boolean(Array.isArray(doc.capabilities) && doc.capabilities.includes(cap));
+  const openapiOp = doc.openapi?.operations?.[cap];
+  const cipOp = doc.execution?.cip?.operations?.[cap];
+  let exposedProfile;
+  if (profileKey && String(profileKey).trim()) {
+    const pk = String(profileKey).trim();
+    const raw = doc.exposed?.profiles?.[pk];
+    exposedProfile = raw !== undefined ? deepClone(raw) : undefined;
+  }
+
+  return {
+    capabilityKey: cap,
+    listedInCapabilities: listed,
+    openapiOperation: openapiOp !== undefined ? deepClone(openapiOp) : undefined,
+    cipOperation: cipOp !== undefined ? deepClone(cipOp) : undefined,
+    exposedProfile
+  };
+}
+
+module.exports = {
+  extractCapabilitySliceForDiff
+};

package/lib/datasource/capability/capability-key.js

@@ -0,0 +1,34 @@
+/**
+ * Normalize and validate external datasource capability keys.
+ *
+ * @fileoverview Capability key helpers for datasource capability CLI
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/** Pattern aligned with external-datasource.schema.json capabilities[].items */
+const CAPABILITY_KEY_PATTERN = /^[a-z][a-zA-Z0-9_]*$/;
+
+/**
+ * @param {string} raw - Raw CLI input
+ * @param {string} label - Option label for errors
+ * @returns {string} Normalized key
+ * @throws {Error} If empty or invalid
+ */
+function normalizeCapabilityKey(raw, label = 'capability') {
+  const s = String(raw || '').trim();
+  if (!s) {
+    throw new Error(`${label} key is required`);
+  }
+  if (!CAPABILITY_KEY_PATTERN.test(s)) {
+    throw new Error(
+      `${label} key "${s}" is invalid: must match ${CAPABILITY_KEY_PATTERN}`
+    );
+  }
+  return s;
+}
+
+module.exports = {
+  normalizeCapabilityKey,
+  CAPABILITY_KEY_PATTERN
+};

package/lib/datasource/capability/capability-resolve.js

@@ -0,0 +1,172 @@
+/**
+ * Map logical capability names (capabilities[] / profiles) to openapi + CIP operation object keys.
+ *
+ * @fileoverview capabilities-first resolution when OpenAPI uses different casing
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * @param {object|undefined} operations
+ * @param {string} logicalKey
+ * @returns {string[]}
+ */
+function findMatchingOpsKeys(operations, logicalKey) {
+  if (!operations || typeof operations !== 'object') {
+    return [];
+  }
+  if (operations[logicalKey] !== undefined) {
+    return [logicalKey];
+  }
+  const lower = String(logicalKey).toLowerCase();
+  return Object.keys(operations).filter((k) => k.toLowerCase() === lower);
+}
+
+/**
+ * @param {object|undefined} operations
+ * @param {string} logicalKey
+ * @param {string} label - For error messages
+ * @returns {string|null} Single match, or null
+ * @throws {Error} When multiple keys differ only by case
+ */
+function resolveSingleOpsKey(operations, logicalKey, label) {
+  const matches = findMatchingOpsKeys(operations, logicalKey);
+  if (matches.length === 1) {
+    return matches[0];
+  }
+  if (matches.length === 0) {
+    return null;
+  }
+  throw new Error(
+    `Ambiguous ${label} operations keys for "${logicalKey}": ${matches.join(', ')}`
+  );
+}
+
+/**
+ * For --from on copy: when capabilities[] is non-empty, the name must appear there (case-insensitive).
+ *
+ * @param {object} doc
+ * @param {string} userKey
+ * @returns {string} Canonical string from capabilities[] or userKey when no list
+ * @throws {Error} When capabilities is non-empty and no entry matches
+ */
+function resolveSourceCapabilityForCopy(doc, userKey) {
+  const u = String(userKey).trim();
+  const caps = doc.capabilities;
+  if (Array.isArray(caps) && caps.length > 0) {
+    const hit = caps.find((c) => String(c).toLowerCase() === u.toLowerCase());
+    if (hit === undefined) {
+      throw new Error(
+        `Source capability "${userKey}" not found in capabilities[]. ` +
+          'Use a name that appears in capabilities[] (case-insensitive match is allowed).'
+      );
+    }
+    return String(hit);
+  }
+  return u;
+}
+
+/**
+ * For remove: prefer canonical name from capabilities when present; otherwise use the user key.
+ *
+ * @param {object} doc
+ * @param {string} userKey
+ * @returns {string}
+ */
+function resolveLogicalNameForRemove(doc, userKey) {
+  const u = String(userKey).trim();
+  const caps = doc.capabilities;
+  if (Array.isArray(caps) && caps.length > 0) {
+    const hit = caps.find((c) => String(c).toLowerCase() === u.toLowerCase());
+    if (hit !== undefined) {
+      return String(hit);
+    }
+  }
+  return u;
+}
+
+/**
+ * Openapi + CIP object keys for a logical capability (exact or single case-insensitive match per section).
+ *
+ * @param {object} doc
+ * @param {string} logicalKey
+ * @returns {{ openapiKey: string, cipKey: string }}
+ * @throws {Error} If a section is missing the operation
+ */
+function resolveOpsKeysForCapability(doc, logicalKey) {
+  const openapiKey = resolveSingleOpsKey(doc.openapi?.operations, logicalKey, 'openapi');
+  const cipKey = resolveSingleOpsKey(doc.execution?.cip?.operations, logicalKey, 'cip');
+  if (!openapiKey) {
+    throw new Error(
+      `Missing openapi.operations entry for capability "${logicalKey}" ` +
+        '(no exact or case-insensitive key match).'
+    );
+  }
+  if (!cipKey) {
+    throw new Error(
+      `Missing execution.cip.operations entry for capability "${logicalKey}" ` +
+        '(no exact or case-insensitive key match).'
+    );
+  }
+  return { openapiKey, cipKey };
+}
+
+/**
+ * @param {object} doc
+ * @param {string} logicalKey
+ * @returns {string|null} profiles key to use, or null
+ * @throws {Error} On ambiguous profile keys
+ */
+function resolveProfileKeyForLogical(doc, logicalKey) {
+  const prof = doc.exposed?.profiles;
+  if (!prof || typeof prof !== 'object') {
+    return null;
+  }
+  if (prof[logicalKey] !== undefined) {
+    return logicalKey;
+  }
+  const lower = String(logicalKey).toLowerCase();
+  const keys = Object.keys(prof).filter((k) => k.toLowerCase() === lower);
+  if (keys.length === 1) {
+    return keys[0];
+  }
+  if (keys.length > 1) {
+    throw new Error(
+      `Ambiguous exposed.profiles keys for "${logicalKey}": ${keys.join(', ')}`
+    );
+  }
+  return null;
+}
+
+/**
+ * True if the name appears in capabilities (case-insensitive) or in openapi or CIP operations (case-insensitive).
+ *
+ * @param {object} doc
+ * @param {string} name
+ * @returns {boolean}
+ */
+function capabilityLogicalExists(doc, name) {
+  if (
+    Array.isArray(doc.capabilities) &&
+    doc.capabilities.some((c) => String(c).toLowerCase() === String(name).toLowerCase())
+  ) {
+    return true;
+  }
+  if (findMatchingOpsKeys(doc.openapi?.operations, name).length > 0) {
+    return true;
+  }
+  if (findMatchingOpsKeys(doc.execution?.cip?.operations, name).length > 0) {
+    return true;
+  }
+  return false;
+}
+
+module.exports = {
+  findMatchingOpsKeys,
+  resolveSingleOpsKey,
+  resolveSourceCapabilityForCopy,
+  resolveLogicalNameForRemove,
+  resolveOpsKeysForCapability,
+  resolveProfileKeyForLogical,
+  capabilityLogicalExists
+};

package/lib/datasource/capability/capability-storage-keys.js

@@ -0,0 +1,22 @@
+/**
+ * Storage naming: openapi/CIP operation map keys and testPayload.scenarios.operation use lowercase.
+ * capabilities[] and exposed.profiles use logical camelCase names (--as).
+ *
+ * @fileoverview capability storage key normalization for copy pipeline
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Lowercase key for openapi.operations / execution.cip.operations / scenario.operation.
+ *
+ * @param {string} logicalCapabilityKey - Normalized --as / capabilities[] name (e.g. updateCountry)
+ * @returns {string}
+ */
+function storageOpsKey(logicalCapabilityKey) {
+  return String(logicalCapabilityKey ?? '').trim().toLowerCase();
+}
+
+module.exports = {
+  storageOpsKey
+};

package/lib/datasource/capability/copy-operations.js

@@ -0,0 +1,348 @@
+/**
+ * Clone a capability within one datasource JSON document.
+ *
+ * @fileoverview capability copy / collision / profile sync
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { rewriteCapabilityReferences } = require('./reference-rewrite');
+const { jsonPointerPath } = require('./json-pointer');
+const { buildBasicExposureProfileArray } = require('./basic-exposure');
+const {
+  resolveProfileKeyForLogical,
+  capabilityLogicalExists,
+  resolveOpsKeysForCapability,
+  resolveSourceCapabilityForCopy,
+  findMatchingOpsKeys
+} = require('./capability-resolve');
+const { copyTestPayloadScenarios } = require('./copy-test-payload');
+const { storageOpsKey } = require('./capability-storage-keys');
+
+/**
+ * @param {object} doc - Datasource object
+ * @param {string} name - Capability key
+ * @returns {boolean}
+ */
+function capabilityExists(doc, name) {
+  return capabilityLogicalExists(doc, name);
+}
+
+/**
+ * @param {object} doc - Mutated datasource
+ * @param {string} logicalKey - Logical capability name (matches capabilities[] casing when listed)
+ * @returns {void}
+ */
+function removeCapability(doc, logicalKey) {
+  const oo = doc.openapi?.operations;
+  const co = doc.execution?.cip?.operations;
+  const openapiKeys = findMatchingOpsKeys(oo, logicalKey);
+  const cipKeys = findMatchingOpsKeys(co, logicalKey);
+  if (openapiKeys.length > 1) {
+    throw new Error(
+      `Ambiguous openapi.operations keys for "${logicalKey}": ${openapiKeys.join(', ')}`
+    );
+  }
+  if (cipKeys.length > 1) {
+    throw new Error(
+      `Ambiguous execution.cip.operations keys for "${logicalKey}": ${cipKeys.join(', ')}`
+    );
+  }
+  const openapiKey = openapiKeys[0];
+  const cipKey = cipKeys[0];
+  const profileKey = resolveProfileKeyForLogical(doc, logicalKey);
+
+  if (Array.isArray(doc.capabilities)) {
+    doc.capabilities = doc.capabilities.filter(
+      (c) => String(c).toLowerCase() !== String(logicalKey).toLowerCase()
+    );
+  }
+  if (openapiKey && oo) {
+    delete oo[openapiKey];
+  }
+  if (cipKey && co) {
+    delete co[cipKey];
+  }
+  if (profileKey && doc.exposed?.profiles) {
+    delete doc.exposed.profiles[profileKey];
+  }
+}
+
+/**
+ * @param {object} doc
+ * @param {string} to - Desired target key
+ * @param {boolean} overwrite
+ * @returns {string} Same as `to` when free or when overwriting
+ * @throws {Error} When target exists and overwrite is false
+ */
+function resolveTargetKey(doc, to, overwrite) {
+  if (overwrite) {
+    return to;
+  }
+  if (!capabilityExists(doc, to)) {
+    return to;
+  }
+  throw new Error(
+    `Capability "${to}" already exists (check capabilities[], openapi.operations, execution.cip.operations). ` +
+      'Use --overwrite to replace it, or choose another --as name.'
+  );
+}
+
+/**
+ * @param {unknown} o
+ * @returns {unknown}
+ */
+function deepClone(o) {
+  return JSON.parse(JSON.stringify(o));
+}
+
+/**
+ * When opts.basicExposure is true, refuse to clobber an existing profile row unless overwriting.
+ *
+ * @param {object} doc
+ * @param {string} resolvedAs
+ * @param {boolean} overwrite
+ * @param {boolean} basicExposure
+ * @returns {void}
+ * @throws {Error}
+ */
+function assertBasicExposureSlot(doc, resolvedAs, overwrite, basicExposure) {
+  if (!basicExposure || overwrite) {
+    return;
+  }
+  if (doc.exposed?.profiles?.[resolvedAs]) {
+    throw new Error(
+      `exposed.profiles.${resolvedAs} already exists. Use --overwrite or choose another --as name.`
+    );
+  }
+}
+
+/**
+ * Copy exposed.profiles[from] → exposed.profiles[resolvedAs], or synthesize basic profile at resolvedAs.
+ *
+ * @param {object} doc
+ * @param {object} opts
+ * @param {string} from - Source capability key (matches profiles[from])
+ * @param {string} resolvedAs - Target capability key (matches profiles[resolvedAs])
+ * @param {object[]} patchOperations
+ * @param {string[]} updatedSections
+ * @returns {void}
+ */
+function copyExposedProfile(doc, opts, logicalFrom, resolvedAs, patchOperations, updatedSections) {
+  if (!doc.exposed) {
+    doc.exposed = {};
+  }
+  if (!doc.exposed.profiles) {
+    doc.exposed.profiles = {};
+  }
+
+  if (opts.basicExposure) {
+    const value = buildBasicExposureProfileArray(doc);
+    doc.exposed.profiles[resolvedAs] = value;
+    patchOperations.push({
+      op: 'add',
+      path: jsonPointerPath('exposed', 'profiles', resolvedAs),
+      value
+    });
+    updatedSections.push(`exposed.profiles.${resolvedAs} (basic from metadataSchema)`);
+    return;
+  }
+
+  const profileFrom = resolveProfileKeyForLogical(doc, logicalFrom);
+  if (profileFrom !== null && doc.exposed.profiles[profileFrom] !== undefined) {
+    doc.exposed.profiles[resolvedAs] = deepClone(doc.exposed.profiles[profileFrom]);
+    patchOperations.push({
+      op: 'add',
+      path: jsonPointerPath('exposed', 'profiles', resolvedAs),
+      value: doc.exposed.profiles[resolvedAs]
+    });
+    updatedSections.push(`exposed.profiles.${resolvedAs}`);
+  }
+}
+
+/**
+ * @param {object} doc
+ * @param {string} from
+ * @param {string} resolvedAs
+ * @param {object[]} patchOperations
+ * @param {string[]} updatedSections
+ * @returns {void}
+ */
+function installClonedOperations(doc, fromKeys, resolvedAs, patchOperations, updatedSections) {
+  const { openapiKey, cipKey, logicalFrom } = fromKeys;
+  const targetOpsKey = storageOpsKey(resolvedAs);
+
+  const openapiClone = deepClone(doc.openapi.operations[openapiKey]);
+  rewriteCapabilityReferences(openapiClone, openapiKey, targetOpsKey);
+  if (logicalFrom !== openapiKey) {
+    rewriteCapabilityReferences(openapiClone, logicalFrom, targetOpsKey);
+  }
+  const cipClone = deepClone(doc.execution.cip.operations[cipKey]);
+  rewriteCapabilityReferences(cipClone, cipKey, targetOpsKey);
+  if (logicalFrom !== cipKey) {
+    rewriteCapabilityReferences(cipClone, logicalFrom, targetOpsKey);
+  }
+
+  if (!doc.openapi.operations) {
+    doc.openapi.operations = {};
+  }
+  if (!doc.execution.cip.operations) {
+    doc.execution.cip.operations = {};
+  }
+
+  doc.openapi.operations[targetOpsKey] = openapiClone;
+  patchOperations.push({
+    op: 'add',
+    path: jsonPointerPath('openapi', 'operations', targetOpsKey),
+    value: openapiClone
+  });
+  updatedSections.push(`openapi.operations.${targetOpsKey} (logical ${resolvedAs})`);
+
+  doc.execution.cip.operations[targetOpsKey] = cipClone;
+  patchOperations.push({
+    op: 'add',
+    path: jsonPointerPath('execution', 'cip', 'operations', targetOpsKey),
+    value: cipClone
+  });
+  updatedSections.push(`execution.cip.operations.${targetOpsKey} (logical ${resolvedAs})`);
+}
+
+/**
+ * Install already-cloned openapi + CIP slices under storage key (no source read).
+ *
+ * @param {object} doc
+ * @param {string} resolvedAs - Logical capability name (capabilities[])
+ * @param {{ targetOpsKey: string, openapiClone: object, cipClone: object }} slices
+ * @param {object[]} patchOperations
+ * @param {string[]} updatedSections
+ * @returns {void}
+ */
+function installPreparedSlices(doc, resolvedAs, slices, patchOperations, updatedSections) {
+  const { targetOpsKey, openapiClone, cipClone } = slices;
+  if (!doc.openapi.operations) {
+    doc.openapi.operations = {};
+  }
+  if (!doc.execution.cip.operations) {
+    doc.execution.cip.operations = {};
+  }
+
+  doc.openapi.operations[targetOpsKey] = openapiClone;
+  patchOperations.push({
+    op: 'add',
+    path: jsonPointerPath('openapi', 'operations', targetOpsKey),
+    value: openapiClone
+  });
+  updatedSections.push(`openapi.operations.${targetOpsKey} (logical ${resolvedAs})`);
+
+  doc.execution.cip.operations[targetOpsKey] = cipClone;
+  patchOperations.push({
+    op: 'add',
+    path: jsonPointerPath('execution', 'cip', 'operations', targetOpsKey),
+    value: cipClone
+  });
+  updatedSections.push(`execution.cip.operations.${targetOpsKey} (logical ${resolvedAs})`);
+}
+
+/**
+ * @param {object} doc
+ * @param {string} resolvedAs
+ * @param {object[]} patchOperations
+ * @param {string[]} updatedSections
+ * @returns {void}
+ */
+function appendCapabilityList(doc, resolvedAs, patchOperations, updatedSections) {
+  if (!Array.isArray(doc.capabilities)) {
+    doc.capabilities = [];
+  }
+  if (doc.capabilities.includes(resolvedAs)) {
+    return;
+  }
+  doc.capabilities.push(resolvedAs);
+  patchOperations.push({
+    op: 'add',
+    path: '/capabilities/-',
+    value: resolvedAs
+  });
+  updatedSections.push(`capabilities[]: ${resolvedAs}`);
+}
+
+/**
+ * Apply capability copy on a deep clone of the document.
+ *
+ * @param {object} originalDoc - Parsed datasource JSON
+ * @param {object} opts - Options
+ * @param {string} opts.from - Source capability key
+ * @param {string} opts.to - Desired target key
+ * @param {boolean} [opts.overwrite=false]
+ * @param {boolean} [opts.basicExposure=false] - Build minimal profile from metadataSchema at exposed.profiles[to]
+ * @param {boolean} [opts.includeTestPayload=false] - Clone matching testPayload.scenarios rows to target operation
+ * @returns {{
+ *   doc: object,
+ *   resolvedAs: string,
+ *   patchOperations: object[],
+ *   updatedSections: string[]
+ * }}
+ */
+function applyCapabilityCopy(originalDoc, opts) {
+  const doc = deepClone(originalDoc);
+  const logicalFrom = resolveSourceCapabilityForCopy(doc, opts.from);
+  const { openapiKey, cipKey } = resolveOpsKeysForCapability(doc, logicalFrom);
+
+  const openapiFrom = doc.openapi?.operations?.[openapiKey];
+  const cipFrom = doc.execution?.cip?.operations?.[cipKey];
+
+  if (!openapiFrom) {
+    throw new Error(`Missing openapi.operations.${openapiKey}`);
+  }
+  if (!cipFrom) {
+    throw new Error(`Missing execution.cip.operations.${cipKey}`);
+  }
+
+  const resolvedAs = resolveTargetKey(doc, opts.to, Boolean(opts.overwrite));
+  assertBasicExposureSlot(doc, resolvedAs, Boolean(opts.overwrite), Boolean(opts.basicExposure));
+
+  const patchOperations = [];
+  const updatedSections = [];
+
+  if (opts.overwrite && capabilityLogicalExists(doc, resolvedAs)) {
+    removeCapability(doc, resolvedAs);
+  }
+
+  installClonedOperations(
+    doc,
+    { openapiKey, cipKey, logicalFrom },
+    resolvedAs,
+    patchOperations,
+    updatedSections
+  );
+  appendCapabilityList(doc, resolvedAs, patchOperations, updatedSections);
+  copyExposedProfile(doc, opts, logicalFrom, resolvedAs, patchOperations, updatedSections);
+  copyTestPayloadScenarios(
+    doc,
+    opts,
+    { openapiKey, cipKey, logicalFrom },
+    resolvedAs,
+    patchOperations,
+    updatedSections
+  );
+
+  return {
+    doc,
+    resolvedAs,
+    patchOperations,
+    updatedSections
+  };
+}
+
+module.exports = {
+  applyCapabilityCopy,
+  capabilityExists,
+  capabilityLogicalExists,
+  resolveTargetKey,
+  deepClone,
+  removeCapability,
+  installPreparedSlices,
+  appendCapabilityList,
+  copyExposedProfile,
+  assertBasicExposureSlot
+};