@open-tomato/rafa 0.45.0 → 0.47.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.
Files changed (144) hide show
  1. package/README.md +285 -23
  2. package/dist/PROMPT.md +18 -1
  3. package/dist/adapters/logger/settings.d.ts +132 -0
  4. package/dist/bugs/closest.d.ts +19 -0
  5. package/dist/bugs/fenced.d.ts +8 -0
  6. package/dist/bugs/places.d.ts +20 -0
  7. package/dist/bugs/record.d.ts +145 -0
  8. package/dist/bugs/title.d.ts +83 -0
  9. package/dist/bundled/agents/doc-updater.md +17 -3
  10. package/dist/bundled/agents/loop-implementer.md +14 -2
  11. package/dist/bundled/operators/skills/rafa-stretch-pit-stop/SKILL.md +10 -3
  12. package/dist/bundled/operators/skills/rafa-stretch-sweep/SKILL.md +5 -0
  13. package/dist/bundled/skills/dev-planner/SKILL.md +101 -18
  14. package/dist/cli.js +76536 -64285
  15. package/dist/config/entry.d.ts +119 -0
  16. package/dist/config/index.d.ts +41 -0
  17. package/dist/config/index.js +54 -0
  18. package/dist/config/shape.d.ts +235 -0
  19. package/dist/config/templates.d.ts +64 -0
  20. package/dist/config-registry.d.ts +136 -0
  21. package/dist/config-schema-board-project.d.ts +157 -0
  22. package/dist/config-schema-bugs.d.ts +71 -0
  23. package/dist/config-schema-checks.d.ts +114 -0
  24. package/dist/config-schema-errors.d.ts +54 -0
  25. package/dist/config-schema-features.d.ts +64 -0
  26. package/dist/config-schema-hub.d.ts +152 -0
  27. package/dist/config-schema-issues.d.ts +95 -0
  28. package/dist/config-schema-logger.d.ts +91 -0
  29. package/dist/config-schema-loop-continue.d.ts +122 -0
  30. package/dist/config-schema-loop-retries.d.ts +94 -0
  31. package/dist/config-schema-release.d.ts +306 -0
  32. package/dist/config-schema-tests.d.ts +178 -0
  33. package/dist/config-schema-triage.d.ts +142 -0
  34. package/dist/config-schema-wrap-up.d.ts +96 -0
  35. package/dist/core/command/command.d.ts +228 -0
  36. package/dist/core/command/confirm.d.ts +73 -0
  37. package/dist/core/command/index.d.ts +130 -0
  38. package/dist/core/command/lazy.d.ts +54 -0
  39. package/dist/core/command/registry-types.d.ts +96 -0
  40. package/dist/core/command/running.d.ts +96 -0
  41. package/dist/core/command/shared-flags.d.ts +40 -0
  42. package/dist/core/command/spends.d.ts +39 -0
  43. package/dist/core/command/types.d.ts +92 -0
  44. package/dist/core/command/version.d.ts +4 -0
  45. package/dist/core/config/branch-template.d.ts +20 -0
  46. package/dist/core/config/config-items.d.ts +86 -0
  47. package/dist/core/config/config-load-module.d.ts +43 -0
  48. package/dist/core/config/config-load.d.ts +78 -0
  49. package/dist/core/config/config-origins.d.ts +58 -0
  50. package/dist/core/config/config-readers.d.ts +167 -0
  51. package/dist/core/config/config-schema.d.ts +212 -0
  52. package/dist/core/config/config-sections.d.ts +493 -0
  53. package/dist/core/config/config.d.ts +385 -0
  54. package/dist/core/config/core-section.d.ts +39 -0
  55. package/dist/core/config/dangerous.d.ts +58 -0
  56. package/dist/core/config/default-routing.d.ts +16 -0
  57. package/dist/core/config/index.d.ts +145 -0
  58. package/dist/core/config/merge-method.d.ts +40 -0
  59. package/dist/core/config/scope.d.ts +42 -0
  60. package/dist/core/config/section.d.ts +286 -0
  61. package/dist/core/config/sections.d.ts +53 -0
  62. package/dist/core/config/standard-schema.d.ts +27 -0
  63. package/dist/core/git/commit.d.ts +232 -0
  64. package/dist/core/git/gh-runner.d.ts +24 -0
  65. package/dist/core/git/git.d.ts +22 -0
  66. package/dist/core/git/index.d.ts +85 -0
  67. package/dist/core/loop/claude.d.ts +388 -0
  68. package/dist/core/loop/hop-record.d.ts +52 -0
  69. package/dist/core/loop/index.d.ts +179 -0
  70. package/dist/core/loop/session-env.d.ts +20 -0
  71. package/dist/core/loop/session-record-parse.d.ts +70 -0
  72. package/dist/core/loop/sessions.d.ts +420 -0
  73. package/dist/core/loop/suite-failure.d.ts +25 -0
  74. package/dist/core/output/active.d.ts +100 -0
  75. package/dist/core/output/stream.d.ts +20 -0
  76. package/dist/core/output/text.d.ts +55 -0
  77. package/dist/core/plan/block-reader.d.ts +46 -0
  78. package/dist/core/plan/blocks.d.ts +139 -0
  79. package/dist/core/plan/declaration.d.ts +366 -0
  80. package/dist/core/plan/plan-stamp.d.ts +75 -0
  81. package/dist/core/runtime/identity.d.ts +21 -0
  82. package/dist/core/runtime/index.d.ts +46 -0
  83. package/dist/effort/store/bring-forward.d.ts +131 -0
  84. package/dist/effort/store/check-rows.d.ts +31 -0
  85. package/dist/effort/store/commit-stats.d.ts +42 -0
  86. package/dist/effort/store/copy.d.ts +35 -0
  87. package/dist/effort/store/development-build.d.ts +105 -0
  88. package/dist/effort/store/effort-levels.d.ts +13 -0
  89. package/dist/effort/store/findings.d.ts +214 -0
  90. package/dist/effort/store/fix-schema.d.ts +184 -0
  91. package/dist/effort/store/index.js +10 -7
  92. package/dist/effort/store/location.d.ts +44 -0
  93. package/dist/effort/store/merge-commit-gaps.d.ts +68 -0
  94. package/dist/effort/store/merge-conflicts.d.ts +91 -0
  95. package/dist/effort/store/merge-rules.d.ts +82 -0
  96. package/dist/effort/store/merge-store.d.ts +211 -0
  97. package/dist/effort/store/merge-union.d.ts +92 -0
  98. package/dist/effort/store/migrate.d.ts +146 -0
  99. package/dist/effort/store/migrations.d.ts +92 -0
  100. package/dist/effort/store/ndjson-files.d.ts +114 -0
  101. package/dist/effort/store/origins.d.ts +116 -0
  102. package/dist/effort/store/plan-stubs.d.ts +79 -0
  103. package/dist/effort/store/rebuild-aside.d.ts +172 -0
  104. package/dist/effort/store/schema-plan.d.ts +102 -0
  105. package/dist/effort/store/session-row-types.d.ts +64 -0
  106. package/dist/effort/store/settings.d.ts +13 -0
  107. package/dist/effort/store/sqlite.d.ts +340 -0
  108. package/dist/effort/store/store-generation.d.ts +17 -0
  109. package/dist/effort/store/store-identity.d.ts +220 -0
  110. package/dist/effort/store/store-meta.d.ts +305 -0
  111. package/dist/effort/store/store-replaced.d.ts +72 -0
  112. package/dist/effort/store/types.d.ts +223 -0
  113. package/dist/errors/codes.d.ts +56 -0
  114. package/dist/errors/rafa-codes.d.ts +36 -0
  115. package/dist/{index-nv34ptht.js → index-38ktnyvz.js} +14 -9
  116. package/dist/index-3mwsr6wg.js +1070 -0
  117. package/dist/index-7dgc5g1t.js +13480 -0
  118. package/dist/index-cbqvgda6.js +766 -0
  119. package/dist/index-eay1bd2w.js +2632 -0
  120. package/dist/index-f1y86zbb.js +125 -0
  121. package/dist/index-n3e31fmw.js +1041 -0
  122. package/dist/{index-r28fzsvc.js → index-nwzx41g1.js} +351 -166
  123. package/dist/index-pzpb1rf7.js +153 -0
  124. package/dist/{index-mgh2s9bj.js → index-r5q2pdky.js} +65 -457
  125. package/dist/index-z1w83f81.js +4 -0
  126. package/dist/index.js +17592 -24119
  127. package/dist/learning/index.js +5 -6
  128. package/dist/plan/index.js +12 -11
  129. package/dist/plan-prompt.md +3 -1
  130. package/dist/ports/index.d.ts +732 -0
  131. package/dist/ports/learning.d.ts +101 -0
  132. package/dist/ports/log-level.d.ts +13 -0
  133. package/dist/ports/spec-review.d.ts +66 -0
  134. package/dist/ready-6p40c3gw.js +2007 -0
  135. package/dist/release-templates/release-bot-fragment.yml +153 -0
  136. package/dist/release-templates/release-publish.yml +110 -0
  137. package/dist/release-templates/release-settle.yml +122 -0
  138. package/dist/release-templates/release-tag.yml +102 -0
  139. package/dist/report/parse.d.ts +415 -0
  140. package/dist/schema/project-id.d.ts +79 -0
  141. package/dist/schema/tiers.d.ts +107 -0
  142. package/package.json +62 -3
  143. package/dist/index-hf2k497d.js +0 -16
  144. package/dist/index-nsr78ct2.js +0 -8219
@@ -0,0 +1,157 @@
1
+ /**
2
+ * The five limits of the `board.project` section: how a call to the
3
+ * GitHub project is retried, how often a long refresh says where it is,
4
+ * and how its field writes are batched and spaced. Each has its field,
5
+ * its default, its reader and its spec here.
6
+ * {@link BOARD_PROJECT_SECTION} hands them to core as one
7
+ * `ConfigSection`, package `board-project`, and the `declare module`
8
+ * below adds {@link BoardProjectLimitSettings} to `RafaConfig`.
9
+ * {@link BoardProjectLimitsShape} holds its part of the shared
10
+ * `board.project` namespace, which `src/config/shape.ts` composes into
11
+ * `BoardProjectShape` of `ConfigShape`, the nested file shape.
12
+ * `config-registry.ts`'s `CONFIG_DEFAULTS` and `SETTINGS`
13
+ * spread the objects below right after `board.project.number`, so the
14
+ * order settings are reported in holds the `board.project` section
15
+ * together.
16
+ *
17
+ * `board.project.template` and `board.project.number` are core's, in
18
+ * `core/config/core-section.ts`; `config-schema-readings.ts` argues
19
+ * them. These five have their own module, as the `loop.wrapUp`
20
+ * key does, because `config-schema.ts` stood at 617 lines and
21
+ * `config-sections.ts` at 744, measured with `wc -l`, when they were
22
+ * added: five more specs and five readers would have put the readers'
23
+ * module within a page of the 800-line cap of `context/source.md`.
24
+ * `config-registry.ts` imports this file to spread it; a caller reads each
25
+ * setting off the resolved `RafaConfig`.
26
+ *
27
+ * ## The keys
28
+ *
29
+ * Issues #922, #923 and #900 found a refresh reading one page of a list,
30
+ * failing on the first network error and printing nothing while it ran.
31
+ * The fix reads every limit off the config, never a constant:
32
+ *
33
+ * | Key | Counts | Default | Accepts |
34
+ * |---|---|---|---|
35
+ * | `retries` | tries after a failure, per call | 3 | 1 to 10, or `false` |
36
+ * | `retryWaitSeconds` | the first wait; each later one doubles | 2 | 1 to 60 |
37
+ * | `progressSeconds` | the most time between two progress lines | 10 | 1 to 300, or `false` |
38
+ * | `writeBatchSize` | field writes per request | 20 | 1 to 100 |
39
+ * | `writePauseMs` | the pause between two write requests | 1000 | 0 to 60000 |
40
+ *
41
+ * ## The readings
42
+ *
43
+ * Four readings the plan leaves to this module:
44
+ *
45
+ * - `false` is the one spelling of "off", and only two keys take it.
46
+ * `retries: false` makes a failed call fail at once, as before the
47
+ * key existed; `progressSeconds: false` drops the lines between the
48
+ * start line and the end line, which stay. A wait, a batch and a
49
+ * pause have no "off" that means anything: a batch of none writes
50
+ * nothing, and a refresh with no waits is `retries: false`.
51
+ * - `0` and a negative number are refused on every key but
52
+ * `writePauseMs`, and never read as off. A number always names a
53
+ * count or a time that happens, as `loop.wrapUp.retries` has it, so
54
+ * a person who wrote `0` meaning "never" learns to write `false`.
55
+ * `writePauseMs: 0` is a pause of no time, a number that still
56
+ * happens, and is accepted: it is what a test or a project with a
57
+ * generous rate limit writes.
58
+ * - Each cap is the plan's, and bounds what one refresh can cost: ten
59
+ * retries, the first wait at most a minute, a progress line at least
60
+ * every five minutes, a hundred field writes to a request and a
61
+ * pause of at most a minute. A cap is a config change away from
62
+ * moving; none was measured against a GitHub limit.
63
+ * - `true`, a fraction and a quoted number are refused, as every
64
+ * reader in `config-sections.ts` refuses them: `true` names no
65
+ * count, and reading it as the default would be a choice nobody
66
+ * wrote.
67
+ *
68
+ * None is a `CommandLineSetting`, for the reason `board.project.number`
69
+ * gives in `config-schema-readings.ts`: every command that refreshes the
70
+ * project must write it the same way, which one run's flag would split.
71
+ */
72
+ import type { ConfigSection, SettingSpec } from '@open-tomato/rafa/core/config';
73
+ import type { Reader } from '@open-tomato/rafa/core/config/sections';
74
+ declare module '@open-tomato/rafa/core/config/config-schema' {
75
+ /** The `board-project` section's fields, added to core's. */
76
+ interface RafaConfig extends BoardProjectLimitSettings {
77
+ }
78
+ }
79
+ /**
80
+ * The `board.project` limits a file writes, the section's part of the
81
+ * shared `board.project` namespace; `src/config/shape.ts` composes it
82
+ * into `BoardProjectShape` beside core's two keys.
83
+ */
84
+ export interface BoardProjectLimitsShape {
85
+ readonly retries: BoardProjectRetries;
86
+ readonly retryWaitSeconds: number;
87
+ readonly progressSeconds: BoardProjectProgressSeconds;
88
+ readonly writeBatchSize: number;
89
+ readonly writePauseMs: number;
90
+ }
91
+ /** The fewest tries after a failure `board.project.retries` accepts as a number. */
92
+ export declare const BOARD_PROJECT_RETRIES_MIN = 1;
93
+ /** The most tries after a failure `board.project.retries` accepts. */
94
+ export declare const BOARD_PROJECT_RETRIES_MAX = 10;
95
+ /** The shortest first wait `board.project.retryWaitSeconds` accepts. */
96
+ export declare const BOARD_PROJECT_RETRY_WAIT_MIN_SECONDS = 1;
97
+ /** The longest first wait `board.project.retryWaitSeconds` accepts. */
98
+ export declare const BOARD_PROJECT_RETRY_WAIT_MAX_SECONDS = 60;
99
+ /** The shortest gap between progress lines `board.project.progressSeconds` accepts. */
100
+ export declare const BOARD_PROJECT_PROGRESS_MIN_SECONDS = 1;
101
+ /** The longest gap between progress lines `board.project.progressSeconds` accepts. */
102
+ export declare const BOARD_PROJECT_PROGRESS_MAX_SECONDS = 300;
103
+ /** The fewest field writes per request `board.project.writeBatchSize` accepts. */
104
+ export declare const BOARD_PROJECT_WRITE_BATCH_MIN = 1;
105
+ /** The most field writes per request `board.project.writeBatchSize` accepts. */
106
+ export declare const BOARD_PROJECT_WRITE_BATCH_MAX = 100;
107
+ /** The shortest pause between write requests `board.project.writePauseMs` accepts. */
108
+ export declare const BOARD_PROJECT_WRITE_PAUSE_MIN_MS = 0;
109
+ /** The longest pause between write requests `board.project.writePauseMs` accepts. */
110
+ export declare const BOARD_PROJECT_WRITE_PAUSE_MAX_MS = 60000;
111
+ /** How many times a failed project call is tried again, or `false` for never. */
112
+ export type BoardProjectRetries = number | false;
113
+ /** The most seconds between two progress lines, or `false` for no lines between start and end. */
114
+ export type BoardProjectProgressSeconds = number | false;
115
+ /** The `board.project` section's limits, resolved. */
116
+ export interface BoardProjectLimitSettings {
117
+ /**
118
+ * The tries after a failure, per call, or `false` for none.
119
+ * `board.project.retries`.
120
+ */
121
+ boardProjectRetries: BoardProjectRetries;
122
+ /**
123
+ * The first wait before a retry, in seconds; each later one doubles.
124
+ * `board.project.retryWaitSeconds`.
125
+ */
126
+ boardProjectRetryWaitSeconds: number;
127
+ /**
128
+ * The most seconds between two progress lines, or `false` for none
129
+ * between the start and end lines. `board.project.progressSeconds`.
130
+ */
131
+ boardProjectProgressSeconds: BoardProjectProgressSeconds;
132
+ /** The field writes sent in one request. `board.project.writeBatchSize`. */
133
+ boardProjectWriteBatchSize: number;
134
+ /**
135
+ * The pause between two write requests, in milliseconds.
136
+ * `board.project.writePauseMs`.
137
+ */
138
+ boardProjectWritePauseMs: number;
139
+ }
140
+ /** Accepts `board.project.retries`; the module note says why `0` and `true` are refused. */
141
+ export declare const boardProjectRetries: Reader<BoardProjectRetries>;
142
+ /** Accepts `board.project.retryWaitSeconds`, with no `false`. */
143
+ export declare const boardProjectRetryWaitSeconds: Reader<number>;
144
+ /** Accepts `board.project.progressSeconds`; `false` keeps only the start and end lines. */
145
+ export declare const boardProjectProgressSeconds: Reader<BoardProjectProgressSeconds>;
146
+ /** Accepts `board.project.writeBatchSize`, with no `false`. */
147
+ export declare const boardProjectWriteBatchSize: Reader<number>;
148
+ /** Accepts `board.project.writePauseMs`, `0` among them, with no `false`. */
149
+ export declare const boardProjectWritePauseMs: Reader<number>;
150
+ /** What the `board.project` limits resolve to when no layer names them. */
151
+ export declare const BOARD_PROJECT_LIMIT_DEFAULTS: Readonly<BoardProjectLimitSettings>;
152
+ /** The `board.project` limits' setting specs. */
153
+ export declare const BOARD_PROJECT_LIMIT_SETTINGS: {
154
+ readonly [K in keyof BoardProjectLimitSettings]: SettingSpec<K>;
155
+ };
156
+ /** The `board-project` section: the five `board.project` limits, with their defaults and no check. */
157
+ export declare const BOARD_PROJECT_SECTION: ConfigSection;
@@ -0,0 +1,71 @@
1
+ /**
2
+ * The `bugs` section of the config schema: `bugs.recheck.runs` and
3
+ * `bugs.recheck.timeoutSeconds`, the two numbers `rafa bug recheck`
4
+ * (#953) reads. {@link BUGS_SECTION} hands them to core as one
5
+ * `ConfigSection`, package `bugs`, and the `declare module` below adds
6
+ * {@link BugsSettings} to `RafaConfig`. {@link BugsShape} holds the keys
7
+ * a file writes, which `src/config/shape.ts` composes into
8
+ * `ConfigShape`, the nested file shape. `config-registry.ts` lists the
9
+ * section right after the `errors` section, and its `CONFIG_DEFAULTS`
10
+ * and `SETTINGS` spread the objects below right after the `errors` ones.
11
+ *
12
+ * ## The keys
13
+ *
14
+ * - `bugs.recheck.runs` is how many FURTHER runs recheck makes after a
15
+ * first run that passed, to tell a bug that is gone from a flaky one:
16
+ * a whole number from 1 to 20, default 5. A first run that failed or
17
+ * judged nothing ends the bug's runs, so this count is never spent on
18
+ * it.
19
+ * - `bugs.recheck.timeoutSeconds` is the deadline of one run, in
20
+ * seconds: a whole number from 1 to 3600, default 300. A run that
21
+ * passes it is a failed run.
22
+ *
23
+ * Each reader refuses `0`, a negative number, a fraction, a quoted
24
+ * number, `true` and `false` and a value above its cap, naming the
25
+ * range: neither key has an "off" spelling, since recheck with no
26
+ * further run, or with no deadline, is a recheck nobody asked for.
27
+ * Neither key is a `CommandLineSetting`.
28
+ */
29
+ import type { ConfigSection, SettingSpec } from './core/config/index.js';
30
+ import type { Reader } from './core/config/sections.js';
31
+ declare module './core/config/config-schema.js' {
32
+ /** The `bugs` section's fields, added to core's. */
33
+ interface RafaConfig extends BugsSettings {
34
+ }
35
+ }
36
+ /** The `bugs` keys a file writes; `src/config/shape.ts` composes them into `ConfigShape`. */
37
+ export interface BugsShape {
38
+ readonly bugs: {
39
+ readonly recheck: {
40
+ readonly runs: number;
41
+ readonly timeoutSeconds: number;
42
+ };
43
+ };
44
+ }
45
+ /** The `bugs` settings, resolved. */
46
+ export interface BugsSettings {
47
+ /** `bugs.recheck.runs`: the further runs after a first pass. */
48
+ bugsRecheckRuns: number;
49
+ /** `bugs.recheck.timeoutSeconds`: one run's deadline, in seconds. */
50
+ bugsRecheckTimeoutSeconds: number;
51
+ }
52
+ /** The fewest further runs `bugs.recheck.runs` accepts. */
53
+ export declare const BUGS_RECHECK_RUNS_MIN = 1;
54
+ /** The most further runs `bugs.recheck.runs` accepts. */
55
+ export declare const BUGS_RECHECK_RUNS_MAX = 20;
56
+ /** The shortest deadline `bugs.recheck.timeoutSeconds` accepts. */
57
+ export declare const BUGS_RECHECK_TIMEOUT_MIN = 1;
58
+ /** The longest deadline `bugs.recheck.timeoutSeconds` accepts: an hour. */
59
+ export declare const BUGS_RECHECK_TIMEOUT_MAX = 3600;
60
+ /** Reads `bugs.recheck.runs`. */
61
+ export declare const bugsRecheckRuns: Reader<number>;
62
+ /** Reads `bugs.recheck.timeoutSeconds`. */
63
+ export declare const bugsRecheckTimeoutSeconds: Reader<number>;
64
+ /** What the `bugs` settings resolve to when no layer names them. */
65
+ export declare const BUGS_DEFAULTS: Readonly<BugsSettings>;
66
+ /** Every `bugs` setting. */
67
+ export declare const BUGS_SETTINGS: {
68
+ readonly [K in keyof BugsSettings]: SettingSpec<K>;
69
+ };
70
+ /** The `bugs` section: `bugs.recheck.runs` and `bugs.recheck.timeoutSeconds`, with their defaults and no check. */
71
+ export declare const BUGS_SECTION: ConfigSection;
@@ -0,0 +1,114 @@
1
+ /**
2
+ * The `checks` section of the config schema: the check-point table, one
3
+ * setting per point of the work at which the runner checks it, each one's
4
+ * field, its default, its spec and its reader. {@link CHECKS_SECTION}
5
+ * hands them to core as one `ConfigSection`, package `checks`, and the
6
+ * `declare module` below adds {@link ChecksSettings} to `RafaConfig`.
7
+ * {@link ChecksShape} holds the keys a file writes, which
8
+ * `src/config/shape.ts` composes into `ConfigShape`, the nested file
9
+ * shape. `config-registry.ts` registers the section after the `tests`
10
+ * section in `CONFIG_SECTIONS`, and its `CONFIG_DEFAULTS` and `SETTINGS`
11
+ * spread the objects below right after the `tests` section's.
12
+ *
13
+ * ## The keys
14
+ *
15
+ * Seven check points, each a list of check names, spelled as the plan
16
+ * `rafa-908-spec-person-sets-checks` names them:
17
+ *
18
+ * - `checks.task`: what a task step runs.
19
+ * - `checks.stage`: what a stage step runs.
20
+ * - `checks.loop`: what the loop runs before its wrap-up.
21
+ * - `checks.pullRequest`: what a pull request's CI runs.
22
+ * - `checks.stretch`: what a stretch of work runs.
23
+ * - `checks.releasePullRequest`: what a release pull request's CI runs.
24
+ * - `checks.publish`: what a publish runs.
25
+ *
26
+ * Each resolves as `checks` and its key's name capitalised:
27
+ * `checksTask`, `checksPullRequest` and the like. The runner's task step
28
+ * reads `checksTask` (`start/suite-task-step.ts`) and its stage step
29
+ * `checksStage` (`start/suite-stage-step.ts`); no step reads the others
30
+ * yet.
31
+ *
32
+ * ## The vocabulary
33
+ *
34
+ * A check name is one of six, {@link CHECK_NAMES}: `affected`,
35
+ * `related`, `unit`, `contract`, `integration` and `full`. The set is
36
+ * closed, and no entry holds a shell command: what each name runs is the
37
+ * resolver's, which imports {@link CHECK_NAMES} from here. {@link checkList}
38
+ * reads a list of them, and refuses a value that is not a list, an entry
39
+ * outside the six, and a name written twice, each naming the key and the
40
+ * six, since a point that runs one check twice says nothing a single
41
+ * mention does not.
42
+ *
43
+ * ## The default
44
+ *
45
+ * Every key defaults to an empty list, and an empty list means what it
46
+ * says: the point runs no check. The values a project adopts come from
47
+ * a template or from its own file, not from this module.
48
+ *
49
+ * No key here is a `CommandLineSetting`: each is a list, which the
50
+ * command line has no spelling for, as `config-schema.ts` says.
51
+ */
52
+ import type { ConfigSection, SettingSpec } from '@open-tomato/rafa/core/config';
53
+ import type { Reader } from '@open-tomato/rafa/core/config/sections';
54
+ declare module '@open-tomato/rafa/core/config/config-schema' {
55
+ /** The `checks` section's fields, added to core's. */
56
+ interface RafaConfig extends ChecksSettings {
57
+ }
58
+ }
59
+ /** The six check names a check-point entry may hold, in the order a refusal lists them. */
60
+ export declare const CHECK_NAMES: readonly ['affected', 'related', 'unit', 'contract', 'integration', 'full'];
61
+ /** One check name: one of {@link CHECK_NAMES}. */
62
+ export type CheckName = (typeof CHECK_NAMES)[number];
63
+ /** The `checks` keys a file writes; `src/config/shape.ts` composes them into `ConfigShape`. */
64
+ export interface ChecksShape {
65
+ /** The `checks` keys, each a list of check names. */
66
+ readonly checks: {
67
+ /** `checks.task`: the checks a task step runs. */
68
+ readonly task: readonly CheckName[];
69
+ /** `checks.stage`: the checks a stage step runs. */
70
+ readonly stage: readonly CheckName[];
71
+ /** `checks.loop`: the checks the loop runs before its wrap-up. */
72
+ readonly loop: readonly CheckName[];
73
+ /** `checks.pullRequest`: the checks a pull request's CI runs. */
74
+ readonly pullRequest: readonly CheckName[];
75
+ /** `checks.stretch`: the checks a stretch of work runs. */
76
+ readonly stretch: readonly CheckName[];
77
+ /** `checks.releasePullRequest`: the checks a release pull request's CI runs. */
78
+ readonly releasePullRequest: readonly CheckName[];
79
+ /** `checks.publish`: the checks a publish runs. */
80
+ readonly publish: readonly CheckName[];
81
+ };
82
+ }
83
+ /** The `checks` section's settings, resolved. */
84
+ export interface ChecksSettings {
85
+ /** The checks a task step runs. `checks.task`. */
86
+ checksTask: readonly CheckName[];
87
+ /** The checks a stage step runs. `checks.stage`. */
88
+ checksStage: readonly CheckName[];
89
+ /** The checks the loop runs before its wrap-up. `checks.loop`. */
90
+ checksLoop: readonly CheckName[];
91
+ /** The checks a pull request's CI runs. `checks.pullRequest`. */
92
+ checksPullRequest: readonly CheckName[];
93
+ /** The checks a stretch of work runs. `checks.stretch`. */
94
+ checksStretch: readonly CheckName[];
95
+ /** The checks a release pull request's CI runs. `checks.releasePullRequest`. */
96
+ checksReleasePullRequest: readonly CheckName[];
97
+ /** The checks a publish runs. `checks.publish`. */
98
+ checksPublish: readonly CheckName[];
99
+ }
100
+ /**
101
+ * The reader every `checks` setting shares: a list of check names, each
102
+ * one of {@link CHECK_NAMES} and none written twice, answered frozen in
103
+ * the order written. A refusal opens with the key's label and lists the
104
+ * six.
105
+ */
106
+ export declare const checkList: Reader<readonly CheckName[]>;
107
+ /** What every `checks` setting resolves to when no layer names it: no check at any point. */
108
+ export declare const CHECKS_DEFAULTS: Readonly<ChecksSettings>;
109
+ /** The `checks` section's setting specs, in the order problems are reported. */
110
+ export declare const CHECKS_SETTINGS: {
111
+ readonly [K in keyof ChecksSettings]: SettingSpec<K>;
112
+ };
113
+ /** The `checks` section: the seven check points, with their defaults and no check. */
114
+ export declare const CHECKS_SECTION: ConfigSection;
@@ -0,0 +1,54 @@
1
+ /**
2
+ * The `errors` section of the config schema: `errors.codes`, the cause
3
+ * codes a project adds to rafa's list (#949). {@link ERRORS_SECTION}
4
+ * hands it to core as one `ConfigSection`, package `errors`, and the
5
+ * `declare module` below adds {@link ErrorsSettings} to `RafaConfig`.
6
+ * {@link ErrorsShape} holds the keys a file writes, which
7
+ * `src/config/shape.ts` composes into `ConfigShape`, the nested file shape.
8
+ * `config-registry.ts`'s `CONFIG_DEFAULTS` and `SETTINGS`
9
+ * spread the objects below right after the `release` section. It has its
10
+ * own module because `config-schema.ts` stood at 643 lines and
11
+ * `config-sections.ts` at 744 when it was added.
12
+ *
13
+ * Each entry is read with the same rules `defineErrorCodes`
14
+ * (`packages/rafa/src/errors/codes.ts`) applies to rafa's list, except
15
+ * that `since` may be left out: a project often has no version to name.
16
+ * Then the list as a
17
+ * whole is checked: a code given twice, or one rafa already declares, is
18
+ * refused with both places named, so neither meaning wins silently. An
19
+ * unknown key inside an entry is kept and warned about, as every other
20
+ * list of mappings does.
21
+ */
22
+ import type { ConfigSection, SettingSpec } from './core/config/index.js';
23
+ import type { ErrorCodeEntry } from './errors/codes.js';
24
+ declare module './core/config/config-schema.js' {
25
+ /** The `errors` section's fields, added to core's. */
26
+ interface RafaConfig extends ErrorsSettings {
27
+ }
28
+ }
29
+ /** The `errors` keys a file writes; `src/config/shape.ts` composes them into `ConfigShape`. */
30
+ export interface ErrorsShape {
31
+ readonly errors: {
32
+ readonly codes: readonly ErrorCodeFileItem[];
33
+ };
34
+ }
35
+ /** One `errors.codes` entry as a file writes it, `since` left out or null. */
36
+ type ErrorCodeFileItem = Pick<ErrorCodeEntry, 'code' | 'description' | 'hint' | 'level'> & {
37
+ readonly since?: string | null;
38
+ };
39
+ /** The `errors` settings. */
40
+ export interface ErrorsSettings {
41
+ /** `errors.codes`: the project's own cause codes. */
42
+ errorsCodes: readonly ErrorCodeEntry[];
43
+ }
44
+ /** The keys one entry reads. */
45
+ export declare const ERROR_CODE_KEYS: readonly ["code", "description", "hint", "level", "since"];
46
+ /** No project codes. */
47
+ export declare const ERRORS_DEFAULTS: Readonly<ErrorsSettings>;
48
+ /** Every `errors` setting. */
49
+ export declare const ERRORS_SETTINGS: {
50
+ readonly [K in keyof ErrorsSettings]: SettingSpec<K>;
51
+ };
52
+ /** The `errors` section: `errors.codes`, with their defaults and no check. */
53
+ export declare const ERRORS_SECTION: ConfigSection;
54
+ export {};
@@ -0,0 +1,64 @@
1
+ /**
2
+ * The `features` section of the config schema: four switches, one per
3
+ * bundled feature, each saying whether that feature's commands are
4
+ * loaded for the invocation. {@link FEATURES_SECTION} hands them to core
5
+ * as one `ConfigSection`, package `features`, and the `declare module`
6
+ * below adds {@link FeaturesSettings} to `RafaConfig`.
7
+ * {@link FeaturesShape} holds the keys a file writes, which
8
+ * `src/config/shape.ts` composes into `ConfigShape`, the nested file
9
+ * shape. `config-registry.ts` registers the section fourteenth in
10
+ * `CONFIG_SECTIONS`, and its `CONFIG_DEFAULTS` and `SETTINGS` spread the
11
+ * objects below last, after the `checks` section.
12
+ *
13
+ * ## The keys
14
+ *
15
+ * `features.board`, `features.pr`, `features.run` and `features.release`
16
+ * each name one bundled feature by its name. Each is read with core's
17
+ * `flag`, so it takes `true` or `false` and refuses anything else, a
18
+ * quoted `"false"` included, naming the key. Each defaults to `true`: a
19
+ * project that names no feature loads every bundled one, as it did
20
+ * before the section existed. None is a `CommandLineSetting`.
21
+ *
22
+ * The section holds the switches and nothing that reads them: what a
23
+ * `false` turns off is the loader's (`packages/rafa/src/modules/load.ts`), which reads
24
+ * these settings off the resolved `RafaConfig`.
25
+ */
26
+ import type { ConfigSection, SettingSpec } from './core/config/index.js';
27
+ declare module './core/config/config-schema.js' {
28
+ /** The `features` section's fields, added to core's. */
29
+ interface RafaConfig extends FeaturesSettings {
30
+ }
31
+ }
32
+ /** The `features` keys as a file writes them. */
33
+ export interface FeaturesShape {
34
+ /** The `features` keys, each `true` or `false`. */
35
+ readonly features: {
36
+ /** `features.board`: whether the board feature's commands load. */
37
+ readonly board: boolean;
38
+ /** `features.pr`: whether the pull-request feature's commands load. */
39
+ readonly pr: boolean;
40
+ /** `features.run`: whether the run feature's commands load. */
41
+ readonly run: boolean;
42
+ /** `features.release`: whether the release feature's commands load. */
43
+ readonly release: boolean;
44
+ };
45
+ }
46
+ /** The `features` section's settings, resolved. */
47
+ export interface FeaturesSettings {
48
+ /** Whether the board feature's commands load. `features.board`. */
49
+ featuresBoard: boolean;
50
+ /** Whether the pull-request feature's commands load. `features.pr`. */
51
+ featuresPr: boolean;
52
+ /** Whether the run feature's commands load. `features.run`. */
53
+ featuresRun: boolean;
54
+ /** Whether the release feature's commands load. `features.release`. */
55
+ featuresRelease: boolean;
56
+ }
57
+ /** What the `features` settings resolve to when no layer names them: every feature on. */
58
+ export declare const FEATURES_DEFAULTS: Readonly<FeaturesSettings>;
59
+ /** The `features` section's setting specs, in the order they are reported. */
60
+ export declare const FEATURES_SETTINGS: {
61
+ readonly [K in keyof FeaturesSettings]: SettingSpec<K>;
62
+ };
63
+ /** The `features` section: the four switches, with their defaults and no check. */
64
+ export declare const FEATURES_SECTION: ConfigSection;
@@ -0,0 +1,152 @@
1
+ /**
2
+ * The `hub` section of the config schema: the three keys a device reads
3
+ * to reach a `rafa-hub` under `effort.sync: service`, each with its
4
+ * field, its default, its spec and its reader, the one refusal that
5
+ * reads two settings at once, and the {@link HubContext} an adapter is
6
+ * handed. {@link HUB_SECTION} hands them to core as one `ConfigSection`,
7
+ * package `hub`, with {@link hubUrlProblems} as its check, and the
8
+ * `declare module` below adds {@link HubSettings} to `RafaConfig`.
9
+ * {@link HubShape} holds the keys a file writes, which
10
+ * `src/config/shape.ts` composes into `ConfigShape`, the nested file shape.
11
+ * `config-registry.ts`'s `CONFIG_DEFAULTS` and `SETTINGS`
12
+ * spread {@link HUB_DEFAULTS} and {@link HUB_SETTINGS} right after
13
+ * `effort.sync`, the setting they serve, as `config-schema-release.ts`'s
14
+ * sections are spread.
15
+ *
16
+ * The section sits in a module of its own, readers included, for the
17
+ * reason `config-schema-release.ts` and `config-readers.ts` give: measured
18
+ * with `wc -l` when it was added, `config-schema.ts` stood at 554 lines
19
+ * and `config-sections.ts` at 699, so the value rules here would have
20
+ * pushed the second against the 800-line cap of `context/source.md`.
21
+ * Every rule `config.ts` and `section.ts` state about a KEY holds here, as every
22
+ * rule `config-sections.ts` states about a VALUE does: nothing is
23
+ * coerced, and a string spelled like a number is refused.
24
+ *
25
+ * ## The keys
26
+ *
27
+ * `.rafa/specs/rafa-325-rafa-hub.md` names them: `hub.url` (required with
28
+ * `effort.sync: service`), `hub.tokenSecret` (the secret store name of
29
+ * the token, never the token) and `hub.timeout` (default `3s`, from `1s`
30
+ * to `30s`, `0` and negative values refused). The server's keys,
31
+ * `hub.repository`, `hub.port`, `hub.storePath` and `hub.auth.cacheFor`,
32
+ * are read by `packages/rafa-hub/` from its own file and are not keys
33
+ * here: in a project's file they are unknown keys, warned about and
34
+ * acted on by nothing. Five readings the spec leaves to this module:
35
+ *
36
+ * - `hub.url` and `hub.tokenSecret` default to NULL, meaning "nobody
37
+ * has said", as `pr.base` does: no default address or secret name
38
+ * is one this module could spell for every team.
39
+ * - `hub.url` is an absolute `http:` or `https:` URL, kept as written,
40
+ * and one carrying a user name or password is refused: a token
41
+ * written into the URL is a token in the config, which the spec
42
+ * forbids, and it would reach every log line naming the hub.
43
+ * - `hub.tokenSecret` is any name holding a character other than
44
+ * whitespace. Whether the secret store holds it is the `service`
45
+ * module's question when it reads the token, not the config's.
46
+ * - `hub.timeout` is whole digits then `s`, as `claims.staleAfter` is
47
+ * whole digits then a unit: `2.5s`, `3000ms`, `3S`, ` 3s` and the
48
+ * bare number `3`, which names no unit, are refused, and so are
49
+ * `0s`, anything below `1s` and anything above `30s`. It is kept as
50
+ * written, and {@link hubTimeoutMs} answers the milliseconds it
51
+ * spells.
52
+ * - None is a `CommandLineSetting`, for the reason the `pr` section
53
+ * gives in `config-schema-release.ts`.
54
+ *
55
+ * ## The refusal across two settings
56
+ *
57
+ * A missing `hub.url` is refused only under `effort.sync: service`, and
58
+ * the two may come from different files: a user scope naming the hub
59
+ * for every project and a project choosing `service` is the layout the
60
+ * spec's README section describes. So no single file can be refused for
61
+ * it, and {@link hubUrlProblems} is the section's check: `resolveConfig`
62
+ * asks it once every setting is ranked, and it names the file that chose
63
+ * `service`, read off that setting's provenance: a scope's module file
64
+ * and its YAML file, the local layer, are each named by their own path,
65
+ * as are the user scope's two files, which both report `user`. Every other
66
+ * strategy reads no `hub` key, so a `hub.url` beside `local` is kept and
67
+ * never refused: switching strategy is then a one-line edit.
68
+ *
69
+ * ## The adapter's context
70
+ *
71
+ * {@link hubContextOf} turns the resolved settings into the
72
+ * {@link HubContext} `selectSync` hands a `sync` adapter as
73
+ * `AdapterContext.hub`, the timeout already in milliseconds. It answers
74
+ * undefined with no `hub.url`, since a hub with no address is none an
75
+ * adapter could reach; the refusal above keeps that from happening
76
+ * under `service`.
77
+ */
78
+ import type { ConfigCheckInput, ConfigSection, SettingSpec } from '@open-tomato/rafa/core/config';
79
+ import type { Reader } from '@open-tomato/rafa/core/config/sections';
80
+ declare module '@open-tomato/rafa/core/config/config-schema' {
81
+ /** The `hub` section's fields, added to core's. */
82
+ interface RafaConfig extends HubSettings {
83
+ }
84
+ }
85
+ /** The `hub` keys a file writes; `src/config/shape.ts` composes them into `ConfigShape`. */
86
+ export interface HubShape {
87
+ readonly hub: {
88
+ readonly url: string;
89
+ readonly tokenSecret: string;
90
+ readonly timeout: HubTimeout;
91
+ };
92
+ }
93
+ /** The shortest `hub.timeout` accepted, in seconds. */
94
+ export declare const HUB_TIMEOUT_MIN_SECONDS = 1;
95
+ /** The longest `hub.timeout` accepted, in seconds. */
96
+ export declare const HUB_TIMEOUT_MAX_SECONDS = 30;
97
+ /** What `hub.timeout` takes: whole seconds, spelled as written (`3s`). */
98
+ export type HubTimeout = `${number}s`;
99
+ /** The `hub` section's settings, resolved. */
100
+ export interface HubSettings {
101
+ /**
102
+ * The address of the hub a `service` sync reaches, or null when
103
+ * nobody has said. `hub.url`.
104
+ */
105
+ hubUrl: string | null;
106
+ /**
107
+ * The name the hub token is stored under in the secret store, never
108
+ * the token, or null when nobody has said. `hub.tokenSecret`.
109
+ */
110
+ hubTokenSecret: string | null;
111
+ /** How long one request to the hub may take. `hub.timeout`. */
112
+ hubTimeout: HubTimeout;
113
+ }
114
+ /** The `hub` section's defaults. */
115
+ export declare const HUB_DEFAULTS: Readonly<HubSettings>;
116
+ /**
117
+ * The milliseconds a `hub.timeout` spells (`3s` → 3000), or null for
118
+ * anything else, `0s` and a value outside the range included.
119
+ */
120
+ export declare function hubTimeoutMs(raw: unknown): number | null;
121
+ /** Accepts a hub timeout of whole seconds in range, kept as written; see the module note. */
122
+ export declare const hubTimeout: Reader<HubTimeout>;
123
+ /** Accepts the hub's address, kept as written; see the module note. */
124
+ export declare const hubUrl: Reader<string>;
125
+ /** The `hub` section's specs, spread into `SETTINGS`. */
126
+ export declare const HUB_SETTINGS: {
127
+ readonly [K in keyof HubSettings]: SettingSpec<K>;
128
+ };
129
+ /**
130
+ * The `hub` section's check: the refusal of a `service` sync with no
131
+ * `hub.url` in any layer, as a list of one sentence, or an empty list;
132
+ * see the module note.
133
+ */
134
+ export declare function hubUrlProblems(input: ConfigCheckInput): readonly string[];
135
+ /** The `hub` section: its three settings, their defaults, and {@link hubUrlProblems}. */
136
+ export declare const HUB_SECTION: ConfigSection;
137
+ /** The hub a `sync` adapter reaches, as `AdapterContext.hub` carries it. */
138
+ export interface HubContext {
139
+ /** The hub's address: the resolved `hub.url`. */
140
+ readonly url: string;
141
+ /** The secret store name of the token, or null: the resolved `hub.tokenSecret`. */
142
+ readonly tokenSecret: string | null;
143
+ /** How long one request may take, in milliseconds: the resolved `hub.timeout`. */
144
+ readonly timeoutMs: number;
145
+ }
146
+ /**
147
+ * The {@link HubContext} the resolved settings name, frozen, or
148
+ * undefined when `hub.url` is null or left out. A `hub.timeout` left out
149
+ * is read as its default, and one the reader would refuse throws a
150
+ * `TypeError`: only a config built by hand can carry one.
151
+ */
152
+ export declare function hubContextOf(config: Partial<HubSettings>): HubContext | undefined;