check( 'section_order', __( 'Section order', 'ai-product-tools' ), 'pass', sprintf( /* translators: %d: number of sections. */ _n( '%d section, in template order.', '%d sections, in template order.', $count, 'ai-product-tools' ), $count ) ); } /** * @param string $unit_id Unit id. * @param string $label Section name. * @param int $word_count Measured word count. * @param int $target_min WordRange.targetMin. * @param int $target_max WordRange.targetMax. * @return array */ public function wordTarget( string $unit_id, string $label, int $word_count, int $target_min, int $target_max ): array { $in_range = $word_count >= $target_min && $word_count <= $target_max; /* translators: %1$d: measured word count. %2$d: target minimum words. %3$d: target maximum words. */ $detail = sprintf( __( '%1$d words - target %2$d-%3$d.', 'ai-product-tools' ), $word_count, $target_min, $target_max ); if ( ! $in_range ) { $detail .= ' ' . ( $word_count < $target_min ? __( 'Below target.', 'ai-product-tools' ) : __( 'Above target.', 'ai-product-tools' ) ); } return $this->check( 'word_target', $label, $in_range ? 'pass' : 'warn', $detail, $unit_id ); } /** * @param string $unit_id Unit id. * @param string $label Section name. * @param int $count Item/row count after any deterministic trim. * @param int $max Configured limit. * @return array */ public function itemLimit( string $unit_id, string $label, int $count, int $max ): array { return $this->check( 'item_limit', $label, 'pass', /* translators: %1$d: measured item count. %2$d: configured item limit. */ sprintf( __( '%1$d items - limit %2$d (enforced).', 'ai-product-tools' ), $count, $max ), $unit_id ); } /** * @param string $unit_id Unit id. * @param string $label Section name. * @return array */ public function fixedTextIdentity( string $unit_id, string $label ): array { return $this->check( 'fixed_text', $label, 'pass', __( 'Identical to the template\'s fixed text, character for character.', 'ai-product-tools' ), $unit_id ); } /** * @param string $unit_id Unit id. * @param string $label Section name. * @param int $present Fields with a value. * @param int $total Fields selected. * @param string[] $missing_labels Labels of the missing fields. * @return array */ public function dataFields( string $unit_id, string $label, int $present, int $total, array $missing_labels ): array { if ( $total === $present ) { return $this->check( 'data_fields', $label, 'pass', __( 'Inserted as stored.', 'ai-product-tools' ), $unit_id ); } /* translators: %1$d: number of fields with a value. %2$d: number of fields selected. */ $detail = sprintf( __( '%1$d of %2$d fields present.', 'ai-product-tools' ), $present, $total ); if ( ! empty( $missing_labels ) ) { /* translators: %s: comma-separated labels of the missing fields. */ $detail .= ' ' . sprintf( __( 'Missing: %s.', 'ai-product-tools' ), implode( ', ', $missing_labels ) ); } return $this->check( 'data_fields', $label, $present > 0 ? 'warn' : 'fail', $detail, $unit_id ); } /** * A check row for a section that did not produce AI/data content: * disabled, skipped (by condition or missing data), fallback, needs * review, or failed. * * @param string $unit_id Unit id. * @param string $label Section name. * @param string $status SectionStatus. * @param string $reason Human-readable reason. * @return array */ public function statusNote( string $unit_id, string $label, string $status, string $reason ): array { $tone_map = array( 'disabled' => 'skip', 'skipped_condition' => 'skip', 'skipped_missing_data' => 'skip', 'fallback' => 'warn', 'needs_review' => 'warn', 'failed' => 'fail', ); $label_map = array( 'disabled' => __( 'Off', 'ai-product-tools' ), 'skipped_condition' => __( 'Skipped', 'ai-product-tools' ), 'skipped_missing_data' => __( 'Skipped', 'ai-product-tools' ), 'fallback' => __( 'Fallback used', 'ai-product-tools' ), 'needs_review' => __( 'Needs review', 'ai-product-tools' ), 'failed' => __( 'Failed', 'ai-product-tools' ), ); $tone = $tone_map[ $status ] ?? 'skip'; $prefix = $label_map[ $status ] ?? ucfirst( str_replace( '_', ' ', $status ) ); return $this->check( 'status', sprintf( '%1$s - %2$s', $prefix, $label ), $tone, $reason, $unit_id ); } /** * Global banned-phrase measured check (copy example: "0 of N found" / * "Found: ..."). * * @param string[] $found Banned phrases actually found anywhere in the output. * @return array */ public function bannedPhrases( array $found ): array { if ( empty( $found ) ) { return $this->check( 'banned_phrases', __( 'Banned phrases', 'ai-product-tools' ), 'pass', __( '0 found.', 'ai-product-tools' ) ); } $quoted = array_map( static function ( $phrase ) { return '"' . $phrase . '"'; }, array_unique( $found ) ); /* translators: %s: comma-separated, quoted banned phrases that were found. */ return $this->check( 'banned_phrases', __( 'Banned phrases', 'ai-product-tools' ), 'fail', sprintf( __( 'Found: %s.', 'ai-product-tools' ), implode( ', ', $quoted ) ) ); } /** * Measured, non-blocking terminology check. * * @param array $hits Preferred-term hits found anywhere in the output. * @return array|null Null when there is nothing to report. */ public function terminology( array $hits ): ?array { if ( empty( $hits ) ) { return null; } $lines = array(); foreach ( $hits as $pair ) { /* translators: %1$s: the preferred term. %2$s: the term to avoid. */ $lines[] = sprintf( __( 'use "%1$s" instead of "%2$s"', 'ai-product-tools' ), $pair['use'], $pair['insteadOf'] ); } return $this->check( 'terminology', __( 'Terminology', 'ai-product-tools' ), 'warn', implode( '; ', array_unique( $lines ) ) ); } /** * Cross-section duplicate-sentence findings: identical (normalized) or * >= 0.8 token-overlap sentences appearing in two DIFFERENT units. * Measured warning only. * * @param array $unit_texts Rendered plain text per unit id. * @return array */ public function duplicateSentences( array $unit_texts ): array { $sentence_map = array(); foreach ( $unit_texts as $unit_id => $text ) { foreach ( TextMetrics::sentences( $text ) as $sentence ) { $normalized = TextMetrics::normalizeForCompare( $sentence ); if ( mb_strlen( $normalized, 'UTF-8' ) < self::DUPLICATE_SENTENCE_MIN_LEN ) { continue; } $sentence_map[] = array( 'unitId' => $unit_id, 'normalized' => $normalized ); } } $findings = array(); $flagged_pairs = array(); $count = count( $sentence_map ); for ( $i = 0; $i < $count; $i++ ) { for ( $j = $i + 1; $j < $count; $j++ ) { if ( $sentence_map[ $i ]['unitId'] === $sentence_map[ $j ]['unitId'] ) { continue; } $overlap = $this->sentenceOverlap( $sentence_map[ $i ]['normalized'], $sentence_map[ $j ]['normalized'] ); if ( $overlap < self::DUPLICATE_SENTENCE_OVERLAP ) { continue; } $pair_key = implode( '|', array_unique( array( $sentence_map[ $i ]['unitId'], $sentence_map[ $j ]['unitId'] ) ) ); if ( isset( $flagged_pairs[ $pair_key ] ) ) { continue; } $flagged_pairs[ $pair_key ] = true; $findings[] = array( 'code' => 'duplicate_sentence', 'severity' => 'warning', /* translators: %1$s: the first unit's id. %2$s: the second unit's id. */ 'message' => sprintf( __( 'A similar sentence appears in both "%1$s" and "%2$s".', 'ai-product-tools' ), $sentence_map[ $i ]['unitId'], $sentence_map[ $j ]['unitId'] ), ); } } return $findings; } /** * Aggregate every finding's severity plus any used, review-outcome * source conflict into the final eligibility verdict. `blocking` * findings prevent any apply at all; `review` findings allow a manual * apply after explicit confirmation. * * @param array $findings Every finding collected for this result. * @param array $conflicts Resolved source conflicts. * @return array{canApply:bool,requiresReview:bool,blockers:array} */ public function eligibility( array $findings, array $conflicts = array() ): array { $blockers = array(); $requires_review = false; foreach ( $findings as $finding ) { $severity = $finding['severity'] ?? ''; if ( 'blocking' === $severity ) { $blockers[] = $finding; } elseif ( 'review' === $severity ) { $requires_review = true; } } foreach ( $conflicts as $conflict ) { if ( 'needs_review' === ( $conflict['outcome'] ?? '' ) && ! empty( $conflict['usedByUnits'] ) ) { $requires_review = true; } } return array( 'canApply' => empty( $blockers ), 'requiresReview' => $requires_review, 'blockers' => $blockers, ); } /** * @param string $id Check id. * @param string $label Check label. * @param string $status 'pass' | 'warn' | 'fail' | 'skip'. * @param string $detail Measured detail sentence. * @param string|null $unit_id Unit id, when the check is unit-scoped. * @return array{id:string,label:string,status:string,detail:string,unitId?:string} */ private function check( string $id, string $label, string $status, string $detail, ?string $unit_id = null ): array { $check = array( 'id' => $id, 'label' => $label, 'status' => $status, 'detail' => $detail ); if ( null !== $unit_id ) { $check['unitId'] = $unit_id; } return $check; } /** * @param string $a Normalized sentence. * @param string $b Normalized sentence. * @return float 0.0..1.0. */ private function sentenceOverlap( string $a, string $b ): float { if ( $a === $b ) { return 1.0; } $tokens_a = TextMetrics::wordTokens( $a ); $tokens_b = TextMetrics::wordTokens( $b ); if ( empty( $tokens_a ) || empty( $tokens_b ) ) { return 0.0; } $intersection = count( array_intersect( $tokens_a, $tokens_b ) ); $smaller = min( count( $tokens_a ), count( $tokens_b ) ); return $smaller > 0 ? $intersection / $smaller : 0.0; } }