@aspruyt/xfg 5.3.0 → 5.4.0

package/dist/config/file-reference-resolver.js

@@ -132,6 +132,23 @@ export function resolveFileReferencesInConfig(raw, options) {
             }
         }
     }
+    // Resolve conditional group file content
+    if (result.conditionalGroups) {
+        for (const cg of result.conditionalGroups) {
+            if (cg.files) {
+                for (const [fileName, fileConfig] of Object.entries(cg.files)) {
+                    if (fileConfig &&
+                        typeof fileConfig === "object" &&
+                        "content" in fileConfig) {
+                        const resolved = resolveContentValue(fileConfig.content, configDir);
+                        if (resolved !== undefined) {
+                            cg.files[fileName] = { ...fileConfig, content: resolved };
+                        }
+                    }
+                }
+            }
+        }
+    }
     // Resolve per-repo file content
     if (result.repos) {
         for (const repo of result.repos) {

package/dist/config/merge.d.ts

@@ -18,6 +18,10 @@ export declare function deepMerge(base: Record<string, unknown>, overlay: Record
  * Strip xfg merge directive keys ($arrayMerge, $values) from an object.
  * Works recursively on nested objects and arrays.
  * Standard $-prefixed keys ($schema, $id, $ref, etc.) are preserved.
+ *
+ * When an unresolved directive object is found (only contains $arrayMerge + $values),
+ * it is replaced with the $values array. This handles the case where a directive
+ * had no base array to merge with.
  */
 export declare function stripMergeDirectives(obj: Record<string, unknown>): Record<string, unknown>;
 export declare function createMergeContext(defaultStrategy?: ArrayMergeStrategy): MergeContext;

package/dist/config/merge.js

@@ -14,6 +14,20 @@ const arrayMergeStrategies = new Map([
     ["append", (base, overlay) => [...base, ...overlay]],
     ["prepend", (base, overlay) => [...overlay, ...base]],
 ]);
+/**
+ * Checks if a value is an unresolved $arrayMerge directive object
+ * (only contains $arrayMerge + $values keys, with a valid strategy and array values).
+ */
+function isUnresolvedDirective(value) {
+    if (!isPlainObject(value))
+        return false;
+    const keys = Object.keys(value);
+    return (keys.length === 2 &&
+        keys.every((k) => XFG_DIRECTIVES.has(k)) &&
+        typeof value.$arrayMerge === "string" &&
+        arrayMergeStrategies.has(value.$arrayMerge) &&
+        Array.isArray(value.$values));
+}
 function mergeArrays(base, overlay, strategy) {
     const handler = arrayMergeStrategies.get(strategy);
     if (handler) {
@@ -36,6 +50,11 @@ export function deepMerge(base, overlay, ctx) {
         if (XFG_DIRECTIVES.has(key))
             continue;
         const baseValue = base[key];
+        // If base is an unresolved directive (from a previous layer with no base array),
+        // resolve it to its $values array before proceeding with merge logic.
+        const resolvedBase = isUnresolvedDirective(baseValue)
+            ? baseValue.$values
+            : baseValue;
         // Per-field $arrayMerge + $values directive
         if (isPlainObject(overlayValue) && "$arrayMerge" in overlayValue) {
             const strategy = overlayValue.$arrayMerge;
@@ -44,19 +63,19 @@ export function deepMerge(base, overlay, ctx) {
                 strategy === "append" ||
                 strategy === "prepend") &&
                 Array.isArray(values) &&
-                Array.isArray(baseValue)) {
-                result[key] = mergeArrays(baseValue, values, strategy);
+                Array.isArray(resolvedBase)) {
+                result[key] = mergeArrays(resolvedBase, values, strategy);
                 continue;
             }
         }
         // Both are arrays — use default strategy
-        if (Array.isArray(baseValue) && Array.isArray(overlayValue)) {
-            result[key] = mergeArrays(baseValue, overlayValue, ctx.defaultArrayStrategy);
+        if (Array.isArray(resolvedBase) && Array.isArray(overlayValue)) {
+            result[key] = mergeArrays(resolvedBase, overlayValue, ctx.defaultArrayStrategy);
             continue;
         }
         // Both are plain objects — recurse
-        if (isPlainObject(baseValue) && isPlainObject(overlayValue)) {
-            result[key] = deepMerge(baseValue, overlayValue, ctx);
+        if (isPlainObject(resolvedBase) && isPlainObject(overlayValue)) {
+            result[key] = deepMerge(resolvedBase, overlayValue, ctx);
             continue;
         }
         // Otherwise, overlay wins (including null values)
@@ -68,6 +87,10 @@ export function deepMerge(base, overlay, ctx) {
  * Strip xfg merge directive keys ($arrayMerge, $values) from an object.
  * Works recursively on nested objects and arrays.
  * Standard $-prefixed keys ($schema, $id, $ref, etc.) are preserved.
+ *
+ * When an unresolved directive object is found (only contains $arrayMerge + $values),
+ * it is replaced with the $values array. This handles the case where a directive
+ * had no base array to merge with.
  */
 export function stripMergeDirectives(obj) {
     const result = {};
@@ -76,7 +99,13 @@ export function stripMergeDirectives(obj) {
         if (XFG_DIRECTIVES.has(key))
             continue;
         if (isPlainObject(value)) {
-            result[key] = stripMergeDirectives(value);
+            if (isUnresolvedDirective(value)) {
+                // Resolve to the $values array, stripping directives from items
+                result[key] = value.$values.map((item) => isPlainObject(item) ? stripMergeDirectives(item) : item);
+            }
+            else {
+                result[key] = stripMergeDirectives(value);
+            }
         }
         else if (Array.isArray(value)) {
             result[key] = value.map((item) => isPlainObject(item) ? stripMergeDirectives(item) : item);

package/dist/config/normalizer.js

@@ -170,7 +170,8 @@ export function mergeSettings(root, perRepo) {
             if (!inheritRulesets && !repoRuleset && rootRuleset) {
                 continue;
             }
-            result.rulesets[name] = mergeRuleset(rootRuleset, repoRuleset);
+            const merged = mergeRuleset(rootRuleset, repoRuleset);
+            result.rulesets[name] = stripMergeDirectives(merged);
         }
         // Clean up empty rulesets object
         if (Object.keys(result.rulesets).length === 0) {

package/dist/config/validators/ruleset-validator.js

@@ -1,4 +1,5 @@
 import { ValidationError } from "../../shared/errors.js";
+import { isPlainObject } from "../../shared/type-guards.js";
 /** Compile-time validates an array matches a type union, while keeping string[] runtime type for .includes() */
 function validValues(values) {
     return values;
@@ -62,6 +63,31 @@ const VALID_RULE_TYPES = validValues([
     "max_file_path_length",
     "max_file_size",
 ]);
+// Intentionally duplicated from merge.ts — validator should not depend on merge internals
+const VALID_MERGE_STRATEGIES = ["replace", "append", "prepend"];
+/**
+ * Checks if a value is an $arrayMerge directive: { $arrayMerge: strategy, $values: [...] }
+ */
+function isArrayMergeDirective(value) {
+    if (!isPlainObject(value))
+        return false;
+    const keys = Object.keys(value);
+    return (keys.length === 2 &&
+        keys.every((k) => k === "$arrayMerge" || k === "$values") &&
+        VALID_MERGE_STRATEGIES.includes(value.$arrayMerge) &&
+        Array.isArray(value.$values));
+}
+/**
+ * Extracts the $values array from a directive, or returns the value as-is if it's already an array.
+ * Returns null if value is neither an array nor a valid directive.
+ */
+function extractArrayOrDirectiveValues(value) {
+    if (Array.isArray(value))
+        return value;
+    if (isArrayMergeDirective(value))
+        return value.$values;
+    return null;
+}
 /**
  * Validates a single ruleset rule.
  */
@@ -158,11 +184,12 @@ export function validateRuleset(ruleset, name, context) {
     }
     // Validate bypassActors
     if (rs.bypassActors !== undefined) {
-        if (!Array.isArray(rs.bypassActors)) {
-            throw new ValidationError(`${context}: ruleset '${name}' bypassActors must be an array`);
+        const actors = extractArrayOrDirectiveValues(rs.bypassActors);
+        if (actors === null) {
+            throw new ValidationError(`${context}: ruleset '${name}' bypassActors must be an array or $arrayMerge directive`);
         }
-        for (let i = 0; i < rs.bypassActors.length; i++) {
-            const actor = rs.bypassActors[i];
+        for (let i = 0; i < actors.length; i++) {
+            const actor = actors[i];
             if (typeof actor !== "object" || actor === null) {
                 throw new ValidationError(`${context}: ruleset '${name}' bypassActors[${i}] must be an object`);
             }
@@ -193,25 +220,28 @@ export function validateRuleset(ruleset, name, context) {
                 Array.isArray(refName)) {
                 throw new ValidationError(`${context}: ruleset '${name}' conditions.refName must be an object`);
             }
-            if (refName.include !== undefined &&
-                (!Array.isArray(refName.include) ||
-                    !refName.include.every((s) => typeof s === "string"))) {
-                throw new ValidationError(`${context}: ruleset '${name}' conditions.refName.include must be an array of strings`);
+            if (refName.include !== undefined) {
+                const include = extractArrayOrDirectiveValues(refName.include);
+                if (include === null || !include.every((s) => typeof s === "string")) {
+                    throw new ValidationError(`${context}: ruleset '${name}' conditions.refName.include must be an array of strings or $arrayMerge directive with string $values`);
+                }
             }
-            if (refName.exclude !== undefined &&
-                (!Array.isArray(refName.exclude) ||
-                    !refName.exclude.every((s) => typeof s === "string"))) {
-                throw new ValidationError(`${context}: ruleset '${name}' conditions.refName.exclude must be an array of strings`);
+            if (refName.exclude !== undefined) {
+                const exclude = extractArrayOrDirectiveValues(refName.exclude);
+                if (exclude === null || !exclude.every((s) => typeof s === "string")) {
+                    throw new ValidationError(`${context}: ruleset '${name}' conditions.refName.exclude must be an array of strings or $arrayMerge directive with string $values`);
+                }
             }
         }
     }
     // Validate rules array
     if (rs.rules !== undefined) {
-        if (!Array.isArray(rs.rules)) {
-            throw new ValidationError(`${context}: ruleset '${name}' rules must be an array`);
+        const rules = extractArrayOrDirectiveValues(rs.rules);
+        if (rules === null) {
+            throw new ValidationError(`${context}: ruleset '${name}' rules must be an array or $arrayMerge directive`);
         }
-        for (let i = 0; i < rs.rules.length; i++) {
-            validateRule(rs.rules[i], `${context}: ruleset '${name}' rules[${i}]`);
+        for (let i = 0; i < rules.length; i++) {
+            validateRule(rules[i], `${context}: ruleset '${name}' rules[${i}]`);
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspruyt/xfg",
-  "version": "5.3.0",
+  "version": "5.4.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",