@hevman/repo-roast 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hevman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# repo-roast
+
+Roast your repository, then turn the joke into a practical quality checklist.
+
+```bash
+npx @hevman/repo-roast
+```
+
+Example output:
+
+```text
+repo-roast
+
+my-app
+Score: 72/100
+
+Roast:
+This repo ships, but it also trusts vibes where a checklist would cost less emotional damage.
+
+Findings:
+x ERROR No test script
+  package.json has no scripts.test.
+! WARNING Thin README
+  README exists, but it is too short to sell or explain the project.
+
+Next fixes:
+1. Add a test script, even if it starts with a tiny smoke test.
+2. Expand README so a stranger can use the project in under one minute.
+```
+
+## Why
+
+Most project audits are boring. Most jokes are useless. `repo-roast` tries to land in the useful middle: it gives you a shareable roast, a score and a short list of fixes that actually improve the repo.
+
+It checks for:
+
+- missing or thin README,
+- missing license,
+- missing test script,
+- missing GitHub Actions workflow,
+- weak npm metadata,
+- TODO/FIXME pileups,
+- large source files,
+- possible committed secrets.
+
+## Install
+
+```bash
+npm install -D @hevman/repo-roast
+```
+
+## CLI
+
+```bash
+repo-roast
+repo-roast --path ../my-project
+repo-roast --json
+repo-roast --strict
+```
+
+`--strict` exits with code `1` when the score is below 80, which makes it usable in CI.
+
+## Library
+
+```ts
+import { analyzeRepo, formatReport } from "@hevman/repo-roast";
+
+const report = await analyzeRepo({ root: process.cwd() });
+console.log(formatReport(report));
+```
+
+## Publishing
+
+```bash
+npm test
+npm pack --dry-run
+npm publish --access public
+```
+
+## License
+
+MIT

package/dist/analyze.d.ts

@@ -0,0 +1,2 @@
+import type { AnalyzeOptions, RoastReport } from "./types.js";
+export declare function analyzeRepo(options?: AnalyzeOptions): Promise<RoastReport>;

package/dist/analyze.js

@@ -0,0 +1,122 @@
+import { access, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { scanFiles } from "./scan.js";
+function finding(code, level, points, title, detail) {
+    return { code, level, points, title, detail };
+}
+async function exists(path) {
+    return access(path).then(() => true, () => false);
+}
+function packageName(pkg) {
+    if (pkg && typeof pkg === "object" && "name" in pkg && typeof pkg.name === "string") {
+        return pkg.name;
+    }
+    return "this repo";
+}
+function packageScripts(pkg) {
+    if (pkg && typeof pkg === "object" && "scripts" in pkg && pkg.scripts && typeof pkg.scripts === "object") {
+        return pkg.scripts;
+    }
+    return {};
+}
+function roastFor(score, findings) {
+    const top = findings[0];
+    if (score >= 90) {
+        return "This repo is annoyingly responsible. I came here to roast and found vegetables already chopped.";
+    }
+    if (score >= 75) {
+        return `Pretty healthy, but ${top?.title.toLowerCase() ?? "one thing"} is still standing in the hallway wearing shoes indoors.`;
+    }
+    if (score >= 55) {
+        return `This repo ships, but it also trusts vibes where a checklist would cost less emotional damage.`;
+    }
+    return "This repo has startup energy: ambition, caffeine, and a README that may or may not know what happened.";
+}
+function fixFor(issue) {
+    const fixes = {
+        "missing-readme": "Add a README with install, usage and one copy-paste example.",
+        "thin-readme": "Expand README so a stranger can use the project in under one minute.",
+        "missing-license": "Add a LICENSE file before publishing.",
+        "missing-test-script": "Add a test script, even if it starts with a tiny smoke test.",
+        "missing-ci": "Add a basic GitHub Actions workflow that runs npm test.",
+        "package-no-repository": "Add repository, homepage and bugs fields to package.json.",
+        "todo-heavy": "Triage TODO/FIXME comments and turn the real ones into issues.",
+        "large-files": "Split the largest source files or move generated output out of source control.",
+        "possible-secret": "Rotate any real secret and move sensitive values into ignored env files."
+    };
+    return fixes[issue.code] ?? issue.title;
+}
+export async function analyzeRepo(options = {}) {
+    const root = resolve(options.root ?? process.cwd());
+    const files = await scanFiles(root, options.maxFiles);
+    const findings = [];
+    const readme = files.find((file) => /^readme\.md$/i.test(file.path));
+    const license = files.find((file) => /^licen[cs]e/i.test(file.path));
+    const workflows = files.filter((file) => file.path.startsWith(".github/workflows/"));
+    const todoCount = files.reduce((sum, file) => {
+        const matches = file.text
+            .split(/\r?\n/)
+            .filter((line) => /(^|\s|\/\/|#)(TODO|FIXME|HACK)\b/i.test(line) && !line.includes("TODO/FIXME/HACK"));
+        return sum + matches.length;
+    }, 0);
+    const largestFiles = files
+        .filter((file) => /\.(js|jsx|ts|tsx|mjs|cjs)$/i.test(file.path))
+        .sort((a, b) => b.lines - a.lines)
+        .slice(0, 5)
+        .map((file) => ({ path: file.path, lines: file.lines }));
+    const packagePath = join(root, "package.json");
+    const packageJson = await exists(packagePath)
+        ? JSON.parse(await readFile(packagePath, "utf8"))
+        : undefined;
+    const scripts = packageScripts(packageJson);
+    if (!readme) {
+        findings.push(finding("missing-readme", "error", 18, "Missing README", "No README.md found at the repository root."));
+    }
+    else if (readme.text.trim().length < 500) {
+        findings.push(finding("thin-readme", "warning", 8, "Thin README", "README exists, but it is too short to sell or explain the project."));
+    }
+    if (!license) {
+        findings.push(finding("missing-license", "warning", 8, "Missing license", "No LICENSE file found."));
+    }
+    if (packageJson) {
+        if (!scripts.test) {
+            findings.push(finding("missing-test-script", "error", 14, "No test script", "package.json has no scripts.test."));
+        }
+        if (typeof packageJson === "object"
+            && packageJson
+            && (!("repository" in packageJson) || !("bugs" in packageJson) || !("homepage" in packageJson))) {
+            findings.push(finding("package-no-repository", "warning", 6, "Weak npm metadata", "package.json is missing repository, homepage or bugs metadata."));
+        }
+    }
+    if (workflows.length === 0) {
+        findings.push(finding("missing-ci", "warning", 7, "No GitHub Actions", "No workflow found in .github/workflows."));
+    }
+    if (todoCount >= 5) {
+        findings.push(finding("todo-heavy", "warning", Math.min(12, todoCount), "TODO pileup", `${todoCount} TODO/FIXME/HACK comments found.`));
+    }
+    if (largestFiles.some((file) => file.lines >= 500)) {
+        const detail = largestFiles.filter((file) => file.lines >= 500).map((file) => `${file.path} (${file.lines} lines)`).join(", ");
+        findings.push(finding("large-files", "warning", 8, "Large source files", detail));
+    }
+    const secretPattern = /(api[_-]?key|secret|password)\s*[:=]\s*["']?[A-Za-z0-9_\-]{16,}/i;
+    const secretHit = files.find((file) => !file.path.endsWith(".env.example") && secretPattern.test(file.text));
+    if (secretHit) {
+        findings.push(finding("possible-secret", "error", 20, "Possible secret", `A secret-looking value appears in ${secretHit.path}.`));
+    }
+    findings.sort((a, b) => b.points - a.points);
+    const score = Math.max(0, 100 - findings.reduce((sum, issue) => sum + issue.points, 0));
+    const fixes = findings.slice(0, 5).map(fixFor);
+    return {
+        name: packageName(packageJson),
+        root,
+        score,
+        roast: roastFor(score, findings),
+        findings,
+        fixes,
+        stats: {
+            files: files.length,
+            todoCount,
+            largestFiles
+        }
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { analyzeRepo, formatReport } from "./index.js";
+function has(args, flag) {
+    return args.includes(flag);
+}
+function option(args, flag) {
+    const index = args.indexOf(flag);
+    return index === -1 ? undefined : args[index + 1];
+}
+function help() {
+    console.log(`repo-roast
+
+Usage:
+  repo-roast
+  repo-roast --path ../my-project
+  repo-roast --json
+
+Options:
+  --path <dir>   Repository directory to scan
+  --json         Print machine-readable JSON
+  --strict       Exit 1 when score is below 80`);
+}
+async function run() {
+    const args = process.argv.slice(2);
+    if (has(args, "--help") || has(args, "-h")) {
+        help();
+        return;
+    }
+    const report = await analyzeRepo({ root: option(args, "--path") });
+    if (has(args, "--json")) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log(formatReport(report));
+    }
+    if (has(args, "--strict") && report.score < 80) {
+        process.exitCode = 1;
+    }
+}
+run().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+});

package/dist/format.d.ts

@@ -0,0 +1,2 @@
+import type { RoastReport } from "./types.js";
+export declare function formatReport(report: RoastReport): string;

package/dist/format.js

@@ -0,0 +1,41 @@
+function icon(level) {
+    if (level === "error") {
+        return "x";
+    }
+    if (level === "warning") {
+        return "!";
+    }
+    return "i";
+}
+export function formatReport(report) {
+    const lines = [
+        "repo-roast",
+        "",
+        `${report.name}`,
+        `Score: ${report.score}/100`,
+        "",
+        "Roast:",
+        report.roast,
+        ""
+    ];
+    if (report.findings.length === 0) {
+        lines.push("Findings:", "No major issues found. Suspiciously wholesome.", "");
+    }
+    else {
+        lines.push("Findings:");
+        for (const issue of report.findings) {
+            lines.push(`${icon(issue.level)} ${issue.level.toUpperCase()} ${issue.title}`);
+            lines.push(`  ${issue.detail}`);
+        }
+        lines.push("");
+    }
+    if (report.fixes.length > 0) {
+        lines.push("Next fixes:");
+        report.fixes.forEach((fix, index) => {
+            lines.push(`${index + 1}. ${fix}`);
+        });
+        lines.push("");
+    }
+    lines.push(`Scanned ${report.stats.files} text files.`);
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { analyzeRepo } from "./analyze.js";
+export { formatReport } from "./format.js";
+export type { AnalyzeOptions, Finding, FindingLevel, RoastReport } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { analyzeRepo } from "./analyze.js";
+export { formatReport } from "./format.js";

package/dist/scan.d.ts

@@ -0,0 +1,7 @@
+export interface ScannedFile {
+    path: string;
+    absolutePath: string;
+    text: string;
+    lines: number;
+}
+export declare function scanFiles(root: string, maxFiles?: number): Promise<ScannedFile[]>;

package/dist/scan.js

@@ -0,0 +1,72 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+const IGNORED_DIRS = new Set([
+    ".git",
+    "node_modules",
+    "dist",
+    "build",
+    "coverage",
+    ".next",
+    ".turbo",
+    ".cache",
+    "vendor"
+]);
+const TEXT_EXTENSIONS = new Set([
+    ".cjs",
+    ".css",
+    ".env",
+    ".example",
+    ".html",
+    ".js",
+    ".json",
+    ".jsx",
+    ".md",
+    ".mjs",
+    ".ts",
+    ".tsx",
+    ".txt",
+    ".yml",
+    ".yaml"
+]);
+function extension(path) {
+    const dot = path.lastIndexOf(".");
+    return dot === -1 ? "" : path.slice(dot).toLowerCase();
+}
+function shouldRead(path) {
+    const ext = extension(path);
+    return TEXT_EXTENSIONS.has(ext) || path.endsWith("Dockerfile") || path.endsWith("LICENSE");
+}
+export async function scanFiles(root, maxFiles = 600) {
+    const files = [];
+    async function walk(directory) {
+        if (files.length >= maxFiles) {
+            return;
+        }
+        const entries = await readdir(directory, { withFileTypes: true });
+        for (const entry of entries) {
+            const absolutePath = join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (!IGNORED_DIRS.has(entry.name)) {
+                    await walk(absolutePath);
+                }
+                continue;
+            }
+            if (!entry.isFile() || !shouldRead(entry.name)) {
+                continue;
+            }
+            const info = await stat(absolutePath);
+            if (info.size > 250_000) {
+                continue;
+            }
+            const text = await readFile(absolutePath, "utf8").catch(() => "");
+            files.push({
+                path: relative(root, absolutePath).replace(/\\/g, "/"),
+                absolutePath,
+                text,
+                lines: text === "" ? 0 : text.split(/\r?\n/).length
+            });
+        }
+    }
+    await walk(root);
+    return files;
+}

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+export type FindingLevel = "info" | "warning" | "error";
+export interface Finding {
+    code: string;
+    level: FindingLevel;
+    title: string;
+    detail: string;
+    points: number;
+}
+export interface RoastReport {
+    name: string;
+    root: string;
+    score: number;
+    roast: string;
+    findings: Finding[];
+    fixes: string[];
+    stats: {
+        files: number;
+        todoCount: number;
+        largestFiles: Array<{
+            path: string;
+            lines: number;
+        }>;
+    };
+}
+export interface AnalyzeOptions {
+    root?: string;
+    maxFiles?: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@hevman/repo-roast",
+  "version": "0.1.0",
+  "description": "A tiny CLI that roasts your repository and turns the joke into a practical quality checklist.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hevman/repo-roast.git"
+  },
+  "homepage": "https://github.com/hevman/repo-roast#readme",
+  "bugs": {
+    "url": "https://github.com/hevman/repo-roast/issues"
+  },
+  "bin": {
+    "repo-roast": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "repo",
+    "roast",
+    "audit",
+    "quality",
+    "cli",
+    "readme",
+    "github",
+    "developer-tools"
+  ],
+  "author": "hevman",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "typescript": "^5.7.3"
+  }
+}