@player-tools/xlr-sdk 0.9.0 → 0.9.1--canary.196.4186

package/src/validator.ts

@@ -16,16 +16,29 @@ import {
   resolveReferenceNode,
   computeEffectiveObject,
 } from "@player-tools/xlr-utils";
-import type { ValidationError } from "./types";
+import { ValidationSeverity } from "./types";
+import type { ValidationMessage } from "./types";
+
+export interface XLRValidatorConfig {
+  /** URL mapping for supplemental documentation */
+  urlMapping?: Record<string, string>;
+}
+
+const MAX_VALID_SHOWN = 20;
 
 /**
  * Validator for XLRs on JSON Nodes
  */
 export class XLRValidator {
+  private config: XLRValidatorConfig;
   private resolveType: (id: string) => NamedType<NodeType> | undefined;
   private regexCache: Map<string, RegExp>;
 
-  constructor(resolveType: (id: string) => NamedType<NodeType> | undefined) {
+  constructor(
+    resolveType: (id: string) => NamedType<NodeType> | undefined,
+    config?: XLRValidatorConfig
+  ) {
+    this.config = config || {};
     this.resolveType = resolveType;
     this.regexCache = new Map();
   }
@@ -34,8 +47,8 @@ export class XLRValidator {
   public validateType(
     rootNode: Node,
     xlrNode: NodeType
-  ): Array<ValidationError> {
-    const validationIssues = new Array<ValidationError>();
+  ): Array<ValidationMessage> {
+    const validationIssues = new Array<ValidationMessage>();
     if (xlrNode.type === "object") {
       if (rootNode.type === "object") {
         validationIssues.push(...this.validateObject(xlrNode, rootNode));
@@ -44,6 +57,7 @@ export class XLRValidator {
           type: "type",
           node: rootNode,
           message: `Expected an object but got an "${rootNode.type}"`,
+          severity: ValidationSeverity.Error,
         });
       }
     } else if (xlrNode.type === "array") {
@@ -54,6 +68,7 @@ export class XLRValidator {
           type: "type",
           node: rootNode,
           message: `Expected an array but got an "${rootNode.type}"`,
+          severity: ValidationSeverity.Error,
         });
       }
     } else if (xlrNode.type === "template") {
@@ -62,31 +77,58 @@ export class XLRValidator {
         validationIssues.push(error);
       }
     } else if (xlrNode.type === "or") {
-      // eslint-disable-next-line no-restricted-syntax
+      const potentialTypeErrors: Array<{
+        type: NodeType;
+        errors: Array<ValidationMessage>;
+      }> = [];
+
       for (const potentialType of xlrNode.or) {
         const potentialErrors = this.validateType(rootNode, potentialType);
+
         if (potentialErrors.length === 0) {
           return validationIssues;
         }
+
+        potentialTypeErrors.push({
+          type: potentialType,
+          errors: potentialErrors,
+        });
       }
 
       let message: string;
+      const expectedTypes = xlrNode.or
+        .map((node) => node.name ?? node.title ?? node.type ?? "<unnamed type>")
+        .join(" | ");
 
       if (xlrNode.name) {
         message = `Does not match any of the expected types for type: '${xlrNode.name}'`;
       } else if (xlrNode.title) {
         message = `Does not match any of the expected types for property: '${xlrNode.title}'`;
       } else {
-        message = `Does not match any of the types ${xlrNode.or
-          .map((node) => node.name ?? node.title ?? "<unnamed type>")
-          .join(" | ")}`;
+        message = `Does not match any of the types: ${expectedTypes}`;
       }
 
+      const { infoMessage } = this.generateNestedTypesInfo(
+        potentialTypeErrors,
+        xlrNode,
+        rootNode
+      );
+
       validationIssues.push({
         type: "value",
         node: rootNode,
-        message,
+        message: message.trim(),
+        severity: ValidationSeverity.Error,
       });
+
+      if (infoMessage) {
+        validationIssues.push({
+          type: "value",
+          node: rootNode,
+          message: infoMessage,
+          severity: ValidationSeverity.Info,
+        });
+      }
     } else if (xlrNode.type === "and") {
       const effectiveType = {
         ...this.computeIntersectionType(xlrNode.and),
@@ -109,6 +151,7 @@ export class XLRValidator {
           type: "unknown",
           node: rootNode,
           message: `Type "${xlrNode.ref}" is not defined in provided bundles`,
+          severity: ValidationSeverity.Error,
         });
       } else {
         validationIssues.push(
@@ -127,12 +170,16 @@ export class XLRValidator {
             type: "type",
             node: rootNode.parent as Node,
             message: `Expected "${xlrNode.const}" but got "${rootNode.value}"`,
+            expected: xlrNode.const,
+            severity: ValidationSeverity.Error,
           });
         } else {
           validationIssues.push({
             type: "type",
             node: rootNode.parent as Node,
             message: `Expected type "${xlrNode.type}" but got "${rootNode.type}"`,
+            expected: xlrNode.type,
+            severity: ValidationSeverity.Error,
           });
         }
       }
@@ -173,15 +220,82 @@ export class XLRValidator {
     return validationIssues;
   }
 
+  private generateNestedTypesInfo(
+    potentialTypeErrors: Array<{
+      type: NodeType;
+      errors: Array<ValidationMessage>;
+    }>,
+    xlrNode: OrType,
+    rootNode: Node
+  ): { nestedTypesList: string; infoMessage?: string } {
+    const nestedTypes = new Set<string>();
+
+    // TODO: Create a recursive function that returns value or xlrNode info
+    // First, try to extract types from potential type errors
+    potentialTypeErrors.forEach((typeError) => {
+      if (typeError.type.type !== "template") {
+        typeError.errors.forEach((error) => {
+          if (error.type === "type" && error.expected) {
+            // Split by separate types if union
+            String(error.expected)
+              .split(" | ")
+              .forEach((val) => nestedTypes.add(val.trim()));
+          }
+        });
+      }
+    });
+
+    // If no types found from errors, try using type from xlrNode
+    if (nestedTypes.size === 0) {
+      xlrNode.or.forEach((type) => {
+        const typeName =
+          type.name ?? type.title ?? type.type ?? "<unnamed type>";
+        nestedTypes.add(typeName);
+      });
+    }
+
+    const nestedTypesArray = [...nestedTypes];
+
+    // Display list of expected types as a union
+    let nestedTypesList =
+      nestedTypesArray.slice(0, MAX_VALID_SHOWN).join(" | ") +
+      (nestedTypesArray.length > MAX_VALID_SHOWN
+        ? ` | +${
+            nestedTypesArray.length - MAX_VALID_SHOWN
+          } ... ${nestedTypesArray.pop()}`
+        : "");
+
+    // TODO: Be able to pass the validator's config to the SDK
+    const docsURL = this.config.urlMapping;
+
+    // Support passing in a URL for matching type
+    if (docsURL && xlrNode.name && docsURL[xlrNode.name]) {
+      nestedTypesList = docsURL[xlrNode.name];
+    }
+
+    // Support supplemental info message
+    let infoMessage;
+
+    if (rootNode.value !== undefined) {
+      infoMessage = `Got: ${rootNode.value} and expected: ${nestedTypesList}`;
+    } else if (nestedTypesList) {
+      infoMessage = `Expected: ${nestedTypesList}`;
+    }
+
+    return { nestedTypesList, infoMessage };
+  }
+
   private validateTemplate(
     node: Node,
     xlrNode: TemplateLiteralType
-  ): ValidationError | undefined {
+  ): ValidationMessage | undefined {
     if (node.type !== "string") {
       return {
         type: "type",
         node: node.parent as Node,
         message: `Expected type "${xlrNode.type}" but got "${typeof node}"`,
+        expected: xlrNode.type,
+        severity: ValidationSeverity.Error,
       };
     }
 
@@ -192,12 +306,14 @@ export class XLRValidator {
         type: "value",
         node: node.parent as Node,
         message: `Does not match expected format: ${xlrNode.format}`,
+        expected: xlrNode.format,
+        severity: ValidationSeverity.Error,
       };
     }
   }
 
   private validateArray(rootNode: Node, xlrNode: ArrayType) {
-    const issues: Array<ValidationError> = [];
+    const issues: Array<ValidationMessage> = [];
     rootNode.children?.forEach((child) =>
       issues.push(...this.validateType(child, xlrNode.elementType))
     );
@@ -205,7 +321,7 @@ export class XLRValidator {
   }
 
   private validateObject(xlrNode: ObjectType, node: Node) {
-    const issues: Array<ValidationError> = [];
+    const issues: Array<ValidationMessage> = [];
     const objectProps = makePropertyMap(node);
 
     // eslint-disable-next-line guard-for-in, no-restricted-syntax
@@ -217,6 +333,7 @@ export class XLRValidator {
           type: "missing",
           node,
           message: `Property "${prop}" missing from type "${xlrNode.name}"`,
+          severity: ValidationSeverity.Error,
         });
       }
 
@@ -238,6 +355,7 @@ export class XLRValidator {
         message: `Unexpected properties on "${xlrNode.name}": ${extraKeys.join(
           ", "
         )}`,
+        severity: ValidationSeverity.Error,
       });
     } else {
       issues.push(
@@ -316,6 +434,9 @@ export class XLRValidator {
     let firstElement = types[0];
     let effectiveType: ObjectType | OrType;
 
+    // Capture the original top-level type name if exists
+    const topLevelTypeName = types[0].name;
+
     if (firstElement.type === "ref") {
       firstElement = this.getRefType(firstElement);
     }
@@ -361,18 +482,38 @@ export class XLRValidator {
         } else {
           effectiveType = {
             ...effectiveType,
-            or: effectiveType.or.map((y) =>
-              this.computeIntersectionType([y, typeToApply])
-            ),
+            or: effectiveType.or.map((y) => {
+              const intersectedType = this.computeIntersectionType([
+                y,
+                typeToApply,
+              ]);
+
+              // If the intersected type doesn't have a name, use the top-level type name
+              if (!intersectedType.name && topLevelTypeName) {
+                intersectedType.name = topLevelTypeName;
+              }
+
+              return intersectedType;
+            }),
           };
         }
       } else if (typeToApply.type === "or") {
         if (effectiveType.type === "object") {
           effectiveType = {
             ...typeToApply,
-            or: typeToApply.or.map((y) =>
-              this.computeIntersectionType([y, effectiveType])
-            ),
+            or: typeToApply.or.map((y) => {
+              const intersectedType = this.computeIntersectionType([
+                y,
+                effectiveType,
+              ]);
+
+              // If the intersected type doesn't have a name, use the top-level type name
+              if (!intersectedType.name && topLevelTypeName) {
+                intersectedType.name = topLevelTypeName;
+              }
+
+              return intersectedType;
+            }),
           };
         } else {
           throw new Error("unimplemented operation or x or projection");
@@ -384,6 +525,15 @@ export class XLRValidator {
       }
     });
 
+    // If the final effective type is an or type and doesn't have a name, use the top-level type name
+    if (
+      effectiveType.type === "or" &&
+      !effectiveType.name &&
+      topLevelTypeName
+    ) {
+      effectiveType.name = topLevelTypeName;
+    }
+
     return effectiveType;
   }
 }

package/types/sdk.d.ts

@@ -78,7 +78,7 @@ export declare class XLRSDK {
      * @param rootNode - Node to validate
      * @returns `Array<ValidationErrors>`
      */
-    validateByName(typeName: string, rootNode: Node): import("./types").ValidationError[];
+    validateByName(typeName: string, rootNode: Node): import("./types").ValidationMessage[];
     /**
      * Validates if a JSONC Node follows the supplied XLR Type
      *
@@ -86,7 +86,7 @@ export declare class XLRSDK {
      * @param rootNode - Node to validate
      * @returns `Array<ValidationErrors>`
      */
-    validateByType(type: NodeType, rootNode: Node): import("./types").ValidationError[];
+    validateByType(type: NodeType, rootNode: Node): import("./types").ValidationMessage[];
     /**
      * Exports the types loaded into the registry to the specified format
      *

package/types/types.d.ts

@@ -1,12 +1,32 @@
 import type { Node } from "jsonc-parser";
-export interface ValidationError {
+/** Support Export Formats */
+export type ExportTypes = "TypeScript";
+export interface BaseValidationMessage<ErrorType extends string = string> {
+    /** Validation Type */
+    type: ErrorType;
     /** Error message text */
     message: string;
     /** JSONC node that the error originates from */
     node: Node;
-    /** Rough categorization of the error type */
-    type: "type" | "missing" | "unknown" | "value" | "unexpected";
+    /** Level of the message */
+    severity: ValidationSeverity;
+}
+export interface TypeValidationError extends BaseValidationMessage<"type"> {
+    /** Expected types */
+    expected?: string[] | string | number | boolean;
+}
+export type MissingValidationError = BaseValidationMessage<"missing">;
+export type UnknownValidationError = BaseValidationMessage<"unknown">;
+export interface ValueValidationError extends BaseValidationMessage<"value"> {
+    /** Expected value */
+    expected?: string;
+}
+export type UnexpectedValidationError = BaseValidationMessage<"unexpected">;
+export type ValidationMessage = TypeValidationError | MissingValidationError | UnknownValidationError | ValueValidationError | UnexpectedValidationError;
+export declare enum ValidationSeverity {
+    Error = 1,
+    Warning = 2,
+    Info = 3,
+    Trace = 4
 }
-/** Support Export Formats */
-export type ExportTypes = "TypeScript";
 //# sourceMappingURL=types.d.ts.map

package/types/validator.d.ts

@@ -1,15 +1,21 @@
 import type { Node } from "jsonc-parser";
 import type { NamedType, NodeType, ObjectType, OrType, RefType } from "@player-tools/xlr";
-import type { ValidationError } from "./types";
+import type { ValidationMessage } from "./types";
+export interface XLRValidatorConfig {
+    /** URL mapping for supplemental documentation */
+    urlMapping?: Record<string, string>;
+}
 /**
  * Validator for XLRs on JSON Nodes
  */
 export declare class XLRValidator {
+    private config;
     private resolveType;
     private regexCache;
-    constructor(resolveType: (id: string) => NamedType<NodeType> | undefined);
+    constructor(resolveType: (id: string) => NamedType<NodeType> | undefined, config?: XLRValidatorConfig);
     /** Main entrypoint for validation */
-    validateType(rootNode: Node, xlrNode: NodeType): Array<ValidationError>;
+    validateType(rootNode: Node, xlrNode: NodeType): Array<ValidationMessage>;
+    private generateNestedTypesInfo;
     private validateTemplate;
     private validateArray;
     private validateObject;