@relvehq/agent-ready 0.3.0 → 0.3.1

package/dist/wp/relve-agent-ready/includes/class-relve-ar-negotiation.php

@@ -1,334 +1,334 @@
-<?php
-/**
- * Negotiation: does this request want Markdown, and for which path?
- *
- * PHP port of @relvehq/agent-ready core/accept.ts and core/detect.ts. Keep the
- * two in step: the cases in tests/run.php mirror test/detect.test.ts.
- *
- * Accept rule: serve Markdown only when `text/markdown` is listed explicitly
- * and its q-value is greater than or equal to the q-value that applies to
- * `text/html`. Ties go to Markdown. Wildcards never select Markdown on their
- * own, but they count towards HTML's q-value. The user agent is never an
- * input (choosing by user agent is cloaking).
- *
- * Three ways to ask, in order of precedence: a `.md` suffix, `?format=md`
- * (also `format=markdown`), the Accept header. Plus the llms.txt path(s).
- * Only GET and HEAD are ever considered.
- *
- * Pure PHP: no WordPress calls, so it is unit-testable without WordPress.
- *
- * @package Relve_Agent_Ready
- */
-
-if ( ! defined( 'ABSPATH' ) ) {
-	exit;
-}
-
-/**
- * Accept negotiation and request detection.
- */
-class Relve_AR_Negotiation {
-
-	/** Longer Accept headers are treated as absent (HTML). */
-	const MAX_ACCEPT_LENGTH = 4096;
-
-	/** Longer paths are never Markdown requests. */
-	const MAX_PATH_LENGTH = 1024;
-
-	/**
-	 * Which format does this Accept header prefer?
-	 *
-	 * @param string|null $accept The Accept header, or null when absent.
-	 * @return string "markdown" or "html".
-	 */
-	public static function choose_format( $accept ) {
-		if ( ! is_string( $accept ) || '' === $accept || strlen( $accept ) > self::MAX_ACCEPT_LENGTH ) {
-			return 'html';
-		}
-		$ranges     = self::parse_accept( $accept );
-		$markdown_q = self::explicit_q( $ranges, 'text', 'markdown' );
-		if ( null === $markdown_q || $markdown_q <= 0 ) {
-			return 'html';
-		}
-		return $markdown_q >= self::html_q( $ranges ) ? 'markdown' : 'html';
-	}
-
-	/**
-	 * Parse an Accept header into media ranges.
-	 *
-	 * @param string $accept Header value.
-	 * @return array[] List of array( 'type' => , 'subtype' => , 'q' => float ).
-	 */
-	public static function parse_accept( $accept ) {
-		$ranges = array();
-		foreach ( explode( ',', $accept ) as $part ) {
-			$params     = explode( ';', $part );
-			$media_type = strtolower( trim( (string) array_shift( $params ) ) );
-			$bits       = explode( '/', $media_type );
-			if ( count( $bits ) !== 2 || '' === $bits[0] || '' === $bits[1] ) {
-				continue;
-			}
-			$q = 1.0;
-			foreach ( $params as $param ) {
-				$kv   = explode( '=', $param );
-				$name = strtolower( trim( $kv[0] ) );
-				if ( 'q' !== $name ) {
-					continue;
-				}
-				$value = isset( $kv[1] ) ? trim( $kv[1] ) : '';
-				$q     = self::parse_q( $value );
-			}
-			$ranges[] = array(
-				'type'    => $bits[0],
-				'subtype' => $bits[1],
-				'q'       => $q,
-			);
-		}
-		return $ranges;
-	}
-
-	/**
-	 * RFC 9110 qvalue. Malformed means unacceptable (0), never preferred.
-	 *
-	 * @param string $value Raw q value.
-	 * @return float
-	 */
-	public static function parse_q( $value ) {
-		if ( ! preg_match( '/^(0(\.\d{0,3})?|1(\.0{0,3})?)$/', $value ) ) {
-			return 0.0;
-		}
-		return (float) $value;
-	}
-
-	/**
-	 * Highest q given to exactly type/subtype, or null if not listed.
-	 *
-	 * @param array[] $ranges  Parsed ranges.
-	 * @param string  $type    Type.
-	 * @param string  $subtype Subtype.
-	 * @return float|null
-	 */
-	private static function explicit_q( $ranges, $type, $subtype ) {
-		$best = null;
-		foreach ( $ranges as $r ) {
-			if ( $r['type'] === $type && $r['subtype'] === $subtype ) {
-				$best = max( null === $best ? 0.0 : $best, $r['q'] );
-			}
-		}
-		return $best;
-	}
-
-	/**
-	 * The q that applies to text/html: text/html, then text/*, then *\/*.
-	 *
-	 * @param array[] $ranges Parsed ranges.
-	 * @return float
-	 */
-	private static function html_q( $ranges ) {
-		foreach ( array( array( 'text', 'html' ), array( 'text', '*' ), array( '*', '*' ) ) as $pair ) {
-			$q = self::explicit_q( $ranges, $pair[0], $pair[1] );
-			if ( null !== $q ) {
-				return $q;
-			}
-		}
-		return 0.0;
-	}
-
-	/**
-	 * Leading slash, no trailing slash, no query or hash. Null for anything
-	 * that is not a plain path (traversal, backslashes, "//host", too long).
-	 *
-	 * @param mixed $raw Path.
-	 * @return string|null
-	 */
-	public static function normalize_path( $raw ) {
-		if ( ! is_string( $raw ) ) {
-			return null;
-		}
-		$path = explode( '#', explode( '?', $raw, 2 )[0], 2 )[0];
-		if ( '' === $path || '/' !== $path[0] || strlen( $path ) > self::MAX_PATH_LENGTH ) {
-			return null;
-		}
-		if ( false !== strpos( $path, '..' ) || false !== strpos( $path, '\\' ) || preg_match( '#//.#', $path ) ) {
-			return null;
-		}
-		$trimmed = rtrim( $path, '/' );
-		return '' === $trimmed ? '/' : $trimmed;
-	}
-
-	/**
-	 * "/x.md" -> "/x"; "<home>/index.md" -> "<home>/" ("/" when home is the
-	 * root); null when not a .md URL or a dotfile ("/.md", "/docs/.md").
-	 *
-	 * @param string $pathname  Request path.
-	 * @param string $home_path Home path without trailing slash ("" or "/blog").
-	 * @return string|null
-	 */
-	public static function strip_md_suffix( $pathname, $home_path = '' ) {
-		$lower = strtolower( $pathname );
-		if ( substr( $lower, -3 ) !== '.md' ) {
-			return null;
-		}
-		if ( strtolower( $home_path . '/index.md' ) === $lower ) {
-			return $home_path . '/';
-		}
-		$base = substr( $pathname, 0, -3 );
-		if ( '' === $base || '/' === substr( $base, -1 ) ) {
-			return null;
-		}
-		return $base;
-	}
-
-	/**
-	 * "/x" -> "/x.md"; the home path -> "<home>/index.md".
-	 *
-	 * @param string $path      Normalised path.
-	 * @param string $home_path Home path without trailing slash.
-	 * @return string
-	 */
-	public static function md_url_path( $path, $home_path = '' ) {
-		$path = rtrim( $path, '/' );
-		if ( '' === $path || $path === $home_path ) {
-			return $home_path . '/index.md';
-		}
-		return $path . '.md';
-	}
-
-	/**
-	 * Detect a Markdown request.
-	 *
-	 * @param string   $method     HTTP method.
-	 * @param string   $uri        Raw REQUEST_URI (path plus query).
-	 * @param string   $accept     Accept header ('' when absent).
-	 * @param string   $home_path  Home path without trailing slash.
-	 * @param string[] $llms_paths Paths llms.txt is answered at (empty = none).
-	 * @return array {
-	 *     @type bool        $markdown Is this a Markdown request?
-	 *     @type string|null $via      suffix|query|accept|llms, null when not.
-	 *     @type string      $path     Normalised page path without ".md".
-	 *     @type bool        $llms     Is this the llms.txt request?
-	 *     @type string|null $uri      REQUEST_URI for WordPress to parse (".md" and format removed), null to keep.
-	 * }
-	 */
-	public static function detect( $method, $uri, $accept, $home_path = '', $llms_paths = array() ) {
-		$no = array(
-			'markdown' => false,
-			'via'      => null,
-			'path'     => '/',
-			'llms'     => false,
-			'uri'      => null,
-		);
-		$method = strtoupper( (string) $method );
-		if ( 'GET' !== $method && 'HEAD' !== $method ) {
-			return $no;
-		}
-		$uri      = (string) $uri;
-		$parts    = explode( '?', $uri, 2 );
-		$pathname = explode( '#', $parts[0], 2 )[0];
-		$query    = isset( $parts[1] ) ? explode( '#', $parts[1], 2 )[0] : '';
-
-		$format = '';
-		$kept   = array();
-		if ( '' !== $query ) {
-			foreach ( explode( '&', $query ) as $pair ) {
-				if ( '' === $pair ) {
-					continue;
-				}
-				$kv   = explode( '=', $pair, 2 );
-				$name = urldecode( $kv[0] );
-				if ( 'format' === $name ) {
-					$format = strtolower( urldecode( isset( $kv[1] ) ? $kv[1] : '' ) );
-					continue;
-				}
-				$kept[] = $pair;
-			}
-		}
-		$search = $kept ? '?' . implode( '&', $kept ) : '';
-
-		if ( in_array( $pathname, (array) $llms_paths, true ) ) {
-			return array(
-				'markdown' => true,
-				'via'      => 'llms',
-				'path'     => $pathname,
-				'llms'     => true,
-				'uri'      => null,
-			);
-		}
-
-		$stripped = self::strip_md_suffix( $pathname, $home_path );
-		if ( null !== $stripped ) {
-			$path = self::normalize_path( $stripped );
-			if ( null === $path ) {
-				return $no;
-			}
-			// WordPress parses the path without ".md". Keep the slash a
-			// "<home>/index.md" mapped to, so the home path itself parses.
-			$wp_path = ( '/' === substr( $stripped, -1 ) ) ? ( '/' === $path ? '/' : $path . '/' ) : $path;
-			return array(
-				'markdown' => true,
-				'via'      => 'suffix',
-				'path'     => $path,
-				'llms'     => false,
-				'uri'      => $wp_path . $search,
-			);
-		}
-
-		$path = self::normalize_path( $pathname );
-		if ( null === $path ) {
-			return $no;
-		}
-		if ( 'md' === $format || 'markdown' === $format ) {
-			return array(
-				'markdown' => true,
-				'via'      => 'query',
-				'path'     => $path,
-				'llms'     => false,
-				'uri'      => $pathname . $search,
-			);
-		}
-		if ( 'markdown' === self::choose_format( $accept ) ) {
-			return array(
-				'markdown' => true,
-				'via'      => 'accept',
-				'path'     => $path,
-				'llms'     => false,
-				'uri'      => null,
-			);
-		}
-		$no['path'] = $path;
-		return $no;
-	}
-
-	/**
-	 * Segment-aware prefix match, like the package's isExcluded: "/cart"
-	 * excludes "/cart" and "/cart/x", not "/cartoon". Rules are matched
-	 * against the full path and the path relative to the home path.
-	 *
-	 * @param string   $path      Normalised path.
-	 * @param string[] $rules     Path prefixes.
-	 * @param string   $home_path Home path without trailing slash.
-	 * @return bool
-	 */
-	public static function is_excluded( $path, $rules, $home_path = '' ) {
-		$candidates = array( $path );
-		if ( '' !== $home_path && ( $path === $home_path || 0 === strpos( $path, $home_path . '/' ) ) ) {
-			$rel          = substr( $path, strlen( $home_path ) );
-			$candidates[] = '' === $rel ? '/' : $rel;
-		}
-		foreach ( (array) $rules as $rule ) {
-			$p = rtrim( trim( (string) $rule ), '/' );
-			if ( '' === $p ) {
-				continue;
-			}
-			if ( '/' !== $p[0] ) {
-				$p = '/' . $p;
-			}
-			foreach ( $candidates as $c ) {
-				if ( $c === $p || 0 === strpos( $c, $p . '/' ) ) {
-					return true;
-				}
-			}
-		}
-		return false;
-	}
-}
+<?php
+/**
+ * Negotiation: does this request want Markdown, and for which path?
+ *
+ * PHP port of @relvehq/agent-ready core/accept.ts and core/detect.ts. Keep the
+ * two in step: the cases in tests/run.php mirror test/detect.test.ts.
+ *
+ * Accept rule: serve Markdown only when `text/markdown` is listed explicitly
+ * and its q-value is greater than or equal to the q-value that applies to
+ * `text/html`. Ties go to Markdown. Wildcards never select Markdown on their
+ * own, but they count towards HTML's q-value. The user agent is never an
+ * input (choosing by user agent is cloaking).
+ *
+ * Three ways to ask, in order of precedence: a `.md` suffix, `?format=md`
+ * (also `format=markdown`), the Accept header. Plus the llms.txt path(s).
+ * Only GET and HEAD are ever considered.
+ *
+ * Pure PHP: no WordPress calls, so it is unit-testable without WordPress.
+ *
+ * @package Relve_Agent_Ready
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Accept negotiation and request detection.
+ */
+class Relve_AR_Negotiation {
+
+	/** Longer Accept headers are treated as absent (HTML). */
+	const MAX_ACCEPT_LENGTH = 4096;
+
+	/** Longer paths are never Markdown requests. */
+	const MAX_PATH_LENGTH = 1024;
+
+	/**
+	 * Which format does this Accept header prefer?
+	 *
+	 * @param string|null $accept The Accept header, or null when absent.
+	 * @return string "markdown" or "html".
+	 */
+	public static function choose_format( $accept ) {
+		if ( ! is_string( $accept ) || '' === $accept || strlen( $accept ) > self::MAX_ACCEPT_LENGTH ) {
+			return 'html';
+		}
+		$ranges     = self::parse_accept( $accept );
+		$markdown_q = self::explicit_q( $ranges, 'text', 'markdown' );
+		if ( null === $markdown_q || $markdown_q <= 0 ) {
+			return 'html';
+		}
+		return $markdown_q >= self::html_q( $ranges ) ? 'markdown' : 'html';
+	}
+
+	/**
+	 * Parse an Accept header into media ranges.
+	 *
+	 * @param string $accept Header value.
+	 * @return array[] List of array( 'type' => , 'subtype' => , 'q' => float ).
+	 */
+	public static function parse_accept( $accept ) {
+		$ranges = array();
+		foreach ( explode( ',', $accept ) as $part ) {
+			$params     = explode( ';', $part );
+			$media_type = strtolower( trim( (string) array_shift( $params ) ) );
+			$bits       = explode( '/', $media_type );
+			if ( count( $bits ) !== 2 || '' === $bits[0] || '' === $bits[1] ) {
+				continue;
+			}
+			$q = 1.0;
+			foreach ( $params as $param ) {
+				$kv   = explode( '=', $param );
+				$name = strtolower( trim( $kv[0] ) );
+				if ( 'q' !== $name ) {
+					continue;
+				}
+				$value = isset( $kv[1] ) ? trim( $kv[1] ) : '';
+				$q     = self::parse_q( $value );
+			}
+			$ranges[] = array(
+				'type'    => $bits[0],
+				'subtype' => $bits[1],
+				'q'       => $q,
+			);
+		}
+		return $ranges;
+	}
+
+	/**
+	 * RFC 9110 qvalue. Malformed means unacceptable (0), never preferred.
+	 *
+	 * @param string $value Raw q value.
+	 * @return float
+	 */
+	public static function parse_q( $value ) {
+		if ( ! preg_match( '/^(0(\.\d{0,3})?|1(\.0{0,3})?)$/', $value ) ) {
+			return 0.0;
+		}
+		return (float) $value;
+	}
+
+	/**
+	 * Highest q given to exactly type/subtype, or null if not listed.
+	 *
+	 * @param array[] $ranges  Parsed ranges.
+	 * @param string  $type    Type.
+	 * @param string  $subtype Subtype.
+	 * @return float|null
+	 */
+	private static function explicit_q( $ranges, $type, $subtype ) {
+		$best = null;
+		foreach ( $ranges as $r ) {
+			if ( $r['type'] === $type && $r['subtype'] === $subtype ) {
+				$best = max( null === $best ? 0.0 : $best, $r['q'] );
+			}
+		}
+		return $best;
+	}
+
+	/**
+	 * The q that applies to text/html: text/html, then text/*, then *\/*.
+	 *
+	 * @param array[] $ranges Parsed ranges.
+	 * @return float
+	 */
+	private static function html_q( $ranges ) {
+		foreach ( array( array( 'text', 'html' ), array( 'text', '*' ), array( '*', '*' ) ) as $pair ) {
+			$q = self::explicit_q( $ranges, $pair[0], $pair[1] );
+			if ( null !== $q ) {
+				return $q;
+			}
+		}
+		return 0.0;
+	}
+
+	/**
+	 * Leading slash, no trailing slash, no query or hash. Null for anything
+	 * that is not a plain path (traversal, backslashes, "//host", too long).
+	 *
+	 * @param mixed $raw Path.
+	 * @return string|null
+	 */
+	public static function normalize_path( $raw ) {
+		if ( ! is_string( $raw ) ) {
+			return null;
+		}
+		$path = explode( '#', explode( '?', $raw, 2 )[0], 2 )[0];
+		if ( '' === $path || '/' !== $path[0] || strlen( $path ) > self::MAX_PATH_LENGTH ) {
+			return null;
+		}
+		if ( false !== strpos( $path, '..' ) || false !== strpos( $path, '\\' ) || preg_match( '#//.#', $path ) ) {
+			return null;
+		}
+		$trimmed = rtrim( $path, '/' );
+		return '' === $trimmed ? '/' : $trimmed;
+	}
+
+	/**
+	 * "/x.md" -> "/x"; "<home>/index.md" -> "<home>/" ("/" when home is the
+	 * root); null when not a .md URL or a dotfile ("/.md", "/docs/.md").
+	 *
+	 * @param string $pathname  Request path.
+	 * @param string $home_path Home path without trailing slash ("" or "/blog").
+	 * @return string|null
+	 */
+	public static function strip_md_suffix( $pathname, $home_path = '' ) {
+		$lower = strtolower( $pathname );
+		if ( substr( $lower, -3 ) !== '.md' ) {
+			return null;
+		}
+		if ( strtolower( $home_path . '/index.md' ) === $lower ) {
+			return $home_path . '/';
+		}
+		$base = substr( $pathname, 0, -3 );
+		if ( '' === $base || '/' === substr( $base, -1 ) ) {
+			return null;
+		}
+		return $base;
+	}
+
+	/**
+	 * "/x" -> "/x.md"; the home path -> "<home>/index.md".
+	 *
+	 * @param string $path      Normalised path.
+	 * @param string $home_path Home path without trailing slash.
+	 * @return string
+	 */
+	public static function md_url_path( $path, $home_path = '' ) {
+		$path = rtrim( $path, '/' );
+		if ( '' === $path || $path === $home_path ) {
+			return $home_path . '/index.md';
+		}
+		return $path . '.md';
+	}
+
+	/**
+	 * Detect a Markdown request.
+	 *
+	 * @param string   $method     HTTP method.
+	 * @param string   $uri        Raw REQUEST_URI (path plus query).
+	 * @param string   $accept     Accept header ('' when absent).
+	 * @param string   $home_path  Home path without trailing slash.
+	 * @param string[] $llms_paths Paths llms.txt is answered at (empty = none).
+	 * @return array {
+	 *     @type bool        $markdown Is this a Markdown request?
+	 *     @type string|null $via      suffix|query|accept|llms, null when not.
+	 *     @type string      $path     Normalised page path without ".md".
+	 *     @type bool        $llms     Is this the llms.txt request?
+	 *     @type string|null $uri      REQUEST_URI for WordPress to parse (".md" and format removed), null to keep.
+	 * }
+	 */
+	public static function detect( $method, $uri, $accept, $home_path = '', $llms_paths = array() ) {
+		$no = array(
+			'markdown' => false,
+			'via'      => null,
+			'path'     => '/',
+			'llms'     => false,
+			'uri'      => null,
+		);
+		$method = strtoupper( (string) $method );
+		if ( 'GET' !== $method && 'HEAD' !== $method ) {
+			return $no;
+		}
+		$uri      = (string) $uri;
+		$parts    = explode( '?', $uri, 2 );
+		$pathname = explode( '#', $parts[0], 2 )[0];
+		$query    = isset( $parts[1] ) ? explode( '#', $parts[1], 2 )[0] : '';
+
+		$format = '';
+		$kept   = array();
+		if ( '' !== $query ) {
+			foreach ( explode( '&', $query ) as $pair ) {
+				if ( '' === $pair ) {
+					continue;
+				}
+				$kv   = explode( '=', $pair, 2 );
+				$name = urldecode( $kv[0] );
+				if ( 'format' === $name ) {
+					$format = strtolower( urldecode( isset( $kv[1] ) ? $kv[1] : '' ) );
+					continue;
+				}
+				$kept[] = $pair;
+			}
+		}
+		$search = $kept ? '?' . implode( '&', $kept ) : '';
+
+		if ( in_array( $pathname, (array) $llms_paths, true ) ) {
+			return array(
+				'markdown' => true,
+				'via'      => 'llms',
+				'path'     => $pathname,
+				'llms'     => true,
+				'uri'      => null,
+			);
+		}
+
+		$stripped = self::strip_md_suffix( $pathname, $home_path );
+		if ( null !== $stripped ) {
+			$path = self::normalize_path( $stripped );
+			if ( null === $path ) {
+				return $no;
+			}
+			// WordPress parses the path without ".md". Keep the slash a
+			// "<home>/index.md" mapped to, so the home path itself parses.
+			$wp_path = ( '/' === substr( $stripped, -1 ) ) ? ( '/' === $path ? '/' : $path . '/' ) : $path;
+			return array(
+				'markdown' => true,
+				'via'      => 'suffix',
+				'path'     => $path,
+				'llms'     => false,
+				'uri'      => $wp_path . $search,
+			);
+		}
+
+		$path = self::normalize_path( $pathname );
+		if ( null === $path ) {
+			return $no;
+		}
+		if ( 'md' === $format || 'markdown' === $format ) {
+			return array(
+				'markdown' => true,
+				'via'      => 'query',
+				'path'     => $path,
+				'llms'     => false,
+				'uri'      => $pathname . $search,
+			);
+		}
+		if ( 'markdown' === self::choose_format( $accept ) ) {
+			return array(
+				'markdown' => true,
+				'via'      => 'accept',
+				'path'     => $path,
+				'llms'     => false,
+				'uri'      => null,
+			);
+		}
+		$no['path'] = $path;
+		return $no;
+	}
+
+	/**
+	 * Segment-aware prefix match, like the package's isExcluded: "/cart"
+	 * excludes "/cart" and "/cart/x", not "/cartoon". Rules are matched
+	 * against the full path and the path relative to the home path.
+	 *
+	 * @param string   $path      Normalised path.
+	 * @param string[] $rules     Path prefixes.
+	 * @param string   $home_path Home path without trailing slash.
+	 * @return bool
+	 */
+	public static function is_excluded( $path, $rules, $home_path = '' ) {
+		$candidates = array( $path );
+		if ( '' !== $home_path && ( $path === $home_path || 0 === strpos( $path, $home_path . '/' ) ) ) {
+			$rel          = substr( $path, strlen( $home_path ) );
+			$candidates[] = '' === $rel ? '/' : $rel;
+		}
+		foreach ( (array) $rules as $rule ) {
+			$p = rtrim( trim( (string) $rule ), '/' );
+			if ( '' === $p ) {
+				continue;
+			}
+			if ( '/' !== $p[0] ) {
+				$p = '/' . $p;
+			}
+			foreach ( $candidates as $c ) {
+				if ( $c === $p || 0 === strpos( $c, $p . '/' ) ) {
+					return true;
+				}
+			}
+		}
+		return false;
+	}
+}