@activatus/code-standards 3.3.1 → 3.3.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +28 -3
- package/docs/Guides/migrating.md +6 -6
- package/docs/Guides/regression-checks.md +9 -0
- package/docs/Guides/setup.md +29 -19
- package/docs/Standards/documentation.md +1 -0
- package/docs/Standards/eslint.md +10 -10
- package/docs/Standards/prettier.md +56 -5
- package/docs/Standards/readable-code.md +2 -2
- package/docs/Structure/folder-structure.md +61 -23
- package/docs/Structure/import-organization.md +31 -46
- package/docs/Structure/naming-conventions.md +1 -1
- package/docs/templates.mdx +14 -0
- package/docs/version-history.md +80 -5
- package/package.json +1 -1
- package/scripts/verifyStandards/checkComponents.mjs +2 -0
- package/scripts/verifyStandards/checkConstants.mjs +22 -48
- package/scripts/verifyStandards/checkStructure.mjs +60 -5
- package/scripts/verifyStandards/formatReport.mjs +1 -1
- package/scripts/verifyStandards/projectFiles.mjs +1 -46
- package/scripts/verifyStandards/recordedExceptions.mjs +176 -0
- package/scripts/verifyStandards/runChecks.mjs +23 -5
- package/static/templates/.prettierignore +7 -0
- package/static/templates/AGENTS.md +29 -26
- package/static/templates/docs/development/coding-standards.md +2 -2
- package/static/templates/eslint/base/eslint.config.mjs +2 -2
- package/static/templates/eslint/nextjs/eslint.config.mjs +2 -2
- package/static/templates/eslint/react/eslint.config.mjs +2 -2
- package/static/templates/eslint/typescript/eslint.config.mjs +2 -2
- package/static/templates/prettier.config.mjs +20 -2
|
@@ -1,15 +1,32 @@
|
|
|
1
|
-
// Standard 13:
|
|
2
|
-
//
|
|
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:
|
|
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
|
-
//
|
|
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
|
|
2
|
-
//
|
|
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
|
-
|
|
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:
|
|
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
|
};
|
|
@@ -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
|
|
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
|
|
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.
|
|
152
|
-
- **Links
|
|
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,
|
|
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
|
|
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
|
{
|
|
@@ -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
|
-
|
|
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
|
{
|