@open-tomato/rafa 0.45.0 → 0.46.0

package/dist/config-schema-board-project.d.ts

@@ -0,0 +1,157 @@
+/**
+ * The five limits of the `board.project` section: how a call to the
+ * GitHub project is retried, how often a long refresh says where it is,
+ * and how its field writes are batched and spaced. Each has its field,
+ * its default, its reader and its spec here.
+ * {@link BOARD_PROJECT_SECTION} hands them to core as one
+ * `ConfigSection`, package `board-project`, and the `declare module`
+ * below adds {@link BoardProjectLimitSettings} to `RafaConfig`.
+ * {@link BoardProjectLimitsShape} holds its part of the shared
+ * `board.project` namespace, which `src/config/shape.ts` composes into
+ * `BoardProjectShape` of `ConfigShape`, the nested file shape.
+ * `config-registry.ts`'s `CONFIG_DEFAULTS` and `SETTINGS`
+ * spread the objects below right after `board.project.number`, so the
+ * order settings are reported in holds the `board.project` section
+ * together.
+ *
+ * `board.project.template` and `board.project.number` are core's, in
+ * `core/config/core-section.ts`; `config-schema-readings.ts` argues
+ * them. These five have their own module, as the `loop.wrapUp`
+ * key does, because `config-schema.ts` stood at 617 lines and
+ * `config-sections.ts` at 744, measured with `wc -l`, when they were
+ * added: five more specs and five readers would have put the readers'
+ * module within a page of the 800-line cap of `context/source.md`.
+ * `config-registry.ts` imports this file to spread it; a caller reads each
+ * setting off the resolved `RafaConfig`.
+ *
+ * ## The keys
+ *
+ * Issues #922, #923 and #900 found a refresh reading one page of a list,
+ * failing on the first network error and printing nothing while it ran.
+ * The fix reads every limit off the config, never a constant:
+ *
+ * | Key | Counts | Default | Accepts |
+ * |---|---|---|---|
+ * | `retries` | tries after a failure, per call | 3 | 1 to 10, or `false` |
+ * | `retryWaitSeconds` | the first wait; each later one doubles | 2 | 1 to 60 |
+ * | `progressSeconds` | the most time between two progress lines | 10 | 1 to 300, or `false` |
+ * | `writeBatchSize` | field writes per request | 20 | 1 to 100 |
+ * | `writePauseMs` | the pause between two write requests | 1000 | 0 to 60000 |
+ *
+ * ## The readings
+ *
+ * Four readings the plan leaves to this module:
+ *
+ *   - `false` is the one spelling of "off", and only two keys take it.
+ *     `retries: false` makes a failed call fail at once, as before the
+ *     key existed; `progressSeconds: false` drops the lines between the
+ *     start line and the end line, which stay. A wait, a batch and a
+ *     pause have no "off" that means anything: a batch of none writes
+ *     nothing, and a refresh with no waits is `retries: false`.
+ *   - `0` and a negative number are refused on every key but
+ *     `writePauseMs`, and never read as off. A number always names a
+ *     count or a time that happens, as `loop.wrapUp.retries` has it, so
+ *     a person who wrote `0` meaning "never" learns to write `false`.
+ *     `writePauseMs: 0` is a pause of no time, a number that still
+ *     happens, and is accepted: it is what a test or a project with a
+ *     generous rate limit writes.
+ *   - Each cap is the plan's, and bounds what one refresh can cost: ten
+ *     retries, the first wait at most a minute, a progress line at least
+ *     every five minutes, a hundred field writes to a request and a
+ *     pause of at most a minute. A cap is a config change away from
+ *     moving; none was measured against a GitHub limit.
+ *   - `true`, a fraction and a quoted number are refused, as every
+ *     reader in `config-sections.ts` refuses them: `true` names no
+ *     count, and reading it as the default would be a choice nobody
+ *     wrote.
+ *
+ * None is a `CommandLineSetting`, for the reason `board.project.number`
+ * gives in `config-schema-readings.ts`: every command that refreshes the
+ * project must write it the same way, which one run's flag would split.
+ */
+import type { ConfigSection, SettingSpec } from '@open-tomato/rafa/core/config';
+import type { Reader } from '@open-tomato/rafa/core/config/sections';
+declare module '@open-tomato/rafa/core/config/config-schema' {
+    /** The `board-project` section's fields, added to core's. */
+    interface RafaConfig extends BoardProjectLimitSettings {
+    }
+}
+/**
+ * The `board.project` limits a file writes, the section's part of the
+ * shared `board.project` namespace; `src/config/shape.ts` composes it
+ * into `BoardProjectShape` beside core's two keys.
+ */
+export interface BoardProjectLimitsShape {
+    readonly retries: BoardProjectRetries;
+    readonly retryWaitSeconds: number;
+    readonly progressSeconds: BoardProjectProgressSeconds;
+    readonly writeBatchSize: number;
+    readonly writePauseMs: number;
+}
+/** The fewest tries after a failure `board.project.retries` accepts as a number. */
+export declare const BOARD_PROJECT_RETRIES_MIN = 1;
+/** The most tries after a failure `board.project.retries` accepts. */
+export declare const BOARD_PROJECT_RETRIES_MAX = 10;
+/** The shortest first wait `board.project.retryWaitSeconds` accepts. */
+export declare const BOARD_PROJECT_RETRY_WAIT_MIN_SECONDS = 1;
+/** The longest first wait `board.project.retryWaitSeconds` accepts. */
+export declare const BOARD_PROJECT_RETRY_WAIT_MAX_SECONDS = 60;
+/** The shortest gap between progress lines `board.project.progressSeconds` accepts. */
+export declare const BOARD_PROJECT_PROGRESS_MIN_SECONDS = 1;
+/** The longest gap between progress lines `board.project.progressSeconds` accepts. */
+export declare const BOARD_PROJECT_PROGRESS_MAX_SECONDS = 300;
+/** The fewest field writes per request `board.project.writeBatchSize` accepts. */
+export declare const BOARD_PROJECT_WRITE_BATCH_MIN = 1;
+/** The most field writes per request `board.project.writeBatchSize` accepts. */
+export declare const BOARD_PROJECT_WRITE_BATCH_MAX = 100;
+/** The shortest pause between write requests `board.project.writePauseMs` accepts. */
+export declare const BOARD_PROJECT_WRITE_PAUSE_MIN_MS = 0;
+/** The longest pause between write requests `board.project.writePauseMs` accepts. */
+export declare const BOARD_PROJECT_WRITE_PAUSE_MAX_MS = 60000;
+/** How many times a failed project call is tried again, or `false` for never. */
+export type BoardProjectRetries = number | false;
+/** The most seconds between two progress lines, or `false` for no lines between start and end. */
+export type BoardProjectProgressSeconds = number | false;
+/** The `board.project` section's limits, resolved. */
+export interface BoardProjectLimitSettings {
+    /**
+     * The tries after a failure, per call, or `false` for none.
+     * `board.project.retries`.
+     */
+    boardProjectRetries: BoardProjectRetries;
+    /**
+     * The first wait before a retry, in seconds; each later one doubles.
+     * `board.project.retryWaitSeconds`.
+     */
+    boardProjectRetryWaitSeconds: number;
+    /**
+     * The most seconds between two progress lines, or `false` for none
+     * between the start and end lines. `board.project.progressSeconds`.
+     */
+    boardProjectProgressSeconds: BoardProjectProgressSeconds;
+    /** The field writes sent in one request. `board.project.writeBatchSize`. */
+    boardProjectWriteBatchSize: number;
+    /**
+     * The pause between two write requests, in milliseconds.
+     * `board.project.writePauseMs`.
+     */
+    boardProjectWritePauseMs: number;
+}
+/** Accepts `board.project.retries`; the module note says why `0` and `true` are refused. */
+export declare const boardProjectRetries: Reader<BoardProjectRetries>;
+/** Accepts `board.project.retryWaitSeconds`, with no `false`. */
+export declare const boardProjectRetryWaitSeconds: Reader<number>;
+/** Accepts `board.project.progressSeconds`; `false` keeps only the start and end lines. */
+export declare const boardProjectProgressSeconds: Reader<BoardProjectProgressSeconds>;
+/** Accepts `board.project.writeBatchSize`, with no `false`. */
+export declare const boardProjectWriteBatchSize: Reader<number>;
+/** Accepts `board.project.writePauseMs`, `0` among them, with no `false`. */
+export declare const boardProjectWritePauseMs: Reader<number>;
+/** What the `board.project` limits resolve to when no layer names them. */
+export declare const BOARD_PROJECT_LIMIT_DEFAULTS: Readonly<BoardProjectLimitSettings>;
+/** The `board.project` limits' setting specs. */
+export declare const BOARD_PROJECT_LIMIT_SETTINGS: {
+    readonly [K in keyof BoardProjectLimitSettings]: SettingSpec<K>;
+};
+/** The `board-project` section: the five `board.project` limits, with their defaults and no check. */
+export declare const BOARD_PROJECT_SECTION: ConfigSection;

package/dist/config-schema-bugs.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The `bugs` section of the config schema: `bugs.recheck.runs` and
+ * `bugs.recheck.timeoutSeconds`, the two numbers `rafa bug recheck`
+ * (#953) reads. {@link BUGS_SECTION} hands them to core as one
+ * `ConfigSection`, package `bugs`, and the `declare module` below adds
+ * {@link BugsSettings} to `RafaConfig`. {@link BugsShape} holds the keys
+ * a file writes, which `src/config/shape.ts` composes into
+ * `ConfigShape`, the nested file shape. `config-registry.ts` lists the
+ * section right after the `errors` section, and its `CONFIG_DEFAULTS`
+ * and `SETTINGS` spread the objects below right after the `errors` ones.
+ *
+ * ## The keys
+ *
+ * - `bugs.recheck.runs` is how many FURTHER runs recheck makes after a
+ *   first run that passed, to tell a bug that is gone from a flaky one:
+ *   a whole number from 1 to 20, default 5. A first run that failed or
+ *   judged nothing ends the bug's runs, so this count is never spent on
+ *   it.
+ * - `bugs.recheck.timeoutSeconds` is the deadline of one run, in
+ *   seconds: a whole number from 1 to 3600, default 300. A run that
+ *   passes it is a failed run.
+ *
+ * Each reader refuses `0`, a negative number, a fraction, a quoted
+ * number, `true` and `false` and a value above its cap, naming the
+ * range: neither key has an "off" spelling, since recheck with no
+ * further run, or with no deadline, is a recheck nobody asked for.
+ * Neither key is a `CommandLineSetting`.
+ */
+import type { ConfigSection, SettingSpec } from '@open-tomato/rafa/core/config';
+import type { Reader } from '@open-tomato/rafa/core/config/sections';
+declare module '@open-tomato/rafa/core/config/config-schema' {
+    /** The `bugs` section's fields, added to core's. */
+    interface RafaConfig extends BugsSettings {
+    }
+}
+/** The `bugs` keys a file writes; `src/config/shape.ts` composes them into `ConfigShape`. */
+export interface BugsShape {
+    readonly bugs: {
+        readonly recheck: {
+            readonly runs: number;
+            readonly timeoutSeconds: number;
+        };
+    };
+}
+/** The `bugs` settings, resolved. */
+export interface BugsSettings {
+    /** `bugs.recheck.runs`: the further runs after a first pass. */
+    bugsRecheckRuns: number;
+    /** `bugs.recheck.timeoutSeconds`: one run's deadline, in seconds. */
+    bugsRecheckTimeoutSeconds: number;
+}
+/** The fewest further runs `bugs.recheck.runs` accepts. */
+export declare const BUGS_RECHECK_RUNS_MIN = 1;
+/** The most further runs `bugs.recheck.runs` accepts. */
+export declare const BUGS_RECHECK_RUNS_MAX = 20;
+/** The shortest deadline `bugs.recheck.timeoutSeconds` accepts. */
+export declare const BUGS_RECHECK_TIMEOUT_MIN = 1;
+/** The longest deadline `bugs.recheck.timeoutSeconds` accepts: an hour. */
+export declare const BUGS_RECHECK_TIMEOUT_MAX = 3600;
+/** Reads `bugs.recheck.runs`. */
+export declare const bugsRecheckRuns: Reader<number>;
+/** Reads `bugs.recheck.timeoutSeconds`. */
+export declare const bugsRecheckTimeoutSeconds: Reader<number>;
+/** What the `bugs` settings resolve to when no layer names them. */
+export declare const BUGS_DEFAULTS: Readonly<BugsSettings>;
+/** Every `bugs` setting. */
+export declare const BUGS_SETTINGS: {
+    readonly [K in keyof BugsSettings]: SettingSpec<K>;
+};
+/** The `bugs` section: `bugs.recheck.runs` and `bugs.recheck.timeoutSeconds`, with their defaults and no check. */
+export declare const BUGS_SECTION: ConfigSection;

package/dist/config-schema-errors.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The `errors` section of the config schema: `errors.codes`, the cause
+ * codes a project adds to rafa's list (#949). {@link ERRORS_SECTION}
+ * hands it to core as one `ConfigSection`, package `errors`, and the
+ * `declare module` below adds {@link ErrorsSettings} to `RafaConfig`.
+ * {@link ErrorsShape} holds the keys a file writes, which
+ * `src/config/shape.ts` composes into `ConfigShape`, the nested file shape.
+ * `config-registry.ts`'s `CONFIG_DEFAULTS` and `SETTINGS`
+ * spread the objects below right after the `release` section. It has its
+ * own module because `config-schema.ts` stood at 643 lines and
+ * `config-sections.ts` at 744 when it was added.
+ *
+ * Each entry is read with the same rules `defineErrorCodes`
+ * (`packages/rafa/src/errors/codes.ts`) applies to rafa's list, except
+ * that `since` may be left out: a project often has no version to name.
+ * Then the list as a
+ * whole is checked: a code given twice, or one rafa already declares, is
+ * refused with both places named, so neither meaning wins silently. An
+ * unknown key inside an entry is kept and warned about, as every other
+ * list of mappings does.
+ */
+import type { ConfigSection, SettingSpec } from '@open-tomato/rafa/core/config';
+import type { ErrorCodeEntry } from '@open-tomato/rafa/errors/codes';
+declare module '@open-tomato/rafa/core/config/config-schema' {
+    /** The `errors` section's fields, added to core's. */
+    interface RafaConfig extends ErrorsSettings {
+    }
+}
+/** The `errors` keys a file writes; `src/config/shape.ts` composes them into `ConfigShape`. */
+export interface ErrorsShape {
+    readonly errors: {
+        readonly codes: readonly ErrorCodeFileItem[];
+    };
+}
+/** One `errors.codes` entry as a file writes it, `since` left out or null. */
+type ErrorCodeFileItem = Pick<ErrorCodeEntry, 'code' | 'description' | 'hint' | 'level'> & {
+    readonly since?: string | null;
+};
+/** The `errors` settings. */
+export interface ErrorsSettings {
+    /** `errors.codes`: the project's own cause codes. */
+    errorsCodes: readonly ErrorCodeEntry[];
+}
+/** The keys one entry reads. */
+export declare const ERROR_CODE_KEYS: readonly ["code", "description", "hint", "level", "since"];
+/** No project codes. */
+export declare const ERRORS_DEFAULTS: Readonly<ErrorsSettings>;
+/** Every `errors` setting. */
+export declare const ERRORS_SETTINGS: {
+    readonly [K in keyof ErrorsSettings]: SettingSpec<K>;
+};
+/** The `errors` section: `errors.codes`, with their defaults and no check. */
+export declare const ERRORS_SECTION: ConfigSection;
+export {};

package/dist/config-schema-features.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The `features` section of the config schema: four switches, one per
+ * bundled feature, each saying whether that feature's commands are
+ * loaded for the invocation. {@link FEATURES_SECTION} hands them to core
+ * as one `ConfigSection`, package `features`, and the `declare module`
+ * below adds {@link FeaturesSettings} to `RafaConfig`.
+ * {@link FeaturesShape} holds the keys a file writes, which
+ * `src/config/shape.ts` composes into `ConfigShape`, the nested file
+ * shape. `config-registry.ts` registers the section fourteenth in
+ * `CONFIG_SECTIONS`, and its `CONFIG_DEFAULTS` and `SETTINGS` spread the
+ * objects below last, after the `tests` section.
+ *
+ * ## The keys
+ *
+ * `features.board`, `features.pr`, `features.run` and `features.release`
+ * each name one bundled feature by its name. Each is read with core's
+ * `flag`, so it takes `true` or `false` and refuses anything else, a
+ * quoted `"false"` included, naming the key. Each defaults to `true`: a
+ * project that names no feature loads every bundled one, as it did
+ * before the section existed. None is a `CommandLineSetting`.
+ *
+ * The section holds the switches and nothing that reads them: what a
+ * `false` turns off is the loader's (`src/modules/load.ts`), which reads
+ * these settings off the resolved `RafaConfig`.
+ */
+import type { ConfigSection, SettingSpec } from '@open-tomato/rafa/core/config';
+declare module '@open-tomato/rafa/core/config/config-schema' {
+    /** The `features` section's fields, added to core's. */
+    interface RafaConfig extends FeaturesSettings {
+    }
+}
+/** The `features` keys as a file writes them. */
+export interface FeaturesShape {
+    /** The `features` keys, each `true` or `false`. */
+    readonly features: {
+        /** `features.board`: whether the board feature's commands load. */
+        readonly board: boolean;
+        /** `features.pr`: whether the pull-request feature's commands load. */
+        readonly pr: boolean;
+        /** `features.run`: whether the run feature's commands load. */
+        readonly run: boolean;
+        /** `features.release`: whether the release feature's commands load. */
+        readonly release: boolean;
+    };
+}
+/** The `features` section's settings, resolved. */
+export interface FeaturesSettings {
+    /** Whether the board feature's commands load. `features.board`. */
+    featuresBoard: boolean;
+    /** Whether the pull-request feature's commands load. `features.pr`. */
+    featuresPr: boolean;
+    /** Whether the run feature's commands load. `features.run`. */
+    featuresRun: boolean;
+    /** Whether the release feature's commands load. `features.release`. */
+    featuresRelease: boolean;
+}
+/** What the `features` settings resolve to when no layer names them: every feature on. */
+export declare const FEATURES_DEFAULTS: Readonly<FeaturesSettings>;
+/** The `features` section's setting specs, in the order they are reported. */
+export declare const FEATURES_SETTINGS: {
+    readonly [K in keyof FeaturesSettings]: SettingSpec<K>;
+};
+/** The `features` section: the four switches, with their defaults and no check. */
+export declare const FEATURES_SECTION: ConfigSection;

package/dist/config-schema-hub.d.ts

@@ -0,0 +1,150 @@
+/**
+ * The `hub` section of the config schema: the three keys a device reads
+ * to reach a `rafa-hub` under `effort.sync: service`, each with its
+ * field, its default, its spec and its reader, the one refusal that
+ * reads two settings at once, and the {@link HubContext} an adapter is
+ * handed. {@link HUB_SECTION} hands them to core as one `ConfigSection`,
+ * package `hub`, with {@link hubUrlProblems} as its check, and the
+ * `declare module` below adds {@link HubSettings} to `RafaConfig`.
+ * {@link HubShape} holds the keys a file writes, which
+ * `src/config/shape.ts` composes into `ConfigShape`, the nested file shape.
+ * `config-registry.ts`'s `CONFIG_DEFAULTS` and `SETTINGS`
+ * spread {@link HUB_DEFAULTS} and {@link HUB_SETTINGS} right after
+ * `effort.sync`, the setting they serve, as `config-schema-release.ts`'s
+ * sections are spread.
+ *
+ * The section sits in a module of its own, readers included, for the
+ * reason `config-schema-release.ts` and `config-readers.ts` give: measured
+ * with `wc -l` when it was added, `config-schema.ts` stood at 554 lines
+ * and `config-sections.ts` at 699, so the value rules here would have
+ * pushed the second against the 800-line cap of `context/source.md`.
+ * Every rule `config.ts` and `section.ts` state about a KEY holds here, as every
+ * rule `config-sections.ts` states about a VALUE does: nothing is
+ * coerced, and a string spelled like a number is refused.
+ *
+ * ## The keys
+ *
+ * `.rafa/specs/rafa-325-rafa-hub.md` names them: `hub.url` (required with
+ * `effort.sync: service`), `hub.tokenSecret` (the secret store name of
+ * the token, never the token) and `hub.timeout` (default `3s`, from `1s`
+ * to `30s`, `0` and negative values refused). The server's keys,
+ * `hub.repository`, `hub.port`, `hub.storePath` and `hub.auth.cacheFor`,
+ * are read by `packages/rafa-hub/` from its own file and are not keys
+ * here: in a project's file they are unknown keys, warned about and
+ * acted on by nothing. Five readings the spec leaves to this module:
+ *
+ *   - `hub.url` and `hub.tokenSecret` default to NULL, meaning "nobody
+ *     has said", as `pr.base` does: no default address or secret name
+ *     is one this module could spell for every team.
+ *   - `hub.url` is an absolute `http:` or `https:` URL, kept as written,
+ *     and one carrying a user name or password is refused: a token
+ *     written into the URL is a token in the config, which the spec
+ *     forbids, and it would reach every log line naming the hub.
+ *   - `hub.tokenSecret` is any name holding a character other than
+ *     whitespace. Whether the secret store holds it is the `service`
+ *     module's question when it reads the token, not the config's.
+ *   - `hub.timeout` is whole digits then `s`, as `claims.staleAfter` is
+ *     whole digits then a unit: `2.5s`, `3000ms`, `3S`, ` 3s` and the
+ *     bare number `3`, which names no unit, are refused, and so are
+ *     `0s`, anything below `1s` and anything above `30s`. It is kept as
+ *     written, and {@link hubTimeoutMs} answers the milliseconds it
+ *     spells.
+ *   - None is a `CommandLineSetting`, for the reason the `pr` section
+ *     gives in `config-schema-release.ts`.
+ *
+ * ## The refusal across two settings
+ *
+ * A missing `hub.url` is refused only under `effort.sync: service`, and
+ * the two may come from different files: a user scope naming the hub
+ * for every project and a project choosing `service` is the layout the
+ * spec's README section describes. So no single file can be refused for
+ * it, and {@link hubUrlProblems} is the section's check: `resolveConfig`
+ * asks it once every setting is ranked, and it names the file that chose
+ * `service`. Every other
+ * strategy reads no `hub` key, so a `hub.url` beside `local` is kept and
+ * never refused: switching strategy is then a one-line edit.
+ *
+ * ## The adapter's context
+ *
+ * {@link hubContextOf} turns the resolved settings into the
+ * {@link HubContext} `selectSync` hands a `sync` adapter as
+ * `AdapterContext.hub`, the timeout already in milliseconds. It answers
+ * undefined with no `hub.url`, since a hub with no address is none an
+ * adapter could reach; the refusal above keeps that from happening
+ * under `service`.
+ */
+import type { ConfigCheckInput, ConfigSection, SettingSpec } from '@open-tomato/rafa/core/config';
+import type { Reader } from '@open-tomato/rafa/core/config/sections';
+declare module '@open-tomato/rafa/core/config/config-schema' {
+    /** The `hub` section's fields, added to core's. */
+    interface RafaConfig extends HubSettings {
+    }
+}
+/** The `hub` keys a file writes; `src/config/shape.ts` composes them into `ConfigShape`. */
+export interface HubShape {
+    readonly hub: {
+        readonly url: string;
+        readonly tokenSecret: string;
+        readonly timeout: HubTimeout;
+    };
+}
+/** The shortest `hub.timeout` accepted, in seconds. */
+export declare const HUB_TIMEOUT_MIN_SECONDS = 1;
+/** The longest `hub.timeout` accepted, in seconds. */
+export declare const HUB_TIMEOUT_MAX_SECONDS = 30;
+/** What `hub.timeout` takes: whole seconds, spelled as written (`3s`). */
+export type HubTimeout = `${number}s`;
+/** The `hub` section's settings, resolved. */
+export interface HubSettings {
+    /**
+     * The address of the hub a `service` sync reaches, or null when
+     * nobody has said. `hub.url`.
+     */
+    hubUrl: string | null;
+    /**
+     * The name the hub token is stored under in the secret store, never
+     * the token, or null when nobody has said. `hub.tokenSecret`.
+     */
+    hubTokenSecret: string | null;
+    /** How long one request to the hub may take. `hub.timeout`. */
+    hubTimeout: HubTimeout;
+}
+/** The `hub` section's defaults. */
+export declare const HUB_DEFAULTS: Readonly<HubSettings>;
+/**
+ * The milliseconds a `hub.timeout` spells (`3s` → 3000), or null for
+ * anything else, `0s` and a value outside the range included.
+ */
+export declare function hubTimeoutMs(raw: unknown): number | null;
+/** Accepts a hub timeout of whole seconds in range, kept as written; see the module note. */
+export declare const hubTimeout: Reader<HubTimeout>;
+/** Accepts the hub's address, kept as written; see the module note. */
+export declare const hubUrl: Reader<string>;
+/** The `hub` section's specs, spread into `SETTINGS`. */
+export declare const HUB_SETTINGS: {
+    readonly [K in keyof HubSettings]: SettingSpec<K>;
+};
+/**
+ * The `hub` section's check: the refusal of a `service` sync with no
+ * `hub.url` in any layer, as a list of one sentence, or an empty list;
+ * see the module note.
+ */
+export declare function hubUrlProblems(input: ConfigCheckInput): readonly string[];
+/** The `hub` section: its three settings, their defaults, and {@link hubUrlProblems}. */
+export declare const HUB_SECTION: ConfigSection;
+/** The hub a `sync` adapter reaches, as `AdapterContext.hub` carries it. */
+export interface HubContext {
+    /** The hub's address: the resolved `hub.url`. */
+    readonly url: string;
+    /** The secret store name of the token, or null: the resolved `hub.tokenSecret`. */
+    readonly tokenSecret: string | null;
+    /** How long one request may take, in milliseconds: the resolved `hub.timeout`. */
+    readonly timeoutMs: number;
+}
+/**
+ * The {@link HubContext} the resolved settings name, frozen, or
+ * undefined when `hub.url` is null or left out. A `hub.timeout` left out
+ * is read as its default, and one the reader would refuse throws a
+ * `TypeError`: only a config built by hand can carry one.
+ */
+export declare function hubContextOf(config: Partial<HubSettings>): HubContext | undefined;

package/dist/config-schema-issues.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The `issues` section of the config schema: the five keys a bug record
+ * is filed and listed with (#951), each one's field, its default, its
+ * spec and its reader. {@link ISSUES_SECTION} hands them to core as one
+ * `ConfigSection`, package `issues`, and the `declare module` below adds
+ * {@link IssuesConfigSettings} to `RafaConfig`.
+ * {@link IssuesShape} holds the keys a file writes, which
+ * `src/config/shape.ts` composes into `ConfigShape`, the nested file shape.
+ * `config-registry.ts`'s `CONFIG_DEFAULTS` and `SETTINGS`
+ * spread the objects below right after the `logger` section. It has its
+ * own module for the reason `config-schema-errors.ts` gives.
+ *
+ * ## The keys
+ *
+ *   - `issues.titles.bug` is the template a bug's title is rendered
+ *     with and read back by (`bugs/title.ts`). It is refused at load
+ *     when it cannot be parsed, when its summary is not the last
+ *     variable outside every group, and when a title it renders does not
+ *     read back as the fields it was rendered from, so `rafa issue list
+ *     --type=bug` can always split a title this project filed.
+ *   - `issues.titles.summaryMax` is the most characters a bug's summary
+ *     holds, from {@link SUMMARY_MAX_FLOOR} to
+ *     {@link SUMMARY_MAX_CEILING}, the cap triage cuts a whole title to.
+ *   - `issues.environments` adds places to `local`, `ci` and `prod`,
+ *     such as `staging`. A place names where a bug was seen, never what
+ *     was running.
+ *   - `issues.vocabulary.modules` and `issues.vocabulary.actions` are the
+ *     names a bug may carry. Empty, the default, accepts any name of the
+ *     shape; set, a name outside the list is refused with the closest
+ *     ones shown, so one module is never filed under three spellings.
+ *
+ * `titles` holds one template: a bug is the only type whose title rafa
+ * renders. Another type's key arrives with the code that renders it.
+ *
+ * ## When they take effect
+ *
+ * At each `rafa issue create --type=bug`, which checks the record
+ * against {@link bugRulesOf}, and each `rafa issue list --type=bug`,
+ * which reads the titles back with the template.
+ *
+ * None of the keys is a `CommandLineSetting`: a line's own flags name
+ * the fields of one bug, and the rules they are held to are the
+ * project's.
+ */
+import type { BugRules } from './bugs/record.js';
+import type { ErrorsSettings } from './config-schema-errors.js';
+import type { ConfigSection, SettingSpec } from '@open-tomato/rafa/core/config';
+declare module '@open-tomato/rafa/core/config/config-schema' {
+    /** The `issues` section's fields, added to core's. */
+    interface RafaConfig extends IssuesConfigSettings {
+    }
+}
+/** The `issues` keys a file writes; `src/config/shape.ts` composes them into `ConfigShape`. */
+export interface IssuesShape {
+    readonly issues: {
+        readonly titles: {
+            readonly bug: string;
+            readonly summaryMax: number;
+        };
+        readonly environments: readonly string[];
+        readonly vocabulary: {
+            readonly modules: readonly string[];
+            readonly actions: readonly string[];
+        };
+    };
+}
+/** The `issues` settings. */
+export interface IssuesConfigSettings {
+    /** The template a bug's title is rendered with. `issues.titles.bug`. */
+    issuesTitleBug: string;
+    /** The most characters a bug's summary holds. `issues.titles.summaryMax`. */
+    issuesSummaryMax: number;
+    /** Places beside local, ci and prod. `issues.environments`. */
+    issuesEnvironments: readonly string[];
+    /** The module names a bug may carry; empty for any. `issues.vocabulary.modules`. */
+    issuesVocabularyModules: readonly string[];
+    /** The actions a bug may carry; empty for any. `issues.vocabulary.actions`. */
+    issuesVocabularyActions: readonly string[];
+}
+/** The summary cap when the config names none. */
+export declare const SUMMARY_MAX_DEFAULT = 80;
+/** The fewest characters `issues.titles.summaryMax` accepts. */
+export declare const SUMMARY_MAX_FLOOR = 20;
+/** The most characters `issues.titles.summaryMax` accepts: triage's cap on a whole title. */
+export declare const SUMMARY_MAX_CEILING = 120;
+/** The defaults: the default template, its cap, no added place and no vocabulary. */
+export declare const ISSUES_DEFAULTS: Readonly<IssuesConfigSettings>;
+/** Every `issues` setting. */
+export declare const ISSUES_SETTINGS: {
+    readonly [K in keyof IssuesConfigSettings]: SettingSpec<K>;
+};
+/** The `issues` section: the five `issues` keys, with their defaults and no check. */
+export declare const ISSUES_SECTION: ConfigSection;
+/** The rules a bug record is checked against, from a resolved config; see the module note. */
+export declare function bugRulesOf(config: IssuesConfigSettings & ErrorsSettings): BugRules;