@aspruyt/xfg 3.9.12 → 3.9.14

package/dist/config/validator.js

@@ -46,9 +46,32 @@ function getGitDisplayName(git) {
     return git;
 }
 /**
- * Validates settings object containing rulesets.
+ * Validates a single label configuration.
  */
-export function validateSettings(settings, context, rootRulesetNames, hasRootRepoSettings) {
+function validateLabel(label, name, context) {
+    if (typeof label !== "object" || label === null || Array.isArray(label)) {
+        throw new Error(`${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 #)`);
+    }
+    if (l.description !== undefined) {
+        if (typeof l.description !== "string") {
+            throw new Error(`${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)`);
+        }
+    }
+    if (l.new_name !== undefined && typeof l.new_name !== "string") {
+        throw new Error(`${context}: label '${name}' new_name must be a string`);
+    }
+}
+/**
+ * Validates settings object containing rulesets, labels, and repo settings.
+ */
+export function validateSettings(settings, context, rootRulesetNames, hasRootRepoSettings, rootLabelNames) {
     if (typeof settings !== "object" ||
         settings === null ||
         Array.isArray(settings)) {
@@ -76,6 +99,26 @@ export function validateSettings(settings, context, rootRulesetNames, hasRootRep
             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`);
+        }
+        const labels = s.labels;
+        for (const [name, label] of Object.entries(labels)) {
+            if (name === "inherit")
+                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`);
+                }
+                continue;
+            }
+            validateLabel(label, name, context);
+        }
+    }
     if (s.deleteOrphaned !== undefined && typeof s.deleteOrphaned !== "boolean") {
         throw new Error(`${context}: settings.deleteOrphaned must be a boolean`);
     }
@@ -208,6 +251,10 @@ export function validateRawConfig(config) {
         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");
         }
+        // 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");
+        }
     }
     // Validate githubHosts if provided
     if (config.githubHosts !== undefined) {
@@ -353,7 +400,10 @@ export function validateRawConfig(config) {
                 ? Object.keys(config.settings.rulesets).filter((k) => k !== "inherit")
                 : [];
             const hasRootRepoSettings = config.settings?.repo !== undefined && config.settings.repo !== false;
-            validateSettings(repo.settings, `Repo ${getGitDisplayName(repo.git)}`, rootRulesetNames, hasRootRepoSettings);
+            const rootLabelNames = config.settings?.labels
+                ? Object.keys(config.settings.labels).filter((k) => k !== "inherit")
+                : [];
+            validateSettings(repo.settings, `Repo ${getGitDisplayName(repo.git)}`, rootRulesetNames, hasRootRepoSettings, rootLabelNames);
         }
     }
 }
@@ -377,19 +427,24 @@ export function validateForSync(config) {
 }
 /**
  * Checks if settings contain actionable configuration.
- * Currently only rulesets, but extensible for future settings features.
  */
 export function hasActionableSettings(settings) {
     if (!settings)
         return false;
-    // Check for rulesets
-    if (settings.rulesets && Object.keys(settings.rulesets).length > 0) {
+    // 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;
+    }
     return false;
 }
 /**
@@ -408,7 +463,7 @@ export function validateForSettings(config) {
     const rootActionable = hasActionableSettings(config.settings);
     const repoActionable = config.repos.some((repo) => hasActionableSettings(repo.settings));
     if (!rootActionable && !repoActionable) {
-        throw new Error("No actionable settings configured. Currently supported: rulesets. " +
+        throw new Error("No actionable settings configured. Currently supported: rulesets, repo, labels. " +
             "To sync files instead, use 'xfg sync'. " +
             "See docs: https://anthony-spruyt.github.io/xfg/settings");
     }

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { runSync, runSettings } from "./cli/index.js";
 export type { SyncOptions, SettingsOptions, SharedOptions, } from "./cli/index.js";
-export { type IRepositoryProcessor, type ProcessorFactory, defaultProcessorFactory, type IRulesetProcessor, type RulesetProcessorFactory, defaultRulesetProcessorFactory, type RepoSettingsProcessorFactory, defaultRepoSettingsProcessorFactory, } from "./cli/index.js";
+export { type IRepositoryProcessor, type ProcessorFactory, defaultProcessorFactory, type IRulesetProcessor, type RulesetProcessorFactory, defaultRulesetProcessorFactory, type RepoSettingsProcessorFactory, defaultRepoSettingsProcessorFactory, type ILabelsProcessor, type LabelsProcessorFactory, defaultLabelsProcessorFactory, } from "./cli/index.js";

package/dist/index.js

@@ -1,3 +1,3 @@
 // Public API for library consumers
 export { runSync, runSettings } from "./cli/index.js";
-export { defaultProcessorFactory, defaultRulesetProcessorFactory, defaultRepoSettingsProcessorFactory, } from "./cli/index.js";
+export { defaultProcessorFactory, defaultRulesetProcessorFactory, defaultRepoSettingsProcessorFactory, defaultLabelsProcessorFactory, } from "./cli/index.js";

package/dist/output/github-summary.d.ts

@@ -19,6 +19,11 @@ export interface RepoSettingsPlanDetail {
     property: string;
     action: "add" | "change";
 }
+export interface LabelsPlanDetail {
+    name: string;
+    action: "create" | "update" | "delete" | "unchanged";
+    newName?: string;
+}
 export interface RepoResult {
     repoName: string;
     status: "succeeded" | "skipped" | "failed";
@@ -28,6 +33,7 @@ export interface RepoResult {
     fileChanges?: FileChanges;
     rulesetPlanDetails?: RulesetPlanDetail[];
     repoSettingsPlanDetails?: RepoSettingsPlanDetail[];
+    labelsPlanDetails?: LabelsPlanDetail[];
 }
 export interface SummaryData {
     title: string;

package/dist/output/github-summary.js

@@ -21,6 +21,9 @@ function formatChangesColumn(result) {
         result.repoSettingsPlanDetails.length > 0) {
         parts.push(formatSettingsPlanSummary(result.repoSettingsPlanDetails));
     }
+    if (result.labelsPlanDetails && result.labelsPlanDetails.length > 0) {
+        parts.push(formatLabelsPlanSummary(result.labelsPlanDetails));
+    }
     return parts.length > 0 ? parts.join("; ") : "-";
 }
 function formatStatus(result, dryRun) {
@@ -110,6 +113,19 @@ function formatSettingsPlanSummary(details) {
         parts.push(`${changes} to change`);
     return parts.join(", ") || "no changes";
 }
+function formatLabelsPlanSummary(details) {
+    const creates = details.filter((d) => d.action === "create").length;
+    const updates = details.filter((d) => d.action === "update").length;
+    const deletes = details.filter((d) => d.action === "delete").length;
+    const parts = [];
+    if (creates > 0)
+        parts.push(`${creates} to create`);
+    if (updates > 0)
+        parts.push(`${updates} to update`);
+    if (deletes > 0)
+        parts.push(`${deletes} to delete`);
+    return parts.join(", ") || "no changes";
+}
 export function formatSummary(data) {
     const lines = [];
     // Header
@@ -176,6 +192,29 @@ export function formatSummary(data) {
                 lines.push("");
                 lines.push("</details>");
             }
+            if (result.labelsPlanDetails && result.labelsPlanDetails.length > 0) {
+                lines.push("");
+                lines.push("<details>");
+                lines.push(`<summary>${result.repoName} — Labels: ${formatLabelsPlanSummary(result.labelsPlanDetails)}</summary>`);
+                lines.push("");
+                lines.push("| Label | Action |");
+                lines.push("|-------|--------|");
+                for (const detail of result.labelsPlanDetails) {
+                    const action = detail.action === "create"
+                        ? "+ Create"
+                        : detail.action === "update"
+                            ? "~ Update"
+                            : detail.action === "delete"
+                                ? "- Delete"
+                                : "No change";
+                    const name = detail.newName
+                        ? `${detail.name} \u2192 ${detail.newName}`
+                        : detail.name;
+                    lines.push(`| ${name} | ${action} |`);
+                }
+                lines.push("");
+                lines.push("</details>");
+            }
         }
         lines.push("");
         lines.push("</details>");

package/dist/output/settings-report.d.ts

@@ -1,5 +1,5 @@
 import { type PropertyDiff } from "../settings/rulesets/formatter.js";
-import type { Ruleset } from "../config/index.js";
+import type { Ruleset, Label } from "../config/index.js";
 export interface SettingsReport {
     repos: RepoChanges[];
     totals: {
@@ -12,12 +12,18 @@ export interface SettingsReport {
             update: number;
             delete: number;
         };
+        labels: {
+            create: number;
+            update: number;
+            delete: number;
+        };
     };
 }
 export interface RepoChanges {
     repoName: string;
     settings: SettingChange[];
     rulesets: RulesetChange[];
+    labels: LabelChange[];
     error?: string;
 }
 export interface SettingChange {
@@ -32,6 +38,17 @@ export interface RulesetChange {
     propertyDiffs?: PropertyDiff[];
     config?: Ruleset;
 }
+export interface LabelChange {
+    name: string;
+    action: "create" | "update" | "delete";
+    newName?: string;
+    propertyChanges?: {
+        property: string;
+        oldValue?: string;
+        newValue?: string;
+    }[];
+    config?: Label;
+}
 export declare function formatSettingsReportCLI(report: SettingsReport): string[];
 export declare function formatValuePlain(val: unknown): string;
 export declare function formatRulesetConfigPlain(config: Ruleset): string[];

package/dist/output/settings-report.js

@@ -68,6 +68,8 @@ function formatSummary(totals) {
     const parts = [];
     const settingsTotal = totals.settings.add + totals.settings.change;
     const rulesetsTotal = totals.rulesets.create + totals.rulesets.update + totals.rulesets.delete;
+    const labelTotals = totals.labels;
+    const labelsTotal = labelTotals.create + labelTotals.update + labelTotals.delete;
     if (settingsTotal > 0) {
         const settingWord = settingsTotal === 1 ? "setting" : "settings";
         const actions = [];
@@ -88,6 +90,17 @@ function formatSummary(totals) {
             actions.push(`${totals.rulesets.delete} to delete`);
         parts.push(`${rulesetsTotal} ${rulesetWord} (${actions.join(", ")})`);
     }
+    if (labelsTotal > 0) {
+        const labelWord = labelsTotal === 1 ? "label" : "labels";
+        const actions = [];
+        if (labelTotals.create > 0)
+            actions.push(`${labelTotals.create} to create`);
+        if (labelTotals.update > 0)
+            actions.push(`${labelTotals.update} to update`);
+        if (labelTotals.delete > 0)
+            actions.push(`${labelTotals.delete} to delete`);
+        parts.push(`${labelsTotal} ${labelWord} (${actions.join(", ")})`);
+    }
     if (parts.length === 0) {
         return "No changes";
     }
@@ -101,6 +114,7 @@ export function formatSettingsReportCLI(report) {
     for (const repo of report.repos) {
         if (repo.settings.length === 0 &&
             repo.rulesets.length === 0 &&
+            repo.labels.length === 0 &&
             !repo.error) {
             continue;
         }
@@ -140,6 +154,41 @@ export function formatSettingsReportCLI(report) {
                 lines.push(chalk.red(`    - ruleset "${ruleset.name}"`));
             }
         }
+        // Labels
+        for (const label of repo.labels) {
+            if (label.action === "create") {
+                lines.push(chalk.green(`    + label "${label.name}"`));
+                if (label.config) {
+                    lines.push(chalk.green(`        color: "${label.config.color}"`));
+                    if (label.config.description !== undefined) {
+                        lines.push(chalk.green(`        description: "${label.config.description}"`));
+                    }
+                }
+            }
+            else if (label.action === "update") {
+                if (label.newName) {
+                    lines.push(chalk.yellow(`    ~ label "${label.name}" \u2192 "${label.newName}"`));
+                }
+                else {
+                    lines.push(chalk.yellow(`    ~ label "${label.name}"`));
+                }
+                if (label.propertyChanges) {
+                    for (const prop of label.propertyChanges) {
+                        if (prop.property === "new_name")
+                            continue;
+                        if (prop.oldValue !== undefined) {
+                            lines.push(chalk.yellow(`        ${prop.property}: "${prop.oldValue}" \u2192 "${prop.newValue}"`));
+                        }
+                        else {
+                            lines.push(chalk.yellow(`        ${prop.property}: "${prop.newValue}"`));
+                        }
+                    }
+                }
+            }
+            else if (label.action === "delete") {
+                lines.push(chalk.red(`    - label "${label.name}"`));
+            }
+        }
         // Error
         if (repo.error) {
             lines.push(chalk.red(`    Error: ${repo.error}`));
@@ -230,6 +279,7 @@ export function formatSettingsReportMarkdown(report, dryRun) {
     for (const repo of report.repos) {
         if (repo.settings.length === 0 &&
             repo.rulesets.length === 0 &&
+            repo.labels.length === 0 &&
             !repo.error) {
             continue;
         }
@@ -274,6 +324,40 @@ export function formatSettingsReportMarkdown(report, dryRun) {
                 diffLines.push(`- ruleset "${ruleset.name}"`);
             }
         }
+        for (const label of repo.labels) {
+            if (label.action === "create") {
+                diffLines.push(`+ label "${label.name}"`);
+                if (label.config) {
+                    diffLines.push(`+   color: "${label.config.color}"`);
+                    if (label.config.description !== undefined) {
+                        diffLines.push(`+   description: "${label.config.description}"`);
+                    }
+                }
+            }
+            else if (label.action === "update") {
+                if (label.newName) {
+                    diffLines.push(`! label "${label.name}" \u2192 "${label.newName}"`);
+                }
+                else {
+                    diffLines.push(`! label "${label.name}"`);
+                }
+                if (label.propertyChanges) {
+                    for (const prop of label.propertyChanges) {
+                        if (prop.property === "new_name")
+                            continue;
+                        if (prop.oldValue !== undefined) {
+                            diffLines.push(`!   ${prop.property}: "${prop.oldValue}" \u2192 "${prop.newValue}"`);
+                        }
+                        else {
+                            diffLines.push(`!   ${prop.property}: "${prop.newValue}"`);
+                        }
+                    }
+                }
+            }
+            else if (label.action === "delete") {
+                diffLines.push(`- label "${label.name}"`);
+            }
+        }
         if (repo.error) {
             diffLines.push(`- Error: ${repo.error}`);
         }

package/dist/output/unified-summary.js

@@ -65,6 +65,19 @@ function formatCombinedSummary(input) {
                 actions.push(`${t.rulesets.delete} ${dry ? "to delete" : "deleted"}`);
             parts.push(`${rulesetsTotal} ${rulesetWord} (${actions.join(", ")})`);
         }
+        const lt = t.labels;
+        const labelsTotal = lt.create + lt.update + lt.delete;
+        if (labelsTotal > 0) {
+            const labelWord = labelsTotal === 1 ? "label" : "labels";
+            const actions = [];
+            if (lt.create > 0)
+                actions.push(`${lt.create} ${dry ? "to create" : "created"}`);
+            if (lt.update > 0)
+                actions.push(`${lt.update} ${dry ? "to update" : "updated"}`);
+            if (lt.delete > 0)
+                actions.push(`${lt.delete} ${dry ? "to delete" : "deleted"}`);
+            parts.push(`${labelsTotal} ${labelWord} (${actions.join(", ")})`);
+        }
     }
     if (parts.length === 0) {
         return "No changes";
@@ -77,7 +90,10 @@ function hasAnyChanges(input) {
         return true;
     if (input.sync?.repos.some((r) => r.files.length > 0 || r.error))
         return true;
-    if (input.settings?.repos.some((r) => r.settings.length > 0 || r.rulesets.length > 0 || r.error))
+    if (input.settings?.repos.some((r) => r.settings.length > 0 ||
+        r.rulesets.length > 0 ||
+        r.labels.length > 0 ||
+        r.error))
         return true;
     return false;
 }
@@ -163,6 +179,28 @@ function renderSettingsLines(settingsRepo, diffLines) {
             diffLines.push(`- ruleset "${ruleset.name}"`);
         }
     }
+    for (const label of settingsRepo.labels) {
+        if (label.action === "create") {
+            diffLines.push(`+ label "${label.name}"`);
+            if (label.config) {
+                diffLines.push(`+   color: "${label.config.color}"`);
+                if (label.config.description !== undefined) {
+                    diffLines.push(`+   description: "${label.config.description}"`);
+                }
+            }
+        }
+        else if (label.action === "update") {
+            if (label.newName) {
+                diffLines.push(`! label "${label.name}" \u2192 "${label.newName}"`);
+            }
+            else {
+                diffLines.push(`! label "${label.name}"`);
+            }
+        }
+        else if (label.action === "delete") {
+            diffLines.push(`- label "${label.name}"`);
+        }
+    }
     if (settingsRepo.error) {
         diffLines.push(`- Error: ${settingsRepo.error}`);
     }
@@ -212,6 +250,7 @@ export function formatUnifiedSummaryMarkdown(input) {
         const hasSettingsChanges = settingsRepo &&
             (settingsRepo.settings.length > 0 ||
                 settingsRepo.rulesets.length > 0 ||
+                settingsRepo.labels.length > 0 ||
                 settingsRepo.error);
         if (!hasLcChange && !hasSyncChanges && !hasSettingsChanges)
             continue;

package/dist/settings/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./rulesets/index.js";
 export * from "./repo-settings/index.js";
+export * from "./labels/index.js";

package/dist/settings/index.js

@@ -2,3 +2,5 @@
 export * from "./rulesets/index.js";
 // Repo settings
 export * from "./repo-settings/index.js";
+// Labels
+export * from "./labels/index.js";

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

@@ -0,0 +1,15 @@
+import type { Label } from "../../config/types.js";
+export interface GitHubLabelPayload {
+    name: string;
+    new_name?: string;
+    color: string;
+    description?: string;
+}
+/**
+ * Strips '#' prefix and lowercases hex color.
+ */
+export declare function normalizeColor(color: string): string;
+/**
+ * Converts a label config entry to a GitHub API payload.
+ */
+export declare function labelConfigToPayload(name: string, label: Label): GitHubLabelPayload;

package/dist/settings/labels/converter.js

@@ -0,0 +1,22 @@
+/**
+ * Strips '#' prefix and lowercases hex color.
+ */
+export function normalizeColor(color) {
+    return color.replace(/^#/, "").toLowerCase();
+}
+/**
+ * Converts a label config entry to a GitHub API payload.
+ */
+export function labelConfigToPayload(name, label) {
+    const payload = {
+        name,
+        color: normalizeColor(label.color),
+    };
+    if (label.new_name !== undefined) {
+        payload.new_name = label.new_name;
+    }
+    if (label.description !== undefined) {
+        payload.description = label.description;
+    }
+    return payload;
+}

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

@@ -0,0 +1,33 @@
+import type { Label } from "../../config/types.js";
+import type { GitHubLabel } from "./types.js";
+export type LabelAction = "create" | "update" | "delete" | "unchanged";
+export interface LabelChange {
+    action: LabelAction;
+    name: string;
+    newName?: string;
+    current?: GitHubLabel;
+    desired?: Label;
+    propertyChanges?: {
+        property: string;
+        oldValue?: string;
+        newValue?: string;
+    }[];
+}
+/**
+ * Compares current labels (from GitHub) with desired labels (from config).
+ *
+ * Matching is case-insensitive by name (GitHub label names are case-insensitive).
+ * Color comparison is case-insensitive bare hex (strip #, lowercase both sides).
+ * Description: undefined in config means "do not compare" (leave current value).
+ * An explicit empty string "" means "set to empty."
+ * GitHub API returns null for labels without descriptions — treat null and
+ * undefined as equivalent when comparing (neither triggers an update).
+ *
+ * @param current - Current labels from GitHub API
+ * @param desired - Desired labels from config (name -> label)
+ * @param managedLabels - Names of labels managed by xfg (from manifest)
+ * @param noDelete - If true, skip delete operations
+ * @returns Array of changes to apply
+ * @throws Error if rename collisions are detected
+ */
+export declare function diffLabels(current: GitHubLabel[], desired: Record<string, Label>, managedLabels: string[], noDelete: boolean): LabelChange[];