in2-agent-server 0.20260821.185429

package/dist/campfire/configItemDescription.js

@@ -0,0 +1,379 @@
+import { richTextFragment } from "../core/richText.js";
+/** Values past this many are summarised as a count — a 50-value picklist is not a description. */
+const MAX_PROJECTED_VALUES = 12;
+/**
+ * Description__c's hard cap. The Configuration Item write is a per-row upsert with per-row failure
+ * isolation (see `campfire.ts`'s `campfire_write_config_items`, ~1636-1685) — one oversized row fails
+ * on its own, not the whole manifest. But this codebase has already lost a whole batch to exactly this
+ * failure class once, on a DIFFERENT all-or-none call: CF63, where one oversized `Blocked_Reason__c`
+ * refused every row of an sObject-Collections `update_campfire_requirements` call. The length cap here
+ * keeps that failure class from recurring on this writer too. `describeConfigItem` must never return a
+ * string longer than this, for any input — see `capFragment` below.
+ */
+const MAX_DESCRIPTION_CHARS = 32_768;
+/**
+ * Cap on any single caller-supplied value interpolated into a sentence — a formula, or one side of
+ * an observed/intended pair. A Salesforce formula can run to 3,900 characters and a deviation list
+ * can carry many of these; bounding each value keeps one outsized field from dominating the row.
+ */
+const MAX_VALUE_CHARS = 240;
+/** Truncates a single interpolated value; unchanged when it is already within the cap. */
+function truncateValue(value) {
+    return value.length > MAX_VALUE_CHARS ? `${value.slice(0, MAX_VALUE_CHARS)}…` : value;
+}
+/**
+ * Flow `start.triggerType` values that mean "this flow runs against a record save/delete" — the only
+ * values a "Record-triggered on X" sentence is true for. `start.object` is also present on scheduled
+ * flows (alongside `start.schedule`), so presence of an object alone never implies record-triggering;
+ * see the `Flow` case in `projectConfiguration` below.
+ */
+const RECORD_TRIGGER_TYPES = new Set(["RecordBeforeSave", "RecordBeforeDelete", "RecordAfterSave"]);
+/**
+ * Cap on the number of DEVIATION sentences. A Layout or Profile row can differ on dozens of leaves
+ * at once, and a description enumerating all of them stops being a description — the remainder is
+ * named as a count instead of dropped silently.
+ */
+const MAX_DEVIATION_SENTENCES = 20;
+/**
+ * Paths whose value in Salesforce settles asynchronously, so a post-deploy read can outrun it.
+ *
+ * Live-caught on the 08-02 A_Agreement__c batch: an OWD-private wave read back
+ * `sharingModel=ReadWrite` because the sharing recalculation had not finished. The difference was
+ * lag, not a deviation — so the hint rides only on these paths, and a blanket hint would teach the
+ * reader to discount every real deviation too.
+ */
+const ASYNC_ORG_PATH_RE = /sharingModel/i;
+const ASYNC_DIFFERENCE_HINT = "This setting applies asynchronously — re-read the org once recalculation settles before treating this as a real difference.";
+/**
+ * The noun phrase for a type, in the words a consultant would use.
+ *
+ * Keyed by CAMPFIRE type. A type absent here falls back to a spaced-out form of its own name, which
+ * is correct often enough ("PathAssistant" -> "path assistant") to beat maintaining 55 entries.
+ */
+const TYPE_NOUN = {
+    ApexClass: "Apex class",
+    ApexPage: "Visualforce page",
+    ApexTrigger: "Apex trigger",
+    App: "app",
+    ApprovalProcess: "approval process",
+    CompactLayout: "compact layout",
+    CustomField: "field",
+    CustomLabel: "custom label",
+    CustomMetadata: "custom metadata record",
+    CustomObject: "object",
+    CustomPermission: "custom permission",
+    Dashboard: "dashboard",
+    EmailTemplate: "email template",
+    FieldSet: "field set",
+    Flow: "flow",
+    GlobalValueSet: "global value set",
+    Group: "public group",
+    Layout: "page layout",
+    LightningPage: "Lightning page",
+    ListView: "list view",
+    PathAssistant: "path",
+    PermissionSet: "permission set",
+    PermissionSetGroup: "permission set group",
+    Profile: "profile",
+    Queue: "queue",
+    QuickAction: "action",
+    RecordType: "record type",
+    Report: "report",
+    ReportType: "report type",
+    // Role and NamedCredential are in CI_RULES because a live QA run delivered them and the
+    // writeback dropped them (2026-08-14, ses_09b70d19); a table that silently degrades is how that
+    // happened, so both carry explicit entries even though the fallback would spell them right.
+    NamedCredential: "named credential",
+    Role: "role",
+    StandardField: "standard field",
+    Tab: "tab",
+    ValidationRule: "validation rule",
+    WebLink: "button",
+    WorkflowEmailAlert: "email alert",
+    WorkflowFieldUpdate: "field update"
+};
+/** "LightningPage" -> "lightning page". Only reached for types absent from TYPE_NOUN. */
+function humanizeType(type) {
+    return type.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+}
+function str(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+}
+/**
+ * Everything the org has shown us about this component, folded across deliveries in wave order.
+ *
+ * PER-KEY LAST OBSERVATION WINS; A PARTIAL LATER BODY MUST NOT ERASE UNRELATED OBSERVED FACTS.
+ * A wave's observed body is only as wide as the facets that wave touched — a label-only re-deploy
+ * carries `label`, not the value set. Taking the last body wholesale dropped facts the org had
+ * already returned: a picklist field renamed in a later wave stopped being describable as a
+ * picklist at all, and an object whose second wave was a `{sharingModel}` facetUpdate lost its
+ * label from the identity line. (Confirmed through the real derivation on both shapes.)
+ *
+ * The fold is SHALLOW on purpose. A later wave that re-read `valueSet` re-read the whole value
+ * set, so its version replaces the earlier one entire; deep-merging two value sets would splice
+ * together a list the org never held at any single moment — a fabricated observation, the one
+ * thing this module may not produce.
+ *
+ * Deliveries without a body (an unconfirmed read, a refused delete) contribute nothing rather
+ * than erasing what earlier waves established.
+ */
+function finalConfiguration(row) {
+    let folded = {};
+    for (const delivery of row.deliveries ?? []) {
+        const configuration = delivery.deliveredConfiguration;
+        if (!configuration || Object.keys(configuration).length === 0)
+            continue;
+        folded = { ...folded, ...configuration };
+    }
+    return folded;
+}
+/**
+ * A boolean facet as the org stated it, or undefined when the org did not state it.
+ *
+ * TRI-STATE, not a coercion. The XML parser hands booleans back as the STRINGS "true"/"false", so
+ * both forms are real observations — a `typeof === "boolean"` gate rejected the wire shape and a
+ * validation rule's Active/Inactive never printed at all. But null, an empty element, and an
+ * unrecognized casing are all "not observed", and collapsing them to false asserts a fact no read
+ * produced; for a validation rule that assertion is load-bearing in the wrong direction —
+ * "Inactive" tells a human the rule blocks nothing.
+ */
+function observedBoolean(value) {
+    if (value === true || value === "true")
+        return true;
+    if (value === false || value === "false")
+        return false;
+    return undefined;
+}
+/**
+ * The noun phrase, refined by observed metadata where the metadata makes it more specific.
+ * A CustomField whose observed `type` is Picklist is a "picklist field", not a "field".
+ */
+function nounFor(row, config) {
+    const base = TYPE_NOUN[row.type] ?? humanizeType(row.type);
+    if (row.type !== "CustomField" && row.type !== "StandardField")
+        return base;
+    const fieldType = str(config.type);
+    return fieldType ? `${fieldType.toLowerCase()} ${base}` : base;
+}
+/**
+ * Inline values, in document order. A picklist field nests them at `valueSet.valueSetDefinition
+ * .value`; a GlobalValueSet carries its own under top-level `customValue` — routing the global set
+ * through the field path read the wrong key and the projection was silently dead code. A value's
+ * `label` is what a user sees and its `fullName` the stored API name, so label wins; an entry the
+ * parser collapsed to a bare string (`<value>Alpha</value>`) is the value itself, not a miss.
+ */
+function observedValues(config, key) {
+    const raw = key === "customValue"
+        ? config.customValue
+        : config.valueSet?.valueSetDefinition?.value;
+    const entries = Array.isArray(raw) ? raw : raw ? [raw] : [];
+    return entries
+        .map((entry) => entry !== null && typeof entry === "object"
+        ? (str(entry.label) ?? str(entry.fullName))
+        : str(entry))
+        .filter((value) => Boolean(value));
+}
+function projectValues(values) {
+    if (values.length === 0)
+        return undefined;
+    if (values.length <= MAX_PROJECTED_VALUES)
+        return `Values: ${values.join(", ")}.`;
+    const shown = values.slice(0, MAX_PROJECTED_VALUES).join(", ");
+    return `Values: ${shown} (+${values.length - MAX_PROJECTED_VALUES} more).`;
+}
+/**
+ * The salient configuration sentences for a row, from observed metadata only.
+ *
+ * A type with nothing concrete to project contributes nothing — an empty array is the correct and
+ * common answer, and padding it with generic prose is exactly the failure this module exists to
+ * avoid.
+ */
+function projectConfiguration(row, config) {
+    const parts = [];
+    switch (row.type) {
+        case "CustomField":
+        case "StandardField": {
+            const values = projectValues(observedValues(config, "valueSet"));
+            if (values)
+                parts.push(values);
+            const formula = str(config.formula);
+            if (formula)
+                parts.push(`Formula: ${truncateValue(formula)}`);
+            break;
+        }
+        case "GlobalValueSet": {
+            const values = projectValues(observedValues(config, "customValue"));
+            if (values)
+                parts.push(values);
+            break;
+        }
+        case "ValidationRule": {
+            const active = observedBoolean(config.active);
+            if (active !== undefined)
+                parts.push(active ? "Active." : "Inactive.");
+            const message = str(config.errorMessage);
+            if (message)
+                parts.push(`Error message: "${truncateValue(message)}"`);
+            break;
+        }
+        case "Flow": {
+            const start = config.start;
+            const triggerObject = str(start?.object);
+            const triggerType = str(start?.triggerType);
+            // `start.object` alone never settles how the flow triggers — it is present on scheduled flows
+            // too. Only an observed record-save/delete triggerType earns "Record-triggered"; a recognised
+            // Scheduled type gets its own true sentence; anything else names the object without claiming
+            // how it triggers, rather than guessing.
+            if (triggerObject && triggerType && RECORD_TRIGGER_TYPES.has(triggerType)) {
+                parts.push(`Record-triggered on ${triggerObject}.`);
+            }
+            else if (triggerObject && triggerType === "Scheduled") {
+                parts.push(`Scheduled, running against ${triggerObject}.`);
+            }
+            else if (triggerObject) {
+                parts.push(`Starts from ${triggerObject}.`);
+            }
+            const processType = str(config.processType);
+            if (processType)
+                parts.push(`Process type: ${processType}.`);
+            const status = str(config.status);
+            if (status)
+                parts.push(`Status: ${status}.`);
+            break;
+        }
+        case "Role": {
+            // The one fact that places a role: where it reports. A top role has no parent and says
+            // nothing rather than inventing "top of hierarchy" the org never stored.
+            const parent = str(config.parentRole);
+            if (parent)
+                parts.push(`Parent role: ${parent}.`);
+            break;
+        }
+        case "NamedCredential": {
+            // Legacy shape puts the URL on `endpoint`; the SecuredEndpoint shape moves the same URL into
+            // a `Url` named-credential parameter. Both are things the org returned; neither is inferred.
+            const url = str(config.endpoint) ?? namedCredentialUrl(config);
+            if (url)
+                parts.push(`URL: ${truncateValue(url)}.`);
+            break;
+        }
+        default:
+            break;
+    }
+    return parts;
+}
+/** The SecuredEndpoint half of NamedCredential's two URL shapes — see the case above. */
+function namedCredentialUrl(config) {
+    const raw = config.namedCredentialParameters;
+    const entries = Array.isArray(raw) ? raw : raw ? [raw] : [];
+    for (const entry of entries) {
+        if (entry === null || typeof entry !== "object")
+            continue;
+        const parameter = entry;
+        const name = str(parameter.parameterName);
+        const parameterType = str(parameter.parameterType);
+        if (name?.toLowerCase() === "url" || parameterType?.toLowerCase() === "url") {
+            const value = str(parameter.parameterValue);
+            if (value)
+                return value;
+        }
+    }
+    return undefined;
+}
+/**
+ * The identity sentence: label (or API name), what it is, and where it lives.
+ *
+ * `label` is what most types carry; FlexiPage / PathAssistant / WebLink use `masterLabel`; a Role
+ * carries its human name in `name`. When the org returned none of them the API name IS the name —
+ * prettifying it here would be inventing a label the org never stored.
+ */
+function identity(row, config) {
+    const name = str(config.label) ?? str(config.masterLabel) ?? str(config.name) ?? row.apiName;
+    const noun = nounFor(row, config);
+    const where = row.objectApiName ? ` on ${row.objectApiName}` : "";
+    return `${name} — ${noun}${where}.`;
+}
+/**
+ * One sentence per observed difference on the FINAL delivery only — mirroring `finalConfiguration`,
+ * which already treats the last delivery as the one that finished the component. A component that
+ * differed in an earlier wave and matched in a later, corrective wave has been fixed: carrying an
+ * earlier wave's difference forward would print it as an unqualified present-tense claim about
+ * current org state, which is exactly the false-inference failure this module exists to avoid. Capped
+ * at `MAX_DEVIATION_SENTENCES` — beyond that, one final sentence names how many more were dropped
+ * rather than growing the row without bound.
+ */
+function deviations(row) {
+    const finalDelivery = (row.deliveries ?? []).at(-1);
+    if (!finalDelivery || finalDelivery.readBack !== "differed")
+        return [];
+    const all = (finalDelivery.differences ?? []).map((difference) => `DEVIATION: ${difference.path} — the org stored ${truncateValue(difference.observed)}; ` +
+        `the approved configuration specified ${truncateValue(difference.intended)}.` +
+        (ASYNC_ORG_PATH_RE.test(difference.path) ? ` ${ASYNC_DIFFERENCE_HINT}` : ""));
+    if (all.length <= MAX_DEVIATION_SENTENCES)
+        return all;
+    const shown = all.slice(0, MAX_DEVIATION_SENTENCES);
+    shown.push(`(+${all.length - MAX_DEVIATION_SENTENCES} more deviations not shown.)`);
+    return shown;
+}
+/**
+ * What happened to this component, for rows the run did not deploy.
+ *
+ * A CI list is what a requirement is BUILT FROM, not a log of one run's deltas, so these rows
+ * belong on the manifest and have to say why they carry no delivery.
+ */
+function originSentence(row) {
+    if (row.origin === "pre-existing") {
+        return ["Already present in the org and owned by this requirement; not deployed by this run."];
+    }
+    if (row.origin === "routed") {
+        return ["Owned by this requirement but not deployable by the direct tier."];
+    }
+    return [];
+}
+/**
+ * Backstop for `MAX_DESCRIPTION_CHARS`. The per-value and per-sentence caps above bound the known
+ * unbounded inputs, but this is the guarantee that actually matters: `describeConfigItem` never
+ * returns a string longer than the field's cap, for any input.
+ *
+ * Bounds the RETURNED fragment, not the plain body: `richTextFragment` grows some characters when it
+ * transforms them — `&` -> `&amp;`, a newline -> `<br/>` — so a plain body sized to the cap can come
+ * out over it. Truncates the PLAIN body and re-escapes rather than cutting the escaped string
+ * directly — slicing mid-transform (e.g. inside `&amp;`) would corrupt the field with a dangling
+ * `&am`.
+ */
+function capFragment(body) {
+    let text = body;
+    let fragment = richTextFragment(text);
+    while (fragment.length > MAX_DESCRIPTION_CHARS && text.length > 0) {
+        const excess = fragment.length - MAX_DESCRIPTION_CHARS;
+        // `excess` is measured in ESCAPED characters; the slice removes PLAIN ones. Dividing by the
+        // measured inflation ratio keeps the two units aligned — subtracting escaped-excess from the
+        // plain body directly over-cut by the ratio (5x on `&`-dense text) and COMPOUNDED per pass,
+        // reducing a 35k body with 25% escapable characters to a bare "…" while the loop reported
+        // success. Ceil guarantees at least one character goes per pass, so the loop still terminates;
+        // richTextFragment never shrinks a character, so the ratio is always >= 1.
+        const ratio = fragment.length / text.length;
+        const cut = Math.max(1, Math.ceil(excess / ratio));
+        text = text.slice(0, Math.max(0, text.length - cut - 1)) + "…";
+        fragment = richTextFragment(text);
+    }
+    return fragment;
+}
+export function describeConfigItem(row) {
+    const config = finalConfiguration(row);
+    // Asserted from the OBSERVED deliveries, never from intent: a delete the org refused is
+    // destructive in the request and a no-op in fact, and this sentence is a claim about the org.
+    const deleted = row.destructive && (row.deliveries ?? []).some((d) => d.action === "deleted");
+    const parts = [
+        identity(row, config),
+        ...projectConfiguration(row, config),
+        ...originSentence(row),
+        ...(deleted ? ["Deleted from the org."] : []),
+        ...deviations(row),
+        ...(row.note ? [row.note] : [])
+    ];
+    // Returns the FINISHED rich-text fragment, not raw prose. Composing it here rather than at the
+    // call site is what keeps caller-supplied names — all apt to carry a `<` — from reaching
+    // Description__c unescaped, and `capFragment` is what keeps it under Description__c's cap.
+    return capFragment(parts.join(" "));
+}