@dep-radius/core 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,48 @@
+# @dep-radius/core
+
+The engine behind [`dep-radius`](../cli/README.md): which changes in a dependency update land on
+code you actually wrote. Use it to build your own integration; for the command line, install
+`dep-radius`.
+
+```ts
+import { createCtx, defaultCacheDir, renderJson, run, type Options } from "@dep-radius/core"
+
+const options: Options = {
+  root: process.cwd(),
+  specs: [],
+  format: "json",
+  offline: false,
+  minAgeMs: undefined,
+  latest: false,
+  notes: true,
+  surface: true,
+  prod: false,
+  concurrency: 8,
+  cacheDir: defaultCacheDir(process.env),
+  verbose: false,
+  now: Date.now(),
+  color: false,
+}
+
+const brief = await run(options, createCtx(options), (event) => {
+  if (event.type === "package") console.error(`${event.done}/${event.total}`)
+})
+
+process.stdout.write(renderJson(brief))
+process.exitCode = brief.exitCode
+```
+
+## Entry points
+
+| Import                                         | Contains                                                            |
+| ---------------------------------------------- | ------------------------------------------------------------------- |
+| `@dep-radius/core`                             | `run`, `createCtx`, the brief types, `renderJson`, `renderMarkdown` |
+| `@dep-radius/core/render`                      | Grouping and labels, to write another renderer                      |
+| `@dep-radius/core/schema/brief-v1.schema.json` | The JSON Schema of `renderJson`'s output                            |
+
+The JSON output is a stable contract (`schemaVersion: 1`). The TypeScript types of the internal
+brief may still change before 1.0.
+
+## License
+
+MIT

package/dist/analyze/brief.d.ts

@@ -0,0 +1,18 @@
+import type { MatchResult } from "../notes/match.ts";
+import type { CollectedNotes } from "../notes/collect.ts";
+import type { Candidate, InstalledDep, PackageBrief, PackageUsage, Site } from "../model.ts";
+export interface BriefParts {
+    dep: InstalledDep;
+    candidate: Candidate;
+    usage: PackageUsage | undefined;
+    surface: PackageBrief["surface"] & {
+        truncatedOnUsedEntry?: boolean;
+    };
+    notes: CollectedNotes | undefined;
+    match: MatchResult | undefined;
+    notesDisabled: boolean;
+}
+export declare function buildPackageBrief(parts: BriefParts): PackageBrief;
+export declare function sitesByName(usage: PackageUsage | undefined): Record<string, Site[]>;
+export declare function uniqueSites(sites: Site[]): Site[];
+//# sourceMappingURL=brief.d.ts.map

package/dist/analyze/brief.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brief.d.ts","sourceRoot":"","sources":["../../src/analyze/brief.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACzD,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,IAAI,EACL,MAAM,aAAa,CAAA;AAEpB,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,YAAY,CAAA;IACjB,SAAS,EAAE,SAAS,CAAA;IACpB,KAAK,EAAE,YAAY,GAAG,SAAS,CAAA;IAC/B,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC,GAAG;QAAE,oBAAoB,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;IACrE,KAAK,EAAE,cAAc,GAAG,SAAS,CAAA;IACjC,KAAK,EAAE,WAAW,GAAG,SAAS,CAAA;IAC9B,aAAa,EAAE,OAAO,CAAA;CACvB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,YAAY,CA6DjE;AAED,wBAAgB,WAAW,CACzB,KAAK,EAAE,YAAY,GAAG,SAAS,GAC9B,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAcxB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAUjD"}

package/dist/analyze/brief.js

@@ -0,0 +1,89 @@
+import semver from "semver";
+import { decide } from "./verdict.js";
+import { level0Names } from "../symbol-path.js";
+export function buildPackageBrief(parts) {
+    const { dep, candidate, usage, surface } = parts;
+    const notes = parts.notesDisabled
+        ? {
+            coverage: "disabled",
+            perVersion: [],
+            total: 0,
+            matched: [],
+            unattributedBreaking: [],
+        }
+        : {
+            coverage: parts.notes?.coverage ?? "unavailable",
+            perVersion: parts.notes?.perVersion ?? [],
+            total: parts.match?.total ?? 0,
+            matched: parts.match?.matched ?? [],
+            unattributedBreaking: parts.match?.unattributedBreaking ?? [],
+        };
+    const from = semver.parse(candidate.from);
+    const to = semver.parse(candidate.to);
+    const zeroMajor = !!from &&
+        !!to &&
+        from.major === 0 &&
+        to.major === 0 &&
+        candidate.bump !== "patch";
+    const { verdict, reasons } = decide({
+        bump: candidate.bump,
+        zeroMajor: zeroMajor && candidate.bump === "major",
+        flags: dep.flags,
+        usage,
+        surface,
+        notes,
+    });
+    const { truncatedOnUsedEntry: _t, ...surfaceOut } = surface;
+    return {
+        pkg: dep.name,
+        from: candidate.from,
+        to: candidate.to,
+        bump: candidate.bump,
+        publishedAt: candidate.publishedAt,
+        versionSource: dep.versionSource,
+        manifests: [...new Set(dep.declaredBy.map((d) => d.manifest))].sort(),
+        level: surface.status === "computed" ? 1 : 0,
+        verdict,
+        reasons,
+        surface: surfaceOut,
+        notes,
+        usage: {
+            files: usage?.files ?? 0,
+            sites: uniqueSites(usage?.refs.map((r) => r.site) ?? []),
+            byName: sitesByName(usage),
+            strongNames: usage?.strongNames ?? [],
+            weakNames: usage?.weakNames ?? [],
+            opaque: usage?.opaque ?? [],
+            blindSpots: usage?.blindSpots ?? [],
+        },
+        skippedNewer: candidate.skippedNewer,
+        ...(candidate.alsoAvailable
+            ? { alsoAvailable: candidate.alsoAvailable }
+            : {}),
+    };
+}
+export function sitesByName(usage) {
+    const map = new Map();
+    for (const r of usage?.refs ?? []) {
+        const n = level0Names(r);
+        for (const name of [...n.strong, ...n.weak]) {
+            const list = map.get(name) ?? [];
+            list.push(r.site);
+            map.set(name, list);
+        }
+    }
+    const out = {};
+    for (const name of [...map.keys()].sort())
+        out[name] = uniqueSites(map.get(name));
+    return out;
+}
+export function uniqueSites(sites) {
+    const seen = new Map();
+    for (const s of sites) {
+        const k = `${s.file}:${s.line}`;
+        const prev = seen.get(k);
+        if (!prev || (prev.typeOnly && !s.typeOnly))
+            seen.set(k, s);
+    }
+    return [...seen.values()].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+}

package/dist/analyze/verdict.d.ts

@@ -0,0 +1,16 @@
+import type { InstalledDep, PackageBrief, PackageUsage, Verdict, VerdictReason } from "../model.ts";
+export interface VerdictInput {
+    bump: PackageBrief["bump"];
+    zeroMajor: boolean;
+    flags: InstalledDep["flags"];
+    usage: PackageUsage | undefined;
+    surface: PackageBrief["surface"] & {
+        truncatedOnUsedEntry?: boolean;
+    };
+    notes: PackageBrief["notes"];
+}
+export declare function decide(input: VerdictInput): {
+    verdict: Verdict;
+    reasons: VerdictReason[];
+};
+//# sourceMappingURL=verdict.d.ts.map

package/dist/analyze/verdict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict.d.ts","sourceRoot":"","sources":["../../src/analyze/verdict.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,OAAO,EACP,aAAa,EACd,MAAM,aAAa,CAAA;AAEpB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAA;IAC1B,SAAS,EAAE,OAAO,CAAA;IAClB,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,CAAA;IAC5B,KAAK,EAAE,YAAY,GAAG,SAAS,CAAA;IAC/B,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC,GAAG;QAAE,oBAAoB,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;IACrE,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,CAAA;CAC7B;AAID,wBAAgB,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG;IAC3C,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,aAAa,EAAE,CAAA;CACzB,CA8IA"}

package/dist/analyze/verdict.js

@@ -0,0 +1,134 @@
+import { UNSEEN_LABEL } from "../labels.js";
+// Evaluated in order, every rule that fires is kept as a reason. The one outcome that must never
+// happen is a wrong "quiet", so anything the tool cannot see pushes towards review.
+export function decide(input) {
+    const reasons = [];
+    const { usage, surface, notes } = input;
+    const strongRemoved = surface.touched.filter((t) => t.bucket === "removed" && t.strength === "strong");
+    if (surface.status === "computed" && strongRemoved.length > 0) {
+        reasons.push({
+            code: "removed-touched",
+            detail: `${strongRemoved.length} removed ${plural(strongRemoved.length, "export")} you use: ${names(strongRemoved.map((t) => t.change.path))}`,
+        });
+    }
+    const changed = surface.touched.filter((t) => t.bucket === "changed" && t.strength === "strong");
+    if (changed.length > 0)
+        reasons.push({
+            code: "changed-touched",
+            detail: `${changed.length} changed ${plural(changed.length, "signature")} you use: ${names(changed.map((t) => t.change.path))}`,
+        });
+    const deprecated = surface.touched.filter((t) => t.bucket === "deprecated" && t.strength === "strong");
+    if (deprecated.length > 0)
+        reasons.push({
+            code: "deprecated-touched",
+            detail: `${deprecated.length} newly deprecated: ${names(deprecated.map((t) => t.change.path))}`,
+        });
+    const weak = surface.touched.filter((t) => t.strength === "weak");
+    if (weak.length > 0)
+        reasons.push({
+            code: "possibly-touched",
+            detail: `${weak.length} changed ${plural(weak.length, "member")} you may reach by name: ${names(weak.map((t) => t.change.path))}`,
+        });
+    if (notes.matched.length > 0) {
+        const direct = notes.matched.filter((m) => m.direct).length;
+        reasons.push({
+            code: "notes-match",
+            detail: `${notes.matched.length} release ${plural(notes.matched.length, "note")} ${notes.matched.length === 1 ? "mentions" : "mention"} names you use (${direct} by name in the text)`,
+        });
+    }
+    if (notes.unattributedBreaking.length > 0) {
+        reasons.push({
+            code: "unattributed-breaking",
+            detail: `${notes.unattributedBreaking.length} breaking ${plural(notes.unattributedBreaking.length, "note")} naming no API, which can apply to anyone`,
+        });
+    }
+    const blind = usage?.blindSpots ?? [];
+    if (blind.length > 0)
+        reasons.push({
+            code: "blind-spots",
+            detail: `usage not fully visible: ${blind.map((b) => `${b.count} ${UNSEEN_LABEL[b.kind] ?? b.kind}`).join(", ")}`,
+        });
+    const opaque = usage?.opaque ?? [];
+    if (opaque.length > 0)
+        reasons.push({
+            code: "opaque-usage",
+            detail: `used in ways names cannot show: ${opaque.map((o) => UNSEEN_LABEL[o.kind] ?? o.kind).join(", ")}`,
+        });
+    if (!usage ||
+        (usage.refs.length === 0 && opaque.length === 0 && blind.length === 0)) {
+        reasons.push({
+            code: "not-referenced",
+            detail: "not referenced by any scanned file; used by a tool, loaded by name, or unused",
+        });
+    }
+    const flagged = input.flags.filter((f) => f === "not-in-registry" || f === "patched" || f === "range-guess");
+    if (flagged.length > 0)
+        reasons.push({
+            code: "flagged-install",
+            detail: `the installed copy is ${flagged.join(", ")}`,
+        });
+    // a wrapper's shape lives in the package it wraps: no types of its own is not the same as no shape
+    if (surface.status === "failed" ||
+        surface.status === "offline-uncached" ||
+        surface.status === "types-elsewhere" ||
+        surface.truncatedOnUsedEntry) {
+        reasons.push({
+            code: "surface-incomplete",
+            detail: surface.detail ?? `type surface ${surface.status}`,
+        });
+    }
+    const notesComplete = notes.coverage === "complete";
+    const surfaceComputed = surface.status === "computed";
+    if (!notesComplete && !surfaceComputed) {
+        reasons.push({
+            code: "no-evidence",
+            detail: `neither net is complete: notes ${notes.coverage}, types ${surface.status}`,
+        });
+    }
+    const bothClean = notesComplete &&
+        surfaceComputed &&
+        surface.touched.length === 0 &&
+        notes.matched.length === 0 &&
+        notes.unattributedBreaking.length === 0;
+    if ((input.bump === "major" || input.zeroMajor) && !bothClean) {
+        reasons.push({
+            code: "major-unproven",
+            detail: `a ${input.zeroMajor ? "0.x minor, a major by convention" : "major"} is only quiet when both nets are complete and clean`,
+        });
+    }
+    let verdict = "quiet";
+    if (reasons.some((r) => r.code === "removed-touched"))
+        verdict = "blocked";
+    else if (reasons.length > 0)
+        verdict = "review";
+    else {
+        if (notesComplete)
+            reasons.push({
+                code: "notes-complete-no-match",
+                detail: "every release note read, none mentions what you use",
+            });
+        if (surfaceComputed)
+            reasons.push({
+                code: "surface-clean",
+                detail: "no changed or removed export you use",
+            });
+        if (!surfaceComputed)
+            reasons.push({
+                code: "caveat-no-types",
+                detail: "no type surface: shape changes were judged from the notes alone",
+            });
+        if (!notesComplete)
+            reasons.push({
+                code: "caveat-no-notes",
+                detail: "no release notes: behaviour changes are invisible here",
+            });
+    }
+    return { verdict, reasons };
+}
+function plural(n, word) {
+    return n === 1 ? word : `${word}s`;
+}
+function names(paths) {
+    const shown = paths.slice(0, 4).join(", ");
+    return paths.length > 4 ? `${shown} and ${paths.length - 4} more` : shown;
+}

package/dist/context.d.ts

@@ -0,0 +1,4 @@
+import type { Ctx, Options } from "./options.ts";
+import { type HttpClient } from "./infra/http.ts";
+export declare function createCtx(opts: Options, http?: HttpClient): Ctx;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAChD,OAAO,EAAa,KAAK,UAAU,EAAiB,MAAM,iBAAiB,CAAA;AAI3E,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,GAAG,CAc/D"}

package/dist/context.js

@@ -0,0 +1,36 @@
+import { promisify } from "node:util";
+import { execFile } from "node:child_process";
+import { DiskCache } from "./infra/cache.js";
+import { createLogger } from "./infra/log.js";
+import { createLimiter } from "./infra/limit.js";
+import { FetchHttp, NoNetworkHttp } from "./infra/http.js";
+const run = promisify(execFile);
+export function createCtx(opts, http) {
+    let token;
+    return {
+        http: http ?? (opts.offline ? new NoNetworkHttp() : new FetchHttp()),
+        cache: new DiskCache(opts.cacheDir),
+        now: opts.now,
+        offline: opts.offline,
+        log: createLogger(opts.verbose),
+        net: createLimiter(opts.concurrency),
+        github: createLimiter(Math.min(4, opts.concurrency)),
+        heavy: createLimiter(2),
+        githubToken: () => (token ??= findGithubToken()),
+        env: process.env,
+    };
+}
+// Sent to api.github.com only.
+async function findGithubToken() {
+    if (process.env.GITHUB_TOKEN)
+        return process.env.GITHUB_TOKEN;
+    if (process.env.GH_TOKEN)
+        return process.env.GH_TOKEN;
+    try {
+        const { stdout } = await run("gh", ["auth", "token"], { timeout: 2000 });
+        return stdout.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/debug.d.ts

@@ -0,0 +1,2 @@
+export declare function runDebug(args: string[]): Promise<number>;
+//# sourceMappingURL=debug.d.ts.map

package/dist/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AAgBA,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkH9D"}

package/dist/debug.js

@@ -0,0 +1,130 @@
+import { resolve } from "node:path";
+import { createCtx } from "./context.js";
+import { scanUsage } from "./usage/scan.js";
+import { collectNotes } from "./notes/collect.js";
+import { diffSurfaces } from "./surface/delta.js";
+import { defaultCacheDir } from "./infra/cache.js";
+import { extractSurface } from "./surface/extract.js";
+import { getPackument } from "./registry/packument.js";
+import { buildInventory } from "./inventory/installed.js";
+import { selectCandidate } from "./registry/candidates.js";
+import { listProjectFiles } from "./inventory/manifests.js";
+import { DEFAULT_MIN_AGE_MS } from "./options.js";
+import { isAgeExcluded, loadRegistryConfig } from "./registry/npmrc.js";
+// Each stage on its own, as JSON, for looking at one step without the rest of the pipeline.
+export async function runDebug(args) {
+    const [cmd, ...rest] = args;
+    const root = resolve(process.env.RADIUS_ROOT ?? process.cwd());
+    const now = process.env.RADIUS_NOW
+        ? Date.parse(process.env.RADIUS_NOW)
+        : Date.now();
+    const opts = {
+        root,
+        specs: [],
+        format: "json",
+        offline: process.env.RADIUS_OFFLINE === "1",
+        minAgeMs: undefined,
+        latest: false,
+        notes: true,
+        surface: true,
+        prod: false,
+        concurrency: 8,
+        cacheDir: process.env.RADIUS_CACHE_DIR ?? defaultCacheDir(process.env),
+        verbose: false,
+        now,
+        color: false,
+    };
+    const ctx = createCtx(opts);
+    const cfg = loadRegistryConfig(root, process.env);
+    const print = (v) => process.stdout.write(`${JSON.stringify(v, null, 2)}\n`);
+    if (cmd === "inventory") {
+        const inv = await buildInventory(root, { prod: false });
+        print({ ...inv, manifests: inv.manifests.map((m) => m.path) });
+        return 0;
+    }
+    if (cmd === "candidates") {
+        const inv = await buildInventory(root, { prod: false });
+        const out = [];
+        for (const d of inv.installed) {
+            const p = await getPackument(ctx, cfg, d.name);
+            if (!p.ok) {
+                out.push({ pkg: d.name, error: p.reason });
+                continue;
+            }
+            out.push({
+                pkg: d.name,
+                installed: d.version,
+                ...selectCandidate(p.packument, d.version, {
+                    now,
+                    minAgeMs: cfg.minimumReleaseAgeMs ?? DEFAULT_MIN_AGE_MS,
+                    ageExcluded: (v) => isAgeExcluded(cfg, d.name, v),
+                    latest: false,
+                }),
+            });
+        }
+        print(out);
+        return 0;
+    }
+    if (cmd === "usage" && rest[0]) {
+        const files = await listProjectFiles(root);
+        const inv = await buildInventory(root, { prod: false }, files);
+        const u = await scanUsage(ctx, root, files, inv);
+        print({
+            scannedFiles: u.scannedFiles,
+            global: u.global,
+            packages: Object.values(u.packages).filter((p) => p.pkg === rest[0]),
+        });
+        return 0;
+    }
+    if (cmd === "notes" && rest[0] && rest[1] && rest[2]) {
+        const p = await getPackument(ctx, cfg, rest[0]);
+        if (!p.ok)
+            return fail(p.reason);
+        const c = selectCandidate(p.packument, rest[1], {
+            now,
+            minAgeMs: 0,
+            ageExcluded: () => true,
+            latest: false,
+            explicit: rest[2],
+        });
+        if (c.kind !== "candidate")
+            return fail(JSON.stringify(c));
+        print(await collectNotes(ctx, cfg, p.packument, c.candidate));
+        return 0;
+    }
+    if (cmd === "surface" && rest[0] && rest[1] && rest[2]) {
+        const p = await getPackument(ctx, cfg, rest[0]);
+        if (!p.ok)
+            return fail(p.reason);
+        const a = await extractSurface(ctx, cfg, p.packument, rest[1]);
+        const b = await extractSurface(ctx, cfg, p.packument, rest[2]);
+        if (!a.ok || !b.ok)
+            return fail(JSON.stringify({ from: a.ok || a, to: b.ok || b }));
+        const delta = diffSurfaces(a.surface, b.surface);
+        print({
+            from: {
+                version: a.surface.version,
+                symbols: Object.keys(a.surface.symbols).length,
+                entries: a.surface.entries,
+                flags: a.surface.flags,
+            },
+            to: {
+                version: b.surface.version,
+                symbols: Object.keys(b.surface.symbols).length,
+                entries: b.surface.entries,
+                flags: b.surface.flags,
+            },
+            counts: Object.fromEntries(Object.entries(delta).map(([k, v]) => [
+                k,
+                v.length,
+            ])),
+            delta,
+        });
+        return 0;
+    }
+    return fail("usage: radius debug inventory | candidates | usage <pkg> | notes <pkg> <from> <to> | surface <pkg> <from> <to>");
+}
+function fail(msg) {
+    process.stderr.write(`radius debug: ${msg}\n`);
+    return 3;
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { createCtx } from "./context.ts";
+export { defaultCacheDir } from "./infra/cache.ts";
+export type { HttpClient, HttpRequest, HttpResponse } from "./infra/http.ts";
+export type * from "./model.ts";
+export { type Ctx, DEFAULT_MIN_AGE_MS, type Format, formatAge, type Options, parseDuration, type RunEvent, } from "./options.ts";
+export { type BriefV1, type CannotSeeV1, type PackageV1, renderJson, type SiteV1, toJsonV1, } from "./render/json.ts";
+export { renderMarkdown } from "./render/markdown.ts";
+export { parseSpec, run, type Spec, toolVersion } from "./run.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAClD,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC5E,mBAAmB,YAAY,CAAA;AAC/B,OAAO,EACL,KAAK,GAAG,EACR,kBAAkB,EAClB,KAAK,MAAM,EACX,SAAS,EACT,KAAK,OAAO,EACZ,aAAa,EACb,KAAK,QAAQ,GACd,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,UAAU,EACV,KAAK,MAAM,EACX,QAAQ,GACT,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,IAAI,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA"}

package/dist/index.js

@@ -0,0 +1,8 @@
+// The public API of the engine. Everything a consumer needs to analyse a project and render the
+// result; the modules behind it are free to move.
+export { createCtx } from "./context.js";
+export { defaultCacheDir } from "./infra/cache.js";
+export { DEFAULT_MIN_AGE_MS, formatAge, parseDuration, } from "./options.js";
+export { renderJson, toJsonV1, } from "./render/json.js";
+export { renderMarkdown } from "./render/markdown.js";
+export { parseSpec, run, toolVersion } from "./run.js";

package/dist/infra/cache.d.ts

@@ -0,0 +1,18 @@
+export declare function defaultCacheDir(env: NodeJS.ProcessEnv): string;
+export interface CacheEntry<T> {
+    value: T;
+    storedAt: number;
+}
+export declare class DiskCache {
+    readonly dir: string;
+    constructor(dir: string);
+    path(key: string): string;
+    getJson<T>(key: string): Promise<CacheEntry<T> | undefined>;
+    setJson<T>(key: string, value: T, now: number): Promise<void>;
+    getBytes(key: string): Promise<Buffer | undefined>;
+    setBytes(key: string, bytes: Uint8Array): Promise<void>;
+    has(key: string): Promise<boolean>;
+    private writeAtomic;
+}
+export declare function safeKey(s: string): string;
+//# sourceMappingURL=cache.d.ts.map

package/dist/infra/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/infra/cache.ts"],"names":[],"mappings":"AAIA,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAQ9D;AAED,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAA;IACR,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,qBAAa,SAAS;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;gBACR,GAAG,EAAE,MAAM;IAIvB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAInB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAS3D,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7D,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAQlD,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;YAU1B,WAAW;CAU1B;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC"}

package/dist/infra/cache.js

@@ -0,0 +1,66 @@
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+export function defaultCacheDir(env) {
+    if (env.RADIUS_CACHE_DIR)
+        return env.RADIUS_CACHE_DIR;
+    if (env.XDG_CACHE_HOME)
+        return join(env.XDG_CACHE_HOME, "dep-radius");
+    if (process.platform === "darwin")
+        return join(homedir(), "Library", "Caches", "dep-radius");
+    if (process.platform === "win32" && env.LOCALAPPDATA)
+        return join(env.LOCALAPPDATA, "dep-radius", "Cache");
+    return join(homedir(), ".cache", "dep-radius");
+}
+export class DiskCache {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    path(key) {
+        return join(this.dir, key);
+    }
+    async getJson(key) {
+        try {
+            const raw = await readFile(this.path(key), "utf8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async setJson(key, value, now) {
+        await this.writeAtomic(key, JSON.stringify({ value, storedAt: now }));
+    }
+    async getBytes(key) {
+        try {
+            return await readFile(this.path(key));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async setBytes(key, bytes) {
+        await this.writeAtomic(key, bytes);
+    }
+    async has(key) {
+        try {
+            await stat(this.path(key));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // A crash mid-write must never leave a truncated entry that a later offline run trusts.
+    async writeAtomic(key, data) {
+        const target = this.path(key);
+        await mkdir(dirname(target), { recursive: true });
+        const tmp = `${target}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+        await writeFile(tmp, data);
+        await rename(tmp, target);
+    }
+}
+export function safeKey(s) {
+    return s.replace(/[^a-zA-Z0-9._@-]+/g, "_");
+}

package/dist/infra/hash.d.ts

@@ -0,0 +1,4 @@
+export declare function sha1(data: string | Uint8Array): string;
+export declare function integrityHex(integrity: string): string | undefined;
+export declare function verifyIntegrity(bytes: Uint8Array, integrity: string): boolean;
+//# sourceMappingURL=hash.d.ts.map

package/dist/infra/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/infra/hash.ts"],"names":[],"mappings":"AAEA,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAEtD;AAGD,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKlE;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAO7E"}