feat(plugin-class-classifier): add deterministic plugin-boundary classifier

Decides, for every composer/composer class, how it is treated at the
plugin boundary (rust-proxy / rust-snapshot / contract / two-world /
php-native / unsupported) so that upstream updates re-classify new or
rewritten classes without re-deriving the design by hand. Rules and
category definitions live in docs/dev/plugin-class-classification.md;
the tool (PHP + nikic/PHP-Parser) implements them as a reachability
closure with direction marks, per-method pure/mutator analysis, and a
leaf-first fixed point for unreachable classes, with three small
versioned exception lists.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

1 files changed, 63 insertions, 0 deletions

diff --git a/scripts/plugin-class-classifier/src/ClassInfo.php b/scripts/plugin-class-classifier/src/ClassInfo.php
new file mode 100644
index 00000000..84af72d4
--- /dev/null
+++ b/scripts/plugin-class-classifier/src/ClassInfo.php
@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shirabe\PluginClassifier;
+
+final class ClassInfo
+{
+    /** @var array<string, MethodInfo> keyed by lowercase method name */
+    public array $methods = [];
+
+    /** @var list<PropertyInfo> */
+    public array $properties = [];
+
+    /** @var list<string> FQCNs of used traits */
+    public array $traitUses = [];
+
+    /**
+     * Types instantiated in method bodies (`new X`). Instantiating a
+     * proxied service from real PHP raises the dual-instantiation question,
+     * so these are tracked apart from static references.
+     *
+     * @var list<string>
+     */
+    public array $newRefs = [];
+
+    /**
+     * Types referenced statically in method bodies (`X::method()`, writes
+     * to `X::$prop`). Satisfied by any executable presence in the child
+     * world, including a generated proxy stub.
+     *
+     * @var list<string>
+     */
+    public array $staticRefs = [];
+
+    /**
+     * Types referenced from method bodies in ways satisfied by a mere
+     * declaration: `instanceof`, `catch`, `X::class`, constant reads.
+     *
+     * @var list<string>
+     */
+    public array $benignBodyRefs = [];
+
+    public bool $writesOwnStaticProps = false;
+
+    public function __construct(
+        public readonly string $fqcn,
+        /** 'class' | 'interface' | 'trait' | 'enum' */
+        public readonly string $kind,
+        public readonly bool $abstract,
+        public readonly bool $final,
+        public readonly ?string $parent,
+        /** @var list<string> */
+        public readonly array $interfaces,
+        public readonly string $file,
+    ) {
+    }
+
+    public function isContractLike(): bool
+    {
+        return $this->kind === 'interface' || ($this->kind === 'class' && $this->abstract);
+    }
+}