@wix/agent-skills 1.36.0 → 1.36.1

package/skills/wix-replatform/resources/rp-mapper/lib/mapping-resolve.js

@@ -1,217 +0,0 @@
-'use strict';
-
-// rp-mapper — DETERMINISTIC mapping resolution.
-//
-// Joins three inputs that are all already data:
-//
-//   discovered header set  ×  vendor overlay columnMap  ×  Wix target spec
-//
-// and answers, with no LLM involved:
-//
-//   - which source columns map to which canonical field, and by which alias (auditable)
-//   - which source columns NOTHING claims                  -> `residue.unmappedColumns`
-//   - which mapped columns have no Wix home                -> `residue.unsupportedTargets`
-//   - which REQUIRED Wix inputs nothing feeds              -> `residue.unfilledRequired`
-//   - which overlay entries reference a column not present  -> `overlayDrift`
-//
-// The agent's job collapses to the `residue` object. Everything else is computed, repeatable, and
-// diffable between runs — which is the point: an identical export must not produce a differently
-// worded mapping plan just because a model sampled differently.
-//
-// The overlay stays ADVISORY in the sense that matters: the authoritative column list is the header
-// row read at discovery time. An overlay can only claim columns that actually exist, and a column
-// the overlay does not know is surfaced, never dropped.
-
-const path = require('path');
-const fs = require('fs');
-const { CANONICAL_FIELDS, TARGETS, validateCanonicalPath } = require('../../rp-target-wix/lib/wix-target-spec.js');
-
-const VENDORS_DIR = path.join(__dirname, '..', '..', 'rp-source-csv', 'vendors');
-
-// Column identity is the NORMALIZED name: lowercase, NFKC, punctuation and whitespace stripped.
-// `Body (HTML)` -> `bodyhtml`, and `Option1 Name` === `Option 1 Name`. This absorbs vendor casing
-// and punctuation churn without a code change.
-function normalizeColumnName(name) {
-  return String(name == null ? '' : name)
-    .normalize('NFKC')
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '');
-}
-
-function loadVendorOverlay(vendor) {
-  const file = path.join(VENDORS_DIR, `${vendor}.json`);
-  if (!fs.existsSync(file)) return null;
-  return JSON.parse(fs.readFileSync(file, 'utf8'));
-}
-
-function listVendors() {
-  return fs
-    .readdirSync(VENDORS_DIR)
-    .filter((f) => f.endsWith('.json'))
-    .map((f) => f.replace(/\.json$/, ''));
-}
-
-/**
- * Resolve a mapping deterministically.
- *
- * @param {object} input
- * @param {string[]} input.headers    the header row AS READ at discovery time (authoritative)
- * @param {string}  input.vendor      detected vendor, or 'custom' for no overlay
- * @param {object}  [input.overlay]   pre-loaded overlay (tests inject; otherwise loaded by vendor)
- * @param {string[]} [input.targets]  which target entities to check coverage for
- */
-function resolveMapping({ headers, vendor, overlay, targets = ['product', 'category'] }) {
-  const overlayDoc = overlay !== undefined ? overlay : loadVendorOverlay(vendor);
-  const headerByNormalized = new Map();
-  const duplicateColumns = [];
-  for (const header of headers || []) {
-    const key = normalizeColumnName(header);
-    if (!key) continue;
-    if (headerByNormalized.has(key)) duplicateColumns.push(header);
-    else headerByNormalized.set(key, header);
-  }
-
-  const fieldMappings = [];
-  const claimedColumns = new Set();
-  const overlayDrift = [];
-  const canonicalErrors = [];
-
-  for (const entry of (overlayDoc && overlayDoc.columnMap) || []) {
-    if (!validateCanonicalPath(entry.wixTarget)) {
-      // A typo or an unmodelled concept in the overlay. Fail loudly at resolve time rather than
-      // silently producing a mapping that targets a field nothing can consume.
-      canonicalErrors.push({ wixTarget: entry.wixTarget, reason: 'not a known canonical field' });
-      continue;
-    }
-    // Aliases are ordered by preference; first present alias wins, and which one matched is
-    // recorded so a reviewer can see WHY a column was claimed.
-    let matched = null;
-    for (const alias of entry.aliases || []) {
-      const key = normalizeColumnName(alias);
-      if (headerByNormalized.has(key)) {
-        matched = { column: headerByNormalized.get(key), alias };
-        break;
-      }
-    }
-    if (!matched) {
-      overlayDrift.push({ wixTarget: entry.wixTarget, aliasesTried: entry.aliases || [], reason: 'no alias present in header' });
-      continue;
-    }
-    claimedColumns.add(normalizeColumnName(matched.column));
-    const def = CANONICAL_FIELDS[entry.wixTarget];
-    fieldMappings.push({
-      sourceColumn: matched.column,
-      matchedAlias: matched.alias,
-      canonicalField: entry.wixTarget,
-      entity: def.entity,
-      kind: def.kind,
-      required: Boolean(def.required),
-      decisionProvenance: 'source_platform_rule',
-    });
-  }
-
-  // --- derived entities ----------------------------------------------------
-  // A `derived` entry synthesizes an entity from the DISTINCT VALUES of one column — this is how
-  // categories and tags arrive in every named vendor's export. Such an entity's name/path is fed
-  // by derivation, not by a column mapping, so crediting it here is what keeps `category.name`
-  // from being reported as an unfilled required field on a perfectly complete export.
-  const derivedEntities = [];
-  for (const entry of (overlayDoc && overlayDoc.derived) || []) {
-    const key = normalizeColumnName(entry.fromColumn);
-    const present = headerByNormalized.has(key);
-    if (present) claimedColumns.add(key);
-    derivedEntities.push({
-      entity: entry.entity,
-      fromColumn: present ? headerByNormalized.get(key) : entry.fromColumn,
-      present,
-      hierarchical: Boolean(entry.hierarchical),
-      linkPolicy: entry.linkPolicy || null,
-      // A hierarchical source taxonomy mapped to a flat target triggers rp-mapper's mandatory
-      // faithfulness-ledger entry; surfacing the flag here is what makes that data-driven.
-      requiresFaithfulnessLedgerEntry: Boolean(entry.hierarchical),
-      fills: present ? [`${entry.entity}.name`, `${entry.entity}.path`].filter(validateCanonicalPath) : [],
-    });
-  }
-  const derivedFilled = new Set(derivedEntities.flatMap((d) => d.fills));
-
-  // --- coverage against the Wix targets ------------------------------------
-  const unsupportedTargets = [];
-  const supportedByTarget = new Map();
-  for (const targetName of targets) {
-    const target = TARGETS[targetName];
-    if (!target) continue;
-    supportedByTarget.set(targetName, new Set(Object.keys(target.fields)));
-  }
-  for (const mapping of fieldMappings) {
-    const target = TARGETS[mapping.entity === 'variant' ? 'product' : mapping.entity];
-    if (!target) continue;
-    if (target.fields[mapping.canonicalField]) continue;
-    const reason = target.unsupported && target.unsupported[mapping.canonicalField];
-    unsupportedTargets.push({
-      sourceColumn: mapping.sourceColumn,
-      canonicalField: mapping.canonicalField,
-      reason: reason || 'no Wix target field is declared for this canonical field',
-      declared: Boolean(reason),
-    });
-  }
-
-  // Required canonical inputs that nothing feeds. These are hard blockers, not review items.
-  const mappedFields = new Set(fieldMappings.map((m) => m.canonicalField));
-  const unfilledRequired = Object.entries(CANONICAL_FIELDS)
-    .filter(([fieldPath, def]) => {
-      if (!def.required || mappedFields.has(fieldPath) || derivedFilled.has(fieldPath)) return false;
-      const target = TARGETS[def.entity === 'variant' ? 'product' : def.entity];
-      return Boolean(target && target.fields[fieldPath]);
-    })
-    .map(([fieldPath]) => fieldPath);
-
-  // Source columns nothing claimed. THIS is the agent's queue.
-  const unmappedColumns = [...headerByNormalized.entries()]
-    .filter(([key]) => !claimedColumns.has(key))
-    .map(([, original]) => original);
-
-  const totalColumns = headerByNormalized.size;
-  return {
-    vendor: vendor || 'custom',
-    overlayVersion: (overlayDoc && overlayDoc.profileVersion) || null,
-    overlayPresent: Boolean(overlayDoc),
-    fieldMappings,
-    coverage: {
-      totalColumns,
-      mappedColumns: claimedColumns.size,
-      unmappedColumns: unmappedColumns.length,
-      // The honest headline number: of the columns the overlay claimed, how many actually land in
-      // Wix. A column mapped to an unsupported canonical field is NOT coverage.
-      landingInWix: fieldMappings.length - unsupportedTargets.length,
-      ratio: totalColumns ? Number((claimedColumns.size / totalColumns).toFixed(4)) : 0,
-    },
-    derivedEntities,
-    residue: { unmappedColumns, unsupportedTargets, unfilledRequired },
-    overlayDrift,
-    canonicalErrors,
-    duplicateColumns,
-  };
-}
-
-// Applies a resolved mapping to one raw source row -> a flat canonical field bag.
-// Deliberately NOT the whole record assembler: grouping rows into products, deriving categories
-// from a column's values, and unit conversion are adapter concerns (rp-source-csv owns them).
-// This is the field-level half, and it is the half that was being hand-written per project.
-function applyMapping(row, resolved) {
-  const out = {};
-  for (const mapping of resolved.fieldMappings) {
-    const raw = row[mapping.sourceColumn];
-    if (raw === undefined) continue;
-    out[mapping.canonicalField] = raw;
-  }
-  return out;
-}
-
-module.exports = {
-  normalizeColumnName,
-  loadVendorOverlay,
-  listVendors,
-  resolveMapping,
-  applyMapping,
-  VENDORS_DIR,
-};

package/skills/wix-replatform/resources/rp-mapper/lib/structure-bridge-planning.js

@@ -1,303 +0,0 @@
-'use strict';
-
-// Mapping-stage planning for structure-bridge-plugin entities .
-//
-// A plugin entity whose only read path is wix-wp-plugin-v2's /query is two different things,
-// and this module keeps them apart:
-//
-//   - A PLANNED ENTITY: the profile proposes a Wix target (`candidateTargetRefs[]`), so the table
-//     becomes a migration entity in its own right. It gets `mapping/entity-decisions/<entity>.json`
-//     and a row in `mapping/mapping-plan.json`, under the same mapping-review gate as a REST
-//     entity, and rp-import-codegen generates a normal incremental reader for it
-//     (rp-source-wordpress/lib/structure-bridge-reader.js).
-//   - A BLOCKED-FIELD SOURCE: no candidate target; the data only fills a field on a target that
-//     is planned through another source (for example gift-card balance). That stays on the
-//     blockedSourceDependencies / blocked-data-requests.js path, unchanged.
-//
-// A target entity may declare a blockedSourceDependency on a source that is ALSO planned here
-// as its own entity (ecom/discount-rule on discount-rule-definition). Routing it through both
-// paths would offer the same table as a one-shot blocked-data request that can never resolve,
-// so partitionBlockedSourceDependencies() removes that dependency before the blocked-data
-// builder runs and records it on the planned entity's decision instead.
-//
-// Readiness is the only thing checked through blocked-data-handlers.js; data is never resolved
-// through blocked-data-requests.js's snapshot mechanism.
-
-const fsp = require('node:fs/promises');
-const path = require('node:path');
-const { fulfillmentReadiness } = require('../../rp-source-wordpress/lib/blocked-data-handlers.js');
-const { readEntityByRef } = require('../../rp-target-wix/lib/domain-knowledge.js');
-const { verifyEavReadPlanIntegrity } = require('../../rp-source-wordpress/lib/wix-wp-plugin-v2-client.js');
-
-const DEFAULT_DOMAINS_DIR = path.join(__dirname, '..', '..', 'rp-target-wix', 'domains');
-const REVIEW_GATE = Object.freeze({ artifact: 'orchestration/approvals.json', field: 'mapping.status' });
-const PLAN_ROW_KEYS = ['entityMappings', 'entityDecisions', 'mappings', 'entities'];
-
-function slugify(value) {
-  return String(value).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'entity';
-}
-
-function sourceEntityRefOf(plugin, entity) {
-  return `plugin.${plugin}.${entity}`;
-}
-
-function structureBridgeFulfillment(entity) {
-  const blockers = [...(entity.blocked || []), ...((entity.pitfalls || []).flatMap((p) => p.blocked || []))];
-  const hit = blockers.find((b) => b.fulfillment && b.fulfillment.kind === 'structure-bridge-plugin');
-  return hit ? hit.fulfillment : null;
-}
-
-async function readJsonIfExists(filePath) {
-  try {
-    return JSON.parse(await fsp.readFile(filePath, 'utf8'));
-  } catch (error) {
-    if (error.code === 'ENOENT') return null;
-    throw error;
-  }
-}
-
-/** A discovery artifact that is not valid JSON is a pending reason, not a crashed mapping run. */
-async function readArtifact(filePath, fileName, pendingReasons) {
-  try {
-    return await readJsonIfExists(filePath);
-  } catch (error) {
-    if (!(error instanceof SyntaxError)) throw error;
-    pendingReasons.push(`discovery artifact ${fileName} is not valid JSON -- re-run discovery for this table`);
-    return null;
-  }
-}
-
-/** Why an EAV read plan cannot drive extraction, or null. Mirrors the reader's own checks. */
-function eavPlanIntegrityReason(plan, planFile) {
-  if (!plan || typeof plan !== 'object' || Array.isArray(plan)) return `read plan ${planFile} is not an object -- re-run discovery for this table`;
-  let problem;
-  try { problem = verifyEavReadPlanIntegrity(plan); } catch (error) { problem = error.message; }
-  if (!Array.isArray(plan.pairs)) problem = problem || 'it has no pairs array';
-  return problem ? `read plan ${planFile} fails its integrity check, so extraction would defer: ${problem}` : null;
-}
-
-function loadTarget(domainsDir, ref) {
-  try { return readEntityByRef(domainsDir, ref); } catch { return null; }
-}
-
-/**
- * Classify every structure-bridge-plugin entity of the detected plugins.
- *
- * @param plugins   [{ plugin, entities: [...] }] -- profiles or wp-plugin-detect's detected list
- * @param dataDir   the project's `data/` directory (discovery sidecars live in wp-discovery/)
- * @param readiness optional override of blocked-data-handlers.js's fulfillmentReadiness
- * @returns { decisions, blockedFieldSources }
- */
-async function planStructureBridgeEntities({ plugins = [], sourceEntities = null, dataDir, readiness = fulfillmentReadiness, domainsDir = DEFAULT_DOMAINS_DIR } = {}) {
-  if (!dataDir) throw new Error('planStructureBridgeEntities needs dataDir');
-  if (sourceEntities === null) {
-    const schema = await readJsonIfExists(path.join(path.dirname(path.resolve(dataDir)), 'source-schema.json'));
-    sourceEntities = Array.isArray(schema?.entities) ? schema.entities
-      : Object.entries(schema?.entities || {}).map(([key, row]) => ({ sourceEntityRef: key, ...row }));
-  }
-  const decisions = [];
-  const blockedFieldSources = [];
-  const boundRefs = new Set();
-  const bound = require('../../rp-source-wordpress/lib/plugin-entity-read-plan.js');
-  for (const entity of sourceEntities) {
-    const planRef = entity.sourceMeta?.extractionPlan;
-    if (!planRef && !entity.bridgeDesignated) continue;
-    const sourceEntityRef = entity.sourceEntityRef;
-    boundRefs.add(sourceEntityRef);
-    const pendingReasons = [];
-    let plan;
-    try { plan = bound.loadPlan({ projectDir: path.dirname(dataDir), sourceEntityRef, planRef }); }
-    catch (error) {
-      pendingReasons.push(error.message);
-      bound.recordPluginExtractionDeferral({ projectDir: path.dirname(dataDir), sourceEntityRef, planRef, code: error.code || 'plan-invalid', reason: error.message });
-    }
-    const candidates = entity.candidateTargetRefs || entity.sourceMeta?.candidateTargetRefs || [];
-    if (!candidates.length) {
-      blockedFieldSources.push({ sourceEntityRef, sourceEntity: entity.entity || sourceEntityRef, table: plan?.components.length === 1 ? plan.components[0].table : null, route: 'blocked-source-dependency' });
-      continue;
-    }
-    const targetRef = candidates[0];
-    const target = loadTarget(domainsDir, targetRef);
-    if (!target) pendingReasons.push(`candidate target ${targetRef} is not in the Wix domain knowledge`);
-    decisions.push({ schemaVersion: 1, sourceEntityRef, sourceEntity: sourceEntityRef,
-      sourcePlugin: sourceEntityRef.split('.')[1], sourceMeta: { ...entity.sourceMeta }, bridgeDesignated: true,
-      sourceType: entity.sourceType || null, sourcePrerequisites: entity.sourcePrerequisites || [],
-      resolution: 'structure-bridge-reader', fulfillment: { kind: 'structure-bridge-plugin', handlerId: 'wix-wp-plugin-v2' },
-      targetRef, targetDomain: targetRef.split('/')[0], targetEntity: targetRef.split('/')[1], targetClassification: target?.target?.classification || null, candidateTargetRefs: candidates,
-      confidence: 'proposed', status: pendingReasons.length ? 'pending' : 'migration-planned', pendingReasons,
-      readiness: { ready: Boolean(plan), reason: pendingReasons.join('; ') || null }, readVariant: 'entity-plan',
-      readArtifacts: { extractionPlan: planRef || null },
-      sourceExtract: { ndjson: `data/source-extract/${sourceEntityRef}.ndjson`, manifest: `data/source-extract/${sourceEntityRef}.manifest.json` },
-      supersedesBlockedDependencies: [], reviewGate: { ...REVIEW_GATE } });
-  }
-  for (const plugin of plugins) {
-    for (const entity of plugin.entities || []) {
-      const fulfillment = structureBridgeFulfillment(entity);
-      if (!fulfillment) continue;
-      const sourceEntityRef = sourceEntityRefOf(plugin.plugin, entity.entity);
-      if (boundRefs.has(sourceEntityRef)) continue;
-      const candidateTargetRefs = [...(entity.candidateTargetRefs || [])];
-      if (candidateTargetRefs.length === 0) {
-        blockedFieldSources.push({ sourceEntityRef, sourceEntity: entity.entity, table: fulfillment.table, route: 'blocked-source-dependency' });
-        continue;
-      }
-
-      const requestFile = `wix-wp-plugin-v2--${slugify(fulfillment.table)}.structure-request.json`;
-      const planFile = `wix-wp-plugin-v2--${slugify(fulfillment.table)}.eav-read-plan.json`;
-      const artifactReasons = [];
-      // eslint-disable-next-line no-await-in-loop
-      const [request, plan, ready] = await Promise.all([
-        readArtifact(path.join(dataDir, 'wp-discovery', requestFile), requestFile, artifactReasons),
-        readArtifact(path.join(dataDir, 'wp-discovery', planFile), planFile, artifactReasons),
-        readiness(fulfillment),
-      ]);
-      const targetRef = candidateTargetRefs[0];
-      const target = loadTarget(domainsDir, targetRef);
-      const pendingReasons = [...artifactReasons];
-      if (!ready || ready.ready !== true) pendingReasons.push(`handler not ready: ${(ready && ready.reason) || 'unknown'}`);
-      if (!target) pendingReasons.push(`candidate target ${targetRef} is not in the Wix domain knowledge`);
-      if (!request && !plan && artifactReasons.length === 0) pendingReasons.push(`discovery produced no read artifact (${requestFile}) -- the table was not sampled successfully`);
-      const integrity = plan ? eavPlanIntegrityReason(plan, planFile) : null;
-      if (integrity) pendingReasons.push(integrity);
-      if (plan && Array.isArray(plan.droppedIdentityColumns) && plan.droppedIdentityColumns.length > 0) {
-        pendingReasons.push(`read plan drops identity column(s) ${plan.droppedIdentityColumns.join(', ')}; complete identity is required -- narrow the mapping or redesign the read plan`);
-      }
-      if (plan && plan.keysTruncated) pendingReasons.push('read plan key list is truncated, so the extraction cannot be whole-table');
-
-      decisions.push({
-        schemaVersion: 1,
-        sourceEntity: entity.entity,
-        sourceEntityRef,
-        sourcePlugin: plugin.plugin,
-        capability: entity.capability || null,
-        channel: entity.channel || null,
-        resolution: 'structure-bridge-reader',
-        fulfillment: { kind: fulfillment.kind, handlerId: fulfillment.handlerId, table: fulfillment.table },
-        readiness: { ready: Boolean(ready && ready.ready), reason: (ready && ready.reason) || null },
-        targetRef,
-        targetDomain: targetRef.split('/')[0],
-        targetEntity: targetRef.split('/')[1],
-        targetClassification: target && target.target ? target.target.classification : null,
-        candidateTargetRefs,
-        confidence: 'proposed',
-        status: pendingReasons.length === 0 ? 'migration-planned' : 'pending',
-        pendingReasons,
-        readVariant: plan ? 'eav' : 'single-request',
-        readArtifacts: {
-          structureRequest: request ? `data/wp-discovery/${requestFile}` : null,
-          eavReadPlan: plan ? `data/wp-discovery/${planFile}` : null,
-        },
-        sourceExtract: {
-          ndjson: `data/source-extract/${entity.entity}.ndjson`,
-          manifest: `data/source-extract/${entity.entity}.manifest.json`,
-        },
-        supersedesBlockedDependencies: [],
-        reviewGate: { ...REVIEW_GATE },
-      });
-    }
-  }
-  return { decisions, blockedFieldSources };
-}
-
-/**
- * Remove blockedSourceDependencies whose source is planned as its own entity, so the
- * blocked-data builder never also requests it. Returns new target objects (inputs untouched) and
- * records each removed dependency on the matching decision.
- */
-function partitionBlockedSourceDependencies(targetEntities = [], decisions = []) {
-  const byRef = new Map(decisions.map((d) => [d.sourceEntityRef, d]));
-  const targets = targetEntities.map((target) => {
-    const deps = Array.isArray(target.blockedSourceDependencies) ? target.blockedSourceDependencies : [];
-    const kept = [];
-    for (const dep of deps) {
-      const decision = byRef.get(dep.sourceEntityRef);
-      if (!decision) { kept.push(dep); continue; }
-      const targetEntity = target.ref || `${target.domain}/${target.entity}`;
-      if (!decision.supersedesBlockedDependencies.some((s) => s.targetEntity === targetEntity && s.degradedField === dep.degradedField)) {
-        decision.supersedesBlockedDependencies.push({ targetEntity, degradedField: dep.degradedField, pitfallCode: dep.pitfallCode });
-      }
-    }
-    return { ...target, blockedSourceDependencies: kept };
-  });
-  return { targetEntities: targets, decisions };
-}
-
-// Fields rp-mapper or the operator may already have set on a row, which a planning rerun keeps.
-// Everything else planning emits is bridge-owned structure (target, readiness, read variant,
-// artifacts, planner-owned status) and is refreshed; fields planning never emits -- field mappings,
-// transformations, relationships, notes, operator edits -- are always preserved.
-const PRESERVED_WHEN_SET = ['confidence'];
-
-/** Merge a bridge decision into an existing row without erasing the mapping work on it. */
-function mergeBridgeRow(existing, decision) {
-  if (!existing || typeof existing !== 'object' || Array.isArray(existing)) return { ...decision };
-  const merged = { ...existing, ...decision };
-  // Only the planner's own provisional states may refresh. Reviewed exclusions,
-  // manual routing and other mapping decisions retain their status and reason.
-  if (existing.status && !['pending', 'migration-planned'].includes(existing.status)) merged.status = existing.status;
-  if (decision.readVariant === 'entity-plan' && existing.targetRef) {
-    for (const key of ['targetRef', 'targetDomain', 'targetEntity', 'targetClassification']) {
-      if (existing[key] !== undefined) merged[key] = existing[key];
-    }
-  }
-  for (const key of PRESERVED_WHEN_SET) {
-    if (existing[key] !== undefined && existing[key] !== null) merged[key] = existing[key];
-  }
-  return merged;
-}
-
-function upsertPlanRows(plan, decisions) {
-  if (plan.entities && typeof plan.entities === 'object' && !Array.isArray(plan.entities)
-    && !PLAN_ROW_KEYS.some((k) => Array.isArray(plan[k]))) {
-    for (const d of decisions) plan.entities[d.sourceEntity] = mergeBridgeRow(plan.entities[d.sourceEntity], d);
-    return plan;
-  }
-  const key = PLAN_ROW_KEYS.find((k) => Array.isArray(plan[k])) || 'entityDecisions';
-  const rows = Array.isArray(plan[key]) ? plan[key] : [];
-  for (const d of decisions) {
-    const index = rows.findIndex((row) => row && (row.sourceEntityRef === d.sourceEntityRef || (row.sourceEntity || row.entityName || row.entityKey) === d.sourceEntity));
-    const decision = key === 'entities' ? { entityKey: index >= 0 ? rows[index].entityKey || d.sourceEntity : d.sourceEntity, ...d } : d;
-    if (index >= 0) rows[index] = mergeBridgeRow(rows[index], decision); else rows.push(mergeBridgeRow(null, decision));
-  }
-  plan[key] = rows;
-  return plan;
-}
-
-async function writeJson(filePath, value) {
-  await fsp.mkdir(path.dirname(filePath), { recursive: true });
-  const staging = `${filePath}.writing`;
-  await fsp.writeFile(staging, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
-  await fsp.rename(staging, filePath);
-}
-
-/**
- * Write the planned entities into the mapping artifacts. Refuses once the mapping review has
- * been approved: adding an entity after the gate would skip the review it depends on.
- */
-async function writeStructureBridgePlanning(projectDir, decisions) {
-  if (!projectDir) throw new Error('writeStructureBridgePlanning needs projectDir');
-  const approvals = await readJsonIfExists(path.join(projectDir, 'orchestration', 'approvals.json'));
-  const gate = approvals && approvals.mapping && approvals.mapping.status;
-  if (gate === 'approved' || gate === 'provisional') {
-    throw new Error(`mapping review is already ${gate}; re-open the mapping review before adding structure-bridge-plugin entities`);
-  }
-  const decisionPaths = [];
-  for (const decision of decisions) {
-    const filePath = path.join(projectDir, 'mapping', 'entity-decisions', `${slugify(decision.sourceEntity)}.json`);
-    // eslint-disable-next-line no-await-in-loop
-    await writeJson(filePath, mergeBridgeRow(await readJsonIfExists(filePath), decision));
-    decisionPaths.push(filePath);
-  }
-  const planPath = path.join(projectDir, 'mapping', 'mapping-plan.json');
-  const plan = (await readJsonIfExists(planPath)) || {};
-  await writeJson(planPath, upsertPlanRows(plan, decisions));
-  return { decisionPaths, planPath };
-}
-
-module.exports = {
-  REVIEW_GATE,
-  planStructureBridgeEntities,
-  partitionBlockedSourceDependencies,
-  writeStructureBridgePlanning,
-  sourceEntityRefOf,
-};

package/skills/wix-replatform/resources/rp-mapper/scripts/coverage-reconcile.js

@@ -1,88 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-
-// Source-coverage reconcile check and decision writer.
-//
-//   node scripts/coverage-reconcile.js check <projectDir> [--json]
-//   node scripts/coverage-reconcile.js decide <projectDir> --coverage-id <id> --value provided|declined [--rationale <text>]
-//
-// `check` joins discovery/source-coverage.json, mapping/review/mapping-gaps.json and
-// orchestration/decisions.json by coverageId. Every coverage row needs exactly one valid
-// disposition: a mapping-gaps.json entry carrying its coverageId, a `sourceCoverage:<coverageId>`
-// decision, or (quick mode only) its declared exclusion.
-//
-// `decide` records a `sourceCoverage:<coverageId>` decision and removes that row's gap entries in
-// the same write, so the normal recovery path never creates a disposition conflict.
-//
-// Exit codes: 0 every row reconciles; 2 a row has no, two, a stale or a mismatched disposition, a
-// gap/decision names an unknown coverageId, or the coverage file is missing or malformed;
-// 1 usage error.
-
-const path = require('node:path');
-const {
-  reconcileProject,
-  recordCoverageDecision,
-  SourceCoverageError,
-} = require('../../../lib/source-coverage.js');
-
-function parseArgs(argv) {
-  const args = { command: null, projectDir: null, coverageId: null, value: null, rationale: null, json: false };
-  const positional = [];
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === '--coverage-id') { args.coverageId = argv[i + 1]; i += 1; }
-    else if (arg === '--value') { args.value = argv[i + 1]; i += 1; }
-    else if (arg === '--rationale') { args.rationale = argv[i + 1]; i += 1; }
-    else if (arg === '--json') args.json = true;
-    else positional.push(arg);
-  }
-  [args.command, args.projectDir] = positional;
-  return args;
-}
-
-function usage() {
-  return 'Usage: coverage-reconcile.js check <projectDir> [--json]\n'
-    + '       coverage-reconcile.js decide <projectDir> --coverage-id <id> --value provided|declined [--rationale <text>]\n';
-}
-
-function report(failures, json) {
-  if (json) {
-    process.stdout.write(`${JSON.stringify({ ok: failures.length === 0, failures }, null, 2)}\n`);
-    return;
-  }
-  if (!failures.length) {
-    process.stdout.write('source coverage reconciles: every row has exactly one valid disposition\n');
-    return;
-  }
-  for (const item of failures) process.stderr.write(`${item.code}: ${item.message}\n`);
-}
-
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
-  if (!['check', 'decide'].includes(args.command) || !args.projectDir) {
-    process.stderr.write(usage());
-    return 1;
-  }
-  const projectDir = path.resolve(args.projectDir);
-  try {
-    if (args.command === 'decide') {
-      const result = await recordCoverageDecision(projectDir, { coverageId: args.coverageId, value: args.value, rationale: args.rationale });
-      process.stdout.write(`${JSON.stringify({ ok: true, ...result })}\n`);
-    }
-    const result = await reconcileProject(projectDir);
-    report(result.failures, args.json);
-    return result.ok ? 0 : 2;
-  } catch (error) {
-    if (error instanceof SourceCoverageError) {
-      const failures = error.failures.length ? error.failures : [{ code: 'invalid_coverage', coverageId: null, message: error.message, sources: [] }];
-      report(failures, args.json);
-      return 2;
-    }
-    throw error;
-  }
-}
-
-main().then((code) => { process.exitCode = code; }).catch((error) => {
-  process.stderr.write(`${error.stack || error.message}\n`);
-  process.exitCode = 1;
-});