@mark1russell7/conventions 0.13.1 → 0.14.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/README.md +5 -1
- package/build/cli.js +1 -1
- package/build/index.d.ts +60 -35
- package/build/index.d.ts.map +1 -1
- package/build/index.js +1 -1
- package/build/{run-BxPv_FTo.js → run-2K_CrANg.js} +8069 -3039
- package/build/run-2K_CrANg.js.map +1 -0
- package/package.json +1 -1
- package/build/run-BxPv_FTo.js.map +0 -1
package/README.md
CHANGED
|
@@ -54,6 +54,7 @@ The rules come from the invariants audit of 2026-10-26 (strategy item s38). The
|
|
|
54
54
|
| `roadmap-parses` | Each call of the Pages workflow of the template (`reusable-pages.yml`) gives a `roadmap`, or `site-pages: false`. Without it, the Status page shows no item of the plan. Each roadmap that a workflow gives to the Status page (a `roadmap:` key) parses as `@mark1russell7/site-pages` reads it. The rule uses the parser of site-pages. Thus a pull request finds a bad row, and the Pages job on `main` does not stop on it. | fleet `fail-closed` (STRATEGY.md, 2026-10-30). |
|
|
55
55
|
| `runner-budget` | All repositories of the account share 40 runners. Each `strategy` with a `matrix` has a `max-parallel` of 3 or less. Each workflow has a concurrency group at the top or in each job. A job that calls a shared workflow of the option `grouped` gets its group from that workflow, and each job of that workflow has a group. The minute of each `cron` comes from a hash of the repository and the file (1 to 59), so the schedules of the repositories do not start together. The repository comes from `GITHUB_REPOSITORY` or from the remote `origin`. | fleet `runner-slots` (STRATEGY.md, 2026-10-30). |
|
|
56
56
|
| `gate-trigger` | No workflow has `paths` or `paths-ignore` on `on.pull_request` or `on.pull_request_target`. The ruleset needs the summary check `<Name> OK` of each gate, and a workflow with a path filter does not start on each pull request. Then its check is not there, the ruleset cannot ask for it, and a pull request can merge before the gate ends. A gate uses the actions `changes` and `gate-summary` of the template (`CI.md`, "A gate with paths"). | fleet `gate-trigger` (STRATEGY.md, 2026-11-02). |
|
|
57
|
+
| `home-package` | A change does not add a function with a signature name of another home of the map (for example `median`, `mulberry32` or `writeFileAtomic`). A local copy drifts from the home and splits the fixes. On 2026-11-02 the fleet had 68 local statistics functions in 14 repositories. The rule examines only the lines that the change adds, so the copies that exist do not break. | fleet direction 18 (STRATEGY.md, 2026-11-02). |
|
|
57
58
|
|
|
58
59
|
The rule `release-files` needs the base of the change. On a pull request, the checkout is a merge commit, and the rule reads its two parents (`fetch-depth` 2 or more). In other runs, give `--base <ref>`. Without a base, the rule shows `skip`. The rule also needs each commit of the change. A shallow checkout can end inside the change. Then the authors and the messages that the rule reads are not those of the change, so the rule shows `error`. A pull request of one commit is complete at depth 2. For a longer one, the CI of the template deepens the checkout to the merge base.
|
|
59
60
|
|
|
@@ -110,6 +111,7 @@ An unknown rule, an unknown option, or an exception or a changed option without
|
|
|
110
111
|
| `runner-budget.minute` | `true` | When `false`, the rule does not examine the minute of the schedules. |
|
|
111
112
|
| `runner-budget.grouped` | `["reusable-ai-review.yml", "reusable-codex-review.yml"]` | The shared workflows that give a concurrency group in each of their jobs. |
|
|
112
113
|
| `gate-trigger.allow` | `[]` | The file names of the workflows that can filter pull requests by path, because they are not a gate (for example a preview). |
|
|
114
|
+
| `home-package.scope` | `"change"` | `"change"`: only the lines that a pull request or `--base` adds. `"all"`: each line of each tracked file, for a sweep of the copies that exist. |
|
|
113
115
|
|
|
114
116
|
## Commands
|
|
115
117
|
|
|
@@ -120,7 +122,7 @@ An unknown rule, an unknown option, or an exception or a changed option without
|
|
|
120
122
|
| `--list` | Show each rule: the reason, the fix, the options, the state and the audit rows. |
|
|
121
123
|
| `--root <folder>` | The root of the repository. The default is the current folder. |
|
|
122
124
|
| `--rule <id>` | Only this rule. Use it again for more rules. |
|
|
123
|
-
| `--base <ref>` | The base commit of the change, for the
|
|
125
|
+
| `--base <ref>` | The base commit of the change, for the rules `release-files` and `home-package`. |
|
|
124
126
|
| `--json` | Write the result as JSON. |
|
|
125
127
|
|
|
126
128
|
## The map of homes
|
|
@@ -134,6 +136,8 @@ conventions map --markdown # the table with the rule, for a CLAUDE.md
|
|
|
134
136
|
conventions map --overlay homes.json --markdown # with more homes from a JSON file
|
|
135
137
|
```
|
|
136
138
|
|
|
139
|
+
Each home can give `signatures`: the names of functions that only the home has, as regular expressions of a whole name. The rule `home-package` breaks on a new function with such a name in another repository. Its message says if the home already exports the name. The index of the exports is `src/home-exports.ts`. The script `scripts/homes/exports.ts` of the template writes it from the latest version of each home on npm.
|
|
140
|
+
|
|
137
141
|
An overlay file has the shape `{ "homes": [...] }`. A home of the overlay takes the place of the home with the same area. The private repositories use an overlay, because the public map names only public packages.
|
|
138
142
|
|
|
139
143
|
## Add a rule
|
package/build/cli.js
CHANGED
package/build/index.d.ts
CHANGED
|
@@ -176,6 +176,61 @@ export declare function convertGate(text: string, file: string, commit?: string)
|
|
|
176
176
|
reason: string;
|
|
177
177
|
};
|
|
178
178
|
export declare const gateTrigger: Rule;
|
|
179
|
+
/** The state of a home: on npm, in a repository but not on npm, only on a roadmap, or with no package. */
|
|
180
|
+
type HomeState = "published" | "unpublished" | "planned" | "none";
|
|
181
|
+
/** One area of code and its home. */
|
|
182
|
+
interface Home {
|
|
183
|
+
/** The id of the area, in kebab case. */
|
|
184
|
+
readonly area: string;
|
|
185
|
+
/** The area in a few plain words. */
|
|
186
|
+
readonly title: string;
|
|
187
|
+
/** The code that belongs in the home. */
|
|
188
|
+
readonly covers: string;
|
|
189
|
+
/** The packages of the home. A planned home has no package yet. */
|
|
190
|
+
readonly packages: readonly string[];
|
|
191
|
+
/** The repository of the home, as owner/name. */
|
|
192
|
+
readonly repo: string;
|
|
193
|
+
/** The state of the home. */
|
|
194
|
+
readonly state: HomeState;
|
|
195
|
+
/** More words that find the area in a search. */
|
|
196
|
+
readonly words: readonly string[];
|
|
197
|
+
/**
|
|
198
|
+
* The names of the functions that only the home has: each is a regular expression of a whole name, for example `median(Of)?`.
|
|
199
|
+
* The rule home-package of conventions breaks on a new function with such a name in another repository. Names that many
|
|
200
|
+
* areas use (for example `parse` or `record`) are not signatures: they give false breaks.
|
|
201
|
+
*/
|
|
202
|
+
readonly signatures?: readonly string[];
|
|
203
|
+
/** A note: the code that goes to another home, or a known split. */
|
|
204
|
+
readonly note?: string;
|
|
205
|
+
}
|
|
206
|
+
/** The rule of the map. Each session and each review applies it. */
|
|
207
|
+
export declare const MAP_RULE = "Before you write a helper, find its home in this map. If the home does not have the function, add it to the home, in a pull request of the home repository. Do not make a local copy, a new package or a new repository for an area that has a home: that needs the strategist. A home that is not on npm is used with workspace:* or a github: specifier pinned to a commit. If no area fits, ask the strategist for a home before you write the code.";
|
|
208
|
+
/** The public homes. Each package of the fleet that other code can use has one area. */
|
|
209
|
+
export declare const HOMES: readonly Home[];
|
|
210
|
+
/** A file of more homes, for example the private repositories, in the shape `{ "homes": Home[] }`. */
|
|
211
|
+
export declare function readOverlay(file: string): readonly Home[];
|
|
212
|
+
/** This function merges the homes. A home of `extra` with the area of a home of `base` takes its place. */
|
|
213
|
+
export declare function mergeHomes(base: readonly Home[], extra: readonly Home[]): readonly Home[];
|
|
214
|
+
/** This function gives the homes that match each word of `query`, best match first. */
|
|
215
|
+
export declare function findHomes(query: string, homes?: readonly Home[]): readonly Home[];
|
|
216
|
+
/** This function writes the map as a Markdown table, with the rule first. */
|
|
217
|
+
export declare function mapMarkdown(homes?: readonly Home[]): string;
|
|
218
|
+
/** This function writes the homes as plain text for a terminal. */
|
|
219
|
+
export declare function mapText(homes: readonly Home[]): string;
|
|
220
|
+
/** One signature of a home, as a regular expression of a whole name. */
|
|
221
|
+
interface Signature {
|
|
222
|
+
readonly home: Home;
|
|
223
|
+
readonly pattern: RegExp;
|
|
224
|
+
}
|
|
225
|
+
/** This function gives the signatures of the homes that a repository can use: on npm, or in a repository with a pin. */
|
|
226
|
+
export declare function signaturesOf(homes: readonly Home[]): Signature[];
|
|
227
|
+
/** This function gives the name of the function that a line declares, or undefined. */
|
|
228
|
+
export declare function declaredName(line: string): string | undefined;
|
|
229
|
+
/** This function gives the repository of the root as owner/name, in lower case: the remote origin, or GITHUB_REPOSITORY. */
|
|
230
|
+
export declare function repoOf(context: RuleContext): string | undefined;
|
|
231
|
+
/** This function gives the message of a break: the home, and if the home already exports the name. */
|
|
232
|
+
export declare function messageOf(file: string, name: string, home: Home): string;
|
|
233
|
+
export declare const homePackage: Rule;
|
|
179
234
|
/** The compare of two real paths. It is true through a link too, and it works on each Node version. */
|
|
180
235
|
export declare const REAL_COMPARE = "process.argv[1] !== undefined && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))";
|
|
181
236
|
/** This function tells if each Node version of the range has `import.meta.main`: 22.18 and later in 22, and 24.2 and later. Node 23 does not have it. */
|
|
@@ -235,6 +290,11 @@ export declare const trustPolicy: Rule;
|
|
|
235
290
|
export declare const workspaceProtocol: Rule;
|
|
236
291
|
/** Each rule of the check. */
|
|
237
292
|
export declare const RULES: readonly Rule[];
|
|
293
|
+
/** The names of the values that each home package exports, with the version that the names come from. */
|
|
294
|
+
export declare const HOME_EXPORTS: Readonly<Record<string, {
|
|
295
|
+
readonly version: string;
|
|
296
|
+
readonly names: readonly string[];
|
|
297
|
+
}>>;
|
|
238
298
|
/** The result of one rule. */
|
|
239
299
|
interface RuleResult {
|
|
240
300
|
readonly id: string;
|
|
@@ -306,41 +366,6 @@ interface CliIo {
|
|
|
306
366
|
export declare const USAGE: string;
|
|
307
367
|
/** This function starts the bin with the arguments `args`, and gives its exit code. */
|
|
308
368
|
export declare function runCli(args: readonly string[], io: CliIo): number;
|
|
309
|
-
/** The state of a home: on npm, in a repository but not on npm, only on a roadmap, or with no package. */
|
|
310
|
-
type HomeState = "published" | "unpublished" | "planned" | "none";
|
|
311
|
-
/** One area of code and its home. */
|
|
312
|
-
interface Home {
|
|
313
|
-
/** The id of the area, in kebab case. */
|
|
314
|
-
readonly area: string;
|
|
315
|
-
/** The area in a few plain words. */
|
|
316
|
-
readonly title: string;
|
|
317
|
-
/** The code that belongs in the home. */
|
|
318
|
-
readonly covers: string;
|
|
319
|
-
/** The packages of the home. A planned home has no package yet. */
|
|
320
|
-
readonly packages: readonly string[];
|
|
321
|
-
/** The repository of the home, as owner/name. */
|
|
322
|
-
readonly repo: string;
|
|
323
|
-
/** The state of the home. */
|
|
324
|
-
readonly state: HomeState;
|
|
325
|
-
/** More words that find the area in a search. */
|
|
326
|
-
readonly words: readonly string[];
|
|
327
|
-
/** A note: the code that goes to another home, or a known split. */
|
|
328
|
-
readonly note?: string;
|
|
329
|
-
}
|
|
330
|
-
/** The rule of the map. Each session and each review applies it. */
|
|
331
|
-
export declare const MAP_RULE = "Before you write a helper, find its home in this map. If the home does not have the function, add it to the home, in a pull request of the home repository. Do not make a local copy, a new package or a new repository for an area that has a home: that needs the strategist. A home that is not on npm is used with workspace:* or a github: specifier pinned to a commit. If no area fits, ask the strategist for a home before you write the code.";
|
|
332
|
-
/** The public homes. Each package of the fleet that other code can use has one area. */
|
|
333
|
-
export declare const HOMES: readonly Home[];
|
|
334
|
-
/** A file of more homes, for example the private repositories, in the shape `{ "homes": Home[] }`. */
|
|
335
|
-
export declare function readOverlay(file: string): readonly Home[];
|
|
336
|
-
/** This function merges the homes. A home of `extra` with the area of a home of `base` takes its place. */
|
|
337
|
-
export declare function mergeHomes(base: readonly Home[], extra: readonly Home[]): readonly Home[];
|
|
338
|
-
/** This function gives the homes that match each word of `query`, best match first. */
|
|
339
|
-
export declare function findHomes(query: string, homes?: readonly Home[]): readonly Home[];
|
|
340
|
-
/** This function writes the map as a Markdown table, with the rule first. */
|
|
341
|
-
export declare function mapMarkdown(homes?: readonly Home[]): string;
|
|
342
|
-
/** This function writes the homes as plain text for a terminal. */
|
|
343
|
-
export declare function mapText(homes: readonly Home[]): string;
|
|
344
369
|
/**
|
|
345
370
|
* This function gives a regular expression for a glob of `/` paths. `*` matches a part of one path
|
|
346
371
|
* segment, `?` matches one character, `**` matches zero or more segments, and `{a,b}` matches one of
|
package/build/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","names":[],"sources":["../src/rule.ts","../src/config.ts","../src/rules/cue-preset.ts","../src/rules/gate-trigger.ts","../src/rules/main-check.ts","../src/rules/no-build-output.ts","../src/rules/no-local-paths.ts","../src/rules/pinned-git-deps.ts","../src/rules/release-files.ts","../src/rules/required-scripts.ts","../src/rules/roadmap-parses.ts","../src/rules/runner-budget.ts","../src/rules/source-main.ts","../src/rules/tests-required.ts","../src/rules/tsconfig-test.ts","../src/rules/typed-files.ts","../src/rules/typed-scripts.ts","../src/rules/trust-policy.ts","../src/rules/workspace-protocol.ts","../src/rules/index.ts","../src/
|
|
1
|
+
{"version":3,"file":"index.d.ts","names":[],"sources":["../src/rule.ts","../src/config.ts","../src/rules/cue-preset.ts","../src/rules/gate-trigger.ts","../src/map.ts","../src/rules/home-package.ts","../src/rules/main-check.ts","../src/rules/no-build-output.ts","../src/rules/no-local-paths.ts","../src/rules/pinned-git-deps.ts","../src/rules/release-files.ts","../src/rules/required-scripts.ts","../src/rules/roadmap-parses.ts","../src/rules/runner-budget.ts","../src/rules/source-main.ts","../src/rules/tests-required.ts","../src/rules/tsconfig-test.ts","../src/rules/typed-files.ts","../src/rules/typed-scripts.ts","../src/rules/trust-policy.ts","../src/rules/workspace-protocol.ts","../src/rules/index.ts","../src/home-exports.ts","../src/run.ts","../src/workspace.ts"],"mappings":"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"}
|
package/build/index.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export {
|
|
1
|
+
export { nt as ACTIONS_COMMIT, I as DEFAULT_ALLOWED, lt as DEPENDENCY_FIELDS, J as HOMES, tt as HOME_EXPORTS, L as HOME_PATTERNS, p as IGNORE_AFTER, Y as MAP_RULE, B as REAL_COMPARE, d as RULES, st as STRICT_OPTIONS, m as TRAIN_SCOPES, t as USAGE, n as annotations, ut as cleanPath, dt as codePackages, _ as configsOfScript, rt as convertGate, r as createContext, ct as cuePreset, U as declaredName, Et as defaultOptions, X as findHomes, i as formatResult, it as gateTrigger, St as globFolders, Ct as globToRegExp, ft as hasFile, V as hasImportMetaMain, x as hasTests, W as homePackage, pt as inFolder, N as isGitSpecifier, P as isPinned, C as isSourcePath, mt as keyLine, ht as lineOf, a as listRules, H as mainCheck, Z as mapMarkdown, Q as mapText, gt as matchesAny, $ as mergeHomes, G as messageOf, z as noBuildOutput, R as noLocalPaths, wt as packageFolders, Dt as parseConfig, _t as parseJsonc, w as pathsOf, F as pinnedGitDeps, at as prPathFilters, o as readConfig, vt as readJsonc, et as readOverlay, M as releaseFiles, yt as replaceLine, K as repoOf, E as repositoryOfRemote, j as requiredScripts, k as roadmapOfLine, A as roadmapParses, s as runChecks, c as runCli, l as runFix, bt as runGit, D as runnerBudget, O as scheduleMinute, v as scriptsOf, q as signaturesOf, T as sourceMain, xt as specifiersOf, u as summaryMarkdown, ot as summaryName, b as testsRequired, h as trustPolicy, S as tsconfigTest, y as typedFiles, g as typedScripts, Tt as workspaceGlobs, f as workspaceProtocol } from "./run-2K_CrANg.js";
|