@aifabrix/builder 2.44.5 → 2.44.6

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

@@ -0,0 +1,219 @@
+/**
+ * Semantic validation for `datasource capability dimension`.
+ *
+ * Pure validation module: no CLI/auth logic.
+ *
+ * @fileoverview dimension binding semantic validator
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+function _asObject(x) {
+  return x && typeof x === 'object' && !Array.isArray(x) ? x : null;
+}
+
+function _getMetadataProp(doc, fieldName) {
+  const props = doc?.metadataSchema?.properties;
+  if (!props || typeof props !== 'object') return null;
+  const node = props[fieldName];
+  return _asObject(node);
+}
+
+function _collectForeignKeyNameSet(doc) {
+  const fks = Array.isArray(doc?.foreignKeys) ? doc.foreignKeys : [];
+  const out = new Set();
+  for (const fk of fks) {
+    const name = typeof fk?.name === 'string' ? fk.name.trim() : '';
+    if (name) out.add(name);
+  }
+  return out;
+}
+
+function _findForeignKeyRow(doc, name) {
+  const fks = Array.isArray(doc?.foreignKeys) ? doc.foreignKeys : [];
+  return fks.find((fk) => fk && fk.name === name) || null;
+}
+
+/**
+ * @typedef {Object} DimensionVia
+ * @property {string} fk
+ * @property {string} dimension
+ */
+
+/**
+ * @typedef {Object} DimensionLocalContext
+ * @property {any} sourceDoc
+ * @property {string} dimensionKey
+ * @property {'local'|'fk'} type
+ * @property {string|undefined} field
+ * @property {DimensionVia[]|undefined} via
+ */
+
+/**
+ * @typedef {Object} DimensionValidationInput
+ * @property {DimensionLocalContext} localContext
+ * @property {Record<string, any>|null} remoteTargetsByKey - map: datasourceKey -> datasource config
+ * @property {Set<string>|null} catalogDimensionKeys - dimension catalog keys when available
+ */
+
+/**
+ * @typedef {Object} DimensionValidationResult
+ * @property {boolean} ok
+ * @property {string[]} errors
+ * @property {string[]} warnings
+ * @property {{ targetDatasourceKeys: string[] }} resolved
+ */
+
+/**
+ * @param {DimensionValidationInput} input
+ * @returns {DimensionValidationResult}
+ */
+function validateDimensionSemantics(input) {
+  const errors = [];
+  const warnings = [];
+  const ctx = _normalizeInputOrReport(input, errors);
+  if (!ctx) return { ok: false, errors, warnings, resolved: { targetDatasourceKeys: [] } };
+
+  _validateCatalogKey({ input, dimensionKey: ctx.dimensionKey, errors });
+
+  if (ctx.type === 'local') {
+    _validateLocalBinding({ source: ctx.sourceDoc, field: ctx.field, errors });
+    return { ok: errors.length === 0, errors, warnings, resolved: { targetDatasourceKeys: [] } };
+  }
+
+  const { targetDatasourceKeys } = _validateFkBinding({
+    source: ctx.sourceDoc,
+    via: ctx.via,
+    remoteTargetsByKey: input?.remoteTargetsByKey,
+    errors,
+    warnings
+  });
+  return { ok: errors.length === 0, errors, warnings, resolved: { targetDatasourceKeys } };
+}
+
+function _normalizeInputOrReport(input, errors) {
+  const local = input?.localContext;
+  const sourceDoc = local?.sourceDoc;
+  if (!_asObject(sourceDoc)) {
+    errors.push('Local validation failed: sourceDoc missing or invalid.');
+    return null;
+  }
+  const dimensionKey = String(local?.dimensionKey || '').trim();
+  if (!dimensionKey) {
+    errors.push('Local validation failed: dimensionKey missing or invalid.');
+    return null;
+  }
+  const type = local?.type;
+  if (type !== 'local' && type !== 'fk') {
+    errors.push('Local validation failed: type must be "local" or "fk".');
+    return null;
+  }
+  return {
+    sourceDoc,
+    dimensionKey,
+    type,
+    field: local?.field,
+    via: local?.via
+  };
+}
+
+function _validateCatalogKey({ input, dimensionKey, errors }) {
+  if (input?.catalogDimensionKeys instanceof Set) {
+    if (!input.catalogDimensionKeys.has(dimensionKey)) {
+      errors.push(`Unknown dimension key (not found in dimension catalog): ${dimensionKey}`);
+    }
+  }
+}
+
+function _validateLocalBinding({ source, field, errors }) {
+  const f = String(field || '').trim();
+  if (!f) {
+    errors.push('Local validation failed: --field is required for type=local.');
+    return;
+  }
+  const node = _getMetadataProp(source, f);
+  if (!node) {
+    errors.push(`Source field not found in metadataSchema.properties: ${f}`);
+  }
+}
+
+function _validateFkBinding({ source, via, remoteTargetsByKey, errors, warnings }) {
+  const hops = Array.isArray(via) ? via : [];
+  if (hops.length === 0) {
+    errors.push('Local validation failed: at least one via entry is required for type=fk.');
+    return { targetDatasourceKeys: [] };
+  }
+
+  const fkNameSet = _collectForeignKeyNameSet(source);
+  const targets = _asObject(remoteTargetsByKey) ? remoteTargetsByKey : {};
+  const targetDatasourceKeys = [];
+
+  hops.forEach((hop) => {
+    const resolved = _validateViaHop({
+      source,
+      fkNameSet,
+      hop,
+      errors,
+      warnings
+    });
+    if (!resolved) return;
+    targetDatasourceKeys.push(resolved.targetDatasource);
+    _validateTargetDimensionIfAvailable({
+      targets,
+      targetDatasource: resolved.targetDatasource,
+      targetDimKey: resolved.targetDimKey,
+      errors
+    });
+  });
+
+  return { targetDatasourceKeys };
+}
+
+function _validateViaHop({ source, fkNameSet, hop, errors, warnings }) {
+  const fkName = String(hop?.fk || '').trim();
+  const targetDimKey = String(hop?.dimension || '').trim();
+  if (!fkName) {
+    errors.push('via[].fk must be a non-empty string.');
+    return null;
+  }
+  if (!targetDimKey) {
+    errors.push('via[].dimension must be a non-empty string.');
+    return null;
+  }
+  if (!/^[a-zA-Z0-9_]+$/.test(targetDimKey)) {
+    errors.push(`via[].dimension "${targetDimKey}" must match ^[a-zA-Z0-9_]+$`);
+  }
+  if (!fkNameSet.has(fkName)) {
+    errors.push(`Foreign key not found in foreignKeys[].name: ${fkName}`);
+    return null;
+  }
+  const targetDatasource = _resolveTargetDatasourceFromFk(source, fkName);
+  if (!targetDatasource) {
+    warnings.push(`Foreign key "${fkName}" has no targetDatasource; remote validation skipped for this hop.`);
+    return null;
+  }
+  return { targetDatasource, targetDimKey };
+}
+
+function _resolveTargetDatasourceFromFk(source, fkName) {
+  const fkRow = _findForeignKeyRow(source, fkName);
+  const targetDatasource = typeof fkRow?.targetDatasource === 'string' ? fkRow.targetDatasource.trim() : '';
+  return targetDatasource || '';
+}
+
+function _validateTargetDimensionIfAvailable({ targets, targetDatasource, targetDimKey, errors }) {
+  const targetCfg = targets[targetDatasource];
+  if (!targetCfg) return;
+  const dims = targetCfg?.dimensions;
+  const okDims = dims && typeof dims === 'object' && !Array.isArray(dims);
+  if (!okDims || !(targetDimKey in dims)) {
+    errors.push(`Target dimension not found: ${targetDatasource}.dimensions.${targetDimKey}`);
+  }
+}
+
+module.exports = {
+  validateDimensionSemantics
+};
+

package/lib/datasource/capability/json-pointer.js

@@ -0,0 +1,31 @@
+/**
+ * JSON Pointer segment escaping for RFC 6902 paths.
+ *
+ * @fileoverview JSON Pointer helpers
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * @param {string} token - Unescaped segment
+ * @returns {string}
+ */
+function escapeJsonPointerToken(token) {
+  return String(token).replace(/~/g, '~0').replace(/\//g, '~1');
+}
+
+/**
+ * @param {...string} segments
+ * @returns {string} Path starting with /
+ */
+function jsonPointerPath(...segments) {
+  if (segments.length === 0) {
+    return '';
+  }
+  return `/${segments.map(escapeJsonPointerToken).join('/')}`;
+}
+
+module.exports = {
+  escapeJsonPointerToken,
+  jsonPointerPath
+};

package/lib/datasource/capability/reference-rewrite.js

@@ -0,0 +1,51 @@
+/**
+ * Rewrite intra-document capability references when cloning an operation.
+ *
+ * @fileoverview Structured reference rewrite (no blind string replace)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/** Keys whose string values may reference another capability name */
+const REFERENCE_KEYS = new Set([
+  'openapiRef',
+  'operation',
+  'operationRef',
+  'capability',
+  'dependsOn',
+  'sourceOperation'
+]);
+
+/**
+ * Deep-walk `node` and replace reference string values `from` → `to`.
+ *
+ * @param {unknown} node - JSON subtree (openapi operation or CIP operation)
+ * @param {string} from - Source capability key
+ * @param {string} to - Target capability key
+ * @returns {void}
+ */
+function rewriteCapabilityReferences(node, from, to) {
+  if (node === null || node === undefined) {
+    return;
+  }
+  if (Array.isArray(node)) {
+    node.forEach((item) => rewriteCapabilityReferences(item, from, to));
+    return;
+  }
+  if (typeof node !== 'object') {
+    return;
+  }
+  for (const key of Object.keys(node)) {
+    const val = node[key];
+    if (REFERENCE_KEYS.has(key) && val === from) {
+      node[key] = to;
+    } else if (typeof val === 'object') {
+      rewriteCapabilityReferences(val, from, to);
+    }
+  }
+}
+
+module.exports = {
+  rewriteCapabilityReferences,
+  REFERENCE_KEYS
+};

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

@@ -0,0 +1,325 @@
+/**
+ * Metadata-only foreign key updates for datasource JSON (plan 132 Phase 4).
+ *
+ * @fileoverview capability relate — foreignKeys[] (+ optional metadataSchema property)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { jsonPointerPath } = require('./json-pointer');
+
+/**
+ * @param {unknown} o
+ * @returns {unknown}
+ */
+function deepClone(o) {
+  return JSON.parse(JSON.stringify(o));
+}
+
+function _asObject(x) {
+  return x && typeof x === 'object' ? x : null;
+}
+
+function _uniqStrings(list) {
+  const out = [];
+  const seen = new Set();
+  for (const x of list || []) {
+    const s = String(x || '').trim();
+    if (!s || seen.has(s)) continue;
+    seen.add(s);
+    out.push(s);
+  }
+  return out;
+}
+
+function _getTargetMetaProps(targetDoc) {
+  const props = targetDoc?.metadataSchema?.properties;
+  return props && typeof props === 'object' ? props : null;
+}
+
+function _buildRelationMetadataSchema({ relationName, targetDoc, resolvedTargetFields }) {
+  // Fallback to a minimal stub when we cannot derive target metadata.
+  const targetProps = _getTargetMetaProps(targetDoc);
+  if (!targetProps) {
+    return {
+      type: 'object',
+      nullable: true,
+      description: `Resolved relation via FK "${relationName}"`
+    };
+  }
+
+  const include = _uniqStrings([
+    ...(Array.isArray(resolvedTargetFields) ? resolvedTargetFields : []),
+    ...(Array.isArray(targetDoc?.primaryKey) ? targetDoc.primaryKey : []),
+    ...(Array.isArray(targetDoc?.labelKey) ? targetDoc.labelKey : [])
+  ]);
+
+  /** @type {Record<string, any>} */
+  const properties = {};
+  for (const f of include) {
+    const node = targetProps[f];
+    if (_asObject(node)) {
+      properties[f] = deepClone(node);
+    }
+  }
+
+  const requiredFromTarget = Array.isArray(targetDoc?.metadataSchema?.required) ? targetDoc.metadataSchema.required : [];
+  const required = requiredFromTarget.filter((x) => include.includes(String(x)));
+
+  const out = {
+    type: 'object',
+    nullable: true,
+    description: `Resolved relation via FK "${relationName}"`,
+    properties
+  };
+  if (required.length > 0) {
+    out.required = required;
+  }
+  return out;
+}
+
+/**
+ * FK `name` must match schema: ^[a-z][a-zA-Z0-9]*$
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+function normalizeRelationName(raw) {
+  const s = String(raw || '').trim();
+  if (!s) {
+    throw new Error('--relation-name is required');
+  }
+  if (!/^[a-z][a-zA-Z0-9]*$/.test(s)) {
+    throw new Error(
+      `--relation-name "${s}" must match ^[a-z][a-zA-Z0-9]*$ (camelCase)`
+    );
+  }
+  return s;
+}
+
+/**
+ * @param {string} raw
+ * @returns {string}
+ */
+function normalizeTargetDatasource(raw) {
+  const s = String(raw || '').trim();
+  if (!s) {
+    throw new Error('--to <targetDatasource> is required');
+  }
+  if (!/^[a-z0-9-]+$/.test(s)) {
+    throw new Error(
+      `--to "${s}" must match targetDatasource pattern (lowercase letters, digits, hyphens)`
+    );
+  }
+  return s;
+}
+
+/**
+ * @param {object} d - Mutated doc clone
+ * @param {object} fkRow
+ * @param {string} relationName
+ * @param {object[]} patchOperations
+ * @param {string[]} updatedSections
+ * @returns {boolean} replaced existing row
+ */
+function upsertForeignKeyRow(d, fkRow, relationName, patchOperations, updatedSections) {
+  const idx = d.foreignKeys.findIndex((fk) => fk && fk.name === relationName);
+  if (idx >= 0) {
+    d.foreignKeys[idx] = fkRow;
+    patchOperations.push({
+      op: 'replace',
+      path: `/foreignKeys/${idx}`,
+      value: fkRow
+    });
+    updatedSections.push(`foreignKeys.${relationName} → ${fkRow.targetDatasource}`);
+    return true;
+  }
+  d.foreignKeys.push(fkRow);
+  patchOperations.push({
+    op: 'add',
+    path: '/foreignKeys/-',
+    value: fkRow
+  });
+  updatedSections.push(`foreignKeys.${relationName} → ${fkRow.targetDatasource}`);
+  return false;
+}
+
+function _buildDefaultFkDescription({ fields, targetDatasource, resolvedTargetFields }) {
+  const left = Array.isArray(fields) ? fields.join(',') : String(fields || '');
+  const tf = Array.isArray(resolvedTargetFields) && resolvedTargetFields.length > 0 ? resolvedTargetFields : null;
+  const right = tf ? `${targetDatasource}.${tf.join(',')}` : targetDatasource;
+  return `Foreign key join: ${left} → ${right}`;
+}
+
+/**
+ * @param {object} d
+ * @param {string} name
+ * @param {object[]} patchOperations
+ * @param {string[]} updatedSections
+ * @returns {void}
+ */
+function addMetadataPropertyStub(d, name, patchOperations, updatedSections, options = {}) {
+  if (!d.metadataSchema) {
+    d.metadataSchema = { type: 'object', properties: {} };
+  }
+  if (!d.metadataSchema.properties) {
+    d.metadataSchema.properties = {};
+  }
+  const exists = Boolean(d.metadataSchema.properties[name]);
+
+  const metaBlock = _buildRelationMetadataSchema({
+    relationName: name,
+    targetDoc: options.targetDoc || null,
+    resolvedTargetFields: options.resolvedTargetFields || null
+  });
+
+  if (exists) {
+    // On overwrite, keep any existing description to avoid wiping user-authored docs.
+    const existingDesc = d.metadataSchema.properties[name]?.description;
+    if (existingDesc) {
+      metaBlock.description = existingDesc;
+    }
+    d.metadataSchema.properties[name] = metaBlock;
+    patchOperations.push({
+      op: 'replace',
+      path: jsonPointerPath('metadataSchema', 'properties', name),
+      value: metaBlock
+    });
+    updatedSections.push(`metadataSchema.properties.${name}`);
+    return;
+  }
+
+  d.metadataSchema.properties[name] = metaBlock;
+  patchOperations.push({
+    op: 'add',
+    path: jsonPointerPath('metadataSchema', 'properties', name),
+    value: metaBlock
+  });
+  updatedSections.push(`metadataSchema.properties.${name}`);
+}
+
+/**
+ * @param {object} opts
+ * @returns {{ fields: string[], targetFields: string[] | undefined }}
+ */
+function parseRelateFields(opts) {
+  const fields = Array.isArray(opts.fields)
+    ? opts.fields.map((f) => String(f).trim()).filter(Boolean)
+    : [];
+  if (fields.length === 0) {
+    throw new Error('Provide at least one --field <name>');
+  }
+  const targetFields =
+    Array.isArray(opts.targetFields) && opts.targetFields.length > 0
+      ? opts.targetFields.map((f) => String(f).trim()).filter(Boolean)
+      : undefined;
+  return { fields, targetFields };
+}
+
+/**
+ * @param {object} d - mutated clone
+ * @param {string} name
+ * @param {boolean} overwrite
+ * @returns {boolean} whether an existing row was found
+ */
+function assertOverwriteAllowedAndGetExisting(d, name, overwrite) {
+  const idx0 = d.foreignKeys.findIndex((fk) => fk && fk.name === name);
+  if (idx0 >= 0 && !overwrite) {
+    throw new Error(
+      `foreignKeys[].name "${name}" already exists; pass --overwrite to replace`
+    );
+  }
+  return idx0 >= 0;
+}
+
+/**
+ * @param {string} name
+ * @param {string[]} fields
+ * @param {string} targetDatasource
+ * @param {string[] | undefined} targetFields
+ * @param {object} [options]
+ * @param {object|null} [options.existingRow]
+ * @param {boolean|undefined} [options.required]
+ * @param {string|undefined} [options.description]
+ * @param {string[]|undefined|null} [options.resolvedTargetFields]
+ * @returns {object}
+ */
+function buildForeignKeyRow(name, fields, targetDatasource, targetFields, options = {}) {
+  const fkRow = { name, fields, targetDatasource };
+  if (targetFields && targetFields.length > 0) {
+    fkRow.targetFields = targetFields;
+  }
+  const existing = options.existingRow && typeof options.existingRow === 'object' ? options.existingRow : null;
+  const required =
+    options.required !== undefined && options.required !== null
+      ? Boolean(options.required)
+      : existing?.required;
+  if (required !== undefined) {
+    fkRow.required = Boolean(required);
+  } else {
+    // Default for new FKs: explicit optional unless user marks required.
+    fkRow.required = false;
+  }
+
+  const description = typeof options.description === 'string' && options.description.trim()
+    ? options.description.trim()
+    : existing?.description;
+  if (typeof description === 'string' && description.trim()) {
+    fkRow.description = description.trim();
+  } else {
+    fkRow.description = _buildDefaultFkDescription({
+      fields,
+      targetDatasource,
+      resolvedTargetFields: options.resolvedTargetFields || null
+    });
+  }
+  return fkRow;
+}
+
+/**
+ * @param {object} doc
+ * @param {object} opts
+ * @returns {{
+ *   doc: object,
+ *   patchOperations: object[],
+ *   updatedSections: string[],
+ *   replaced: boolean
+ * }}
+ */
+function applyCapabilityRelate(doc, opts) {
+  const name = normalizeRelationName(opts.relationName);
+  const targetDatasource = normalizeTargetDatasource(opts.targetDatasource);
+  const { fields, targetFields } = parseRelateFields(opts);
+
+  const d = deepClone(doc);
+  if (!Array.isArray(d.foreignKeys)) {
+    d.foreignKeys = [];
+  }
+
+  const replaced = assertOverwriteAllowedAndGetExisting(d, name, Boolean(opts.overwrite));
+  const existingRow = replaced ? d.foreignKeys.find((fk) => fk && fk.name === name) : null;
+  const fkRow = buildForeignKeyRow(name, fields, targetDatasource, targetFields, {
+    existingRow,
+    required: opts.required,
+    description: opts.description,
+    resolvedTargetFields: opts.resolvedTargetFields
+  });
+  const patchOperations = [];
+  const updatedSections = [];
+  upsertForeignKeyRow(d, fkRow, name, patchOperations, updatedSections);
+
+  if (opts.addMetadataProperty !== false) {
+    addMetadataPropertyStub(d, name, patchOperations, updatedSections, {
+      targetDoc: opts.targetDoc,
+      resolvedTargetFields: opts.resolvedTargetFields
+    });
+  }
+
+  return { doc: d, patchOperations, updatedSections, replaced };
+}
+
+module.exports = {
+  applyCapabilityRelate,
+  normalizeRelationName,
+  normalizeTargetDatasource
+};