shipready 1.5.3 → 1.7.0

package/README.md

@@ -242,6 +242,30 @@ console.log("startup banner"); // shipready-ignore
 
 For project-wide exceptions, prefer `secretAllowlist` in the config (see below) so the suppression is reviewable in one place.
 
+## Scoring
+
+The score starts at 100 and every deduction is itemized right under the score bar - the number is never a black box:
+
+| Deduction | Points |
+| --- | --- |
+| No package.json | -20 |
+| No README | -15 |
+| Weak README | -8 |
+| No build script | -8 |
+| No test script | -6 |
+| `.env.example` missing | -10 |
+| `.env` not ignored by git | -15 |
+| Hardcoded secret | -25 each (capped at -50) |
+| Secret in git history | -10 each (capped at -30) |
+| TODO/FIXME comment | -2 each (capped at -15) |
+
+Checks adapt to what your repo actually is:
+
+- **Monorepos** - workspaces (`package.json` `workspaces`, `pnpm-workspace.yaml`, including `**` globs) and conventional `frontend/` + `backend/` splits are detected; scripts and `.env.example` files in workspace packages count.
+- **Libraries** - packages with a `files` allowlist aren't required to have `dev`/`build` scripts.
+- **Non-JS ecosystems** - Go/Rust/Python/etc. projects get ecosystem-appropriate `.gitignore` expectations, and `.env` is only expected if the code actually reads env vars.
+- **Mixed-language repos** - a FastAPI + React project reads "Vite + Python", not just "Vite".
+
 ## Configuration
 
 Optional `shipready.config.json` in your project root:

package/dist/checks/env.js

@@ -83,7 +83,7 @@ export function findRealLookingExampleValues(content) {
     return suspicious;
 }
 /** Checks .env / .env.example / gitignore safety around env vars. */
-export function checkEnv(root, envUsages) {
+export function checkEnv(root, envUsages, workspaceDirs = []) {
     const findings = [];
     const hasEnv = fileExists(root, ".env");
     const exampleContent = readTextFile(root, ".env.example") ?? readTextFile(root, ".env.sample");
@@ -111,8 +111,17 @@ export function checkEnv(root, envUsages) {
             });
         }
     }
+    // Monorepos keep .env.example per workspace package, not at the root.
+    const workspaceExamples = workspaceDirs.filter((d) => fileExists(root, `${d}/.env.example`) || fileExists(root, `${d}/.env.sample`));
     // .env.example presence
-    if (usedVars.length > 0 && !hasExample) {
+    if (usedVars.length > 0 && !hasExample && workspaceExamples.length > 0) {
+        findings.push({
+            severity: "success",
+            rule: "env.example-found-workspaces",
+            message: `.env.example found in ${workspaceExamples.length} workspace package${workspaceExamples.length > 1 ? "s" : ""}`,
+        });
+    }
+    else if (usedVars.length > 0 && !hasExample) {
         findings.push({
             severity: "error",
             rule: "env.example-missing",

package/dist/checks/gitignore.js

@@ -1,4 +1,6 @@
+import { isNodeEcosystem } from "../utils/framework.js";
 import { readTextFile } from "../utils/files.js";
+/** Node-ecosystem entries (also the default when the framework is unknown). */
 export const IMPORTANT_IGNORES = [
     ".env",
     ".env.local",
@@ -7,8 +9,47 @@ export const IMPORTANT_IGNORES = [
     "build",
     ".next",
 ];
+/**
+ * Expected entries per ecosystem. Suggesting node_modules to a Go project
+ * (or target/ to a Python one) is noise that erodes trust in the tool, so
+ * each ecosystem only gets entries that actually apply to it.
+ */
+const ECOSYSTEM_IGNORES = {
+    Python: [".env", "__pycache__", ".venv"],
+    Go: [".env"],
+    Rust: [".env", "target"],
+    PHP: [".env", "vendor"],
+    Ruby: [".env", ".bundle"],
+    Java: [".env", "target", "build"],
+    Deno: [".env"],
+    "Static HTML": [".env"],
+    unknown: [".env"],
+};
+/** Returns the entries a project of the given framework should ignore. */
+export function importantIgnoresFor(framework, ctx) {
+    // Without context, keep the legacy full list (also the config-less API).
+    if (!framework && !ctx)
+        return IMPORTANT_IGNORES;
+    if (!framework || isNodeEcosystem(framework)) {
+        const entries = [".env", ".env.local", "node_modules"];
+        // Build output dirs are only worth ignoring when something builds.
+        if (ctx?.hasBuildScript !== false) {
+            if (framework === "Next.js")
+                entries.push(".next");
+            else
+                entries.push("dist");
+        }
+        return entries;
+    }
+    const base = ECOSYSTEM_IGNORES[framework] ?? [".env"];
+    // A repo that reads no env vars gains nothing from ignoring .env -
+    // suggesting it to e.g. ripgrep is pure noise.
+    if (ctx?.usesEnv === false)
+        return base.filter((e) => e !== ".env");
+    return base;
+}
 /** Returns which important entries are missing from gitignore content. */
-export function missingIgnoreEntries(content) {
+export function missingIgnoreEntries(content, framework, ctx) {
     const lines = content
         .split("\n")
         .map((l) => l.trim())
@@ -23,10 +64,10 @@ export function missingIgnoreEntries(content) {
         // "node_modules/" style already normalized above
         return false;
     });
-    return IMPORTANT_IGNORES.filter((e) => !covers(e));
+    return importantIgnoresFor(framework, ctx).filter((e) => !covers(e));
 }
 /** Checks .gitignore existence and important entries. */
-export function checkGitignore(root) {
+export function checkGitignore(root, framework, ctx) {
     const findings = [];
     const content = readTextFile(root, ".gitignore");
     if (content === null) {
@@ -37,7 +78,7 @@ export function checkGitignore(root) {
         });
         return { name: "gitignore", findings };
     }
-    const missing = missingIgnoreEntries(content);
+    const missing = missingIgnoreEntries(content, framework, ctx);
     if (missing.length > 0) {
         findings.push({
             severity: "warning",

package/dist/checks/packageJson.js

@@ -1,5 +1,23 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileExists } from "../utils/files.js";
 import { isNodeEcosystem } from "../utils/framework.js";
 const IMPORTANT_SCRIPTS = ["dev", "build", "test", "lint"];
+/** Linter configs that count as lint coverage even without a lint script. */
+const LINTER_CONFIGS = [
+    "biome.json",
+    "biome.jsonc",
+    "eslint.config.js",
+    "eslint.config.mjs",
+    "eslint.config.cjs",
+    "eslint.config.ts",
+    ".eslintrc",
+    ".eslintrc.js",
+    ".eslintrc.cjs",
+    ".eslintrc.json",
+    ".eslintrc.yml",
+    ".eslintrc.yaml",
+];
 /** Checks package.json existence and important scripts. */
 export function checkPackageJson(project) {
     const findings = [];
@@ -26,7 +44,34 @@ export function checkPackageJson(project) {
         rule: "package-json.found",
         message: "package.json found",
     });
-    const missing = IMPORTANT_SCRIPTS.filter((s) => !project.scripts[s]);
+    const hasLinterConfig = LINTER_CONFIGS.some((f) => fileExists(project.root, f));
+    // Published libraries (a "files" allowlist, not private) ship source, not
+    // a running app - requiring dev/build scripts of e.g. express is noise.
+    const pkg = project.packageJson;
+    const isLibrary = Array.isArray(pkg?.["files"]) && pkg?.["private"] !== true;
+    // In monorepos the scripts live in workspace packages, not the root.
+    const workspaceScripts = new Set();
+    for (const dir of project.workspaceDirs ?? []) {
+        try {
+            const wsPkg = JSON.parse(fs.readFileSync(path.join(project.root, dir, "package.json"), "utf8"));
+            for (const name of Object.keys(wsPkg.scripts ?? {}))
+                workspaceScripts.add(name);
+        }
+        catch { /* skip unreadable workspace */ }
+    }
+    const missing = IMPORTANT_SCRIPTS.filter((s) => {
+        if (project.scripts[s])
+            return false;
+        if (workspaceScripts.has(s))
+            return false;
+        if (isLibrary && (s === "dev" || s === "build"))
+            return false;
+        // A biome/eslint config means linting is set up; the script name is
+        // a convention, not a requirement (e.g. Biome repos run "biome check").
+        if (s === "lint" && hasLinterConfig)
+            return false;
+        return true;
+    });
     if (missing.length > 0) {
         findings.push({
             severity: "warning",

package/dist/fixers/gitignore.js

@@ -1,18 +1,13 @@
-import { missingIgnoreEntries } from "../checks/gitignore.js";
+import { importantIgnoresFor, missingIgnoreEntries } from "../checks/gitignore.js";
 import { readTextFile, writeTextFile } from "../utils/files.js";
 /** Adds missing important entries to .gitignore (creates it if absent). */
-export function fixGitignore(root, dryRun = false) {
+export function fixGitignore(root, dryRun = false, framework) {
     const file = ".gitignore";
     const existing = readTextFile(root, file);
     if (existing === null) {
         const content = [
             "# Added by shipready",
-            ".env",
-            ".env.local",
-            "node_modules",
-            "dist",
-            "build",
-            ".next",
+            ...importantIgnoresFor(framework),
             "",
         ].join("\n");
         if (!dryRun) {
@@ -20,7 +15,7 @@ export function fixGitignore(root, dryRun = false) {
         }
         return { file, action: "created", dryRun, preview: content };
     }
-    const missing = missingIgnoreEntries(existing);
+    const missing = missingIgnoreEntries(existing, framework);
     if (missing.length === 0) {
         return { file, action: "skipped", reason: "already complete" };
     }

package/dist/scanner.js

@@ -8,7 +8,7 @@ import { checkHistory, isGitRepo, scanGitHistory } from "./checks/history.js";
 import { verifySecrets } from "./checks/verify.js";
 import { checkTodos, scanContentForTodos } from "./checks/todos.js";
 import { fileExists, findSourceFiles, isProbablyBinary, readJsonFile, readTextFile, } from "./utils/files.js";
-import { detectFramework, detectPackageManager } from "./utils/framework.js";
+import { detectExtraLanguages, detectFramework, detectPackageManager, findWorkspaceDirs } from "./utils/framework.js";
 import { isRuleDisabled, loadConfig } from "./config.js";
 /** File extensions considered code for content scanning (not config/data). */
 const CODE_ONLY = new Set([
@@ -21,14 +21,17 @@ const CODE_ONLY = new Set([
 export async function detectProject(root, config) {
     const pkg = readJsonFile(root, "package.json");
     const sourceFiles = await findSourceFiles(root, config?.ignore ?? []);
+    const workspaceDirs = findWorkspaceDirs(root, pkg);
     return {
         root,
         hasPackageJson: fileExists(root, "package.json"),
         packageJson: pkg,
         packageManager: detectPackageManager(root),
-        framework: detectFramework(pkg, root, sourceFiles),
+        framework: detectFramework(pkg, root, sourceFiles, workspaceDirs),
         scripts: pkg?.scripts ?? {},
         sourceFiles,
+        workspaceDirs,
+        extraLanguages: detectExtraLanguages(root, detectFramework(pkg, root, sourceFiles, workspaceDirs)),
     };
 }
 /** Extracts env usages, secrets, and todos from all source files. */
@@ -73,37 +76,50 @@ export function scanFiles(root, files, secretAllowlist = []) {
     }
     return { envUsages, secrets, todos };
 }
-/** Score deductions per the shipready scoring model. */
-export function calculateScore(results) {
-    let score = 100;
+/**
+ * Score deductions per the shipready scoring model. Returns the breakdown
+ * so users can see exactly where every point went instead of trusting an
+ * opaque number.
+ */
+export function calculateScoreBreakdown(results) {
     const all = results.flatMap((r) => r.findings);
     const has = (rule) => all.some((f) => f.rule === rule);
     const count = (rule) => all.filter((f) => f.rule === rule).length;
+    const deductions = [];
+    const deduct = (points, reason) => {
+        if (points > 0)
+            deductions.push({ reason, points });
+    };
     if (has("package-json.missing"))
-        score -= 20;
+        deduct(20, "no package.json");
     if (has("readme.missing"))
-        score -= 15;
+        deduct(15, "no README");
     if (has("readme.weak"))
-        score -= 8;
+        deduct(8, "weak README");
     // Missing scripts: look at message to determine which ones
     const scriptsFinding = all.find((f) => f.rule === "scripts.missing");
     if (scriptsFinding) {
         if (scriptsFinding.message.includes("build"))
-            score -= 8;
+            deduct(8, "no build script");
         if (scriptsFinding.message.includes("test"))
-            score -= 6;
+            deduct(6, "no test script");
     }
     if (has("env.example-missing"))
-        score -= 10;
+        deduct(10, ".env.example missing");
     if (has("env.not-ignored"))
-        score -= 15;
+        deduct(15, ".env not ignored");
     const secretCount = count("secrets.detected-item");
-    score -= Math.min(secretCount * 25, 50);
+    deduct(Math.min(secretCount * 25, 50), secretCount === 1 ? "hardcoded secret" : `hardcoded secrets (${secretCount})`);
     const historyCount = count("history.secret-item");
-    score -= Math.min(historyCount * 10, 30);
+    deduct(Math.min(historyCount * 10, 30), historyCount === 1 ? "secret in git history" : `secrets in git history (${historyCount})`);
     const todoCount = count("todos.item");
-    score -= Math.min(todoCount * 2, 15);
-    return Math.max(0, score);
+    deduct(Math.min(todoCount * 2, 15), todoCount === 1 ? "TODO comment" : `TODO comments (${todoCount})`);
+    const total = deductions.reduce((sum, d) => sum + d.points, 0);
+    return { score: Math.max(0, 100 - total), deductions };
+}
+/** Score per the shipready scoring model (see calculateScoreBreakdown). */
+export function calculateScore(results) {
+    return calculateScoreBreakdown(results).score;
 }
 /** Removes findings whose rules are disabled by config. */
 function applyDisabledRules(results, disableRules) {
@@ -133,17 +149,20 @@ export async function runScan(root, options = {}) {
     const rawResults = [
         checkPackageJson(project),
         checkReadme(root),
-        checkEnv(root, envUsages),
+        checkEnv(root, envUsages, project.workspaceDirs),
         checkSecrets(secrets),
         ...(options.history ? [checkHistory(historySecrets, historyScanned)] : []),
         checkTodos(todos),
-        checkGitignore(root),
+        checkGitignore(root, project.framework, {
+            hasBuildScript: Boolean(project.scripts["build"]),
+            usesEnv: envUsages.length > 0,
+        }),
     ];
     // Disabled rules are removed before scoring so they don't affect the score.
     const results = applyDisabledRules(rawResults, config.disableRules);
     return {
         project,
         results,
-        score: calculateScore(results),
+        ...calculateScoreBreakdown(results),
     };
 }

package/dist/utils/framework.js

@@ -1,4 +1,108 @@
+import fs from "node:fs";
+import path from "node:path";
 import { fileExists } from "./files.js";
+/**
+ * Finds workspace package directories for monorepos. Reads patterns from
+ * package.json "workspaces" and pnpm-workspace.yaml, expanding one level of
+ * trailing-star globs ("apps/*"). Only dirs that contain a package.json
+ * count - that's what makes them workspace packages.
+ */
+export function findWorkspaceDirs(root, pkg) {
+    const patterns = [];
+    const ws = pkg?.["workspaces"];
+    if (Array.isArray(ws))
+        patterns.push(...ws);
+    else if (ws && typeof ws === "object" && Array.isArray(ws.packages)) {
+        patterns.push(...(ws.packages));
+    }
+    const pnpmWs = path.join(root, "pnpm-workspace.yaml");
+    if (fs.existsSync(pnpmWs)) {
+        try {
+            // Minimal YAML: only the common "packages:" list form is supported.
+            const lines = fs.readFileSync(pnpmWs, "utf8").split("\n");
+            let inPackages = false;
+            for (const raw of lines) {
+                const line = raw.trim();
+                if (line.startsWith("packages:")) {
+                    inPackages = true;
+                    continue;
+                }
+                if (inPackages) {
+                    if (line.startsWith("- "))
+                        patterns.push(line.slice(2).trim().replace(/^["']|["']$/g, ""));
+                    else if (line && !line.startsWith("#"))
+                        inPackages = false;
+                }
+            }
+        }
+        catch { /* unreadable yaml: treat as no workspaces */ }
+    }
+    const dirs = new Set();
+    const addPackagesUnder = (base, depth) => {
+        const abs = path.join(root, base);
+        if (!fs.existsSync(abs))
+            return;
+        try {
+            for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
+                if (!entry.isDirectory() || entry.name === "node_modules")
+                    continue;
+                const rel = path.join(base, entry.name);
+                if (fs.existsSync(path.join(root, rel, "package.json")))
+                    dirs.add(rel);
+                // "packages/**/*" style patterns nest one extra level (e.g. astro's
+                // packages/integrations/react). Depth-capped to avoid crawling.
+                else if (depth > 1)
+                    addPackagesUnder(rel, depth - 1);
+            }
+        }
+        catch { /* unreadable dir */ }
+    };
+    for (const pattern of patterns) {
+        if (pattern.startsWith("!"))
+            continue;
+        if (pattern.includes("**")) {
+            addPackagesUnder(pattern.slice(0, pattern.indexOf("**")).replace(/\/$/, ""), 3);
+        }
+        else if (pattern.endsWith("/*")) {
+            addPackagesUnder(pattern.slice(0, -2), 1);
+        }
+        else if (fs.existsSync(path.join(root, pattern, "package.json"))) {
+            dirs.add(pattern);
+        }
+    }
+    // Repos without workspace config often still split into conventional
+    // app dirs (frontend/ + backend/, client/ + server/). Treating those as
+    // pseudo-workspaces makes env/script checks see the whole project.
+    if (dirs.size === 0) {
+        for (const conventional of ["frontend", "backend", "client", "server", "web", "app", "api"]) {
+            if (fs.existsSync(path.join(root, conventional, "package.json"))) {
+                dirs.add(conventional);
+            }
+        }
+    }
+    return [...dirs].sort();
+}
+/**
+ * Detects non-JS languages living alongside the primary framework, so a
+ * FastAPI + React template reads "Vite + Python" instead of hiding half
+ * the project.
+ */
+export function detectExtraLanguages(root, framework) {
+    const markers = [
+        ["pyproject.toml", "Python"],
+        ["requirements.txt", "Python"],
+        ["go.mod", "Go"],
+        ["Cargo.toml", "Rust"],
+        ["Gemfile", "Ruby"],
+        ["composer.json", "PHP"],
+    ];
+    const found = new Set();
+    for (const [file, lang] of markers) {
+        if (lang !== framework && fs.existsSync(path.join(root, file)))
+            found.add(lang);
+    }
+    return [...found];
+}
 /** Detects the package manager based on lockfiles and manifests. */
 export function detectPackageManager(root) {
     // Node ecosystems (lockfile wins over manifest)
@@ -45,12 +149,26 @@ function countByExt(files, exts) {
  * that static sites, Python, Go, Rust, PHP, and Ruby projects are
  * identified instead of reported as "unknown".
  */
-export function detectFramework(pkg, root, sourceFiles = []) {
+export function detectFramework(pkg, root, sourceFiles = [], workspaceDirs = []) {
     if (pkg) {
         const deps = {
             ...pkg.dependencies,
             ...pkg.devDependencies,
         };
+        // Monorepo roots rarely depend on the framework directly - check the
+        // workspace packages so a Turborepo of Next.js apps reads "Next.js",
+        // not "Node.js".
+        if (root && workspaceDirs.length > 0 && !deps["next"] && !deps["react"] && !deps["vue"] && !deps["svelte"]) {
+            for (const dir of workspaceDirs) {
+                try {
+                    const wsPkg = JSON.parse(fs.readFileSync(path.join(root, dir, "package.json"), "utf8"));
+                    const wsResult = detectFramework(wsPkg, undefined, []);
+                    if (wsResult !== "Node.js")
+                        return wsResult;
+                }
+                catch { /* skip unreadable workspace */ }
+            }
+        }
         // Order matters: meta-frameworks before their underlying libraries.
         if (deps["next"])
             return "Next.js";

package/dist/utils/report.js

@@ -125,6 +125,7 @@ export function renderReport(report, verbose = false, version) {
         : project.packageManager;
     const meta = pc.dim("project ") +
         project.framework +
+        (project.extraLanguages.length > 0 ? " + " + project.extraLanguages.join(" + ") : "") +
         pc.dim("  \u00b7  ") +
         pc.dim("pm ") +
         pmLabel;
@@ -132,6 +133,12 @@ export function renderReport(report, verbose = false, version) {
     lines.push(...box([title, meta]));
     lines.push("");
     lines.push(`  ${pc.bold("Score")}  ${scoreBar(report.score)}  ${scoreLabel(report.score)}  ${verdict(report.score)}`);
+    if (report.deductions.length > 0) {
+        lines.push("  " +
+            pc.dim(report.deductions
+                .map((d) => `-${d.points} ${d.reason}`)
+                .join("  \u00b7  ")));
+    }
     lines.push("");
     // Aligned checks table: one row per check, then its top-level findings.
     const labelWidth = Math.max(...report.results.map((r) => (CHECK_LABELS[r.name] ?? r.name).length));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shipready",
-  "version": "1.5.3",
+  "version": "1.7.0",
   "description": "Pre-flight check for your repo before shipping. Scans AI-coded projects for secrets, env issues, debug leftovers, and generates AI-agent instruction files.",
   "type": "module",
   "license": "MIT",