stolt / lean-package-validator
Library and CLI for validating if a project or package has and will have lean releases.
Fund package maintenance!
raphaelstolt
Installs: 1 052
Dependents: 8
Suggesters: 0
Security: 0
Stars: 11
Watchers: 4
Forks: 5
Open Issues: 4
Requires
- php: >=8.1
- sebastian/diff: ^6.0.1||^5.0||^4.0.3
- symfony/console: ^7.1.0||^v5.4.8
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.0
- mockery/mockery: ^1.0
- phlak/semver: ^4.1
- php-mock/php-mock-phpunit: ^2.7||^1.1
- phpstan/phpstan: ^1.11
- phpunit/phpunit: ^11.2.6||^10.5.25
- zenstruck/console-test: ^1.6
- dev-main
- v4.0.5
- v4.0.4
- v4.0.3
- v4.0.2
- v4.0.1
- v4.0.0
- v3.3.2
- v3.3.1
- v3.3.0
- v3.2.0
- v3.1.1
- v3.1.0
- v3.0.1
- v3.0.0
- v2.0.2
- v2.0.1
- v2.0.0
- v1.9.0
- v1.8.1
- v1.8.0
- v1.7.3
- v1.7.2
- v1.7.1
- v1.7.0
- v1.6.0
- v1.5.2
- v1.5.1
- v1.5.0
- v1.4.0
- v1.3.1
- v1.3.0
- v1.2.0
- v1.1.0
- v1.0.6
- v1.0.5
- v1.0.4
- v1.0.3
- v1.0.2
- v1.0.1
- v1.0.0
- dev-dependabot/composer/phlak/semver-tw-4.1or-tw-6.0
This package is auto-updated.
Last update: 2024-11-07 12:39:52 UTC
README
The lean package validator is a utility tool that validates a project/micro-package
for its leanness
. A project/micro-package is considered lean
when its common
repository artifacts won't be included in release assets.
Installation
The lean package validator CLI can be installed globally through Composer.
composer global require stolt/lean-package-validator
Make sure that the path to your global vendor binaries directory is in your $PATH
.
You can determine the location of your global vendor binaries directory via
composer global config bin-dir --absolute
. This way the lean-package-validator
executable can be located.
Since the default name of the CLI is quite a mouthful, an alias which can be placed
in ~/.aliases
, ~/.zshrc
or the like might come in handy. The alias shown next
assumes that $COMPOSER_HOME
is ~/.config/composer
and not ~/.composer
.
alias lpv='~/.config/composer/vendor/bin/lean-package-validator $@'
The lean package validator also can be installed locally to a project which allows further utilisation via Composer scripts.
composer require --dev stolt/lean-package-validator
A third option to use the lean package validator is via cpx.
cpx stolt/lean-package-validator validate
Tip
As of release v1.9.0
it's also possible to install and use the lean package validator
via a PHAR file.
Therefor download a released version e.g. v3.3.1 and move it to /usr/local/bin
as shown next.
wget --quiet https://github.com/raphaelstolt/lean-package-validator/releases/download/v3.3.1/lean-package-validator.phar mv lean-package-validator.phar /usr/local/bin/lean-package-validator
Usage
Run the lean package validator CLI within or against a project/micro-package
directory, and it will validate the export-ignore entries present in
a .gitattributes
file against a set of common repository artifacts. If no
.gitattributes
file is present it will suggest to create one.
lean-package-validator validate [<directory>]
Available options
The --enforce-strict-order
option will enforce a strict order comparison
of export-ignores in the .gitattributes
file and fail validation if the order
differs. Per default the order comparison is done in a non-strict fashion.
lean-package-validator validate [<directory>] --enforce-strict-order
The --create|-c
option creates an .gitattributes
file if nonexistent.
lean-package-validator validate [<directory>] --create
The --overwrite|-o
option overwrites an existing .gitattributes
file when
there are any export-ignore
entries missing. Using this option on a directory
with a nonexistent .gitattributes
file implicates the --create
option.
lean-package-validator validate [<directory>] --overwrite
The --glob-pattern
option allows you to overwrite the default pattern used
to match common repository artifacts. The amount of pattern in the grouping
braces is expected to be >1
. As shown next this utility could thereby also
be used for projects (i.e. Python) outside the PHP ecosystem.
lean-package-validator validate [<directory>] --glob-pattern '{.*,*.rst,*.py[cod],dist/}'
The default pattern is defined in the PHP preset file.
The --glob-pattern-file
option allows you to load patterns, which should
be used to match the common repository artifacts, from a given file. You
can put a .lpv
file in the repository which will be used per default and
overwrite the default pattern. The structure of such a glob pattern file
can be taken from the example directory or be created
via lean-package-validator init
.
lean-package-validator validate [<directory>] --glob-pattern-file /path/to/glob-pattern-file
The --keep-license
option will allow a license file in the release/dist archive file which is per default ommitted.
lean-package-validator validate [<directory>] --keep-license
The --align-export-ignores|-a
option will align the created or overwritten export-ignores for a better readability.
lean-package-validator validate [<directory>] --align-export-ignores --create
The --enforce-alignment
option will enforce a strict alignment of export-ignores
in the .gitattributes
file and fail validation if they aren't aligned. Per default
no alignment is enforced.
The --validate-git-archive
option will validate that no common repository artifacts slip
into the release/dist archive file. It will do so by creating a temporary archive
from the
current Git HEAD
and inspecting its content. With a set --keep-license
option a license
file becomes mandatory and will fail the archive validation if not present.
lean-package-validator validate [<directory>] --validate-git-archive
The --diff
option will show a visual diff between the actual and expected .gitattributes
content.
lean-package-validator validate --diff The present .gitattributes file is considered invalid. Would expect the following .gitattributes file content: --- Original +++ Expected @@ -7,9 +7,8 @@ .github/ export-ignore .gitignore export-ignore .gitmessage export-ignore .php-cs-fixer.php export-ignore -.phpunit.result.cache export-ignore +.idea/ export-ignore bin/application-version export-ignore bin/lean-package-validator.phar export-ignore bin/release-version export-ignore
The --report-stale-export-ignores
option extends the validation to look for export-ignore statements referencing non-existent
repository artifacts. In combination with the --diff
option these will be shown in the output.
Additional commands
The init
command will create an initial .lpv
file with the default patterns used to match common repository artifacts.
lean-package-validator init [<directory>]
The --overwrite|-o
option overwrites an existing .lpv
file.
The --preset
option allows to choose from a predefined set of glob pattern.
Available presets are PHP
, Python
, and Go
. With PHP
being the default.
Utilisation via Composer scripts or it's dedicated GitHub Action
To avoid that changes coming from contributions or own modifications slip into release/dist archives it might be helpful to use a guarding Composer script, which will be available at everyone's fingertips.
By adding the following to the project/micro-package its composer.json
the .gitattributes
file can
now be easily validated via composer validate-gitattributes
.
{ "scripts": { "validate-gitattributes": "lean-package-validator validate" }, }
For utilising a dedicated GitHub Action have a look at the documentation over here.
Running tests
composer lpv:test
License
This library and its CLI are licensed under the MIT license. Please see LICENSE.md for more details.
Changelog
Please see CHANGELOG.md for more details.
Contributing
Please see CONTRIBUTING.md for more details.