Implement includes, config file support & .distignore parsing (#1108, #1159)

[faisalahammad]

Description

This PR introduces comprehensive enhancements to how the Plugin Check tool filters files. It adds support for CLI include options, configuration files (.plugin-check.json), and automatic .distignore parsing. This addresses both #1108 (CLI includes) and #1159 (Admin UI exclusions via backend logic).

Why This Change Is Needed

Currently, the tool only supports excluding files/directories via CLI flags. There is no way to:

1. Whitelist files: Check only specific files or folders (useful for CI/CD or focused development).
2. Persist settings: Save exclusion/inclusion rules so they don't need to be typed every time.
3. Respect distribution rules: Automatically ignore files that won't be in the final plugin zip (like tests/, node_modules/, etc.) by reading .distignore.

How It Solves The Issue

1. New CLI Options

Added --include-files and --include-directories to the check command.

• These are mutually exclusive with their exclude counterparts to prevent ambiguity.
• --include-directories works recursively.

2. Configuration File Support

The tool now looks for a .plugin-check.json file in the plugin root.
Example:

{
  "exclude-directories": ["tests", "vendor"],
  "include-files": ["plugin.php"]
}

3. .distignore Support

If a .distignore file exists, its patterns are automatically parsed and added to the exclusion list.

• Supports standard glob patterns (e.g., *.md, build/).
• Converted to regex internally for precise matching.

4. Hybrid Priority System

To ensure predictable behavior, we implemented a strict priority order:

1. CLI Arguments (Highest priority - overrides everything)
2. Configuration File (.plugin-check.json)
3. .distignore (if present)
4. Defaults (Lowest - e.g., .git, node_modules)

Verification

I have added comprehensive unit tests to verify:

• CLI Validation: Ensures you can't mix include/exclude options.
• Config Parsing: Validates JSON structure and merging logic.
• Distignore Parsing: Tests standard gitignore-style patterns (comments, globs, directories).
• Integration: tested the full file scanning and filtering pipeline.

Run the new tests:

vendor/bin/phpunit --bootstrap tests/phpunit/includes/isolated-bootstrap.php tests/phpunit/tests/Utilities/Distignore_Parser_Tests.php
vendor/bin/phpunit --bootstrap tests/phpunit/tests/Checker/Checks/Abstract_File_Check_Ignore_Test.php

Before vs After

Before:
User has to manually type long exclude strings every time:

wp plugin check my-plugin --exclude-directories=tests,bin,node_modules,vendor

After:
User can just run:

wp plugin check my-plugin

(And the tool automatically respects .distignore and .plugin-check.json)

OR user can check just one file:

wp plugin check my-plugin --include-files=includes/admin.php

Checklist

• Documentation updated (CLI help)
• Unit tests added
• Code follows WordPress coding standards

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: faisalahammad <faisalahammad@git.wordpress.org>
Co-authored-by: mukeshpanchal27 <mukesh27@git.wordpress.org>
Co-authored-by: davidperezgar <davidperez@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[mukeshpanchal27]

Suggested change

[davidperezgar]

Thanks for your contribution!
You need to fix tests before we review this PR.