pr-shepherd 0.60.1 → 1.0.0

package/bin/config/load.mjs

@@ -1,43 +1,41 @@
-/* eslint-disable max-lines */
 import { readFileSync, statSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";
-import { parse } from "yaml";
-import builtins from "../config.json" with { type: "json" };
+import { isScalar, parse, parseDocument } from "yaml";
 import { getEffectiveCwd } from "../execution-context.mjs";
-import { findMergeStrategies } from "./merge-command-args.mjs";
-import { parseMergeMethod } from "./merge-method.mjs";
-import { parseGithubTransport } from "../github/transport-mode.mjs";
-import { STANDARD_RULE_NAMES } from "../classify/standard/index.mjs";
-const MINIMIZE_COMMENTS_POLICIES = ["all", "bots", "users", "none"];
-const RESOLVE_OTHER_HUMAN_THREADS = ["none", "outdated", "always"];
-export const INSTRUCTION_STYLES = ["playbook", "inline"];
-export function isInstructionStyle(value) {
-    return INSTRUCTION_STYLES.some((style) => style === value);
-}
-export const POLL_MODES = ["auto", "poll", "event"];
-export function isPollMode(value) {
-    return POLL_MODES.some((mode) => mode === value);
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { configError, issueLines, resolveConfig } from "./resolve.mjs";
+import { CONFIG_VERSION, configFileSchema } from "./schema.mjs";
+/** Accepted config file names, checked in every directory from cwd up to `$HOME`. */
+const CONFIG_FILE_NAMES = [
+    ".pr-shepherdrc.yml",
+    ".pr-shepherdrc.yaml",
+    join(".pr-shepherd", "config.yml"),
+    join(".pr-shepherd", "config.yaml"),
+];
+function configFileIn(dir) {
+    const found = CONFIG_FILE_NAMES.map((name) => join(dir, name)).filter((candidate) => statSync(candidate, { throwIfNoEntry: false })?.isFile() === true);
+    if (found.length > 1) {
+        throw new ShepherdError(`multiple config files in ${dir}: ${found.join(", ")}. Keep exactly one.`, EXIT.CONFIG);
+    }
+    return found[0];
 }
-const RC_FILENAME = ".pr-shepherdrc.yml";
 /**
- * Collect `.pr-shepherdrc.yml` files from `startDir` toward `$HOME` (closest first).
- * `$HOME/.pr-shepherdrc.yml` is always included when it exists, even if cwd is
- * outside the home directory. The walk never includes the filesystem root, so a
- * `/.pr-shepherdrc.yml` cannot override the user-level file.
+ * Collect config files from `startDir` toward `$HOME` (closest first). The `$HOME` file is
+ * always included when it exists, even if cwd is outside the home directory. The walk never
+ * includes the filesystem root, so a root-level file cannot override the user-level file.
  */
-function collectRcFiles(startDir) {
+function collectConfigFiles(startDir) {
     const home = resolve(homedir());
-    const seen = new Set();
     const files = [];
+    const visited = new Set();
     const add = (dir) => {
-        const candidate = resolve(join(dir, RC_FILENAME));
-        if (seen.has(candidate))
+        if (visited.has(dir))
             return;
-        if (statSync(candidate, { throwIfNoEntry: false })?.isFile()) {
-            seen.add(candidate);
-            files.push(candidate);
-        }
+        visited.add(dir);
+        const file = configFileIn(dir);
+        if (file !== undefined)
+            files.push(file);
     };
     let current = resolve(startDir);
     while (current !== dirname(current)) {
@@ -49,432 +47,79 @@ function collectRcFiles(startDir) {
     add(home);
     return files;
 }
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 function deepMerge(base, override) {
     const result = { ...base };
-    for (const key of Object.keys(override)) {
-        const overVal = override[key];
+    for (const [key, overVal] of Object.entries(override)) {
         const baseVal = base[key];
-        if (overVal !== null &&
-            typeof overVal === "object" &&
-            !Array.isArray(overVal) &&
-            typeof baseVal === "object" &&
-            baseVal !== null &&
-            !Array.isArray(baseVal)) {
-            result[key] = deepMerge(baseVal, overVal);
-        }
-        else if (overVal !== undefined) {
-            result[key] = overVal;
-        }
+        result[key] =
+            isPlainObject(overVal) && isPlainObject(baseVal) ? deepMerge(baseVal, overVal) : overVal;
     }
     return result;
 }
-function isMinimizeCommentsPolicy(value) {
-    return MINIMIZE_COMMENTS_POLICIES.some((policy) => policy === value);
-}
-function parseMinimizeCommentsPolicy(value) {
-    if (value === "users") {
-        process.stderr.write('pr-shepherd: config: iterate.minimizeComments: "users" is deprecated and is now treated as "none".\n');
-        return "none";
-    }
-    if (isMinimizeCommentsPolicy(value))
-        return value;
-    throw new Error(`Invalid config: iterate.minimizeComments must be one of "all", "bots", "users", or "none", got ${JSON.stringify(value)}`);
-}
-function parseResolveOtherHumanThreads(value) {
-    if (typeof value === "string" &&
-        RESOLVE_OTHER_HUMAN_THREADS.includes(value)) {
-        return value;
-    }
-    throw new Error(`Invalid config: iterate.resolveOtherHumanThreads must be one of "none", "outdated", or "always", got ${JSON.stringify(value)}`);
-}
-function parseInstructionStyle(value) {
-    if (isInstructionStyle(value))
-        return value;
-    throw new Error(`Invalid config: iterate.instructions must be "playbook" or "inline", got ${JSON.stringify(value)}`);
-}
-function parseReviewOutputMaxChars(value) {
-    if (typeof value === "number" && Number.isInteger(value) && value >= 0)
-        return value;
-    throw new Error(`Invalid config: iterate.reviewOutputMaxChars must be a non-negative integer, got ${JSON.stringify(value)}`);
-}
-function parseCliCommand(value) {
-    if (!Array.isArray(value) ||
-        value.length === 0 ||
-        !value.every((arg) => typeof arg === "string" && arg.trim() !== "")) {
-        throw new Error("Invalid config: cliCommand must be a non-empty array of non-empty strings");
-    }
-    return value;
-}
-function parseBotUsernames(value) {
-    if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
-        throw new Error(`Invalid config: botUsernames must be an array of strings`);
-    }
-    return value;
-}
-function parseIgnoreChecks(value) {
-    if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
-        throw new Error(`Invalid config: ignoreChecks must be an array of strings`);
-    }
-    return value;
-}
-function parseNeverCancelRuns(value) {
-    if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
-        throw new Error(`Invalid config: actions.neverCancelRuns must be an array of strings`);
-    }
-    return value;
-}
-function parseIgnoreLogLines(value) {
-    if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
-        throw new Error(`Invalid config: checks.ignoreLogLines must be an array of strings`);
-    }
-    for (const pattern of value) {
-        try {
-            new RegExp(pattern);
-        }
-        catch {
-            throw new Error(`Invalid config: checks.ignoreLogLines contains an invalid regular expression: ${pattern}`);
-        }
-    }
-    return value;
-}
-const SHEPHERD_OWNED_MERGE_FLAGS = [
-    "--repo",
-    "-R",
-    "--auto",
-    "--disable-auto",
-    "--match-head-commit",
-    "--admin",
-    "--body-file",
-    "-F",
-    "--help",
-    "-h",
-];
-function parseMergeCommandArgs(value) {
-    if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
-        throw new Error("Invalid config: merge.commandArgs must be an array of strings");
-    }
-    for (const arg of value) {
-        if (SHEPHERD_OWNED_MERGE_FLAGS.some((flag) => arg === flag ||
-            arg.startsWith(`${flag}=`) ||
-            (flag.startsWith("-") && !flag.startsWith("--") && arg.startsWith(flag)))) {
-            throw new Error(`Invalid config: merge.commandArgs cannot include Shepherd-owned ${arg}`);
-        }
-    }
-    const strategies = findMergeStrategies(value);
-    if (strategies.length > 1) {
-        throw new Error(`Invalid config: merge.commandArgs includes multiple merge strategies: ${strategies.join(", ")}`);
-    }
-    return [...value];
-}
-function parsePollConfig(value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        throw new Error("Invalid config: poll must be a plain object");
-    }
-    const record = value;
-    const intervalSeconds = parsePollDuration(record["intervalSeconds"], "intervalSeconds");
-    const timeoutSeconds = parsePollDuration(record["timeoutSeconds"], "timeoutSeconds");
-    const debounceSeconds = parsePollDuration(record["debounceSeconds"], "debounceSeconds", true);
-    const reconcileSeconds = parsePollDuration(record["reconcileSeconds"], "reconcileSeconds", true);
-    const stackIntervalFactor = parseStackIntervalFactor(record["stackIntervalFactor"]);
-    assertAggregateIntervalFits(intervalSeconds, stackIntervalFactor);
-    const quietStatus = record["quietStatus"];
-    if (typeof quietStatus !== "boolean") {
-        throw new Error(`Invalid config: poll.quietStatus must be a boolean, got ${JSON.stringify(quietStatus)}`);
-    }
-    const mode = record["mode"];
-    if (!isPollMode(mode)) {
-        throw new Error(`Invalid config: poll.mode must be one of ${POLL_MODES.join(", ")}, got ${JSON.stringify(mode)}`);
-    }
-    return {
-        intervalSeconds,
-        stackIntervalFactor,
-        timeoutSeconds,
-        debounceSeconds,
-        quietStatus,
-        mode,
-        reconcileSeconds,
-    };
-}
-function parseStackIntervalFactor(value) {
-    if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
-        throw new Error(`Invalid config: poll.stackIntervalFactor must be a finite number greater than or equal to 1, got ${JSON.stringify(value)}`);
-    }
-    return value;
-}
-/** Largest `setTimeout` delay. A bigger aggregate sleep would clamp to ~24.8 days. */
-const MAX_POLL_INTERVAL_MS = 2 ** 31 - 1;
-function assertAggregateIntervalFits(intervalSeconds, factor) {
-    const ms = intervalSeconds * factor * 1000;
-    if (!Number.isFinite(ms) || ms > MAX_POLL_INTERVAL_MS) {
-        throw new Error(`Invalid config: poll.intervalSeconds * poll.stackIntervalFactor must be finite and at most ${MAX_POLL_INTERVAL_MS} milliseconds, got ${JSON.stringify(ms)}`);
-    }
-}
-function parsePollDuration(value, key, allowZero = false) {
-    if (typeof value !== "number" ||
-        !Number.isFinite(value) ||
-        (allowZero ? value < 0 : value <= 0)) {
-        const range = allowZero ? "a non-negative" : "a positive";
-        throw new Error(`Invalid config: poll.${key} must be ${range} finite number, got ${JSON.stringify(value)}`);
-    }
-    return value;
-}
-function parseGraphqlQuotaWarnings(value, pollIntervalSeconds) {
-    if (!Array.isArray(value)) {
-        throw new Error("Invalid config: watch.graphqlQuotaWarnings must be an array");
-    }
-    const seen = new Set();
-    const parsed = value.map((item, index) => {
-        if (item === null || typeof item !== "object" || Array.isArray(item)) {
-            throw new Error(`Invalid config: watch.graphqlQuotaWarnings[${index}] must be an object`);
-        }
-        const record = item;
-        const remainingPercent = record["remainingPercent"];
-        const pollIntervalMinutes = record["pollIntervalMinutes"];
-        const pollIntervalFactor = record["pollIntervalFactor"];
-        if (typeof remainingPercent !== "number" ||
-            !Number.isInteger(remainingPercent) ||
-            remainingPercent < 1 ||
-            remainingPercent > 100) {
-            throw new Error(`Invalid config: watch.graphqlQuotaWarnings[${index}].remainingPercent must be an integer from 1 to 100`);
-        }
-        if (pollIntervalMinutes === undefined && pollIntervalFactor === undefined) {
-            throw new Error(`Invalid config: watch.graphqlQuotaWarnings[${index}] must define pollIntervalMinutes, pollIntervalFactor, or both`);
-        }
-        if (pollIntervalMinutes !== undefined &&
-            (typeof pollIntervalMinutes !== "number" ||
-                !Number.isFinite(pollIntervalMinutes) ||
-                pollIntervalMinutes <= 0)) {
-            throw new Error(`Invalid config: watch.graphqlQuotaWarnings[${index}].pollIntervalMinutes must be a positive number`);
-        }
-        if (pollIntervalFactor !== undefined &&
-            (typeof pollIntervalFactor !== "number" ||
-                !Number.isFinite(pollIntervalFactor) ||
-                pollIntervalFactor < 1)) {
-            throw new Error(`Invalid config: watch.graphqlQuotaWarnings[${index}].pollIntervalFactor must be a number greater than or equal to 1`);
-        }
-        if (seen.has(remainingPercent)) {
-            throw new Error(`Invalid config: watch.graphqlQuotaWarnings has duplicate remainingPercent ${remainingPercent}`);
-        }
-        seen.add(remainingPercent);
-        const factorMinutes = typeof pollIntervalFactor === "number" ? (pollIntervalSeconds * pollIntervalFactor) / 60 : 0;
-        const absoluteMinutes = typeof pollIntervalMinutes === "number" ? pollIntervalMinutes : 0;
-        const resolvedPollIntervalMinutes = Math.max(absoluteMinutes, factorMinutes);
-        if (!Number.isFinite(resolvedPollIntervalMinutes)) {
-            throw new Error(`Invalid config: watch.graphqlQuotaWarnings[${index}] resolves to a non-finite poll interval`);
-        }
-        return {
-            remainingPercent,
-            pollIntervalMinutes: resolvedPollIntervalMinutes,
-        };
-    });
-    parsed.sort((left, right) => right.remainingPercent - left.remainingPercent);
-    for (let index = 1; index < parsed.length; index += 1) {
-        const previous = parsed[index - 1];
-        const current = parsed[index];
-        if (previous !== undefined &&
-            current !== undefined &&
-            current.pollIntervalMinutes < previous.pollIntervalMinutes) {
-            throw new Error("Invalid config: watch.graphqlQuotaWarnings pollIntervalMinutes must not decrease as remainingPercent decreases");
-        }
-    }
-    return parsed;
-}
-const KNOWN_CONFIG_KEYS = new Set([
-    "github",
-    "classify",
-    "cliCommand",
-    "botUsernames",
-    "ignoreChecks",
-    "iterate",
-    "poll",
-    "watch",
-    "resolve",
-    "checks",
-    "mergeStatus",
-    "merge",
-    "actions",
-]);
-const KNOWN_NESTED_KEYS = {
-    github: new Set(["transport"]),
-    iterate: new Set([
-        "fixAttemptsPerThread",
-        "stallTimeoutMinutes",
-        "minimizeApprovals",
-        "minimizeComments",
-        "behindBaseHint",
-        "resolveOtherHumanThreads",
-        "instructions",
-        "reviewOutputMaxChars",
-    ]),
-    poll: new Set([
-        "intervalSeconds",
-        "stackIntervalFactor",
-        "timeoutSeconds",
-        "debounceSeconds",
-        "quietStatus",
-        "mode",
-        "reconcileSeconds",
-    ]),
-    watch: new Set(["readyDelayMinutes", "graphqlQuotaWarnings"]),
-    resolve: new Set(["shaPoll"]),
-    checks: new Set(["ciTriggerEvents", "ignoreLogLines"]),
-    mergeStatus: new Set(["blockingReviewerLogins"]),
-    merge: new Set(["commandArgs", "method"]),
-    actions: new Set([
-        "autoMinimizeSuppressed",
-        "autoMarkReady",
-        "neverCancelRuns",
-        "workWhileQueued",
-        "autoResolveOutdated",
-        "commitSuggestions",
-    ]),
-};
-function warnUnknownConfigKeys(config) {
-    for (const key of Object.keys(config)) {
-        if (!KNOWN_CONFIG_KEYS.has(key)) {
-            process.stderr.write(`pr-shepherd: config: unknown key "${key}" ignored.\n`);
-            delete config[key];
-            continue;
-        }
-        const value = config[key];
-        const nested = KNOWN_NESTED_KEYS[key];
-        if (nested === undefined ||
-            value === null ||
-            typeof value !== "object" ||
-            Array.isArray(value)) {
-            continue;
-        }
-        for (const child of Object.keys(value)) {
-            if (!nested.has(child)) {
-                process.stderr.write(`pr-shepherd: config: unknown key "${key}.${child}" ignored.\n`);
-                delete value[child];
-            }
-        }
-    }
-}
-const rawDefaults = builtins;
-/**
- * Resolves `classify.standard` (`{ all?: boolean, <rule>?: boolean }`) to enabled rule names.
- * A named entry overrides `all`. Unknown names and non-boolean values warn and are ignored.
- */
-function parseStandardRules(classify) {
-    if (classify === null || typeof classify !== "object" || Array.isArray(classify))
-        return [];
-    const standard = classify["standard"];
-    if (standard === undefined)
-        return [];
-    if (standard === null || typeof standard !== "object" || Array.isArray(standard)) {
-        process.stderr.write("pr-shepherd: config: classify.standard must be a map of rule name to boolean; ignored.\n");
-        return [];
-    }
-    const entries = standard;
-    const flags = new Map();
-    for (const [name, value] of Object.entries(entries)) {
-        if (name !== "all" && !STANDARD_RULE_NAMES.includes(name)) {
-            process.stderr.write(`pr-shepherd: config: unknown standard classification rule "classify.standard.${name}" ignored.\n`);
-            continue;
-        }
-        if (typeof value !== "boolean") {
-            process.stderr.write(`pr-shepherd: config: classify.standard.${name} must be a boolean; ignored.\n`);
-            continue;
-        }
-        flags.set(name, value);
-    }
-    const all = flags.get("all") ?? false;
-    return STANDARD_RULE_NAMES.filter((name) => flags.get(name) ?? all).sort();
-}
-function parseConfig(value, normalizeMergeArgs = true) {
-    const config = value;
-    const github = value["github"];
-    if (github === null || typeof github !== "object" || Array.isArray(github)) {
-        throw new Error("Invalid config: github must be a plain object");
-    }
-    config.github = {
-        transport: parseGithubTransport(github["transport"] ?? "auto"),
-    };
-    config.cliCommand = parseCliCommand(config.cliCommand);
-    config.botUsernames = parseBotUsernames(config.botUsernames);
-    config.ignoreChecks = parseIgnoreChecks(config.ignoreChecks);
-    config.actions.neverCancelRuns = parseNeverCancelRuns(config.actions.neverCancelRuns);
-    if (config.merge && normalizeMergeArgs) {
-        config.merge.commandArgs = parseMergeCommandArgs(config.merge.commandArgs);
-        if (config.merge.method !== undefined)
-            config.merge.method = parseMergeMethod(config.merge.method);
-        const fromArgs = findMergeStrategies(config.merge.commandArgs)[0];
-        if (config.merge.method && fromArgs && fromArgs !== config.merge.method) {
-            throw new Error(`Invalid config: merge.method ${config.merge.method} conflicts with merge.commandArgs strategy ${fromArgs}`);
-        }
-    }
-    config.poll = parsePollConfig(config.poll);
-    config.watch.graphqlQuotaWarnings = parseGraphqlQuotaWarnings(config.watch.graphqlQuotaWarnings, config.poll.intervalSeconds);
-    config.iterate.minimizeComments = parseMinimizeCommentsPolicy(config.iterate.minimizeComments);
-    config.iterate.resolveOtherHumanThreads = parseResolveOtherHumanThreads(config.iterate.resolveOtherHumanThreads);
-    config.iterate.instructions = parseInstructionStyle(config.iterate.instructions);
-    config.iterate.reviewOutputMaxChars = parseReviewOutputMaxChars(config.iterate.reviewOutputMaxChars);
-    config.checks.ignoreLogLines = parseIgnoreLogLines(config.checks.ignoreLogLines);
-    config.standardRules = parseStandardRules(config.classify);
-    return config;
-}
-const defaults = parseConfig(structuredClone(rawDefaults), false);
-const configCache = new Map();
-function stripDeprecatedActionKeys(parsed) {
-    const rawActions = parsed.actions;
-    if (rawActions === null || typeof rawActions !== "object" || Array.isArray(rawActions))
-        return;
-    const actions = rawActions;
-    for (const key of ["autoResolveOutdated", "commitSuggestions"]) {
-        if (key in actions) {
-            process.stderr.write(`pr-shepherd: config: actions.${key} is deprecated and ignored.\n`);
-            delete actions[key];
-        }
-    }
-}
-function readRcFile(rcPath) {
+/** Parse and validate one config file without applying defaults. */
+function readConfigFile(file) {
+    let raw;
+    let text;
     try {
-        const raw = readFileSync(rcPath, "utf8");
-        const parsed = (parse(raw) ?? {});
-        stripDeprecatedActionKeys(parsed);
-        warnUnknownConfigKeys(parsed);
-        return parsed;
+        text = readFileSync(file, "utf8");
+        raw = parse(text);
     }
     catch (err) {
-        process.stderr.write(`pr-shepherd: failed to parse ${rcPath}: ${err instanceof Error ? err.message : String(err)}\n`);
-        return null;
-    }
+        throw configError(file, [err instanceof Error ? err.message : String(err)]);
+    }
+    // `parse` returns null for an empty document and for an explicit `null` or `~` scalar.
+    if (raw === null && !isExplicitNull(text))
+        raw = {};
+    if (!isPlainObject(raw))
+        throw configError(file, ["the top level must be a mapping"]);
+    // An empty file sets nothing, so it needs no version.
+    if (Object.keys(raw).length === 0)
+        return raw;
+    const version = raw["version"];
+    // A newer format may rename or add keys, so report only the version mismatch.
+    if (typeof version === "number" && Number.isInteger(version) && version > CONFIG_VERSION) {
+        throw configError(file, [
+            `\`version: ${version}\` needs a newer pr-shepherd; this release reads config version ${CONFIG_VERSION}`,
+        ]);
+    }
+    const result = configFileSchema.safeParse(raw);
+    if (!result.success) {
+        throw configError(file, result.error.issues.flatMap((issue) => issue.path.length === 1 && issue.path[0] === "version"
+            ? [versionIssue(version)]
+            : issueLines(issue, raw)));
+    }
+    return raw;
+}
+function isExplicitNull(text) {
+    const contents = parseDocument(text).contents;
+    return isScalar(contents) && contents.source !== "";
+}
+function versionIssue(version) {
+    return version === undefined
+        ? `\`version\` is required: add \`version: ${CONFIG_VERSION}\` (0.x config files have none; see docs/configuration.md#version)`
+        : `\`version\` must be ${CONFIG_VERSION}`;
 }
+const configCache = new Map();
+/**
+ * Load the config for the effective cwd: built-in defaults, then `$HOME`, then each ancestor
+ * down to cwd, closest file winning. Any invalid file throws a `ShepherdError` (exit 78).
+ */
 export function loadConfig() {
     const cwd = getEffectiveCwd();
-    if (configCache.has(cwd))
-        return configCache.get(cwd);
-    const rcPaths = collectRcFiles(cwd);
-    if (rcPaths.length === 0) {
-        configCache.set(cwd, defaults);
-        return defaults;
-    }
-    try {
-        // Farthest file first so closer directories override, ESLint-style.
-        let overlay = {};
-        let loaded = false;
-        for (const rcPath of [...rcPaths].reverse()) {
-            const parsed = readRcFile(rcPath);
-            if (parsed === null)
-                continue;
-            overlay = deepMerge(overlay, parsed);
-            loaded = true;
-        }
-        if (!loaded) {
-            configCache.set(cwd, defaults);
-            return defaults;
-        }
-        const config = parseConfig(deepMerge(structuredClone(rawDefaults), overlay));
-        configCache.set(cwd, config);
-        return config;
-    }
-    catch (err) {
-        process.stderr.write(`pr-shepherd: failed to parse ${rcPaths[0]}: ${err instanceof Error ? err.message : String(err)}\n`);
-        configCache.set(cwd, defaults);
-        return defaults;
-    }
+    const cached = configCache.get(cwd);
+    if (cached !== undefined)
+        return cached;
+    const files = collectConfigFiles(cwd);
+    // Farthest file first so closer directories override, ESLint-style.
+    let overlay = {};
+    for (const file of [...files].reverse())
+        overlay = deepMerge(overlay, readConfigFile(file));
+    const config = resolveConfig(overlay, files.length > 0 ? files.join(", ") : undefined);
+    configCache.set(cwd, config);
+    return config;
 }
 /** Reset the config cache — for use in tests that change directories. */
 export function _resetConfigCache() {

package/bin/config/merge-command-args.mjs

@@ -20,7 +20,7 @@ export function findMergeStrategies(args) {
         const assignment = longAssignment ?? shortAssignment;
         if (assignment) {
             if (assignment[2] !== "true" && assignment[2] !== "false") {
-                throw new Error(`Invalid config: merge.commandArgs strategy ${arg} must use true or false`);
+                throw new Error(`strategy ${arg} must use true or false`);
             }
             if (assignment[2] === "true") {
                 strategies.push(MERGE_STRATEGY_FLAGS.get(assignment[1]));
@@ -37,7 +37,7 @@ export function findMergeStrategies(args) {
             continue;
         }
         if (/^-[dmrs].+/.test(arg)) {
-            throw new Error(`Invalid config: merge.commandArgs cannot safely parse compound short option ${arg}; use separate flags or long options`);
+            throw new Error(`cannot safely parse compound short option ${arg}; use separate flags or long options`);
         }
     }
     return strategies;

package/bin/config/merge-method.d.mts

@@ -6,10 +6,9 @@ export interface RepositoryMergeSettings {
 }
 /** `undefined` when the query did not select repository merge settings. */
 export declare function readAllowedMergeMethods(repository: RepositoryMergeSettings | null | undefined): MergeMethod[] | undefined;
-export declare function parseMergeMethod(value: unknown): MergeMethod;
 export declare function configuredMergeMethod(merge: {
     method?: MergeMethod;
-    commandArgs?: string[];
+    "command-args": string[];
 }): MergeMethod | null;
 export declare function chooseMergeMethod(input: {
     allowed: readonly MergeMethod[] | undefined;

package/bin/config/merge-method.mjs

@@ -1,5 +1,4 @@
 import { findMergeStrategies } from "./merge-command-args.mjs";
-const MERGE_METHODS = new Set(["merge", "squash", "rebase"]);
 const METHOD_ORDER = ["merge", "squash", "rebase"];
 /** `undefined` when the query did not select repository merge settings. */
 export function readAllowedMergeMethods(repository) {
@@ -18,14 +17,8 @@ export function readAllowedMergeMethods(repository) {
         allowed.push("rebase");
     return allowed;
 }
-export function parseMergeMethod(value) {
-    if (typeof value === "string" && MERGE_METHODS.has(value)) {
-        return value;
-    }
-    throw new Error("Invalid config: merge.method must be merge, squash, or rebase");
-}
 export function configuredMergeMethod(merge) {
-    const fromArgs = findMergeStrategies(merge.commandArgs ?? [])[0];
+    const fromArgs = findMergeStrategies(merge["command-args"])[0];
     return merge.method ?? fromArgs ?? null;
 }
 export function chooseMergeMethod(input) {

package/bin/config/renames.d.mts

@@ -0,0 +1,8 @@
+type PathSegment = string | number;
+export declare function formatPath(path: readonly PathSegment[]): string;
+/**
+ * Describe one unrecognized key at `path`. Old keys get a rename hint; an unknown section is
+ * searched for renamed keys inside it before it is reported as unknown as a whole.
+ */
+export declare function describeUnknownKey(path: readonly PathSegment[], value: unknown): string[];
+export {};