dep-radius 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 prakticode
+
+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,78 @@
+# dep-radius
+
+[![npm](https://img.shields.io/npm/v/dep-radius)](https://www.npmjs.com/package/dep-radius)
+[![CI](https://github.com/prakticode/dep-radius/actions/workflows/ci.yml/badge.svg)](https://github.com/prakticode/dep-radius/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/dep-radius)](LICENSE)
+
+Which changes in a dependency update land on code you actually wrote.
+
+```sh
+npx dep-radius                 # every direct dependency with an update waiting
+npx dep-radius schemakit       # one package
+npx dep-radius schemakit@3.2.0 # an exact target
+```
+
+```
+◇  Read 412 files
+◇  Checked 38 packages in 9.4s
+
+schemakit  3.1.4 → 3.2.0  minor  published 3d ago   REVIEW
+  surface changes ......... 12
+  changes you touch ....... 0
+  notes mentioning you .... 1  of 18, notes for 1/1 versions (github-release)
+
+  3.2.0  ⚠️ The email pattern no longer accepts quoted local parts
+    you use: email
+    src/signup/schema.ts:14
+    src/billing/contact.ts:9  (via src/lib/validation.ts)
+
+...
+
+38 with an update  31 quiet · 7 review · 0 blocked  · 12 up to date
+```
+
+No account, no configuration file, no build. It reads the folder as it is: any installer, one
+manifest or fifty, TypeScript or plain JavaScript.
+
+## How it decides
+
+Two nets, counted apart and never merged into one reassuring number:
+
+1. **The type surface.** Both versions' declaration files are compared, and every changed or removed
+   export is matched against the names your code resolves into the package, through local re-export
+   files and values built in other files.
+2. **The release notes.** GitHub releases or the changelog, split into entries, kept only when they
+   name something you use.
+
+| Verdict | Exit | Means                                                                |
+| ------- | ---- | -------------------------------------------------------------------- |
+| quiet   | 0    | nothing you use changed, no note mentions it: merge without reading  |
+| review  | 1    | here are the lines concerned, or here is what the tool could not see |
+| blocked | 2    | an export you call was removed                                       |
+
+Anything the tool cannot see pushes towards review, never towards quiet: packages used only from
+scripts, config strings or CSS, names passed around whole, packages with neither types nor notes. A
+quiet verdict that stood on one net only is marked `*`.
+
+## Options
+
+`--json`, `--markdown` (a pull request comment), `--offline`, `--min-age <duration>` (default 1d, or
+the project's `minimumReleaseAge`), `--latest`, `--no-notes`, `--no-surface`, `--prod`, `--verbose`.
+Set `GITHUB_TOKEN`, or log in with `gh`, to lift GitHub's limit from 60 to 5000 requests an hour.
+
+`--json` is a stable contract, `schemaVersion: 1`, described by
+[`brief-v1.schema.json`](../core/schema/brief-v1.schema.json), shipped in `@dep-radius/core` as
+`@dep-radius/core/schema/brief-v1.schema.json`. Version 1 only ever gains fields; removing or
+renaming one means version 2.
+
+Everything downloaded is cached: a second run is offline and takes about as long as reading your
+files. Type surfaces are keyed by tarball integrity, so they are the same for everyone.
+
+## Limits
+
+- Behaviour changes are only seen through release notes.
+- No type checker runs over your code: a member reached through a callback or a value from an
+  unfollowed place is matched by name only.
+- A package whose declarations re-export another package's types is judged from its notes only.
+- Release notes are read from GitHub and the package's own changelog.
+- Transitive dependencies are out of scope; a lockfile and an install cooldown own that risk.

package/dist/cli.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { createRequire } from "node:module";
+import { existsSync, statSync } from "node:fs";
+import { runDebug } from "@dep-radius/core/debug";
+import { createCtx, defaultCacheDir, parseDuration, renderJson, renderMarkdown, run, } from "@dep-radius/core";
+import { renderTerminal } from "./render/terminal.js";
+import { createProgressView } from "./render/progress.js";
+const HELP = `radius: which changes in a dependency update land on code you wrote
+
+usage
+  radius [path]                      every direct dependency with an update waiting
+  radius <pkg>[@<version|tag>] ...   only these packages (a version analyses that exact target)
+
+options
+  --json                 the brief as JSON (schemaVersion 1)
+  --markdown             a pull request comment
+  --offline              read the cache only, never the network
+  --min-age <duration>   hold back versions younger than this (default 1d, or the project's
+                         minimumReleaseAge); "0" disables
+  --latest               target the newest version, across majors
+  --no-notes             do not read release notes
+  --no-surface           do not compare type surfaces
+  --prod                 skip devDependencies
+  --concurrency <n>      network requests at once (default 8)
+  --cache-dir <dir>      default $RADIUS_CACHE_DIR, then the platform cache folder
+  --verbose              every note, every site, every quiet package
+  --version, --help
+
+exit codes
+  0 quiet: nothing you use changed    1 review: read the brief    2 blocked: something you use was removed
+  3 the command itself failed
+
+GITHUB_TOKEN, GH_TOKEN or a logged in gh raise the GitHub limit from 60 to 5000 requests an hour.
+`;
+async function main(argv) {
+    if (argv[0] === "debug")
+        return runDebug(argv.slice(1));
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            allowNegative: true,
+            options: {
+                json: { type: "boolean" },
+                markdown: { type: "boolean" },
+                offline: { type: "boolean" },
+                "min-age": { type: "string" },
+                latest: { type: "boolean" },
+                notes: { type: "boolean", default: true },
+                surface: { type: "boolean", default: true },
+                prod: { type: "boolean" },
+                concurrency: { type: "string" },
+                "cache-dir": { type: "string" },
+                verbose: { type: "boolean", short: "v" },
+                now: { type: "string" },
+                version: { type: "boolean" },
+                help: { type: "boolean", short: "h" },
+            },
+        });
+    }
+    catch (error) {
+        process.stderr.write(`radius: ${error.message}\n\n${HELP}`);
+        return 3;
+    }
+    const v = parsed.values;
+    if (v.help) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (v.version) {
+        process.stdout.write(`${cliVersion()}\n`);
+        return 0;
+    }
+    if (v.json && v.markdown) {
+        process.stderr.write("radius: --json and --markdown cannot be combined\n");
+        return 3;
+    }
+    let root = process.cwd();
+    const specs = [];
+    // a path is written like one (./x, ../x, /x, a/b that exists); a bare word is a package, so a
+    // folder that shares a package's name is reached as ./name
+    for (const p of parsed.positionals) {
+        const abs = resolve(p);
+        const pathLike = p === "." ||
+            p.startsWith("./") ||
+            p.startsWith("../") ||
+            p.startsWith("/") ||
+            p.includes("\\") ||
+            (p.includes("/") && !p.startsWith("@"));
+        if (pathLike && existsSync(abs) && statSync(abs).isDirectory())
+            root = abs;
+        else if (pathLike) {
+            process.stderr.write(`radius: ${p} is not a directory\n`);
+            return 3;
+        }
+        else
+            specs.push(p);
+    }
+    if (!existsSync(root)) {
+        process.stderr.write(`radius: ${root} does not exist\n`);
+        return 3;
+    }
+    const nowRaw = v.now ?? process.env.RADIUS_NOW;
+    const now = nowRaw ? Date.parse(nowRaw) : Date.now();
+    if (!Number.isFinite(now)) {
+        process.stderr.write(`radius: invalid --now ${nowRaw}\n`);
+        return 3;
+    }
+    let minAgeMs;
+    try {
+        minAgeMs =
+            v["min-age"] !== undefined ? parseDuration(v["min-age"]) : undefined;
+    }
+    catch (error) {
+        process.stderr.write(`radius: ${error.message}\n`);
+        return 3;
+    }
+    const format = v.json ? "json" : v.markdown ? "markdown" : "terminal";
+    const opts = {
+        root,
+        specs,
+        format,
+        offline: !!v.offline,
+        minAgeMs,
+        latest: !!v.latest,
+        notes: v.notes !== false,
+        surface: v.surface !== false,
+        prod: !!v.prod,
+        concurrency: Math.max(1, Number(v.concurrency ?? 8) || 8),
+        cacheDir: v["cache-dir"]
+            ? resolve(v["cache-dir"])
+            : defaultCacheDir(process.env),
+        verbose: !!v.verbose,
+        now,
+        color: format === "terminal" && !!process.stdout.isTTY && !process.env.NO_COLOR,
+    };
+    const ctx = createCtx(opts);
+    // a person watching gets progress on stderr; --json, --markdown, CI and pipes get none
+    const view = format === "terminal" &&
+        process.stderr.isTTY &&
+        // a pseudo terminal that reports no width wraps every frame after one character
+        (process.stderr.columns ?? 0) >= 40 &&
+        !process.env.CI
+        ? createProgressView(process.stderr)
+        : undefined;
+    let brief;
+    try {
+        brief = await run(opts, ctx, view ? (e) => view.onEvent(e) : undefined);
+    }
+    catch (error) {
+        view?.fail();
+        throw error;
+    }
+    view?.finish(brief);
+    const text = format === "json"
+        ? renderJson(brief)
+        : format === "markdown"
+            ? renderMarkdown(brief, now)
+            : renderTerminal(brief, {
+                color: opts.color,
+                verbose: opts.verbose,
+                now,
+            });
+    process.stdout.write(text);
+    return brief.exitCode;
+}
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    process.stderr.write(`radius: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+    process.exitCode = 3;
+});
+// the version of this package, which is what `radius --version` reports; the brief carries the engine's
+function cliVersion() {
+    return createRequire(import.meta.url)("../package.json").version;
+}

package/dist/render/progress.js

@@ -0,0 +1,53 @@
+import { progress, spinner } from "@clack/prompts";
+// Drawn on stderr, and only when a person is watching: the report on stdout stays byte for byte
+// what a script or an agent reads.
+export function createProgressView(output, now = Date.now) {
+    const started = now();
+    const reading = spinner({ output, withGuide: false });
+    reading.start("Reading project files");
+    let bar;
+    let files = 0;
+    const running = new Set();
+    return {
+        onEvent(e) {
+            if (e.type === "files") {
+                files = e.total;
+                reading.message(`Reading project files  ${e.done}/${e.total}`);
+            }
+            else if (e.type === "packages") {
+                reading.stop(`Read ${files} ${files === 1 ? "file" : "files"}`);
+                if (e.total === 0)
+                    return;
+                bar = progress({ output, withGuide: false, max: e.total, size: 30 });
+                bar.start(`Checking ${e.total} ${e.total === 1 ? "package" : "packages"}`);
+            }
+            else if (e.type === "package-start") {
+                running.add(e.name);
+            }
+            else if (bar) {
+                running.delete(e.name);
+                const percent = Math.round((100 * e.done) / e.total);
+                // every package starts at once, so names only help once a few slow ones remain
+                const waiting = running.size > 0 && running.size <= 3
+                    ? `  waiting on ${[...running].join(", ")}`
+                    : "";
+                bar.advance(1, `${e.done}/${e.total}  ${percent}%${waiting}`);
+            }
+        },
+        finish(brief) {
+            const seconds = ((now() - started) / 1000).toFixed(1);
+            const checked = brief.packages.length + brief.upToDate;
+            const message = `Checked ${checked} ${checked === 1 ? "package" : "packages"} in ${seconds}s`;
+            if (bar)
+                bar.stop(message);
+            else
+                reading.stop(message);
+        },
+        fail() {
+            if (bar)
+                bar.error("Stopped");
+            else
+                reading.error("Stopped");
+        },
+    };
+}

package/dist/render/terminal.js

@@ -0,0 +1,121 @@
+import { styleText } from "node:util";
+import { ago, coverageLabel, groupBriefs, oneNetOnly, opaqueLabel, siteLabel, sitesFor, surfaceLabel, } from "@dep-radius/core/render";
+export function renderTerminal(brief, opts) {
+    const c = (style, s) => (opts.color ? styleText(style, s) : s);
+    const out = [];
+    const g = groupBriefs(brief);
+    const sources = [...new Set(brief.packages.map((p) => p.versionSource))].join(", ") ||
+        "none";
+    out.push(`${c("bold", "radius")}  ${brief.root}`);
+    out.push(c("dim", `${brief.manifests} ${brief.manifests === 1 ? "manifest" : "manifests"} · ${brief.packages.length} with an update · ${brief.upToDate} up to date · versions from ${sources}`));
+    out.push("");
+    const siteCap = opts.verbose ? Number.POSITIVE_INFINITY : 5;
+    for (const p of g.detailed) {
+        out.push(...packageBlock(p, c, siteCap, opts));
+        out.push("");
+    }
+    if (g.quiet.length > 0) {
+        out.push(`${c("green", "quiet")} (${g.quiet.length})  ${c("dim", "merge without reading")}`);
+        const items = g.quiet.map((p) => `${p.pkg} ${p.from} → ${p.to}${oneNetOnly(p) ? "*" : ""}`);
+        if (opts.verbose)
+            for (const p of g.quiet)
+                out.push(`  ${p.pkg} ${p.from} → ${p.to}  ${c("dim", p.reasons.map((r) => r.detail).join("; "))}`);
+        else
+            out.push(`  ${items.join(", ")}`);
+        if (!opts.verbose && g.quiet.some(oneNetOnly))
+            out.push(c("dim", "  * judged on one net only: no types, or notes missing for some versions (--verbose)"));
+        out.push("");
+    }
+    if (g.unseen.length > 0) {
+        out.push(`${c("yellow", "cannot see how you use these")} (${g.unseen.length})  ${c("dim", "run your build or tests")}`);
+        for (const p of g.unseen)
+            out.push(`  ${p.pkg} ${p.from} → ${p.to} ${c("dim", p.bump)}  ${c("dim", opaqueLabel(p))}`);
+        out.push("");
+    }
+    if (brief.notAnalyzed.length > 0) {
+        out.push(c("dim", `not analysed (${brief.notAnalyzed.length})`));
+        for (const n of brief.notAnalyzed)
+            out.push(c("dim", `  ${n.pkg}: ${n.reason}`));
+        out.push("");
+    }
+    const globalLine = brief.global.map((x) => `${x.count} ${x.kind}`).join(", ");
+    if (globalLine)
+        out.push(c("dim", `whole project: ${globalLine}`));
+    if (brief.limits.length > 0) {
+        out.push(c("dim", "limits"));
+        for (const l of brief.limits)
+            out.push(c("dim", `  - ${l}`));
+    }
+    const rateLimited = brief.packages.some((p) => p.notes.perVersion.some((v) => v.reason === "rate-limited"));
+    if (rateLimited) {
+        out.push("");
+        out.push(c("yellow", "GitHub's rate limit was reached, so some release notes were not read: set GITHUB_TOKEN or run gh auth login."));
+    }
+    const count = (v) => brief.packages.filter((p) => p.verdict === v).length;
+    out.push("");
+    out.push(`${c("bold", `${brief.packages.length} with an update`)}  ${c("green", `${count("quiet")} quiet`)} · ${c("yellow", `${count("review")} review`)} · ${c("red", `${count("blocked")} blocked`)}  ${c("dim", `· ${brief.upToDate} up to date`)}`);
+    return `${out.join("\n")}\n`;
+}
+function packageBlock(p, c, siteCap, opts) {
+    const lines = [];
+    const verdict = p.verdict === "blocked"
+        ? c(["bold", "red"], "BLOCKED")
+        : c(["bold", "yellow"], "REVIEW");
+    lines.push(`${c("bold", p.pkg)}  ${p.from} → ${p.to}  ${p.bump}  ${c("dim", `published ${ago(p.publishedAt, opts.now)}`)}   ${verdict}`);
+    const direct = p.notes.matched.filter((m) => m.direct).length;
+    const possibly = p.notes.matched.length - direct;
+    lines.push(`  surface changes ......... ${surfaceLabel(p)}`);
+    if (p.surface.status === "computed")
+        lines.push(`  changes you touch ....... ${p.surface.touched.length}`);
+    lines.push(`  notes mentioning you .... ${p.notes.coverage === "disabled" ? "not read" : direct}${possibly > 0 ? c("dim", `  (+${possibly} possibly)`) : ""}${c("dim", `  of ${p.notes.total}, ${coverageLabel(p)}`)}`);
+    lines.push(c("dim", `  used in ${p.usage.files} ${p.usage.files === 1 ? "file" : "files"}, ${p.usage.sites.length} sites · ${p.manifests.join(", ")}`));
+    const touchCap = opts.verbose ? Number.POSITIVE_INFINITY : 10;
+    for (const t of p.surface.touched.slice(0, touchCap)) {
+        lines.push("");
+        const label = t.bucket === "removed" ? c("red", "removed") : t.bucket;
+        lines.push(`  ${label}  ${c("bold", t.change.path)}${t.strength === "weak" ? c("dim", "  (by member name)") : ""}`);
+        if (t.change.before)
+            lines.push(c("dim", `    before  ${t.change.before.join("  |  ").slice(0, 200)}`));
+        if (t.change.after)
+            lines.push(c("dim", `    after   ${t.change.after.join("  |  ").slice(0, 200)}`));
+        for (const s of t.sites.slice(0, siteCap))
+            lines.push(`    ${siteLabel(s)}`);
+        if (t.sites.length > siteCap)
+            lines.push(c("dim", `    ... ${t.sites.length - siteCap} more`));
+    }
+    if (p.surface.touched.length > touchCap)
+        lines.push("", c("dim", `  ... ${p.surface.touched.length - touchCap} more changes you touch (--verbose)`));
+    const shownNotes = opts.verbose
+        ? p.notes.matched
+        : p.notes.matched.slice(0, 8);
+    if (shownNotes.length > 0)
+        lines.push("");
+    for (const m of shownNotes) {
+        const names = [...new Set(m.hits.map((h) => h.name))];
+        const tag = m.direct ? "" : c("dim", "  possibly");
+        lines.push(`  ${c("cyan", m.entry.version)}  ${m.entry.title}${tag}`);
+        const strongNames = m.hits
+            .filter((h) => h.strength === "strong")
+            .map((h) => h.name);
+        const sites = sitesFor(p, strongNames.length > 0 ? strongNames : names);
+        lines.push(c("dim", `    you use: ${names.join(", ")}`));
+        for (const s of sites.slice(0, m.direct ? Math.min(3, siteCap) : 1))
+            lines.push(`    ${siteLabel(s)}`);
+        if (sites.length > (m.direct ? Math.min(3, siteCap) : 1))
+            lines.push(c("dim", `    ... ${sites.length - (m.direct ? Math.min(3, siteCap) : 1)} more sites`));
+    }
+    if (p.notes.matched.length > shownNotes.length)
+        lines.push(c("dim", `  ... ${p.notes.matched.length - shownNotes.length} more notes (--verbose)`));
+    for (const e of p.notes.unattributedBreaking)
+        lines.push(`  ${c("cyan", e.version)}  ${e.title}  ${c("dim", "breaking, names no API")}`);
+    lines.push("");
+    for (const r of p.reasons)
+        lines.push(c("dim", `  why: ${r.detail}`));
+    const skipped = p.skippedNewer.filter((s) => s.reason === "too-new");
+    if (skipped.length > 0) {
+        lines.push(c("dim", `  newer, held back: ${skipped.map((s) => `${s.version} (${s.publishedAt ? ago(s.publishedAt, opts.now) : "too new"})`).join(", ")}`));
+    }
+    if (p.alsoAvailable)
+        lines.push(c("dim", `  also available: ${p.alsoAvailable.version} (${p.alsoAvailable.bump}, not analysed; radius ${p.pkg}@${p.alsoAvailable.version})`));
+    return lines;
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "dep-radius",
+  "version": "0.1.0",
+  "description": "Tells you which changes in a dependency update land on code you actually wrote.",
+  "license": "MIT",
+  "author": "prakticode",
+  "homepage": "https://github.com/prakticode/dep-radius#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prakticode/dep-radius.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/prakticode/dep-radius/issues"
+  },
+  "keywords": [
+    "dependencies",
+    "upgrade",
+    "semver",
+    "changelog",
+    "release-notes",
+    "renovate",
+    "dependabot",
+    "breaking-changes",
+    "typescript",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "radius": "dist/cli.js",
+    "dep-radius": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.0",
+    "@dep-radius/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0",
+    "@types/node": "^24.0.0",
+    "eslint": "^9.39.5",
+    "typescript": "~6.0.3",
+    "vitest": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "node src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint --max-warnings 0",
+    "lint:fix": "eslint --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist .turbo"
+  }
+}