Make the toolchain work, and the docs match it

.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        # The floor this package declares, and current stable. Consumers sit on both.
+        php: ['7.4', '8.3']
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+
+      - uses: ramsey/composer-install@v3
+
+      - run: composer cs
+
+      - run: composer analyze
+
+      - run: composer test

.github/workflows/upstream-check.yml

@@ -0,0 +1,81 @@
+name: Upstream check
+
+# The failure a stubs package actually has is staleness: the plugin ships a new release, this package
+# does not, and nobody finds out until a consumer's static analysis reports a symbol that should
+# exist. Nothing here looks broken in the meantime, which is why it needs a schedule rather than a
+# reviewer.
+
+on:
+  schedule:
+    # Mondays, 06:00 UTC.
+    - cron: '0 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  compare:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Compare the latest release against the latest tag
+        id: compare
+        run: |
+          set -euo pipefail
+
+          latest="$(
+            curl -fsSL "https://api.wordpress.org/plugins/info/1.0/fluentform.json" \
+              | php -r 'echo json_decode(file_get_contents("php://stdin"), true)["version"] ?? "";'
+          )"
+
+          tagged="$(git tag --sort=-v:refname | head -n1 | sed 's/^v//')"
+
+          # Validated before either value goes near a later step. One comes from a public API and the
+          # other from a tag, and a version string is the only shape that should reach an issue body.
+          for v in "$latest" "$tagged"; do
+            if ! printf '%s' "$v" | grep -qE '^[0-9]+(\.[0-9]+)*$'; then
+              echo "ERROR: refusing to act on a version that is not numeric: '$v'" >&2
+              exit 1
+            fi
+          done
+
+          echo "latest=$latest" >> "$GITHUB_OUTPUT"
+          echo "tagged=$tagged" >> "$GITHUB_OUTPUT"
+          echo "stale=$( [ "$latest" = "$tagged" ] && echo false || echo true )" >> "$GITHUB_OUTPUT"
+
+          echo "tagged $tagged, latest $latest"
+
+      - name: Open an issue when a newer release exists
+        if: steps.compare.outputs.stale == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          LATEST: ${{ steps.compare.outputs.latest }}
+          TAGGED: ${{ steps.compare.outputs.tagged }}
+        run: |
+          set -euo pipefail
+
+          title="fluentform ${LATEST} is out (stubs tagged ${TAGGED})"
+
+          # Reuse an open issue rather than filing one every Monday until somebody acts.
+          if gh issue list --state open --search "$title" --json title --jq '.[].title' | grep -Fxq "$title"; then
+            echo "already reported"
+            exit 0
+          fi
+
+          gh issue create \
+            --title "$title" \
+            --body "$(printf '%s\n' \
+              "WordPress.org lists **${LATEST}**; the newest tag here is **${TAGGED}**." \
+              "" \
+              "Regenerate and release:" \
+              "" \
+              '```bash' \
+              "composer release" \
+              '```' \
+            )"

.gitignore

@@ -4,3 +4,7 @@
 .DS_Store
 /.idea/
 /.vscode/
+
+# PHPUnit
+.phpunit.result.cache
+coverage/

CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to this package are documented here.
+
+**Versions track the upstream plugin.** A release of this package stubs the matching upstream
+release, so you can require the same version you run against. That is also why the entries below are
+mostly "regenerated against X" — the stubs have no behaviour of their own to change.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Added
+
+- `tests/StubsTest.php` and `phpunit.xml.dist`, so `composer test` runs. It asserts every generated
+  stub file parses and actually declares something — the two ways a regeneration fails silently.
+- `phpcs.xml.dist`, so `composer cs` and `composer cs-fix` have a ruleset. Generated `.stub` files
+  and `source/` are excluded; only the PHP written by hand here is checked.
+- CI on push and pull request across PHP 7.4 and 8.3, running `cs`, `analyze` and `test`.
+- This changelog.
+
+### Fixed
+
+- `composer test`, `composer cs` and `composer check` all failed: `phpunit` had no configuration and
+  `phpcs` had no ruleset.
+- `composer analyze` reported errors that are inherent to stubs. The generated files were in
+  PHPStan's `paths`, which asks it to check the bodies of declarations that are empty by definition.
+  They are `scanFiles` now — the symbols become known without any claim about bodies a stub cannot
+  have — and `paths` covers the hand-written PHP instead.
+
+## [6.2.12] - 2026-08-16
+
+Regenerated against upstream 6.2.12.
+
+## [6.2.10] - 2026-08-16
+
+Regenerated against upstream 6.2.10.
+
+## [6.2.9] - 2026-08-16
+
+Regenerated against upstream 6.2.9.
+
+## [6.2.7] - 2026-08-16
+
+Regenerated against upstream 6.2.7.
+
+## [6.2.6] - 2026-08-16
+
+Regenerated against upstream 6.2.6.
+
+## [6.2.5] - 2026-06-15
+
+Regenerated against upstream 6.2.5.
+
+## [6.2.4] - 2026-05-27
+
+Regenerated against upstream 6.2.4.
+
+## [6.2.3] - 2026-05-27
+
+Regenerated against upstream 6.2.3.
+
+## [6.2.2] - 2026-05-27
+
+Regenerated against upstream 6.2.2.
+
+## [6.2.1] - 2026-05-27
+
+Regenerated against upstream 6.2.1.
+
+## [6.2.0] - 2026-05-27
+
+Regenerated against upstream 6.2.0.
+
+## [6.1.21] - 2026-05-27
+
+Regenerated against upstream 6.1.21.

phpcs.xml.dist

@@ -0,0 +1,23 @@
+<?xml version="1.0"?>
+<ruleset name="fluent-forms-stubs">
+    <description>Coding standards for the files this repository writes by hand.</description>
+
+    <file>bin</file>
+    <file>configs</file>
+    <file>tests</file>
+
+    <!--
+        The .stub files are generated by php-stubs/generator and rewritten wholesale by
+        `composer generate`, so linting them would report on output nobody edits. source/ is the
+        upstream copy, and vendor/ is not ours either.
+    -->
+    <exclude-pattern>*/source/*</exclude-pattern>
+    <exclude-pattern>*/vendor/*</exclude-pattern>
+    <exclude-pattern>*.stub</exclude-pattern>
+
+    <arg name="extensions" value="php"/>
+    <arg name="colors"/>
+    <arg value="ps"/>
+
+    <rule ref="PSR12"/>
+</ruleset>

phpstan.neon

@@ -1,14 +1,24 @@
 parameters:
+    level: 5
+
+    # The hand-written PHP, which is all this repository actually authors.
     paths:
-        - fluent-forms-stubs.stub
+        - configs
+        - tests
+
+    # The stubs are SCANNED, not analysed.
+    #
+    # They used to sit in `paths`, which asks PHPStan to check the bodies of declarations that are
+    # empty by definition -- "should return string but return statement is missing" for every one,
+    # plus unknown-class errors for whatever WordPress internals upstream touches. None of it is a
+    # defect in this package, and PHPStan 2.x classifies several of those as non-ignorable, so
+    # neither an ignoreErrors pattern nor a baseline can hold them.
+    #
+    # Scanning makes the symbols known without asserting anything about their bodies, which is the
+    # only claim a generated stub can honour. What the stubs are checked FOR -- that they parse, and
+    # that they declare something -- is tests/StubsTest.php.
     scanFiles:
         - fluent-forms-constants-stubs.stub
+        - fluent-forms-stubs.stub
     bootstrapFiles:
         - configs/bootstrap.php
-    level: 5
-    ignoreErrors:
-        - '#but return statement is missing\.$#'
-        - '#has an unused parameter#'
-        - '#^(Property|Static property|Method|Static method) \S+ is unused\.$#'
-        - '#is never read, only written\.$#'
-        - '#has invalid (return )?type (WP_Error|WP_Customize_Manager|WP_Theme|WP_User|WP_Site|WP_Upgrader)#'

phpunit.xml.dist

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.6/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+         failOnWarning="true"
+         failOnRisky="true">
+    <testsuites>
+        <testsuite name="stubs">
+            <directory suffix="Test.php">tests</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>