diff --git a/.gitattributes b/.gitattributes index 2248014..670a52f 100644 --- a/.gitattributes +++ b/.gitattributes @@ -5,16 +5,20 @@ # https://www.reddit.com/r/PHP/comments/2jzp6k/i_dont_need_your_tests_in_my_production # https://blog.madewithlove.be/post/gitattributes/ # -/.gitattributes export-ignore -/.gitignore export-ignore -/.github export-ignore -/phpcs.xml.dist export-ignore -/phpstan.neon.dist export-ignore -/phpunit.xml.dist export-ignore -/phpunitlte9.xml.dist export-ignore -/phpunit-bootstrap.php export-ignore -/PHPCSDebug/Tests export-ignore -/Tests export-ignore +/.gitattributes export-ignore +/.gitignore export-ignore +/.github export-ignore +/.markdownlint-cli2.yaml export-ignore +/.remarkignore export-ignore +/.remarkrc export-ignore +/.yamllint.yml export-ignore +/phpcs.xml.dist export-ignore +/phpstan.neon.dist export-ignore +/phpunit.xml.dist export-ignore +/phpunitlte9.xml.dist export-ignore +/phpunit-bootstrap.php export-ignore +/PHPCSDebug/Tests export-ignore +/Tests export-ignore # # Auto detect text files and perform LF normalization diff --git a/.github/workflows/cs.yml b/.github/workflows/cs.yml index a7c0e92..1b74d83 100644 --- a/.github/workflows/cs.yml +++ b/.github/workflows/cs.yml @@ -142,3 +142,17 @@ jobs: phpstan: uses: PHPCSStandards/.github/.github/workflows/reusable-phpstan.yml@main + + markdownlint: + name: 'Lint Markdown' + uses: PHPCSStandards/.github/.github/workflows/reusable-markdownlint.yml@main + + remark: + name: 'QA Markdown' + uses: PHPCSStandards/.github/.github/workflows/reusable-remark.yml@main + + yamllint: + name: 'Lint Yaml' + uses: PHPCSStandards/.github/.github/workflows/reusable-yamllint.yml@main + with: + strict: true diff --git a/.github/workflows/quicktest.yml b/.github/workflows/quicktest.yml index f07eafe..a113404 100644 --- a/.github/workflows/quicktest.yml +++ b/.github/workflows/quicktest.yml @@ -32,7 +32,7 @@ jobs: - php: '5.4' phpcs_version: '3.1.0' - name: "QTest${{ matrix.lint && ' + Lint' || '' }}: PHP ${{ matrix.php }} - PHPCS ${{ matrix.phpcs_version }}" + name: "QTest${{ matrix.phpcs_version == 'dev-master' && ' + Lint' || '' }}: PHP ${{ matrix.php }} - PHPCS ${{ matrix.phpcs_version }}" steps: - name: Checkout code @@ -98,12 +98,16 @@ jobs: - name: Grab PHPUnit version id: phpunit_version + # yamllint disable rule:line-length run: echo "VERSION=$(vendor/bin/phpunit --version | grep --only-matching --max-count=1 --extended-regexp '\b[0-9]+\.[0-9]+')" >> "$GITHUB_OUTPUT" + # yamllint enable rule:line-length - name: Determine PHPUnit composer script to use id: phpunit_script run: | - if [ "${{ startsWith( steps.phpunit_version.outputs.VERSION, '10.' ) || startsWith( steps.phpunit_version.outputs.VERSION, '11.' ) }}" == "true" ]; then + if [ "${{ startsWith( steps.phpunit_version.outputs.VERSION, '11.' ) }}" == "true" ]; then + echo 'SUFFIX=' >> "$GITHUB_OUTPUT" + elif [ "${{ startsWith( steps.phpunit_version.outputs.VERSION, '10.' ) }}" == "true" ]; then echo 'SUFFIX=' >> "$GITHUB_OUTPUT" else echo 'SUFFIX=-lte9' >> "$GITHUB_OUTPUT" diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 00e0ae5..3288d81 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -158,12 +158,16 @@ jobs: - name: Grab PHPUnit version id: phpunit_version + # yamllint disable rule:line-length run: echo "VERSION=$(vendor/bin/phpunit --version | grep --only-matching --max-count=1 --extended-regexp '\b[0-9]+\.[0-9]+')" >> "$GITHUB_OUTPUT" + # yamllint enable rule:line-length - name: Determine PHPUnit composer script to use id: phpunit_script run: | - if [ "${{ startsWith( steps.phpunit_version.outputs.VERSION, '10.' ) || startsWith( steps.phpunit_version.outputs.VERSION, '11.' ) }}" == "true" ]; then + if [ "${{ startsWith( steps.phpunit_version.outputs.VERSION, '11.' ) }}" == "true" ]; then + echo 'SUFFIX=' >> "$GITHUB_OUTPUT" + elif [ "${{ startsWith( steps.phpunit_version.outputs.VERSION, '10.' ) }}" == "true" ]; then echo 'SUFFIX=' >> "$GITHUB_OUTPUT" else echo 'SUFFIX=-lte9' >> "$GITHUB_OUTPUT" diff --git a/.github/workflows/update-website.yml b/.github/workflows/update-website.yml index 4387345..7255d94 100644 --- a/.github/workflows/update-website.yml +++ b/.github/workflows/update-website.yml @@ -94,10 +94,10 @@ jobs: build_dir: 'deploy' target_branch: 'gh-pages' keep_history: true - #allow_empty_commit: false # Turn on after verification that it all works as expected. + allow_empty_commit: false jekyll: true commit_message: ${{ steps.commit_msg.outputs.MSG }} dry_run: ${{ steps.base_branch.outputs.BRANCH != 'stable' }} - verbose: ${{ matrix.verbose }} + verbose: false env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore index 817ab77..9c95df2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ build/ deploy/ +node_modules/ vendor/ composer.lock .phpcs.xml diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 0000000..4639775 --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,121 @@ +# +# Configuration file for MarkdownLint-CLI2. +# +# Example file with all options: +# https://github.com/DavidAnson/markdownlint-cli2/blob/main/test/markdownlint-cli2-yaml-example/.markdownlint-cli2.yaml +# + +# Do not fix any fixable errors. +fix: false + +# Define glob expressions to use (only valid at root). +globs: + - "**/*.md" + - ".github/**/*.md" + +# Show found files on stdout (only valid at root) +showFound: true + +# Define glob expressions to ignore. +ignores: + - "node_modules/" + - "vendor/" + +# Disable inline config comments. +noInlineConfig: true + +# Disable progress on stdout (only valid at root). +noProgress: false + +# Adjust the configuration for some built-in rules. +# For full information on the options and defaults, see: +# https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml +config: + ###################### + # Disable a few rules. + ###################### + # MD031/blanks-around-fences - Fenced code blocks should be surrounded by blank lines. + MD031: false + # MD032/blanks-around-lists - Lists should be surrounded by blank lines. + MD032: false + + ############################## + # Customize a few other rules. + ############################## + # MD003/heading-style/header-style - Heading style. + MD003: + # Heading style - Always use hashes. + style: "atx" + + # MD004/ul-style - Unordered list style. + MD004: + # List style - each level has a different, but consistent symbol. + style: "sublist" + + # MD007/ul-indent - Unordered list indentation. + MD007: + indent: 4 + # Whether to indent the first level of the list. + start_indented: false + + # MD012/no-multiple-blanks - Multiple consecutive blank lines. + MD012: + maximum: 2 + + # MD013/line-length - Line length. + MD013: + # Number of characters. No need for being too fussy. + line_length: 1000 + # Number of characters for headings. + heading_line_length: 100 + # Number of characters for code blocks. + code_block_line_length: 140 + # Stern length checking (applies to tables, code blocks etc which have their own max line length). + stern: true + + # MD022/blanks-around-headings : Headings should be surrounded by blank lines. + MD022: + # Blank lines above heading + lines_above: [2, 1, 1, 1, 1] + # Blank lines below heading + lines_below: [1, 1, -1, -1, -1] + + # MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the same content. + MD024: + # Only check sibling headings. + siblings_only: true + + # MD033/no-inline-html - Inline HTML. + MD033: + # Allowed elements. + allowed_elements: + - div + - details + - summary + - b + - code + - ul + - li + + # MD044/proper-names - Proper names should have the correct capitalization. + MD044: + # List of proper names. + names: ["PHPDevTools", "PHPCSUtils", "PHP", "PHP_CodeSniffer", "CodeSniffer", "PHPUnit"] + # Include code blocks. + code_blocks: false + + # MD046/code-block-style - Code block style + MD046: + style: "fenced" + + # MD048/code-fence-style - Code fence style + MD048: + style: "backtick" + + # MD049/emphasis-style - Emphasis style should be consistent + MD049: + style: "underscore" + + # MD050/strong-style - Strong style should be consistent + MD050: + style: "asterisk" diff --git a/.remarkignore b/.remarkignore new file mode 100644 index 0000000..6718a0b --- /dev/null +++ b/.remarkignore @@ -0,0 +1,5 @@ +# Ignore rules for Remark. +# Docs: https://github.com/unifiedjs/unified-engine/blob/HEAD/doc/ignore.md + +/node_modules/ +/vendor/ diff --git a/.remarkrc b/.remarkrc new file mode 100644 index 0000000..f9f457f --- /dev/null +++ b/.remarkrc @@ -0,0 +1,46 @@ +{ + "plugins": [ + "remark-gfm", + ["remark-lint-checkbox-character-style", "consistent"], + ["remark-lint-checkbox-content-indent", "consistent"], + "remark-lint-definition-spacing", + "remark-lint-file-extension", + ["remark-lint-linebreak-style", "unix"], + ["remark-lint-link-title-style", "\""], + ["remark-lint-ordered-list-marker-style", "."], + [ + "remark-lint-no-dead-urls", + { + "skipUrlPatterns": [ + "https://packagist.org/packages/phpcsstandards/phpcsdevtools#dev-develop" + ], + "deadOrAliveOptions": { + "maxRetries": 3 + } + } + ], + "remark-lint-no-duplicate-defined-urls", + "remark-lint-no-duplicate-definitions", + "remark-lint-no-empty-url", + "remark-lint-no-file-name-consecutive-dashes", + ["remark-lint-no-file-name-irregular-characters", "\\.a-zA-Z0-9_-"], + "remark-lint-no-file-name-outer-dashes", + "remark-lint-no-heading-like-paragraph", + "remark-lint-no-literal-urls", + "remark-lint-no-reference-like-url", + "remark-lint-no-shortcut-reference-image", + "remark-lint-no-table-indentation", + "remark-lint-no-undefined-references", + "remark-lint-no-unneeded-full-reference-image", + "remark-lint-no-unneeded-full-reference-link", + "remark-lint-no-unused-definitions", + ["remark-lint-strikethrough-marker", "~~"], + ["remark-lint-table-cell-padding", "consistent"], + "remark-lint-heading-whitespace", + "remark-lint-list-item-punctuation", + "remark-lint-match-punctuation", + "remark-lint-no-hr-after-heading", + "remark-lint-are-links-valid-duplicate", + "remark-validate-links" + ] +} diff --git a/.yamllint.yml b/.yamllint.yml new file mode 100644 index 0000000..b5c4202 --- /dev/null +++ b/.yamllint.yml @@ -0,0 +1,23 @@ +# Details on the default config: +# https://yamllint.readthedocs.io/en/stable/configuration.html#default-configuration +extends: default + +yaml-files: + - '*.yaml' + - '*.yml' + - '.yamllint' + - 'phpstan.neon*' + +# Rule documentation: https://yamllint.readthedocs.io/en/stable/rules.html +rules: + colons: + max-spaces-after: -1 # Disabled to allow aligning of values. + comments: + min-spaces-from-content: 1 + comments-indentation: {} + document-start: + present: false + line-length: + max: 145 + truthy: + allowed-values: ["true", "false", "on", "off"] diff --git a/CHANGELOG.md b/CHANGELOG.md index adc2dce..d8d00f9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,8 @@ -# Change Log for the PHPCSDevTools standard for PHP Codesniffer +# Change Log for the PHPCSDevTools standard for PHP_CodeSniffer All notable changes to this project will be documented in this file. -This projects adheres to [Keep a CHANGELOG](http://keepachangelog.com/) and uses [Semantic Versioning](http://semver.org/). +This projects adheres to [Keep a CHANGELOG](https://keepachangelog.com/) and uses [Semantic Versioning](https://semver.org/). ## [Unreleased] diff --git a/README.md b/README.md index 11f31a6..a5337b7 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,25 @@ -PHPCSDevTools for developers of PHP_CodeSniffer sniffs -===================================================== +# PHPCSDevTools for developers of PHP_CodeSniffer sniffs -This is a set of tools to assist developers of sniffs for [PHP CodeSniffer](https://github.com/PHPCSStandards/PHP_CodeSniffer). +This is a set of tools to assist developers of sniffs for [PHP CodeSniffer][phpcs-gh]. * [Installation](#installation) + [Composer Project-based Installation](#composer-project-based-installation) @@ -34,8 +33,7 @@ This is a set of tools to assist developers of sniffs for [PHP CodeSniffer](http * [License](#license) -Installation -------------------------------------------- +## Installation ### Composer Project-based Installation @@ -58,9 +56,9 @@ Composer will automatically install dependencies and register the PHPCSDebug sta ### Stand-alone Installation -* Install [PHP CodeSniffer](https://github.com/PHPCSStandards/PHP_CodeSniffer) via [your preferred method](https://github.com/PHPCSStandards/PHP_CodeSniffer#installation). +* Install [PHP CodeSniffer][phpcs-gh] via [your preferred method][phpcs-gh-install]. * Register the path to PHPCS in your system `$PATH` environment variable to make the `phpcs` command available from anywhere in your file system. -* Download the [latest PHPCSDevTools release](https://github.com/PHPCSStandards/PHPCSDevTools/releases) and unzip/untar it into an arbitrary directory. +* Download the [latest PHPCSDevTools release][phpcsdevtools-releases] and unzip/untar it into an arbitrary directory. You can also choose to clone this repository using git. * Add the path to the directory in which you placed your copy of the PHPCSDevTools repo to the PHP CodeSniffer configuration using the below command: ```bash @@ -72,8 +70,7 @@ Composer will automatically install dependencies and register the PHPCSDebug sta ``` -Features ------------------------------- +## Features ### Checking whether all sniffs in a PHPCS standard are feature complete @@ -94,7 +91,7 @@ php -f "path/to/PHPCSDevTools/bin/phpcs-check-feature-completeness" If all is good, you will see a `All # sniffs are accompanied by unit tests and documentation.` message. If there are files missing, you will see errors/warnings for each missing file, like so: -``` +```text WARNING: Documentation missing for path/to/project/StandardName/Sniffs/Category/SniffNameSniff.php. ERROR: Unit tests missing for path/to/project/StandardName/Sniffs/Category/SniffNameSniff.php. ``` @@ -105,7 +102,7 @@ phpcs-check-feature-completeness ./StandardName ``` #### Options -``` +```text directories One or more specific directories to examine. Defaults to the directory from which the script is run. -q, --quiet Turn off warnings for missing documentation. @@ -143,7 +140,7 @@ phpcs ./SniffNameUnitTest.inc --standard=YourStandard,PHPCSDebug --sniffs=YourSt ``` The output will look something along the lines of: -``` +```text Ptr | Ln | Col | Cond | ( #) | Token Type | [len]: Content ------------------------------------------------------------------------- 0 | L1 | C 1 | CC 0 | ( 0) | T_OPEN_TAG | [ 5]: