@aspruyt/xfg 3.3.2 → 3.4.0

package/dist/index.js

@@ -3,6 +3,7 @@ import { program, Command } from "commander";
 import { resolve, join, dirname } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import chalk from "chalk";
 import { loadRawConfig, normalizeConfig, } from "./config.js";
 import { validateForSync, validateForSettings } from "./config-validator.js";
 // Get version from package.json
@@ -215,6 +216,11 @@ export async function runSettings(options, processorFactory = defaultRulesetProc
     let successCount = 0;
     let failCount = 0;
     let skipCount = 0;
+    // Tracking for multi-repo summary in dry-run mode
+    let totalCreates = 0;
+    let totalUpdates = 0;
+    let totalDeletes = 0;
+    let reposWithChanges = 0;
     for (let i = 0; i < reposWithRulesets.length; i++) {
         const repoConfig = reposWithRulesets[i];
         let repoInfo;
@@ -248,6 +254,27 @@ export async function runSettings(options, processorFactory = defaultRulesetProc
                 managedRulesets,
                 noDelete: options.noDelete,
             });
+            // Display plan output for dry-run mode
+            if (options.dryRun && result.planOutput) {
+                if (result.planOutput.lines.length > 0) {
+                    logger.rulesetPlan(repoName, result.planOutput.lines, {
+                        creates: result.planOutput.creates,
+                        updates: result.planOutput.updates,
+                        deletes: result.planOutput.deletes,
+                        unchanged: result.planOutput.unchanged,
+                    });
+                }
+                // Accumulate totals for multi-repo summary
+                totalCreates += result.planOutput.creates;
+                totalUpdates += result.planOutput.updates;
+                totalDeletes += result.planOutput.deletes;
+                if (result.planOutput.creates +
+                    result.planOutput.updates +
+                    result.planOutput.deletes >
+                    0) {
+                    reposWithChanges++;
+                }
+            }
             if (result.skipped) {
                 logger.skip(i + 1, repoName, result.message);
                 skipCount++;
@@ -292,6 +319,19 @@ export async function runSettings(options, processorFactory = defaultRulesetProc
             failCount++;
         }
     }
+    // Multi-repo summary for dry-run mode
+    if (options.dryRun && reposWithChanges > 0) {
+        console.log("");
+        console.log(chalk.gray("─".repeat(40)));
+        const totalParts = [];
+        if (totalCreates > 0)
+            totalParts.push(chalk.green(`${totalCreates} to create`));
+        if (totalUpdates > 0)
+            totalParts.push(chalk.yellow(`${totalUpdates} to update`));
+        if (totalDeletes > 0)
+            totalParts.push(chalk.red(`${totalDeletes} to delete`));
+        console.log(chalk.bold(`Total: ${totalParts.join(", ")} across ${reposWithChanges} ${reposWithChanges === 1 ? "repository" : "repositories"}`));
+    }
     // Summary
     console.log("\n" + "=".repeat(50));
     console.log(`Completed: ${successCount} succeeded, ${skipCount} skipped, ${failCount} failed`);

package/dist/logger.d.ts

@@ -1,8 +1,15 @@
 import { FileStatus } from "./diff-utils.js";
+export interface RulesetPlanCounts {
+    creates: number;
+    updates: number;
+    deletes: number;
+    unchanged: number;
+}
 export interface ILogger {
     info(message: string): void;
     fileDiff(fileName: string, status: FileStatus, diffLines: string[]): void;
     diffSummary(newCount: number, modifiedCount: number, unchangedCount: number, deletedCount?: number): void;
+    rulesetPlan(repoName: string, planLines: string[], counts: RulesetPlanCounts): void;
     setTotal(total: number): void;
     progress(current: number, repoName: string, message: string): void;
     success(current: number, repoName: string, message: string): void;
@@ -34,6 +41,10 @@ export declare class Logger implements ILogger {
      * Display summary statistics for dry-run diff.
      */
     diffSummary(newCount: number, modifiedCount: number, unchangedCount: number, deletedCount?: number): void;
+    /**
+     * Display ruleset plan output for dry-run mode.
+     */
+    rulesetPlan(repoName: string, planLines: string[], counts: RulesetPlanCounts): void;
     summary(): void;
     hasFailures(): boolean;
 }

package/dist/logger.js

@@ -62,6 +62,29 @@ export class Logger {
             console.log(chalk.gray(`    Summary: ${parts.join(", ")}`));
         }
     }
+    /**
+     * Display ruleset plan output for dry-run mode.
+     */
+    rulesetPlan(repoName, planLines, counts) {
+        console.log("");
+        console.log(chalk.bold(`Repository: ${repoName}`));
+        for (const line of planLines) {
+            console.log(line);
+        }
+        // Summary line
+        const parts = [];
+        if (counts.creates > 0)
+            parts.push(chalk.green(`${counts.creates} to create`));
+        if (counts.updates > 0)
+            parts.push(chalk.yellow(`${counts.updates} to update`));
+        if (counts.deletes > 0)
+            parts.push(chalk.red(`${counts.deletes} to delete`));
+        const unchangedPart = counts.unchanged > 0
+            ? chalk.gray(` (${counts.unchanged} unchanged)`)
+            : "";
+        const summaryLine = parts.length > 0 ? parts.join(", ") + unchangedPart : "No changes";
+        console.log(chalk.gray(`Plan: ${summaryLine}`));
+    }
     summary() {
         console.log("");
         console.log(chalk.bold("Summary:"));

package/dist/ruleset-plan-formatter.d.ts

@@ -0,0 +1,27 @@
+import type { RulesetChange } from "./ruleset-diff.js";
+export type DiffAction = "add" | "change" | "remove";
+export interface PropertyDiff {
+    path: string[];
+    action: DiffAction;
+    oldValue?: unknown;
+    newValue?: unknown;
+}
+export interface RulesetPlanResult {
+    lines: string[];
+    creates: number;
+    updates: number;
+    deletes: number;
+    unchanged: number;
+}
+/**
+ * Recursively compute property-level diffs between two objects.
+ */
+export declare function computePropertyDiffs(current: Record<string, unknown>, desired: Record<string, unknown>, parentPath?: string[]): PropertyDiff[];
+/**
+ * Format property diffs as an indented tree structure.
+ */
+export declare function formatPropertyTree(diffs: PropertyDiff[]): string[];
+/**
+ * Format ruleset changes as a Terraform-style plan.
+ */
+export declare function formatRulesetPlan(changes: RulesetChange[]): RulesetPlanResult;

package/dist/ruleset-plan-formatter.js

@@ -0,0 +1,314 @@
+// src/ruleset-plan-formatter.ts
+import chalk from "chalk";
+// =============================================================================
+// Property Diff Algorithm
+// =============================================================================
+/**
+ * Recursively compute property-level diffs between two objects.
+ */
+export function computePropertyDiffs(current, desired, parentPath = []) {
+    const diffs = [];
+    const allKeys = new Set([...Object.keys(current), ...Object.keys(desired)]);
+    for (const key of allKeys) {
+        const path = [...parentPath, key];
+        const currentVal = current[key];
+        const desiredVal = desired[key];
+        if (!(key in current)) {
+            // Added property
+            diffs.push({ path, action: "add", newValue: desiredVal });
+        }
+        else if (!(key in desired)) {
+            // Removed property
+            diffs.push({ path, action: "remove", oldValue: currentVal });
+        }
+        else if (!deepEqual(currentVal, desiredVal)) {
+            // Changed property
+            if (isObject(currentVal) && isObject(desiredVal)) {
+                // Recurse into nested objects
+                diffs.push(...computePropertyDiffs(currentVal, desiredVal, path));
+            }
+            else {
+                diffs.push({
+                    path,
+                    action: "change",
+                    oldValue: currentVal,
+                    newValue: desiredVal,
+                });
+            }
+        }
+        // Unchanged properties are not included
+    }
+    return diffs;
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+function isObject(val) {
+    return val !== null && typeof val === "object" && !Array.isArray(val);
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null || a === undefined || b === undefined)
+        return a === b;
+    if (typeof a !== typeof b)
+        return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((val, i) => deepEqual(val, b[i]));
+    }
+    if (isObject(a) && isObject(b)) {
+        const keysA = Object.keys(a);
+        const keysB = Object.keys(b);
+        if (keysA.length !== keysB.length)
+            return false;
+        return keysA.every((key) => deepEqual(a[key], b[key]));
+    }
+    return false;
+}
+/**
+ * Build a tree structure from flat property diffs.
+ */
+function buildTree(diffs) {
+    const root = { name: "", children: new Map() };
+    for (const diff of diffs) {
+        let current = root;
+        for (let i = 0; i < diff.path.length; i++) {
+            const segment = diff.path[i];
+            const isLast = i === diff.path.length - 1;
+            if (!current.children.has(segment)) {
+                current.children.set(segment, {
+                    name: segment,
+                    children: new Map(),
+                });
+            }
+            const child = current.children.get(segment);
+            if (isLast) {
+                child.action = diff.action;
+                child.oldValue = diff.oldValue;
+                child.newValue = diff.newValue;
+            }
+            else {
+                // Intermediate node - mark as change if any child changes
+                if (!child.action) {
+                    child.action = "change";
+                }
+            }
+            current = child;
+        }
+    }
+    return root;
+}
+/**
+ * Format a value for display.
+ */
+function formatValue(val) {
+    if (val === null)
+        return "null";
+    if (val === undefined)
+        return "undefined";
+    if (typeof val === "string")
+        return `"${val}"`;
+    if (Array.isArray(val)) {
+        if (val.length <= 3) {
+            return `[${val.map(formatValue).join(", ")}]`;
+        }
+        return `[${val.slice(0, 3).map(formatValue).join(", ")}, ... (${val.length - 3} more)]`;
+    }
+    if (typeof val === "object") {
+        return "{...}";
+    }
+    return String(val);
+}
+/**
+ * Get the symbol and color for an action.
+ */
+function getActionStyle(action) {
+    switch (action) {
+        case "add":
+            return { symbol: "+", color: chalk.green };
+        case "remove":
+            return { symbol: "-", color: chalk.red };
+        case "change":
+            return { symbol: "~", color: chalk.yellow };
+    }
+}
+/**
+ * Recursively render tree nodes to formatted lines.
+ */
+function renderTree(node, indent = 0) {
+    const lines = [];
+    const indentStr = "    ".repeat(indent);
+    for (const [, child] of node.children) {
+        const style = child.action
+            ? getActionStyle(child.action)
+            : { symbol: " ", color: chalk.gray };
+        const hasChildren = child.children.size > 0;
+        if (hasChildren) {
+            // Intermediate node
+            lines.push(style.color(`${indentStr}${style.symbol} ${child.name}:`));
+            lines.push(...renderTree(child, indent + 1));
+        }
+        else {
+            // Leaf node with value
+            let valuePart = "";
+            if (child.action === "change") {
+                valuePart = `: ${formatValue(child.oldValue)} → ${formatValue(child.newValue)}`;
+            }
+            else if (child.action === "add") {
+                valuePart = `: ${formatValue(child.newValue)}`;
+            }
+            else if (child.action === "remove") {
+                valuePart = ` (was: ${formatValue(child.oldValue)})`;
+            }
+            lines.push(style.color(`${indentStr}${style.symbol} ${child.name}${valuePart}`));
+        }
+    }
+    return lines;
+}
+/**
+ * Format property diffs as an indented tree structure.
+ */
+export function formatPropertyTree(diffs) {
+    if (diffs.length === 0) {
+        return [];
+    }
+    const tree = buildTree(diffs);
+    return renderTree(tree);
+}
+// =============================================================================
+// Ruleset Plan Formatter
+// =============================================================================
+/**
+ * Normalize a GitHubRuleset or Ruleset for comparison.
+ * Converts to snake_case and removes metadata fields.
+ */
+function normalizeForDiff(obj) {
+    const result = {};
+    const ignoreFields = new Set(["id", "name", "source_type", "source"]);
+    for (const [key, value] of Object.entries(obj)) {
+        if (ignoreFields.has(key) || value === undefined)
+            continue;
+        // Convert camelCase to snake_case for consistency
+        const snakeKey = key.replace(/([A-Z])/g, "_$1").toLowerCase();
+        result[snakeKey] = normalizeNestedValue(value);
+    }
+    return result;
+}
+function normalizeNestedValue(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (Array.isArray(value))
+        return value.map(normalizeNestedValue);
+    if (typeof value === "object") {
+        const obj = value;
+        const result = {};
+        for (const [key, val] of Object.entries(obj)) {
+            const snakeKey = key.replace(/([A-Z])/g, "_$1").toLowerCase();
+            result[snakeKey] = normalizeNestedValue(val);
+        }
+        return result;
+    }
+    return value;
+}
+/**
+ * Format a full ruleset config as tree lines (for create action).
+ */
+function formatFullConfig(ruleset, indent = 2) {
+    const lines = [];
+    const style = getActionStyle("add");
+    function renderValue(key, value, currentIndent) {
+        const pad = "    ".repeat(currentIndent);
+        if (value === null || value === undefined)
+            return;
+        if (Array.isArray(value)) {
+            if (value.length === 0) {
+                lines.push(style.color(`${pad}+ ${key}: []`));
+            }
+            else if (value.every((v) => typeof v !== "object")) {
+                lines.push(style.color(`${pad}+ ${key}: ${formatValue(value)}`));
+            }
+            else {
+                lines.push(style.color(`${pad}+ ${key}:`));
+                for (const item of value) {
+                    if (typeof item === "object" && item !== null) {
+                        lines.push(style.color(`${pad}    - ${JSON.stringify(item)}`));
+                    }
+                    else {
+                        lines.push(style.color(`${pad}    - ${formatValue(item)}`));
+                    }
+                }
+            }
+        }
+        else if (typeof value === "object") {
+            lines.push(style.color(`${pad}+ ${key}:`));
+            for (const [k, v] of Object.entries(value)) {
+                renderValue(k, v, currentIndent + 1);
+            }
+        }
+        else {
+            lines.push(style.color(`${pad}+ ${key}: ${formatValue(value)}`));
+        }
+    }
+    for (const [key, value] of Object.entries(ruleset)) {
+        renderValue(key, value, indent);
+    }
+    return lines;
+}
+/**
+ * Format ruleset changes as a Terraform-style plan.
+ */
+export function formatRulesetPlan(changes) {
+    const lines = [];
+    let creates = 0;
+    let updates = 0;
+    let deletes = 0;
+    let unchanged = 0;
+    // Group by action type
+    const createChanges = changes.filter((c) => c.action === "create");
+    const updateChanges = changes.filter((c) => c.action === "update");
+    const deleteChanges = changes.filter((c) => c.action === "delete");
+    const unchangedChanges = changes.filter((c) => c.action === "unchanged");
+    creates = createChanges.length;
+    updates = updateChanges.length;
+    deletes = deleteChanges.length;
+    unchanged = unchangedChanges.length;
+    // Format creates
+    if (createChanges.length > 0) {
+        lines.push(chalk.bold("  Create:"));
+        for (const change of createChanges) {
+            lines.push(chalk.green(`    + ruleset "${change.name}"`));
+            if (change.desired) {
+                lines.push(...formatFullConfig(change.desired, 2));
+            }
+            lines.push(""); // Blank line between rulesets
+        }
+    }
+    // Format updates
+    if (updateChanges.length > 0) {
+        lines.push(chalk.bold("  Update:"));
+        for (const change of updateChanges) {
+            lines.push(chalk.yellow(`    ~ ruleset "${change.name}"`));
+            if (change.current && change.desired) {
+                const currentNorm = normalizeForDiff(change.current);
+                const desiredNorm = normalizeForDiff(change.desired);
+                const diffs = computePropertyDiffs(currentNorm, desiredNorm);
+                const treeLines = formatPropertyTree(diffs);
+                for (const line of treeLines) {
+                    lines.push(`        ${line}`);
+                }
+            }
+            lines.push(""); // Blank line between rulesets
+        }
+    }
+    // Format deletes
+    if (deleteChanges.length > 0) {
+        lines.push(chalk.bold("  Delete:"));
+        for (const change of deleteChanges) {
+            lines.push(chalk.red(`    - ruleset "${change.name}"`));
+        }
+        lines.push(""); // Blank line after deletes
+    }
+    return { lines, creates, updates, deletes, unchanged };
+}

package/dist/ruleset-processor.d.ts

@@ -1,6 +1,7 @@
 import type { RepoConfig } from "./config.js";
 import type { RepoInfo } from "./repo-detector.js";
 import { GitHubRulesetStrategy } from "./strategies/github-ruleset-strategy.js";
+import { RulesetPlanResult } from "./ruleset-plan-formatter.js";
 export interface IRulesetProcessor {
     process(repoConfig: RepoConfig, repoInfo: RepoInfo, options: RulesetProcessorOptions): Promise<RulesetProcessorResult>;
 }
@@ -26,6 +27,7 @@ export interface RulesetProcessorResult {
     manifestUpdate?: {
         rulesets: string[];
     };
+    planOutput?: RulesetPlanResult;
 }
 /**
  * Processes ruleset configuration for a repository.

package/dist/ruleset-processor.js

@@ -1,6 +1,7 @@
 import { isGitHubRepo, getRepoDisplayName } from "./repo-detector.js";
 import { GitHubRulesetStrategy } from "./strategies/github-ruleset-strategy.js";
 import { diffRulesets } from "./ruleset-diff.js";
+import { formatRulesetPlan, } from "./ruleset-plan-formatter.js";
 // =============================================================================
 // Processor Implementation
 // =============================================================================
@@ -60,12 +61,14 @@ export class RulesetProcessor {
             // Dry run mode - report planned changes without applying
             if (dryRun) {
                 const summary = this.formatChangeSummary(changeCounts);
+                const planOutput = formatRulesetPlan(changes);
                 return {
                     success: true,
                     repoName,
                     message: `[DRY RUN] ${summary}`,
                     dryRun: true,
                     changes: changeCounts,
+                    planOutput,
                     manifestUpdate: this.computeManifestUpdate(desiredRulesets, deleteOrphaned),
                 };
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspruyt/xfg",
-  "version": "3.3.2",
+  "version": "3.4.0",
   "description": "CLI tool for repository-as-code",
   "type": "module",
   "main": "dist/index.js",