@activatus/code-standards 3.3.1 → 3.3.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +28 -3
- package/docs/Guides/migrating.md +6 -6
- package/docs/Guides/regression-checks.md +9 -0
- package/docs/Guides/setup.md +29 -19
- package/docs/Standards/documentation.md +1 -0
- package/docs/Standards/eslint.md +10 -10
- package/docs/Standards/prettier.md +56 -5
- package/docs/Standards/readable-code.md +2 -2
- package/docs/Structure/folder-structure.md +61 -23
- package/docs/Structure/import-organization.md +31 -46
- package/docs/Structure/naming-conventions.md +1 -1
- package/docs/templates.mdx +14 -0
- package/docs/version-history.md +80 -5
- package/package.json +1 -1
- package/scripts/verifyStandards/checkComponents.mjs +2 -0
- package/scripts/verifyStandards/checkConstants.mjs +22 -48
- package/scripts/verifyStandards/checkStructure.mjs +60 -5
- package/scripts/verifyStandards/formatReport.mjs +1 -1
- package/scripts/verifyStandards/projectFiles.mjs +1 -46
- package/scripts/verifyStandards/recordedExceptions.mjs +176 -0
- package/scripts/verifyStandards/runChecks.mjs +23 -5
- package/static/templates/.prettierignore +7 -0
- package/static/templates/AGENTS.md +29 -26
- package/static/templates/docs/development/coding-standards.md +2 -2
- package/static/templates/eslint/base/eslint.config.mjs +2 -2
- package/static/templates/eslint/nextjs/eslint.config.mjs +2 -2
- package/static/templates/eslint/react/eslint.config.mjs +2 -2
- package/static/templates/eslint/typescript/eslint.config.mjs +2 -2
- package/static/templates/prettier.config.mjs +20 -2
|
@@ -71,11 +71,9 @@ project-root/
|
|
|
71
71
|
│ ├── constants/ # Constants shared across the app: see Constants below
|
|
72
72
|
│ │ ├── routes.ts # r: every link
|
|
73
73
|
│ │ ├── strings.ts # s: every piece of static text
|
|
74
|
-
│ │ ├── numbers.ts #
|
|
74
|
+
│ │ ├── numbers.ts # Numbers more than one file uses
|
|
75
75
|
│ │ ├── noData.ts # Stand-in data for local development
|
|
76
|
-
│ │ ├──
|
|
77
|
-
│ │ ├── artwork.ts # What is drawn and where, once there is any
|
|
78
|
-
│ │ ├── classNames.ts # Class names shared between files, once there are any
|
|
76
|
+
│ │ ├── status.ts # Statuses the app shares, once there are any
|
|
79
77
|
│ │ └── index.ts
|
|
80
78
|
│ ├── errors/ # Error types and handlers shared across the app
|
|
81
79
|
│ └── types/ # Types shared across the app; a component's own types stay in its types.ts
|
|
@@ -148,10 +146,11 @@ project-root/
|
|
|
148
146
|
| **The site frame** — navigation, header, footer | `components/layout/` | `components/layout/siteHeader/` |
|
|
149
147
|
| **Three or more pages** of this project | `components/shared/` | `components/shared/pricingTable/` |
|
|
150
148
|
| **Three or more pages in one section** | A `components/` folder in that section's route group | `app/(billing)/components/invoiceTable/` |
|
|
149
|
+
| **Three or more pages in a section that already shares a folder** | A `components/` folder in that shared folder | `app/orders/[id]/components/orderSummary/` |
|
|
151
150
|
| **One or two pages** | A `components/` folder in that page's route folder | `app/account-settings/components/accountForm/` |
|
|
152
151
|
| **The homepage** | `app/(homepage)/components/` | `app/(homepage)/components/heroSection/` |
|
|
153
152
|
|
|
154
|
-
A route group is a folder in brackets, such as `(billing)`. It groups pages without changing their URLs: `app/(billing)/invoices/page.tsx` is served at `/invoices`.
|
|
153
|
+
A route group is a folder in brackets, such as `(billing)`. It groups pages without changing their URLs: `app/(billing)/invoices/page.tsx` is served at `/invoices`. **A route group is only needed when a section's pages do not already share a folder.** When they all sit under one URL folder, such as `app/orders/[id]/`, that folder is the section, and its components go in its own `components/` folder. Never move pages just to make a route group.
|
|
155
154
|
|
|
156
155
|
**The homepage is a route group too: `app/(homepage)/`.** It holds the homepage's `page.tsx` and its own `components/` and `utils/` folders, and is served at `/`. Without it, the homepage's components sit loose in `app/components/` beside the root layout, with no clean place for the next page's. `app/` keeps only the root `layout.tsx` and the files Next.js needs there, such as `globals.css`. A folder inside `app/` is only a route when it holds a `page.tsx` or `route.ts`, so `components/` and `utils/` folders inside `app/` are safe: they never become URLs.
|
|
157
156
|
|
|
@@ -299,25 +298,29 @@ Add the export to `utils/index.ts` whenever you add a function.
|
|
|
299
298
|
|
|
300
299
|
---
|
|
301
300
|
|
|
302
|
-
## 🔤 Constants: `r`, `s
|
|
301
|
+
## 🔤 Constants: `r`, `s` and shared values {#constants}
|
|
303
302
|
|
|
304
|
-
Every link
|
|
303
|
+
**Every link goes in `r`, and every piece of text people see or hear goes in `s`**, both in `lib/constants/`, never written straight into a component. A link then changes in one place, and every piece of text is in one place when the site is translated into other languages.
|
|
304
|
+
|
|
305
|
+
**Every other value lives with the code that uses it, until it is shared.** A number, list or internal string that one file uses is a named constant at the top of that file. Once more than one file needs it, it moves to `lib/constants/`, into the file that fits it.
|
|
305
306
|
|
|
306
307
|
```text
|
|
307
308
|
lib/constants/
|
|
308
|
-
├── routes.ts
|
|
309
|
-
├── strings.ts
|
|
310
|
-
├── numbers.ts
|
|
311
|
-
├── noData.ts
|
|
312
|
-
├── animation.ts
|
|
313
|
-
├── artwork.ts
|
|
314
|
-
├── classNames.ts
|
|
315
|
-
|
|
309
|
+
├── routes.ts # r: every link
|
|
310
|
+
├── strings.ts # s: every piece of text people see or hear
|
|
311
|
+
├── numbers.ts # Numbers more than one file uses
|
|
312
|
+
├── noData.ts # Stand-in data, once the data's shape is decided
|
|
313
|
+
├── animation.ts # How things move, when more than one file uses it
|
|
314
|
+
├── artwork.ts # What is drawn and where, when more than one file uses it
|
|
315
|
+
├── classNames.ts # Class names shared between files
|
|
316
|
+
├── status.ts # Statuses the app shares
|
|
317
|
+
├── unsortedValues.ts # Values waiting for the person to say where they go
|
|
318
|
+
└── index.ts # Exports all of them
|
|
316
319
|
```
|
|
317
320
|
|
|
318
|
-
|
|
321
|
+
`routes.ts`, `strings.ts` and `index.ts` exist from the start. Every other file is created only once there is something to put in it. Each is one file, never split by topic.
|
|
319
322
|
|
|
320
|
-
| A value that is…
|
|
323
|
+
| A shared value that is… | Goes in |
|
|
321
324
|
| ----------------------------------------------------------- | ------------------- |
|
|
322
325
|
| A link | `r` in `routes.ts` |
|
|
323
326
|
| Text people see or hear | `s` in `strings.ts` |
|
|
@@ -326,8 +329,9 @@ lib/constants/
|
|
|
326
329
|
| A group of values that together say how something moves | `animation.ts` |
|
|
327
330
|
| A group of values that together say what is drawn and where | `artwork.ts` |
|
|
328
331
|
| A Tailwind class string used by more than one file | `classNames.ts` |
|
|
332
|
+
| A status more than one part of the app reads | `status.ts` |
|
|
329
333
|
|
|
330
|
-
**This table is the base, and where each value goes is the project's call.**
|
|
334
|
+
**This table is the base, and where each value goes is the project's call.** A shared value that fits none of these goes in a file of its own in `lib/constants/`, named after what it holds. When it is not clear where a value goes, it goes in [`unsortedValues.ts`](#unsorted-values) until the person says.
|
|
331
335
|
|
|
332
336
|
A file outside the folder imports everything it needs in one line:
|
|
333
337
|
|
|
@@ -371,7 +375,7 @@ export const s = {
|
|
|
371
375
|
|
|
372
376
|
- **The keys of `s` are the site's translation keys.** When a site gets more languages, each key is translated into each language. Name each key after what the text says or does, and never use one key for two different jobs.
|
|
373
377
|
- **Only real copy goes in `s`.** Dummy text belongs in `noData.ts`.
|
|
374
|
-
- **Internal strings are not `s`.** Ids, keys, event names, log messages and media queries are never shown to people. Each is a key in the object that uses it, or a named constant at the top of the file that uses it, such as `const CLOSE_EVENT = "close";`.
|
|
378
|
+
- **Internal strings are not `s`.** Ids, keys, event names, log messages and media queries are never shown to people. Each is a key in the object that uses it, or a named constant at the top of the file that uses it, such as `const CLOSE_EVENT = "close";`. A status more than one part of the app reads goes in [`status.ts`](#statuses).
|
|
375
379
|
|
|
376
380
|
### A list of items with links
|
|
377
381
|
|
|
@@ -453,11 +457,11 @@ const insights =
|
|
|
453
457
|
- **Dummy values sit at the top of `noData.ts`** as their own constants, `DUMMY_HEADING` and the rest. They are never added to `s`.
|
|
454
458
|
- **noData is for the whole site.** All of it lives in this one file.
|
|
455
459
|
|
|
456
|
-
### Numbers: named,
|
|
460
|
+
### Numbers: named, and shared from one file {#numbers-named-and-kept-by-topic}
|
|
457
461
|
|
|
458
462
|
**A number other than `-1`, `0` or `1` gets a name**, such as `MAXIMUM_RETRY_ATTEMPTS`. Those three mean "nothing", "one more" and "not found", so they read clearly as they are. Any other number was chosen by someone, and its name says what it controls. ESLint checks this with `no-magic-numbers`.
|
|
459
463
|
|
|
460
|
-
**
|
|
464
|
+
**A number only one file uses is a named constant at the top of that file. A number more than one file uses lives in `lib/constants/numbers.ts`.** There is no `n` object: each number is its own `SCREAMING_SNAKE_CASE` export.
|
|
461
465
|
|
|
462
466
|
```ts title="lib/constants/numbers.ts"
|
|
463
467
|
export const COOKIE_DURATION_DAYS = 30;
|
|
@@ -518,9 +522,42 @@ export const SURFACE_CLASS_NAME =
|
|
|
518
522
|
- **A class name used in one file stays inline in that file.**
|
|
519
523
|
- **Name each export after what it styles, ending in `_CLASS_NAME`**, or `_CLASS_NAMES` for a set keyed by variant.
|
|
520
524
|
|
|
525
|
+
### Statuses {#statuses}
|
|
526
|
+
|
|
527
|
+
**`status.ts` holds the statuses more than one part of the app reads**, such as the states a review or a workflow can be in. A status only one file reads stays at the top of that file.
|
|
528
|
+
|
|
529
|
+
```ts title="lib/types/status.ts"
|
|
530
|
+
export type ReviewStatusType = "passed" | "rejected" | "errored";
|
|
531
|
+
```
|
|
532
|
+
|
|
533
|
+
```ts title="lib/constants/status.ts"
|
|
534
|
+
import type { ReviewStatusType } from "@/lib/types";
|
|
535
|
+
|
|
536
|
+
export const REVIEW_FAILED_STATUSES: readonly ReviewStatusType[] = [
|
|
537
|
+
"rejected",
|
|
538
|
+
"errored",
|
|
539
|
+
];
|
|
540
|
+
```
|
|
541
|
+
|
|
542
|
+
- **The status is the value the code checks. The words people see stay in `s`**, under the same key: `"rejected"` is what the code compares, and `s.reviewStatuses.rejected` is the "Rejected" on the badge.
|
|
543
|
+
- **Name each export after what it lists**, ending in `_STATUSES` or `_STATES`.
|
|
544
|
+
|
|
545
|
+
### When it is not clear where a value goes {#unsorted-values}
|
|
546
|
+
|
|
547
|
+
**Put it in `lib/constants/unsortedValues.ts`, and carry on.** The work never waits for the answer.
|
|
548
|
+
|
|
549
|
+
**At the end of the work, ask the person about every value in it**, one line each, with where you would put it: at the top of the file that uses it, or in a shared file named after what it holds.
|
|
550
|
+
|
|
551
|
+
```text
|
|
552
|
+
REVIEW_FAILED_STATUSES (used in runReview and ReviewBadge)
|
|
553
|
+
→ keep it in runReview.ts, or move it to lib/constants/status.ts?
|
|
554
|
+
```
|
|
555
|
+
|
|
556
|
+
Move each value where the person says, then delete the file. [`pnpm standards:check`](/docs/Guides/setup#checking-a-project) reports `unsortedValues.ts` for as long as it exists, so nothing is left waiting.
|
|
557
|
+
|
|
521
558
|
### Types for constants {#types-for-constants}
|
|
522
559
|
|
|
523
|
-
**Every object and list constant gets a real type where it is declared, from `lib/types/`.** `r` and `s` are the exception: their types are read from their values, such as `keyof typeof r.plans`, so they are never typed by hand. **A single number or string needs no type of its own**: `const COOKIE_DURATION_DAYS = 30;` is already exactly typed, and writing `: number` adds nothing.
|
|
560
|
+
**Every object and list constant in `lib/constants/` gets a real type where it is declared, from `lib/types/`.** `r` and `s` are the exception: their types are read from their values, such as `keyof typeof r.plans`, so they are never typed by hand. **A single number or string needs no type of its own**: `const COOKIE_DURATION_DAYS = 30;` is already exactly typed, and writing `: number` adds nothing.
|
|
524
561
|
|
|
525
562
|
```ts title="lib/types/animation.ts"
|
|
526
563
|
export interface EntranceAnimationType {
|
|
@@ -540,6 +577,7 @@ export const ENTRANCE_ANIMATION: EntranceAnimationType = {
|
|
|
540
577
|
};
|
|
541
578
|
```
|
|
542
579
|
|
|
580
|
+
- **A constant kept at the top of the file that uses it is typed beside it**, from that file's own `.types.ts`, the same as its `Props`. `lib/types/` is for the shared constants.
|
|
543
581
|
- **Types live in `lib/types/`, in files named by topic**, such as `animation.ts` and `artwork.ts`. A types file is not exempt from the 300-line limit: split it by topic when it grows.
|
|
544
582
|
- **A type a constant needs lives in `lib/types/`**, with every type it depends on. Components import it from `@/lib/types`.
|
|
545
583
|
- **`lib/types/` reads a constant's type straight from its file**: `import type { r } from "@/lib/constants/routes";`, never through `@/lib/constants`. It is the one exception to importing constants in one line. `import type` is removed at build, so the two folders reading each other's types never makes a real loop.
|
|
@@ -590,7 +628,7 @@ export const ENTRANCE_ANIMATION: EntranceAnimationType = {
|
|
|
590
628
|
A list of keys a loop runs over, such as `planIds` in [A list of items with links](#a-list-of-items-with-links), is not a loose id: it stays a list.
|
|
591
629
|
|
|
592
630
|
- **CSS belongs in a stylesheet, never in a constant.** Styles written as a string in TypeScript move to `globals.css`. Styles for when JavaScript is off go there under `@media (scripting: none)`; a browser without that query misses the fallback, and the standard accepts that. **A media query the code reads is not CSS**, such as the one an animation library matches to switch motion off: it stays in its object in `animation.ts`.
|
|
593
|
-
- **
|
|
631
|
+
- **Every file in `lib/constants/` can run past 300 lines.** They are data only, so ESLint does not apply `max-lines` to them. Keep each one a single file: never split them to get under the limit.
|
|
594
632
|
|
|
595
633
|
---
|
|
596
634
|
|
|
@@ -6,63 +6,52 @@ sidebar_position: 4
|
|
|
6
6
|
|
|
7
7
|
Consistent import organization makes code easier to read and understand.
|
|
8
8
|
|
|
9
|
-
## Import
|
|
9
|
+
## Import order is sorted for you
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
**Prettier sorts the imports of every file** with `@ianvs/prettier-plugin-sort-imports`, the same way it sorts Tailwind classes. Nobody sorts imports by hand, and agents never reorder them themselves: `pnpm format`, or saving in the editor, does it. See [Import sorting](/docs/Standards/prettier#import-sorting).
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
3. **External packages**
|
|
16
|
-
4. **Side effect imports**
|
|
17
|
-
5. **Parent imports** (`../`)
|
|
18
|
-
6. **Same-folder imports** (`./`)
|
|
19
|
-
7. **Style imports** (`.css`, `.module.css`)
|
|
13
|
+
```tsx
|
|
14
|
+
"use client";
|
|
20
15
|
|
|
21
|
-
|
|
16
|
+
import { readFileSync } from "node:fs";
|
|
22
17
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
import {
|
|
18
|
+
import Link from "next/link";
|
|
19
|
+
import { useState } from "react";
|
|
20
|
+
|
|
21
|
+
import { Button } from "@/components/ui";
|
|
22
|
+
import { r, s } from "@/lib/constants";
|
|
23
|
+
|
|
24
|
+
import { formatDate } from "../utils/formatDate";
|
|
27
25
|
|
|
28
|
-
|
|
29
|
-
import { Button } from "@acme/ui";
|
|
30
|
-
import { useAuthentication } from "@acme/authentication";
|
|
26
|
+
import type { SampleProps } from "./Sample.types";
|
|
31
27
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
import clsx from "clsx";
|
|
28
|
+
import "./sample.css";
|
|
29
|
+
```
|
|
35
30
|
|
|
36
|
-
|
|
37
|
-
import "prismjs/themes/prism-tomorrow.css";
|
|
31
|
+
Node's own modules, then packages, the project's `@/` aliases, parent folders (`../`), and the same folder (`./`). **Side-effect imports, such as CSS, go after every other import**: the sorter never moves them, because the order they load in can matter.
|
|
38
32
|
|
|
39
|
-
|
|
40
|
-
import { formatDate } from "../utils";
|
|
33
|
+
## Importing components
|
|
41
34
|
|
|
42
|
-
|
|
43
|
-
import { Header } from "./Header";
|
|
44
|
-
import { useUserData } from "./useUserData";
|
|
35
|
+
**`components/ui/`, `components/layout/` and `components/shared/` each have an `index.ts`**, and code outside a category imports from it, so imports stay short:
|
|
45
36
|
|
|
46
|
-
|
|
47
|
-
import "
|
|
48
|
-
import styles from "./styles.module.css";
|
|
37
|
+
```tsx
|
|
38
|
+
import { Button, Card } from "@/components/ui";
|
|
49
39
|
```
|
|
50
40
|
|
|
51
|
-
|
|
41
|
+
- **No `index.ts` directly in `components/`.** The import shows whether a component is a Design System Component, part of the site frame, or shared.
|
|
42
|
+
- **Inside a category, components import each other by file**, never through the category's own `index.ts`. See [Inside a folder, import files directly](#2-inside-a-folder-import-files-directly).
|
|
43
|
+
- **A category's `index.ts` exports only components a Client Component can import.** A Client Component that imports a category pulls in everything its `index.ts` exports, so one server-only component in it breaks the build for every Client Component that imports the category.
|
|
44
|
+
- **A component that reaches server-only code**, such as authentication, the database, secrets or `next/headers`, starts with `import "server-only";`. It is left out of its category's `index.ts`, and imported from its own folder:
|
|
52
45
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
4. **Side effects** - Imports that don't export values (CSS, polyfills)
|
|
57
|
-
5. **Parent imports** - Code from parent directories
|
|
58
|
-
6. **Same-folder** - Code from the current directory
|
|
59
|
-
7. **Styles last** - Visual separation, easy to find style imports
|
|
46
|
+
```tsx
|
|
47
|
+
// components/layout/siteHeader/SiteHeader.tsx
|
|
48
|
+
import "server-only";
|
|
60
49
|
|
|
61
|
-
|
|
50
|
+
// app/layout.tsx
|
|
51
|
+
import { SiteHeader } from "@/components/layout/siteHeader";
|
|
52
|
+
```
|
|
62
53
|
|
|
63
|
-
-
|
|
64
|
-
- ✅ **Blank lines** between groups
|
|
65
|
-
- ✅ **No duplicates** - Import each module once
|
|
54
|
+
`import "server-only";` makes a mistake fail the build with a clear error, instead of sending server code to the browser.
|
|
66
55
|
|
|
67
56
|
## Import Safety
|
|
68
57
|
|
|
@@ -152,7 +141,3 @@ export const database = createConnection(DATABASE_URL);
|
|
|
152
141
|
Code that runs on import makes the order files load in matter. Code that only defines things does not.
|
|
153
142
|
|
|
154
143
|
Enforced by ESLint `unicorn/no-top-level-side-effects`.
|
|
155
|
-
|
|
156
|
-
## Import Order Is Not Enforced
|
|
157
|
-
|
|
158
|
-
The **order of the import lines** is a convention, not a lint rule. Follow the same pattern in every file so imports are easy to read, but ESLint will not report an error if the order differs.
|
|
@@ -330,7 +330,7 @@ Code files are camelCase or PascalCase. A short list of things are kebab-case in
|
|
|
330
330
|
Use ESLint and Prettier to enforce these conventions automatically:
|
|
331
331
|
|
|
332
332
|
- **eslint-plugin-react** - React naming conventions
|
|
333
|
-
-
|
|
333
|
+
- **@ianvs/prettier-plugin-sort-imports** - Import ordering, run by Prettier
|
|
334
334
|
- **@typescript-eslint** - TypeScript naming rules
|
|
335
335
|
|
|
336
336
|
See [ESLint](/docs/Standards/eslint) and [Prettier](/docs/Standards/prettier) configuration for setup.
|
package/docs/templates.mdx
CHANGED
|
@@ -9,6 +9,7 @@ import eslintReact from "!!raw-loader!@site/static/templates/eslint/react/eslint
|
|
|
9
9
|
import eslintNextjs from "!!raw-loader!@site/static/templates/eslint/nextjs/eslint.config.mjs";
|
|
10
10
|
import eslintBase from "!!raw-loader!@site/static/templates/eslint/base/eslint.config.mjs";
|
|
11
11
|
import prettier from "!!raw-loader!@site/static/templates/prettier.config.mjs";
|
|
12
|
+
import prettierIgnore from "!!raw-loader!@site/static/templates/.prettierignore";
|
|
12
13
|
import stylelintCss from "!!raw-loader!@site/static/templates/stylelint/css/stylelint.config.mjs";
|
|
13
14
|
import stylelintScss from "!!raw-loader!@site/static/templates/stylelint/scss/stylelint.config.mjs";
|
|
14
15
|
import globalsCss from "!!raw-loader!@site/static/templates/globals.css";
|
|
@@ -50,6 +51,7 @@ Each file is also served as a plain file, so a person or an AI agent can fetch i
|
|
|
50
51
|
| [ESLint — Next.js](#eslintnextjs) | `eslint.config.mjs` in the project root | [`/templates/eslint/nextjs/eslint.config.mjs`](pathname:///templates/eslint/nextjs/eslint.config.mjs) |
|
|
51
52
|
| [ESLint — JavaScript / Node.js](#eslintbase) | `eslint.config.mjs` in the project root | [`/templates/eslint/base/eslint.config.mjs`](pathname:///templates/eslint/base/eslint.config.mjs) |
|
|
52
53
|
| [Prettier](#prettier) | `prettier.config.mjs` in the project root | [`/templates/prettier.config.mjs`](pathname:///templates/prettier.config.mjs) |
|
|
54
|
+
| [Prettier ignore](#prettierignore) | `.prettierignore` in the project root | [`/templates/.prettierignore`](pathname:///templates/.prettierignore) |
|
|
53
55
|
| [Stylelint — CSS and CSS Modules](#stylelintcss) | `stylelint.config.mjs` in the project root | [`/templates/stylelint/css/stylelint.config.mjs`](pathname:///templates/stylelint/css/stylelint.config.mjs) |
|
|
54
56
|
| [Stylelint — SCSS](#stylelintscss) | `stylelint.config.mjs` in the project root | [`/templates/stylelint/scss/stylelint.config.mjs`](pathname:///templates/stylelint/scss/stylelint.config.mjs) |
|
|
55
57
|
| [Global styles and colour palette](#globalscss) | `app/globals.css` | [`/templates/globals.css`](pathname:///templates/globals.css) |
|
|
@@ -135,6 +137,18 @@ See the [Prettier page](/docs/Standards/prettier).
|
|
|
135
137
|
|
|
136
138
|
---
|
|
137
139
|
|
|
140
|
+
## Prettier ignore {#prettierignore}
|
|
141
|
+
|
|
142
|
+
**Copy to:** `.prettierignore` in the project root, or add its lines to the project's own
|
|
143
|
+
|
|
144
|
+
See [What Prettier skips](/docs/Standards/prettier#what-prettier-skips).
|
|
145
|
+
|
|
146
|
+
<CodeBlock language="text" title=".prettierignore">
|
|
147
|
+
{prettierIgnore}
|
|
148
|
+
</CodeBlock>
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
138
152
|
## Stylelint — CSS and CSS Modules {#stylelintcss}
|
|
139
153
|
|
|
140
154
|
**Copy to:** `stylelint.config.mjs` in the project root
|
package/docs/version-history.md
CHANGED
|
@@ -60,6 +60,7 @@ Anyone changing the standards adds a version, alongside the change:
|
|
|
60
60
|
- **Changing a released major version** goes under its version, newest at the top. Update the version's changes in place where they are now wrong. Write each entry so a project already on the version before it knows what to do.
|
|
61
61
|
- **Every entry is headed `**Fixes in 3.2.3.**`**, with its number, followed by "If the project already applied 3.2.2, check these:".
|
|
62
62
|
- **A middle-number entry adds `**Structural changes in 3.3.0.**` straight under its heading**, listing each change that moves or renames files in a project, with a rough size, such as "one move per file", so a project can plan the work and take a [regression check](/docs/Guides/regression-checks) baseline first. A last-number entry never moves files.
|
|
63
|
+
- **Anything a version can change in the `AGENTS.md` template lives between the `code-standards` markers.** A project copies only that section on an update, and `pnpm standards:check` compares only that section, so a rule outside the markers never reaches a project that is already set up.
|
|
63
64
|
- **Every release commit is titled `docs: version N.N.N — <what changed>`**, such as `docs: version 3.2.2 — full version numbers`, so releases are easy to find in the git log.
|
|
64
65
|
- **Every number is published.** Publish each one to npm as soon as its entry is written. A Fixes entry for a version that was never published sends a project to install something that does not exist.
|
|
65
66
|
- **Judgement calls after release are fixes, not workarounds.** When a project's update needed a call the steps did not cover, add it under the version's Fixes so every other project gets it too. A project should never keep a private workaround for an unclear step.
|
|
@@ -68,10 +69,84 @@ Anyone changing the standards adds a version, alongside the change:
|
|
|
68
69
|
|
|
69
70
|
## Version 3
|
|
70
71
|
|
|
71
|
-
**Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.3.
|
|
72
|
+
**Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.3.3
|
|
72
73
|
|
|
73
74
|
Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 first: it says which parts of the project's `AGENTS.md` are now the project's own to write.
|
|
74
75
|
|
|
76
|
+
**Fixes in 3.3.3.** If the project already applied 3.3.2, check these:
|
|
77
|
+
|
|
78
|
+
- **The Ontology and Documentation sections of `AGENTS.md` are now inside the `code-standards` markers.** They were above them, so copying the Code standards section on an update never brought them in, and `pnpm standards:check` never noticed a project without them. 3.3.2's "Record a check only after it has run" rule was one of the rules that never arrived. Anything a version can change now lives inside the markers. The Documentation section's line about `docsSite/` now starts "If the project has a `docsSite/`".
|
|
79
|
+
|
|
80
|
+
**What to do:** copy the Code standards section of `AGENTS.md` from the template again: everything from `<!-- code-standards:start -->` to `<!-- code-standards:end -->`. It now ends with the Ontology and Documentation sections. Then delete the project's old Ontology and Documentation sections above the markers, so neither appears twice. Anything project-specific in them moves to a section of its own, outside the markers.
|
|
81
|
+
|
|
82
|
+
- **A section whose pages already share a folder needs no route group.** When all a section's pages sit under one URL folder, such as `app/orders/[id]/`, that folder is the section, and components three or more of its pages use go in its own `components/` folder. Never move pages just to make a route group. See [Where components live](/docs/Structure/folder-structure#-where-components-live). Nothing to do.
|
|
83
|
+
- **Prettier sorts imports.** The Prettier template adds `@ianvs/prettier-plugin-sort-imports`: Node's own modules, then packages, `@/` aliases, `../`, then `./`, with a blank line between groups. Directives such as `"use client"` stay at the top, type imports stay on their own line, and side-effect imports, such as CSS, never move. Nobody sorts imports by hand. The seven-step order on [Import Organization](/docs/Structure/import-organization) is gone. See [Import sorting](/docs/Standards/prettier#import-sorting).
|
|
84
|
+
|
|
85
|
+
**What to do:**
|
|
86
|
+
|
|
87
|
+
1. `pnpm add -D @ianvs/prettier-plugin-sort-imports`.
|
|
88
|
+
2. Copy `static/templates/prettier.config.mjs` over the project's again. A project without Tailwind removes `prettier-plugin-tailwindcss` and `tailwindStylesheet` as before.
|
|
89
|
+
3. Move each side-effect import, such as `import "./globals.css";`, below the file's other imports.
|
|
90
|
+
4. Run `pnpm format`, and **commit the result on its own**, with nothing else in it, so the reordering never hides a real change in a review.
|
|
91
|
+
|
|
92
|
+
- **Components are imported from their category.** `components/ui/`, `components/layout/` and `components/shared/` each have an `index.ts`, and code outside a category imports from it: `import { Button } from "@/components/ui";`. There is no `components/index.ts`, and `pnpm standards:check` now reports one. **A category's `index.ts` exports only components a Client Component can import**: a Client Component that imports a category pulls in everything it exports, so one server-only component in it breaks the build. A component that reaches server-only code, such as authentication, the database, secrets or `next/headers`, starts with `import "server-only";`, is left out of the `index.ts`, and is imported from its own folder, such as `@/components/layout/siteHeader`. Tested with a Next.js 16 build: the build fails with a server-only component in the category's `index.ts`, and passes once it is imported from its own folder. See [Importing components](/docs/Structure/import-organization#importing-components).
|
|
93
|
+
|
|
94
|
+
**What to do:**
|
|
95
|
+
|
|
96
|
+
1. Delete any `components/index.ts`, and point its imports at the category: `@/components/ui`, `@/components/layout` or `@/components/shared`.
|
|
97
|
+
2. Give each category an `index.ts` if it has none.
|
|
98
|
+
3. For each component that reaches server-only code, add `import "server-only";` at the top, take it out of its category's `index.ts`, and import it from its own folder.
|
|
99
|
+
4. Copy the Code standards section of `AGENTS.md` from the template again, if not already done for the first fix above.
|
|
100
|
+
|
|
101
|
+
- **"Unfinished changes": write "None", with no note after it.** 3.3.2 said "exactly None", but the check also accepts "None." with a full stop. The template now says what the check does. Nothing to do.
|
|
102
|
+
|
|
103
|
+
**How to check:** `pnpm standards:check` passes, or lists only recorded exceptions; `AGENTS.md` has one Ontology and one Documentation section, both inside the markers; `pnpm format:check` passes; `git ls-files components/index.ts` finds nothing; no category's `index.ts` exports a file that `grep -rln "server-only" components` lists.
|
|
104
|
+
|
|
105
|
+
**Fixes in 3.3.2.** If the project already applied 3.3.1, check these:
|
|
106
|
+
|
|
107
|
+
- **Only well-formed lines under "Details" count as exceptions.** `pnpm standards:check` used to read any line under "Details" in `docs/development/coding-standards.md` that started with a number as an exception to that standard, so a plain numbered list switched standards off without a word. Now a line counts only in the shape `N. Name — skipped: reason` or `N. Name — changed: reason`, with the number and name from the [setup list](/docs/Guides/setup#3-agree-the-standards). Any other line that starts with a number fails the check, and a misread line can never be hidden as an exception itself.
|
|
108
|
+
|
|
109
|
+
**What to do:** run `pnpm standards:check`. For each line under "Details" it reports, write it in the exception shape, or turn it into a bullet point that does not start with a number. Copy the "Details" and "Unfinished changes" notes from `static/templates/docs/development/coding-standards.md` if the project's still has the old ones.
|
|
110
|
+
|
|
111
|
+
- **An exception can cover only some files.** Name them in backticks after `for`, as in the [setup example](/docs/Guides/setup#3-agree-the-standards). The check then hides findings for those files only. `**` matches any depth, `*` stays inside one folder, and a path ending in `/` covers the whole folder. An exception that names no files still covers the whole standard. A `for` with no path in backticks fails the check, because it would otherwise cover every file.
|
|
112
|
+
|
|
113
|
+
**What to do:** nothing, unless the project skipped a whole standard only to cover some files. Then narrow that exception to the files, with the person's yes.
|
|
114
|
+
|
|
115
|
+
- **`AGENTS.md` and the agent skills are Prettier-ignored.** The check compares them word for word with the templates, and Prettier reformatted them, so a formatted project always failed standard 21. There is now a `.prettierignore` template: see [What Prettier skips](/docs/Standards/prettier#what-prettier-skips).
|
|
116
|
+
|
|
117
|
+
**What to do:** add these lines to the project's `.prettierignore`, then copy the Code standards section of `AGENTS.md` and the skills from the templates again, so Prettier's changes to them are undone:
|
|
118
|
+
|
|
119
|
+
```text title=".prettierignore"
|
|
120
|
+
AGENTS.md
|
|
121
|
+
.agents/skills/
|
|
122
|
+
.claude/commands/
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
If the project wrapped the section in `<!-- prettier-ignore-start -->` and `<!-- prettier-ignore-end -->` to work around this, remove those two comments.
|
|
126
|
+
|
|
127
|
+
- **`components/` holds only `ui/`, `layout/` and `shared/`**, as [Where components live](/docs/Structure/folder-structure#-where-components-live) already said. `pnpm standards:check` now reports any other folder, and any component file, directly in `components/`.
|
|
128
|
+
|
|
129
|
+
**What to do:** run `pnpm standards:check`, and move each folder or file it reports into the home that fits: `components/ui/`, `components/layout/`, `components/shared/`, or the `components/` folder of the page or section that uses it.
|
|
130
|
+
|
|
131
|
+
- **Only `r`, `s` and shared values go in `lib/constants/`.** Every link still goes in `r` and every piece of text people see or hear in `s`, so links change in one place and the text can be translated. Every other value, such as a number, list, status or internal string, now lives at the top of the file that uses it until more than one file needs it, then moves to the file in `lib/constants/` that fits. Forcing a value only one file uses into a global file sent readers across the project to find it. `lib/constants/` may hold any file named after what it holds, such as the new `status.ts` for statuses the app shares; only `routes.ts`, `strings.ts` and `index.ts` are required, and every file in it is exempt from `max-lines`. A constant kept at the top of its file is typed from that file's own `.types.ts`; `lib/types/` is for the shared constants. See [Constants](/docs/Structure/folder-structure#constants).
|
|
132
|
+
|
|
133
|
+
**What to do:** nothing has to move. Copy the Code standards section of `AGENTS.md` from the template again, and copy the project's ESLint template over `eslint.config.mjs` again: the `max-lines` block now reads `lib/constants/*.ts`. A value moved into `lib/constants/` only because the old rule said so may move back to the file that uses it when that file is next changed. Remove any comment that names a "Details" entry for a value that fitted no file: such a value now goes in `unsortedValues.ts`, below.
|
|
134
|
+
|
|
135
|
+
- **When it is not clear where a value goes, it goes in `lib/constants/unsortedValues.ts`.** The agent carries on, and at the end of the work asks the person where each value in it goes, then moves each one and deletes the file. `pnpm standards:check` reports the file for as long as it exists. See [When it is not clear where a value goes](/docs/Structure/folder-structure#unsorted-values).
|
|
136
|
+
|
|
137
|
+
**What to do:** nothing. Copied in with the `AGENTS.md` section above.
|
|
138
|
+
|
|
139
|
+
- **Record a check only after it has run.** A doc never says a URL, commit, date or "passed" for a check that has not happened yet. Write what was decided, and add the result once it exists. The `AGENTS.md` template, [Docs](/docs/Standards/documentation) and [Regression Checks](/docs/Guides/regression-checks) say so.
|
|
140
|
+
|
|
141
|
+
**What to do:** read `docs/testing/regression.md` and any other doc that records a check. Remove any result, URL or commit for a check that has not actually run. Copied into `AGENTS.md` with the section above. _Changed in 3.3.3: the rule was in the template's Documentation section, outside the markers, so copying the section did not bring it in. Do the 3.3.3 step._
|
|
142
|
+
|
|
143
|
+
- **Comparing two local servers: copy `node_modules`, never symlink it.** Turbopack refuses a `node_modules` that points outside the project folder. On macOS, `cp -Rc` makes a copy-on-write clone in seconds. See [Comparing two local servers instead](/docs/Guides/regression-checks#comparing-two-local-servers-instead). Nothing to do.
|
|
144
|
+
- **"Unfinished changes" says exactly "None" when nothing is left.** A note after it, such as "None. ESLint was switched on in an earlier ticket.", reads as an unfinished change. The template and the check's report now say so.
|
|
145
|
+
|
|
146
|
+
**What to do:** if the project's "Unfinished changes" says "None" with a note after it, leave only "None". The history belongs in the change that did the work.
|
|
147
|
+
|
|
148
|
+
**How to check:** `pnpm standards:check` passes, or lists only recorded exceptions; `.prettierignore` lists `AGENTS.md`, `.agents/skills/` and `.claude/commands/`; `grep -rn "prettier-ignore" AGENTS.md` finds nothing; `pnpm format:check` passes; `lib/constants/unsortedValues.ts` does not exist.
|
|
149
|
+
|
|
75
150
|
**Fixes in 3.3.1.** If the project already applied 3.3.0, check these:
|
|
76
151
|
|
|
77
152
|
- **A single number or string needs no type of its own.** 3.3.0 said every constant gets a type from `lib/types/`. It means every object and list constant: `const COOKIE_DURATION_DAYS = 30;` is already exactly typed. The Animation and Artwork examples now have their types. Nothing to do, unless the project added `: number` or `: string` only to follow 3.3.0: those can stay or go.
|
|
@@ -144,7 +219,7 @@ grep -rnE "(^|[^y] )([A-Z][A-Za-z]*Type|string|number|boolean)\[\]" lib/types/
|
|
|
144
219
|
|
|
145
220
|
- **Where each constant goes is the project's call.** The [Constants table](/docs/Structure/folder-structure#constants) says what each file is for, not where every value in every project goes. 3.2.1's examples and check named values from one project; they are now neutral, and `pnpm standards:check` no longer guesses a value's file from its name. It lists the file, and the project decides.
|
|
146
221
|
|
|
147
|
-
**What to do:** best practice is every value in `lib/constants/` in the file the table says fits, with ids and CSS following the two rules below. Bring the project's values in line with that. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `coding-standards.md`.
|
|
222
|
+
**What to do:** best practice is every value in `lib/constants/` in the file the table says fits, with ids and CSS following the two rules below. Bring the project's values in line with that. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `coding-standards.md`. _Changed in 3.3.2: only `r`, `s` and shared values go in `lib/constants/`; a value one file uses stays at the top of that file. Skip this step if the project is updating past 3.3.2._
|
|
148
223
|
|
|
149
224
|
- **An id lives in the object that uses it.** A value that picks which item something acts on is a key inside that object, never a loose constant. A list of keys a loop runs over stays a list. See the [before and after](/docs/Structure/folder-structure#constants-rules).
|
|
150
225
|
|
|
@@ -192,7 +267,7 @@ grep -rnE "export const [A-Z_]+_ID = " lib/constants/
|
|
|
192
267
|
|
|
193
268
|
Each animation and artwork object stays whole, its values named by their keys. Never lift them out into `numbers.ts`, which keeps loose single numbers only: lifting them out makes long names and splits one object across files. Each file is one file, never split by topic. See [Constants](/docs/Structure/folder-structure#constants).
|
|
194
269
|
|
|
195
|
-
**What to do:** move every component `constants.ts`, and every other file in `lib/constants/`, into the seven files. Where each value goes is the project's call: read the [Constants table](/docs/Structure/folder-structure#constants), decide each value's home. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `coding-standards.md`, and the work carries on. In `eslint.config.mjs`, copy the template over it again: the `max-lines` block now reads `lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts`. Copy the Constants rules into `AGENTS.md` from the template.
|
|
270
|
+
**What to do:** move every component `constants.ts`, and every other file in `lib/constants/`, into the seven files. Where each value goes is the project's call: read the [Constants table](/docs/Structure/folder-structure#constants), decide each value's home. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `coding-standards.md`, and the work carries on. In `eslint.config.mjs`, copy the template over it again: the `max-lines` block now reads `lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts`. Copy the Constants rules into `AGENTS.md` from the template. _Changed in 3.3.2: only `r`, `s` and shared values go in `lib/constants/`; a value one file uses stays at the top of that file. Skip this step if the project is updating past 3.3.2._
|
|
196
271
|
|
|
197
272
|
- **A loop over a list looks each item up by its key.** Write a key out by name when you mean one item, `r.plans.starter`. Inside a loop over the list, use the item's key, typed from `r`: `keyof typeof r.plans`. Delete separate lookup objects that map a key to its link: `r` already is that lookup. See [A list of items with links](/docs/Structure/folder-structure#a-list-of-items-with-links).
|
|
198
273
|
|
|
@@ -249,8 +324,8 @@ grep -rnE "export const [A-Z_]+_ID = " lib/constants/
|
|
|
249
324
|
- **The site frame lives in `components/layout/`**: navigation, header, footer and anything else that frames the pages. It may read `r` and `s`. Move those components there from `components/shared/` or `app/components/`. Layout primitives such as Duplex stay in `components/ui/`.
|
|
250
325
|
- **A props-only component that is not on the Design System Components list stays in `components/ui/`.** Record it, with its props, in `docs/development/coding-standards.md`, under a new "Components for the standards" heading (copy it from the template), and tell the person. Move back into `components/ui/` any such component that was moved out only because it was not listed.
|
|
251
326
|
- **Four components joined the list:** Brand Logo, Notification Card, Scroll Cue and Dropdown Menu. If the project has them, check their props match the [list](/docs/design-system-components).
|
|
252
|
-
- **Every named number lives in `lib/constants/numbers.ts`**, even one only one file uses, in one file that is never split. Move numbers from the tops of app files and from any topic files (`durations.ts`, `limits.ts`) into it. _Changed in 3.2.1: motion and artwork objects stay whole in `animation.ts` and `artwork.ts`. Do the 3.2.1 step instead of moving their numbers here._ Config files and scripts outside the app keep theirs at the top.
|
|
253
|
-
- **No component-level `constants.ts`.** Every link, piece of text and number goes in `lib/constants/`, even if one file uses it, so all the text is in one place for translation. Move any component's `constants.ts` into `r`, `s` and `numbers.ts`. _Changed in 3.2.1: there are seven constants files to move into. Do the 3.2.1 step instead._
|
|
327
|
+
- **Every named number lives in `lib/constants/numbers.ts`**, even one only one file uses, in one file that is never split. Move numbers from the tops of app files and from any topic files (`durations.ts`, `limits.ts`) into it. _Changed in 3.2.1: motion and artwork objects stay whole in `animation.ts` and `artwork.ts`. Do the 3.2.1 step instead of moving their numbers here._ Config files and scripts outside the app keep theirs at the top. _Changed in 3.3.2: only `r`, `s` and shared values go in `lib/constants/`; a value one file uses stays at the top of that file. Skip this step if the project is updating past 3.3.2._
|
|
328
|
+
- **No component-level `constants.ts`.** Every link, piece of text and number goes in `lib/constants/`, even if one file uses it, so all the text is in one place for translation. Move any component's `constants.ts` into `r`, `s` and `numbers.ts`. _Changed in 3.2.1: there are seven constants files to move into. Do the 3.2.1 step instead._ _Changed in 3.3.2: only `r`, `s` and shared values go in `lib/constants/`; a value one file uses stays at the top of that file. Skip this step if the project is updating past 3.3.2._
|
|
254
329
|
- **Write `r` and `s` keys out by name**, `r.plans.starter`, never `r.plans[planId]`. A list of items keeps its words in `s` and its links in `r` under the same keys. See [A list of items with links](/docs/Structure/folder-structure#a-list-of-items-with-links).
|
|
255
330
|
- **No `"#"` placeholder links.** Show the text without a link and put `{/* TODO: … */}` above it until the page exists. Unfinished work is marked `// TODO: Message`.
|
|
256
331
|
- **`lib/constants/` never imports from `lib/types/`.** Move any type it imports from there beside the constant. _Withdrawn in 3.3.0: constants now take their types from `lib/types/`. Do the 3.3.0 step instead._
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@activatus/code-standards",
|
|
3
|
-
"version": "3.3.
|
|
3
|
+
"version": "3.3.3",
|
|
4
4
|
"description": "The Activatus code standards: the rules as Markdown, and the config files to copy. Install it so an AI agent can read the standards from node_modules.",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -73,6 +73,7 @@ const checkUiComponents = ({
|
|
|
73
73
|
)
|
|
74
74
|
.map((folder) => ({
|
|
75
75
|
standard: "15",
|
|
76
|
+
file: `components/ui/${folder}/`,
|
|
76
77
|
message: `components/ui/${folder} is not on the Design System Components list. If it takes everything through props, record it under "Components for the standards" in docs/development/coding-standards.md; otherwise move it out of components/ui/`,
|
|
77
78
|
page: "docs/design-system-components.md",
|
|
78
79
|
}));
|
|
@@ -109,6 +110,7 @@ const checkTestFiles = ({ projectDirectory, projectFiles }) => {
|
|
|
109
110
|
.filter((filePath) => !findTestFile({ filePath, projectFileSet }))
|
|
110
111
|
.map((filePath) => ({
|
|
111
112
|
standard: "4",
|
|
113
|
+
file: filePath,
|
|
112
114
|
message: `${filePath} has no test file beside it`,
|
|
113
115
|
page: "docs/Standards/readable-code.md#every-function-and-component-has-a-test-file",
|
|
114
116
|
}));
|
|
@@ -1,65 +1,39 @@
|
|
|
1
|
-
// Standard 12.1: lib/constants/
|
|
2
|
-
//
|
|
1
|
+
// Standard 12.1: lib/constants/ has r, s and the index that exports
|
|
2
|
+
// them, and nothing is left waiting in unsortedValues.ts.
|
|
3
3
|
const REQUIRED_FILES = [
|
|
4
4
|
"lib/constants/index.ts",
|
|
5
5
|
"lib/constants/routes.ts",
|
|
6
6
|
"lib/constants/strings.ts",
|
|
7
|
-
"lib/constants/numbers.ts",
|
|
8
7
|
];
|
|
9
|
-
|
|
10
|
-
const OPTIONAL_FILES = [
|
|
11
|
-
"lib/constants/noData.ts",
|
|
12
|
-
"lib/constants/animation.ts",
|
|
13
|
-
"lib/constants/artwork.ts",
|
|
14
|
-
"lib/constants/classNames.ts",
|
|
15
|
-
];
|
|
16
|
-
const CONSTANTS_FOLDER = "lib/constants/";
|
|
17
|
-
const COMPONENT_CONSTANTS_PATTERN = /(^|\/)constants\.tsx?$/;
|
|
18
|
-
const CODE_FILE_PATTERN = /\.(?:ts|tsx|js|mjs)$/;
|
|
8
|
+
const UNSORTED_VALUES_FILE = "lib/constants/unsortedValues.ts";
|
|
19
9
|
const PAGE = "docs/Structure/folder-structure.md#constants";
|
|
20
|
-
// Where each value goes is the project's call, made from the table.
|
|
21
|
-
const NEXT_STEP =
|
|
22
|
-
"Move each of its values into the file the Constants table says fits, and record any value that fits none in docs/development/coding-standards.md";
|
|
23
10
|
|
|
24
11
|
const checkMissingFiles = ({ projectFileSet }) =>
|
|
25
12
|
REQUIRED_FILES.filter(
|
|
26
13
|
(filePath) => !projectFileSet.has(filePath),
|
|
27
14
|
).map((filePath) => ({
|
|
28
15
|
standard: "12.1",
|
|
16
|
+
file: filePath,
|
|
29
17
|
message: `${filePath} is missing`,
|
|
30
18
|
page: PAGE,
|
|
31
19
|
}));
|
|
32
20
|
|
|
33
|
-
const
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
standard: "12.1",
|
|
45
|
-
message: `${filePath} is not one of the seven constants files. ${NEXT_STEP}`,
|
|
46
|
-
page: PAGE,
|
|
47
|
-
}));
|
|
48
|
-
};
|
|
49
|
-
|
|
50
|
-
const checkComponentFiles = ({ projectFiles }) =>
|
|
51
|
-
projectFiles
|
|
52
|
-
.filter((filePath) => !filePath.startsWith(CONSTANTS_FOLDER))
|
|
53
|
-
.filter((filePath) => !filePath.startsWith("node_modules/"))
|
|
54
|
-
.filter((filePath) => COMPONENT_CONSTANTS_PATTERN.test(filePath))
|
|
55
|
-
.map((filePath) => ({
|
|
56
|
-
standard: "12.1",
|
|
57
|
-
message: `${filePath}: there is no component-level constants file. ${NEXT_STEP}`,
|
|
58
|
-
page: PAGE,
|
|
59
|
-
}));
|
|
21
|
+
const checkUnsortedValues = ({ projectFileSet }) =>
|
|
22
|
+
projectFileSet.has(UNSORTED_VALUES_FILE)
|
|
23
|
+
? [
|
|
24
|
+
{
|
|
25
|
+
standard: "12.1",
|
|
26
|
+
file: UNSORTED_VALUES_FILE,
|
|
27
|
+
message: `${UNSORTED_VALUES_FILE} still holds values. Ask the person where each one goes, move it there, and delete the file`,
|
|
28
|
+
page: PAGE,
|
|
29
|
+
},
|
|
30
|
+
]
|
|
31
|
+
: [];
|
|
60
32
|
|
|
61
|
-
export const checkConstants = ({ projectFiles }) =>
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
33
|
+
export const checkConstants = ({ projectFiles }) => {
|
|
34
|
+
const projectFileSet = new Set(projectFiles);
|
|
35
|
+
return [
|
|
36
|
+
...checkMissingFiles({ projectFileSet }),
|
|
37
|
+
...checkUnsortedValues({ projectFileSet }),
|
|
38
|
+
];
|
|
39
|
+
};
|