refactor(pcre): inline Preg into its call sites and drop the crate

Preg had shed everything it owned: after the last few rounds its methods
were one-line forwards to the shim's preg_*(), differing only in a
default argument or a wrapper the caller unwrapped anyway. The 460 call
sites now name the shim function, and shirabe-pcre is gone from the
workspace along with its LICENSE entry.

The forwards expand as they read: isMatch becomes
preg_match2(.., 0).is_some() (is_none() where PHP negates it), isMatch3
and match3 drop the .is_some(), matchAll counts through
preg_match_all2(..).occurrence_count(), and replace4/replace5 spell out
the limit and count arguments preg_replace2 takes. Callbacks are the one
place the shapes differ: preg_replace_callback carries an error out of
the callback, so the fourteen infallible closures wrap their result in
Ok() and expect() it back.

Config::process() is the fifteenth, and it drops the `error` cell it
captured to smuggle a failure past a closure that could only return a
String. The `?` in the closure now carries it, which is what the PHP
does -- a throw from the callback leaves preg_replace_callback at the
failing match rather than running the remaining replacements and
reporting the last error.

The module doc that explained why composer/pcre's exceptions and
*StrictGroups() variants have no counterpart moves to the shim's preg
module, where the functions it describes live.

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

1 files changed, 15 insertions, 0 deletions

diff --git a/crates/shirabe-php-shim/src/preg.rs b/crates/shirabe-php-shim/src/preg.rs
index 1e3e9726..202510e9 100644
--- a/crates/shirabe-php-shim/src/preg.rs
+++ b/crates/shirabe-php-shim/src/preg.rs
@@ -1,3 +1,18 @@
+//! PHP's `preg_*` functions. Composer reaches PCRE through the `Composer\Pcre\Preg` wrapper; its
+//! call sites are ported straight onto these functions. `Preg`'s `*StrictGroups()` variants have no
+//! counterpart here because `Option` already tells a non-participating capture group from an empty
+//! one, and a pattern that fails to compile panics instead of raising `PcreException`: Composer
+//! never assembles a pattern that PCRE rejects, so such a failure is a programming error.
+//!
+//! This module's functions do not mirror the PHP signatures for two reasons.
+//!
+//! * Typing: the shape of the `$matches` out parameter of `preg_*()` functions depends on the
+//!   `PREG_*` flags, which is hard to represent in a type-safe way.
+//! * Performance: pattern matching is performed in Composer's hot loops such as dependency
+//!   resolution. Allocating a PHP-compatible `$matches` array is expensive.
+//!
+//! See docs/dev/regex-porting.md for the regex porting rules.
+
 use indexmap::IndexMap;
 use std::sync::{Arc, LazyLock, Mutex};