Merge pull request #2849 from Strategy11/feature/windsurf-configuration-formidable

Add comprehensive Windsurf configuration for Formidable Forms development

Author: Crabcyborg

.gitattributes

@@ -17,6 +17,7 @@
 .php-cs-fixer.cache export-ignore
 .wp-env.json export-ignore
 .coderabbit.yaml export-ignore
+.windsurf export-ignore
 cypress.config.js export-ignore
 /bin/ export-ignore
 changelog.txt export-ignore
@@ -45,6 +46,7 @@ mago.toml export-ignore
 /resources/ export-ignore
 webpack.dev.js export-ignore
 .browserslistrc export-ignore
+/eslint-rules/ export-ignore
 /phpcs-sniffs/ export-ignore
 .deepsource.toml export-ignore
 .semgrepignore export-ignore

.windsurf/.editorconfig

@@ -0,0 +1,7 @@
+# Override parent EditorConfig for .windsurf/ markdown files
+# Code blocks in these rule files must use WP coding standards (tabs, indent_size 4)
+# while all other .md files in the project keep space/2 from the root config.
+
+[*.md]
+indent_style = tab
+indent_size = 4

.windsurf/.markdownlint.json

@@ -0,0 +1,8 @@
+{
+	"default": true,
+	"MD003": { "style": "atx" },
+	"MD007": { "indent": 4 },
+	"MD013": { "line_length": 9999 },
+	"no-hard-tabs": false,
+	"whitespace": false
+}

.windsurf/rules/enterprise/code-change-principles.md

@@ -0,0 +1,104 @@
+---
+trigger: always_on
+description: Enterprise code change principles for safe, minimal-scope modifications.
+---
+
+# Enterprise Code Change Principles
+
+Critical principles for enterprise-level plugin development.
+
+---
+
+## Core Principles
+
+1. **NEVER guess**: Always search and verify before making changes
+2. **Minimal scope**: Fix at the most specific location, closest to the problem
+3. **Backward compatibility**: Maintain 100% compatibility with existing callers
+4. **No custom solutions**: Never invent new patterns. Use existing ones or search the web to review best practices, then follow the official WordPress standards or VIP guidelines.
+5. **User changes are final**: If user makes manual changes, treat as authoritative
+6. **Multi-issue fixes**: When fixing multiple issues in one request, run all 6 phases independently for each issue. Findings from one issue's phases may inform the next, but every phase is mandatory for every issue, even when issues share a root cause.
+
+---
+
+## Analysis Phase
+
+Before proposing solutions:
+
+### Phase 1: Understand
+
+- Read and understand the complete issue
+- Clarify expected vs actual behavior
+- Identify reproduction steps
+- Determine scope: which plugin(s), which feature(s)
+- **Cross-plugin**: Identify if the feature or setting exists in Lite, Pro, or both. Understand the full feature context across all relevant plugins
+    - Working on an addon: research must include Lite AND Pro
+    - Working on Pro: research must include Lite
+    - Working on Lite: check if the change affects Pro or any active addon
+
+### Phase 2: Locate
+
+- Use code_search to find the root cause (not just symptoms)
+- Trace execution flow from entry point to failure
+- **Analyze complete context** of the class or file being changed — all features, logic, and flows
+- **Trace parent hierarchy**: search parent classes and files up to plugin root
+- **CSS-Specific Rules - Trace complete style cascade**: When debugging CSS on an element, identify ALL classes on the element and its ancestors, then search for ALL CSS rules affecting it (not just the obvious class). Understand the complete cascade before proposing changes
+- Identify ALL affected locations in the codebase
+- Map dependencies: what calls this code, what does this code call
+- Check plugin requirements: must code work standalone or require Pro/addons
+- **Cross-plugin**: Search for the same feature, helper, or code path in Lite and Pro (and addons if relevant). Understand how data flows between plugins
+
+### Phase 3: Research
+
+- **Never invent custom solutions if existing patterns exist**
+- Find existing patterns: search models, controllers, helpers, views for similar functionality
+- Study pattern usage: search ALL places using the pattern
+- Search official WordPress/VIP docs: function parameters, return types, deprecated alternatives
+- Search platform-specific docs: performance and security best practices
+- Verify alignment: ensure approach matches existing codebase patterns
+- **Cross-plugin**: Search for existing patterns and helpers in Lite and Pro that already solve the problem. Reuse them instead of inventing new solutions
+- **Iterate**: if a better pattern is found, repeat from Phase 2
+
+---
+
+## Solution Phase
+
+### Phase 4: Select Solution
+
+- Propose 2-3 solutions with trade-offs clearly stated
+- Select the solution with minimal scope and lowest risk
+- Fix at the most specific location, closest to root cause
+- Prefer adding safety checks over refactoring
+- Fix must be testable without touching other code
+- **Verify changes are not overkill**: If affecting several areas, review everything carefully to make sure the fix is not excessive. If it is, go back to Phase 2
+
+---
+
+## Change Phase
+
+### Phase 5: Implement
+
+- Never refactor unrelated code in the same commit
+- If a rule conflicts with existing code in the file being modified, follow the rule for new code but do not refactor unrelated existing code
+- Make the smallest change that completely solves the problem
+- **CSS-Specific Rules - Never modify shared CSS classes**: If a CSS class is already used elsewhere in the plugin, do not change its behavior. Instead, add a new specific class for the feature and define new styles for it
+- Use Big-O to compare algorithms and choose the most efficient one for large inputs and iterations
+- Never change method signatures, return types, or data structures
+- Add defensive checks where data comes in, not where used everywhere
+- Add PHPDoc/JSDoc for new methods/properties/functions and comments for complex logic
+- Never guess the version number and use `@since x.x` as the version placeholder in docblocks
+
+---
+
+## Change Verification Phase
+
+### Phase 6: Verify
+
+- Confirm fix resolves the reported issue
+- Confirm backward compatibility with existing callers
+- Confirm this change does not break any existing functionality
+- Test with Pro plugin active AND inactive
+- Test with empty data and missing keys
+- Confirm no PHP warnings, notices, or errors in any scenario
+- Test edge cases
+- Remove all debug code (error_log statements, debug comments, debug files)
+- Verify code passes phpcs/linting checks

.windsurf/rules/enterprise/conventional-commits.md

@@ -0,0 +1,127 @@
+---
+trigger: always_on
+description: Enforces conventional commit message format for all git commits in the project.
+---
+
+# Conventional Commit Messages
+
+All commit messages MUST follow the Conventional Commits 1.0.0 specification.
+
+## Format
+
+```text
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+## Types
+
+| Type       | Description                                           | SemVer |
+| ---------- | ----------------------------------------------------- | ------ |
+| `fix`      | Bug fix (patches a bug in the codebase)               | PATCH  |
+| `feat`     | New feature (adds functionality to the codebase)      | MINOR  |
+| `docs`     | Documentation only changes                            | -      |
+| `style`    | Code style changes (formatting, whitespace, etc.)     | -      |
+| `refactor` | Code change that neither fixes a bug nor adds feature | -      |
+| `perf`     | Performance improvement                               | -      |
+| `test`     | Adding or correcting tests                            | -      |
+| `build`    | Changes to build system or external dependencies      | -      |
+| `ci`       | CI configuration changes                              | -      |
+| `chore`    | Other changes that don't modify src or test files     | -      |
+
+## Scope (Optional)
+
+The scope provides additional context about what part of the codebase the commit affects:
+
+- `builder`: Form builder related changes
+- `entries`: Entry management changes
+- `fields`: Field types or field handling
+- `api`: API endpoints or integrations
+- `admin`: Admin UI changes
+- `frontend`: Front-end form display
+- `db`: Database operations
+- `i18n`: Internationalization
+- `security`: Security fixes or improvements
+- `deps`: Dependencies
+
+## Breaking Changes
+
+Indicate breaking changes with:
+
+1. `!` after type/scope: `feat(api)!: change response format`
+2. `BREAKING CHANGE:` footer in the commit body
+
+## Examples
+
+```text
+fix(fields): resolve date field validation error
+
+The date field was incorrectly validating dates in non-US formats.
+Added locale-aware date parsing.
+```
+
+```text
+feat(builder): add drag-and-drop field reordering
+
+Implements smooth drag-and-drop functionality for reordering fields
+in the form builder interface.
+```
+
+```text
+fix: prevent XSS in field labels
+
+Escape HTML entities in field labels before output.
+```
+
+```text
+refactor(entries)!: change entry meta storage
+
+BREAKING CHANGE: Entry meta now uses JSON encoding instead of
+serialized PHP arrays. Run migration script before updating.
+```
+
+## Character Limits (50/72 Rule)
+
+The 50/72 rule is a Git convention for readable commit messages:
+
+| Element      | Limit         | Reason                                                  |
+| ------------ | ------------- | ------------------------------------------------------- |
+| Subject line | 50 characters | GitHub truncates at 72, but 50 is ideal for readability |
+| Body lines   | 72 characters | Matches terminal width and Git log formatting           |
+
+**Subject Line (50 chars):**
+
+- Forces concise, scannable summaries
+- Displays fully in `git log --oneline`
+- GitHub shows full title without truncation
+
+**Body Lines (72 chars):**
+
+- Readable in terminals and Git interfaces
+- Prevents awkward line breaks
+- Matches email format conventions
+
+---
+
+## Rules
+
+1. Type MUST be lowercase.
+2. Description MUST start with lowercase letter.
+3. Description MUST NOT end with a period.
+4. Description MUST be imperative mood ("add" not "added" or "adds").
+5. Body MUST be separated from description by a blank line.
+6. Breaking changes MUST be indicated with `!` or `BREAKING CHANGE:` footer.
+7. Subject line MUST be 50 characters or fewer.
+8. Body lines MUST wrap at 72 characters.
+
+## AI Commit Message Generation
+
+When generating commit messages:
+
+1. Analyze the staged changes to determine the appropriate type.
+2. Identify the scope from the files/directories changed.
+3. Write a concise description in imperative mood.
+4. Add body with details if the change is complex.

.windsurf/rules/enterprise/principles.md

@@ -0,0 +1,23 @@
+---
+trigger: always_on
+description: Baseline rules that apply across the entire Formidable Forms plugin ecosystem.
+---
+
+# General Principles
+
+Baseline rules that apply across the Formidable Forms plugin ecosystem.
+
+## Writing Style for Generated Text
+
+Applies to all generated text: PR titles, PR body, commit messages, comments, and etc.
+
+- **No em dashes** (`—` or `–`): use commas, periods, or rewrite the sentence
+- **No semicolons** (`;`): split into separate sentences instead
+- **Full GitHub URL** for issue references (e.g., `https://github.com/Strategy11/formidable-pro/issues/3030`), never shorthand `#number` (PRs may target a different repo than the issue)
+- **No hard-wrapping** in PR body text: let GitHub handle line wrapping. The 72-char wrap rule applies only to **commit message bodies**
+
+---
+
+## PHPDoc/JSdoc Parameter Descriptions
+
+PHPDoc/JSdoc `@param` descriptions must be concise and describe what the parameter contains. Never document a parameter as "Unused", always describe its content, even when it is present only for hook/filter signature compatibility.