Repository navigation
Prepare 0.4.0 - #38
Merged
Merged
Conversation
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).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.error,warnandoff, withtrue/falseas aliases. Warnings never fail the build. The baseline reports stale entries, and--fail-on-staleturns them into a failure (ADR 0015).depends_onbut no longer closes a cycle. Both are configurable (ADR 0016).hostmodule: code outside the modules (app,routes,databaseby default) is analysed, and its use of module internals is reported as ahost_accesswarning (ADR 0017, closes Optionalhostmodule for code outside modules #25).config/cordon.phpstopscordon:verifywith exit code 2 and a suggestion (ADR 0019).layers,strictmodules,@cordon-ignorewith a reason,unused_dependency,public_api_leak, thecordon:explain,why,impactandgraphcommands, andverify <paths>(ADR 0020).layersreports 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).cordon:verifyresolves 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.3constraint will not pick it up without asking.Verification.
--prefer-lowest(707 passed, 8 skipped). Pint, PHPStan and the docs build pass.host, and the case studies page now says so.Not covered: the
v0.4.0tag and the release are created after this is merged, so the@v0.4.0examples resolve only from then on.