depbrief 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Liam McCall
+
+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,61 @@
+# depbrief
+
+One verdict per dependency upgrade — semver bump class, known vulnerabilities, deprecation status. No GitHub App to install, no account, no config.
+
+```
+$ npx depbrief
+
+[AVOID]    lodash 4.17.20 -> 4.17.21 (patch)
+           - the version you would upgrade to has a known unpatched vulnerability
+[REVIEW]   express 4.18.2 -> 5.0.0 (major)
+           - major version bump — breaking changes are likely, check the changelog
+[URGENT]   axios 0.21.1 -> 0.21.4 (patch)
+           - current version has a known vulnerability — upgrading resolves it
+[SAFE]     chalk 5.2.0 -> 5.3.0 (minor)
+           - minor bump, no known vulnerabilities, not deprecated
+
+4 of 41 dependencies have updates available (37 already up to date).
+```
+
+## Why
+
+`npm outdated` tells you what's outdated. `npm audit` tells you what's *currently* vulnerable. Neither tells you, in one line, whether upgrading from A to B is the kind of thing you can merge without looking, or the kind of thing that needs a human. Renovate and Dependabot solve this well but require installing a GitHub App and living in PRs — `depbrief` is the same idea as a 2-second local command, for the moment before you even open one.
+
+## What it checks, per dependency
+
+- **Semver bump class** — patch / minor / major (0.x minor bumps are treated as major, since semver itself makes no compatibility promise below 1.0).
+- **Known vulnerabilities** — queries [OSV.dev](https://osv.dev) (free, no API key) for both the current and target version.
+- **Deprecation** — checks whether the target version is marked deprecated on the npm registry.
+
+These combine into one of five verdicts, worst first: `AVOID` (target itself has a known vuln) > `URGENT` (current version has a known vuln) > `REVIEW` (major bump) > `CAUTION` (deprecated target, or a downgrade) > `SAFE`.
+
+## Install / usage
+
+```bash
+# scan the current project's package.json + lockfile
+npx depbrief
+
+# check one upgrade directly, no project needed
+npx depbrief express 4.18.2 5.0.0
+
+# machine-readable output
+npx depbrief --json
+
+# CI gate: fail the build on anything AVOID or URGENT
+npx depbrief --fail-on AVOID,URGENT
+```
+
+Needs network access (npm registry + OSV.dev, both public and free). Zero runtime dependencies — uses Node's built-in `fetch`.
+
+## Limitations (v1)
+
+- Semver parsing is deliberately minimal (no build-metadata, no range satisfaction) — it classifies two concrete versions, it doesn't resolve ranges.
+- No changelog summarization yet — verdicts are based on structured signals (bump class, OSV, deprecation), not parsed release notes. That's a reasonable v2 direction if there's demand.
+
+## Contributing
+
+Issues and PRs welcome. Decision logic lives in `lib/verdict.js` and `lib/semver.js`, both pure/offline and unit tested — network I/O is isolated in `lib/npmRegistry.js` and `lib/osv.js`.
+
+## License
+
+MIT

package/bin/depbrief.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+const { analyzeProject, analyzePair } = require('../lib/index');
+const { printReport, printJson } = require('../lib/report');
+
+function parseArgs(argv) {
+  const args = { positional: [], json: false, failOn: null, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') args.json = true;
+    else if (a === '--fail-on') args.failOn = argv[++i];
+    else if (a === '-h' || a === '--help') args.help = true;
+    else args.positional.push(a);
+  }
+  return args;
+}
+
+function printHelp() {
+  console.log(`depbrief - one verdict per dependency upgrade (semver bump, known vulns, deprecation)
+
+Usage:
+  depbrief                        Scan package.json + lockfile in the current directory
+  depbrief <pkg> <from> <to>      Check a single upgrade directly, no project needed
+  depbrief --json                 Machine-readable output
+  depbrief --fail-on AVOID,URGENT Exit non-zero if any result matches these verdicts (for CI)
+
+Verdicts: AVOID > URGENT > REVIEW > CAUTION > SAFE
+`);
+}
+
+const VERDICT_RANK = { AVOID: 0, URGENT: 1, REVIEW: 2, CAUTION: 3, SAFE: 4 };
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  let results;
+  let meta = {};
+
+  if (args.positional.length === 3) {
+    const [name, from, to] = args.positional;
+    results = await analyzePair(name, from, to);
+  } else if (args.positional.length === 0) {
+    const projectResult = await analyzeProject(process.cwd());
+    if (!projectResult) {
+      console.log('No package.json found in the current directory.');
+      process.exitCode = 1;
+      return;
+    }
+    results = projectResult.results;
+    meta = { upToDateCount: projectResult.upToDateCount, totalCount: projectResult.totalCount };
+  } else {
+    console.error('Usage: depbrief | depbrief <pkg> <from> <to>. Run depbrief --help for details.');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (args.json) {
+    printJson(results);
+  } else {
+    printReport(results, { useColor: process.stdout.isTTY, ...meta });
+  }
+
+  if (args.failOn) {
+    const failVerdicts = new Set(args.failOn.split(',').map((s) => s.trim().toUpperCase()));
+    if (results.some((r) => failVerdicts.has(r.verdict))) {
+      process.exitCode = 1;
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error(`depbrief error: ${err.message}`);
+  process.exitCode = 1;
+});

package/lib/discover.js

@@ -0,0 +1,54 @@
+const fs = require('fs');
+const path = require('path');
+
+function readJson(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function depNamesFromPackageJson(pkg) {
+  return Object.keys({ ...pkg.dependencies, ...pkg.devDependencies });
+}
+
+// Returns Map<name, installedVersion> using whatever source is available,
+// preferring the lockfile (exact resolved versions) over node_modules.
+function resolveInstalledVersions(dir, names) {
+  const resolved = new Map();
+
+  const lock = readJson(path.join(dir, 'package-lock.json'));
+  if (lock && lock.packages) {
+    // npm lockfileVersion 2/3
+    for (const name of names) {
+      const entry = lock.packages[`node_modules/${name}`];
+      if (entry && entry.version) resolved.set(name, entry.version);
+    }
+  } else if (lock && lock.dependencies) {
+    // npm lockfileVersion 1
+    for (const name of names) {
+      const entry = lock.dependencies[name];
+      if (entry && entry.version) resolved.set(name, entry.version);
+    }
+  }
+
+  for (const name of names) {
+    if (resolved.has(name)) continue;
+    const pkgJsonPath = path.join(dir, 'node_modules', name, 'package.json');
+    const pkg = readJson(pkgJsonPath);
+    if (pkg && pkg.version) resolved.set(name, pkg.version);
+  }
+
+  return resolved;
+}
+
+function loadProject(dir) {
+  const pkg = readJson(path.join(dir, 'package.json'));
+  if (!pkg) return null;
+  const names = depNamesFromPackageJson(pkg);
+  const installed = resolveInstalledVersions(dir, names);
+  return { names, installed };
+}
+
+module.exports = { loadProject };

package/lib/index.js

@@ -0,0 +1,64 @@
+const { loadProject } = require('./discover');
+const { fetchPackageMetadata, getLatestVersion, isVersionDeprecated } = require('./npmRegistry');
+const { queryVulnerabilities } = require('./osv');
+const { computeVerdict } = require('./verdict');
+
+const CONCURRENCY = 8;
+
+async function mapWithConcurrency(items, limit, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  async function worker() {
+    while (next < items.length) {
+      const i = next++;
+      results[i] = await fn(items[i], i);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  return results;
+}
+
+async function analyzeDependency(name, from, to) {
+  const meta = await fetchPackageMetadata(name);
+  const targetDeprecated = meta ? isVersionDeprecated(meta, to) : false;
+
+  const vulnMap = await queryVulnerabilities([
+    { name, version: from },
+    { name, version: to },
+  ]);
+
+  return computeVerdict({
+    name,
+    from,
+    to,
+    currentHasVuln: vulnMap.get(`${name}@${from}`) || false,
+    targetHasVuln: vulnMap.get(`${name}@${to}`) || false,
+    targetDeprecated,
+  });
+}
+
+async function analyzePair(name, from, to) {
+  return [await analyzeDependency(name, from, to)];
+}
+
+async function analyzeProject(dir) {
+  const project = loadProject(dir);
+  if (!project) return null;
+
+  const entries = [...project.installed.entries()];
+  const withLatest = await mapWithConcurrency(entries, CONCURRENCY, async ([name, current]) => {
+    const meta = await fetchPackageMetadata(name);
+    const latest = meta ? getLatestVersion(meta) : null;
+    return { name, current, latest };
+  });
+
+  const toCheck = withLatest.filter((d) => d.latest && d.latest !== d.current);
+
+  const results = await mapWithConcurrency(toCheck, CONCURRENCY, ({ name, current, latest }) =>
+    analyzeDependency(name, current, latest)
+  );
+
+  return { results, upToDateCount: withLatest.length - toCheck.length, totalCount: withLatest.length };
+}
+
+module.exports = { analyzeProject, analyzePair };

package/lib/npmRegistry.js

@@ -0,0 +1,31 @@
+const REGISTRY_BASE = 'https://registry.npmjs.org';
+
+const cache = new Map();
+
+async function fetchPackageMetadata(name) {
+  if (cache.has(name)) return cache.get(name);
+  const url = `${REGISTRY_BASE}/${encodeURIComponent(name).replace('%40', '@')}`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    if (res.status === 404) {
+      const empty = null;
+      cache.set(name, empty);
+      return empty;
+    }
+    throw new Error(`npm registry returned ${res.status} for ${name}`);
+  }
+  const json = await res.json();
+  cache.set(name, json);
+  return json;
+}
+
+function getLatestVersion(meta) {
+  return meta && meta['dist-tags'] ? meta['dist-tags'].latest : null;
+}
+
+function isVersionDeprecated(meta, version) {
+  if (!meta || !meta.versions || !meta.versions[version]) return false;
+  return Boolean(meta.versions[version].deprecated);
+}
+
+module.exports = { fetchPackageMetadata, getLatestVersion, isVersionDeprecated };

package/lib/osv.js

@@ -0,0 +1,33 @@
+const OSV_BATCH_URL = 'https://api.osv.dev/v1/querybatch';
+
+// pairs: [{ name, version }]. Returns Map key `${name}@${version}` -> boolean (has known vuln).
+async function queryVulnerabilities(pairs) {
+  const result = new Map();
+  if (pairs.length === 0) return result;
+
+  const queries = pairs.map((p) => ({
+    package: { name: p.name, ecosystem: 'npm' },
+    version: p.version,
+  }));
+
+  const res = await fetch(OSV_BATCH_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ queries }),
+  });
+
+  if (!res.ok) {
+    throw new Error(`OSV.dev returned ${res.status}`);
+  }
+
+  const json = await res.json();
+  const results = json.results || [];
+  pairs.forEach((p, i) => {
+    const entry = results[i];
+    const hasVuln = Boolean(entry && Array.isArray(entry.vulns) && entry.vulns.length > 0);
+    result.set(`${p.name}@${p.version}`, hasVuln);
+  });
+  return result;
+}
+
+module.exports = { queryVulnerabilities };

package/lib/report.js

@@ -0,0 +1,48 @@
+const COLORS = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  green: '\x1b[32m',
+  gray: '\x1b[90m',
+  magenta: '\x1b[35m',
+};
+
+const VERDICT_COLOR = {
+  AVOID: COLORS.magenta,
+  URGENT: COLORS.red,
+  REVIEW: COLORS.yellow,
+  CAUTION: COLORS.yellow,
+  SAFE: COLORS.green,
+};
+
+function printReport(results, { useColor = true, upToDateCount, totalCount } = {}) {
+  const c = (code, s) => (useColor ? `${code}${s}${COLORS.reset}` : s);
+
+  if (results.length === 0) {
+    console.log('All dependencies are up to date.');
+    return;
+  }
+
+  const order = ['AVOID', 'URGENT', 'REVIEW', 'CAUTION', 'SAFE'];
+  const sorted = [...results].sort((a, b) => order.indexOf(a.verdict) - order.indexOf(b.verdict));
+
+  console.log('');
+  for (const r of sorted) {
+    const tag = c(VERDICT_COLOR[r.verdict], `[${r.verdict}]`.padEnd(10));
+    console.log(`${tag} ${c(COLORS.bold, r.name)} ${r.from} -> ${r.to} (${r.bump})`);
+    for (const reason of r.reasons) {
+      console.log(`           ${c(COLORS.gray, '-')} ${reason}`);
+    }
+  }
+  console.log('');
+  if (typeof totalCount === 'number') {
+    console.log(`${results.length} of ${totalCount} dependencies have updates available (${upToDateCount} already up to date).`);
+  }
+}
+
+function printJson(results) {
+  console.log(JSON.stringify(results, null, 2));
+}
+
+module.exports = { printReport, printJson };

package/lib/semver.js

@@ -0,0 +1,36 @@
+// Minimal semver handling — deliberately not the full spec (no build metadata,
+// no range satisfaction). Good enough for "what kind of bump is this" between
+// two concrete version strings, which is all depbrief needs.
+
+const CORE_RE = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/;
+
+function parse(version) {
+  const cleaned = String(version).replace(/^[\^~>=<v]+/, '').trim();
+  const m = CORE_RE.exec(cleaned);
+  if (!m) return null;
+  return {
+    major: Number(m[1]),
+    minor: Number(m[2]),
+    patch: Number(m[3]),
+    prerelease: m[4] || null,
+    raw: cleaned,
+  };
+}
+
+// Returns 'major' | 'minor' | 'patch' | 'none' | 'downgrade' | 'unknown'
+function classifyBump(fromVersion, toVersion) {
+  const from = parse(fromVersion);
+  const to = parse(toVersion);
+  if (!from || !to) return 'unknown';
+
+  if (to.major > from.major) return 'major';
+  if (to.major < from.major) return 'downgrade';
+  if (to.minor > from.minor) return from.major === 0 ? 'major' : 'minor';
+  if (to.minor < from.minor) return 'downgrade';
+  if (to.patch > from.patch) return 'patch';
+  if (to.patch < from.patch) return 'downgrade';
+  if (from.prerelease && !to.prerelease) return 'patch';
+  return 'none';
+}
+
+module.exports = { parse, classifyBump };

package/lib/verdict.js

@@ -0,0 +1,50 @@
+const { classifyBump } = require('./semver');
+
+/**
+ * Pure decision logic — no network I/O — so it's unit-testable with
+ * plain fixture objects.
+ *
+ * input: {
+ *   name, from, to,
+ *   currentHasVuln: boolean,   // known OSV vuln affects the *current* version
+ *   targetHasVuln: boolean,    // known OSV vuln affects the *target* version
+ *   targetDeprecated: boolean, // npm registry marks target version deprecated
+ * }
+ */
+function computeVerdict(input) {
+  const bump = classifyBump(input.from, input.to);
+  const reasons = [];
+
+  if (input.targetHasVuln) {
+    reasons.push('the version you would upgrade to has a known unpatched vulnerability');
+    return { name: input.name, from: input.from, to: input.to, bump, verdict: 'AVOID', reasons };
+  }
+
+  if (input.currentHasVuln) {
+    reasons.push('current version has a known vulnerability — upgrading resolves it');
+    if (bump === 'major') reasons.push('this is also a major version bump — review the changelog');
+    return { name: input.name, from: input.from, to: input.to, bump, verdict: 'URGENT', reasons };
+  }
+
+  if (bump === 'major') {
+    reasons.push('major version bump — breaking changes are likely, check the changelog');
+    return { name: input.name, from: input.from, to: input.to, bump, verdict: 'REVIEW', reasons };
+  }
+
+  if (input.targetDeprecated) {
+    reasons.push('target version is marked deprecated on the npm registry');
+    return { name: input.name, from: input.from, to: input.to, bump, verdict: 'CAUTION', reasons };
+  }
+
+  if (bump === 'downgrade' || bump === 'unknown') {
+    reasons.push(bump === 'downgrade' ? 'this would downgrade the package' : "couldn't parse one of the versions");
+    return { name: input.name, from: input.from, to: input.to, bump, verdict: 'CAUTION', reasons };
+  }
+
+  reasons.push(`${bump} bump, no known vulnerabilities, not deprecated`);
+  return { name: input.name, from: input.from, to: input.to, bump, verdict: 'SAFE', reasons };
+}
+
+const VERDICT_ORDER = ['AVOID', 'URGENT', 'REVIEW', 'CAUTION', 'SAFE'];
+
+module.exports = { computeVerdict, VERDICT_ORDER };

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "depbrief",
+  "version": "0.1.0",
+  "description": "One verdict per dependency upgrade: semver bump class, known vulnerabilities, deprecation status. No accounts, no GitHub App, no dependencies.",
+  "keywords": [
+    "npm",
+    "dependencies",
+    "upgrade",
+    "semver",
+    "vulnerability",
+    "security",
+    "cli",
+    "developer-tools"
+  ],
+  "license": "MIT",
+  "bin": {
+    "depbrief": "bin/depbrief.js"
+  },
+  "main": "lib/index.js",
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test/run.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/greatfighter891-gif/depbrief.git"
+  }
+}