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, 40 insertions, 0 deletions

diff --git a/scripts/plugin-class-classifier/classify b/scripts/plugin-class-classifier/classify
new file mode 100755
index 00000000..03406ac2
--- /dev/null
+++ b/scripts/plugin-class-classifier/classify
@@ -0,0 +1,40 @@
+#!/usr/bin/env php
+<?php
+
+declare(strict_types=1);
+
+require __DIR__ . '/vendor/autoload.php';
+
+use Shirabe\PluginClassifier\Classifier;
+use Shirabe\PluginClassifier\Lists;
+use Shirabe\PluginClassifier\Report;
+
+$repoRoot = dirname(__DIR__, 2);
+$composerSrc = $repoRoot . '/composer/src/Composer';
+$out = __DIR__ . '/report.json';
+
+foreach (array_slice($argv, 1) as $arg) {
+    if (str_starts_with($arg, '--composer-src=')) {
+        $composerSrc = substr($arg, strlen('--composer-src='));
+    } elseif (str_starts_with($arg, '--out=')) {
+        $out = substr($arg, strlen('--out='));
+    } else {
+        fwrite(STDERR, "usage: classify [--composer-src=DIR] [--out=FILE]\n");
+        exit(2);
+    }
+}
+
+if (!is_dir($composerSrc)) {
+    fwrite(STDERR, "not a directory: $composerSrc\n");
+    exit(2);
+}
+
+$classifier = new Classifier($composerSrc, Lists::load(__DIR__ . '/lists'));
+$classifier->run();
+
+$report = new Report($classifier);
+$report->writeJson($out);
+$report->printSummary();
+
+fwrite(STDERR, "report written to $out\n");
+exit($classifier->violations === [] ? 0 : 1);