LeanPackageValidator

The LeanPackageValidator is an utility tool that validates a project/micro-package for it's leanness. A project/micro-package is considered lean when it's common repository artifacts won’t be included in release/dist archive files.

Installation

The LeanPackageValidator CLI should be installed globally through composer.

composer global require stolt/lean-package-validator

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.

alias lpv='$HOME/.composer/vendor/bin/lean-package-validator $@'

The LeanPackageValidator also can be installed locally to a project which allows further utilisation via Composer scripts.

composer require --dev stolt/lean-package-validator

Usage

Just run the LeanPackageValidator 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 of the PHP ecosystem.

lean-package-validator validate [<directory>] --glob-pattern '{.*,*.rst,*.py[cod],dist/}'

* The default pattern is {.*,*.lock,*.txt,*.rst,*.{md,MD},*.xml,*.yml,box.json,*dist*,{B,b}uild*,{D,d}oc*,{T,t}ool*,{T,t}est*,{S,s}pec*,{E,e}xample*,LICENSE,{{M,m}ake,{B,b}ox,{V,v}agrant,{P,p}hulp}file,RMT}*.

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.

lean-package-validator validate [<directory>] --glob-pattern-file /path/to/glob-pattern-file

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 it's content.

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

Utilisation via Composer scripts

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 everyones 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"
    },
}

Further this Composer script could also be utilised in Travis CI builds similar to the composer test script call.

Running tests

composer test

License

This library and it's CLI are licensed under the MIT license. Please see LICENSE for more details.

Changelog

Please see CHANGELOG for more details.

Contributing

Please see CONTRIBUTING for more details.