feat(php-shim): give ported exceptions PHP's class hierarchy

Ported exceptions were flat structs reached with `downcast_ref`, so
Composer's `catch (\RuntimeException $e)` only matched the exact leaf
type and `get_class($e)` had nothing to report. Each exception now
embeds an instance of the class it extends and travels inside an
`AnyThrowable`; `Catch::catch`/`catch_mut` walk that chain, and
`PhpClass::php_class_name` yields the PHP FQCN.

Dropping the `std::error::Error` impls from the exception types leaves
`AnyThrowable` as the only route into an `anyhow::Error`, so the walk
cannot be bypassed. A `no_exception_downcast` linter catches the
`downcast::<X>()` calls that would now silently answer `None`.

Three sites change behavior as a result: the `TransportException`
exit-code override reaches `MaxFileSizeExceededException`, the
`catch (\LogicException)` in findSimilar() reaches its subclasses, and
rendered exception titles carry the real class name rather than a
guess. `get_class_err()` is no longer a `todo!()`, which re-enables
FilesystemRepositoryTest::testCorruptedRepositoryFile.

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

2 files changed, 85 insertions, 0 deletions

diff --git a/scripts/linters/lint b/scripts/linters/lint
index 44ea7f6d..5f59945d 100755
--- a/scripts/linters/lint
+++ b/scripts/linters/lint
@@ -9,6 +9,7 @@ use Shirabe\Lint\Linters\CargoWorkspaceDependencies;
 use Shirabe\Lint\Linters\ContiguousUseBlock;
 use Shirabe\Lint\Linters\NoBannedUse;
 use Shirabe\Lint\Linters\NoDecorativeSectionComment;
+use Shirabe\Lint\Linters\NoExceptionDowncast;
 use Shirabe\Lint\Linters\NoFormatTrailingComma;
 use Shirabe\Lint\Linters\NoModRs;
 use Shirabe\Lint\Linters\NoStdCollectionsMaps;
@@ -26,6 +27,14 @@ $runner = new Runner($rootDir, [
     [new NoDecorativeSectionComment(), [
         'crates/shirabe-semver/src/version_parser.rs',
     ]],
+    [new NoExceptionDowncast(), [
+        // Defines the box and the walk the rule points at.
+        'crates/shirabe-php-shim/src/exception.rs',
+        // Downcast a panic payload, not an error: PHP's error handler throws an \ErrorException
+        // where these call sites `catch` it.
+        'crates/shirabe/src/cache.rs',
+        'crates/shirabe/src/util/filesystem.rs',
+    ]],
     [new NoFormatTrailingComma(), [
         'crates/shirabe/src/package/loader/root_package_loader.rs',
         'crates/shirabe-spdx-licenses/src/spdx_licenses.rs',
diff --git a/scripts/linters/src/Linters/NoExceptionDowncast.php b/scripts/linters/src/Linters/NoExceptionDowncast.php
new file mode 100644
index 00000000..8d60712b
--- /dev/null
+++ b/scripts/linters/src/Linters/NoExceptionDowncast.php
@@ -0,0 +1,76 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shirabe\Lint\Linters;
+
+use Shirabe\Lint\Linter;
+use Shirabe\Lint\Support\FileFinder;
+use Shirabe\Lint\Support\Paths;
+
+/**
+ * A ported exception travels as an `AnyThrowable`, never as itself, so `downcast_ref::<X>()`
+ * against an exception type compiles and always answers `None`. It would also answer only for the
+ * exact class, where PHP's `catch` answers for every subclass too.
+ */
+final class NoExceptionDowncast implements Linter
+{
+    private const DOWNCAST_RE = '/\bdowncast(?:_ref|_mut)?::<\s*(?:[A-Za-z_][A-Za-z0-9_]*\s*::\s*)*([A-Za-z_][A-Za-z0-9_]*)\s*>/';
+
+    private const EXCEPTION_DEFINITION_RE = '/\b(?:impl_php_exception|define_php_exception)!\(\s*(?:@accessors\s+)?\$?([A-Za-z_][A-Za-z0-9_]*)/';
+
+    public function name(): string
+    {
+        return 'no_exception_downcast';
+    }
+
+    public function failureIntro(): string
+    {
+        return "Found `downcast` against a ported PHP exception type.\n"
+            . 'An exception is carried by an `AnyThrowable`, so this never matches; '
+            . 'use `Catch::catch` / `Catch::catch_mut`, which match subclasses too:';
+    }
+
+    public function check(string $rootDir, array $excludes): array
+    {
+        $exceptionTypes = $this->exceptionTypes($rootDir);
+        $errors = [];
+
+        foreach (FileFinder::rustFiles($rootDir) as $path) {
+            $relative = Paths::relativeTo($rootDir, $path);
+            if (in_array($relative, $excludes, true)) {
+                continue;
+            }
+
+            foreach (file($path) as $idx => $line) {
+                if (!preg_match(self::DOWNCAST_RE, $line, $m)) {
+                    continue;
+                }
+                if (!isset($exceptionTypes[$m[1]])) {
+                    continue;
+                }
+
+                $errors[] = "{$relative}:" . ($idx + 1) . ": downcast to `{$m[1]}`";
+            }
+        }
+
+        return $errors;
+    }
+
+    /** @return array<string, true> the type name of every ported exception */
+    private function exceptionTypes(string $rootDir): array
+    {
+        $types = [];
+
+        foreach (FileFinder::rustFiles($rootDir) as $path) {
+            preg_match_all(self::EXCEPTION_DEFINITION_RE, file_get_contents($path), $matches);
+            foreach ($matches[1] as $name) {
+                if ($name !== 'ty') {
+                    $types[$name] = true;
+                }
+            }
+        }
+
+        return $types;
+    }
+}