@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.
@@ -1,15 +1,32 @@
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
+ // The project's components/ has no index.ts of its own: code imports
17
+ // from a category, "@/components/ui".
18
+ const COMPONENTS_INDEX_PATTERN =
19
+ /^(?:src\/)?components\/index\.(?:ts|tsx|js|jsx)$/;
20
+ // A component file directly in components/: components/Foo.tsx.
21
+ const LOOSE_COMPONENT_FILE_PATTERN =
22
+ /^(?:src\/)?components\/[A-Z][A-Za-z0-9]*\.(?:tsx|jsx)$/;
23
+ const WHERE_COMPONENTS_LIVE_PAGE =
24
+ "docs/Structure/folder-structure.md#-where-components-live";
9
25
  const NESTED_PAGE =
10
26
  "docs/Structure/component-organization.md#nested-components";
11
27
 
12
- // A component folder holds a PascalCase component file, Card.tsx.
28
+ // A component folder holds a PascalCase component file, Card.tsx. A
29
+ // components/ folder never is one, even with a file loose in it.
13
30
  const listComponentFolders = ({ projectFiles }) =>
14
31
  new Set(
15
32
  projectFiles
@@ -17,7 +34,10 @@ const listComponentFolders = ({ projectFiles }) =>
17
34
  .filter((filePath) =>
18
35
  COMPONENT_FILE_PATTERN.test(path.posix.basename(filePath)),
19
36
  )
20
- .map((filePath) => path.posix.dirname(filePath)),
37
+ .map((filePath) => path.posix.dirname(filePath))
38
+ .filter(
39
+ (folder) => path.posix.basename(folder) !== COMPONENTS_FOLDER,
40
+ ),
21
41
  );
22
42
 
23
43
  // The topmost component folder above this one, or undefined for a
@@ -57,22 +77,57 @@ const checkSubComponentFolders = ({ componentFolders }) =>
57
77
  .filter(({ folder, flatFolder }) => folder !== flatFolder)
58
78
  .map(({ folder, rootComponent, flatFolder }) => ({
59
79
  standard: "13",
80
+ file: `${folder}/`,
60
81
  message: `${folder} is not flat in ${rootComponent}/${COMPONENTS_FOLDER}/. Move it to ${flatFolder}`,
61
82
  page: NESTED_PAGE,
62
83
  }));
63
84
 
85
+ const checkLooseComponentFolders = ({ projectFiles }) => {
86
+ const looseFolders = new Set(
87
+ projectFiles
88
+ .map((filePath) => TOP_COMPONENTS_FOLDER_PATTERN.exec(filePath))
89
+ .filter(Boolean)
90
+ .filter((match) => !COMPONENTS_HOMES.has(match[2]))
91
+ .map((match) => match[1]),
92
+ );
93
+ const looseFiles = projectFiles.filter((filePath) =>
94
+ LOOSE_COMPONENT_FILE_PATTERN.test(filePath),
95
+ );
96
+ return [...looseFolders, ...looseFiles].map((loosePath) => ({
97
+ standard: "13",
98
+ file: looseFiles.includes(loosePath)
99
+ ? loosePath
100
+ : `${loosePath}/`,
101
+ 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`,
102
+ page: WHERE_COMPONENTS_LIVE_PAGE,
103
+ }));
104
+ };
105
+
106
+ const checkComponentsIndex = ({ projectFiles }) =>
107
+ projectFiles
108
+ .filter((filePath) => COMPONENTS_INDEX_PATTERN.test(filePath))
109
+ .map((filePath) => ({
110
+ standard: "13",
111
+ file: filePath,
112
+ message: `${filePath} should not exist. Import from a category instead, such as "@/components/ui", and delete it`,
113
+ page: "docs/Structure/import-organization.md#importing-components",
114
+ }));
115
+
64
116
  const checkHomepage = ({ projectFiles }) =>
65
117
  projectFiles
66
118
  .filter((filePath) => UNGROUPED_HOMEPAGE_PATTERN.test(filePath))
67
119
  .map((filePath) => ({
68
120
  standard: "13",
121
+ file: filePath,
69
122
  message: `${filePath} is the homepage outside its route group. Move it to app/(homepage)/`,
70
- page: "docs/Structure/folder-structure.md#-where-components-live",
123
+ page: WHERE_COMPONENTS_LIVE_PAGE,
71
124
  }));
72
125
 
73
126
  export const checkStructure = ({ projectFiles }) => {
74
127
  const componentFolders = listComponentFolders({ projectFiles });
75
128
  return [
129
+ ...checkLooseComponentFolders({ projectFiles }),
130
+ ...checkComponentsIndex({ projectFiles }),
76
131
  ...checkSubComponentFolders({ componentFolders }),
77
132
  ...checkHomepage({ projectFiles }),
78
133
  ];
@@ -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
  };
@@ -0,0 +1,7 @@
1
+ # pnpm rewrites this on every install, in its own style.
2
+ pnpm-workspace.yaml
3
+ # Copied from the code standards and compared word for word by
4
+ # pnpm standards:check, so Prettier leaves them as they are.
5
+ AGENTS.md
6
+ .agents/skills/
7
+ .claude/commands/
@@ -80,33 +80,11 @@ Example: `🟢 [ABC-12](https://linear.app/[workspace]/issue/ABC-12) Short title
80
80
  | --- | --- | --- |
81
81
  | `[VARIABLE_NAME]` | [Yes / No] | [What it is for] |
82
82
 
83
- ## Ontology
84
-
85
- Activatus uses a fixed vocabulary, the ontology, in two parts:
86
-
87
- - **Code words** — component, utils, Decision Doc and the rest — are defined in the code standards: https://activatus-code-standards.vercel.app/docs/ontology
88
- - **Product words** — what this project builds and how its work is planned — are defined in `docs/product/ontology.md`.
89
-
90
- - **Read both before starting work.** If the project's ontology gives a code word a different meaning, the code standards win — point the difference out.
91
- - **Use their terms** in code, docs, database names and messages — never a synonym. It is `utils`, not `helpers` or `utilities`.
92
- - **Never use a term either ontology has removed.**
93
- - If a person uses a word loosely, work out which ontology term they mean and use that term. **If you are not sure what a term means, ask.** Do not guess and do not invent a new term.
94
-
95
- ## Documentation
96
-
97
- The project's docs are plain Markdown in `docs/`. **Every file is a Decision Doc**: it states one decision and why it was made.
98
-
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
- - **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
- - **Never invent a product decision to unblock yourself.** If the docs do not answer it, stop and ask.
102
- - **Update the docs in the same change.** If a change makes a doc wrong, fix the doc and change its Updated date.
103
- - Do not edit `docsSite/` unless the task is about the docs viewer itself.
104
-
105
83
  <!-- code-standards:start -->
106
84
 
107
85
  ## Code standards
108
86
 
109
- **This section is copied from the code standards and replaced on every update.** Never edit it to describe a project exception: record exceptions in `docs/development/coding-standards.md`. Anything else the project adds, such as the block a framework writes, goes outside this section.
87
+ **This section, and the Ontology and Documentation sections after it, are copied from the code standards and replaced on every update.** Never edit it to describe a project exception: record exceptions in `docs/development/coding-standards.md`. Anything else the project adds, such as the block a framework writes, goes outside this section.
110
88
 
111
89
  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.
112
90
 
@@ -123,7 +101,7 @@ This is the version the code follows, written in full so it pairs with the insta
123
101
  Follow these rules in every change:
124
102
 
125
103
  - **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 seven constants files in `lib/constants/`, which hold data only.
104
+ - **No file longer than 300 lines.** Test files are exempt, and so are the files in `lib/constants/`, which hold data only.
127
105
  - **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
106
 
129
107
  | Never | Always |
@@ -142,14 +120,16 @@ Follow these rules in every change:
142
120
  - **The linter only checks some names.** Folders, props, form fields, database columns, routes and environment variables are not linted — check every one of them yourself.
143
121
  - **Always `const`.** Never `var`. Use `let` only when a value must be reassigned, with `// eslint-disable-next-line no-restricted-syntax -- <reason>` on the line above.
144
122
  - **Arrow functions everywhere.** Never use the `function` keyword: `export const Button = () => {}`, not `export function Button() {}`.
123
+ - **Never sort imports by hand.** Prettier sorts them on `pnpm format`. Side-effect imports, such as CSS, go after every other import.
124
+ - **Import components from their category:** `import { Button } from "@/components/ui";`. There is no `components/index.ts`. A category's `index.ts` exports only components a Client Component can import: a component that reaches server-only code starts with `import "server-only";`, is left out of it, and is imported from its own folder, such as `@/components/layout/siteHeader`.
145
125
  - **No circular imports, ever.** A file never imports a file that imports it back. Inside a folder, import files directly — never through the folder's own `index.ts` — and never import a parent component from its sub-component.
146
126
  - **Define before use.** A function or variable is written above the code that uses it.
147
127
  - **A function does one thing.**
148
128
  - **Functions, never classes.**
149
129
  - **One parameter per function.** Use a single object when more than one value is needed.
150
130
  - **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. 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. Every object and list constant except `r` and `s` gets a real type from `lib/types/`, in files named by topic; a single number or string needs none. `lib/types/` reads a constant's type with `import type` straight from its file, never through `@/lib/constants`. 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
131
+ - **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.
132
+ - **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
133
  - **No nested ternaries. No boolean flag parameters.**
154
134
  - **No `any`, no non-null `!`, no `as` cast without a comment saying why.**
155
135
  - **Named exports only**, except where a tool requires a default export.
@@ -177,6 +157,29 @@ Follow these rules in every change:
177
157
 
178
158
  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
159
 
160
+ ## Ontology
161
+
162
+ Activatus uses a fixed vocabulary, the ontology, in two parts:
163
+
164
+ - **Code words** — component, utils, Decision Doc and the rest — are defined in the code standards: https://activatus-code-standards.vercel.app/docs/ontology
165
+ - **Product words** — what this project builds and how its work is planned — are defined in `docs/product/ontology.md`.
166
+
167
+ - **Read both before starting work.** If the project's ontology gives a code word a different meaning, the code standards win — point the difference out.
168
+ - **Use their terms** in code, docs, database names and messages — never a synonym. It is `utils`, not `helpers` or `utilities`.
169
+ - **Never use a term either ontology has removed.**
170
+ - If a person uses a word loosely, work out which ontology term they mean and use that term. **If you are not sure what a term means, ask.** Do not guess and do not invent a new term.
171
+
172
+ ## Documentation
173
+
174
+ The project's docs are plain Markdown in `docs/`. **Every file is a Decision Doc**: it states one decision and why it was made.
175
+
176
+ - **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.
177
+ - **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.
178
+ - **Never invent a product decision to unblock yourself.** If the docs do not answer it, stop and ask.
179
+ - **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.
180
+ - **Update the docs in the same change.** If a change makes a doc wrong, fix the doc and change its Updated date.
181
+ - If the project has a `docsSite/`, do not edit it unless the task is about the docs viewer itself.
182
+
180
183
  <!-- code-standards:end -->
181
184
 
182
185
  ## Available skills
@@ -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, 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".]
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 "None", with no note 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 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}"],
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 seven constants files are data, not logic, so they can be long.
206
- files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
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 seven constants files are data, not logic, so they can be long.
208
- files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
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 seven constants files are data, not logic, so they can be long.
188
- files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
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
  {
@@ -1,4 +1,4 @@
1
- /** @type {import("prettier").Config & import("prettier-plugin-tailwindcss").PluginOptions} */
1
+ /** @type {import("prettier").Config & import("@ianvs/prettier-plugin-sort-imports").PluginConfig & import("prettier-plugin-tailwindcss").PluginOptions} */
2
2
  const config = {
3
3
  // Short lines, so code reads well on a phone.
4
4
  printWidth: 70,
@@ -12,7 +12,25 @@ const config = {
12
12
  arrowParens: "always",
13
13
  semi: true,
14
14
  endOfLine: "lf",
15
- plugins: ["prettier-plugin-tailwindcss"],
15
+ // The Tailwind plugin must stay last.
16
+ plugins: [
17
+ "@ianvs/prettier-plugin-sort-imports",
18
+ "prettier-plugin-tailwindcss",
19
+ ],
20
+ // Node's own modules, packages, the project's @/ aliases, then
21
+ // ../ and ./, with a blank line between groups. Side-effect
22
+ // imports, such as CSS, never move.
23
+ importOrder: [
24
+ "<BUILTIN_MODULES>",
25
+ "",
26
+ "<THIRD_PARTY_MODULES>",
27
+ "",
28
+ "^@/",
29
+ "",
30
+ "^[.][.]/",
31
+ "",
32
+ "^[.]/",
33
+ ],
16
34
  tailwindStylesheet: "./app/globals.css",
17
35
  overrides: [
18
36
  {