} */ public static function normalize( array $in ): array { $errors = array(); $empty = self::emptyProfile(); $description_result = DefinitionPrimitives::multiLineText( $in['description'] ?? $empty['description'], self::DESCRIPTION_MAX_LEN ); if ( $description_result['overLimit'] ) { $errors[] = DefinitionPrimitives::issue( 'description', 'too_long', __( 'Brand description is too long.', 'ai-product-tools' ) ); } $audience_result = DefinitionPrimitives::multiLineText( $in['audience'] ?? $empty['audience'], self::AUDIENCE_MAX_LEN ); if ( $audience_result['overLimit'] ) { $errors[] = DefinitionPrimitives::issue( 'audience', 'too_long', __( 'Target audience is too long.', 'ai-product-tools' ) ); } $raw_traits = is_array( $in['traits'] ?? null ) ? $in['traits'] : array(); $traits = array(); foreach ( $raw_traits as $i => $trait ) { if ( in_array( $trait, self::TRAIT_KEYS, true ) ) { $traits[] = $trait; } else { $errors[] = DefinitionPrimitives::issue( 'traits[' . $i . ']', 'invalid_enum', __( 'Invalid trait.', 'ai-product-tools' ) ); } } $expression = array_key_exists( 'expression', $in ) ? $in['expression'] : $empty['expression']; if ( ! in_array( $expression, array( 0, 1, 2 ), true ) ) { $errors[] = DefinitionPrimitives::issue( 'expression', 'invalid_enum', __( 'Invalid expression.', 'ai-product-tools' ) ); $expression = $empty['expression']; } $writing_rules = self::normalizeTextList( $in['writingRules'] ?? array(), self::WRITING_RULES_MAX, self::WRITING_RULE_MAX_LEN, 'writingRules', false, $errors ); $preferred_terms = self::normalizePreferredTerms( $in['preferredTerms'] ?? array(), $errors ); $avoid_phrases = self::normalizeTextList( $in['avoidPhrases'] ?? array(), self::AVOID_PHRASES_MAX, self::AVOID_PHRASE_MAX_LEN, 'avoidPhrases', false, $errors ); $approved_samples = self::normalizeTextList( $in['approvedSamples'] ?? array(), self::APPROVED_SAMPLES_MAX, self::APPROVED_SAMPLE_MAX_LEN, 'approvedSamples', true, $errors ); $claim_rules = self::normalizeTextList( $in['claimRules'] ?? array(), self::CLAIM_RULES_MAX, self::CLAIM_RULE_MAX_LEN, 'claimRules', true, $errors ); return array( 'profile' => array( 'description' => $description_result['value'], 'audience' => $audience_result['value'], 'traits' => $traits, 'expression' => $expression, 'writingRules' => $writing_rules, 'preferredTerms' => $preferred_terms, 'avoidPhrases' => $avoid_phrases, 'approvedSamples' => $approved_samples, 'claimRules' => $claim_rules, ), 'errors' => $errors, ); } /** * An empty, valid BrandProfileData. * * @return array */ public static function emptyProfile(): array { return array( 'description' => '', 'audience' => '', 'traits' => array(), 'expression' => 1, 'writingRules' => array(), 'preferredTerms' => array(), 'avoidPhrases' => array(), 'approvedSamples' => array(), 'claimRules' => array(), ); } /** * The two always-on anti-fabrication rules. Never shown as editable, * never affected by any creativity/expression setting, always included * by BrandVoiceCompiler regardless of whether a profile is selected. * * @return string[] */ public static function lockedClaims(): array { return array( __( 'Never state a specification, certification, compliance claim, award, warranty term, or a claim about how the product is delivered, shipped, redeemed, installed or used, or its available amounts or options, unless it is present in the provided sources.', 'ai-product-tools' ), __( 'Never estimate or generalize a fact; state only what the provided sources directly support.', 'ai-product-tools' ), ); } /** * The 6 trait keys with their label, description and a minimal-pair * example showing the trait's concrete effect (shown in the UI as * "Example"). * * @return array */ public static function traits(): array { return array( 'plain' => array( 'label' => __( 'Plain', 'ai-product-tools' ), 'description' => __( 'Simple, direct language without jargon or embellishment.', 'ai-product-tools' ), 'example' => array( 'without' => __( 'This premium-grade apparatus facilitates optimal culinary outcomes.', 'ai-product-tools' ), 'with' => __( 'This pan heats evenly, so food cooks the way you want.', 'ai-product-tools' ), ), ), 'confident' => array( 'label' => __( 'Confident', 'ai-product-tools' ), 'description' => __( 'States what the product does without hedging or over-qualifying.', 'ai-product-tools' ), 'example' => array( 'without' => __( 'This might help keep your coffee a little warmer for a while.', 'ai-product-tools' ), 'with' => __( 'This mug keeps your coffee hot for four hours.', 'ai-product-tools' ), ), ), 'practical' => array( 'label' => __( 'Practical', 'ai-product-tools' ), 'description' => __( 'Focuses on real use, not abstract claims.', 'ai-product-tools' ), 'example' => array( 'without' => __( 'An essential addition to any thoughtfully curated home.', 'ai-product-tools' ), 'with' => __( 'Fits in a kitchen drawer and goes straight in the dishwasher.', 'ai-product-tools' ), ), ), 'warm' => array( 'label' => __( 'Warm', 'ai-product-tools' ), 'description' => __( 'Friendly and approachable, like a helpful person, not a brochure.', 'ai-product-tools' ), 'example' => array( 'without' => __( 'The product is designed for consumer satisfaction.', 'ai-product-tools' ), 'with' => __( 'We made this so your mornings start a little easier.', 'ai-product-tools' ), ), ), 'expert' => array( 'label' => __( 'Expert', 'ai-product-tools' ), 'description' => __( 'Shows real product knowledge, with specific detail.', 'ai-product-tools' ), 'example' => array( 'without' => __( 'This bag is really good quality.', 'ai-product-tools' ), 'with' => __( 'The seams are double-stitched nylon, rated for 20 kg.', 'ai-product-tools' ), ), ), 'playful' => array( 'label' => __( 'Playful', 'ai-product-tools' ), 'description' => __( 'Light and a little fun, without losing clarity.', 'ai-product-tools' ), 'example' => array( 'without' => __( 'This water bottle meets all hydration requirements.', 'ai-product-tools' ), 'with' => __( 'This bottle wants you to actually drink your water today.', 'ai-product-tools' ), ), ), ); } /** * Labels for the 3-point expression scale (prototype `EXPR`). * * @return string[] ['Restrained', 'Balanced', 'Expressive']. */ public static function expressionLabels(): array { return array( __( 'Restrained', 'ai-product-tools' ), __( 'Balanced', 'ai-product-tools' ), __( 'Expressive', 'ai-product-tools' ), ); } /** * Normalize a flat list of plain-text strings with a count and * per-entry length cap. Entries over the length cap are rejected * (error), not truncated; empty entries are dropped silently (no * validation value in keeping a blank row). * * @param mixed $raw Raw value (expected array). * @param int $max_count Maximum entries. * @param int $max_len Maximum characters per entry. * @param string $path Error path prefix. * @param bool $multiline Whether entries may contain line breaks. * @param array &$errors Collected errors. * @return string[] */ private static function normalizeTextList( $raw, int $max_count, int $max_len, string $path, bool $multiline, array &$errors ): array { $raw = is_array( $raw ) ? array_values( $raw ) : array(); if ( count( $raw ) > $max_count ) { $errors[] = DefinitionPrimitives::issue( $path, 'too_many', __( 'Too many entries.', 'ai-product-tools' ) ); $raw = array_slice( $raw, 0, $max_count ); } $result = array(); foreach ( $raw as $i => $value ) { $sanitized = $multiline ? DefinitionPrimitives::multiLineText( $value, $max_len ) : DefinitionPrimitives::singleLineText( $value, $max_len ); if ( $sanitized['overLimit'] ) { $errors[] = DefinitionPrimitives::issue( $path . '[' . $i . ']', 'too_long', __( 'This entry is too long.', 'ai-product-tools' ) ); continue; } if ( '' !== $sanitized['value'] ) { $result[] = $sanitized['value']; } } return $result; } /** * Normalize the preferredTerms {use, insteadOf} pair list. * * @param mixed $raw Raw value (expected array). * @param array &$errors Collected errors. * @return array */ private static function normalizePreferredTerms( $raw, array &$errors ): array { $raw = is_array( $raw ) ? array_values( $raw ) : array(); if ( count( $raw ) > self::PREFERRED_TERMS_MAX ) { $errors[] = DefinitionPrimitives::issue( 'preferredTerms', 'too_many', __( 'Too many preferred terms.', 'ai-product-tools' ) ); $raw = array_slice( $raw, 0, self::PREFERRED_TERMS_MAX ); } $result = array(); foreach ( $raw as $i => $pair ) { if ( ! is_array( $pair ) ) { $errors[] = DefinitionPrimitives::issue( 'preferredTerms[' . $i . ']', 'invalid_shape', __( 'Invalid preferred term.', 'ai-product-tools' ) ); continue; } $use_result = DefinitionPrimitives::singleLineText( $pair['use'] ?? '', self::PREFERRED_TERM_MAX_LEN ); $instead_of_result = DefinitionPrimitives::singleLineText( $pair['insteadOf'] ?? '', self::PREFERRED_TERM_MAX_LEN ); if ( $use_result['overLimit'] ) { $errors[] = DefinitionPrimitives::issue( 'preferredTerms[' . $i . '].use', 'too_long', __( 'Preferred term is too long.', 'ai-product-tools' ) ); } if ( $instead_of_result['overLimit'] ) { $errors[] = DefinitionPrimitives::issue( 'preferredTerms[' . $i . '].insteadOf', 'too_long', __( 'Term to avoid is too long.', 'ai-product-tools' ) ); } $result[] = array( 'use' => $use_result['value'], 'insteadOf' => $instead_of_result['value'], ); } return $result; } }