Skip to content

Prepare 0.4.0 - #38

Merged
ChrisAbner merged 63 commits into
mainfrom
release/0.4.0
Nov 11, 2026
Merged

ChrisAbner merged 63 commits into
mainfrom
release/0.4.0

Conversation

@ChrisAbner

Copy link
Copy Markdown
Owner

Brings 0.4.0 to main: the model that 1.0 will freeze. The changelog has the full list, and UPGRADE.md covers what breaks.

  • Rule severities error, warn and off, with true/false as aliases. Warnings never fail the build. The baseline reports stale entries, and --fail-on-stale turns them into a failure (ADR 0015).
  • Listener edges: listening to another module's event counts for depends_on but no longer closes a cycle. Both are configurable (ADR 0016).
  • The host module: code outside the modules (app, routes, database by default) is analysed, and its use of module internals is reported as a host_access warning (ADR 0017, closes Optional host module for code outside modules #25).
  • A versioned JSON report, plus GitLab Code Quality, JUnit and Checkstyle output (ADR 0018).
  • Strict config validation: a typo in config/cordon.php stops cordon:verify with exit code 2 and a suggestion (ADR 0019).
  • layers, strict modules, @cordon-ignore with a reason, unused_dependency, public_api_leak, the cordon:explain, why, impact and graph commands, and verify <paths> (ADR 0020).
  • layers reports one violation per file and class, and names the class. This is so the baseline cannot hide a new class from an upper layer (ADR 0014).
  • Fixes cordon:verify resolves the modules and loads the baseline twice #20 (modules and baseline loaded twice) and Messages from the core still name artisan commands #23 (core messages naming artisan commands).

It is a minor version with breaking changes, as the changelog allows before 1.0. A ^0.3 constraint will not pick it up without asking.

Verification.

  • The suite passes on PHP 8.4 (714 tests, 1 known warning from Test suite warns when PHPStan's cache is cold #21) and on PHP 8.2 with --prefer-lowest (707 passed, 8 skipped). Pint, PHPStan and the docs build pass.
  • The extractor is checked against a matrix of 1,818 positions, metamorphic relations and reflection. Mutation testing was used on the core: surviving mutants went from about 253 to 91, and all 91 left are equivalent or unreachable.
  • On the three case studies (Bagisto, Advising App, LaravelEcomm), at the same commits and with the same configs, 0.4.0 reports exactly the same errors as 0.3.1. The new warnings come from host, and the case studies page now says so.

Not covered: the v0.4.0 tag and the release are created after this is merged, so the @v0.4.0 examples resolve only from then on.

php-parser parses property hooks since 5.2.0 and resolves the names inside
them since 5.3.0. With ^5.0, a project on 5.0 or 5.1 skipped files with hooks
as parse errors, and one on 5.2 lost the types of hook parameters. Both were
silent unless --fail-on-parse-error was passed.

Also adds a CI row with the lowest dependencies, and a local Docker image
for running the suite against one PHP version.
…n core messages

Verifier resolved the modules again for the configuration warnings, and read
the baseline file once per call. Both are now memoized; pruning refreshes the
memoized baseline. Closes #20.

The outdated baseline warning and the header of the generated docs no longer
say php artisan, since vendor/bin/cordon runs them too. Closes #23.
A misspelled key was ignored: with depend_on instead of depends_on the module
was left open and CI stayed green. config/cordon.php is now validated before
anything is analysed. Unknown keys, unknown modules or dependencies, and
settings of the wrong type stop cordon:verify with exit code 2, with a
suggestion for the closest valid name. cordon:modules shows the same errors
as warnings, and the PHPStan rule reports them as cordon.configuration.

Module::Interface in depends_on is reserved for named interfaces, and each
module may carry a free-form metadata array.
Each rule in config/cordon.php takes error, warn or off; true and false keep
working as error and off. Violations of a rule in warn are reported apart
from the errors (Result::$warnings): they never fail cordon:verify, the Pest
expectation or the exit code, and --generate-baseline leaves them out. The
text, JSON and GitHub reports show them, each violation now carries its
severity, and the PHPStan rule reports only in error.

Custom rules take a severity when their class is the key. An unknown rule
id, which used to be ignored and leave the rule on, is now a configuration
error, like an invalid severity.
…default

A module that publishes an event does not depend on who listens to it, yet a
listener's reference to the event closed a cycle: two modules talking through
a contract one way and an event the other were reported as tangled.

References now have a kind. The type of the first parameter of handle() or
__invoke(), when the class sits under an Events namespace, and the event of
Event::listen() are listener references; anything else, including a service
a job injects into handle(), is a use. Listener edges do not close cycles and
still count for depends_on. The new listeners config switches both.

The event inventory of cordon:docs shares the same signature detection.
The stale baseline count was only a notice, so fixed violations could stay in
the baseline and hide a regression later. With --fail-on-stale a stale entry
fails cordon:verify and every one is listed with the occurrences it records
and the ones the code still has. As PHPStan does with its baseline, the check
is skipped (and says so) when a file did not parse, since its occurrences are
missing. It cannot be combined with --no-baseline.
The JSON report starts with "version": 1 and is described by
resources/schemas/report-v1.schema.json, which the tests validate it against.
Every object in the schema is closed, so a new field needs a new version, and
scripts and agents can rely on the shape. The Boost skill explains the
version, the warnings and the severity of each entry.

The local Docker image is left out of the package.
Every class, interface and enum in src/ now says whether users may rely on
it. The @api surface is what custom rules and tests need: the Rule contract,
the analysis context and its edges, references, declarations and violations,
modules, the severities, the attributes and the Pest helper. ModuleResolver,
DependencyExtractor and Reporter stay internal until they are opened as
extension points. A test keeps the list and the tags in step.
The changelog for 0.4.0, with what may report different violations, an
UPGRADE.md from 0.3, and a compatibility page that lists what 1.0 will freeze,
what is never covered and how new checks arrive. The configuration guide
covers severities, listeners, metadata and the validation; the CI guide has a
table of exit codes. SECURITY.md and the README status are up to date.
…Pest, and recognise more listeners

- --module dropped every warning, so a team checking its own module never saw
  the rules it had set to warn.
- A rule moved to warn made its baseline entries look stale: --fail-on-stale
  failed and --prune-baseline removed debt that was still in the code.
  Warnings now count as found.
- toRespectBoundaries() did not validate the config, so a typo such as
  depend_on passed where cordon:verify exits with 2. It now fails with the
  same errors (Cordon::configurationErrors()).
- Listeners that still closed cycles are recognised: the handled event in a
  listener's other methods (failed()), the $listen map of an
  EventServiceProvider, and closures passed to Event::listen().
The test suite cannot run with the lowest php-parser composer.json allows,
because the dev dependencies require a newer one. A parser-floor job installs
Cordon alone at its minimums and checks that property hooks are analysed.
The config, modules, public API, baseline, severities and tracked files the
PHPStan rule read in boot() move to a CordonContext service, so the rules for
undeclared dependencies and cycles can use the same setup. The parity test
between the CLI and PHPStan now compares the kind of each reference too.
Editors run PHPStan on the buffer as a temporary file outside the project
(--tmp-file with --instead-of), so its path matched no module and the file
being edited never got its violations. The module now comes from the first
class the file declares, excluded directories are checked against that
class's namespace, and the baseline is matched against the real path, found
as the one file of the module named after the class.
undeclared_dependency only needs the module map and the module's depends_on,
so it runs per file in PHPStan like internal_access: same message and
baseline keys as cordon:verify, the listeners.depends_on setting, only in
error, and the identifier cordon.undeclaredDependency with a tip that links
to the rule's documentation.
Editor mode arrived in PHPStan 2.1.17, and the lowest dependencies install
2.1.3.
Cycles need the whole graph, so a collector gathers the modules each file
references and a rule on the collected data finds the cycles, with the same
algorithm as cordon:verify (now CycleFinder). Each cycle is reported at the
first reference of its dependency, with the identifier cordon.cycle, the
listeners.cycles setting and the Cordon baseline. When some modules were not
analysed it says so (cordon.incompleteGraph) instead of guessing, and it does
nothing when PHPStan analyses only some files.

A parity test runs PHPStan on two fixture apps and expects the same findings
as cordon:verify for the three rules.
cordon:verify takes files and directories. The whole project is still
analysed, so cycles and the baseline are checked as usual, but only the
violations of those paths are reported, plus the cycles their modules take
part in. Relative paths are read from the project root; a missing path exits
with 2, and paths cannot be combined with writing the baseline. A recipe
shows a plain git hook, CaptainHook and GrumPHP.
Every Cordon error in PHPStan ends with a link to its rule in the guide, and
a test checks that the anchor exists. The PHPStan guide covers the three
rules, how cycles work with collectors, editor mode and the limits; the CI
guide covers verify with paths.
- Editor mode now reads the real path PHPStan was given for the temporary
  buffer instead of guessing it from the class the file declares. Excluded
  directories in lower case are skipped again, files without a class (routes,
  migrations) are reported, and the baseline applies even when a module has
  two files with the same name. Outside editor mode, a file belongs to the
  module of its path, as in cordon:verify.
- The cycles rule tracks the directories of the modules it checks, so with
  bleedingEdge a file appearing in a module PHPStan does not analyse brings
  back cordon.incompleteGraph.
- cordon.incompleteGraph and cordon.configuration link to the PHPStan guide.
- The docs said cycles were not reported in the editor; they are, since
  editor mode analyses the whole project. The README and the compatibility
  page list the new identifiers, the changelog has a note for current users
  of the extension, and the pre-commit recipe handles renamed files, spaces
  and projects in a subdirectory.
- The parity test also compares the target of each finding, and the tests
  that run PHPStan use one process.
…o its rule

Adding an optional field to the JSON report keeps version 1, so the schema
now accepts fields it does not list and only requires the fields of version 1.
Each violation carries docs_url, the documentation of its rule (null for
custom rules).
unused_dependency reports a depends_on entry no reference uses, so the config
keeps showing the real dependencies. It is a new check, so it warns by
default (built-in rules can now start below error). Listening to a module's
event counts as using it unless listeners.depends_on is false. The target is
"Module -> Dependency", so two modules with the same unused entry get
different baseline keys.
--format=gitlab writes Code Quality issues (errors major, warnings minor)
whose fingerprint is the baseline key plus the occurrence number, so it stays
when the code above moves. --format=junit has a test case per module that
fails with its errors, warnings in the output. --format=checkstyle groups the
violations by file. Violations without a file, such as cycles, are reported
at config/cordon.php.
cordon:explain <class> tells which module a class belongs to, whether other
modules may use it and why (an attribute, an open module, a public namespace
or the public setting), and who uses it. cordon:why <from> <to> lists the
references behind a dependency and whether depends_on allows it.
cordon:impact <module> lists the modules that depend on it, directly or
through others. All three take --format=json and run from vendor/bin/cordon.
cordon:graph prints the module dependency graph: Mermaid by default, DOT for
Graphviz, or JSON with the references, kinds and violations of each
dependency. Dependencies with violations are marked, listener-only ones are
dashed in DOT, and --module keeps one module and its neighbours. The Mermaid
diagram is the one cordon:docs draws, now in GraphExporter.
An Eloquent relation to another module's model ($this->belongsTo(X::class),
hasMany, morphToMany and their siblings) ties the two modules' tables
together, which depending on a contract does not undo. References now carry
a relation flag, and an internal_access on such a model links to the recipe
for cross-module relations, in cordon:verify and in PHPStan. Calls on
anything but $this, imports and docblocks are not relations.
Each canvas of cordon:docs lists the module's classes by role: models,
controllers, commands, jobs, listeners, events, policies, notifications, mail
and the rest. A known Laravel parent class decides first, then a namespace
segment, then ShouldQueue for jobs, so a queued listener stays a listener.
The description and owner of the module's metadata appear at the top.
Class declarations now record their parent class and interfaces, and modules
their metadata.
- cordon:docs takes a component's role from its name inside the module,
  follows parent classes declared in the project, knows pivots and the
  app's base controller, and escapes pipes in the owner.
- cordon:why gives the reason cordon:verify would: reported, in the
  baseline, rule off, or only listeners that depends_on does not count.
- cordon:explain marks the uses verify reports, after severity and baseline.
- explain, why, impact and graph reject unknown formats and write errors
  to stderr, so JSON output stays JSON.
- cordon:graph labels Mermaid with references, like DOT and JSON, and
  dots listener-only dependencies.
- JUnit lists only the checked modules and counts failing test cases; the
  CI formats report files that do not parse.
- Paths outside the project root are written with ../, so baselines and
  fingerprints do not depend on the machine.
- unused_dependency says nothing about a module with a file that does not
  parse; AnalysisContext carries the parse errors.
The metamorphic tests found it: with class names lowercased, a listener's
event was counted as a plain use (closing a false cycle) and #[PublicApi]
or #[Internal] were not recognised. A listener's failed() also lost its
signature when it became a listener reference.
- Tests and oracles remove their temporary files and directories when the
  process ends (tests/Oracle/Temp.php), also in the older PHPStan and
  feature tests that copied projects.
- The oracle tests that start a process per cell or mutation, and the
  PHPStan parity on the real projects, are in the oracle group: composer
  oracle and CI run them, composer test does not (32 s instead of 52 s).
- check-matrix.php and reflection.php fail when they check nothing.
- The metamorphic and determinism tests require non-empty projects; the
  calibration test checks the generator's hash.
- References are sorted with strcmp; the Pest docs say how parse errors
  and cycles show up.
Declare mutates(IgnoreDirectives::class) and cover the statement-range scan,
the trailing-comment detection and the comment filtering. Survivors 37 -> 8,
score 71.3% -> 93.8%.

The 8 left are equivalent: the early return when the text does not mention
the directive (the pattern would not match anyway), the string cast and the
inner trim before the pattern (the outer trim covers it), the loop bound and
the final return of followsCode (token 0 is always an open tag or inline
HTML and returns first), the unreachable non-array branch for the comment
line, and slicing from the comment itself (it is skipped).
Add a dedicated test that extracts snippets and checks the declarations,
the owner of each reference, Eloquent relations, listener events (also
nested in anonymous or local classes), Event::listen closures and the
public-signature marks. A warning in the collector now fails the test.
Survivors 42 -> 24, score 83.5% -> 90.6%.

Of the 24 left, 11 are not reachable by the tool: the RELATIONS constant
and the match header are not tracked by pcov, although every relation
name is covered by a dataset. The other 13 are equivalent: array_values
over a list, the implicit creation of the events key, the early returns
after nodes that no later check matches, the re-marking of the handled
event when the class closes, the true value in the events map (isset),
the dynamic call name marked as skipped, the parameter name guards (a
parameter variable is always a Variable), the array cast of a stack pop
and the ltrim of a resolved attribute name.
Add a dedicated test over synthetic results: the modules and cycles a
filter keeps, the checked modules, the ignore fields, path matching
(trailing slashes, siblings with the same prefix, symbolic links) and a
check that the filter raises no notice. Survivors 29 -> 0, score 100%.
Add a dedicated test that builds file analyses with directives: which
violations a directive takes out, the unused and invalid directives, the
messages and their order by file and line. Survivors 21 -> 4, score
96.5%.

The 4 left: the rules-without-line constant is not tracked by pcov (both
entries are covered by a dataset), and two are equivalent: a used flag
stored as false is still set for isset(), and a directive with no rule
marked valid has nothing to match or report.
Add a dedicated test over parsed snippets: handle() and __invoke() event
types (union, intersection, nullable, scalar), the Event::listen closure,
class and array forms, and the $listen map of an EventServiceProvider. A
notice in the reader (a property a node does not have) now fails the
test. Survivors 23 -> 1, score 99%. The one left, the match header, is
not tracked by pcov.
Cover the reason of every branch, the default public namespaces, entries
written with surrounding backslashes, whole-segment matching of the
per-module list and empty entries. A notice in the policy now fails the
test. Survivors 15 -> 6, score 76.5% -> 92.9%.

The 6 left: the default namespaces array is a constructor default that
pcov does not track (every entry is covered by a dataset), and one is
equivalent: an empty prefix never matches in either spelling of the check.
Add a dedicated test over module graphs: rings, tangled groups, separate
components, the shortest way back, dependencies on modules outside the
graph and numeric module names (PHP turns them into integer keys).
Survivors 12 -> 12, score 84.6%, none of them reachable.

All 12 are equivalent or dead code: the starting index of Tarjan's
algorithm, flags stored as false (read with isset), the string casts of
values that are already strings or are used as array keys, the visited
set of the breadth-first search (it only prunes paths that cannot be
shorter), and the unreachable fallback return.
Add a dedicated test: the listener flags of each rule (observed through
what the rules report), custom rules set to off, severities with
defaults and overrides, the errors of malformed entries and the layers
config. A notice in the rule set now fails the test. Survivors 24 -> 18,
score 84.7%.

Of the 18 left, 10 are the BUILT_IN and DEFAULTS constants, which pcov
does not track (the exact list is asserted in an error message). The 8
others are equivalent: flags stored as false and read with isset, string
casts of keys that are already strings, entry keys that are never read
for the entries that lack them, and array_values over a foreach.
Add a dedicated unit test over a synthetic context: the message and the
location of a leak, one report per file and internal class, and each
reason for not reporting (no class, class outside the modules, no
signature, target in another module or outside the modules, internal
source, public target), also through #[Internal] and #[PublicApi]. A
notice in the rule now fails the test. Survivors 9 -> 4, score 83.3%.

The 4 left are equivalent: the key of the reported set only has to be
unique per file and class (a file name ends in .php, which no class name
contains), and a flag stored as false is still read by isset().
Declare mutates(LayerRule::class) and cover the default for listeners,
a module listed in several layers (the first wins) and the one report per
file and target module. Survivors 9 -> 4, score 69.0% -> 86.2%.

The 4 left are equivalent: the key of the reported set only has to be
unique per file and module (a file name ends in .php, which no module
name contains), and a flag stored as false is still read by isset().
Add a dedicated unit test over host edges: the message and location of a
violation, public API left alone, one report per file and class, and the
relation hint only for the file and class that use a relation. Survivors
18 -> 2, score 28% -> 92%.

The 2 left are equivalent: flags stored as false are still read by isset().
Add a dedicated unit test: the exact message and location, the relation
hint only for the class used as the model of a relation, public classes
left alone and one report per file and class. Survivors 5 -> 2 (on the
measured tests), score 92%.

The 2 left are equivalent: flags stored as false are still read by isset().
Add a dedicated unit test: the message and location, listed and
undeclared dependencies, one report per file and module, and the
listener flag. Survivors 5 -> 4, score 72.2% -> 77.8%.

The 4 left are equivalent: the key of the reported set only has to be
unique per file and module (a file name ends in .php, which no module
name contains), and a flag stored as false is still read by isset().
layers reported one violation per file and target module, so once a
file was in the baseline for Services -> Http, any new Http class used
by that file stayed suppressed, and the message did not name the class.
Report per file and class like internal_access, with the class as the
target and in the message (ADR 0014).
@ChrisAbner
ChrisAbner merged commit 7ae9613 into main Nov 11, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Optional host module for code outside modules cordon:verify resolves the modules and loads the baseline twice

1 participant