archbyte 0.1.0

package/dist/cli/stats.js

@@ -0,0 +1,158 @@
+import * as fs from "fs";
+import * as path from "path";
+import chalk from "chalk";
+import { resolveArchitecturePath, loadArchitectureFile, loadRulesConfig, getThreshold } from "./shared.js";
+/**
+ * Print an architecture health dashboard to the terminal.
+ */
+export async function handleStats(options) {
+    const diagramPath = resolveArchitecturePath(options);
+    const arch = loadArchitectureFile(diagramPath);
+    const config = loadRulesConfig(options.config);
+    const realNodes = arch.nodes;
+    const components = realNodes.filter((n) => n.type === "component" || n.type === "service");
+    const databases = realNodes.filter((n) => n.type === "database");
+    const externals = realNodes.filter((n) => n.type === "external");
+    const totalConnections = arch.edges.length;
+    // Auto-detect project name from cwd
+    const projectName = process.cwd().split("/").pop() || "project";
+    console.log();
+    console.log(chalk.bold.cyan(`⚡ ArchByte Stats — ${projectName}`));
+    console.log();
+    // ── Scan Info (from analysis.json metadata) ──
+    const analysisPath = path.join(process.cwd(), ".archbyte", "analysis.json");
+    let scanMeta = {};
+    try {
+        if (fs.existsSync(analysisPath)) {
+            const raw = JSON.parse(fs.readFileSync(analysisPath, "utf-8"));
+            scanMeta = (raw.metadata ?? {});
+        }
+    }
+    catch { /* ignore */ }
+    if (scanMeta.analyzedAt || scanMeta.durationMs || scanMeta.filesScanned) {
+        const parts = [];
+        if (scanMeta.durationMs != null) {
+            parts.push(`${(scanMeta.durationMs / 1000).toFixed(1)}s`);
+        }
+        if (scanMeta.filesScanned != null) {
+            parts.push(`${scanMeta.filesScanned} files scanned`);
+        }
+        if (scanMeta.tokenUsage) {
+            const total = scanMeta.tokenUsage.input + scanMeta.tokenUsage.output;
+            parts.push(`${total.toLocaleString()} tokens`);
+        }
+        if (scanMeta.mode) {
+            parts.push(scanMeta.mode === "pipeline" ? "static + model" : "static only");
+        }
+        if (scanMeta.analyzedAt) {
+            const d = new Date(scanMeta.analyzedAt);
+            parts.push(d.toLocaleDateString("en-GB", { day: "numeric", month: "short", year: "numeric" }));
+        }
+        console.log(chalk.gray(`  Last scan: ${parts.join("  |  ")}`));
+        console.log();
+    }
+    // ── Summary ──
+    console.log(`  Components: ${chalk.bold(String(components.length))}          Connections: ${chalk.bold(String(totalConnections))}`);
+    console.log(`  Databases:  ${chalk.bold(String(databases.length))}          Ext Services: ${chalk.bold(String(externals.length))}`);
+    console.log();
+    // ── By Layer ──
+    const layers = ["presentation", "application", "data", "external", "deployment"];
+    const layerCounts = new Map();
+    for (const node of realNodes) {
+        layerCounts.set(node.layer, (layerCounts.get(node.layer) || 0) + 1);
+    }
+    const maxCount = Math.max(...layerCounts.values(), 1);
+    console.log(chalk.bold("  By Layer:"));
+    for (const layer of layers) {
+        const count = layerCounts.get(layer) || 0;
+        if (count === 0)
+            continue;
+        const barLen = Math.round((count / maxCount) * 10);
+        const bar = "█".repeat(barLen) + "░".repeat(10 - barLen);
+        const pct = realNodes.length > 0
+            ? `(${Math.round((count / realNodes.length) * 100)}%)`
+            : "";
+        const label = (layer + "          ").slice(0, 14);
+        console.log(chalk.gray(`    ${label}${bar}  ${count} ${pct}`));
+    }
+    console.log();
+    // ── Health Indicators ──
+    console.log(chalk.bold("  Health Indicators:"));
+    // Connection density: edges / (n * (n-1) / 2) for undirected sense
+    const n = realNodes.length;
+    const possibleConnections = n > 1 ? (n * (n - 1)) / 2 : 1;
+    const density = totalConnections / possibleConnections;
+    const densityStr = density.toFixed(2);
+    if (density < 0.5) {
+        console.log(chalk.green(`    ✓ Connection density: ${densityStr} (healthy < 0.5)`));
+    }
+    else {
+        console.log(chalk.yellow(`    ⚠ Connection density: ${densityStr} (threshold: 0.5)`));
+    }
+    // Hub detection (threshold: 5 connections)
+    const connectionCounts = new Map();
+    for (const edge of arch.edges) {
+        connectionCounts.set(edge.source, (connectionCounts.get(edge.source) || 0) + 1);
+        connectionCounts.set(edge.target, (connectionCounts.get(edge.target) || 0) + 1);
+    }
+    const hubThreshold = getThreshold(config, "max-connections", 6);
+    let hubFound = false;
+    for (const node of realNodes) {
+        const count = connectionCounts.get(node.id) || 0;
+        if (count >= hubThreshold) {
+            console.log(chalk.yellow(`    ⚠ Hub detected: "${node.label}" has ${count} connections (threshold: ${hubThreshold})`));
+            hubFound = true;
+        }
+    }
+    if (!hubFound) {
+        console.log(chalk.green(`    ✓ No hubs detected (threshold: ${hubThreshold})`));
+    }
+    // Orphan detection
+    const connectedIds = new Set();
+    for (const edge of arch.edges) {
+        connectedIds.add(edge.source);
+        connectedIds.add(edge.target);
+    }
+    let orphanFound = false;
+    for (const node of realNodes) {
+        if (!connectedIds.has(node.id)) {
+            console.log(chalk.yellow(`    ⚠ Orphan found: "${node.label}" has 0 connections`));
+            orphanFound = true;
+        }
+    }
+    if (!orphanFound) {
+        console.log(chalk.green("    ✓ No orphans detected"));
+    }
+    // Layer violations (presentation → data, skipping application)
+    const layerOrder = {
+        presentation: 0,
+        application: 1,
+        data: 2,
+        external: 3,
+        deployment: 4,
+    };
+    const nodeMap = new Map();
+    for (const node of realNodes) {
+        nodeMap.set(node.id, node);
+    }
+    let violationFound = false;
+    for (const edge of arch.edges) {
+        const src = nodeMap.get(edge.source);
+        const tgt = nodeMap.get(edge.target);
+        if (!src || !tgt)
+            continue;
+        const srcOrder = layerOrder[src.layer];
+        const tgtOrder = layerOrder[tgt.layer];
+        if (srcOrder === undefined || tgtOrder === undefined)
+            continue;
+        // Only check the core layers (presentation/application/data)
+        if (srcOrder <= 1 && tgtOrder === 2 && tgtOrder - srcOrder > 1) {
+            console.log(chalk.yellow(`    ⚠ Layer violation: "${src.label}" (${src.layer}) → "${tgt.label}" (${tgt.layer})`));
+            violationFound = true;
+        }
+    }
+    if (!violationFound) {
+        console.log(chalk.green("    ✓ No layer violations detected"));
+    }
+    console.log();
+}

package/dist/cli/ui.d.ts

@@ -0,0 +1,18 @@
+interface Spinner {
+    stop(result: string, color?: "green" | "red" | "yellow" | "cyan"): void;
+}
+/**
+ * Animated braille spinner. Falls back to static console.log when not a TTY.
+ */
+export declare function spinner(label: string): Spinner;
+/**
+ * Arrow-key selection menu. Returns the selected index.
+ * Non-TTY fallback: returns 0 (first option).
+ */
+export declare function select(prompt: string, options: string[]): Promise<number>;
+/**
+ * Y/n confirmation prompt. Returns true for y/Enter, false for n.
+ * Non-TTY fallback: returns true.
+ */
+export declare function confirm(prompt: string): Promise<boolean>;
+export {};

package/dist/cli/ui.js

@@ -0,0 +1,144 @@
+import chalk from "chalk";
+const BRAILLE_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/**
+ * Animated braille spinner. Falls back to static console.log when not a TTY.
+ */
+export function spinner(label) {
+    if (!process.stdout.isTTY) {
+        console.log(`  ${label}...`);
+        return {
+            stop(result) {
+                console.log(`  ${label}... ${result}`);
+            },
+        };
+    }
+    let frame = 0;
+    const interval = setInterval(() => {
+        const char = BRAILLE_FRAMES[frame % BRAILLE_FRAMES.length];
+        process.stdout.write(`\r\x1b[K  ${chalk.cyan(char)} ${label}`);
+        frame++;
+    }, 80);
+    return {
+        stop(result, color) {
+            clearInterval(interval);
+            const icon = color === "red" ? "✗" : "✓";
+            const colorFn = color ? chalk[color] : chalk.green;
+            process.stdout.write(`\r\x1b[K  ${colorFn(icon)} ${label}... ${colorFn(result)}\n`);
+        },
+    };
+}
+/**
+ * Arrow-key selection menu. Returns the selected index.
+ * Non-TTY fallback: returns 0 (first option).
+ */
+export function select(prompt, options) {
+    if (!process.stdout.isTTY || options.length === 0) {
+        console.log(`  ${prompt}`);
+        if (options.length > 0)
+            console.log(`  → ${options[0]}`);
+        return Promise.resolve(0);
+    }
+    return new Promise((resolve) => {
+        const stdin = process.stdin;
+        const wasRaw = stdin.isRaw;
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding("utf8");
+        let selected = 0;
+        // Hide cursor
+        process.stdout.write("\x1b[?25l");
+        function render() {
+            // Move up to clear previous render (except first time)
+            const lines = options.length + 1; // prompt + options
+            process.stdout.write(`\x1b[${lines}A`);
+            process.stdout.write(`\x1b[K  ${chalk.bold(prompt)}\n`);
+            for (let i = 0; i < options.length; i++) {
+                process.stdout.write("\x1b[K");
+                if (i === selected) {
+                    process.stdout.write(`    ${chalk.cyan("❯")} ${chalk.cyan(options[i])}\n`);
+                }
+                else {
+                    process.stdout.write(`      ${chalk.gray(options[i])}\n`);
+                }
+            }
+        }
+        // Initial render — write blank lines first so cursor math works
+        process.stdout.write(`\x1b[K  ${chalk.bold(prompt)}\n`);
+        for (let i = 0; i < options.length; i++) {
+            process.stdout.write("\x1b[K");
+            if (i === selected) {
+                process.stdout.write(`    ${chalk.cyan("❯")} ${chalk.cyan(options[i])}\n`);
+            }
+            else {
+                process.stdout.write(`      ${chalk.gray(options[i])}\n`);
+            }
+        }
+        const onData = (data) => {
+            if (data === "\x1b[A") {
+                // Up arrow
+                selected = (selected - 1 + options.length) % options.length;
+                render();
+            }
+            else if (data === "\x1b[B") {
+                // Down arrow
+                selected = (selected + 1) % options.length;
+                render();
+            }
+            else if (data === "\r" || data === "\n") {
+                // Enter — confirm
+                cleanup();
+                resolve(selected);
+            }
+            else if (data === "\x03") {
+                // Ctrl+C
+                cleanup();
+                process.exit(0);
+            }
+        };
+        function cleanup() {
+            stdin.removeListener("data", onData);
+            stdin.setRawMode(wasRaw ?? false);
+            stdin.pause();
+            // Show cursor
+            process.stdout.write("\x1b[?25h");
+        }
+        stdin.on("data", onData);
+    });
+}
+/**
+ * Y/n confirmation prompt. Returns true for y/Enter, false for n.
+ * Non-TTY fallback: returns true.
+ */
+export function confirm(prompt) {
+    if (!process.stdout.isTTY) {
+        console.log(`  ${prompt} (Y/n): y`);
+        return Promise.resolve(true);
+    }
+    return new Promise((resolve) => {
+        process.stdout.write(`  ${prompt} ${chalk.gray("(Y/n)")}: `);
+        const stdin = process.stdin;
+        const wasRaw = stdin.isRaw;
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding("utf8");
+        const onData = (data) => {
+            stdin.removeListener("data", onData);
+            stdin.setRawMode(wasRaw ?? false);
+            stdin.pause();
+            if (data === "n" || data === "N") {
+                process.stdout.write("n\n");
+                resolve(false);
+            }
+            else if (data === "\x03") {
+                process.stdout.write("\n");
+                process.exit(0);
+            }
+            else {
+                // y, Y, Enter — all true
+                process.stdout.write("y\n");
+                resolve(true);
+            }
+        };
+        stdin.on("data", onData);
+    });
+}

package/dist/cli/validate.d.ts

@@ -0,0 +1,54 @@
+import type { Architecture, ArchNode } from "../server/src/generator/index.js";
+import { type RuleLevel, type CustomRule, type CustomRuleMatcher } from "./shared.js";
+interface ValidateOptions {
+    diagram?: string;
+    config?: string;
+    ci?: boolean;
+    watch?: boolean;
+}
+export interface Violation {
+    rule: string;
+    level: RuleLevel;
+    message: string;
+}
+/**
+ * Check for layer bypass violations.
+ * Returns violations where a connection skips layers (e.g. presentation → data).
+ */
+export declare function checkNoLayerBypass(arch: Architecture, realNodes: ArchNode[], nodeMap: Map<string, ArchNode>, level: RuleLevel): Violation[];
+/**
+ * Check for nodes exceeding the max connection threshold.
+ */
+export declare function checkMaxConnections(arch: Architecture, realNodes: ArchNode[], level: RuleLevel, threshold: number): Violation[];
+/**
+ * Check for orphan nodes (no connections).
+ */
+export declare function checkNoOrphans(arch: Architecture, realNodes: ArchNode[], level: RuleLevel): Violation[];
+/**
+ * Check for circular dependencies.
+ */
+export declare function checkCircularDeps(arch: Architecture, realNodes: ArchNode[], nodeMap: Map<string, ArchNode>, level: RuleLevel): Violation[];
+/**
+ * Check if a node matches a custom rule matcher.
+ */
+export declare function matchesNode(node: ArchNode, matcher: CustomRuleMatcher): boolean;
+/**
+ * Evaluate custom rules against the architecture.
+ */
+export declare function evaluateCustomRules(arch: Architecture, realNodes: ArchNode[], nodeMap: Map<string, ArchNode>, customRules: CustomRule[]): Violation[];
+interface ValidationResult {
+    violations: Violation[];
+    errors: number;
+    warnings: number;
+    totalNodes: number;
+    totalEdges: number;
+}
+/**
+ * Core validation logic — runs all rules and returns results without side effects.
+ */
+export declare function runValidation(options: ValidateOptions): ValidationResult;
+/**
+ * Run architecture fitness function validation.
+ */
+export declare function handleValidate(options: ValidateOptions): Promise<void>;
+export {};

package/dist/cli/validate.js

@@ -0,0 +1,315 @@
+import chalk from "chalk";
+import * as fs from "fs";
+import * as path from "path";
+import { resolveArchitecturePath, loadArchitectureFile, loadRulesConfig, getRuleLevel, getThreshold, parseCustomRulesFromYaml, } from "./shared.js";
+/**
+ * Check for layer bypass violations.
+ * Returns violations where a connection skips layers (e.g. presentation → data).
+ */
+export function checkNoLayerBypass(arch, realNodes, nodeMap, level) {
+    const violations = [];
+    const layerOrder = {
+        presentation: 0,
+        application: 1,
+        data: 2,
+    };
+    for (const edge of arch.edges) {
+        const src = nodeMap.get(edge.source);
+        const tgt = nodeMap.get(edge.target);
+        if (!src || !tgt)
+            continue;
+        const srcOrder = layerOrder[src.layer];
+        const tgtOrder = layerOrder[tgt.layer];
+        if (srcOrder === undefined || tgtOrder === undefined)
+            continue;
+        if (tgtOrder - srcOrder > 1) {
+            violations.push({
+                rule: "no-layer-bypass",
+                level,
+                message: `"${src.label}" (${src.layer}) → "${tgt.label}" (${tgt.layer})`,
+            });
+        }
+    }
+    return violations;
+}
+/**
+ * Check for nodes exceeding the max connection threshold.
+ */
+export function checkMaxConnections(arch, realNodes, level, threshold) {
+    const violations = [];
+    const connectionCounts = new Map();
+    for (const edge of arch.edges) {
+        connectionCounts.set(edge.source, (connectionCounts.get(edge.source) || 0) + 1);
+        connectionCounts.set(edge.target, (connectionCounts.get(edge.target) || 0) + 1);
+    }
+    for (const node of realNodes) {
+        const count = connectionCounts.get(node.id) || 0;
+        if (count > threshold) {
+            violations.push({
+                rule: "max-connections",
+                level,
+                message: `"${node.label}" has ${count} connections (threshold: ${threshold})`,
+            });
+        }
+    }
+    return violations;
+}
+/**
+ * Check for orphan nodes (no connections).
+ */
+export function checkNoOrphans(arch, realNodes, level) {
+    const violations = [];
+    const connectedIds = new Set();
+    for (const edge of arch.edges) {
+        connectedIds.add(edge.source);
+        connectedIds.add(edge.target);
+    }
+    for (const node of realNodes) {
+        if (!connectedIds.has(node.id)) {
+            violations.push({
+                rule: "no-orphans",
+                level,
+                message: `"${node.label}" has no connections`,
+            });
+        }
+    }
+    return violations;
+}
+/**
+ * Check for circular dependencies.
+ */
+export function checkCircularDeps(arch, realNodes, nodeMap, level) {
+    const violations = [];
+    const cycles = detectCycles(arch, realNodes);
+    for (const cycle of cycles) {
+        violations.push({
+            rule: "no-circular-deps",
+            level,
+            message: `Cycle: ${cycle.map((id) => nodeMap.get(id)?.label || id).join(" → ")}`,
+        });
+    }
+    return violations;
+}
+/**
+ * Check if a node matches a custom rule matcher.
+ */
+export function matchesNode(node, matcher) {
+    let matches = true;
+    if (matcher.type && node.type !== matcher.type)
+        matches = false;
+    if (matcher.layer && node.layer !== matcher.layer)
+        matches = false;
+    if (matcher.id && node.id !== matcher.id)
+        matches = false;
+    return matcher.not ? !matches : matches;
+}
+/**
+ * Evaluate custom rules against the architecture.
+ */
+export function evaluateCustomRules(arch, realNodes, nodeMap, customRules) {
+    const violations = [];
+    for (const rule of customRules) {
+        for (const edge of arch.edges) {
+            const src = nodeMap.get(edge.source);
+            const tgt = nodeMap.get(edge.target);
+            if (!src || !tgt)
+                continue;
+            if (matchesNode(src, rule.from) && matchesNode(tgt, rule.to)) {
+                violations.push({
+                    rule: rule.name,
+                    level: rule.level,
+                    message: `"${src.label}" (${src.layer}/${src.type}) → "${tgt.label}" (${tgt.layer}/${tgt.type})`,
+                });
+            }
+        }
+    }
+    return violations;
+}
+/**
+ * Core validation logic — runs all rules and returns results without side effects.
+ */
+export function runValidation(options) {
+    const diagramPath = resolveArchitecturePath(options);
+    const arch = loadArchitectureFile(diagramPath);
+    const config = loadRulesConfig(options.config);
+    const violations = [];
+    const realNodes = arch.nodes;
+    const nodeMap = new Map();
+    for (const node of realNodes) {
+        nodeMap.set(node.id, node);
+    }
+    const layerBypassLevel = getRuleLevel(config, "no-layer-bypass", "error");
+    if (layerBypassLevel !== "off") {
+        violations.push(...checkNoLayerBypass(arch, realNodes, nodeMap, layerBypassLevel));
+    }
+    const maxConnLevel = getRuleLevel(config, "max-connections", "warn");
+    if (maxConnLevel !== "off") {
+        const threshold = getThreshold(config, "max-connections", 6);
+        violations.push(...checkMaxConnections(arch, realNodes, maxConnLevel, threshold));
+    }
+    const orphanLevel = getRuleLevel(config, "no-orphans", "warn");
+    if (orphanLevel !== "off") {
+        violations.push(...checkNoOrphans(arch, realNodes, orphanLevel));
+    }
+    const circularLevel = getRuleLevel(config, "no-circular-deps", "error");
+    if (circularLevel !== "off") {
+        violations.push(...checkCircularDeps(arch, realNodes, nodeMap, circularLevel));
+    }
+    // Custom rules
+    const rootDir = process.cwd();
+    const configPath = options.config
+        ? path.resolve(rootDir, options.config)
+        : path.join(rootDir, ".archbyte", "archbyte.yaml");
+    if (fs.existsSync(configPath)) {
+        const yamlContent = fs.readFileSync(configPath, "utf-8");
+        const customRules = parseCustomRulesFromYaml(yamlContent);
+        if (customRules.length > 0) {
+            violations.push(...evaluateCustomRules(arch, realNodes, nodeMap, customRules));
+        }
+    }
+    return {
+        violations,
+        errors: violations.filter((v) => v.level === "error").length,
+        warnings: violations.filter((v) => v.level === "warn").length,
+        totalNodes: realNodes.length,
+        totalEdges: arch.edges.length,
+    };
+}
+/**
+ * Run architecture fitness function validation.
+ */
+export async function handleValidate(options) {
+    const result = runValidation(options);
+    // CI mode: output JSON and exit
+    if (options.ci) {
+        const output = {
+            passed: result.errors === 0,
+            errors: result.errors,
+            warnings: result.warnings,
+            violations: result.violations.map((v) => ({
+                rule: v.rule,
+                level: v.level,
+                message: v.message,
+            })),
+            summary: {
+                totalNodes: result.totalNodes,
+                totalEdges: result.totalEdges,
+            },
+        };
+        console.log(JSON.stringify(output, null, 2));
+        process.exit(result.errors > 0 ? 1 : 0);
+        return;
+    }
+    // Human-readable output
+    printValidationReport(result);
+    // Watch mode: re-validate on file changes
+    if (options.watch) {
+        const chokidar = await import("chokidar");
+        const diagramPath = resolveArchitecturePath(options);
+        console.log(chalk.gray(`  Watching ${diagramPath} for changes...`));
+        console.log(chalk.gray("  Press Ctrl+C to stop."));
+        const watcher = chokidar.watch(diagramPath, { ignoreInitial: true });
+        watcher.on("change", () => {
+            console.clear();
+            const watchResult = runValidation(options);
+            printValidationReport(watchResult);
+            console.log(chalk.gray(`  Watching ${diagramPath} for changes...`));
+            console.log(chalk.gray("  Press Ctrl+C to stop."));
+        });
+        return;
+    }
+    if (result.errors > 0) {
+        process.exit(1);
+    }
+}
+function printValidationReport(result) {
+    const projectName = process.cwd().split("/").pop() || "project";
+    console.log();
+    console.log(chalk.bold.cyan(`⚡ ArchByte Validate — ${projectName}`));
+    console.log();
+    // Group violations by rule for display
+    const ruleViolations = new Map();
+    for (const v of result.violations) {
+        if (!ruleViolations.has(v.rule))
+            ruleViolations.set(v.rule, []);
+        ruleViolations.get(v.rule).push(v);
+    }
+    // Print built-in rules (even if they passed)
+    const builtinRules = ["no-layer-bypass", "max-connections", "no-orphans", "no-circular-deps"];
+    for (const rule of builtinRules) {
+        const violations = ruleViolations.get(rule) || [];
+        printRuleResult(rule, violations.length > 0 ? violations[0].level : "error", violations.length, result.violations);
+    }
+    // Print custom rule results
+    for (const [rule, violations] of ruleViolations) {
+        if (builtinRules.includes(rule))
+            continue;
+        printRuleResult(rule, violations[0].level, violations.length, result.violations);
+    }
+    console.log();
+    const resultStr = result.errors > 0 ? chalk.red("FAIL") : chalk.green("PASS");
+    console.log(`  Result: ${result.warnings} warning${result.warnings !== 1 ? "s" : ""}, ${result.errors} error${result.errors !== 1 ? "s" : ""} — ${resultStr}`);
+    console.log();
+}
+function printRuleResult(rule, level, count, violations) {
+    if (count === 0) {
+        console.log(chalk.green(`  ✓ ${rule}: passed (0 violations)`));
+    }
+    else {
+        const icon = level === "error" ? chalk.red("✗") : chalk.yellow("⚠");
+        const label = level === "error"
+            ? chalk.red(`${count} error${count !== 1 ? "s" : ""}`)
+            : chalk.yellow(`${count} warning${count !== 1 ? "s" : ""}`);
+        console.log(`  ${icon} ${rule}: ${label}`);
+        const ruleViolations = violations.filter((v) => v.rule === rule);
+        for (const v of ruleViolations) {
+            console.log(chalk.gray(`    → ${v.message}`));
+        }
+    }
+}
+/**
+ * Detect cycles in the directed graph using DFS.
+ * Returns an array of cycles, each represented as a list of node IDs.
+ */
+function detectCycles(arch, realNodes) {
+    const adjacency = new Map();
+    for (const node of realNodes) {
+        adjacency.set(node.id, []);
+    }
+    for (const edge of arch.edges) {
+        const neighbors = adjacency.get(edge.source);
+        if (neighbors) {
+            neighbors.push(edge.target);
+        }
+    }
+    const visited = new Set();
+    const inStack = new Set();
+    const cycles = [];
+    const path = [];
+    function dfs(nodeId) {
+        visited.add(nodeId);
+        inStack.add(nodeId);
+        path.push(nodeId);
+        for (const neighbor of adjacency.get(nodeId) || []) {
+            if (!visited.has(neighbor)) {
+                dfs(neighbor);
+            }
+            else if (inStack.has(neighbor)) {
+                // Found a cycle — extract it from the path
+                const cycleStart = path.indexOf(neighbor);
+                if (cycleStart !== -1) {
+                    const cycle = [...path.slice(cycleStart), neighbor];
+                    cycles.push(cycle);
+                }
+            }
+        }
+        path.pop();
+        inStack.delete(nodeId);
+    }
+    for (const node of realNodes) {
+        if (!visited.has(node.id)) {
+            dfs(node.id);
+        }
+    }
+    return cycles;
+}