refactor(pcre): return the Preg $matches instead of filling an out-param

`Composer\Pcre\Preg` fills `$matches` through a by-ref parameter, and the
port mirrored that with a `&mut` (or `Option<&mut>`) out-param plus a
bool or count return. Callers had to declare an empty map one line ahead
of the call, and the type never said the map is only meaningful when the
call matched. Return the matches instead:

- match3/match4/is_match3/is_match4 -> Option<PregMatchedGroups>
- is_match_named -> Option<PregNamedGroups>
- match_all2/is_match_all -> PregMatchesAll
- is_match_all_with_offsets3 -> PregMatchesAllWithOffsets

Nothing is lost: the bool is `Option::is_some()`, and the occurrence
count is the length of any one column of a PREG_PATTERN_ORDER map, now
spelled `PregMatchesAll::occurrence_count()`. is_match() still answers
the bool question directly for callers that want no groups.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

7 files changed, 69 insertions, 124 deletions

diff --git a/crates/shirabe/src/command/archive_command.rs b/crates/shirabe/src/command/archive_command.rs
index 1d7165ac..09066c9f 100644
--- a/crates/shirabe/src/command/archive_command.rs
+++ b/crates/shirabe/src/command/archive_command.rs
@@ -26,7 +26,7 @@ use crate::util::Platform;
 use crate::util::ProcessExecutor;
 use crate::util::r#loop::Loop;
 use indexmap::IndexMap;
-use shirabe_pcre::{CaptureKey, Preg, PregMatchedGroups};
+use shirabe_pcre::{CaptureKey, Preg};
 use shirabe_php_shim::{LogicException, get_debug_type, impl_php_class, php_regex};
 use shirabe_symfony_console::command::Command;
 use shirabe_symfony_console::input::InputInterface;
@@ -228,25 +228,21 @@ impl ArchiveCommand {
             min_stability = "stable".to_string();
         }
 
-        if let Some(version_str) = &version {
-            let mut matches = PregMatchedGroups::new();
-            if Preg::match3(
-                php_regex!(r"{@(stable|RC|beta|alpha|dev)$}i"),
-                version_str,
-                Some(&mut matches),
-            ) {
-                let m1 = matches
-                    .get(&CaptureKey::ByIndex(1))
-                    .cloned()
-                    .unwrap_or_default();
-                let m0 = matches
-                    .get(&CaptureKey::ByIndex(0))
-                    .cloned()
-                    .unwrap_or_default();
-                min_stability = VersionParser::normalize_stability(&m1)?;
-                let full_match_len = m0.len();
-                version = Some(version_str[..version_str.len() - full_match_len].to_string());
-            }
+        if let Some(version_str) = &version
+            && let Some(matches) =
+                Preg::match3(php_regex!(r"{@(stable|RC|beta|alpha|dev)$}i"), version_str)
+        {
+            let m1 = matches
+                .get(&CaptureKey::ByIndex(1))
+                .cloned()
+                .unwrap_or_default();
+            let m0 = matches
+                .get(&CaptureKey::ByIndex(0))
+                .cloned()
+                .unwrap_or_default();
+            min_stability = VersionParser::normalize_stability(&m1)?;
+            let full_match_len = m0.len();
+            version = Some(version_str[..version_str.len() - full_match_len].to_string());
         }
 
         let mut repo_set = RepositorySet::new(
diff --git a/crates/shirabe/src/command/config_command.rs b/crates/shirabe/src/command/config_command.rs
index 550ddf3c..86375f49 100644
--- a/crates/shirabe/src/command/config_command.rs
+++ b/crates/shirabe/src/command/config_command.rs
@@ -18,7 +18,7 @@ use crate::util::Filesystem;
 use crate::util::Platform;
 use crate::util::Silencer;
 use indexmap::IndexMap;
-use shirabe_pcre::{CaptureKey, Preg, PregMatchedGroups};
+use shirabe_pcre::{CaptureKey, Preg};
 use shirabe_php_shim::{
     InvalidArgumentException, PhpMixed, RuntimeException, array_is_list, array_merge,
     escapeshellcmd, exec, explode, file_exists, impl_php_class, implode, in_array_loose,
@@ -701,11 +701,9 @@ impl Command for ConfigCommand {
             let mut source = config.borrow_mut().get_source_of_value(&setting_key);
 
             let mut value: PhpMixed;
-            let mut matches = PregMatchedGroups::new();
-            if Preg::is_match3(
+            if let Some(matches) = Preg::is_match3(
                 php_regex!("/^repos?(?:itories)?(?:\\.(.+))?/"),
                 &setting_key,
-                Some(&mut matches),
             ) {
                 if matches.get(&CaptureKey::ByIndex(1)).is_none() {
                     value = data
@@ -929,12 +927,9 @@ impl Command for ConfigCommand {
             return Ok(0);
         }
         // handle preferred-install per-package config
-        let mut matches = PregMatchedGroups::new();
-        if Preg::is_match3(
-            php_regex!("/^preferred-install\\.(.+)/"),
-            &setting_key,
-            Some(&mut matches),
-        ) {
+        if let Some(matches) =
+            Preg::is_match3(php_regex!("/^preferred-install\\.(.+)/"), &setting_key)
+        {
             if input.borrow().get_option("unset")?.as_bool() == Some(true) {
                 self.config_source
                     .borrow_mut()
@@ -967,11 +962,9 @@ impl Command for ConfigCommand {
         }
 
         // handle allow-plugins config setting elements true or false to add/remove
-        let mut matches = PregMatchedGroups::new();
-        if Preg::is_match3(
+        if let Some(matches) = Preg::is_match3(
             php_regex!("{^allow-plugins\\.([a-zA-Z0-9/*-]+)}"),
             &setting_key,
-            Some(&mut matches),
         ) {
             if input.borrow().get_option("unset")?.as_bool() == Some(true) {
                 self.config_source
@@ -1037,12 +1030,9 @@ impl Command for ConfigCommand {
         }
 
         // handle repositories
-        let mut matches = PregMatchedGroups::new();
-        if Preg::is_match3(
-            php_regex!("/^repos?(?:itories)?\\.(.+)/"),
-            &setting_key,
-            Some(&mut matches),
-        ) {
+        if let Some(matches) =
+            Preg::is_match3(php_regex!("/^repos?(?:itories)?\\.(.+)/"), &setting_key)
+        {
             if input.borrow().get_option("unset")?.as_bool() == Some(true) {
                 self.config_source
                     .borrow_mut()
@@ -1106,16 +1096,11 @@ impl Command for ConfigCommand {
             }
 
             return Err(RuntimeException::new("You must pass the type and a url. Example: shirabe config repositories.foo vcs https://bar.com".to_string())
-            .into());
+        .into());
         }
 
         // handle extra
-        let mut matches = PregMatchedGroups::new();
-        if Preg::is_match3(
-            php_regex!("/^extra\\.(.+)/"),
-            &setting_key,
-            Some(&mut matches),
-        ) {
+        if let Some(matches) = Preg::is_match3(php_regex!("/^extra\\.(.+)/"), &setting_key) {
             if input.borrow().get_option("unset")?.as_bool() == Some(true) {
                 self.config_source
                     .borrow_mut()
@@ -1187,12 +1172,7 @@ impl Command for ConfigCommand {
         }
 
         // handle suggest
-        let mut matches = PregMatchedGroups::new();
-        if Preg::is_match3(
-            php_regex!("/^suggest\\.(.+)/"),
-            &setting_key,
-            Some(&mut matches),
-        ) {
+        if let Some(matches) = Preg::is_match3(php_regex!("/^suggest\\.(.+)/"), &setting_key) {
             if input.borrow().get_option("unset")?.as_bool() == Some(true) {
                 self.config_source
                     .borrow_mut()
@@ -1226,12 +1206,7 @@ impl Command for ConfigCommand {
         }
 
         // handle platform
-        let mut matches = PregMatchedGroups::new();
-        if Preg::is_match3(
-            php_regex!("/^platform\\.(.+)/"),
-            &setting_key,
-            Some(&mut matches),
-        ) {
+        if let Some(matches) = Preg::is_match3(php_regex!("/^platform\\.(.+)/"), &setting_key) {
             if input.borrow().get_option("unset")?.as_bool() == Some(true) {
                 self.config_source
                     .borrow_mut()
@@ -1348,13 +1323,11 @@ impl Command for ConfigCommand {
         }
 
         // handle auth
-        let mut matches = PregMatchedGroups::new();
-        if Preg::is_match3(
+        if let Some(matches) = Preg::is_match3(
             php_regex!(
                 "/^(bitbucket-oauth|github-oauth|gitlab-oauth|gitlab-token|http-basic|custom-headers|bearer|forgejo-token)\\.(.+)/"
             ),
             &setting_key,
-            Some(&mut matches),
         ) {
             if input.borrow().get_option("unset")?.as_bool() == Some(true) {
                 self.auth_config_source
@@ -1474,12 +1447,7 @@ impl Command for ConfigCommand {
                     }
 
                     // Check if the header is in correct "Name: Value" format
-                    let mut header_parts = PregMatchedGroups::new();
-                    if !Preg::is_match3(
-                        php_regex!("/^[^:]+:\\s*.+$/"),
-                        header,
-                        Some(&mut header_parts),
-                    ) {
+                    if Preg::is_match3(php_regex!("/^[^:]+:\\s*.+$/"), header).is_none() {
                         return Err(RuntimeException::new(format!(
                             "Header \"{}\" is not in \"Header-Name: Header-Value\" format",
                             header
@@ -1527,12 +1495,7 @@ impl Command for ConfigCommand {
         }
 
         // handle script
-        let mut matches = PregMatchedGroups::new();
-        if Preg::is_match3(
-            php_regex!("/^scripts\\.(.+)/"),
-            &setting_key,
-            Some(&mut matches),
-        ) {
+        if let Some(matches) = Preg::is_match3(php_regex!("/^scripts\\.(.+)/"), &setting_key) {
             if input.borrow().get_option("unset")?.as_bool() == Some(true) {
                 self.config_source
                     .borrow_mut()
@@ -1770,11 +1733,13 @@ fn build_unique_config_values() -> IndexMap<String, (ValidatorFn, NormalizerFn)>
         "cache-files-maxsize".to_string(),
         (
             Box::new(|val| {
-                PhpMixed::Bool(Preg::is_match3(
-                    php_regex!("/^\\s*([0-9.]+)\\s*(?:([kmg])(?:i?b)?)?\\s*$/i"),
-                    val.as_string().unwrap_or(""),
-                    None,
-                ))
+                PhpMixed::Bool(
+                    Preg::is_match3(
+                        php_regex!("/^\\s*([0-9.]+)\\s*(?:([kmg])(?:i?b)?)?\\s*$/i"),
+                        val.as_string().unwrap_or(""),
+                    )
+                    .is_some(),
+                )
             }),
             Box::new(|val| val.clone()),
         ),
diff --git a/crates/shirabe/src/command/create_project_command.rs b/crates/shirabe/src/command/create_project_command.rs
index 33bfb021..ae46da30 100644
--- a/crates/shirabe/src/command/create_project_command.rs
+++ b/crates/shirabe/src/command/create_project_command.rs
@@ -37,7 +37,7 @@ use crate::util::Filesystem;
 use crate::util::Platform;
 use crate::util::ProcessExecutor;
 use indexmap::IndexMap;
-use shirabe_pcre::{CaptureKey, Preg, PregMatchedGroups};
+use shirabe_pcre::{CaptureKey, Preg};
 use shirabe_php_shim::Catch as _;
 use shirabe_php_shim::{
     InvalidArgumentException, PhpMixed, RuntimeException, UnexpectedValueException, array_pop,
@@ -526,34 +526,26 @@ impl CreateProjectCommand {
             if package_version.is_none() {
                 stability = Some("stable".to_string());
             } else {
-                let ok = {
-                    let mut matched = PregMatchedGroups::new();
-                    let ok = Preg::is_match3(
-                        format!(
-                            "{{^[^,\\s]*?@({})$}}i",
-                            implode(
-                                "|",
-                                &STABILITIES
-                                    .keys()
-                                    .map(|k| k.to_string())
-                                    .collect::<Vec<_>>()
-                            )
-                        ),
-                        package_version.as_deref().unwrap_or(""),
-                        Some(&mut matched),
+                let matched = Preg::is_match3(
+                    format!(
+                        "{{^[^,\\s]*?@({})$}}i",
+                        implode(
+                            "|",
+                            &STABILITIES
+                                .keys()
+                                .map(|k| k.to_string())
+                                .collect::<Vec<_>>()
+                        )
+                    ),
+                    package_version.as_deref().unwrap_or(""),
+                );
+                if let Some(matched) = matched {
+                    stability = Some(
+                        matched
+                            .get(&CaptureKey::ByIndex(1))
+                            .cloned()
+                            .unwrap_or_default(),
                     );
-                    if ok {
-                        stability = Some(
-                            matched
-                                .get(&CaptureKey::ByIndex(1))
-                                .cloned()
-                                .unwrap_or_default(),
-                        );
-                    }
-                    ok
-                };
-                if ok {
-                    // stability already set above
                 } else {
                     stability = Some(VersionParser::parse_stability(
                         package_version.as_deref().unwrap_or(""),
diff --git a/crates/shirabe/src/command/diagnose_command.rs b/crates/shirabe/src/command/diagnose_command.rs
index aa581c82..ff9e0e63 100644
--- a/crates/shirabe/src/command/diagnose_command.rs
+++ b/crates/shirabe/src/command/diagnose_command.rs
@@ -33,7 +33,7 @@ use crate::util::ProcessExecutor;
 use crate::util::http::ProxyManager;
 use crate::util::http::RequestProxy;
 use indexmap::IndexMap;
-use shirabe_pcre::{CaptureKey, Preg, PregMatchedGroups};
+use shirabe_pcre::{CaptureKey, Preg};
 use shirabe_php_shim::Catch as _;
 use shirabe_php_shim::{
     AnyThrowable, CmpOp, InvalidArgumentException, PHP_EOL, PhpClass as _, PhpMixed,
@@ -862,11 +862,9 @@ impl DiagnoseCommand {
             warnings.insert("zlib".to_string(), PhpMixed::Bool(true));
         }
 
-        let mut phpinfo_match = PregMatchedGroups::new();
-        if Preg::is_match3(
+        if let Some(phpinfo_match) = Preg::is_match3(
             php_regex!("{Configure Command(?: *</td><td class=\"v\">| *=> *)(.*?)(?:</td>|$)}m"),
             &diagnostics.phpinfo_general,
-            Some(&mut phpinfo_match),
         ) {
             let configure = phpinfo_match
                 .get(&CaptureKey::ByIndex(1))
diff --git a/crates/shirabe/src/command/init_command.rs b/crates/shirabe/src/command/init_command.rs
index 243df290..f9a504be 100644
--- a/crates/shirabe/src/command/init_command.rs
+++ b/crates/shirabe/src/command/init_command.rs
@@ -19,7 +19,7 @@ use crate::util::Filesystem;
 use crate::util::ProcessExecutor;
 use crate::util::Silencer;
 use indexmap::IndexMap;
-use shirabe_pcre::{CaptureKey, Preg, PregMatchedGroups, PregMatchesAll};
+use shirabe_pcre::{CaptureKey, Preg};
 use shirabe_php_shim::Catch as _;
 use shirabe_php_shim::{
     FILE_IGNORE_NEW_LINES, InvalidArgumentException, PHP_EOL, PHP_SERVER, PhpMixed,
@@ -90,11 +90,9 @@ impl InitCommand {
         &self,
         author: &str,
     ) -> anyhow::Result<IndexMap<String, Option<String>>> {
-        let mut m = PregMatchedGroups::new();
-        if Preg::is_match3(
+        if let Some(m) = Preg::is_match3(
             php_regex!(r#"/^(?P<name>[- .,\p{L}\p{N}\p{Mn}\'’\"()]+)(?:\s+<(?P<email>.+?)>)?$/u"#),
             author,
-            Some(&mut m),
         ) {
             let email = m.get(&CaptureKey::ByName("email".to_string())).cloned();
             if let Some(ref email) = email
@@ -175,8 +173,8 @@ impl InitCommand {
         ) == 0
         {
             *self.git_config.borrow_mut() = Some(IndexMap::new());
-            let mut m = PregMatchesAll::new();
-            if Preg::is_match_all(php_regex!(r"{^([^=]+)=(.*)$}m"), &output, &mut m) {
+            let m = Preg::is_match_all(php_regex!(r"{^([^=]+)=(.*)$}m"), &output);
+            if m.occurrence_count() > 0 {
                 let keys: Vec<Option<String>> =
                     m.get(&CaptureKey::ByIndex(1)).cloned().unwrap_or_default();
                 let values: Vec<Option<String>> =
diff --git a/crates/shirabe/src/command/package_discovery_trait.rs b/crates/shirabe/src/command/package_discovery_trait.rs
index 877cc7da..4745a7d5 100644
--- a/crates/shirabe/src/command/package_discovery_trait.rs
+++ b/crates/shirabe/src/command/package_discovery_trait.rs
@@ -19,7 +19,7 @@ use crate::repository::RepositorySet;
 use crate::repository::{RepositoryInterface, SearchResult};
 use crate::util::Filesystem;
 use indexmap::IndexMap;
-use shirabe_pcre::{CaptureKey, Preg, PregMatchedGroups};
+use shirabe_pcre::{CaptureKey, Preg};
 use shirabe_php_shim::Catch as _;
 use shirabe_php_shim::{
     Exception, InvalidArgumentException, LogicException, PHP_EOL, PhpMixed, array_keys,
@@ -330,11 +330,9 @@ pub trait PackageDiscoveryTrait: BaseCommand {
                                 }
                             }
 
-                            let mut m = PregMatchedGroups::new();
-                            if Preg::is_match3(
+                            if let Some(m) = Preg::is_match3(
                                 php_regex!(r"{^\s*(?P<name>[\S/]+)(?:\s+(?P<version>\S+))?\s*$}"),
                                 &selection,
-                                Some(&mut m),
                             ) {
                                 if let Some(v) =
                                     m.get(&CaptureKey::ByName("version".to_string())).cloned()
diff --git a/crates/shirabe/src/command/show_command.rs b/crates/shirabe/src/command/show_command.rs
index e8be4da5..419de424 100644
--- a/crates/shirabe/src/command/show_command.rs
+++ b/crates/shirabe/src/command/show_command.rs
@@ -36,7 +36,7 @@ use crate::repository::RepositoryUtils;
 use crate::repository::RootPackageRepository;
 use crate::util::PackageInfo;
 use indexmap::IndexMap;
-use shirabe_pcre::{CaptureKey, Preg, PregMatchedGroups};
+use shirabe_pcre::{CaptureKey, Preg};
 use shirabe_php_shim::{
     CmpOp, DATE_ATOM, InvalidArgumentException, LogicException, PhpMixed, UnexpectedValueException,
     array_search, date_format_to_strftime, date_local, extension_loaded, impl_php_class,
@@ -1372,12 +1372,10 @@ impl ShowCommand {
         }
 
         if target_version.is_none() {
-            let mut groups = PregMatchedGroups::new();
             if major_only
-                && Preg::is_match3(
+                && let Some(groups) = Preg::is_match3(
                     php_regex!(r"{^(?P<zero_major>(?:0\.)+)?(?P<first_meaningful>\d+)\.}"),
                     &package.get_version(),
-                    Some(&mut groups),
                 )
             {
                 let zero_major = groups