@salesforce/plugin-bre-to-cml 1.3.0 → 1.3.2

package/lib/shared/cml-operators.js

@@ -14,11 +14,29 @@ export function doubleQuotedIfNeeded(value, dataType) {
     const singleValue = value[0];
     return `${dataType === 'string' ? doubleQuoted(singleValue) ?? '' : singleValue ?? "''"}`;
 }
-export function generateInCmlExpression(left, right) {
+/**
+ * Whether values of this resolved CML type are emitted quoted. An absent type means the caller
+ * resolved none, and quoting is the conservative direction — an unquoted value reaches the curated
+ * model verbatim. (`doubleQuotedIfNeeded` predates this and reads an absent type as non-string;
+ * `In`/`NotIn` are new to type-awareness, so an omitted type keeps their long-standing quoting.)
+ */
+function quotesValues(dataType) {
+    return dataType === undefined || dataType === 'string';
+}
+/**
+ * Expands an In list into a chain of `==` comparisons. Because those are equality comparisons, the
+ * values follow the same quoting rule Equals follows: quoted only for `string`. Quoting a value
+ * against an attribute the model declares `decimal` compares a number with a string literal, and
+ * the comparison never fires.
+ *
+ * `dataType` is optional and last so existing callers that pass none keep emitting quoted values.
+ */
+export function generateInCmlExpression(left, right, dataType) {
+    const emit = (value) => (quotesValues(dataType) ? doubleQuoted(value) : value);
     if (typeof right === 'string') {
-        return `${left} == ${doubleQuoted(right)}`;
+        return `${left} == ${emit(right)}`;
     }
-    return right.map((r) => `${left} == ${doubleQuoted(r)}`).join(' || ');
+    return right.map((r) => `${left} == ${emit(r)}`).join(' || ');
 }
 function firstValue(right) {
     if (right === undefined)
@@ -49,12 +67,12 @@ export function convertToCmlExpression(left, ruleExprOperator, right, dataType)
             return `!strcontain(${left}, ${doubleQuoted(firstValue(right))})`;
         case 'In':
             if (right) {
-                return `(${generateInCmlExpression(left, right)})`;
+                return `(${generateInCmlExpression(left, right, dataType)})`;
             }
             return `${left} == null`;
         case 'NotIn':
             if (right) {
-                return `!(${generateInCmlExpression(left, right)})`;
+                return `!(${generateInCmlExpression(left, right, dataType)})`;
             }
             return `${left} != null`;
         default: {

package/lib/shared/cml-operators.js.map

@@ -1 +1 @@
-{"version":3,"file":"cml-operators.js","sourceRoot":"","sources":["../../src/shared/cml-operators.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cml-operators.js","sourceRoot":"","sources":["../../src/shared/cml-operators.ts"],"names":[],"mappings":"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"}

package/lib/shared/insurance/confirm-org-changes.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The confirmation gate for the org-mutating insurance import commands
+ * (export/review/import design, work item W-23654540 §4). Callers MUST have rendered the full
+ * PlannedChange[] — built from read-only operations — before calling this, and MUST NOT issue any
+ * write until it resolves.
+ *
+ * Used today by `insurance import record-updates`; the matrix is command-agnostic, so
+ * `cml import as-expression-set` can gate on it when that work lands (§7 step 12).
+ */
+/** Minimal surface the gate needs, so it is unit-testable without oclif. */
+export type ConfirmHost = {
+    warn(message: string): unknown;
+    confirm(options: {
+        message: string;
+        ms?: number;
+        defaultAnswer?: boolean;
+    }): Promise<boolean>;
+};
+export type ConfirmOptions = {
+    noPrompt: boolean;
+    /**
+     * Whether a human can actually answer. Callers pass
+     * `process.stdout.isTTY && process.stdin.isTTY && !this.jsonEnabled()`.
+     */
+    interactive: boolean;
+};
+export type ConfirmText = {
+    /** Warning emitted when `--no-prompt` bypasses the gate. */
+    skippingPrompt: string;
+    /** The confirmation question (no question mark, no Y/N — `confirm` adds those). */
+    confirmApply: string;
+    /**
+     * Built lazily: the prompt could not run and `--no-prompt` was not passed. Must carry remediation
+     * actions, and must name which cause applied — a terminal that cannot prompt and a `--json` run
+     * that must not prompt need different remediation.
+     */
+    confirmationRequired: () => Error;
+    /** Built lazily: the operator answered "no". */
+    aborted: () => Error;
+};
+/**
+ * Applies the confirmation matrix. Returns normally only when the caller may proceed to write.
+ *
+ * A non-interactive invocation without `--no-prompt` fails fast instead of prompting: `confirm`
+ * does not throw on timeout, it returns `defaultAnswer` (false) after `ms`, which in CI reads as a
+ * 30-second hang followed by a silent abort. Detecting up front turns that into an immediate,
+ * actionable error.
+ */
+export declare function confirmOrThrow(host: ConfirmHost, options: ConfirmOptions, text: ConfirmText): Promise<void>;

package/lib/shared/insurance/confirm-org-changes.js

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2026, Salesforce, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** How long to wait for an answer before falling back to the (negative) default. */
+const CONFIRM_TIMEOUT_MS = 30_000;
+/**
+ * Applies the confirmation matrix. Returns normally only when the caller may proceed to write.
+ *
+ * A non-interactive invocation without `--no-prompt` fails fast instead of prompting: `confirm`
+ * does not throw on timeout, it returns `defaultAnswer` (false) after `ms`, which in CI reads as a
+ * 30-second hang followed by a silent abort. Detecting up front turns that into an immediate,
+ * actionable error.
+ */
+export async function confirmOrThrow(host, options, text) {
+    if (options.noPrompt) {
+        host.warn(text.skippingPrompt);
+        return;
+    }
+    if (!options.interactive) {
+        throw text.confirmationRequired();
+    }
+    const proceed = await host.confirm({
+        message: text.confirmApply,
+        defaultAnswer: false,
+        ms: CONFIRM_TIMEOUT_MS,
+    });
+    if (!proceed) {
+        throw text.aborted();
+    }
+}
+//# sourceMappingURL=confirm-org-changes.js.map

package/lib/shared/insurance/confirm-org-changes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm-org-changes.js","sourceRoot":"","sources":["../../../src/shared/insurance/confirm-org-changes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA0CH,oFAAoF;AACpF,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAElC;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAiB,EAAE,OAAuB,EAAE,IAAiB;IAChG,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC/B,OAAO;IACT,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QACzB,MAAM,IAAI,CAAC,oBAAoB,EAAE,CAAC;IACpC,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC;QACjC,OAAO,EAAE,IAAI,CAAC,YAAY;QAC1B,aAAa,EAAE,KAAK;QACpB,EAAE,EAAE,kBAAkB;KACvB,CAAC,CAAC;IACH,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;IACvB,CAAC;AACH,CAAC"}

package/lib/shared/insurance/insurance-cml-merge.d.ts

@@ -1,5 +1,7 @@
 import { Connection } from '@salesforce/core';
 import { ParsedRuleDefinition, RuleRecord } from './models.js';
+import { AttributeDataTypes } from './insurance-rule-generator.js';
+import { ContextTagBindings } from './insurance-context-tags.js';
 /**
  * MERGE MODE (insurance-only): instead of building a fresh single-type CML and PATCH-replacing
  * the org's curated "Gold Standard" ConstraintModel, this module reads the existing model text,
@@ -11,10 +13,36 @@ import { ParsedRuleDefinition, RuleRecord } from './models.js';
  *
  * Why pathed keys: when a ProductSurcharge is persisted as ConstraintEngine the platform
  * auto-generates `RuleKey` as `SC` + sanitize(ProductCode) of every segment in ProductPath (in
- * order) + sanitize(apiName), joined by `__`. The Core surcharge engine matches the fired CML rule
- * key against that auto-generated RuleKey by exact string, so the CML rule key MUST be pathed too.
+ * order) + sanitize(leaf), joined by `__`. The leaf is the parent `Surcharge.Code` (resolved via
+ * ProductSurcharge.SurchargeId), NOT the rule apiName — see {@link fetchSurchargeCodes} and
+ * {@link buildPathedSurchargeRules}. The Core surcharge engine matches the fired CML rule key
+ * against that auto-generated RuleKey by exact string, so the CML rule key MUST be pathed and use
+ * the same Code-derived leaf.
  */
 export declare const SURCHARGE_RULE_ACTION = "InsuranceSurchargeRule";
+/**
+ * A context-tag reference the merge will DECLARE into the model so the rule's expression resolves.
+ *
+ * Only a BRE `Tag` condition (`attributeId` null) produces one of these, and only when the tag
+ * resolved unambiguously against the org's context metadata (see insurance-context-tags.ts). An
+ * `Attribute` condition never does: those name product attributes the curated model is expected to
+ * already declare, and auto-declaring one would paper over the real cause — usually that the rule
+ * targets a type belonging to a different model.
+ */
+export type ContextTagDeclaration = {
+    /** Raw ContextTag.Title, e.g. `Cause Of Loss`. Carried verbatim by the emitted annotation. */
+    tag: string;
+    /**
+     * `sanitizeName(tag)`, so the CML identifier stays legal even when the title contains spaces or
+     * punctuation. The TRUE name is never lost — it travels in the `tagName` / `contextPath`
+     * annotation, which is what actually binds the value.
+     */
+    identifier: string;
+    /** CML declaration type from ContextAttribute.DataType (e.g. `date`, `decimal(2)`). */
+    cmlType: string;
+    /** Which binding form to emit: a top-level `extern`, or an in-type `@(tagName = ...)`. */
+    scope: 'transaction' | 'item';
+};
 export type PathedSurchargeRule = {
     recordId: string;
     recordName: string;
@@ -34,6 +62,19 @@ export type PathedSurchargeRule = {
     statement: string;
     /** Sanitized attribute names referenced by the rule declaration (for visibility warnings). */
     referencedAttributes: string[];
+    /**
+     * The context-tag references this rule needs, resolved against the org. The merge declares each
+     * one that the model does not already carry, and treats it as visible for the absent-reference
+     * gate. A tag that did NOT resolve is deliberately absent from this list, so it stays invisible to
+     * the gate and its rule is withheld exactly as before.
+     */
+    contextTagDeclarations: ContextTagDeclaration[];
+    /**
+     * Set when {@link findUnconvertibleConditions} found something in this rule CML cannot express.
+     * The merge refuses such a rule outright — `statement` is built anyway (the shapes stay uniform)
+     * but must never be placed.
+     */
+    unconvertibleReason?: string;
 };
 export type MergePlacement = {
     rule: PathedSurchargeRule;
@@ -91,14 +132,23 @@ export type UnderwritingConstraintRule = {
         name: string;
         cmlType: string;
     }>;
+    /** See {@link PathedSurchargeRule.unconvertibleReason}. */
+    unconvertibleReason?: string;
 };
 /**
  * Builds the pathed surcharge rule key that mirrors the platform's auto-generated
  * `ProductSurcharge.RuleKey`: prefix + every path-segment product code + apiName.
  */
 export declare function buildPathedRuleKey(prefix: string, pathProductCodes: string[], apiName: string, stageTransition?: string): string;
-/** Splits a `ProductPath` into its ordered Product2 ids (slash-separated). */
-export declare function splitProductPath(productPath: string): string[];
+/**
+ * Splits a `ProductPath` into its ordered Product2 ids (slash-separated).
+ *
+ * ProductPath is nullable in the org even on records that carry a rule, so nullish input yields an
+ * empty path rather than throwing. Callers rely on that: an empty path is already a recognized skip
+ * (see the empty-ProductPath guard in mergeSurchargeRules), whereas throwing here aborted the whole
+ * conversion run before any record could be skipped.
+ */
+export declare function splitProductPath(productPath: string | null | undefined): string[];
 /**
  * Reads the org's existing ConstraintModel text for the given CML API name, mirroring the lookup
  * the common import uses (ExpressionSetDefinition.DeveloperName -> ExpressionSetDefinitionVersion).
@@ -115,6 +165,15 @@ export declare function fetchExistingConstraintModel(conn: Connection, cmlApiNam
  * correct way to find which existing `type` block a surcharge's leaf product nests into.
  */
 export declare function fetchProductTypeTags(conn: Connection, productIds: Set<string>): Promise<Map<string, string>>;
+/**
+ * Resolves Surcharge id -> Surcharge.Code. The platform builds the LEAF segment of
+ * `ProductSurcharge.RuleKey` from the parent Surcharge's Code (e.g. `basictaxcode`), NOT from the
+ * rule apiName. `buildPathedSurchargeRules` uses this map so the emitted CML rule key matches the
+ * platform-generated RuleKey exactly; without it the surcharge imports cleanly but never fires
+ * ("No active rule model found"). Ids with no resolvable Code are omitted (caller warns + falls
+ * back to apiName).
+ */
+export declare function fetchSurchargeCodes(conn: Connection, surchargeIds: Set<string>): Promise<Map<string, string>>;
 export declare function escapeRegExp(value: string): string;
 /**
  * [Fix #4] Detects the dominant line ending of a CML text by counting CRLF vs bare-LF occurrences.
@@ -132,16 +191,46 @@ export declare function detectDominantLineEnding(cml: string): string;
  * structural close, which would return a too-early closeIdx and splice a new rule mid-statement.
  */
 export declare function matchClosingBrace(cml: string, openIdx: number): number | undefined;
+/**
+ * Prefix every merge skip raised by {@link findUnconvertibleConditions} carries, so the commands'
+ * skip breakdown can bucket it the way it buckets the other reasons.
+ */
+export declare const UNCONVERTIBLE_SKIP_PREFIX = "cannot be expressed in CML";
 /** Builds the `rule(...)` statement for a surcharge, using the same constraint generator as build mode. */
 export declare function buildSurchargeRuleStatement(declaration: string, ruleKey: string): string;
+export type BuildPathedSurchargeRulesOptions = {
+    /**
+     * Surcharge id -> Surcharge.Code (from {@link fetchSurchargeCodes}). The platform derives the
+     * LEAF segment of ProductSurcharge.RuleKey from the parent Surcharge's Code, so this is preferred
+     * over the rule apiName for the key leaf. When a rule's surchargeId is missing or not present in
+     * this map, the leaf falls back to the apiName and {@link onSurchargeCodeFallback} fires.
+     */
+    surchargeIdToCode?: Map<string, string>;
+    /** Called with the rule's recordName when its Surcharge.Code could not be resolved (key leaf fell back to apiName). */
+    onSurchargeCodeFallback?: (recordName: string) => void;
+    /**
+     * Org-resolved attribute types (see {@link AttributeDataTypes}). Required for a numeric picklist
+     * to be compared as a number: without it the merged rule compares a decimal attribute — as the
+     * curated model already declares it — against a quoted string, and the surcharge never fires.
+     */
+    attributeDataTypes?: AttributeDataTypes;
+    /**
+     * Raw context tag -> its org-resolved binding (see {@link fetchContextTagBindings}). Absent or
+     * empty means no tag resolves, which leaves every Tag-condition rule to the absent-reference gate
+     * — the behaviour before context-tag resolution existed, and still the correct fallback.
+     */
+    contextTagBindings?: ContextTagBindings;
+};
 /**
  * Prepares the pathed-rule descriptors for a set of parsed surcharge records.
  * `productIdToCode` and `productIdToType` must already cover every ProductPath segment.
+ * `options.surchargeIdToCode` should map every rule's parent Surcharge id to its Code so the key
+ * leaf matches the platform-generated RuleKey (see {@link fetchSurchargeCodes}).
  */
 export declare function buildPathedSurchargeRules(prefix: string, ruleDefs: Array<{
     record: RuleRecord;
     ruleDef: ParsedRuleDefinition;
-}>, productIdToCode: Map<string, string>, productIdToType: Map<string, string>): PathedSurchargeRule[];
+}>, productIdToCode: Map<string, string>, productIdToType: Map<string, string>, options?: BuildPathedSurchargeRulesOptions): PathedSurchargeRule[];
 /**
  * Builds the `constraint <name> = (...)` statement for underwriting eligibility, using the same
  * constraint generator as build mode's constraint-form branch (see `buildCmlModel`).
@@ -157,7 +246,7 @@ export declare function buildUnderwritingConstraintStatement(constraintName: str
 export declare function buildUnderwritingConstraintRules(keyPrefix: string, constraintLabel: string, ruleDefs: Array<{
     record: RuleRecord;
     ruleDef: ParsedRuleDefinition;
-}>, productIdToCode: Map<string, string>, productIdToType: Map<string, string>): UnderwritingConstraintRule[];
+}>, productIdToCode: Map<string, string>, productIdToType: Map<string, string>, attributeDataTypes?: AttributeDataTypes): UnderwritingConstraintRule[];
 /**
  * Merges the pathed surcharge `rule(...)` statements into the existing CML text. If the rule key is
  * already present, the existing statement line is replaced in place (idempotent). Otherwise the
@@ -174,13 +263,11 @@ export declare function mergeSurchargeRules(existingCml: string, rules: PathedSu
  * statement (from the `constraint` keyword through the terminating `;`) is replaced in place
  * (idempotent — re-running the merge with the same input reproduces the same output).
  * - Otherwise the statement is inserted just before the closing brace of the leaf `type` block.
- * - Before placing a rule's constraint, any of its `referencedAttributes` not already declared
- * anywhere in the leaf `type` block are auto-inserted (as `<cmlType> <attrName>;`) right after
- * the block's opening brace, and reported via `attributeWarnings` so the caller can log them —
- * unlike surcharge merge (which only WARNS about missing attributes, since injecting into the
- * curated model there was judged too risky for a `rule(...)` action statement), underwriting
- * constraints reference attributes that must resolve for the constraint to compile, so the
- * declaration is added rather than merely flagged.
+ * - Any of a rule's `referencedAttributes` not already declared anywhere in the leaf `type` block
+ * are reported via `attributeWarnings`; the curated model is never mutated to add them. NOTE: this
+ * is weaker than the surcharge merge, which WITHHOLDS such a rule outright — an unresolvable
+ * reference makes the solver reject the whole model at deploy, so warning here still lets a
+ * model-wide outage through. See findAbsentAttributes.
  *
  * Rules with a blank ProductPath, no resolved leaf type tag, an ambiguous/duplicate type block, or
  * an intra-run duplicate (typeName, constraintName) pair are skipped (reported, never silently