From 90e800ba1f012063f4a19364f9a44129f1b6e215 Mon Sep 17 00:00:00 2001 From: kj Date: Mon, 5 Oct 2026 18:10:30 -0300 Subject: [PATCH] feat(commands): describe catalog rows per component with package fallback --- README.org | 18 ++++++------- .../src/Toolbox/Commands/CatalogCommand.php | 2 +- packages/commands/src/Toolbox/Component.php | 11 ++++++++ packages/commands/src/Toolbox/Manifest.php | 13 ++++++++++ tests/group2_manifest_test.php | 25 +++++++++++++++++++ tests/group7_commands_test.php | 24 ++++++++++++++++++ 6 files changed, 83 insertions(+), 10 deletions(-) diff --git a/README.org b/README.org index f6231f7..f3a0c40 100644 --- a/README.org +++ b/README.org @@ -131,7 +131,7 @@ duckbrain update --dry-run # muestra el plan sin escribir - =list=: core y componentes instalados con versión y modo. - =doctor=: matriz de compatibilidad, sin efectos secundarios. -- =catalog=: paquetes y componentes disponibles. +- =catalog=: paquetes y componentes disponibles, cada uno con su descripción. - =adopt=: registra copias hechas a mano en proyectos antiguos. * Manifiesto =duckbrain.json= @@ -278,15 +278,15 @@ Hay *dos* sistemas de versión y no hay que confundirlos: =make help= lista los objetivos: -| Objetivo | Qué hace | -|--------------+-------------------------------------------------------------------------------------------| -| =make test= | Corre la suite (=php tests/run.php=). En verde antes de commitear. | -| =make build= | Genera =dist/duckbrain.phar= + =dist/duckbrain.phar.sha256=. | +| Objetivo | Qué hace | +|--------------+------------------------------------------------------------------------------------------------------------------------| +| =make test= | Corre la suite (=php tests/run.php=). En verde antes de commitear. | +| =make build= | Genera =dist/duckbrain.phar= + =dist/duckbrain.phar.sha256=. | | =make compat= | Barrido de compatibilidad contra el core real (=scripts/compat-sweep=); requiere red. =ARGS="--only pkg"= para un paquete. | -| =make release= | Asistente interactivo de releases de paquetes (=ARGS="pkg minor --yes"= para modo directo). | -| =make publish= | =build= + publica la release =v$(Config::VERSION)= con los assets. Requiere =FORGEJO_TOKEN=. | -| =make check= | =self-update --check= contra el servidor: =actual/disponible=, exit 1 si hay nuevo. | -| =make clean= | Borra =dist/=. | +| =make release= | Asistente interactivo de releases de paquetes (=ARGS="pkg minor --yes"= para modo directo). | +| =make publish= | =build= + publica la release =v$(Config::VERSION)= con los assets. Requiere =FORGEJO_TOKEN=. | +| =make check= | =self-update --check= contra el servidor: =actual/disponible=, exit 1 si hay nuevo. | +| =make clean= | Borra =dist/=. | El token para publicar es un token personal de la API de Forgejo (*Ajustes → Aplicaciones*, scope =write:repository=, con caducidad y revocable). diff --git a/packages/commands/src/Toolbox/Commands/CatalogCommand.php b/packages/commands/src/Toolbox/Commands/CatalogCommand.php index f1c8b4a..655525f 100644 --- a/packages/commands/src/Toolbox/Commands/CatalogCommand.php +++ b/packages/commands/src/Toolbox/Commands/CatalogCommand.php @@ -31,7 +31,7 @@ final class CatalogCommand extends Command $first ? $package->name . ' (' . $package->version . ')' : '', $name, $installed, - $first ? $package->description : '', + $package->descriptionOf($name) ?? '', ]; $first = false; } diff --git a/packages/commands/src/Toolbox/Component.php b/packages/commands/src/Toolbox/Component.php index 39bd404..d1df145 100644 --- a/packages/commands/src/Toolbox/Component.php +++ b/packages/commands/src/Toolbox/Component.php @@ -15,6 +15,7 @@ final class Component public readonly array $requires = [], public readonly ?string $coreRequires = null, public readonly ?string $coreTested = null, + public readonly ?string $description = null, public readonly ?array $destinations = null, public readonly bool $override = false, ) { @@ -51,12 +52,22 @@ final class Component } } + $description = null; + if (isset($data['description'])) { + if (!is_string($data['description'])) { + throw new ToolboxException("El componente '{$name}' tiene un 'description' inválido"); + } + + $description = $data['description']; + } + return new self( name: $name, files: array_values($data['files']), requires: $requires, coreRequires: $data['core']['requires'] ?? null, coreTested: $data['core']['tested'] ?? null, + description: $description, destinations: $destinations, override: (bool) ($data['override'] ?? false), ); diff --git a/packages/commands/src/Toolbox/Manifest.php b/packages/commands/src/Toolbox/Manifest.php index ad4ec34..207f91d 100644 --- a/packages/commands/src/Toolbox/Manifest.php +++ b/packages/commands/src/Toolbox/Manifest.php @@ -157,4 +157,17 @@ final class Manifest return $this->coreTested; } + + /** + * Descripcion efectiva: la propia del componente o, en su ausencia, la del + * paquete (mismo patrón de herencia que los rangos de core). + */ + public function descriptionOf(?string $component = null): ?string + { + if ($component !== null) { + return $this->component($component)->description ?? $this->description; + } + + return $this->description; + } } diff --git a/tests/group2_manifest_test.php b/tests/group2_manifest_test.php index 82d4b74..05025a6 100644 --- a/tests/group2_manifest_test.php +++ b/tests/group2_manifest_test.php @@ -121,3 +121,28 @@ Harness::it('ciclo de dependencias se detecta', function () { rrmdir($dir); }); + +Harness::it('la descripcion del componente prevalece y hereda del paquete', function () { + $m = Manifest::fromArray([ + 'name' => 'pkg', + 'version' => '1.0.0', + 'description' => 'Resumen del paquete', + 'components' => [ + 'a' => ['files' => ['src/A.php'], 'description' => 'Componente A'], + 'b' => ['files' => ['src/B.php']], + ], + ]); + + eq('Componente A', $m->descriptionOf('a'), 'descripción propia gana'); + eq('Resumen del paquete', $m->descriptionOf('b'), 'sin descripción propia hereda del paquete'); + eq('Resumen del paquete', $m->descriptionOf(), 'sin componente: la del paquete'); + + $m2 = Manifest::fromArray(['name' => 'x', 'version' => '1.0.0', 'components' => ['c' => ['files' => ['c.php']]]]); + eq('', $m2->descriptionOf('c'), 'paquete sin texto produce cadena vacía (no null)'); + + throws(fn () => Manifest::fromArray([ + 'name' => 'y', + 'version' => '1.0.0', + 'components' => ['c' => ['files' => ['c.php'], 'description' => 7]], + ]), 'description no-string es inválida'); +}); diff --git a/tests/group7_commands_test.php b/tests/group7_commands_test.php index 548ba30..fcfd3e6 100644 --- a/tests/group7_commands_test.php +++ b/tests/group7_commands_test.php @@ -238,3 +238,27 @@ Harness::it('--force resuelve drift pero no salta avisos de compatibilidad', fun rrmdir($proj); rrmdir($tool); }); + +Harness::it('el catálogo describe cada componente con su texto propio o heredado', function () { + $toolbox = g7_toolbox(); + $manifest = json_decode((string) file_get_contents($toolbox . '/packages/http/duckbrain.json'), true); + $manifest['components']['curlRequest']['description'] = 'Cliente HTTP sobre cURL'; + write_file($toolbox . '/packages/http/duckbrain.json', json_encode($manifest, JSON_PRETTY_PRINT)); + + $proj = tmpdir('proj'); + $out = fopen('php://memory', 'rw'); + $code = (new Toolbox\Commands\CatalogCommand(new Console($out)))->run( + ['--root=' . $proj, '--toolbox=' . $toolbox] + ); + rewind($out); + $text = (string) stream_get_contents($out); + + eq(0, $code, 'catalog termina bien'); + ok((bool) preg_match('/curlRequest.*Cliente HTTP sobre cURL/', $text), 'fila propia con su texto'); + ok((bool) preg_match('/aria2.*Utilidades HTTP/', $text), 'fila sin texto hereda el del paquete'); + ok((bool) preg_match('/compreFace.*Utilidades HTTP/', $text), 'vecino heredando igual'); + ok(!preg_match('/aria2.*cURL/', $text), 'los textos no se mezclan entre filas'); + + rrmdir($toolbox); + rrmdir($proj); +});