@velumo/core 0.1.0-beta.0

package/src/theme-validation.ts

@@ -0,0 +1,410 @@
+import type { ValidationIssue } from "./types.js";
+import { describeType, issue } from "./validation-issue.js";
+
+type IndexedRecord = Record<string, unknown>;
+
+const FORBIDDEN_RENDERER_KEYS = new Set(["style", "className", "element"]);
+const RENDERER_EVENT_HANDLER_PATTERN = /^on[A-Z]/;
+
+type TokenValidator = (
+  value: unknown,
+  path: string,
+) => readonly ValidationIssue[];
+type TokenFieldValidators = Partial<Record<string, TokenValidator>>;
+type TokenFamilyValidators = Partial<Record<string, TokenValidator>>;
+
+function isRecord(value: unknown): value is IndexedRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function typeIssue(
+  path: string,
+  message: string,
+  expected: string,
+  received: unknown,
+): ValidationIssue {
+  return issue(path, "wrong_type", message, {
+    expected,
+    received: describeType(received),
+  });
+}
+
+function validateSerializableValue(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (typeof value === "function") {
+    return [
+      issue(path, "not_serializable", `${path} must be JSON-serializable`, {
+        received: "function",
+        suggestion: "Remove functions from theme tokens; they must be JSON.",
+      }),
+    ];
+  }
+
+  if (value === undefined) {
+    return [
+      issue(path, "not_serializable", `${path} must not be undefined`, {
+        received: "undefined",
+      }),
+    ];
+  }
+
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    return [
+      issue(path, "not_serializable", `${path} must be a finite JSON number`, {
+        received: String(value),
+      }),
+    ];
+  }
+
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => {
+      issues.push(...validateSerializableValue(item, `${path}[${index}]`));
+    });
+    return issues;
+  }
+
+  if (isRecord(value)) {
+    for (const [key, child] of Object.entries(value)) {
+      issues.push(...validateSerializableValue(child, `${path}.${key}`));
+    }
+  }
+
+  return issues;
+}
+
+function validateRendererNeutralFields(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (!isRecord(value)) {
+    return issues;
+  }
+
+  for (const [key, child] of Object.entries(value)) {
+    if (
+      FORBIDDEN_RENDERER_KEYS.has(key) ||
+      RENDERER_EVENT_HANDLER_PATTERN.test(key)
+    ) {
+      issues.push(
+        issue(
+          `${path}.${key}`,
+          "renderer_specific",
+          `${path}.${key} is renderer-specific and not allowed`,
+          {
+            suggestion:
+              "Keep theme tokens renderer-neutral; renderers map tokens to CSS.",
+          },
+        ),
+      );
+    }
+
+    issues.push(...validateRendererNeutralFields(child, `${path}.${key}`));
+  }
+
+  return issues;
+}
+
+function validateStringToken(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  const serializableIssues = validateSerializableValue(value, path);
+  if (serializableIssues.length > 0) {
+    return serializableIssues;
+  }
+
+  if (typeof value !== "string") {
+    return [typeIssue(path, `${path} must be a string`, "string", value)];
+  }
+
+  return [];
+}
+
+function validateStringOrNumberToken(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  const serializableIssues = validateSerializableValue(value, path);
+  if (serializableIssues.length > 0) {
+    return serializableIssues;
+  }
+
+  if (typeof value !== "string" && typeof value !== "number") {
+    return [
+      typeIssue(
+        path,
+        `${path} must be a string or number`,
+        "string | number",
+        value,
+      ),
+    ];
+  }
+
+  return [];
+}
+
+function validateRecordFamily(
+  value: unknown,
+  path: string,
+  validateToken: TokenValidator,
+): readonly ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (!isRecord(value)) {
+    return [typeIssue(path, `${path} must be an object`, "object", value)];
+  }
+
+  for (const [tokenName, tokenValue] of Object.entries(value)) {
+    issues.push(...validateToken(tokenValue, `${path}.${tokenName}`));
+  }
+
+  return issues;
+}
+
+function validateTypedTokenObject(
+  value: unknown,
+  path: string,
+  fieldValidators: TokenFieldValidators,
+): readonly ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (!isRecord(value)) {
+    return [typeIssue(path, `${path} must be an object`, "object", value)];
+  }
+
+  for (const [key, child] of Object.entries(value)) {
+    const validateField = fieldValidators[key];
+
+    if (validateField === undefined) {
+      issues.push(
+        issue(
+          `${path}.${key}`,
+          "unknown_field",
+          `${path}.${key} is not allowed`,
+          {
+            expected: Object.keys(fieldValidators).join(", "),
+            suggestion: `Remove \`${key}\`; it is not a recognized token field.`,
+          },
+        ),
+      );
+      continue;
+    }
+
+    issues.push(...validateField(child, `${path}.${key}`));
+  }
+
+  return issues;
+}
+
+function validateTypographyToken(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  return validateTypedTokenObject(value, path, {
+    fontFamily: validateStringToken,
+    fontSize: validateStringOrNumberToken,
+    lineHeight: validateStringOrNumberToken,
+    fontWeight: validateStringOrNumberToken,
+    letterSpacing: validateStringOrNumberToken,
+  });
+}
+
+function validateMotionToken(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  return validateTypedTokenObject(value, path, {
+    duration: validateStringOrNumberToken,
+    easing: validateStringToken,
+    delay: validateStringOrNumberToken,
+  });
+}
+
+function validateStringRecordFamily(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  return validateRecordFamily(value, path, validateStringToken);
+}
+
+function validateStringOrNumberRecordFamily(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  return validateRecordFamily(value, path, validateStringOrNumberToken);
+}
+
+function validateTypographyRecordFamily(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  return validateRecordFamily(value, path, validateTypographyToken);
+}
+
+function validateMotionRecordFamily(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  return validateRecordFamily(value, path, validateMotionToken);
+}
+
+const TOKEN_FAMILY_VALIDATORS: TokenFamilyValidators = {
+  colors: validateStringRecordFamily,
+  typography: validateTypographyRecordFamily,
+  spacing: validateStringOrNumberRecordFamily,
+  radii: validateStringOrNumberRecordFamily,
+  shadows: validateStringRecordFamily,
+  motion: validateMotionRecordFamily,
+  surfaces: validateStringRecordFamily,
+  text: validateStringRecordFamily,
+};
+
+function validateThemeTokens(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (!isRecord(value)) {
+    return [typeIssue(path, `${path} must be an object`, "object", value)];
+  }
+
+  issues.push(...validateRendererNeutralFields(value, path));
+
+  for (const [family, tokens] of Object.entries(value)) {
+    const validateFamily = TOKEN_FAMILY_VALIDATORS[family];
+
+    if (validateFamily === undefined) {
+      issues.push(
+        issue(
+          `${path}.${family}`,
+          "unknown_field",
+          `${path}.${family} is not allowed`,
+          {
+            expected: Object.keys(TOKEN_FAMILY_VALIDATORS).join(", "),
+            suggestion: `Remove \`${family}\`; it is not a recognized token family.`,
+          },
+        ),
+      );
+      continue;
+    }
+
+    issues.push(...validateFamily(tokens, `${path}.${family}`));
+  }
+
+  return issues;
+}
+
+const FONT_FACE_FIELD_VALIDATORS: TokenFieldValidators = {
+  family: validateStringToken,
+  source: validateStringToken,
+  format: validateStringToken,
+  weight: validateStringOrNumberToken,
+  style: validateStringToken,
+  display: validateStringToken,
+  unicodeRange: validateStringToken,
+  stretch: validateStringToken,
+};
+
+// `family` and `source` are required non-empty strings. The shared
+// `validateTypedTokenObject` helper rejects unknown fields and type-checks every
+// present field, but has no required-field machinery — so the required checks
+// are layered around it (mirroring how `validateTheme` requires `id`). A present
+// non-string family/source is left to the field validator (`wrong_type`); only a
+// missing or empty value yields `required`, so the two never double up.
+function isMissingOrEmpty(value: unknown): boolean {
+  return (
+    value === undefined ||
+    (typeof value === "string" && value.trim().length === 0)
+  );
+}
+
+function validateThemeFontFace(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  if (!isRecord(value)) {
+    return [typeIssue(path, `${path} must be an object`, "object", value)];
+  }
+
+  const issues: ValidationIssue[] = [];
+
+  for (const field of ["family", "source"] as const) {
+    if (isMissingOrEmpty(value[field])) {
+      issues.push(
+        issue(`${path}.${field}`, "required", `${path}.${field} is required`, {
+          suggestion: `Provide a non-empty value for \`${path}.${field}\`.`,
+        }),
+      );
+    }
+  }
+
+  issues.push(
+    ...validateTypedTokenObject(value, path, FONT_FACE_FIELD_VALIDATORS),
+  );
+
+  return issues;
+}
+
+export function validateTheme(
+  value: unknown,
+  path = "theme",
+): readonly ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (!isRecord(value)) {
+    return [typeIssue(path, `${path} must be an object`, "object", value)];
+  }
+
+  if (!isNonEmptyString(value.id)) {
+    issues.push(
+      issue(`${path}.id`, "required", `${path}.id is required`, {
+        suggestion: `Provide a value for \`${path}.id\`.`,
+      }),
+    );
+  }
+
+  if (value.tokens !== undefined) {
+    issues.push(...validateThemeTokens(value.tokens, `${path}.tokens`));
+  }
+
+  if (value.css !== undefined && typeof value.css !== "string") {
+    issues.push(
+      typeIssue(
+        `${path}.css`,
+        `${path}.css must be a string`,
+        "string",
+        value.css,
+      ),
+    );
+  }
+
+  if (value.fonts !== undefined) {
+    if (!Array.isArray(value.fonts)) {
+      issues.push(
+        typeIssue(
+          `${path}.fonts`,
+          `${path}.fonts must be an array`,
+          "array",
+          value.fonts,
+        ),
+      );
+    } else {
+      value.fonts.forEach((face, index) => {
+        issues.push(...validateThemeFontFace(face, `${path}.fonts.${index}`));
+      });
+    }
+  }
+
+  return issues;
+}