@mark1russell7/conventions 0.8.0 → 0.8.2

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 CHANGED
@@ -14,11 +14,20 @@ Add the script `"check:conventions": "conventions check"` to the root `package.j
14
14
 
15
15
  ```sh
16
16
  pnpm exec conventions check
17
+ pnpm exec conventions fix
17
18
  pnpm exec conventions --list
18
19
  ```
19
20
 
20
21
  Each break shows the file, the line, the rule and the fix. In GitHub Actions, the check also writes an annotation on the line of each break. It also writes a table of the rules to the summary of the run (`GITHUB_STEP_SUMMARY`). The exit code is 1 when a rule has a break.
21
22
 
23
+ `conventions fix` writes the fixes that the rules know, and checks again. It continues until no fix applies. Each fix is an exact change of a file, and the fix writes it only when the file did not change after the check. These breaks have a fix:
24
+
25
+ - `runner-budget`: the minute of a schedule, a `max-parallel` of a matrix, and a concurrency group at the top of a workflow. A new run of a pull request stops the old run. A run of another event waits for the old run.
26
+ - `tests-required`: the option `passWithNoTests` in a config or a script, in a package with test files. A package with no tests needs a person, who removes its test script.
27
+ - `typed-files`: a config file at the root of a package (`vitest.config.ts`). The fix adds `*.config.ts` and `rootDir: "."` to the `tsconfig.test.json` of the package, when that file has no comments.
28
+
29
+ The text output marks each break that has a fix. In the JSON output, such a break has `fixable: true`. The release train starts `conventions fix` in its update pull requests. Thus a break that a script can fix does not block a repository.
30
+
22
31
  ## Rules
23
32
 
24
33
  The rules come from the invariants audit of 2026-10-26 (strategy item s38). The audit read the rule documents of 7 repositories. Each rule here is a convention that 3 or more repositories tell, and that a script examines exactly. The column "From" gives the repository and the id of each audit row.
@@ -98,6 +107,7 @@ An unknown rule, an unknown option, or an exception or a changed option without
98
107
  | Option | What it sets |
99
108
  |---|---|
100
109
  | `check` | Start each rule. |
110
+ | `fix` | Write the fixes of the breaks that have one, and check again. The exit code is 1 when a break stays. |
101
111
  | `--list` | Show each rule: the reason, the fix, the options, the state and the audit rows. |
102
112
  | `--root <folder>` | The root of the repository. The default is the current folder. |
103
113
  | `--rule <id>` | Only this rule. Use it again for more rules. |
@@ -106,13 +116,16 @@ An unknown rule, an unknown option, or an exception or a changed option without
106
116
 
107
117
  ## Add a rule
108
118
 
109
- A rule is a module in `src/rules/` that exports a `Rule`. A `Rule` has an `id`, a `title`, a `reason`, a `fix` and its audit `sources`. It also has its `options` with defaults, and a function `check(context, options)`. The function gives a list of breaks, or `{ skipped: "<reason>" }`. Add the rule to `RULES` in `src/rules/index.ts`, with a test of a case that passes and a case that breaks. Add a rule only when 3 or more repositories tell it and a script examines it exactly.
119
+ A rule is a module in `src/rules/` that exports a `Rule`. A `Rule` has an `id`, a `title`, a `reason`, a `fix` and its audit `sources`. It also has its `options` with defaults, and a function `check(context, options)`. The function gives a list of breaks, or `{ skipped: "<reason>" }`.
120
+
121
+ A break can have `edits`: each edit gives a file, its whole text `before` and its whole text `after`. Give an edit only when the fix is certain, and test it with `runFix`. Add the rule to `RULES` in `src/rules/index.ts`, with a test of a case that passes and a case that breaks. Add a rule only when 3 or more repositories tell it and a script examines it exactly.
110
122
 
111
123
  ## Library
112
124
 
113
125
  The package also exports the functions of the tool:
114
126
 
115
- - `runChecks(options)` starts the rules and gives the result of each rule. `runCli(args, io)` is the bin.
127
+ - `runChecks(options)` starts the rules and gives the result of each rule. `runFix(options)` writes the edits and gives the changed files and the last result. `runCli(args, io)` is the bin.
128
+ - `replaceLine(text, line, lines)` gives the text with one line replaced, for the edits of a rule.
116
129
  - `formatResult(result)`, `summaryMarkdown(result)`, `annotations(result)` and `listRules(config)` give the output.
117
130
  - `parseConfig(value, rules)` and `readConfig(root)` read the field `conventions`.
118
131
  - `RULES` and each rule, with the helpers `isGitSpecifier`, `isPinned`, `isSourcePath` and `parseJsonc`.
package/build/cli.js CHANGED
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- import { c as runCli } from "./run-d-5ceKnT.js";
2
+ import { c as runCli } from "./run-DD72yQn7.js";
3
3
  // src/cli.ts
4
4
  try {
5
5
  process.exitCode = runCli(process.argv.slice(2), {
package/build/index.d.ts CHANGED
@@ -13,7 +13,23 @@ interface Break {
13
13
  readonly message: string;
14
14
  /** A fix for this break. The fix of the rule applies when this field is missing. */
15
15
  readonly fix?: string;
16
+ /** The changes of files that fix this break, for `conventions fix`. A break with no edits needs a person. */
17
+ readonly edits?: readonly Edit[];
16
18
  }
19
+ /**
20
+ * A change of one file that `conventions fix` writes. The file must still have the text `before`, else the edit does
21
+ * not apply. An edit that an earlier edit made stale waits for the next check.
22
+ */
23
+ interface Edit {
24
+ /** The file, relative to the root, with `/`. */
25
+ readonly file: string;
26
+ /** The whole text of the file before the change. */
27
+ readonly before: string;
28
+ /** The whole text of the file after the change. */
29
+ readonly after: string;
30
+ }
31
+ /** This function gives `text` with the line `line` (from 1) replaced by `lines`, with the line ends of `text`. An empty `lines` removes the line. */
32
+ export declare function replaceLine(text: string, line: number, lines: readonly string[]): string;
17
33
  /** A value of an option of a rule. */
18
34
  type OptionValue = string | number | boolean | readonly string[];
19
35
  /** The options of a rule, after the defaults. */
@@ -222,6 +238,21 @@ export declare function readConfig(root: string, rules?: readonly Rule[]): Conve
222
238
  export declare function createContext(root: string, config: ConventionsConfig, options?: Pick<CheckOptions, "base" | "env">): RuleContext;
223
239
  /** This function starts each rule on the repository at `options.root`, and gives the result of each rule. */
224
240
  export declare function runChecks(options: CheckOptions): CheckResult;
241
+ /** The result of `runFix`. */
242
+ interface FixResult {
243
+ /** The files that the edits changed, relative to the root, with `/`, in the order of the first change. */
244
+ readonly changed: readonly string[];
245
+ /** The number of checks. */
246
+ readonly passes: number;
247
+ /** The result of the last check, after the edits. */
248
+ readonly result: CheckResult;
249
+ }
250
+ /**
251
+ * This function writes the edits of the breaks, and checks again, until no edit applies. In each pass it writes the first
252
+ * edit of each file whose `before` is the current text of the file. The other edits of that file wait for the next check,
253
+ * which gives them again from the new text. Thus a fix does not write over a change that it did not see.
254
+ */
255
+ export declare function runFix(options: CheckOptions): FixResult;
225
256
  /** This function gives the text of a result for a terminal or a CI log. */
226
257
  export declare function formatResult(result: CheckResult): string;
227
258
  /** This function gives the result as Markdown for the summary of a GitHub Actions run. */
@@ -265,5 +296,5 @@ export declare function workspaceGlobs(root: string): string[] | undefined;
265
296
  * The result has absolute paths, in the order of the code units.
266
297
  */
267
298
  export declare function packageFolders(root: string, globs?: readonly string[] | undefined): string[];
268
- export type { AuditSource, Break, CheckOptions, CheckResult, CliIo, ConventionsConfig, Manifest, OptionSpec, OptionValue, Options, PackageInfo, Rule, RuleConfig, RuleContext, RuleOutcome, RuleResult };
299
+ export type { AuditSource, Break, CheckOptions, CheckResult, CliIo, ConventionsConfig, Edit, FixResult, Manifest, OptionSpec, OptionValue, Options, PackageInfo, Rule, RuleConfig, RuleContext, RuleOutcome, RuleResult };
269
300
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","names":[],"sources":["../src/rule.ts","../src/config.ts","../src/rules/cue-preset.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/workspace-protocol.ts","../src/rules/index.ts","../src/run.ts","../src/workspace.ts"],"mappings":";UASiB;WACN;WACA;WACA;;;UAIM;;WAEN;;WAEA;WACA;;WAEA;;;KAIC;;KAGA,UAAU,SAAS,eAAe;;UAG7B;WACN;WACA,SAAS;WACT;;;KAIC,WAAW,SAAS;;UAGf;;WAEN;;WAEA;;WAEA;;WAEA;WACA,UAAU;;;UAIJ;;WAEN;;WAEA,aAAa;;WAEb,mBAAmB;;WAEnB,KAAK,SAAS;;WAEd;;EAET;;EAEA,IAAI;;;KAIM,uBAAuB;WAAqB;;;UAGvC;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA,kBAAkB;;WAElB,SAAS,SAAS,eAAe;EAC1C,MAAM,SAAS,aAAa,SAAS,UAAU;;;qBAIpC;;wBAGG,aAAa,UAAU,UAAU;;wBAOjC,OAAO,cAAc,gBAAgB;;wBAOrC,QAAQ,cAAc,eAAe;;qBAMxC,WAAY,gBAAgB;;qBAG5B,YAAa;;wBAGV,WAAW,cAAc;;;;;;wBASzB,WAAW;;wBA2BX,UAAU;;wBAUV,OAAO,cAAc;;qBAOxB,UAAW,aAAa;;;;;wBAMrB,aAAa,SAAS,KAAK,oDAAoD;;UC9K9E;;WAEN;;WAEA;;WAEA;;WAEA,SAAS;;;UAIH;;WAEN;;WAEA,OAAO,SAAS,eAAe;;;wBAW1B,eAAe,MAAM,OAAO;;;;;;;wBAU5B,YAAY,gBAAgB,gBAAgB,SAAS;;qBCnCxD;qBA2FA,WAAW;qBC/FX,eAAe;;qBCYf;;qBAGA,wBAAwB;qBAOxB,cAAc;;wBCnBX,eAAe;;;;;wBAaf,SAAS,cAAc;qBAqB1B,eAAe;qBCEf,cAAc;qBCrBd,iBAAiB;;wBCqCd,cAAc;qBAajB,eAAe;;;;;;wBCnBZ,eAAe,oBAAoB;;wBAUnC,mBAAmB;qBAqGtB,cAAc;;wBC5JX,QAAQ;;wBAQR,aAAa;qBAKhB,YAAY;qBCVZ,eAAe;;wBCHZ,SAAS,0BAA0B;qBAKtC,cAAc;;wBC4CX,gBAAgB;;;;;wBA4BhB,UAAU,SAAS,SAAS,0BAA0B,cAAc,OAAM;qBA+C7E,YAAY;qBChGZ,cAAc;qBC9Bd,mBAAmB;;qBCYnB,gBAAgB;;UCRZ;WACN;WACA;WACA;;WAEA;WACA,iBAAiB;;WAEjB;;WAEA;;;UAIM;WACN,gBAAgB;;WAEhB;;;UAIM;;WAEN;;WAEA;;WAEA;WACA,MAAM,SAAS;;WAEf,iBAAiB;;;wBAaZ,WAAW,cAAc,iBAAgB,SAAiB;;wBAO1D,cAAc,cAAc,QAAQ,mBAAmB,UAAS,KAAK,gCAAqC;;wBAwB1G,UAAU,SAAS,eAAe;;wBA0ClC,aAAa,QAAQ;;wBA0BrB,gBAAgB,QAAQ;;wBAsBxB,YAAY,QAAQ;;wBAYpB,UAAU,QAAQ,+BAA+B,iBAAgB;;UAkBhE;WACN;WACA,KAAK,SAAS;WACd,SAAS;WACT,SAAS;;;qBAIP;;wBAwBG,OAAO,yBAAyB,IAAI;;;;;;wBCxNpC,aAAa,eAAe;;;;;wBA+C5B,YAAY,cAAc;;;;;;wBA8B1B,eAAe;;;;;;;wBAwCf,eAAe,cAAc"}
1
+ {"version":3,"file":"index.d.ts","names":[],"sources":["../src/rule.ts","../src/config.ts","../src/rules/cue-preset.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/workspace-protocol.ts","../src/rules/index.ts","../src/run.ts","../src/workspace.ts"],"mappings":";UASiB;WACN;WACA;WACA;;;UAIM;;WAEN;;WAEA;WACA;;WAEA;;WAEA,iBAAiB;;;;;;UAOX;;WAEN;;WAEA;;WAEA;;;wBAIK,YAAY,cAAc,cAAc;;KAQ5C;;KAGA,UAAU,SAAS,eAAe;;UAG7B;WACN;WACA,SAAS;WACT;;;KAIC,WAAW,SAAS;;UAGf;;WAEN;;WAEA;;WAEA;;WAEA;WACA,UAAU;;;UAIJ;;WAEN;;WAEA,aAAa;;WAEb,mBAAmB;;WAEnB,KAAK,SAAS;;WAEd;;EAET;;EAEA,IAAI;;;KAIM,uBAAuB;WAAqB;;;UAGvC;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA,kBAAkB;;WAElB,SAAS,SAAS,eAAe;EAC1C,MAAM,SAAS,aAAa,SAAS,UAAU;;;qBAIpC;;wBAGG,aAAa,UAAU,UAAU;;wBAOjC,OAAO,cAAc,gBAAgB;;wBAOrC,QAAQ,cAAc,eAAe;;qBAMxC,WAAY,gBAAgB;;qBAG5B,YAAa;;wBAGV,WAAW,cAAc;;;;;;wBASzB,WAAW;;wBA2BX,UAAU;;wBAUV,OAAO,cAAc;;qBAOxB,UAAW,aAAa;;;;;wBAMrB,aAAa,SAAS,KAAK,oDAAoD;;UCrM9E;;WAEN;;WAEA;;WAEA;;WAEA,SAAS;;;UAIH;;WAEN;;WAEA,OAAO,SAAS,eAAe;;;wBAW1B,eAAe,MAAM,OAAO;;;;;;;wBAU5B,YAAY,gBAAgB,gBAAgB,SAAS;;qBCnCxD;qBA2FA,WAAW;qBC/FX,eAAe;;qBCYf;;qBAGA,wBAAwB;qBAOxB,cAAc;;wBCnBX,eAAe;;;;;wBAaf,SAAS,cAAc;qBAqB1B,eAAe;qBCEf,cAAc;qBCrBd,iBAAiB;;wBCqCd,cAAc;qBAajB,eAAe;;;;;;wBCnBZ,eAAe,oBAAoB;;wBAUnC,mBAAmB;qBAsJtB,cAAc;;wBC7MX,QAAQ;;wBAQR,aAAa;qBAKhB,YAAY;qBCkBZ,eAAe;;wBCpBZ,SAAS,0BAA0B;qBAKtC,cAAc;;wBCiCX,gBAAgB;;;;;wBA4BhB,UAAU,SAAS,SAAS,0BAA0B,cAAc,OAAM;qBAgG7E,YAAY;qBCjJZ,cAAc;qBC9Bd,mBAAmB;;qBCYnB,gBAAgB;;UCRZ;WACN;WACA;WACA;;WAEA;WACA,iBAAiB;;WAEjB;;WAEA;;;UAIM;WACN,gBAAgB;;WAEhB;;;UAIM;;WAEN;;WAEA;;WAEA;WACA,MAAM,SAAS;;WAEf,iBAAiB;;;wBAaZ,WAAW,cAAc,iBAAgB,SAAiB;;wBAO1D,cAAc,cAAc,QAAQ,mBAAmB,UAAS,KAAK,gCAAqC;;wBAwB1G,UAAU,SAAS,eAAe;;UAoCjC;;WAEN;;WAEA;;WAEA,QAAQ;;;;;;;wBAWH,OAAO,SAAS,eAAe;;wBAuC/B,aAAa,QAAQ;;wBA0BrB,gBAAgB,QAAQ;;wBAsBxB,YAAY,QAAQ;;wBAYpB,UAAU,QAAQ,+BAA+B,iBAAgB;;UAkBhE;WACN;WACA,KAAK,SAAS;WACd,SAAS;WACT,SAAS;;;qBAIP;;wBA0BG,OAAO,yBAAyB,IAAI;;;;;;wBC5QpC,aAAa,eAAe;;;;;wBAsD5B,YAAY,cAAc;;;;;;wBA8B1B,eAAe;;;;;;;wBAwCf,eAAe,cAAc"}
package/build/index.js CHANGED
@@ -1 +1 @@
1
- export { M as DEFAULT_ALLOWED, R as DEPENDENCY_FIELDS, N as HOME_PATTERNS, u as RULES, I as STRICT_OPTIONS, t as USAGE, n as annotations, z as cleanPath, B as codePackages, p as configsOfScript, r as createContext, L as cuePreset, et as defaultOptions, i as formatResult, X as globFolders, Z as globToRegExp, V as hasFile, g as hasTests, H as inFolder, k as isGitSpecifier, A as isPinned, y as isSourcePath, U as keyLine, W as lineOf, a as listRules, G as matchesAny, F as noBuildOutput, P as noLocalPaths, Q as packageFolders, tt as parseConfig, K as parseJsonc, b as pathsOf, j as pinnedGitDeps, o as readConfig, q as readJsonc, O as releaseFiles, S as repositoryOfRemote, D as requiredScripts, T as roadmapOfLine, E as roadmapParses, s as runChecks, c as runCli, J as runGit, C as runnerBudget, w as scheduleMinute, m as scriptsOf, x as sourceMain, Y as specifiersOf, l as summaryMarkdown, v as testsRequired, _ as tsconfigTest, h as typedFiles, f as typedScripts, $ as workspaceGlobs, d as workspaceProtocol } from "./run-d-5ceKnT.js";
1
+ export { N as DEFAULT_ALLOWED, z as DEPENDENCY_FIELDS, P as HOME_PATTERNS, d as RULES, L as STRICT_OPTIONS, t as USAGE, n as annotations, B as cleanPath, V as codePackages, m as configsOfScript, r as createContext, R as cuePreset, nt as defaultOptions, i as formatResult, Q as globFolders, $ as globToRegExp, H as hasFile, v as hasTests, U as inFolder, A as isGitSpecifier, j as isPinned, b as isSourcePath, W as keyLine, G as lineOf, a as listRules, K as matchesAny, I as noBuildOutput, F as noLocalPaths, et as packageFolders, rt as parseConfig, q as parseJsonc, x as pathsOf, M as pinnedGitDeps, o as readConfig, J as readJsonc, k as releaseFiles, Y as replaceLine, C as repositoryOfRemote, O as requiredScripts, E as roadmapOfLine, D as roadmapParses, s as runChecks, c as runCli, l as runFix, X as runGit, w as runnerBudget, T as scheduleMinute, h as scriptsOf, S as sourceMain, Z as specifiersOf, u as summaryMarkdown, _ as testsRequired, y as tsconfigTest, g as typedFiles, p as typedScripts, tt as workspaceGlobs, f as workspaceProtocol } from "./run-DD72yQn7.js";