, * fieldLabels: array, * requiredSignals: array{hasName:bool,hasAnyAllowedField:bool,hasWarranty:bool,hasCareFact:bool,hasCompatibilityFact:bool,hasOwnData?:bool}, * extensionData?: array|null, * extensionSkipReason?: string, * } * @return array{status:string,reason:string,needsModelCall:bool,missingFields:string[]} */ public function plan( array $section, array $input ): array { if ( empty( $section['enabled'] ) ) { return $this->result( 'disabled', __( 'This section is turned off.', 'ai-product-tools' ), false ); } $resolved_fields = isset( $input['resolvedFields'] ) && is_array( $input['resolvedFields'] ) ? $input['resolvedFields'] : array(); $field_labels = isset( $input['fieldLabels'] ) && is_array( $input['fieldLabels'] ) ? $input['fieldLabels'] : array(); $condition = isset( $section['condition'] ) && is_array( $section['condition'] ) ? $section['condition'] : array( 'enabled' => false ); if ( ! empty( $condition['enabled'] ) && ! $this->evaluateCondition( $condition, $resolved_fields ) ) { return $this->result( 'skipped_condition', $this->conditionReasonSentence( $condition, $field_labels ), false ); } if ( 'fixed' === ( $section['mode'] ?? '' ) ) { return $this->result( 'included', '', false ); } if ( 'data' === ( $section['mode'] ?? '' ) ) { if ( array_key_exists( 'extensionData', $input ) ) { return $this->planExtensionData( $section, $input['extensionData'], (string) ( $input['extensionSkipReason'] ?? '' ) ); } return $this->planData( $section, $resolved_fields ); } $required_signals = isset( $input['requiredSignals'] ) && is_array( $input['requiredSignals'] ) ? $input['requiredSignals'] : array(); if ( $this->isDataStarved( (string) ( $section['type'] ?? '' ), $required_signals ) ) { return $this->planMissing( $section, $this->dataStarvedReason( $required_signals ) ); } return $this->result( 'pending', '', true ); } /** * Evaluate a BlueprintSection.condition against already-resolved fields. * * @param array $condition {enabled, field, operator, value}. * @param array $resolved_fields ref => {type,value,empty}. * @return bool True when the condition passes (section proceeds). */ public function evaluateCondition( array $condition, array $resolved_fields ): bool { if ( empty( $condition['enabled'] ) ) { return true; } $field = (string) ( $condition['field'] ?? '' ); $resolved = $resolved_fields[ $field ] ?? array( 'type' => 'text', 'value' => '', 'empty' => true ); $operator = (string) ( $condition['operator'] ?? 'not_empty' ); $is_empty = ! empty( $resolved['empty'] ); switch ( $operator ) { case 'not_empty': return ! $is_empty; case 'empty': return $is_empty; case 'equals': return $this->scalarText( $resolved ) === trim( (string) ( $condition['value'] ?? '' ) ); case 'contains': $needle = trim( (string) ( $condition['value'] ?? '' ) ); return '' !== $needle && false !== mb_stripos( $this->scalarText( $resolved ), $needle, 0, 'UTF-8' ); default: return true; } } /** * Whether an AI section of $type has no usable data to write from. * * @param string $type Section type. * @param array $required_signals {hasName,hasAnyAllowedField,hasWarranty,hasCareFact,hasCompatibilityFact,hasOwnData?}. * @return bool */ public function isDataStarved( string $type, array $required_signals ): bool { if ( array_key_exists( 'hasOwnData', $required_signals ) ) { return empty( $required_signals['hasOwnData'] ); } switch ( $type ) { case 'warranty': return empty( $required_signals['hasWarranty'] ); case 'care': return empty( $required_signals['hasCareFact'] ); case 'compatibility': return empty( $required_signals['hasCompatibilityFact'] ); default: return empty( $required_signals['hasName'] ) || empty( $required_signals['hasAnyAllowedField'] ); } } /** * The reason sentence for a data-starved AI section: the generic one * every type shares, unless the type's own extension already decided a * more specific reason (an isolated section's own data check — see * SubjectContextResolver::requiredSignalsFor()'s `dataStarvedReason`), * folded into the same sentence so the distinct cases read differently * without changing the shape every caller of this reason already relies * on. * * @param array $required_signals {..., dataStarvedReason?:string}. * @return string */ private function dataStarvedReason( array $required_signals ): string { $specific = (string) ( $required_signals['dataStarvedReason'] ?? '' ); if ( '' === $specific ) { return __( 'No usable data was found for this section, so the AI was not asked to write it.', 'ai-product-tools' ); } /* translators: %s: the specific reason this section has no data (e.g. "not enough approved reviews yet"). */ return sprintf( __( 'No usable data was found for this section (%s), so the AI was not asked to write it.', 'ai-product-tools' ), $specific ); } /** * Decide a `data` mode section: included when at least one selected * field has a value, otherwise the section's own missing-data policy. * * @param array $section Normalized BlueprintSection. * @param array $resolved_fields The section's selected fields, already resolved. * @return array{status:string,reason:string,needsModelCall:bool,missingFields:string[]} */ private function planData( array $section, array $resolved_fields ): array { $missing = array(); $present = 0; foreach ( $resolved_fields as $ref => $resolved ) { if ( ! empty( $resolved['empty'] ) ) { $missing[] = $ref; } else { $present++; } } if ( 0 === $present ) { return $this->planMissing( $section, __( 'No data was available for the selected fields.', 'ai-product-tools' ), $missing ); } return array( 'status' => 'included', 'reason' => '', 'needsModelCall' => false, 'missingFields' => $missing, ); } /** * Decide a `data` section an extension builds: included when the * extension found its data, otherwise the section's own missing-data * policy, with the extension's own reason sentence. * * @param array $section Normalized BlueprintSection. * @param array|null $data The extension's data, or null when it found none. * @param string $reason The extension's sentence for why there is none. * @return array{status:string,reason:string,needsModelCall:bool,missingFields:string[]} */ private function planExtensionData( array $section, $data, string $reason ): array { if ( is_array( $data ) && ! empty( $data ) ) { return $this->result( 'included', '', false ); } return $this->planMissing( $section, '' !== $reason ? $reason : __( 'No data was available for this section.', 'ai-product-tools' ) ); } /** * Apply a section's `missing` policy when its data is not available. * * @param array $section Normalized BlueprintSection. * @param string $reason Human-readable reason sentence. * @param string[] $missing_fields Missing field refs, when known. * @return array{status:string,reason:string,needsModelCall:bool,missingFields:string[]} */ private function planMissing( array $section, string $reason, array $missing_fields = array() ): array { $missing = isset( $section['missing'] ) && is_array( $section['missing'] ) ? $section['missing'] : array(); $policy = (string) ( $missing['policy'] ?? 'skip' ); if ( 'fallback' === $policy && '' !== trim( (string) ( $missing['fallbackText'] ?? '' ) ) ) { return $this->result( 'fallback', $reason, false, $missing_fields ); } if ( 'review' === $policy ) { return $this->result( 'needs_review', $reason, false, $missing_fields ); } return $this->result( 'skipped_missing_data', $reason, false, $missing_fields ); } /** * @param array $condition {field, operator, value}. * @param array $field_labels ref => label. * @return string */ private function conditionReasonSentence( array $condition, array $field_labels ): string { $field = (string) ( $condition['field'] ?? '' ); $label = $field_labels[ $field ] ?? $field; $value = (string) ( $condition['value'] ?? '' ); switch ( (string) ( $condition['operator'] ?? '' ) ) { case 'not_empty': /* translators: %s: the condition's field label. */ return sprintf( __( 'Skipped because %s is empty for this subject.', 'ai-product-tools' ), $label ); case 'empty': /* translators: %s: the condition's field label. */ return sprintf( __( 'Skipped because %s is not empty for this subject.', 'ai-product-tools' ), $label ); case 'equals': /* translators: %1$s: the condition's field label. %2$s: the required value. */ return sprintf( __( 'Skipped because %1$s does not equal "%2$s".', 'ai-product-tools' ), $label, $value ); case 'contains': /* translators: %1$s: the condition's field label. %2$s: the required substring. */ return sprintf( __( 'Skipped because %1$s does not contain "%2$s".', 'ai-product-tools' ), $label, $value ); default: /* translators: %s: the condition's field label. */ return sprintf( __( 'Skipped because the condition on %s was not met.', 'ai-product-tools' ), $label ); } } /** * @param array $resolved {type,value,empty}. * @return string */ private function scalarText( array $resolved ): string { if ( 'list' === ( $resolved['type'] ?? '' ) ) { return implode( ', ', array_map( 'strval', (array) $resolved['value'] ) ); } if ( 'pairs' === ( $resolved['type'] ?? '' ) ) { $parts = array(); foreach ( (array) $resolved['value'] as $pair ) { $parts[] = ( $pair['label'] ?? '' ) . ': ' . ( $pair['value'] ?? '' ); } return implode( '; ', $parts ); } return (string) ( $resolved['value'] ?? '' ); } /** * @param string $status One of the recognized section statuses. * @param string $reason Human-readable reason sentence. * @param bool $needs_model_call Whether this section still needs an AI call. * @param string[] $missing_fields Missing field refs, when relevant. * @return array{status:string,reason:string,needsModelCall:bool,missingFields:string[]} */ private function result( string $status, string $reason, bool $needs_model_call, array $missing_fields = array() ): array { return array( 'status' => $status, 'reason' => $reason, 'needsModelCall' => $needs_model_call, 'missingFields' => $missing_fields, ); } }