@uipath/data-fabric-tool 1.198.0 → 1.199.0-preview.104

package/src/utils/validate.ts

@@ -0,0 +1,611 @@
+/**
+ * Client-side validators for Data Fabric authoring bodies.
+ *
+ * Each helper checks one rule and returns either `null` (OK) or a
+ * `ValidationError` (from @uipath/common) the caller can hand straight to
+ * `fail()`.
+ *
+ * These catch known footguns before the request hits the server:
+ * - UI-broken field types the server accepts but the Data Fabric UI can't render.
+ * - Entity / field names that violate the server's format, reserved-name, or
+ *   reserved-keyword rules (the server rejects them, but with unhelpful codes).
+ * - `isUnique` toggled in an `updateFields` payload, which the server silently
+ *   ignores while still returning Success.
+ * - Choice-set value `Name` fields that hit the server's case-sensitive
+ *   keyword blocklist (with the additional NumberId-shift footgun a failed
+ *   value-create leaves behind).
+ */
+
+import type { ValidationError } from "@uipath/common";
+
+export type { ValidationError } from "@uipath/common";
+
+// Types the SDK enum still exposes but that render broken in the Data Fabric UI.
+// The server accepts them and `entities create` returns Success; the column then
+// can't be rendered, filtered, or edited in the UI.
+export const UI_BROKEN_FIELD_TYPES = new Set([
+    "INTEGER",
+    "BIG_INTEGER",
+    "FLOAT",
+    "DOUBLE",
+    "UUID",
+    "DATETIME",
+]);
+
+const UI_BROKEN_SUBSTITUTIONS: Record<string, string> = {
+    INTEGER: "DECIMAL with decimalPrecision: 0",
+    BIG_INTEGER: "DECIMAL with decimalPrecision: 0",
+    FLOAT: "DECIMAL with a required decimalPrecision",
+    DOUBLE: "DECIMAL with a required decimalPrecision",
+    UUID: "RELATIONSHIP (if it's a foreign key) or STRING",
+    DATETIME: "DATETIME_WITH_TZ",
+};
+
+// System-generated columns present on every entity — reusing these names errors.
+const RESERVED_FIELD_NAMES = new Set([
+    "Id",
+    "CreatedBy",
+    "CreateTime",
+    "UpdatedBy",
+    "UpdateTime",
+]);
+
+// The commonly-hit C# / VB reserved words the server rejects with
+// `RESERVED_LANGUAGE_KEYWORDS`. Match is case-insensitive: the server treats
+// `Class`, `class`, and `CLASS` all as the same keyword.
+// Not exhaustive — the authoritative list lives server-side. Any keyword that
+// slips through still hits the server error path, which the CLI surfaces
+// verbatim.
+const RESERVED_KEYWORDS_LOWER = new Set([
+    "case",
+    "class",
+    "if",
+    "then",
+    "else",
+    "new",
+    "object",
+    "public",
+    "return",
+    "select",
+    "internal",
+    "private",
+    "static",
+]);
+
+const NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]{2,99}$/;
+
+export type NameKind = "entity" | "field" | "choice set";
+
+/**
+ * Check an entity / field / choice-set name against the server's format,
+ * reserved-name, and reserved-keyword rules.
+ */
+export function validateName(
+    name: string,
+    kind: NameKind,
+): ValidationError | null {
+    // Reserved / keyword checks fire before the format check so short reserved
+    // names like `Id`, `If`, `New` get the actionable message instead of the
+    // generic "too short" one.
+    if (kind === "field" && RESERVED_FIELD_NAMES.has(name)) {
+        return {
+            message: `Field name '${name}' is reserved`,
+            instructions: `The following field names are reserved by the platform: ${[...RESERVED_FIELD_NAMES].join(", ")}. Pick a different name.`,
+        };
+    }
+
+    if (RESERVED_KEYWORDS_LOWER.has(name.toLowerCase())) {
+        return {
+            message: `${kind === "entity" ? "Entity" : kind === "field" ? "Field" : "Choice set"} name '${name}' is a reserved C# or VB keyword`,
+            instructions:
+                "Reserved keywords are rejected with RESERVED_LANGUAGE_KEYWORDS. Pick a domain-specific rename, for example 'Case' -> 'WorkItem', 'Class' -> 'Category', 'New' -> 'IsNew'.",
+        };
+    }
+
+    if (!NAME_PATTERN.test(name)) {
+        return {
+            message: `Invalid ${kind} name '${name}'`,
+            instructions:
+                "Names must start with a letter, contain only letters, digits, and underscores, and be 3-100 characters long.",
+        };
+    }
+
+    return null;
+}
+
+/**
+ * Scan a list of field definitions for names that fail validation. Returns
+ * the first failure; callers should surface it and let the user fix the body
+ * before calling again.
+ */
+export function findInvalidFieldName(
+    fields: unknown[],
+): ValidationError | null {
+    for (const f of fields) {
+        if (typeof f !== "object" || f === null) continue;
+        const fieldName = (f as Record<string, unknown>).fieldName;
+        if (typeof fieldName !== "string") continue;
+        const err = validateName(fieldName, "field");
+        if (err) return err;
+    }
+    return null;
+}
+
+/**
+ * Scan a list of field definitions for any type value that lives in
+ * `UI_BROKEN_FIELD_TYPES`. Returns the first offender's suggested
+ * substitution.
+ */
+export function findUiBrokenFieldType(
+    fields: unknown[],
+): ValidationError | null {
+    for (const f of fields) {
+        if (typeof f !== "object" || f === null) continue;
+        const rec = f as Record<string, unknown>;
+        const type = rec.type;
+        if (typeof type !== "string") continue;
+        if (UI_BROKEN_FIELD_TYPES.has(type)) {
+            const fieldName =
+                typeof rec.fieldName === "string" ? rec.fieldName : "<field>";
+            const substitute = UI_BROKEN_SUBSTITUTIONS[type];
+            return {
+                message: `Field '${fieldName}' uses type '${type}' which the Data Fabric UI cannot render`,
+                instructions: `The server accepts '${type}' but the UI cannot render, filter, or edit the column. Use ${substitute} instead. UI-broken types: ${[...UI_BROKEN_FIELD_TYPES].join(", ")}.`,
+            };
+        }
+    }
+    return null;
+}
+
+// `referenceFolderKey` is a per-field folder hint used by RELATIONSHIP / FILE
+// fields to point at a target that lives in a specific folder. CHOICE_SET_*
+// fields resolve their folder server-side from `choiceSetId`, so passing
+// `referenceFolderKey` on a CHOICE_SET_* field is always wrong. Reject it up
+// front instead of letting the server return a misleading cross-scope error.
+export function findReferenceFolderKeyOnChoiceSet(
+    fields: unknown[],
+): ValidationError | null {
+    for (const f of fields) {
+        if (typeof f !== "object" || f === null) continue;
+        const rec = f as Record<string, unknown>;
+        const type = rec.type;
+        if (
+            (type === "CHOICE_SET_SINGLE" || type === "CHOICE_SET_MULTIPLE") &&
+            rec.referenceFolderKey !== undefined
+        ) {
+            const fieldName =
+                typeof rec.fieldName === "string" ? rec.fieldName : "<field>";
+            return {
+                message: `CHOICE_SET_* field '${fieldName}' must not pass 'referenceFolderKey'`,
+                instructions:
+                    "The server resolves a choice set's folder from 'choiceSetId' alone. Passing 'referenceFolderKey' here is rejected by the platform with a misleading cross-scope error. Drop 'referenceFolderKey' from CHOICE_SET_SINGLE / CHOICE_SET_MULTIPLE field definitions.",
+            };
+        }
+    }
+    return null;
+}
+
+// Complex field types need extra config the SDK enum alone can't teach:
+// CHOICE_SET_* takes a choiceSetId; RELATIONSHIP takes referenceEntityId +
+// referenceFieldId. Missing extras trip a less-informative server error;
+// catch them up front with the field name spelled out.
+export function findMissingComplexFieldExtras(
+    fields: unknown[],
+): ValidationError | null {
+    for (const f of fields) {
+        if (typeof f !== "object" || f === null) continue;
+        const rec = f as Record<string, unknown>;
+        const type = rec.type;
+        if (typeof type !== "string") continue;
+        const fieldName =
+            typeof rec.fieldName === "string" ? rec.fieldName : "<field>";
+
+        if (type === "CHOICE_SET_SINGLE" || type === "CHOICE_SET_MULTIPLE") {
+            if (
+                typeof rec.choiceSetId !== "string" ||
+                rec.choiceSetId.trim() === ""
+            ) {
+                return {
+                    message: `Field '${fieldName}' (type '${type}') requires 'choiceSetId'`,
+                    instructions:
+                        "Set 'choiceSetId' to the UUID from 'uip df choice-sets list'. If the target choice set doesn't exist, create it with 'uip df choice-sets create' first.",
+                };
+            }
+        } else if (type === "RELATIONSHIP") {
+            if (
+                typeof rec.referenceEntityId !== "string" ||
+                rec.referenceEntityId.trim() === ""
+            ) {
+                return {
+                    message: `Field '${fieldName}' (type 'RELATIONSHIP') requires 'referenceEntityId'`,
+                    instructions:
+                        "Set 'referenceEntityId' to the UUID of the target entity from 'uip df entities list --native-only'.",
+                };
+            }
+            if (
+                typeof rec.referenceFieldId !== "string" ||
+                rec.referenceFieldId.trim() === ""
+            ) {
+                return {
+                    message: `Field '${fieldName}' (type 'RELATIONSHIP') requires 'referenceFieldId'`,
+                    instructions:
+                        "Set 'referenceFieldId' to the UUID of the display field on the target entity — get it from 'uip df entities get <target-entity-id>' (Fields[].Id). This controls which target field renders in the UI; the stored value is always the target record's Id UUID.",
+                };
+            }
+        }
+    }
+    return null;
+}
+
+// Per-type constraint validity: lengthLimit / maxValue / minValue /
+// decimalPrecision each apply to specific types. Passing one to an
+// unsupported type errors server-side with a generic "does not accept"
+// message. Catch it up front and cite the allowed range.
+const LENGTH_LIMIT_RANGES: Record<string, [number, number]> = {
+    STRING: [1, 4000],
+    MULTILINE_TEXT: [1, 10000],
+    MULTILINE_MAX: [1, 131072],
+};
+
+function isNumber(v: unknown): v is number {
+    return typeof v === "number" && Number.isFinite(v);
+}
+
+export function findInvalidFieldConstraints(
+    fields: unknown[],
+): ValidationError | null {
+    for (const f of fields) {
+        if (typeof f !== "object" || f === null) continue;
+        const rec = f as Record<string, unknown>;
+        const type = rec.type;
+        if (typeof type !== "string") continue;
+        const fieldName =
+            typeof rec.fieldName === "string" ? rec.fieldName : "<field>";
+
+        if (rec.lengthLimit !== undefined) {
+            if (!isNumber(rec.lengthLimit)) {
+                return {
+                    message: `Field '${fieldName}' 'lengthLimit' must be a number`,
+                    instructions:
+                        "Pass a positive integer within the type's range (STRING 1-4000, MULTILINE_TEXT 1-10000, MULTILINE_MAX 1-131072 UTF-16 bytes).",
+                };
+            }
+            const range = LENGTH_LIMIT_RANGES[type];
+            if (range === undefined) {
+                return {
+                    message: `Field '${fieldName}' of type '${type}' does not accept 'lengthLimit'`,
+                    instructions:
+                        "'lengthLimit' applies only to STRING, MULTILINE_TEXT, and MULTILINE_MAX. Remove it or change the field type.",
+                };
+            }
+            const [min, max] = range;
+            if (rec.lengthLimit < min || rec.lengthLimit > max) {
+                return {
+                    message: `Field '${fieldName}' 'lengthLimit' ${rec.lengthLimit} is outside the allowed range for type '${type}'`,
+                    instructions: `'lengthLimit' on '${type}' must be between ${min} and ${max}. MULTILINE_MAX 'lengthLimit' is a UTF-16 byte budget (≈2 per char).`,
+                };
+            }
+        }
+
+        if (rec.maxValue !== undefined || rec.minValue !== undefined) {
+            if (type !== "DECIMAL") {
+                const which =
+                    rec.maxValue !== undefined ? "maxValue" : "minValue";
+                return {
+                    message: `Field '${fieldName}' of type '${type}' does not accept '${which}'`,
+                    instructions:
+                        "'minValue' and 'maxValue' apply only to DECIMAL. Remove them or change the field type.",
+                };
+            }
+            if (rec.maxValue !== undefined && !isNumber(rec.maxValue)) {
+                return {
+                    message: `Field '${fieldName}' 'maxValue' must be a number`,
+                    instructions: "Pass a numeric value.",
+                };
+            }
+            if (rec.minValue !== undefined && !isNumber(rec.minValue)) {
+                return {
+                    message: `Field '${fieldName}' 'minValue' must be a number`,
+                    instructions: "Pass a numeric value.",
+                };
+            }
+            if (
+                rec.maxValue !== undefined &&
+                rec.minValue !== undefined &&
+                (rec.minValue as number) >= (rec.maxValue as number)
+            ) {
+                return {
+                    message: `Field '${fieldName}' 'minValue' (${rec.minValue}) must be strictly less than 'maxValue' (${rec.maxValue})`,
+                    instructions:
+                        "Adjust the bounds so 'minValue < maxValue', or drop one of the two.",
+                };
+            }
+        }
+
+        if (rec.decimalPrecision !== undefined) {
+            if (type !== "DECIMAL") {
+                return {
+                    message: `Field '${fieldName}' of type '${type}' does not accept 'decimalPrecision'`,
+                    instructions:
+                        "'decimalPrecision' applies only to DECIMAL. Remove it or change the field type.",
+                };
+            }
+            if (
+                !isNumber(rec.decimalPrecision) ||
+                !Number.isInteger(rec.decimalPrecision) ||
+                rec.decimalPrecision < 0 ||
+                rec.decimalPrecision > 10
+            ) {
+                return {
+                    message: `Field '${fieldName}' 'decimalPrecision' ${rec.decimalPrecision} is invalid`,
+                    instructions:
+                        "'decimalPrecision' must be an integer between 0 and 10 (0 for whole numbers, 2 for money).",
+                };
+            }
+        }
+    }
+    return null;
+}
+
+// Choice-set-value Name blocklist — case-sensitive, partial list.
+//
+// The server's choice-set-value validator is a different code path from the
+// entity / field-name validator, with different behavior: match is
+// case-sensitive (`Class` may pass while `class` is rejected) and the list
+// is narrower. Reject the lowercase tokens the server is known to reject;
+// let the server catch anything else. The known bug where a rejected
+// value-create shifts subsequent NumberIds is documented for the caller —
+// this validator's job is to prevent the failed create in the first place.
+const CHOICE_VALUE_KEYWORDS = new Set([
+    "internal",
+    "public",
+    "private",
+    "class",
+    "case",
+    "new",
+    "default",
+    "static",
+    "void",
+    "event",
+    "lock",
+    "object",
+    "string",
+    "int",
+]);
+
+const CHOICE_VALUE_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]{2,99}$/;
+
+/**
+ * Validate the `Name` argument of `choice-set-values create`. See
+ * data-fabric-tool `choice-sets.md` -> Value `Name` validation for the full
+ * story on why the rules differ from entity / field names.
+ */
+export function validateChoiceValueName(name: string): ValidationError | null {
+    if (!CHOICE_VALUE_NAME_PATTERN.test(name)) {
+        return {
+            message: `Invalid choice-set value name '${name}'`,
+            instructions:
+                "Choice-set value names must start with a letter, contain only letters, digits, and underscores, and be 3-100 characters long.",
+        };
+    }
+
+    if (CHOICE_VALUE_KEYWORDS.has(name)) {
+        return {
+            message: `Choice-set value name '${name}' is a reserved C# keyword`,
+            instructions:
+                "The server's choice-set-value validator is case-sensitive and rejects known reserved keywords. Use lowercase snake_case with a suffix so the token no longer matches, and move the label to --display-name. Example: --display-name \"Internal\" with a name of 'internal_audit'.",
+        };
+    }
+
+    return null;
+}
+
+// Operator tokens the server accepts on a `queryFilters[]` leaf. Anything
+// else (`==`, `equals`, `Equals`, `like`, `BETWEEN`, `regex`, …) trips a
+// server 400 with a message that doesn't teach the tokens; catch it here.
+const FILTER_OPERATORS = new Set([
+    "=",
+    "!=",
+    ">",
+    "<",
+    ">=",
+    "<=",
+    "contains",
+    "not contains",
+    "startswith",
+    "endswith",
+    "in",
+    "not in",
+]);
+
+const VALUELIST_OPERATORS = new Set(["in", "not in"]);
+
+const FILTER_OPERATORS_LIST = [...FILTER_OPERATORS]
+    .map((o) => `'${o}'`)
+    .join(", ");
+
+function validateFilterLeaf(
+    leaf: unknown,
+    path: string,
+): ValidationError | null {
+    if (typeof leaf !== "object" || leaf === null) {
+        return {
+            message: `${path} must be a filter object`,
+            instructions:
+                "Each queryFilters entry must be an object with fieldName, operator, and value (or valueList for 'in' / 'not in').",
+        };
+    }
+    const rec = leaf as Record<string, unknown>;
+
+    if (typeof rec.fieldName !== "string" || rec.fieldName.trim() === "") {
+        return {
+            message: `${path}.fieldName must be a non-empty string`,
+            instructions:
+                'Set fieldName to the column you want to filter, for example {"fieldName":"Status","operator":"=","value":"Active"}.',
+        };
+    }
+
+    if (typeof rec.operator !== "string") {
+        return {
+            message: `${path}.operator must be a string`,
+            instructions: `Supported operators: ${FILTER_OPERATORS_LIST}.`,
+        };
+    }
+    if (!FILTER_OPERATORS.has(rec.operator)) {
+        return {
+            message: `${path} uses unsupported operator '${rec.operator}'`,
+            instructions: `The server rejects operators outside the supported set. Supported: ${FILTER_OPERATORS_LIST}. Compose BETWEEN as '>=' + '<=' in one queryFilters group; use 'contains' / 'startswith' / 'endswith' in place of regex.`,
+        };
+    }
+
+    const needsValueList = VALUELIST_OPERATORS.has(rec.operator);
+    if (needsValueList) {
+        if (!Array.isArray(rec.valueList)) {
+            return {
+                message: `${path} operator '${rec.operator}' requires 'valueList' array`,
+                instructions:
+                    '\'in\' and \'not in\' take a JSON array of values under \'valueList\', for example {"fieldName":"Status","operator":"in","valueList":["A","B"]}.',
+            };
+        }
+    } else {
+        // Every other operator uses 'value'. `null` is legal — it means
+        // is-empty (with `=`) or is-not-empty (with `!=`). Missing key is
+        // rejected so the user notices; the server accepts `undefined` but
+        // silently returns unfiltered rows.
+        if (!("value" in rec)) {
+            return {
+                message: `${path} operator '${rec.operator}' requires 'value'`,
+                instructions:
+                    "Set 'value' to the JSON-string form of the compared value. Use null for is-empty ('=' with null) / is-not-empty ('!=' with null).",
+            };
+        }
+    }
+
+    return null;
+}
+
+function validateFilterGroup(
+    group: unknown,
+    path: string,
+): ValidationError | null {
+    if (typeof group !== "object" || group === null || Array.isArray(group)) {
+        return {
+            message: `${path} must be an object`,
+            instructions:
+                "A filter group is {logicalOperator, queryFilters, filterGroups?}.",
+        };
+    }
+    const rec = group as Record<string, unknown>;
+
+    if (rec.logicalOperator !== undefined) {
+        const op = rec.logicalOperator;
+        const okString =
+            typeof op === "string" && /^(and|or)$/i.test(op.trim());
+        const okNumber = op === 0 || op === 1;
+        if (!okString && !okNumber) {
+            return {
+                message: `${path}.logicalOperator must be 'AND' / 'OR' / 0 / 1`,
+                instructions:
+                    "Use the integer form (0 for AND, 1 for OR) or the string form ('AND' / 'OR', case-insensitive).",
+            };
+        }
+    }
+
+    if (rec.queryFilters !== undefined) {
+        if (!Array.isArray(rec.queryFilters)) {
+            return {
+                message: `${path}.queryFilters must be an array`,
+                instructions:
+                    "queryFilters is an array of {fieldName, operator, value|valueList} clauses.",
+            };
+        }
+        for (let i = 0; i < rec.queryFilters.length; i++) {
+            const err = validateFilterLeaf(
+                rec.queryFilters[i],
+                `${path}.queryFilters[${i}]`,
+            );
+            if (err) return err;
+        }
+    }
+
+    if (rec.filterGroups !== undefined) {
+        if (!Array.isArray(rec.filterGroups)) {
+            return {
+                message: `${path}.filterGroups must be an array`,
+                instructions:
+                    "filterGroups is an array of nested groups, each with the same shape as the parent.",
+            };
+        }
+        for (let i = 0; i < rec.filterGroups.length; i++) {
+            const err = validateFilterGroup(
+                rec.filterGroups[i],
+                `${path}.filterGroups[${i}]`,
+            );
+            if (err) return err;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Validate the `filterGroup` on a `records query` body. Catches unsupported
+ * operator tokens, missing value / valueList, and malformed nested groups
+ * without an SDK round-trip. Does NOT enforce the operator x field-type
+ * matrix — that needs the target entity's schema (deferred).
+ */
+export function validateQueryFilter(
+    filterGroup: unknown,
+): ValidationError | null {
+    if (filterGroup === undefined) return null;
+    return validateFilterGroup(filterGroup, "filterGroup");
+}
+
+/**
+ * `records insert` / `records update` silently strip any key whose target
+ * field is FILE-typed — the server returns Success and the file column is
+ * unchanged. Refuse the call up front so callers don't ship a body they
+ * assume was accepted. The caller provides the FILE field names (from
+ * `entities.getById`); this stays SDK-free.
+ */
+export function findFilePayloadKeys(
+    records: unknown[],
+    fileFieldNames: Set<string>,
+): ValidationError | null {
+    if (fileFieldNames.size === 0) return null;
+    for (let i = 0; i < records.length; i++) {
+        const rec = records[i];
+        if (typeof rec !== "object" || rec === null) continue;
+        for (const key of Object.keys(rec as Record<string, unknown>)) {
+            if (fileFieldNames.has(key)) {
+                return {
+                    message: `Record #${i} includes FILE-typed field '${key}'`,
+                    instructions: `The server silently drops FILE values from records insert / update payloads and returns Success unchanged. Omit '${key}' from the body, then attach the file with 'uip df files upload <entity-id> <record-id> ${key} --file <path>'. To clear, use 'uip df files delete'.`,
+                };
+            }
+        }
+    }
+    return null;
+}
+
+/**
+ * `updateFields` cannot change `isUnique` — the server returns Success but
+ * silently ignores the value. Refuse the call up front so callers don't
+ * report a change that never happened.
+ */
+export function findIsUniqueInUpdateFields(
+    updateFields: unknown[],
+): ValidationError | null {
+    for (const f of updateFields) {
+        if (typeof f !== "object" || f === null) continue;
+        const rec = f as Record<string, unknown>;
+        if (rec.isUnique === undefined) continue;
+        const fieldId = typeof rec.id === "string" ? rec.id : "<unknown>";
+        return {
+            message: `Cannot change 'isUnique' on field '${fieldId}' via updateFields`,
+            instructions:
+                "'isUnique' is fixed at field creation. The server silently ignores it on updateFields while still returning Success. To change uniqueness, drop the field with removeFields and re-add it with addFields (this drops every existing value in the column).",
+        };
+    }
+    return null;
+}