pika-review 2.0.1 → 2.2.0

package/README.md

@@ -1,22 +1,30 @@
 # Pika Review 🦊
-### Enterprise-grade AI Architectural Sentinel
 
-Pika Review is a high-performance CLI tool designed to perform surgical code reviews using AI. It focuses on deep architectural debt, security vulnerabilities, and UI/UX anomalies that traditional linters miss.
+### Enterprise-grade AI Architectural Sentinel & Compliance Engine
+
+Pika Review is a high-performance CLI tool designed to perform surgical code reviews using AI. It focuses on deep architectural debt, security vulnerabilities, and project-specific compliance that traditional linters miss.
 
 **GitHub**: [HackX-IN/pika-review](https://github.com/HackX-IN/pika-review)
 
 ---
 
 ## 🚀 Key Features
-- **Provider Agnostic**: Seamlessly works with Cloudflare Workers AI, OpenAI, Grok, or local LLMs via OpenAI-compatible endpoints.
-- **Mixture of Experts (MoE) Reasoning**: Leverages advanced LLMs for deep structural analysis.
-- **Polyglot Heuristics**: Idiom-aware reviews across Python, JS/TS, Go, Rust, and React.
-- **Interactive UI**: Claude-inspired terminal experience with real-time progress and multi-select discovery.
-- **Enterprise-Ready**: Built-in token safety, JSON self-healing, and CI/CD integration.
+
+- **🧠 Architecture Rules Engine**: Enforce project-specific standards via `.pika-rules.md`.
+- **🦙 Native Local Ollama Support**: Run 100% private, free, offline scans using local LLMs (e.g. Qwen, Llama).
+- **🎛️ Local Model Selector**: Interactively choose and configure local models from the command line.
+- **🛡️ Git Commit Safeguard Hook**: Prevent pushing high-severity compliance debt and vulnerabilities automatically.
+- **📊 Health Dashboard**: Track architectural health trends over time with `pika-review stats`.
+- **🎨 Premium Interactive Reports**: Immersive, dark-mode HTML reports for deep triage.
+- **🔍 Smart Context Scanning**: Uses `-U10` context windows for higher AI reasoning accuracy.
+- **🛡️ "Pika-Ignore" support**: Suppress specific lines using `// pika-ignore` comments.
+- **⚡ Parallel Orchestration**: Scans multiple files concurrently with `p-limit`.
+- **🌍 Provider Agnostic**: Works with OpenAI, Claude, Grok, local Ollama, or any OpenAI-compatible endpoint.
 
 ---
 
 ## 📦 Installation
+
 ```bash
 # Via Bun (Recommended)
 bun add -g pika-review
@@ -26,53 +34,113 @@ npm install -g pika-review
 ```
 
 ## 🛠️ Setup
+
 1. Initialize your configuration:
    ```bash
    pika-review init
    ```
-2. Open `~/.pika-review.yaml` and add your Cloudflare credentials:
+2. Configure your AI provider in `~/.pika-review.yaml`:
    ```yaml
    ai:
-     accountId: "your-account-id"
-     apiKey: "your-scoped-api-token"
+     apiKey: "your-api-token"
+     model: "gpt-4o" # or your preferred model
+     baseURL: "https://api.openai.com/v1"
    ```
 
-### 🌍 Custom AI Providers (OpenAI, Grok, etc.)
-Pika Review works with any OpenAI-compatible API. To use a different provider, simply override the `baseURL` and `model` in your config:
+---
+
+## 🏗️ Enterprise Features
 
-```yaml
-ai:
-  apiKey: "your-openai-key"
-  model: "gpt-4o"
-  baseURL: "https://api.openai.com/v1"
+### 1. Architecture Rules Engine
+
+Create a `.pika-rules.md` file in your repository root to guide the AI with project-specific context:
+
+```markdown
+# Architectural Rules
+
+- Use Functional Components with Hooks, never Class Components.
+- All service calls must go through `src/api/client.ts`.
+- Database queries are restricted to the Repository layer.
 ```
 
-## 🔍 Usage
-Scan staged git changes:
-```bash
-pika-review scan
+### 2. Pika-Ignore
+
+Suppress false positives or acknowledged risks directly in your code:
+
+```typescript
+const secret = "12345"; // pika-ignore (intentional for testing)
 ```
 
-Scan specific files:
+### 3. Health Stats
+
+Monitor your codebase's architectural debt over time:
+
 ```bash
-pika-review scan src/index.ts src/utils/token.ts
+pika-review stats
 ```
 
-Scan unstaged changes:
+---
+
+## 🔍 Usage
+
+| Command                 | Description                                                  |
+| :---------------------- | :----------------------------------------------------------- |
+| `pika-review scan`      | Scan staged git changes (Default)                            |
+| `pika-review scan -i`   | Interactive file selection mode                              |
+| `pika-review view`      | Open the latest interactive report                           |
+| `pika-review stats`     | View architectural health trends and scan dashboard          |
+| `pika-review models`    | Interactively select and configure local Ollama models       |
+| `pika-review hook <act>`| Install (`install`) or uninstall (`uninstall`) Git safeguards |
+| `pika-review rules -g`  | Auto-generate architectural `.pika-rules.md` guidelines       |
+| `pika-review scan --ci` | Fail pipeline on Critical/High issues                        |
+
+---
+
+## 🦙 Local Ollama & Offline Setup
+
+Pika Review fully supports local, 100% private, offline code reviews via [Ollama](https://ollama.com).
+
+### 1. Configure Ollama Provider
+Initialize your configuration:
 ```bash
-pika-review scan --unstaged
+pika-review init
 ```
+Open `~/.pika-review.yaml` and configure the Ollama provider:
+```yaml
+ai:
+  provider: "ollama"
+  model: "qwen2.5-coder:7b" # Or your pulled model
+  baseURL: "http://localhost:11434/v1"
+```
+
+### 2. Interactive Local Setup
+To avoid editing files manually, you can manage everything directly from the command line:
 
-### CI/CD Mode
-Use the `--ci` flag in GitHub Actions or other pipelines to fail if Critical or High severity issues are found:
 ```bash
-pika-review scan --ci
+# Discover local pulled models and switch active model instantly
+pika-review models
+
+# Automatically bootstrap customized architectural rules for your tech stack
+pika-review rules --generate
+
+# Register git safeguard hooks to run scans automatically before commits
+pika-review hook install
 ```
 
 ---
 
+## 🤝 Contributing
+
+We welcome contributions from the community to help make Pika Review the ultimate architectural code reviewer! 
+
+Please read our **[Contributing Guide](CONTRIBUTING.md)** for details on how to set up local development, run compiler checks, write custom CLI commands, and submit high-quality Pull Requests.
+
+---
+
 ## 🛡️ Privacy & Security
-Pika Review uses your local git diffs and sends them directly to your Cloudflare Workers AI instance. No code is stored by Pika Review.
+
+Pika Review processes your local git diffs and transmits them directly to your configured AI provider via SSL. No code is stored or cached by the Pika Review engine.
 
 ## 📄 License
+
 MIT © Pika Review Contributors

package/dist/cmd/hook.js

@@ -0,0 +1,85 @@
+import fs from "fs";
+import path from "path";
+import chalk from "chalk";
+import { logger } from "../utils/logger.js";
+/**
+ * CLI Command Action: hook [action]
+ * Manages the Git pre-commit hook installation/removal.
+ */
+export async function hookAction(action) {
+    const gitPath = path.join(process.cwd(), ".git");
+    if (!fs.existsSync(gitPath)) {
+        logger.error("Not a Git repository.");
+        logger.dim("Pika Review Git hooks can only be installed in the root of a Git repository.");
+        return;
+    }
+    const hooksPath = path.join(gitPath, "hooks");
+    const hookFile = path.join(hooksPath, "pre-commit");
+    // Ensure hooks directory exists
+    if (!fs.existsSync(hooksPath)) {
+        fs.mkdirSync(hooksPath, { recursive: true });
+    }
+    const HOOK_SCRIPT = `#!/bin/sh
+# Pika Review - Architectural Sentinel Git Safeguard Hook
+echo "🦊 Running local architectural compliance checks..."
+pika-review scan --ci
+
+EXIT_CODE=$?
+if [ $EXIT_CODE -ne 0 ]; then
+  echo "❌ [Pika Review] Commit rejected due to high-severity compliance anomalies."
+  exit $EXIT_CODE
+fi
+
+exit 0
+`;
+    if (action === "install") {
+        let backupCreated = false;
+        if (fs.existsSync(hookFile)) {
+            const content = fs.readFileSync(hookFile, "utf-8");
+            if (content.includes("Pika Review")) {
+                logger.info("Pika Review hook is already installed!");
+                return;
+            }
+            // Create backup of existing hook
+            const backupPath = `${hookFile}.bak`;
+            fs.writeFileSync(backupPath, content);
+            backupCreated = true;
+            logger.info(`Existing hook backed up to ${chalk.cyan("pre-commit.bak")}`);
+        }
+        try {
+            fs.writeFileSync(hookFile, HOOK_SCRIPT, { mode: 0o755 });
+            logger.success("Git pre-commit hook installed successfully!");
+            logger.info(`Path: ${chalk.dim(hookFile)}`);
+            logger.dim("Pika Review will now scan your staged files automatically before every commit.");
+        }
+        catch (e) {
+            logger.error(`Failed to install Git hook: ${e.message}`);
+        }
+    }
+    else if (action === "uninstall") {
+        if (!fs.existsSync(hookFile)) {
+            logger.warn("No pre-commit hook found to uninstall.");
+            return;
+        }
+        const content = fs.readFileSync(hookFile, "utf-8");
+        if (!content.includes("Pika Review")) {
+            logger.warn("The existing pre-commit hook was not installed by Pika Review. Leaving it untouched.");
+            return;
+        }
+        try {
+            fs.unlinkSync(hookFile);
+            logger.success("Pika Review Git pre-commit hook uninstalled successfully.");
+            // Restore backup if it exists
+            const backupPath = `${hookFile}.bak`;
+            if (fs.existsSync(backupPath)) {
+                fs.renameSync(backupPath, hookFile);
+                // Make sure it remains executable
+                fs.chmodSync(hookFile, 0o755);
+                logger.success("Restored previous pre-commit hook from backup!");
+            }
+        }
+        catch (e) {
+            logger.error(`Failed to uninstall Git hook: ${e.message}`);
+        }
+    }
+}

package/dist/cmd/models.js

@@ -0,0 +1,68 @@
+import prompts from "prompts";
+import chalk from "chalk";
+import { getConfig, saveConfig } from "../utils/config.js";
+import { logger } from "../utils/logger.js";
+/**
+ * CLI Command Action: models
+ * Queries local Ollama daemon for available models and updates active configuration.
+ */
+export async function modelsAction() {
+    const config = getConfig();
+    // Extract base host from configuration baseURL or fallback to localhost
+    let host = "http://localhost:11434";
+    if (config.ai.baseURL) {
+        try {
+            const url = new URL(config.ai.baseURL);
+            host = `${url.protocol}//${url.host}`;
+        }
+        catch (e) { }
+    }
+    logger.info(`Connecting to Ollama daemon at ${chalk.cyan(host)}...`);
+    try {
+        const res = await fetch(`${host}/api/tags`);
+        if (!res.ok) {
+            throw new Error(`Server returned HTTP ${res.status}`);
+        }
+        const data = (await res.json());
+        if (!data.models || data.models.length === 0) {
+            logger.warn(`No models found inside your local Ollama instance.`);
+            logger.info(`Try pulling a model first using: ${chalk.yellow("ollama pull llama3")}`);
+            return;
+        }
+        const choices = data.models.map((m) => {
+            const sizeGB = m.size ? `${(m.size / (1024 * 1024 * 1024)).toFixed(2)} GB` : "Unknown size";
+            const paramSize = m.details?.parameter_size ? ` [${m.details.parameter_size}]` : "";
+            return {
+                title: `${chalk.bold(m.name)} ${chalk.dim(`(${sizeGB}${paramSize})`)}`,
+                value: m.name,
+            };
+        });
+        const response = await prompts({
+            type: "select",
+            name: "model",
+            message: "Select your active local Ollama model:",
+            choices,
+            initial: 0,
+        });
+        if (response.model) {
+            config.ai.provider = "ollama";
+            config.ai.model = response.model;
+            // Auto-set standard baseURL if empty or not set to localhost
+            if (!config.ai.baseURL || config.ai.baseURL.includes("cloudflare")) {
+                config.ai.baseURL = "http://localhost:11434/v1";
+            }
+            saveConfig(config);
+            logger.success(`Configuration updated successfully!`);
+            logger.info(`Active Model:   ${chalk.green(response.model)}`);
+            logger.info(`AI Provider:    ${chalk.cyan("ollama")}`);
+            logger.info(`API Base URL:   ${chalk.cyan(config.ai.baseURL)}`);
+        }
+    }
+    catch (error) {
+        logger.error(`Could not connect to Ollama daemon.`);
+        console.log(chalk.dim(`\n💡 To solve this, make sure:`));
+        console.log(` 1. Ollama is installed on your machine (https://ollama.com).`);
+        console.log(` 2. The daemon is running (${chalk.yellow("ollama serve")} or desktop application).`);
+        console.log(` 3. Your config baseURL is pointing to your active daemon (current: ${chalk.red(host)}).\n`);
+    }
+}

package/dist/cmd/rules.js

@@ -0,0 +1,114 @@
+import fs from "fs";
+import path from "path";
+import prompts from "prompts";
+import chalk from "chalk";
+import OpenAI from "openai";
+import { getConfig } from "../utils/config.js";
+import { listProjectFiles } from "../core/scanner.js";
+import { logger } from "../utils/logger.js";
+/**
+ * CLI Command Action: rules generate
+ * Uses the configured AI provider to bootstrap architectural rules tailored to the current codebase.
+ */
+export async function rulesAction() {
+    const config = getConfig();
+    const isOllama = config.ai.provider === "ollama";
+    if (!isOllama && (!config.ai.apiKey || !config.ai.accountId)) {
+        logger.error("Missing AI credentials in ~/.pika-review.yaml.");
+        logger.info("Run 'pika-review init' to initialize config or set provider to 'ollama' for offline mode.");
+        return;
+    }
+    const rulesPath = path.join(process.cwd(), ".pika-rules.md");
+    if (fs.existsSync(rulesPath)) {
+        const overwrite = await prompts({
+            type: "confirm",
+            name: "confirm",
+            message: "An existing .pika-rules.md already exists. Do you want to overwrite it?",
+            initial: false,
+        });
+        if (!overwrite.confirm) {
+            logger.info("Operation cancelled.");
+            return;
+        }
+    }
+    else {
+        const confirm = await prompts({
+            type: "confirm",
+            name: "confirm",
+            message: "Generate a custom, AI-crafted .pika-rules.md architectural guidelines guide for this codebase?",
+            initial: true,
+        });
+        if (!confirm.confirm) {
+            logger.info("Operation cancelled.");
+            return;
+        }
+    }
+    logger.info("Analyzing codebase structure and dependencies...");
+    // 1. Gather package.json context
+    let projectTechStack = "";
+    try {
+        const packageJsonPath = path.join(process.cwd(), "package.json");
+        if (fs.existsSync(packageJsonPath)) {
+            const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+            const deps = Object.keys(packageJson.dependencies || {}).join(", ");
+            const devDeps = Object.keys(packageJson.devDependencies || {}).join(", ");
+            projectTechStack += `Package Name: ${packageJson.name || "unknown"}\nDependencies: ${deps || "none"}\nDevDependencies: ${devDeps || "none"}\n`;
+        }
+    }
+    catch (e) { }
+    // 2. Gather file layout context
+    const files = listProjectFiles();
+    const fileSummary = files.slice(0, 30).map(f => ` - ${f}`).join("\n");
+    const projectStructure = `Detected files (subset):\n${fileSummary}\nTotal files discovered: ${files.length}\n`;
+    logger.info(`Synthesizing tailored rules using AI model (${chalk.green(config.ai.model)})...`);
+    const prompt = `You are an Elite Senior Software Architect and Compliance Officer.
+Your task is to write a highly detailed, professional, and practical architectural rules file called ".pika-rules.md" for a project with the following tech stack and structure:
+
+<project_tech_stack>
+${projectTechStack || "Generic web/software codebase"}
+</project_tech_stack>
+
+<project_structure>
+${projectStructure}
+</project_structure>
+
+Instructions:
+- Write the output in clean, professional Markdown format.
+- Establish 5 to 8 strict, concrete, actionable architectural rules tailored to the libraries, patterns, and folder layout of this specific project (e.g. naming conventions, folder segregation, API patterns, state management, security).
+- Provide a brief justification for each rule.
+- Do NOT output any preamble, greeting, markdown backticks wrapper, or postscript.
+- Start directly with "# Pika Architectural Rules" and start rules lists immediately.`;
+    const baseURL = config.ai.baseURL && config.ai.baseURL.trim()
+        ? config.ai.baseURL
+        : (isOllama
+            ? "http://localhost:11434/v1"
+            : `https://api.cloudflare.com/client/v4/accounts/${config.ai.accountId}/ai/v1`);
+    const openai = new OpenAI({
+        apiKey: config.ai.apiKey || "ollama",
+        baseURL,
+    });
+    try {
+        const response = await openai.chat.completions.create({
+            model: config.ai.model,
+            messages: [{ role: "user", content: prompt }],
+            temperature: 0.3,
+            max_tokens: 1500,
+        });
+        let rawMarkdown = response.choices[0]?.message?.content || "";
+        // Clean code block ticks if LLM ignored instructions
+        rawMarkdown = rawMarkdown
+            .replace(/```markdown/g, "")
+            .replace(/```/g, "")
+            .trim();
+        if (!rawMarkdown.startsWith("#")) {
+            rawMarkdown = `# Pika Architectural Rules\n\n${rawMarkdown}`;
+        }
+        fs.writeFileSync(rulesPath, rawMarkdown, "utf-8");
+        logger.success(".pika-rules.md generated successfully!");
+        logger.info(`Location: ${chalk.dim(rulesPath)}`);
+        logger.dim("The local Pika Review engine will now enforce these rules during future scans!");
+    }
+    catch (error) {
+        logger.error(`Failed to generate rules: ${error.message}`);
+    }
+}

package/dist/cmd/scan.js

@@ -1,5 +1,6 @@
 import prompts from "prompts";
 import chalk from "chalk";
+import { execSync } from "child_process";
 import { runScan, getDiffFiles, listProjectFiles } from "../core/scanner.js";
 import { logger } from "../utils/logger.js";
 /**
@@ -10,55 +11,102 @@ export async function scanAction(files, options) {
     const target = options.unstaged ? "unstaged" : "staged";
     const isCI = !!options.ci;
     let targets = files.length > 0 ? files : undefined;
-    // Interactive Discovery: If no files provided and no git changes, ask the user
-    if (!targets && !isCI) {
-        const gitChanges = getDiffFiles(target);
-        if (gitChanges.length === 0) {
-            logger.info("No git changes detected. Entering interactive selection mode...");
-            const allFiles = listProjectFiles();
-            if (allFiles.length > 0) {
-                const selection = await prompts({
-                    type: "multiselect",
-                    name: "files",
-                    message: "Select files to analyze (Space to select, Enter to confirm):",
-                    choices: allFiles.map(f => ({ title: f, value: f })),
-                    hint: "- Space to select. Return to submit"
-                });
-                if (selection.files && selection.files.length > 0) {
-                    targets = selection.files;
-                }
+    // Interactive Discovery: If requested or if no files provided and no git changes
+    if (!isCI && (options.interactive || (!targets && getDiffFiles(target).length === 0))) {
+        logger.info("Entering interactive selection mode...");
+        const allFiles = listProjectFiles();
+        if (allFiles.length > 0) {
+            const selection = await prompts({
+                type: "multiselect",
+                name: "files",
+                message: "Select files to analyze (Space to select, Enter to confirm):",
+                choices: allFiles.map(f => ({ title: f, value: f })),
+                hint: "- Space to select. Return to submit",
+                instructions: false
+            });
+            if (selection.files && selection.files.length > 0) {
+                targets = selection.files;
+            }
+            else if (options.interactive) {
+                logger.warn("No files selected. Exiting.");
+                return;
             }
         }
     }
-    let reports = await runScan(target, isCI, targets);
-    if (!reports || reports.length === 0) {
+    const { markdownReports, htmlReport, findings } = await runScan(target, isCI, targets);
+    if (!markdownReports || markdownReports.length === 0) {
         if (!isCI) {
-            logger.success("Scan complete. No critical architectural anomalies detected.");
-            logger.dim("Try scanning with '--unstaged' if you have uncommitted changes.");
+            console.log(`\n  ${chalk.green("✓")}  ${chalk.bold("Scan complete. No architectural anomalies or security risks detected.")}`);
+            console.log(`     ${chalk.dim("Try scanning with '--unstaged' if you have unstaged changes.")}\n`);
         }
         return;
     }
     if (!isCI) {
-        console.log(chalk.bold(`\n${"=".repeat(50)}`));
-        logger.warn(`ANALYTICAL REPORT READY`);
-        logger.dim(`${reports.length} file(s) require your immediate attention.\n`);
+        // Count findings by severity
+        let criticalCount = 0;
+        let highCount = 0;
+        let mediumCount = 0;
+        let lowCount = 0;
+        let totalIssues = 0;
+        findings.forEach((f) => {
+            totalIssues += f.reviews.length;
+            f.reviews.forEach((r) => {
+                if (r.severity === "Critical")
+                    criticalCount++;
+                else if (r.severity === "High")
+                    highCount++;
+                else if (r.severity === "Medium")
+                    mediumCount++;
+                else if (r.severity === "Low")
+                    lowCount++;
+            });
+        });
+        // Sleek summary box
+        console.log(`\n  ${chalk.cyan.bold("◆  Scan Completed Successfully")}`);
+        console.log(`     ${chalk.dim("─".repeat(34))}`);
+        console.log(`     ${chalk.bold("Files Audited:")}   ${findings.length}`);
+        console.log(`     ${chalk.bold("Total Findings:")}  ${totalIssues}`);
+        if (totalIssues > 0) {
+            console.log(`\n     ${chalk.bold("Severity Breakdown:")}`);
+            if (criticalCount > 0)
+                console.log(`       🚨 ${chalk.red.bold(criticalCount)} Critical`);
+            if (highCount > 0)
+                console.log(`       🔥 ${chalk.yellow.bold(highCount)} High`);
+            if (mediumCount > 0)
+                console.log(`       ⚠️ ${chalk.blue.bold(mediumCount)} Medium`);
+            if (lowCount > 0)
+                console.log(`       📝 ${chalk.gray.bold(lowCount)} Low`);
+        }
+        console.log(`\n     ${chalk.bold("Obsidian Report:")}  ${chalk.cyan.underline(`file://${htmlReport}`)}\n`);
         const response = await prompts({
             type: "select",
             name: "action",
-            message: "What is your next step?",
+            message: "Choose post-scan action:",
             choices: [
-                { title: "📂 Open generated Markdown reports", value: "view" },
+                { title: "✨ Open Interactive HTML Dashboard (Recommended)", value: "html" },
+                { title: "📂 List generated Markdown file paths", value: "markdown" },
                 { title: "🛑 Exit and start refactoring", value: "exit" },
             ],
             initial: 0,
         });
-        if (response.action === "view") {
-            logger.info("\nGenerated Artifacts:");
-            reports.forEach((r) => {
+        if (response.action === "html") {
+            console.log(`\n  ${chalk.cyan("→")} Opening interactive report in browser...`);
+            try {
+                const command = process.platform === "win32" ? "start" : process.platform === "darwin" ? "open" : "xdg-open";
+                execSync(`${command} "${htmlReport}"`);
+            }
+            catch (e) {
+                console.log(`     ${chalk.red("✖")} Failed to open browser automatically.`);
+                console.log(`     ${chalk.dim(`Manually open: file://${htmlReport}`)}`);
+            }
+        }
+        else if (response.action === "markdown") {
+            console.log(`\n  ${chalk.bold("Generated Markdown Artifacts:")}`);
+            markdownReports.forEach((r) => {
                 const fileName = r.split("/").pop();
-                console.log(` ${chalk.cyan("→")} ${chalk.bold(fileName)} ${chalk.dim(`(${r})`)}`);
+                console.log(`    ${chalk.cyan("•")} ${chalk.bold(fileName)} ${chalk.dim(`(file://${r})`)}`);
             });
-            console.log(chalk.dim("\nTip: Use 'cat' or a Markdown viewer to read the findings."));
+            console.log(`\n  ${chalk.dim("Tip: Click any file:// link above to open directly in your editor.")}\n`);
         }
     }
 }

package/dist/cmd/stats.js

@@ -0,0 +1,55 @@
+import fs from "fs";
+import path from "path";
+import chalk from "chalk";
+import { logger } from "../utils/logger.js";
+/**
+ * Stats Action: Displays architectural health trends.
+ */
+export async function statsAction() {
+    const historyPath = path.join(process.cwd(), ".pika-reports", "history.json");
+    if (!fs.existsSync(historyPath)) {
+        logger.error("No scan history found. Run some scans first!");
+        return;
+    }
+    try {
+        const history = JSON.parse(fs.readFileSync(historyPath, "utf-8"));
+        if (history.length === 0) {
+            logger.error("Scan history is empty.");
+            return;
+        }
+        console.log(`\n${chalk.bgBlue.white.bold(" PIKA ARCHITECTURAL HEALTH DASHBOARD ")}\n`);
+        console.log(`${chalk.dim("Tracking trends across the last " + history.length + " scans")}\n`);
+        // Table Header
+        console.log(chalk.bold("Date                Files   Issues   Critical   High   Medium   Low"));
+        console.log(chalk.dim("-".repeat(75)));
+        history.slice(-10).forEach((run) => {
+            const date = new Date(run.timestamp).toLocaleString().padEnd(20);
+            const files = String(run.totalFiles).padEnd(8);
+            const issues = String(run.totalIssues).padEnd(9);
+            const crit = chalk.red(String(run.severityCounts.Critical || 0).padEnd(11));
+            const high = chalk.hex("#fb923c")(String(run.severityCounts.High || 0).padEnd(7));
+            const med = chalk.yellow(String(run.severityCounts.Medium || 0).padEnd(9));
+            const low = chalk.green(String(run.severityCounts.Low || 0).padEnd(6));
+            console.log(`${date}${files}${issues}${crit}${high}${med}${low}`);
+        });
+        // Summary Insights
+        const latest = history[history.length - 1];
+        const previous = history.length > 1 ? history[history.length - 2] : null;
+        console.log(`\n${chalk.bold("Latest Insight:")}`);
+        if (previous) {
+            const diff = latest.totalIssues - previous.totalIssues;
+            const direction = diff > 0 ? chalk.red("increased") : diff < 0 ? chalk.green("decreased") : "remained stable";
+            console.log(`- Issue count ${direction} by ${Math.abs(diff)} since the last scan.`);
+        }
+        const critTotal = latest.severityCounts.Critical || 0;
+        if (critTotal > 0) {
+            console.log(`- ${chalk.red("🚨 Critical Action Required:")} ${critTotal} architectural risks detected.`);
+        }
+        else {
+            console.log(`- ${chalk.green("✅ Zero Critical Issues:")} Maintain this standard!`);
+        }
+    }
+    catch (e) {
+        logger.error("Failed to parse history data.");
+    }
+}