@open-tomato/rafa 0.45.0 → 0.46.0

package/dist/core/config/config.d.ts

@@ -0,0 +1,320 @@
+/**
+ * Reading rafa's settings: the phase 1 schema of the project's config
+ * (`.rafa/config.yaml`, `rafa.config.ts` or `rafa.config.mjs`).
+ *
+ * Every setting takes the value the COMMAND LINE gave it, else the
+ * value the project's config gave it, else the value the user scope's
+ * config under `~/.rafa/` gave it, else its default. Each
+ * setting is ranked on its own, so a flag naming one leaves the others
+ * to the files and a project file naming one leaves the others to the
+ * user's, and {@link ResolvedConfig.sources} records which layer
+ * answered each. That record keeps precedence observable when two
+ * layers agree: a file spelling the default still reports `file`, where
+ * the value alone could not tell a file that was read from one that was
+ * skipped. `file` names the project's file, as it did when that was the
+ * only file read, and `user` names the user scope's.
+ *
+ * This module is the pure half: text, or a document already parsed,
+ * into a layer, and layers into one resolution. Finding and reading each
+ * scope's file, behind a home seam, is `config-load.ts`, which reads a
+ * module file's merged entries through the same {@link readConfigDocument}
+ * a YAML file's document goes through. Scope resolution and `rafa init`
+ * are not here.
+ *
+ * ## Where the rules live
+ *
+ * The reader is three modules and a helper of the schema's, and a name
+ * moving between them is a refactor, never a change of behaviour. This
+ * file is intended as the public surface, re-exporting everything the
+ * other two modules export for a caller to import rather than reaching
+ * into a sibling; however, most
+ * callers import `config-sections.ts`'s names directly,
+ * through its barrel `core/config/sections.js`. The pull request port
+ * owns `MergeMethod`: a caller reading {@link RafaConfig.prMergeMethod}
+ * imports it from `./pr/index.js`, and neither this module nor
+ * `config-sections.ts` re-exports it, which would make the config a
+ * second place to learn it from.
+ *
+ *   - `config-sections.ts` holds every rule about a VALUE: the readers,
+ *     the closed lists of values, and why nothing is coerced.
+ *   - `config-items.ts` holds the prerequisite item and module source
+ *     shapes, read through the helpers `config-sections.ts` exports.
+ *     This module re-exports its types and kind lists, as it did while
+ *     they sat in `config-sections.ts`.
+ *   - The rules about a KEY sit in three modules. `config-schema.ts`
+ *     declares {@link RafaConfig}'s core fields and the setting types,
+ *     and exports no value. `core-section.ts` holds core's file keys,
+ *     specs and defaults, and {@link CONFIG_FILE}. `section.ts` holds
+ *     the registry the sections are handed to, and the setting, section
+ *     and known-key indexes it reads off the registered specs. This
+ *     module reads each spec, each default and every index off that
+ *     registry, and names no section. `src/config-registry.ts`, outside
+ *     `packages/rafa/src/core/`, lists the sections and exports the merged schema,
+ *     `CONFIG_DEFAULTS` and `SETTINGS` among it. The four readings the
+ *     spec leaves to the reader — open tracker kinds, empty
+ *     prerequisite tiers, `version: 1` alone, and `loop.settingSources`
+ *     as an ordered list — are argued in `core-section.ts`; the readings each
+ *     later section's spec leaves are argued in
+ *     `config-schema-readings.ts`, a note that exports nothing, except
+ *     the `pr` and `release` sections', which sit with their fields in
+ *     `config-schema-release.ts`, the `tests` section's, which sit
+ *     with theirs in `config-schema-tests.ts`, the `triage`
+ *     section's, in `config-schema-triage.ts`, and the `errors`
+ *     section's, in `config-schema-errors.ts`, each handed to core as
+ *     a section by `src/config-registry.ts`.
+ *   - `config-readers.ts` holds `mapOf` and the named readers
+ *     `core-section.ts` reads its settings through. No caller reads a
+ *     setting through them but the schema, so nothing here re-exports
+ *     them.
+ *   - This module holds the rules about LAYERS: which layer answers a
+ *     setting, what a file may carry, and what is refused.
+ *
+ * The split is what keeps each under the 800-line cap of
+ * `context/source.md`, which no gate reads. Measured with `wc -l` at the
+ * commit that added the `pr` section: `config.ts` is 506 lines,
+ * `config-schema.ts` 396 and `config-sections.ts` 478. A new setting is
+ * one field in `config-schema.ts` with one default and one spec in
+ * `core-section.ts` (in
+ * `config-schema-release.ts` for a `pr` or `release` key, in
+ * `config-schema-tests.ts` for a `tests` key, in
+ * `config-schema-triage.ts` for a `triage` key, in
+ * `config-schema-errors.ts` for an `errors` key), and its reader
+ * in `config-sections.ts`. Nothing here names it: {@link readLayer}
+ * and {@link resolveConfig} loop over the names registered with
+ * `section.ts` (`activeSettings()`) and take each default from
+ * `activeDefaults()`, so a layer and a resolution hold every registered
+ * setting, in registration order. `src/config-registry.ts`, outside
+ * `packages/rafa/src/core/`, registers the fourteen sections when its
+ * `registerCoreConfigSections` is called; a process that has not called
+ * it reads no setting at all, where the
+ * literal this loop replaced held every setting whatever was registered.
+ *
+ * {@link parseConfigText} turns YAML text into one file layer and
+ * {@link resolveConfig} ranks the layers. Both are pure, so every
+ * precedence case is tested without a disk. The only read and the only
+ * place that prints are in `config-load.ts`.
+ *
+ * ## Unknown keys and unusable values
+ *
+ * The two are treated differently, and the difference is who the file
+ * was written for.
+ *
+ *   - An UNKNOWN key is retained and warned about, never refused. It
+ *     lands in {@link ConfigFile.extras} under its path (`nonesuch`,
+ *     `plan.depth`, `prerequisites.required[0].timeout`) with the value
+ *     it carried, and acts on nothing. A file written for a later phase
+ *     names keys this one has never heard of; refusing them would make
+ *     every addition to the schema a breaking change for older
+ *     installs. That is the reason `core/plan/declaration.ts` keeps an
+ *     unrecognised declaration key in its `extras`, and it holds here
+ *     unchanged. The warning lists the keys known where the unknown one
+ *     sits: the top level's, a section's, or an item's.
+ *   - An UNUSABLE value for a key this module DOES answer to is
+ *     refused with a {@link ConfigError}. `store: postgres` asks for a
+ *     backend nothing here provides, and falling back to the default
+ *     would write rows into a store other than the one the operator
+ *     named — a silent success, the failure the collector refuses an
+ *     unrecognised argument to prevent. Every problem is collected
+ *     before the throw, so one run names all of them. A section that is
+ *     not a mapping is one: `tracker: linear` is refused, where a
+ *     phase 0 file could carry it as an unknown key.
+ *
+ * A refusal that reads two settings at once is a section's `checks`
+ * (`section.ts`), since the two may come from different files:
+ * {@link resolveConfig} runs every registered section's checks once
+ * every setting is ranked and throws one {@link ConfigError} with every
+ * problem they report. The one check today is the `hub` section's,
+ * `effort.sync: service` with no `hub.url` in any layer, naming the
+ * file that chose `service`; `config-schema-hub.ts` argues it.
+ *
+ * A file is judged whole, whatever the command line says. A flag that
+ * outranks an unusable file value does not excuse it, because the next
+ * run without the flag reads it.
+ *
+ * A `null` value says nothing; it is neither a value nor a problem.
+ * YAML makes `null` of a key whose children are all commented out —
+ * `plan:` above `  # inject: full` parses to `{ plan: null }` — and
+ * refusing it would punish the commonest edit a config file receives.
+ * Three settings RESOLVE to null — `pr.provider`, `pr.base` and
+ * `roadmap.issue` — and the rule holds for them unchanged: a file naming one with no value is
+ * silent, and silence there resolves to the same null from the defaults
+ * layer, reported as `default` rather than `file`. What null means to a
+ * caller is `core-section.ts`'s and `config-schema-release.ts`'s to say.
+ *
+ * A setting's dotted path is built by joining keys, so `plan.inject`
+ * written flat at the top level reaches the same setting as `inject`
+ * nested under `plan`. Both spellings are accepted, and a file giving
+ * one setting in both is refused: they are different YAML keys, so the
+ * parser keeps both, and letting one win would be a silent choice.
+ *
+ * Every key here is looked up in the `Map` and the `Set` `section.ts`
+ * builds off the registered settings, never with `in` or an object
+ * index; the reason is argued there.
+ *
+ * ## The parser, measured on bun 1.3.14
+ *
+ * `Bun.YAML.parse` is the whole parser; the repo takes no YAML
+ * dependency. Six of its behaviours shape the rules above, each read
+ * off the parser rather than its documentation:
+ *
+ *   - An empty file, a whitespace-only one, a comment-only one and a
+ *     bare `---` all parse to `null`, and read as a file that says
+ *     nothing.
+ *   - A multi-document stream parses to a LIST of documents, which is
+ *     refused with every other top level that is not a mapping.
+ *   - A duplicated key is not an error: the last occurrence wins and
+ *     the first leaves no trace, so nothing here can warn about it.
+ *   - Malformed YAML throws a `SyntaxError` whose message carries no
+ *     line or column. The refusal names the file; it cannot name the
+ *     line.
+ *   - A child indented with a TAB parses differently by version: on
+ *     bun 1.3.14 `plan:` over a tab-indented `inject: full` parses as
+ *     `plan: null` beside a top-level `inject`, and on bun 1.4.2 it
+ *     throws `Tab characters cannot be used as indentation`. So a line
+ *     whose indentation holds a tab is refused, by line number, before
+ *     the parser sees the text, and every bun gives one answer. A blank
+ *     or comment line may carry one, and a tab inside a value parses as
+ *     the value's own on both. One cost: a block scalar line whose
+ *     content opens with a tab after its spaces is refused too.
+ *   - `yes` and `on` parse as strings, and `True` and `TRUE` as the
+ *     boolean. So a `tracking` flag spelled `yes` is refused rather
+ *     than read as true.
+ */
+import type { SettingOrigin, ShadowedFile } from './config-origins.js';
+import type { CommandLineSetting, ConfigSetting, RafaConfig } from './config-schema.js';
+import type { ConfigExtra } from './config-sections.js';
+export type { CommandLineSetting, ConfigSetting, RafaConfig, } from './config-schema.js';
+export { CONFIG_FILE } from './core-section.js';
+export type { BoardRelationshipMode, ClaimsAhead, ClaimsStaleAfter, ClaudeSettingSource, ConfigExtra, ConfigVersion, InjectMode, LessonSwitch, OutputMode, PrProvider, ReleaseEnabled, RouteTarget, SkillResolverName, StoreBackend, SyncStrategy, TierPin, TierSwitch, } from './config-sections.js';
+export { BOARD_PROJECT_TEMPLATE_DEFAULT, BOARD_RELATIONSHIP_MODES, CLAUDE_SETTING_SOURCES, CONFIG_VERSIONS, INJECT_MODES, OUTPUT_MODES, PR_PROVIDERS, RELEASE_AUTO, STORE_BACKENDS, SYNC_STRATEGIES, } from './config-sections.js';
+export type { ModuleSource, ModuleSourceKind, OptionalPrerequisiteItem, PrerequisiteItem, PrerequisiteKind, PrerequisiteScope, } from './config-items.js';
+export { MODULE_SOURCE_KINDS, PREREQUISITE_KINDS } from './config-items.js';
+/**
+ * The layer that answered a setting: the command line, the project's
+ * file, the user scope's file, or the default.
+ */
+export type ConfigSource = 'cli' | 'file' | 'user' | 'default';
+/**
+ * One layer's say on every setting: a value, or undefined for silence.
+ *
+ * Every key is REQUIRED, with undefined standing for silence, so a
+ * setting added to {@link RafaConfig} is a compile error wherever a
+ * layer is built rather than a setting some layer forgot.
+ */
+export type ConfigLayer = {
+    readonly [K in ConfigSetting]: RafaConfig[K] | undefined;
+};
+/**
+ * Command-line values as a flag parser hands them over: the raw string,
+ * or undefined when the flag was not given. {@link resolveConfig}
+ * validates them and refuses what the file would refuse, an empty
+ * string included. A key naming no {@link CommandLineSetting} is not
+ * read.
+ */
+export type ConfigOverrides = {
+    readonly [K in CommandLineSetting]?: string | undefined;
+};
+/** What one config file said. */
+export interface ConfigFile {
+    /** The file, as the caller named it. */
+    path: string;
+    /** Its value for each setting, or undefined where it said nothing. */
+    values: ConfigLayer;
+    /** Every key that names no setting and opens no section. */
+    extras: readonly ConfigExtra[];
+    /**
+     * The zero-based entry that last set each setting, for a file of
+     * several entries. Absent for a file of one, a YAML file, whose every
+     * setting is entry 0.
+     */
+    entries?: ReadonlyMap<ConfigSetting, number>;
+}
+/** The layers {@link resolveConfig} ranks, highest first. */
+export interface ConfigLayers {
+    /** Command-line values. Absent is the same as no flag given. */
+    cli?: ConfigOverrides;
+    /** The project's parsed file, or null when there is none. */
+    file?: ConfigFile | null;
+    /** The user scope's parsed file, or null when there is none. */
+    user?: ConfigFile | null;
+}
+/** Every setting resolved, with the layer each value came from. */
+export interface ResolvedConfig {
+    /** The value each setting resolved to. */
+    config: RafaConfig;
+    /** The layer that answered each setting. */
+    sources: Readonly<Record<ConfigSetting, ConfigSource>>;
+    /** The project's file consulted, or null when there was none. */
+    path: string | null;
+    /** The user scope's file consulted, or null when there was none. */
+    userPath: string | null;
+    /** The project file's unknown keys, retained. Empty with no file. */
+    extras: readonly ConfigExtra[];
+    /** The user file's unknown keys, retained. Empty with no file. */
+    userExtras: readonly ConfigExtra[];
+    /** One sentence per retained unknown key, the user file's first. */
+    warnings: readonly string[];
+    /**
+     * The file and entry that answered each setting, or null where the
+     * command line or a default did (`config-origins.ts`).
+     */
+    provenance: Readonly<Record<ConfigSetting, SettingOrigin | null>>;
+    /** The YAML files a module file of their scope left unread. Empty here; `config-load.ts` fills it. */
+    shadowed: readonly ShadowedFile[];
+}
+/**
+ * A config the loop cannot run on: unreadable, not YAML, not a
+ * mapping, or naming a value a setting does not accept.
+ *
+ * Its own class so a caller can tell a refusal it should print and
+ * exit on from a fault it should not swallow.
+ */
+export declare class ConfigError extends Error {
+    /** Every problem found, one sentence each. */
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[], options?: ErrorOptions);
+}
+/**
+ * Parses YAML into its document, refusing text that is not YAML with
+ * the file named. A tab in a line's indentation is refused before the
+ * parser sees the text, because bun's parser answers it differently by
+ * version. Judges no key: {@link readConfigDocument} does.
+ */
+export declare function parseConfigDocument(text: string, path: string): unknown;
+/** The config file's path under `root`. */
+export declare function configFilePath(root: string): string;
+/**
+ * Reads config text into one file layer. Pure: `path` only labels the
+ * layer and the refusals.
+ *
+ * Throws a {@link ConfigError} naming every problem the text has — a
+ * line indented with a tab, not YAML, not a mapping at the top, a section that is not a mapping, a
+ * setting given twice, a value a setting does not accept. An unknown
+ * key is none of these: it is retained in {@link ConfigFile.extras},
+ * the keys an item carried after the keys of the document.
+ */
+export declare function parseConfigText(text: string, path: string): ConfigFile;
+/**
+ * Reads a parsed document into one file layer, as {@link parseConfigText}
+ * reads the text it parses: null says nothing, anything but a mapping at
+ * the top is refused, and every key is judged. Pure; `path` only labels.
+ */
+export declare function readConfigDocument(parsed: unknown, path: string): ConfigFile;
+/**
+ * Ranks the layers: for each registered setting, the command line over
+ * the project's file, the project's over the user scope's, and the
+ * user's over its registered default (`activeDefaults()` in
+ * `section.ts`).
+ *
+ * Pure. Warnings come back as data — one per unknown key either file
+ * retained, the user file's first — and are never printed here. A command-line value no
+ * setting accepts throws a {@link ConfigError} naming every one, and
+ * is never downgraded to the file's value: an operator who mistyped a
+ * flag asked for something, and running on something else is the
+ * silent success the module note refuses. Every registered section's
+ * checks then run over the resolution, and any problem one reports
+ * throws a {@link ConfigError} too naming every such problem: the
+ * `hub` section's refuses `effort.sync: service` with no `hub.url` in
+ * any layer, naming the file that chose `service`.
+ */
+export declare function resolveConfig(layers?: ConfigLayers): ResolvedConfig;

package/dist/core/config/core-section.d.ts

@@ -0,0 +1,39 @@
+import type { RafaConfig, SettingSpec } from './config-schema.js';
+import type { ConfigSection } from './section.js';
+/**
+ * The config file, relative to the directory it sits under: the project
+ * root for the project's, the home directory for the user scope's.
+ *
+ * `join` rather than a literal, as `effort/store/ndjson-files.ts` spells
+ * its own directory, so a path built here compares equal to one a
+ * caller built with `join` of its own.
+ */
+export declare const CONFIG_FILE: string;
+/**
+ * The directory a scope keeps its files in, relative to the project
+ * root or the home: `.rafa`. Taken from `CONFIG_FILE`, so the two
+ * cannot name different directories.
+ */
+export declare const SCOPE_DIR: string;
+/**
+ * The name of one of core's own settings: every field `config-schema.ts`
+ * declares on `RafaConfig`, in the order problems are reported. Spelled
+ * rather than read off a value, since `isolatedDeclarations` asks every
+ * exported type to be written out.
+ */
+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';
+/** Core's section: its package, the spec and the default of each of its settings, and no check. */
+export interface CoreSection extends ConfigSection {
+    /** Each of core's settings, by name, in the order problems are reported. */
+    readonly settings: {
+        readonly [K in CoreSetting]: SettingSpec<K>;
+    };
+    /** What each of core's settings resolves to when no layer names it. */
+    readonly defaults: Readonly<Pick<RafaConfig, CoreSetting>>;
+}
+/**
+ * Core's own settings, handed in as a section: package `core`, every
+ * setting `config-schema.ts` declares with its spec and its default, and
+ * no cross-key check. Frozen, with its settings record.
+ */
+export declare const CORE_SECTION: CoreSection;

package/dist/core/config/dangerous.d.ts

@@ -0,0 +1,58 @@
+import type { ResolvedConfig } from './config.js';
+/** What a command does under each `dangerous.*` key it declares, by key. */
+export type DangerousPhrases = Readonly<Record<string, string>>;
+/**
+ * Runs `run` with `phrases` as the running command's in an async scope
+ * of its own, and answers what `run` answers; see the module note.
+ *
+ * @param phrases - The command's `dangerous` field, absent for none.
+ * @param run - The command's run.
+ * @returns What `run` answers.
+ */
+export declare function runWithDangerousPhrases<T>(phrases: DangerousPhrases | undefined, run: () => T): T;
+/**
+ * Sets `phrases` at module level; see the module note.
+ *
+ * @param phrases - The phrases to set, absent for none.
+ * @returns The module-level phrases replaced, for {@link restoreDangerousPhrases}.
+ */
+export declare function setDangerousPhrases(phrases: DangerousPhrases | undefined): DangerousPhrases;
+/**
+ * Puts back phrases {@link setDangerousPhrases} answered.
+ *
+ * @param previous - The phrases it answered.
+ */
+export declare function restoreDangerousPhrases(previous: DangerousPhrases): void;
+/**
+ * The running command's phrases: the scope's, else the module-level ones.
+ *
+ * @returns The phrases by key, empty when none is declared.
+ */
+export declare function dangerousPhrases(): DangerousPhrases;
+/**
+ * Every key of the active registry that opens with `dangerous.`, in
+ * registration order; see the module note.
+ *
+ * @returns The keys, such as `dangerous.acceptStaleRefs`; empty while
+ *   no section is registered.
+ */
+export declare function dangerousKeys(): readonly string[];
+/**
+ * One pass line per dangerous key `resolved` holds off its default; see
+ * the module note.
+ *
+ * @param resolved - A resolution `loadConfig` or `resolveConfig` answered.
+ * @returns The lines, such as
+ *   `dangerous.acceptStaleRefs: true (/repo/rafa.config.ts, entry 1)`,
+ *   each ending with `; <phrase>` for a key the running command declares.
+ */
+export declare function dangerousPassLines(resolved: ResolvedConfig): readonly string[];
+/**
+ * Writes through `warn` each of `resolved`'s pass lines not yet written
+ * for `invocation`; see the module note.
+ *
+ * @param resolved - The resolution just loaded.
+ * @param warn - The warning sink `loadConfig` writes through.
+ * @param invocation - The object one invocation is known by.
+ */
+export declare function writeDangerousPassLines(resolved: ResolvedConfig, warn: (message: string) => void, invocation: object): void;

package/dist/core/config/default-routing.d.ts

@@ -0,0 +1,16 @@
+/**
+ * rafa's routing defaults: which agent a task of each shape goes to
+ * when no config layer says otherwise.
+ *
+ * The table moved here from `src/tiers/routing.ts`, which re-exports
+ * each name, so `core-section.ts` reads {@link DEFAULT_ROUTING} without
+ * importing above core. What the rows mean, and why the map is one
+ * shared `Map` while the list is frozen, is `routing.ts`'s module note.
+ */
+import type { RouteTarget } from './config-sections.js';
+/** One default row: a task shape and the agent that takes it. */
+export type Route = readonly [shape: string, agent: string];
+/** rafa's routing table, in the order the spec lists it. */
+export declare const DEFAULT_ROUTES: readonly Route[];
+/** {@link DEFAULT_ROUTES} as the map `routing` resolves to by default. */
+export declare const DEFAULT_ROUTING: ReadonlyMap<string, RouteTarget>;

package/dist/core/config/index.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The barrel over the config's schema and its layers: every name
+ * `config-items.ts`, `config-schema.ts`, `core-section.ts`, `section.ts`,
+ * `config.ts`, `dangerous.ts`, `scope.ts` and `default-routing.ts` export, less the names the
+ * `sections.ts` barrel holds, and nothing else.
+ *
+ * A file outside `packages/rafa/src/core/` imports this file and never the eight
+ * behind it (`scripts/survey/core-barrels.ts` measures that, and
+ * `src/tests/core-barrels.sweep.test.ts` holds it against the tree). A
+ * file inside `packages/rafa/src/core/` imports the eight directly and never this
+ * file.
+ *
+ * ## The barrels hold no name in common
+ *
+ * `packages/rafa/src/core/config/` has three barrels, all listed under `CORE_BARRELS`
+ * in `scripts/survey/core-moves.ts`. `sections.ts` holds the leaf pair,
+ * `config-sections.ts` and `config-readers.ts`, with `branch-template.ts`
+ * beside it, and argues why the pair has a barrel of its own. `load.ts` holds `config-load.ts` alone, and
+ * argues the same for it. This one holds the four files that read a
+ * key or rank a layer, and `section.ts`, the contract a section file
+ * outside `packages/rafa/src/core/` is typed by, the registry it is handed to and the
+ * key indexes read off that registry. `dangerous.ts` joined it with the
+ * running command's phrases (`runWithDangerousPhrases`), which the
+ * dispatcher sets around every command. It fits neither other barrel:
+ * it imports `config-sections.ts`, so it is no leaf for `sections.ts`,
+ * and `src/index.ts` publishes `load.ts` whole, where the phrases and
+ * pass lines are no published name.
+ *
+ * `scope.ts` joined it with a scope's paths, `Scope`, the project the
+ * dispatcher resolved, `ProjectFound`, and `scopeAt`, whose walk,
+ * `resolveScope`, stays in `src/project/scope.ts`. It reads `config.ts`
+ * and `core-section.ts` by value and `config-load.ts` as a type, so it
+ * is no leaf for `sections.ts`, and `load.ts` holds `config-load.ts`
+ * alone.
+ *
+ * `config.ts` re-exports twenty-seven names of `config-sections.ts`
+ * (`InjectMode`, `OUTPUT_MODES`, `ConfigExtra` and the like), as it did
+ * before it moved. None of them is exported here: a caller outside
+ * `packages/rafa/src/core/` takes each from `sections.ts`, so a name has one barrel to
+ * be learned from. A file that used to take `ConfigError` and
+ * `OUTPUT_MODES` in one line from `config.js` now spells two lines.
+ *
+ * ## Why one barrel can hold all eight
+ *
+ * A barrel that groups a file with a file outside `packages/rafa/src/core/` that
+ * imports the barrel back by value is a runtime cycle. None of the
+ * eight files behind this one imports outward by value:
+ * `core-section.ts` reads the routing defaults from `default-routing.ts`
+ * beside it, and `src/tiers/routing.ts` imports them from this barrel by
+ * value with nothing here importing it back. No file behind it
+ * imports a section file (`src/config-schema-*.ts`), by value or as a
+ * type: `config-merged.ts`, which spread the eleven into one schema,
+ * was retired when its importers moved to `src/config-registry.ts`,
+ * `config.ts` reads every key index and runs every section's checks
+ * off `section.ts`, and `src/tests/core-config-sections.sweep.test.ts`
+ * holds the rule for every file under `packages/rafa/src/core/`. The registry imports
+ * this barrel by value and nothing here imports the registry. A section
+ * file reads its values from `sections.ts`, which imports none of the
+ * eight, and adds its fields to `RafaConfig` with a `declare module` on
+ * `config-schema.ts`, which the checker follows and which loads
+ * nothing. `config-schema.ts` and `section.ts` import types alone.
+ *
+ * Measured when the three moved: the value imports of the non-test files
+ * under `src/`, `scripts/` and `packages/` held six cycles before the
+ * move and the same six after it, none through a file of this folder,
+ * and each barrel, each of the three files and each section file loaded
+ * first in a fresh `bun` process, `SETTINGS` holding its 89 entries
+ * each time.
+ *
+ * Measured again when core's keys moved into `core-section.ts`, on bun
+ * 1.3.14: each barrel, each of the five files, `section.ts`,
+ * `src/tiers/routing.ts` and each section file loaded first in a fresh
+ * `bun` process, `SETTINGS` and `CONFIG_DEFAULTS` holding 89 entries and
+ * `CORE_SECTION` 42 each time. The control, `config-schema-hub.ts`
+ * reading `SETTINGS` off this barrel at load, threw `Cannot access
+ * 'HUB_DEFAULTS' before initialization` when loaded first.
+ *
+ * Measured again when `section.ts` joined and each section file took a
+ * `ConfigSection` of its own, on bun 1.3.14: each config barrel,
+ * `section.ts`, the since-retired `config-merged.ts`, `config.ts` and
+ * each section file loaded first in a fresh `bun` process with
+ * `SETTINGS` holding 89 entries, and core's section and the eleven
+ * merged by `mergeConfigSections` into the same 89 settings and the
+ * same defaults as `SETTINGS` and `CONFIG_DEFAULTS`, with one check.
+ *
+ * Measured again when `config-merged.ts` was retired, on bun 1.3.14:
+ * the value imports of the five files behind this one reach no section
+ * file and not the registry, and each config barrel, each of the five
+ * files, `config-load.ts`, the registry, `packages/rafa/src/effort/store/settings.ts`,
+ * `src/tiers/routing.ts`, `packages/rafa/src/core/adapters/registry.ts` and each
+ * section file loaded first in a fresh `bun` process, the registry then
+ * answering 89 registered settings and 89 defaults each time.
+ *
+ * Measured again when `dangerous.ts` joined, on bun 1.3.14: this
+ * barrel, `dangerous.ts`, `config-load.ts`, the registry,
+ * `src/cli/dispatch.ts` and `packages/rafa/src/core/command/command.ts` each loaded
+ * first in a fresh `bun` process, the registry then holding 91 settings
+ * and `dangerousKeys` three keys each time.
+ *
+ * ## What it exports
+ *
+ * Each name is spelled, types apart from values, as `sections.ts` spells
+ * its own, and taken from the file that declares it: `config.ts`
+ * re-exports `RafaConfig` from `config-schema.ts`, `CONFIG_FILE` from
+ * `core-section.ts` and the item types and kind lists from
+ * `config-items.ts`, and each is exported here once. The merged schema
+ * (`SETTINGS`, `CONFIG_DEFAULTS`, `SETTING_NAMES`, `SETTING_BY_KEY`,
+ * `SECTIONS` and `knownKeysAbove`) is not here: a file outside
+ * `packages/rafa/src/core/` imports it from `src/config-registry.ts`, and core reads
+ * the registered settings, defaults and key indexes off `section.ts`.
+ * Neither are the hub's `HubContext` and `HubTimeout`, which a file
+ * imports from `src/config-schema-hub.ts`.
+ *
+ * The published surface is narrower than this file. `src/index.ts`
+ * re-exports part of it, and of the runtime names leaves out core's
+ * section, the routing defaults, the item readers, `config.ts`'s two
+ * document readers the loader reads a scope through, and the section
+ * registry with its key indexes (`CORE_SECTION`, `moduleSource`, `registerConfigSections`,
+ * `activeSettingByKey` and twenty-eight more), which `src/index.test.ts`
+ * spells under `CONFIG_BARREL_ONLY`. Its `CONFIG_DEFAULTS` is
+ * `src/config-registry.ts`'s.
+ *
+ * `index.test.ts` holds the list to the eight files: every name any of
+ * them exports and `sections.ts` does not is here once, as the same
+ * binding, and no other name is here.
+ */
+export type { ModuleSource, ModuleSourceKind, OptionalPrerequisiteItem, PrerequisiteItem, PrerequisiteKind, PrerequisiteScope, } from './config-items.js';
+export type { CommandLineSetting, ConfigSetting, RafaConfig, SettingSpec, } from './config-schema.js';
+export type { CoreSection, CoreSetting } from './core-section.js';
+export type { ConfigCheck, ConfigCheckInput, ConfigLoadHook, ConfigSection, ConfigSectionRegistry, SettingsRecord, } from './section.js';
+export type { ConfigFile, ConfigLayer, ConfigLayers, ConfigOverrides, ConfigSource, ResolvedConfig, } from './config.js';
+export type { DangerousPhrases } from './dangerous.js';
+export type { ProjectFound, Scope } from './scope.js';
+export type { Route } from './default-routing.js';
+export { MODULE_SOURCE_KEYS, MODULE_SOURCE_KINDS, moduleSource, OPTIONAL_ITEM_KEYS, optionalPrerequisite, PREREQUISITE_KINDS, REQUIRED_ITEM_KEYS, requiredPrerequisite, } from './config-items.js';
+export { CONFIG_FILE, CORE_SECTION, SCOPE_DIR } from './core-section.js';
+export { activeChecks, activeConfigLoadHook, activeDefaults, activeKnownKeysAbove, activeSectionPaths, activeSections, activeSettingByKey, activeSettings, ConfigSectionError, EMPTY_CONFIG_REGISTRY, mergeConfigSections, registerConfigSections, restoreConfigSections, setConfigLoadHook, } from './section.js';
+export { ConfigError, configFilePath, parseConfigDocument, parseConfigText, readConfigDocument, resolveConfig, } from './config.js';
+export { dangerousKeys, dangerousPassLines, dangerousPhrases, restoreDangerousPhrases, runWithDangerousPhrases, setDangerousPhrases, writeDangerousPassLines, } from './dangerous.js';
+export { scopeAt } from './scope.js';
+export { DEFAULT_ROUTES, DEFAULT_ROUTING } from './default-routing.js';

package/dist/core/config/scope.d.ts

@@ -0,0 +1,42 @@
+/**
+ * One scope's paths, and the project the dispatcher resolved: the
+ * shapes `resolveScope` answers in `src/project/scope.ts`, and
+ * {@link scopeAt}, which builds a scope from its base directory.
+ *
+ * The walk itself, `resolveScope` with its refusals and its hint, stays
+ * in `src/project/scope.ts`, which imports these names from the config
+ * barrel and re-exports them under the same names. Core holds the
+ * shapes alone, so `RafaContext` can name the project a command runs in
+ * and the session store can find a project's `.rafa` directory without
+ * importing a file above core.
+ */
+import type { ConfigRoots } from './config-load.js';
+/** One scope's paths: its `.rafa` directory and its config file. */
+export interface Scope {
+    /** `<base>/.rafa`. */
+    readonly dir: string;
+    /**
+     * The config file. For a project found, the first of
+     * {@link CONFIG_LOOKUP} its root holds; otherwise, and for the user
+     * scope, `<base>/.rafa/config.yaml`, the file `rafa init` writes.
+     */
+    readonly configFile: string;
+}
+/**
+ * The walk found a project. The answer is the `ConfigRoots` for
+ * `loadConfig`: `root` is the project root, a real path, and `home` is
+ * the home as the caller gave it.
+ */
+export interface ProjectFound extends ConfigRoots {
+    readonly found: true;
+    /** The project scope, under `root`. */
+    readonly project: Scope;
+    /** The user scope, under `home`. */
+    readonly user: Scope;
+}
+/**
+ * The scope under `base`: `base` is a project root or a home directory.
+ * `configFile` is `file` when given, the lookup name found under
+ * `base`, and `<base>/.rafa/config.yaml` otherwise.
+ */
+export declare function scopeAt(base: string, file?: string): Scope;