@aspruyt/xfg 5.3.1 → 5.5.0

package/dist/{shared → cli}/branch-utils.js

@@ -1,4 +1,4 @@
-import { ValidationError } from "./errors.js";
+import { ValidationError } from "../shared/errors.js";
 export function sanitizeBranchName(fileName) {
     return fileName
         .toLowerCase()

package/dist/cli/settings-report-builder.d.ts

@@ -1,5 +1,5 @@
 import type { SettingsReport } from "../output/settings-report.js";
-import { type RepoSettingsPlanEntry, type RulesetPlanEntry, type LabelsPlanEntry } from "../settings/index.js";
+import { type RepoSettingsPlanEntry, type RulesetPlanEntry, type LabelsPlanEntry, type CodeScanningPlanEntry } from "../settings/index.js";
 /**
  * Result from processing a repository's settings and rulesets.
  * Used to collect results during settings command execution.
@@ -21,6 +21,11 @@ export interface ProcessorResults {
             entries?: LabelsPlanEntry[];
         };
     };
+    codeScanningResult?: {
+        planOutput?: {
+            entries?: CodeScanningPlanEntry[];
+        };
+    };
     error?: string;
 }
 export declare function buildSettingsReport(results: ProcessorResults[]): SettingsReport;

package/dist/cli/settings-report-builder.js

@@ -66,6 +66,25 @@ export function buildSettingsReport(results) {
             totals.labels.update += counts.update;
             totals.labels.delete += counts.delete;
         }
+        // Convert code scanning processor output
+        if (result.codeScanningResult?.planOutput?.entries) {
+            let csCreates = 0;
+            let csUpdates = 0;
+            for (const entry of result.codeScanningResult.planOutput.entries) {
+                repoChanges.settings.push({
+                    name: `codeScanning.${entry.property}`,
+                    action: entry.action,
+                    oldValue: entry.oldValue,
+                    newValue: entry.newValue ?? null,
+                });
+                if (entry.action === "create")
+                    csCreates++;
+                if (entry.action === "update")
+                    csUpdates++;
+            }
+            totals.settings.create += csCreates;
+            totals.settings.update += csUpdates;
+        }
         if (result.error) {
             repoChanges.error = result.error;
         }

package/dist/cli/sync-command.js

@@ -3,10 +3,11 @@ import { existsSync } from "node:fs";
 import { loadRawConfig, normalizeConfig, validateForSync, } from "../config/index.js";
 import { ValidationError, SyncError } from "../shared/errors.js";
 import { parseGitUrl, getRepoDisplayName, isGitHubRepo, } from "../shared/repo-detector.js";
-import { sanitizeBranchName, validateBranchName, } from "../shared/branch-utils.js";
+import { sanitizeBranchName, validateBranchName } from "./branch-utils.js";
 import { createTokenManager } from "../vcs/index.js";
 import { RepositoryProcessor } from "../sync/index.js";
-import { RulesetProcessor, RepoSettingsProcessor, LabelsProcessor, GitHubRulesetStrategy, GitHubRepoSettingsStrategy, GitHubLabelsStrategy, } from "../settings/index.js";
+import { RulesetProcessor, RepoSettingsProcessor, LabelsProcessor, CodeScanningProcessor, GitHubRulesetStrategy, GitHubRepoSettingsStrategy, GitHubLabelsStrategy, GitHubCodeScanningStrategy, } from "../settings/index.js";
+import { GitHubRepoMetadataProvider } from "../shared/repo-metadata-provider.js";
 import { ShellCommandExecutor } from "../shared/command-executor.js";
 import { Logger } from "../shared/logger.js";
 import { generateWorkspaceName } from "../shared/workspace-utils.js";
@@ -24,12 +25,18 @@ function createDefaultRulesetProcessorFactory() {
 }
 function createDefaultRepoSettingsProcessorFactory() {
     const cwd = process.cwd();
-    return () => new RepoSettingsProcessor(new GitHubRepoSettingsStrategy(getDefaultExecutor(), { cwd }));
+    const executor = getDefaultExecutor();
+    return () => new RepoSettingsProcessor(new GitHubRepoSettingsStrategy(executor, { cwd }), new GitHubRepoMetadataProvider(executor, { cwd }));
 }
 function createDefaultLabelsProcessorFactory() {
     const cwd = process.cwd();
     return () => new LabelsProcessor(new GitHubLabelsStrategy(getDefaultExecutor(), { cwd }));
 }
+function createDefaultCodeScanningProcessorFactory() {
+    const cwd = process.cwd();
+    const executor = getDefaultExecutor();
+    return () => new CodeScanningProcessor(new GitHubCodeScanningStrategy(executor, { cwd }), new GitHubRepoMetadataProvider(executor, { cwd }));
+}
 import { ResultsCollector } from "./results-collector.js";
 import { buildSettingsReport, } from "./settings-report-builder.js";
 import { formatSettingsReportCLI } from "../output/settings-report.js";
@@ -40,7 +47,7 @@ import { formatLifecycleReportCLI, hasLifecycleChanges, } from "../output/lifecy
 import { writeUnifiedSummary } from "../output/unified-summary.js";
 import { toErrorMessage } from "../shared/type-guards.js";
 import { resolveGitHubToken } from "../shared/gh-api-utils.js";
-import { RepoLifecycleManager, runLifecycleCheck, toCreateRepoSettings, } from "../lifecycle/index.js";
+import { RepoLifecycleManager, runLifecycleCheck, } from "../lifecycle/index.js";
 function getUniqueFileNames(config) {
     const fileNames = new Set();
     for (const repo of config.repos) {
@@ -97,46 +104,53 @@ function logSettingsResult(result, label, repoNumber, repoName, settingsCollecto
         settingsCollector.appendError(repoName, result.message);
     }
 }
+// Each processor returns a subtype of BaseProcessorResult whose planOutput
+// contains both `lines` (for CLI display) and `entries` (for report building).
+// ProcessorResults fields capture only the `entries` slice; the runtime object
+// satisfies both views, so we assign with an explicit per-field cast.
+async function runAndStoreResult(factory, repoConfig, repoInfo, opts, repoName, settingsCollector, assign) {
+    const result = await runSettingsProcessor(factory, repoConfig, repoInfo, opts);
+    if (!result.skipped) {
+        assign(settingsCollector.getOrCreate(repoName), result);
+    }
+    return result;
+}
 function buildSettingsDescriptors(ctx) {
-    const { repoConfig, repoInfo, options, token, repoName, settingsCollector, rulesetProcessorFactory, repoSettingsProcessorFactory, labelsProcessorFactory, } = ctx;
+    const { repoConfig, repoInfo, options, token, repoName, settingsCollector, rulesetProcessorFactory, repoSettingsProcessorFactory, labelsProcessorFactory, codeScanningProcessorFactory, } = ctx;
     const sharedOpts = {
         dryRun: options.dryRun,
         noDelete: options.noDelete,
         token,
     };
-    // Each processor returns a subtype of BaseProcessorResult whose planOutput
-    // contains both `lines` (for CLI display) and `entries` (for report building).
-    // ProcessorResults fields capture only the `entries` slice; the runtime object
-    // satisfies both views, so we assign with an explicit per-field cast.
-    const runAndStore = async (factory, opts, assign) => {
-        const result = await runSettingsProcessor(factory, repoConfig, repoInfo, opts);
-        if (!result.skipped) {
-            assign(settingsCollector.getOrCreate(repoName), result);
-        }
-        return result;
-    };
     return [
         {
             key: "rulesets",
             label: "Rulesets",
-            run: () => runAndStore(rulesetProcessorFactory, sharedOpts, (e, r) => {
+            run: () => runAndStoreResult(rulesetProcessorFactory, repoConfig, repoInfo, sharedOpts, repoName, settingsCollector, (e, r) => {
                 e.rulesetResult = r;
             }),
         },
         {
             key: "labels",
             label: "Labels",
-            run: () => runAndStore(labelsProcessorFactory, sharedOpts, (e, r) => {
+            run: () => runAndStoreResult(labelsProcessorFactory, repoConfig, repoInfo, sharedOpts, repoName, settingsCollector, (e, r) => {
                 e.labelsResult = r;
             }),
         },
         {
             key: "repo",
             label: "Repo Settings",
-            run: () => runAndStore(repoSettingsProcessorFactory, { dryRun: options.dryRun, token }, (e, r) => {
+            run: () => runAndStoreResult(repoSettingsProcessorFactory, repoConfig, repoInfo, { dryRun: options.dryRun, token }, repoName, settingsCollector, (e, r) => {
                 e.settingsResult = r;
             }),
         },
+        {
+            key: "codeScanning",
+            label: "Code Scanning",
+            run: () => runAndStoreResult(codeScanningProcessorFactory, repoConfig, repoInfo, sharedOpts, repoName, settingsCollector, (e, r) => {
+                e.codeScanningResult = r;
+            }),
+        },
     ];
 }
 function runSettingsProcessor(factory, repoConfig, repoInfo, processOptions) {
@@ -269,6 +283,7 @@ async function processSingleRepo(repoConfig, index, ctx) {
         rulesetProcessorFactory: ctx.rulesetProcessorFactory,
         repoSettingsProcessorFactory: ctx.repoSettingsProcessorFactory,
         labelsProcessorFactory: ctx.labelsProcessorFactory,
+        codeScanningProcessorFactory: ctx.codeScanningProcessorFactory,
     });
 }
 /**
@@ -278,7 +293,7 @@ async function processSingleRepo(repoConfig, index, ctx) {
 async function runLifecyclePhase(repo, ctx) {
     const repoNumber = repo.index + 1;
     try {
-        const { outputLines, lifecycleResult } = await runLifecycleCheck(repo.repoConfig, repo.repoInfo, {
+        const { outputLines, lifecycleResult, createSettings } = await runLifecycleCheck(repo.repoConfig, repo.repoInfo, {
             dryRun: ctx.options.dryRun ?? false,
             resolvedWorkDir: repo.workDir,
             githubHosts: ctx.config.githubHosts,
@@ -290,7 +305,6 @@ async function runLifecyclePhase(repo, ctx) {
         for (const line of outputLines) {
             getLogger().info(line);
         }
-        const createSettings = toCreateRepoSettings(ctx.config.settings?.repo);
         ctx.lifecycleReportInputs.push({
             repoName: repo.repoName,
             action: lifecycleResult.action,
@@ -381,10 +395,10 @@ export async function runSync(options, deps = {}) {
     // Reset module-level singletons to ensure fresh state per invocation
     _defaultExecutor = undefined;
     _logger = undefined;
-    const { lifecycleManager, rulesetProcessorFactory = createDefaultRulesetProcessorFactory(), repoSettingsProcessorFactory = createDefaultRepoSettingsProcessorFactory(), labelsProcessorFactory = createDefaultLabelsProcessorFactory(), } = deps;
+    const { lifecycleManager, rulesetProcessorFactory = createDefaultRulesetProcessorFactory(), repoSettingsProcessorFactory = createDefaultRepoSettingsProcessorFactory(), labelsProcessorFactory = createDefaultLabelsProcessorFactory(), codeScanningProcessorFactory = createDefaultCodeScanningProcessorFactory(), } = deps;
     const configPath = resolve(options.config);
     if (!existsSync(configPath)) {
-        throw new ValidationError(`Config file not found: ${configPath}`);
+        throw new ValidationError(`Config path not found: ${configPath}`);
     }
     getLogger().log(`Loading config from: ${configPath}`);
     if (options.dryRun) {
@@ -432,6 +446,7 @@ export async function runSync(options, deps = {}) {
         rulesetProcessorFactory,
         repoSettingsProcessorFactory,
         labelsProcessorFactory,
+        codeScanningProcessorFactory,
     };
     for (let i = 0; i < config.repos.length; i++) {
         await processSingleRepo(config.repos[i], i, ctx);

package/dist/cli/sync-report-builder.d.ts

@@ -1,10 +1,11 @@
+import type { MergeMode } from "../config/index.js";
 import type { SyncReport, ReportFileChange } from "../output/sync-report.js";
 interface SyncResultInput {
     repoName: string;
     success: boolean;
     fileChanges: ReportFileChange[];
     prUrl?: string;
-    mergeOutcome?: "manual" | "auto" | "force" | "direct";
+    mergeOutcome?: MergeMode;
     error?: string;
 }
 export declare function buildSyncReport(results: SyncResultInput[]): SyncReport;

package/dist/cli/types.d.ts

@@ -1,7 +1,7 @@
 import type { MergeMode, MergeStrategy, RepoConfig } from "../config/index.js";
 import type { IRepoLifecycleManager } from "../lifecycle/index.js";
 import type { IRepositoryProcessor } from "../sync/index.js";
-import type { ISettingsProcessor, IRulesetProcessor, IRepoSettingsProcessor, ILabelsProcessor, BaseProcessorResult } from "../settings/index.js";
+import type { ISettingsProcessor, IRulesetProcessor, IRepoSettingsProcessor, ILabelsProcessor, ICodeScanningProcessor, BaseProcessorResult } from "../settings/index.js";
 import type { RepoInfo } from "../shared/repo-detector.js";
 import type { ResultsCollector } from "./results-collector.js";
 export type ProcessorFactory = () => IRepositoryProcessor;
@@ -9,6 +9,7 @@ export type SettingsProcessorFactory<T extends ISettingsProcessor> = () => T;
 export type RulesetProcessorFactory = SettingsProcessorFactory<IRulesetProcessor>;
 export type RepoSettingsProcessorFactory = SettingsProcessorFactory<IRepoSettingsProcessor>;
 export type LabelsProcessorFactory = SettingsProcessorFactory<ILabelsProcessor>;
+export type CodeScanningProcessorFactory = SettingsProcessorFactory<ICodeScanningProcessor>;
 /**
  * Dependencies for the sync command (dependency injection).
  */
@@ -18,6 +19,7 @@ export interface SyncDependencies {
     rulesetProcessorFactory?: RulesetProcessorFactory;
     repoSettingsProcessorFactory?: RepoSettingsProcessorFactory;
     labelsProcessorFactory?: LabelsProcessorFactory;
+    codeScanningProcessorFactory?: CodeScanningProcessorFactory;
 }
 export interface SharedOptions {
     config: string;
@@ -41,7 +43,7 @@ export interface SyncResultEntry {
         diffLines?: string[];
     }>;
     prUrl?: string;
-    mergeOutcome?: "manual" | "auto" | "force" | "direct";
+    mergeOutcome?: MergeMode;
     error?: string;
 }
 export interface SettingsResult extends BaseProcessorResult {
@@ -65,4 +67,5 @@ export interface ApplyRepoSettingsContext {
     rulesetProcessorFactory: NonNullable<SyncDependencies["rulesetProcessorFactory"]>;
     repoSettingsProcessorFactory: NonNullable<SyncDependencies["repoSettingsProcessorFactory"]>;
     labelsProcessorFactory: NonNullable<SyncDependencies["labelsProcessorFactory"]>;
+    codeScanningProcessorFactory: NonNullable<SyncDependencies["codeScanningProcessorFactory"]>;
 }

package/dist/config/config-merger.d.ts

@@ -0,0 +1,6 @@
+import type { RawConfig } from "./types.js";
+export interface ConfigFragment {
+    fileName: string;
+    config: Partial<RawConfig>;
+}
+export declare function mergeConfigFragments(fragments: ConfigFragment[]): RawConfig;

package/dist/config/config-merger.js

@@ -0,0 +1,66 @@
+import { ValidationError } from "../shared/errors.js";
+/** Keys that can only appear in one file across a config directory. */
+const SINGLE_FILE_KEYS = [
+    "id",
+    "files",
+    "prOptions",
+    "prTemplate",
+    "settings",
+    "githubHosts",
+    "deleteOrphaned",
+];
+export function mergeConfigFragments(fragments) {
+    if (fragments.length === 0) {
+        throw new ValidationError("No config fragments to merge");
+    }
+    const merged = {};
+    const singleKeySource = {};
+    const allRepos = [];
+    const allGroups = {};
+    const groupSource = {};
+    const allConditionalGroups = [];
+    for (const { fileName, config } of fragments) {
+        // Enforce single-file keys
+        for (const key of SINGLE_FILE_KEYS) {
+            if (config[key] !== undefined) {
+                if (singleKeySource[key] !== undefined) {
+                    throw new ValidationError(`'${key}' is defined in both ${singleKeySource[key]} and ${fileName} — this key can only appear in one file`);
+                }
+                singleKeySource[key] = fileName;
+                merged[key] = config[key];
+            }
+        }
+        // Concatenate repos
+        if (config.repos) {
+            allRepos.push(...config.repos);
+        }
+        // Merge groups (unique names only)
+        if (config.groups) {
+            for (const [groupName, groupConfig] of Object.entries(config.groups)) {
+                if (groupName in allGroups) {
+                    throw new ValidationError(`group '${groupName}' is defined in both ${groupSource[groupName]} and ${fileName} — group names must be unique across files`);
+                }
+                allGroups[groupName] = groupConfig;
+                groupSource[groupName] = fileName;
+            }
+        }
+        // Concatenate conditional groups
+        if (config.conditionalGroups) {
+            allConditionalGroups.push(...config.conditionalGroups);
+        }
+    }
+    if (!merged.id) {
+        throw new ValidationError("No 'id' found in any config file — exactly one file must define 'id'");
+    }
+    if (allRepos.length === 0) {
+        throw new ValidationError("No 'repos' found in any config file — at least one file must define 'repos'");
+    }
+    return {
+        ...merged,
+        repos: allRepos,
+        ...(Object.keys(allGroups).length > 0 ? { groups: allGroups } : {}),
+        ...(allConditionalGroups.length > 0
+            ? { conditionalGroups: allConditionalGroups }
+            : {}),
+    };
+}

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, RawGroupConfig, RawRepoSettings, RawRepoConfig, RawConfig, RawConditionalGroupWhen, RawConditionalGroupConfig, RepoConfig, Config, FileContent, ContentValue, } from "./types.js";
+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 { RULESET_COMPARABLE_FIELDS } from "./types.js";
 export { loadRawConfig, loadConfig, normalizeConfig } from "./loader.js";
 export { convertContentToString } from "./formatter.js";

package/dist/config/loader.d.ts

@@ -5,5 +5,5 @@ export { normalizeConfigInternal as normalizeConfig };
  * Load and validate raw config without normalization.
  * Use this when you need to perform command-specific validation before normalizing.
  */
-export declare function loadRawConfig(filePath: string): RawConfig;
-export declare function loadConfig(filePath: string, env: Record<string, string | undefined>): Config;
+export declare function loadRawConfig(configPath: string): RawConfig;
+export declare function loadConfig(configPath: string, env: Record<string, string | undefined>): Config;

package/dist/config/loader.js

@@ -1,17 +1,29 @@
-import { readFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { readFileSync, statSync, readdirSync } from "node:fs";
+import { dirname, join, extname } from "node:path";
 import { parse } from "yaml";
 import { validateRawConfig } from "./validator.js";
 import { normalizeConfig as normalizeConfigInternal } from "./normalizer.js";
 import { resolveFileReferencesInConfig } from "./file-reference-resolver.js";
 import { toErrorMessage } from "../shared/type-guards.js";
 import { ValidationError } from "../shared/errors.js";
+import { mergeConfigFragments } from "./config-merger.js";
 export { normalizeConfigInternal as normalizeConfig };
 /**
  * Load and validate raw config without normalization.
  * Use this when you need to perform command-specific validation before normalizing.
  */
-export function loadRawConfig(filePath) {
+export function loadRawConfig(configPath) {
+    const stat = statSync(configPath);
+    if (stat.isDirectory()) {
+        return loadRawConfigFromDirectory(configPath);
+    }
+    return loadRawConfigFromFile(configPath);
+}
+export function loadConfig(configPath, env) {
+    const rawConfig = loadRawConfig(configPath);
+    return normalizeConfigInternal(rawConfig, env);
+}
+function loadRawConfigFromFile(filePath) {
     const content = readFileSync(filePath, "utf-8");
     const configDir = dirname(filePath);
     let rawConfig;
@@ -27,7 +39,39 @@ export function loadRawConfig(filePath) {
     validateRawConfig(rawConfig);
     return rawConfig;
 }
-export function loadConfig(filePath, env) {
-    const rawConfig = loadRawConfig(filePath);
-    return normalizeConfigInternal(rawConfig, env);
+function loadRawConfigFromDirectory(dirPath) {
+    const entries = readdirSync(dirPath, { withFileTypes: true });
+    const yamlFiles = entries
+        .filter((entry) => entry.isFile() &&
+        [".yaml", ".yml"].includes(extname(entry.name).toLowerCase()))
+        .map((entry) => entry.name)
+        .sort();
+    if (yamlFiles.length === 0) {
+        throw new ValidationError(`No .yaml or .yml files found in directory: ${dirPath}`);
+    }
+    const fragments = yamlFiles.map((fileName) => {
+        const filePath = join(dirPath, fileName);
+        const content = readFileSync(filePath, "utf-8");
+        const configDir = dirname(filePath);
+        let config;
+        try {
+            config = parse(content);
+        }
+        catch (error) {
+            const message = toErrorMessage(error);
+            throw new ValidationError(`Failed to parse YAML config at ${filePath}: ${message}`);
+        }
+        if (!config || typeof config !== "object") {
+            throw new ValidationError(`Config file ${fileName} is empty or invalid — expected a YAML mapping`);
+        }
+        // Safe cast: resolveFileReferencesInConfig only accesses optional fields
+        // (files, groups, etc.), so fragments missing id/repos work correctly.
+        config = resolveFileReferencesInConfig(config, {
+            configDir,
+        });
+        return { fileName, config };
+    });
+    const merged = mergeConfigFragments(fragments);
+    validateRawConfig(merged);
+    return merged;
 }

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);
@@ -111,23 +140,18 @@ export function mergeTextContent(base, overlay, strategy = "replace") {
     if (typeof overlay === "string") {
         return overlay;
     }
-    // If overlay is an array
-    if (Array.isArray(overlay)) {
-        // If base is also an array, apply merge strategy
-        if (Array.isArray(base)) {
-            switch (strategy) {
-                case "append":
-                    return [...base, ...overlay];
-                case "prepend":
-                    return [...overlay, ...base];
-                case "replace":
-                default:
-                    return overlay;
-            }
+    // If base is also an array, apply merge strategy
+    if (Array.isArray(base)) {
+        switch (strategy) {
+            case "append":
+                return [...base, ...overlay];
+            case "prepend":
+                return [...overlay, ...base];
+            case "replace":
+            default:
+                return overlay;
         }
-        // Base is string, overlay is array - overlay replaces
-        return overlay;
     }
-    // Fallback (shouldn't reach here with proper types)
+    // Base is string, overlay is array - overlay replaces
     return overlay;
 }

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) {
@@ -202,6 +203,26 @@ export function mergeSettings(root, perRepo) {
     if (mergedLabels) {
         result.labels = mergedLabels;
     }
+    // Merge code scanning: per-repo fully replaces root (not shallow merge).
+    // Unlike `repo` settings (which shallow-merge via spread), code scanning
+    // uses full replacement because its 3 fields (state, querySuite, languages)
+    // are tightly coupled — partial inheritance (e.g., inheriting languages
+    // from root while changing querySuite) would be confusing.
+    // codeScanning: false means opt out of all root code scanning settings
+    if (perRepo?.codeScanning === false) {
+        // Opt-out: don't include any code scanning settings
+    }
+    else {
+        const mergedCodeScanning = perRepo?.codeScanning ?? root?.codeScanning;
+        if (mergedCodeScanning) {
+            // At this point mergedCodeScanning is CodeScanningSettings (not false),
+            // because root uses RawRootSettings where false is filtered by the
+            // outer check on perRepo?.codeScanning === false
+            if (typeof mergedCodeScanning === "object") {
+                result.codeScanning = mergedCodeScanning;
+            }
+        }
+    }
     return Object.keys(result).length > 0 ? result : undefined;
 }
 /**
@@ -343,6 +364,15 @@ function mergeRawSettings(base, overlay) {
             }
         }
     }
+    // Merge code scanning: overlay fully replaces base (same semantics as mergeSettings)
+    if (overlay.codeScanning !== undefined) {
+        if (overlay.codeScanning === false) {
+            result.codeScanning = false;
+        }
+        else {
+            result.codeScanning = structuredClone(overlay.codeScanning);
+        }
+    }
     // deleteOrphaned: overlay wins
     if (overlay.deleteOrphaned !== undefined) {
         result.deleteOrphaned = overlay.deleteOrphaned;

package/dist/config/types.d.ts

@@ -259,6 +259,14 @@ export interface Label {
     /** Rename target. Maps to GitHub API's new_name field. */
     new_name?: string;
 }
+export type CodeScanningState = "configured" | "not-configured";
+export type CodeScanningQuerySuite = "default" | "extended";
+export type CodeScanningLanguage = "actions" | "c-cpp" | "csharp" | "go" | "java-kotlin" | "javascript-typescript" | "python" | "ruby" | "swift";
+export interface CodeScanningSettings {
+    state: CodeScanningState;
+    querySuite?: CodeScanningQuerySuite;
+    languages?: CodeScanningLanguage[];
+}
 export interface RepoSettings {
     /** GitHub rulesets keyed by name */
     rulesets?: Record<string, Ruleset>;
@@ -266,6 +274,8 @@ export interface RepoSettings {
     repo?: GitHubRepoSettings;
     /** GitHub labels keyed by name */
     labels?: Record<string, Label>;
+    /** GitHub code scanning default setup */
+    codeScanning?: CodeScanningSettings;
     deleteOrphaned?: boolean;
 }
 export type ContentValue = Record<string, unknown> | string | string[];
@@ -323,6 +333,7 @@ export interface RawRootSettings {
     rulesets?: Record<string, Ruleset | false>;
     repo?: GitHubRepoSettings | false;
     labels?: Record<string, Label | false>;
+    codeScanning?: CodeScanningSettings | false;
     deleteOrphaned?: boolean;
 }
 export interface RawRepoSettings {
@@ -333,6 +344,7 @@ export interface RawRepoSettings {
     labels?: Record<string, Label | false> & {
         inherit?: boolean;
     };
+    codeScanning?: CodeScanningSettings | false;
     deleteOrphaned?: boolean;
 }
 export interface RawRepoConfig {