@aspruyt/xfg 5.1.6 → 5.3.0

package/dist/cli/types.d.ts

@@ -44,7 +44,7 @@ export interface SyncResultEntry {
     mergeOutcome?: "manual" | "auto" | "force" | "direct";
     error?: string;
 }
-export interface SettingsResult extends Pick<BaseProcessorResult, "success" | "message" | "skipped"> {
+export interface SettingsResult extends BaseProcessorResult {
     planOutput?: {
         lines?: string[];
     };

package/dist/config/extends-resolver.d.ts

@@ -0,0 +1,13 @@
+import type { RawGroupConfig } from "./types.js";
+/**
+ * Resolves a single group's extends chain into an ordered list of group names.
+ * Parents appear before children (topological order). Detects circular extends
+ * and missing group references.
+ */
+export declare function resolveExtendsChain(groupName: string, groupDefs: Record<string, RawGroupConfig>): string[];
+/**
+ * Expands a repo's group list by resolving extends chains for each group.
+ * Returns the full ordered list with transitive parents, deduplicated.
+ * First occurrence wins for deduplication (preserves topological order).
+ */
+export declare function expandRepoGroups(repoGroups: string[], groupDefs: Record<string, RawGroupConfig>): string[];

package/dist/config/extends-resolver.js

@@ -0,0 +1,63 @@
+const MAX_EXTENDS_DEPTH = 100;
+/**
+ * Resolves a single group's extends chain into an ordered list of group names.
+ * Parents appear before children (topological order). Detects circular extends
+ * and missing group references.
+ */
+export function resolveExtendsChain(groupName, groupDefs) {
+    function walk(name, visited, depth) {
+        if (depth > MAX_EXTENDS_DEPTH) {
+            throw new Error(`Extends chain exceeds maximum depth of ${MAX_EXTENDS_DEPTH} — likely misconfigured`);
+        }
+        if (visited.has(name)) {
+            const cycle = [...visited, name].join(" -> ");
+            throw new Error(`Circular extends detected: ${cycle}`);
+        }
+        visited.add(name);
+        const group = groupDefs[name];
+        if (!group) {
+            throw new Error(`Group '${name}' referenced in extends chain does not exist`);
+        }
+        if (!group.extends) {
+            return [name];
+        }
+        const parents = Array.isArray(group.extends)
+            ? group.extends
+            : [group.extends];
+        const result = [];
+        const seen = new Set();
+        for (const parent of parents) {
+            const chain = walk(parent, new Set(visited), depth + 1);
+            for (const n of chain) {
+                if (!seen.has(n)) {
+                    seen.add(n);
+                    result.push(n);
+                }
+            }
+        }
+        if (!seen.has(name)) {
+            result.push(name);
+        }
+        return result;
+    }
+    return walk(groupName, new Set(), 0);
+}
+/**
+ * Expands a repo's group list by resolving extends chains for each group.
+ * Returns the full ordered list with transitive parents, deduplicated.
+ * First occurrence wins for deduplication (preserves topological order).
+ */
+export function expandRepoGroups(repoGroups, groupDefs) {
+    const result = [];
+    const seen = new Set();
+    for (const groupName of repoGroups) {
+        const chain = resolveExtendsChain(groupName, groupDefs);
+        for (const name of chain) {
+            if (!seen.has(name)) {
+                seen.add(name);
+                result.push(name);
+            }
+        }
+    }
+    return result;
+}

package/dist/config/index.d.ts

@@ -1,4 +1,4 @@
-export type { MergeMode, MergeStrategy, BypassActor, StatusCheckConfig, CodeScanningTool, PullRequestRuleParameters, RulesetRule, Ruleset, GitHubRepoSettings, RepoVisibility, SquashMergeCommitTitle, SquashMergeCommitMessage, MergeCommitTitle, MergeCommitMessage, Label, RepoSettings, RawFileConfig, RawRepoFileOverride, RawRepoSettings, RawRepoConfig, RawConfig, RepoConfig, Config, FileContent, ContentValue, } from "./types.js";
+export type { MergeMode, MergeStrategy, BypassActor, StatusCheckConfig, CodeScanningTool, PullRequestRuleParameters, RulesetRule, Ruleset, GitHubRepoSettings, RepoVisibility, SquashMergeCommitTitle, SquashMergeCommitMessage, MergeCommitTitle, MergeCommitMessage, Label, RepoSettings, RawFileConfig, RawRepoFileOverride, RawGroupConfig, RawRepoSettings, RawRepoConfig, RawConfig, RawConditionalGroupWhen, RawConditionalGroupConfig, RepoConfig, Config, FileContent, ContentValue, } from "./types.js";
 export { RULESET_COMPARABLE_FIELDS } from "./types.js";
 export { loadRawConfig, loadConfig, normalizeConfig } from "./loader.js";
 export { convertContentToString } from "./formatter.js";

package/dist/config/normalizer.js

@@ -1,5 +1,6 @@
 import { deepMerge, stripMergeDirectives, createMergeContext, isTextContent, mergeTextContent, } from "./merge.js";
 import { interpolateContent } from "../shared/env.js";
+import { expandRepoGroups } from "./extends-resolver.js";
 /**
  * Clone content, stripping merge directives from object content.
  * Text content is cloned as-is since it has no merge directives.
@@ -203,6 +204,47 @@ export function mergeSettings(root, perRepo) {
     }
     return Object.keys(result).length > 0 ? result : undefined;
 }
+/**
+ * Applies a single file-layer onto an accumulated file map: inherit:false clears,
+ * file:false removes entries, otherwise deep-merges content.
+ */
+function applyFileLayer(accumulated, layerFiles) {
+    const inheritFiles = shouldInherit(layerFiles);
+    if (!inheritFiles) {
+        accumulated = {};
+    }
+    for (const [fileName, fileConfig] of Object.entries(layerFiles)) {
+        if (fileName === "inherit")
+            continue;
+        if (fileConfig === false) {
+            delete accumulated[fileName];
+            continue;
+        }
+        if (fileConfig === undefined)
+            continue;
+        const existing = accumulated[fileName];
+        if (existing) {
+            const overlay = fileConfig;
+            let mergedContent;
+            if (overlay.override || !existing.content || !overlay.content) {
+                mergedContent = overlay.content ?? existing.content;
+            }
+            else {
+                mergedContent = mergeContentPair(existing.content, overlay.content, existing.mergeStrategy ?? "replace");
+            }
+            const { override: _override, ...restFileConfig } = fileConfig;
+            accumulated[fileName] = {
+                ...existing,
+                ...restFileConfig,
+                content: mergedContent,
+            };
+        }
+        else {
+            accumulated[fileName] = structuredClone(fileConfig);
+        }
+    }
+    return accumulated;
+}
 /**
  * Merges group file layers onto root files, producing an effective root file map.
  * Each group layer is processed in order: inherit:false clears accumulated,
@@ -214,45 +256,7 @@ function mergeGroupFiles(rootFiles, groupNames, groupDefs) {
         const group = groupDefs[groupName];
         if (!group?.files)
             continue;
-        const inheritFiles = shouldInherit(group.files);
-        if (!inheritFiles) {
-            // Intentionally clear: "discard everything above me"
-            accumulated = {};
-        }
-        for (const [fileName, fileConfig] of Object.entries(group.files)) {
-            if (fileName === "inherit")
-                continue;
-            // file: false removes from accumulated set
-            if (fileConfig === false) {
-                delete accumulated[fileName];
-                continue;
-            }
-            if (fileConfig === undefined)
-                continue;
-            const existing = accumulated[fileName];
-            if (existing) {
-                // Deep-merge content if both sides have object content
-                const overlay = fileConfig;
-                let mergedContent;
-                if (overlay.override || !existing.content || !overlay.content) {
-                    // override:true or one side missing content — use overlay content
-                    mergedContent = overlay.content ?? existing.content;
-                }
-                else {
-                    mergedContent = mergeContentPair(existing.content, overlay.content, existing.mergeStrategy ?? "replace");
-                }
-                const { override: _override, ...restFileConfig } = fileConfig;
-                accumulated[fileName] = {
-                    ...existing,
-                    ...restFileConfig,
-                    content: mergedContent,
-                };
-            }
-            else {
-                // New file introduced by group
-                accumulated[fileName] = structuredClone(fileConfig);
-            }
-        }
+        accumulated = applyFileLayer(accumulated, group.files);
     }
     return accumulated;
 }
@@ -358,6 +362,47 @@ function mergeGroupSettings(rootSettings, groupNames, groupDefs) {
     }
     return accumulated;
 }
+/**
+ * Evaluates a conditional group's `when` clause against a repo's effective groups.
+ * Both `allOf` (every listed group present) and `anyOf` (at least one present)
+ * must be satisfied. Absent conditions are treated as satisfied.
+ */
+function evaluateWhenClause(when, effectiveGroups) {
+    // Defensive: if neither condition is specified, don't match
+    if (!when.allOf && !when.anyOf)
+        return false;
+    const allOfSatisfied = !when.allOf || when.allOf.every((g) => effectiveGroups.has(g));
+    const anyOfSatisfied = !when.anyOf || when.anyOf.some((g) => effectiveGroups.has(g));
+    return allOfSatisfied && anyOfSatisfied;
+}
+/**
+ * Merges matching conditional groups into the accumulated files/prOptions/settings.
+ * Each matching conditional group is applied in array order, using the same
+ * merge semantics as regular group layers (inherit:false, file:false, override:true).
+ */
+function mergeConditionalGroups(accumulatedFiles, accumulatedPROptions, accumulatedSettings, effectiveGroups, conditionalGroups) {
+    let files = structuredClone(accumulatedFiles);
+    let prOptions = accumulatedPROptions
+        ? structuredClone(accumulatedPROptions)
+        : undefined;
+    let settings = accumulatedSettings;
+    for (const cg of conditionalGroups) {
+        if (!evaluateWhenClause(cg.when, effectiveGroups))
+            continue;
+        if (cg.files) {
+            files = applyFileLayer(files, cg.files);
+        }
+        // Merge prOptions
+        if (cg.prOptions) {
+            prOptions = mergePROptions(prOptions, cg.prOptions);
+        }
+        // Merge settings
+        if (cg.settings) {
+            settings = mergeRawSettings(settings, cg.settings);
+        }
+    }
+    return { files, prOptions, settings };
+}
 /**
  * Resolves a single file entry by merging root config with repo overrides.
  * Returns null if the file should be skipped.
@@ -396,16 +441,28 @@ export function normalizeConfig(raw, env) {
     const expandedRepos = [];
     for (const rawRepo of raw.repos) {
         const gitUrls = Array.isArray(rawRepo.git) ? rawRepo.git : [rawRepo.git];
-        // Resolve groups: build effective root files/prOptions/settings by merging group layers
-        const effectiveRootFiles = rawRepo.groups?.length
-            ? mergeGroupFiles(raw.files ?? {}, rawRepo.groups, raw.groups ?? {})
+        // Phase 0: Expand extends chains
+        const expandedGroups = rawRepo.groups?.length
+            ? expandRepoGroups(rawRepo.groups, raw.groups ?? {})
+            : [];
+        // Phase 1: Resolve groups - build effective root files/prOptions/settings by merging group layers
+        let effectiveRootFiles = expandedGroups.length
+            ? mergeGroupFiles(raw.files ?? {}, expandedGroups, raw.groups ?? {})
             : (raw.files ?? {});
-        const effectivePROptions = rawRepo.groups?.length
-            ? mergeGroupPROptions(raw.prOptions, rawRepo.groups, raw.groups ?? {})
+        let effectivePROptions = expandedGroups.length
+            ? mergeGroupPROptions(raw.prOptions, expandedGroups, raw.groups ?? {})
             : raw.prOptions;
-        const effectiveSettings = rawRepo.groups?.length
-            ? mergeGroupSettings(raw.settings, rawRepo.groups, raw.groups ?? {})
+        let effectiveSettings = expandedGroups.length
+            ? mergeGroupSettings(raw.settings, expandedGroups, raw.groups ?? {})
             : raw.settings;
+        // Phase 2 + 3: Evaluate and merge conditional groups
+        if (raw.conditionalGroups?.length) {
+            const effectiveGroups = new Set(expandedGroups);
+            const merged = mergeConditionalGroups(effectiveRootFiles, effectivePROptions, effectiveSettings, effectiveGroups, raw.conditionalGroups);
+            effectiveRootFiles = merged.files;
+            effectivePROptions = merged.prOptions;
+            effectiveSettings = merged.settings;
+        }
         const fileNames = Object.keys(effectiveRootFiles);
         for (const gitUrl of gitUrls) {
             const files = [];

package/dist/config/types.d.ts

@@ -292,12 +292,33 @@ export interface RawRepoFileOverride {
     deleteOrphaned?: boolean;
 }
 export interface RawGroupConfig {
+    extends?: string | string[];
     files?: Record<string, RawFileConfig | RawRepoFileOverride | false> & {
         inherit?: boolean;
     };
     prOptions?: PRMergeOptions;
     settings?: RawRepoSettings;
 }
+/** Condition for conditional group activation */
+export interface RawConditionalGroupWhen {
+    /** All listed groups must be present in the repo's effective group set */
+    allOf?: string[];
+    /** At least one listed group must be present */
+    anyOf?: string[];
+}
+/** Conditional group: activates based on which groups a repo has */
+export interface RawConditionalGroupConfig {
+    /** Condition that determines when this group activates */
+    when: RawConditionalGroupWhen;
+    /** File definitions or overrides (same capabilities as regular groups) */
+    files?: Record<string, RawFileConfig | RawRepoFileOverride | false> & {
+        inherit?: boolean;
+    };
+    /** PR merge options */
+    prOptions?: PRMergeOptions;
+    /** Repository settings (rulesets, labels, repo settings) */
+    settings?: RawRepoSettings;
+}
 export interface RawRootSettings {
     rulesets?: Record<string, Ruleset | false>;
     repo?: GitHubRepoSettings | false;
@@ -331,6 +352,7 @@ export interface RawConfig {
     id: string;
     files?: Record<string, RawFileConfig>;
     groups?: Record<string, RawGroupConfig>;
+    conditionalGroups?: RawConditionalGroupConfig[];
     repos: RawRepoConfig[];
     prOptions?: PRMergeOptions;
     prTemplate?: string;

package/dist/config/validator.js

@@ -1,3 +1,4 @@
+import { resolveExtendsChain, expandRepoGroups } from "./extends-resolver.js";
 import { isTextContent, isObjectContent, isStructuredFileExtension, validateFileName, VALID_STRATEGIES, } from "./validators/file-validator.js";
 import { validateRepoSettings } from "./validators/repo-settings-validator.js";
 import { validateRuleset } from "./validators/ruleset-validator.js";
@@ -259,6 +260,71 @@ function validatePrOptions(config) {
         }
     }
 }
+/**
+ * Validates the extends field on a single group definition.
+ * Checks type, self-reference, and that all referenced groups exist.
+ */
+function validateGroupExtends(groupName, extends_, groupNames) {
+    // Type check
+    if (typeof extends_ === "string") {
+        if (extends_.length === 0) {
+            throw new ValidationError(`groups.${groupName}: 'extends' must be a non-empty string or array of strings`);
+        }
+        // Self-reference
+        if (extends_ === groupName) {
+            throw new ValidationError(`groups.${groupName}: extends cannot reference itself`);
+        }
+        // Existence
+        if (!groupNames.has(extends_)) {
+            throw new ValidationError(`groups.${groupName}: extends references undefined group '${extends_}'`);
+        }
+    }
+    else if (Array.isArray(extends_)) {
+        if (extends_.length === 0) {
+            throw new ValidationError(`groups.${groupName}: 'extends' must be a non-empty string or array of strings`);
+        }
+        const seen = new Set();
+        for (const entry of extends_) {
+            if (typeof entry !== "string") {
+                throw new ValidationError(`groups.${groupName}: 'extends' array entries must be strings`);
+            }
+            if (entry.length === 0) {
+                throw new ValidationError(`groups.${groupName}: 'extends' array entries must be non-empty strings`);
+            }
+            if (entry === groupName) {
+                throw new ValidationError(`groups.${groupName}: extends cannot reference itself`);
+            }
+            if (!groupNames.has(entry)) {
+                throw new ValidationError(`groups.${groupName}: extends references undefined group '${entry}'`);
+            }
+            if (seen.has(entry)) {
+                throw new ValidationError(`groups.${groupName}: duplicate '${entry}' in extends`);
+            }
+            seen.add(entry);
+        }
+    }
+    else {
+        throw new ValidationError(`groups.${groupName}: 'extends' must be a non-empty string or array of strings`);
+    }
+}
+/**
+ * Detects circular extends chains across all groups.
+ * Reuses resolveExtendsChain from extends-resolver.ts to avoid
+ * duplicating the chain-walking logic. Converts thrown errors
+ * to ValidationError.
+ */
+function validateNoCircularExtends(groups) {
+    for (const name of Object.keys(groups)) {
+        if (!groups[name].extends)
+            continue;
+        try {
+            resolveExtendsChain(name, groups);
+        }
+        catch (error) {
+            throw new ValidationError(error instanceof Error ? error.message : String(error));
+        }
+    }
+}
 function validateGroups(config) {
     if (config.groups === undefined)
         return;
@@ -266,10 +332,18 @@ function validateGroups(config) {
         throw new ValidationError("groups must be an object");
     }
     const rootCtx = buildRootSettingsContext(config);
+    const groupNames = new Set(Object.keys(config.groups));
     for (const [groupName, group] of Object.entries(config.groups)) {
         if (groupName === "inherit") {
             throw new ValidationError("'inherit' is a reserved key and cannot be used as a group name");
         }
+        if (groupName === "extends") {
+            throw new ValidationError("'extends' is a reserved key and cannot be used as a group name");
+        }
+        // Validate extends field
+        if (group.extends !== undefined) {
+            validateGroupExtends(groupName, group.extends, groupNames);
+        }
         if (group.files) {
             for (const [fileName, fileConfig] of Object.entries(group.files)) {
                 if (fileName === "inherit")
@@ -285,6 +359,81 @@ function validateGroups(config) {
             validateSettings(group.settings, `groups.${groupName}`, rootCtx);
         }
     }
+    // Validate no circular extends after individual validation
+    validateNoCircularExtends(config.groups);
+}
+function validateConditionalGroups(config) {
+    if (config.conditionalGroups === undefined)
+        return;
+    if (!Array.isArray(config.conditionalGroups)) {
+        throw new ValidationError("conditionalGroups must be an array");
+    }
+    const rootCtx = buildRootSettingsContext(config);
+    const groupNames = config.groups ? Object.keys(config.groups) : [];
+    for (let i = 0; i < config.conditionalGroups.length; i++) {
+        const entry = config.conditionalGroups[i];
+        const ctx = `conditionalGroups[${i}]`;
+        // Validate 'when' clause
+        if (!entry.when || !isPlainObject(entry.when)) {
+            throw new ValidationError(`${ctx}: 'when' is required and must be an object`);
+        }
+        const { allOf, anyOf } = entry.when;
+        if (!allOf && !anyOf) {
+            throw new ValidationError(`${ctx}: 'when' must have at least one of 'allOf' or 'anyOf'`);
+        }
+        if (allOf !== undefined) {
+            if (!Array.isArray(allOf) || allOf.length === 0) {
+                throw new ValidationError(`${ctx}: 'allOf' must be a non-empty array of strings`);
+            }
+            const seen = new Set();
+            for (const name of allOf) {
+                if (typeof name !== "string") {
+                    throw new ValidationError(`${ctx}: 'allOf' entries must be strings`);
+                }
+                if (!groupNames.includes(name)) {
+                    throw new ValidationError(`${ctx}: group '${name}' in allOf is not defined in root 'groups'`);
+                }
+                if (seen.has(name)) {
+                    throw new ValidationError(`${ctx}: duplicate group '${name}' in allOf`);
+                }
+                seen.add(name);
+            }
+        }
+        if (anyOf !== undefined) {
+            if (!Array.isArray(anyOf) || anyOf.length === 0) {
+                throw new ValidationError(`${ctx}: 'anyOf' must be a non-empty array of strings`);
+            }
+            const seen = new Set();
+            for (const name of anyOf) {
+                if (typeof name !== "string") {
+                    throw new ValidationError(`${ctx}: 'anyOf' entries must be strings`);
+                }
+                if (!groupNames.includes(name)) {
+                    throw new ValidationError(`${ctx}: group '${name}' in anyOf is not defined in root 'groups'`);
+                }
+                if (seen.has(name)) {
+                    throw new ValidationError(`${ctx}: duplicate group '${name}' in anyOf`);
+                }
+                seen.add(name);
+            }
+        }
+        // Validate files
+        if (entry.files) {
+            for (const [fileName, fileConfig] of Object.entries(entry.files)) {
+                if (fileName === "inherit")
+                    continue;
+                if (fileConfig === false)
+                    continue;
+                if (fileConfig === undefined)
+                    continue;
+                validateFileConfigFields(fileConfig, fileName, `${ctx}:`);
+            }
+        }
+        // Validate settings
+        if (entry.settings !== undefined) {
+            validateSettings(entry.settings, ctx, rootCtx);
+        }
+    }
 }
 function validateRepoGitField(repo, index) {
     if (!repo.git) {
@@ -349,7 +498,8 @@ function validateRepoFiles(config, repo, index, repoLabel) {
     }
     const knownFiles = new Set(config.files ? Object.keys(config.files) : []);
     if (repo.groups && config.groups) {
-        for (const groupName of repo.groups) {
+        const expandedGroups = expandRepoGroups(repo.groups, config.groups);
+        for (const groupName of expandedGroups) {
             const group = config.groups[groupName];
             if (group?.files) {
                 for (const fn of Object.keys(group.files)) {
@@ -359,6 +509,16 @@ function validateRepoFiles(config, repo, index, repoLabel) {
             }
         }
     }
+    if (config.conditionalGroups) {
+        for (const cg of config.conditionalGroups) {
+            if (cg.files) {
+                for (const fn of Object.keys(cg.files)) {
+                    if (fn !== "inherit")
+                        knownFiles.add(fn);
+                }
+            }
+        }
+    }
     for (const fileName of Object.keys(repo.files)) {
         if (fileName === "inherit") {
             const inheritValue = repo.files.inherit;
@@ -386,7 +546,8 @@ function validateRepoSettingsEntry(config, repo, repoLabel) {
         return;
     const rootCtx = buildRootSettingsContext(config);
     if (repo.groups && config.groups) {
-        for (const groupName of repo.groups) {
+        const expandedGroups = expandRepoGroups(repo.groups, config.groups);
+        for (const groupName of expandedGroups) {
             const group = config.groups[groupName];
             if (group?.settings?.rulesets) {
                 for (const name of Object.keys(group.settings.rulesets)) {
@@ -400,6 +561,29 @@ function validateRepoSettingsEntry(config, repo, repoLabel) {
                         rootCtx.labelNames.push(name);
                 }
             }
+            if (group?.settings?.repo !== undefined &&
+                group.settings.repo !== false) {
+                rootCtx.hasRepoSettings = true;
+            }
+        }
+    }
+    if (config.conditionalGroups) {
+        for (const cg of config.conditionalGroups) {
+            if (cg.settings?.rulesets) {
+                for (const name of Object.keys(cg.settings.rulesets)) {
+                    if (name !== "inherit")
+                        rootCtx.rulesetNames.push(name);
+                }
+            }
+            if (cg.settings?.labels) {
+                for (const name of Object.keys(cg.settings.labels)) {
+                    if (name !== "inherit")
+                        rootCtx.labelNames.push(name);
+                }
+            }
+            if (cg.settings?.repo !== undefined && cg.settings.repo !== false) {
+                rootCtx.hasRepoSettings = true;
+            }
         }
     }
     validateSettings(repo.settings, `Repo ${repoLabel}`, rootCtx);
@@ -427,7 +611,20 @@ export function validateRawConfig(config) {
     const hasGrpFiles = hasGroupFiles(config);
     const hasGrpSettings = isPlainObject(config.groups) &&
         Object.values(config.groups).some((g) => g.settings && isPlainObject(g.settings));
-    if (!hasFiles && !hasSettings && !hasGrpFiles && !hasGrpSettings) {
+    const hasCondGrpFiles = Array.isArray(config.conditionalGroups) &&
+        config.conditionalGroups.some((cg) => cg.files &&
+            Object.keys(cg.files).filter((k) => k !== "inherit" && cg.files[k] !== false).length > 0);
+    const hasCondGrpSettings = Array.isArray(config.conditionalGroups) &&
+        config.conditionalGroups.some((cg) => cg.settings && isPlainObject(cg.settings));
+    const hasCondGrpPR = Array.isArray(config.conditionalGroups) &&
+        config.conditionalGroups.some((cg) => cg.prOptions && isPlainObject(cg.prOptions));
+    if (!hasFiles &&
+        !hasSettings &&
+        !hasGrpFiles &&
+        !hasGrpSettings &&
+        !hasCondGrpFiles &&
+        !hasCondGrpSettings &&
+        !hasCondGrpPR) {
         throw new ValidationError("Config requires at least one of: 'files' or 'settings'. " +
             "Use 'files' to sync configuration files, or 'settings' to manage repository settings.");
     }
@@ -443,6 +640,7 @@ export function validateRawConfig(config) {
     validateGithubHosts(config);
     validatePrOptions(config);
     validateGroups(config);
+    validateConditionalGroups(config);
     for (let i = 0; i < config.repos.length; i++) {
         validateRepoEntry(config, config.repos[i], i);
     }
@@ -461,11 +659,21 @@ export function validateForSync(config) {
     const hasRepoSettings = config.repos.some((repo) => hasActionableSettings(repo.settings));
     const hasGroupSettings = isPlainObject(config.groups) &&
         Object.values(config.groups).some((g) => g.settings && hasActionableSettings(g.settings));
+    const hasCondGrpFiles = Array.isArray(config.conditionalGroups) &&
+        config.conditionalGroups.some((cg) => cg.files &&
+            Object.keys(cg.files).filter((k) => k !== "inherit" && cg.files[k] !== false).length > 0);
+    const hasCondGrpSettings = Array.isArray(config.conditionalGroups) &&
+        config.conditionalGroups.some((cg) => cg.settings && hasActionableSettings(cg.settings));
+    const hasCondGrpPR = Array.isArray(config.conditionalGroups) &&
+        config.conditionalGroups.some((cg) => cg.prOptions && isPlainObject(cg.prOptions));
     if (!hasRootFiles &&
         !hasGrpFiles &&
         !hasSettings &&
         !hasRepoSettings &&
-        !hasGroupSettings) {
+        !hasGroupSettings &&
+        !hasCondGrpFiles &&
+        !hasCondGrpSettings &&
+        !hasCondGrpPR) {
         throw new ValidationError("Config requires at least one of: 'files' or 'settings'. " +
             "Use 'files' to sync configuration files, or 'settings' to manage repository settings.");
     }

package/dist/output/settings-report.js

@@ -1,5 +1,6 @@
 import chalk from "chalk";
 import { writeGitHubStepSummary } from "./github-summary.js";
+import { formatScalarValue } from "../shared/string-utils.js";
 /**
  * Shared recursive renderer for ruleset config objects.
  * The formatLine callback controls indentation style and coloring:
@@ -127,14 +128,9 @@ export function formatSettingsReportCLI(report) {
     return lines;
 }
 function formatValuePlain(val) {
-    if (val === null)
-        return "null";
-    if (val === undefined)
-        return "undefined";
-    if (typeof val === "string")
-        return `"${val}"`;
-    if (typeof val === "boolean")
-        return val ? "true" : "false";
+    const scalar = formatScalarValue(val);
+    if (scalar !== undefined)
+        return scalar;
     if (typeof val === "object")
         return JSON.stringify(val);
     return String(val);

package/dist/settings/base-processor.js

@@ -1,40 +1,46 @@
 import { isGitHubRepo, getRepoDisplayName } from "../shared/repo-detector.js";
 import { toErrorMessage } from "../shared/type-guards.js";
+/**
+ * Build a base result that satisfies TResult for guard early-returns.
+ * All TResult subtypes only extend BaseProcessorResult with optional fields,
+ * so a base-only object is structurally valid. If adding a new processor
+ * result type, ensure all extension fields are optional.
+ */
+function baseResult(result) {
+    return result;
+}
 /**
  * Common boilerplate for GitHub settings processors: GitHub-only gating,
  * empty settings check, token resolution, and error wrapping.
  */
 export async function withGitHubGuards(repoConfig, repoInfo, options, guards) {
     const repoName = getRepoDisplayName(repoInfo);
-    // Safe cast: all TResult subtypes (RulesetProcessorResult, LabelsProcessorResult,
-    // RepoSettingsProcessorResult) only extend BaseProcessorResult with optional fields.
-    // If adding a new processor result type, ensure all extension fields are optional.
     if (!isGitHubRepo(repoInfo)) {
-        return {
+        return baseResult({
             success: true,
             repoName,
             message: `Skipped: ${repoName} is not a GitHub repository`,
             skipped: true,
-        };
+        });
     }
     if (!guards.hasDesiredSettings(repoConfig)) {
-        return {
+        return baseResult({
             success: true,
             repoName,
             message: guards.emptySettingsMessage,
             skipped: true,
-        };
+        });
     }
     try {
         return await guards.applySettings(repoInfo, repoConfig, options, options.token, repoName);
     }
     catch (error) {
         const message = toErrorMessage(error);
-        return {
+        return baseResult({
             success: false,
             repoName,
             message: `Failed: ${message}`,
-        };
+        });
     }
 }
 /** Type predicate that narrows entries with an active (non-"unchanged") action. */

package/dist/settings/labels/diff.d.ts

@@ -29,6 +29,6 @@ export interface LabelChange {
  * @param deleteOrphaned - If true, delete current labels not in desired config
  * @param noDelete - If true, skip delete operations
  * @returns Array of changes to apply
- * @throws Error if rename collisions are detected
+ * @throws ValidationError if rename collisions are detected
  */
 export declare function diffLabels(current: GitHubLabel[], desired: Record<string, Label>, deleteOrphaned: boolean, noDelete: boolean): LabelChange[];

package/dist/settings/labels/diff.js

@@ -15,7 +15,7 @@ import { ValidationError } from "../../shared/errors.js";
  * @param deleteOrphaned - If true, delete current labels not in desired config
  * @param noDelete - If true, skip delete operations
  * @returns Array of changes to apply
- * @throws Error if rename collisions are detected
+ * @throws ValidationError if rename collisions are detected
  */
 export function diffLabels(current, desired, deleteOrphaned, noDelete) {
     const changes = [];

package/dist/settings/repo-settings/formatter.js

@@ -1,17 +1,10 @@
 import chalk from "chalk";
+import { formatScalarValue } from "../../shared/string-utils.js";
 /**
  * Format a value for display.
  */
 function formatValue(val) {
-    if (val === null)
-        return "null";
-    if (val === undefined)
-        return "undefined";
-    if (typeof val === "string")
-        return `"${val}"`;
-    if (typeof val === "boolean")
-        return val ? "true" : "false";
-    return String(val);
+    return formatScalarValue(val) ?? String(val);
 }
 /**
  * Get warning message for a property change.

package/dist/settings/rulesets/formatter.js

@@ -1,5 +1,6 @@
 import chalk from "chalk";
 import { projectToDesiredShape, normalizeRuleset, } from "./diff.js";
+import { formatScalarValue } from "../../shared/string-utils.js";
 import { computePropertyDiffs, } from "./diff-algorithm.js";
 import { isPlainObject } from "../../shared/type-guards.js";
 /**
@@ -39,12 +40,9 @@ function buildTree(diffs) {
  * Format a value for inline display (scalars and simple arrays only).
  */
 function formatValue(val) {
-    if (val === null)
-        return "null";
-    if (val === undefined)
-        return "undefined";
-    if (typeof val === "string")
-        return `"${val}"`;
+    const scalar = formatScalarValue(val);
+    if (scalar !== undefined)
+        return scalar;
     if (Array.isArray(val)) {
         if (val.every((v) => typeof v !== "object" || v === null)) {
             return `[${val.map(formatValue).join(", ")}]`;
@@ -224,10 +222,10 @@ export function formatRulesetPlan(changes) {
     for (const c of changes) {
         grouped[c.action].push(c);
     }
+    if (grouped.create.length > 0) {
+        lines.push(chalk.bold("  Create:"));
+    }
     for (const change of grouped.create) {
-        if (grouped.create.indexOf(change) === 0) {
-            lines.push(chalk.bold("  Create:"));
-        }
         lines.push(chalk.green(`    + ruleset "${change.name}"`));
         if (change.desired) {
             lines.push(...formatFullConfig(change.desired, 2));
@@ -243,10 +241,10 @@ export function formatRulesetPlan(changes) {
         });
         lines.push("");
     }
+    if (grouped.update.length > 0) {
+        lines.push(chalk.bold("  Update:"));
+    }
     for (const change of grouped.update) {
-        if (grouped.update.indexOf(change) === 0) {
-            lines.push(chalk.bold("  Update:"));
-        }
         lines.push(chalk.yellow(`    ~ ruleset "${change.name}"`));
         if (change.current && change.desired) {
             const currentNorm = normalizeRuleset(change.current);

package/dist/shared/branch-utils.d.ts

@@ -1,6 +1,6 @@
 export declare function sanitizeBranchName(fileName: string): string;
 /**
  * Validates a user-provided branch name against git's naming rules.
- * @throws Error if the branch name is invalid
+ * @throws ValidationError if the branch name is invalid
  */
 export declare function validateBranchName(branchName: string): void;

package/dist/shared/branch-utils.js

@@ -9,7 +9,7 @@ export function sanitizeBranchName(fileName) {
 }
 /**
  * Validates a user-provided branch name against git's naming rules.
- * @throws Error if the branch name is invalid
+ * @throws ValidationError if the branch name is invalid
  */
 export function validateBranchName(branchName) {
     if (!branchName || branchName.trim() === "") {

package/dist/shared/gh-api-utils.d.ts

@@ -13,6 +13,8 @@ interface GhApiCallParams {
     payload?: unknown;
     options?: GhApiOptions;
     paginate?: boolean;
+    /** Override for delay function (test injection) */
+    _retryDelay?: (ms: number) => Promise<void>;
 }
 /**
  * Get the hostname flag for gh commands.
@@ -20,6 +22,20 @@ interface GhApiCallParams {
  */
 export declare function getHostnameFlag(repoInfo: GitHubRepoInfo): string;
 export declare function buildTokenEnv(token?: string): Record<string, string> | undefined;
+/**
+ * Strips HTTP response headers from `gh api --include` output.
+ * Splits on the first blank line (LF or CRLF) and returns everything after it.
+ * If no blank line is found, returns the full string (no headers present).
+ */
+export declare function parseResponseBody(raw: string): string;
+/**
+ * Parses Retry-After header from an exec error's stdout and attaches it
+ * as error.retryAfter (number of seconds). Only extracts the numeric value
+ * to avoid leaking tokens from other headers.
+ *
+ * No-op if stdout is absent or does not contain a numeric Retry-After header.
+ */
+export declare function attachRetryAfter(error: unknown): void;
 /**
  * Encapsulates executor + retries for GitHub API calls.
  * Strategies compose with this instead of duplicating ghApi wrappers.

package/dist/shared/gh-api-utils.js

@@ -14,6 +14,40 @@ export function getHostnameFlag(repoInfo) {
 export function buildTokenEnv(token) {
     return token ? { GH_TOKEN: token } : undefined;
 }
+/**
+ * Strips HTTP response headers from `gh api --include` output.
+ * Splits on the first blank line (LF or CRLF) and returns everything after it.
+ * If no blank line is found, returns the full string (no headers present).
+ */
+export function parseResponseBody(raw) {
+    // Try CRLF first, then LF
+    const crlfIndex = raw.indexOf("\r\n\r\n");
+    if (crlfIndex !== -1) {
+        return raw.slice(crlfIndex + 4);
+    }
+    const lfIndex = raw.indexOf("\n\n");
+    if (lfIndex !== -1) {
+        return raw.slice(lfIndex + 2);
+    }
+    return raw;
+}
+/**
+ * Parses Retry-After header from an exec error's stdout and attaches it
+ * as error.retryAfter (number of seconds). Only extracts the numeric value
+ * to avoid leaking tokens from other headers.
+ *
+ * No-op if stdout is absent or does not contain a numeric Retry-After header.
+ */
+export function attachRetryAfter(error) {
+    const stdout = error.stdout;
+    if (!stdout)
+        return;
+    const stdoutStr = typeof stdout === "string" ? stdout : stdout.toString();
+    const match = stdoutStr.match(/^retry-after:\s*(\d+)\s*$/im);
+    if (match) {
+        error.retryAfter = parseInt(match[1], 10);
+    }
+}
 /**
  * Executes a GitHub API call using the gh CLI.
  * Shared by labels, rulesets, and repo-settings strategies.
@@ -30,23 +64,38 @@ async function ghApiCall(method, endpoint, opts) {
     if (paginate) {
         args.push("--paginate");
     }
+    else {
+        args.push("--include");
+    }
     if (apiOpts?.host && apiOpts.host !== "github.com") {
         args.push("--hostname", escapeShellArg(apiOpts.host));
     }
     args.push(escapeShellArg(endpoint));
     const baseCommand = args.join(" ");
     const env = buildTokenEnv(apiOpts?.token);
+    const execAndParse = async (command) => {
+        try {
+            const raw = await executor.exec(command, cwd, { env });
+            return paginate ? raw : parseResponseBody(raw);
+        }
+        catch (error) {
+            if (!paginate) {
+                attachRetryAfter(error);
+            }
+            throw error;
+        }
+    };
+    const retryOpts = {
+        retries,
+        ...(opts._retryDelay ? { _delay: opts._retryDelay } : {}),
+    };
     if (payload &&
         (method === "POST" || method === "PUT" || method === "PATCH")) {
         const payloadJson = JSON.stringify(payload);
         const command = `echo ${escapeShellArg(payloadJson)} | ${baseCommand} --input -`;
-        return await withRetry(() => executor.exec(command, cwd, { env }), {
-            retries,
-        });
+        return await withRetry(() => execAndParse(command), retryOpts);
     }
-    return await withRetry(() => executor.exec(baseCommand, cwd, { env }), {
-        retries,
-    });
+    return await withRetry(() => execAndParse(baseCommand), retryOpts);
 }
 /**
  * Encapsulates executor + retries for GitHub API calls.
@@ -61,7 +110,7 @@ export class GhApiClient {
         this.retries = retries;
         this.cwd = cwd;
     }
-    async call(method, endpoint, params) {
+    call(method, endpoint, params) {
         return ghApiCall(method, endpoint, {
             executor: this.executor,
             retries: this.retries,
@@ -69,6 +118,7 @@ export class GhApiClient {
             apiOpts: params?.options,
             payload: params?.payload,
             paginate: params?.paginate,
+            _retryDelay: params?._retryDelay,
         });
     }
 }

package/dist/shared/retry-utils.d.ts

@@ -8,6 +8,11 @@ export declare const CORE_PERMANENT_ERROR_PATTERNS: RegExp[];
  * Extends CORE_PERMANENT_ERROR_PATTERNS with git-CLI-specific patterns.
  */
 export declare const DEFAULT_PERMANENT_ERROR_PATTERNS: RegExp[];
+/**
+ * Checks if an error specifically indicates a rate limit (not just any transient error).
+ * Rate limit errors need longer backoff (60s+) compared to network errors (1-4s).
+ */
+export declare function isRateLimitError(error: unknown): boolean;
 interface RetryOptions {
     /** Maximum number of retries (default: 3) */
     retries?: number;
@@ -21,6 +26,8 @@ interface RetryOptions {
     log?: {
         info(msg: string): void;
     };
+    /** Override for delay function (test injection) */
+    _delay?: (ms: number) => Promise<void>;
 }
 /**
  * Classifies an error as permanent (should not retry) or transient (should retry).

package/dist/shared/retry-utils.js

@@ -65,6 +65,36 @@ const DEFAULT_TRANSIENT_ERROR_PATTERNS = [
     /could\s*not\s*resolve\s*host/i,
     /unable\s*to\s*access/i,
 ];
+/**
+ * Patterns that specifically indicate rate limiting (a subset of transient errors).
+ * Used to apply longer backoff delays -- connection resets and 5xx errors
+ * should NOT get 60-second waits.
+ */
+const RATE_LIMIT_PATTERNS = [
+    /rate\s*limit/i,
+    /too\s*many\s*requests/i,
+    /abuse\s*detection/i,
+];
+/**
+ * Checks if an error specifically indicates a rate limit (not just any transient error).
+ * Rate limit errors need longer backoff (60s+) compared to network errors (1-4s).
+ */
+export function isRateLimitError(error) {
+    const message = error instanceof Error ? error.message : String(error ?? "");
+    const stderr = error.stderr?.toString() ?? "";
+    const combined = `${message} ${stderr}`;
+    for (const pattern of RATE_LIMIT_PATTERNS) {
+        if (pattern.test(combined)) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Default delay (seconds) for rate limit errors when no Retry-After header is available. */
+const RATE_LIMIT_FALLBACK_DELAY_SECONDS = 60;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 /**
  * Classifies an error as permanent (should not retry) or transient (should retry).
  */
@@ -116,6 +146,7 @@ export async function withRetry(fn, options) {
         }
         catch (error) {
             if (error instanceof Error &&
+                !isTransientError(error, options?.transientErrorPatterns) &&
                 isPermanentError(error, permanentPatterns)) {
                 // Wrap in AbortError to stop retrying immediately
                 throw new AbortError(error);
@@ -124,8 +155,15 @@ export async function withRetry(fn, options) {
         }
     }, {
         retries,
-        onFailedAttempt: (context) => {
-            // Only log if this isn't the last attempt
+        onFailedAttempt: async (context) => {
+            // Apply rate-limit-specific delay before the next retry
+            if (context.retriesLeft > 0 && isRateLimitError(context.error)) {
+                const retryAfterSeconds = context.error.retryAfter ??
+                    RATE_LIMIT_FALLBACK_DELAY_SECONDS;
+                options?.log?.info(`Rate limited. Waiting ${retryAfterSeconds}s before retry...`);
+                await (options?._delay ?? delay)(retryAfterSeconds * 1000);
+            }
+            // Log the failure (existing behavior)
             if (context.retriesLeft > 0) {
                 const msg = sanitizeCredentials(context.error.message) || "Unknown error";
                 options?.log?.info(`Attempt ${context.attemptNumber}/${retries + 1} failed: ${msg}. Retrying...`);

package/dist/shared/string-utils.d.ts

@@ -2,3 +2,9 @@
  * Convert a camelCase string to snake_case.
  */
 export declare function camelToSnake(str: string): string;
+/**
+ * Format a scalar value for display: null, undefined, string, boolean.
+ * Returns undefined for non-scalar types (arrays, objects) so callers
+ * can apply domain-specific formatting.
+ */
+export declare function formatScalarValue(val: unknown): string | undefined;

package/dist/shared/string-utils.js

@@ -4,3 +4,19 @@
 export function camelToSnake(str) {
     return str.replace(/([A-Z])/g, "_$1").toLowerCase();
 }
+/**
+ * Format a scalar value for display: null, undefined, string, boolean.
+ * Returns undefined for non-scalar types (arrays, objects) so callers
+ * can apply domain-specific formatting.
+ */
+export function formatScalarValue(val) {
+    if (val === null)
+        return "null";
+    if (val === undefined)
+        return "undefined";
+    if (typeof val === "string")
+        return `"${val}"`;
+    if (typeof val === "boolean")
+        return val ? "true" : "false";
+    return undefined;
+}

package/dist/sync/auth-options-builder.d.ts

@@ -1,5 +1,5 @@
 import { RepoInfo } from "../shared/repo-detector.js";
-import { GitHubAppTokenManager } from "../vcs/github-app-token-manager.js";
+import type { GitHubAppTokenManager } from "../vcs/index.js";
 import type { AuthResult, IAuthOptionsBuilder } from "./types.js";
 import type { ILogger } from "../shared/logger.js";
 export declare class AuthOptionsBuilder implements IAuthOptionsBuilder {

package/dist/sync/repository-processor.d.ts

@@ -1,7 +1,7 @@
 import type { RepoConfig } from "../config/index.js";
 import type { RepoInfo } from "../shared/repo-detector.js";
 import type { ILogger } from "../shared/logger.js";
-import type { GitHubAppTokenManager } from "../vcs/github-app-token-manager.js";
+import type { GitHubAppTokenManager } from "../vcs/index.js";
 import type { IFileWriter, IManifestManager, IBranchManager, IAuthOptionsBuilder, IRepositorySession, ICommitPushManager, IFileSyncOrchestrator, IPRMergeHandler, ISyncWorkflow, IRepositoryProcessor, GitOpsFactory, ProcessorOptions, ProcessorResult } from "./types.js";
 /**
  * Thin facade that delegates to SyncWorkflow with FileSyncStrategy.

package/dist/vcs/git-ops.d.ts

@@ -18,7 +18,7 @@ export declare class GitOps implements ILocalGitOps {
     /**
      * Validates that a file path doesn't escape the workspace directory.
      * @returns The resolved absolute file path
-     * @throws Error if path traversal is detected
+     * @throws ValidationError if path traversal is detected
      */
     private validatePath;
     cleanWorkspace(): void;
@@ -70,7 +70,7 @@ export declare class GitOps implements ILocalGitOps {
     /**
      * Stage all changes and commit with the given message.
      * Uses --no-verify to skip pre-commit hooks (config sync should always succeed).
-     * @returns true if a commit was made, false if there were no staged changes
+     * @returns true if a commit was made (or would be made in dry-run mode), false if there were no staged changes
      */
     commit(message: string): Promise<boolean>;
     /**

package/dist/vcs/git-ops.js

@@ -20,7 +20,7 @@ export class GitOps {
     /**
      * Validates that a file path doesn't escape the workspace directory.
      * @returns The resolved absolute file path
-     * @throws Error if path traversal is detected
+     * @throws ValidationError if path traversal is detected
      */
     validatePath(fileName) {
         const filePath = join(this._workDir, fileName);
@@ -209,7 +209,7 @@ export class GitOps {
     /**
      * Stage all changes and commit with the given message.
      * Uses --no-verify to skip pre-commit hooks (config sync should always succeed).
-     * @returns true if a commit was made, false if there were no staged changes
+     * @returns true if a commit was made (or would be made in dry-run mode), false if there were no staged changes
      */
     async commit(message) {
         if (this.dryRun) {

package/dist/vcs/graphql-commit-strategy.d.ts

@@ -43,7 +43,8 @@ export declare class GraphQLCommitStrategy implements ICommitStrategy {
      * Uses the createCommitOnBranch mutation for verified commits.
      *
      * @returns Commit result with SHA and verified: true
-     * @throws Error if repo is not GitHub, payload exceeds 50MB, or API fails
+     * @throws ValidationError if repo is not GitHub or payload exceeds 50MB
+     * @throws GraphQLApiError if the API call fails
      */
     commit(options: CommitOptions): Promise<CommitResult>;
     /**

package/dist/vcs/graphql-commit-strategy.js

@@ -70,7 +70,8 @@ export class GraphQLCommitStrategy {
      * Uses the createCommitOnBranch mutation for verified commits.
      *
      * @returns Commit result with SHA and verified: true
-     * @throws Error if repo is not GitHub, payload exceeds 50MB, or API fails
+     * @throws ValidationError if repo is not GitHub or payload exceeds 50MB
+     * @throws GraphQLApiError if the API call fails
      */
     async commit(options) {
         const { repoInfo, branchName, message, fileChanges, workDir, retries = 3, token, } = options;

package/dist/vcs/index.d.ts

@@ -1,5 +1,6 @@
 export type { PRMergeConfig, FileChange, FileAction, IGitOps, ILocalGitOps, IPRStrategy, GitAuthOptions, PRResult, ICommitStrategy, } from "./types.js";
 export type { GitOpsOptions } from "./git-ops.js";
 export { createCommitStrategy, createTokenManager, } from "./commit-strategy-selector.js";
+export type { GitHubAppTokenManager } from "./github-app-token-manager.js";
 export { createPRStrategy } from "./pr-strategy-factory.js";
 export { createPR, mergePR } from "./pr-creator.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspruyt/xfg",
-  "version": "5.1.6",
+  "version": "5.3.0",
   "description": "Manage files, settings, and repositories across GitHub, Azure DevOps, and GitLab — declaratively, from a single YAML config",
   "type": "module",
   "main": "dist/index.js",
@@ -78,6 +78,7 @@
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "bottleneck": "^2.19.5",
     "c8": "^11.0.0",
     "tsx": "^4.15.0",
     "typescript": "^5.4.5"