snapshots = $snapshots ?? new SnapshotStore(); $this->subjectContext = $subjectContext ?? new SubjectContextResolver(); } /** * @inheritDoc */ public function findings( int $product_id, WC_Product $product, array $definition ): array { $findings = array(); $description_html = (string) ( $this->snapshots->readCurrentFieldValue( $product_id, 'description' ) ?? '' ); $description_plain = trim( wp_strip_all_tags( $description_html ) ); if ( '' === $description_plain ) { $findings[] = array( 'code' => 'description_missing', 'severity' => 'warning', 'field' => 'description', 'message' => __( 'The long description is empty.', 'ai-product-tools' ), 'label' => __( 'no description', 'ai-product-tools' ), ); } $short_description_html = (string) ( $this->snapshots->readCurrentFieldValue( $product_id, 'short_description' ) ?? '' ); $short_description_plain = trim( wp_strip_all_tags( $short_description_html ) ); if ( '' === $short_description_plain ) { $findings[] = array( 'code' => 'short_description_missing', 'severity' => 'warning', 'field' => 'short_description', 'message' => __( 'The short description is empty.', 'ai-product-tools' ), 'label' => __( 'no short description', 'ai-product-tools' ), ); } else { $length_finding = $this->shortDescriptionLengthFinding( $short_description_html, $definition ); if ( null !== $length_finding ) { $findings[] = $length_finding; } } $tags = $this->currentTags( $product_id ); $tags_finding = $this->tagsFinding( $tags, $definition ); if ( null !== $tags_finding ) { $findings[] = $tags_finding; } $banned = StructureBannedPhrases::of( $definition ); $banned_finding = BannedPhraseCheck::finding( $description_plain, $banned, 'description' ); if ( null !== $banned_finding ) { $findings[] = $banned_finding; } foreach ( $this->sectionSkipFindings( $product, $definition ) as $skip_finding ) { $findings[] = $skip_finding; } return $findings; } /** * @inheritDoc */ public function provenanceFieldMap(): array { return array( 'description' => 'description', 'short_description' => 'short_description', 'tags' => 'tags', ); } /** * @param int $product_id Product id. * @return string[] Current tag names. */ private function currentTags( int $product_id ): array { $raw = $this->snapshots->readCurrentFieldValue( $product_id, 'tags' ); $decoded = is_string( $raw ) && '' !== $raw ? json_decode( $raw, true ) : array(); return is_array( $decoded ) ? array_values( array_filter( array_map( 'strval', $decoded ) ) ) : array(); } /** * @param string[] $tags Current tag names. * @param array $definition Clamped BlueprintDefinition. * @return array|null */ private function tagsFinding( array $tags, array $definition ): ?array { $count = count( $tags ); if ( 0 === $count ) { return array( 'code' => 'tags_missing', 'severity' => 'warning', 'field' => 'tags', 'message' => __( 'No tags are set.', 'ai-product-tools' ), 'label' => __( 'no tags', 'ai-product-tools' ), ); } $max = isset( $definition['structure']['companions']['tags']['max'] ) ? (int) $definition['structure']['companions']['tags']['max'] : 10; if ( $count > $max ) { return array( 'code' => 'tags_over_max', 'severity' => 'warning', 'field' => 'tags', /* translators: %1$d: measured tag count. %2$d: the template's allowed tag count. */ 'message' => sprintf( __( 'There are %1$d tags; this template allows %2$d.', 'ai-product-tools' ), $count, $max ), 'label' => __( 'too many tags', 'ai-product-tools' ), 'measured' => $count, 'limit' => $max, ); } return null; } /** * @param string $short_description_html Current short description (may contain HTML). * @param array $definition Clamped BlueprintDefinition. * @return array|null */ private function shortDescriptionLengthFinding( string $short_description_html, array $definition ): ?array { $length = $definition['structure']['companions']['shortDescription']['length'] ?? array(); $min = isset( $length['targetMin'] ) ? (int) $length['targetMin'] : 0; $max = isset( $length['targetMax'] ) ? (int) $length['targetMax'] : 0; $count = TextMetrics::wordCount( $short_description_html ); if ( $count >= $min && $count <= $max ) { return null; } $limit = $count < $min ? $min : $max; return array( 'code' => 'short_description_length', 'severity' => 'warning', 'field' => 'short_description', /* translators: %1$d: measured word count. %2$d: the template's nearer word-count bound. */ 'message' => sprintf( __( 'The short description is %1$d words; this template targets %2$d.', 'ai-product-tools' ), $count, $limit ), 'label' => __( 'short description length', 'ai-product-tools' ), 'measured' => $count, 'limit' => $limit, ); } /** * `section_will_skip` findings, one per section whose pre-call plan is * `skipped_missing_data` — computed the same * way a real run would (`SubjectContextResolver` + `SectionPlanner`), * but source-less: {@see \AIPT\Api\ContentStructure\Engine\Context\SourceContextBuilder::build()} * with no blueprint items and no provider results always returns empty * blocks, so this never fetches or re-fetches an external source. Only * the product's own field data decides whether a section is * data-starved. * * @param WC_Product $product Product. * @param array $definition Clamped BlueprintDefinition. * @return array> */ private function sectionSkipFindings( WC_Product $product, array $definition ): array { $sections = isset( $definition['structure']['sections'] ) && is_array( $definition['structure']['sections'] ) ? $definition['structure']['sections'] : array(); if ( empty( $sections ) ) { return array(); } $ctx = array( 'generator' => Generators::DESCRIPTION, 'product' => $product, 'definition' => $definition ); $subject_context = $this->subjectContext->buildSubjectContext( $ctx ); $plans = $this->subjectContext->planSections( $sections, $subject_context, array( 'blocks' => array(), 'sourcesUsed' => array() ), array() ); $catalog = SectionCatalog::typesFor( Generators::DESCRIPTION ); $findings = array(); foreach ( $sections as $section ) { $id = (string) ( $section['id'] ?? '' ); $plan = $plans[ $id ] ?? null; if ( null === $plan || 'skipped_missing_data' !== ( $plan['status'] ?? '' ) ) { continue; } $findings[] = $this->sectionSkipFinding( $section, $catalog, $product, $plan ); } return $findings; } /** * @param array $section Normalized BlueprintSection. * @param array $catalog SectionCatalog::typesFor( Generators::DESCRIPTION ). * @param WC_Product $product Product being checked. * @param array $plan The section's plan. * @return array */ private function sectionSkipFinding( array $section, array $catalog, WC_Product $product, array $plan ): array { $type = (string) ( $section['type'] ?? '' ); $name = trim( (string) ( $section['name'] ?? '' ) ); $label = '' !== $name ? $name : (string) ( $catalog[ $type ]['label'] ?? $type ); $why = $this->sectionSkipReason( $type, $section, $product, $plan ); return array( 'code' => 'section_will_skip', 'severity' => 'info', 'field' => 'description', /* translators: %1$s: the section's own name/label. %2$s: the short reason it will be skipped. */ 'message' => sprintf( __( '%1$s will be skipped: %2$s.', 'ai-product-tools' ), $label, $why ), /* translators: %s: the section's own name/label. */ 'label' => sprintf( __( '%s will be skipped', 'ai-product-tools' ), $label ), 'sectionId' => (string) ( $section['id'] ?? '' ), ); } /** * The short, section-type-specific reason a `section_will_skip` finding * names. A section type an extension writes names its own reason (each * may call for a different merchant action); every other type keeps * today's wording. * * @param string $type Section type. * @param array $section Normalized BlueprintSection. * @param WC_Product $product Product being checked. * @param array $plan The section's plan. * @return string */ private function sectionSkipReason( string $type, array $section, WC_Product $product, array $plan ): string { $extension = SectionTypeExtensions::get( $type ); if ( null !== $extension ) { $reason = $extension->checkReason( $product, $plan ); if ( '' !== $reason ) { return $reason; } } $fields_mode = (string) ( $section['fields']['mode'] ?? 'all' ); if ( 'specs' === $type && 'selected' !== $fields_mode ) { return __( 'no product attributes', 'ai-product-tools' ); } return __( 'no data for this section', 'ai-product-tools' ); } }