stolt/lean-package-validator

Library and CLI for validating if a project or package has and will have lean releases.

Lean package validator

, _(*1)

, _(*2)

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., _(*3)

Installation

The lean package validator CLI can be installed globally through Composer., _(*4)

``` bash composer global require stolt/lean-package-validator, <sub>(*5)</sub>

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`.

``` bash
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., <sub>(*6)</sub>

``` bash composer require --dev stolt/lean-package-validator, <sub>(*7)</sub>

> [!TIP] 
> As of release `v1.9.0` it's also possible to install and use the lean package validator
> via a PHAR [file](https://github.com/raphaelstolt/lean-package-validator/releases/tag/v1.9.0).

Therefor download a released version e.g. v3.3.1 and move it to `/usr/local/bin` as shown next.

``` bash
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., <sub>(*8)</sub>

``` bash lean-package-validator validate [], <sub>(*9)</sub>

### 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.

``` bash
lean-package-validator validate --enforce-strict-order [<directory>]

The --create|-c option creates an .gitattributes file if nonexistent., <sub>(*10)</sub>

``` bash lean-package-validator validate --create [], <sub>(*11)</sub>

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.

``` bash
lean-package-validator validate --overwrite [<directory>]

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., <sub>(*12)</sub>

``` bash lean-package-validator validate --glob-pattern '{.,.rst,*.py[cod],dist/}' [], <sub>(*13)</sub>

The default pattern is defined in the PHP preset [file](./src/Presets/PhpPreset.php).

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](example/.lpv) directory or be created
via `lean-package-validator init`.

``` bash
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., <sub>(*14)</sub>

``` bash lean-package-validator validate --keep-license [], <sub>(*15)</sub>

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

``` bash
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., <sub>(*16)</sub>

``` bash lean-package-validator validate --keep-glob-pattern '{LICENSE.,README.,docs*}' [], <sub>(*17)</sub>

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

``` bash
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., <sub>(*18)</sub>

``` bash lean-package-validator validate --sort-from-directories-to-files --create [], <sub>(*19)</sub>

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.

``` bash
lean-package-validator validate --validate-git-archive [<directory>]

The --diff option will show a visual diff between the actual and expected .gitattributes content., <sub>(*20)</sub>

``` bash lean-package-validator validate --diff [], <sub>(*21)</sub>

The present .gitattributes file is considered invalid., <sub>(*22)</sub>

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, <sub>(*23)</sub>

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.

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

Additional commands

Init command

The init command will create an initial .lpv file with the default patterns used to match common repository artifacts., <sub>(*24)</sub>

``` bash lean-package-validator init [], <sub>(*25)</sub>

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.

#### 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.

``` bash
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
├── lpv-logo.png
├── peck.json
├── .php-cs-fixer.php
├── phpstan.neon.dist
├── phpunit.xml.dist
└── README.md

5 directories, 15 files

``` bash lean-package-validator tree --dist-package [], <sub>(*26)</sub>

Package: stolt/lean-package-validator . ├── bin ├── composer.json └── src, <sub>(*27)</sub>

2 directories, 1 file, <sub>(*28)</sub>

## 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](https://getcomposer.org/doc/articles/scripts.md), 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`.

``` json
{
    "scripts": {
        "validate-gitattributes": "lean-package-validator validate"
    },
}

Another option to utilise the lean package validator is via cpx., <sub>(*29)</sub>

``` bash cpx stolt/lean-package-validator validate, <sub>(*30)</sub>

For utilising a dedicated GitHub Action have a look at the documentation over [here](https://github.com/raphaelstolt/lean-package-validator-action).

### Running tests

``` bash
composer lpv:test

License

This library and its CLI are licensed under the MIT license. Please see LICENSE.md for more details., <sub>(*31)</sub>

Changelog

Please see CHANGELOG.md for more details., <sub>(*32)</sub>

Contributing

Please see CONTRIBUTING.md for more details., <sub>(*33)</sub>