@uipath/packager-tool-datafabric 1.201.0-preview.134

package/src/schema/create-entity-skeleton.ts

@@ -0,0 +1,104 @@
+import {
+    type EntityField,
+    type EntityJSON,
+    FieldDisplayType,
+    SqlTypeName,
+} from "@uipath/entity-modeler/schema";
+
+/** Data Fabric resolves this on actual resource creation. Same sentinel Studio
+ *  Web writes (`UNASSIGNED_FOLDER_ID` in custom-render/data-service). */
+const UNASSIGNED_FOLDER_ID = "99999999-9999-9999-9999-999999999999";
+
+/** Every property a system field pins, mirroring Studio Web's
+ *  `SYSTEM_FIELD_DEFAULTS`. Each template below overrides only what differs. */
+const SYSTEM_FIELD_DEFAULTS = {
+    IsPrimaryKey: false,
+    IsForeignKey: false,
+    IsExternalField: false,
+    IsHiddenField: true,
+    FieldCategoryId: 0,
+    IsUnique: false,
+    ReferenceType: "ManyToOne",
+    Transformation: null,
+    IsRequired: false,
+    IsEncrypted: false,
+    Description: "",
+    IsSystemField: true,
+    FieldDisplayType: FieldDisplayType.Basic,
+    IsAttachment: false,
+    IsRbacEnabled: false,
+    IsModelReserved: false,
+} as const satisfies Partial<EntityField>;
+
+/** The 5 canonical system fields, in Studio Web's order. Also the validator's
+ *  source of truth for "unmodified system fields": every property here is
+ *  compared, and properties absent here are not. */
+export const SYSTEM_FIELD_TEMPLATES: readonly EntityField[] = [
+    {
+        ...SYSTEM_FIELD_DEFAULTS,
+        Name: "Id",
+        DisplayName: "Id",
+        IsPrimaryKey: true,
+        SqlType: { Name: SqlTypeName.UNIQUEIDENTIFIER },
+    },
+    {
+        ...SYSTEM_FIELD_DEFAULTS,
+        Name: "CreateTime",
+        DisplayName: "CreateTime",
+        SqlType: { Name: SqlTypeName.DATETIMEOFFSET },
+    },
+    {
+        ...SYSTEM_FIELD_DEFAULTS,
+        Name: "CreatedBy",
+        DisplayName: "CreatedBy",
+        FieldDisplayType: FieldDisplayType.Relationship,
+        SqlType: { Name: SqlTypeName.UNIQUEIDENTIFIER },
+    },
+    {
+        ...SYSTEM_FIELD_DEFAULTS,
+        Name: "UpdateTime",
+        DisplayName: "UpdateTime",
+        SqlType: { Name: SqlTypeName.DATETIMEOFFSET },
+    },
+    {
+        ...SYSTEM_FIELD_DEFAULTS,
+        Name: "UpdatedBy",
+        DisplayName: "UpdatedBy",
+        FieldDisplayType: FieldDisplayType.Relationship,
+        SqlType: { Name: SqlTypeName.UNIQUEIDENTIFIER },
+    },
+];
+
+/**
+ * A new entity's starting schema: the 5 system fields and the empty runtime
+ * defaults, in the order and shape Studio Web's `_initializeFromValues` writes,
+ * so an entity authored here and one authored there are the same document.
+ * Pure, no I/O. A system-fields-only entity is valid and deployable. `name` is
+ * used as-is — validity is the validator's concern, not this factory's.
+ */
+export function createEntitySkeleton(name: string): EntityJSON {
+    return {
+        Id: globalThis.crypto.randomUUID(),
+        Name: name,
+        DisplayName: name,
+        EntityTypeId: 0,
+        EntityType: "Entity",
+        Description: "",
+        FolderId: UNASSIGNED_FOLDER_ID,
+        Fields: SYSTEM_FIELD_TEMPLATES.map((template) => ({
+            ...template,
+            SqlType: { ...template.SqlType },
+        })),
+        Data: null,
+        ExternalFields: null,
+        SourceJoinCriterias: null,
+        RecordCount: 0,
+        StorageSizeInMB: null,
+        UsedStorageSizeInMB: null,
+        AttachmentSizeInByte: null,
+        IsRbacEnabled: false,
+        InvalidIdentifiers: [],
+        IsModelReserved: false,
+        CategoryId: null,
+    };
+}

package/src/schema/validate-entity.ts

@@ -0,0 +1,208 @@
+import { findReservedNameError } from "@uipath/common/entity-name-rules";
+import {
+    ALLOWED_TYPE_PAIRS,
+    type EntityField,
+    type EntityJSON,
+    NAME_PATTERN,
+} from "@uipath/entity-modeler/schema";
+import { SYSTEM_FIELD_TEMPLATES } from "./create-entity-skeleton.js";
+
+/** Stable diagnostic codes: the editor keys Problems entries and pack output on
+ *  these. Messages are for humans and may change. */
+export const DIAGNOSTIC_CODES = {
+    entityNameInvalid: "ENTITY_NAME_INVALID",
+    entityNameNotUnique: "ENTITY_NAME_NOT_UNIQUE",
+    fieldNameInvalid: "FIELD_NAME_INVALID",
+    duplicateFieldName: "DUPLICATE_FIELD_NAME",
+    fieldTypeNotAllowed: "FIELD_TYPE_NOT_ALLOWED",
+    nameReserved: "NAME_RESERVED",
+    systemFieldMissing: "SYSTEM_FIELD_MISSING",
+    systemFieldModified: "SYSTEM_FIELD_MODIFIED",
+} as const;
+export type DiagnosticCode =
+    (typeof DIAGNOSTIC_CODES)[keyof typeof DIAGNOSTIC_CODES];
+
+export interface EntityDiagnostic {
+    code: DiagnosticCode;
+    /** Human-readable, actionable message. */
+    message: string;
+    severity: "error";
+    /** The field the diagnostic is about, when field-scoped. */
+    fieldName?: string;
+}
+
+export interface ValidateEntityContext {
+    /** Every OTHER entity name in the solution; only the host knows these. */
+    siblingNames: readonly string[];
+}
+
+/**
+ * Every schema rule in one place: the editor runs it on each edit and pack runs
+ * it again, so the two can never disagree. Returns ALL diagnostics rather than
+ * stopping at the first, and never throws.
+ */
+export function validateEntity(
+    entity: EntityJSON,
+    ctx: ValidateEntityContext,
+): EntityDiagnostic[] {
+    const diagnostics: EntityDiagnostic[] = [];
+
+    if (!NAME_PATTERN.test(entity.Name)) {
+        diagnostics.push({
+            code: DIAGNOSTIC_CODES.entityNameInvalid,
+            message: `Entity name '${entity.Name}' must start with a letter and contain 3-100 letters or digits.`,
+            severity: "error",
+        });
+    }
+
+    // The server's reserved lists, shared with `uip df entities create` so the
+    // two authors cannot drift. Checked separately from the pattern above, which
+    // is the modeller's format rule.
+    const reservedEntityName = findReservedNameError(entity.Name, "entity");
+    if (reservedEntityName) {
+        diagnostics.push({
+            code: DIAGNOSTIC_CODES.nameReserved,
+            message: `${reservedEntityName.message}. ${reservedEntityName.instructions}`,
+            severity: "error",
+        });
+    }
+
+    const entityNameLower = entity.Name.toLowerCase();
+    if (
+        ctx.siblingNames.some(
+            (sibling) => sibling.toLowerCase() === entityNameLower,
+        )
+    ) {
+        diagnostics.push({
+            code: DIAGNOSTIC_CODES.entityNameNotUnique,
+            message: `An entity named '${entity.Name}' already exists in this solution. Entity names are solution-wide unique.`,
+            severity: "error",
+        });
+    }
+
+    const seenFieldNames = new Map<string, string>();
+    for (const field of entity.Fields) {
+        // Custom fields only: system names are canonical ("Id" is 2 chars) and
+        // pinned by the integrity check below.
+        if (!field.IsSystemField && !NAME_PATTERN.test(field.Name)) {
+            diagnostics.push({
+                code: DIAGNOSTIC_CODES.fieldNameInvalid,
+                message: `Field name '${field.Name}' must start with a letter and contain 3-100 letters or digits.`,
+                severity: "error",
+                fieldName: field.Name,
+            });
+        }
+
+        if (!field.IsSystemField) {
+            const reservedFieldName = findReservedNameError(
+                field.Name,
+                "field",
+            );
+            if (reservedFieldName) {
+                diagnostics.push({
+                    code: DIAGNOSTIC_CODES.nameReserved,
+                    message: `${reservedFieldName.message}. ${reservedFieldName.instructions}`,
+                    severity: "error",
+                    fieldName: field.Name,
+                });
+            }
+        }
+
+        const fieldNameLower = field.Name.toLowerCase();
+        const firstWithName = seenFieldNames.get(fieldNameLower);
+        if (firstWithName !== undefined) {
+            diagnostics.push({
+                code: DIAGNOSTIC_CODES.duplicateFieldName,
+                message: `Duplicate field name '${field.Name}' (names are case-insensitive; first defined as '${firstWithName}').`,
+                severity: "error",
+                fieldName: field.Name,
+            });
+        } else {
+            seenFieldNames.set(fieldNameLower, field.Name);
+        }
+
+        // Custom fields only, again: system fields use pairs the palette
+        // doesn't offer and are pinned by the integrity check instead. This is
+        // also what rejects custom Relationship fields.
+        if (
+            !field.IsSystemField &&
+            !ALLOWED_TYPE_PAIRS.has(
+                `${field.FieldDisplayType}:${field.SqlType.Name}`,
+            )
+        ) {
+            diagnostics.push({
+                code: DIAGNOSTIC_CODES.fieldTypeNotAllowed,
+                message:
+                    `Field '${field.Name}' uses an unsupported type combination ` +
+                    `(${field.FieldDisplayType} / ${field.SqlType.Name}).`,
+                severity: "error",
+                fieldName: field.Name,
+            });
+        }
+    }
+
+    diagnostics.push(...validateSystemFields(entity));
+
+    return diagnostics;
+}
+
+/** Properties Data Fabric assigns when it creates the resource. A document that
+ *  has round-tripped through the service carries these; they are not edits. */
+const SERVER_ASSIGNED_FIELD_PROPS: ReadonlySet<string> = new Set([
+    "Id",
+    "CreateTime",
+    "CreatedBy",
+    "UpdateTime",
+    "UpdatedBy",
+]);
+
+/**
+ * Does `actual` still match the canonical template? Every property the template
+ * pins must be equal — Studio Web fixes all of them, since system fields are not
+ * editable — and `actual` may add nothing beyond the server-assigned set. The
+ * second half is what catches a retargeted system FK: `ReferenceEntity` is not a
+ * template property, so ignoring unknown keys would let it through.
+ */
+function isUnmodifiedSystemField(
+    template: EntityField,
+    actual: EntityField,
+): boolean {
+    const equal = (left: unknown, right: unknown): boolean =>
+        JSON.stringify(left ?? null) === JSON.stringify(right ?? null);
+
+    for (const key of Object.keys(template) as Array<keyof EntityField>) {
+        if (!equal(template[key], actual[key])) {
+            return false;
+        }
+    }
+    return Object.keys(actual).every(
+        (key) => key in template || SERVER_ASSIGNED_FIELD_PROPS.has(key),
+    );
+}
+
+function validateSystemFields(entity: EntityJSON): EntityDiagnostic[] {
+    const diagnostics: EntityDiagnostic[] = [];
+    for (const template of SYSTEM_FIELD_TEMPLATES) {
+        const actual = entity.Fields.find(
+            (field) => field.Name === template.Name,
+        );
+        if (!actual) {
+            diagnostics.push({
+                code: DIAGNOSTIC_CODES.systemFieldMissing,
+                message: `System field '${template.Name}' is missing. System fields cannot be removed.`,
+                severity: "error",
+                fieldName: template.Name,
+            });
+            continue;
+        }
+        if (!isUnmodifiedSystemField(template, actual)) {
+            diagnostics.push({
+                code: DIAGNOSTIC_CODES.systemFieldModified,
+                message: `System field '${template.Name}' was modified. System fields are read-only.`,
+                severity: "error",
+                fieldName: template.Name,
+            });
+        }
+    }
+    return diagnostics;
+}