@sanity/agent-schema 0.1.0 → 0.3.0

package/dist/validation/index.d.ts

@@ -0,0 +1,317 @@
+import { a as ValidateValueFn, c as ValidationErrorCode, h as ManifestSchemaType, i as PatchOperations, l as ValidationResult, n as InsertOperation, o as ValidationContext, r as LocalizationConfig, s as ValidationError, t as FieldSchemaLookupResult } from "../_chunks-dts/types.js";
+import { SanityClient } from "@sanity/client";
+/**
+ * Validate an array value and its items.
+ */
+declare function validateArray(value: unknown, fieldSchema: ManifestSchemaType, path: string, schema: ManifestSchemaType[], errors: ValidationError[], context: ValidationContext, validateValue: ValidateValueFn): Promise<void>;
+/**
+ * Validate that new items don't duplicate existing array items or each other.
+ * Used by patch operations (APPEND, INSERT) to check uniqueItems constraints
+ * against the existing document state.
+ */
+declare function validateUniqueItems(newItems: unknown[], existingArray: unknown[], pathPrefix: string, errors: ValidationError[]): void;
+/**
+ * Return paths of fields with custom validators on the document type.
+ * Document-level custom validators are reported at `(document)`.
+ */
+declare function detectCustomValidators(documentType: string, schema: ManifestSchemaType[]): string[];
+interface PathResolutionResult {
+  /** The resolved field schema, or null if not found */
+  schema: ManifestSchemaType | null;
+  /** How the schema was resolved: 'schema' (static), 'document' (dynamic), or null (failed) */
+  resolvedVia: 'schema' | 'document' | null;
+}
+/**
+ * Resolve field schema at path, using document for accurate type resolution.
+ *
+ * When a document is provided and the path contains array selectors, we use
+ * document-based resolution to determine the correct type at each array access.
+ * This is essential for union arrays where multiple types have the same field name.
+ *
+ * @param path - Dot-notation path, may include array selectors like [_key=="abc"]
+ * @param typeSchema - The document type schema to start navigation from
+ * @param allSchemas - All available schemas for type resolution
+ * @param document - Optional existing document for dynamic resolution
+ * @returns Resolution result with schema and resolution method
+ */
+declare function resolveFieldSchemaAtPath(path: string, typeSchema: ManifestSchemaType, allSchemas: ManifestSchemaType[], document?: Record<string, unknown>): PathResolutionResult;
+/**
+ * Validate a document-level language field value against available languages.
+ *
+ * This validator is called when:
+ * 1. The document uses document-level translation
+ * 2. The field being validated is the language field (e.g., "language", "locale")
+ * 3. There are known available languages to validate against
+ *
+ * @param value - The language value to validate
+ * @param languageFieldName - Name of the language field (e.g., "language", "locale")
+ * @param availableLanguages - List of valid language codes from existing documents
+ * @param path - The field path for error reporting
+ * @param errors - Array to collect validation errors
+ */
+declare function validateDocumentLanguageField(value: unknown, languageFieldName: string, availableLanguages: string[], path: string, errors: ValidationError[]): void;
+/**
+ * Validate a field-level language key (the _key in internationalizedArray items).
+ *
+ * This validator is called when processing arrays with options.languages,
+ * to ensure that array item _key values match configured language IDs.
+ *
+ * @param key - The _key value from an array item
+ * @param allowedLanguages - List of allowed languages with id and title
+ * @param path - The field path for error reporting
+ * @param errors - Array to collect validation errors
+ */
+declare function validateFieldLevelLanguageKey(key: string, allowedLanguages: Array<{
+  id: string;
+  title: string | null;
+}>, path: string, errors: ValidationError[]): void;
+/**
+ * Validate a field-level language field value (v5 format where language is a dedicated field).
+ *
+ * In v5 of the internationalized-array plugin, the language code is stored in a
+ * dedicated `language` field instead of `_key`.
+ */
+declare function validateFieldLevelLanguageField(languageValue: unknown, allowedLanguages: Array<{
+  id: string;
+  title: string | null;
+}>, path: string, errors: ValidationError[]): void;
+type LanguageOption = {
+  id: string;
+  title: string | null;
+};
+interface SchemaWithOptions {
+  name?: string;
+  type?: string;
+  fields?: Array<{
+    name: string;
+    type: string;
+  }>;
+  of?: Array<{
+    name?: string;
+    type?: string;
+    fields?: Array<{
+      name: string;
+      type: string;
+    }>;
+  }>;
+  options?: {
+    languages?: LanguageOption[];
+  };
+}
+/**
+ * Detect whether an internationalized array uses v5 format (dedicated `language` field)
+ * by checking if the array's value type has a `language` field in its schema.
+ */
+declare function isV5InternationalizedArray(fieldSchema: SchemaWithOptions, allSchemas: SchemaWithOptions[]): boolean;
+/**
+ * Check if a field schema represents an internationalized array type.
+ *
+ * @param fieldSchema - The field schema to check
+ * @returns true if the field is an internationalized array
+ */
+declare function isInternationalizedArrayField(fieldSchema: SchemaWithOptions): boolean;
+/**
+ * Validate a SET operation against internationalized array language constraints.
+ *
+ * Handles two cases:
+ * 1. Setting the whole array (value is an array) — validates each item's _key
+ * 2. Setting a _key directly (path ends with `._key`) — validates the new key value
+ *
+ * Resolves the field schema from the path. No-ops if the field isn't an internationalized array.
+ *
+ * @param path - The SET operation path
+ * @param value - The new value being set
+ * @param fieldSchema - The resolved field schema for the path
+ * @param typeSchema - The document type schema (for resolving parent paths)
+ * @param allSchemas - All schemas for resolving named types
+ * @param errors - Array to collect validation errors
+ */
+declare function validateInternationalizedArraySet(path: string, value: unknown, fieldSchema: ManifestSchemaType, typeSchema: ManifestSchemaType, allSchemas: ManifestSchemaType[], errors: ValidationError[]): void;
+/**
+ * Validate language keys for items being added to an internationalized array.
+ *
+ * Callers should check `isInternationalizedArrayField()` before calling this.
+ *
+ * @param items - Array items to validate
+ * @param fieldSchema - The field schema (may be a named type reference)
+ * @param allSchemas - All schemas for resolving named types
+ * @param path - The array field path (e.g., 'description')
+ * @param errors - Array to collect validation errors
+ */
+declare function validateInternationalizedArrayItems(items: unknown[], fieldSchema: SchemaWithOptions, allSchemas: SchemaWithOptions[], path: string, errors: ValidationError[]): void;
+/**
+ * Validate an object value and its fields.
+ */
+declare function validateObject(value: unknown, fieldSchema: ManifestSchemaType, path: string, schema: ManifestSchemaType[], errors: ValidationError[], context: ValidationContext, validateValue: ValidateValueFn): Promise<void>;
+/**
+ * Get valid image metadata field names for a given image path.
+ *
+ * This uses the navigation logic to find the image field schema
+ * and extract valid metadata field names. Used for silent filtering of metadata.
+ *
+ * @param imagePath - The path to the image field
+ * @param typeSchema - The document type schema
+ * @param schema - All available schemas
+ * @returns Set of valid metadata field names, or null if path is invalid
+ */
+declare function getValidImageMetadataFields(imagePath: string, typeSchema: ManifestSchemaType, schema: ManifestSchemaType[]): Set<string> | null;
+/**
+ * Get the field schema(s) at a given path in the document type.
+ *
+ * For union types (arrays with multiple `of` types), returns ALL possible schemas.
+ * This is important for validating fields that might exist in some but not all union types.
+ *
+ * @param path - Dot-notation path, may include array selectors like [_key=="abc"]
+ * @param documentType - The document type name
+ * @param schema - Full schema array
+ * @param existingDocument - Optional document to validate path existence against
+ * @returns Object with schemas array and any validation errors
+ */
+declare function getFieldSchemaAtPath(path: string, documentType: string, schema: ManifestSchemaType[], existingDocument?: Record<string, unknown>): FieldSchemaLookupResult;
+/**
+ * Validate that a path points to an image field.
+ *
+ * This is a convenience wrapper around getFieldSchemaAtPath that checks
+ * whether the field at the path is an image type.
+ *
+ * @param path - Dot-notation path to the field
+ * @param documentType - The document type name
+ * @param schema - Full schema array
+ * @param existingDocument - Optional document to validate path existence against
+ * @returns Validation result with errors if path is invalid or not an image field
+ */
+declare function validateImagePath(path: string, documentType: string, schema: ManifestSchemaType[], existingDocument?: Record<string, unknown>): ValidationResult;
+/**
+ * Validates metadata fields for an image against the schema
+ * Removes fields that don't exist in the image field's schema definition
+ *
+ * @param metadata - The metadata object to validate (e.g., {alt: "...", caption: "..."})
+ * @param imagePath - The path to the image field (e.g., "heroImage" or "content[_key=="abc"].image")
+ * @param typeSchema - The document type schema
+ * @param schema - All available schemas
+ * @returns Cleaned metadata object with only valid fields, or undefined if no valid fields
+ */
+declare function validateImageMetadata(metadata: Record<string, string>, imagePath: string, typeSchema: ManifestSchemaType, schema: ManifestSchemaType[]): Record<string, string> | undefined;
+/**
+ * Validate a Portable Text block value.
+ *
+ * Blocks have special validation requirements:
+ * - children must be an array containing spans and inline objects (from block.of)
+ * - markDefs must be an array containing annotations (from block.marks.annotations)
+ * - style, listItem, level are optional fields
+ */
+declare function validateBlock(value: unknown, fieldSchema: ManifestSchemaType, path: string, schema: ManifestSchemaType[], errors: ValidationError[], context: ValidationContext, validateValue: ValidateValueFn): Promise<void>;
+/**
+ * Validate a primitive value against its schema type.
+ */
+declare function validatePrimitive(value: unknown, schemaType: string, path: string, errors: ValidationError[], fieldSchema?: ManifestSchemaType): void;
+/**
+ * Validate a value against schema validation rules (min, max, enum, uniqueItems).
+ *
+ * Supports two schema formats:
+ * - Manifest format: { flag: 'min', constraint: 5 }
+ * - Encoded format (from @sanity/descriptors): { type: 'minimum', value: '5' }
+ */
+declare function validateSchemaRules(value: unknown, fieldSchema: ManifestSchemaType, path: string, errors: ValidationError[], warnings?: ValidationError[]): void;
+/**
+ * Validate a reference value.
+ * Checks structure and optionally validates existence via client.
+ */
+declare function validateReference(value: unknown, fieldSchema: ManifestSchemaType, path: string, errors: ValidationError[], context: ValidationContext): Promise<void>;
+declare function validateRequiredFields(document: Record<string, unknown>, documentType: string, schema: ManifestSchemaType[]): ValidationError[];
+/**
+ * Check whether the slug values on a draft collide with any other document in
+ * the dataset (excluding the draft and its published twin).
+ */
+declare function validateSlugCollisions(document: Record<string, unknown>, documentType: string, schema: ManifestSchemaType[], client: SanityClient, ids: {
+  publishedId: string;
+  draftId: string;
+}): Promise<ValidationError[]>;
+/**
+ * Validate a slug value.
+ */
+declare function validateSlug(value: unknown, path: string, errors: ValidationError[]): void;
+/**
+ * Validate a geopoint value.
+ */
+declare function validateGeopoint(value: unknown, path: string, errors: ValidationError[]): void;
+/**
+ * Validate an image value structure.
+ * Note: Asset existence is validated separately in reference validation.
+ */
+declare function validateImage(value: unknown, path: string, errors: ValidationError[], fieldSchema?: ManifestSchemaType, schema?: ManifestSchemaType[]): void;
+/**
+ * Validate a file value structure.
+ */
+declare function validateFile(value: unknown, path: string, errors: ValidationError[]): void;
+/**
+ * Create a validation error with consistent formatting.
+ */
+declare function createError(path: string, code: ValidationErrorCode, message: string, received: string, expected: string, fix: string): ValidationError;
+/**
+ * Format a value for display in error messages.
+ * Handles truncation for long values.
+ */
+declare function formatValue(value: unknown): string;
+/**
+ * Map Sanity schema type to expected JavaScript type.
+ * See SANITY_SCHEMA_STRUCTURE.md for full reference.
+ */
+declare function getExpectedJsType(schemaType: string): 'string' | 'number' | 'boolean' | 'array' | 'object';
+/**
+ * Get the actual JavaScript type of a value.
+ */
+declare function getActualJsType(value: unknown): 'string' | 'number' | 'boolean' | 'array' | 'object' | 'null' | 'undefined';
+/**
+ * Get the uniqueness key for an array item based on its type.
+ * - References: unique by _ref
+ * - Primitives: unique by value
+ * - Objects: strip _key and compare rest
+ */
+declare function getUniquenessKey(item: unknown): string;
+/**
+ * Get a value from an object using a path string.
+ * Supports dot notation, array index notation [0], and _key selectors [_key=="value"].
+ */
+declare function getValueAtPath(obj: unknown, path: string): unknown;
+/**
+ * Validate that an object only contains allowed properties.
+ * Reports errors for any unknown properties found.
+ *
+ * @param obj - The object to validate
+ * @param allowedProperties - Set of property names that are allowed
+ * @param path - The path to the object for error reporting
+ * @param typeName - Human-readable type name for error messages (e.g., "reference", "slug")
+ * @param errors - Array to collect validation errors
+ */
+declare function validateNoExtraProperties(obj: Record<string, unknown>, allowedProperties: Set<string>, path: string, typeName: string, errors: ValidationError[]): void;
+/**
+ * Format validation errors for display to the LLM.
+ *
+ * @param errors - List of validation errors
+ * @returns Formatted error message
+ */
+declare function formatValidationErrors(errors: ValidationError[]): string;
+/**
+ * Validate a single value against its schema.
+ * This is the core recursive validator that dispatches to type-specific validators.
+ */
+declare function validateValue(value: unknown, fieldSchema: ManifestSchemaType, path: string, errors: ValidationError[], context: ValidationContext, schema: ManifestSchemaType[], warnings?: ValidationError[]): Promise<void>;
+type ValidateForPublishInput = {
+  document: Record<string, unknown>;
+  documentType: string;
+  schema: ManifestSchemaType[];
+  client: SanityClient;
+  publishedId: string;
+  draftId: string;
+};
+declare function validateForPublish({
+  document,
+  documentType,
+  schema,
+  client,
+  publishedId,
+  draftId
+}: ValidateForPublishInput): Promise<ValidationResult>;
+export { type FieldSchemaLookupResult, type InsertOperation, type LocalizationConfig, type PatchOperations, type ValidateValueFn, type ValidationContext, type ValidationError, type ValidationErrorCode, type ValidationResult, createError, detectCustomValidators, formatValidationErrors, formatValue, getActualJsType, getExpectedJsType, getFieldSchemaAtPath, getUniquenessKey, getValidImageMetadataFields, getValueAtPath, isInternationalizedArrayField, isV5InternationalizedArray, resolveFieldSchemaAtPath, validateArray, validateBlock, validateDocumentLanguageField, validateFieldLevelLanguageField, validateFieldLevelLanguageKey, validateFile, validateForPublish, validateGeopoint, validateImage, validateImageMetadata, validateImagePath, validateInternationalizedArrayItems, validateInternationalizedArraySet, validateNoExtraProperties, validateObject, validatePrimitive, validateReference, validateRequiredFields, validateSchemaRules, validateSlug, validateSlugCollisions, validateUniqueItems, validateValue };
+//# sourceMappingURL=index.d.ts.map

package/dist/validation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/validation/array.validator.ts","../../src/validation/customValidators.ts","../../src/validation/document-path-resolver.ts","../../src/validation/language.validator.ts","../../src/validation/object.validator.ts","../../src/validation/path-validation.ts","../../src/validation/portable-text.validator.ts","../../src/validation/primitive.validator.ts","../../src/validation/reference.validator.ts","../../src/validation/requiredFields.ts","../../src/validation/slugCollisions.ts","../../src/validation/special-types.validator.ts","../../src/validation/utils.ts","../../src/validation/validate-value.ts","../../src/validation/validateForPublish.ts"],"mappings":"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"}