|
1 | | -# PleaseAI Code Style Rules |
2 | | - |
3 | | -Canonical rules for `@pleaseai/code-style`. The `@pleaseai/eslint-config` package |
4 | | -(based on `@antfu/eslint-config`) is the single source of truth — this document |
5 | | -summarises the parts that an AI coding assistant needs to know _before_ writing |
6 | | -code, so generated output passes lint on the first try. |
7 | | - |
8 | | -## Formatting |
9 | | - |
10 | | -- **No semicolons** at the end of statements. |
11 | | -- **Single quotes** for strings; template literals are fine when interpolating. |
12 | | -- **2-space indentation**, never tabs. |
13 | | -- **Trailing commas** in multi-line arrays, objects, and parameter lists. |
14 | | -- **LF** line endings. |
15 | | -- Soft line length ~100, hard limit 120. |
16 | | - |
17 | | -## Modules |
18 | | - |
19 | | -- **ESM only** (`"type": "module"`). Never emit `require`/`module.exports`. |
20 | | -- Use `import` / `export` statements. |
21 | | -- Source extensions: `.ts`, `.tsx`, `.mjs`, `.mts`. |
22 | | -- Import ordering (auto-fixable): node builtins → external → internal aliases → |
23 | | - parent → sibling → index, with a blank line between groups and alphabetised |
24 | | - within each group. |
25 | | -- Use **named exports** so one name search finds the definition and every use. |
26 | | - Default exports are only for files whose shape a framework dictates (config |
27 | | - files, Nuxt 4 `app/pages/`/`app/layouts/`/`app/middleware/`/`app/plugins/`, Nitro |
28 | | - `server/api/`/`routes/`, Storybook stories). The `ts-no-default-export` |
29 | | - rule of `@pleaseai/ast-grep-config` lists the exact paths. |
30 | | - |
31 | | -## TypeScript |
32 | | - |
33 | | -- `target: ES2022`, `moduleResolution: bundler`. |
34 | | -- `strict: true` — no implicit `any`, no unchecked indexed access hacks. |
35 | | -- Prefer `type` aliases over `interface` unless `extends`/declaration merging |
36 | | - is actually needed. |
37 | | -- Use `const` by default; `let` only when reassignment is required; never `var`. |
38 | | -- Avoid `any`; use `unknown` and narrow, or define a precise type. |
39 | | -- Add explicit return types on exported functions and public class methods. |
40 | | -- No unused imports or variables (auto-removed by `eslint --fix`). |
41 | | - |
42 | | -## Code Quality |
43 | | - |
44 | | -- Prefer **early returns** over deeply nested conditionals. |
45 | | -- Use **optional chaining** (`?.`) and **nullish coalescing** (`??`). |
46 | | -- Prefer `async`/`await` over raw `.then()` chains. |
47 | | -- No `console.log` in production code paths — use a logger or remove before |
48 | | - commit. `console.warn`/`console.error` are acceptable for CLI tooling. |
49 | | -- Throw `Error` instances (or subclasses), never bare strings or objects. |
50 | | - |
51 | | -## File Organisation |
52 | | - |
53 | | -- One primary export per file when practical. A file with a single public |
54 | | - symbol is named after it in kebab-case (`UserService` → `user-service.ts`). |
55 | | -- Target file size ≤ 500 lines; split when a file grows past that. |
56 | | -- Put a module's error classes in its `errors.ts`. |
57 | | -- Avoid barrel re-exports (`index.ts` that just re-exports everything) for |
58 | | - internal modules — they defeat tree-shaking. |
59 | | - |
60 | | -## Testing |
61 | | - |
62 | | -- Tests live under the package's test root, `test/` or `tests/` (one per |
63 | | - package), at a path mirrored from the source they test, with a `.test.ts` |
64 | | - (or `.spec.ts`) suffix: |
65 | | - - one source root: drop its name — `src/foo/bar.ts` → `test/foo/bar.test.ts`; |
66 | | - - several roots (Nuxt 4 `app/`, `server/`, `shared/`): keep it — |
67 | | - `server/utils/db.ts` → `test/unit/server/utils/db.test.ts`. |
68 | | -- One environment segment is allowed directly under the test root: `unit`, |
69 | | - `nuxt`, `browser`, or `e2e`. End-to-end tests with no single source file go |
70 | | - under `test/e2e/`. |
71 | | -- Never write `*.test.ts` next to the source, and never use Vitest in-source |
72 | | - tests (`if (import.meta.vitest)`). |
73 | | -- Helpers shared by two or more test files go in the language's designated |
74 | | - location: `<test-root>/test-utils/` for TypeScript (`test/test-utils/` or |
75 | | - `tests/test-utils/`), `test/helpers/` for Dart, `src/testFixtures/` for |
76 | | - Kotlin and Java, and `tests/common/` for Rust. A helper used by one test file |
77 | | - stays in that file. |
78 | | -- Not every source file needs a test. These rules say where a test goes, not |
79 | | - whether it must exist. |
80 | | - |
81 | | -These are the ADR-0022 code-organization rules. Check them with `ast-grep scan` |
82 | | -(structural rules from `@pleaseai/ast-grep-config`) and `please-style check` |
83 | | -(file names and test paths); each `ast-grep scan` warning links to a README |
84 | | -that explains the fix. |
85 | | - |
86 | | -## JSON & `package.json` |
87 | | - |
88 | | -- `package.json` keys are sorted by `eslint-plugin-package-json`. |
89 | | -- Declare `engines.node` (>= 22 for PleaseAI projects). |
90 | | -- Libraries must ship an explicit `exports` map; no bare `main`-only fields. |
91 | | -- `"type": "module"` is required. |
92 | | - |
93 | | -## Commit Messages |
94 | | - |
95 | | -- Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, |
96 | | - `chore:`, `build:`, `ci:`, `perf:`, `style:`, `revert:`. |
97 | | -- Subject ≤ 72 chars, imperative mood, no trailing period. |
98 | | -- Body explains **why**, not **what** — the diff already shows the what. |
| 1 | +# Passion Factory Code Style Rules |
| 2 | + |
| 3 | +The rules are split by language. Read `rules/general.md` for the rules that |
| 4 | +apply to every language, then the guide for the language you are writing: |
| 5 | + |
| 6 | +- [`rules/general.md`](./rules/general.md) — every language |
| 7 | +- [`rules/typescript.md`](./rules/typescript.md) — TypeScript and JavaScript |
| 8 | +- [`rules/dart.md`](./rules/dart.md) — Dart and Flutter |
| 9 | +- [`rules/rust.md`](./rules/rust.md) — Rust |
| 10 | +- [`rules/java.md`](./rules/java.md) — Java |
| 11 | +- [`rules/go.md`](./rules/go.md) — Go |
| 12 | +- [`rules/python.md`](./rules/python.md) — Python |
| 13 | +- [`rules/ruby.md`](./rules/ruby.md) — Ruby |
| 14 | +- [`rules/csharp.md`](./rules/csharp.md) — C# |
| 15 | +- [`rules/html-css.md`](./rules/html-css.md) — HTML and CSS |
| 16 | + |
| 17 | +`pleaseai-code-style update` points your `AGENTS.md` block at the general and |
| 18 | +TypeScript guides; the other guides are read from this index for now. |
0 commit comments