README

The lean package validator or its abbreviation lpv 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.

It can also create and update the leanness enforcing export-ignore entries of a .gitattributes file.

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

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 --enforce-strict-order [<directory>]

The --create|-c option creates an .gitattributes file if nonexistent.

lean-package-validator validate --create [<directory>]

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 --overwrite [<directory>]

Warning

As of release v5.0 the --create and --overwrite options are deprecated and will be removed in the next major release. Please migrate to the dedicated commands create and update.

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 --glob-pattern '{.*,*.rst,*.py[cod],dist/}' [<directory>]

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 --glob-pattern-file /path/to/glob-pattern-file [<directory>]

The --keep-license option will allow a license file in the release/dist archive file which is per default ommitted.

lean-package-validator validate --keep-license [<directory>]

The --keep-readme option will allow a README file in the release/dist archive file which is per default ommitted.

lean-package-validator validate --keep-readme [<directory>]

The --keep-glob-pattern option allows to keep matching files in the release/dist archive file which are per default ommitted.

lean-package-validator validate --keep-glob-pattern '{LICENSE.*,README.*,docs*}' [<directory>]

The --align-export-ignores|-a option will align the created or overwritten export-ignores for a better readability.

lean-package-validator validate --align-export-ignores --create [<directory>]

The --sort-from-directories-to-files|-s option will order the export-ignores from directories to files for a better readability.

lean-package-validator validate --sort-from-directories-to-files --create [<directory>]

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 --preset=[<preset>] option will use a predefined set of glob pattern. Available presets are PHP, Python, Rust, JavaScript, and Go. With PHP being the default.

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 --validate-git-archive [<directory>]

The --diff option will show a visual diff between the actual and expected .gitattributes content.

lean-package-validator validate --diff [<directory>]

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.

The --stdin-input option allows the validate command to read from STDIN, so that the following piped output can be used for validation. It currently only does a strict comparison.

cat .gitattributes | lean-package-validator validate --stdin-input

Additional commands

Create command

The create command will create a .gitattributes file in the given directory. This command replaces the --create option of the validate command. Please migrate to the dedicated commands.

Update command

The update command will update a present .gitattributes file in the given directory. This command replaces the --overwrite option of the validate command. Please migrate to the dedicated commands. Like the above-mentioned create command it provides a --dry-run option to see what the .gitattributes content would look like.

Init command

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 choosing from a predefined set of glob pattern. Available presets are PHP, Python, Rust, JavaScript, and Go. With PHP being the default.

The --dry-run option will show the content of the .lpv file that would be created.

Tree command

The tree command of the lean package validator allows you to inspect the flat source and dist package structure of the given project/micro-package. It is not intended for validation use.

lean-package-validator tree --src [<directory>]

Package: stolt/lean-package-validator
.
├── bin
├── example
├── .github
├── src
├── tests
├── box.json.dist
├── CHANGELOG.md
├── composer.json
├── composer.lock
├── .editorconfig
├── .gitattributes
├── .gitignore
├── .gitmessage
├── LICENSE.md
├── llms.txt
├── lpv-logo.png
├── peck.json
├── .php-cs-fixer.php
├── phpstan.neon.dist
├── phpunit.xml.dist
└── README.md

5 directories, 15 files

lean-package-validator tree --dist-package [<directory>]

Package: stolt/lean-package-validator
.
├── bin
├── composer.json
└── src

2 directories, 1 file

Utilisation via Composer scripts, cpx, 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"
    },
}

Another option to utilise the lean package validator is via cpx.

cpx stolt/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.