Library API

spyglass can be used programmatically in any Node.js or Bun project to analyze dependency trees with npm registry data, disk size, and outdated detection.

Installation

npm install @linuxctrl/spyglass

Import

import { parseGraph, findCircular, findUnused, why } from "@linuxctrl/spyglass";
import type { GraphNode, PackageInfo, CircularResult, UnusedResult, WhyResult } from "@linuxctrl/spyglass";

parseGraph

Parse the full dependency graph. Returns the tree with npm info, disk size, circular dependencies, unused packages, and a summary.

const result = await parseGraph();
// {
//   tree: GraphNode[],
//   circular: CircularResult[],
//   unused: UnusedResult[],
//   summary: GraphSummary
// }

const result = await parseGraph({
  path: "./packages/core",
  production: true,
  npm: false,  // skip npm registry lookups
});

findCircular

Find circular dependencies in the project.

const cycles = await findCircular();
// [{ chain: ["a", "b", "c", "a"] }]

findUnused

Find dependencies in package.json that are not used, with npm info.

const unused = await findUnused();
// [{ name: "lodash", version: "^4.17.21", info: { ... } }]

why

Trace why a specific package is in the dependency tree. Includes npm metadata like description and weekly downloads.

const result = await why("typescript");
// {
//   name: "typescript",
//   version: "5.9.3",
//   path: ["typescript"],
//   info: {
//     description: "TypeScript is a language for application scale JavaScript development",
//     latest: "6.0.3",
//     weeklyDownloads: 215900000,
//     diskSize: "22.5 MB",
//     outdated: true,
//   }
// }

Types

interface PackageInfo {
  description?: string;
  latest?: string;
  weeklyDownloads?: number;
  diskSize?: string;
  outdated: boolean;
}

interface GraphNode {
  name: string;
  version: string;
  depth: number;
  children: GraphNode[];
  info?: PackageInfo;
}

interface CircularResult {
  chain: string[];
}

interface UnusedResult {
  name: string;
  version: string;
  info?: PackageInfo;
}

interface WhyResult {
  name: string;
  version: string;
  path: string[];
  info?: PackageInfo;
}

interface GraphSummary {
  total: number;
  outdated: number;
  diskSize: string;
}

interface GraphOptions {
  path?: string;
  production?: boolean;
  npm?: boolean;
}