<?php
/**
 * File Path: includes/import/class-mbs-importer-base.php
 *
 * MBS_Importer_Base -- Abstract base class for all MBS import handlers.
 *
 * Every F-020+ import handler must extend this class and implement import().
 * Return shape: array{ imported: int, updated: int, skipped: int, errors: array<string> }
 *
 * RF-009: Establishes the typed stats-array contract. Existing importers
 * (MBT, WXR, CSV) are NOT retrofitted per backlog note.
 *
 * @package    My_Book_Showroom
 * @subpackage Includes/Import
 * @since      1.1.0
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

abstract class MBS_Importer_Base { // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedClassFound -- mbs_/MBS_ prefix is correct; scanner not configured with plugin prefix

	/**
	 * Run the import.
	 *
	 * @param array $rows  Associative arrays, one per record.
	 * @return array{ imported: int, updated: int, skipped: int, errors: array<string> }
	 */
	abstract public function import( array $rows ) : array;

	/**
	 * Return a zeroed stats array.
	 *
	 * @return array
	 */
	protected function make_stats() : array {
		return array(
			'imported' => 0,
			'updated'  => 0,
			'skipped'  => 0,
			'errors'   => array(),
		);
	}

	/**
	 * Append an error message to the stats array.
	 *
	 * @param array  &$stats  Stats array passed by reference.
	 * @param string  $message  Error description.
	 */
	protected function add_error( array &$stats, string $message ) : void {
		$stats['errors'][] = $message;
	}
}
