@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.
- package/README.md +27 -3
- package/docs/Guides/migrating.md +6 -6
- package/docs/Guides/regression-checks.md +18 -3
- package/docs/Guides/setup.md +29 -19
- package/docs/Standards/documentation.md +1 -0
- package/docs/Standards/eslint.md +9 -9
- package/docs/Standards/prettier.md +5 -1
- package/docs/Standards/readable-code.md +2 -2
- package/docs/Structure/folder-structure.md +65 -24
- package/docs/templates.mdx +14 -0
- package/docs/version-history.md +72 -9
- package/package.json +1 -1
- package/scripts/verifyStandards/checkComponents.mjs +2 -0
- package/scripts/verifyStandards/checkConstants.mjs +22 -48
- package/scripts/verifyStandards/checkStructure.mjs +45 -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 +5 -4
- 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/tests/visual/playwright.config.mjs +5 -3
|
@@ -99,6 +99,7 @@ The project's docs are plain Markdown in `docs/`. **Every file is a Decision Doc
|
|
|
99
99
|
- **Read them before starting work** — the three docs in `docs/overview/` first, then the docs for the area being changed. Read the files directly; do not start the docs site to read them.
|
|
100
100
|
- **Check each doc's Status.** `Decided` is settled. `Current plan` may change. `Under evaluation` and `Not started` are **not decisions** — do not treat them as one and do not invent one. Ask.
|
|
101
101
|
- **Never invent a product decision to unblock yourself.** If the docs do not answer it, stop and ask.
|
|
102
|
+
- **Record a check only after it has run.** Never write 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.
|
|
102
103
|
- **Update the docs in the same change.** If a change makes a doc wrong, fix the doc and change its Updated date.
|
|
103
104
|
- Do not edit `docsSite/` unless the task is about the docs viewer itself.
|
|
104
105
|
|
|
@@ -123,7 +124,7 @@ This is the version the code follows, written in full so it pairs with the insta
|
|
|
123
124
|
Follow these rules in every change:
|
|
124
125
|
|
|
125
126
|
- **Every function and component has a test file**, created in the same change. One test file tests one function or one component.
|
|
126
|
-
- **No file longer than 300 lines.** Test files are exempt, and so are the
|
|
127
|
+
- **No file longer than 300 lines.** Test files are exempt, and so are the files in `lib/constants/`, which hold data only.
|
|
127
128
|
- **Every name is made of whole, human-readable words.** Variables, parameters, props, types, constants, form fields, files, folders, routes, database columns, scripts and environment variables — everything. No shortened words, no single letters (except `r` and `s`, below), no numbered names, not even for a loop counter or an event handler. Full rule: Human-Readable Names in the code standards (https://activatus-code-standards.vercel.app/docs/Standards/human-readable-names).
|
|
128
129
|
|
|
129
130
|
| Never | Always |
|
|
@@ -148,8 +149,8 @@ Follow these rules in every change:
|
|
|
148
149
|
- **Functions, never classes.**
|
|
149
150
|
- **One parameter per function.** Use a single object when more than one value is needed.
|
|
150
151
|
- **Return early.** Never nest more than three levels deep.
|
|
151
|
-
- **No magic numbers or strings.** Use named constants. Only `-1`, `0` and `1` stay bare.
|
|
152
|
-
- **Links
|
|
152
|
+
- **No magic numbers or strings.** Use named constants. Only `-1`, `0` and `1` stay bare. Put the unit in the name: `SESSION_TIMEOUT_MILLISECONDS`. Config files keep their numbers at the top of the file.
|
|
153
|
+
- **Links go in `r` and text people see or hear goes in `s`**, both in `lib/constants/`, never written straight into a component. The keys of `s` become the translation keys when the site gets more languages. **Every other value lives with the code that uses it until it is shared:** a number, list, status or internal string (ids, keys, event names, log messages) one file uses is a named constant at the top of that file. Once more than one file needs it, it moves to the file in `lib/constants/` that fits, such as `numbers.ts`, `animation.ts`, `classNames.ts` or `status.ts`, or a new file named after what it holds. Stand-in data for local development goes in `noData.ts`, named `NO_DATA_` plus the thing it replaces. **Not sure where a value goes?** Put it in `lib/constants/unsortedValues.ts` and carry on. At the end of the work, ask the person where each value in it goes, move each one there, and delete the file. Constants in `lib/constants/` get real types from `lib/types/`, never `as const`. No `"#"` placeholder links: show plain text with a `{/* TODO: … */}` until the page exists. `r` and `s` are the only single-letter names allowed anywhere. Import constants in one line: `import { r, s } from "@/lib/constants";`. Full rule: https://activatus-code-standards.vercel.app/docs/Structure/folder-structure#constants
|
|
153
154
|
- **No nested ternaries. No boolean flag parameters.**
|
|
154
155
|
- **No `any`, no non-null `!`, no `as` cast without a comment saying why.**
|
|
155
156
|
- **Named exports only**, except where a tool requires a default export.
|
|
@@ -173,7 +174,7 @@ Follow these rules in every change:
|
|
|
173
174
|
|
|
174
175
|
**Lint must pass before you finish.** Run `pnpm lint` and `pnpm test` before finishing any task, and fix every error by changing the code. After setting up or updating the standards, also run `pnpm standards:check`.
|
|
175
176
|
|
|
176
|
-
**Never switch a lint rule off to make an error go away.** Do not add `eslint-disable` comments, edit `eslint.config.mjs` or `eslint.overrides.mjs`, or move files to hide them. The only exceptions are `let
|
|
177
|
+
**Never switch a lint rule off to make an error go away.** Do not add `eslint-disable` comments, edit `eslint.config.mjs` or `eslint.overrides.mjs`, or move files to hide them. The only exceptions are `let`, a type cast and an `as const` that cannot be avoided, each on a single line with a reason after ` -- `. If a rule seems impossible to satisfy, stop and ask.
|
|
177
178
|
|
|
178
179
|
When you report a lint error to the person, explain it in plain English: what is wrong, why it matters, and what you did to fix it.
|
|
179
180
|
|
|
@@ -14,7 +14,7 @@ Every Activatus project follows the same standards, so people and agents can mov
|
|
|
14
14
|
|
|
15
15
|
## Details
|
|
16
16
|
|
|
17
|
-
[For each standard this project skips or changes, at setup or later: its number and name from the setup list,
|
|
17
|
+
[For each standard this project skips or changes, at setup or later, one line: its number and name from the setup list, "skipped" or "changed", why, and the date the person agreed. For example: "7. Prettier — skipped: the project uses Biome for formatting (2026-10-23)." An exception for only some files names them in backticks after "for": "4. Every function and component has a test file — changed for `app/api/**`: legacy routes, tested when replaced (2026-10-27)." Start no other line here with a number: `pnpm standards:check` reads every numbered line as an exception. Every rule in `eslint.overrides.mjs` has an entry here. If nothing differs, write "No differences".]
|
|
18
18
|
|
|
19
19
|
- Working with the agent: GitHub repo [link or None]; Linear project [project or None]; status circles [yes or no]; ask before every commit and push [yes or no]; told about decisions [yes or no] ([YYYY-MM-DD]).
|
|
20
20
|
|
|
@@ -24,7 +24,7 @@ Every Activatus project follows the same standards, so people and agents can mov
|
|
|
24
24
|
|
|
25
25
|
## Unfinished changes
|
|
26
26
|
|
|
27
|
-
[Changes from a code standards version that are not done yet, each with its version and number, what is left, and where it is being done. For example: "Version 2, change 4: the standard ESLint config is not switched on yet. Being done in ACT-120." If there are none, write "None".]
|
|
27
|
+
[Changes from a code standards version that are not done yet, each with its version and number, what is left, and where it is being done. For example: "Version 2, change 4: the standard ESLint config is not switched on yet. Being done in ACT-120." If there are none, write exactly "None", with nothing after it: a note after "None" reads as an unfinished change.]
|
|
28
28
|
|
|
29
29
|
## Related
|
|
30
30
|
|
|
@@ -121,8 +121,8 @@ const config = [
|
|
|
121
121
|
rules: { "max-lines": "off", "no-magic-numbers": "off" },
|
|
122
122
|
},
|
|
123
123
|
{
|
|
124
|
-
// The
|
|
125
|
-
files: ["lib/constants
|
|
124
|
+
// The constants files are data, not logic, so they can be long.
|
|
125
|
+
files: ["lib/constants/*.{js,mjs}"],
|
|
126
126
|
rules: { "max-lines": "off" },
|
|
127
127
|
},
|
|
128
128
|
{
|
|
@@ -202,8 +202,8 @@ const config = [
|
|
|
202
202
|
},
|
|
203
203
|
},
|
|
204
204
|
{
|
|
205
|
-
// The
|
|
206
|
-
files: ["lib/constants
|
|
205
|
+
// The constants files are data, not logic, so they can be long.
|
|
206
|
+
files: ["lib/constants/*.ts"],
|
|
207
207
|
rules: { "max-lines": "off" },
|
|
208
208
|
},
|
|
209
209
|
{
|
|
@@ -204,8 +204,8 @@ const config = [
|
|
|
204
204
|
},
|
|
205
205
|
},
|
|
206
206
|
{
|
|
207
|
-
// The
|
|
208
|
-
files: ["lib/constants
|
|
207
|
+
// The constants files are data, not logic, so they can be long.
|
|
208
|
+
files: ["lib/constants/*.ts"],
|
|
209
209
|
rules: { "max-lines": "off" },
|
|
210
210
|
},
|
|
211
211
|
{
|
|
@@ -184,8 +184,8 @@ const config = [
|
|
|
184
184
|
},
|
|
185
185
|
},
|
|
186
186
|
{
|
|
187
|
-
// The
|
|
188
|
-
files: ["lib/constants
|
|
187
|
+
// The constants files are data, not logic, so they can be long.
|
|
188
|
+
files: ["lib/constants/*.ts"],
|
|
189
189
|
rules: { "max-lines": "off" },
|
|
190
190
|
},
|
|
191
191
|
{
|
|
@@ -2,8 +2,10 @@
|
|
|
2
2
|
// See "Regression Checks for Refactors" in the code standards.
|
|
3
3
|
import { defineConfig } from "@playwright/test";
|
|
4
4
|
|
|
5
|
-
// The baseline
|
|
6
|
-
//
|
|
5
|
+
// The baseline comes from the last known-good page, never from the
|
|
6
|
+
// branch being tested: the live production site, or the branch's last
|
|
7
|
+
// commit before the refactor, served on its own. Set it before running
|
|
8
|
+
// test:visual:update.
|
|
7
9
|
const PRODUCTION_URL = process.env.VISUAL_PRODUCTION_URL;
|
|
8
10
|
const isUpdatingBaseline = process.env.VISUAL_UPDATE === "true";
|
|
9
11
|
// The project's own production build, on a port of its own.
|
|
@@ -13,7 +15,7 @@ const SERVER_START_TIMEOUT_MILLISECONDS = 300_000;
|
|
|
13
15
|
|
|
14
16
|
if (isUpdatingBaseline && !PRODUCTION_URL) {
|
|
15
17
|
throw new Error(
|
|
16
|
-
"Set VISUAL_PRODUCTION_URL to the
|
|
18
|
+
"Set VISUAL_PRODUCTION_URL to the last known-good page before updating the baseline: the live site, or the last commit before the refactor, served on its own.",
|
|
17
19
|
);
|
|
18
20
|
}
|
|
19
21
|
|