@aspruyt/xfg 4.0.0 → 4.0.2

package/dist/config/validator.js

@@ -1,6 +1,8 @@
 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";
+import { escapeRegExp } from "../shared/shell-utils.js";
+import { ValidationError } from "./errors.js";
 // Pattern for valid config ID: alphanumeric, hyphens, underscores
 const CONFIG_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
 const CONFIG_ID_MAX_LENGTH = 64;
@@ -19,12 +21,6 @@ function isValidGitUrl(url) {
     }
     return false;
 }
-/**
- * Escape special regex characters in a string.
- */
-function escapeRegExp(str) {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 /**
  * Check if a git URL points to GitHub (github.com).
  * Used to reject GitHub URLs as migration sources (not supported).
@@ -45,66 +41,136 @@ function getGitDisplayName(git) {
     }
     return git;
 }
+/**
+ * Validate file config fields shared between root files and per-repo overrides.
+ */
+function validateFileConfigFields(fileConfig, fileName, context) {
+    if (fileConfig.content !== undefined) {
+        const hasText = isTextContent(fileConfig.content);
+        const hasObject = isObjectContent(fileConfig.content);
+        if (!hasText && !hasObject) {
+            throw new ValidationError(`${context} file '${fileName}' content must be an object, string, or array of strings`);
+        }
+        const isStructured = isStructuredFileExtension(fileName);
+        if (isStructured && hasText) {
+            throw new ValidationError(`${context} file '${fileName}' has JSON/YAML extension but string content. Use object content for structured files.`);
+        }
+        if (!isStructured && hasObject) {
+            throw new ValidationError(`${context} file '${fileName}' has text extension but object content. Use string or string[] for text files, or use .json/.yaml/.yml extension.`);
+        }
+    }
+    if (fileConfig.mergeStrategy !== undefined &&
+        !VALID_STRATEGIES.includes(fileConfig.mergeStrategy)) {
+        throw new ValidationError(`${context} file '${fileName}' has invalid mergeStrategy: ${fileConfig.mergeStrategy}. Must be one of: ${VALID_STRATEGIES.join(", ")}`);
+    }
+    const booleanFields = [
+        "createOnly",
+        "executable",
+        "template",
+        "deleteOrphaned",
+    ];
+    for (const field of booleanFields) {
+        if (fileConfig[field] !== undefined &&
+            typeof fileConfig[field] !== "boolean") {
+            throw new ValidationError(`${context} file '${fileName}' ${field} must be a boolean`);
+        }
+    }
+    const stringFields = ["schemaUrl"];
+    for (const field of stringFields) {
+        if (fileConfig[field] !== undefined &&
+            typeof fileConfig[field] !== "string") {
+            throw new ValidationError(`${context} file '${fileName}' ${field} must be a string`);
+        }
+    }
+    if (fileConfig.header !== undefined) {
+        if (typeof fileConfig.header !== "string" &&
+            (!Array.isArray(fileConfig.header) ||
+                !fileConfig.header.every((h) => typeof h === "string"))) {
+            throw new ValidationError(`${context} file '${fileName}' header must be a string or array of strings`);
+        }
+    }
+    if (fileConfig.vars !== undefined) {
+        if (typeof fileConfig.vars !== "object" ||
+            fileConfig.vars === null ||
+            Array.isArray(fileConfig.vars)) {
+            throw new ValidationError(`${context} file '${fileName}' vars must be an object with string values`);
+        }
+        for (const [key, value] of Object.entries(fileConfig.vars)) {
+            if (typeof value !== "string") {
+                throw new ValidationError(`${context} file '${fileName}' vars.${key} must be a string`);
+            }
+        }
+    }
+}
 /**
  * Validates a single label configuration.
  */
 function validateLabel(label, name, context) {
     if (typeof label !== "object" || label === null || Array.isArray(label)) {
-        throw new Error(`${context}: label '${name}' must be an object`);
+        throw new ValidationError(`${context}: label '${name}' must be an object`);
     }
     const l = label;
     if (typeof l.color !== "string" || !/^#?[0-9a-fA-F]{6}$/.test(l.color)) {
-        throw new Error(`${context}: label '${name}' color must be a 6-character hex code (with or without #)`);
+        throw new ValidationError(`${context}: label '${name}' color must be a 6-character hex code (with or without #)`);
     }
     if (l.description !== undefined) {
         if (typeof l.description !== "string") {
-            throw new Error(`${context}: label '${name}' description must be a string`);
+            throw new ValidationError(`${context}: label '${name}' description must be a string`);
         }
         if (l.description.length > 100) {
-            throw new Error(`${context}: label '${name}' description exceeds 100 characters (GitHub limit)`);
+            throw new ValidationError(`${context}: label '${name}' description exceeds 100 characters (GitHub limit)`);
         }
     }
     if (l.new_name !== undefined && typeof l.new_name !== "string") {
-        throw new Error(`${context}: label '${name}' new_name must be a string`);
+        throw new ValidationError(`${context}: label '${name}' new_name must be a string`);
     }
 }
+function buildRootSettingsContext(config) {
+    return {
+        rulesetNames: config.settings?.rulesets
+            ? Object.keys(config.settings.rulesets).filter((k) => k !== "inherit")
+            : [],
+        hasRepoSettings: config.settings?.repo !== undefined && config.settings.repo !== false,
+        labelNames: config.settings?.labels
+            ? Object.keys(config.settings.labels).filter((k) => k !== "inherit")
+            : [],
+    };
+}
 /**
  * Validates settings object containing rulesets, labels, and repo settings.
  */
-export function validateSettings(settings, context, rootRulesetNames, hasRootRepoSettings, rootLabelNames) {
+function validateSettings(settings, context, rootRulesetNames, hasRootRepoSettings, rootLabelNames) {
     if (typeof settings !== "object" ||
         settings === null ||
         Array.isArray(settings)) {
-        throw new Error(`${context}: settings must be an object`);
+        throw new ValidationError(`${context}: settings must be an object`);
     }
     const s = settings;
     if (s.rulesets !== undefined) {
         if (typeof s.rulesets !== "object" ||
             s.rulesets === null ||
             Array.isArray(s.rulesets)) {
-            throw new Error(`${context}: rulesets must be an object`);
+            throw new ValidationError(`${context}: rulesets must be an object`);
         }
         const rulesets = s.rulesets;
         for (const [name, ruleset] of Object.entries(rulesets)) {
             // Skip reserved key
             if (name === "inherit")
                 continue;
-            // Check for opt-out of non-existent root ruleset
             if (ruleset === false) {
                 if (rootRulesetNames && !rootRulesetNames.includes(name)) {
-                    throw new Error(`${context}: Cannot opt out of '${name}' - not defined in root settings.rulesets`);
+                    throw new ValidationError(`${context}: Cannot opt out of '${name}' - not defined in root settings.rulesets`);
                 }
                 continue; // Skip further validation for false entries
             }
             validateRuleset(ruleset, name, context);
         }
     }
-    // Validate labels
     if (s.labels !== undefined) {
         if (typeof s.labels !== "object" ||
             s.labels === null ||
             Array.isArray(s.labels)) {
-            throw new Error(`${context}: labels must be an object`);
+            throw new ValidationError(`${context}: labels must be an object`);
         }
         const labels = s.labels;
         for (const [name, label] of Object.entries(labels)) {
@@ -112,7 +178,7 @@ export function validateSettings(settings, context, rootRulesetNames, hasRootRep
                 continue;
             if (label === false) {
                 if (rootLabelNames && !rootLabelNames.includes(name)) {
-                    throw new Error(`${context}: Cannot opt out of label '${name}' - not defined in root settings.labels`);
+                    throw new ValidationError(`${context}: Cannot opt out of label '${name}' - not defined in root settings.labels`);
                 }
                 continue;
             }
@@ -120,18 +186,17 @@ export function validateSettings(settings, context, rootRulesetNames, hasRootRep
         }
     }
     if (s.deleteOrphaned !== undefined && typeof s.deleteOrphaned !== "boolean") {
-        throw new Error(`${context}: settings.deleteOrphaned must be a boolean`);
+        throw new ValidationError(`${context}: settings.deleteOrphaned must be a boolean`);
     }
-    // Validate repo settings
     if (s.repo !== undefined) {
         if (s.repo === false) {
             if (!rootRulesetNames) {
                 // Root level — repo: false not valid here
-                throw new Error(`${context}: repo: false is not valid at root level. Define repo settings or remove the field.`);
+                throw new ValidationError(`${context}: repo: false is not valid at root level. Define repo settings or remove the field.`);
             }
             // Per-repo level — check root has repo settings to opt out of
             if (!hasRootRepoSettings) {
-                throw new Error(`${context}: Cannot opt out of repo settings — not defined in root settings.repo`);
+                throw new ValidationError(`${context}: Cannot opt out of repo settings — not defined in root settings.repo`);
             }
             // Valid opt-out, skip further repo validation
         }
@@ -140,389 +205,250 @@ export function validateSettings(settings, context, rootRulesetNames, hasRootRep
         }
     }
 }
-/**
- * Validates raw config structure before normalization.
- * @throws Error if validation fails
- */
-export function validateRawConfig(config) {
-    // Validate required id field
+function validateConfigId(config) {
     if (!config.id || typeof config.id !== "string") {
-        throw new Error("Config requires an 'id' field. This unique identifier is used to namespace managed files in .xfg.json");
+        throw new ValidationError("Config requires an 'id' field. This unique identifier is used to namespace managed files in .xfg.json");
     }
     if (!CONFIG_ID_PATTERN.test(config.id)) {
-        throw new Error(`Config 'id' contains invalid characters: '${config.id}'. Use only alphanumeric characters, hyphens, and underscores.`);
+        throw new ValidationError(`Config 'id' contains invalid characters: '${config.id}'. Use only alphanumeric characters, hyphens, and underscores.`);
     }
     if (config.id.length > CONFIG_ID_MAX_LENGTH) {
-        throw new Error(`Config 'id' exceeds maximum length of ${CONFIG_ID_MAX_LENGTH} characters`);
-    }
-    // Validate at least one of files or settings exists (including in groups)
-    const hasFiles = config.files &&
-        typeof config.files === "object" &&
-        Object.keys(config.files).length > 0;
-    const hasSettings = config.settings && typeof config.settings === "object";
-    const hasGroupFiles = config.groups &&
-        typeof config.groups === "object" &&
-        !Array.isArray(config.groups) &&
-        Object.values(config.groups).some((g) => g.files &&
-            Object.keys(g.files).filter((k) => k !== "inherit" && g.files[k] !== false).length > 0);
-    const hasGroupSettings = config.groups &&
-        typeof config.groups === "object" &&
-        !Array.isArray(config.groups) &&
-        Object.values(config.groups).some((g) => g.settings && typeof g.settings === "object");
-    if (!hasFiles && !hasSettings && !hasGroupFiles && !hasGroupSettings) {
-        throw new Error("Config requires at least one of: 'files' or 'settings'. " +
-            "Use 'files' to sync configuration files, or 'settings' to manage repository settings.");
+        throw new ValidationError(`Config 'id' exceeds maximum length of ${CONFIG_ID_MAX_LENGTH} characters`);
     }
-    const fileNames = hasFiles ? Object.keys(config.files) : [];
-    // Check for reserved key 'inherit' at root files level
-    if (hasFiles && "inherit" in config.files) {
-        throw new Error("'inherit' is a reserved key and cannot be used as a filename");
+}
+function validateRootFiles(config) {
+    if (!config.files || Object.keys(config.files).length === 0)
+        return;
+    if ("inherit" in config.files) {
+        throw new ValidationError("'inherit' is a reserved key and cannot be used as a filename");
     }
-    // Validate each file definition
-    for (const fileName of fileNames) {
+    for (const fileName of Object.keys(config.files)) {
         validateFileName(fileName);
         const fileConfig = config.files[fileName];
         if (!fileConfig || typeof fileConfig !== "object") {
-            throw new Error(`File '${fileName}' must have a configuration object`);
-        }
-        // Validate content type
-        if (fileConfig.content !== undefined) {
-            const hasText = isTextContent(fileConfig.content);
-            const hasObject = isObjectContent(fileConfig.content);
-            if (!hasText && !hasObject) {
-                throw new Error(`File '${fileName}' content must be an object, string, or array of strings`);
-            }
-            // Validate content type matches file extension
-            const isStructured = isStructuredFileExtension(fileName);
-            if (isStructured && hasText) {
-                throw new Error(`File '${fileName}' has JSON/YAML extension but string content. Use object content for structured files.`);
-            }
-            if (!isStructured && hasObject) {
-                throw new Error(`File '${fileName}' has text extension but object content. Use string or string[] for text files, or use .json/.yaml/.yml extension.`);
-            }
-        }
-        if (fileConfig.mergeStrategy !== undefined &&
-            !VALID_STRATEGIES.includes(fileConfig.mergeStrategy)) {
-            throw new Error(`File '${fileName}' has invalid mergeStrategy: ${fileConfig.mergeStrategy}. Must be one of: ${VALID_STRATEGIES.join(", ")}`);
+            throw new ValidationError(`File '${fileName}' must have a configuration object`);
         }
-        if (fileConfig.createOnly !== undefined &&
-            typeof fileConfig.createOnly !== "boolean") {
-            throw new Error(`File '${fileName}' createOnly must be a boolean`);
-        }
-        if (fileConfig.executable !== undefined &&
-            typeof fileConfig.executable !== "boolean") {
-            throw new Error(`File '${fileName}' executable must be a boolean`);
+        validateFileConfigFields(fileConfig, fileName, `File '${fileName}':`);
+    }
+}
+function validateRootSettings(config) {
+    if (config.settings === undefined)
+        return;
+    validateSettings(config.settings, "Root");
+    if (config.settings.rulesets && "inherit" in config.settings.rulesets) {
+        throw new ValidationError("'inherit' is a reserved key and cannot be used as a ruleset name");
+    }
+    if (config.settings.labels && "inherit" in config.settings.labels) {
+        throw new ValidationError("'inherit' is a reserved key and cannot be used as a label name");
+    }
+}
+function validateGithubHosts(config) {
+    if (config.githubHosts === undefined)
+        return;
+    if (!Array.isArray(config.githubHosts) ||
+        !config.githubHosts.every((h) => typeof h === "string")) {
+        throw new ValidationError("githubHosts must be an array of strings");
+    }
+    for (const host of config.githubHosts) {
+        if (!host) {
+            throw new ValidationError("githubHosts entries must be non-empty hostnames");
         }
-        if (fileConfig.header !== undefined) {
-            if (typeof fileConfig.header !== "string" &&
-                (!Array.isArray(fileConfig.header) ||
-                    !fileConfig.header.every((h) => typeof h === "string"))) {
-                throw new Error(`File '${fileName}' header must be a string or array of strings`);
-            }
+        if (host.includes("://")) {
+            throw new ValidationError(`githubHosts entries must be hostnames only, not URLs. Got: ${host}`);
         }
-        if (fileConfig.schemaUrl !== undefined &&
-            typeof fileConfig.schemaUrl !== "string") {
-            throw new Error(`File '${fileName}' schemaUrl must be a string`);
+        if (host.includes("/")) {
+            throw new ValidationError(`githubHosts entries must be hostnames only, not paths. Got: ${host}`);
         }
-        if (fileConfig.template !== undefined &&
-            typeof fileConfig.template !== "boolean") {
-            throw new Error(`File '${fileName}' template must be a boolean`);
+    }
+}
+function validatePrOptions(config) {
+    if (config.prOptions?.labels === undefined)
+        return;
+    if (!Array.isArray(config.prOptions.labels)) {
+        throw new ValidationError("prOptions.labels must be an array of strings");
+    }
+    for (const label of config.prOptions.labels) {
+        if (typeof label !== "string" || label.length === 0) {
+            throw new ValidationError("prOptions.labels entries must be non-empty strings");
         }
-        if (fileConfig.vars !== undefined) {
-            if (typeof fileConfig.vars !== "object" ||
-                fileConfig.vars === null ||
-                Array.isArray(fileConfig.vars)) {
-                throw new Error(`File '${fileName}' vars must be an object with string values`);
-            }
-            for (const [key, value] of Object.entries(fileConfig.vars)) {
-                if (typeof value !== "string") {
-                    throw new Error(`File '${fileName}' vars.${key} must be a string`);
-                }
+    }
+}
+function validateGroups(config) {
+    if (config.groups === undefined)
+        return;
+    if (typeof config.groups !== "object" ||
+        config.groups === null ||
+        Array.isArray(config.groups)) {
+        throw new ValidationError("groups must be an object");
+    }
+    const rootCtx = buildRootSettingsContext(config);
+    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 (group.files) {
+            for (const [fileName, fileConfig] of Object.entries(group.files)) {
+                if (fileName === "inherit")
+                    continue;
+                if (fileConfig === false)
+                    continue;
+                if (fileConfig === undefined)
+                    continue;
+                validateFileConfigFields(fileConfig, fileName, `groups.${groupName}:`);
             }
         }
-        if (fileConfig.deleteOrphaned !== undefined &&
-            typeof fileConfig.deleteOrphaned !== "boolean") {
-            throw new Error(`File '${fileName}' deleteOrphaned must be a boolean`);
+        if (group.settings !== undefined) {
+            validateSettings(group.settings, `groups.${groupName}`, rootCtx.rulesetNames, rootCtx.hasRepoSettings, rootCtx.labelNames);
         }
     }
-    // Validate global deleteOrphaned
-    if (config.deleteOrphaned !== undefined &&
-        typeof config.deleteOrphaned !== "boolean") {
-        throw new Error("Global deleteOrphaned must be a boolean");
+}
+function validateRepoEntry(config, repo, index) {
+    if (!repo.git) {
+        throw new ValidationError(`Repo at index ${index} missing required field: git`);
     }
-    if (!config.repos || !Array.isArray(config.repos)) {
-        throw new Error("Config missing required field: repos (must be an array)");
+    if (Array.isArray(repo.git) && repo.git.length === 0) {
+        throw new ValidationError(`Repo at index ${index} has empty git array`);
     }
-    // Validate root settings
-    if (config.settings !== undefined) {
-        validateSettings(config.settings, "Root");
-        // Check for reserved key 'inherit' at root rulesets level
-        if (config.settings.rulesets && "inherit" in config.settings.rulesets) {
-            throw new Error("'inherit' is a reserved key and cannot be used as a ruleset name");
+    const repoLabel = getGitDisplayName(repo.git);
+    if (repo.upstream !== undefined && repo.source !== undefined) {
+        throw new ValidationError(`Repo ${repoLabel}: 'upstream' and 'source' are mutually exclusive. ` +
+            `Use 'upstream' to fork, or 'source' to migrate, not both.`);
+    }
+    if (repo.upstream !== undefined) {
+        if (typeof repo.upstream !== "string") {
+            throw new ValidationError(`Repo ${repoLabel}: 'upstream' must be a string`);
         }
-        // Check for reserved key 'inherit' at root labels level
-        if (config.settings.labels && "inherit" in config.settings.labels) {
-            throw new Error("'inherit' is a reserved key and cannot be used as a label name");
+        if (!isValidGitUrl(repo.upstream)) {
+            throw new ValidationError(`Repo ${repoLabel}: 'upstream' must be a valid git URL ` +
+                `(SSH: git@host:path or HTTPS: https://host/path)`);
         }
     }
-    // Validate githubHosts if provided
-    if (config.githubHosts !== undefined) {
-        if (!Array.isArray(config.githubHosts) ||
-            !config.githubHosts.every((h) => typeof h === "string")) {
-            throw new Error("githubHosts must be an array of strings");
+    if (repo.source !== undefined) {
+        if (typeof repo.source !== "string") {
+            throw new ValidationError(`Repo ${repoLabel}: 'source' must be a string`);
         }
-        for (const host of config.githubHosts) {
-            if (!host) {
-                throw new Error("githubHosts entries must be non-empty hostnames");
-            }
-            if (host.includes("://")) {
-                throw new Error(`githubHosts entries must be hostnames only, not URLs. Got: ${host}`);
-            }
-            if (host.includes("/")) {
-                throw new Error(`githubHosts entries must be hostnames only, not paths. Got: ${host}`);
-            }
+        if (!isValidGitUrl(repo.source)) {
+            throw new ValidationError(`Repo ${repoLabel}: 'source' must be a valid git URL ` +
+                `(SSH: git@host:path or HTTPS: https://host/path)`);
         }
-    }
-    // Validate prOptions.labels if present
-    if (config.prOptions?.labels !== undefined) {
-        if (!Array.isArray(config.prOptions.labels)) {
-            throw new Error("prOptions.labels must be an array of strings");
+        if (isGitHubUrl(repo.source, config.githubHosts)) {
+            throw new ValidationError(`Repo ${repoLabel}: 'source' cannot be a GitHub URL. ` +
+                `Migration from GitHub is not supported. Currently supported sources: Azure DevOps`);
         }
-        for (const label of config.prOptions.labels) {
-            if (typeof label !== "string" || label.length === 0) {
-                throw new Error("prOptions.labels entries must be non-empty strings");
+    }
+    if (repo.groups !== undefined) {
+        if (!Array.isArray(repo.groups) ||
+            !repo.groups.every((g) => typeof g === "string")) {
+            throw new ValidationError(`Repo at index ${index}: groups must be an array of strings`);
+        }
+        const seen = new Set();
+        for (const groupName of repo.groups) {
+            if (!config.groups || !config.groups[groupName]) {
+                throw new ValidationError(`Repo at index ${index}: group '${groupName}' is not defined in root 'groups'`);
             }
+            if (seen.has(groupName)) {
+                throw new ValidationError(`Repo at index ${index}: duplicate group '${groupName}'`);
+            }
+            seen.add(groupName);
         }
     }
-    // Validate groups
-    if (config.groups !== undefined) {
-        if (typeof config.groups !== "object" ||
-            config.groups === null ||
-            Array.isArray(config.groups)) {
-            throw new Error("groups must be an object");
+    if (repo.files) {
+        if (typeof repo.files !== "object" || Array.isArray(repo.files)) {
+            throw new ValidationError(`Repo at index ${index}: files must be an object`);
         }
-        const rootRulesetNames = config.settings?.rulesets
-            ? Object.keys(config.settings.rulesets).filter((k) => k !== "inherit")
-            : [];
-        const hasRootRepoSettings = config.settings?.repo !== undefined && config.settings.repo !== false;
-        const rootLabelNames = config.settings?.labels
-            ? Object.keys(config.settings.labels).filter((k) => k !== "inherit")
-            : [];
-        for (const [groupName, group] of Object.entries(config.groups)) {
-            if (groupName === "inherit") {
-                throw new Error("'inherit' is a reserved key and cannot be used as a group name");
-            }
-            // Validate group files
-            if (group.files) {
-                for (const [fileName, fileConfig] of Object.entries(group.files)) {
-                    if (fileName === "inherit")
-                        continue;
-                    if (fileConfig === false)
-                        continue;
-                    if (fileConfig === undefined)
-                        continue;
-                    const fc = fileConfig;
-                    if (fc.content !== undefined) {
-                        const hasText = isTextContent(fc.content);
-                        const hasObject = isObjectContent(fc.content);
-                        if (!hasText && !hasObject) {
-                            throw new Error(`groups.${groupName}: file '${fileName}' content must be an object, string, or array of strings`);
-                        }
-                        const isStructured = isStructuredFileExtension(fileName);
-                        if (isStructured && hasText) {
-                            throw new Error(`groups.${groupName}: file '${fileName}' has JSON/YAML extension but string content`);
-                        }
-                        if (!isStructured && hasObject) {
-                            throw new Error(`groups.${groupName}: file '${fileName}' has text extension but object content`);
-                        }
+        const knownFiles = new Set(config.files ? Object.keys(config.files) : []);
+        if (repo.groups && config.groups) {
+            for (const groupName of repo.groups) {
+                const group = config.groups[groupName];
+                if (group?.files) {
+                    for (const fn of Object.keys(group.files)) {
+                        if (fn !== "inherit")
+                            knownFiles.add(fn);
                     }
                 }
             }
-            // Validate group settings
-            if (group.settings !== undefined) {
-                validateSettings(group.settings, `groups.${groupName}`, rootRulesetNames, hasRootRepoSettings, rootLabelNames);
-            }
-        }
-    }
-    // Validate each repo
-    for (let i = 0; i < config.repos.length; i++) {
-        const repo = config.repos[i];
-        if (!repo.git) {
-            throw new Error(`Repo at index ${i} missing required field: git`);
-        }
-        if (Array.isArray(repo.git) && repo.git.length === 0) {
-            throw new Error(`Repo at index ${i} has empty git array`);
         }
-        // Validate lifecycle fields (upstream/source)
-        if (repo.upstream !== undefined && repo.source !== undefined) {
-            throw new Error(`Repo ${getGitDisplayName(repo.git)}: 'upstream' and 'source' are mutually exclusive. ` +
-                `Use 'upstream' to fork, or 'source' to migrate, not both.`);
-        }
-        if (repo.upstream !== undefined) {
-            if (typeof repo.upstream !== "string") {
-                throw new Error(`Repo ${getGitDisplayName(repo.git)}: 'upstream' must be a string`);
-            }
-            if (!isValidGitUrl(repo.upstream)) {
-                throw new Error(`Repo ${getGitDisplayName(repo.git)}: 'upstream' must be a valid git URL ` +
-                    `(SSH: git@host:path or HTTPS: https://host/path)`);
+        for (const fileName of Object.keys(repo.files)) {
+            if (fileName === "inherit") {
+                const inheritValue = repo.files.inherit;
+                if (typeof inheritValue !== "boolean") {
+                    throw new ValidationError(`Repo at index ${index}: files.inherit must be a boolean`);
+                }
+                continue;
             }
-        }
-        if (repo.source !== undefined) {
-            if (typeof repo.source !== "string") {
-                throw new Error(`Repo ${getGitDisplayName(repo.git)}: 'source' must be a string`);
+            if (!knownFiles.has(fileName)) {
+                throw new ValidationError(`Repo at index ${index} references undefined file '${fileName}'. File must be defined in root 'files' object or in a referenced group.`);
             }
-            if (!isValidGitUrl(repo.source)) {
-                throw new Error(`Repo ${getGitDisplayName(repo.git)}: 'source' must be a valid git URL ` +
-                    `(SSH: git@host:path or HTTPS: https://host/path)`);
+            const fileOverride = repo.files[fileName];
+            if (fileOverride === false) {
+                continue;
             }
-            if (isGitHubUrl(repo.source, config.githubHosts)) {
-                throw new Error(`Repo ${getGitDisplayName(repo.git)}: 'source' cannot be a GitHub URL. ` +
-                    `Migration from GitHub is not supported. Currently supported sources: Azure DevOps`);
+            if (fileOverride.override && !fileOverride.content) {
+                throw new ValidationError(`Repo ${repoLabel} has override: true for file '${fileName}' but no content defined. ` +
+                    `Use content: "" for an empty text file override, or content: {} for an empty JSON/YAML override.`);
             }
+            validateFileConfigFields(fileOverride, fileName, `Repo ${repoLabel}:`);
         }
-        // Validate per-repo groups
-        if (repo.groups !== undefined) {
-            if (!Array.isArray(repo.groups) ||
-                !repo.groups.every((g) => typeof g === "string")) {
-                throw new Error(`Repo at index ${i}: groups must be an array of strings`);
-            }
-            const seen = new Set();
+    }
+    if (repo.settings !== undefined) {
+        const rootCtx = buildRootSettingsContext(config);
+        if (repo.groups && config.groups) {
             for (const groupName of repo.groups) {
-                if (!config.groups || !config.groups[groupName]) {
-                    throw new Error(`Repo at index ${i}: group '${groupName}' is not defined in root 'groups'`);
-                }
-                if (seen.has(groupName)) {
-                    throw new Error(`Repo at index ${i}: duplicate group '${groupName}'`);
-                }
-                seen.add(groupName);
-            }
-        }
-        // Validate per-repo file overrides
-        if (repo.files) {
-            if (typeof repo.files !== "object" || Array.isArray(repo.files)) {
-                throw new Error(`Repo at index ${i}: files must be an object`);
-            }
-            // Build the set of known files once per repo (root + referenced groups)
-            const knownFiles = new Set(config.files ? Object.keys(config.files) : []);
-            if (repo.groups && config.groups) {
-                for (const groupName of repo.groups) {
-                    const group = config.groups[groupName];
-                    if (group?.files) {
-                        for (const fn of Object.keys(group.files)) {
-                            if (fn !== "inherit")
-                                knownFiles.add(fn);
-                        }
+                const group = config.groups[groupName];
+                if (group?.settings?.rulesets) {
+                    for (const name of Object.keys(group.settings.rulesets)) {
+                        if (name !== "inherit")
+                            rootCtx.rulesetNames.push(name);
                     }
                 }
-            }
-            for (const fileName of Object.keys(repo.files)) {
-                // Skip reserved key 'inherit'
-                if (fileName === "inherit") {
-                    const inheritValue = repo.files.inherit;
-                    if (typeof inheritValue !== "boolean") {
-                        throw new Error(`Repo at index ${i}: files.inherit must be a boolean`);
-                    }
-                    continue;
-                }
-                // Ensure the file is defined at root level or in a referenced group
-                if (!knownFiles.has(fileName)) {
-                    throw new Error(`Repo at index ${i} references undefined file '${fileName}'. File must be defined in root 'files' object or in a referenced group.`);
-                }
-                const fileOverride = repo.files[fileName];
-                // false means exclude this file for this repo - no further validation needed
-                if (fileOverride === false) {
-                    continue;
-                }
-                if (fileOverride.override && !fileOverride.content) {
-                    throw new Error(`Repo ${getGitDisplayName(repo.git)} has override: true for file '${fileName}' but no content defined. ` +
-                        `Use content: "" for an empty text file override, or content: {} for an empty JSON/YAML override.`);
-                }
-                // Validate content type
-                if (fileOverride.content !== undefined) {
-                    const hasText = isTextContent(fileOverride.content);
-                    const hasObject = isObjectContent(fileOverride.content);
-                    if (!hasText && !hasObject) {
-                        throw new Error(`Repo at index ${i}: file '${fileName}' content must be an object, string, or array of strings`);
-                    }
-                    // Validate content type matches file extension
-                    const isStructured = isStructuredFileExtension(fileName);
-                    if (isStructured && hasText) {
-                        throw new Error(`Repo at index ${i}: file '${fileName}' has JSON/YAML extension but string content. Use object content for structured files.`);
-                    }
-                    if (!isStructured && hasObject) {
-                        throw new Error(`Repo at index ${i}: file '${fileName}' has text extension but object content. Use string or string[] for text files, or use .json/.yaml/.yml extension.`);
-                    }
-                }
-                if (fileOverride.createOnly !== undefined &&
-                    typeof fileOverride.createOnly !== "boolean") {
-                    throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' createOnly must be a boolean`);
-                }
-                if (fileOverride.executable !== undefined &&
-                    typeof fileOverride.executable !== "boolean") {
-                    throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' executable must be a boolean`);
-                }
-                if (fileOverride.header !== undefined) {
-                    if (typeof fileOverride.header !== "string" &&
-                        (!Array.isArray(fileOverride.header) ||
-                            !fileOverride.header.every((h) => typeof h === "string"))) {
-                        throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' header must be a string or array of strings`);
-                    }
-                }
-                if (fileOverride.schemaUrl !== undefined &&
-                    typeof fileOverride.schemaUrl !== "string") {
-                    throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' schemaUrl must be a string`);
-                }
-                if (fileOverride.template !== undefined &&
-                    typeof fileOverride.template !== "boolean") {
-                    throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' template must be a boolean`);
-                }
-                if (fileOverride.vars !== undefined) {
-                    if (typeof fileOverride.vars !== "object" ||
-                        fileOverride.vars === null ||
-                        Array.isArray(fileOverride.vars)) {
-                        throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' vars must be an object with string values`);
-                    }
-                    for (const [key, value] of Object.entries(fileOverride.vars)) {
-                        if (typeof value !== "string") {
-                            throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' vars.${key} must be a string`);
-                        }
-                    }
-                }
-                if (fileOverride.deleteOrphaned !== undefined &&
-                    typeof fileOverride.deleteOrphaned !== "boolean") {
-                    throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' deleteOrphaned must be a boolean`);
-                }
-            }
-        }
-        // Validate per-repo settings
-        if (repo.settings !== undefined) {
-            const rootRulesetNames = config.settings?.rulesets
-                ? Object.keys(config.settings.rulesets).filter((k) => k !== "inherit")
-                : [];
-            const hasRootRepoSettings = config.settings?.repo !== undefined && config.settings.repo !== false;
-            const rootLabelNames = config.settings?.labels
-                ? Object.keys(config.settings.labels).filter((k) => k !== "inherit")
-                : [];
-            // Augment known names with those from the repo's referenced groups
-            if (repo.groups && config.groups) {
-                for (const groupName of repo.groups) {
-                    const group = config.groups[groupName];
-                    if (group?.settings?.rulesets) {
-                        for (const name of Object.keys(group.settings.rulesets)) {
-                            if (name !== "inherit")
-                                rootRulesetNames.push(name);
-                        }
-                    }
-                    if (group?.settings?.labels) {
-                        for (const name of Object.keys(group.settings.labels)) {
-                            if (name !== "inherit")
-                                rootLabelNames.push(name);
-                        }
+                if (group?.settings?.labels) {
+                    for (const name of Object.keys(group.settings.labels)) {
+                        if (name !== "inherit")
+                            rootCtx.labelNames.push(name);
                     }
                 }
             }
-            validateSettings(repo.settings, `Repo ${getGitDisplayName(repo.git)}`, rootRulesetNames, hasRootRepoSettings, rootLabelNames);
         }
+        validateSettings(repo.settings, `Repo ${repoLabel}`, rootCtx.rulesetNames, rootCtx.hasRepoSettings, rootCtx.labelNames);
+    }
+}
+/**
+ * Validates raw config structure before normalization.
+ * @throws Error if validation fails
+ */
+export function validateRawConfig(config) {
+    validateConfigId(config);
+    const hasFiles = config.files &&
+        typeof config.files === "object" &&
+        Object.keys(config.files).length > 0;
+    const hasSettings = config.settings && typeof config.settings === "object";
+    const hasGroupFiles = config.groups &&
+        typeof config.groups === "object" &&
+        !Array.isArray(config.groups) &&
+        Object.values(config.groups).some((g) => g.files &&
+            Object.keys(g.files).filter((k) => k !== "inherit" && g.files[k] !== false).length > 0);
+    const hasGroupSettings = config.groups &&
+        typeof config.groups === "object" &&
+        !Array.isArray(config.groups) &&
+        Object.values(config.groups).some((g) => g.settings && typeof g.settings === "object");
+    if (!hasFiles && !hasSettings && !hasGroupFiles && !hasGroupSettings) {
+        throw new ValidationError("Config requires at least one of: 'files' or 'settings'. " +
+            "Use 'files' to sync configuration files, or 'settings' to manage repository settings.");
+    }
+    validateRootFiles(config);
+    if (config.deleteOrphaned !== undefined &&
+        typeof config.deleteOrphaned !== "boolean") {
+        throw new ValidationError("Global deleteOrphaned must be a boolean");
+    }
+    if (!config.repos || !Array.isArray(config.repos)) {
+        throw new ValidationError("Config missing required field: repos (must be an array)");
+    }
+    validateRootSettings(config);
+    validateGithubHosts(config);
+    validatePrOptions(config);
+    validateGroups(config);
+    for (let i = 0; i < config.repos.length; i++) {
+        validateRepoEntry(config, config.repos[i], i);
     }
 }
 // =============================================================================
@@ -548,7 +474,7 @@ export function validateForSync(config) {
         !hasSettings &&
         !hasRepoSettings &&
         !hasGroupSettings) {
-        throw new Error("Config requires at least one of: 'files' or 'settings'. " +
+        throw new ValidationError("Config requires at least one of: 'files' or 'settings'. " +
             "Use 'files' to sync configuration files, or 'settings' to manage repository settings.");
     }
 }
@@ -558,16 +484,13 @@ export function validateForSync(config) {
 export function hasActionableSettings(settings) {
     if (!settings)
         return false;
-    // Check for rulesets (filter out inherit key)
     if (settings.rulesets &&
         Object.keys(settings.rulesets).filter((k) => k !== "inherit").length > 0) {
         return true;
     }
-    // Check for repo settings
     if (settings.repo && Object.keys(settings.repo).length > 0) {
         return true;
     }
-    // Check for labels (filter out inherit key)
     if (settings.labels &&
         Object.keys(settings.labels).filter((k) => k !== "inherit").length > 0) {
         return true;