@aifabrix/builder 2.44.5 → 2.45.0

package/lib/datasource/capability/copy-test-payload.js

@@ -0,0 +1,139 @@
+/**
+ * Clone testPayload.scenarios rows when copying a capability.
+ *
+ * @fileoverview Used by applyCapabilityCopy when includeTestPayload is true
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { jsonPointerPath } = require('./json-pointer');
+const { storageOpsKey } = require('./capability-storage-keys');
+
+/**
+ * @param {unknown} o
+ * @returns {unknown}
+ */
+function deepClone(o) {
+  return JSON.parse(JSON.stringify(o));
+}
+
+/**
+ * @param {object[]} initialScenarios
+ * @param {Set<string>} aliases
+ * @param {string} resolvedAs
+ * @param {boolean} overwrite
+ * @returns {{ sourceMatches: object[], finalScenarios: object[] }}
+ */
+function computeScenarioClone(initialScenarios, aliases, resolvedAs, overwrite) {
+  const sourceMatches = initialScenarios.filter((s) => s && aliases.has(s.operation));
+  let base = [...initialScenarios];
+  if (overwrite) {
+    const lower = String(resolvedAs).toLowerCase();
+    base = base.filter((s) => !s || String(s.operation).toLowerCase() !== lower);
+  }
+  const opKey = storageOpsKey(resolvedAs);
+  const clones = sourceMatches.map((s) => {
+    const c = deepClone(s);
+    c.operation = opKey;
+    return c;
+  });
+  return { sourceMatches, clones, finalScenarios: [...base, ...clones] };
+}
+
+/**
+ * Dry-run JSON Patch: only the additions (incremental array append or new testPayload.scenarios).
+ *
+ * @param {boolean} hadTestPayloadRoot
+ * @param {boolean} hadScenariosArray
+ * @param {object[]} clones - New scenario rows only
+ * @param {object[]} patchOperations
+ * @returns {void}
+ */
+function pushTestPayloadScenarioPatches(
+  hadTestPayloadRoot,
+  hadScenariosArray,
+  clones,
+  patchOperations
+) {
+  if (clones.length === 0) {
+    return;
+  }
+  const clonedRows = clones.map((c) => deepClone(c));
+
+  if (!hadTestPayloadRoot) {
+    patchOperations.push({
+      op: 'add',
+      path: '/testPayload',
+      value: { scenarios: clonedRows }
+    });
+    return;
+  }
+  if (!hadScenariosArray) {
+    patchOperations.push({
+      op: 'add',
+      path: jsonPointerPath('testPayload', 'scenarios'),
+      value: clonedRows
+    });
+    return;
+  }
+  for (const row of clonedRows) {
+    patchOperations.push({
+      op: 'add',
+      path: '/testPayload/scenarios/-',
+      value: row
+    });
+  }
+}
+
+/**
+ * @param {object} doc
+ * @param {object} opts
+ * @param {{ openapiKey: string, cipKey: string, logicalFrom: string }} fromKeys
+ * @param {string} resolvedAs
+ * @param {object[]} patchOperations
+ * @param {string[]} updatedSections
+ * @returns {void}
+ */
+function copyTestPayloadScenarios(doc, opts, fromKeys, resolvedAs, patchOperations, updatedSections) {
+  if (!opts.includeTestPayload) {
+    return;
+  }
+  const { openapiKey, cipKey, logicalFrom } = fromKeys;
+  const aliases = new Set([logicalFrom, openapiKey, cipKey].filter(Boolean));
+
+  const initialScenarios = Array.isArray(doc.testPayload?.scenarios)
+    ? doc.testPayload.scenarios
+    : [];
+
+  const hadTestPayloadRoot =
+    doc.testPayload !== undefined &&
+    doc.testPayload !== null &&
+    typeof doc.testPayload === 'object';
+  const hadScenariosArray = hadTestPayloadRoot && Array.isArray(doc.testPayload.scenarios);
+
+  const { sourceMatches, clones, finalScenarios } = computeScenarioClone(
+    initialScenarios,
+    aliases,
+    resolvedAs,
+    Boolean(opts.overwrite)
+  );
+
+  if (sourceMatches.length === 0) {
+    updatedSections.push('testPayload.scenarios: (no rows matched source operation)');
+    return;
+  }
+
+  if (!doc.testPayload) {
+    doc.testPayload = {};
+  }
+  doc.testPayload.scenarios = finalScenarios;
+
+  pushTestPayloadScenarioPatches(hadTestPayloadRoot, hadScenariosArray, clones, patchOperations);
+  updatedSections.push(
+    `testPayload.scenarios: +${sourceMatches.length} clone(s) → operation "${resolvedAs}"`
+  );
+}
+
+module.exports = {
+  copyTestPayloadScenarios
+};

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

@@ -0,0 +1,235 @@
+/**
+ * Create capability without --from: OpenAPI operationId match or JSON template.
+ *
+ * @fileoverview Plan 132 Phase 3 — template / openapi-operation create
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const path = require('path');
+const fsReal = require('../../internal/fs-real-sync');
+const {
+  applyCapabilityCopy,
+  deepClone,
+  removeCapability,
+  installPreparedSlices,
+  appendCapabilityList,
+  copyExposedProfile,
+  assertBasicExposureSlot,
+  resolveTargetKey
+} = require('./copy-operations');
+const { rewriteCapabilityReferences } = require('./reference-rewrite');
+const { storageOpsKey } = require('./capability-storage-keys');
+const { capabilityLogicalExists } = require('./capability-resolve');
+
+/**
+ * @param {string} targetOpsKey
+ * @returns {object}
+ */
+function buildMinimalCip(targetOpsKey) {
+  return {
+    enabled: true,
+    steps: [{ fetch: { source: 'openapi', openapiRef: targetOpsKey } }]
+  };
+}
+
+/**
+ * @param {object} originalDoc
+ * @param {object} opts
+ * @returns {{ doc: object, resolvedAs: string, targetOpsKey: string }}
+ */
+function prepareDocForNewCapability(originalDoc, opts) {
+  const doc = deepClone(originalDoc);
+  const resolvedAs = resolveTargetKey(doc, opts.to, Boolean(opts.overwrite));
+  assertBasicExposureSlot(doc, resolvedAs, Boolean(opts.overwrite), Boolean(opts.basicExposure));
+  const targetOpsKey = storageOpsKey(resolvedAs);
+  if (opts.overwrite && capabilityLogicalExists(doc, resolvedAs)) {
+    removeCapability(doc, resolvedAs);
+  }
+  return { doc, resolvedAs, targetOpsKey };
+}
+
+/**
+ * @param {object} doc
+ * @param {string} resolvedAs
+ * @param {{ targetOpsKey: string, openapiClone: object, cipClone: object }} slices
+ * @param {object} opts
+ * @param {object[]} patchOperations
+ * @param {string[]} updatedSections
+ * @returns {void}
+ */
+function finalizeNewCapabilitySlices(doc, resolvedAs, slices, opts, patchOperations, updatedSections) {
+  installPreparedSlices(doc, resolvedAs, slices, patchOperations, updatedSections);
+  appendCapabilityList(doc, resolvedAs, patchOperations, updatedSections);
+  copyExposedProfile(
+    doc,
+    { basicExposure: Boolean(opts.basicExposure), includeTestPayload: false },
+    resolvedAs,
+    resolvedAs,
+    patchOperations,
+    updatedSections
+  );
+}
+
+/**
+ * @param {object} doc
+ * @param {string} operationId
+ * @returns {string[]}
+ */
+function findOpenapiKeysByOperationId(doc, operationId) {
+  const ops = doc.openapi?.operations;
+  if (!ops || typeof ops !== 'object') {
+    return [];
+  }
+  const want = String(operationId).trim().toLowerCase();
+  const keys = [];
+  for (const k of Object.keys(ops)) {
+    const oid = ops[k]?.operationId;
+    if (oid !== undefined && String(oid).trim().toLowerCase() === want) {
+      keys.push(k);
+    }
+  }
+  return keys;
+}
+
+/**
+ * @param {object} originalDoc
+ * @param {object} opts
+ * @param {string} opts.to
+ * @param {string} opts.openApiOperationId
+ * @param {boolean} [opts.overwrite]
+ * @param {boolean} [opts.basicExposure]
+ * @returns {object}
+ */
+function applyCreateFromOpenApiOperation(originalDoc, opts) {
+  const operationId = String(opts.openApiOperationId).trim();
+  const keys = findOpenapiKeysByOperationId(originalDoc, operationId);
+  if (keys.length === 0) {
+    throw new Error(`No openapi.operations entry with operationId "${operationId}"`);
+  }
+  if (keys.length > 1) {
+    throw new Error(
+      `Ambiguous operationId "${operationId}": openapi.operations keys ${keys.join(', ')}`
+    );
+  }
+  const sourceOpenapiKey = keys[0];
+  const { doc, resolvedAs, targetOpsKey } = prepareDocForNewCapability(originalDoc, opts);
+
+  const openapiClone = deepClone(doc.openapi.operations[sourceOpenapiKey]);
+  rewriteCapabilityReferences(openapiClone, sourceOpenapiKey, targetOpsKey);
+
+  const patchOperations = [];
+  const updatedSections = [];
+  finalizeNewCapabilitySlices(
+    doc,
+    resolvedAs,
+    { targetOpsKey, openapiClone, cipClone: buildMinimalCip(targetOpsKey) },
+    opts,
+    patchOperations,
+    updatedSections
+  );
+
+  return {
+    doc,
+    resolvedAs,
+    patchOperations,
+    updatedSections
+  };
+}
+
+/**
+ * @param {object} originalDoc
+ * @param {object} opts
+ * @param {string} opts.to
+ * @param {string} opts.template
+ * @param {boolean} [opts.overwrite]
+ * @param {boolean} [opts.basicExposure]
+ * @returns {object}
+ */
+function applyCreateFromTemplate(originalDoc, opts) {
+  const name = String(opts.template).trim();
+  const templatePath = path.join(__dirname, 'templates', `${name}.json`);
+  if (!fsReal.existsSync(templatePath)) {
+    throw new Error(`Unknown template "${name}" (not found next to capability templates)`);
+  }
+  const template = _readCapabilityTemplateOrThrow(templatePath, name);
+  if (!template.openapiOperation || !template.cipOperation) {
+    throw new Error('Template must include top-level openapiOperation and cipOperation objects');
+  }
+
+  const { doc, resolvedAs, targetOpsKey } = prepareDocForNewCapability(originalDoc, opts);
+  const openapiClone = deepClone(template.openapiOperation);
+  const cipJson = JSON.stringify(template.cipOperation).replace(/__STORAGE_KEY__/g, targetOpsKey);
+  const cipClone = JSON.parse(cipJson);
+
+  const patchOperations = [];
+  const updatedSections = [];
+  finalizeNewCapabilitySlices(
+    doc,
+    resolvedAs,
+    { targetOpsKey, openapiClone, cipClone },
+    opts,
+    patchOperations,
+    updatedSections
+  );
+
+  return {
+    doc,
+    resolvedAs,
+    patchOperations,
+    updatedSections
+  };
+}
+
+function _readCapabilityTemplateOrThrow(templatePath, name) {
+  let templateRaw;
+  try {
+    templateRaw = fsReal.readFileSync(templatePath, 'utf8');
+  } catch (e) {
+    // Jest suites may partially mock fs.existsSync; treat missing files as unknown template.
+    if (e && e.code === 'ENOENT') {
+      throw new Error(`Unknown template "${name}" (not found next to capability templates)`);
+    }
+    throw e;
+  }
+  return JSON.parse(templateRaw);
+}
+
+/**
+ * Exactly one of: opts.from, opts.openApiOperationId, opts.template.
+ *
+ * @param {object} originalDoc
+ * @param {object} opts
+ * @returns {object}
+ */
+function applyCapabilityCreate(originalDoc, opts) {
+  const hasFrom = opts.from !== undefined && opts.from !== null && String(opts.from).trim() !== '';
+  const hasOid =
+    opts.openApiOperationId !== undefined &&
+    opts.openApiOperationId !== null &&
+    String(opts.openApiOperationId).trim() !== '';
+  const hasTpl =
+    opts.template !== undefined && opts.template !== null && String(opts.template).trim() !== '';
+
+  const count = [hasFrom, hasOid, hasTpl].filter(Boolean).length;
+  if (count !== 1) {
+    throw new Error(
+      'Specify exactly one of: --from <key>, --template <name>, --openapi-operation <operationId>'
+    );
+  }
+
+  if (hasFrom) {
+    return applyCapabilityCopy(originalDoc, opts);
+  }
+  if (hasOid) {
+    return applyCreateFromOpenApiOperation(originalDoc, opts);
+  }
+  return applyCreateFromTemplate(originalDoc, opts);
+}
+
+module.exports = {
+  applyCapabilityCreate,
+  applyCreateFromOpenApiOperation,
+  applyCreateFromTemplate,
+  findOpenapiKeysByOperationId
+};

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

@@ -0,0 +1,151 @@
+/**
+ * Metadata-only dimension binding updates for datasource JSON.
+ *
+ * Writes root `dimensions.<dimensionKey>` binding (local or fk) with JSON Patch operations.
+ *
+ * @fileoverview capability dimension — dimensions{} binding upsert
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const { jsonPointerPath } = require('./json-pointer');
+
+/**
+ * @param {unknown} o
+ * @returns {any}
+ */
+function deepClone(o) {
+  return JSON.parse(JSON.stringify(o));
+}
+
+function _asObject(x) {
+  return x && typeof x === 'object' && !Array.isArray(x) ? x : null;
+}
+
+/**
+ * @param {string} raw
+ * @returns {string}
+ */
+function normalizeDimensionKey(raw) {
+  const s = String(raw || '').trim();
+  if (!s) {
+    throw new Error('--dimension <key> is required');
+  }
+  if (!/^[a-zA-Z0-9_]+$/.test(s)) {
+    throw new Error(`--dimension "${s}" must match ^[a-zA-Z0-9_]+$`);
+  }
+  return s;
+}
+
+/**
+ * @param {string} raw
+ * @returns {'local'|'fk'}
+ */
+function normalizeDimensionType(raw) {
+  const s = String(raw || '').trim().toLowerCase();
+  if (!s) {
+    throw new Error('--type <local|fk> is required');
+  }
+  if (s !== 'local' && s !== 'fk') {
+    throw new Error('--type must be "local" or "fk"');
+  }
+  return s;
+}
+
+/**
+ * @param {any} doc
+ * @param {string} dimKey
+ * @param {boolean} overwrite
+ * @returns {boolean} replaced
+ */
+function assertOverwriteAllowed(doc, dimKey, overwrite) {
+  const dims = doc?.dimensions;
+  const exists = Boolean(dims && typeof dims === 'object' && !Array.isArray(dims) && dims[dimKey] !== undefined);
+  if (exists && !overwrite) {
+    throw new Error(`dimensions.${dimKey} already exists; pass --overwrite to replace`);
+  }
+  return exists;
+}
+
+/**
+ * @param {object} opts
+ * @returns {object} dimensionBinding
+ */
+function buildDimensionBinding(opts) {
+  const type = normalizeDimensionType(opts.type);
+
+  if (type === 'local') {
+    const field = String(opts.field || '').trim();
+    if (!field) {
+      throw new Error('--field <normalizedAttr> is required for --type local');
+    }
+    return { type: 'local', field };
+  }
+
+  const via = Array.isArray(opts.via) ? opts.via : [];
+  if (via.length === 0) {
+    throw new Error('Provide at least one --via <fkName>:<dimensionKey> for --type fk');
+  }
+
+  /** @type {any} */
+  const binding = { type: 'fk', via };
+  if (opts.actor !== undefined && opts.actor !== null && String(opts.actor).trim()) {
+    binding.actor = String(opts.actor).trim();
+  }
+  if (opts.operator !== undefined && opts.operator !== null && String(opts.operator).trim()) {
+    binding.operator = String(opts.operator).trim();
+  }
+  if (opts.required !== undefined && opts.required !== null) {
+    binding.required = Boolean(opts.required);
+  }
+  return binding;
+}
+
+/**
+ * @param {any} doc
+ * @param {object} opts
+ * @returns {{
+ *   doc: any,
+ *   patchOperations: object[],
+ *   updatedSections: string[],
+ *   replaced: boolean
+ * }}
+ */
+function applyCapabilityDimension(doc, opts) {
+  const dimKey = normalizeDimensionKey(opts.dimension);
+  const d = deepClone(doc);
+
+  if (!_asObject(d.dimensions)) {
+    d.dimensions = {};
+  }
+
+  const replaced = assertOverwriteAllowed(d, dimKey, Boolean(opts.overwrite));
+  const binding = buildDimensionBinding(opts);
+
+  /** @type {object[]} */
+  const patchOperations = [];
+  /** @type {string[]} */
+  const updatedSections = [];
+
+  const path = jsonPointerPath('dimensions', dimKey);
+  if (replaced) {
+    d.dimensions[dimKey] = binding;
+    patchOperations.push({ op: 'replace', path, value: binding });
+  } else {
+    d.dimensions[dimKey] = binding;
+    patchOperations.push({ op: 'add', path, value: binding });
+  }
+  updatedSections.push(`dimensions.${dimKey}`);
+
+  return { doc: d, patchOperations, updatedSections, replaced };
+}
+
+module.exports = {
+  applyCapabilityDimension,
+  normalizeDimensionKey,
+  normalizeDimensionType,
+  buildDimensionBinding
+};
+