Merge pull request #524 from wayofdev/feat/tpl-updates

feat: markdown-lint action and Makefile command

.github/CODE_OF_CONDUCT.md

@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-[email protected].
+<[email protected]>.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the
@@ -116,13 +116,13 @@ the community.
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage],
 version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
 
 Community Impact Guidelines were inspired by [Mozilla's code of conduct
 enforcement ladder](https://github.com/mozilla/diversity).
 
 [homepage]: https://www.contributor-covenant.org
 
 For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at
-https://www.contributor-covenant.org/translations.
+<https://www.contributor-covenant.org/faq>. Translations are available at
+<https://www.contributor-covenant.org/translations>.

.github/CONTRIBUTING.md

@@ -30,7 +30,7 @@ Before you begin, you will need to set up your local development environment. He
 This project uses a Makefile to streamline common development tasks. The Makefile includes utilities for managing Docker environments, running tests, and linting code.
 
 ```bash
-$ make help
+make help
 ```
 
 ![Screenshot](../assets/screenshot.png)
@@ -74,7 +74,7 @@ This package leverages Docker to provide a consistent and isolated development e
 To run docker container:
 
 ```bash
-$ make up
+make up
 ```
 
 Other commands:
@@ -112,15 +112,15 @@ Our project employs [GitHub Actions](https://github.com/features/actions) for co
 
 <br>
 
-## ✉️ Commit Message Guidelines
+## 📩 Commit Message Guidelines
 
 We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard. Please structure your commit messages as follows, using the appropriate prefix:
 
 **Examples:**
 
 ```bash
-$ git commit -am 'feat: some feature was introduced'
-$ git commit -am 'fix: something has been fixed'
+git commit -am 'feat: some feature was introduced'
+git commit -am 'fix: something has been fixed'
 ```
 
 **Allowed Prefixes:**
@@ -154,7 +154,7 @@ We use [`ergebnis/composer-normalize`](https://github.com/ergebnis/composer-norm
 Use:
 
 ```bash
-$ make lint-composer
+make lint-composer
 ```
 
 ### → Yaml Lint
@@ -164,7 +164,7 @@ We use [`yamllint`](https://github.com/adrienverge/yamllint) to enforce coding s
 To lint yaml files run:
 
 ```bash
-$ make lint-yaml
+make lint-yaml
 ```
 
 by default, [`cytopia/yamllint`](https://github.com/cytopia/docker-yamllint) Docker image will be used to run linter.
@@ -175,11 +175,10 @@ by default, [`cytopia/yamllint`](https://github.com/cytopia/docker-yamllint) Doc
 
 We use [`actionlint`](https://github.com/rhysd/actionlint) to enforce coding standards in GitHub Actions workflows.
 
-
 To lint GitHub Actions run:
 
 ```bash
-$ make lint-actions
+make lint-actions
 ```
 
 by default, [`rhysd/actionlint`](https://hub.docker.com/r/rhysd/actionlint/tags) Docker image will be used to run linter.
@@ -193,7 +192,7 @@ We use [`friendsofphp/php-cs-fixer`](https://github.com/FriendsOfPHP/PHP-CS-Fixe
 Run
 
 ```bash
-$ make lint-php
+make lint-php
 ```
 
 to automatically fix coding standard violations.
@@ -207,7 +206,7 @@ We use [`maglnet/composer-require-checker`](https://github.com/maglnet/ComposerR
 Run
 
 ```sh
-$ make lint-deps
+make lint-deps
 ```
 
 to run a dependency analysis.
@@ -221,7 +220,7 @@ We use [`infection/infection`](https://github.com/infection/infection) to ensure
 Xdebug support is enabled by default, when running commands through `Makefile`:
 
 ```sh
-$ make infect
+make infect
 ```
 
 to run mutation tests.
@@ -235,8 +234,8 @@ We use both [`phpstan/phpstan`](https://github.com/phpstan/phpstan) and [`vimeo/
 Run
 
 ```sh
-$ make lint-stan
-$ make lint-psalm
+make lint-stan
+make lint-psalm
 ```
 
 to run a static code analysis.
@@ -246,8 +245,8 @@ We also use the baseline features of [`phpstan/phpstan`](https://phpstan.org/use
 Run
 
 ```sh
-$ make lint-stan-baseline
-$ make lint-psalm-baseline
+make lint-stan-baseline
+make lint-psalm-baseline
 ```
 
 to regenerate the baselines in:
@@ -268,7 +267,7 @@ We use [`phpunit/phpunit`](https://github.com/sebastianbergmann/phpunit) and [`p
 Run
 
 ```sh
-$ make tests
+make tests
 ```
 
 to run all the tests.
@@ -294,5 +293,5 @@ Our pre-commit configuration includes several hooks:
 To utilize these hooks, you first need to install them using the command provided by the Makefile:
 
 ```bash
-$ make hooks
+make hooks
 ```

.github/workflows/integrate.yml

@@ -21,7 +21,6 @@ jobs:
       - name: 📦 Check out the codebase
         uses: actions/[email protected]
 
-      # See: https://github.com/wagoid/commitlint-github-action
       - name: 🧐 Lint commits using "commitlint"
         uses: wagoid/[email protected]
         with:
@@ -30,6 +29,23 @@ jobs:
           failOnErrors: false
           helpURL: 'https://github.com/conventional-changelog/commitlint/#what-is-commitlint'
 
+  markdown-linting:
+    timeout-minutes: 4
+    runs-on: ubuntu-latest
+    concurrency:
+      cancel-in-progress: true
+      group: markdown-linting-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+    steps:
+      - name: 📦 Check out the codebase
+        uses: actions/[email protected]
+
+      - name: 🧐 Lint Markdown files
+        uses: DavidAnson/[email protected]
+        with:
+          globs: |
+            **/*.md
+            !CHANGELOG.md
+
   code-coverage:
     timeout-minutes: 4
     runs-on: ${{ matrix.os }}
@@ -45,7 +61,6 @@ jobs:
           - '8.2'
         dependencies:
           - locked
-
     steps:
       - name: 📦 Check out the codebase
         uses: actions/[email protected]
@@ -106,7 +121,6 @@ jobs:
           - '8.2'
         dependencies:
           - locked
-
     steps:
       - name: 📦 Check out the codebase
         uses: actions/[email protected]

.markdownlint.json

@@ -0,0 +1,7 @@
+{
+    "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/v0.34.0/schema/markdownlint-config-schema.json",
+    "line-length": false,
+    "no-inline-html": false,
+    "first-line-h1": false,
+    "no-duplicate-heading": false
+}

.pre-commit-config.yaml

@@ -29,4 +29,13 @@ repos:
         pass_filenames: false
         require_serial: true
 
+  - repo: local
+    hooks:
+      - id: markdownlint
+        name: markdownlint-cli2
+        description: Run markdownlint-cli2 on your Markdown files using the docker image
+        language: docker_image
+        types: [markdown]
+        entry: davidanson/markdownlint-cli2-rules:latest
+
 ...

Makefile

@@ -40,6 +40,11 @@ ACTION_LINT_RUNNER ?= $(DOCKER) run --rm $$(tty -s && echo "-it" || echo) \
 	 rhysd/actionlint:latest \
 	 -color
 
+MARKDOWN_LINT_RUNNER ?= $(DOCKER) run --rm $$(tty -s && echo "-it" || echo) \
+	-v $(shell pwd):/app \
+	--workdir /app \
+	davidanson/markdownlint-cli2-rules:latest
+
 PHIVE_RUNNER ?= $(DOCKER_COMPOSE) run --rm --no-deps app
 
 NPM_RUNNER ?= pnpm
@@ -178,7 +183,7 @@ hooks: ## Install git hooks from pre-commit-config
 	pre-commit autoupdate
 .PHONY: hooks
 
-lint: lint-yaml lint-actions lint-php lint-stan lint-composer lint-audit ## Runs all linting commands
+lint: lint-yaml lint-actions lint-md lint-php lint-stan lint-composer lint-audit ## Runs all linting commands
 .PHONY: lint
 
 lint-yaml: ## Lints yaml files inside project
@@ -189,6 +194,14 @@ lint-actions: ## Lint all github actions
 	@$(ACTION_LINT_RUNNER) | tee -a $(MAKE_LOGFILE)
 .PHONY: lint-actions
 
+lint-md: ## Lint all markdown files using markdownlint-cli2
+	@$(MARKDOWN_LINT_RUNNER) --fix "**/*.md" "!CHANGELOG.md" "!vendor" | tee -a $(MAKE_LOGFILE)
+.PHONY: lint-md
+
+lint-md-dry: ## Lint all markdown files using markdownlint-cli2 in dry-run mode
+	@$(MARKDOWN_LINT_RUNNER) "**/*.md" "!CHANGELOG.md" "!vendor" | tee -a $(MAKE_LOGFILE)
+.PHONY: lint-md-dry
+
 lint-php: prepare ## Fixes code to follow coding standards using php-cs-fixer
 	$(APP_COMPOSER) cs:fix
 .PHONY: lint-php

README.md

@@ -17,11 +17,11 @@
 <a href="https://github.com/wayofdev/laravel-package-tpl/actions" target="_blank"><img alt="Build Status" src="https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fwayofdev%2Flaravel-package-tpl%2Fbadge&style=flat-square&label=github%20actions"/></a>
 <a href="https://packagist.org/packages/wayofdev/laravel-package-tpl" target="_blank"><img src="https://img.shields.io/packagist/dt/wayofdev/laravel-package-tpl?&style=flat-square" alt="Total Downloads"></a>
 <a href="https://packagist.org/packages/wayofdev/laravel-package-tpl" target="_blank"><img src="https://img.shields.io/packagist/v/wayofdev/laravel-package-tpl?&style=flat-square" alt="Latest Stable Version"></a>
-<a href="https://packagist.org/packages/wayofdev/laravel-package-tpl" target="_blank"><img src="https://img.shields.io/packagist/l/wayofdev/laravel-package-tpl?style=flat-square&color=blue" alt="Software License"/></a>
 <a href="https://packagist.org/packages/wayofdev/laravel-package-tpl" target="_blank"><img alt="Commits since latest release" src="https://img.shields.io/github/commits-since/wayofdev/laravel-package-tpl/latest?style=flat-square"></a>
 <a href="https://packagist.org/packages/wayofdev/laravel-package-tpl" target="_blank"><img alt="PHP Version Require" src="https://poser.pugx.org/wayofdev/laravel-package-tpl/require/php?style=flat-square"></a>
 <a href="https://app.codecov.io/gh/wayofdev/laravel-package-tpl" target="_blank"><img alt="Codecov" src="https://img.shields.io/codecov/c/github/wayofdev/laravel-package-tpl?style=flat-square&logo=codecov"></a>
 <a href="https://dashboard.stryker-mutator.io/reports/github.com/wayofdev/laravel-package-tpl/master" target="_blank"><img alt="Mutation testing badge" src="https://img.shields.io/endpoint?style=flat-square&label=mutation%20score&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fwayofdev%2Flaravel-package-tpl%2Fmaster"></a>
+<a href=""><img src="https://img.shields.io/badge/phpstan%20level-6%20of%209-yellowgreen?style=flat-square" alt="PHP Stan Level 6 of 9"></a>
 <a href="https://discord.gg/CE3TcCC5vr" target="_blank"><img alt="Codecov" src="https://img.shields.io/discord/1228506758562058391?style=flat-square&logo=discord&labelColor=7289d9&logoColor=white&color=39456d"></a>
 <a href="https://x.com/intent/follow?screen_name=wayofdev" target="_blank"><img alt="Follow on Twitter (X)" src="https://img.shields.io/badge/-Follow-black?style=flat-square&logo=X"></a>
 </div>
@@ -59,7 +59,7 @@ This template repository includes several features to streamline the development
 - [Psalm](https://psalm.dev) for finding errors in PHP applications through static analysis.
 - [PHP Rector](https://github.com/rectorphp/rector) for automated code upgrades and refactoring, maintaining modern code standards.
 
-### → Coding Standards:
+### → Coding Standards
 
 - [PHP CS Fixer](https://github.com/wayofdev/php-cs-fixer-config) with custom configuration for consistent code style.
 - [Composer Normalize](https://github.com/ergebnis/composer-normalize) to ensure a consistent `composer.json` format.
@@ -81,7 +81,7 @@ This template repository includes several features to streamline the development
 
 ### → Issue Templates
 
-* This package is equipped with a set of ready-to-use issue templates to streamline contributions and issue reporting.
+- This package is equipped with a set of ready-to-use issue templates to streamline contributions and issue reporting.
 
   You can find these templates organized in the [`.github/ISSUE_TEMPLATE`](.github/ISSUE_TEMPLATE) directory.
 
@@ -115,31 +115,61 @@ $ make help
 To run tests, run the following command:
 
 ```bash
-$ make test
+make test
+```
+
+### → Mutation tests
+
+To run mutation tests, using [`infection/infection`](https://github.com/infection/infection):
+
+```bash
+make infect
 ```
 
 ### → Static Analysis
 
 Code quality using PHPStan:
 
 ```bash
-$ make lint-stan
+make lint-stan
+```
+
+and using Psalm:
+
+```bash
+make lint-psalm
 ```
 
 ### → Coding Standards Fixing
 
 Fix code using The PHP Coding Standards Fixer (PHP CS Fixer) to follow our standards:
 
 ```bash
-$ make lint-php
+make lint-php
 ```
 
 ### → Lint Yaml files
 
 Lint all yaml files in project:
 
 ```bash
-$ make lint-yaml
+make lint-yaml
+```
+
+### → Lint Markdown files
+
+Lint all yaml files in project:
+
+```bash
+make lint-md
+```
+
+### → Lint GitHub Actions
+
+Lint all yaml files in project:
+
+```bash
+make lint-actions
 ```
 
 <br>
@@ -169,7 +199,6 @@ You are more than welcome. Before contributing, kindly check our [contribution g
 
 [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=for-the-badge)](https://conventionalcommits.org)
 
-
 <br>
 
 ## 🌐 Social Links