$productFacts The product's own labeled facts (implicit ref 'product'). * @param array $sourceFacts Flat list of source facts, each already tagged with its source ref. * @param string[] $priority Refs in priority order (first = highest priority; e.g. ['product','src:5']). * @param string $policy 'review' | 'prefer' | 'skip'. * @param array $decisions Previously stored decisions. * @return array{conflicts:array>,facts:array>} */ public function detect( array $productFacts, array $sourceFacts, array $priority, string $policy, array $decisions ): array { $byLabel = array(); foreach ( $productFacts as $fact ) { $this->addCandidate( $byLabel, 'product', $fact, $priority ); } foreach ( $sourceFacts as $fact ) { $ref = isset( $fact['ref'] ) ? (string) $fact['ref'] : ''; if ( '' === $ref ) { continue; } $this->addCandidate( $byLabel, $ref, $fact, $priority ); } $conflicts = array(); $facts = array(); foreach ( $byLabel as $normalizedLabel => $candidates ) { if ( count( $candidates ) < 2 ) { if ( 1 === count( $candidates ) ) { $facts[ $normalizedLabel ] = $candidates[0]; } continue; } $normalizedValues = array_unique( array_map( array( $this, 'normalizeValue' ), array_column( $candidates, 'value' ) ) ); if ( count( $normalizedValues ) < 2 ) { $facts[ $normalizedLabel ] = $candidates[0]; continue; } usort( $candidates, static function ( $a, $b ) { return $a['priorityRank'] <=> $b['priorityRank']; } ); $preferred = $candidates[0]; $versionsHash = $this->versionsHash( $candidates ); $decision = $this->matchingDecision( $decisions, $normalizedLabel, $versionsHash ); $resolvedRef = $preferred['ref']; $outcome = 'needs_review'; if ( null !== $decision ) { $outcome = 'accepted'; $resolvedRef = (string) $decision['chosenRef']; } elseif ( 'prefer' === $policy ) { $outcome = 'used_preferred'; } elseif ( 'skip' === $policy ) { $outcome = 'omitted'; $resolvedRef = ''; } elseif ( 'review' === $policy ) { $outcome = 'needs_review'; } if ( '' !== $resolvedRef ) { foreach ( $candidates as $candidate ) { if ( $candidate['ref'] === $resolvedRef ) { $facts[ $normalizedLabel ] = $candidate; break; } } } $conflicts[] = array( 'id' => 'conflict_' . substr( hash( 'sha256', $normalizedLabel ), 0, 10 ), 'field' => $normalizedLabel, 'values' => array_map( static function ( $c ) { return array( 'ref' => $c['ref'], 'label' => $c['label'], 'priority' => $c['priorityRank'], 'value' => $c['value'], ); }, $candidates ), 'preferredRef' => $preferred['ref'], 'policy' => $policy, 'outcome' => $outcome, 'usedByUnits' => array(), 'versionsHash' => $versionsHash, ); } return array( 'conflicts' => $conflicts, 'facts' => $facts, ); } /** * Register one candidate value under its normalized label. * * @param array>> $byLabel Accumulator, by reference. * @param string $ref 'product' or a 'src:' ref. * @param array{label?:mixed,value?:mixed,version?:mixed} $fact Raw candidate fact. * @param string[] $priority Refs in priority order. * @return void */ private function addCandidate( array &$byLabel, string $ref, array $fact, array $priority ): void { $label = trim( (string) ( $fact['label'] ?? '' ) ); $value = trim( (string) ( $fact['value'] ?? '' ) ); if ( '' === $label || '' === $value ) { return; } $normalized = $this->normalizeLabel( $label ); if ( '' === $normalized ) { return; } $rank = array_search( $ref, $priority, true ); $byLabel[ $normalized ][] = array( 'ref' => $ref, 'label' => $label, 'value' => $value, 'priorityRank' => false !== $rank ? $rank : PHP_INT_MAX, 'version' => $fact['version'] ?? '', ); } /** * Public wrapper for `normalizeLabel()`. A caller that must decide * whether a raw "Label: value" prompt line belongs to one of THIS * detect() call's own conflicting labels (to drop it, or to add a * "use only this value" instruction around it) needs the exact same * normalization this class uses internally for its own `conflicts`/ * `facts` dictionary keys — this is that normalization, not a second, * possibly-drifting implementation of it. * * @param string $label Raw label. * @return string */ public function normalizeLabelForMatching( string $label ): string { return $this->normalizeLabel( $label ); } /** * Normalize a label for cross-source comparison: lowercase, trimmed, * punctuation/whitespace collapsed, simple trailing-s plural folding. * * @param string $label Raw label. * @return string */ private function normalizeLabel( string $label ): string { $label = mb_strtolower( trim( $label ), 'UTF-8' ); $label = (string) preg_replace( '/[^\p{L}\p{N}]+/u', ' ', $label ); $label = trim( (string) preg_replace( '/\s+/', ' ', $label ) ); if ( mb_strlen( $label, 'UTF-8' ) > 3 && 's' === mb_substr( $label, -1, 1, 'UTF-8' ) ) { $label = mb_substr( $label, 0, -1, 'UTF-8' ); } return $label; } /** * Normalize a value for comparison: lowercase, trimmed, collapsed * whitespace, decimal comma folded to point, and the space between a * number and its unit removed (so "150 min" === "150min"). * * @param string $value Raw value. * @return string */ private function normalizeValue( string $value ): string { $value = mb_strtolower( trim( $value ), 'UTF-8' ); $value = (string) preg_replace( '/(\d),(\d)/', '$1.$2', $value ); $value = (string) preg_replace( '/\s+/', ' ', $value ); $value = (string) preg_replace( '/(\d)\s+([a-z%])/u', '$1$2', $value ); return trim( $value ); } /** * Hash of every competing candidate's (ref, version), order-independent. * * Stored decisions are bound to this hash; when any competing source's * content version (or the product's own version token) changes, the * hash changes and a previously-accepted decision no longer matches. * * @param array $candidates Competing candidates. * @return string */ private function versionsHash( array $candidates ): string { $parts = array(); foreach ( $candidates as $c ) { $parts[] = $c['ref'] . ':' . (string) $c['version']; } sort( $parts ); return hash( 'sha256', implode( '|', $parts ) ); } /** * Find a stored decision matching this field and the current versions hash. * * @param array $decisions Stored decisions. * @param string $fieldKey Normalized label. * @param string $versionsHash Current versions hash. * @return array{fieldKey:string,chosenRef:string,versionsHash:string}|null */ private function matchingDecision( array $decisions, string $fieldKey, string $versionsHash ): ?array { foreach ( $decisions as $decision ) { if ( ( $decision['fieldKey'] ?? '' ) === $fieldKey && ( $decision['versionsHash'] ?? '' ) === $versionsHash ) { return $decision; } } return null; } }