@mark1russell7/conventions 0.0.0-stage → 0.2.0

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.
@@ -0,0 +1,1608 @@
1
+ import { createRequire } from "node:module";
2
+ import { spawnSync } from "node:child_process";
3
+ import { appendFileSync, existsSync, readFileSync, readdirSync, statSync } from "node:fs";
4
+ import { dirname, extname, join, relative, resolve, sep } from "node:path";
5
+ // src/config.ts
6
+ /** The fields of the configuration of a rule that are not options. */
7
+ const RULE_FIELDS = [
8
+ "off",
9
+ "ignore",
10
+ "reason"
11
+ ];
12
+ const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
13
+ const isStrings = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
14
+ /** This function gives the options of a rule with their defaults. */
15
+ function defaultOptions(rule) {
16
+ return Object.fromEntries(Object.entries(rule.options).map(([name, spec]) => [name, spec.default]));
17
+ }
18
+ /**
19
+ * This function reads the field `conventions` of the root `package.json` (`value`), and gives the
20
+ * configuration of each rule of `rules`.
21
+ *
22
+ * @throws Error when the field has a wrong shape, an unknown rule or option, or an exception or a changed option without a reason
23
+ */
24
+ function parseConfig(value, rules) {
25
+ const byId = new Map(rules.map((rule) => [rule.id, rule]));
26
+ const result = {};
27
+ for (const rule of rules) result[rule.id] = {
28
+ ignore: [],
29
+ options: defaultOptions(rule)
30
+ };
31
+ if (value === void 0) return { rules: result };
32
+ if (!isObject(value)) throw new Error("The field conventions of package.json must be an object.");
33
+ const unknown = Object.keys(value).filter((key) => key !== "packages" && key !== "rules" && key !== "$comment");
34
+ if (unknown.length > 0) throw new Error(`conventions has unknown fields: ${unknown.join(", ")}.`);
35
+ const packages = value["packages"];
36
+ if (packages !== void 0 && !isStrings(packages)) throw new Error("conventions.packages must be an array of globs.");
37
+ const rulesValue = value["rules"] ?? {};
38
+ if (!isObject(rulesValue)) throw new Error("conventions.rules must be an object, with a rule id for each key.");
39
+ for (const [id, entry] of Object.entries(rulesValue)) {
40
+ const rule = byId.get(id);
41
+ if (rule === void 0) throw new Error(`conventions.rules has an unknown rule: ${id}. The rules are: ${[...byId.keys()].join(", ")}.`);
42
+ const where = `conventions.rules["${id}"]`;
43
+ if (!isObject(entry)) throw new Error(`${where} must be an object, for example { "off": "<reason>" }.`);
44
+ const off = entry["off"];
45
+ if (off !== void 0 && (typeof off !== "string" || off.trim() === "")) throw new Error(`${where}.off must be the reason why the rule is off, as text.`);
46
+ const ignore = entry["ignore"] ?? [];
47
+ if (!isStrings(ignore)) throw new Error(`${where}.ignore must be an array of globs.`);
48
+ const reason = entry["reason"];
49
+ if (reason !== void 0 && (typeof reason !== "string" || reason.trim() === "")) throw new Error(`${where}.reason must be text.`);
50
+ if (ignore.length > 0 && reason === void 0) throw new Error(`${where}.ignore needs a reason: add "reason": "<why these files are an exception>".`);
51
+ const options = { ...defaultOptions(rule) };
52
+ const changed = [];
53
+ for (const [name, option] of Object.entries(entry)) {
54
+ if (RULE_FIELDS.includes(name)) continue;
55
+ const spec = rule.options[name];
56
+ if (spec === void 0) {
57
+ const known = [...RULE_FIELDS, ...Object.keys(rule.options)].join(", ");
58
+ throw new Error(`${where} has an unknown field: ${name}. The fields are: ${known}.`);
59
+ }
60
+ if (!(spec.type === "strings" ? isStrings(option) : typeof option === spec.type)) throw new Error(`${where}.${name} must be ${spec.type === "strings" ? "an array of strings" : `a ${spec.type}`}.`);
61
+ options[name] = option;
62
+ changed.push(name);
63
+ }
64
+ if (changed.length > 0 && reason === void 0 && off === void 0) throw new Error(`${where} changes the option${changed.length > 1 ? "s" : ""} ${changed.join(", ")}, and needs a reason: add "reason": "<why this repository changes the default>".`);
65
+ result[id] = {
66
+ ...off === void 0 ? {} : { off },
67
+ ignore,
68
+ ...reason === void 0 ? {} : { reason },
69
+ options
70
+ };
71
+ }
72
+ return {
73
+ ...packages === void 0 ? {} : { packages },
74
+ rules: result
75
+ };
76
+ }
77
+ // src/workspace.ts
78
+ /**
79
+ * The package folders of a repository: the folders that the globs of the workspace name, with a
80
+ * `package.json` file. This file is a copy of `workspace.ts` of `@mark1russell7/api-report`, so that
81
+ * each tool has no runtime dependency.
82
+ */
83
+ /** This function compares two strings by their code units, as the default sort does. */
84
+ const byCode = (a, b) => a < b ? -1 : a > b ? 1 : 0;
85
+ /** This function gives a path relative to `root`, with `/`. */
86
+ const relativePath = (root, file) => relative(root, file).split(sep).join("/");
87
+ /** The characters that have a meaning in a regular expression. */
88
+ const SPECIAL = /* @__PURE__ */ new Set([..."\\^$.|+()[]{}*?/"]);
89
+ /**
90
+ * This function gives a regular expression for a glob of `/` paths. `*` matches a part of one path
91
+ * segment, `?` matches one character, `**` matches zero or more segments, and `{a,b}` matches one of
92
+ * its parts. The function escapes each other special character.
93
+ */
94
+ function globToRegExp(glob) {
95
+ let source = "";
96
+ let braces = 0;
97
+ for (let index = 0; index < glob.length; index++) {
98
+ const char = glob.charAt(index);
99
+ if (char === "/" && glob.slice(index + 1) === "**") {
100
+ source += "(?:/.*)?";
101
+ break;
102
+ }
103
+ if (char === "*" && glob.charAt(index + 1) === "*") {
104
+ const atStart = index === 0 || glob.charAt(index - 1) === "/";
105
+ const after = glob.charAt(index + 2);
106
+ if (atStart && after === "/") {
107
+ source += "(?:[^/]+/)*";
108
+ index += 2;
109
+ } else if (atStart && after === "") {
110
+ source += ".*";
111
+ index += 1;
112
+ } else {
113
+ source += "[^/]*";
114
+ index += 1;
115
+ }
116
+ } else if (char === "*") source += "[^/]*";
117
+ else if (char === "?") source += "[^/]";
118
+ else if (char === "{") {
119
+ braces++;
120
+ source += "(?:";
121
+ } else if (char === "}" && braces > 0) {
122
+ braces--;
123
+ source += ")";
124
+ } else if (char === "," && braces > 0) source += "|";
125
+ else if (SPECIAL.has(char)) source += `\\${char}`;
126
+ else source += char;
127
+ }
128
+ if (braces > 0) throw new Error(`A glob with a "{" that has no "}": ${glob}`);
129
+ return new RegExp(`^${source}$`);
130
+ }
131
+ /** The characters that make a path segment a pattern. */
132
+ const GLOB_CHARS = /[*?{]/;
133
+ /**
134
+ * This function gives the folders under `root` that a glob names, as `/` paths relative to `root`,
135
+ * in the order of the code units. It does not go into `node_modules` or a folder that starts with `.`.
136
+ */
137
+ function globFolders(root, glob) {
138
+ const clean = glob.replace(/^\.\//, "").replace(/\/+$/, "");
139
+ const segments = clean.split("/");
140
+ const firstPattern = segments.findIndex((segment) => GLOB_CHARS.test(segment));
141
+ if (firstPattern < 0) return existsSync(join(root, clean)) ? [clean] : [];
142
+ const base = segments.slice(0, firstPattern).join("/");
143
+ const depth = clean.includes("**") ? Number.POSITIVE_INFINITY : segments.length - firstPattern;
144
+ const pattern = globToRegExp(clean);
145
+ const start = join(root, base);
146
+ if (!existsSync(start)) return [];
147
+ const found = [];
148
+ const walk = (folder, level) => {
149
+ for (const entry of readdirSync(folder, { withFileTypes: true })) {
150
+ if (!entry.isDirectory() || entry.name === "node_modules" || entry.name.startsWith(".")) continue;
151
+ const path = join(folder, entry.name);
152
+ if (pattern.test(relativePath(root, path))) found.push(relativePath(root, path));
153
+ if (level < depth) walk(path, level + 1);
154
+ }
155
+ };
156
+ if (base !== "" && pattern.test(base)) found.push(base);
157
+ walk(start, 1);
158
+ return found.sort(byCode);
159
+ }
160
+ /**
161
+ * This function gives the globs of the workspace at `root`: the `packages` list of
162
+ * `pnpm-workspace.yaml`, then the `workspaces` field of `package.json`. The result is undefined when
163
+ * the repository has no workspace.
164
+ */
165
+ function workspaceGlobs(root) {
166
+ const yaml = join(root, "pnpm-workspace.yaml");
167
+ if (existsSync(yaml)) {
168
+ const lines = readFileSync(yaml, "utf8").split(/\r?\n/);
169
+ const start = lines.findIndex((line) => /^packages\s*:/.test(line));
170
+ if (start >= 0) {
171
+ const unquote = (text) => text.replace(/\s+#.*$/, "").trim().replace(/^["']|["']$/g, "");
172
+ const inline = /^packages\s*:\s*\[(.*)\]/.exec(lines[start] ?? "");
173
+ if (inline) return (inline[1] ?? "").split(",").map(unquote).filter(Boolean);
174
+ const globs = [];
175
+ for (const line of lines.slice(start + 1)) {
176
+ if (/^\s*(#.*)?$/.test(line)) continue;
177
+ const item = /^\s+-\s+(.+)$/.exec(line);
178
+ if (!item) break;
179
+ globs.push(unquote(item[1] ?? ""));
180
+ }
181
+ return globs;
182
+ }
183
+ }
184
+ const manifestFile = join(root, "package.json");
185
+ if (existsSync(manifestFile)) {
186
+ const { workspaces } = JSON.parse(readFileSync(manifestFile, "utf8"));
187
+ if (Array.isArray(workspaces)) return workspaces.filter((glob) => typeof glob === "string");
188
+ if (typeof workspaces === "object" && workspaces !== null && "packages" in workspaces && Array.isArray(workspaces.packages)) return workspaces.packages.filter((glob) => typeof glob === "string");
189
+ }
190
+ }
191
+ /**
192
+ * This function gives the package folders of the repository at `root`: the folders of the globs
193
+ * that have a `package.json` file. A glob that starts with `!` removes folders. Without globs, the
194
+ * function reads the globs of the workspace, and a repository with no workspace is one package.
195
+ * The result has absolute paths, in the order of the code units.
196
+ */
197
+ function packageFolders(root, globs = workspaceGlobs(root)) {
198
+ if (globs === void 0) return existsSync(join(root, "package.json")) ? [root] : [];
199
+ const included = /* @__PURE__ */ new Set();
200
+ for (const glob of globs.filter((item) => !item.startsWith("!"))) for (const folder of globFolders(root, glob)) included.add(folder);
201
+ for (const glob of globs.filter((item) => item.startsWith("!"))) for (const folder of globFolders(root, glob.slice(1))) included.delete(folder);
202
+ return [...included].filter((folder) => existsSync(join(root, folder, "package.json"))).sort(byCode).map((folder) => join(root, folder));
203
+ }
204
+ // src/rule.ts
205
+ /**
206
+ * The shape of a rule, the facts that a rule reads (the context), and small helpers for the rules.
207
+ */
208
+ /** The fields of `package.json` that hold dependencies. */
209
+ const DEPENDENCY_FIELDS = [
210
+ "dependencies",
211
+ "devDependencies",
212
+ "peerDependencies",
213
+ "optionalDependencies"
214
+ ];
215
+ /** This function gives each entry of a field of `package.json` that maps names to specifiers. */
216
+ function specifiersOf(manifest, field) {
217
+ const value = manifest[field];
218
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return [];
219
+ return Object.entries(value).filter((entry) => typeof entry[1] === "string");
220
+ }
221
+ /** This function gives the line (from 1) of the first line of `text` that contains `needle`, from the line `from`. */
222
+ function lineOf(text, needle, from = 1) {
223
+ const lines = text.split(/\r?\n/);
224
+ for (let index = Math.max(0, from - 1); index < lines.length; index++) if ((lines[index] ?? "").includes(needle)) return index + 1;
225
+ }
226
+ /** This function gives the line of the key `"name":` in `package.json`, after the line of the field `field`. */
227
+ function keyLine(text, field, name) {
228
+ const start = lineOf(text, `"${field}"`) ?? 1;
229
+ return lineOf(text, `${JSON.stringify(name)}:`, start) ?? lineOf(text, JSON.stringify(name), start);
230
+ }
231
+ /** This function joins a folder and a file name as a path relative to the root. */
232
+ const inFolder = (folder, file) => folder === "" ? file : `${folder}/${file}`;
233
+ /** This function removes `./` at the start of a path. */
234
+ const cleanPath = (path) => path.replace(/^\.\//, "");
235
+ /** This function tells if a path matches one of the globs. */
236
+ function matchesAny(path, globs) {
237
+ return globs.some((glob) => globToRegExp(cleanPath(glob)).test(path));
238
+ }
239
+ /**
240
+ * This function reads a JSON file with comments and commas at the end of a list (a `tsconfig.json`).
241
+ *
242
+ * @throws SyntaxError when the text is not JSON after the comments are removed
243
+ */
244
+ function parseJsonc(text) {
245
+ let out = "";
246
+ let inString = false;
247
+ for (let index = 0; index < text.length; index++) {
248
+ const char = text.charAt(index);
249
+ const next = text.charAt(index + 1);
250
+ if (inString) {
251
+ out += char;
252
+ if (char === "\\") {
253
+ out += next;
254
+ index++;
255
+ } else if (char === "\"") inString = false;
256
+ } else if (char === "\"") {
257
+ inString = true;
258
+ out += char;
259
+ } else if (char === "/" && next === "/") {
260
+ while (index < text.length && text.charAt(index) !== "\n") index++;
261
+ out += "\n";
262
+ } else if (char === "/" && next === "*") {
263
+ const end = text.indexOf("*/", index + 2);
264
+ index = end < 0 ? text.length : end + 1;
265
+ } else out += char;
266
+ }
267
+ return JSON.parse(out.replace(/,(\s*[}\]])/g, "$1"));
268
+ }
269
+ /** This function reads a JSON file with comments, or gives undefined when the file does not exist or is not JSON. */
270
+ function readJsonc(file) {
271
+ if (!existsSync(file)) return void 0;
272
+ try {
273
+ return parseJsonc(readFileSync(file, "utf8"));
274
+ } catch {
275
+ return;
276
+ }
277
+ }
278
+ /** This function starts git in `root` with `args`, and gives its output, or undefined when git fails. */
279
+ function runGit(root, args) {
280
+ const result = spawnSync("git", [...args], {
281
+ cwd: root,
282
+ encoding: "utf8",
283
+ maxBuffer: 268435456,
284
+ windowsHide: true
285
+ });
286
+ if (result.error || result.status !== 0) return void 0;
287
+ return result.stdout;
288
+ }
289
+ /** This function tells if `file` exists in the folder `dir`. */
290
+ const hasFile = (dir, file) => existsSync(join(dir, file));
291
+ // src/rules/cue-preset.ts
292
+ /**
293
+ * The rule `cue-preset`: the `tsconfig.json` of each package extends a preset of `@mark1russell7/cue`.
294
+ * No config of a package turns off a strict option of its preset.
295
+ */
296
+ /** The compiler options that make the type check strict. A package does not turn them off. */
297
+ const STRICT_OPTIONS = [
298
+ "strict",
299
+ "noImplicitAny",
300
+ "strictNullChecks",
301
+ "strictFunctionTypes",
302
+ "strictBindCallApply",
303
+ "strictPropertyInitialization",
304
+ "strictBuiltinIteratorReturn",
305
+ "noImplicitThis",
306
+ "useUnknownInCatchVariables",
307
+ "alwaysStrict",
308
+ "noUncheckedIndexedAccess",
309
+ "exactOptionalPropertyTypes",
310
+ "noImplicitOverride",
311
+ "noImplicitReturns",
312
+ "noFallthroughCasesInSwitch",
313
+ "noPropertyAccessFromIndexSignature"
314
+ ];
315
+ /** The options that `strict` turns on when a config does not set them. */
316
+ const STRICT_FAMILY = /* @__PURE__ */ new Set([
317
+ "noImplicitAny",
318
+ "strictNullChecks",
319
+ "strictFunctionTypes",
320
+ "strictBindCallApply",
321
+ "strictPropertyInitialization",
322
+ "strictBuiltinIteratorReturn",
323
+ "noImplicitThis",
324
+ "useUnknownInCatchVariables",
325
+ "alwaysStrict"
326
+ ]);
327
+ const asObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
328
+ /** This function gives the `extends` list of a tsconfig. */
329
+ const extendsOf = (config) => {
330
+ const value = config["extends"];
331
+ if (typeof value === "string") return [value];
332
+ return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
333
+ };
334
+ /**
335
+ * This function gives the compiler options of the configs that `config` extends, with the options of
336
+ * a later config over an earlier one.
337
+ */
338
+ function inheritedOptions(config, dir, depth = 0) {
339
+ if (depth > 10) return {
340
+ options: {},
341
+ complete: false
342
+ };
343
+ let options = {};
344
+ let complete = true;
345
+ for (const base of extendsOf(config)) {
346
+ let file;
347
+ if (base.startsWith(".")) file = resolve(dir, base.endsWith(".json") ? base : `${base}.json`);
348
+ else try {
349
+ file = createRequire(join(dir, "package.json")).resolve(base);
350
+ } catch {
351
+ file = void 0;
352
+ }
353
+ const parent = file === void 0 ? void 0 : readJsonc(file);
354
+ if (parent === void 0 || file === void 0) {
355
+ complete = false;
356
+ continue;
357
+ }
358
+ const above = inheritedOptions(asObject(parent), dirname(file), depth + 1);
359
+ complete &&= above.complete;
360
+ options = {
361
+ ...options,
362
+ ...above.options,
363
+ ...asObject(asObject(parent)["compilerOptions"])
364
+ };
365
+ }
366
+ return {
367
+ options,
368
+ complete
369
+ };
370
+ }
371
+ /**
372
+ * This function tells if a config that extends configs with the options `inherited` turns on the
373
+ * option. When the rule cannot read each config, it gives true: the package turns off a strict option.
374
+ */
375
+ function inheritedOn(option, inherited) {
376
+ if (!inherited.complete) return true;
377
+ const value = inherited.options[option];
378
+ if (typeof value === "boolean") return value;
379
+ return STRICT_FAMILY.has(option) && inherited.options["strict"] === true;
380
+ }
381
+ const cuePreset = {
382
+ id: "cue-preset",
383
+ title: "The `tsconfig.json` of each package extends a preset of `@mark1russell7/cue`, and no config of a package turns off a strict option.",
384
+ reason: "`pnpm package add` writes the configs from a preset, so each package checks its types with the same strict options. A config by hand or a strict option turned off lets the packages drift apart.",
385
+ fix: "Make the package with `pnpm package add <name> --preset=<preset>`, or set `extends` to `@mark1russell7/cue/ts/config/<preset>.json`. Correct the code, not the strict option.",
386
+ sources: [
387
+ {
388
+ repo: "client",
389
+ rule: "cue-config",
390
+ doc: "CLAUDE.md:64"
391
+ },
392
+ {
393
+ repo: "client",
394
+ rule: "no-manual-tsconfig",
395
+ doc: "CLAUDE.md:64"
396
+ },
397
+ {
398
+ repo: "Graph",
399
+ rule: "cue-preset-strict",
400
+ doc: "docs/architecture/ecosystem-and-structure.md:58"
401
+ },
402
+ {
403
+ repo: "Graph",
404
+ rule: "strict-preset",
405
+ doc: "docs/architecture/ecosystem-and-structure.md:58"
406
+ },
407
+ {
408
+ repo: "Graph",
409
+ rule: "new-package-via-cli",
410
+ doc: "CLAUDE.md:14"
411
+ },
412
+ {
413
+ repo: "coeval",
414
+ rule: "package-scaffold",
415
+ doc: "CLAUDE.md:16"
416
+ },
417
+ {
418
+ repo: "crawler",
419
+ rule: "package-scaffold",
420
+ doc: "CLAUDE.md:16"
421
+ },
422
+ {
423
+ repo: "headroom",
424
+ rule: "package-scaffold",
425
+ doc: "CLAUDE.md:30"
426
+ },
427
+ {
428
+ repo: "Vex",
429
+ rule: "package-scaffold",
430
+ doc: "CLAUDE.md:22"
431
+ }
432
+ ],
433
+ options: { prefix: {
434
+ type: "string",
435
+ default: "@mark1russell7/cue/",
436
+ description: "The start of the `extends` path of a preset."
437
+ } },
438
+ check(context, options) {
439
+ if (context.packages.length === 0) return { skipped: "the repository has no workspace packages" };
440
+ const prefix = typeof options["prefix"] === "string" ? options["prefix"] : "@mark1russell7/cue/";
441
+ const breaks = [];
442
+ for (const info of context.packages) {
443
+ if (!hasFile(info.dir, "tsconfig.json")) continue;
444
+ for (const name of ["tsconfig.json", "tsconfig.test.json"]) {
445
+ const path = join(info.dir, name);
446
+ const file = inFolder(info.folder, name);
447
+ const value = readJsonc(path);
448
+ if (value === void 0) {
449
+ if (hasFile(info.dir, name)) breaks.push({
450
+ file,
451
+ message: `${name} is not JSON.`,
452
+ fix: "Correct the JSON."
453
+ });
454
+ continue;
455
+ }
456
+ const config = asObject(value);
457
+ if (name === "tsconfig.json" && !extendsOf(config).some((base) => base.startsWith(prefix))) {
458
+ const line = lineOf(readFileSync(path, "utf8"), "\"extends\"");
459
+ breaks.push({
460
+ file,
461
+ ...line === void 0 ? {} : { line },
462
+ message: `tsconfig.json does not extend a preset of ${prefix.replace(/\/$/, "")}.`
463
+ });
464
+ }
465
+ const own = asObject(config["compilerOptions"]);
466
+ const inherited = inheritedOptions(config, info.dir);
467
+ for (const option of STRICT_OPTIONS) {
468
+ if (own[option] !== false || !inheritedOn(option, inherited)) continue;
469
+ breaks.push({
470
+ file,
471
+ message: `${name} turns off the strict option ${option}.`,
472
+ fix: `Remove "${option}": false, and correct the code that it hides.`
473
+ });
474
+ }
475
+ }
476
+ }
477
+ return breaks;
478
+ }
479
+ };
480
+ // src/rules/no-build-output.ts
481
+ /**
482
+ * The rule `no-build-output`: git does not keep build output.
483
+ */
484
+ const noBuildOutput = {
485
+ id: "no-build-output",
486
+ title: "Git keeps no build output: no tracked file is in a folder named `dist` or `build`.",
487
+ reason: "The release workflow builds each package from the source. Build output in git goes stale, makes noise in each diff, and a user can get old code from a git install.",
488
+ fix: "Remove the folder from git with `git rm -r --cached <folder>`, and keep its name in `.gitignore`.",
489
+ sources: [
490
+ {
491
+ repo: "client",
492
+ rule: "no-build-output",
493
+ doc: "CLAUDE.md:48"
494
+ },
495
+ {
496
+ repo: "client",
497
+ rule: "no-dist",
498
+ doc: "CLAUDE.md:48"
499
+ },
500
+ {
501
+ repo: "client",
502
+ rule: "no-dist-commit",
503
+ doc: "CLAUDE.md:48"
504
+ }
505
+ ],
506
+ options: { folders: {
507
+ type: "strings",
508
+ default: ["dist", "build"],
509
+ description: "The names of the folders of build output."
510
+ } },
511
+ check(context, options) {
512
+ const files = context.gitFiles();
513
+ if (files === void 0) return { skipped: "the root is not in a git repository" };
514
+ const names = new Set(Array.isArray(options["folders"]) ? options["folders"] : ["dist", "build"]);
515
+ const counts = /* @__PURE__ */ new Map();
516
+ for (const file of files) {
517
+ const segments = file.split("/");
518
+ const index = segments.slice(0, -1).findIndex((segment) => names.has(segment));
519
+ if (index < 0) continue;
520
+ const folder = segments.slice(0, index + 1).join("/");
521
+ counts.set(folder, (counts.get(folder) ?? 0) + 1);
522
+ }
523
+ return [...counts.keys()].sort(byCode).map((folder) => ({
524
+ file: `${folder}/`,
525
+ message: `Git keeps ${counts.get(folder) ?? 0} file(s) in ${folder}/.`,
526
+ fix: `Start \`git rm -r --cached ${folder}\`, and keep ${folder.split("/").pop() ?? folder}/ in .gitignore.`
527
+ }));
528
+ }
529
+ };
530
+ // src/rules/no-local-paths.ts
531
+ /**
532
+ * The rule `no-local-paths`: no tracked file names the home folder of a user of a computer.
533
+ */
534
+ /** The extensions of files that are not text. The rule does not read them. */
535
+ const BINARY = new Set(".png .jpg .jpeg .gif .webp .avif .ico .bmp .tiff .pdf .zip .gz .tgz .bz2 .xz .7z .tar .woff .woff2 .ttf .otf .eot .mp3 .mp4 .webm .mov .wav .ogg .wasm .node .exe .dll .so .dylib .bin .db .sqlite .duckdb".split(" "));
536
+ /** The largest file that the rule reads, in bytes. */
537
+ const MAX_BYTES = 2097152;
538
+ /** The names in a home path that do not identify a person: CI users, container users and placeholders. */
539
+ const DEFAULT_ALLOWED = [
540
+ "runner",
541
+ "runneradmin",
542
+ "user",
543
+ "username",
544
+ "you",
545
+ "me",
546
+ "name",
547
+ "yourname",
548
+ "your-name",
549
+ "example",
550
+ "node",
551
+ "ubuntu",
552
+ "vscode",
553
+ "codespace",
554
+ "public",
555
+ "default",
556
+ "shared",
557
+ "all users"
558
+ ];
559
+ /** The forms of a home folder: Windows, macOS and Linux. The group `user` is the name of the user. */
560
+ const HOME_PATTERNS = [
561
+ /\b[A-Za-z]:(?:\\{1,2}|\/)Users(?:\\{1,2}|\/)(?<user>[^\\/\s"'`<>|:*?%$(){}[\],;]+)/g,
562
+ /(?<![\w.~-])\/Users\/(?<user>[^/\s"'`<>|:*?%$(){}[\],;]+)/g,
563
+ /(?<![\w.~-])\/home\/(?<user>[^/\s"'`<>|:*?%$(){}[\],;]+)/g
564
+ ];
565
+ const noLocalPaths = {
566
+ id: "no-local-paths",
567
+ title: "No tracked file has the home folder of a user (`C:\\Users\\<name>`, `/Users/<name>`, `/home/<name>`).",
568
+ reason: "A public file must not name a computer, a user or a path of a computer. A local path also works only on one computer.",
569
+ fix: "Use a path relative to the repository, `~`, an environment variable, or a placeholder such as `<you>`.",
570
+ sources: [
571
+ {
572
+ repo: "client",
573
+ rule: "I12",
574
+ doc: "packages/documentation/ARCHITECTURE.md:201"
575
+ },
576
+ {
577
+ repo: "systems",
578
+ rule: "no-identifying-names",
579
+ doc: "CLAUDE.md:12"
580
+ },
581
+ {
582
+ repo: "systems",
583
+ rule: "no-private-identifiers",
584
+ doc: "CLAUDE.md:12"
585
+ },
586
+ {
587
+ repo: "systems",
588
+ rule: "no-private-names",
589
+ doc: "CLAUDE.md:12"
590
+ },
591
+ {
592
+ repo: "coeval",
593
+ rule: "no-private-names",
594
+ doc: "CLAUDE.md:22"
595
+ }
596
+ ],
597
+ options: {
598
+ allow: {
599
+ type: "strings",
600
+ default: [],
601
+ description: "More user names that do not identify a person."
602
+ },
603
+ patterns: {
604
+ type: "strings",
605
+ default: [],
606
+ description: "More regular expressions of text that no file has. The environment variable CONVENTIONS_PRIVATE_PATTERNS adds one on each line, so a private name stays out of package.json."
607
+ }
608
+ },
609
+ check(context, options) {
610
+ const files = context.gitFiles();
611
+ if (files === void 0) return { skipped: "the root is not in a git repository" };
612
+ const allowed = new Set([...DEFAULT_ALLOWED, ...Array.isArray(options["allow"]) ? options["allow"] : []].map((name) => name.toLowerCase()));
613
+ const fromEnv = (context.env["CONVENTIONS_PRIVATE_PATTERNS"] ?? "").split("\n").map((line) => line.trim()).filter((line) => line !== "");
614
+ const extra = [...Array.isArray(options["patterns"]) ? options["patterns"] : [], ...fromEnv].map((source) => new RegExp(source, "g"));
615
+ const rootFile = context.rootPackage.file;
616
+ const breaks = [];
617
+ for (const file of files) {
618
+ if (BINARY.has(extname(file).toLowerCase())) continue;
619
+ const path = join(context.root, file);
620
+ let text;
621
+ try {
622
+ if (statSync(path).size > MAX_BYTES) continue;
623
+ text = readFileSync(path, "utf8");
624
+ } catch {
625
+ continue;
626
+ }
627
+ if (text.includes("\0")) continue;
628
+ const lines = text.split(/\r?\n/);
629
+ for (let index = 0; index < lines.length; index++) {
630
+ const line = lines[index] ?? "";
631
+ for (const pattern of HOME_PATTERNS) for (const match of line.matchAll(pattern)) {
632
+ const user = match.groups?.["user"] ?? "";
633
+ if (user.length < 2 || allowed.has(user.toLowerCase())) continue;
634
+ breaks.push({
635
+ file,
636
+ line: index + 1,
637
+ message: `The text "${match[0]}" is the home folder of a user.`
638
+ });
639
+ }
640
+ for (const pattern of extra) {
641
+ if (file === rootFile && line.trim().replace(/,$/, "") === JSON.stringify(pattern.source)) continue;
642
+ for (const match of line.matchAll(pattern)) breaks.push({
643
+ file,
644
+ line: index + 1,
645
+ message: `The text "${match[0]}" matches the pattern ${pattern.source}.`,
646
+ fix: "Remove the text."
647
+ });
648
+ }
649
+ }
650
+ }
651
+ return breaks;
652
+ }
653
+ };
654
+ // src/rules/pinned-git-deps.ts
655
+ /**
656
+ * The rule `pinned-git-deps`: a dependency from git names a full commit.
657
+ */
658
+ /** The fields of the root `package.json` that replace the specifiers of dependencies. */
659
+ const OVERRIDE_FIELDS = ["overrides", "resolutions"];
660
+ /** This function tells if a specifier gets the package from git, not from a registry or the workspace. */
661
+ function isGitSpecifier(spec) {
662
+ const value = spec.trim();
663
+ if (/^(github|gitlab|bitbucket|gist):/i.test(value)) return true;
664
+ if (/^git(\+[a-z]+)?:/i.test(value) || /^git@/i.test(value)) return true;
665
+ if (/^https?:\/\/(www\.)?(github\.com|gitlab\.com|bitbucket\.org|codeload\.github\.com)\//i.test(value)) return true;
666
+ return /^[\w-][\w.-]*\/[\w.-]+(#.*)?$/.test(value) && !value.startsWith("@");
667
+ }
668
+ /**
669
+ * This function tells if a git specifier names a commit. A specifier names a commit when its ref
670
+ * (after `#`) is a commit SHA, or when a tarball URL has the SHA in its path.
671
+ */
672
+ function isPinned(spec, fullSha) {
673
+ const sha = fullSha ? /^[0-9a-f]{40}$/i : /^[0-9a-f]{7,40}$/i;
674
+ const hash = spec.indexOf("#");
675
+ if (hash >= 0) return spec.slice(hash + 1).split("&").some((part) => sha.test(part.replace(/^commit=/, "")));
676
+ const path = /^https?:\/\/[^/]+\/(.*)$/i.exec(spec.trim())?.[1];
677
+ return path !== void 0 && path.split(/[/.]/).some((part) => sha.test(part));
678
+ }
679
+ /** This function gives the specifiers of the fields of overrides, also the field `overrides` of `pnpm`. */
680
+ function overridesOf(manifest) {
681
+ const out = [];
682
+ for (const field of OVERRIDE_FIELDS) for (const [name, spec] of specifiersOf(manifest, field)) out.push([
683
+ field,
684
+ name,
685
+ spec
686
+ ]);
687
+ const pnpm = manifest["pnpm"];
688
+ if (typeof pnpm === "object" && pnpm !== null) for (const [name, spec] of specifiersOf(pnpm, "overrides")) out.push([
689
+ "pnpm",
690
+ name,
691
+ spec
692
+ ]);
693
+ return out;
694
+ }
695
+ const pinnedGitDeps = {
696
+ id: "pinned-git-deps",
697
+ title: "A dependency from git (github:, git+https: or owner/repo) names a full commit SHA.",
698
+ reason: "A git ref without a commit moves with the branch. Then an install today and an install tomorrow get different code, and the lockfile hides the change.",
699
+ fix: "Use the npm version, `workspace:*` for a package of this repository, or `github:owner/repo#<full commit SHA>`.",
700
+ sources: [
701
+ {
702
+ repo: "coeval",
703
+ rule: "pinned-deps",
704
+ doc: "CLAUDE.md:41"
705
+ },
706
+ {
707
+ repo: "coeval",
708
+ rule: "unpublished-dep-pinned",
709
+ doc: "CLAUDE.md:41"
710
+ },
711
+ {
712
+ repo: "headroom",
713
+ rule: "non-npm-deps-pinned",
714
+ doc: "CLAUDE.md:38"
715
+ },
716
+ {
717
+ repo: "headroom",
718
+ rule: "pinned-github-specifier",
719
+ doc: "CLAUDE.md:38"
720
+ },
721
+ {
722
+ repo: "Graph",
723
+ rule: "github-dep-full-sha",
724
+ doc: "docs/decisions.md:1384"
725
+ },
726
+ {
727
+ repo: "Graph",
728
+ rule: "github-dep-pinned",
729
+ doc: "docs/decisions.md:1384"
730
+ },
731
+ {
732
+ repo: "client",
733
+ rule: "general-npm-version",
734
+ doc: "CLAUDE.md:54"
735
+ }
736
+ ],
737
+ options: { fullSha: {
738
+ type: "boolean",
739
+ default: true,
740
+ description: "When false, a short SHA of 7 or more characters is also a commit."
741
+ } },
742
+ check(context, options) {
743
+ const fullSha = options["fullSha"] !== false;
744
+ const breaks = [];
745
+ for (const info of [context.rootPackage, ...context.packages]) {
746
+ const found = [];
747
+ for (const field of DEPENDENCY_FIELDS) for (const [name, spec] of specifiersOf(info.manifest, field)) found.push([
748
+ field,
749
+ name,
750
+ spec
751
+ ]);
752
+ found.push(...overridesOf(info.manifest));
753
+ for (const [field, name, spec] of found) {
754
+ if (!isGitSpecifier(spec) || isPinned(spec, fullSha)) continue;
755
+ const line = keyLine(info.text, field, name);
756
+ breaks.push({
757
+ file: info.file,
758
+ ...line === void 0 ? {} : { line },
759
+ message: `${field} "${name}" is "${spec}": a git dependency without a ${fullSha ? "full " : ""}commit SHA.`
760
+ });
761
+ }
762
+ }
763
+ return breaks;
764
+ }
765
+ };
766
+ // src/rules/release-files.ts
767
+ /**
768
+ * The rule `release-files`: a pull request changes a file of the release flow only with a reason
769
+ * that everyone can see.
770
+ */
771
+ /** This function gives the range of the change: the option `--base`, or the merge commit of a pull request. */
772
+ function rangeOf(context) {
773
+ if (context.base !== void 0) {
774
+ if (context.git([
775
+ "rev-parse",
776
+ "--verify",
777
+ "--quiet",
778
+ `${context.base}^{commit}`
779
+ ]) === void 0) return { skipped: `git does not know the base ${context.base}` };
780
+ return {
781
+ diff: [`${context.base}...HEAD`],
782
+ log: [`${context.base}..HEAD`]
783
+ };
784
+ }
785
+ const event = context.env["GITHUB_EVENT_NAME"];
786
+ if (event !== "pull_request" && event !== "pull_request_target") return { skipped: "no base: the rule runs on a pull request, or with --base <ref>" };
787
+ if ((context.git([
788
+ "rev-list",
789
+ "--parents",
790
+ "-n",
791
+ "1",
792
+ "HEAD"
793
+ ])?.trim().split(/\s+/) ?? []).length !== 3) return { skipped: "HEAD is not the merge commit of the pull request" };
794
+ if (context.git([
795
+ "cat-file",
796
+ "-e",
797
+ "HEAD^1^{commit}"
798
+ ]) === void 0) return { skipped: "the checkout has no parent of HEAD: set fetch-depth to 2 or more" };
799
+ return {
800
+ diff: ["HEAD^1", "HEAD"],
801
+ log: ["HEAD^1..HEAD"]
802
+ };
803
+ }
804
+ /** This function gives the body of the pull request from the event file of GitHub Actions, or an empty string. */
805
+ function pullRequestBody(context) {
806
+ const file = context.env["GITHUB_EVENT_PATH"];
807
+ if (file === void 0 || file === "" || !existsSync(file)) return "";
808
+ try {
809
+ const event = JSON.parse(readFileSync(file, "utf8"));
810
+ return typeof event.pull_request?.body === "string" ? event.pull_request.body : "";
811
+ } catch {
812
+ return "";
813
+ }
814
+ }
815
+ /** This function escapes the special characters of a regular expression. */
816
+ const escape = (text) => text.replace(/[\\^$.|?*+()[\]{}]/g, "\\$&");
817
+ const releaseFiles = {
818
+ id: "release-files",
819
+ title: "A pull request changes `.github/workflows/release.yml` or `scripts/release/` only with a `Release-Edit: <reason>` line.",
820
+ reason: "The release flow publishes to npm with trusted publishing. A change of its files by a session that does not own the release can stop or break each release.",
821
+ fix: "Revert the change of the release files. When the owner asked for the change, add the line `Release-Edit: <reason>` to the last commit message or to the body of the pull request.",
822
+ sources: [
823
+ {
824
+ repo: "coeval",
825
+ rule: "no-release-edit",
826
+ doc: "CLAUDE.md:40"
827
+ },
828
+ {
829
+ repo: "coeval",
830
+ rule: "no-release-edits",
831
+ doc: "CLAUDE.md:40"
832
+ },
833
+ {
834
+ repo: "crawler",
835
+ rule: "no-release-edit",
836
+ doc: "CLAUDE.md:80"
837
+ },
838
+ {
839
+ repo: "crawler",
840
+ rule: "no-release-edits",
841
+ doc: "CLAUDE.md:80"
842
+ },
843
+ {
844
+ repo: "headroom",
845
+ rule: "no-release-edits",
846
+ doc: "CLAUDE.md:37"
847
+ },
848
+ {
849
+ repo: "headroom",
850
+ rule: "release-files-frozen",
851
+ doc: "CLAUDE.md:37"
852
+ }
853
+ ],
854
+ options: {
855
+ paths: {
856
+ type: "strings",
857
+ default: [".github/workflows/release.yml", "scripts/release/**"],
858
+ description: "The globs of the files that the release flow owns."
859
+ },
860
+ trailer: {
861
+ type: "string",
862
+ default: "Release-Edit",
863
+ description: "The key of the line that gives the reason of a change."
864
+ },
865
+ authors: {
866
+ type: "strings",
867
+ default: ["mark1russell7-release-train[bot]"],
868
+ description: "The authors of the release flow. A change of the release files in commits of only these authors (the sync of the template) needs no reason."
869
+ }
870
+ },
871
+ check(context, options) {
872
+ const range = rangeOf(context);
873
+ if ("skipped" in range) return range;
874
+ const globs = Array.isArray(options["paths"]) ? options["paths"] : [];
875
+ const changed = (context.git([
876
+ "diff",
877
+ "--name-only",
878
+ ...range.diff
879
+ ]) ?? "").split(/\r?\n/).filter((file) => file !== "" && matchesAny(file, globs));
880
+ if (changed.length === 0) return [];
881
+ const trailer = typeof options["trailer"] === "string" ? options["trailer"] : "Release-Edit";
882
+ const line = new RegExp(`^${escape(trailer)}:[ \\t]*\\S`, "im");
883
+ const messages = context.git([
884
+ "log",
885
+ "--no-merges",
886
+ "--format=%B",
887
+ ...range.log
888
+ ]) ?? "";
889
+ if (line.test(messages) || line.test(pullRequestBody(context))) return [];
890
+ const authors = new Set(Array.isArray(options["authors"]) ? options["authors"] : []);
891
+ const changers = (context.git([
892
+ "log",
893
+ "--no-merges",
894
+ "--format=%an",
895
+ ...range.log,
896
+ "--",
897
+ ...changed
898
+ ]) ?? "").split(/\r?\n/).filter((name) => name !== "");
899
+ if (changers.length > 0 && changers.every((name) => authors.has(name))) return [];
900
+ return changed.map((file) => ({
901
+ file,
902
+ message: `The change edits ${file}, a file of the release flow, with no "${trailer}: <reason>" line.`
903
+ }));
904
+ }
905
+ };
906
+ // src/rules/required-scripts.ts
907
+ /**
908
+ * The rule `required-scripts`: the root `package.json` keeps the scripts that the shared CI starts.
909
+ */
910
+ /** The package of the STE linter. */
911
+ const STE_LINT = "@mark1russell7/ste-lint";
912
+ /** The configuration file of the STE linter. */
913
+ const STE_CONFIG = "ste.config.json";
914
+ /** The examples of the scripts that the fix shows. */
915
+ const EXAMPLES = {
916
+ "lint:ste": "ste-lint",
917
+ typecheck: "pnpm -r run typecheck"
918
+ };
919
+ /**
920
+ * This function tells if the repository uses the STE prose standard: the root `package.json` has a
921
+ * dependency on `@mark1russell7/ste-lint`, or the root has a `ste.config.json`.
922
+ */
923
+ function usesSteLint(context) {
924
+ const manifest = context.rootPackage.manifest;
925
+ if (DEPENDENCY_FIELDS.some((field) => specifiersOf(manifest, field).some(([name]) => name === STE_LINT))) return true;
926
+ return hasFile(context.root, STE_CONFIG);
927
+ }
928
+ const requiredScripts = {
929
+ id: "required-scripts",
930
+ title: "The root `package.json` has the script `typecheck`, and also `lint:ste` when the repository uses `ste-lint`.",
931
+ reason: "The shared CI starts each script of its list that `package.json` has, and it skips the others. Thus a removed script turns its check off, and nothing shows it.",
932
+ fix: "Add the script, for example `\"lint:ste\": \"ste-lint\"` or `\"typecheck\": \"pnpm -r run typecheck\"`.",
933
+ sources: [
934
+ {
935
+ repo: "client",
936
+ rule: "ste-prose",
937
+ doc: "CLAUDE.md:5"
938
+ },
939
+ {
940
+ repo: "coeval",
941
+ rule: "ste-prose",
942
+ doc: "CLAUDE.md:5"
943
+ },
944
+ {
945
+ repo: "crawler",
946
+ rule: "ste-prose",
947
+ doc: "CLAUDE.md:5"
948
+ },
949
+ {
950
+ repo: "Graph",
951
+ rule: "ste-prose",
952
+ doc: "CLAUDE.md:5"
953
+ },
954
+ {
955
+ repo: "headroom",
956
+ rule: "ste-prose",
957
+ doc: "CLAUDE.md:19"
958
+ },
959
+ {
960
+ repo: "systems",
961
+ rule: "lint-ste-in-ci",
962
+ doc: "CLAUDE.md:24"
963
+ },
964
+ {
965
+ repo: "Vex",
966
+ rule: "ste-prose",
967
+ doc: "CLAUDE.md:5"
968
+ },
969
+ {
970
+ repo: "coeval",
971
+ rule: "tsconfig-test",
972
+ doc: "CLAUDE.md:18"
973
+ },
974
+ {
975
+ repo: "crawler",
976
+ rule: "tsconfig-test",
977
+ doc: "CLAUDE.md:18"
978
+ },
979
+ {
980
+ repo: "headroom",
981
+ rule: "tsconfig-test",
982
+ doc: "CLAUDE.md:32"
983
+ },
984
+ {
985
+ repo: "Vex",
986
+ rule: "tsconfig-test",
987
+ doc: "CLAUDE.md:23"
988
+ }
989
+ ],
990
+ options: {
991
+ scripts: {
992
+ type: "strings",
993
+ default: ["typecheck"],
994
+ description: "The scripts that the root `package.json` has."
995
+ },
996
+ steScripts: {
997
+ type: "strings",
998
+ default: ["lint:ste"],
999
+ description: "The scripts that the root `package.json` has when the repository uses `ste-lint` (a dependency on `@mark1russell7/ste-lint`, or a `ste.config.json` at the root)."
1000
+ }
1001
+ },
1002
+ check(context, options) {
1003
+ const always = Array.isArray(options["scripts"]) ? options["scripts"] : ["typecheck"];
1004
+ const ste = Array.isArray(options["steScripts"]) ? options["steScripts"] : ["lint:ste"];
1005
+ const wanted = [.../* @__PURE__ */ new Set([...always, ...usesSteLint(context) ? ste : []])];
1006
+ const value = context.rootPackage.manifest["scripts"];
1007
+ const scripts = typeof value === "object" && value !== null ? value : {};
1008
+ const line = lineOf(context.rootPackage.text, "\"scripts\"");
1009
+ return wanted.filter((name) => typeof scripts[name] !== "string" || scripts[name] === "").map((name) => {
1010
+ const example = EXAMPLES[name];
1011
+ const why = ste.includes(name) && !always.includes(name) ? " The repository uses ste-lint." : "";
1012
+ return {
1013
+ file: context.rootPackage.file,
1014
+ ...line === void 0 ? {} : { line },
1015
+ message: `The root package.json has no script "${name}".${why}`,
1016
+ fix: example === void 0 ? `Add the script "${name}".` : `Add the script, for example "${name}": "${example}".`
1017
+ };
1018
+ });
1019
+ }
1020
+ };
1021
+ // src/rules/source-main.ts
1022
+ /**
1023
+ * The rule `source-main`: a workspace package is a source package, and a public package moves its
1024
+ * entries to the build when it is published.
1025
+ */
1026
+ /** The fields of `package.json` that name the entries of a package. */
1027
+ const ENTRY_FIELDS = [
1028
+ "main",
1029
+ "module",
1030
+ "types",
1031
+ "typings",
1032
+ "exports",
1033
+ "bin"
1034
+ ];
1035
+ /** This function gives each path in the value of an entry field (a string, or the strings in an object). */
1036
+ function pathsOf(value) {
1037
+ if (typeof value === "string") return [value];
1038
+ if (Array.isArray(value)) return value.flatMap(pathsOf);
1039
+ if (typeof value === "object" && value !== null) return Object.values(value).flatMap(pathsOf);
1040
+ return [];
1041
+ }
1042
+ /** This function tells if a path is a source file: a file in `src/`, or a TypeScript file that is not a declaration file. */
1043
+ function isSourcePath(path) {
1044
+ const clean = cleanPath(path);
1045
+ return clean.startsWith("src/") || /\.(c|m)?tsx?$/.test(clean) && !/\.d\.(c|m)?ts$/.test(clean);
1046
+ }
1047
+ const sourceMain = {
1048
+ id: "source-main",
1049
+ title: "Each workspace package is a source package (`main` is `src/index.ts`), and a public package moves its entries to the build in `publishConfig`.",
1050
+ reason: "Other packages of the workspace import the source, so a change is visible at once with no build. A public package that publishes its source entries gives TypeScript files to npm users.",
1051
+ fix: "Set `\"main\": \"./src/index.ts\"`. In a public package, add `publishConfig` with main, types, exports and bin that point at the build, as `pnpm package add` does.",
1052
+ sources: [
1053
+ {
1054
+ repo: "coeval",
1055
+ rule: "package-main-source",
1056
+ doc: "CLAUDE.md:17"
1057
+ },
1058
+ {
1059
+ repo: "coeval",
1060
+ rule: "source-package-main",
1061
+ doc: "CLAUDE.md:17"
1062
+ },
1063
+ {
1064
+ repo: "crawler",
1065
+ rule: "pkg-source-main",
1066
+ doc: "CLAUDE.md:17"
1067
+ },
1068
+ {
1069
+ repo: "crawler",
1070
+ rule: "source-package-main",
1071
+ doc: "CLAUDE.md:17"
1072
+ },
1073
+ {
1074
+ repo: "crawler",
1075
+ rule: "publish-config-build",
1076
+ doc: "CLAUDE.md:41"
1077
+ },
1078
+ {
1079
+ repo: "Graph",
1080
+ rule: "new-package-main-index",
1081
+ doc: "CLAUDE.md:15"
1082
+ },
1083
+ {
1084
+ repo: "Graph",
1085
+ rule: "source-package-main",
1086
+ doc: "CLAUDE.md:15"
1087
+ },
1088
+ {
1089
+ repo: "headroom",
1090
+ rule: "source-package-main",
1091
+ doc: "CLAUDE.md:31"
1092
+ }
1093
+ ],
1094
+ options: {
1095
+ main: {
1096
+ type: "string",
1097
+ default: "src/index.ts",
1098
+ description: "The path of `main` in each package."
1099
+ },
1100
+ publishConfig: {
1101
+ type: "boolean",
1102
+ default: true,
1103
+ description: "When false, the rule does not examine `publishConfig`."
1104
+ }
1105
+ },
1106
+ check(context, options) {
1107
+ if (context.packages.length === 0) return { skipped: "the repository has no workspace packages" };
1108
+ const main = cleanPath(typeof options["main"] === "string" ? options["main"] : "src/index.ts");
1109
+ const breaks = [];
1110
+ for (const info of context.packages) {
1111
+ const manifest = info.manifest;
1112
+ const at = (field) => {
1113
+ const line = lineOf(info.text, `"${field}"`);
1114
+ return line === void 0 ? {} : { line };
1115
+ };
1116
+ const value = manifest["main"];
1117
+ if (typeof value === "string") {
1118
+ if (cleanPath(value) !== main) breaks.push({
1119
+ file: info.file,
1120
+ ...at("main"),
1121
+ message: `"main" is "${value}", not "./${main}".`
1122
+ });
1123
+ } else if (ENTRY_FIELDS.some((field) => manifest[field] !== void 0) || manifest["private"] !== true) {
1124
+ if (manifest["bin"] === void 0) breaks.push({
1125
+ file: info.file,
1126
+ ...at("name"),
1127
+ message: `The package has no "main". A source package has "main": "./${main}".`
1128
+ });
1129
+ }
1130
+ if (options["publishConfig"] === false || manifest["private"] === true) continue;
1131
+ const published = typeof manifest["publishConfig"] === "object" && manifest["publishConfig"] !== null ? manifest["publishConfig"] : {};
1132
+ for (const field of ENTRY_FIELDS) {
1133
+ const source = pathsOf(manifest[field]).filter(isSourcePath);
1134
+ if (source.length === 0) continue;
1135
+ if (published[field] === void 0) {
1136
+ breaks.push({
1137
+ file: info.file,
1138
+ ...at(field),
1139
+ message: `"${field}" points at the source (${source[0] ?? ""}), and publishConfig has no "${field}": npm users get the source.`,
1140
+ fix: `Add publishConfig.${field} that points at the build.`
1141
+ });
1142
+ continue;
1143
+ }
1144
+ const still = pathsOf(published[field]).filter(isSourcePath);
1145
+ if (still.length > 0) breaks.push({
1146
+ file: info.file,
1147
+ ...at("publishConfig"),
1148
+ message: `publishConfig.${field} points at the source (${still[0] ?? ""}).`,
1149
+ fix: `Point publishConfig.${field} at the build.`
1150
+ });
1151
+ }
1152
+ }
1153
+ return breaks;
1154
+ }
1155
+ };
1156
+ // src/rules/tsconfig-test.ts
1157
+ /**
1158
+ * The rule `tsconfig-test`: each TypeScript package has a `tsconfig.test.json`, and its typecheck
1159
+ * examines it.
1160
+ */
1161
+ const tsconfigTest = {
1162
+ id: "tsconfig-test",
1163
+ title: "Each package with a `tsconfig.json` has a `tsconfig.test.json`, and its `typecheck` script examines it.",
1164
+ reason: "The build config leaves out the tests. Without a second config, `pnpm typecheck` does not examine the tests, and a type error in a test hides until the test runs.",
1165
+ fix: "Add `tsconfig.test.json` (extends `./tsconfig.json`, includes the tests, `noEmit`), and set the script `typecheck` to `tsc -p tsconfig.json && tsc -p tsconfig.test.json`.",
1166
+ sources: [
1167
+ {
1168
+ repo: "coeval",
1169
+ rule: "package-tsconfig-test",
1170
+ doc: "CLAUDE.md:18"
1171
+ },
1172
+ {
1173
+ repo: "coeval",
1174
+ rule: "tsconfig-test",
1175
+ doc: "CLAUDE.md:18"
1176
+ },
1177
+ {
1178
+ repo: "crawler",
1179
+ rule: "pkg-tsconfig-test",
1180
+ doc: "CLAUDE.md:18"
1181
+ },
1182
+ {
1183
+ repo: "crawler",
1184
+ rule: "tsconfig-test",
1185
+ doc: "CLAUDE.md:18"
1186
+ },
1187
+ {
1188
+ repo: "headroom",
1189
+ rule: "tsconfig-test",
1190
+ doc: "CLAUDE.md:32"
1191
+ },
1192
+ {
1193
+ repo: "headroom",
1194
+ rule: "tsconfig-test-per-package",
1195
+ doc: "CLAUDE.md:32"
1196
+ },
1197
+ {
1198
+ repo: "Vex",
1199
+ rule: "package-tsconfig-test",
1200
+ doc: "CLAUDE.md:23"
1201
+ },
1202
+ {
1203
+ repo: "Vex",
1204
+ rule: "tsconfig-test",
1205
+ doc: "CLAUDE.md:23"
1206
+ }
1207
+ ],
1208
+ options: { file: {
1209
+ type: "string",
1210
+ default: "tsconfig.test.json",
1211
+ description: "The name of the config of the tests."
1212
+ } },
1213
+ check(context, options) {
1214
+ if (context.packages.length === 0) return { skipped: "the repository has no workspace packages" };
1215
+ const file = typeof options["file"] === "string" ? options["file"] : "tsconfig.test.json";
1216
+ const breaks = [];
1217
+ for (const info of context.packages) {
1218
+ if (!hasFile(info.dir, "tsconfig.json")) continue;
1219
+ if (!hasFile(info.dir, file)) {
1220
+ breaks.push({
1221
+ file: inFolder(info.folder, file),
1222
+ message: `The package has a tsconfig.json and no ${file}.`
1223
+ });
1224
+ continue;
1225
+ }
1226
+ const scripts = info.manifest["scripts"];
1227
+ const typecheck = typeof scripts === "object" && scripts !== null ? scripts["typecheck"] : void 0;
1228
+ if (typeof typecheck === "string" && !typecheck.includes(file)) {
1229
+ const line = lineOf(info.text, "\"typecheck\"");
1230
+ breaks.push({
1231
+ file: info.file,
1232
+ ...line === void 0 ? {} : { line },
1233
+ message: `The script typecheck ("${typecheck}") does not examine ${file}.`,
1234
+ fix: `Add \`tsc -p ${file}\` to the script typecheck.`
1235
+ });
1236
+ }
1237
+ }
1238
+ return breaks;
1239
+ }
1240
+ };
1241
+ // src/rules/workspace-protocol.ts
1242
+ /**
1243
+ * The rule `workspace-protocol`: a package uses another package of the workspace through `workspace:`.
1244
+ */
1245
+ /** The fields that the rule examines. A peer dependency often keeps a range for its users, so the rule does not examine it. */
1246
+ const FIELDS = [
1247
+ "dependencies",
1248
+ "devDependencies",
1249
+ "optionalDependencies"
1250
+ ];
1251
+ const workspaceProtocol = {
1252
+ id: "workspace-protocol",
1253
+ title: "A dependency on a package of this workspace uses the `workspace:` protocol.",
1254
+ reason: "A version range or a git ref of a package of the same repository gets an old copy from the registry or from git, not the source next to it. Then a change and its test do not meet.",
1255
+ fix: "Use `\"workspace:*\"`. pnpm writes the real version when it publishes the package.",
1256
+ sources: [
1257
+ {
1258
+ repo: "client",
1259
+ rule: "workspace-protocol",
1260
+ doc: "CLAUDE.md:52"
1261
+ },
1262
+ {
1263
+ repo: "client",
1264
+ rule: "workspace-deps",
1265
+ doc: "CLAUDE.md:52"
1266
+ },
1267
+ {
1268
+ repo: "coeval",
1269
+ rule: "pinned-deps",
1270
+ doc: "CLAUDE.md:41"
1271
+ },
1272
+ {
1273
+ repo: "headroom",
1274
+ rule: "non-npm-deps-pinned",
1275
+ doc: "CLAUDE.md:38"
1276
+ },
1277
+ {
1278
+ repo: "crawler",
1279
+ rule: "mcp-workspace-dep",
1280
+ doc: "CLAUDE.md:55"
1281
+ }
1282
+ ],
1283
+ options: { prefix: {
1284
+ type: "string",
1285
+ default: "workspace:",
1286
+ description: "The start of each specifier, for example \"workspace:*\" to refuse \"workspace:^\"."
1287
+ } },
1288
+ check(context, options) {
1289
+ const prefix = typeof options["prefix"] === "string" ? options["prefix"] : "workspace:";
1290
+ const names = new Set(context.packages.map((info) => info.manifest["name"]).filter((name) => typeof name === "string"));
1291
+ const breaks = [];
1292
+ for (const info of [context.rootPackage, ...context.packages]) for (const field of FIELDS) for (const [name, spec] of specifiersOf(info.manifest, field)) {
1293
+ if (!names.has(name) || name === info.manifest["name"] || spec.startsWith(prefix)) continue;
1294
+ const line = keyLine(info.text, field, name);
1295
+ breaks.push({
1296
+ file: info.file,
1297
+ ...line === void 0 ? {} : { line },
1298
+ message: `${field} "${name}" is "${spec}", but "${name}" is a package of this workspace.`,
1299
+ fix: `Use "${prefix === "workspace:" ? "workspace:*" : prefix}".`
1300
+ });
1301
+ }
1302
+ return breaks;
1303
+ }
1304
+ };
1305
+ // src/rules/index.ts
1306
+ /** Each rule of the check. */
1307
+ const RULES = [
1308
+ pinnedGitDeps,
1309
+ workspaceProtocol,
1310
+ sourceMain,
1311
+ tsconfigTest,
1312
+ cuePreset,
1313
+ requiredScripts,
1314
+ noBuildOutput,
1315
+ noLocalPaths,
1316
+ releaseFiles
1317
+ ];
1318
+ // src/run.ts
1319
+ /**
1320
+ * The commands `check` and `--list` of the bin `conventions`, as functions. `runChecks` starts the
1321
+ * rules, and `runCli` reads the arguments and writes the result.
1322
+ */
1323
+ /** This function reads a `package.json` file. */
1324
+ function readPackage(root, dir) {
1325
+ const path = join(dir, "package.json");
1326
+ const text = readFileSync(path, "utf8");
1327
+ const parsed = JSON.parse(text);
1328
+ const manifest = typeof parsed === "object" && parsed !== null ? parsed : {};
1329
+ return {
1330
+ folder: relativePath(root, dir),
1331
+ dir,
1332
+ file: relativePath(root, path),
1333
+ text,
1334
+ manifest
1335
+ };
1336
+ }
1337
+ /** This function reads the configuration of the root `package.json` at `root`. */
1338
+ function readConfig(root, rules = RULES) {
1339
+ const file = join(root, "package.json");
1340
+ if (!existsSync(file)) throw new Error(`No package.json in ${root}.`);
1341
+ return parseConfig(JSON.parse(readFileSync(file, "utf8"))["conventions"], rules);
1342
+ }
1343
+ /** This function gives the facts of the repository at `root` that the rules read. */
1344
+ function createContext(root, config, options = {}) {
1345
+ const rootPackage = readPackage(root, root);
1346
+ const packages = packageFolders(root, config.packages ?? void 0).filter((dir) => resolve(dir) !== resolve(root)).map((dir) => readPackage(root, dir));
1347
+ let files = null;
1348
+ return {
1349
+ root,
1350
+ rootPackage,
1351
+ packages,
1352
+ env: options.env ?? {},
1353
+ ...options.base === void 0 ? {} : { base: options.base },
1354
+ gitFiles() {
1355
+ if (files === null) {
1356
+ const out = runGit(root, [
1357
+ "ls-files",
1358
+ "-z",
1359
+ "--cached"
1360
+ ]);
1361
+ files = out === void 0 ? void 0 : out.split("\0").filter((file) => file !== "");
1362
+ }
1363
+ return files;
1364
+ },
1365
+ git: (args) => runGit(root, args)
1366
+ };
1367
+ }
1368
+ /** This function starts each rule on the repository at `options.root`, and gives the result of each rule. */
1369
+ function runChecks(options) {
1370
+ const root = resolve(options.root);
1371
+ const rules = options.rules ?? RULES;
1372
+ const unknown = (options.only ?? []).filter((id) => !rules.some((rule) => rule.id === id));
1373
+ if (unknown.length > 0) throw new Error(`Unknown rule: ${unknown.join(", ")}. The rules are: ${rules.map((rule) => rule.id).join(", ")}.`);
1374
+ const config = readConfig(root, rules);
1375
+ const context = createContext(root, config, options);
1376
+ const results = [];
1377
+ for (const rule of rules) {
1378
+ if (options.only !== void 0 && options.only.length > 0 && !options.only.includes(rule.id)) continue;
1379
+ const ruleConfig = config.rules[rule.id] ?? {
1380
+ ignore: [],
1381
+ options: {}
1382
+ };
1383
+ const base = {
1384
+ id: rule.id,
1385
+ title: rule.title,
1386
+ fix: rule.fix
1387
+ };
1388
+ if (ruleConfig.off !== void 0) {
1389
+ results.push({
1390
+ ...base,
1391
+ status: "off",
1392
+ breaks: [],
1393
+ ignored: 0,
1394
+ note: ruleConfig.off
1395
+ });
1396
+ continue;
1397
+ }
1398
+ let outcome;
1399
+ try {
1400
+ outcome = rule.check(context, ruleConfig.options);
1401
+ } catch (error) {
1402
+ results.push({
1403
+ ...base,
1404
+ status: "error",
1405
+ breaks: [],
1406
+ ignored: 0,
1407
+ note: error instanceof Error ? error.message : String(error)
1408
+ });
1409
+ continue;
1410
+ }
1411
+ if ("skipped" in outcome) {
1412
+ results.push({
1413
+ ...base,
1414
+ status: "skipped",
1415
+ breaks: [],
1416
+ ignored: 0,
1417
+ note: outcome.skipped
1418
+ });
1419
+ continue;
1420
+ }
1421
+ const breaks = outcome.filter((item) => !matchesAny(item.file, ruleConfig.ignore));
1422
+ const ignored = outcome.length - breaks.length;
1423
+ const note = ruleConfig.reason === void 0 ? {} : { note: ruleConfig.reason };
1424
+ results.push({
1425
+ ...base,
1426
+ status: breaks.length > 0 ? "break" : "pass",
1427
+ breaks,
1428
+ ignored,
1429
+ ...note
1430
+ });
1431
+ }
1432
+ return {
1433
+ rules: results,
1434
+ failed: results.some((result) => result.status === "break" || result.status === "error")
1435
+ };
1436
+ }
1437
+ /** The most breaks of one rule in the text output. The JSON output has each break. */
1438
+ const MAX_SHOWN = 50;
1439
+ /** This function gives the place of a break as `file:line`. */
1440
+ const placeOf = (item) => item.line === void 0 ? item.file : `${item.file}:${item.line}`;
1441
+ /** This function gives the text of a result for a terminal or a CI log. */
1442
+ function formatResult(result) {
1443
+ const count = (status) => result.rules.filter((rule) => rule.status === status).length;
1444
+ const breaks = result.rules.reduce((sum, rule) => sum + rule.breaks.length, 0);
1445
+ const out = [`conventions: ${result.rules.length} rules: ${count("pass")} pass, ${count("break")} with ${breaks} break(s), ${count("off")} off, ${count("skipped")} skipped, ${count("error")} error(s).`, ""];
1446
+ const label = {
1447
+ pass: "pass ",
1448
+ break: "BREAK",
1449
+ off: "off ",
1450
+ skipped: "skip ",
1451
+ error: "ERROR"
1452
+ };
1453
+ for (const rule of result.rules) {
1454
+ const extra = rule.ignored > 0 ? ` (${rule.ignored} ignored: ${rule.note ?? ""})` : rule.note !== void 0 && rule.status !== "pass" ? ` (${rule.note})` : "";
1455
+ out.push(`${label[rule.status]} ${rule.id}${rule.breaks.length > 0 ? `: ${rule.breaks.length} break(s)` : ""}${extra}`);
1456
+ for (const item of rule.breaks.slice(0, MAX_SHOWN)) {
1457
+ out.push(` ${placeOf(item)} ${item.message}`);
1458
+ if (item.fix !== void 0) out.push(` fix: ${item.fix}`);
1459
+ }
1460
+ if (rule.breaks.length > MAX_SHOWN) out.push(` ... ${rule.breaks.length - MAX_SHOWN} more. Start \`conventions check --json\` for each break.`);
1461
+ if (rule.breaks.length > 0) out.push(` rule: ${rule.title}`, ` fix: ${rule.fix}`);
1462
+ }
1463
+ if (result.failed) out.push("", "To turn a rule off or to keep an exception, add a reason in the field conventions of package.json (`conventions --list`).");
1464
+ return `${out.join("\n")}\n`;
1465
+ }
1466
+ /** This function escapes the text of a cell of a Markdown table. */
1467
+ const cell = (text) => text.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
1468
+ /** This function gives the result as Markdown for the summary of a GitHub Actions run. */
1469
+ function summaryMarkdown(result) {
1470
+ const out = [
1471
+ "### Conventions",
1472
+ "",
1473
+ "| Rule | Result | Note |",
1474
+ "|---|---|---|"
1475
+ ];
1476
+ for (const rule of result.rules) {
1477
+ const shown = rule.status === "break" ? `${rule.breaks.length} break(s)` : rule.status;
1478
+ const note = rule.ignored > 0 ? `${rule.ignored} ignored: ${rule.note ?? ""}` : rule.note ?? "";
1479
+ out.push(`| \`${rule.id}\` | ${shown} | ${cell(note)} |`);
1480
+ }
1481
+ const broken = result.rules.filter((rule) => rule.breaks.length > 0);
1482
+ for (const rule of broken) {
1483
+ out.push("", `<details open><summary><code>${rule.id}</code>: ${rule.breaks.length} break(s)</summary>`, "", `${rule.title} Fix: ${rule.fix}`, "");
1484
+ for (const item of rule.breaks.slice(0, MAX_SHOWN)) out.push(`- \`${placeOf(item)}\`: ${item.message}${item.fix === void 0 ? "" : ` Fix: ${item.fix}`}`);
1485
+ if (rule.breaks.length > MAX_SHOWN) out.push(`- ... ${rule.breaks.length - MAX_SHOWN} more`);
1486
+ out.push("", "</details>");
1487
+ }
1488
+ return `${out.join("\n")}\n`;
1489
+ }
1490
+ /** This function escapes a value of a workflow command of GitHub Actions. */
1491
+ const escapeData = (text) => text.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
1492
+ const escapeProperty = (text) => escapeData(text).replace(/:/g, "%3A").replace(/,/g, "%2C");
1493
+ /** This function gives an `::error` workflow command for each break, so that GitHub shows each break on its line in the pull request. */
1494
+ function annotations(result) {
1495
+ const out = [];
1496
+ for (const rule of result.rules) for (const item of rule.breaks) {
1497
+ const line = item.line === void 0 ? "" : `,line=${item.line}`;
1498
+ out.push(`::error file=${escapeProperty(item.file)}${line},title=${escapeProperty(`conventions ${rule.id}`)}::${escapeData(`${item.message} Fix: ${item.fix ?? rule.fix}`)}`);
1499
+ }
1500
+ return out.length === 0 ? "" : `${out.join("\n")}\n`;
1501
+ }
1502
+ /** This function gives the text of `--list`: each rule, its reason, its fix, its options, its state and its audit sources. */
1503
+ function listRules(config, rules = RULES) {
1504
+ const out = [];
1505
+ for (const rule of rules) {
1506
+ const ruleConfig = config?.rules[rule.id];
1507
+ const state = ruleConfig?.off !== void 0 ? `off: ${ruleConfig.off}` : "on";
1508
+ out.push(`${rule.id} (${state})`, ` ${rule.title}`, ` why: ${rule.reason}`, ` fix: ${rule.fix}`);
1509
+ for (const [name, spec] of Object.entries(rule.options)) {
1510
+ const value = ruleConfig?.options[name] ?? spec.default;
1511
+ out.push(` option ${name} = ${JSON.stringify(value)}: ${spec.description}`);
1512
+ }
1513
+ if (ruleConfig !== void 0 && ruleConfig.ignore.length > 0) out.push(` ignore ${ruleConfig.ignore.join(", ")}: ${ruleConfig.reason ?? ""}`);
1514
+ else if (ruleConfig?.reason !== void 0) out.push(` reason: ${ruleConfig.reason}`);
1515
+ out.push(` from: ${rule.sources.map((source) => `${source.repo} ${source.rule} (${source.doc})`).join("; ")}`, "");
1516
+ }
1517
+ return `${out.join("\n")}`;
1518
+ }
1519
+ /** The help text of the bin. */
1520
+ const USAGE = `Usage: conventions check [options]
1521
+ conventions --list
1522
+
1523
+ check Start each rule. Exit code 1 when a rule has a break.
1524
+ --list Show each rule: why, fix, options, state and the audit rows that it comes from.
1525
+
1526
+ --root <folder> The root of the repository. The default is the current folder.
1527
+ --rule <id> Only this rule. Use it again for more rules.
1528
+ --base <ref> The base commit of the change, for the rule release-files. On a pull request, the rule finds it.
1529
+ --json Write the result as JSON.
1530
+ -h, --help Show this text.
1531
+
1532
+ The field "conventions" of the root package.json turns a rule off with a reason, keeps an exception
1533
+ with a reason, and sets the options of a rule with a reason:
1534
+
1535
+ "conventions": { "rules": { "no-build-output": { "off": "<reason>" },
1536
+ "cue-preset": { "ignore": ["packages/web/**"], "reason": "<reason>" },
1537
+ "workspace-protocol": { "prefix": "workspace:*", "reason": "<reason>" } } }
1538
+ `;
1539
+ /** An error of the arguments: exit code 2 and the help text. */
1540
+ var UsageError = class extends Error {};
1541
+ /** This function starts the bin with the arguments `args`, and gives its exit code. */
1542
+ function runCli(args, io) {
1543
+ let check = false;
1544
+ let list = false;
1545
+ let json = false;
1546
+ let root = io.cwd;
1547
+ let base;
1548
+ const only = [];
1549
+ try {
1550
+ for (let index = 0; index < args.length; index++) {
1551
+ const arg = args[index] ?? "";
1552
+ const value = () => {
1553
+ const next = args[++index];
1554
+ if (next === void 0 || next.startsWith("-")) throw new UsageError(`The option ${arg} needs a value.`);
1555
+ return next;
1556
+ };
1557
+ if (arg === "check") check = true;
1558
+ else if (arg === "--list" || arg === "list") list = true;
1559
+ else if (arg === "--json") json = true;
1560
+ else if (arg === "--root") root = resolve(io.cwd, value());
1561
+ else if (arg === "--rule") only.push(value());
1562
+ else if (arg === "--base") base = value();
1563
+ else if (arg === "--help" || arg === "-h") {
1564
+ io.stdout(USAGE);
1565
+ return 0;
1566
+ } else throw new UsageError(`An unknown argument: ${arg}`);
1567
+ }
1568
+ if (!check && !list) throw new UsageError("Give the command check, or --list.");
1569
+ } catch (error) {
1570
+ if (!(error instanceof UsageError)) throw error;
1571
+ io.stderr(`conventions: ${error.message}\n\n${USAGE}`);
1572
+ return 2;
1573
+ }
1574
+ if (list) {
1575
+ let config;
1576
+ try {
1577
+ config = existsSync(join(root, "package.json")) ? readConfig(root) : void 0;
1578
+ } catch (error) {
1579
+ io.stderr(`conventions: ${error instanceof Error ? error.message : String(error)}\n`);
1580
+ return 1;
1581
+ }
1582
+ io.stdout(listRules(config));
1583
+ return 0;
1584
+ }
1585
+ let result;
1586
+ try {
1587
+ result = runChecks({
1588
+ root,
1589
+ only,
1590
+ env: io.env,
1591
+ ...base === void 0 ? {} : { base }
1592
+ });
1593
+ } catch (error) {
1594
+ io.stderr(`conventions: ${error instanceof Error ? error.message : String(error)}\n`);
1595
+ return 1;
1596
+ }
1597
+ if (json) io.stdout(`${JSON.stringify(result, null, 2)}\n`);
1598
+ else {
1599
+ if (io.env["GITHUB_ACTIONS"] === "true") io.stdout(annotations(result));
1600
+ io.stdout(formatResult(result));
1601
+ }
1602
+ const summary = io.env["GITHUB_STEP_SUMMARY"];
1603
+ if (summary) appendFileSync(summary, summaryMarkdown(result));
1604
+ return result.failed ? 1 : 0;
1605
+ }
1606
+ export { inFolder as A, packageFolders as B, noLocalPaths as C, DEPENDENCY_FIELDS as D, cuePreset as E, readJsonc as F, defaultOptions as H, runGit as I, specifiersOf as L, lineOf as M, matchesAny as N, cleanPath as O, parseJsonc as P, globFolders as R, HOME_PATTERNS as S, STRICT_OPTIONS as T, parseConfig as U, workspaceGlobs as V, releaseFiles as _, listRules as a, pinnedGitDeps as b, runCli as c, workspaceProtocol as d, tsconfigTest as f, requiredScripts as g, sourceMain as h, formatResult as i, keyLine as j, hasFile as k, summaryMarkdown as l, pathsOf as m, annotations as n, readConfig as o, isSourcePath as p, createContext as r, runChecks as s, USAGE as t, RULES as u, isGitSpecifier as v, noBuildOutput as w, DEFAULT_ALLOWED as x, isPinned as y, globToRegExp as z };
1607
+
1608
+ //# sourceMappingURL=run-B73MKaR7.js.map