proj-pulse 1.0.0

package/Readme.md

@@ -0,0 +1,95 @@
+# 🩺 proj-pulse
+
+> A health checkup for your project — one command to catch what's quietly rotting.
+
+```bash
+npx proj-pulse
+```
+
+---
+
+## What it checks
+
+| Check | What it finds |
+|---|---|
+| 📦 **Unused Dependencies** | npm packages installed but never imported |
+| 🔐 **Env Var Health** | Missing keys, weak secrets, .env not in .gitignore |
+| 📝 **Stale TODOs** | TODO/FIXME comments older than 30 days |
+| 📁 **Large Files** | Source files over 500 KB that shouldn't be in git |
+| 🛡️ **.gitignore Safety** | Missing critical entries (node_modules, .env, etc.) |
+
+---
+
+## Install
+
+```bash
+# Run instantly with npx (no install needed)
+npx proj-pulse
+
+# Or install globally
+npm install -g proj-pulse
+proj-pulse
+
+# Or scan a specific folder
+proj-pulse /path/to/my/project
+```
+
+---
+
+## Example Output
+
+```
+  🩺 proj-pulse   Project Health Check
+
+  Scanning: /Users/dev/my-app
+
+  ✔  Unused Dependencies
+     All 12 dependencies appear to be used.
+
+  ⚠  Env Var Health
+     2 env issues detected:
+       · .env is NOT listed in .gitignore — risk of leaking secrets
+       · Line 4: DB_PASSWORD — weak/short secret
+     → Fix: Review your .env file and update insecure or missing values.
+
+  ✖  Stale TODOs
+     5 TODO/FIXME found, 3 older than 30 days:
+       · [TODO] src/api/auth.js:42 — "refactor token handling" (87d old)
+       · [FIXME] src/utils/parser.js:11 — "edge case for empty array" (63d old)
+       · [HACK] src/db/index.js:7 — "replace with proper pool" (45d old)
+     → Fix: Address or remove comments older than 30 days.
+
+  ✔  Large Files
+     No unexpectedly large source files found (threshold: 500 KB).
+
+  ⚠  .gitignore Safety
+     1 .gitignore issue found:
+       · Missing: ".env"  (secrets / API keys)
+     → Fix: Add missing entries to your .gitignore file.
+
+──────────────────────────────────────────────────
+  Summary
+
+  ✔ Passed   2/5
+  ⚠ Warnings 2/5
+  ✖ Failed   1/5
+
+  Health Score: 40%
+──────────────────────────────────────────────────
+```
+
+---
+
+## Roadmap
+
+- [ ] `--fix` flag to auto-resolve safe issues
+- [ ] JSON output for CI integration (`--json`)
+- [ ] Config file (`.proj-pulse.json`) for custom thresholds
+- [ ] Git history analysis for churn / hotspot detection
+- [ ] Dead code detection
+
+---
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+ 
+"use strict";
+ 
+const path = require("path");
+const { runPulse } = require("../src/index");
+ 
+const projectRoot = process.argv[2]
+  ? path.resolve(process.argv[2])
+  : process.cwd();
+ 
+runPulse(projectRoot);
+ 

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "proj-pulse",
+  "version": "1.0.0",
+  "description": "A health checkup for your project — dead deps, stale TODOs, unused env vars, and more.",
+  "main": "src/index.js",
+  "bin": {
+    "proj-pulse": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js",
+    "test": "node bin/cli.js"
+  },
+  "keywords": [
+    "developer-tools",
+    "cli",
+    "health-check",
+    "project",
+    "dependencies",
+    "audit"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "glob": "^8.1.0",
+    "ora": "^5.4.1"
+  }
+}

package/src/checks/envVars.js

@@ -0,0 +1,84 @@
+"use strict";
+const fs   = require("fs");
+const path = require("path");
+
+const INSECURE_PATTERNS = [
+  { pattern: /^(password|pass|pwd|secret|key|token|api_key)=.{1,7}$/i, label: "weak/short secret" },
+  { pattern: /=password$/i,   label: "default password value" },
+  { pattern: /=secret$/i,     label: "default secret value" },
+  { pattern: /=changeme$/i,   label: "placeholder value (changeme)" },
+  { pattern: /=12345/,        label: "weak numeric value" },
+  { pattern: /=true$/i,       label: "boolean flag — confirm intentional" },
+];
+
+async function checkEnvVars(projectRoot) {
+  const envPath       = path.join(projectRoot, ".env");
+  const examplePath   = path.join(projectRoot, ".env.example");
+  const templatePath  = path.join(projectRoot, ".env.template");
+
+  const hasEnv     = fs.existsSync(envPath);
+  const hasExample = fs.existsSync(examplePath) || fs.existsSync(templatePath);
+
+  if (!hasEnv && !hasExample) {
+    return { status: "skip", message: "No .env or .env.example file found." };
+  }
+
+  const issues = [];
+
+  // Check .env is NOT committed (check .gitignore)
+  const gitignorePath = path.join(projectRoot, ".gitignore");
+  if (hasEnv && fs.existsSync(gitignorePath)) {
+    const gi = fs.readFileSync(gitignorePath, "utf8");
+    if (!gi.includes(".env")) {
+      issues.push(".env is NOT listed in .gitignore — risk of leaking secrets");
+    }
+  }
+
+  // Parse .env and check for insecure patterns
+  if (hasEnv) {
+    const lines = fs.readFileSync(envPath, "utf8").split("\n");
+    lines.forEach((line, i) => {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) return;
+
+      INSECURE_PATTERNS.forEach(({ pattern, label }) => {
+        if (pattern.test(trimmed)) {
+          const key = trimmed.split("=")[0];
+          issues.push(`Line ${i + 1}: ${key} — ${label}`);
+        }
+      });
+    });
+
+    // Cross-check .env vs .env.example for missing keys
+    if (hasExample) {
+      const exPath = fs.existsSync(examplePath) ? examplePath : templatePath;
+      const exampleKeys = fs.readFileSync(exPath, "utf8")
+        .split("\n")
+        .filter(l => l.includes("=") && !l.startsWith("#"))
+        .map(l => l.split("=")[0].trim());
+
+      const envKeys = fs.readFileSync(envPath, "utf8")
+        .split("\n")
+        .filter(l => l.includes("=") && !l.startsWith("#"))
+        .map(l => l.split("=")[0].trim());
+
+      const missing = exampleKeys.filter(k => !envKeys.includes(k));
+      if (missing.length > 0) {
+        missing.forEach(k => issues.push(`Missing key from .env.example: ${k}`));
+      }
+    }
+  }
+
+  if (issues.length === 0) {
+    return { status: "pass", message: ".env looks healthy — no obvious issues found." };
+  }
+
+  return {
+    status: "warn",
+    message: `${issues.length} env ${issues.length === 1 ? "issue" : "issues"} detected:`,
+    items: issues,
+    fix: "Review your .env file and update insecure or missing values.",
+  };
+}
+
+module.exports = checkEnvVars;

package/src/checks/gitignore.js

@@ -0,0 +1,71 @@
+"use strict";
+
+const fs   = require("fs");
+const path = require("path");
+
+const MUST_IGNORE = [
+  { entry: ".env",           reason: "secrets / API keys" },
+  { entry: "node_modules",   reason: "dependencies (bloats repo)" },
+  { entry: ".DS_Store",      reason: "macOS metadata noise" },
+  { entry: "*.log",          reason: "log files" },
+  { entry: "dist",           reason: "build output" },
+  { entry: "coverage",       reason: "test coverage output" },
+];
+
+const SENSITIVE_FILES = [
+  ".env", ".env.local", ".env.production",
+  "*.pem", "*.key", "*.p12", "*.pfx",
+  "secrets.json", "credentials.json",
+];
+
+async function checkGitignore(projectRoot) {
+  const gitignorePath = path.join(projectRoot, ".gitignore");
+
+  if (!fs.existsSync(gitignorePath)) {
+    return {
+      status: "fail",
+      message: "No .gitignore file found! This is risky for any project.",
+      fix: "Run: npx gitignore node  (or create one manually)",
+    };
+  }
+
+  const content = fs.readFileSync(gitignorePath, "utf8");
+  const lines   = content.split("\n").map(l => l.trim()).filter(Boolean);
+
+  const isIgnored = (entry) =>
+    lines.some(l => l === entry || l === `/${entry}` || l === `${entry}/`);
+
+  const missing = MUST_IGNORE.filter(({ entry }) => !isIgnored(entry));
+
+  // Check if any sensitive files actually exist but are NOT gitignored
+  const exposedSecrets = SENSITIVE_FILES.filter(pattern => {
+    const cleanPattern = pattern.replace(/\*/g, "");
+    const exists = fs.existsSync(path.join(projectRoot, cleanPattern.startsWith(".") ? cleanPattern : `.${cleanPattern}`))
+      || fs.existsSync(path.join(projectRoot, cleanPattern));
+    const ignored = lines.some(l => l.includes(cleanPattern) || l === pattern);
+    return exists && !ignored;
+  });
+
+  const issues = [
+    ...missing.map(({ entry, reason }) => `Missing: "${entry}"  (${reason})`),
+    ...exposedSecrets.map(f => `⚠ Sensitive file exists and is NOT ignored: ${f}`),
+  ];
+
+  if (issues.length === 0) {
+    return {
+      status: "pass",
+      message: ".gitignore covers all common dangerous entries.",
+    };
+  }
+
+  const hasCritical = exposedSecrets.length > 0;
+
+  return {
+    status: hasCritical ? "fail" : "warn",
+    message: `${issues.length} .gitignore ${issues.length === 1 ? "issue" : "issues"} found:`,
+    items: issues,
+    fix: `Add missing entries to your .gitignore file.`,
+  };
+}
+
+module.exports = checkGitignore;

package/src/checks/largeFiles.js

@@ -0,0 +1,66 @@
+"use strict";
+
+const fs   = require('fs');
+const path = require('path');
+const glob = require('glob')
+
+const SIZE_WARN_MB  = 0.5;   // 500 KB
+const SIZE_FAIL_MB  = 2;     // 2 MB
+
+const IGNORED_EXTENSIONS = [
+  ".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".ico",
+  ".mp4", ".mov", ".avi", ".mp3", ".wav",
+  ".zip", ".tar", ".gz", ".rar",
+  ".pdf", ".woff", ".woff2", ".ttf", ".eot",
+];
+
+function formatSize(bytes) {
+  if (bytes >= 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  if (bytes >= 1024)        return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${bytes} B`;
+}
+
+async function checkLargeFiles(projectRoot) {
+  const allFiles = glob.sync("**/*", {
+    cwd: projectRoot,
+    ignore: ["node_modules/**", "dist/**", "build/**", ".next/**", ".git/**"],
+    absolute: true,
+    nodir: true,
+  });
+
+  const large = [];
+
+  for (const filePath of allFiles) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (IGNORED_EXTENSIONS.includes(ext)) continue;
+
+    let stat;
+    try { stat = fs.statSync(filePath); } catch { continue; }
+
+    const mb = stat.size / (1024 * 1024);
+    if (mb >= SIZE_WARN_MB) {
+      const relPath = path.relative(projectRoot, filePath);
+      large.push({ relPath, size: stat.size, mb });
+    }
+  }
+
+  if (large.length === 0) {
+    return { status: "pass", message: `No unexpectedly large source files found (threshold: ${SIZE_WARN_MB * 1000} KB).` };
+  }
+
+  large.sort((a, b) => b.size - a.size);
+
+  const hasFail = large.some(f => f.mb >= SIZE_FAIL_MB);
+  const status  = hasFail ? "fail" : "warn";
+
+  const items = large.map(f => `${f.relPath}  (${formatSize(f.size)})`);
+
+  return {
+    status,
+    message: `${large.length} large ${large.length === 1 ? "file" : "files"} found in source:`,
+    items,
+    fix: "Consider moving large files to a CDN or adding them to .gitignore.",
+  };
+}
+
+module.exports = checkLargeFiles;

package/src/checks/staleTodos.js

@@ -0,0 +1,82 @@
+"use strict";
+
+const fs        = require("fs");
+const path      = require("path");
+const glob      = require("glob");
+const { execSync } = require("child_process");
+
+const TODO_PATTERN = /\/\/\s*(TODO|FIXME|HACK|XXX|BUG):?\s*(.+)/i;
+
+function getFileAge(filePath) {
+  try {
+    const out = execSync(`git log -1 --format="%ci" -- "${filePath}" 2>/dev/null`, {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "ignore"],
+    }).trim();
+    if (!out) return null;
+    return new Date(out);
+  } catch {
+    return null;
+  }
+}
+
+function daysSince(date) {
+  return Math.floor((Date.now() - date.getTime()) / (1000 * 60 * 60 * 24));
+}
+
+async function checkStaleTodos(projectRoot) {
+  const sourceFiles = glob.sync("**/*.{js,ts,jsx,tsx,mjs,cjs,py,rb,go,java,cs}", {
+    cwd: projectRoot,
+    ignore: ["node_modules/**", "dist/**", "build/**", ".next/**"],
+    absolute: true,
+  });
+
+  if (sourceFiles.length === 0) {
+    return { status: "skip", message: "No source files found." };
+  }
+
+  const todos = [];
+
+  for (const filePath of sourceFiles) {
+    let content;
+    try { content = fs.readFileSync(filePath, "utf8"); } catch { continue; }
+
+    const lines = content.split("\n");
+    lines.forEach((line, i) => {
+      const match = line.match(TODO_PATTERN);
+      if (!match) return;
+
+      const relPath = path.relative(projectRoot, filePath);
+      const age     = getFileAge(filePath);
+      const days    = age ? daysSince(age) : null;
+      const label   = match[1].toUpperCase();
+      const text    = match[2].trim().slice(0, 60);
+      const ageStr  = days !== null ? `${days}d old` : "age unknown";
+
+      todos.push({ relPath, line: i + 1, label, text, days, ageStr });
+    });
+  }
+
+  if (todos.length === 0) {
+    return { status: "pass", message: "No TODO/FIXME comments found. Clean codebase!" };
+  }
+
+  // Sort by oldest first
+  todos.sort((a, b) => (b.days || 0) - (a.days || 0));
+
+  const stale = todos.filter(t => t.days !== null && t.days > 30);
+  const status = stale.length > 5 ? "fail" : stale.length > 0 ? "warn" : "pass";
+
+  const items = todos.map(t =>
+    `[${t.label}] ${t.relPath}:${t.line} — "${t.text}" (${t.ageStr})`
+  );
+
+  return {
+    status,
+    message: `${todos.length} TODO/FIXME found, ${stale.length} older than 30 days:`,
+    items,
+    fix: stale.length > 0 ? "Address or remove comments older than 30 days." : undefined,
+  };
+}
+
+module.exports = checkStaleTodos;

package/src/checks/unusedDeps.js

@@ -0,0 +1,61 @@
+"use strict";
+const fs   = require("fs");
+const path = require("path");
+const glob = require("glob");
+
+async function checkUnusedDependencies(projectRoot) {
+  const pkgPath = path.join(projectRoot, "package.json");
+
+  if (!fs.existsSync(pkgPath)) {
+    return { status: "skip", message: "No package.json found." };
+  }
+
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  const deps = Object.keys(pkg.dependencies || {});
+
+  if (deps.length === 0) {
+    return { status: "pass", message: "No dependencies declared." };
+  }
+
+  // Gather all source files
+  const sourceFiles = glob.sync("**/*.{js,ts,jsx,tsx,mjs,cjs}", {
+    cwd: projectRoot,
+    ignore: ["node_modules/**", "dist/**", "build/**", ".next/**"],
+    absolute: true,
+  });
+
+  if (sourceFiles.length === 0) {
+    return { status: "skip", message: "No source files found to scan." };
+  }
+
+  // Read all source content once
+  const allSource = sourceFiles.map(f => {
+    try { return fs.readFileSync(f, "utf8"); } catch { return ""; }
+  }).join("\n");
+
+  const unused = deps.filter(dep => {
+    // Match require("dep"), require('dep'), from "dep", from 'dep'
+    const escaped = dep.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
+    const pattern = new RegExp(
+      `require\\(['"](${escaped})['"](\\/.+)?['"]\\)|from\\s+['"](${escaped})(\\/.+)?['"]`,
+      "m"
+    );
+    return !pattern.test(allSource);
+  });
+
+  if (unused.length === 0) {
+    return {
+      status: "pass",
+      message: `All ${deps.length} dependencies appear to be used.`,
+    };
+  }
+
+  return {
+    status: "warn",
+    message: `${unused.length} potentially unused ${unused.length === 1 ? "dependency" : "dependencies"} found:`,
+    items: unused.map(d => `${d}`),
+    fix: `npm uninstall ${unused.slice(0, 3).join(" ")}${unused.length > 3 ? " ..." : ""}`,
+  };
+}
+
+module.exports = checkUnusedDependencies;

package/src/index.js

@@ -0,0 +1,99 @@
+"use strict";
+
+const chalk = require("chalk");
+const ora = require("ora");
+const path = require("path");
+
+const checkUnusedDependencies = require("./checks/unusedDeps");
+const checkEnvVars = require("./checks/envVars");
+const checkStaleTodos = require("./checks/staleTodos");
+const checkLargeFiles = require("./checks/largeFiles");
+const checkGitignore = require("./checks/gitignore");
+
+const CHECKS = [
+  { name: "Unused Dependencies",   fn: checkUnusedDependencies },
+  { name: "Env Var Health",        fn: checkEnvVars },
+  { name: "Stale TODOs",           fn: checkStaleTodos },
+  { name: "Large Files",           fn: checkLargeFiles },
+  { name: ".gitignore Safety",     fn: checkGitignore },
+];
+
+function printHeader() {
+  console.log("\n" + chalk.bgGreen.black.bold("  🩺 proj-pulse  ") + chalk.gray("  Project Health Check\n"));
+}
+
+function printSummary(results) {
+  const total   = results.length;
+  const passed  = results.filter(r => r.status === "pass").length;
+  const warned  = results.filter(r => r.status === "warn").length;
+  const failed  = results.filter(r => r.status === "fail").length;
+
+  console.log("\n" + chalk.bold("─".repeat(50)));
+  console.log(chalk.bold("  Summary\n"));
+  console.log(`  ${chalk.green("✔")} Passed   ${chalk.green.bold(passed)}/${total}`);
+  if (warned) console.log(`  ${chalk.yellow("⚠")} Warnings ${chalk.yellow.bold(warned)}/${total}`);
+  if (failed) console.log(`  ${chalk.red("✖")} Failed   ${chalk.red.bold(failed)}/${total}`);
+
+  const score = Math.round((passed / total) * 100);
+  const scoreColor = score >= 80 ? chalk.green : score >= 50 ? chalk.yellow : chalk.red;
+  console.log("\n  " + chalk.bold("Health Score: ") + scoreColor.bold(`${score}%`));
+  console.log(chalk.bold("─".repeat(50)) + "\n");
+}
+
+function printCheckResult(result) {
+  const icons = { pass: chalk.green("✔"), warn: chalk.yellow("⚠"), fail: chalk.red("✖"), skip: chalk.gray("–") };
+  const colors = { pass: chalk.green, warn: chalk.yellow, fail: chalk.red, skip: chalk.gray };
+
+  const icon  = icons[result.status]  || chalk.gray("–");
+  const color = colors[result.status] || chalk.gray;
+
+  console.log(`\n  ${icon}  ${chalk.bold(result.name)}`);
+
+  if (result.message) {
+    console.log(`     ${color(result.message)}`);
+  }
+
+  if (result.items && result.items.length > 0) {
+    result.items.slice(0, 8).forEach(item => {
+      console.log(`       ${chalk.gray("·")} ${item}`);
+    });
+    if (result.items.length > 8) {
+      console.log(`       ${chalk.gray(`... and ${result.items.length - 8} more`)}`);
+    }
+  }
+
+  if (result.fix) {
+    console.log(`     ${chalk.cyan("→ Fix:")} ${chalk.cyan(result.fix)}`);
+  }
+}
+
+async function runPulse(projectRoot) {
+  printHeader();
+  console.log(chalk.gray(`  Scanning: ${projectRoot}\n`));
+
+  const results = [];
+
+  for (const check of CHECKS) {
+    const spinner = ora({ text: chalk.gray(`Checking ${check.name}...`), spinner: "dots" }).start();
+    try {
+      const result = await check.fn(projectRoot);
+      result.name = check.name;
+      results.push(result);
+      spinner.stop();
+      printCheckResult(result);
+    } catch (err) {
+      spinner.stop();
+      const errResult = {
+        name: check.name,
+        status: "skip",
+        message: `Skipped — ${err.message}`,
+      };
+      results.push(errResult);
+      printCheckResult(errResult);
+    }
+  }
+
+  printSummary(results);
+}
+
+module.exports = { runPulse };