@open-tomato/rafa 0.46.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.
- package/README.md +65 -35
- package/dist/adapters/logger/settings.d.ts +2 -2
- package/dist/bugs/record.d.ts +1 -1
- package/dist/bundled/skills/dev-planner/SKILL.md +1 -1
- package/dist/cli.js +74711 -74226
- package/dist/config/index.d.ts +5 -0
- package/dist/config/index.js +6 -3
- package/dist/config/shape.d.ts +8 -5
- package/dist/config/templates.d.ts +64 -0
- package/dist/config-registry.d.ts +21 -12
- package/dist/config-schema-bugs.d.ts +3 -3
- package/dist/config-schema-checks.d.ts +114 -0
- package/dist/config-schema-errors.d.ts +3 -3
- package/dist/config-schema-features.d.ts +4 -4
- package/dist/config-schema-hub.d.ts +3 -1
- package/dist/config-schema-issues.d.ts +2 -2
- package/dist/config-schema-logger.d.ts +3 -3
- package/dist/config-schema-release.d.ts +11 -12
- package/dist/config-schema-tests.d.ts +32 -24
- package/dist/core/command/command.d.ts +1 -1
- package/dist/core/command/confirm.d.ts +11 -5
- package/dist/core/command/index.d.ts +27 -9
- package/dist/core/command/shared-flags.d.ts +40 -0
- package/dist/core/config/config-load-module.d.ts +43 -0
- package/dist/core/config/config-load.d.ts +43 -12
- package/dist/core/config/config-origins.d.ts +31 -30
- package/dist/core/config/config-schema.d.ts +5 -0
- package/dist/core/config/config.d.ts +90 -25
- package/dist/core/config/core-section.d.ts +1 -1
- package/dist/core/config/index.d.ts +10 -6
- package/dist/core/config/merge-method.d.ts +40 -0
- package/dist/core/config/scope.d.ts +2 -2
- package/dist/core/config/section.d.ts +81 -1
- package/dist/core/config/sections.d.ts +13 -5
- package/dist/core/loop/hop-record.d.ts +6 -6
- package/dist/core/loop/index.d.ts +6 -6
- package/dist/core/loop/session-record-parse.d.ts +9 -2
- package/dist/core/loop/sessions.d.ts +22 -10
- package/dist/core/plan/block-reader.d.ts +1 -1
- package/dist/effort/store/index.js +5 -5
- package/dist/errors/rafa-codes.d.ts +1 -1
- package/dist/{index-77ajfffn.js → index-38ktnyvz.js} +1 -1
- package/dist/{index-jh1r4kcn.js → index-3mwsr6wg.js} +333 -330
- package/dist/{index-gqz4jn6j.js → index-7dgc5g1t.js} +4755 -4722
- package/dist/{index-gvek4r8m.js → index-cbqvgda6.js} +82 -26
- package/dist/{index-cy98y87p.js → index-eay1bd2w.js} +143 -108
- package/dist/{index-2a7nb3an.js → index-f1y86zbb.js} +31 -31
- package/dist/{index-j4k2vdz3.js → index-n3e31fmw.js} +205 -289
- package/dist/{index-39kbcw68.js → index-nwzx41g1.js} +4 -4
- package/dist/index-pzpb1rf7.js +153 -0
- package/dist/{index-ykggr043.js → index-r5q2pdky.js} +10 -5
- package/dist/index.js +14602 -14328
- package/dist/learning/index.js +1 -1
- package/dist/plan/index.js +3 -3
- package/dist/ports/index.d.ts +1 -1
- package/dist/{ready-4f8edezt.js → ready-6p40c3gw.js} +260 -269
- package/package.json +22 -1
- package/dist/pr/checks.d.ts +0 -133
- package/dist/pr/types.d.ts +0 -422
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The barrel over the command contract: every name `command.ts`,
|
|
3
3
|
* `confirm.ts`, `lazy.ts`, `registry-types.ts`, `running.ts`,
|
|
4
|
-
* `spends.ts`, `types.ts` and `version.ts` export,
|
|
4
|
+
* `shared-flags.ts`, `spends.ts`, `types.ts` and `version.ts` export,
|
|
5
|
+
* and nothing else.
|
|
5
6
|
*
|
|
6
|
-
* A file outside `packages/rafa/src/core/` imports this file and never the
|
|
7
|
+
* A file outside `packages/rafa/src/core/` imports this file and never the nine
|
|
7
8
|
* behind it (`scripts/survey/core-barrels.ts` measures that, and
|
|
8
9
|
* `src/tests/core-barrels.sweep.test.ts` holds it against the tree). A
|
|
9
|
-
* file inside `packages/rafa/src/core/` imports the
|
|
10
|
+
* file inside `packages/rafa/src/core/` imports the nine directly and never this
|
|
10
11
|
* file.
|
|
11
12
|
*
|
|
12
13
|
* ## What sits behind it
|
|
@@ -25,6 +26,11 @@
|
|
|
25
26
|
* builder stays in `src/cli/registry.ts`;
|
|
26
27
|
* - `running.ts`: the command this process is running with its parsed
|
|
27
28
|
* flags, recorded by the dispatcher and read by the spend guard;
|
|
29
|
+
* - `shared-flags.ts`: the flags commands of several features
|
|
30
|
+
* declare, spelled once: `HINT_FLAG` and `HINT_FLAG_SPEC`, the
|
|
31
|
+
* `--no-hint` flag of the six commands that end with a hint, and
|
|
32
|
+
* `DEFAULT_CI_TIMEOUT_MIN`, the default of the loop's
|
|
33
|
+
* `--ci-timeout` and of `pr wait`'s `--timeout`;
|
|
28
34
|
* - `spends.ts`: a command's `spends` declaration, `CommandSpend`, its
|
|
29
35
|
* shape check and the mark help ends a spender's roster line with;
|
|
30
36
|
* - `types.ts`: the contracts copied from open-tomato's `cli-core`,
|
|
@@ -33,13 +39,13 @@
|
|
|
33
39
|
* - `version.ts`: the version the running build answers with, and the
|
|
34
40
|
* line that spells it.
|
|
35
41
|
*
|
|
36
|
-
* The
|
|
42
|
+
* The nine hold no name in common, so each name is exported once and
|
|
37
43
|
* from the file that declares it.
|
|
38
44
|
*
|
|
39
|
-
* ## Why one barrel can hold all
|
|
45
|
+
* ## Why one barrel can hold all nine
|
|
40
46
|
*
|
|
41
47
|
* A barrel that groups a file with a file outside `packages/rafa/src/core/` that
|
|
42
|
-
* imports the barrel back by value is a runtime cycle. None of the
|
|
48
|
+
* imports the barrel back by value is a runtime cycle. None of the nine
|
|
43
49
|
* imports a file outside `packages/rafa/src/core/` by value. `command.ts` takes
|
|
44
50
|
* `spendsProblem` from `spends.ts` beside it, and both take
|
|
45
51
|
* `describeValue` from `packages/rafa/src/core/config/config-sections.ts`.
|
|
@@ -54,9 +60,10 @@
|
|
|
54
60
|
* `Output` port with `import type`. `registry-types.ts` imports nothing
|
|
55
61
|
* by value either: it names `command.ts` with `import type`, and this
|
|
56
62
|
* file exports its names with `export type`, so loading the barrel
|
|
57
|
-
* never loads it.
|
|
63
|
+
* never loads it. `shared-flags.ts` imports nothing by value either: it
|
|
64
|
+
* names `command.ts` with `import type` alone.
|
|
58
65
|
*
|
|
59
|
-
* `command.ts` also names `src/project/scope.ts` with `import type`,
|
|
66
|
+
* `command.ts` also names `packages/rafa/src/project/scope.ts` with `import type`,
|
|
60
67
|
* which is erased before anything loads; it named `src/cli/registry.ts`
|
|
61
68
|
* the same way until the registry's contract moved into
|
|
62
69
|
* `registry-types.ts`. `src/cli/registry.ts` imports this barrel by
|
|
@@ -87,13 +94,23 @@
|
|
|
87
94
|
* The same `HELP_WORD` control held a sixth, `src/cli/registry.ts`,
|
|
88
95
|
* `command.ts` and this file.
|
|
89
96
|
*
|
|
97
|
+
* Measured again when `shared-flags.ts` moved in, the same way and with
|
|
98
|
+
* the untracked new file read: five cycles at the base and four after
|
|
99
|
+
* the move, none through a file of this folder. The one gone is
|
|
100
|
+
* `src/next/actions.ts` and `src/next/hint.ts`, broken because
|
|
101
|
+
* `actions.ts` now takes `HINT_FLAG` from this barrel rather than from
|
|
102
|
+
* `hint.ts`. The control, `shared-flags.ts` taking one value
|
|
103
|
+
* (`HINT_TIMEOUT_MS`) from `src/next/hint.ts`, folded this file,
|
|
104
|
+
* `shared-flags.ts` and `hint.ts` into one strongly connected set of
|
|
105
|
+
* seventy files.
|
|
106
|
+
*
|
|
90
107
|
* ## What it exports
|
|
91
108
|
*
|
|
92
109
|
* Each name is spelled, types apart from values, as the config barrels
|
|
93
110
|
* spell theirs. No name here is part of the published surface:
|
|
94
111
|
* `src/index.ts` re-exports nothing from this file.
|
|
95
112
|
*
|
|
96
|
-
* `index.test.ts` holds the list to the
|
|
113
|
+
* `index.test.ts` holds the list to the nine files: every name any of
|
|
97
114
|
* them exports is here once, as the same binding, and no other name is
|
|
98
115
|
* here.
|
|
99
116
|
*/
|
|
@@ -108,5 +125,6 @@ export { COMMAND_OUTPUTS, CommandExit, commandProblem, commandSpelling, isRoutin
|
|
|
108
125
|
export { createLinePrompter, lazyPrompter } from './confirm.js';
|
|
109
126
|
export { lazyCommand } from './lazy.js';
|
|
110
127
|
export { restoreRunningCommand, runAsRunningCommand, runningCommand, setRunningCommand, } from './running.js';
|
|
128
|
+
export { DEFAULT_CI_TIMEOUT_MIN, HINT_FLAG, HINT_FLAG_SPEC } from './shared-flags.js';
|
|
111
129
|
export { SPENDS_GLYPH, SPENDS_WHEN, spendsCondition, spendsMark, spendsProblem, } from './spends.js';
|
|
112
130
|
export { RAFA_VERSION, versionLine } from './version.js';
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The flags commands of several features declare, spelled once.
|
|
3
|
+
*
|
|
4
|
+
* {@link HINT_FLAG_SPEC} is the `--no-hint` flag of the six commands
|
|
5
|
+
* that end by naming the step that follows (`src/next/ending.ts`):
|
|
6
|
+
* `pr merge`, `pr wait`, `pr triage`, `plan create`, `issue ready` and
|
|
7
|
+
* `loop start`. They belong to four features, and three of them are
|
|
8
|
+
* declared in a declarations file (`src/commands/pr/declarations.ts`,
|
|
9
|
+
* `src/commands/issue/declarations.ts`), which imports core's entries
|
|
10
|
+
* alone and no module under `src/`. So the flag lives here, where every
|
|
11
|
+
* one of the six can reach it, and each declares this value itself
|
|
12
|
+
* rather than a copy its tests would have to hold equal.
|
|
13
|
+
*
|
|
14
|
+
* {@link DEFAULT_CI_TIMEOUT_MIN} is here for the same reason: the
|
|
15
|
+
* loop's `--ci-timeout` (`src/commands/loop/start.ts`,
|
|
16
|
+
* `src/start/run-setup.ts`) and `pr wait`'s `--timeout`
|
|
17
|
+
* (`src/commands/pr/declarations.ts`, `src/commands/pr/wait.ts`) both
|
|
18
|
+
* default to it, and the second is spelled in a declarations file.
|
|
19
|
+
*
|
|
20
|
+
* The file imports nothing by value: it names `command.ts` with
|
|
21
|
+
* `import type` for {@link RafaFlagSpec}, which is erased before
|
|
22
|
+
* anything loads.
|
|
23
|
+
*/
|
|
24
|
+
import type { RafaFlagSpec } from './command.js';
|
|
25
|
+
/** The flag each of the six commands declares to let a hint be turned off. */
|
|
26
|
+
export declare const HINT_FLAG = "hint";
|
|
27
|
+
/**
|
|
28
|
+
* The flag each of the six declares, so `--no-hint` suppresses the
|
|
29
|
+
* ending. Boolean and defaulting to true, which is what makes
|
|
30
|
+
* `--no-hint` read as false for it (`src/cli/core/parseArgs.ts`).
|
|
31
|
+
*/
|
|
32
|
+
export declare const HINT_FLAG_SPEC: RafaFlagSpec;
|
|
33
|
+
/**
|
|
34
|
+
* How many minutes a pull request's checks are polled before the wait
|
|
35
|
+
* gives up on them. The loop's `--ci-timeout` and `pr wait`'s
|
|
36
|
+
* `--timeout` both default to it, so one wait typed by hand and the
|
|
37
|
+
* loop's own CI gate hold a pull request to the same deadline;
|
|
38
|
+
* `pr triage --resolve` waits this long too.
|
|
39
|
+
*/
|
|
40
|
+
export declare const DEFAULT_CI_TIMEOUT_MIN: number;
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The helpers `config-load.ts` reads a module file (`rafa.config.ts`,
|
|
3
|
+
* `rafa.config.mjs`) through: the `false` the merge removes set back,
|
|
4
|
+
* the entry that last touched each setting, and the refusal of a module
|
|
5
|
+
* it imports and cannot find.
|
|
6
|
+
*
|
|
7
|
+
* They sit beside the loader rather than in it so `config-load.ts`,
|
|
8
|
+
* which reads two places per scope, stays under the 800-line ceiling of
|
|
9
|
+
* `context/source.md`. The rules they apply are the loader's, argued in
|
|
10
|
+
* its module note under "Reading a scope's file" and "Refusals"; nothing
|
|
11
|
+
* here reads a file, and no file outside `config-load.ts` imports this
|
|
12
|
+
* one.
|
|
13
|
+
*/
|
|
14
|
+
import type { Mapping } from './config-sections.js';
|
|
15
|
+
import type { ConfigSetting } from './config.js';
|
|
16
|
+
import type { LoadResult, Provenance } from '@open-tomato/define-config';
|
|
17
|
+
/**
|
|
18
|
+
* The refusal of a module file importing `specifier`, which cannot be
|
|
19
|
+
* found from it: the file, the module and, for a package, the install.
|
|
20
|
+
*
|
|
21
|
+
* @param path - The module file.
|
|
22
|
+
* @param specifier - The import it could not resolve.
|
|
23
|
+
* @returns One problem sentence.
|
|
24
|
+
*/
|
|
25
|
+
export declare function missingModuleProblem(path: string, specifier: string): string;
|
|
26
|
+
/**
|
|
27
|
+
* A module file's merged value with each `false` the merge removed set
|
|
28
|
+
* back, unless a later entry removed or replaced a mapping above it or
|
|
29
|
+
* the key's reader refuses `false` there; see "Reading a scope's file"
|
|
30
|
+
* in `config-load.ts`.
|
|
31
|
+
*
|
|
32
|
+
* @param result - What define-config's loader read off the file.
|
|
33
|
+
* @returns The mapping the file's settings are read from.
|
|
34
|
+
*/
|
|
35
|
+
export declare function restoredMapping({ config, provenance }: LoadResult): Mapping;
|
|
36
|
+
/**
|
|
37
|
+
* The last entry that touched each registered setting of a module file,
|
|
38
|
+
* its key or a key below it: what `provenance` names.
|
|
39
|
+
*
|
|
40
|
+
* @param provenance - The loader's record of every key the file's entries set.
|
|
41
|
+
* @returns The entry by setting, for the settings the file touched.
|
|
42
|
+
*/
|
|
43
|
+
export declare function entriesOf(provenance: Provenance): ReadonlyMap<ConfigSetting, number>;
|
|
@@ -6,6 +6,13 @@ export interface ConfigRoots {
|
|
|
6
6
|
/** The home directory: the user scope's files sit under its `.rafa/`. */
|
|
7
7
|
readonly home: string;
|
|
8
8
|
}
|
|
9
|
+
/** The project scope's two files, each read with its templates laid under; see {@link readProjectScope}. */
|
|
10
|
+
export interface ProjectScopeFiles {
|
|
11
|
+
/** The project's YAML file, its local layer, or null when there is none. */
|
|
12
|
+
readonly local: ConfigFile | null;
|
|
13
|
+
/** The project's module file, `rafa.config.ts` or `rafa.config.mjs`, or null when there is none. */
|
|
14
|
+
readonly file: ConfigFile | null;
|
|
15
|
+
}
|
|
9
16
|
/**
|
|
10
17
|
* Reads `.rafa/config.yaml` under `root`, or answers null when nothing
|
|
11
18
|
* is at that path. Anything there that cannot be read — a directory,
|
|
@@ -16,13 +23,34 @@ export interface ConfigRoots {
|
|
|
16
23
|
*/
|
|
17
24
|
export declare function readConfigFile(root: string): ConfigFile | null;
|
|
18
25
|
/**
|
|
19
|
-
* Reads the
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
+
* Reads the project scope's two files under `root`, each with the
|
|
27
|
+
* templates it names laid under it, and answers them unranked: no user
|
|
28
|
+
* scope, no warning printed, no load hook called and no store setting
|
|
29
|
+
* touched. Every refusal {@link loadConfig} raises for either file is
|
|
30
|
+
* raised here, a key set twice in one file at the `merge.duplicates`
|
|
31
|
+
* of the two files included. See the module note.
|
|
32
|
+
*
|
|
33
|
+
* @param root - The project root: the module file sits here and the
|
|
34
|
+
* YAML file under its `.rafa/`.
|
|
35
|
+
* @returns The YAML file as `local` and the module file as `file`, each
|
|
36
|
+
* null when the project holds none.
|
|
37
|
+
* @throws {ConfigError} For a file the load refuses.
|
|
38
|
+
* @throws {Error} When no config section is registered.
|
|
39
|
+
*/
|
|
40
|
+
export declare function readProjectScope(root: string): Promise<ProjectScopeFiles>;
|
|
41
|
+
/**
|
|
42
|
+
* Reads the user scope's two files under `roots.home` and the project's
|
|
43
|
+
* two under `roots.root`, ranks the four against `cli`, and prints a
|
|
44
|
+
* warning per key set twice in one file and per unknown key through
|
|
45
|
+
* `warn`, the active output's `warn` when none is given. After them it
|
|
46
|
+
* writes one pass line per `dangerous.*` key set off its default
|
|
47
|
+
* (`dangerous.ts`), once per invocation: the active output's when
|
|
48
|
+
* `warn` is the default, the sink's own when one is given.
|
|
49
|
+
*
|
|
50
|
+
* Each scope's YAML file is its local layer, ranked over its module
|
|
51
|
+
* file key by key: the project's as `local` over its module file as
|
|
52
|
+
* `file`, the user scope's as `userLocal` over its module file as
|
|
53
|
+
* `user`. See "The local layer" in the module note.
|
|
26
54
|
*
|
|
27
55
|
* The resolved config is handed to the load hook (`activeConfigLoadHook`
|
|
28
56
|
* in `section.ts`) before any warning is printed. The registry,
|
|
@@ -35,13 +63,16 @@ export declare function readConfigFile(root: string): ConfigFile | null;
|
|
|
35
63
|
* (`effort/store/settings.ts`), so every store open after this call
|
|
36
64
|
* waits that long for a lock.
|
|
37
65
|
*
|
|
66
|
+
* Each file has the templates its `templates` key names laid under its
|
|
67
|
+
* own keys, read through the active template hook; a name the hook does
|
|
68
|
+
* not know is refused. See "Templates" in the module note.
|
|
69
|
+
*
|
|
38
70
|
* The files are read and judged before the command line is looked at,
|
|
39
|
-
* the user's first
|
|
40
|
-
*
|
|
41
|
-
* every refusal.
|
|
71
|
+
* the user's first and each scope's module file before its YAML file,
|
|
72
|
+
* so a run with problems in every layer reports the first file's alone.
|
|
73
|
+
* See the module note for the home, the lookup and every refusal.
|
|
42
74
|
*
|
|
43
75
|
* @returns The resolution, with `provenance` naming the file and entry
|
|
44
|
-
* of each setting a file answered
|
|
45
|
-
* module file left unread.
|
|
76
|
+
* of each setting a file answered.
|
|
46
77
|
*/
|
|
47
78
|
export declare function loadConfig(roots: ConfigRoots, cli?: ConfigOverrides, warn?: (message: string) => void): Promise<ResolvedConfig>;
|
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Where a resolved setting came from
|
|
3
|
-
*
|
|
4
|
-
* `provenance` and `shadowed` (`config.ts`).
|
|
2
|
+
* Where a resolved setting came from: the record `ResolvedConfig`
|
|
3
|
+
* carries beside its values, `provenance` (`config.ts`).
|
|
5
4
|
*
|
|
6
5
|
* ## An origin
|
|
7
6
|
*
|
|
@@ -11,19 +10,24 @@
|
|
|
11
10
|
* file is one entry, so every setting it answers is entry 0. A setting
|
|
12
11
|
* the command line or a default answered has no origin: no file set it.
|
|
13
12
|
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
13
|
+
* `resolveConfig` ranks four files, two per scope: the project's local
|
|
14
|
+
* file, the project's file, the user scope's local file and the user
|
|
15
|
+
* scope's file, highest first. {@link originOf} takes the FILE that
|
|
16
|
+
* answered a setting, never a source name, so the two user files, which
|
|
17
|
+
* both report source `user`, each name their own path, as the project's
|
|
18
|
+
* local file (`local`) and its other file (`file`) do. `cli` and
|
|
19
|
+
* `default` name no file and answer none. A map setting merged across
|
|
20
|
+
* several files names the highest of them, the file its source names.
|
|
19
21
|
*
|
|
20
|
-
*
|
|
22
|
+
* A setting a template answered (`template`) names the file whose
|
|
23
|
+
* `templates` key named it, which is the file that answered, since a
|
|
24
|
+
* file's templates are laid under its own keys, with the entry of that
|
|
25
|
+
* file that last set `templates`, and carries the template's name as
|
|
26
|
+
* `template`. An origin a file's own key gave carries no `template`.
|
|
21
27
|
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
* file of its scope left unread, named so the warning and `rafa doctor`
|
|
26
|
-
* can say which keys stopped applying.
|
|
28
|
+
* No file of a scope shadows another: each scope is read from its
|
|
29
|
+
* module file and its YAML file over it (`config-load.ts`), so no
|
|
30
|
+
* record here names a file left unread.
|
|
27
31
|
*/
|
|
28
32
|
import type { ConfigFile, ConfigSetting, ConfigSource } from './config.js';
|
|
29
33
|
/** The two scopes a config file is read in. */
|
|
@@ -32,26 +36,23 @@ export type ConfigScopeName = 'user' | 'project';
|
|
|
32
36
|
export interface SettingOrigin {
|
|
33
37
|
/** The file, as its layer names it. */
|
|
34
38
|
readonly file: string;
|
|
35
|
-
/**
|
|
39
|
+
/**
|
|
40
|
+
* The zero-based entry of that file that last set the setting, or for
|
|
41
|
+
* a template's setting the entry that last set the file's `templates`.
|
|
42
|
+
*/
|
|
36
43
|
readonly entry: number;
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
export interface ShadowedFile {
|
|
40
|
-
/** The scope both files sit in. */
|
|
41
|
-
readonly layer: ConfigScopeName;
|
|
42
|
-
/** The YAML file left unread. */
|
|
43
|
-
readonly path: string;
|
|
44
|
-
/** The module file read in its place. */
|
|
45
|
-
readonly by: string;
|
|
44
|
+
/** The template that answered the setting, by name; absent for a file's own key. */
|
|
45
|
+
readonly template?: string;
|
|
46
46
|
}
|
|
47
47
|
/**
|
|
48
|
-
* The origin of `setting`,
|
|
49
|
-
*
|
|
48
|
+
* The origin of `setting`, read off the file that answered it; see the
|
|
49
|
+
* module note.
|
|
50
50
|
*
|
|
51
51
|
* @param source - The layer that answered the setting.
|
|
52
52
|
* @param setting - The setting.
|
|
53
|
-
* @param
|
|
54
|
-
*
|
|
55
|
-
* @returns The file and entry, or null for the command line
|
|
53
|
+
* @param answeredBy - The file that answered it, or null where the
|
|
54
|
+
* command line or a default did.
|
|
55
|
+
* @returns The file and entry, or null for the command line, a default,
|
|
56
|
+
* or a template the file records none for.
|
|
56
57
|
*/
|
|
57
|
-
export declare function originOf(source: ConfigSource, setting: ConfigSetting,
|
|
58
|
+
export declare function originOf(source: ConfigSource, setting: ConfigSetting, answeredBy: ConfigFile | null): SettingOrigin | null;
|
|
@@ -177,6 +177,11 @@ export interface RafaConfig {
|
|
|
177
177
|
* once; `loop start` creates the branch it names. `naming.branch`.
|
|
178
178
|
*/
|
|
179
179
|
namingBranch: string;
|
|
180
|
+
/**
|
|
181
|
+
* The config templates a file adopts, by name: each a non-empty
|
|
182
|
+
* string, in the order written. `templates`.
|
|
183
|
+
*/
|
|
184
|
+
templates: readonly string[];
|
|
180
185
|
}
|
|
181
186
|
/** The name of one setting, as a field of {@link RafaConfig}. */
|
|
182
187
|
export type ConfigSetting = keyof RafaConfig;
|
|
@@ -1,18 +1,35 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Reading rafa's settings: the phase 1 schema of the
|
|
2
|
+
* Reading rafa's settings: the phase 1 schema of the config files
|
|
3
3
|
* (`.rafa/config.yaml`, `rafa.config.ts` or `rafa.config.mjs`).
|
|
4
4
|
*
|
|
5
|
+
* Four files rank, two per scope ({@link ConfigLayers}): the project's
|
|
6
|
+
* local file over the project's file, then the user scope's local file
|
|
7
|
+
* over the user scope's file under `~/.rafa/`. A scope's local file is
|
|
8
|
+
* its `.rafa/config.yaml`, read over the scope's module file key by key;
|
|
9
|
+
* which file on disk fills each layer is `config-load.ts`'s to say.
|
|
5
10
|
* Every setting takes the value the COMMAND LINE gave it, else the
|
|
6
|
-
* value the
|
|
7
|
-
*
|
|
11
|
+
* value of the first of the four files, in that order, that gave it one,
|
|
12
|
+
* else its default; a map setting merges by key in the reverse order,
|
|
13
|
+
* the default under the user's files under the project's. Each
|
|
8
14
|
* setting is ranked on its own, so a flag naming one leaves the others
|
|
9
|
-
* to the files and a
|
|
10
|
-
*
|
|
15
|
+
* to the files and a file naming one leaves the others to the files
|
|
16
|
+
* under it, and {@link ResolvedConfig.sources} records which layer
|
|
11
17
|
* answered each. That record keeps precedence observable when two
|
|
12
|
-
* layers agree: a file spelling the default still reports
|
|
13
|
-
* the value alone could not tell a file that was read from one
|
|
14
|
-
* skipped. `
|
|
15
|
-
*
|
|
18
|
+
* layers agree: a file spelling the default still reports its layer,
|
|
19
|
+
* where the value alone could not tell a file that was read from one
|
|
20
|
+
* that was skipped. `local` names the project's local file and `file`
|
|
21
|
+
* the project's other file, as it did when that was the only file read;
|
|
22
|
+
* `user` names either of the user scope's, and the origin in
|
|
23
|
+
* {@link ResolvedConfig.provenance}, read off the file that answered,
|
|
24
|
+
* tells the two apart.
|
|
25
|
+
*
|
|
26
|
+
* A file may name config templates with its `templates` key, and each
|
|
27
|
+
* template's entry sits under that file's own keys and over every lower
|
|
28
|
+
* file: each of the four over its own templates over the next file down,
|
|
29
|
+
* the last over the default. A setting a template answered and no
|
|
30
|
+
* file outranked reports `template`, and its `provenance` names the
|
|
31
|
+
* template and the file that named it. {@link layTemplatesUnder} lays
|
|
32
|
+
* them; `config-load.ts` reads them through the template hook.
|
|
16
33
|
*
|
|
17
34
|
* This module is the pure half: text, or a document already parsed,
|
|
18
35
|
* into a layer, and layers into one resolution. Finding and reading each
|
|
@@ -29,11 +46,10 @@
|
|
|
29
46
|
* other two modules export for a caller to import rather than reaching
|
|
30
47
|
* into a sibling; however, most
|
|
31
48
|
* callers import `config-sections.ts`'s names directly,
|
|
32
|
-
* through its barrel `core/config/sections.js`.
|
|
33
|
-
*
|
|
34
|
-
*
|
|
35
|
-
* `
|
|
36
|
-
* second place to learn it from.
|
|
49
|
+
* through its barrel `core/config/sections.js`. `MergeMethod`, the type
|
|
50
|
+
* of {@link RafaConfig.prMergeMethod}, is `merge-method.ts`'s, exported
|
|
51
|
+
* by that barrel and re-exported by the pull request port
|
|
52
|
+
* (`src/pr/types.ts`); this module does not re-export it.
|
|
37
53
|
*
|
|
38
54
|
* - `config-sections.ts` holds every rule about a VALUE: the readers,
|
|
39
55
|
* the closed lists of values, and why nothing is coerced.
|
|
@@ -180,7 +196,7 @@
|
|
|
180
196
|
* boolean. So a `tracking` flag spelled `yes` is refused rather
|
|
181
197
|
* than read as true.
|
|
182
198
|
*/
|
|
183
|
-
import type { SettingOrigin
|
|
199
|
+
import type { SettingOrigin } from './config-origins.js';
|
|
184
200
|
import type { CommandLineSetting, ConfigSetting, RafaConfig } from './config-schema.js';
|
|
185
201
|
import type { ConfigExtra } from './config-sections.js';
|
|
186
202
|
export type { CommandLineSetting, ConfigSetting, RafaConfig, } from './config-schema.js';
|
|
@@ -191,9 +207,11 @@ export type { ModuleSource, ModuleSourceKind, OptionalPrerequisiteItem, Prerequi
|
|
|
191
207
|
export { MODULE_SOURCE_KINDS, PREREQUISITE_KINDS } from './config-items.js';
|
|
192
208
|
/**
|
|
193
209
|
* The layer that answered a setting: the command line, the project's
|
|
194
|
-
* file, the
|
|
210
|
+
* local file, the project's file, either of the user scope's two files,
|
|
211
|
+
* a template any file named, or the default. Which user file answered,
|
|
212
|
+
* and which file named the template, is the setting's `provenance`.
|
|
195
213
|
*/
|
|
196
|
-
export type ConfigSource = 'cli' | 'file' | 'user' | 'default';
|
|
214
|
+
export type ConfigSource = 'cli' | 'local' | 'file' | 'user' | 'template' | 'default';
|
|
197
215
|
/**
|
|
198
216
|
* One layer's say on every setting: a value, or undefined for silence.
|
|
199
217
|
*
|
|
@@ -228,13 +246,30 @@ export interface ConfigFile {
|
|
|
228
246
|
* setting is entry 0.
|
|
229
247
|
*/
|
|
230
248
|
entries?: ReadonlyMap<ConfigSetting, number>;
|
|
249
|
+
/**
|
|
250
|
+
* The template that answered each setting the file's own keys left
|
|
251
|
+
* silent, by name, as {@link layTemplatesUnder} laid it. Absent for a
|
|
252
|
+
* file naming no template.
|
|
253
|
+
*/
|
|
254
|
+
templates?: ReadonlyMap<ConfigSetting, string>;
|
|
255
|
+
}
|
|
256
|
+
/** One template a file named, read: its name and its say on every setting. */
|
|
257
|
+
export interface TemplateLayer {
|
|
258
|
+
/** The name the file's `templates` key gave. */
|
|
259
|
+
readonly name: string;
|
|
260
|
+
/** Its value for each setting, or undefined where it said nothing. */
|
|
261
|
+
readonly values: ConfigLayer;
|
|
231
262
|
}
|
|
232
263
|
/** The layers {@link resolveConfig} ranks, highest first. */
|
|
233
264
|
export interface ConfigLayers {
|
|
234
265
|
/** Command-line values. Absent is the same as no flag given. */
|
|
235
266
|
cli?: ConfigOverrides;
|
|
267
|
+
/** The project's parsed local file, its `.rafa/config.yaml`, or null when there is none. */
|
|
268
|
+
local?: ConfigFile | null;
|
|
236
269
|
/** The project's parsed file, or null when there is none. */
|
|
237
270
|
file?: ConfigFile | null;
|
|
271
|
+
/** The user scope's parsed local file, or null when there is none. Its settings report `user`. */
|
|
272
|
+
userLocal?: ConfigFile | null;
|
|
238
273
|
/** The user scope's parsed file, or null when there is none. */
|
|
239
274
|
user?: ConfigFile | null;
|
|
240
275
|
}
|
|
@@ -246,21 +281,31 @@ export interface ResolvedConfig {
|
|
|
246
281
|
sources: Readonly<Record<ConfigSetting, ConfigSource>>;
|
|
247
282
|
/** The project's file consulted, or null when there was none. */
|
|
248
283
|
path: string | null;
|
|
284
|
+
/** The project's local file consulted, or null when there was none. */
|
|
285
|
+
localPath: string | null;
|
|
249
286
|
/** The user scope's file consulted, or null when there was none. */
|
|
250
287
|
userPath: string | null;
|
|
288
|
+
/** The user scope's local file consulted, its `~/.rafa/config.yaml`, or null when there was none. */
|
|
289
|
+
userLocalPath: string | null;
|
|
251
290
|
/** The project file's unknown keys, retained. Empty with no file. */
|
|
252
291
|
extras: readonly ConfigExtra[];
|
|
292
|
+
/** The project's local file's unknown keys, retained. Empty with no file. */
|
|
293
|
+
localExtras: readonly ConfigExtra[];
|
|
253
294
|
/** The user file's unknown keys, retained. Empty with no file. */
|
|
254
295
|
userExtras: readonly ConfigExtra[];
|
|
255
|
-
/**
|
|
296
|
+
/** The user scope's local file's unknown keys, retained. Empty with no file. */
|
|
297
|
+
userLocalExtras: readonly ConfigExtra[];
|
|
298
|
+
/**
|
|
299
|
+
* One sentence per retained unknown key, in layer order from the
|
|
300
|
+
* bottom: the user file's, the user's local file's, the project
|
|
301
|
+
* file's, then the project's local file's.
|
|
302
|
+
*/
|
|
256
303
|
warnings: readonly string[];
|
|
257
304
|
/**
|
|
258
305
|
* The file and entry that answered each setting, or null where the
|
|
259
306
|
* command line or a default did (`config-origins.ts`).
|
|
260
307
|
*/
|
|
261
308
|
provenance: Readonly<Record<ConfigSetting, SettingOrigin | null>>;
|
|
262
|
-
/** The YAML files a module file of their scope left unread. Empty here; `config-load.ts` fills it. */
|
|
263
|
-
shadowed: readonly ShadowedFile[];
|
|
264
309
|
}
|
|
265
310
|
/**
|
|
266
311
|
* A config the loop cannot run on: unreadable, not YAML, not a
|
|
@@ -300,14 +345,34 @@ export declare function parseConfigText(text: string, path: string): ConfigFile;
|
|
|
300
345
|
* the top is refused, and every key is judged. Pure; `path` only labels.
|
|
301
346
|
*/
|
|
302
347
|
export declare function readConfigDocument(parsed: unknown, path: string): ConfigFile;
|
|
348
|
+
/**
|
|
349
|
+
* `file` with each of `templates` laid under its own keys, in the order
|
|
350
|
+
* named, a later template over an earlier one: a setting the file left
|
|
351
|
+
* silent takes the last template's value that answers it, and a map
|
|
352
|
+
* setting merges by key, the templates under the file. Each setting a
|
|
353
|
+
* template answered and the file did not is recorded in
|
|
354
|
+
* {@link ConfigFile.templates} under that template's name. Pure; answers
|
|
355
|
+
* `file` itself when no template is given.
|
|
356
|
+
*
|
|
357
|
+
* @param file - The file as its own keys read.
|
|
358
|
+
* @param templates - The templates its `templates` key named, read.
|
|
359
|
+
* @returns The file with the templates' values beneath its own.
|
|
360
|
+
*/
|
|
361
|
+
export declare function layTemplatesUnder(file: ConfigFile, templates: readonly TemplateLayer[]): ConfigFile;
|
|
303
362
|
/**
|
|
304
363
|
* Ranks the layers: for each registered setting, the command line over
|
|
305
|
-
* the project's file,
|
|
306
|
-
* user's over
|
|
307
|
-
* `section.ts`).
|
|
364
|
+
* the project's local file, that over the project's file, that over the
|
|
365
|
+
* user scope's local file, that over the user scope's file, and that
|
|
366
|
+
* over its registered default (`activeDefaults()` in `section.ts`). A
|
|
367
|
+
* map setting merges by key in the reverse order, each file over the
|
|
368
|
+
* ones beneath it. A file's templates are already laid under it
|
|
369
|
+
* ({@link layTemplatesUnder}), so a setting one answered ranks with its
|
|
370
|
+
* file and reports `template`. Each setting's origin is read off the
|
|
371
|
+
* file that answered it ({@link originOf}), the highest one naming a map
|
|
372
|
+
* setting, so the two user files, both reporting `user`, name their own.
|
|
308
373
|
*
|
|
309
|
-
* Pure. Warnings come back as data — one per unknown key
|
|
310
|
-
* retained, the
|
|
374
|
+
* Pure. Warnings come back as data — one per unknown key any file
|
|
375
|
+
* retained, from the bottom layer up — and are never printed here. A command-line value no
|
|
311
376
|
* setting accepts throws a {@link ConfigError} naming every one, and
|
|
312
377
|
* is never downgraded to the file's value: an operator who mistyped a
|
|
313
378
|
* flag asked for something, and running on something else is the
|
|
@@ -21,7 +21,7 @@ export declare const SCOPE_DIR: string;
|
|
|
21
21
|
* rather than read off a value, since `isolatedDeclarations` asks every
|
|
22
22
|
* exported type to be written out.
|
|
23
23
|
*/
|
|
24
|
-
export type CoreSetting = 'version' | 'store' | 'effortBusyTimeoutMs' | 'effortSync' | 'inject' | 'planDir' | 'specsDir' | 'trackerDefault' | 'trackerFallback' | 'learningAdapter' | 'learningBlessMinConfidence' | 'learningPromoteAfter' | 'learningPromoteMinConfidence' | 'outputMode' | 'prerequisitesRequired' | 'prerequisitesOptional' | 'trackingSpecs' | 'trackingPlans' | 'trackingAll' | 'modules' | 'allowList' | 'settingSources' | 'loopWorktreeDir' | 'boardTrustedAuthors' | 'boardRelationships' | 'boardProjectTemplate' | 'boardProjectNumber' | 'roadmapIssue' | 'claimsStaleAfter' | 'claimsAhead' | 'cleanupStaleDays' | 'cleanupWorktreeIdleDays' | 'cleanupKeep' | 'dangerousAcceptStaleRefs' | 'dangerousSelfUpdateDuringLoop' | 'statusNotice' | 'tiersRafa' | 'tiersSkills' | 'tiersAgents' | 'routing' | 'taskSkills' | 'taskLessons' | 'mergeDuplicates' | 'namingBranch';
|
|
24
|
+
export type CoreSetting = 'version' | 'store' | 'effortBusyTimeoutMs' | 'effortSync' | 'inject' | 'planDir' | 'specsDir' | 'trackerDefault' | 'trackerFallback' | 'learningAdapter' | 'learningBlessMinConfidence' | 'learningPromoteAfter' | 'learningPromoteMinConfidence' | 'outputMode' | 'prerequisitesRequired' | 'prerequisitesOptional' | 'trackingSpecs' | 'trackingPlans' | 'trackingAll' | 'modules' | 'allowList' | 'settingSources' | 'loopWorktreeDir' | 'boardTrustedAuthors' | 'boardRelationships' | 'boardProjectTemplate' | 'boardProjectNumber' | 'roadmapIssue' | 'claimsStaleAfter' | 'claimsAhead' | 'cleanupStaleDays' | 'cleanupWorktreeIdleDays' | 'cleanupKeep' | 'dangerousAcceptStaleRefs' | 'dangerousSelfUpdateDuringLoop' | 'statusNotice' | 'tiersRafa' | 'tiersSkills' | 'tiersAgents' | 'routing' | 'taskSkills' | 'taskLessons' | 'mergeDuplicates' | 'namingBranch' | 'templates';
|
|
25
25
|
/** Core's section: its package, the spec and the default of each of its settings, and no check. */
|
|
26
26
|
export interface CoreSection extends ConfigSection {
|
|
27
27
|
/** Each of core's settings, by name, in the order problems are reported. */
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
*
|
|
29
29
|
* `scope.ts` joined it with a scope's paths, `Scope`, the project the
|
|
30
30
|
* dispatcher resolved, `ProjectFound`, and `scopeAt`, whose walk,
|
|
31
|
-
* `resolveScope`, stays in `src/project/scope.ts`. It reads `config.ts`
|
|
31
|
+
* `resolveScope`, stays in `packages/rafa/src/project/scope.ts`. It reads `config.ts`
|
|
32
32
|
* and `core-section.ts` by value and `config-load.ts` as a type, so it
|
|
33
33
|
* is no leaf for `sections.ts`, and `load.ts` holds `config-load.ts`
|
|
34
34
|
* alone.
|
|
@@ -108,6 +108,10 @@
|
|
|
108
108
|
* `SECTIONS` and `knownKeysAbove`) is not here: a file outside
|
|
109
109
|
* `packages/rafa/src/core/` imports it from `src/config-registry.ts`, and core reads
|
|
110
110
|
* the registered settings, defaults and key indexes off `section.ts`.
|
|
111
|
+
* A feature file that reads the whole `CONFIG_DEFAULTS` or `SETTINGS`
|
|
112
|
+
* record without importing the registry takes `registeredDefaults()`
|
|
113
|
+
* or `registeredSettings()` from here, which answer the registered
|
|
114
|
+
* records typed whole.
|
|
111
115
|
* Neither are the hub's `HubContext` and `HubTimeout`, which a file
|
|
112
116
|
* imports from `src/config-schema-hub.ts`.
|
|
113
117
|
*
|
|
@@ -116,7 +120,7 @@
|
|
|
116
120
|
* section, the routing defaults, the item readers, `config.ts`'s two
|
|
117
121
|
* document readers the loader reads a scope through, and the section
|
|
118
122
|
* registry with its key indexes (`CORE_SECTION`, `moduleSource`, `registerConfigSections`,
|
|
119
|
-
* `activeSettingByKey` and
|
|
123
|
+
* `activeSettingByKey` and thirty-three more), which `src/index.test.ts`
|
|
120
124
|
* spells under `CONFIG_BARREL_ONLY`. Its `CONFIG_DEFAULTS` is
|
|
121
125
|
* `src/config-registry.ts`'s.
|
|
122
126
|
*
|
|
@@ -127,15 +131,15 @@
|
|
|
127
131
|
export type { ModuleSource, ModuleSourceKind, OptionalPrerequisiteItem, PrerequisiteItem, PrerequisiteKind, PrerequisiteScope, } from './config-items.js';
|
|
128
132
|
export type { CommandLineSetting, ConfigSetting, RafaConfig, SettingSpec, } from './config-schema.js';
|
|
129
133
|
export type { CoreSection, CoreSetting } from './core-section.js';
|
|
130
|
-
export type { ConfigCheck, ConfigCheckInput, ConfigLoadHook, ConfigSection, ConfigSectionRegistry, SettingsRecord, } from './section.js';
|
|
131
|
-
export type { ConfigFile, ConfigLayer, ConfigLayers, ConfigOverrides, ConfigSource, ResolvedConfig, } from './config.js';
|
|
134
|
+
export type { ConfigCheck, ConfigCheckInput, ConfigLoadHook, ConfigSection, ConfigSectionRegistry, ConfigTemplateHook, SettingsRecord, } from './section.js';
|
|
135
|
+
export type { ConfigFile, ConfigLayer, ConfigLayers, ConfigOverrides, ConfigSource, ResolvedConfig, TemplateLayer, } from './config.js';
|
|
132
136
|
export type { DangerousPhrases } from './dangerous.js';
|
|
133
137
|
export type { ProjectFound, Scope } from './scope.js';
|
|
134
138
|
export type { Route } from './default-routing.js';
|
|
135
139
|
export { MODULE_SOURCE_KEYS, MODULE_SOURCE_KINDS, moduleSource, OPTIONAL_ITEM_KEYS, optionalPrerequisite, PREREQUISITE_KINDS, REQUIRED_ITEM_KEYS, requiredPrerequisite, } from './config-items.js';
|
|
136
140
|
export { CONFIG_FILE, CORE_SECTION, SCOPE_DIR } from './core-section.js';
|
|
137
|
-
export { activeChecks, activeConfigLoadHook, activeDefaults, activeKnownKeysAbove, activeSectionPaths, activeSections, activeSettingByKey, activeSettings, ConfigSectionError, EMPTY_CONFIG_REGISTRY, mergeConfigSections, registerConfigSections, restoreConfigSections, setConfigLoadHook, } from './section.js';
|
|
138
|
-
export { ConfigError, configFilePath, parseConfigDocument, parseConfigText, readConfigDocument, resolveConfig, } from './config.js';
|
|
141
|
+
export { activeChecks, activeConfigLoadHook, activeConfigTemplateHook, activeDefaults, activeKnownKeysAbove, activeSectionPaths, activeSections, activeSettingByKey, activeSettings, ConfigSectionError, EMPTY_CONFIG_REGISTRY, mergeConfigSections, registerConfigSections, registeredDefaults, registeredSettings, restoreConfigSections, setConfigLoadHook, setConfigTemplateHook, } from './section.js';
|
|
142
|
+
export { ConfigError, configFilePath, layTemplatesUnder, parseConfigDocument, parseConfigText, readConfigDocument, resolveConfig, } from './config.js';
|
|
139
143
|
export { dangerousKeys, dangerousPassLines, dangerousPhrases, restoreDangerousPhrases, runWithDangerousPhrases, setDangerousPhrases, writeDangerousPassLines, } from './dangerous.js';
|
|
140
144
|
export { scopeAt } from './scope.js';
|
|
141
145
|
export { DEFAULT_ROUTES, DEFAULT_ROUTING } from './default-routing.js';
|