Skip to content

Commit 64f5101

Browse files
matthieu-crouzetmatthieu-crouzet
committed
feat: add windsurf rules
1 parent 65c98d7 commit 64f5101

File tree

8 files changed

+265
-0
lines changed

8 files changed

+265
-0
lines changed

‎.windsurf/rules/code-style-typescript.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
trigger: glob
3+
globs: **/*.ts
4+
---
5+
6+
# Otter Framework - TypeScript/JavaScript Code Style
7+
8+
## General Formatting
9+
10+
All formatting rules (charset, indentation, line endings, etc.) are defined in `.editorconfig` at the repository root. Refer to that file for the configuration.
11+
12+
## TypeScript / JavaScript Conventions
13+
14+
- **Always write JSDoc comments** for methods and properties using `/** ... */` pattern
15+
- **Properties must have the most restricted type possible**:
16+
```typescript
17+
// Bad
18+
private type: string;
19+
20+
// Good
21+
private type: 'A' | 'B';
22+
```
23+
- **Imports must be at the top of the file** - never in the middle of code
24+
- **Follow existing ESLint rules** defined in `packages/@o3r/eslint-config`
25+
- **Use `const` by default**, `let` only when reassignment is needed, never `var`
26+
27+
## File Organization
28+
29+
- **One class/interface per file** when possible
30+
- **Keep files focused** - split large files into smaller, focused modules
31+
- **Co-locate tests** with source files (e.g., `foo.service.ts` and `foo.service.spec.ts`)

‎.windsurf/rules/commands.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
trigger: always_on
3+
---
4+
5+
# Otter Framework - Commands
6+
7+
## Build
8+
9+
```bash
10+
yarn build # Full build (includes TS and JAR targets)
11+
yarn build:ts # TypeScript-only build (preferred for local dev)
12+
```
13+
14+
## Lint
15+
16+
```bash
17+
yarn lint # Full lint (mandatory before any PR)
18+
```
19+
20+
## Tests
21+
22+
```bash
23+
yarn test # Unit tests (mandatory before any PR)
24+
yarn test-e2e # E2E tests (Playwright)
25+
yarn test-int # Integration tests (requires Verdaccio)
26+
```
27+
28+
## Per-project commands (Nx)
29+
30+
```bash
31+
yarn nx build <project>
32+
yarn nx lint <project>
33+
yarn nx test <project>
34+
```
35+
36+
## Validation Workflow
37+
38+
Before considering changes complete, always run:
39+
40+
```bash
41+
yarn build # Full build
42+
yarn lint # Linting
43+
yarn test # Unit tests
44+
```

‎.windsurf/rules/documentation.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
trigger: always_on
3+
---
4+
5+
# Otter Framework - Documentation Requirements
6+
7+
## Code Documentation
8+
9+
- **Always write description comments** for public methods, classes, and properties
10+
- **Use JSDoc format**: `/** Your comment */`
11+
- **Document parameters and return types** for complex functions
12+
- **Add `@deprecated` tag** when deprecating code, mentioning the major version for removal
13+
14+
## Example
15+
16+
```typescript
17+
/**
18+
* Calculates the total price including tax.
19+
* @param basePrice - The base price before tax
20+
* @param taxRate - The tax rate as a decimal (e.g., 0.2 for 20%)
21+
* @deprecated Will be removed in v15. Use `calculatePriceWithTax()` instead.
22+
*/
23+
public calculateTotal(basePrice: number, taxRate: number): number {
24+
return basePrice * (1 + taxRate);
25+
}
26+
```

‎.windsurf/rules/git-ci.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
trigger: always_on
3+
---
4+
5+
# Otter Framework - Git & CI
6+
7+
## Commit Message Format
8+
9+
Follow [Conventional Commits](https://www.conventionalcommits.org/). Allowed types are defined in `commitlint.config.cts`:
10+
11+
| Type | Purpose |
12+
|------|---------|
13+
| `feat` / `feature` | New feature |
14+
| `fix` / `bugfix` | Bug fix |
15+
| `docs` | Documentation changes |
16+
| `refactor` | Code refactoring (no behavior change) |
17+
| `perf` | Performance improvement |
18+
| `test` | Adding or updating tests |
19+
| `build` | Build system or dependencies |
20+
| `ci` | CI configuration |
21+
| `chore` | Maintenance tasks |
22+
| `style` | Code style (formatting, no logic change) |
23+
| `revert` | Reverting a previous commit |
24+
| `deprecate` | Deprecating functionality |
25+
| `improvement` | General improvement |
26+
27+
```bash
28+
# Examples
29+
git commit -m "fix: correct null check in service"
30+
git commit -m "feat(core): add new validation helper"
31+
git commit -m "docs: update API documentation"
32+
git commit -m "refactor!: rename config options" # Breaking change
33+
```
34+
35+
**Rules** (from `commitlint.config.cts`):
36+
- Header max length: **100 characters**
37+
- Subject must not be empty or end with a period
38+
- Type and scope must be lowercase
39+
40+
## CI Contract - Do Not Break
41+
42+
- **All required CI jobs must remain green**: build, lint, unit tests, IT tests, E2E tests
43+
- **Do not modify CI workflows** (`.github/workflows/*`) unless explicitly requested
44+
- **Do not touch release/versioning/publish flows**: `GitVersion.yml`, `release.yml`, `publish.yml`
45+
- **All changes must go through Pull Requests** - never publish directly

‎.windsurf/rules/project-structure.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
trigger: always_on
3+
---
4+
5+
# Otter Framework - Project Structure Reference
6+
7+
## Directory Layout
8+
9+
```
10+
├── apps/ # Applications (showcase, extensions, etc.)
11+
├── packages/
12+
│ ├── @o3r/* # Core Otter framework libraries
13+
│ ├── @ama-sdk/* # SDK-related packages
14+
│ ├── @ama-openapi/* # OpenAPI tooling
15+
│ ├── @ama-styling/* # Styling/design tooling
16+
│ ├── @ama-mcp/* # MCP tooling
17+
│ └── @ama-mfe/* # Micro-frontend utilities
18+
├── tools/
19+
│ ├── github-actions/* # Local GitHub Actions
20+
│ └── @o3r/* # Internal build/test helpers
21+
├── docs/ # Documentation
22+
└── migration-guides/ # Version migration guides
23+
```
24+
25+
## Package Scopes
26+
27+
| Scope | Purpose | Angular |
28+
|-------|---------|---------|
29+
| `@o3r/*` | Core Otter framework libraries | Yes |
30+
| `@ama-sdk/*` | SDK generation and client utilities | Partial |
31+
| `@ama-openapi/*` | OpenAPI tooling and CLI | No |
32+
| `@ama-styling/*` | Styling and design tooling | No |
33+
| `@ama-mcp/*` | MCP (Model Context Protocol) tooling | No |
34+
| `@ama-mfe/*` | Micro-frontend utilities | Yes |
35+
36+
## Additional Resources
37+
38+
- [CONTRIBUTING.md](./CONTRIBUTING.md) - Full contribution guidelines
39+
- [packages/@o3r/eslint-config](./packages/@o3r/eslint-config/README.md) - ESLint configuration

‎.windsurf/rules/repository-overview.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
trigger: always_on
3+
---
4+
5+
# Otter Framework - Repository Overview
6+
7+
## Type
8+
9+
Large Nx-powered monorepo for the **Otter Framework**
10+
11+
## Purpose
12+
13+
Highly modular Angular-based framework and tooling to accelerate building Angular web apps:
14+
- Reusable Angular libraries (`packages/@o3r/*`, `@ama-sdk/*`, `@ama-openapi/*`, `@ama-mcp/*`, `@ama-mfe/*`, `@ama-styling/*`)
15+
- Dev tools (VS Code / Chrome extensions, GitHub Actions, CLIs, design tooling, OpenAPI tooling)
16+
- Showcase app (`apps/showcase`) and other apps
17+
18+
## Main Tech Stack
19+
20+
- Angular 20, TypeScript, RxJS, Redux-style patterns
21+
- Nx 21 monorepo tooling
22+
- Jest for unit/integration tests, Playwright for e2e
23+
- ESLint (flat config), Stylelint, Husky, lint-staged
24+
25+
## Layout
26+
27+
Root monorepo with `apps/`, `packages/`, and `tools/` as main code roots

‎.windsurf/rules/runtime-setup.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
trigger: always_on
3+
---
4+
5+
# Otter Framework - Runtime & Setup
6+
7+
## Runtime Requirements
8+
9+
**Always respect the runtime constraints declared in `package.json`.**
10+
11+
- **Node.js**: Use a version satisfying `engines.node` field in root `package.json` (currently `^20.19.0 || ^22.17.0 || ^24.0.0`)
12+
- **Yarn**: Use Yarn 4 with Plug'n'Play (`.pnp.cjs`). **Never use `npm install` or `pnpm`**
13+
- **Package manager**: Defined by `packageManager` field in root `package.json`
14+
15+
## Setup and Bootstrap
16+
17+
From repo root:
18+
19+
```bash
20+
# Install dependencies (always first)
21+
yarn install
22+
23+
# Optional: clear Nx cache when debugging
24+
yarn nx reset
25+
```

‎.windsurf/rules/testing.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
trigger: always_on
3+
---
4+
5+
# Otter Framework - Testing Requirements
6+
7+
## General Testing Guidelines
8+
9+
- **Add relevant unit tests** for all new code
10+
- **E2E tests must pass** - check screenshot update process if visual tests fail
11+
- **Follow existing test patterns** in the codebase
12+
13+
## Test Frameworks
14+
15+
- **Use Jest** for unit tests
16+
- **Use Playwright** for e2e tests
17+
18+
## Test File Naming
19+
20+
- Unit tests: `*.spec.ts` (co-located with source files)
21+
- E2E tests: Located in `e2e-playwright/` directories
22+
23+
## Best Practices
24+
25+
- **Test behavior, not implementation** - focus on what the code does, not how
26+
- **Use descriptive test names** - clearly state what is being tested
27+
- **Keep tests independent** - each test should be able to run in isolation
28+
- **Mock external dependencies** - use Jest mocks for services, HTTP calls, etc.

0 commit comments

Comments
 (0)