@activatus/code-standards 3.3.0 → 3.3.2

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.
@@ -68,10 +68,71 @@ Anyone changing the standards adds a version, alongside the change:
68
68
 
69
69
  ## Version 3
70
70
 
71
- **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.3.0
71
+ **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.3.2
72
72
 
73
73
  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
74
 
75
+ **Fixes in 3.3.2.** If the project already applied 3.3.1, check these:
76
+
77
+ - **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.
78
+
79
+ **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.
80
+
81
+ - **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.
82
+
83
+ **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.
84
+
85
+ - **`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).
86
+
87
+ **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:
88
+
89
+ ```text title=".prettierignore"
90
+ AGENTS.md
91
+ .agents/skills/
92
+ .claude/commands/
93
+ ```
94
+
95
+ If the project wrapped the section in `<!-- prettier-ignore-start -->` and `<!-- prettier-ignore-end -->` to work around this, remove those two comments.
96
+
97
+ - **`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/`.
98
+
99
+ **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.
100
+
101
+ - **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).
102
+
103
+ **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.
104
+
105
+ - **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).
106
+
107
+ **What to do:** nothing. Copied in with the `AGENTS.md` section above.
108
+
109
+ - **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.
110
+
111
+ **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.
112
+
113
+ - **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.
114
+ - **"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.
115
+
116
+ **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.
117
+
118
+ **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.
119
+
120
+ **Fixes in 3.3.1.** If the project already applied 3.3.0, check these:
121
+
122
+ - **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.
123
+ - **The `readonly` search also finds `string[]`, `number[]` and `boolean[]` lists.** 3.3.0's search only found named types.
124
+
125
+ **What to do:** run the new search in 3.3.0's How to check, and make each hit that a constant uses `readonly`.
126
+
127
+ - **The regression baseline comes from the last known-good page.** That is the live production site, unless the branch's page has already changed from production, such as a redesign not yet live: then it is the branch's last commit before the refactor, built and served on its own. Record where the baseline came from in `docs/testing/regression.md`. See [Regression Checks](/docs/Guides/regression-checks). The comment and error message in the `playwright.config.mjs` template say the same; a project's frozen copy need not change.
128
+
129
+ **What to do:** if the project's `docs/testing/regression.md` does not say where its baseline came from, add it: the production URL, or the commit and the date.
130
+
131
+ - **`AGENTS.md`: an `as const` that cannot be avoided is one of the allowed lint disables**, beside `let` and a type cast, as 3.3.0 already said. Copy the Code standards section from the template again.
132
+ - **3.3.0's What to do had a step joined onto the end of a list.** "Copy the TypeScript skill again" and the disable-with-reason line now sit in their own paragraph. Nothing new to do.
133
+
134
+ **How to check:** the 3.3.0 How to check searches find nothing; `docs/testing/regression.md` says where the baseline came from.
135
+
75
136
  **Fixes in 3.3.0.** If the project already applied 3.2.2, check these:
76
137
 
77
138
  **Structural changes in 3.3.0.** These move files. Plan them, and take a [regression check](/docs/Guides/regression-checks) baseline first:
@@ -84,9 +145,9 @@ Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 firs
84
145
  - a class name only one file uses
85
146
  - numbers in config files
86
147
 
87
- - **Constants get real types, from `lib/types/`.** Every constant except `r` and `s` is typed where it is declared, with a type from `lib/types/`. "`lib/constants/` never imports from `lib/types/`" is withdrawn: it only ever guarded against a loop of types, which `import type` removes at build, and it pushed projects into `as const` and into retyping values wherever they were read. `lib/types/` now reads a constant's type with `import type` straight from its file, never through `@/lib/constants`. See [Types for constants](/docs/Structure/folder-structure#types-for-constants).
148
+ - **Constants get real types, from `lib/types/`.** Every object and list constant except `r` and `s` is typed where it is declared, with a type from `lib/types/`. _Changed in 3.3.1: a single number or string needs no type of its own._ "`lib/constants/` never imports from `lib/types/`" is withdrawn: it only ever guarded against a loop of types, which `import type` removes at build, and it pushed projects into `as const` and into retyping values wherever they were read. `lib/types/` now reads a constant's type with `import type` straight from its file, never through `@/lib/constants`. See [Types for constants](/docs/Structure/folder-structure#types-for-constants).
88
149
 
89
- **What to do:** change every import in `lib/types/` from `@/lib/constants` to the constant's own file, as `import type`. Give every constant except `r` and `s` a type from `lib/types/`, in files named by topic, and move the types it uses there with what they depend on. Point imports at `@/lib/types`, delete component `types.ts` files left empty, and remove imports left unused. Then remove the workarounds: values retyped where they are read, test values retyped or bent around missing properties. Make every list in a constant's type `readonly`, including lists inside an item. Copy the Code standards section of `AGENTS.md` from the template again.
150
+ **What to do:** change every import in `lib/types/` from `@/lib/constants` to the constant's own file, as `import type`. Give every object and list constant except `r` and `s` a type from `lib/types/`, in files named by topic, and move the types it uses there with what they depend on. Point imports at `@/lib/types`, delete component `types.ts` files left empty, and remove imports left unused. Then remove the workarounds: values retyped where they are read, test values retyped or bent around missing properties. Make every list in a constant's type `readonly`, including lists inside an item. Copy the Code standards section of `AGENTS.md` from the template again.
90
151
 
91
152
  - **No `as const` anywhere.** A written type is the contract; when the code needs exact values, they go in the type. Each constant's list type is `readonly`. A list that must hold every id is checked with a `Record` or a test. ESLint now reports `as const` as an error: `consistent-type-assertions` always let it through, so the configs ban it with `no-restricted-syntax`. See [No `as const`](/docs/Standards/readable-code#no-as-const).
92
153
 
@@ -95,7 +156,9 @@ Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 firs
95
156
  - values in tests
96
157
  - internal strings, as a named constant at the top of the file that uses them
97
158
  - a class name only one file uses
98
- - numbers in config files Copy `static/templates/skills/typescript.md` into `.agents/skills/` and `.claude/commands/` again. Where one `as const` is genuinely unavoidable, disable the rule on that line with the reason.
159
+ - numbers in config files
160
+
161
+ Copy `static/templates/skills/typescript.md` into `.agents/skills/` and `.claude/commands/` again. Where one `as const` is genuinely unavoidable, disable the rule on that line with the reason.
99
162
 
100
163
  - **The regression test template has no `as const`**, and a frozen test may take a change that touches only types. A code standards update that changes only types may be applied to a frozen test with the person's yes. Nothing the test does changes, and the check must still pass against the existing baseline. See [Regression Checks](/docs/Guides/regression-checks).
101
164
 
@@ -113,7 +176,7 @@ grep -rn "as const" --include='*.ts' --include='*.tsx' --exclude-dir=node_module
113
176
  This search lists types in `lib/types/` with a list that is not `readonly`. Fix each hit that a constant uses; a type only props or parameters use can stay as it is:
114
177
 
115
178
  ```bash
116
- grep -rnE "(^|[^y] )[A-Z][A-Za-z]*Type\[\]" lib/types/
179
+ grep -rnE "(^|[^y] )([A-Z][A-Za-z]*Type|string|number|boolean)\[\]" lib/types/
117
180
  ```
118
181
 
119
182
  **Fixes in 3.2.2.** If the project already applied 3.2.1, check these:
@@ -126,7 +189,7 @@ grep -rnE "(^|[^y] )[A-Z][A-Za-z]*Type\[\]" lib/types/
126
189
 
127
190
  - **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.
128
191
 
129
- **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`.
192
+ **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._
130
193
 
131
194
  - **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).
132
195
 
@@ -174,7 +237,7 @@ grep -rnE "export const [A-Z_]+_ID = " lib/constants/
174
237
 
175
238
  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).
176
239
 
177
- **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.
240
+ **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._
178
241
 
179
242
  - **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).
180
243
 
@@ -231,8 +294,8 @@ grep -rnE "export const [A-Z_]+_ID = " lib/constants/
231
294
  - **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/`.
232
295
  - **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.
233
296
  - **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).
234
- - **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.
235
- - **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._
297
+ - **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._
298
+ - **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._
236
299
  - **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).
237
300
  - **No `"#"` placeholder links.** Show the text without a link and put `{/* TODO: … */}` above it until the page exists. Unfinished work is marked `// TODO: Message`.
238
301
  - **`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.0",
3
+ "version": "3.3.2",
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/ holds the seven standard files and
2
- // nothing else, and no component keeps its own constants file.
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
- // Created only once the project has something to put in them.
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 checkExtraFiles = ({ projectFiles }) => {
34
- const standardFiles = new Set([
35
- ...REQUIRED_FILES,
36
- ...OPTIONAL_FILES,
37
- ]);
38
- return projectFiles
39
- .filter((filePath) => filePath.startsWith(CONSTANTS_FOLDER))
40
- .filter((filePath) => CODE_FILE_PATTERN.test(filePath))
41
- .filter((filePath) => !filePath.includes(".test."))
42
- .filter((filePath) => !standardFiles.has(filePath))
43
- .map((filePath) => ({
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
- ...checkMissingFiles({ projectFileSet: new Set(projectFiles) }),
63
- ...checkExtraFiles({ projectFiles }),
64
- ...checkComponentFiles({ projectFiles }),
65
- ];
33
+ export const checkConstants = ({ projectFiles }) => {
34
+ const projectFileSet = new Set(projectFiles);
35
+ return [
36
+ ...checkMissingFiles({ projectFileSet }),
37
+ ...checkUnsortedValues({ projectFileSet }),
38
+ ];
39
+ };
@@ -1,15 +1,28 @@
1
- // Standard 13: components sit at most two levels deep, the component
2
- // then its sub-components, and the homepage is in app/(homepage)/.
1
+ // Standard 13: the project's components/ folder holds only ui/,
2
+ // layout/ and shared/, components sit at most two levels deep, the
3
+ // component then its sub-components, and the homepage is in
4
+ // app/(homepage)/.
3
5
  import path from "node:path";
4
6
 
5
7
  const COMPONENT_FILE_PATTERN = /^[A-Z][A-Za-z0-9]*\.(?:tsx|jsx)$/;
6
8
  const COMPONENTS_FOLDER = "components";
7
9
  const UNGROUPED_HOMEPAGE_PATTERN =
8
10
  /^(?:src\/)?app\/page\.(?:tsx|jsx)$/;
11
+ // A folder directly in the project's own components/ folder, not a
12
+ // page's: components/projectTabs/, src/components/projectTabs/.
13
+ const TOP_COMPONENTS_FOLDER_PATTERN =
14
+ /^((?:src\/)?components\/([^/]+))\//;
15
+ const COMPONENTS_HOMES = new Set(["ui", "layout", "shared"]);
16
+ // A component file directly in components/: components/Foo.tsx.
17
+ const LOOSE_COMPONENT_FILE_PATTERN =
18
+ /^(?:src\/)?components\/[A-Z][A-Za-z0-9]*\.(?:tsx|jsx)$/;
19
+ const WHERE_COMPONENTS_LIVE_PAGE =
20
+ "docs/Structure/folder-structure.md#-where-components-live";
9
21
  const NESTED_PAGE =
10
22
  "docs/Structure/component-organization.md#nested-components";
11
23
 
12
- // A component folder holds a PascalCase component file, Card.tsx.
24
+ // A component folder holds a PascalCase component file, Card.tsx. A
25
+ // components/ folder never is one, even with a file loose in it.
13
26
  const listComponentFolders = ({ projectFiles }) =>
14
27
  new Set(
15
28
  projectFiles
@@ -17,7 +30,10 @@ const listComponentFolders = ({ projectFiles }) =>
17
30
  .filter((filePath) =>
18
31
  COMPONENT_FILE_PATTERN.test(path.posix.basename(filePath)),
19
32
  )
20
- .map((filePath) => path.posix.dirname(filePath)),
33
+ .map((filePath) => path.posix.dirname(filePath))
34
+ .filter(
35
+ (folder) => path.posix.basename(folder) !== COMPONENTS_FOLDER,
36
+ ),
21
37
  );
22
38
 
23
39
  // The topmost component folder above this one, or undefined for a
@@ -57,22 +73,46 @@ const checkSubComponentFolders = ({ componentFolders }) =>
57
73
  .filter(({ folder, flatFolder }) => folder !== flatFolder)
58
74
  .map(({ folder, rootComponent, flatFolder }) => ({
59
75
  standard: "13",
76
+ file: `${folder}/`,
60
77
  message: `${folder} is not flat in ${rootComponent}/${COMPONENTS_FOLDER}/. Move it to ${flatFolder}`,
61
78
  page: NESTED_PAGE,
62
79
  }));
63
80
 
81
+ const checkLooseComponentFolders = ({ projectFiles }) => {
82
+ const looseFolders = new Set(
83
+ projectFiles
84
+ .map((filePath) => TOP_COMPONENTS_FOLDER_PATTERN.exec(filePath))
85
+ .filter(Boolean)
86
+ .filter((match) => !COMPONENTS_HOMES.has(match[2]))
87
+ .map((match) => match[1]),
88
+ );
89
+ const looseFiles = projectFiles.filter((filePath) =>
90
+ LOOSE_COMPONENT_FILE_PATTERN.test(filePath),
91
+ );
92
+ return [...looseFolders, ...looseFiles].map((loosePath) => ({
93
+ standard: "13",
94
+ file: looseFiles.includes(loosePath)
95
+ ? loosePath
96
+ : `${loosePath}/`,
97
+ message: `${loosePath} is loose in components/, which holds only ui/, layout/ and shared/. Move it to the one that fits, or to the components/ folder of the page or section that uses it`,
98
+ page: WHERE_COMPONENTS_LIVE_PAGE,
99
+ }));
100
+ };
101
+
64
102
  const checkHomepage = ({ projectFiles }) =>
65
103
  projectFiles
66
104
  .filter((filePath) => UNGROUPED_HOMEPAGE_PATTERN.test(filePath))
67
105
  .map((filePath) => ({
68
106
  standard: "13",
107
+ file: filePath,
69
108
  message: `${filePath} is the homepage outside its route group. Move it to app/(homepage)/`,
70
- page: "docs/Structure/folder-structure.md#-where-components-live",
109
+ page: WHERE_COMPONENTS_LIVE_PAGE,
71
110
  }));
72
111
 
73
112
  export const checkStructure = ({ projectFiles }) => {
74
113
  const componentFolders = listComponentFolders({ projectFiles });
75
114
  return [
115
+ ...checkLooseComponentFolders({ projectFiles }),
76
116
  ...checkSubComponentFolders({ componentFolders }),
77
117
  ...checkHomepage({ projectFiles }),
78
118
  ];
@@ -66,7 +66,7 @@ export const formatReport = ({ result, projectDirectory }) => {
66
66
  }
67
67
  if (result.unfinishedChanges) {
68
68
  sections.push(
69
- `Unfinished changes, from docs/development/coding-standards.md:\n\n${result.unfinishedChanges}`,
69
+ `Unfinished changes, from docs/development/coding-standards.md. If none are left, the section says only "None":\n\n${result.unfinishedChanges}`,
70
70
  );
71
71
  }
72
72
  if (result.failures.length === 0) {
@@ -1,5 +1,5 @@
1
1
  // Reads what the checks need from the project: its files, and the
2
- // exceptions it has recorded in docs/development/coding-standards.md.
2
+ // sections of its Markdown docs.
3
3
  import { execFileSync } from "node:child_process";
4
4
  import { existsSync, readFileSync } from "node:fs";
5
5
  import path from "node:path";
@@ -15,13 +15,6 @@ export const PACKAGE_DIRECTORY = path.resolve(
15
15
  export const CODING_STANDARDS_PATH =
16
16
  "docs/development/coding-standards.md";
17
17
 
18
- const NO_VALUE_WORDS = new Set(["none", "no differences"]);
19
-
20
- // A recorded exception starts with its standard number:
21
- // "7. Prettier — skipped", "- 12.1. Constants — changed".
22
- const STANDARD_NUMBER_PATTERN =
23
- /^\s*(?:[-*]\s+)?(?:\*\*)?(\d+(?:\.\d+)?)\.\s/;
24
-
25
18
  export const readTextFile = ({ projectDirectory, filePath }) => {
26
19
  const fullPath = path.join(projectDirectory, filePath);
27
20
  return existsSync(fullPath)
@@ -69,41 +62,3 @@ export const readSection = ({ markdown, heading }) => {
69
62
  }
70
63
  return sectionLines.join("\n").trim();
71
64
  };
72
-
73
- const hasContent = (sectionText) => {
74
- const words = sectionText
75
- .replaceAll(/[".]/g, "")
76
- .trim()
77
- .toLowerCase();
78
- return words.length > 0 && !NO_VALUE_WORDS.has(words);
79
- };
80
-
81
- export const readRecordedExceptions = ({ projectDirectory }) => {
82
- const markdown =
83
- readTextFile({
84
- projectDirectory,
85
- filePath: CODING_STANDARDS_PATH,
86
- }) ?? "";
87
- const details = readSection({ markdown, heading: "Details" });
88
- const standardNumbers = new Set(
89
- details
90
- .split("\n")
91
- .map((line) => STANDARD_NUMBER_PATTERN.exec(line)?.[1])
92
- .filter(Boolean),
93
- );
94
- const componentsSection = readSection({
95
- markdown,
96
- heading: "Components for the standards",
97
- });
98
- const unfinishedSection = readSection({
99
- markdown,
100
- heading: "Unfinished changes",
101
- });
102
- return {
103
- standardNumbers,
104
- componentsText: componentsSection.toLowerCase(),
105
- unfinishedChanges: hasContent(unfinishedSection)
106
- ? unfinishedSection
107
- : undefined,
108
- };
109
- };
@@ -0,0 +1,176 @@
1
+ // Reads the exceptions a project has recorded in
2
+ // docs/development/coding-standards.md: which standards it skips or
3
+ // changes, for which files, and what is left unfinished.
4
+ import { readFileSync } from "node:fs";
5
+ import path from "node:path";
6
+
7
+ import {
8
+ CODING_STANDARDS_PATH,
9
+ PACKAGE_DIRECTORY,
10
+ readSection,
11
+ readTextFile,
12
+ } from "./projectFiles.mjs";
13
+
14
+ const NO_VALUE_WORDS = new Set(["none", "no differences"]);
15
+
16
+ // Any line that starts with a number, which is read as a standard
17
+ // number: "7. Prettier", "- 12.1. Constants", "**6. ESLint**".
18
+ const NUMBERED_LINE_PATTERN =
19
+ /^\s*(?:[-*]\s+)?(?:\*\*)?(\d+(?:\.\d+)?)\.\s/;
20
+
21
+ // A recorded exception, named as in the setup list: "7. Prettier —
22
+ // skipped: the project uses Biome", or "4. Every function and
23
+ // component has a test file — changed for `app/api/**`: legacy code".
24
+ const EXCEPTION_PATTERN =
25
+ /^\s*(?:[-*]\s+)?(?:\*\*)?(\d+(?:\.\d+)?)\.\s+(.+?)(?:\*\*)?\s+[—–-]+\s+(?:\*\*)?(?:skipped|changed)\b(.*)$/i;
26
+
27
+ const FILES_CLAUSE_PATTERN = /^\s*for\s+([^:]+)/i;
28
+ const INLINE_CODE_PATTERN = /`([^`]+)`/g;
29
+ const SETUP_LIST_START = "These are the Activatus Code Standards.";
30
+ const SETUP_LIST_ITEM_PATTERN = /^\s*(\d+(?:\.\d+)?)\.\s+([^:,]+)/;
31
+
32
+ // Lowercase letters and digits only, so "ESLint" and "eslint," match.
33
+ const toComparableName = (name) =>
34
+ name.toLowerCase().replaceAll(/[^a-z\d]/g, "");
35
+
36
+ // The standard names, by number, from the list in
37
+ // docs/Guides/setup.md that a project records its choices against.
38
+ const readStandardNames = () => {
39
+ const setupText = readFileSync(
40
+ path.join(PACKAGE_DIRECTORY, "docs/Guides/setup.md"),
41
+ "utf8",
42
+ );
43
+ const lines = setupText.split("\n");
44
+ const startIndex = lines.findIndex((line) =>
45
+ line.startsWith(SETUP_LIST_START),
46
+ );
47
+ const listLines = lines.slice(startIndex + 1);
48
+ const endIndex = listLines.findIndex((line) =>
49
+ line.startsWith("```"),
50
+ );
51
+ return new Map(
52
+ listLines
53
+ .slice(0, endIndex)
54
+ .map((line) => SETUP_LIST_ITEM_PATTERN.exec(line))
55
+ .filter(Boolean)
56
+ .map((match) => [match[1], match[2].trim()]),
57
+ );
58
+ };
59
+
60
+ // The files after "for", each in backticks. Undefined when there is a
61
+ // "for" but no file in backticks: read as no files, it would cover the
62
+ // whole standard.
63
+ const readFileGlobs = (textAfterVerb) => {
64
+ const filesClause = FILES_CLAUSE_PATTERN.exec(textAfterVerb)?.[1];
65
+ if (filesClause === undefined) {
66
+ return [];
67
+ }
68
+ const fileGlobs = Array.from(
69
+ filesClause.matchAll(INLINE_CODE_PATTERN),
70
+ (match) => match[1],
71
+ );
72
+ return fileGlobs.length > 0 ? fileGlobs : undefined;
73
+ };
74
+
75
+ // One line under Details: an exception, a line that looks like one
76
+ // but is not read as one, or anything else.
77
+ const readDetailsLine = ({ line, standardNames }) => {
78
+ const standard = NUMBERED_LINE_PATTERN.exec(line)?.[1];
79
+ if (standard === undefined) {
80
+ return {};
81
+ }
82
+ const match = EXCEPTION_PATTERN.exec(line);
83
+ if (match === null) {
84
+ return {
85
+ unreadLine: `"${line.trim()}" starts with a number, so it reads as standard ${standard}, but it is not shaped like an exception: "${standard}. Name — skipped: reason". Write it as an exception, or start the line without a number`,
86
+ };
87
+ }
88
+ const standardName = standardNames.get(standard);
89
+ const recordedName = toComparableName(match[2]);
90
+ if (
91
+ standardName === undefined ||
92
+ !toComparableName(standardName).startsWith(recordedName)
93
+ ) {
94
+ return {
95
+ unreadLine: `"${line.trim()}" names standard ${standard}, which is ${standardName === undefined ? "not on the standards list" : `"${standardName}"`}. Use the number and name from the list in docs/Guides/setup.md`,
96
+ };
97
+ }
98
+ const fileGlobs = readFileGlobs(match[3]);
99
+ if (fileGlobs === undefined) {
100
+ return {
101
+ unreadLine: `"${line.trim()}" names files after "for", but none in backticks, so it would cover every file. Put each path in backticks: for \`app/api/**\``,
102
+ };
103
+ }
104
+ return { exception: { standard, fileGlobs } };
105
+ };
106
+
107
+ const hasContent = (sectionText) => {
108
+ const words = sectionText
109
+ .replaceAll(/[".]/g, "")
110
+ .trim()
111
+ .toLowerCase();
112
+ return words.length > 0 && !NO_VALUE_WORDS.has(words);
113
+ };
114
+
115
+ export const readRecordedExceptions = ({ projectDirectory }) => {
116
+ const markdown =
117
+ readTextFile({
118
+ projectDirectory,
119
+ filePath: CODING_STANDARDS_PATH,
120
+ }) ?? "";
121
+ const standardNames = readStandardNames();
122
+ const detailsLines = readSection({ markdown, heading: "Details" })
123
+ .split("\n")
124
+ .map((line) => readDetailsLine({ line, standardNames }));
125
+ const componentsSection = readSection({
126
+ markdown,
127
+ heading: "Components for the standards",
128
+ });
129
+ const unfinishedSection = readSection({
130
+ markdown,
131
+ heading: "Unfinished changes",
132
+ });
133
+ return {
134
+ exceptions: detailsLines
135
+ .map(({ exception }) => exception)
136
+ .filter(Boolean),
137
+ unreadLines: detailsLines
138
+ .map(({ unreadLine }) => unreadLine)
139
+ .filter(Boolean),
140
+ componentsText: componentsSection.toLowerCase(),
141
+ unfinishedChanges: hasContent(unfinishedSection)
142
+ ? unfinishedSection
143
+ : undefined,
144
+ };
145
+ };
146
+
147
+ const escapeForPattern = (text) =>
148
+ text.replaceAll(/[.+^${}()|[\]\\]/g, String.raw`\$&`);
149
+
150
+ // "app/api/**" matches every file under app/api/, "*" stays inside
151
+ // one folder, and a glob ending in "/" means the whole folder.
152
+ const toGlobPattern = (fileGlob) => {
153
+ const fullGlob = fileGlob.endsWith("/")
154
+ ? `${fileGlob}**`
155
+ : fileGlob;
156
+ const pattern = escapeForPattern(fullGlob)
157
+ .replaceAll("**", "\0")
158
+ .replaceAll("*", "[^/]*")
159
+ .replaceAll("?", "[^/]")
160
+ .replaceAll("\0", ".*");
161
+ return new RegExp(`^${pattern}$`);
162
+ };
163
+
164
+ // A finding is recorded when an exception covers its standard, and,
165
+ // if the exception names files, the finding's file is one of them.
166
+ export const isRecordedFinding = ({ finding, exceptions }) =>
167
+ exceptions
168
+ .filter((exception) => exception.standard === finding.standard)
169
+ .some(
170
+ (exception) =>
171
+ exception.fileGlobs.length === 0 ||
172
+ (finding.file !== undefined &&
173
+ exception.fileGlobs.some((fileGlob) =>
174
+ toGlobPattern(fileGlob).test(finding.file),
175
+ )),
176
+ );
@@ -1,5 +1,5 @@
1
- // Runs every check, and separates the findings for standards the
2
- // project has recorded as skipped or changed.
1
+ // Runs every check, and separates the findings the project has
2
+ // recorded as skipped or changed.
3
3
  import { readFileSync } from "node:fs";
4
4
  import path from "node:path";
5
5
 
@@ -14,8 +14,11 @@ import { checkStructure } from "./checkStructure.mjs";
14
14
  import {
15
15
  listProjectFiles,
16
16
  PACKAGE_DIRECTORY,
17
- readRecordedExceptions,
18
17
  } from "./projectFiles.mjs";
18
+ import {
19
+ isRecordedFinding,
20
+ readRecordedExceptions,
21
+ } from "./recordedExceptions.mjs";
19
22
 
20
23
  const readPackageVersion = () => {
21
24
  const packageText = readFileSync(
@@ -55,9 +58,24 @@ export const runChecks = ({ projectDirectory }) => {
55
58
  ...checkDocs({ projectDirectory, projectFiles }),
56
59
  ];
57
60
  const isRecorded = (finding) =>
58
- recordedExceptions.standardNumbers.has(finding.standard);
61
+ isRecordedFinding({
62
+ finding,
63
+ exceptions: recordedExceptions.exceptions,
64
+ });
65
+ // A line misread as an exception could hide any standard, so it is
66
+ // never hidden itself.
67
+ const unreadLineFindings = recordedExceptions.unreadLines.map(
68
+ (unreadLine) => ({
69
+ standard: "21",
70
+ message: `Under "Details" in docs/development/coding-standards.md: ${unreadLine}`,
71
+ page: "docs/Guides/setup.md#3-agree-the-standards",
72
+ }),
73
+ );
59
74
  return {
60
- failures: findings.filter((finding) => !isRecorded(finding)),
75
+ failures: [
76
+ ...unreadLineFindings,
77
+ ...findings.filter((finding) => !isRecorded(finding)),
78
+ ],
61
79
  recorded: findings.filter((finding) => isRecorded(finding)),
62
80
  unfinishedChanges: recordedExceptions.unfinishedChanges,
63
81
  };