docs(regex): add regex porting rules

Document the conventions for porting PCRE patterns to the regex crate
(no PCRE crate, panic on compile failure, dropping performance-only
possessive quantifiers, ad-hoc compatibility comments). Apply the rule
to Platform::expand_path by rewriting its conditional subpattern as an
explicit alternation, which the regex crate can compile.

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

2 files changed, 9 insertions, 2 deletions

diff --git a/crates/shirabe-external-packages/src/composer/pcre/preg.rs b/crates/shirabe-external-packages/src/composer/pcre/preg.rs
index 1ff7dc6..2c7430d 100644
--- a/crates/shirabe-external-packages/src/composer/pcre/preg.rs
+++ b/crates/shirabe-external-packages/src/composer/pcre/preg.rs
@@ -8,6 +8,8 @@
 //! - `UnexpectedNullMatchException`: thrown by the `Preg::*StrictGroups()` variants when a capture
 //!   group did not participate. Those variants were dropped because Rust's `Option` already
 //!   distinguishes participating from non-participating groups.
+//!
+//! See docs/dev/regex-porting.md for more detailed regex porting rules.
 
 use indexmap::IndexMap;
 use shirabe_php_shim::{
diff --git a/crates/shirabe/src/util/platform.rs b/crates/shirabe/src/util/platform.rs
index 797bac2..7c9f569 100644
--- a/crates/shirabe/src/util/platform.rs
+++ b/crates/shirabe/src/util/platform.rs
@@ -101,11 +101,16 @@ impl Platform {
             );
         }
 
+        // Regex pattern compatibility:
+        // The original pattern uses a conditional subpattern to make the trailing `%` required
+        // only for the `%VAR%` form. The Rust regex crate does not support conditionals, so the
+        // two forms are written as an explicit alternation: `$VAR` or `%VAR%`.
         Preg::replace_callback(
-            r"#^(\$|(?P<percent>%))(?P<var>\w++)(?(percent)%)(?P<path>.*)#",
+            r"#^(?:\$(?P<dvar>\w+)|%(?P<pvar>\w+)%)(?P<path>.*)#",
             |matches: &indexmap::IndexMap<CaptureKey, String>| -> String {
                 let var = matches
-                    .get(&CaptureKey::ByName("var".to_string()))
+                    .get(&CaptureKey::ByName("dvar".to_string()))
+                    .or_else(|| matches.get(&CaptureKey::ByName("pvar".to_string())))
                     .map(|s| s.as_str())
                     .unwrap_or("");
                 let path_part = matches