@activatus/code-standards 3.1.1 → 3.2.1
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 +92 -60
- package/docs/Guides/regression-checks.md +72 -0
- package/docs/Guides/setup.md +53 -17
- package/docs/Standards/documentation.md +38 -1
- package/docs/Standards/eslint.md +15 -13
- package/docs/Standards/readable-code.md +2 -2
- package/docs/Structure/folder-structure.md +98 -6
- package/docs/templates.mdx +10 -2
- package/docs/version-history.md +54 -7
- package/package.json +6 -2
- package/scripts/verifyStandards/checkAgentFiles.mjs +148 -0
- package/scripts/verifyStandards/checkComponents.mjs +129 -0
- package/scripts/verifyStandards/checkConfigFiles.mjs +230 -0
- package/scripts/verifyStandards/checkConstants.mjs +127 -0
- package/scripts/verifyStandards/checkDocs.mjs +86 -0
- package/scripts/verifyStandards/checkRecordedAnswers.mjs +83 -0
- package/scripts/verifyStandards/checkRequiredFiles.mjs +67 -0
- package/scripts/verifyStandards/checkStructure.mjs +79 -0
- package/scripts/verifyStandards/formatReport.mjs +76 -0
- package/scripts/verifyStandards/projectFiles.mjs +109 -0
- package/scripts/verifyStandards/runChecks.mjs +68 -0
- package/scripts/verifyStandards/verifyStandards.mjs +22 -0
- package/static/templates/AGENTS.md +4 -4
- package/static/templates/docs/development/coding-standards.md +6 -0
- package/static/templates/docs/overview/writing-docs.md +4 -0
- package/static/templates/eslint/base/eslint.config.mjs +2 -2
- package/static/templates/eslint/nextjs/eslint.config.mjs +4 -3
- package/static/templates/eslint/react/eslint.config.mjs +4 -3
- package/static/templates/eslint/typescript/eslint.config.mjs +2 -2
- package/static/templates/tests/visual/pageLayout.visual.ts +188 -0
- package/static/templates/tests/visual/playwright.config.mjs +65 -0
- package/static/templates/tests/visual/visualPages.mjs +3 -0
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
// Standards 6 to 10: the copied config files match the templates.
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
|
|
4
|
+
import { readTextFile } from "./projectFiles.mjs";
|
|
5
|
+
|
|
6
|
+
const ESLINT_TEMPLATE_NAMES = [
|
|
7
|
+
"base",
|
|
8
|
+
"typescript",
|
|
9
|
+
"react",
|
|
10
|
+
"nextjs",
|
|
11
|
+
];
|
|
12
|
+
const STYLELINT_TEMPLATE_NAMES = ["css", "scss"];
|
|
13
|
+
const FORMAT_SCRIPTS = {
|
|
14
|
+
format:
|
|
15
|
+
"git ls-files -z --cached --others --exclude-standard | xargs -0 prettier --write --ignore-unknown --no-error-on-unmatched-pattern",
|
|
16
|
+
"format:check":
|
|
17
|
+
"git ls-files -z --cached --others --exclude-standard | xargs -0 prettier --check --ignore-unknown --no-error-on-unmatched-pattern",
|
|
18
|
+
};
|
|
19
|
+
// Lines a project is told to change in prettier.config.mjs: the
|
|
20
|
+
// stylesheet path, and the plugin lines in a project without Tailwind.
|
|
21
|
+
const PRETTIER_PROJECT_LINES = /tailwindStylesheet|plugins:/;
|
|
22
|
+
|
|
23
|
+
// Comments and spacing may be rewrapped by the project's own
|
|
24
|
+
// formatting; only the settings themselves have to match.
|
|
25
|
+
const normaliseSettings = (text) =>
|
|
26
|
+
text
|
|
27
|
+
.replaceAll("\r\n", "\n")
|
|
28
|
+
.replaceAll(/\/\*[\s\S]*?\*\//g, "")
|
|
29
|
+
.replaceAll(/^\s*\/\/.*$/gm, "")
|
|
30
|
+
.replaceAll(/\s+/g, " ")
|
|
31
|
+
.trim();
|
|
32
|
+
|
|
33
|
+
const readTemplate = ({ templatesDirectory, filePath }) =>
|
|
34
|
+
readTextFile({ projectDirectory: templatesDirectory, filePath });
|
|
35
|
+
|
|
36
|
+
const matchesAnyTemplate = ({
|
|
37
|
+
projectText,
|
|
38
|
+
templatesDirectory,
|
|
39
|
+
templatePaths,
|
|
40
|
+
}) =>
|
|
41
|
+
templatePaths.some(
|
|
42
|
+
(templatePath) =>
|
|
43
|
+
normaliseSettings(
|
|
44
|
+
readTemplate({
|
|
45
|
+
templatesDirectory,
|
|
46
|
+
filePath: templatePath,
|
|
47
|
+
}) ?? "",
|
|
48
|
+
) === normaliseSettings(projectText),
|
|
49
|
+
);
|
|
50
|
+
|
|
51
|
+
const checkEslint = ({ projectDirectory, templatesDirectory }) => {
|
|
52
|
+
const config = readTextFile({
|
|
53
|
+
projectDirectory,
|
|
54
|
+
filePath: "eslint.config.mjs",
|
|
55
|
+
});
|
|
56
|
+
if (config === undefined) {
|
|
57
|
+
return [
|
|
58
|
+
{ standard: "6", message: "eslint.config.mjs is missing" },
|
|
59
|
+
];
|
|
60
|
+
}
|
|
61
|
+
const isTemplateCopy = matchesAnyTemplate({
|
|
62
|
+
projectText: config,
|
|
63
|
+
templatesDirectory,
|
|
64
|
+
templatePaths: ESLINT_TEMPLATE_NAMES.map((name) =>
|
|
65
|
+
path.join("eslint", name, "eslint.config.mjs"),
|
|
66
|
+
),
|
|
67
|
+
});
|
|
68
|
+
const findings = [];
|
|
69
|
+
if (!isTemplateCopy) {
|
|
70
|
+
findings.push({
|
|
71
|
+
standard: "6",
|
|
72
|
+
message:
|
|
73
|
+
"eslint.config.mjs differs from every template. Copy the template over it, and move the project's own rules into eslint.overrides.mjs",
|
|
74
|
+
page: "docs/Standards/eslint.md#project-specific-overrides",
|
|
75
|
+
});
|
|
76
|
+
}
|
|
77
|
+
const overrides = readTextFile({
|
|
78
|
+
projectDirectory,
|
|
79
|
+
filePath: "eslint.overrides.mjs",
|
|
80
|
+
});
|
|
81
|
+
if (overrides === undefined) {
|
|
82
|
+
findings.push({
|
|
83
|
+
standard: "6",
|
|
84
|
+
message:
|
|
85
|
+
"eslint.overrides.mjs is missing. Copy it from static/templates/eslint.overrides.mjs",
|
|
86
|
+
page: "docs/Standards/eslint.md#project-specific-overrides",
|
|
87
|
+
});
|
|
88
|
+
}
|
|
89
|
+
return findings;
|
|
90
|
+
};
|
|
91
|
+
|
|
92
|
+
const withoutProjectLines = (text) =>
|
|
93
|
+
normaliseSettings(
|
|
94
|
+
text
|
|
95
|
+
.split("\n")
|
|
96
|
+
.filter((line) => !PRETTIER_PROJECT_LINES.test(line))
|
|
97
|
+
.join("\n"),
|
|
98
|
+
);
|
|
99
|
+
|
|
100
|
+
const checkPrettier = ({ projectDirectory, templatesDirectory }) => {
|
|
101
|
+
const config = readTextFile({
|
|
102
|
+
projectDirectory,
|
|
103
|
+
filePath: "prettier.config.mjs",
|
|
104
|
+
});
|
|
105
|
+
if (config === undefined) {
|
|
106
|
+
return [
|
|
107
|
+
{ standard: "7", message: "prettier.config.mjs is missing" },
|
|
108
|
+
];
|
|
109
|
+
}
|
|
110
|
+
const findings = [];
|
|
111
|
+
const template =
|
|
112
|
+
readTemplate({
|
|
113
|
+
templatesDirectory,
|
|
114
|
+
filePath: "prettier.config.mjs",
|
|
115
|
+
}) ?? "";
|
|
116
|
+
if (withoutProjectLines(config) !== withoutProjectLines(template)) {
|
|
117
|
+
findings.push({
|
|
118
|
+
standard: "7",
|
|
119
|
+
message: "prettier.config.mjs differs from the template",
|
|
120
|
+
page: "docs/Standards/prettier.md",
|
|
121
|
+
});
|
|
122
|
+
}
|
|
123
|
+
const packageText =
|
|
124
|
+
readTextFile({ projectDirectory, filePath: "package.json" }) ??
|
|
125
|
+
"{}";
|
|
126
|
+
const scripts = JSON.parse(packageText).scripts ?? {};
|
|
127
|
+
for (const [name, command] of Object.entries(FORMAT_SCRIPTS)) {
|
|
128
|
+
if (scripts[name] !== command) {
|
|
129
|
+
findings.push({
|
|
130
|
+
standard: "7",
|
|
131
|
+
message: `The "${name}" script in package.json is not the standard one`,
|
|
132
|
+
page: "docs/Standards/prettier.md#usage",
|
|
133
|
+
});
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
return findings;
|
|
137
|
+
};
|
|
138
|
+
|
|
139
|
+
const checkExactCopy = ({
|
|
140
|
+
projectDirectory,
|
|
141
|
+
templatesDirectory,
|
|
142
|
+
filePath,
|
|
143
|
+
standard,
|
|
144
|
+
page,
|
|
145
|
+
}) => {
|
|
146
|
+
const projectText = readTextFile({ projectDirectory, filePath });
|
|
147
|
+
if (projectText === undefined) {
|
|
148
|
+
return [{ standard, message: `${filePath} is missing`, page }];
|
|
149
|
+
}
|
|
150
|
+
const isCopy = matchesAnyTemplate({
|
|
151
|
+
projectText,
|
|
152
|
+
templatesDirectory,
|
|
153
|
+
templatePaths: [filePath],
|
|
154
|
+
});
|
|
155
|
+
return isCopy
|
|
156
|
+
? []
|
|
157
|
+
: [
|
|
158
|
+
{
|
|
159
|
+
standard,
|
|
160
|
+
message: `${filePath} differs from the template`,
|
|
161
|
+
page,
|
|
162
|
+
},
|
|
163
|
+
];
|
|
164
|
+
};
|
|
165
|
+
|
|
166
|
+
const checkStylelint = ({ projectDirectory, templatesDirectory }) => {
|
|
167
|
+
const config = readTextFile({
|
|
168
|
+
projectDirectory,
|
|
169
|
+
filePath: "stylelint.config.mjs",
|
|
170
|
+
});
|
|
171
|
+
// Stylelint is only for projects with hand-written CSS.
|
|
172
|
+
if (config === undefined) {
|
|
173
|
+
return [];
|
|
174
|
+
}
|
|
175
|
+
const isCopy = matchesAnyTemplate({
|
|
176
|
+
projectText: config,
|
|
177
|
+
templatesDirectory,
|
|
178
|
+
templatePaths: STYLELINT_TEMPLATE_NAMES.map((name) =>
|
|
179
|
+
path.join("stylelint", name, "stylelint.config.mjs"),
|
|
180
|
+
),
|
|
181
|
+
});
|
|
182
|
+
return isCopy
|
|
183
|
+
? []
|
|
184
|
+
: [
|
|
185
|
+
{
|
|
186
|
+
standard: "8",
|
|
187
|
+
message: "stylelint.config.mjs differs from both templates",
|
|
188
|
+
page: "docs/Standards/stylelint.md",
|
|
189
|
+
},
|
|
190
|
+
];
|
|
191
|
+
};
|
|
192
|
+
|
|
193
|
+
export const checkConfigFiles = ({
|
|
194
|
+
projectDirectory,
|
|
195
|
+
templatesDirectory,
|
|
196
|
+
}) => {
|
|
197
|
+
const nodeVersion = readTextFile({
|
|
198
|
+
projectDirectory,
|
|
199
|
+
filePath: ".nvmrc",
|
|
200
|
+
});
|
|
201
|
+
return [
|
|
202
|
+
...checkEslint({ projectDirectory, templatesDirectory }),
|
|
203
|
+
...checkPrettier({ projectDirectory, templatesDirectory }),
|
|
204
|
+
...checkStylelint({ projectDirectory, templatesDirectory }),
|
|
205
|
+
...checkExactCopy({
|
|
206
|
+
projectDirectory,
|
|
207
|
+
templatesDirectory,
|
|
208
|
+
filePath: ".editorconfig",
|
|
209
|
+
standard: "9",
|
|
210
|
+
page: "docs/Standards/editorconfig.md",
|
|
211
|
+
}),
|
|
212
|
+
...checkExactCopy({
|
|
213
|
+
projectDirectory,
|
|
214
|
+
templatesDirectory,
|
|
215
|
+
filePath: ".envrc",
|
|
216
|
+
standard: "10",
|
|
217
|
+
page: "docs/Standards/direnv.mdx",
|
|
218
|
+
}),
|
|
219
|
+
// The Node version itself is the project's choice.
|
|
220
|
+
...(nodeVersion === undefined
|
|
221
|
+
? [
|
|
222
|
+
{
|
|
223
|
+
standard: "10",
|
|
224
|
+
message: ".nvmrc is missing",
|
|
225
|
+
page: "docs/Standards/direnv.mdx",
|
|
226
|
+
},
|
|
227
|
+
]
|
|
228
|
+
: []),
|
|
229
|
+
];
|
|
230
|
+
};
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
// Standard 12.1: lib/constants/ holds the seven standard files and
|
|
2
|
+
// nothing else, and no component keeps its own constants file.
|
|
3
|
+
import { readTextFile } from "./projectFiles.mjs";
|
|
4
|
+
|
|
5
|
+
const REQUIRED_FILES = [
|
|
6
|
+
"lib/constants/index.ts",
|
|
7
|
+
"lib/constants/routes.ts",
|
|
8
|
+
"lib/constants/strings.ts",
|
|
9
|
+
"lib/constants/numbers.ts",
|
|
10
|
+
];
|
|
11
|
+
// Created only once the project has something to put in them.
|
|
12
|
+
const OPTIONAL_FILES = [
|
|
13
|
+
"lib/constants/noData.ts",
|
|
14
|
+
"lib/constants/animation.ts",
|
|
15
|
+
"lib/constants/artwork.ts",
|
|
16
|
+
"lib/constants/classNames.ts",
|
|
17
|
+
];
|
|
18
|
+
const CONSTANTS_FOLDER = "lib/constants/";
|
|
19
|
+
const COMPONENT_CONSTANTS_PATTERN = /(^|\/)constants\.tsx?$/;
|
|
20
|
+
const CODE_FILE_PATTERN = /\.(?:ts|tsx|js|mjs)$/;
|
|
21
|
+
const EXPORT_PATTERN =
|
|
22
|
+
/^export const ([\w$]+)\s*(?::[^=]+)?=\s*(\S)/gm;
|
|
23
|
+
const MAXIMUM_NAMES_SHOWN = 3;
|
|
24
|
+
const PAGE = "docs/Structure/folder-structure.md#constants";
|
|
25
|
+
|
|
26
|
+
const UNSURE_HOME = "the file the Constants table names";
|
|
27
|
+
|
|
28
|
+
// The name says what most exports are; the first character of the
|
|
29
|
+
// value settles the rest. Checked in this order.
|
|
30
|
+
const NAME_HOMES = [
|
|
31
|
+
{ pattern: /CLASS_NAMES?$/, home: "classNames.ts" },
|
|
32
|
+
{
|
|
33
|
+
pattern:
|
|
34
|
+
/MOTION|ANIMATION|ENTRANCE|SCROLL|DRIFT|ZOOM|EASE|SPRING|TRANSITION|KEYFRAME|QUERY|QUERIES/,
|
|
35
|
+
home: "animation.ts",
|
|
36
|
+
},
|
|
37
|
+
{
|
|
38
|
+
pattern:
|
|
39
|
+
/ARTWORK|LAYOUT|SHAPE|PATH|CANVAS|TILE|IMAGE|PIECE|GEOMETRY|SVG/,
|
|
40
|
+
home: "artwork.ts",
|
|
41
|
+
},
|
|
42
|
+
{ pattern: /ROUTE|HREF|LINK|URL/, home: "r in routes.ts" },
|
|
43
|
+
{ pattern: /^NO_DATA_|^DUMMY_/, home: "noData.ts" },
|
|
44
|
+
// Raw CSS is not text for s, and not a class name.
|
|
45
|
+
{ pattern: /STYLES?$/, home: UNSURE_HOME },
|
|
46
|
+
];
|
|
47
|
+
const VALUE_HOMES = [
|
|
48
|
+
{ pattern: /[\d-]/, home: "numbers.ts" },
|
|
49
|
+
{ pattern: /["'`]/, home: "s in strings.ts" },
|
|
50
|
+
];
|
|
51
|
+
|
|
52
|
+
const findHome = ({ name, valueStart }) =>
|
|
53
|
+
NAME_HOMES.find(({ pattern }) => pattern.test(name))?.home ??
|
|
54
|
+
VALUE_HOMES.find(({ pattern }) => pattern.test(valueStart))?.home ??
|
|
55
|
+
UNSURE_HOME;
|
|
56
|
+
|
|
57
|
+
const describeNames = (names) => {
|
|
58
|
+
const shown = names.slice(0, MAXIMUM_NAMES_SHOWN).join(", ");
|
|
59
|
+
const hiddenCount = names.length - MAXIMUM_NAMES_SHOWN;
|
|
60
|
+
return hiddenCount > 0 ? `${shown} and ${hiddenCount} more` : shown;
|
|
61
|
+
};
|
|
62
|
+
|
|
63
|
+
// "Move CONFIDENCE_MOTION to animation.ts; CARD_FACE_CLASS_NAME to
|
|
64
|
+
// classNames.ts".
|
|
65
|
+
const suggestHomes = ({ projectDirectory, filePath }) => {
|
|
66
|
+
const source = readTextFile({ projectDirectory, filePath }) ?? "";
|
|
67
|
+
// Map.groupBy needs Node 21, and the package supports Node 20.
|
|
68
|
+
const namesByHome = new Map();
|
|
69
|
+
for (const [, name, valueStart] of source.matchAll(
|
|
70
|
+
EXPORT_PATTERN,
|
|
71
|
+
)) {
|
|
72
|
+
const home = findHome({ name, valueStart });
|
|
73
|
+
namesByHome.set(home, [...(namesByHome.get(home) ?? []), name]);
|
|
74
|
+
}
|
|
75
|
+
const moves = [...namesByHome].map(
|
|
76
|
+
([home, names]) => `${describeNames(names)} to ${home}`,
|
|
77
|
+
);
|
|
78
|
+
return moves.length > 0
|
|
79
|
+
? `Move ${moves.join("; ")}`
|
|
80
|
+
: "Move its values into the seven files in lib/constants/";
|
|
81
|
+
};
|
|
82
|
+
|
|
83
|
+
const checkMissingFiles = ({ projectFileSet }) =>
|
|
84
|
+
REQUIRED_FILES.filter(
|
|
85
|
+
(filePath) => !projectFileSet.has(filePath),
|
|
86
|
+
).map((filePath) => ({
|
|
87
|
+
standard: "12.1",
|
|
88
|
+
message: `${filePath} is missing`,
|
|
89
|
+
page: PAGE,
|
|
90
|
+
}));
|
|
91
|
+
|
|
92
|
+
const checkExtraFiles = ({ projectDirectory, projectFiles }) => {
|
|
93
|
+
const standardFiles = new Set([
|
|
94
|
+
...REQUIRED_FILES,
|
|
95
|
+
...OPTIONAL_FILES,
|
|
96
|
+
]);
|
|
97
|
+
return projectFiles
|
|
98
|
+
.filter((filePath) => filePath.startsWith(CONSTANTS_FOLDER))
|
|
99
|
+
.filter((filePath) => CODE_FILE_PATTERN.test(filePath))
|
|
100
|
+
.filter((filePath) => !filePath.includes(".test."))
|
|
101
|
+
.filter((filePath) => !standardFiles.has(filePath))
|
|
102
|
+
.map((filePath) => ({
|
|
103
|
+
standard: "12.1",
|
|
104
|
+
message: `${filePath} is not one of the seven constants files. ${suggestHomes({ projectDirectory, filePath })}`,
|
|
105
|
+
page: PAGE,
|
|
106
|
+
}));
|
|
107
|
+
};
|
|
108
|
+
|
|
109
|
+
const checkComponentFiles = ({ projectDirectory, projectFiles }) =>
|
|
110
|
+
projectFiles
|
|
111
|
+
.filter((filePath) => !filePath.startsWith(CONSTANTS_FOLDER))
|
|
112
|
+
.filter((filePath) => !filePath.startsWith("node_modules/"))
|
|
113
|
+
.filter((filePath) => COMPONENT_CONSTANTS_PATTERN.test(filePath))
|
|
114
|
+
.map((filePath) => ({
|
|
115
|
+
standard: "12.1",
|
|
116
|
+
message: `${filePath}: there is no component-level constants file. ${suggestHomes({ projectDirectory, filePath })}`,
|
|
117
|
+
page: PAGE,
|
|
118
|
+
}));
|
|
119
|
+
|
|
120
|
+
export const checkConstants = ({
|
|
121
|
+
projectDirectory,
|
|
122
|
+
projectFiles,
|
|
123
|
+
}) => [
|
|
124
|
+
...checkMissingFiles({ projectFileSet: new Set(projectFiles) }),
|
|
125
|
+
...checkExtraFiles({ projectDirectory, projectFiles }),
|
|
126
|
+
...checkComponentFiles({ projectDirectory, projectFiles }),
|
|
127
|
+
];
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
// Standard 18: every doc is a Decision Doc in the standard format.
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
|
|
4
|
+
import { readTextFile } from "./projectFiles.mjs";
|
|
5
|
+
|
|
6
|
+
const DOC_PATTERN = /^docs\/(?!assets\/).+\.mdx?$/;
|
|
7
|
+
const TITLE_PATTERN = /^# (.+) — (.+)$/;
|
|
8
|
+
const STATUS_PATTERN =
|
|
9
|
+
/^\*\*Status:\*\* (Not started|Under evaluation|Current plan|Decided) · \*\*Updated:\*\* /m;
|
|
10
|
+
const REQUIRED_SECTIONS = ["Decision", "Why", "Related"];
|
|
11
|
+
const CODE_FENCE = "```";
|
|
12
|
+
const PAGE = "docs/Standards/documentation.md#-the-doc-format";
|
|
13
|
+
|
|
14
|
+
// Headings inside code blocks are examples, not headings.
|
|
15
|
+
const readTopHeadings = (markdown) => {
|
|
16
|
+
const headings = [];
|
|
17
|
+
// eslint-disable-next-line no-restricted-syntax -- flips at each code fence while reading line by line
|
|
18
|
+
let isInCodeBlock = false;
|
|
19
|
+
for (const line of markdown.split("\n")) {
|
|
20
|
+
if (line.startsWith(CODE_FENCE)) {
|
|
21
|
+
isInCodeBlock = !isInCodeBlock;
|
|
22
|
+
continue;
|
|
23
|
+
}
|
|
24
|
+
if (!isInCodeBlock && line.startsWith("# ")) {
|
|
25
|
+
headings.push(line.trimEnd());
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
return headings;
|
|
29
|
+
};
|
|
30
|
+
|
|
31
|
+
const toKebabCase = (text) =>
|
|
32
|
+
text
|
|
33
|
+
.toLowerCase()
|
|
34
|
+
.replaceAll(/[^a-z0-9]+/g, "-")
|
|
35
|
+
.replaceAll(/^-|-$/g, "");
|
|
36
|
+
|
|
37
|
+
const checkTitle = ({ filePath, headings }) => {
|
|
38
|
+
if (headings.length !== 1) {
|
|
39
|
+
return [
|
|
40
|
+
`has ${headings.length} "#" headings. A doc has exactly one, its title`,
|
|
41
|
+
];
|
|
42
|
+
}
|
|
43
|
+
const match = TITLE_PATTERN.exec(headings[0]);
|
|
44
|
+
if (!match) {
|
|
45
|
+
return [
|
|
46
|
+
'has a title that is not in "Group — Menu item" form, such as "# Overview — What Is It"',
|
|
47
|
+
];
|
|
48
|
+
}
|
|
49
|
+
const expectedFileName = toKebabCase(match[2]);
|
|
50
|
+
const fileName = path.posix.parse(filePath).name;
|
|
51
|
+
return fileName === expectedFileName
|
|
52
|
+
? []
|
|
53
|
+
: [
|
|
54
|
+
`is named ${fileName}, but its menu item "${match[2]}" makes it ${expectedFileName}`,
|
|
55
|
+
];
|
|
56
|
+
};
|
|
57
|
+
|
|
58
|
+
const checkDocument = ({ projectDirectory, filePath }) => {
|
|
59
|
+
const markdown = readTextFile({ projectDirectory, filePath }) ?? "";
|
|
60
|
+
const problems = [
|
|
61
|
+
...checkTitle({ filePath, headings: readTopHeadings(markdown) }),
|
|
62
|
+
];
|
|
63
|
+
if (!STATUS_PATTERN.test(markdown)) {
|
|
64
|
+
problems.push(
|
|
65
|
+
"has no **Status:** · **Updated:** line with a standard status",
|
|
66
|
+
);
|
|
67
|
+
}
|
|
68
|
+
const missingSections = REQUIRED_SECTIONS.filter(
|
|
69
|
+
(section) => !markdown.includes(`\n## ${section}\n`),
|
|
70
|
+
);
|
|
71
|
+
if (missingSections.length > 0) {
|
|
72
|
+
problems.push(`is missing ## ${missingSections.join(", ## ")}`);
|
|
73
|
+
}
|
|
74
|
+
return problems.map((problem) => ({
|
|
75
|
+
standard: "18",
|
|
76
|
+
message: `${filePath} ${problem}`,
|
|
77
|
+
page: PAGE,
|
|
78
|
+
}));
|
|
79
|
+
};
|
|
80
|
+
|
|
81
|
+
export const checkDocs = ({ projectDirectory, projectFiles }) =>
|
|
82
|
+
projectFiles
|
|
83
|
+
.filter((filePath) => DOC_PATTERN.test(filePath))
|
|
84
|
+
.flatMap((filePath) =>
|
|
85
|
+
checkDocument({ projectDirectory, filePath }),
|
|
86
|
+
);
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
// What setup asks the person and writes down: the four agent answers
|
|
2
|
+
// (standard 21) and the colour palette (standard 11).
|
|
3
|
+
import {
|
|
4
|
+
CODING_STANDARDS_PATH,
|
|
5
|
+
readSection,
|
|
6
|
+
readTextFile,
|
|
7
|
+
} from "./projectFiles.mjs";
|
|
8
|
+
|
|
9
|
+
const DESIGN_SYSTEM_PATH = "docs/design/design-system.md";
|
|
10
|
+
const AGENT_ANSWERS = [
|
|
11
|
+
{ name: "the GitHub repo", pattern: /github/i },
|
|
12
|
+
{ name: "the Linear project", pattern: /linear/i },
|
|
13
|
+
{ name: "the status circles", pattern: /status circles?/i },
|
|
14
|
+
{ name: "asking before committing", pattern: /commit/i },
|
|
15
|
+
];
|
|
16
|
+
// The template's unfilled line: "[link or None]", "[yes or no]".
|
|
17
|
+
const UNFILLED_ANSWER_PATTERN = /\[[^\]]+ or [^\]]+\]/;
|
|
18
|
+
const TABLE_ROW_PATTERN = /^\|/;
|
|
19
|
+
const TABLE_SEPARATOR_PATTERN = /^\|[\s:|-]+\|$/;
|
|
20
|
+
const PLACEHOLDER_ROW_PATTERN = /^\|\s*\[/;
|
|
21
|
+
// The header row comes before the separator.
|
|
22
|
+
const HEADER_ROW_COUNT = 1;
|
|
23
|
+
|
|
24
|
+
const checkAgentAnswers = ({ projectDirectory }) => {
|
|
25
|
+
const markdown = readTextFile({
|
|
26
|
+
projectDirectory,
|
|
27
|
+
filePath: CODING_STANDARDS_PATH,
|
|
28
|
+
});
|
|
29
|
+
if (markdown === undefined) {
|
|
30
|
+
return [];
|
|
31
|
+
}
|
|
32
|
+
const details = readSection({ markdown, heading: "Details" })
|
|
33
|
+
.split("\n")
|
|
34
|
+
.filter((line) => !UNFILLED_ANSWER_PATTERN.test(line))
|
|
35
|
+
.join("\n");
|
|
36
|
+
return AGENT_ANSWERS.filter(
|
|
37
|
+
({ pattern }) => !pattern.test(details),
|
|
38
|
+
).map(({ name }) => ({
|
|
39
|
+
standard: "21",
|
|
40
|
+
message: `${CODING_STANDARDS_PATH} does not record ${name} under "Details". Ask the person, and write their answer down, even if it is "None" or "No"`,
|
|
41
|
+
page: "docs/Guides/setup.md#4-working-with-the-agent",
|
|
42
|
+
}));
|
|
43
|
+
};
|
|
44
|
+
|
|
45
|
+
const readPaletteRows = ({ section }) =>
|
|
46
|
+
section
|
|
47
|
+
.split("\n")
|
|
48
|
+
.map((line) => line.trim())
|
|
49
|
+
.filter((line) => TABLE_ROW_PATTERN.test(line))
|
|
50
|
+
.filter((line) => !TABLE_SEPARATOR_PATTERN.test(line))
|
|
51
|
+
.slice(HEADER_ROW_COUNT);
|
|
52
|
+
|
|
53
|
+
const checkPalette = ({ projectDirectory }) => {
|
|
54
|
+
const markdown = readTextFile({
|
|
55
|
+
projectDirectory,
|
|
56
|
+
filePath: DESIGN_SYSTEM_PATH,
|
|
57
|
+
});
|
|
58
|
+
if (markdown === undefined) {
|
|
59
|
+
return [];
|
|
60
|
+
}
|
|
61
|
+
const section = readSection({
|
|
62
|
+
markdown,
|
|
63
|
+
heading: "Colour palette",
|
|
64
|
+
});
|
|
65
|
+
const rows = readPaletteRows({ section });
|
|
66
|
+
const isFilledIn =
|
|
67
|
+
rows.length > 0 &&
|
|
68
|
+
rows.every((row) => !PLACEHOLDER_ROW_PATTERN.test(row));
|
|
69
|
+
return isFilledIn
|
|
70
|
+
? []
|
|
71
|
+
: [
|
|
72
|
+
{
|
|
73
|
+
standard: "11",
|
|
74
|
+
message: `${DESIGN_SYSTEM_PATH} has no filled-in "## Colour palette" table. List each colour, its value, its class names and what it is for`,
|
|
75
|
+
page: "docs/Standards/styling.md#-colours-always-come-from-global-variables",
|
|
76
|
+
},
|
|
77
|
+
];
|
|
78
|
+
};
|
|
79
|
+
|
|
80
|
+
export const checkRecordedAnswers = ({ projectDirectory }) => [
|
|
81
|
+
...checkAgentAnswers({ projectDirectory }),
|
|
82
|
+
...checkPalette({ projectDirectory }),
|
|
83
|
+
];
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
// Standards 18 and 21: the docs every project has.
|
|
2
|
+
import { readdirSync, statSync } from "node:fs";
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
|
|
5
|
+
import { CODING_STANDARDS_PATH } from "./projectFiles.mjs";
|
|
6
|
+
|
|
7
|
+
// Setup renames this file after the project: what-is-launchpad.md.
|
|
8
|
+
const RENAMED_OVERVIEW_PATH = "overview/what-is-it.md";
|
|
9
|
+
const RENAMED_OVERVIEW_PATTERN = /^docs\/overview\/what-is-.+\.md$/;
|
|
10
|
+
|
|
11
|
+
const listTemplateDocs = ({ directory, prefix = "" }) =>
|
|
12
|
+
readdirSync(directory).flatMap((entry) => {
|
|
13
|
+
const entryPath = path.join(directory, entry);
|
|
14
|
+
const relativePath = path.posix.join(prefix, entry);
|
|
15
|
+
return statSync(entryPath).isDirectory()
|
|
16
|
+
? listTemplateDocs({
|
|
17
|
+
directory: entryPath,
|
|
18
|
+
prefix: relativePath,
|
|
19
|
+
})
|
|
20
|
+
: [relativePath];
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
const checkDocsFiles = ({ templatesDirectory, projectFiles }) => {
|
|
24
|
+
const projectFileSet = new Set(projectFiles);
|
|
25
|
+
const templateDocuments = listTemplateDocs({
|
|
26
|
+
directory: path.join(templatesDirectory, "docs"),
|
|
27
|
+
});
|
|
28
|
+
const isOverviewRenamed = projectFiles.some((filePath) =>
|
|
29
|
+
RENAMED_OVERVIEW_PATTERN.test(filePath),
|
|
30
|
+
);
|
|
31
|
+
return templateDocuments
|
|
32
|
+
.filter(
|
|
33
|
+
(templateDocument) =>
|
|
34
|
+
!projectFileSet.has(`docs/${templateDocument}`),
|
|
35
|
+
)
|
|
36
|
+
.filter(
|
|
37
|
+
(templateDocument) =>
|
|
38
|
+
!(
|
|
39
|
+
templateDocument === RENAMED_OVERVIEW_PATH &&
|
|
40
|
+
isOverviewRenamed
|
|
41
|
+
),
|
|
42
|
+
)
|
|
43
|
+
.map((templateDocument) => ({
|
|
44
|
+
standard: "18",
|
|
45
|
+
message: `docs/${templateDocument} is missing. Copy it from the doc templates`,
|
|
46
|
+
page: "docs/Standards/documentation.md#every-file-exists-from-the-start",
|
|
47
|
+
}));
|
|
48
|
+
};
|
|
49
|
+
|
|
50
|
+
export const checkRequiredFiles = ({
|
|
51
|
+
templatesDirectory,
|
|
52
|
+
projectFiles,
|
|
53
|
+
}) => {
|
|
54
|
+
const codingStandards = projectFiles.includes(CODING_STANDARDS_PATH)
|
|
55
|
+
? []
|
|
56
|
+
: [
|
|
57
|
+
{
|
|
58
|
+
standard: "21",
|
|
59
|
+
message: `${CODING_STANDARDS_PATH} is missing. It records the standards this project skips or changes`,
|
|
60
|
+
page: "docs/Guides/setup.md#3-agree-the-standards",
|
|
61
|
+
},
|
|
62
|
+
];
|
|
63
|
+
return [
|
|
64
|
+
...codingStandards,
|
|
65
|
+
...checkDocsFiles({ templatesDirectory, projectFiles }),
|
|
66
|
+
];
|
|
67
|
+
};
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
// Standard 13: components sit at most two levels deep, the component
|
|
2
|
+
// then its sub-components, and the homepage is in app/(homepage)/.
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
|
|
5
|
+
const COMPONENT_FILE_PATTERN = /^[A-Z][A-Za-z0-9]*\.(?:tsx|jsx)$/;
|
|
6
|
+
const COMPONENTS_FOLDER = "components";
|
|
7
|
+
const UNGROUPED_HOMEPAGE_PATTERN =
|
|
8
|
+
/^(?:src\/)?app\/page\.(?:tsx|jsx)$/;
|
|
9
|
+
const NESTED_PAGE =
|
|
10
|
+
"docs/Structure/component-organization.md#nested-components";
|
|
11
|
+
|
|
12
|
+
// A component folder holds a PascalCase component file, Card.tsx.
|
|
13
|
+
const listComponentFolders = ({ projectFiles }) =>
|
|
14
|
+
new Set(
|
|
15
|
+
projectFiles
|
|
16
|
+
.filter((filePath) => !filePath.startsWith("node_modules/"))
|
|
17
|
+
.filter((filePath) =>
|
|
18
|
+
COMPONENT_FILE_PATTERN.test(path.posix.basename(filePath)),
|
|
19
|
+
)
|
|
20
|
+
.map((filePath) => path.posix.dirname(filePath)),
|
|
21
|
+
);
|
|
22
|
+
|
|
23
|
+
// The topmost component folder above this one, or undefined for a
|
|
24
|
+
// component that is not inside another.
|
|
25
|
+
const findRootComponent = ({ folder, componentFolders }) => {
|
|
26
|
+
const ancestors = [];
|
|
27
|
+
// eslint-disable-next-line no-restricted-syntax -- walks up one folder at a time
|
|
28
|
+
let parent = path.posix.dirname(folder);
|
|
29
|
+
while (parent !== ".") {
|
|
30
|
+
ancestors.push(parent);
|
|
31
|
+
parent = path.posix.dirname(parent);
|
|
32
|
+
}
|
|
33
|
+
return ancestors.findLast((ancestor) =>
|
|
34
|
+
componentFolders.has(ancestor),
|
|
35
|
+
);
|
|
36
|
+
};
|
|
37
|
+
|
|
38
|
+
// A sub-component's only home is its root component's components/
|
|
39
|
+
// folder: card/components/cardHeader/. Never card/cardHeader/,
|
|
40
|
+
// card/parts/cardHeader/ or card/components/cardHeader/components/.
|
|
41
|
+
const checkSubComponentFolders = ({ componentFolders }) =>
|
|
42
|
+
[...componentFolders]
|
|
43
|
+
.map((folder) => ({
|
|
44
|
+
folder,
|
|
45
|
+
rootComponent: findRootComponent({ folder, componentFolders }),
|
|
46
|
+
}))
|
|
47
|
+
.filter(({ rootComponent }) => rootComponent !== undefined)
|
|
48
|
+
.map(({ folder, rootComponent }) => ({
|
|
49
|
+
folder,
|
|
50
|
+
rootComponent,
|
|
51
|
+
flatFolder: path.posix.join(
|
|
52
|
+
rootComponent,
|
|
53
|
+
COMPONENTS_FOLDER,
|
|
54
|
+
path.posix.basename(folder),
|
|
55
|
+
),
|
|
56
|
+
}))
|
|
57
|
+
.filter(({ folder, flatFolder }) => folder !== flatFolder)
|
|
58
|
+
.map(({ folder, rootComponent, flatFolder }) => ({
|
|
59
|
+
standard: "13",
|
|
60
|
+
message: `${folder} is not flat in ${rootComponent}/${COMPONENTS_FOLDER}/. Move it to ${flatFolder}`,
|
|
61
|
+
page: NESTED_PAGE,
|
|
62
|
+
}));
|
|
63
|
+
|
|
64
|
+
const checkHomepage = ({ projectFiles }) =>
|
|
65
|
+
projectFiles
|
|
66
|
+
.filter((filePath) => UNGROUPED_HOMEPAGE_PATTERN.test(filePath))
|
|
67
|
+
.map((filePath) => ({
|
|
68
|
+
standard: "13",
|
|
69
|
+
message: `${filePath} is the homepage outside its route group. Move it to app/(homepage)/`,
|
|
70
|
+
page: "docs/Structure/folder-structure.md#-where-components-live",
|
|
71
|
+
}));
|
|
72
|
+
|
|
73
|
+
export const checkStructure = ({ projectFiles }) => {
|
|
74
|
+
const componentFolders = listComponentFolders({ projectFiles });
|
|
75
|
+
return [
|
|
76
|
+
...checkSubComponentFolders({ componentFolders }),
|
|
77
|
+
...checkHomepage({ projectFiles }),
|
|
78
|
+
];
|
|
79
|
+
};
|