@activatus/code-standards 3.2.0 → 3.2.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/docs/Guides/migrating.md +11 -3
- package/docs/Guides/setup.md +37 -28
- package/docs/Standards/eslint.md +9 -9
- package/docs/Standards/readable-code.md +2 -2
- package/docs/Standards/working-with-agents.md +5 -1
- package/docs/Structure/folder-structure.md +111 -8
- package/docs/version-history.md +113 -19
- package/package.json +1 -1
- package/scripts/verifyStandards/checkAgentFiles.mjs +50 -8
- package/scripts/verifyStandards/checkConstants.mjs +65 -0
- package/scripts/verifyStandards/checkRecordedAnswers.mjs +87 -0
- package/scripts/verifyStandards/checkRequiredFiles.mjs +1 -30
- package/scripts/verifyStandards/checkStructure.mjs +79 -0
- package/scripts/verifyStandards/formatReport.mjs +3 -1
- package/scripts/verifyStandards/runChecks.mjs +9 -7
- package/static/templates/AGENTS.md +9 -6
- package/static/templates/docs/development/coding-standards.md +2 -0
- 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
|
@@ -7,23 +7,22 @@ import { checkAgentFiles } from "./checkAgentFiles.mjs";
|
|
|
7
7
|
import { checkComponents } from "./checkComponents.mjs";
|
|
8
8
|
import { checkConfigFiles } from "./checkConfigFiles.mjs";
|
|
9
9
|
import { checkDocs } from "./checkDocs.mjs";
|
|
10
|
+
import { checkConstants } from "./checkConstants.mjs";
|
|
11
|
+
import { checkRecordedAnswers } from "./checkRecordedAnswers.mjs";
|
|
10
12
|
import { checkRequiredFiles } from "./checkRequiredFiles.mjs";
|
|
13
|
+
import { checkStructure } from "./checkStructure.mjs";
|
|
11
14
|
import {
|
|
12
15
|
listProjectFiles,
|
|
13
16
|
PACKAGE_DIRECTORY,
|
|
14
17
|
readRecordedExceptions,
|
|
15
18
|
} from "./projectFiles.mjs";
|
|
16
19
|
|
|
17
|
-
const
|
|
20
|
+
const readPackageVersion = () => {
|
|
18
21
|
const packageText = readFileSync(
|
|
19
22
|
path.join(PACKAGE_DIRECTORY, "package.json"),
|
|
20
23
|
"utf8",
|
|
21
24
|
);
|
|
22
|
-
|
|
23
|
-
".",
|
|
24
|
-
1,
|
|
25
|
-
);
|
|
26
|
-
return Number(majorVersion);
|
|
25
|
+
return JSON.parse(packageText).version;
|
|
27
26
|
};
|
|
28
27
|
|
|
29
28
|
export const runChecks = ({ projectDirectory }) => {
|
|
@@ -40,10 +39,13 @@ export const runChecks = ({ projectDirectory }) => {
|
|
|
40
39
|
...checkAgentFiles({
|
|
41
40
|
projectDirectory,
|
|
42
41
|
templatesDirectory,
|
|
43
|
-
|
|
42
|
+
packageVersion: readPackageVersion(),
|
|
44
43
|
}),
|
|
45
44
|
...checkConfigFiles({ projectDirectory, templatesDirectory }),
|
|
46
45
|
...checkRequiredFiles({ templatesDirectory, projectFiles }),
|
|
46
|
+
...checkConstants({ projectFiles }),
|
|
47
|
+
...checkStructure({ projectFiles }),
|
|
48
|
+
...checkRecordedAnswers({ projectDirectory }),
|
|
47
49
|
...checkComponents({
|
|
48
50
|
projectDirectory,
|
|
49
51
|
projectFiles,
|
|
@@ -42,6 +42,7 @@
|
|
|
42
42
|
[How this project runs its work. These are the project's own decisions, not part of the code standards. Say where they are written up (usually `docs/development/`), then list the rules an agent must follow:]
|
|
43
43
|
|
|
44
44
|
- **Who commits**: [whether AI agents may commit, push or make branches, and when. If the person said yes to asking before committing during setup: "Ask the person before every commit and push, and wait for a clear yes to that specific action. A yes covers one action only." If they said no, leave the asking rule out]
|
|
45
|
+
- **Decisions**: [Optional. If the person said yes to being told about decisions during setup: "Tell the person about each coding decision you make that the code standards do not cover, in the summary at the end of the task." Delete this line if they said no]
|
|
45
46
|
- **Branches**: [how branches are named]
|
|
46
47
|
- **Commit messages**: [the commit message format]
|
|
47
48
|
- **Pull requests**: [review and CI requirements, and where Pull Requests merge to]
|
|
@@ -109,18 +110,20 @@ The project's docs are plain Markdown in `docs/`. **Every file is a Decision Doc
|
|
|
109
110
|
|
|
110
111
|
This project follows the Activatus Code Standards. They are installed as the `@activatus/code-standards` dev dependency: **read them in `node_modules/@activatus/code-standards/docs/`**, which is the exact version this project uses. The same pages are at https://activatus-code-standards.vercel.app for people.
|
|
111
112
|
|
|
112
|
-
**Code standards version:** [the
|
|
113
|
+
**Code standards version:** [the full version of the installed `@activatus/code-standards` package when the standards were last applied, such as 3.2.2]
|
|
113
114
|
|
|
114
|
-
This is the version the code follows
|
|
115
|
+
This is the version the code follows, written in full so it pairs with the installed package. When the package is updated, read only the entries newer than this number in `node_modules/@activatus/code-standards/docs/version-history.md`, make the changes they list, then update this number. See "Updating to a newer version" in `docs/Guides/setup.md`.
|
|
116
|
+
|
|
117
|
+
**The standards are the base, and you build freely from there.** Most of a project's code is something the standards never mention: decide it yourself, and keep the decision the same across the codebase. This covers how the code is built: its structure, names, files and where each value goes. It never covers what the product does, says or shows: those are product decisions, and you ask. Only skipping, loosening or changing a standard needs the person's yes.
|
|
115
118
|
|
|
116
119
|
**Standards this project skips or changes** are listed, by number, in `docs/development/coding-standards.md`. Follow every other standard.
|
|
117
120
|
|
|
118
|
-
**The standards are this project's base. Never skip, loosen or change one on your own.** Ask the person first. If they agree, record it in `docs/development/coding-standards.md`, under "Details" (the standard's number and name, what is different, why, and the date), then make the change. ESLint changes go in `eslint.overrides.mjs` with a comment naming the standard's number. Never edit `eslint.config.mjs`: it is copied from the standards unchanged.
|
|
121
|
+
**The standards are this project's base. Never skip, loosen or change one on your own.** Ask the person first. If they agree, record it in `docs/development/coding-standards.md`, under "Details" (the standard's number and name, what is different, why, and the date), then make the change and keep going. Never stop the work to wait for a new version of the standards. ESLint changes go in `eslint.overrides.mjs` with a comment naming the standard's number. Never edit `eslint.config.mjs`: it is copied from the standards unchanged.
|
|
119
122
|
|
|
120
123
|
Follow these rules in every change:
|
|
121
124
|
|
|
122
125
|
- **Every function and component has a test file**, created in the same change. One test file tests one function or one component.
|
|
123
|
-
- **No file longer than 300 lines.** Test files are exempt, and so are
|
|
126
|
+
- **No file longer than 300 lines.** Test files are exempt, and so are the seven constants files in `lib/constants/`, which hold data only.
|
|
124
127
|
- **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).
|
|
125
128
|
|
|
126
129
|
| Never | Always |
|
|
@@ -145,8 +148,8 @@ Follow these rules in every change:
|
|
|
145
148
|
- **Functions, never classes.**
|
|
146
149
|
- **One parameter per function.** Use a single object when more than one value is needed.
|
|
147
150
|
- **Return early.** Never nest more than three levels deep.
|
|
148
|
-
- **No magic numbers or strings.** Use named constants. Only `-1`, `0` and `1` stay bare. Every named number goes in `lib/constants/numbers.ts`, even one only one file uses; config files keep theirs at the top. Put the unit in the name: `SESSION_TIMEOUT_MILLISECONDS`.
|
|
149
|
-
- **Links, text and stand-in data live in `lib/constants/`**, never written straight into a component. `r` holds every link (pages, outside sites, `mailto:`, `tel:`, `sms:`). `s` holds every piece of
|
|
151
|
+
- **No magic numbers or strings.** Use named constants. Only `-1`, `0` and `1` stay bare. Every loose named number goes in `lib/constants/numbers.ts`, even one only one file uses; config files keep theirs at the top. Put the unit in the name: `SESSION_TIMEOUT_MILLISECONDS`.
|
|
152
|
+
- **Links, text and stand-in data live in `lib/constants/`**, never written straight into a component. `r` holds every link (pages, outside sites, `mailto:`, `tel:`, `sms:`). `s` holds every piece of text people see or hear, and its keys become the translation keys when the site gets more languages. `noData.ts` holds stand-in data named `NO_DATA_` plus the thing it replaces (`NO_DATA_INSIGHTS`), used only in local development when the real source can't be reached, never in production. Dummy values sit at the top of `noData.ts`, never in `s`. `animation.ts` holds how and when things move and `artwork.ts` what is drawn, where it ends up and how it is grouped, each object kept whole with its numbers named by their keys, never lifted out into `numbers.ts`. `classNames.ts` holds Tailwind class strings shared between files, only when a component cannot hold them and they still repeat; a class name one file uses stays inline. Create each of these three only once there is something to put in it. These seven files are the only ones in `lib/constants/`, each never split by topic. Internal strings (ids, keys, event names, log messages) are not `s`: each is a key in the object that uses it, or a named constant at the top of the file that uses it. Where each value goes is the project's call: decide from the Constants table. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `docs/development/coding-standards.md`, and the work carries on. An id lives in the object that uses it, never as a loose constant; a list of keys a loop runs over stays a list. CSS goes in a stylesheet, never in a constant: styles for when JavaScript is off go in `globals.css` under `@media (scripting: none)`. A media query the code reads, such as one an animation library matches, is not CSS: it stays in its object in `animation.ts`. There is no component-level `constants.ts`: every value goes in `lib/constants/`, even if one file uses it, except internal strings, which stay with the code that uses them. `lib/constants/` never imports from `lib/types/`. Write each key out by name, `r.plans.starter`, never `r.plans[planId]`, except inside a loop over the list, which looks each item up by a key typed `keyof typeof r.plans`. No separate lookup objects that map a key to its link: `r` already is the lookup. No `"#"` placeholder links: show plain text with a `{/* TODO: … */}` until the page exists. Create `noData.ts` only once the data's shape is decided; stand-in data asked for before then carries `// Not the real schema: a basic shape to finish the task.` Import them all in one line, `import { NO_DATA_INSIGHTS, r, s } from "@/lib/constants";`. `r` and `s` are the only single-letter names allowed anywhere. Full rule: https://activatus-code-standards.vercel.app/docs/Structure/folder-structure#constants
|
|
150
153
|
- **No nested ternaries. No boolean flag parameters.**
|
|
151
154
|
- **No `any`, no non-null `!`, no `as` cast without a comment saying why.**
|
|
152
155
|
- **Named exports only**, except where a tool requires a default export.
|
|
@@ -16,6 +16,8 @@ Every Activatus project follows the same standards, so people and agents can mov
|
|
|
16
16
|
|
|
17
17
|
[For each standard this project skips or changes, at setup or later: its number and name from the setup list, what is different, why, and the date the person agreed. For example: "7. Prettier — skipped: the project uses Biome for formatting (2026-10-23)." Every rule in `eslint.overrides.mjs` has an entry here. If nothing differs, write "No differences".]
|
|
18
18
|
|
|
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
|
+
|
|
19
21
|
## Components for the standards
|
|
20
22
|
|
|
21
23
|
[Props-only components this project keeps in `components/ui/` that are not in the Design System Components list yet, each with its props, to be added in the next release of the standards. If there are none, write "None".]
|
|
@@ -121,8 +121,8 @@ const config = [
|
|
|
121
121
|
rules: { "max-lines": "off", "no-magic-numbers": "off" },
|
|
122
122
|
},
|
|
123
123
|
{
|
|
124
|
-
//
|
|
125
|
-
files: ["lib/constants/{routes,strings,numbers,noData}.{js,mjs}"],
|
|
124
|
+
// The seven constants files are data, not logic, so they can be long.
|
|
125
|
+
files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.{js,mjs}"],
|
|
126
126
|
rules: { "max-lines": "off" },
|
|
127
127
|
},
|
|
128
128
|
{
|
|
@@ -193,8 +193,8 @@ const config = [
|
|
|
193
193
|
},
|
|
194
194
|
},
|
|
195
195
|
{
|
|
196
|
-
//
|
|
197
|
-
files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
|
|
196
|
+
// The seven constants files are data, not logic, so they can be long.
|
|
197
|
+
files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
|
|
198
198
|
rules: { "max-lines": "off" },
|
|
199
199
|
},
|
|
200
200
|
{
|
|
@@ -195,8 +195,8 @@ const config = [
|
|
|
195
195
|
},
|
|
196
196
|
},
|
|
197
197
|
{
|
|
198
|
-
//
|
|
199
|
-
files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
|
|
198
|
+
// The seven constants files are data, not logic, so they can be long.
|
|
199
|
+
files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
|
|
200
200
|
rules: { "max-lines": "off" },
|
|
201
201
|
},
|
|
202
202
|
{
|
|
@@ -175,8 +175,8 @@ const config = [
|
|
|
175
175
|
},
|
|
176
176
|
},
|
|
177
177
|
{
|
|
178
|
-
//
|
|
179
|
-
files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
|
|
178
|
+
// The seven constants files are data, not logic, so they can be long.
|
|
179
|
+
files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
|
|
180
180
|
rules: { "max-lines": "off" },
|
|
181
181
|
},
|
|
182
182
|
{
|