isc-transforms-mcp 1.0.20 → 1.0.22

package/JSONS/sailpoint.isc.transforms.concat.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "sailpoint.isc.transforms.concat.schema.json",
   "title": "SailPoint ISC Transform Schema - concat",
-  "description": "Strict schema derived from the SailPoint official Concatenation operation documentation. Concatenates an array of values (static strings or nested transform objects) into a single string output.",
+  "description": "Strict schema for the SailPoint ISC concat (Concatenation) transform. Joins an ordered array of values (static strings or nested transform outputs) into a single combined string. Key behaviors: (1) Items are joined in order with NO automatic separator — spaces, hyphens, or other delimiters must be added as explicit string entries in the array. (2) Each array entry can be a static string literal or a nested transform object whose output string is used. (3) A single-entry values array is valid JSON but semantically pointless — use the nested transform directly in that case.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -12,16 +12,18 @@
   ],
   "properties": {
     "type": {
-      "const": "concat"
+      "const": "concat",
+      "description": "Transform operation type. Must be exactly 'concat'."
     },
     "name": {
       "type": "string",
-      "minLength": 1
+      "minLength": 1,
+      "description": "Display name for this transform, shown in UI dropdowns and identity profile mappings."
     },
     "requiresPeriodicRefresh": {
       "type": "boolean",
       "default": false,
-      "description": "Whether the transform logic should be reevaluated nightly as part of identity refresh. Default false."
+      "description": "If true, re-evaluates this transform during the nightly identity refresh cycle. Default is false."
     },
     "attributes": {
       "type": "object",
@@ -29,15 +31,17 @@
       "required": [
         "values"
       ],
+      "description": "Required container for concat operation attributes. The only valid attribute is 'values'.",
       "properties": {
         "values": {
           "type": "array",
-          "minItems": 2,
-          "description": "Array of items to join. Each item must be a static string or a nested transform object.",
+          "minItems": 1,
+          "description": "Required. Ordered array of items to join into a single output string. Items are concatenated in sequence with no automatic separator. Rules: (1) Each entry must be a static string literal or a nested transform object {type, attributes} whose output is used. (2) To include spaces, hyphens, or any other separator, add them as explicit string entries between the value entries. (3) A single-entry array is valid but pointless — the nested transform can be used directly. Examples: [firstName, ' ', lastName] → 'Jane Doe'; [jobTitle, ' - ', jobCode] → 'Engineer - ENG001'.",
           "items": {
-            "oneOf": [
+            "anyOf": [
               {
-                "type": "string"
+                "type": "string",
+                "description": "Static string literal included as-is in the output (e.g., ' ', ' - ', ' (Contractor)')."
               },
               {
                 "$ref": "#/$defs/NestedTransform"
@@ -51,7 +55,7 @@
   "$defs": {
     "NestedTransform": {
       "type": "object",
-      "description": "Nested transform object used inside other transforms (docs examples often omit 'name' on nested transforms). Operation-specific validation should be applied by the referenced operation schema.",
+      "description": "A nested transform object used as one element in the values array. Its output string is inserted at the corresponding position in the concatenated result. The 'name' field is optional in nested transforms per SailPoint docs.",
       "additionalProperties": false,
       "required": [
         "type",
@@ -59,18 +63,22 @@
       ],
       "properties": {
         "id": {
-          "type": "string"
+          "type": "string",
+          "description": "Optional ID when referencing an existing saved transform."
         },
         "name": {
           "type": "string",
-          "minLength": 1
+          "minLength": 1,
+          "description": "Optional display name for the nested transform."
         },
         "type": {
           "type": "string",
-          "minLength": 1
+          "minLength": 1,
+          "description": "The operation type of the nested transform (e.g., 'accountAttribute', 'identityAttribute', 'static', 'lower', 'trim')."
         },
         "requiresPeriodicRefresh": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Whether this nested transform re-evaluates during nightly refresh."
         },
         "attributes": {
           "type": "object",
@@ -82,8 +90,54 @@
   },
   "examples": [
     {
+      "name": "Full Name from HR Source",
+      "type": "concat",
+      "attributes": {
+        "values": [
+          {
+            "type": "accountAttribute",
+            "attributes": {
+              "sourceName": "HR Source",
+              "attributeName": "FirstName"
+            }
+          },
+          " ",
+          {
+            "type": "accountAttribute",
+            "attributes": {
+              "sourceName": "HR Source",
+              "attributeName": "LastName"
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "Job Title with Code",
+      "type": "concat",
+      "attributes": {
+        "values": [
+          {
+            "type": "accountAttribute",
+            "attributes": {
+              "sourceName": "HR Source",
+              "attributeName": "JobTitle"
+            }
+          },
+          " - ",
+          {
+            "type": "accountAttribute",
+            "attributes": {
+              "sourceName": "HR Source",
+              "attributeName": "JobCode"
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "Contractor Display Name",
       "type": "concat",
-      "name": "Test Concat Transform",
       "attributes": {
         "values": [
           {
@@ -104,6 +158,38 @@
           " (Contractor)"
         ]
       }
+    },
+    {
+      "name": "Lowercase Email from Identity Attributes",
+      "type": "concat",
+      "attributes": {
+        "values": [
+          {
+            "type": "lower",
+            "attributes": {
+              "input": {
+                "type": "identityAttribute",
+                "attributes": {
+                  "name": "firstname"
+                }
+              }
+            }
+          },
+          ".",
+          {
+            "type": "lower",
+            "attributes": {
+              "input": {
+                "type": "identityAttribute",
+                "attributes": {
+                  "name": "lastname"
+                }
+              }
+            }
+          },
+          "@example.com"
+        ]
+      }
     }
   ]
 }

package/dist/transforms/lint.js

@@ -18,7 +18,7 @@ const ALLOWED_ATTRS = {
     ]),
     base64Decode: new Set(["input"]),
     base64Encode: new Set(["input"]),
-    concat: new Set(["values", "input"]),
+    concat: new Set(["values"]),
     conditional: "open", // dynamic variable keys allowed per docs
     dateCompare: new Set(["firstDate", "secondDate", "operator", "positiveCondition", "negativeCondition"]),
     dateFormat: new Set(["input", "inputFormat", "outputFormat"]),
@@ -129,7 +129,8 @@ function checkRequired(spec, attrs) {
             continue;
         }
         const val = attrs?.[req];
-        if (val === undefined || val === null || (typeof val === "string" && val.length === 0)) {
+        // Empty string "" is intentional for fields like negativeCondition, positiveCondition, static.value
+        if (val === undefined || val === null) {
             push(msgs, "error", `Missing required attribute: ${req}.`, `attributes.${req}`);
         }
     }
@@ -276,25 +277,30 @@ function lintConditional(attrs) {
         return msgs;
     }
     // --- 2. Forbidden operators (using any of these throws IllegalArgumentException at runtime) ---
+    // If a forbidden operator is found, that is the root cause. Skip rules 3 and 4 to avoid
+    // duplicate errors (they would fire as consequences of the forbidden operator, not separate issues).
     const forbidden = /(!=|==|>=|<=|>|<|\bne\b|\bgt\b|\blt\b|\bge\b|\ble\b)/i;
-    if (forbidden.test(expr)) {
-        push(msgs, "error", `Unsupported operator in expression '${expr}'. ` +
-            "Only 'eq' is supported — using !=, ==, >, <, ne, gt, lt, ge, le throws IllegalArgumentException at runtime.", "attributes.expression");
+    const forbiddenOpFound = forbidden.test(expr);
+    if (forbiddenOpFound) {
+        push(msgs, "error", `Unsupported operator in expression: '${expr}'. Only 'eq' comparator is supported ` +
+            "(e.g., '$var eq value'). Using !=, ==, >, <, ne, gt, lt, ge, le throws IllegalArgumentException at runtime.", "attributes.expression");
     }
-    // --- 3. Must contain exactly one 'eq' ---
+    // --- 3. Must contain exactly one 'eq' (skip if forbidden operator already diagnosed) ---
     const eqMatches = expr.match(/\beq\b/gi) ?? [];
-    if (eqMatches.length === 0) {
-        push(msgs, "error", `Conditional expression must use the 'eq' comparator: '<ValueA> eq <ValueB>'. Got: '${expr}'.`, "attributes.expression");
-    }
-    else if (eqMatches.length > 1) {
-        push(msgs, "error", `Expression must contain exactly one 'eq'. Found ${eqMatches.length} occurrences in: '${expr}'. ` +
-            "Nest multiple conditions using separate conditional transforms if needed.", "attributes.expression");
+    if (!forbiddenOpFound) {
+        if (eqMatches.length === 0) {
+            push(msgs, "error", `Conditional expression must use the 'eq' comparator: '<ValueA> eq <ValueB>'. Got: '${expr}'.`, "attributes.expression");
+        }
+        else if (eqMatches.length > 1) {
+            push(msgs, "error", `Expression must contain exactly one 'eq'. Found ${eqMatches.length} occurrences in: '${expr}'. ` +
+                "Nest multiple conditions using separate conditional transforms if needed.", "attributes.expression");
+        }
     }
-    // --- 4. Both sides of 'eq' must be non-empty ---
+    // --- 4. Both sides of 'eq' must be non-empty (skip if forbidden operator already diagnosed) ---
     const parts = expr.split(/\beq\b/i);
     const valueA = parts[0]?.trim() ?? "";
     const valueB = parts[1]?.trim() ?? "";
-    if (parts.length !== 2 || valueA.length === 0 || valueB.length === 0) {
+    if (!forbiddenOpFound && (parts.length !== 2 || valueA.length === 0 || valueB.length === 0)) {
         push(msgs, "error", `Expression must follow '<ValueA> eq <ValueB>' with non-empty values on both sides. Got: '${expr}'.`, "attributes.expression");
     }
     // --- 5. Case-sensitivity info for literal operands ---
@@ -839,6 +845,13 @@ function lintDateFormat(attrs) {
                 "(expected tokens like y, M, d, H, h, m, s, S, Z). " +
                 `Valid named formats: ${Array.from(NAMED_FORMATS).join(", ")}.`, `attributes.${field}`);
         }
+        // Warn on uppercase Y (week-year) — a very common Java SimpleDateFormat mistake.
+        // YYYY = ISO 8601 week-based year (e.g. 2023-12-30 could become 2024); yyyy = calendar year.
+        if (/Y/.test(t) && !/^[A-Z][A-Z0-9_]+$/.test(t)) {
+            push(msgs, "warn", `${field} '${t}' contains uppercase 'Y' which is the ISO 8601 week-year in Java SimpleDateFormat, NOT the calendar year. ` +
+                "This is a common mistake: 'YYYY' for a December date can silently produce the following year's number. " +
+                "Use lowercase 'yyyy' for the calendar year (e.g., 'dd-MM-yyyy' instead of 'dd-MM-YYYY').", `attributes.${field}`);
+        }
     };
     checkFmt("inputFormat");
     checkFmt("outputFormat");
@@ -1313,9 +1326,20 @@ function lintStatic(attrs) {
         while ((m = refPattern.exec(value)) !== null) {
             vtlRefs.add(m[1]);
         }
+        // 3a. Detect VTL-local variables assigned via #set($var = ...) — these are internal
+        // VTL temporaries, NOT dynamic attributes that need to be defined in the attributes object.
+        const vtlLocalVars = new Set();
+        const setPattern = /#set\(\s*\$([A-Za-z_][A-Za-z0-9_]*)\s*[=\s]/g;
+        let sm;
+        while ((sm = setPattern.exec(value)) !== null) {
+            vtlLocalVars.add(sm[1]);
+        }
         if (vtlRefs.size > 0) {
-            // 4. Warn for each VTL reference that has no matching dynamic variable in attributes
+            // 4. Warn for each VTL reference that has no matching dynamic variable in attributes.
+            // Skip VTL-local variables (those assigned with #set inside the template itself).
             for (const varName of vtlRefs) {
+                if (vtlLocalVars.has(varName))
+                    continue; // #set local — not an attribute
                 if (!Object.prototype.hasOwnProperty.call(attrs, varName)) {
                     push(msgs, "warn", `VTL references $${varName} in value but no dynamic variable '${varName}' is defined in attributes. ` +
                         `Add a '${varName}' key to attributes with a static string or nested transform that supplies the value.`, `attributes.${varName}`);
@@ -1412,6 +1436,63 @@ function lintRfc5646(attrs) {
     return msgs;
 }
 // ---------------------------------------------------------------------------
+// lintConcat — concat (Concatenation)
+// Docs: https://developer.sailpoint.com/docs/extensibility/transforms/operations/concatenation
+// Joins an ordered array of strings / nested-transform outputs into one string.
+// No automatic separators — spaces, hyphens, etc. must be explicit array entries.
+// ---------------------------------------------------------------------------
+function lintConcat(attrs) {
+    const msgs = [];
+    const values = attrs?.values;
+    // --- 1. values is the only attribute and is required ---
+    if (values === undefined || values === null) {
+        push(msgs, "error", "values is required for concat. Provide an ordered array of strings and/or nested transform objects " +
+            "whose outputs will be joined into a single string.", "attributes.values");
+        return msgs;
+    }
+    if (!Array.isArray(values)) {
+        push(msgs, "error", "values must be an array of strings and/or nested transform objects.", "attributes.values");
+        return msgs;
+    }
+    if (values.length === 0) {
+        push(msgs, "error", "values array must not be empty. Provide at least one string or nested transform.", "attributes.values");
+        return msgs;
+    }
+    // --- 2. Warn if only a single entry — concat is pointless with one value ---
+    if (values.length === 1) {
+        push(msgs, "warn", "values array has only one entry. concat is designed to join multiple values — " +
+            "consider using the nested transform directly instead of wrapping it in a concat.", "attributes.values");
+    }
+    // --- 3. Validate each item: must be string or a nested transform object ---
+    values.forEach((item, idx) => {
+        if (item === null || item === undefined) {
+            push(msgs, "warn", `values[${idx}] is null/undefined — this will produce the string "null"/"undefined" in the output. ` +
+                "Remove it or replace with a static string or a nested transform.", `attributes.values[${idx}]`);
+        }
+        else if (typeof item === "string") {
+            // Valid — static strings (including spaces, separators, literals) are expected
+        }
+        else if (isPlainObject(item)) {
+            if (typeof item.type !== "string" || item.type.trim() === "") {
+                push(msgs, "error", `values[${idx}] is an object but is missing a 'type' field — it does not look like a valid nested transform. ` +
+                    "Add a 'type' (e.g., 'accountAttribute', 'identityAttribute', 'static').", `attributes.values[${idx}]`);
+            }
+        }
+        else {
+            push(msgs, "error", `values[${idx}] must be a string or a nested transform object {type, attributes}. ` +
+                `Got: ${typeof item}.`, `attributes.values[${idx}]`);
+        }
+    });
+    // --- 4. Separator hint: inform if no explicit spacing string found between transform objects ---
+    const allTransforms = values.every((v) => isPlainObject(v));
+    if (allTransforms && values.length > 1) {
+        push(msgs, "info", "concat does not insert any separator between values automatically. " +
+            "If the output needs spaces, hyphens, or other delimiters, add them as explicit string entries " +
+            "in the values array (e.g., [firstName, \" \", lastName]).", "attributes.values");
+    }
+    return msgs;
+}
+// ---------------------------------------------------------------------------
 // Main lintTransform export
 // ---------------------------------------------------------------------------
 export function lintTransform(input) {
@@ -1502,6 +1583,8 @@ export function lintTransform(input) {
         messages.push(...lintRandom(requestedType, attrs));
     if (requestedType === "rfc5646")
         messages.push(...lintRfc5646(attrs));
+    if (requestedType === "concat")
+        messages.push(...lintConcat(attrs));
     // --- Recursive nested transform lint ---
     // Recursively lint every nested transform found inside attributes.
     // We start from normalized.attributes (not the root) to avoid double-linting root.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isc-transforms-mcp",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "type": "module",
   "description": "MCP server for SailPoint Identity Security Cloud (ISC) Transform authoring — scaffold, strict lint, catalog, and safe upsert to live tenants.",
   "author": {