diff --git a/.agents/skills/php-forge-coding-standard b/.agents/skills/php-forge-coding-standard new file mode 120000 index 0000000..e30c4d0 --- /dev/null +++ b/.agents/skills/php-forge-coding-standard @@ -0,0 +1 @@ +../../skills/php-forge-coding-standard \ No newline at end of file diff --git a/.claude/skills/php-forge-coding-standard b/.claude/skills/php-forge-coding-standard new file mode 120000 index 0000000..e30c4d0 --- /dev/null +++ b/.claude/skills/php-forge-coding-standard @@ -0,0 +1 @@ +../../skills/php-forge-coding-standard \ No newline at end of file diff --git a/.gitattributes b/.gitattributes index 2360366..8f4bdd7 100644 --- a/.gitattributes +++ b/.gitattributes @@ -41,3 +41,25 @@ # Avoid merge conflicts in CHANGELOG # https://about.gitlab.com/2015/02/10/gitlab-reduced-merge-conflicts-by-90-percent-with-changelog-placeholders/ /CHANGELOG.md merge=union + +/.agents export-ignore + +/.claude export-ignore + +/internal export-ignore +/vendor export-ignore +/node_modules export-ignore +/.env export-ignore +/.env.* export-ignore + +/.phpunit.cache export-ignore + +/.phpunit.result.cache export-ignore + +/.stryker-tmp export-ignore + +/.codex export-ignore + +/.config export-ignore + +/reports/mutation export-ignore diff --git a/.github/workflows/ecs.yml b/.github/workflows/ecs.yml index 86889c3..a3ac3a7 100644 --- a/.github/workflows/ecs.yml +++ b/.github/workflows/ecs.yml @@ -17,6 +17,6 @@ permissions: jobs: easy-coding-standard: - uses: yii2-framework/actions/.github/workflows/ecs.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1 + uses: php-forge/actions/.github/workflows/ecs.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0 with: command-options: check src --config src/ecs-83.php --ansi diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml index ea2c87f..165fd2f 100644 --- a/.github/workflows/quality.yml +++ b/.github/workflows/quality.yml @@ -10,7 +10,7 @@ permissions: jobs: quality: - uses: yii2-framework/actions/.github/workflows/quality.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1 + uses: php-forge/actions/.github/workflows/quality.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0 permissions: contents: read with: diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml index 6a771ba..b3b632c 100644 --- a/.github/workflows/security.yml +++ b/.github/workflows/security.yml @@ -10,7 +10,7 @@ permissions: jobs: security: - uses: yii2-framework/actions/.github/workflows/security.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1 + uses: php-forge/actions/.github/workflows/security.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0 permissions: contents: read with: diff --git a/.gitignore b/.gitignore index f5ae66e..e05e634 100644 --- a/.gitignore +++ b/.gitignore @@ -114,3 +114,16 @@ Thumbs.db .buildpath .project .settings + +# Package skill discovery; keep other local client state private. +!/.agents/ +/.agents/* +!/.agents/skills/ +/.agents/skills/* +!/.agents/skills/php-forge-coding-standard +!/.claude/ +/.claude/* +!/.claude/skills/ +/.claude/skills/* +!/.claude/skills/php-forge-coding-standard +/internal/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 105aa3e..ccb662a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## 0.3.5 Under development +- chore: standardize package guidance, skill discovery, configuration checks and security reporting. + ## 0.3.4 September 07, 2026 - fix: support ECS `13.3.2+` with the native PER-CS set and explicit PHP `8.1-8.4` migration rules instead of the removed `withPhpCsFixerSets()` arguments. diff --git a/README.md b/README.md index f97717e..3441429 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@

- PHP Forge + PHP Forge

Coding standard


@@ -40,21 +40,21 @@ Then run `composer update`. This package ships shared ECS and Rector configurations under `vendor/php-forge/coding-standard/src/`: -| File | Purpose | -| ------------------- | ------------------------------------------------------- | -| `src/ecs.php` | Shared ECS base rules, no PHP migration set | -| `src/ecs-81.php` | Base + `@PHP81Migration` PHP-CS-Fixer set | -| `src/ecs-82.php` | Base + `@PHP82Migration` | -| `src/ecs-83.php` | Base + `@PHP83Migration` | -| `src/ecs-84.php` | Base + `@PHP84Migration` | -| `src/rector.php` | Shared Rector base rules, no PHP level set | -| `src/rector-81.php` | Base + `SetList::PHP_81` + `LevelSetList::UP_TO_PHP_81` | -| `src/rector-82.php` | Base + `SetList::PHP_82` + `LevelSetList::UP_TO_PHP_82` | -| `src/rector-83.php` | Base + `SetList::PHP_83` + `LevelSetList::UP_TO_PHP_83` | -| `src/rector-84.php` | Base + `SetList::PHP_84` + `LevelSetList::UP_TO_PHP_84` | - -Pick the version that matches the **minimum** PHP your project supports; Rector upgrades code up to that level and -PHP-CS-Fixer enforces matching syntax. The plain `ecs.php` / `rector.php` apply no PHP-version migrations. +| File | Purpose | +| ----------------- | -------------------------------------------------- | +| src/ecs.php | Shared ECS base rules, no PHP migration set | +| src/ecs-81.php | Base + `@PHP81Migration` | +| src/ecs-82.php | Base + `@PHP82Migration` | +| src/ecs-83.php | Base + `@PHP82Migration` (no additional 8.3 rules) | +| src/ecs-84.php | Base + `@PHP84Migration` | +| src/rector.php | Shared Rector base rules, no PHP level set | +| src/rector-81.php | Base + `LevelSetList::UP_TO_PHP_81` | +| src/rector-82.php | Base + `LevelSetList::UP_TO_PHP_82` | +| src/rector-83.php | Base + `LevelSetList::UP_TO_PHP_83` | +| src/rector-84.php | Base + `LevelSetList::UP_TO_PHP_84` | + +Pick the version that matches the **minimum** PHP your project supports; Rector applies migrations up to that level and +ECS applies the corresponding non-risky migration rules. These tools do not prove minimum-version compatibility. The plain `ecs.php` / `rector.php` apply no PHP-version migrations. ### ECS wrapper (ecs.php) @@ -187,6 +187,16 @@ Follow the same convention used across PHP Forge repositories: } ``` +## Testing + +Run `composer tests` to check that each versioned ECS and Rector configuration detects a sample transformation +without modifying the input. Development dependencies require PHP 8.3 or later; the package runtime supports PHP 8.1. + +## AI assistance + +Use the [php-forge-coding-standard skill](skills/php-forge-coding-standard/SKILL.md) and the [AI assistance guide](docs/agents.md) for +package-specific setup, invocation examples and verification. + ## Package information [![PHP](https://img.shields.io/badge/%3E%3D8.1-777BB4.svg?style=for-the-badge&logo=php&logoColor=white)](https://www.php.net/releases/8.1/en.php) @@ -196,8 +206,8 @@ Follow the same convention used across PHP Forge repositories: ## Project status [![Quality](https://img.shields.io/github/actions/workflow/status/php-forge/coding-standard/quality.yml?style=for-the-badge&label=Quality&logo=github)](https://github.com/php-forge/coding-standard/actions/workflows/quality.yml) -[![Security](https://img.shields.io/github/actions/workflow/status/php-forge/coding-standard/security.yml?style=for-the-badge&label=Security&logo=github)](https://github.com/php-forge/coding-standard/actions/workflows/security.yml) -[![StyleCI](https://img.shields.io/badge/StyleCI-Passed-44CC11.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.styleci.io/repos/1141292628?branch=main) +[![Zizmor](https://img.shields.io/github/actions/workflow/status/php-forge/coding-standard/security.yml?style=for-the-badge&label=Zizmor&logo=github)](https://github.com/php-forge/coding-standard/actions/workflows/security.yml) +[![StyleCI](https://img.shields.io/badge/StyleCI-Passing-44CC11.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.styleci.io/repos/1141292628?branch=main) ## Our social networks diff --git a/composer.json b/composer.json index 3830292..33d4ef4 100644 --- a/composer.json +++ b/composer.json @@ -41,6 +41,9 @@ "allowed-packages": [ "php-forge/baseline" ] + }, + "skills": { + "source": "skills" } }, "config": { @@ -50,7 +53,6 @@ } }, "scripts": { - "tests": "php tests/ecs.php", "ecs": "./vendor/bin/ecs check src --config src/ecs-83.php --fix", "rector": "./vendor/bin/rector process src --config src/rector-83.php" } diff --git a/docs/agents.md b/docs/agents.md new file mode 100644 index 0000000..e778020 --- /dev/null +++ b/docs/agents.md @@ -0,0 +1,55 @@ +# AI assistance + +Use the package-owned [php-forge-coding-standard](../skills/php-forge-coding-standard/SKILL.md) skill for selecting PHP Forge ECS and Rector configurations for a supported PHP target. The canonical source is `skills/`; checkout discovery links in `.agents/skills/` and `.claude/skills/` point to that same source. + +## Install in an application + +Composer is the primary distribution path. `extra.skills.source` declares the bundle; installing the package alone does +not register its skill at the application root. In a consumer already configured for `llm/skills`, explicitly trust +`php-forge/coding-standard` and use that installed synchronizer's documented setup. Do not enable plugins or broaden trust by +copying an example. With verified auto-sync enabled, installation/update can synchronize the bundle; otherwise use +`composer skills:update` and inspect `composer skills:show`. Composer exit zero is not proof of client activation. + +An optional pinned installer can use a local checkout or an installed package that contains the bundle: + +```bash +npx skills@1.7.2 add /absolute/path/to/coding-standard --list +npx skills@1.7.2 add /absolute/path/to/coding-standard --skill php-forge-coding-standard --agent claude-code codex opencode +``` + +Keep project scope. Inspect a remote source with `--list` before claiming an unpublished skill is available there. +Copied installations must be refreshed after upgrades. The complete skill directory is the unit of installation. + +## Discover and invoke + +Open a fresh client session at the checkout or consumer root. Codex discovers `.agents/skills/php-forge-coding-standard/` and supports +`$php-forge-coding-standard` or its skill picker. Claude Code uses `.claude/skills/php-forge-coding-standard/` and `/php-forge-coding-standard`. For OpenCode, verify the +installed client's native skill tool and shared paths. Do not assume one client's invocation syntax works in another. + +## Example prompts + +Explicit Codex invocation: + +```text +$php-forge-coding-standard +Prepare ECS and Rector wrappers for a PHP 8.1 consumer using this package. Preserve its src/tests paths and demonstrate dry-run commands; do not upgrade syntax to the host PHP version. +``` + +Natural selection: + +```text +My project supports PHP 8.1 but runs tools on PHP 8.5. Configure its ECS and Rector wrappers using php-forge/coding-standard, preserve src and tests paths, and show non-mutating checks. +``` + +Record whether the client loads this skill rather than a global same-named copy. As an unrelated negative control, ask it to explain HTTP 301 versus 302 without inspecting the +repository or loading package skills. + +## Verify the result + +Capture the native load/tool evidence and selected source path, then execute the generated task checks against the +installed package. Cover the normal operation, the described boundary case and a failure/unsupported input. Inspect +generated code before executing it; use disposable fixtures for writes. Run the package's actual non-mutating checks +and report runtime versions, warnings and unavailable dependencies. Listing, manually reading the skill, or supplying +its body in a prompt does not prove native activation or functional execution. + +[Back to README](../README.md) diff --git a/docs/svgs/features-mobile.svg b/docs/svgs/features-mobile.svg index 26db843..6a1941c 100644 --- a/docs/svgs/features-mobile.svg +++ b/docs/svgs/features-mobile.svg @@ -24,15 +24,15 @@ - Metadata & Linter Standards - .editorconfig, .gitignore, .gitattributes, Prettier, stylelint baselines - Super-Linter configs: actionlint, codespell, gitleaks, markdownlint + Independent Configurations + Shared ECS and Rector rules have no project-specific paths + Choose the target matching the minimum supported PHP version Scaffold Provider - yii2-extensions/scaffold integration distributes files on install - Modes replace, append and preserve protect local edits + Optional scaffold integration distributes wrapper templates + Preserve mode keeps consumer wrapper edits diff --git a/docs/svgs/features.svg b/docs/svgs/features.svg index 2a0aa70..b0cada8 100644 --- a/docs/svgs/features.svg +++ b/docs/svgs/features.svg @@ -25,16 +25,16 @@ - Metadata & Linter Standards - .editorconfig, .gitignore, .gitattributes, Prettier and stylelint baselines - Super-Linter configs: actionlint, codespell, gitleaks, markdownlint + Independent Configurations + Shared ECS and Rector rules have no project-specific paths + Choose the target matching the minimum supported PHP version Scaffold Provider - yii2-extensions/scaffold integration distributes files on install - Modes replace, append and preserve protect local edits + Optional scaffold integration distributes wrapper templates + Preserve mode keeps consumer wrapper edits diff --git a/ecs.php b/ecs.php new file mode 100644 index 0000000..9ff5e15 --- /dev/null +++ b/ecs.php @@ -0,0 +1,35 @@ +withPaths([ + __DIR__ . '/src', + __DIR__ . '/tests', + ]) + // include *.php files in the root directory + ->withRootFiles() + + // add a single rule + ->withRules([ + NoUnusedImportsFixer::class, + ]) + + // add sets - group of rules, from easiest to more complex ones + // uncomment one, apply one, commit, PR, merge and repeat + //->withPreparedSets( + // spaces: true, + // namespaces: true, + // docblocks: true, + // arrays: true, + // comments: true, + //) + + // ...but first: take it step by step + ->withSpacesLevel(0) + ->withArrayLevel(0) + ->withControlStructuresLevel(0) + ->withDocblockLevel(0); diff --git a/skills/php-forge-coding-standard/SKILL.md b/skills/php-forge-coding-standard/SKILL.md new file mode 100644 index 0000000..197975e --- /dev/null +++ b/skills/php-forge-coding-standard/SKILL.md @@ -0,0 +1,32 @@ +--- +name: php-forge-coding-standard +description: Use when selecting PHP Forge ECS and Rector configurations for a supported PHP target. +license: BSD-3-Clause +--- + +# Use php-forge/coding-standard + +## Resolve the package + +Inspect the installed package path, actual source and Composer metadata before choosing APIs. The current PHP constraint +is `>=8.1`. A lockfile or branch alias alone does not prove the installed files match it. Use +local guides at that revision; if a guide is excluded from the archive, consult the matching repository revision, not +unverified current documentation. Installing this skill does not install dependencies or authorize mutations. + +## Package contracts + +Select `src/ecs-81.php` through `ecs-84.php` and the corresponding Rector configuration from the consumer's minimum +supported PHP version, not the interpreter currently running. For other minimum versions, inspect the available sets and explain that no matching wrapper is provided. Plain +`ecs.php` and `rector.php` do not select a migration level. Inspect actual configuration files: an ECS entrypoint returns a builder; the Rector configuration returns a +closure that receives `RectorConfig`. Do not assume interchangeable wrapper shapes. + +Preserve consumer paths and justified skips. Run non-mutating checks first; ECS/Rector fix commands change files. +Do not raise the language target merely to clear a finding. Verify installed ECS/Rector compatibility and the selected +configuration with the consumer's tests. + +## Verify the task + +Run the relevant existing package checks and independent assertions for the selected operation. Read `composer.json` +scripts before executing them: fixers, installers and cleanup commands can mutate files. Use isolated synthetic inputs +for side-effecting behavior. Report the PHP version and missing dependencies. Distinguish native skill discovery, +activation, generated snippets and executed functional results; none substitutes for the others. diff --git a/src/ecs.php b/src/ecs.php index 62fdd6a..ca7b9a8 100644 --- a/src/ecs.php +++ b/src/ecs.php @@ -9,7 +9,7 @@ use PhpCsFixer\Fixer\PhpUnit\PhpUnitTestCaseStaticMethodCallsFixer; use PhpCsFixer\Fixer\Strict\{DeclareStrictTypesFixer, StrictComparisonFixer, StrictParamFixer}; use PhpCsFixer\Fixer\StringNotation\SingleQuoteFixer; -use PhpCsFixer\Fixer\Whitespace\HeredocIndentationFixer; +use PhpCsFixer\Fixer\Whitespace\{HeredocIndentationFixer, NoExtraBlankLinesFixer}; use Symplify\EasyCodingStandard\Config\ECSConfig; return ECSConfig::configure() @@ -86,5 +86,8 @@ ], ) ->withSkip( - [HeredocIndentationFixer::class], + [ + HeredocIndentationFixer::class, + NoExtraBlankLinesFixer::class, + ], ); diff --git a/src/rector.php b/src/rector.php index 99aa40a..e6dc808 100644 --- a/src/rector.php +++ b/src/rector.php @@ -14,7 +14,7 @@ * import either this file (no version target) or one of the version-pinned wrappers (`rector-81.php`, `rector-82.php`, * `rector-83.php`, `rector-84.php`) and set their own paths. * - * The version-pinned wrappers add the matching `SetList::PHP_XX` and `LevelSetList::UP_TO_PHP_XX` on top of this base. + * The version-pinned wrappers add the matching `LevelSetList::UP_TO_PHP_XX` on top of this base. */ return static function (RectorConfig $rectorConfig): void { $rectorConfig->parallel();