install-guard 1.1.1 → 1.1.2

package/src/format.js

@@ -1,106 +1,127 @@
 import chalk from "chalk";
 
-const SEPARATOR = chalk.gray("━".repeat(50));
-const THIN_SEP = chalk.gray("─".repeat(50));
+const W = 58;
+const SEPARATOR = chalk.gray("━".repeat(W));
+const THIN_SEP = chalk.gray("─".repeat(W));
 
 function riskBar(score) {
   const filled = score;
   const empty = 10 - score;
   const color =
-    score <= 3 ? chalk.green : score <= 6 ? chalk.yellow : chalk.red;
+    score <= 2 ? chalk.green : score <= 5 ? chalk.yellow : score <= 7 ? chalk.red : chalk.redBright;
   return color("█".repeat(filled)) + chalk.gray("░".repeat(empty));
 }
 
-function riskLabel(level) {
-  switch (level) {
-    case "low":
-      return chalk.green.bold("✅ Low Risk");
-    case "medium":
-      return chalk.yellow.bold("⚠  Medium Risk");
-    case "high":
-      return chalk.red.bold("🚨 High Risk");
+function riskLabel(label) {
+  switch (label) {
+    case "LOW":
+      return chalk.green.bold("✅ LOW");
+    case "MEDIUM":
+      return chalk.yellow.bold("⚠  MEDIUM");
+    case "HIGH":
+      return chalk.red.bold("🚨 HIGH");
+    case "CRITICAL":
+      return chalk.redBright.bold("💀 CRITICAL");
+    default:
+      return label;
   }
 }
 
-function checkIcon(status) {
-  switch (status) {
-    case "pass":
-      return chalk.green("✔");
-    case "warn":
-      return chalk.yellow("⚠");
-    case "fail":
+function severityIcon(severity) {
+  switch (severity) {
+    case "critical":
+      return chalk.redBright("✘");
+    case "high":
       return chalk.red("✘");
+    case "medium":
+      return chalk.yellow("⚠");
+    case "info":
+      return chalk.green("✔");
+    default:
+      return chalk.gray("·");
+  }
+}
+
+function severityColor(severity) {
+  switch (severity) {
+    case "critical":
+      return chalk.redBright;
+    case "high":
+      return chalk.red;
+    case "medium":
+      return chalk.yellow;
+    case "info":
+      return chalk.green;
+    default:
+      return chalk.white;
   }
 }
 
 function timeAgo(dateStr) {
   if (!dateStr) return "Unknown";
   const diff = Date.now() - new Date(dateStr).getTime();
-  const days = Math.floor(diff / (1000 * 60 * 60 * 24));
-  if (days < 1) return "today";
+  const hours = Math.floor(diff / (1000 * 60 * 60));
+  if (hours < 1) return "just now";
+  if (hours < 24) return `${hours} hour(s) ago`;
+  const days = Math.floor(hours / 24);
   if (days === 1) return "1 day ago";
   if (days < 30) return `${days} days ago`;
   const months = Math.floor(days / 30);
-  if (months === 1) return "1 month ago";
-  if (months < 12) return `${months} months ago`;
+  if (months < 12) return `${months} month(s) ago`;
   const years = Math.floor(days / 365);
-  if (years === 1) return "1 year ago";
-  return `${years} years ago`;
+  return `${years} year(s) ago`;
 }
 
-export function formatAnalysis(data, result) {
+/**
+ * Formats the full pipeline result for CLI display.
+ */
+export function formatPipelineResult(result) {
   const lines = [];
 
   lines.push("");
   lines.push(SEPARATOR);
   lines.push(
-    chalk.bold(`  📦 ${data.name} `) + chalk.gray(`v${data.version}`)
+    chalk.bold(`  📦 ${result.package} `) + chalk.gray(`v${result.version}`)
   );
-  if (data.description) {
-    lines.push(chalk.gray(`  ${data.description.slice(0, 70)}`));
+  if (result.description) {
+    lines.push(chalk.gray(`  ${result.description.slice(0, W - 4)}`));
   }
   lines.push(SEPARATOR);
 
-  // Risk score
+  // ── Risk Score ──────────────────────────────
   lines.push("");
   lines.push(
-    `  Risk Score: ${chalk.bold(`${result.score}/10`)}  ${riskLabel(result.level)}`
+    `  Risk Level: ${riskLabel(result.label)}  ${chalk.bold(`(${result.score}/10)`)}`
   );
   lines.push(`  ${riskBar(result.score)}`);
 
   lines.push("");
   lines.push(THIN_SEP);
 
-  // Package info
+  // ── Package Info ────────────────────────────
   lines.push("");
   lines.push(chalk.bold("  📊 Package Info"));
   lines.push("");
 
   const info = [
-    ["Downloads (weekly)", data.downloads.toLocaleString()],
-    ["Maintainers", String(data.maintainers.length)],
-    [
-      "License",
-      typeof data.license === "string"
-        ? data.license
-        : data.license?.type || "Unknown",
-    ],
-    ["Last Published", timeAgo(data.lastPublished)],
-    ["Dependencies", String(data.dependencies)],
-    ["Versions", String(data.totalVersions)],
+    ["Downloads (weekly)", result.downloads.toLocaleString()],
+    ["Maintainers", result.maintainers.join(", ") || "None"],
+    ["License", typeof result.license === "string" ? result.license : result.license?.type || "Unknown"],
+    ["Published", timeAgo(result.publishedAt)],
+    ["Dependencies", String(result.dependencyCount)],
+    ["Total Versions", String(result.totalVersions)],
+    ["Repository", result.repository ? "✔" : "✘ None"],
   ];
 
   for (const [label, value] of info) {
-    lines.push(
-      `  ${chalk.gray(label.padEnd(22))} ${chalk.white(value)}`
-    );
+    lines.push(`  ${chalk.gray(label.padEnd(22))} ${chalk.white(value)}`);
   }
 
-  if (data.deprecated) {
+  if (result.deprecated) {
     lines.push("");
     lines.push(
       chalk.red.bold(
-        `  ⚠ DEPRECATED: ${typeof data.deprecated === "string" ? data.deprecated : "This package is deprecated"}`
+        `  ⚠ DEPRECATED: ${typeof result.deprecated === "string" ? result.deprecated : "This package is deprecated"}`
       )
     );
   }
@@ -108,20 +129,51 @@ export function formatAnalysis(data, result) {
   lines.push("");
   lines.push(THIN_SEP);
 
-  // Security checks
+  // ── Findings ────────────────────────────────
   lines.push("");
-  lines.push(chalk.bold("  🔍 Security Checks"));
+  lines.push(chalk.bold("  🔍 Findings"));
   lines.push("");
 
-  for (const check of result.checks) {
-    const icon = checkIcon(check.status);
-    const detail =
-      check.status === "pass"
-        ? chalk.green(check.detail)
-        : check.status === "warn"
-          ? chalk.yellow(check.detail)
-          : chalk.red(check.detail);
-    lines.push(`  ${icon} ${chalk.gray(check.label + ":")} ${detail}`);
+  // Group by severity
+  const critical = result.findings.filter((f) => f.severity === "critical");
+  const high = result.findings.filter((f) => f.severity === "high");
+  const medium = result.findings.filter((f) => f.severity === "medium");
+  const info2 = result.findings.filter((f) => f.severity === "info");
+
+  for (const group of [critical, high, medium, info2]) {
+    for (const f of group) {
+      const icon = severityIcon(f.severity);
+      const color = severityColor(f.severity);
+      lines.push(`  ${icon} ${color(f.message)}`);
+    }
+  }
+
+  // ── Recommendation ──────────────────────────
+  if (result.recommendation) {
+    lines.push("");
+    lines.push(THIN_SEP);
+    lines.push("");
+    lines.push(chalk.bold("  💡 Recommendation"));
+    lines.push("");
+    if (result.label === "CRITICAL" || result.label === "HIGH") {
+      lines.push(chalk.red(`  ⛔ Avoid installing ${result.package}@${result.version}`));
+    }
+    lines.push(
+      chalk.green(
+        `  ✔ Safe alternative: ${result.package}@${chalk.bold(result.recommendation.version)}`
+      )
+    );
+    lines.push(
+      chalk.gray(`    ${result.recommendation.reason}`)
+    );
+  } else if (result.label === "CRITICAL" || result.label === "HIGH") {
+    lines.push("");
+    lines.push(THIN_SEP);
+    lines.push("");
+    lines.push(chalk.bold("  💡 Recommendation"));
+    lines.push("");
+    lines.push(chalk.red(`  ⛔ Avoid installing this version`));
+    lines.push(chalk.gray("    No safe alternative version found"));
   }
 
   lines.push("");
@@ -131,10 +183,13 @@ export function formatAnalysis(data, result) {
   return lines.join("\n");
 }
 
+/**
+ * Formats a summary table for scan results.
+ */
 export function formatScanSummary(results) {
   const lines = [];
 
-  results.sort((a, b) => b.result.score - a.result.score);
+  results.sort((a, b) => b.score - a.score);
 
   lines.push("");
   lines.push(SEPARATOR);
@@ -142,57 +197,58 @@ export function formatScanSummary(results) {
   lines.push(SEPARATOR);
   lines.push("");
 
-  const nameWidth = Math.max(
-    20,
-    ...results.map((r) => r.data.name.length + 2)
-  );
+  const nameWidth = Math.max(20, ...results.map((r) => r.package.length + 2));
 
   lines.push(
     chalk.gray(
       "  " +
         "Package".padEnd(nameWidth) +
-        "Risk".padEnd(12) +
-        "Status"
+        "Score".padEnd(10) +
+        "Level"
     )
   );
-  lines.push(chalk.gray("  " + "─".repeat(nameWidth + 26)));
-
-  for (const { data, result } of results) {
-    const name = data.name.padEnd(nameWidth);
-    const risk = `${result.score}/10`.padEnd(12);
-    let status;
-    switch (result.level) {
-      case "low":
-        status = chalk.green("✅ Safe");
+  lines.push(chalk.gray("  " + "─".repeat(nameWidth + 24)));
+
+  for (const r of results) {
+    const name = r.package.padEnd(nameWidth);
+    const score = `${r.score}/10`.padEnd(10);
+    let level;
+    switch (r.label) {
+      case "LOW":
+        level = chalk.green("✅ Low");
+        break;
+      case "MEDIUM":
+        level = chalk.yellow("⚠  Medium");
         break;
-      case "medium":
-        status = chalk.yellow("⚠  Medium");
+      case "HIGH":
+        level = chalk.red("🚨 High");
         break;
-      case "high":
-        status = chalk.red("🚨 High Risk");
+      case "CRITICAL":
+        level = chalk.redBright("💀 Critical");
         break;
     }
 
     const colorFn =
-      result.level === "high"
+      r.label === "CRITICAL" || r.label === "HIGH"
         ? chalk.red
-        : result.level === "medium"
+        : r.label === "MEDIUM"
           ? chalk.yellow
           : chalk.white;
-    lines.push(`  ${colorFn(name)}${risk}${status}`);
+    lines.push(`  ${colorFn(name)}${score}${level}`);
   }
 
   lines.push("");
   lines.push(THIN_SEP);
 
-  const safe = results.filter((r) => r.result.level === "low").length;
-  const medium = results.filter(
-    (r) => r.result.level === "medium"
-  ).length;
-  const high = results.filter((r) => r.result.level === "high").length;
+  const low = results.filter((r) => r.label === "LOW").length;
+  const med = results.filter((r) => r.label === "MEDIUM").length;
+  const high = results.filter((r) => r.label === "HIGH").length;
+  const crit = results.filter((r) => r.label === "CRITICAL").length;
 
   lines.push(
-    `  ${chalk.bold("Summary:")} ${chalk.green(`${safe} safe`)} · ${chalk.yellow(`${medium} medium`)} · ${chalk.red(`${high} high risk`)}`
+    `  ${chalk.bold("Total:")} ${results.length} packages  ` +
+    `${chalk.green(`${low} low`)} · ${chalk.yellow(`${med} medium`)} · ` +
+    `${chalk.red(`${high} high`)} · ${chalk.redBright(`${crit} critical`)}`
   );
   lines.push("");
   lines.push(SEPARATOR);

package/src/index.js

@@ -1,5 +1,5 @@
 import { analyze } from "./analyze.js";
 
-export async function analyzePackage(pkg) {
-    return await analyze(pkg);
+export async function analyzePackage(pkg, version, opts) {
+    return await analyze(pkg, version, opts);
 }

package/src/install.js

@@ -2,9 +2,8 @@ import { execFileSync } from "child_process";
 import readline from "readline";
 import chalk from "chalk";
 import ora from "ora";
-import { getPackageData } from "./npm.js";
-import { calculateRisk } from "./score.js";
-import { formatAnalysis } from "./format.js";
+import { runPipeline } from "./services/pipeline.js";
+import { formatPipelineResult } from "./format.js";
 
 const VALID_PKG_NAME = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*(@[a-z0-9._^~>=<|-]+)?$/i;
 
@@ -30,27 +29,34 @@ export async function analyzeAndPrompt(pkgName) {
 
     const spinner = ora(`Analyzing ${pkgName}...`).start();
 
-    let data, result;
+    let result;
     try {
-        data = await getPackageData(pkgName);
-        result = calculateRisk(data);
+        result = await runPipeline(pkgName);
         spinner.stop();
     } catch (err) {
         spinner.fail(`Failed to analyze "${pkgName}": ${err.message}`);
         return;
     }
 
-    console.log(formatAnalysis(data, result));
+    console.log(formatPipelineResult(result));
 
-    if (result.level === "high") {
+    if (result.label === "CRITICAL") {
         const ans = await askQuestion(
-            chalk.red.bold("  ⚠ High risk package. Continue install? (y/n): ")
+            chalk.redBright.bold("  💀 CRITICAL risk. Are you absolutely sure? (y/n): ")
         );
         if (ans.toLowerCase() !== "y") {
             console.log(chalk.yellow("\n  Installation aborted.\n"));
             return;
         }
-    } else if (result.level === "medium") {
+    } else if (result.label === "HIGH") {
+        const ans = await askQuestion(
+            chalk.red.bold("  🚨 HIGH risk package. Continue install? (y/n): ")
+        );
+        if (ans.toLowerCase() !== "y") {
+            console.log(chalk.yellow("\n  Installation aborted.\n"));
+            return;
+        }
+    } else if (result.label === "MEDIUM") {
         const ans = await askQuestion(
             chalk.yellow("  ⚠ Medium risk. Continue install? (y/n): ")
         );

package/src/scan.js

@@ -2,11 +2,10 @@ import fs from "fs";
 import path from "path";
 import chalk from "chalk";
 import ora from "ora";
-import { getPackageData } from "./npm.js";
-import { calculateRisk } from "./score.js";
-import { formatAnalysis, formatScanSummary } from "./format.js";
+import { runPipeline } from "./services/pipeline.js";
+import { formatPipelineResult, formatScanSummary } from "./format.js";
 
-export async function scanProject({ verbose } = {}) {
+export async function scanProject({ verbose, json, skipGithub } = {}) {
     const pkgPath = path.resolve("package.json");
 
     if (!fs.existsSync(pkgPath)) {
@@ -36,18 +35,17 @@ export async function scanProject({ verbose } = {}) {
     for (const dep of depNames) {
         spinner.start(`Analyzing ${dep}...`);
         try {
-            const data = await getPackageData(dep);
-            const result = calculateRisk(data);
-            results.push({ data, result });
+            const result = await runPipeline(dep, undefined, { skipGithub: skipGithub !== false });
+            results.push(result);
 
             if (verbose) {
                 spinner.stop();
-                console.log(formatAnalysis(data, result));
+                console.log(formatPipelineResult(result));
             } else {
                 const icon =
-                    result.level === "high"
+                    result.label === "CRITICAL" || result.label === "HIGH"
                         ? "🚨"
-                        : result.level === "medium"
+                        : result.label === "MEDIUM"
                           ? "⚠"
                           : "✅";
                 spinner.succeed(
@@ -59,5 +57,9 @@ export async function scanProject({ verbose } = {}) {
         }
     }
 
-    console.log(formatScanSummary(results));
+    if (json) {
+        console.log(JSON.stringify(results, null, 2));
+    } else {
+        console.log(formatScanSummary(results));
+    }
 }

package/src/services/pipeline.js

@@ -0,0 +1,105 @@
+import { buildContext } from "../utils/registry.js";
+import {
+  checkRecentPublish,
+  checkDependencyDiff,
+  checkScripts,
+  checkTyposquat,
+  checkMaintainers,
+  checkLicense,
+  checkGithubVerify,
+  checkDeprecation,
+} from "../checks/index.js";
+import { computeScore } from "./scorer.js";
+
+/**
+ * Runs the full detection pipeline on a package+version.
+ * Returns structured results consumable by CLI or JSON output.
+ */
+export async function runPipeline(packageName, version, opts = {}) {
+  const ctx = await buildContext(packageName, version);
+
+  // Run sync checks immediately
+  const syncResults = [
+    checkRecentPublish(ctx),
+    checkScripts(ctx),
+    checkTyposquat(ctx),
+    checkMaintainers(ctx),
+    checkLicense(ctx),
+    checkDeprecation(ctx),
+  ];
+
+  // Run async checks in parallel
+  const asyncChecks = [checkDependencyDiff(ctx)];
+
+  if (!opts.skipGithub) {
+    asyncChecks.push(checkGithubVerify(ctx));
+  }
+
+  const asyncResults = await Promise.all(asyncChecks);
+  const allChecks = [...syncResults, ...asyncResults];
+
+  const { score, label, findings } = computeScore(allChecks);
+
+  // Find a safe version recommendation
+  const safeVersion = findSafeVersion(ctx, score);
+
+  return {
+    package: ctx.name,
+    version: ctx.version,
+    previousVersion: ctx.previousVersion,
+    description: ctx.description,
+    downloads: ctx.downloads,
+    maintainers: ctx.currentMaintainers.map((m) => m.name || m.email),
+    license: ctx.license,
+    publishedAt: ctx.publishedAt,
+    repository: ctx.repository,
+    deprecated: ctx.deprecated,
+    totalVersions: ctx.totalVersions,
+    dependencyCount: Object.keys(ctx.dependencies).length,
+
+    score,
+    label,
+    findings,
+    checks: allChecks,
+
+    recommendation: safeVersion,
+  };
+}
+
+/**
+ * Suggests the latest safe version — one that is older, with no install scripts,
+ * and published more than 7 days ago.
+ */
+function findSafeVersion(ctx, currentScore) {
+  if (currentScore <= 3) return null; // current version is fine
+
+  const registry = ctx._registry;
+  const timeData = registry.time || {};
+  const versions = ctx.allVersions.slice().reverse(); // newest first
+  const sevenDaysAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;
+
+  for (const v of versions) {
+    if (v === ctx.version) continue;
+
+    const vData = registry.versions[v];
+    if (!vData) continue;
+    if (vData.deprecated) continue;
+    if (
+      vData.scripts?.postinstall ||
+      vData.scripts?.preinstall ||
+      vData.scripts?.install
+    )
+      continue;
+
+    const publishTime = new Date(timeData[v] || 0).getTime();
+    if (publishTime > sevenDaysAgo) continue;
+
+    return {
+      version: v,
+      publishedAt: timeData[v],
+      reason: "No install scripts, published > 7 days ago",
+    };
+  }
+
+  return null;
+}

package/src/services/scorer.js

@@ -0,0 +1,36 @@
+/**
+ * Weighted risk scorer.
+ * Takes raw check results and computes a normalized 0-10 score with label.
+ */
+
+// Max raw score (theoretical) — used to normalize
+const MAX_RAW = 50;
+
+export function computeScore(checkResults) {
+  let rawScore = 0;
+  const allFindings = [];
+  let hasCritical = false;
+
+  for (const check of checkResults) {
+    for (const f of check.findings) {
+      allFindings.push({ ...f, checkId: check.id });
+      rawScore += f.score;
+      if (f.severity === "critical") hasCritical = true;
+    }
+  }
+
+  // Normalize to 0-10
+  let score = Math.round((rawScore / MAX_RAW) * 10);
+  score = Math.max(0, Math.min(10, score));
+
+  // Critical findings floor at 7
+  if (hasCritical && score < 7) score = 7;
+
+  let label;
+  if (score <= 2) label = "LOW";
+  else if (score <= 5) label = "MEDIUM";
+  else if (score <= 7) label = "HIGH";
+  else label = "CRITICAL";
+
+  return { score, label, rawScore, findings: allFindings };
+}

package/src/utils/cache.js

@@ -0,0 +1,44 @@
+import fs from "fs";
+import path from "path";
+import { createHash } from "crypto";
+
+const CACHE_DIR = path.join(
+  process.env.HOME || process.env.USERPROFILE || "/tmp",
+  ".install-guard-cache"
+);
+const TTL_MS = 15 * 60 * 1000; // 15 minutes
+
+function ensureDir() {
+  if (!fs.existsSync(CACHE_DIR)) {
+    fs.mkdirSync(CACHE_DIR, { recursive: true });
+  }
+}
+
+function keyToFile(key) {
+  const hash = createHash("sha256").update(key).digest("hex").slice(0, 16);
+  return path.join(CACHE_DIR, `${hash}.json`);
+}
+
+export function getCached(key) {
+  try {
+    const file = keyToFile(key);
+    if (!fs.existsSync(file)) return null;
+    const raw = JSON.parse(fs.readFileSync(file, "utf-8"));
+    if (Date.now() - raw.ts > TTL_MS) {
+      fs.unlinkSync(file);
+      return null;
+    }
+    return raw.data;
+  } catch {
+    return null;
+  }
+}
+
+export function setCache(key, data) {
+  try {
+    ensureDir();
+    fs.writeFileSync(keyToFile(key), JSON.stringify({ ts: Date.now(), data }));
+  } catch {
+    // cache write failures are non-fatal
+  }
+}