diff --git a/.cursor/rules/core-development.mdc b/.cursor/rules/core-development.mdc index bd5d4e671..a7cf0cb49 100644 --- a/.cursor/rules/core-development.mdc +++ b/.cursor/rules/core-development.mdc @@ -24,11 +24,11 @@ Do not affirm my statements or assume my conclusions are correct. Question assum ## Coding Standards - Plan before coding, explain reasoning for complex suggestions -- No code comments - write self-explanatory code +- Follow the code comment guidance in `AGENTS.md` - Keep imports alphabetically sorted - Keep code SOLID but simple - separation of concerns without over-engineering -- Aim to keep files under 300 lines - split when it improves clarity -- Write tests for critical paths only. Use AAA pattern. +- Treat file length as a signal; split only for reuse, meaningful separation, or clearer testing +- Follow the testing requirements in `AGENTS.md`. Use the AAA pattern. - Run `npm run lint` for lint check ## Prohibited Actions diff --git a/.cursor/rules/declarative-react.mdc b/.cursor/rules/declarative-react.mdc index cf8b2d28d..3dcd72406 100644 --- a/.cursor/rules/declarative-react.mdc +++ b/.cursor/rules/declarative-react.mdc @@ -15,7 +15,7 @@ Always write React code in a declarative style. 3. Use hooks (`useState`, `useReducer`, `useEffect`, `useMemo`, `useCallback`) responsibly: - Avoid running imperative logic in `useEffect` that can be expressed through declarative data-flow. - Derive data instead of duplicating state. -4. Build UI by **composing** smaller components. Prefer conditional rendering (`{condition && }`) and array mapping to create lists. +4. Separate components when doing so clarifies responsibility or enables reuse. Prefer conditional rendering (`{condition && }`) and array mapping to create lists. 5. Keep side-effects isolated; only place effectful code inside `useEffect`, `useLayoutEffect`, or custom hooks. 6. Use **refs** sparingly and only for non-DOM data persistence, not for styling or visibility toggling. 7. Prefer **controlled components** for forms. Keep input values in React state. @@ -24,6 +24,8 @@ Always write React code in a declarative style. 10. Favor pure functions and immutable data patterns to make render output predictable. 11. **Avoid cascading state updates**: Never create chains where updating one state triggers a `useEffect` that updates another state. Instead, derive values using `useMemo` or calculate them during render. 12. **Prefer direct state updates over useEffect chains**: When you need to update multiple related state values, do it directly in the event handler rather than creating cascading useEffect dependencies. +13. **Keep hooks non-visual**: Custom hooks return state and actions, not rendered elements. +14. **Avoid trivial memoization**: Calculate inexpensive derived values during render instead of wrapping them in `useMemo` or `useCallback`. ## Anti-Patterns to Avoid diff --git a/.cursor/rules/development-guidelines.mdc b/.cursor/rules/development-guidelines.mdc index bc581baf9..955cc8549 100644 --- a/.cursor/rules/development-guidelines.mdc +++ b/.cursor/rules/development-guidelines.mdc @@ -17,17 +17,14 @@ alwaysApply: true ## File Organization -- Break code into multiple smaller files instead of creating large monolithic files - Keep files focused on a single responsibility or closely related functionality -- Aim for files under 200-300 lines when possible -- Split large components, services, or modules into logical sub-modules +- Treat file length as a signal; split only for reuse, meaningful separation, or clearer testing +- Avoid single-use helper files and pass-through abstractions - Use clear directory structure to organize related files ## Testing Requirements -- Write tests for all new code functionality -- Add tests when modifying existing code to ensure no regressions -- Focus on testing the most critical paths and edge cases +- Follow the testing requirements in `AGENTS.md` - Follow existing testing patterns and conventions in the codebase - Ensure tests are deterministic and properly isolated diff --git a/.cursor/rules/development-workflow.mdc b/.cursor/rules/development-workflow.mdc index 00412cb51..f2aa448fa 100644 --- a/.cursor/rules/development-workflow.mdc +++ b/.cursor/rules/development-workflow.mdc @@ -17,13 +17,13 @@ alwaysApply: true ## During Development 1. **Follow Patterns**: Use existing patterns and conventions -2. **Write Tests**: Add tests for critical paths +2. **Write Tests**: Follow the testing requirements in `AGENTS.md` 3. **Type Safety**: Use TypeScript strictly 4. **Document APIs**: Document all public interfaces ## After Implementation -1. **Run Tests**: Ensure all tests pass +1. **Run Tests**: Run and verify the merge gate required by `AGENTS.md` before release integration 2. **Lint Code**: Fix any linting issues 3. **Check Dependencies**: Verify no circular dependencies 4. **Test Integration**: Verify with other packages diff --git a/.cursor/rules/general-code-style.mdc b/.cursor/rules/general-code-style.mdc index 5984d4e72..8cbc1fdbe 100644 --- a/.cursor/rules/general-code-style.mdc +++ b/.cursor/rules/general-code-style.mdc @@ -22,7 +22,8 @@ alwaysApply: true ## Self-Documented Code - Avoid adding comments that can be a constant or a well-named function -- Always prefer to create small functions that describe themselves +- Prefer existing or local functions for small, stateless, single-use behavior; extract helpers when they provide reuse + or meaningful separation - Only add comments to explain "why" when it is truly not understandable from the code itself - Do NOT add comments that explain "what" the code does (the code should be self-explanatory) - Examples of unnecessary comments to avoid: diff --git a/.cursor/rules/wordpress.mdc b/.cursor/rules/wordpress.mdc index e4d0aa3d0..bc4708413 100644 --- a/.cursor/rules/wordpress.mdc +++ b/.cursor/rules/wordpress.mdc @@ -12,7 +12,8 @@ You are an expert in WordPress, PHP, and related web development technologies. - Provide precise, technical PHP and WordPress examples - Adhere to PHP and WordPress best practices for consistency and readability -- Emphasize object-oriented programming (OOP) for better modularity +- Use OOP for state, lifecycle, contracts, or reusable behavior; prefer existing or local functions for small, stateless, + single-use behavior - Focus on code reusability through iteration and modularization, avoiding duplication - Use descriptive and meaningful function, variable, and file names - Directory naming conventions: lowercase with hyphens (e.g., wp-content/themes/my-theme) @@ -22,7 +23,8 @@ You are an expert in WordPress, PHP, and related web development technologies. - Utilize features of PHP 7.4+ (e.g., typed properties, arrow functions) where applicable - Follow WordPress PHP coding standards throughout the codebase -- Enable strict typing by adding `declare(strict_types=1);` at the top of PHP files +- Prefer `declare(strict_types=1);` in appropriate new or already-strict code; do not add it as unrelated cleanup in + existing integration files - Leverage core WordPress functions and APIs wherever possible - Maintain WordPress theme and plugin directory structure and naming conventions - Implement robust error handling: @@ -34,11 +36,11 @@ You are an expert in WordPress, PHP, and related web development technologies. - For database interactions: - Use WordPress's `$wpdb` abstraction layer - Apply `prepare()` statements for all dynamic queries to prevent SQL injection - - Use the `dbDelta()` function for managing database schema changes + - Use the `dbDelta()` function for schema changes only after custom storage is justified under `AGENTS.md` ## Dependencies -- Ensure compatibility with the latest stable version of WordPress +- Ensure compatibility with the repository's minimum supported WordPress and PHP versions - Use Composer for dependency management in advanced plugins or themes ## WordPress Best Practices diff --git a/AGENTS.md b/AGENTS.md index dc50d2700..80bf88ea6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -103,7 +103,8 @@ plugins. - Namespace: `Code_Snippets\` — all new classes must live under this namespace and be PSR-4 autoloaded. - Vendor dependencies: always use the prefixed namespace `Code_Snippets\Vendor\…` (Imposter-prefixed). -- Guard direct execution at the top of every standalone file: `defined('ABSPATH') || exit;` +- Guard direct execution at the top of executable entry points and procedural files with + `defined('ABSPATH') || exit;`; do not add guards to autoloaded class files. - Use `wp_die()` for fatal admin errors; never `die()` or `exit` with user-facing output. - In `src/php/Plugin.php` (and Core bootstrap), rely on `autoload.php`; avoid manual `require_once` chains. - Avoid creating custom database tables. Prefer WordPress-native storage: `wp_options` for settings/flags, transients @@ -127,8 +128,11 @@ plugins. - Prefer direct state updates in event handlers over using `useEffect` to synchronize multiple state values. - Use controlled components for forms; keep input values in React state. - Derive computed values at render-time rather than duplicating them in separate state. -- **Component composition**: Break components into smaller, focused units. Use JSX for markup rather than - `createElement` in utility functions. +- **Hooks**: Hooks return state and actions, not rendered elements. +- **Clarity**: Avoid nested ternaries, trivial memoization, unnecessary ARIA roles, and props that repeat component + defaults. +- **Component composition**: Separate components when doing so clarifies responsibility or enables reuse. Use JSX for + markup rather than `createElement` in utility functions. - Do not create 'index.ts' barrel files for components or hooks; import them directly to avoid circular dependencies and improve tree-shaking. - Reuse existing functions and components where possible, creating new common components under @@ -140,10 +144,10 @@ plugins. ### Code Organization -- Keep individual source files under 300 lines to improve maintainability and testability; split larger files into - focused modules. -- Maintain a direct mapping between source classes and their test files; if a test file grows large, consider whether - the source class can be broken into smaller concerns. +- Treat file length as a signal, not a reason to split cohesive code. Extract code only for reuse, meaningful separation, + or clearer testing; avoid single-use and pass-through abstractions. +- Maintain a direct mapping between source classes and their test files; split source classes and tests only when doing + so creates a meaningful separation or clearer testing boundary. --- @@ -154,6 +158,8 @@ plugins. plugins using the same libraries. - **Snippet model** — core data unit is `Code_Snippets\Model\Snippet`; use its API for reading/writing snippet data, not raw DB access. +- **Data boundaries** — models preserve data, remote response decoding normalizes remote data, and rendering handles + presentation sanitation and escaping. - **Hook-driven extensibility** — use WordPress filters and actions as the primary extension mechanism; expose a filter before changing any default behaviour that may be preference-driven. - **Safe mode** — `src/php/Core/load.php` boots a recovery path when safe mode is active; any change to snippet @@ -168,8 +174,11 @@ plugins. - **Development branches:** `feat/…`, `fix/…`, `chore/…`, `hotfix/…` - Branch from `core-beta` for all feature and fix work. - Open PRs back into `core-beta`. -- Use **merge commits** (not squash/rebase) when merging dev branches into `core-beta`. +- Preserve granular history during development and use merge commits for active stack propagation. Squash-merging a + large, fully reviewed chain into `core-beta` is preferred after explicit approval and a passing chain-peak matrix. - Hotfixes branch from `core` and merge directly back into `core`. +- Intermediate stacked PRs may fail when the failure is understood and fixed later in the same chain. The current chain + peak must pass the complete required matrix before release integration. ### Commit Messages