Library

scan and serve from code, what they return, their errors, and the types @foundry.sh/spyglass exports.

The CLI’s scans and server, called from code. A program scans a workspace, reads what came back, and serves it, with the same results the CLI prints.

import { scan, serve } from "@foundry.sh/spyglass";

const everything = await scan("./my-workspace"); // workspace and every complete package's internals
const workspace = await scan.workspace("./my-workspace"); // workspace level only
const db = await scan.package("./my-workspace", "@acme/db"); // one package's internals
const past = await scan("./my-workspace", { history: true });

const server = await serve("./my-workspace", { port: 0 });
server.url;
await server.stop();

// Several workspaces, read together as a collection
const collection = await scan.collection(["./platform", "./product"]);
collection.manifest.crossings; // dependencies from one workspace on another
const both = await serve.collection(["./platform", "./product"], { port: 0 });
await both.stop();

Runtime

• Spyglass runs on Bun 1.3.14 or newer. bun add @foundry.sh/spyglass installs the library and the spyglass binary together.
• Under Node, the package loads and scan works, but it starts its analysis workers with bun from the PATH, so Bun must still be installed. Under Bun, the running Bun starts them.
• serve needs Bun itself. Under Node it rejects with Spyglass serve needs Bun (>=1.3.14).
• The declarations use URL, which a TypeScript project gets from the DOM library, @types/node, or Bun’s types.

Exports

The package has one entry, @foundry.sh/spyglass. Nothing else in it can be imported.

root is the workspace directory, resolved through symbolic links; roots are a collection’s.

What a scan returns

scan and scan.workspace return what they saved: the dataset read back from disk, not kept in memory.

• The plain fields are JSON. The accessors are functions, so JSON.stringify leaves them out.
• Each accessor reads the manifest, one file, and the manifest again. Once another scan of the workspace has saved over the dataset, the accessor rejects with DatasetReplacedError; scan again to read the new one.
• A scan reuses the cache, so scanning an unchanged workspace again is fast. There is no separate function that reads a saved scan.
• scan.package(root, name) analyzes fresh what scan(root).internals(name) reads back, and returns the six stages: topology, locality, responsibilities, primitives, rewiring, and review.

Options

ScanOptions, for scan and scan.workspace:

ServeOptions, for serve:

scan.package takes no options: it reads the workspace’s configuration and saves nothing.

Progress

A ScanProgressEvent is one of these, told apart by kind:

The server

serve returns an SpyglassServer:

serve takes no lock. A scan that runs while it serves replaces the dataset atomically, and later requests see the new one.

Several workspaces

A collection is one or more workspaces read together, such as a product split across repositories that depend on each other. The CLI forms one only from two or more distinct paths; the library also takes one. Each workspace keeps its own state, dataset, cache, and lock; nothing is saved for the collection itself. What ties them is the collection manifest, derived from the workspaces’ saved manifests whenever it is asked for: each workspace with its id, label, and qualified package ids (<workspace id>:<package>), and the crossings, the declared dependencies of a package in one workspace on a package in another. See output.

The paths are resolved through symbolic links, and a workspace given twice counts once. They are put in one order, by resolved root, whatever the order given. A workspace inside another is refused, and so are no paths at all; one workspace is a collection of one.

scan.collection(roots, options?) scans each workspace as scan does, one after the other in that order, each under its own lock, and returns a CollectionScan:

Its options are scan’s (state, history), except that onProgress receives a CollectionProgressEvent, { kind: "workspace", id, root, event }: the workspace’s id and resolved root, and the ScanProgressEvent its own scan emitted. When a workspace fails, the ones scanned before it keep the datasets they saved, and the call rejects with Spyglass could not scan <root>: <message>, the workspace’s own error as its cause and their scans, each a Scan with its accessors, as scanned.

serve.collection(roots, options?) takes serve’s options and returns a CollectionServer, with url and stop() as an SpyglassServer has and roots, the resolved roots in the collection’s order, in place of root. It serves data/collection-manifest.json, derived at each request, and each workspace’s dataset under data/<workspace id>/; any other path under data/, an unknown id included, is not found. It checks every workspace’s saved dataset first, as serve checks one, and takes no lock: a scan of one workspace while it serves is seen by later requests, the collection manifest included. While a workspace’s dataset cannot be read (deleted, caught mid-swap by a scan, or saved with another schema version), the collection manifest answers 503 with Retry-After: 1 and a message naming the workspace. The viewer draws a collection as one archipelago per workspace, side by side, with the crossings between them drawn on the map and listed in Place.

Errors

Every function rejects with an Error whose message says what to do; the CLI prints the same message after Spyglass: .

Only the two dataset errors have their own classes in 0.1. Test for them with instanceof; tell the others apart by message.

Types

The types nested inside these are not exported. Reach one by indexed access, such as DatasetManifest["packages"][number] for a package’s entry in the manifest. Editors show nested types under Spyglass’s internal names, many starting with Semantics, and show PackageReport as SurfaceReport; the exported names are the ones to write.

DATASET_SCHEMA_VERSION is the dataset’s promise: a dataset whose manifest has this version holds the files output describes, in that shape. A program that reads output/ itself, rather than through a scan’s accessors, checks the manifest’s schemaVersion against it. History has its own version, HISTORY_SCHEMA_VERSION, in its own manifest.

Configuration files

A configuration file in .foundry/spyglass/ can check itself against SpyglassConfig:

// .foundry/spyglass/index.ts
import type { SpyglassConfig } from "@foundry.sh/spyglass";

export default {
  exclude: ["packages/fixtures"],
} satisfies SpyglassConfig;

The import is type-only, so it is removed before the file runs; the workspace needs @foundry.sh/spyglass installed only for its editor to check the types. A domain is NonNullable<SpyglassConfig["domains"]>[number], and a rule NonNullable<SpyglassConfig["rules"]>[number]. See configuration.

One scan at a time

scan and scan.workspace hold the workspace’s lock in its state directory from start to finish, history included. A second scan or export of the same workspace fails at once rather than waiting; scans of different workspaces, or of one workspace under different state roots, run side by side. scan.collection holds each workspace’s lock while it scans that workspace. scan.package, serve, and serve.collection take no lock.

Not exported

The analyses themselves, the dataset reader, the report printer (spyglass report is CLI only), spyglass export, and the codemods are not part of the library. spyglass scan and spyglass serve are scan and serve plus formatting; see the CLI.