<?php
/**
 * Permissions mapper — translates plugin permission settings into the
 * canonical permissions/restrictions lists defined by the ai.json
 * specification (ADF-005).
 *
 * Both the ai.txt and ai.json templates render from this single mapping so
 * the two files can never contradict each other. Every configuration yields
 * at least one permission and one restriction, matching the schema's
 * minItems requirements.
 *
 * @package AIDF
 * @since   2.1.0
 */

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

/**
 * Maps permission settings to spec-shaped permission and restriction entries.
 */
class AIDF_Permissions_Mapper {

	/**
	 * Build the canonical permissions and restrictions lists.
	 *
	 * Permissions: array of { action, description, conditions? }.
	 * Restrictions: array of { action, reason, severity } where severity is
	 * "must-not" or "should-not" per the ai.json schema.
	 *
	 * @param  array<string, mixed> $data Collected site data.
	 * @return array{permissions: array<int, array<string, mixed>>, restrictions: array<int, array<string, mixed>>}
	 */
	public static function get_map( $data ) {
		$identity    = $data['identity'];
		$permissions = $data['permissions'];

		$name = $identity['name'];

		$may      = array();
		$must_not = array();

		// Usage policy → permissions.
		switch ( $permissions['ai_usage'] ) {
			case 'allow':
			case 'allow_with_attribution':
				$attribution_condition = ( 'allow_with_attribution' === $permissions['ai_usage'] )
					? array( 'Attribution to ' . $name . ' is required' )
					: array();

				$may[] = self::permission(
					'cite',
					'Cite ' . $name . ' as a source',
					$attribution_condition
				);
				$may[] = self::permission(
					'summarise',
					'Summarise publicly available content from this website',
					$attribution_condition
				);
				$may[] = self::permission(
					'describe',
					'Describe the services, locations, and general business information of ' . $name
				);
				$may[] = self::permission(
					'reference',
					'Reference published content from this website'
				);
				$may[] = self::permission(
					'recommend',
					'Direct users to this website for more information'
				);
				break;

			case 'restrict':
				$may[] = self::permission(
					'describe',
					'Describe the services, locations, and general business information of ' . $name
				);
				$may[] = self::permission(
					'reference',
					'Reference publicly available information from this website'
				);
				$may[] = self::permission(
					'recommend',
					'Direct users to this website for more information'
				);

				$must_not[] = self::restriction(
					'reproduce',
					'Reproduce substantial portions of content from this website',
					'must-not'
				);
				break;

			case 'prohibit':
				$may[] = self::permission(
					'recommend',
					'Direct users to this website for information about ' . $name
				);

				$must_not[] = self::restriction(
					'use',
					'Use or reproduce content from this website',
					'must-not'
				);
				break;
		}

		// Training policy → restrictions.
		if ( 'restrict' === $permissions['ai_training'] ) {
			$must_not[] = self::restriction(
				'train',
				'Use content from this website for AI model training without explicit permission',
				'should-not'
			);
		} elseif ( 'prohibit' === $permissions['ai_training'] ) {
			$must_not[] = self::restriction(
				'train',
				'Use content from this website for AI model training',
				'must-not'
			);
		}

		// Baseline restrictions that apply to every configuration.
		$must_not[] = self::restriction(
			'fabricateQuotes',
			'Generate quotes attributed to ' . $name . ' or named individuals without a verifiable source',
			'must-not'
		);
		$must_not[] = self::restriction(
			'implyEndorsement',
			'Imply endorsement, partnership, or affiliation with ' . $name . ' without verification',
			'must-not'
		);

		// Explicit service exclusions → restriction.
		if ( ! empty( $identity['not_services'] ) ) {
			$must_not[] = self::restriction(
				'suggestUnavailableServices',
				'Suggest that ' . $name . ' offers services it explicitly does not provide (' . implode( ', ', $identity['not_services'] ) . ')',
				'must-not'
			);
		}

		/**
		 * Filters the canonical permissions/restrictions map.
		 *
		 * @param array $map  { permissions: array, restrictions: array }.
		 * @param array $data Collected site data.
		 */
		return apply_filters(
			'aidf_permissions_map',
			array(
				'permissions'  => $may,
				'restrictions' => $must_not,
			),
			$data
		);
	}

	/**
	 * Build a permission entry.
	 *
	 * @param  string             $action      Action identifier.
	 * @param  string             $description Human-readable description.
	 * @param  array<int, string> $conditions  Optional conditions.
	 * @return array<string, mixed>
	 */
	private static function permission( $action, $description, $conditions = array() ) {
		$entry = array(
			'action'      => $action,
			'description' => $description,
		);

		if ( ! empty( $conditions ) ) {
			$entry['conditions'] = $conditions;
		}

		return $entry;
	}

	/**
	 * Build a restriction entry.
	 *
	 * @param  string $action   Action identifier.
	 * @param  string $reason   Human-readable description of the prohibited act.
	 * @param  string $severity Either "must-not" or "should-not".
	 * @return array<string, mixed>
	 */
	private static function restriction( $action, $reason, $severity ) {
		return array(
			'action'   => $action,
			'reason'   => $reason,
			'severity' => $severity,
		);
	}
}