feat(plugin): generate the worker proxy stubs from the Composer sources

Replace the hand-written proxy stubs under crates/shirabe-php-rpc/php/stubs
with output of scripts/plugin-stub-generator, a deterministic emitter that
derives every stub from the Composer checkout and the classifier report.
Anything it cannot faithfully proxy (by-ref/variadic parameters, magic
methods, public properties, diverging omitted overrides, stale stub files,
a STUB_FILES entry missing in lib.rs) fails generation instead of degrading
silently, so future Composer releases surface new members as explicit
errors rather than silent gaps.

Regenerating the stubs also normalizes the hand-written inconsistencies
(uniform guarded constructors, import-based type spellings) and fixes real
gaps the review of the generated diff uncovered: the BaseIO authentication
methods now carry the real class's untyped signatures, and the previously
missing ConsoleIO::sanitize is materialized together with its private
static helper. A cargo test runs generate-stubs --check to keep the
committed stubs, the generator and the embedded list from drifting apart.

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

1 files changed, 86 insertions, 0 deletions

diff --git a/scripts/plugin-stub-generator/src/SourceFile.php b/scripts/plugin-stub-generator/src/SourceFile.php
new file mode 100644
index 00000000..771e83a8
--- /dev/null
+++ b/scripts/plugin-stub-generator/src/SourceFile.php
@@ -0,0 +1,86 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shirabe\PluginStubGenerator;
+
+use PhpParser\Node\Stmt\ClassLike;
+use PhpParser\Node\Stmt\GroupUse;
+use PhpParser\Node\Stmt\Namespace_;
+use PhpParser\Node\Stmt\Use_;
+use PhpParser\NodeTraverser;
+use PhpParser\NodeVisitor\NameResolver;
+use PhpParser\Parser;
+
+/**
+ * A parsed source file: the class-like it declares, its namespace and its import table.
+ * All Name nodes in the AST carry a `resolvedName` attribute (NameResolver with
+ * replaceNodes disabled), so signatures can be re-rendered under another file's context.
+ */
+final class SourceFile
+{
+    public ?string $namespace = null;
+
+    /** @var array<string, string> alias as written => FQCN, in declaration order */
+    public array $aliases = [];
+
+    public ClassLike $classLike;
+
+    /** @var list<string> */
+    public array $lines;
+
+    public function __construct(
+        public readonly string $path,
+        public readonly string $expectedFqcn,
+        Parser $parser,
+    ) {
+        $code = file_get_contents($path);
+        if ($code === false) {
+            throw new GenerationError(["cannot read $path"]);
+        }
+        $this->lines = explode("\n", $code);
+
+        $ast = $parser->parse($code);
+        if ($ast === null) {
+            throw new GenerationError(["cannot parse $path"]);
+        }
+        $traverser = new NodeTraverser();
+        $traverser->addVisitor(new NameResolver(null, ['replaceNodes' => false]));
+        $ast = $traverser->traverse($ast);
+
+        $classLike = null;
+        foreach ($ast as $stmt) {
+            if (!$stmt instanceof Namespace_) {
+                continue;
+            }
+            $this->namespace = $stmt->name?->toString();
+            foreach ($stmt->stmts as $inner) {
+                if ($inner instanceof Use_) {
+                    if ($inner->type !== Use_::TYPE_NORMAL) {
+                        throw new GenerationError(["$path: function/const use statements are not supported"]);
+                    }
+                    foreach ($inner->uses as $use) {
+                        $this->aliases[$use->getAlias()->toString()] = $use->name->toString();
+                    }
+                } elseif ($inner instanceof GroupUse) {
+                    throw new GenerationError(["$path: group use statements are not supported"]);
+                } elseif ($inner instanceof ClassLike) {
+                    $fqcn = ($this->namespace === null ? '' : $this->namespace . '\\') . $inner->name?->toString();
+                    if ($fqcn === $expectedFqcn) {
+                        $classLike = $inner;
+                    }
+                }
+            }
+        }
+        if ($classLike === null) {
+            throw new GenerationError(["$path does not declare $expectedFqcn"]);
+        }
+        $this->classLike = $classLike;
+    }
+
+    /** The declaration's verbatim source text, without any leading doc comment. */
+    public function verbatim(int $startLine, int $endLine): string
+    {
+        return implode("\n", array_slice($this->lines, $startLine - 1, $endLine - $startLine + 1));
+    }
+}