diff --git a/.changelog/framework-skill-sources.md b/.changelog/framework-skill-sources.md new file mode 100644 index 0000000..3cd03f3 --- /dev/null +++ b/.changelog/framework-skill-sources.md @@ -0,0 +1,12 @@ +--- +category: changed +type: patch +--- + +Trust Fast Forward Composer skill donors through `fast-forward/*` and register +the framework's bundled consumer skill as a local source for synchronization. +Allow Changelog contributor skill updates within the stable `0.4.x` release line. +Load the project autoloader for PHPDoc checks when DevTools is installed as a +dependency. +Render the provider guide with supported reStructuredText instead of unavailable +PHP domain directives. diff --git a/.gitattributes b/.gitattributes index ca4c7cb..cbd55f1 100755 --- a/.gitattributes +++ b/.gitattributes @@ -17,3 +17,4 @@ /phpunit.xml export-ignore /README*.md export-ignore /skills.json export-ignore +/.php-cs-fixer.dist.php export-ignore diff --git a/.php-cs-fixer.dist.php b/.php-cs-fixer.dist.php new file mode 100644 index 0000000..d2e6954 --- /dev/null +++ b/.php-cs-fixer.dist.php @@ -0,0 +1,50 @@ + + * @license https://opensource.org/licenses/MIT MIT License + * + * @see https://php-fast-forward.github.io/framework/ + * @see https://github.com/php-fast-forward/framework + * @see https://github.com/php-fast-forward/framework/issues + * @see https://datatracker.ietf.org/doc/html/rfc2119 + */ + +use FastForward\DevTools\Path\WorkingProjectPathResolver; +use PhpCsFixer\Config; +use PhpCsFixer\Finder; + +require __DIR__ . '/vendor/autoload.php'; + +$header = trim((string) preg_replace( + ['!^/\*\*\n!', '! \*/!', '! \* ?!', '!%year%!', '!' . date('Y-Y') . '!'], + ['', '', '', date('Y'), date('Y')], + str_replace("\r\n", "\n", (string) file_get_contents(__DIR__ . '/.docheader')), +)); + +return (new Config()) + ->setRiskyAllowed(false) + ->setFinder(Finder::create()->in(__DIR__)->exclude(WorkingProjectPathResolver::TOOLING_EXCLUDED_DIRECTORIES)) + ->setRules([ + 'header_comment' => [ + 'header' => $header, + 'comment_type' => 'PHPDoc', + 'location' => 'after_declare_strict', + 'separate' => 'both', + ], + 'phpdoc_indent' => true, + 'phpdoc_order' => ['order' => ['param', 'return', 'throws']], + 'phpdoc_separation' => true, + 'phpdoc_trim' => true, + 'phpdoc_trim_consecutive_blank_line_separation' => true, + 'phpdoc_scalar' => true, + 'phpdoc_types' => true, + 'phpdoc_to_comment' => false, + 'phpdoc_add_missing_param_annotation' => true, + ]); diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f8aa927..1b68a22 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,14 +22,18 @@ The development-only `llm/skills` Composer plugin restores the Changelog skill from the reviewed GitHub source in `skills.json`; generated files are ignored by Git. Use `composer skills:show` to inspect it and `composer skills:update --from=github` for an explicit refresh within the -configured version range. Review `skills.json` before changing that range. +configured `^0.4.0` version range (stable `0.4.x` releases, starting at `0.4.0`). +With `auto-sync: true`, Composer also synchronizes skills after install/update; +`--no-scripts` suppresses this automatic step. Review `skills.json` before +changing that range. ## Composer dependency skills -The development-only manager restores the consumer skills from these explicitly -trusted Composer donors. Their minimum versions include the bundled payload; -trust does not extend to other installed packages. No separate GitHub source -is used for these libraries. +The development-only manager restores consumer skills from installed Composer +packages matching the `fast-forward/*` trust pattern. `trusted-replace` keeps +packages outside that namespace untrusted, including other direct dependencies. +The following dependencies have minimum versions that include their bundled +payload. No separate GitHub source is used for these libraries. | Composer donor | Minimum version | Dependency scope | | --- | --- | --- | @@ -50,12 +54,26 @@ is used for these libraries. The HTTP components remain transitive dependencies; Composer conflicts exclude older versions without adding duplicate runtime requirements. The template has an explicit development requirement. Composer Installers is not part of the -installed graph, and the framework's own skill remains in its canonical -`resources/skills` source rather than being a trusted dependency of itself. +installed graph. The framework's own skill is registered as an explicit `dir` +source in `skills.json`, using its canonical `resources/skills` directory. The +directory adapter derives the donor identity without a package override. Inspect donors with `composer skills:show` and refresh their payloads with `composer skills:update --from=composer`. The existing GitHub source continues -to manage the Changelog contributor skill independently. Generated copies remain +to manage the Changelog contributor skill independently, discovering its bundled +skill from the remote package's Composer metadata without a skill allowlist. +Refresh the framework's own skill with `composer skills:update --from=dir`. +Generated copies remain ignored. Synchronization does not upgrade runtime dependencies; an installed version without a bundled skill contributes no skill. Check installed versions and the bundled skill's supported contract before using its instructions. + +## PHPDoc and documentation checks + +The repository's `.php-cs-fixer.dist.php` loads the consumer autoloader and +applies the DevTools PHPDoc and file-header rules. This avoids requiring a +nonexistent nested `vendor/autoload.php` inside the installed DevTools package. +Run `composer dev-tools` for the complete checks and generated documentation. +An install with `--no-plugins` skips preparation of the signed phpDocumentor +executable. When it is missing, run `composer reinstall phpdocumentor/shim` +with the already approved plugins enabled before building documentation. diff --git a/docs/api/service-provider.rst b/docs/api/service-provider.rst index 4dfc1ab..fdbbada 100644 --- a/docs/api/service-provider.rst +++ b/docs/api/service-provider.rst @@ -1,16 +1,16 @@ FrameworkServiceProvider ======================== -.. php:class:: FastForward\Framework\ServiceProvider\FrameworkServiceProvider +``FastForward\Framework\ServiceProvider\FrameworkServiceProvider`` - Aggregates the default Fast Forward framework providers into a single container entry point. - In the current package, it composes the HTTP stack, the event-dispatcher stack, and the clock utilities - by delegating to ``FastForward\Http\ServiceProvider\HttpServiceProvider``, - ``FastForward\EventDispatcher\ServiceProvider\EventDispatcherServiceProvider``, and - ``FastForward\Clock\ServiceProvider\ClockServiceProvider``. +Aggregates the default Fast Forward framework providers into a single container entry point. +In the current package, it composes the HTTP stack, the event-dispatcher stack, and the clock utilities +by delegating to ``FastForward\Http\ServiceProvider\HttpServiceProvider``, +``FastForward\EventDispatcher\ServiceProvider\EventDispatcherServiceProvider``, and +``FastForward\Clock\ServiceProvider\ClockServiceProvider``. - The class extends ``FastForward\Container\ServiceProvider\AggregateServiceProvider``, - so it inherits the provider-merging behavior used across the ecosystem. +The class extends ``FastForward\Container\ServiceProvider\AggregateServiceProvider``, +so it inherits the provider-merging behavior used across the ecosystem. Usage ----- @@ -44,10 +44,10 @@ Important behavior inherited from ``AggregateServiceProvider`` Constructor ----------- -.. php:method:: __construct() +``__construct()`` - Initializes the provider by passing the framework's default provider list to the parent - aggregate provider. +Initializes the provider by passing the framework's default provider list to the parent +aggregate provider. Current scope ------------- diff --git a/skills.json b/skills.json index 2e318b8..47b322e 100644 --- a/skills.json +++ b/skills.json @@ -1,5 +1,5 @@ { - "$schema": "https://raw.githubusercontent.com/roxblnfk/skills/master/resources/skills.schema.json", + "$schema": "https://raw.githubusercontent.com/roxblnfk/skills/1.15.0/resources/skills.schema.json", "target": ".agents/skills", "aliases": [], "discovery": false, @@ -8,31 +8,20 @@ "dependencies": { "composer": { "trusted": [ - "fast-forward/clock", - "fast-forward/config", - "fast-forward/container", - "fast-forward/defer", - "fast-forward/enum", - "fast-forward/event-dispatcher", - "fast-forward/fork", - "fast-forward/http", - "fast-forward/http-client", - "fast-forward/http-factory", - "fast-forward/http-message", - "fast-forward/iterators", - "fast-forward/phpdoc-bootstrap-template" + "fast-forward/*" ], "trusted-replace": true } }, "sources": [ + { + "from": "dir", + "path": "resources/skills" + }, { "from": "github", "package": "php-fast-forward/changelog", - "ref": "^0.3.0", - "skills": [ - "fast-forward-changelog" - ] + "ref": "^0.4.0" } ] }