Add phpcs module for PHP CodeSniffer (v2.2.6)

CHANGELOG.md

@@ -1,3 +1,18 @@
+## [2.2.6] - 2026-01-03
+
+### Added
+- **PHP CodeSniffer module**: New standalone module for PHP_CodeSniffer
+  - `php/phpcs/check` - Run PHP CodeSniffer to detect coding standard violations
+  - `php/phpcs/fix` - Run PHP Code Beautifier to auto-fix violations
+  - `php/phpcs/staged` - Run PHP CodeSniffer on staged PHP files only
+  - Configuration options: `phpcs_parallel`, `phpcs_cache`, `phpcs_progress`, `phpcs_report`
+  - Runtime variables: `phpcs_files=` for paths, `phpcs_args=` for extra options
+  - Depends on `php` module
+
+### Changed
+- **PHP module**: Removed old `php/phpcs` and `php/phpcbf` targets (now in separate phpcs module)
+- **Documentation**: Added pitfall about `##` comments in `define...endef` blocks being literal text
+
 ## [2.2.5] - 2025-12-26
 
 ### Added

CLAUDE.md

@@ -258,6 +258,7 @@ Cache files stored in `tmp/cache/` with TTL support.
 4. **Windows Support**: Test PowerShell commands - some Make features differ on Windows
 5. **Module Dependencies**: Circular dependencies are not detected - avoid them
 6. **Include Guards**: Always use unique include guards in .mk files
+7. **Comments in define blocks**: `##` comments inside `define...endef` are NOT comments - they become literal output text. Only use comments OUTSIDE define blocks or use `$(info ...)` for debug output
 
 ## Code Style
 

modules/php/php/php.mk

@@ -98,12 +98,6 @@ php/psalm: ## Run Psalm to psalm.output
 		|| true \
 	)
 
-php/phpcs: ## Run PHP CodeSniffer to check code style issues
-	$(call php_invoke,vendor/bin/phpcs -s)
-
-php/phpcbf: ## Run PHP CodeSniffer to fix code style issues
-	$(call php_invoke,vendor/bin/phpcbf)
-
 endif # __MB_MODULES_PHP_TARGETS__
 
 endif # __MB_MODULES_PHP__

modules/php/phpcs/mod_config.mk

@@ -0,0 +1,26 @@
+## Path to PHP CodeSniffer binary
+phpcs_bin ?= vendor/bin/phpcs#
+
+## Path to PHP Code Beautifier and Fixer binary
+phpcbf_bin ?= vendor/bin/phpcbf#
+
+## Path to phpcs configuration file
+phpcs_config_file ?= phpcs.xml#
+
+## If true, send check output to file instead of stdout
+phpcs_send_to_file ?= $(mb_true)#
+
+## Output file for phpcs check results
+phpcs_output_file ?= phpcs.output#
+
+## Number of parallel processes (requires PCNTL extension, 1 = sequential)
+phpcs_parallel ?=#
+
+## Enable caching (empty = no cache, or path to cache file)
+phpcs_cache ?=#
+
+## Show progress dots during check
+phpcs_progress ?=#
+
+## Report format (full, json, checkstyle, junit, summary, etc.)
+phpcs_report ?=#

modules/php/phpcs/mod_info.mk

@@ -0,0 +1,6 @@
+mb_module_name := phpcs
+mb_module_version := 1.0.0
+mb_module_description := PHP CodeSniffer module for MakeBind
+mb_module_author := AntonioCS
+mb_module_license := MIT
+mb_module_depends := php

modules/php/phpcs/phpcs.mk

@@ -0,0 +1,55 @@
+#####################################################################################
+# Project: MakeBind
+# File: modules/php/phpcs/phpcs.mk
+# Description: PHP CodeSniffer module for MakeBind
+# Author: AntonioCS
+# License: MIT License
+#####################################################################################
+ifndef __MB_MODULES_PHP_PHPCS__
+__MB_MODULES_PHP_PHPCS__ := 1
+
+## Internal function to build phpcs command arguments
+## @returns Common arguments for phpcs/phpcbf
+define phpcs_build_args
+$(strip
+	$(eval $0_args :=)
+	$(eval
+		$0_args += $(if $(wildcard $(phpcs_config_file)),--standard=$(phpcs_config_file))
+		$0_args += $(if $(phpcs_parallel),--parallel=$(phpcs_parallel))
+		$0_args += $(if $(phpcs_cache),--cache=$(phpcs_cache))
+		$0_args += $(if $(phpcs_progress),-p)
+		$0_args += $(if $(phpcs_report),--report=$(phpcs_report))
+		$0_args += $(if $(value phpcs_args),$(phpcs_args))
+		$0_args += $(if $(value phpcs_files),$(phpcs_files))
+	)
+	$(strip $($0_args))
+)
+endef
+
+## Skip target definitions when loaded dynamically (e.g., during test discovery)
+ifndef __MB_TEST_DISCOVERY__
+
+## Verify php module is loaded (check once at module level)
+$(if $(value php_invoke),,$(error phpcs module requires php module - please add php module first))
+
+php/phpcs/check: ## Run PHP CodeSniffer (phpcs_files= for paths, phpcs_args= for extra options)
+	$(eval $@_cmd := $(phpcs_bin) -s $(call phpcs_build_args))
+	$(if $(call mb_is_true,$(phpcs_send_to_file)),\
+		$(eval $@_cmd += > $(phpcs_output_file) 2>&1 || true)\
+		$(call mb_printf_info,Running phpcs and sending output to $(phpcs_output_file))\
+	)
+	$(call php_invoke,$($@_cmd))
+	$(if $(call mb_is_true,$(phpcs_send_to_file)),\
+		$(call mb_printf_info,Results saved to $(phpcs_output_file))\
+	)
+
+php/phpcs/fix: ## Run PHP Code Beautifier to auto-fix (phpcs_files= for paths, phpcs_args= for extra options)
+	$(eval $@_cmd := $(phpcbf_bin) $(call phpcs_build_args))
+	$(call php_invoke,$($@_cmd))
+
+php/phpcs/staged: ## Run PHP CodeSniffer on staged PHP files only
+	$(call mb_run_on_staged,php,$(call php_invoke,$(phpcs_bin) -s))
+
+endif # __MB_TEST_DISCOVERY__
+
+endif # __MB_MODULES_PHP_PHPCS__

modules/php/phpcs/phpcs_test.mk

@@ -0,0 +1,97 @@
+#####################################################################################
+# Project: MakeBind
+# File: modules/php/phpcs/phpcs_test.mk
+# Description: Tests for the phpcs module
+# Author: AntonioCS
+# License: MIT License
+#####################################################################################
+
+include $(mb_core_path)/util.mk
+include $(mb_core_path)/functions.mk
+
+## Load config to define variables
+include $(mb_modules_path)/php/phpcs/mod_config.mk
+
+######################################################################################
+# Configuration tests
+######################################################################################
+
+define test_modules_phpcs_config_defaults
+	$(call mb_assert_eq,vendor/bin/phpcs,$(phpcs_bin),phpcs_bin should default to vendor/bin/phpcs)
+	$(call mb_assert_eq,vendor/bin/phpcbf,$(phpcbf_bin),phpcbf_bin should default to vendor/bin/phpcbf)
+	$(call mb_assert_eq,phpcs.xml,$(phpcs_config_file),phpcs_config_file should default to phpcs.xml)
+	$(call mb_assert_eq,$(mb_true),$(phpcs_send_to_file),phpcs_send_to_file should default to mb_true)
+	$(call mb_assert_eq,phpcs.output,$(phpcs_output_file),phpcs_output_file should default to phpcs.output)
+	$(call mb_assert_empty,$(phpcs_parallel),phpcs_parallel should be empty by default)
+	$(call mb_assert_empty,$(phpcs_cache),phpcs_cache should be empty by default)
+	$(call mb_assert_empty,$(phpcs_progress),phpcs_progress should be empty by default)
+	$(call mb_assert_empty,$(phpcs_report),phpcs_report should be empty by default)
+endef
+
+######################################################################################
+# phpcs_build_args tests
+######################################################################################
+
+## Need to include the main module for function tests
+include $(mb_modules_path)/php/phpcs/phpcs.mk
+
+define test_modules_phpcs_build_args_empty
+	$(eval phpcs_config_file := nonexistent.xml)
+	$(eval $0_result := $(call phpcs_build_args))
+	$(call mb_assert_empty,$($0_result),Should return empty when no config and no options)
+	$(eval phpcs_config_file := phpcs.xml)
+endef
+
+define test_modules_phpcs_build_args_with_parallel
+	$(eval phpcs_parallel := 4)
+	$(eval phpcs_config_file := nonexistent.xml)
+	$(eval $0_result := $(call phpcs_build_args))
+	$(call mb_assert_eq,--parallel=4,$($0_result),Should include parallel option)
+	$(eval phpcs_parallel :=)
+	$(eval phpcs_config_file := phpcs.xml)
+endef
+
+define test_modules_phpcs_build_args_with_cache
+	$(eval phpcs_cache := .phpcs.cache)
+	$(eval phpcs_config_file := nonexistent.xml)
+	$(eval $0_result := $(call phpcs_build_args))
+	$(call mb_assert_eq,--cache=.phpcs.cache,$($0_result),Should include cache option)
+	$(eval phpcs_cache :=)
+	$(eval phpcs_config_file := phpcs.xml)
+endef
+
+define test_modules_phpcs_build_args_with_progress
+	$(eval phpcs_progress := 1)
+	$(eval phpcs_config_file := nonexistent.xml)
+	$(eval $0_result := $(call phpcs_build_args))
+	$(call mb_assert_eq,-p,$($0_result),Should include progress flag)
+	$(eval phpcs_progress :=)
+	$(eval phpcs_config_file := phpcs.xml)
+endef
+
+define test_modules_phpcs_build_args_with_report
+	$(eval phpcs_report := json)
+	$(eval phpcs_config_file := nonexistent.xml)
+	$(eval $0_result := $(call phpcs_build_args))
+	$(call mb_assert_eq,--report=json,$($0_result),Should include report option)
+	$(eval phpcs_report :=)
+	$(eval phpcs_config_file := phpcs.xml)
+endef
+
+define test_modules_phpcs_build_args_with_files
+	$(eval phpcs_files := src/Controller/)
+	$(eval phpcs_config_file := nonexistent.xml)
+	$(eval $0_result := $(call phpcs_build_args))
+	$(call mb_assert_eq,src/Controller/,$($0_result),phpcs_files should be included)
+	$(eval phpcs_files :=)
+	$(eval phpcs_config_file := phpcs.xml)
+endef
+
+define test_modules_phpcs_build_args_runtime_args
+	$(eval phpcs_args := --colors -n)
+	$(eval phpcs_config_file := nonexistent.xml)
+	$(eval $0_result := $(call phpcs_build_args))
+	$(call mb_assert_eq,--colors -n,$($0_result),Runtime phpcs_args should be included)
+	$(eval phpcs_args :=)
+	$(eval phpcs_config_file := phpcs.xml)
+endef