@aspruyt/xfg 6.0.3 → 6.2.0

package/dist/config/formatter.js

@@ -42,6 +42,11 @@ function buildCommentOnlyYaml(header, schemaUrl) {
         return undefined;
     return lines.join("\n") + "\n";
 }
+function buildJson5HeaderComment(header) {
+    if (!header || header.length === 0)
+        return undefined;
+    return header.map((h) => `// ${h}`).join("\n") + "\n";
+}
 /**
  * Converts content to string in the appropriate format.
  * Handles null content (empty files), text content (string/string[]), and object content (JSON/YAML).
@@ -55,6 +60,12 @@ export function convertContentToString(content, fileName, options) {
                 return commentOnly;
             }
         }
+        if (format === "json5" && options) {
+            const commentOnly = buildJson5HeaderComment(options.header);
+            if (commentOnly) {
+                return commentOnly;
+            }
+        }
         return "";
     }
     if (typeof content === "string") {
@@ -92,8 +103,14 @@ export function convertContentToString(content, fileName, options) {
             indent: 2,
             defaultStringType: "QUOTE_DOUBLE",
             defaultKeyType: "PLAIN",
+            lineWidth: 0,
         });
     }
-    // JSON and JSON5 — both use standard JSON.stringify (valid JSON5 superset)
+    if (format === "json5" && options) {
+        const headerComment = buildJson5HeaderComment(options.header);
+        if (headerComment) {
+            return headerComment + JSON.stringify(content, null, 2) + "\n";
+        }
+    }
     return JSON.stringify(content, null, 2) + "\n";
 }

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, CodeScanningSettings, CodeScanningState, CodeScanningQuerySuite, CodeScanningLanguage, RepoSettings, RawFileConfig, RawRepoFileOverride, RawGroupConfig, RawRepoSettings, RawRepoConfig, RawConfig, RawConditionalGroupWhen, RawConditionalGroupConfig, RepoConfig, Config, FileContent, ContentValue, } from "./types.js";
+export type { PRMergeOptions, MergeMode, MergeStrategy, BypassActor, StatusCheckConfig, CodeScanningTool, PullRequestRuleParameters, RulesetRule, Ruleset, GitHubRepoSettings, RepoVisibility, SquashMergeCommitTitle, SquashMergeCommitMessage, MergeCommitTitle, MergeCommitMessage, Label, CodeScanningSettings, CodeScanningState, CodeScanningQuerySuite, CodeScanningLanguage, 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/loader.js

@@ -13,7 +13,13 @@ export { normalizeConfigInternal as normalizeConfig };
  * Use this when you need to perform command-specific validation before normalizing.
  */
 export function loadRawConfig(configPath) {
-    const stat = statSync(configPath);
+    let stat;
+    try {
+        stat = statSync(configPath);
+    }
+    catch (error) {
+        throw new ValidationError(`Failed to read config at ${configPath}: ${toErrorMessage(error)}`, { cause: error });
+    }
     if (stat.isDirectory()) {
         return loadRawConfigFromDirectory(configPath);
     }
@@ -24,7 +30,13 @@ export function loadConfig(configPath, env) {
     return normalizeConfigInternal(rawConfig, env);
 }
 function loadRawConfigFromFile(filePath) {
-    const content = readFileSync(filePath, "utf-8");
+    let content;
+    try {
+        content = readFileSync(filePath, "utf-8");
+    }
+    catch (error) {
+        throw new ValidationError(`Failed to read config file ${filePath}: ${toErrorMessage(error)}`, { cause: error });
+    }
     const configDir = dirname(filePath);
     let rawConfig;
     try {
@@ -32,7 +44,7 @@ function loadRawConfigFromFile(filePath) {
     }
     catch (error) {
         const message = toErrorMessage(error);
-        throw new ValidationError(`Failed to parse YAML config at ${filePath}: ${message}`);
+        throw new ValidationError(`Failed to parse YAML config at ${filePath}: ${message}`, { cause: error });
     }
     // Resolve file references before validation so content type checking works
     rawConfig = resolveFileReferencesInConfig(rawConfig, { configDir });
@@ -40,7 +52,13 @@ function loadRawConfigFromFile(filePath) {
     return rawConfig;
 }
 function loadRawConfigFromDirectory(dirPath) {
-    const entries = readdirSync(dirPath, { withFileTypes: true });
+    let entries;
+    try {
+        entries = readdirSync(dirPath, { withFileTypes: true });
+    }
+    catch (error) {
+        throw new ValidationError(`Failed to read config directory ${dirPath}: ${toErrorMessage(error)}`, { cause: error });
+    }
     const yamlFiles = entries
         .filter((entry) => entry.isFile() &&
         [".yaml", ".yml"].includes(extname(entry.name).toLowerCase()))
@@ -51,7 +69,13 @@ function loadRawConfigFromDirectory(dirPath) {
     }
     const fragments = yamlFiles.map((fileName) => {
         const filePath = join(dirPath, fileName);
-        const content = readFileSync(filePath, "utf-8");
+        let content;
+        try {
+            content = readFileSync(filePath, "utf-8");
+        }
+        catch (error) {
+            throw new ValidationError(`Failed to read config file ${filePath}: ${toErrorMessage(error)}`, { cause: error });
+        }
         const configDir = dirname(filePath);
         let config;
         try {
@@ -59,7 +83,7 @@ function loadRawConfigFromDirectory(dirPath) {
         }
         catch (error) {
             const message = toErrorMessage(error);
-            throw new ValidationError(`Failed to parse YAML config at ${filePath}: ${message}`);
+            throw new ValidationError(`Failed to parse YAML config at ${filePath}: ${message}`, { cause: error });
         }
         if (!config || typeof config !== "object") {
             throw new ValidationError(`Config file ${fileName} is empty or invalid — expected a YAML mapping`);

package/dist/config/merge.d.ts

@@ -2,7 +2,17 @@
  * Deep merge utilities for JSON configuration objects.
  * Supports per-field array merge strategies via $arrayMerge + $values directives.
  */
-export type ArrayMergeStrategy = "replace" | "append" | "prepend";
+/**
+ * Candidate keys for matching array items by identity rather than index.
+ * Order matters — first key found across all items wins.
+ */
+export declare const MATCH_KEY_CANDIDATES: readonly ["type", "actor_id"];
+/**
+ * Finds a key that uniquely identifies items in both arrays.
+ * Returns the first candidate key present in every item of both arrays, or undefined.
+ */
+export declare function findMatchKey(base: unknown[], overlay: unknown[]): string | undefined;
+export type ArrayMergeStrategy = "replace" | "append" | "prepend" | "merge";
 export interface MergeContext {
     defaultArrayStrategy: ArrayMergeStrategy;
 }

package/dist/config/merge.js

@@ -3,16 +3,87 @@
  * Supports per-field array merge strategies via $arrayMerge + $values directives.
  */
 import { isPlainObject } from "../shared/type-guards.js";
+/**
+ * Candidate keys for matching array items by identity rather than index.
+ * Order matters — first key found across all items wins.
+ */
+export const MATCH_KEY_CANDIDATES = ["type", "actor_id"];
+/**
+ * Finds a key that uniquely identifies items in both arrays.
+ * Returns the first candidate key present in every item of both arrays, or undefined.
+ */
+export function findMatchKey(base, overlay) {
+    if (base.length === 0 && overlay.length === 0)
+        return undefined;
+    const hasKey = (item, key) => isPlainObject(item) && key in item;
+    for (const candidate of MATCH_KEY_CANDIDATES) {
+        if (base.every((item) => hasKey(item, candidate)) &&
+            overlay.every((item) => hasKey(item, candidate))) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
 /**
  * Keys reserved for xfg merge directives.
  * Only these are stripped during merge — standard $-prefixed keys
  * like $schema, $id, $ref, $generated are preserved.
  */
 const XFG_DIRECTIVES = new Set(["$arrayMerge", "$values"]);
+function mergeByKey(base, overlay, matchKey, ctx) {
+    const baseByKey = new Map();
+    // findMatchKey guarantees every item in both arrays is a plain object with matchKey
+    for (let i = 0; i < base.length; i++) {
+        const item = base[i];
+        const keyValue = item[matchKey];
+        if (keyValue !== undefined && !baseByKey.has(keyValue)) {
+            baseByKey.set(keyValue, { item, index: i });
+        }
+    }
+    const appended = [];
+    for (const overlayItem of overlay) {
+        const item = overlayItem;
+        const keyValue = item[matchKey];
+        const baseEntry = baseByKey.get(keyValue);
+        if (baseEntry) {
+            baseByKey.set(keyValue, {
+                item: deepMerge(baseEntry.item, item, ctx),
+                index: baseEntry.index,
+            });
+        }
+        else {
+            appended.push(overlayItem);
+        }
+    }
+    const result = [];
+    for (let i = 0; i < base.length; i++) {
+        const item = base[i];
+        const keyValue = item[matchKey];
+        const entry = baseByKey.get(keyValue);
+        if (entry && entry.index === i) {
+            result.push(entry.item);
+        }
+        else {
+            result.push(item);
+        }
+    }
+    result.push(...appended);
+    return result;
+}
 const arrayMergeStrategies = new Map([
     ["replace", (_base, overlay) => overlay],
     ["append", (base, overlay) => [...base, ...overlay]],
     ["prepend", (base, overlay) => [...overlay, ...base]],
+    [
+        "merge",
+        (base, overlay, ctx) => {
+            const matchKey = findMatchKey(base, overlay);
+            if (!matchKey) {
+                return [...base, ...overlay];
+            }
+            return mergeByKey(base, overlay, matchKey, ctx);
+        },
+    ],
 ]);
 /**
  * Checks if a value is an unresolved $arrayMerge directive object
@@ -28,12 +99,11 @@ function isUnresolvedDirective(value) {
         arrayMergeStrategies.has(value.$arrayMerge) &&
         Array.isArray(value.$values));
 }
-function mergeArrays(base, overlay, strategy) {
+function mergeArrays(base, overlay, strategy, ctx) {
     const handler = arrayMergeStrategies.get(strategy);
     if (handler) {
-        return handler(base, overlay);
+        return handler(base, overlay, ctx);
     }
-    // Fallback to replace for unknown strategies
     return overlay;
 }
 /**
@@ -61,16 +131,17 @@ export function deepMerge(base, overlay, ctx) {
             const values = overlayValue.$values;
             if ((strategy === "replace" ||
                 strategy === "append" ||
-                strategy === "prepend") &&
+                strategy === "prepend" ||
+                strategy === "merge") &&
                 Array.isArray(values) &&
                 Array.isArray(resolvedBase)) {
-                result[key] = mergeArrays(resolvedBase, values, strategy);
+                result[key] = mergeArrays(resolvedBase, values, strategy, ctx);
                 continue;
             }
         }
         // Both are arrays — use default strategy
         if (Array.isArray(resolvedBase) && Array.isArray(overlayValue)) {
-            result[key] = mergeArrays(resolvedBase, overlayValue, ctx.defaultArrayStrategy);
+            result[key] = mergeArrays(resolvedBase, overlayValue, ctx.defaultArrayStrategy, ctx);
             continue;
         }
         // Both are plain objects — recurse
@@ -144,6 +215,7 @@ export function mergeTextContent(base, overlay, strategy = "replace") {
     if (Array.isArray(base)) {
         switch (strategy) {
             case "append":
+            case "merge":
                 return [...base, ...overlay];
             case "prepend":
                 return [...overlay, ...base];

package/dist/config/normalizer.js

@@ -1,5 +1,5 @@
 import { deepMerge, stripMergeDirectives, createMergeContext, isTextContent, mergeTextContent, } from "./merge.js";
-import { interpolateContent } from "../shared/env.js";
+import { interpolateContent } from "./env.js";
 import { expandRepoGroups } from "./extends-resolver.js";
 /**
  * Clone content, stripping merge directives from object content.
@@ -79,22 +79,8 @@ function mergePROptions(global, perRepo) {
         return perRepo;
     if (!perRepo)
         return global;
-    const result = {};
-    const merge = perRepo.merge ?? global.merge;
-    const mergeStrategy = perRepo.mergeStrategy ?? global.mergeStrategy;
-    const deleteBranch = perRepo.deleteBranch ?? global.deleteBranch;
-    const bypassReason = perRepo.bypassReason ?? global.bypassReason;
-    const labels = perRepo.labels ?? global.labels;
-    if (merge !== undefined)
-        result.merge = merge;
-    if (mergeStrategy !== undefined)
-        result.mergeStrategy = mergeStrategy;
-    if (deleteBranch !== undefined)
-        result.deleteBranch = deleteBranch;
-    if (bypassReason !== undefined)
-        result.bypassReason = bypassReason;
-    if (labels !== undefined)
-        result.labels = labels;
+    const merged = { ...global, ...perRepo };
+    const result = Object.fromEntries(Object.entries(merged).filter(([, v]) => v !== undefined));
     return Object.keys(result).length > 0 ? result : undefined;
 }
 /**
@@ -454,6 +440,35 @@ function resolveFileEntry(fileName, fileConfig, repoOverride, inheritFiles, glob
             globalDeleteOrphaned,
     };
 }
+function normalizeRepoEntry(ctx) {
+    const files = [];
+    const inheritFiles = shouldInherit(ctx.rawRepo.files);
+    for (const fileName of ctx.fileNames) {
+        if (fileName === "inherit")
+            continue;
+        const entry = resolveFileEntry(fileName, ctx.effectiveRootFiles[fileName], ctx.rawRepo.files?.[fileName], inheritFiles, ctx.globalDeleteOrphaned, ctx.env);
+        if (entry)
+            files.push(entry);
+    }
+    for (const fileName of ctx.repoOnlyFileNames) {
+        const repoOverride = ctx.rawRepo.files[fileName];
+        if (repoOverride === false)
+            continue;
+        const entry = resolveFileEntry(fileName, {}, repoOverride, true, ctx.globalDeleteOrphaned, ctx.env);
+        if (entry)
+            files.push(entry);
+    }
+    const prOptions = mergePROptions(ctx.effectivePROptions, ctx.rawRepo.prOptions);
+    const settings = mergeSettings(ctx.effectiveSettings, ctx.rawRepo.settings);
+    return {
+        git: ctx.gitUrl,
+        files,
+        prOptions,
+        settings,
+        upstream: ctx.rawRepo.upstream,
+        source: ctx.rawRepo.source,
+    };
+}
 /**
  * Normalizes raw config into expanded, merged config.
  * Pipeline: expand git arrays -> merge content -> interpolate env vars
@@ -485,29 +500,29 @@ export function normalizeConfig(raw, env) {
             effectiveSettings = merged.settings;
         }
         const fileNames = Object.keys(effectiveRootFiles);
-        for (const gitUrl of gitUrls) {
-            const files = [];
-            const inheritFiles = shouldInherit(rawRepo.files);
-            for (const fileName of fileNames) {
-                // Skip reserved key
-                if (fileName === "inherit")
+        // Collect repo-only file names (defined at repo level but not in root/groups)
+        const repoOnlyFileNames = [];
+        if (rawRepo.files) {
+            for (const name of Object.keys(rawRepo.files)) {
+                if (name === "inherit")
                     continue;
-                const entry = resolveFileEntry(fileName, effectiveRootFiles[fileName], rawRepo.files?.[fileName], inheritFiles, raw.deleteOrphaned, env);
-                if (entry)
-                    files.push(entry);
+                if (!effectiveRootFiles[name]) {
+                    repoOnlyFileNames.push(name);
+                }
             }
-            // Merge PR options: per-repo overrides effective (root + groups)
-            const prOptions = mergePROptions(effectivePROptions, rawRepo.prOptions);
-            // Merge settings: per-repo deep merges with effective (root + groups)
-            const settings = mergeSettings(effectiveSettings, rawRepo.settings);
-            expandedRepos.push({
-                git: gitUrl,
-                files,
-                prOptions,
-                settings,
-                upstream: rawRepo.upstream,
-                source: rawRepo.source,
-            });
+        }
+        for (const gitUrl of gitUrls) {
+            expandedRepos.push(normalizeRepoEntry({
+                gitUrl,
+                rawRepo,
+                effectiveRootFiles,
+                fileNames,
+                repoOnlyFileNames,
+                effectivePROptions,
+                effectiveSettings,
+                globalDeleteOrphaned: raw.deleteOrphaned,
+                env,
+            }));
         }
     }
     // Normalize root settings by reusing mergeSettings with no per-repo overlay.

package/dist/config/validator.d.ts

@@ -1,4 +1,4 @@
-import type { RawConfig, RawRepoSettings, RawRootSettings } from "./types.js";
+import type { RawConfig, RawRootSettings, RawRepoSettings } from "./types.js";
 /**
  * Validates raw config structure before normalization.
  * @throws ValidationError if validation fails
@@ -9,7 +9,4 @@ export declare function validateRawConfig(config: RawConfig): void;
  * @throws ValidationError if neither files nor settings are present
  */
 export declare function validateForSync(config: RawConfig): void;
-/**
- * Checks if settings contain actionable configuration.
- */
 export declare function hasActionableSettings(settings: RawRootSettings | RawRepoSettings | undefined): boolean;