@cosmicdrift/kumiko-guards 0.362.0 → 0.364.0

package/src/_lib/direct-dependencies.ts

@@ -0,0 +1,80 @@
+/**
+ * Direct dependencies declared by one repo: its root package.json and every workspace member.
+ */
+import { join } from "node:path";
+import { readPackageJson, workspaceMemberDirs } from "./installed-packages";
+
+const DEP_FIELDS = [
+  "dependencies",
+  "devDependencies",
+  "optionalDependencies",
+  "peerDependencies",
+] as const;
+
+export type DirectDependency = {
+  readonly name: string;
+  readonly version: string;
+};
+
+function isFirstParty(name: string, spec: string): boolean {
+  return (
+    name.startsWith("@cosmicdrift/") ||
+    name.startsWith("@cosmicdriftgamestudio/") ||
+    name.startsWith("@app/") ||
+    spec.startsWith("workspace:")
+  );
+}
+
+function stringEntries(section: unknown): [string, string][] {
+  if (typeof section !== "object" || section === null) return [];
+  return Object.entries(section).filter(
+    (entry): entry is [string, string] => typeof entry[1] === "string",
+  );
+}
+
+/** Every declared (name, spec) pair across the repo, duplicates kept so each differing range stays visible. */
+export function collectDeclaredDependencies(repoRoot: string): DirectDependency[] {
+  const deps: DirectDependency[] = [];
+  for (const dir of [repoRoot, ...workspaceMemberDirs(repoRoot)]) {
+    const pkg = readPackageJson(join(dir, "package.json"));
+    if (!pkg) continue;
+    for (const field of DEP_FIELDS) {
+      for (const [name, version] of stringEntries(pkg[field])) {
+        if (!isFirstParty(name, version)) deps.push({ name, version });
+      }
+    }
+  }
+  return deps;
+}
+
+/** Unique direct dependencies by name (first declaration wins), sorted. */
+export function collectDirectDependencies(repoRoot: string): DirectDependency[] {
+  const byName = new Map<string, DirectDependency>();
+  for (const dep of collectDeclaredDependencies(repoRoot)) {
+    if (!byName.has(dep.name)) byName.set(dep.name, dep);
+  }
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Every declared spec per name, so an install satisfying any one of several differing ranges counts as direct. */
+export function collectDeclaredSpecsByName(
+  repoRoot: string,
+): ReadonlyMap<string, readonly string[]> {
+  const byName = new Map<string, string[]>();
+  for (const dep of collectDeclaredDependencies(repoRoot)) {
+    const specs = byName.get(dep.name);
+    if (specs) specs.push(dep.version);
+    else byName.set(dep.name, [dep.version]);
+  }
+  return byName;
+}
+
+/** Pins from the root package.json `overrides` / `resolutions` (string values only). */
+export function collectRootOverrides(repoRoot: string): ReadonlyMap<string, string> {
+  const pkg = readPackageJson(join(repoRoot, "package.json"));
+  const overrides = new Map<string, string>();
+  for (const field of ["overrides", "resolutions"] as const) {
+    for (const [name, value] of stringEntries(pkg?.[field])) overrides.set(name, value);
+  }
+  return overrides;
+}

package/src/_lib/guard-kit.ts

@@ -583,8 +583,13 @@ function guardKitVersion(): string {
   const pkgPath = resolve(import.meta.dir, "../../package.json");
   // The version only decorates the banner; it must never abort a guard run.
   try {
-    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { readonly version?: string };
-    return pkg.version ?? "unknown";
+    const pkg: unknown = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    return typeof pkg === "object" &&
+      pkg !== null &&
+      "version" in pkg &&
+      typeof pkg.version === "string"
+      ? pkg.version
+      : "unknown";
   } catch {
     return "unknown";
   }

package/src/_lib/installed-packages.ts

@@ -0,0 +1,146 @@
+/**
+ * Installed third-party packages of one repo, found the way Bun resolves them:
+ * node_modules of the repo root, of its workspace members and of every
+ * ancestor directory (a hoisted parent workspace or a `.wt/` worktree has no
+ * node_modules of its own).
+ */
+import { type Dirent, existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export type InstalledPackage = {
+  readonly name: string;
+  readonly version: string;
+  readonly license: string | null;
+  readonly path: string;
+};
+
+const FIRST_PARTY_SCOPES = ["@cosmicdrift/", "@cosmicdriftgamestudio/", "@app/"];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function readPackageJson(file: string): Record<string, unknown> | undefined {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(file, "utf-8"));
+    return isRecord(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Workspace member directories declared by the repo's package.json `workspaces`. */
+export function workspaceMemberDirs(repoRoot: string): string[] {
+  const workspaces = readPackageJson(join(repoRoot, "package.json"))?.["workspaces"];
+  const patterns = Array.isArray(workspaces)
+    ? workspaces
+    : isRecord(workspaces) && Array.isArray(workspaces["packages"])
+      ? workspaces["packages"]
+      : [];
+  const dirs = new Set<string>();
+  for (const pattern of patterns) {
+    if (typeof pattern !== "string" || pattern.startsWith("!")) continue;
+    for (const match of new Bun.Glob(pattern).scanSync({ cwd: repoRoot, onlyFiles: false })) {
+      const dir = join(repoRoot, match);
+      if (existsSync(join(dir, "package.json"))) dirs.add(dir);
+    }
+  }
+  return [...dirs];
+}
+
+/** `node_modules` directories Bun would load from for this repo, nearest first. */
+export function nodeModulesDirs(repoRoot: string): string[] {
+  const dirs: string[] = [];
+  const add = (dir: string): void => {
+    const nodeModules = join(dir, "node_modules");
+    if (!dirs.includes(nodeModules) && existsSync(nodeModules)) dirs.push(nodeModules);
+  };
+  add(repoRoot);
+  for (const member of workspaceMemberDirs(repoRoot)) add(member);
+  for (let dir = dirname(repoRoot); ; dir = dirname(dir)) {
+    add(dir);
+    if (dirname(dir) === dir) break;
+  }
+  return dirs;
+}
+
+/** Directories whose node_modules a scan of `repoRoot` reads — also where their exception files live. */
+export function installationRoots(repoRoot: string): string[] {
+  return [repoRoot, ...nodeModulesDirs(repoRoot).map((dir) => dirname(dir))];
+}
+
+export function collectInstalledPackages(repoRoot: string): InstalledPackage[] {
+  const seen = new Map<string, InstalledPackage>();
+  const visited = new Set<string>();
+  for (const dir of nodeModulesDirs(repoRoot)) walkNodeModules(dir, seen, visited);
+  return [...seen.values()].sort((a, b) =>
+    `${a.name}@${a.version}`.localeCompare(`${b.name}@${b.version}`),
+  );
+}
+
+function readUnvisitedDir(dir: string, visited: Set<string>): Dirent[] {
+  try {
+    const real = realpathSync(dir);
+    if (visited.has(real)) return [];
+    visited.add(real);
+    return readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+function walkNodeModules(
+  dir: string,
+  seen: Map<string, InstalledPackage>,
+  visited: Set<string>,
+): void {
+  const entries = readUnvisitedDir(dir, visited);
+  for (const entry of entries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    if (entry.name.startsWith(".")) continue;
+    const full = join(dir, entry.name);
+    if (entry.name.startsWith("@")) {
+      walkNodeModules(full, seen, visited);
+      continue;
+    }
+    const info = readPackageInfo(join(full, "package.json"));
+    if (info && !seen.has(`${info.name}@${info.version}`)) {
+      seen.set(`${info.name}@${info.version}`, info);
+    }
+    walkNodeModules(join(full, "node_modules"), seen, visited);
+  }
+}
+
+function readPackageInfo(file: string): InstalledPackage | undefined {
+  const pkg = readPackageJson(file);
+  if (!pkg) return undefined;
+  const { name, version } = pkg;
+  if (typeof name !== "string" || typeof version !== "string") return undefined;
+  // Workspace members and the repo's own scopes are first-party, not third-party licences.
+  if (pkg["private"] === true || FIRST_PARTY_SCOPES.some((scope) => name.startsWith(scope))) {
+    return undefined;
+  }
+  return {
+    name,
+    version,
+    license: normalizeLicense(pkg["license"] ?? pkg["licenses"]),
+    path: file,
+  };
+}
+
+function licenseTypeOf(entry: unknown): string | undefined {
+  if (typeof entry === "string") return entry.trim() || undefined;
+  if (isRecord(entry) && typeof entry["type"] === "string")
+    return entry["type"].trim() || undefined;
+  return undefined;
+}
+
+/** SPDX string from package.json `license` (string | {type}) or legacy `licenses` (array). */
+export function normalizeLicense(raw: unknown): string | null {
+  if (Array.isArray(raw)) {
+    const parts = raw.map(licenseTypeOf).filter((part): part is string => part !== undefined);
+    if (parts.length === 0) return null;
+    return parts.length === 1 ? (parts[0] ?? null) : `(${parts.join(" OR ")})`;
+  }
+  return licenseTypeOf(raw) ?? null;
+}

package/src/_lib/npm-registry.ts

@@ -0,0 +1,168 @@
+// Registry lookups go through `bun info` (honors the project's registry/auth config) instead of raw HTTP.
+
+export type LatestRelease = {
+  readonly version: string;
+  readonly publishedAt: string;
+};
+
+export type DeprecationLookup =
+  | { readonly kind: "deprecated"; readonly message: string }
+  | { readonly kind: "current" }
+  | { readonly kind: "unknown"; readonly reason: string };
+
+export type RegistryClient = {
+  /** Deprecation status of one exact version; `unknown` when the registry could not answer. */
+  deprecation(name: string, version: string): Promise<DeprecationLookup>;
+  /** Latest dist-tag with its publish date; `null` when unknown. */
+  latestRelease(name: string): Promise<LatestRelease | null>;
+};
+
+const BUN_INFO_TIMEOUT_MS = 30_000;
+
+export type BunInfoResult =
+  | { readonly ok: true; readonly exitCode: number; readonly value: unknown }
+  | { readonly ok: false; readonly reason: string };
+
+async function bunInfoJson(cwd: string, args: readonly string[]): Promise<BunInfoResult> {
+  try {
+    const proc = Bun.spawn(["bun", "info", ...args, "--json"], {
+      cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+      timeout: BUN_INFO_TIMEOUT_MS,
+    });
+    const [out, err, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    if (out.trim() === "") {
+      const firstErrorLine = err.trim().split("\n")[0];
+      return { ok: false, reason: firstErrorLine || `bun info exited ${exitCode} without output` };
+    }
+    return { ok: true, exitCode, value: JSON.parse(out) };
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// `bun info <pkg>@<v> deprecated` answers a version without the field with exit 1 and {"error":"Property not found"}.
+function isPropertyNotFound(value: unknown): boolean {
+  return isRecord(value) && value["error"] === "Property not found";
+}
+
+export function interpretDeprecationLookup(result: BunInfoResult): DeprecationLookup {
+  if (!result.ok) return { kind: "unknown", reason: result.reason };
+  if (isPropertyNotFound(result.value)) return { kind: "current" };
+  if (result.exitCode === 0 && typeof result.value === "string") {
+    return result.value === ""
+      ? { kind: "current" }
+      : { kind: "deprecated", message: result.value };
+  }
+  return { kind: "unknown", reason: `unexpected bun info answer (exit ${result.exitCode})` };
+}
+
+/** `cwd` must contain a package.json — `bun info` refuses to run without one. */
+export function createBunInfoClient(cwd: string): RegistryClient {
+  return {
+    async deprecation(name, version) {
+      return interpretDeprecationLookup(
+        await bunInfoJson(cwd, [`${name}@${version}`, "deprecated"]),
+      );
+    },
+    async latestRelease(name) {
+      const version = await bunInfoJson(cwd, [name, "dist-tags.latest"]);
+      if (!version.ok || version.exitCode !== 0 || typeof version.value !== "string") return null;
+      const time = await bunInfoJson(cwd, [name, "time"]);
+      const publishedAt = time.ok && isRecord(time.value) ? time.value[version.value] : undefined;
+      return typeof publishedAt === "string" ? { version: version.value, publishedAt } : null;
+    },
+  };
+}
+
+/** Memoizes per call key, so a package listed twice costs one lookup. */
+export function memoizeRegistryClient(client: RegistryClient): RegistryClient {
+  const deprecation = new Map<string, Promise<DeprecationLookup>>();
+  const latest = new Map<string, Promise<LatestRelease | null>>();
+  return {
+    deprecation(name, version) {
+      const key = `${name}@${version}`;
+      const cached = deprecation.get(key);
+      if (cached) return cached;
+      const pending = client.deprecation(name, version);
+      deprecation.set(key, pending);
+      return pending;
+    },
+    latestRelease(name) {
+      const cached = latest.get(name);
+      if (cached) return cached;
+      const pending = client.latestRelease(name);
+      latest.set(name, pending);
+      return pending;
+    },
+  };
+}
+
+export function parseMajor(version: string): number | null {
+  const match = version.match(/^(\d+)/);
+  return match?.[1] === undefined ? null : Number.parseInt(match[1], 10);
+}
+
+export type MajorLagWarning = {
+  readonly name: string;
+  readonly current: string;
+  readonly latest: string;
+  readonly latestPublished: string;
+};
+
+export function findMajorLagWarning(
+  name: string,
+  currentVersion: string,
+  release: LatestRelease,
+  lagMonths: number,
+  nowMs: number,
+): MajorLagWarning | null {
+  const currentMajor = parseMajor(currentVersion);
+  const latestMajor = parseMajor(release.version);
+  if (currentMajor === null || latestMajor === null || latestMajor <= currentMajor) return null;
+
+  let published: Temporal.Instant;
+  try {
+    published = Temporal.Instant.from(release.publishedAt);
+  } catch {
+    return null;
+  }
+  const cutoff = Temporal.Instant.fromEpochMilliseconds(nowMs)
+    .toZonedDateTimeISO("UTC")
+    .subtract({ months: lagMonths });
+  if (Temporal.Instant.compare(published, cutoff.toInstant()) > 0) return null;
+
+  return {
+    name,
+    current: currentVersion,
+    latest: release.version,
+    latestPublished: release.publishedAt,
+  };
+}
+
+export async function mapWithConcurrency<T, R>(
+  items: readonly T[],
+  concurrency: number,
+  fn: (item: T) => Promise<R>,
+): Promise<R[]> {
+  const results: R[] = new Array(items.length);
+  let index = 0;
+  async function worker(): Promise<void> {
+    while (index < items.length) {
+      const i = index++;
+      const item = items[i];
+      if (item !== undefined) results[i] = await fn(item);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, () => worker()));
+  return results;
+}