fix(style-code): Resolve static analysis errors and improve type safety

This commit addresses a series of issues identified by PHPStan, enhancing the overall type safety and robustness of the data structures.

- **BinaryHeap:** Corrected type inference by specifying the heap property as a `list`, which eliminates the need for explicit integer casting when removing elements.
- **TreeMap/TreeMapNode:** Fixed a potential null pointer exception in `balanceAfterInsertion` by adding a safety check for the grandparent node.
- **HashMap:** Refactored to use a consistent internal key handling mechanism, resolving type errors and adding proper support for object keys.
- **ArrayList:** Fixed a `Cannot cast mixed to string` error by explicitly handling the `resource` type.
- **phpstan.neon:** Cleaned up the configuration by removing obsolete ignored error patterns.

Author: walmir-silva

Makefile

@@ -149,6 +149,28 @@ security-check: check-environment check-container-running
 	$(EXEC_PHP) ./vendor/bin/security-checker security:check
 	@echo "${GREEN}${CHECK_MARK} Security check completed!${NC}"
 
+## stan-src: Run PHPStan static analysis on src/
+stan-src: check-environment check-container-running
+	@echo "${GREEN}${INFO} Running PHPStan on src/...${NC}"
+	$(EXEC_PHP) ./vendor/bin/phpstan analyse src --memory-limit=1G --ansi
+	@echo "${GREEN}${CHECK_MARK} PHPStan (src/) analysis completed!${NC}"
+
+## stan-tests: Run PHPStan static analysis on tests/
+stan-tests: check-environment check-container-running
+	@echo "${GREEN}${INFO} Running PHPStan on tests/...${NC}"
+	$(EXEC_PHP) ./vendor/bin/phpstan analyse tests --memory-limit=1G --ansi
+	@echo "${GREEN}${CHECK_MARK} PHPStan (tests/) analysis completed!${NC}"
+
+## stan-file: Run PHPStan analysis on a specific file. Usage: make stan-file FILE=path/to/file.php
+stan-file: check-environment check-container-running
+	@if [ -z "$(FILE)" ]; then \
+		echo "${RED}${WARNING}  You must specify a file. Usage: make stan-file FILE=path/to/file.php${NC}"; \
+	else \
+		echo "${GREEN}${INFO} Running PHPStan on file: $(FILE)...${NC}"; \
+		$(EXEC_PHP) ./vendor/bin/phpstan analyse $(FILE) --memory-limit=1G --ansi; \
+		echo "${GREEN}${CHECK_MARK} PHPStan analysis completed for $(FILE)!${NC}"; \
+	fi
+
 ## quality: Run all quality commands
 quality: check-environment check-container-running cs-check test security-check 
 	@echo "${GREEN}${CHECK_MARK} All quality commands executed!${NC}"
@@ -171,4 +193,4 @@ help:
 	@echo "\n${GREEN}Available commands:${NC}"
 	@sed -n 's/^##//p' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ": "}; {printf "${YELLOW}%-30s${NC} %s\n", $$1, $$2}'
 
-.PHONY: setup-env up down build logs re-build shell composer-install composer-remove composer-update test test-file coverage coverage-html run-script cs-check cs-fix security-check quality help
+.PHONY: setup-env up down build logs re-build shell composer-install composer-remove composer-update test test-file coverage coverage-html run-script cs-check cs-fix security-check stan-src stan-tests stan-file quality help

composer.json

@@ -46,6 +46,7 @@
   "require-dev": {
     "friendsofphp/php-cs-fixer": "^3.58",
     "nunomaduro/phpinsights": "^2.11",
+    "phpstan/phpstan": "^1.10",
     "phpunit/phpunit": "^10.5",
     "squizlabs/php_codesniffer": "^3.10",
     "mockery/mockery": "^1.6",