diff options
Diffstat (limited to 'scripts')
| -rwxr-xr-x | scripts/plugin-stub-generator/generate-stubs | 118 | ||||
| -rw-r--r-- | scripts/plugin-stub-generator/guard-exemptions.list | 14 | ||||
| -rw-r--r-- | scripts/plugin-stub-generator/src/Generator.php | 29 | ||||
| -rw-r--r-- | scripts/plugin-stub-generator/src/GuardGenerator.php | 215 | ||||
| -rw-r--r-- | scripts/plugin-stub-generator/src/Report.php | 33 | ||||
| -rw-r--r-- | scripts/plugin-stub-generator/src/SourceFile.php | 21 |
6 files changed, 373 insertions, 57 deletions
diff --git a/scripts/plugin-stub-generator/generate-stubs b/scripts/plugin-stub-generator/generate-stubs index 5db83a27..c58e6a92 100755 --- a/scripts/plugin-stub-generator/generate-stubs +++ b/scripts/plugin-stub-generator/generate-stubs @@ -7,6 +7,8 @@ require __DIR__ . '/vendor/autoload.php'; use Shirabe\PluginStubGenerator\GenerationError; use Shirabe\PluginStubGenerator\Generator; +use Shirabe\PluginStubGenerator\GuardGenerator; +use Shirabe\PluginStubGenerator\NamePrinter; use Shirabe\PluginStubGenerator\Project; use Shirabe\PluginStubGenerator\Report; @@ -14,6 +16,7 @@ $repoRoot = dirname(__DIR__, 2); $composerRoot = $repoRoot . '/composer'; $reportPath = $repoRoot . '/scripts/plugin-class-classifier/report.json'; $stubsDir = $repoRoot . '/crates/shirabe-php-rpc/php/stubs'; +$guardsDir = $repoRoot . '/crates/shirabe-php-rpc/php/guards'; $libRs = $repoRoot . '/crates/shirabe-php-rpc/src/lib.rs'; $check = false; @@ -24,21 +27,31 @@ foreach (array_slice($argv, 1) as $arg) { $reportPath = substr($arg, strlen('--report=')); } elseif (str_starts_with($arg, '--stubs-dir=')) { $stubsDir = substr($arg, strlen('--stubs-dir=')); + } elseif (str_starts_with($arg, '--guards-dir=')) { + $guardsDir = substr($arg, strlen('--guards-dir=')); } elseif ($arg === '--check') { $check = true; } else { - fwrite(STDERR, "usage: generate-stubs [--composer-root=DIR] [--report=FILE] [--stubs-dir=DIR] [--check]\n"); + fwrite(STDERR, "usage: generate-stubs [--composer-root=DIR] [--report=FILE] [--stubs-dir=DIR]" + . " [--guards-dir=DIR] [--check]\n"); exit(2); } } -$targets = []; -foreach (file(__DIR__ . '/targets.list', FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES) as $line) { - $line = trim($line); - if ($line !== '' && !str_starts_with($line, '#')) { - $targets[] = $line; +/** @return list<string> */ +$readList = static function (string $path): array { + $entries = []; + foreach (file($path, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES) as $line) { + $line = trim($line); + if ($line !== '' && !str_starts_with($line, '#')) { + $entries[] = $line; + } } -} + return $entries; +}; + +$targets = $readList(__DIR__ . '/targets.list'); +$exemptions = $readList(__DIR__ . '/guard-exemptions.list'); // Hand-written dual-mode classes (php/runtime/) resolve through the same worker autoloader as // the generated stubs; the generator must know them so they can serve as stub base classes and @@ -61,9 +74,45 @@ if (is_dir($runtimeDir)) { sort($runtimeProvided); sort($runtimeFiles); +$problems = []; +$report = Report::load($reportPath); +$project = new Project($composerRoot); + +// Every class the Rust side owns and neither a stub nor a runtime class shadows gets a guard, so +// that the worker cannot fall through to the real implementation and run a second instance. +// Exempt entries stay real because the worker has a mechanism that makes a native instance +// correct; each one is justified where it is listed. +$exempt = array_flip($exemptions); +$guardTargets = []; +foreach ($report->inCategories(['rust-proxy', 'rust-snapshot', 'unsupported']) as $fqcn) { + if (in_array($fqcn, $targets, true) || in_array($fqcn, $runtimeProvided, true)) { + continue; + } + if (isset($exempt[$fqcn])) { + unset($exempt[$fqcn]); + continue; + } + if ($report->kind($fqcn) !== 'class') { + $problems[] = "$fqcn is a {$report->kind($fqcn)} in a Rust-owned category; a guard can only" + . ' shadow a class'; + continue; + } + $guardTargets[] = $fqcn; +} +foreach (array_keys($exempt) as $fqcn) { + $problems[] = "stale guard exemption in guard-exemptions.list: $fqcn needs no guard"; +} + try { - $generator = new Generator($composerRoot, Report::load($reportPath), $targets, $runtimeProvided); + $generator = new Generator($composerRoot, $report, $targets, $runtimeProvided); $files = $generator->generate(); + $guardGenerator = new GuardGenerator( + $project, + new NamePrinter(), + $guardTargets, + array_merge($targets, $runtimeProvided), + ); + $guardFiles = $guardGenerator->generate(); } catch (GenerationError $e) { foreach ($e->errors as $error) { fwrite(STDERR, "error: $error\n"); @@ -71,8 +120,6 @@ try { exit(1); } -$problems = []; - // Handoff classification of Composer\Console\Application's declared properties. The worker-side // runtime definition (php/runtime/Composer/Console/Application.php) hands off exactly the state // a plugin-visible application exposes; a property the upstream class declares and this table @@ -87,7 +134,7 @@ $applicationPropertyTable = [ 'hasPluginCommands' => 'rust-local', // Rust-side runtime state, never shared 'logo' => 'static-config', // static rendering data, the worker never needs it ]; -$applicationFile = (new Project($composerRoot))->sourceFor('Composer\\Console\\Application'); +$applicationFile = $project->sourceFor('Composer\\Console\\Application'); $declaredProperties = []; foreach ($applicationFile->classLike->getProperties() as $property) { foreach ($property->props as $prop) { @@ -105,14 +152,23 @@ foreach ($applicationPropertyTable as $name => $_) { } } -$iterator = new RecursiveIteratorIterator( - new RecursiveDirectoryIterator($stubsDir, FilesystemIterator::SKIP_DOTS) -); -foreach ($iterator as $entry) { - if ($entry->isFile() && str_ends_with($entry->getFilename(), '.php')) { - $relative = substr($entry->getPathname(), strlen($stubsDir) + 1); - if (!isset($files[$relative])) { - $problems[] = "stale stub not covered by targets.list: $stubsDir/$relative"; +$generatedSets = [ + [$stubsDir, $files, 'targets.list'], + [$guardsDir, $guardFiles, 'the classifier report'], +]; +foreach ($generatedSets as [$dir, $generated, $source]) { + if (!is_dir($dir)) { + continue; + } + $iterator = new RecursiveIteratorIterator( + new RecursiveDirectoryIterator($dir, FilesystemIterator::SKIP_DOTS) + ); + foreach ($iterator as $entry) { + if ($entry->isFile() && str_ends_with($entry->getFilename(), '.php')) { + $relative = substr($entry->getPathname(), strlen($dir) + 1); + if (!isset($generated[$relative])) { + $problems[] = "stale file not covered by $source: $dir/$relative"; + } } } } @@ -131,24 +187,26 @@ foreach ($runtimeFiles as $relative) { } } -if ($check) { - foreach ($files as $relative => $content) { - $current = @file_get_contents("$stubsDir/$relative"); - if ($current === false) { - $problems[] = "missing stub (regenerate): $stubsDir/$relative"; - } elseif ($current !== $content) { - $problems[] = "stale stub (regenerate): $stubsDir/$relative"; +foreach ([[$stubsDir, $files, 'stubs'], [$guardsDir, $guardFiles, 'guards']] as [$dir, $generated, $what]) { + if ($check) { + foreach ($generated as $relative => $content) { + $current = @file_get_contents("$dir/$relative"); + if ($current === false) { + $problems[] = "missing file (regenerate): $dir/$relative"; + } elseif ($current !== $content) { + $problems[] = "stale file (regenerate): $dir/$relative"; + } } + continue; } -} else { - foreach ($files as $relative => $content) { - $path = "$stubsDir/$relative"; + foreach ($generated as $relative => $content) { + $path = "$dir/$relative"; if (!is_dir(dirname($path))) { mkdir(dirname($path), 0777, true); } file_put_contents($path, $content); } - fwrite(STDERR, count($files) . " stubs written to $stubsDir\n"); + fwrite(STDERR, count($generated) . " $what written to $dir\n"); } foreach ($problems as $problem) { diff --git a/scripts/plugin-stub-generator/guard-exemptions.list b/scripts/plugin-stub-generator/guard-exemptions.list new file mode 100644 index 00000000..90adcb20 --- /dev/null +++ b/scripts/plugin-stub-generator/guard-exemptions.list @@ -0,0 +1,14 @@ +# Classes the Rust side owns that the worker still resolves to the real Composer implementation, +# so no guard is emitted for them. An entry belongs here only when the worker has a mechanism that +# makes a natively constructed instance correct; without one the class must be guarded, or code +# running here would silently work on an instance the Rust side never sees. One FQCN per line, +# each with the mechanism that justifies it. + +# The wire codec revives values of this class from the object record serialize() writes for them +# (php/runtime/Shirabe/MaterializedValue.php), so the real declaration has to stay loadable. +Composer\Package\Link + +# Real Composer\Command code running in this worker constructs one (BaseCommand::initialize), and +# the dual-mode Composer\EventDispatcher\Event (php/runtime/) carries a natively constructed event +# to the Rust side as a P-table entity. +Composer\Plugin\PreCommandRunEvent diff --git a/scripts/plugin-stub-generator/src/Generator.php b/scripts/plugin-stub-generator/src/Generator.php index dd62da60..0b8ef037 100644 --- a/scripts/plugin-stub-generator/src/Generator.php +++ b/scripts/plugin-stub-generator/src/Generator.php @@ -159,7 +159,7 @@ final class Generator return []; } $surface = []; - $parentFqcn = $class->extends === null ? null : $this->resolvedName($class->extends); + $parentFqcn = $class->extends === null ? null : SourceFile::resolvedName($class->extends); if ($parentFqcn !== null) { $surface = $this->surfaces[$parentFqcn] ?? $this->surfaceFromRealClass($parentFqcn); } @@ -195,7 +195,7 @@ final class Generator . '; only rust-proxy and contract classes can become proxy stubs'; } - $parentFqcn = $class->extends === null ? null : $this->resolvedName($class->extends); + $parentFqcn = $class->extends === null ? null : SourceFile::resolvedName($class->extends); $isRoot = $parentFqcn === null; if ($parentFqcn !== null && !isset($this->targetSet[$parentFqcn])) { if (isset($this->runtimeSet[$parentFqcn])) { @@ -348,7 +348,7 @@ final class Generator $header = "// Generated by scripts/plugin-stub-generator; do not edit by hand.\n" . "// Proxy stub for $fqcn: the public surface forwards to the Rust-side entity over RPC."; $text = "<?php\n\n$header\n\nnamespace {$file->namespace};\n\n"; - $uses = $this->usedImports($file, $decl . "\n" . $body); + $uses = $file->importsUsedBy($decl . "\n" . $body); if ($uses !== '') { $text .= $uses . "\n\n"; } @@ -446,11 +446,11 @@ final class Generator } $out[] = $file; foreach ($file->classLike->extends as $parent) { - $visit($this->resolvedName($parent)); + $visit(SourceFile::resolvedName($parent)); } }; foreach ($class->implements as $interface) { - $visit($this->resolvedName($interface)); + $visit(SourceFile::resolvedName($interface)); } return $out; } @@ -527,23 +527,4 @@ final class Generator } return $fingerprint; } - - /** The original file's imports, restricted to names the emitted stub actually uses. */ - private function usedImports(SourceFile $file, string $emittedText): string - { - $kept = []; - foreach ($file->aliases as $alias => $fqcn) { - if (preg_match('/(?<![\\\\$\w])' . preg_quote($alias, '/') . '\b/', $emittedText) === 1) { - $kept[] = 'use ' . $fqcn - . (str_ends_with($fqcn, '\\' . $alias) || $fqcn === $alias ? '' : " as $alias") . ';'; - } - } - return implode("\n", $kept); - } - - private function resolvedName(Name $name): string - { - $resolved = $name->getAttribute('resolvedName'); - return $resolved instanceof Name ? $resolved->toString() : $name->toString(); - } } diff --git a/scripts/plugin-stub-generator/src/GuardGenerator.php b/scripts/plugin-stub-generator/src/GuardGenerator.php new file mode 100644 index 00000000..e471f1a3 --- /dev/null +++ b/scripts/plugin-stub-generator/src/GuardGenerator.php @@ -0,0 +1,215 @@ +<?php + +declare(strict_types=1); + +namespace Shirabe\PluginStubGenerator; + +use PhpParser\Node\Name; +use PhpParser\Node\Stmt\Class_; +use PhpParser\Node\Stmt\ClassMethod; + +/** + * Emits the guard classes: same FQCN, same hierarchy and constants as the real Composer class, + * but every constructor and method raises an explicit error. They cover the classes whose entity + * the Rust side owns and that have no proxy stub, so the worker's autoloader can no longer fall + * through to the real implementation and run a second instance the Rust side never sees. + * + * A declaration-only reference (`instanceof`, `X::class`, a constant) keeps working; only running + * the code fails. + */ +final class GuardGenerator +{ + /** @var list<string> */ + private array $errors = []; + + /** @var array<string, true> */ + private array $guardSet = []; + + /** @var array<string, true> */ + private array $providedSet = []; + + /** @var list<string> `Ancestor::member` entries the class being emitted cannot redeclare */ + private array $inheritedFinals = []; + + /** + * @param list<string> $targets FQCNs to emit a guard for + * @param list<string> $provided FQCNs the worker resolves to a proxy stub or a hand-written + * runtime class; a guard never reproduces their members, since + * those declarations already shadow the real class + */ + public function __construct( + private readonly Project $project, + private readonly NamePrinter $printer, + private readonly array $targets, + array $provided, + ) { + foreach ($targets as $fqcn) { + $this->guardSet[$fqcn] = true; + } + foreach ($provided as $fqcn) { + $this->providedSet[$fqcn] = true; + } + } + + /** @return array<string, string> relative guard path => file content */ + public function generate(): array + { + $files = []; + foreach ($this->targets as $fqcn) { + $files[str_replace('\\', '/', $fqcn) . '.php'] = $this->emitClass($fqcn); + } + if ($this->errors !== []) { + throw new GenerationError($this->errors); + } + return $files; + } + + private function emitClass(string $fqcn): string + { + $file = $this->project->sourceFor($fqcn); + $class = $file->classLike; + if (!$class instanceof Class_) { + $this->errors[] = "$fqcn is not a class"; + return ''; + } + + // Constants and public static properties are compile-time data with no instance behind + // them; they are copied verbatim, visibility included, so that the references a guard is + // meant to keep working (`Link::TYPE_REQUIRE` and friends) resolve to the real values. + $data = []; + foreach ($class->getConstants() as $constant) { + $data[] = $file->verbatim($constant->getStartLine(), $constant->getEndLine()); + } + foreach ($class->getProperties() as $property) { + if ($property->isPublic() && $property->isStatic()) { + $data[] = $file->verbatim($property->getStartLine(), $property->getEndLine()); + } + } + + $methods = []; + $this->inheritedFinals = []; + $closure = $this->methodClosure($fqcn); + if (!isset($closure['__construct'])) { + // Nothing in the hierarchy declares one, so PHP would hand out the implicit + // constructor. The guard declares its own to close that door. + $methods[] = " public function __construct()\n {\n" + . " \\ShirabeUnsupportedClass::fail(self::class, '__construct');\n }"; + } + foreach ($closure as $lowerName => [$method, $declaringFile]) { + if ($method->isPrivate() || $lowerName === '__destruct') { + // A private method is reachable only from the code the guard replaces, and a + // destructor that throws would fire while an exception is already unwinding. + continue; + } + $methods[] = $this->renderMethod($class, $method, $declaringFile); + } + + $decl = ($class->isAbstract() ? 'abstract ' : '') . ($class->isFinal() ? 'final ' : '') + . 'class ' . $class->name?->toString(); + if ($class->extends !== null) { + $decl .= ' extends ' . $this->printer->renderName($class->extends, $file); + } + $interfaces = array_map(fn (Name $n): string => $this->printer->renderName($n, $file), $class->implements); + if ($interfaces !== []) { + $decl .= ' implements ' . implode(', ', $interfaces); + } + + $body = implode("\n\n", array_merge($data === [] ? [] : [implode("\n", $data)], $methods)); + + $header = "// Generated by scripts/plugin-stub-generator; do not edit by hand.\n" + . "// Guard for $fqcn.\n" + . "// The Rust side owns this class and the worker has no proxy for it, so this\n" + . "// declaration shadows the real one: the constants and the hierarchy stay, while\n" + . "// constructing it or calling anything on it raises an explicit error."; + foreach ($this->inheritedFinals as $member) { + $header .= "\n// $member() is final, so it keeps running the real implementation here."; + } + $text = "<?php\n\n$header\n\nnamespace {$file->namespace};\n\n"; + $uses = $file->importsUsedBy($decl . "\n" . $body); + if ($uses !== '') { + $text .= $uses . "\n\n"; + } + return $text . $decl . "\n{\n" . ($body === '' ? '' : $body . "\n") . "}\n"; + } + + /** + * Every method a guard must redeclare: its own (traits included), plus the ones it would + * otherwise inherit from real ancestors. The walk stops at an ancestor that is guarded or + * shadowed by a stub, since that declaration carries the members from there on up. + * + * @return array<string, array{ClassMethod, SourceFile}> lowercased name => method and the + * file its signature is written in + */ + private function methodClosure(string $fqcn): array + { + $file = $this->project->sourceFor($fqcn); + $class = $file->classLike; + $methods = []; + foreach ($class->getMethods() as $method) { + $methods[strtolower($method->name->toString())] ??= [$method, $file]; + } + foreach ($class->getTraitUses() as $traitUse) { + foreach ($traitUse->traits as $trait) { + foreach ($this->methodClosure(SourceFile::resolvedName($trait)) as $name => $entry) { + $methods[$name] ??= $entry; + } + } + } + $parent = $class instanceof Class_ && $class->extends !== null + ? SourceFile::resolvedName($class->extends) + : null; + // A PHP builtin ancestor (FilterIterator, ...) has no source file to read; its methods + // work on internal state that only its own constructor sets up, which the guard blocks. + $isInternal = $parent !== null && class_exists($parent, false) + && (new \ReflectionClass($parent))->isInternal(); + if ($parent !== null && !$isInternal + && !isset($this->guardSet[$parent]) && !isset($this->providedSet[$parent])) { + foreach ($this->methodClosure($parent) as $name => $entry) { + if (isset($methods[$name])) { + continue; + } + if ($entry[0]->isFinal()) { + // PHP refuses the redeclaration, so this member keeps running the real + // implementation; emitClass records it in the guard's header. + $this->inheritedFinals[] = $parent . '::' . $entry[0]->name->toString(); + continue; + } + $methods[$name] = $entry; + } + } + return $methods; + } + + private function renderMethod(Class_ $class, ClassMethod $method, SourceFile $target): string + { + $name = $method->name->toString(); + $params = []; + foreach ($method->params as $param) { + $rendered = ''; + if ($param->type !== null) { + $rendered = $this->printer->renderType($param->type, $target) . ' '; + } + // A promoted constructor property declares state the guard has no use for; the + // parameter itself is kept so the signature a caller sees does not change. + $rendered .= ($param->byRef ? '&' : '') . ($param->variadic ? '...' : '') . '$' . $param->var->name; + if ($param->default !== null) { + $rendered .= ' = ' . $this->printer->renderExpr($param->default, $target); + } + $params[] = $rendered; + } + + $abstract = $method->isAbstract() && $class->isAbstract(); + $returnType = $this->printer->renderType($method->returnType, $target); + $signature = ($abstract ? 'abstract ' : '') . ($method->isFinal() ? 'final ' : '') + . ($method->isPublic() ? 'public' : 'protected') + . ($method->isStatic() ? ' static' : '') + . ' function ' . ($method->byRef ? '&' : '') . $name . '(' . implode(', ', $params) . ')' + . ($returnType === '' ? '' : ": $returnType"); + if ($abstract) { + return " $signature;"; + } + return " $signature\n {\n" + . " \\ShirabeUnsupportedClass::fail(self::class, '$name');\n }"; + } + +} diff --git a/scripts/plugin-stub-generator/src/Report.php b/scripts/plugin-stub-generator/src/Report.php index 92e0565e..758a1768 100644 --- a/scripts/plugin-stub-generator/src/Report.php +++ b/scripts/plugin-stub-generator/src/Report.php @@ -7,8 +7,11 @@ namespace Shirabe\PluginStubGenerator; /** The classifier report (scripts/plugin-class-classifier/report.json). */ final class Report { - /** @param array<string, string> $categories fqcn => category */ - private function __construct(private readonly array $categories) + /** + * @param array<string, string> $categories fqcn => category + * @param array<string, string> $kinds fqcn => class / interface / trait / enum + */ + private function __construct(private readonly array $categories, private readonly array $kinds) { } @@ -24,14 +27,38 @@ final class Report throw new GenerationError(["$path records classification violations; fix the classifier lists first"]); } $categories = []; + $kinds = []; foreach ($data['classes'] as $class) { $categories[$class['fqcn']] = $class['category']; + $kinds[$class['fqcn']] = $class['kind']; } - return new self($categories); + return new self($categories, $kinds); } public function category(string $fqcn): ?string { return $this->categories[$fqcn] ?? null; } + + public function kind(string $fqcn): ?string + { + return $this->kinds[$fqcn] ?? null; + } + + /** + * The FQCNs of the given categories, in report order. + * + * @param list<string> $categories + * @return list<string> + */ + public function inCategories(array $categories): array + { + $out = []; + foreach ($this->categories as $fqcn => $category) { + if (in_array($category, $categories, true)) { + $out[] = $fqcn; + } + } + return $out; + } } diff --git a/scripts/plugin-stub-generator/src/SourceFile.php b/scripts/plugin-stub-generator/src/SourceFile.php index 771e83a8..e20bf00f 100644 --- a/scripts/plugin-stub-generator/src/SourceFile.php +++ b/scripts/plugin-stub-generator/src/SourceFile.php @@ -4,6 +4,7 @@ declare(strict_types=1); namespace Shirabe\PluginStubGenerator; +use PhpParser\Node\Name; use PhpParser\Node\Stmt\ClassLike; use PhpParser\Node\Stmt\GroupUse; use PhpParser\Node\Stmt\Namespace_; @@ -83,4 +84,24 @@ final class SourceFile { return implode("\n", array_slice($this->lines, $startLine - 1, $endLine - $startLine + 1)); } + + /** This file's imports, restricted to the names the emitted text actually uses. */ + public function importsUsedBy(string $emittedText): string + { + $kept = []; + foreach ($this->aliases as $alias => $fqcn) { + if (preg_match('/(?<![\\\\$\w])' . preg_quote($alias, '/') . '\b/', $emittedText) === 1) { + $kept[] = 'use ' . $fqcn + . (str_ends_with($fqcn, '\\' . $alias) || $fqcn === $alias ? '' : " as $alias") . ';'; + } + } + return implode("\n", $kept); + } + + /** The FQCN a Name node resolved to, the NameResolver having left the node itself alone. */ + public static function resolvedName(Name $name): string + { + $resolved = $name->getAttribute('resolvedName'); + return $resolved instanceof Name ? $resolved->toString() : $name->toString(); + } } |