From e71e24b5b5cacb93aab3a62e809414fbe9c8a438 Mon Sep 17 00:00:00 2001
From: nsfisis <nsfisis@gmail.com>
Date: Sun, 14 Jun 2026 15:02:44 +0900
Subject: 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>
---
 .../src/composer/pcre/preg.rs                      |  2 ++
 crates/shirabe/src/util/platform.rs                |  9 +++--
 docs/dev/regex-porting.md                          | 39 ++++++++++++++++++++++
 3 files changed, 48 insertions(+), 2 deletions(-)
 create mode 100644 docs/dev/regex-porting.md

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
diff --git a/docs/dev/regex-porting.md b/docs/dev/regex-porting.md
new file mode 100644
index 0000000..4503304
--- /dev/null
+++ b/docs/dev/regex-porting.md
@@ -0,0 +1,39 @@
+# Regex porting
+
+Composer uses PHP's `preg_*` functions (backed by PCRE). Shirabe ports these to the Rust
+[`regex`](https://docs.rs/regex) crate. Because PCRE and the `regex` crate have different feature
+sets, follow the rules below when porting.
+
+## Do not introduce a PCRE crate
+
+The `regex` crate is not based on PCRE library and does not support some features that PCRE does.
+
+Even when such a feature is needed, do not introduce a PCRE-family crate such as `pcre2`. Either
+rewrite the pattern into a form the `regex` crate can express, or decompose it into hand-written
+logic that does not use a regular expression.
+
+## Panic on pattern compile failure
+
+When a pattern fails to compile, `panic!`. Do not wrap it in a `Result` and propagate it to the
+caller.
+
+This reflects a design assumption that Composer-derived patterns always compile successfully at
+runtime: a compile failure is not a recoverable error but a programming mistake (or a porting bug).
+
+## Do not port performance-only possessive quantifiers
+
+When a PCRE possessive quantifier (`++`, `*+`, `?+`, etc.) is used solely to suppress backtracking
+for performance, replace it with the plain quantifier (`+`, `*`, `?`).
+
+The `regex` crate never backtracks, so it has no possessive quantifiers and has no need for them.
+
+## Port other unsupported features ad hoc
+
+For any other PCRE feature the `regex` crate does not support (conditional subpatterns,
+backreferences, etc.), port it case by case. When you do, make the transformation explicit with a
+comment in the following form:
+
+```
+// Regex pattern compatibility:
+// <description>
+```
-- 
cgit v1.3.1