@aspruyt/xfg 3.13.1 → 4.0.1

package/dist/output/unified-summary.js

@@ -1,83 +1,87 @@
-// src/output/unified-summary.ts
-import { appendFileSync } from "node:fs";
 import { hasLifecycleChanges } from "./lifecycle-report.js";
-import { formatValuePlain, formatRulesetConfigPlain, } from "./settings-report.js";
+import { writeGitHubStepSummary } from "./github-summary.js";
+import { renderRepoSettingsDiffLines, formatCountEntry, } from "./settings-report.js";
 // =============================================================================
 // Helpers
 // =============================================================================
+function selectLabel(dry, pastLabel, futureLabel) {
+    return dry ? futureLabel : pastLabel;
+}
 function formatCombinedSummary(input) {
     const parts = [];
     const dry = input.dryRun;
-    // Lifecycle totals
     if (input.lifecycle) {
         const t = input.lifecycle.totals;
-        const repoTotal = t.created + t.forked + t.migrated;
-        if (repoTotal > 0) {
-            const repoParts = [];
-            if (t.created > 0)
-                repoParts.push(`${t.created} ${dry ? "to create" : "created"}`);
-            if (t.forked > 0)
-                repoParts.push(`${t.forked} ${dry ? "to fork" : "forked"}`);
-            if (t.migrated > 0)
-                repoParts.push(`${t.migrated} ${dry ? "to migrate" : "migrated"}`);
-            const repoWord = repoTotal === 1 ? "repo" : "repos";
-            parts.push(`${repoTotal} ${repoWord} (${repoParts.join(", ")})`);
-        }
+        const entry = formatCountEntry("repo", "repos", [
+            { label: selectLabel(dry, "created", "to create"), value: t.created },
+            { label: selectLabel(dry, "forked", "to fork"), value: t.forked },
+            { label: selectLabel(dry, "migrated", "to migrate"), value: t.migrated },
+        ]);
+        if (entry)
+            parts.push(entry);
     }
-    // Sync totals
     if (input.sync) {
         const t = input.sync.totals;
-        const fileTotal = t.files.create + t.files.update + t.files.delete;
-        if (fileTotal > 0) {
-            const fileParts = [];
-            if (t.files.create > 0)
-                fileParts.push(`${t.files.create} ${dry ? "to create" : "created"}`);
-            if (t.files.update > 0)
-                fileParts.push(`${t.files.update} ${dry ? "to update" : "updated"}`);
-            if (t.files.delete > 0)
-                fileParts.push(`${t.files.delete} ${dry ? "to delete" : "deleted"}`);
-            const fileWord = fileTotal === 1 ? "file" : "files";
-            parts.push(`${fileTotal} ${fileWord} (${fileParts.join(", ")})`);
-        }
+        const entry = formatCountEntry("file", "files", [
+            {
+                label: selectLabel(dry, "created", "to create"),
+                value: t.files.create,
+            },
+            {
+                label: selectLabel(dry, "updated", "to update"),
+                value: t.files.update,
+            },
+            {
+                label: selectLabel(dry, "deleted", "to delete"),
+                value: t.files.delete,
+            },
+        ]);
+        if (entry)
+            parts.push(entry);
     }
-    // Settings totals
     if (input.settings) {
         const t = input.settings.totals;
-        const settingsTotal = t.settings.add + t.settings.change;
-        if (settingsTotal > 0) {
-            const settingWord = settingsTotal === 1 ? "setting" : "settings";
-            const actions = [];
-            if (t.settings.add > 0)
-                actions.push(`${t.settings.add} ${dry ? "to add" : "added"}`);
-            if (t.settings.change > 0)
-                actions.push(`${t.settings.change} ${dry ? "to change" : "changed"}`);
-            parts.push(`${settingsTotal} ${settingWord} (${actions.join(", ")})`);
-        }
-        const rulesetsTotal = t.rulesets.create + t.rulesets.update + t.rulesets.delete;
-        if (rulesetsTotal > 0) {
-            const rulesetWord = rulesetsTotal === 1 ? "ruleset" : "rulesets";
-            const actions = [];
-            if (t.rulesets.create > 0)
-                actions.push(`${t.rulesets.create} ${dry ? "to create" : "created"}`);
-            if (t.rulesets.update > 0)
-                actions.push(`${t.rulesets.update} ${dry ? "to update" : "updated"}`);
-            if (t.rulesets.delete > 0)
-                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(", ")})`);
-        }
+        const settingsEntry = formatCountEntry("setting", "settings", [
+            { label: selectLabel(dry, "added", "to add"), value: t.settings.add },
+            {
+                label: selectLabel(dry, "changed", "to change"),
+                value: t.settings.change,
+            },
+        ]);
+        if (settingsEntry)
+            parts.push(settingsEntry);
+        const rulesetsEntry = formatCountEntry("ruleset", "rulesets", [
+            {
+                label: selectLabel(dry, "created", "to create"),
+                value: t.rulesets.create,
+            },
+            {
+                label: selectLabel(dry, "updated", "to update"),
+                value: t.rulesets.update,
+            },
+            {
+                label: selectLabel(dry, "deleted", "to delete"),
+                value: t.rulesets.delete,
+            },
+        ]);
+        if (rulesetsEntry)
+            parts.push(rulesetsEntry);
+        const labelsEntry = formatCountEntry("label", "labels", [
+            {
+                label: selectLabel(dry, "created", "to create"),
+                value: t.labels.create,
+            },
+            {
+                label: selectLabel(dry, "updated", "to update"),
+                value: t.labels.update,
+            },
+            {
+                label: selectLabel(dry, "deleted", "to delete"),
+                value: t.labels.delete,
+            },
+        ]);
+        if (labelsEntry)
+            parts.push(labelsEntry);
     }
     if (parts.length === 0) {
         return "No changes";
@@ -140,70 +144,7 @@ function renderSyncLines(syncRepo, diffLines) {
     }
 }
 function renderSettingsLines(settingsRepo, diffLines) {
-    for (const setting of settingsRepo.settings) {
-        if (setting.oldValue === undefined && setting.newValue === undefined) {
-            continue;
-        }
-        if (setting.action === "add") {
-            diffLines.push(`+ ${setting.name}: ${formatValuePlain(setting.newValue)}`);
-        }
-        else {
-            diffLines.push(`! ${setting.name}: ${formatValuePlain(setting.oldValue)} → ${formatValuePlain(setting.newValue)}`);
-        }
-    }
-    for (const ruleset of settingsRepo.rulesets) {
-        if (ruleset.action === "create") {
-            diffLines.push(`+ ruleset "${ruleset.name}"`);
-            if (ruleset.config) {
-                diffLines.push(...formatRulesetConfigPlain(ruleset.config));
-            }
-        }
-        else if (ruleset.action === "update") {
-            diffLines.push(`! ruleset "${ruleset.name}"`);
-            if (ruleset.propertyDiffs && ruleset.propertyDiffs.length > 0) {
-                for (const diff of ruleset.propertyDiffs) {
-                    const path = diff.path.join(".");
-                    if (diff.action === "add") {
-                        diffLines.push(`+   ${path}: ${formatValuePlain(diff.newValue)}`);
-                    }
-                    else if (diff.action === "change") {
-                        diffLines.push(`!   ${path}: ${formatValuePlain(diff.oldValue)} → ${formatValuePlain(diff.newValue)}`);
-                    }
-                    else if (diff.action === "remove") {
-                        diffLines.push(`-   ${path}`);
-                    }
-                }
-            }
-        }
-        else if (ruleset.action === "delete") {
-            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}`);
-    }
+    renderRepoSettingsDiffLines(settingsRepo, diffLines);
 }
 // =============================================================================
 // Markdown Formatter
@@ -276,11 +217,8 @@ export function formatUnifiedSummaryMarkdown(input) {
 // File Writer
 // =============================================================================
 export function writeUnifiedSummary(input) {
-    const summaryPath = process.env.GITHUB_STEP_SUMMARY;
-    if (!summaryPath)
-        return;
     const markdown = formatUnifiedSummaryMarkdown(input);
     if (!markdown)
         return;
-    appendFileSync(summaryPath, "\n" + markdown + "\n");
+    writeGitHubStepSummary(markdown);
 }

package/dist/settings/base-processor.d.ts

@@ -0,0 +1,67 @@
+import type { RepoConfig } from "../config/index.js";
+import type { RepoInfo, GitHubRepoInfo } from "../shared/repo-detector.js";
+export interface BaseProcessorOptions {
+    dryRun?: boolean;
+    /** Pre-resolved auth token. Callers (e.g. sync-command) must resolve via resolveGitHubToken before passing. */
+    token?: string;
+}
+export interface BaseProcessorResult {
+    success: boolean;
+    repoName: string;
+    message: string;
+    skipped?: boolean;
+    dryRun?: boolean;
+}
+/**
+ * Generic settings processor interface for dependency injection.
+ * All three settings processors (rulesets, labels, repo-settings)
+ * share this contract — specific interfaces extend it for type safety.
+ */
+export interface ISettingsProcessor<TOptions extends BaseProcessorOptions = BaseProcessorOptions, TResult extends BaseProcessorResult = BaseProcessorResult> {
+    process(repoConfig: RepoConfig, repoInfo: RepoInfo, options: TOptions): Promise<TResult>;
+}
+/**
+ * Guards for GitHub settings processing — passed to withGitHubGuards.
+ */
+interface SettingsGuards<TOptions extends BaseProcessorOptions, TResult extends BaseProcessorResult> {
+    hasDesiredSettings(repoConfig: RepoConfig): boolean;
+    emptySettingsMessage: string;
+    processSettings(githubRepo: GitHubRepoInfo, repoConfig: RepoConfig, options: TOptions, effectiveToken: string | undefined, repoName: string): Promise<TResult>;
+}
+/**
+ * Common boilerplate for GitHub settings processors: GitHub-only gating,
+ * empty settings check, token resolution, and error wrapping.
+ */
+export declare function withGitHubGuards<TOptions extends BaseProcessorOptions, TResult extends BaseProcessorResult>(repoConfig: RepoConfig, repoInfo: RepoInfo, options: TOptions, guards: SettingsGuards<TOptions, TResult>): Promise<TResult>;
+export interface ChangeCounts {
+    create: number;
+    update: number;
+    delete: number;
+    unchanged: number;
+}
+/**
+ * Count actions from a diff result array.
+ * Works with any change type that has an `action` field.
+ */
+export declare function countActions(changes: ReadonlyArray<{
+    action: string;
+}>): ChangeCounts;
+export declare function formatChangeSummary(counts: ChangeCounts): string;
+/**
+ * Build a standardized dry-run result for settings processors.
+ * Returns an intersection of BaseProcessorResult with the extra fields,
+ * which is assignable to any result subtype whose extra fields are provided.
+ */
+export declare function buildDryRunResult<E extends Record<string, unknown> = Record<string, never>>(repoName: string, changeCounts: ChangeCounts, extra?: E): BaseProcessorResult & {
+    changes: ChangeCounts;
+    dryRun: true;
+} & E;
+/**
+ * Build a standardized apply result for settings processors.
+ * Returns an intersection of BaseProcessorResult with the extra fields,
+ * which is assignable to any result subtype whose extra fields are provided.
+ */
+export declare function buildApplyResult<E extends Record<string, unknown> = Record<string, never>>(repoName: string, changeCounts: ChangeCounts, appliedCount: number, extra?: E): BaseProcessorResult & {
+    changes: ChangeCounts;
+} & E;
+export {};

package/dist/settings/base-processor.js

@@ -0,0 +1,91 @@
+import { isGitHubRepo, getRepoDisplayName } from "../shared/repo-detector.js";
+import { toErrorMessage } from "../shared/type-guards.js";
+/**
+ * Common boilerplate for GitHub settings processors: GitHub-only gating,
+ * empty settings check, token resolution, and error wrapping.
+ */
+export async function withGitHubGuards(repoConfig, repoInfo, options, guards) {
+    const repoName = getRepoDisplayName(repoInfo);
+    if (!isGitHubRepo(repoInfo)) {
+        return {
+            success: true,
+            repoName,
+            message: `Skipped: ${repoName} is not a GitHub repository`,
+            skipped: true,
+        };
+    }
+    if (!guards.hasDesiredSettings(repoConfig)) {
+        return {
+            success: true,
+            repoName,
+            message: guards.emptySettingsMessage,
+            skipped: true,
+        };
+    }
+    try {
+        return await guards.processSettings(repoInfo, repoConfig, options, options.token, repoName);
+    }
+    catch (error) {
+        const message = toErrorMessage(error);
+        return {
+            success: false,
+            repoName,
+            message: `Failed: ${message}`,
+        };
+    }
+}
+/**
+ * Count actions from a diff result array.
+ * Works with any change type that has an `action` field.
+ */
+export function countActions(changes) {
+    return {
+        create: changes.filter((c) => c.action === "create").length,
+        update: changes.filter((c) => c.action === "update").length,
+        delete: changes.filter((c) => c.action === "delete").length,
+        unchanged: changes.filter((c) => c.action === "unchanged").length,
+    };
+}
+export function formatChangeSummary(counts) {
+    const parts = [];
+    if (counts.create > 0)
+        parts.push(`${counts.create} created`);
+    if (counts.update > 0)
+        parts.push(`${counts.update} updated`);
+    if (counts.delete > 0)
+        parts.push(`${counts.delete} deleted`);
+    if (counts.unchanged > 0)
+        parts.push(`${counts.unchanged} unchanged`);
+    return parts.length > 0 ? parts.join(", ") : "no changes";
+}
+/**
+ * Build a standardized dry-run result for settings processors.
+ * Returns an intersection of BaseProcessorResult with the extra fields,
+ * which is assignable to any result subtype whose extra fields are provided.
+ */
+export function buildDryRunResult(repoName, changeCounts, extra) {
+    const summary = formatChangeSummary(changeCounts);
+    const base = {
+        success: true,
+        repoName,
+        message: `[DRY RUN] ${summary}`,
+        dryRun: true,
+        changes: changeCounts,
+    };
+    return Object.assign(base, extra);
+}
+/**
+ * Build a standardized apply result for settings processors.
+ * Returns an intersection of BaseProcessorResult with the extra fields,
+ * which is assignable to any result subtype whose extra fields are provided.
+ */
+export function buildApplyResult(repoName, changeCounts, appliedCount, extra) {
+    const summary = formatChangeSummary(changeCounts);
+    const base = {
+        success: true,
+        repoName,
+        message: appliedCount > 0 ? `Applied: ${summary}` : "No changes needed",
+        changes: changeCounts,
+    };
+    return Object.assign(base, extra);
+}

package/dist/settings/index.d.ts

@@ -1,3 +1,4 @@
-export * from "./rulesets/index.js";
-export * from "./repo-settings/index.js";
-export * from "./labels/index.js";
+export { type ISettingsProcessor } from "./base-processor.js";
+export { type PropertyDiff, formatPropertyTree, type RulesetPlanEntry, RulesetProcessor, type IRulesetProcessor, } from "./rulesets/index.js";
+export { RepoSettingsProcessor, type IRepoSettingsProcessor, type RepoSettingsPlanEntry, } from "./repo-settings/index.js";
+export { type LabelsPlanEntry, LabelsProcessor, type ILabelsProcessor, } from "./labels/index.js";

package/dist/settings/index.js

@@ -1,6 +1,6 @@
 // Rulesets
-export * from "./rulesets/index.js";
+export { formatPropertyTree, RulesetProcessor, } from "./rulesets/index.js";
 // Repo settings
-export * from "./repo-settings/index.js";
+export { RepoSettingsProcessor, } from "./repo-settings/index.js";
 // Labels
-export * from "./labels/index.js";
+export { LabelsProcessor, } from "./labels/index.js";

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

@@ -1,5 +1,5 @@
 import type { Label } from "../../config/types.js";
-export interface GitHubLabelPayload {
+interface GitHubLabelPayload {
     name: string;
     new_name?: string;
     color: string;
@@ -13,3 +13,4 @@ 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;
+export {};

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

@@ -25,9 +25,9 @@ export interface LabelChange {
  *
  * @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 deleteOrphaned - If true, delete current labels not in desired config
  * @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[];
+export declare function diffLabels(current: GitHubLabel[], desired: Record<string, Label>, deleteOrphaned: boolean, noDelete: boolean): LabelChange[];

package/dist/settings/labels/diff.js

@@ -11,19 +11,18 @@ import { normalizeColor } from "./converter.js";
  *
  * @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 deleteOrphaned - If true, delete current labels not in desired config
  * @param noDelete - If true, skip delete operations
  * @returns Array of changes to apply
  * @throws Error if rename collisions are detected
  */
-export function diffLabels(current, desired, managedLabels, noDelete) {
+export function diffLabels(current, desired, deleteOrphaned, noDelete) {
     const changes = [];
     // Build case-insensitive lookup of current labels
     const currentByName = new Map();
     for (const label of current) {
         currentByName.set(label.name.toLowerCase(), label);
     }
-    const managedSet = new Set(managedLabels.map((n) => n.toLowerCase()));
     // Collect rename targets for collision detection
     const renameTargets = new Map(); // lowercase target -> source name
     for (const [name, label] of Object.entries(desired)) {
@@ -38,10 +37,10 @@ export function diffLabels(current, desired, managedLabels, noDelete) {
     // Determine which labels will be deleted (for collision checking)
     const desiredLower = new Set(Object.keys(desired).map((n) => n.toLowerCase()));
     const deletedNames = new Set();
-    if (!noDelete) {
-        for (const name of managedSet) {
-            if (!desiredLower.has(name) && currentByName.has(name)) {
-                deletedNames.add(name);
+    if (deleteOrphaned && !noDelete) {
+        for (const nameLower of currentByName.keys()) {
+            if (!desiredLower.has(nameLower)) {
+                deletedNames.add(nameLower);
             }
         }
     }
@@ -130,18 +129,15 @@ export function diffLabels(current, desired, managedLabels, noDelete) {
             }
         }
     }
-    // Check for orphaned labels (in manifest but not in desired config)
-    if (!noDelete) {
-        for (const name of managedSet) {
-            if (!desiredLower.has(name)) {
-                const currentLabel = currentByName.get(name);
-                if (currentLabel) {
-                    changes.push({
-                        action: "delete",
-                        name: currentLabel.name,
-                        current: currentLabel,
-                    });
-                }
+    // Desired-state orphan detection: delete ALL current not in desired
+    if (deleteOrphaned && !noDelete) {
+        for (const [nameLower, currentLabel] of currentByName) {
+            if (!desiredLower.has(nameLower)) {
+                changes.push({
+                    action: "delete",
+                    name: currentLabel.name,
+                    current: currentLabel,
+                });
             }
         }
     }

package/dist/settings/labels/github-labels-strategy.d.ts

@@ -1,7 +1,8 @@
 import { ICommandExecutor } from "../../shared/command-executor.js";
 import { RepoInfo } from "../../shared/repo-detector.js";
-import type { ILabelsStrategy, GitHubLabel, LabelsStrategyOptions } from "./types.js";
-export interface GitHubLabelsStrategyOptions {
+import { type GhApiOptions } from "../../shared/gh-api-utils.js";
+import type { ILabelsStrategy, GitHubLabel } from "./types.js";
+interface GitHubLabelsStrategyOptions {
     retries?: number;
 }
 /**
@@ -12,14 +13,13 @@ export interface GitHubLabelsStrategyOptions {
  * escapeShellArg for input sanitization, matching the rulesets strategy pattern.
  */
 export declare class GitHubLabelsStrategy implements ILabelsStrategy {
-    private executor;
-    private retries;
+    private api;
     constructor(executor?: ICommandExecutor, options?: GitHubLabelsStrategyOptions);
     /**
      * Lists all labels for a repository.
      * Uses --paginate to retrieve all labels.
      */
-    list(repoInfo: RepoInfo, options?: LabelsStrategyOptions): Promise<GitHubLabel[]>;
+    list(repoInfo: RepoInfo, options?: GhApiOptions): Promise<GitHubLabel[]>;
     /**
      * Creates a new label.
      */
@@ -27,7 +27,7 @@ export declare class GitHubLabelsStrategy implements ILabelsStrategy {
         name: string;
         color: string;
         description?: string;
-    }, options?: LabelsStrategyOptions): Promise<void>;
+    }, options?: GhApiOptions): Promise<void>;
     /**
      * Updates an existing label.
      * Uses encodeURIComponent for label name in URL path.
@@ -36,20 +36,11 @@ export declare class GitHubLabelsStrategy implements ILabelsStrategy {
         new_name?: string;
         color?: string;
         description?: string;
-    }, options?: LabelsStrategyOptions): Promise<void>;
+    }, options?: GhApiOptions): Promise<void>;
     /**
      * Deletes a label.
      * Uses encodeURIComponent for label name in URL path.
      */
-    delete(repoInfo: RepoInfo, name: string, options?: LabelsStrategyOptions): Promise<void>;
-    /**
-     * Validates that the repo is a GitHub repository.
-     */
-    private validateGitHub;
-    /**
-     * Executes a GitHub API call using the gh CLI.
-     * Uses the project's ICommandExecutor + escapeShellArg pattern
-     * (matching github-ruleset-strategy.ts).
-     */
-    private ghApi;
+    delete(repoInfo: RepoInfo, name: string, options?: GhApiOptions): Promise<void>;
 }
+export {};