@buoy-design/cli 0.1.0 → 0.1.2

package/dist/commands/explain.js

@@ -0,0 +1,212 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { spinner, success, error, info, newline, } from "../output/reporters.js";
+import { resolveTarget, runExplainAgents, } from "../explain/agents.js";
+import { loadConfig } from "../config/loader.js";
+import { ScanOrchestrator } from "../scan/orchestrator.js";
+export function createExplainCommand() {
+    const cmd = new Command("explain")
+        .description("AI-powered investigation of code and drift signals")
+        .argument("[target]", "File, directory, or drift:<id> (runs scan if omitted)")
+        .option("-a, --all", "Explain the entire design system")
+        .option("-s, --save", "Save the explanation to .buoy/explain/")
+        .option("-o, --output <path>", "Save explanation to custom path")
+        .option("-v, --verbose", "Show detailed agent progress")
+        .option("-q, --quick", "Quick analysis (shorter prompts, faster)")
+        .option("--json", "Output as JSON")
+        .action(async (targetArg, options) => {
+        try {
+            // Resolve target
+            let target = resolveTarget(targetArg, options.all);
+            // If no target, run scan mode - explain the current drift state
+            if (!target) {
+                target = await runScanAndBuildTarget();
+                if (!target) {
+                    success("No drift detected. Your design system is aligned!");
+                    newline();
+                    info("To investigate specific code, try:");
+                    console.log(chalk.gray("  buoy explain src/components/Button.tsx"));
+                    console.log(chalk.gray("  buoy explain src/components/"));
+                    return;
+                }
+            }
+            // Progress tracking
+            const agentStatus = {};
+            const spin = spinner(`Investigating ${target.name}...`);
+            const updateSpinner = () => {
+                const statuses = Object.entries(agentStatus)
+                    .map(([agent, status]) => {
+                    const icon = status === "completed" ? "✓" : status === "failed" ? "✗" : "○";
+                    const color = status === "completed" ? chalk.green : status === "failed" ? chalk.red : chalk.gray;
+                    return color(`${icon} ${agent}`);
+                })
+                    .join("  ");
+                spin.text = `Investigating ${target.name}...\n  ${statuses}`;
+            };
+            // Run agents
+            const result = await runExplainAgents(target, {
+                verbose: options.verbose,
+                quick: options.quick,
+                onProgress: (agent, status) => {
+                    const displayName = agent
+                        .split("-")
+                        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+                        .join(" ");
+                    agentStatus[displayName] = status;
+                    updateSpinner();
+                },
+            });
+            spin.stop();
+            newline();
+            // Check for failures
+            const failures = result.findings.filter((f) => !f.success);
+            if (failures.length > 0) {
+                newline();
+                for (const f of failures) {
+                    console.log(chalk.yellow(`⚠ ${f.agent}: ${f.error}`));
+                }
+                newline();
+                // If ALL failed, show help
+                if (failures.length === result.findings.length) {
+                    info("All agents failed. Common causes:");
+                    console.log(chalk.gray("  • Claude CLI not installed (run: npm install -g @anthropic-ai/claude-code)"));
+                    console.log(chalk.gray("  • Not authenticated (run: claude login)"));
+                    console.log(chalk.gray("  • Network issues"));
+                    newline();
+                }
+            }
+            // Output
+            if (options.json) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                // Print the synthesis with nice formatting
+                console.log(chalk.gray("─".repeat(60)));
+                newline();
+                console.log(result.synthesis);
+                newline();
+                console.log(chalk.gray("─".repeat(60)));
+            }
+            // Save if requested
+            if (options.save || options.output) {
+                const outputDir = options.output || join(process.cwd(), ".buoy", "explain");
+                mkdirSync(outputDir, { recursive: true });
+                const filename = `${target.name}.md`;
+                const filepath = join(outputDir, filename);
+                writeFileSync(filepath, result.synthesis);
+                newline();
+                success(`Saved to ${filepath}`);
+            }
+            // Verbose: show individual agent outputs
+            if (options.verbose) {
+                newline();
+                info("Individual agent findings:");
+                newline();
+                for (const finding of result.findings) {
+                    if (finding.success) {
+                        console.log(chalk.bold.cyan(`── ${finding.agent} ──`));
+                        console.log(finding.output);
+                        newline();
+                    }
+                }
+            }
+        }
+        catch (err) {
+            error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    return cmd;
+}
+/**
+ * Run a Buoy scan and build an ExplainTarget from the results
+ */
+async function runScanAndBuildTarget() {
+    const spin = spinner("Scanning for drift...");
+    try {
+        const { config } = await loadConfig();
+        const orchestrator = new ScanOrchestrator(config);
+        const { components } = await orchestrator.scanComponents({
+            onProgress: (msg) => {
+                spin.text = msg;
+            },
+        });
+        spin.text = "Analyzing drift...";
+        const { SemanticDiffEngine } = await import("@buoy-design/core/analysis");
+        const engine = new SemanticDiffEngine();
+        const diffResult = engine.analyzeComponents(components, {
+            checkDeprecated: true,
+            checkNaming: true,
+            checkDocumentation: true,
+        });
+        spin.stop();
+        const drifts = diffResult.drifts;
+        if (drifts.length === 0) {
+            return null;
+        }
+        // Format drift data for AI analysis
+        const scanData = formatDriftsForAI(drifts, components.length);
+        return {
+            type: "scan",
+            path: process.cwd(),
+            name: "current-drift",
+            scanData,
+        };
+    }
+    catch (err) {
+        spin.stop();
+        throw err;
+    }
+}
+/**
+ * Format drift signals into a structured text for AI analysis
+ */
+function formatDriftsForAI(drifts, componentCount) {
+    const summary = {
+        total: drifts.length,
+        critical: drifts.filter((d) => d.severity === "critical").length,
+        warning: drifts.filter((d) => d.severity === "warning").length,
+        info: drifts.filter((d) => d.severity === "info").length,
+    };
+    const byType = {};
+    for (const drift of drifts) {
+        if (!byType[drift.type]) {
+            byType[drift.type] = [];
+        }
+        byType[drift.type].push(drift);
+    }
+    let output = `# Buoy Scan Results
+
+## Summary
+- Components scanned: ${componentCount}
+- Total drift signals: ${summary.total}
+- Critical: ${summary.critical}
+- Warning: ${summary.warning}
+- Info: ${summary.info}
+
+## Drift Signals by Type
+
+`;
+    for (const [type, signals] of Object.entries(byType)) {
+        output += `### ${type} (${signals.length})\n\n`;
+        for (const signal of signals.slice(0, 10)) { // Limit to avoid token overflow
+            output += `- **${signal.source.entityName}** (${signal.severity})\n`;
+            output += `  ${signal.message}\n`;
+            if (signal.source.location) {
+                output += `  Location: ${signal.source.location}\n`;
+            }
+            const suggestions = signal.details?.suggestions;
+            if (suggestions && suggestions.length > 0) {
+                output += `  Suggestion: ${suggestions[0]}\n`;
+            }
+            output += "\n";
+        }
+        if (signals.length > 10) {
+            output += `  ... and ${signals.length - 10} more ${type} signals\n\n`;
+        }
+    }
+    return output;
+}
+//# sourceMappingURL=explain.js.map

package/dist/commands/explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../src/commands/explain.ts"],"names":[],"mappings":"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"}

package/dist/commands/graph.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function createGraphCommand(): Command;
+//# sourceMappingURL=graph.d.ts.map

package/dist/commands/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/commands/graph.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4BpC,wBAAgB,kBAAkB,IAAI,OAAO,CAS5C"}

package/dist/commands/graph.js

@@ -0,0 +1,430 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { spinner, success, error, info, header, keyValue, newline, setJsonMode, } from "../output/reporters.js";
+import { GraphBuilder, getGraphStats, exportToDOT, exportToCytoscape, exportToJSON, findUnusedTokens, findUntestedComponents, findUndocumentedComponents, findRepeatOffenders, calculateCoverage, collectGitHistory, collectUsages, collectImports, } from "@buoy-design/core";
+export function createGraphCommand() {
+    const cmd = new Command("graph")
+        .description("Build and query the design system knowledge graph")
+        .addCommand(createBuildCommand())
+        .addCommand(createQueryCommand())
+        .addCommand(createExportCommand())
+        .addCommand(createStatsCommand());
+    return cmd;
+}
+// ============================================================================
+// Build Command
+// ============================================================================
+function createBuildCommand() {
+    return new Command("build")
+        .description("Build the knowledge graph from the codebase")
+        .option("--git", "Include git history", true)
+        .option("--no-git", "Skip git history collection")
+        .option("--usages", "Include token/component usages", true)
+        .option("--no-usages", "Skip usage collection")
+        .option("--imports", "Include import relationships", true)
+        .option("--no-imports", "Skip import collection")
+        .option("--since <date>", "Only include commits since date (ISO format)")
+        .option("--json", "Output as JSON")
+        .action(async (options) => {
+        if (options.json) {
+            setJsonMode(true);
+        }
+        const spin = spinner("Building knowledge graph...");
+        const projectRoot = process.cwd();
+        try {
+            const builder = new GraphBuilder({ projectId: "default" });
+            const stats = {
+                commits: 0,
+                developers: 0,
+                tokenUsages: 0,
+                componentUsages: 0,
+                imports: 0,
+                files: new Set(),
+            };
+            // Collect git history
+            if (options.git) {
+                spin.text = "Collecting git history...";
+                const gitResult = await collectGitHistory(projectRoot, {
+                    since: options.since ? new Date(options.since) : undefined,
+                    includeStats: true,
+                });
+                // Add commits to graph
+                for (const commit of gitResult.commits) {
+                    const commitId = builder.addCommit(commit.sha, commit.message, commit.author, commit.authorEmail, commit.timestamp);
+                    // Track files
+                    for (const file of commit.filesChanged) {
+                        const fileId = builder.addFile(file.path, file.path);
+                        stats.files.add(file.path);
+                        builder.addEdge("CHANGED", commitId, fileId, {
+                            createdAt: commit.timestamp,
+                        });
+                    }
+                }
+                // Add developers
+                for (const dev of gitResult.developers) {
+                    const devId = builder.addDeveloper(dev.id, dev.name, dev.email, undefined, dev.commitCount);
+                    // Link to commits
+                    for (const commit of gitResult.commits) {
+                        if (commit.authorEmail === dev.email) {
+                            const commitId = `commit:${commit.sha}`;
+                            builder.addEdge("AUTHORED", devId, commitId);
+                        }
+                    }
+                }
+                stats.commits = gitResult.commits.length;
+                stats.developers = gitResult.developers.length;
+            }
+            // Collect usages
+            if (options.usages) {
+                spin.text = "Collecting token and component usages...";
+                const usageResult = await collectUsages({ projectRoot });
+                // Track hardcoded values as potential tokens
+                for (const usage of usageResult.hardcodedValues) {
+                    stats.files.add(usage.filePath);
+                }
+                stats.tokenUsages = usageResult.tokenUsages.length;
+                stats.componentUsages = usageResult.componentUsages.length;
+            }
+            // Collect imports
+            if (options.imports) {
+                spin.text = "Collecting import relationships...";
+                const importResult = await collectImports({ projectRoot });
+                for (const imp of importResult.imports) {
+                    if (!imp.isExternal) {
+                        const sourceId = builder.addFile(imp.sourceFile, imp.sourceFile);
+                        const targetId = builder.addFile(imp.targetFile, imp.targetFile);
+                        builder.addEdge("IMPORTS", sourceId, targetId, {
+                            createdAt: new Date(),
+                        });
+                        stats.files.add(imp.sourceFile);
+                        stats.files.add(imp.targetFile);
+                    }
+                }
+                stats.imports = importResult.imports.filter((i) => !i.isExternal)
+                    .length;
+            }
+            spin.stop();
+            const graph = builder.build();
+            const graphStats = getGraphStats(graph);
+            if (options.json) {
+                console.log(JSON.stringify({
+                    stats: {
+                        nodes: graphStats.nodeCount,
+                        edges: graphStats.edgeCount,
+                        commits: stats.commits,
+                        developers: stats.developers,
+                        files: stats.files.size,
+                        imports: stats.imports,
+                    },
+                    nodesByType: graphStats.nodesByType,
+                    edgesByType: graphStats.edgesByType,
+                }, null, 2));
+                return;
+            }
+            success("Graph built successfully!");
+            newline();
+            header("Graph Statistics");
+            keyValue("Total nodes", String(graphStats.nodeCount));
+            keyValue("Total edges", String(graphStats.edgeCount));
+            newline();
+            header("Collected");
+            keyValue("Commits", String(stats.commits));
+            keyValue("Developers", String(stats.developers));
+            keyValue("Files", String(stats.files.size));
+            keyValue("Import relationships", String(stats.imports));
+            newline();
+            if (Object.keys(graphStats.nodesByType).length > 0) {
+                header("Nodes by Type");
+                for (const [type, count] of Object.entries(graphStats.nodesByType)) {
+                    keyValue(type, String(count));
+                }
+            }
+        }
+        catch (err) {
+            spin.stop();
+            const message = err instanceof Error ? err.message : String(err);
+            error(`Graph build failed: ${message}`);
+            process.exit(1);
+        }
+    });
+}
+// ============================================================================
+// Query Command
+// ============================================================================
+function createQueryCommand() {
+    return new Command("query")
+        .description("Query the knowledge graph")
+        .argument("<question>", "What to query (e.g., 'unused tokens')")
+        .option("--json", "Output as JSON")
+        .action(async (question, options) => {
+        if (options.json) {
+            setJsonMode(true);
+        }
+        const spin = spinner("Building graph for query...");
+        const projectRoot = process.cwd();
+        try {
+            // Build a quick graph for querying
+            const builder = new GraphBuilder({ projectId: "default" });
+            // For now, we'll build a minimal graph for queries
+            // In production, this would load from SQLite
+            spin.text = "Collecting data...";
+            const gitResult = await collectGitHistory(projectRoot, { maxCount: 100 });
+            for (const dev of gitResult.developers) {
+                builder.addDeveloper(dev.id, dev.name, dev.email, undefined, dev.commitCount);
+            }
+            spin.stop();
+            const graph = builder.build();
+            // Parse and execute query
+            const queryLower = question.toLowerCase();
+            let result = null;
+            if (queryLower.includes("unused") && queryLower.includes("token")) {
+                result = findUnusedTokens(graph);
+                if (options.json) {
+                    console.log(JSON.stringify({ unusedTokens: result }, null, 2));
+                }
+                else {
+                    header("Unused Tokens");
+                    const tokens = result;
+                    if (tokens.length === 0) {
+                        info("No unused tokens found (graph may not have token data)");
+                    }
+                    else {
+                        for (const t of tokens) {
+                            console.log(`  ${chalk.yellow("•")} ${t}`);
+                        }
+                    }
+                }
+            }
+            else if (queryLower.includes("untested") && queryLower.includes("component")) {
+                result = findUntestedComponents(graph);
+                if (options.json) {
+                    console.log(JSON.stringify({ untestedComponents: result }, null, 2));
+                }
+                else {
+                    header("Untested Components");
+                    const components = result;
+                    if (components.length === 0) {
+                        info("No untested components found");
+                    }
+                    else {
+                        for (const c of components) {
+                            console.log(`  ${chalk.yellow("•")} ${c}`);
+                        }
+                    }
+                }
+            }
+            else if (queryLower.includes("undocumented") && queryLower.includes("component")) {
+                result = findUndocumentedComponents(graph);
+                if (options.json) {
+                    console.log(JSON.stringify({ undocumentedComponents: result }, null, 2));
+                }
+                else {
+                    header("Undocumented Components");
+                    const components = result;
+                    if (components.length === 0) {
+                        info("No undocumented components found");
+                    }
+                    else {
+                        for (const c of components) {
+                            console.log(`  ${chalk.yellow("•")} ${c}`);
+                        }
+                    }
+                }
+            }
+            else if (queryLower.includes("repeat") || queryLower.includes("offender")) {
+                result = findRepeatOffenders(graph);
+                if (options.json) {
+                    console.log(JSON.stringify({ repeatOffenders: result }, null, 2));
+                }
+                else {
+                    header("Repeat Offenders");
+                    const offenders = result;
+                    if (offenders.length === 0) {
+                        info("No repeat offenders found");
+                    }
+                    else {
+                        for (const o of offenders) {
+                            console.log(`  ${chalk.red("•")} ${o.file} ${chalk.dim(`(${o.driftCount} drift signals)`)}`);
+                        }
+                    }
+                }
+            }
+            else if (queryLower.includes("coverage")) {
+                result = calculateCoverage(graph);
+                if (options.json) {
+                    console.log(JSON.stringify({ coverage: result }, null, 2));
+                }
+                else {
+                    header("Design System Coverage");
+                    const coverage = result;
+                    keyValue("Token usage", `${(coverage.tokenCoverage * 100).toFixed(1)}%`);
+                    keyValue("Test coverage", `${(coverage.testCoverage * 100).toFixed(1)}%`);
+                    keyValue("Story coverage", `${(coverage.storyCoverage * 100).toFixed(1)}%`);
+                }
+            }
+            else {
+                error(`Unknown query: "${question}"`);
+                newline();
+                info("Available queries:");
+                info("  • unused tokens");
+                info("  • untested components");
+                info("  • undocumented components");
+                info("  • repeat offenders");
+                info("  • coverage");
+                process.exit(1);
+            }
+        }
+        catch (err) {
+            spin.stop();
+            const message = err instanceof Error ? err.message : String(err);
+            error(`Query failed: ${message}`);
+            process.exit(1);
+        }
+    });
+}
+// ============================================================================
+// Export Command
+// ============================================================================
+function createExportCommand() {
+    return new Command("export")
+        .description("Export the graph for visualization")
+        .option("-f, --format <format>", "Output format (json, dot, cytoscape)", "json")
+        .option("-o, --output <file>", "Output file (default: stdout)")
+        .action(async (options) => {
+        const spin = spinner("Building graph for export...");
+        const projectRoot = process.cwd();
+        try {
+            // Build graph
+            const builder = new GraphBuilder({ projectId: "default" });
+            spin.text = "Collecting data...";
+            const gitResult = await collectGitHistory(projectRoot, { maxCount: 200 });
+            for (const commit of gitResult.commits) {
+                builder.addCommit(commit.sha, commit.message, commit.author, commit.authorEmail, commit.timestamp);
+            }
+            for (const dev of gitResult.developers) {
+                builder.addDeveloper(dev.id, dev.name, dev.email, undefined, dev.commitCount);
+            }
+            spin.text = "Collecting imports...";
+            const importResult = await collectImports({ projectRoot });
+            for (const imp of importResult.imports) {
+                if (!imp.isExternal) {
+                    const sourceId = builder.addFile(imp.sourceFile, imp.sourceFile);
+                    const targetId = builder.addFile(imp.targetFile, imp.targetFile);
+                    builder.addEdge("IMPORTS", sourceId, targetId);
+                }
+            }
+            spin.stop();
+            const graph = builder.build();
+            let output;
+            switch (options.format) {
+                case "dot":
+                    output = exportToDOT(graph);
+                    break;
+                case "cytoscape":
+                    output = JSON.stringify(exportToCytoscape(graph), null, 2);
+                    break;
+                case "json":
+                default:
+                    output = JSON.stringify(exportToJSON(graph), null, 2);
+                    break;
+            }
+            if (options.output) {
+                const fs = await import("fs/promises");
+                await fs.writeFile(options.output, output, "utf-8");
+                success(`Graph exported to ${options.output}`);
+            }
+            else {
+                console.log(output);
+            }
+        }
+        catch (err) {
+            spin.stop();
+            const message = err instanceof Error ? err.message : String(err);
+            error(`Export failed: ${message}`);
+            process.exit(1);
+        }
+    });
+}
+// ============================================================================
+// Stats Command
+// ============================================================================
+function createStatsCommand() {
+    return new Command("stats")
+        .description("Show graph statistics")
+        .option("--json", "Output as JSON")
+        .action(async (options) => {
+        if (options.json) {
+            setJsonMode(true);
+        }
+        const spin = spinner("Analyzing codebase...");
+        const projectRoot = process.cwd();
+        try {
+            // Collect basic stats without building full graph
+            spin.text = "Analyzing git history...";
+            const gitResult = await collectGitHistory(projectRoot, { maxCount: 1000 });
+            spin.text = "Analyzing usages...";
+            const usageResult = await collectUsages({ projectRoot });
+            spin.text = "Analyzing imports...";
+            const importResult = await collectImports({ projectRoot });
+            spin.stop();
+            const stats = {
+                git: {
+                    commits: gitResult.commits.length,
+                    developers: gitResult.developers.length,
+                    dateRange: gitResult.stats.dateRange,
+                },
+                usages: {
+                    tokenUsages: usageResult.tokenUsages.length,
+                    componentUsages: usageResult.componentUsages.length,
+                    hardcodedValues: usageResult.hardcodedValues.length,
+                    filesScanned: usageResult.stats.filesScanned,
+                },
+                imports: {
+                    localImports: importResult.imports.filter((i) => !i.isExternal).length,
+                    externalPackages: importResult.externalDependencies.size,
+                    filesScanned: importResult.stats.filesScanned,
+                },
+            };
+            if (options.json) {
+                console.log(JSON.stringify(stats, null, 2));
+                return;
+            }
+            header("Git History");
+            keyValue("Commits", String(stats.git.commits));
+            keyValue("Contributors", String(stats.git.developers));
+            if (stats.git.dateRange) {
+                keyValue("Date range", `${stats.git.dateRange.start.toLocaleDateString()} - ${stats.git.dateRange.end.toLocaleDateString()}`);
+            }
+            newline();
+            header("Token/Component Usages");
+            keyValue("Token usages", String(stats.usages.tokenUsages));
+            keyValue("Component usages", String(stats.usages.componentUsages));
+            keyValue("Hardcoded values", String(stats.usages.hardcodedValues));
+            keyValue("Files scanned", String(stats.usages.filesScanned));
+            newline();
+            header("Import Analysis");
+            keyValue("Local imports", String(stats.imports.localImports));
+            keyValue("External packages", String(stats.imports.externalPackages));
+            keyValue("Files scanned", String(stats.imports.filesScanned));
+            // Show top external deps
+            if (importResult.externalDependencies.size > 0) {
+                newline();
+                header("Top External Dependencies");
+                const deps = Array.from(importResult.externalDependencies).slice(0, 10);
+                for (const dep of deps) {
+                    console.log(`  ${chalk.blue("•")} ${dep}`);
+                }
+                if (importResult.externalDependencies.size > 10) {
+                    info(`  ... and ${importResult.externalDependencies.size - 10} more`);
+                }
+            }
+        }
+        catch (err) {
+            spin.stop();
+            const message = err instanceof Error ? err.message : String(err);
+            error(`Stats failed: ${message}`);
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=graph.js.map