in2-agent-server 0.20260821.185429

package/dist/direct/removals.js

@@ -0,0 +1,262 @@
+import { canonJson } from "../projection/diff.js";
+const isObj = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+const gone = (v) => v === undefined || v === null;
+// Pure reorder is not a removal: the org alphabetizes many collections on read-back.
+function sameMultiset(a, b) {
+    const key = (arr) => arr.map(canonJson).sort().join(" ");
+    return key(a) === key(b);
+}
+// Elements of a metadata collection are identified by a NAME, not by their position. Salesforce
+// reorders freely on read-back, and an insertion shifts every later index — so positional matching
+// compares unrelated things and reports the difference as a loss.
+//
+// Live (CF77): inserting an "Intake Details" section at index 1 of a Layout made this report
+// `layoutSections[2].layoutColumns 3 → 2 items` as CONTENT REMOVED. Nothing was removed; index 2
+// was "Custom Links" before and "System Information" after. The operator had to hand-diff the
+// pre and post images to prove the alarm was empty — on the one check whose whole job is to be
+// trustworthy about silent loss.
+//
+// Matching by identity also makes the check STRONGER, not just quieter: a section genuinely
+// deleted from the middle used to be masked by the same shift.
+const NAME_INDIVIDUALLY_UP_TO = 6;
+const IDENTITY_KEYS = ["fullName", "name", "label", "field", "relatedList", "apiName"];
+// PARTIALLY keyed is the normal case, not the exception, and requiring every element to carry the
+// key threw away the whole mechanism whenever one did not. Live: a Layout's "Custom Links" section
+// has NO label in the org's pre-image (the org materializes one only on the way back out), so a
+// single unlabeled section sent the entire comparison back to positional matching and reproduced
+// the exact index-shift false alarm identity matching was added to remove.
+/**
+ * Which keys across a set of containers hold a COLLECTION rather than a scalar setting?
+ *
+ * Not answerable per value: the Metadata API collapses a single-element collection to a BARE
+ * OBJECT on read-back (the same quirk compareIntent normalizes, and that findRemovals already
+ * coerces for on the after-side), and generic types get no array normalization on the way in. So a
+ * Layout column holding exactly ONE layoutItem arrives as `layoutItems: {…}`, indistinguishable by
+ * shape from a scalar-valued setting.
+ *
+ * Two signals, unioned, and computed over BOTH sides together so the two merges cannot classify
+ * the same key differently — which would compare an array against an object and report nothing:
+ *   - it is an array on at least one container anywhere, or
+ *   - it appears on more than one container (a per-container SETTING would too, but multiplying a
+ *     repeated scalar into a list only ever makes this check noisier, never blinder).
+ */
+function collectionKeysOf(containers) {
+    const keys = new Set();
+    const seen = new Map();
+    for (const el of containers) {
+        if (!isObj(el))
+            continue;
+        for (const [k, v] of Object.entries(el)) {
+            if (Array.isArray(v))
+                keys.add(k);
+            seen.set(k, (seen.get(k) ?? 0) + 1);
+        }
+    }
+    for (const [k, n] of seen)
+        if (n > 1)
+            keys.add(k);
+    return keys;
+}
+/**
+ * Collapse a list of anonymous container objects into one, concatenating their collections.
+ *
+ * Used only where the containers themselves have no identity, so which container a child sits in
+ * carries no meaning the removals check should assert on — only whether the child still EXISTS
+ * somewhere in the collection.
+ *
+ * `collectionKeys` must come from BOTH sides via collectionKeysOf. An earlier version decided
+ * per value with `Array.isArray`, which silently DROPPED any collection the org had collapsed to a
+ * bare object — turning a real full-file-replace loss into a clean DIFF_VERIFIED. That is the exact
+ * 6.5.4 failure this module was written to close, so the classification is deliberately shared.
+ */
+function mergeContainers(list, collectionKeys) {
+    const merged = {};
+    for (const el of list) {
+        if (!isObj(el))
+            continue;
+        for (const [k, v] of Object.entries(el)) {
+            if (collectionKeys.has(k)) {
+                const prior = merged[k];
+                const priorArr = prior === undefined ? [] : Array.isArray(prior) ? prior : [prior];
+                merged[k] = [...priorArr, ...(Array.isArray(v) ? v : [v])];
+            }
+            else if (merged[k] === undefined) {
+                merged[k] = v;
+            }
+        }
+    }
+    return merged;
+}
+function identityKey(before, after) {
+    for (const key of IDENTITY_KEYS) {
+        const read = (arr) => {
+            const vals = arr.filter(isObj).map((el) => el[key]).filter((v) => typeof v === "string" && v !== "");
+            // An EMPTY side cannot supply a key but must not veto one either — a wholesale wipe is the
+            // case where naming each casualty matters most, and the names are all on the other side.
+            if (arr.length === 0)
+                return true;
+            // Otherwise usable when the values that ARE present are unambiguous. One keyless element no
+            // longer disqualifies the rest — those are handled separately and conservatively below.
+            return vals.length > 0 && new Set(vals).size === vals.length;
+        };
+        if (read(before) && read(after))
+            return key;
+    }
+    return null;
+}
+export function findRemovals(pre, post, intent) {
+    if (!pre || !post)
+        return []; // a create has no pre-image — nothing can be lost
+    const out = [];
+    const statedRoots = new Set(Object.keys(intent ?? {}));
+    const walk = (before, after, path, root) => {
+        const stated = statedRoots.has(root);
+        if (Array.isArray(before)) {
+            const afterArr = Array.isArray(after) ? after : gone(after) ? [] : [after];
+            // A pure reorder is never a removal, whatever the shape.
+            if (sameMultiset(before, afterArr))
+                return;
+            const key = identityKey(before, afterArr);
+            if (key) {
+                // Identity-matched: report only elements that genuinely disappeared, and compare each
+                // survivor against ITS OWN counterpart rather than whatever now sits at its old index.
+                const byId = new Map();
+                for (const el of afterArr) {
+                    if (!isObj(el))
+                        continue;
+                    const id = el[key];
+                    if (typeof id === "string" && id !== "")
+                        byId.set(id, el);
+                }
+                const missing = [];
+                for (const el of before) {
+                    const id = isObj(el) ? el[key] : undefined;
+                    if (typeof id !== "string" || id === "") {
+                        // No identity, so there is no honest way to say WHICH element in `after` this became.
+                        // Counting it as missing is how the false alarm was manufactured; the only defensible
+                        // evidence for a keyless element is the anonymous population shrinking, checked below.
+                        continue;
+                    }
+                    const match = byId.get(id);
+                    if (match === undefined)
+                        missing.push(id);
+                    else
+                        walk(el, match, `${path}[${key}=${id}]`, root);
+                }
+                // Compare KEYLESS against KEYLESS, not against the whole collection. Gating on the total
+                // shrinking conflates two populations: every named casualty is already reported
+                // individually below, so a collection that lost one named element and no anonymous ones
+                // fired this line as well — double-reporting, and blocking DIFF_VERIFIED on the strength of
+                // a count nobody can act on.
+                //
+                // It also manufactured a fresh false positive once columns merge (CF63 w4's shape): a
+                // Layout's pooled layoutItems legitimately contain `emptySpace` padding cells, which carry
+                // no `field` and so land here. A field moving column while a spacer disappeared read as
+                // content loss. Padding is not content — a cell that states nothing but its own emptiness
+                // cannot be something the org lost.
+                const anonymous = (list) => list.filter((el) => {
+                    const id = isObj(el) ? el[key] : undefined;
+                    if (typeof id === "string" && id !== "")
+                        return false;
+                    return !(isObj(el) && el.emptySpace !== undefined);
+                }).length;
+                const keylessBefore = anonymous(before);
+                const keylessAfter = anonymous(afterArr);
+                if (keylessBefore > keylessAfter) {
+                    out.push({ path, detail: `${keylessBefore} → ${keylessAfter} unnamed item(s)`, stated });
+                }
+                // Name them individually — that is the whole point, and "2 → 0 item(s)" used to send the
+                // reader to the pre-image to find out WHAT died. Past a handful it inverts: a wholesale
+                // wipe (a Profile losing 400 fieldPermissions) would bury every other finding, so collapse.
+                if (missing.length > NAME_INDIVIDUALLY_UP_TO) {
+                    out.push({ path, detail: `${before.length} → ${afterArr.length} item(s), including ${missing.slice(0, 3).join(", ")}…`, stated });
+                }
+                else {
+                    for (const id of missing)
+                        out.push({ path: `${path}[${key}=${id}]`, detail: "present → absent", stated });
+                }
+                return;
+            }
+            // ANONYMOUS CONTAINERS. The elements are objects but carry no identity of their own, and they
+            // hold the collections that DO — `Layout.layoutColumns` is the canonical case: a column has no
+            // name, only `layoutItems`. Position is not identity here either (the same reason stated at
+            // the top of this file), so comparing column 0 to column 0 reports a field that merely MOVED
+            // COLUMN as a loss.
+            //
+            // Live-caught CF63 w4: the supervisor moved CF63_Due_Date__c and CF63_Requester_Email__c
+            // between columns of the "Intake Details" section. This reported both as CONTENT REMOVED
+            // while compareIntent — in the SAME response — correctly scored them `orderOnly: 2`. Two
+            // subsystems disagreeing about the same two fields, and the wrong one is the one that blocks
+            // DIFF_VERIFIED. It cost a hand-read of the post-deploy layout to prove nothing was lost.
+            //
+            // Merging the containers and comparing the contents is also STRICTLY STRONGER than per-index:
+            // a field deleted outright is absent from EVERY column, so it still reports — while a field
+            // that simply moved no longer does.
+            // The gate asks collectionKeysOf rather than testing for an array directly, for the same
+            // single-element-collapse reason: a section whose columns each hold exactly ONE layoutItem
+            // has no array anywhere, and an Array.isArray gate would drop it back to positional matching
+            // — reproducing the very bug this branch exists to fix, on the narrowest layouts.
+            const collectionKeys = collectionKeysOf([...before, ...afterArr]);
+            const anonymousContainers = before.length > 0 && before.every(isObj) && afterArr.every(isObj) && collectionKeys.size > 0;
+            if (anonymousContainers) {
+                walk(mergeContainers(before, collectionKeys), mergeContainers(afterArr, collectionKeys), path, root);
+                return;
+            }
+            // No usable identity (scalars, or a key that repeats): fall back to counting, then to
+            // positional comparison — the best available answer for a collection with nothing to key on.
+            if (afterArr.length < before.length) {
+                out.push({ path, detail: `${before.length} → ${afterArr.length} item(s)`, stated });
+                return;
+            }
+            for (let i = 0; i < before.length; i += 1)
+                walk(before[i], afterArr[i], `${path}[${i}]`, root);
+            return;
+        }
+        if (isObj(before)) {
+            if (!isObj(after)) {
+                if (gone(after))
+                    out.push({ path, detail: "present → absent", stated });
+                return;
+            }
+            for (const [k, v] of Object.entries(before))
+                walk(v, after[k], `${path}.${k}`, root);
+            return;
+        }
+        // Scalar leaf: only a disappearance counts. A CHANGED value is ordinary drift and is
+        // already covered by the intent check + three-way diff; re-reporting it here would drown
+        // the signal this exists for.
+        if (!gone(before) && before !== "" && gone(after)) {
+            out.push({ path, detail: `${JSON.stringify(before).slice(0, 48)} → absent`, stated });
+        }
+    };
+    for (const [k, v] of Object.entries(pre))
+        walk(v, post[k], `metadata.${k}`, k);
+    return out;
+}
+export function renderRemovals(component, removals) {
+    const shown = removals.slice(0, 8).map((r) => `${r.path} (${r.detail})${r.stated ? "" : " [UNSTATED]"}`);
+    const more = removals.length > shown.length ? ` …and ${removals.length - shown.length} more` : "";
+    return `${component}: ${shown.join(", ")}${more}`;
+}
+/**
+ * Drop the two removal classes that are artifacts of comparing an ORG READ-BACK against PARSED
+ * SOURCE XML — the pre-flight comparison only. The post-deploy check compares two read-backs, where
+ * neither class can arise.
+ *
+ * Measured on CF78: 5 of 8 pre-flight findings were one of these. On the w4 RE-APPLY — after the
+ * supervisor had correctly carried every real facet forward — the check fired twice and BOTH were
+ * false, which is what forced an ack of the whole rule. Acks are per-rule, so that ack would also
+ * have waved through a genuine drop introduced in the same wave. A check that is usually wrong does
+ * not merely waste attention; it actively disarms itself.
+ *
+ *   fullName — path-derived in source format, so it is NEVER in an authored file. It fired on every
+ *              pre-flight of every existing component: a 100% false-positive rate by construction.
+ *   default-valued scalars — `false` and `""` are what the platform stores when an element is
+ *              omitted, so omitting them changes nothing. compareIntent already treats this exact
+ *              class as agreement; this brings the removals check into line.
+ */
+export function isSourceFormatArtifact(r) {
+    if (r.path === "metadata.fullName")
+        return true;
+    return /^(false|"")\s*→ absent$/.test(r.detail);
+}