Merge branch 'dev' of https://github.com/HUMBLEF0OL/grotto into staging

Author: HUMBLEF0OL

.changeset/git-compass-cli-readiness.md

@@ -0,0 +1,10 @@
+---
+"@git-compass/core": minor
+"@git-compass/web": minor
+---
+
+NPM Publication Readiness:
+- Turn `@git-compass/web` into a global CLI tool out of the box.
+- Create `bin/git-compass.js` wrapper with dynamic `REPO_PATH` resolution.
+- Update `package.json` metadata (description, keywords, bin) for professional NPM distribution.
+- Align `@git-compass/core` metadata for registry discoverability.

packages/cli/package.json

@@ -41,6 +41,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
+    "cli": "tsx src/bin/git-compass.ts",
     "lint": "eslint .",
     "test": "vitest run"
   },

packages/cli/report.txt

@@ -33,6 +33,8 @@ import {
   saveCache,
 } from "../utils/cache.js";
 import { ensureGitIgnore } from "../utils/gitignore.js";
+import { printConsoleReport } from "../formatters/console.js";
+
 
 export const analyzeAllCommand = new Command("analyze-all")
   .description("Scan a directory for Git repositories and analyze them all")
@@ -156,6 +158,10 @@ export const analyzeAllCommand = new Command("analyze-all")
               `${repoName}: ${result.meta.commitCount} commits, ${highRiskCount} high-risk files.`,
             ),
           );
+
+          if (options.detailLevel === "verbose") {
+            printConsoleReport(result, "normal", !!options.ai);
+          }
         } catch (err) {
           repoSpinner.fail(chalk.red(`Failed to analyze ${repoName}: ${(err as Error).message}`));
         }

packages/cli/src/commands/analyze-all.ts

@@ -111,13 +111,16 @@ export const analyzeCommand = new Command("analyze")
         : await getCommits(git, {
             branch: options.branch,
             maxCount: parseInt(options.maxCommits, 10),
+            since: options.window !== "all" ? options.window : undefined,
           });
 
       if (!cachedResult && commits.length === 0) {
         spinner.fail(chalk.red("No commits found in the specified window/branch."));
         return;
       }
 
+      spinner.text = `Performing deep analysis on ${commits.length} commits...`;
+
       const result: AnalysisResult = cachedResult || {
         meta: {
           repoPath,
@@ -126,42 +129,38 @@ export const analyzeCommand = new Command("analyze")
           commitCount: commits.length,
           generatedAt: new Date(),
         },
-        hotspots: analyzeHotspots(commits, options.window as any),
-        riskScores: computeRiskScores(analyzeHotspots(commits, options.window as any)), // Simplified for rebuild
-        churn: analyzeChurn(commits, options.window as any),
-        contributors: analyzeContributors(commits),
-        burnout: analyzeBurnout(commits),
-        coupling: analyzeCoupling(commits),
-        knowledge: analyzeKnowledge(commits),
-        impact: analyzeImpact(commits),
-        rot: analyzeRot(commits),
-        compass: analyzeCompass(commits),
-        health: analyzeHealth(
-          commits,
-          analyzeChurn(commits, options.window as any),
-          analyzeCoupling(commits),
-        ),
-        contributorTimeline: analyzeContributorTimeline(commits),
+        hotspots: [],
+        riskScores: [],
+        churn: [],
+        contributors: [],
+        contributorTimeline: [],
+        burnout: { flags: [], afterHoursCommits: 0, weekendCommits: 0, contributors: [] },
+        coupling: [],
+        knowledge: [],
+        impact: [],
+        rot: [],
+        compass: { essentials: [], components: [] },
+        health: { stability: 0, velocity: 0, simplicity: 0, coverage: 0, decoupling: 0 },
       };
 
-      // Re-calculate hotspots/risk if we don't have cached result (above logic is a bit messy, let's fix)
       if (!cachedResult) {
-        spinner.text = `Analyzing ${commits.length} commits...`;
-        const h = analyzeHotspots(commits, options.window as any);
-        result.hotspots = h;
-        result.riskScores = computeRiskScores(h);
+        const hotspots = analyzeHotspots(commits, options.window as any);
+        const riskScores = computeRiskScores(hotspots);
         const churn = analyzeChurn(commits, options.window as any);
         const coupling = analyzeCoupling(commits);
+
+        result.hotspots = hotspots;
+        result.riskScores = riskScores;
         result.churn = churn;
+        result.coupling = coupling;
         result.contributors = analyzeContributors(commits);
+        result.contributorTimeline = analyzeContributorTimeline(commits);
         result.burnout = analyzeBurnout(commits);
-        result.coupling = coupling;
         result.knowledge = analyzeKnowledge(commits);
         result.impact = analyzeImpact(commits);
         result.rot = analyzeRot(commits);
         result.compass = analyzeCompass(commits);
         result.health = analyzeHealth(commits, churn, coupling);
-        result.contributorTimeline = analyzeContributorTimeline(commits);
       }
 
       if (options.ai) {

packages/cli/src/commands/analyze.ts

@@ -15,3 +15,9 @@ export const ENV_VARS = {
   GEMINI_API_KEY: "GEMINI_API_KEY",
   AI_PROVIDER: "GIT_COMPASS_AI_PROVIDER",
 } as const;
+
+export const HEALTH_THRESHOLDS = {
+  GOOD: 70,
+  WARNING: 40,
+} as const;
+

packages/cli/src/constants/index.ts

@@ -2,6 +2,7 @@ import chalk from "chalk";
 import boxen from "boxen";
 import { table, getBorderCharacters } from "table";
 import type { AnalysisResult } from "@git-compass/core";
+import { HEALTH_THRESHOLDS } from "../constants/index.js";
 
 export function printConsoleReport(
   result: AnalysisResult,
@@ -36,7 +37,11 @@ export function printConsoleReport(
         5,
     );
     const healthColor =
-      healthScore > 70 ? chalk.green : healthScore > 40 ? chalk.yellow : chalk.red;
+      healthScore > HEALTH_THRESHOLDS.GOOD
+        ? chalk.green
+        : healthScore > HEALTH_THRESHOLDS.WARNING
+          ? chalk.yellow
+          : chalk.red;
 
     console.log(
       boxen(
@@ -86,7 +91,7 @@ export function printConsoleReport(
     }
 
     if (isSummary) {
-      printHealthIndicators(health, impact, rot, !!result.aiSummary);
+      printHealthIndicators(health, impact, rot, result.churn, !!result.aiSummary);
       return;
     }
 
@@ -129,8 +134,13 @@ export function printConsoleReport(
         const riskLevel = fileRisk?.level || "low";
         const riskColor = getRiskColor(riskLevel);
 
+        // Explanatory factors
+        const factors = fileRisk?.factors
+          ? `(${chalk.gray(`freq:${fileRisk.factors.changeFrequency},auth:${fileRisk.factors.uniqueAuthors},rec:${fileRisk.factors.recentActivity}`)})`
+          : "";
+
         hotspotData.push([
-          chalk.white(h.path),
+          chalk.white(h.path) + (factors ? "\n" + factors : ""),
           chalk.cyan(h.changeCount.toString()),
           chalk.magenta(h.uniqueAuthors.toString()),
           chalk.hex(riskColor).bold(riskLevel.toUpperCase()),
@@ -209,20 +219,30 @@ export function printConsoleReport(
         });
       }
 
+      const highImpact = [...(impact || [])].sort((a, b) => b.blastRadius - a.blastRadius);
+      if (highImpact.length > 0) {
+        insightsData.push([chalk.bold("High Blast Radius (Impact)")]);
+        highImpact.slice(0, 5).forEach((i) => {
+          insightsData.push([
+            `  ${chalk.white(i.path)}\n  ${chalk.gray("Avg Change Ripple: ")}${chalk.yellow(i.blastRadius.toFixed(1) + " files")}`,
+          ]);
+        });
+      }
+
       if (insightsData.length > 0) {
         console.log(chalk.blue.bold("\nDeep Architecture Insights"));
         console.log(table(insightsData, { border: getBorderCharacters("ramac") }));
       }
     }
 
     // 7. Health Indicators & Footer Tip
-    printHealthIndicators(health, impact, rot, showAI);
+    printHealthIndicators(health, impact, rot, result.churn, showAI);
   } catch (err) {
     console.error(chalk.red("\nError printing report:"), err);
   }
 }
 
-function printHealthIndicators(health: any, impact: any[], rot: any[], showAI: boolean) {
+function printHealthIndicators(health: any, impact: any[], rot: any[], churn: any[], showAI: boolean) {
   const avgImpact =
     impact.length > 0
       ? (impact.reduce((acc: number, i: any) => acc + i.blastRadius, 0) / impact.length).toFixed(2)
@@ -234,11 +254,26 @@ function printHealthIndicators(health: any, impact: any[], rot: any[], showAI: b
     `${chalk.white("Stability:   ")} ${chalk.cyan(health.stability + "%")}`,
     `${chalk.white("Velocity:    ")} ${chalk.cyan(health.velocity + "%")}`,
     `${chalk.white("Complexity:  ")} ${chalk.cyan(health.simplicity + "%")}`,
+    `${chalk.white("Coverage:    ")} ${chalk.cyan(health.coverage + "%")}`,
     `${chalk.white("Decoupling:  ")} ${chalk.cyan(health.decoupling + "%")}`,
     `${chalk.white("Blast Radius:")} ${chalk.yellow(avgImpact + " files")}`,
     `${chalk.white("Code Rot:    ")} ${chalk.red(rot.length + " abandoned files")}`,
   ];
 
+  // Churn trend summary
+  if (churn && churn.length > 0) {
+    const sortedChurn = [...churn].sort(
+      (a: any, b: any) => b.linesAdded + b.linesRemoved - (a.linesAdded + a.linesRemoved),
+    );
+    const peak = sortedChurn[0];
+    const peakDate = new Date(peak.date).toLocaleDateString();
+    footerContent.splice(
+      2,
+      0,
+      `${chalk.white("Peak Churn:  ")} ${chalk.magenta(peakDate)} ${chalk.gray(`(${peak.linesAdded + peak.linesRemoved} lines)`)}`,
+    );
+  }
+
   if (!showAI) {
     footerContent.push("");
     footerContent.push(