Fix code quality tools configuration and update documentation

2025-04-21 14:32:11 +01:00
parent 3926927791
commit 3048e91a78
8 changed files with 300 additions and 11 deletions
--- a/.codacy.yml
+++ b/.codacy.yml
@@ -3,6 +3,52 @@ engines:
  markdownlint:
    enabled: true
    config_file: .markdownlint.json
+  phpmd:
+    enabled: true
+  phpcs:
+    enabled: true
+  stylelint:
+    enabled: false
+  shellcheck:
+    enabled: false
+  # Disable tools that are causing issues
+  eslint:
+    enabled: false
+  eslint-8:
+    enabled: false
+  eslint-9:
+    enabled: false
+  trivy:
+    enabled: false
+  semgrep:
+    enabled: false
+  checkov:
+    enabled: false
+  pmd:
+    enabled: false
+  pmd-7:
+    enabled: false
+  lizard:
+    enabled: false
+  jshint:
+    enabled: false
+  csslint:
+    enabled: false
+  jacksonlinter:
+    enabled: false
+  spectral:
+    enabled: false
+
+duplication:
+  enabled: true
+  exclude_patterns:
+    - "tests/**"
+    - "vendor/**"
+    - "node_modules/**"
+
+metrics:
+  enabled: true
+
 exclude_paths:
  - "vendor/**"
  - "node_modules/**"
@@ -11,3 +57,5 @@ exclude_paths:
  - "bin/**"
  - ".github/**"
  - "tests/**"
+  - "*.lock"
+  - "*.json"
--- a/.eslintrc.json
+++ b/.eslintrc.json
@@ -0,0 +1,19 @@
+{
+  "env": {
+    "browser": true,
+    "jquery": true,
+    "es6": true
+  },
+  "extends": "eslint:recommended",
+  "parserOptions": {
+    "ecmaVersion": 2018,
+    "sourceType": "module"
+  },
+  "rules": {
+    "indent": ["error", 2],
+    "linebreak-style": ["error", "unix"],
+    "quotes": ["error", "single"],
+    "semi": ["error", "always"]
+  },
+  "ignorePatterns": ["vendor/**", "node_modules/**", "build/**", "dist/**", "bin/**"]
+}
--- a/.github/workflows/code-quality.yml
+++ b/.github/workflows/code-quality.yml
@@ -27,13 +27,13 @@ jobs:
        run: composer install --prefer-dist --no-progress

      - name: Run PHPCS
-        run: composer run phpcs
+        run: phpcs --standard=./phpcs.xml .
        continue-on-error: true

      - name: Run PHPCBF (report only)
        run: |
          echo "Running PHPCBF in dry-run mode to show what would be fixed"
-          composer run phpcbf -- --dry-run
+          phpcbf --standard=./phpcs.xml -n
        continue-on-error: true

  phpstan:
@@ -130,13 +130,16 @@ jobs:
          verbose: true
          output: results.sarif
          format: sarif
-          # Adjust the below patterns based on your project structure
+          # Limit the number of issues to prevent GitHub Code Scanning rejection
          gh-code-scanning-compat: true
-          max-allowed-issues: 2147483647
+          max-allowed-issues: 20
+          max-allowed-security-issues: 20
+          # Limit tools to prevent timeouts and stay under GitHub's 20 runs limit
+          tool: phpcs,phpmd,markdownlint
        continue-on-error: true

      - name: Upload SARIF results file
-        uses: github/codeql-action/upload-sarif@v2
+        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif
        continue-on-error: true
--- a/.markdownlint.json
+++ b/.markdownlint.json
@@ -1,4 +1,5 @@
 {
+  "default": true,
  "MD004": {
    "style": "asterisk"
  },
--- a/.stylelintrc.json
+++ b/.stylelintrc.json
@@ -0,0 +1,49 @@
+{
+  "extends": "stylelint-config-standard",
+  "rules": {
+    "indentation": 4,
+    "string-quotes": "single",
+    "no-duplicate-selectors": true,
+    "color-hex-case": "lower",
+    "color-hex-length": "short",
+    "selector-combinator-space-after": "always",
+    "selector-attribute-quotes": "always",
+    "selector-attribute-operator-space-before": "never",
+    "selector-attribute-operator-space-after": "never",
+    "selector-attribute-brackets-space-inside": "never",
+    "declaration-block-trailing-semicolon": "always",
+    "declaration-colon-space-before": "never",
+    "declaration-colon-space-after": "always",
+    "property-no-vendor-prefix": true,
+    "value-no-vendor-prefix": true,
+    "number-leading-zero": "always",
+    "function-url-quotes": "always",
+    "font-weight-notation": "numeric",
+    "font-family-name-quotes": "always-where-recommended",
+    "at-rule-no-vendor-prefix": true,
+    "selector-no-vendor-prefix": true,
+    "media-feature-name-no-vendor-prefix": true,
+    "at-rule-empty-line-before": [
+      "always",
+      {
+        "except": [
+          "blockless-after-same-name-blockless",
+          "first-nested"
+        ],
+        "ignore": [
+          "after-comment"
+        ]
+      }
+    ],
+    "at-rule-name-case": "lower",
+    "at-rule-name-space-after": "always-single-line",
+    "at-rule-semicolon-newline-after": "always"
+  },
+  "ignoreFiles": [
+    "vendor/**",
+    "node_modules/**",
+    "build/**",
+    "dist/**",
+    "bin/**"
+  ]
+}
--- a/README.md
+++ b/README.md
@@ -252,10 +252,25 @@ This project uses several automated code quality tools to ensure high standards.
 3. **Codacy**: Code quality and static analysis
   * [Website](https://www.codacy.com/)
   * Identifies issues related to code style, security, and performance
+   * Requires a `CODACY_PROJECT_TOKEN` secret in your GitHub repository settings
+   * To set up Codacy:
+     1. Go to [Codacy](https://www.codacy.com/) and sign in with your GitHub account
+     2. Add your repository to Codacy
+     3. Go to your project settings > Integrations > Project API
+     4. Generate a project API token
+     5. Add the token as a secret named `CODACY_PROJECT_TOKEN` in your GitHub repository settings
+     6. Note: Codacy tokens are project-specific, so they need to be added at the repository level. However, you can use GitHub Actions to securely pass these tokens between repositories if needed.

 4. **SonarCloud**: Code quality and security analysis
   * [Website](https://sonarcloud.io/)
   * Provides detailed analysis of code quality and security
+   * Requires a `SONAR_TOKEN` secret in your GitHub repository settings
+   * To set up SonarCloud:
+     1. Go to [SonarCloud](https://sonarcloud.io/) and sign in with your GitHub account
+     2. Create a new organization or use an existing one
+     3. Add your repository to SonarCloud
+     4. Generate a token in SonarCloud (Account > Security > Tokens)
+     5. Add the token as a secret named `SONAR_TOKEN` in your GitHub repository or organization settings (see "GitHub Secrets Management" section below)

 ### Using AI Assistants with Code Quality Tools

@@ -269,6 +284,94 @@ When you receive feedback from these code quality tools, you can use AI assistan

 For more information on coding standards and how to pass code quality checks, see the [Coding Standards Guide](.wiki/Coding-Standards.md).

+### GitHub Secrets Management
+
+GitHub offers three levels of secrets management, each with different scopes and use cases:
+
+1. **Organization Secrets** (recommended for teams and organizations):
+   * Available at: GitHub Organization > Settings > Secrets and variables > Actions
+   * Scope: Can be shared across multiple repositories within the organization
+   * Benefits: Centralized management, reduced duplication, easier rotation
+   * Recommended for: `SONAR_TOKEN` and other tokens that apply to multiple repositories
+   * Note: You can restrict which repositories can access organization secrets
+   * Note: Codacy tokens (`CODACY_PROJECT_TOKEN`) are project-specific and should be set at the repository level
+
+2. **Repository Secrets**:
+   * Available at: Repository > Settings > Secrets and variables > Actions
+   * Scope: Limited to a single repository
+   * Benefits: Repository-specific, higher isolation
+   * Recommended for: `CODACY_PROJECT_TOKEN` and other repository-specific credentials or tokens that shouldn't be shared
+
+3. **Environment Secrets**:
+   * Available at: Repository > Settings > Environments > (select environment) > Environment secrets
+   * Scope: Limited to specific deployment environments (e.g., production, staging)
+   * Benefits: Environment-specific, can have approval requirements
+   * Recommended for: Deployment credentials that vary between environments
+
+For code quality tools like SonarCloud, organization secrets are recommended if you have multiple repositories that use these tools. This approach reduces management overhead and ensures consistent configuration across projects. For Codacy, since tokens are project-specific, they should be set at the repository level.
+
+### Local Environment Setup for Code Quality Tools
+
+To run code quality tools locally before committing to GitHub:
+
+1. **Set up environment variables**:
+
+   * **For macOS/Linux**:
+     ```bash
+     export SONAR_TOKEN=your_sonar_token
+     export CODACY_PROJECT_TOKEN=your_codacy_token
+     ```
+
+   * **For Windows (Command Prompt)**:
+     ```cmd
+     set SONAR_TOKEN=your_sonar_token
+     set CODACY_PROJECT_TOKEN=your_codacy_token
+     ```
+
+   * **For Windows (PowerShell)**:
+     ```powershell
+     $env:SONAR_TOKEN="your_sonar_token"
+     $env:CODACY_PROJECT_TOKEN="your_codacy_token"
+     ```
+
+2. **Create a .env file** (alternative approach):
+   ```
+   # .env (already included in .gitignore to prevent committing secrets)
+   SONAR_TOKEN=your_sonar_token
+   CODACY_PROJECT_TOKEN=your_codacy_token
+   ```
+
+   Then load these variables:
+   ```bash
+   # Using a tool like dotenv
+   source .env
+   ```
+
+3. **Run SonarCloud locally**:
+   ```bash
+   # Install SonarScanner
+   npm install -g sonarqube-scanner
+
+   # Run analysis
+   sonar-scanner \
+     -Dsonar.projectKey=your_project_key \
+     -Dsonar.organization=your_organization \
+     -Dsonar.sources=. \
+     -Dsonar.host.url=https://sonarcloud.io \
+     -Dsonar.login=$SONAR_TOKEN
+   ```
+
+4. **Run Codacy locally**:
+   ```bash
+   # Install Codacy CLI
+   npm install -g codacy-coverage
+
+   # Run analysis
+   codacy-analysis-cli analyze --directory . --project-token $CODACY_PROJECT_TOKEN
+   ```
+
+By running these tools locally, you can identify and fix issues before pushing your code to GitHub, ensuring smoother CI/CD workflows.
+
 ## Developers

 ### AI-Powered Development
--- a/phpcs.xml
+++ b/phpcs.xml
@@ -0,0 +1,65 @@
+<?xml version="1.0"?>
+<ruleset name="WordPress Coding Standards">
+    <description>WordPress dev PHP_CodeSniffer ruleset.</description>
+
+    <!-- Check all PHP files in directory tree by default. -->
+    <file>.</file>
+
+	<exclude-pattern>*/vendor/*</exclude-pattern>
+	<exclude-pattern>*/bin/*</exclude-pattern>
+	<exclude-pattern>*/.github/*</exclude-pattern>
+	<exclude-pattern>*/tests/*</exclude-pattern>
+	<exclude-pattern>libs/</exclude-pattern>
+
+    <arg value="sp" />
+	<arg name="extensions" value="php" />
+	<arg name="basepath" value="." />
+	<arg name="parallel" value="8" />
+
+	<!-- Configs -->
+	<config name="minimum_supported_wp_version" value="5.2" />
+
+	<!-- Rules -->
+	<rule ref="WordPress">
+		<exclude name="WordPress.NamingConventions.ValidVariableName" />
+		<exclude name="WordPress.CodeAnalysis.AssignmentInCondition.FoundInWhileCondition" />
+
+		<!-- Disable Strict comparison in array check. Not applicable in the mojority of cases. -->
+		<exclude name="WordPress.PHP.StrictInArray" />
+
+		<exclude name="WordPress.WP.I18n" />
+
+		<exclude name="WordPress.Files.FileName.InvalidClassFileName" />
+		<exclude name="WordPress.DB.DirectDatabaseQuery.NoCaching" />
+
+		<exclude name="Universal.ControlStructures.DisallowAlternativeSyntax.FoundIfWithInlineHTML" />
+		<exclude name="Universal.ControlStructures.DisallowAlternativeSyntax.FoundForeachWithInlineHTML" />
+		<exclude name="Universal.ControlStructures.DisallowAlternativeSyntax.FoundIf" />
+		<exclude name="Universal.ControlStructures.IfElseDeclaration.NoNewLine" />
+		<exclude name="Universal.Classes.RequireFinalClass.NonFinalClassFound" />
+		<exclude name="Universal.Namespaces.EnforceCurlyBraceSyntax.Forbidden" />
+
+		<exclude name="Generic.Commenting.Todo" />
+		<exclude name="Generic.CodeAnalysis.AssignmentInCondition.FoundInWhileCondition" />
+		<exclude name="Generic.CodeAnalysis.EmptyStatement.DetectedCatch" />
+		<exclude name="Generic.WhiteSpace.DisallowSpaceIndent" />
+		<exclude name="WordPress.WP.CapitalPDangit.Misspelled" />
+	</rule>
+
+	<rule ref="Generic.WhiteSpace.ScopeIndent">
+		<properties>
+			<property name="indent" value="4"/>
+			<property name="tabIndent" value="false"/>
+		</properties>
+	</rule>
+
+	<rule ref="Generic.WhiteSpace.DisallowTabIndent" />
+
+	<rule ref="Generic.Formatting.MultipleStatementAlignment">
+		<properties>
+			<property name="maxPadding" value="1" />
+			<property name="error" value="false" />
+		</properties>
+	</rule>
+
+</ruleset>
--- a/phpstan.neon
+++ b/phpstan.neon
@@ -5,12 +5,13 @@ parameters:
        - admin
        - wp-plugin-starter-template.php
    excludePaths:
-        - vendor
-        - node_modules
-        - tests
-        - bin
-        - build
-        - dist
+        analyseAndScan:
+            - vendor
+            - node_modules (?)
+            - tests
+            - bin (?)
+            - build (?)
+            - dist (?)
    ignoreErrors:
        - '#Function apply_filters invoked with [0-9]+ parameters, 2 required.#'
        - '#Function do_action invoked with [0-9]+ parameters, 1 required.#'