@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.
Files changed (59) hide show
  1. package/README.md +65 -35
  2. package/dist/adapters/logger/settings.d.ts +2 -2
  3. package/dist/bugs/record.d.ts +1 -1
  4. package/dist/bundled/skills/dev-planner/SKILL.md +1 -1
  5. package/dist/cli.js +74711 -74226
  6. package/dist/config/index.d.ts +5 -0
  7. package/dist/config/index.js +6 -3
  8. package/dist/config/shape.d.ts +8 -5
  9. package/dist/config/templates.d.ts +64 -0
  10. package/dist/config-registry.d.ts +21 -12
  11. package/dist/config-schema-bugs.d.ts +3 -3
  12. package/dist/config-schema-checks.d.ts +114 -0
  13. package/dist/config-schema-errors.d.ts +3 -3
  14. package/dist/config-schema-features.d.ts +4 -4
  15. package/dist/config-schema-hub.d.ts +3 -1
  16. package/dist/config-schema-issues.d.ts +2 -2
  17. package/dist/config-schema-logger.d.ts +3 -3
  18. package/dist/config-schema-release.d.ts +11 -12
  19. package/dist/config-schema-tests.d.ts +32 -24
  20. package/dist/core/command/command.d.ts +1 -1
  21. package/dist/core/command/confirm.d.ts +11 -5
  22. package/dist/core/command/index.d.ts +27 -9
  23. package/dist/core/command/shared-flags.d.ts +40 -0
  24. package/dist/core/config/config-load-module.d.ts +43 -0
  25. package/dist/core/config/config-load.d.ts +43 -12
  26. package/dist/core/config/config-origins.d.ts +31 -30
  27. package/dist/core/config/config-schema.d.ts +5 -0
  28. package/dist/core/config/config.d.ts +90 -25
  29. package/dist/core/config/core-section.d.ts +1 -1
  30. package/dist/core/config/index.d.ts +10 -6
  31. package/dist/core/config/merge-method.d.ts +40 -0
  32. package/dist/core/config/scope.d.ts +2 -2
  33. package/dist/core/config/section.d.ts +81 -1
  34. package/dist/core/config/sections.d.ts +13 -5
  35. package/dist/core/loop/hop-record.d.ts +6 -6
  36. package/dist/core/loop/index.d.ts +6 -6
  37. package/dist/core/loop/session-record-parse.d.ts +9 -2
  38. package/dist/core/loop/sessions.d.ts +22 -10
  39. package/dist/core/plan/block-reader.d.ts +1 -1
  40. package/dist/effort/store/index.js +5 -5
  41. package/dist/errors/rafa-codes.d.ts +1 -1
  42. package/dist/{index-77ajfffn.js → index-38ktnyvz.js} +1 -1
  43. package/dist/{index-jh1r4kcn.js → index-3mwsr6wg.js} +333 -330
  44. package/dist/{index-gqz4jn6j.js → index-7dgc5g1t.js} +4755 -4722
  45. package/dist/{index-gvek4r8m.js → index-cbqvgda6.js} +82 -26
  46. package/dist/{index-cy98y87p.js → index-eay1bd2w.js} +143 -108
  47. package/dist/{index-2a7nb3an.js → index-f1y86zbb.js} +31 -31
  48. package/dist/{index-j4k2vdz3.js → index-n3e31fmw.js} +205 -289
  49. package/dist/{index-39kbcw68.js → index-nwzx41g1.js} +4 -4
  50. package/dist/index-pzpb1rf7.js +153 -0
  51. package/dist/{index-ykggr043.js → index-r5q2pdky.js} +10 -5
  52. package/dist/index.js +14602 -14328
  53. package/dist/learning/index.js +1 -1
  54. package/dist/plan/index.js +3 -3
  55. package/dist/ports/index.d.ts +1 -1
  56. package/dist/{ready-4f8edezt.js → ready-6p40c3gw.js} +260 -269
  57. package/package.json +22 -1
  58. package/dist/pr/checks.d.ts +0 -133
  59. 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, and nothing else.
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 eight
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 eight directly and never this
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 eight hold no name in common, so each name is exported once and
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 eight
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 eight
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 eight files: every name any of
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 user scope's file under `roots.home` and the project's
20
- * under `roots.root`, ranks both against `cli`, and prints a warning
21
- * per shadowed YAML file, per key set twice in one file and per unknown
22
- * key through `warn`, the active output's `warn` when none is given.
23
- * After them it writes one pass line per `dangerous.*` key set off its
24
- * default (`dangerous.ts`), once per invocation: the active output's
25
- * when `warn` is the default, the sink's own when one is given.
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, so a run with problems in all three reports the
40
- * user file's alone. See the module note for the home, the lookup and
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, and `shadowed` the YAML files a
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, and which file a scope left
3
- * unread: the two records `ResolvedConfig` carries beside its values,
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
- * {@link originOf} reads the origin off the layer `resolveConfig`
15
- * ranked first, so it follows `sources` exactly: `file` names the
16
- * project's file, `user` the user scope's, and `cli` and `default` name
17
- * none. A map setting merged across both files names the project's,
18
- * the file its source names.
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
- * ## A shadowed file
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
- * A scope is read from one file, the first of `rafa.config.ts`,
23
- * `rafa.config.mjs` and its `.rafa/config.yaml` that is a file
24
- * (`config-load.ts`). A {@link ShadowedFile} is a YAML file a module
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
- /** The zero-based entry of that file that last set the setting. */
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
- /** A YAML file left unread because a module file holds its scope. */
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`, answered by the layer `source` names; see
49
- * the module note.
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 file - The project's file, or null when there was none.
54
- * @param user - The user scope's file, or null when there was none.
55
- * @returns The file and entry, or null for the command line or a default.
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, file: ConfigFile | null, user: ConfigFile | null): SettingOrigin | null;
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 project's config
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 project's config gave it, else the value the user scope's
7
- * config under `~/.rafa/` gave it, else its default. Each
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 project file naming one leaves the others to the
10
- * user's, and {@link ResolvedConfig.sources} records which layer
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 `file`, where
13
- * the value alone could not tell a file that was read from one that was
14
- * skipped. `file` names the project's file, as it did when that was the
15
- * only file read, and `user` names the user scope's.
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`. The pull request port
33
- * owns `MergeMethod`: a caller reading {@link RafaConfig.prMergeMethod}
34
- * imports it from `./pr/index.js`, and neither this module nor
35
- * `config-sections.ts` re-exports it, which would make the config a
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, ShadowedFile } from './config-origins.js';
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 user scope's file, or the default.
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
- /** One sentence per retained unknown key, the user file's first. */
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, the project's over the user scope's, and the
306
- * user's over its registered default (`activeDefaults()` in
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 either file
310
- * retained, the user file's first — and are never printed here. A command-line value no
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 twenty-eight more), which `src/index.test.ts`
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';