@takodotid/circuit 0.34.3 → 0.35.0

package/src/studio/data.ts

@@ -3,11 +3,11 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { portsOf } from "../adapters/devices/catalog";
-import { familyOf, host } from "../core/addr";
-import { type AddressReport, addressesOf } from "../core/addresses";
-import { type Annotated, type Holder, holdersOf, keyOf } from "../core/graph";
-import { SCHEMA_FILES, schemaTypes } from "../core/schema-docs";
+import { Catalog } from "../platforms/catalog";
+import { Address } from "../core/address";
+import { AddressSpace, type AddressReport } from "../core/address-space";
+import { Topology, type Annotated, type Holder } from "../core/topology";
+import { SchemaDocs } from "../core/schema-docs";
 import type { Device } from "../schema";
 
 /** One BGP session, with its group's settings filled in, and what is at its far end. */
@@ -68,188 +68,192 @@ export type StudioData = {
     docs: Record<string, TypeDocs>;
 };
 
-function sessionsOf(devices: readonly Device[], owners: Map<string, Holder>): Session[] {
-    const all = devices.flatMap((device) => {
-        const bgp = device.routing?.bgp;
-
-        return Object.entries(bgp?.neighbors ?? {}).map(([name, neighbor]): Session & { deviceObject: Device } => {
-            const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;
-            const settings = { ...group, ...neighbor };
-
-            return {
-                deviceObject: device,
-                device: device.name,
-                name,
-                address: neighbor.address,
-                group: neighbor.group,
-                remoteAs: settings.remote_as,
-                role: settings.role,
-                import: settings.import,
-                export: settings.export,
-                description: settings.description,
-            };
-        });
-    });
-
-    const ownerOf = (address: string) => owners.get(keyOf(address) ?? "")?.device;
+/** Where a device is kept, relative to the config: the file that declares it, and its snapshot. Either is absent when it cannot be found. */
+export type DeviceFiles = { source?: string; snapshot?: string };
 
-    return all.map(({ deviceObject, ...session }) => {
-        const far = ownerOf(session.address);
+/** How Studio learns what a device would run and what it ran, from the caller, which knows the adapters and the state directory. */
+export type DeviceTexts = {
+    /** What the device would run, as `circuit build` prints it. */
+    render: (device: Device) => string;
+    /** Its last snapshot, or undefined when it has none. */
+    snapshot: (device: Device) => string | undefined;
+    /** Its file and its snapshot's file. */
+    files: (device: Device) => DeviceFiles;
+};
 
-        if (far && far !== deviceObject) {
-            // The session back is one of the same family: a v4 session back does not answer a v6 session.
-            const back = all.some(
-                (other) =>
-                    other.deviceObject === far &&
-                    ownerOf(other.address) === deviceObject &&
-                    familyOf(other.address) === familyOf(session.address)
-            );
-            return { ...session, far: far.name, ...(back ? {} : { oneSided: true as const }) };
+export class StudioModel {
+    /** Everything Studio shows. `graph` comes ready from the caller, with each device compared with its snapshot. */
+    static build(devices: readonly Device[], graph: Annotated, texts: DeviceTexts): StudioData {
+        const owners = new Map<string, Holder>();
+        for (const holder of Topology.holders(devices)) {
+            const key = Topology.keyOf(Address.host(holder.address))!;
+            if (!owners.has(key)) owners.set(key, holder);
         }
 
-        return { ...session, ...(session.remoteAs ? { far: `AS${session.remoteAs}` } : {}) };
-    });
-}
+        const attempt = <T>(work: () => T, otherwise: (error: Error) => T) => {
+            try {
+                return work();
+            } catch (error) {
+                return otherwise(error as Error);
+            }
+        };
 
-function cablesOf(devices: readonly Device[]): Cable[] {
-    const byName = new Map(devices.map((device) => [device.name, device]));
-    const drawn = new Set<string>();
-    const cables: Cable[] = [];
-
-    const vlansOf = (device: Device, portName: string) => {
-        const port = device.ports?.[portName];
-        const lag = port?.lag ? device.interfaces?.[port.lag] : undefined;
-        const carrier = lag?.type === "lag" ? lag : port;
-        const names = [carrier?.access_vlan, carrier?.native_vlan, ...(carrier?.trunk_vlans ?? [])].filter((name) => name !== undefined);
-
-        return [...new Set(names)].map((name) => `${name} (${device.vlans?.[name]?.id ?? "?"})`);
-    };
-
-    for (const device of devices) {
-        for (const [portName, port] of Object.entries(device.ports ?? {})) {
-            const link = port?.link;
-            if (!port || !link) continue;
-
-            const here = `${device.name} ${portName}`;
-            const there = `${link.device} ${link.port}`;
-            if (drawn.has(`${there}|${here}`)) continue;
-            drawn.add(`${here}|${there}`);
-
-            const farPort = byName.get(link.device)?.ports?.[link.port];
-            const linksBack = farPort?.link?.device === device.name && farPort.link.port === portName;
-
-            cables.push({
-                device: device.name,
-                port: portName,
-                farDevice: link.device,
-                farPort: link.port,
-                ...(port.lag ? { lag: port.lag } : {}),
-                ...(farPort?.lag ? { farLag: farPort.lag } : {}),
-                ...(port.description ? { description: port.description } : {}),
-                vlans: vlansOf(device, portName),
-                ...(linksBack ? {} : { oneSided: true as const }),
-            });
-        }
+        return {
+            graph,
+            devices,
+            ports: Object.fromEntries(
+                devices.map((device) => [
+                    device.name,
+                    attempt(
+                        () => Catalog.ports(device.platform, device.model),
+                        () => []
+                    ),
+                ])
+            ),
+            rendered: Object.fromEntries(
+                devices.map((device) => [
+                    device.name,
+                    attempt(
+                        () => texts.render(device),
+                        (error) => `Cannot be rendered: ${error.message}`
+                    ),
+                ])
+            ),
+            snapshots: Object.fromEntries(
+                devices.flatMap((device) => {
+                    const text = texts.snapshot(device);
+                    return text === undefined ? [] : [[device.name, text]];
+                })
+            ),
+            files: Object.fromEntries(devices.map((device) => [device.name, texts.files(device)])),
+            addresses: AddressSpace.report(devices),
+            sessions: StudioModel.sessionsOf(devices, owners),
+            cables: StudioModel.cablesOf(devices),
+            docs: StudioModel.schemaDocs(),
+        };
     }
 
-    return cables;
-}
-
-/** The directory Circuit is installed in: the nearest one up with its package.json. Its sources ship with it, in src: the schema, and the files of Studio's page. */
-export function packageRoot(): string | undefined {
-    let directory = dirname(fileURLToPath(import.meta.url));
+    /** The directory Circuit is installed in: the nearest one up with its package.json. Its sources ship with it, in src: the schema, and the files of Studio's page. */
+    static packageRoot(): string | undefined {
+        let directory = dirname(fileURLToPath(import.meta.url));
 
-    while (true) {
-        const manifest = join(directory, "package.json");
-        if (existsSync(manifest) && JSON.parse(readFileSync(manifest, "utf8")).name === "@takodotid/circuit") return directory;
+        while (true) {
+            const manifest = join(directory, "package.json");
+            if (existsSync(manifest) && JSON.parse(readFileSync(manifest, "utf8")).name === "@takodotid/circuit") return directory;
 
-        const parent = dirname(directory);
-        if (parent === directory) return undefined;
-        directory = parent;
+            const parent = dirname(directory);
+            if (parent === directory) return undefined;
+            directory = parent;
+        }
     }
-}
 
-/** The schema's descriptions, or none when its sources cannot be found. */
-function schemaDocs(): Record<string, TypeDocs> {
-    const root = packageRoot();
-    if (!root) return {};
+    private static sessionsOf(devices: readonly Device[], owners: Map<string, Holder>): Session[] {
+        const all = devices.flatMap((device) => {
+            const bgp = device.routing?.bgp;
+
+            return Object.entries(bgp?.neighbors ?? {}).map(([name, neighbor]): Session & { deviceObject: Device } => {
+                const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;
+                const settings = { ...group, ...neighbor };
+
+                return {
+                    deviceObject: device,
+                    device: device.name,
+                    name,
+                    address: neighbor.address,
+                    group: neighbor.group,
+                    remoteAs: settings.remote_as,
+                    role: settings.role,
+                    import: settings.import,
+                    export: settings.export,
+                    description: settings.description,
+                };
+            });
+        });
 
-    const sources = SCHEMA_FILES.map(([file]) => readFileSync(join(root, "src", "schema", file), "utf8"));
-    const docs: Record<string, TypeDocs> = {};
+        const ownerOf = (address: string) => owners.get(Topology.keyOf(address) ?? "")?.device;
 
-    for (const type of schemaTypes(sources).flat()) {
-        docs[type.name] = {
-            description: type.description,
-            includes: (type.includes ?? []).map((name) => name.replace(/<.*$/, "")),
-            fields: Object.fromEntries(
-                type.fields.map((field) => [field.path.replace(/\?$/, ""), { type: field.type, description: field.description }])
-            ),
-        };
+        return all.map(({ deviceObject, ...session }) => {
+            const far = ownerOf(session.address);
+
+            if (far && far !== deviceObject) {
+                // The session back is one of the same family: a v4 session back does not answer a v6 session.
+                const back = all.some(
+                    (other) =>
+                        other.deviceObject === far &&
+                        ownerOf(other.address) === deviceObject &&
+                        Address.family(other.address) === Address.family(session.address)
+                );
+                return { ...session, far: far.name, ...(back ? {} : { oneSided: true as const }) };
+            }
+
+            return { ...session, ...(session.remoteAs ? { far: `AS${session.remoteAs}` } : {}) };
+        });
     }
 
-    return docs;
-}
+    private static cablesOf(devices: readonly Device[]): Cable[] {
+        const byName = new Map(devices.map((device) => [device.name, device]));
+        const drawn = new Set<string>();
+        const cables: Cable[] = [];
+
+        const vlansOf = (device: Device, portName: string) => {
+            const port = device.ports?.[portName];
+            const lag = port?.lag ? device.interfaces?.[port.lag] : undefined;
+            const carrier = lag?.type === "lag" ? lag : port;
+            const names = [carrier?.access_vlan, carrier?.native_vlan, ...(carrier?.trunk_vlans ?? [])].filter(
+                (name) => name !== undefined
+            );
 
-/** Where a device is kept, relative to the config: the file that declares it, and its snapshot. Either is absent when it cannot be found. */
-export type DeviceFiles = { source?: string; snapshot?: string };
+            return [...new Set(names)].map((name) => `${name} (${device.vlans?.[name]?.id ?? "?"})`);
+        };
 
-/** How Studio learns what a device would run and what it ran, from the caller, which knows the adapters and the state directory. */
-export type DeviceTexts = {
-    /** What the device would run, as `circuit build` prints it. */
-    render: (device: Device) => string;
-    /** Its last snapshot, or undefined when it has none. */
-    snapshot: (device: Device) => string | undefined;
-    /** Its file and its snapshot's file. */
-    files: (device: Device) => DeviceFiles;
-};
+        for (const device of devices) {
+            for (const [portName, port] of Object.entries(device.ports ?? {})) {
+                const link = port?.link;
+                if (!port || !link) continue;
+
+                const here = `${device.name} ${portName}`;
+                const there = `${link.device} ${link.port}`;
+                if (drawn.has(`${there}|${here}`)) continue;
+                drawn.add(`${here}|${there}`);
+
+                const farPort = byName.get(link.device)?.ports?.[link.port];
+                const linksBack = farPort?.link?.device === device.name && farPort.link.port === portName;
+
+                cables.push({
+                    device: device.name,
+                    port: portName,
+                    farDevice: link.device,
+                    farPort: link.port,
+                    ...(port.lag ? { lag: port.lag } : {}),
+                    ...(farPort?.lag ? { farLag: farPort.lag } : {}),
+                    ...(port.description ? { description: port.description } : {}),
+                    vlans: vlansOf(device, portName),
+                    ...(linksBack ? {} : { oneSided: true as const }),
+                });
+            }
+        }
 
-/** Everything Studio shows. `graph` comes ready from the caller, with each device compared with its snapshot. */
-export function studioData(devices: readonly Device[], graph: Annotated, texts: DeviceTexts): StudioData {
-    const owners = new Map<string, Holder>();
-    for (const holder of holdersOf(devices)) {
-        const key = keyOf(host(holder.address))!;
-        if (!owners.has(key)) owners.set(key, holder);
+        return cables;
     }
 
-    const attempt = <T>(work: () => T, otherwise: (error: Error) => T) => {
-        try {
-            return work();
-        } catch (error) {
-            return otherwise(error as Error);
-        }
-    };
-
-    return {
-        graph,
-        devices,
-        ports: Object.fromEntries(
-            devices.map((device) => [
-                device.name,
-                attempt(
-                    () => portsOf(device.platform, device.model),
-                    () => []
-                ),
-            ])
-        ),
-        rendered: Object.fromEntries(
-            devices.map((device) => [
-                device.name,
-                attempt(
-                    () => texts.render(device),
-                    (error) => `Cannot be rendered: ${error.message}`
+    /** The schema's descriptions, or none when its sources cannot be found. */
+    private static schemaDocs(): Record<string, TypeDocs> {
+        const root = StudioModel.packageRoot();
+        if (!root) return {};
+
+        const sources = SchemaDocs.FILES.map(([file]) => readFileSync(join(root, "src", "schema", file), "utf8"));
+        const docs: Record<string, TypeDocs> = {};
+
+        for (const type of SchemaDocs.read(sources).flat()) {
+            docs[type.name] = {
+                description: type.description,
+                includes: (type.includes ?? []).map((name) => name.replace(/<.*$/, "")),
+                fields: Object.fromEntries(
+                    type.fields.map((field) => [field.path.replace(/\?$/, ""), { type: field.type, description: field.description }])
                 ),
-            ])
-        ),
-        snapshots: Object.fromEntries(
-            devices.flatMap((device) => {
-                const text = texts.snapshot(device);
-                return text === undefined ? [] : [[device.name, text]];
-            })
-        ),
-        files: Object.fromEntries(devices.map((device) => [device.name, texts.files(device)])),
-        addresses: addressesOf(devices),
-        sessions: sessionsOf(devices, owners),
-        cables: cablesOf(devices),
-        docs: schemaDocs(),
-    };
+            };
+        }
+
+        return docs;
+    }
 }

package/src/studio/git.ts

@@ -14,106 +14,111 @@ export type Commit = {
     subject: string;
 };
 
-/** The environment without git's own variables, such as GIT_DIR in a hook, which would point git at another repository than the directory's. */
-const environment = () => Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("GIT_")));
-
-/** Run git in a directory, and give what it printed, or fail with what it said. */
-function git(cwd: string, args: string[]): Promise<string> {
-    return new Promise((done, fail) => {
-        execFile("git", args, { cwd, env: environment(), maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => {
-            if (error) fail(new Error((stderr || error.message).trim()));
-            else done(stdout);
-        });
-    });
-}
+export class Git {
+    private static readonly FORMAT = "--format=%H%x1f%h%x1f%an%x1f%aI%x1f%s";
 
-const FORMAT = "--format=%H%x1f%h%x1f%an%x1f%aI%x1f%s";
+    /** The environment without git's own variables, such as GIT_DIR in a hook, which would point git at another repository than the directory's. */
+    private static environment(): Record<string, string | undefined> {
+        return Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("GIT_")));
+    }
 
-function commitsOf(text: string): Commit[] {
-    return text
-        .split("\n")
-        .filter(Boolean)
-        .map((line) => {
-            const [commit = "", short = "", author = "", date = "", subject = ""] = line.split("\x1f");
-            return { commit, short, author, date, subject };
+    /** Run git in a directory, and give what it printed, or fail with what it said. */
+    private static run(cwd: string, args: string[]): Promise<string> {
+        return new Promise((done, fail) => {
+            execFile("git", args, { cwd, env: Git.environment(), maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => {
+                if (error) fail(new Error((stderr || error.message).trim()));
+                else done(stdout);
+            });
         });
-}
+    }
 
-/** The top of the git repository the directory is in, or undefined when it is in none, or git is missing. */
-export async function gitTop(directory: string): Promise<string | undefined> {
-    try {
-        return (await git(directory, ["rev-parse", "--show-toplevel"])).trim();
-    } catch {
-        return undefined;
+    private static commitsOf(text: string): Commit[] {
+        return text
+            .split("\n")
+            .filter(Boolean)
+            .map((line) => {
+                const [commit = "", short = "", author = "", date = "", subject = ""] = line.split("\x1f");
+                return { commit, short, author, date, subject };
+            });
     }
-}
 
-/** The latest commits that changed any of these files, relative to the directory, newest first. */
-export async function history(directory: string, files: string[], limit = 50): Promise<Commit[]> {
-    if (!files.length) return [];
-    return commitsOf(await git(directory, ["log", `-n${limit}`, FORMAT, "--", ...files]));
-}
+    /** The top of the git repository the directory is in, or undefined when it is in none, or git is missing. */
+    static async top(directory: string): Promise<string | undefined> {
+        try {
+            return (await Git.run(directory, ["rev-parse", "--show-toplevel"])).trim();
+        } catch {
+            return undefined;
+        }
+    }
 
-/** Branches and tags to compare with, and the latest commits. */
-export async function references(directory: string): Promise<{ names: string[]; commits: Commit[] }> {
-    const names = (
-        await git(directory, [
-            "for-each-ref",
-            "--count=100",
-            "--sort=-committerdate",
-            "--format=%(refname:short)",
-            "refs/heads",
-            "refs/remotes",
-            "refs/tags",
-        ])
-    )
-        .split("\n")
-        .filter((name) => name && !name.endsWith("/HEAD"));
-
-    return { names, commits: commitsOf(await git(directory, ["log", "-n30", FORMAT])) };
-}
+    /** The latest commits that changed any of these files, relative to the directory, newest first. */
+    static async history(directory: string, files: string[], limit = 50): Promise<Commit[]> {
+        if (!files.length) return [];
+        return Git.commitsOf(await Git.run(directory, ["log", `-n${limit}`, Git.FORMAT, "--", ...files]));
+    }
 
-/** A branch, tag or commit, as the commit it names, or undefined when it names none. Only the characters a git name can hold are accepted. */
-export async function commitOf(directory: string, name: string): Promise<Commit | undefined> {
-    if (!/^[A-Za-z0-9][\w./@^~-]*$/.test(name)) return undefined;
+    /** Branches and tags to compare with, and the latest commits. */
+    static async references(directory: string): Promise<{ names: string[]; commits: Commit[] }> {
+        const names = (
+            await Git.run(directory, [
+                "for-each-ref",
+                "--count=100",
+                "--sort=-committerdate",
+                "--format=%(refname:short)",
+                "refs/heads",
+                "refs/remotes",
+                "refs/tags",
+            ])
+        )
+            .split("\n")
+            .filter((name) => name && !name.endsWith("/HEAD"));
+
+        return { names, commits: Git.commitsOf(await Git.run(directory, ["log", "-n30", Git.FORMAT])) };
+    }
+
+    /** A branch, tag or commit, as the commit it names, or undefined when it names none. Only the characters a git name can hold are accepted. */
+    static async commitOf(directory: string, name: string): Promise<Commit | undefined> {
+        if (!/^[A-Za-z0-9][\w./@^~-]*$/.test(name)) return undefined;
 
-    try {
-        const [commit] = commitsOf(await git(directory, ["log", "-n1", FORMAT, `${name}^{commit}`, "--"]));
-        return commit;
-    } catch {
-        return undefined;
+        try {
+            const [commit] = Git.commitsOf(await Git.run(directory, ["log", "-n1", Git.FORMAT, `${name}^{commit}`, "--"]));
+            return commit;
+        } catch {
+            return undefined;
+        }
     }
-}
 
-/**
- * Read the network as it was at a commit: check that commit out beside the project, in `.circuit/cache/`, which git ignores, gather it there with `gather`, then remove the checkout. The config is the file of that name in the same directory, `configDirectory`.
- *
- * The checkout sits inside the project, so its imports of Circuit resolve to the version installed now.
- */
-export async function networkAt(
-    configDirectory: string,
-    configPath: string,
-    commit: string,
-    gather: (configPath: string) => Promise<string>
-): Promise<string> {
-    const top = await gitTop(configDirectory);
-    if (!top) throw new Error("the config is not in a git repository");
-
-    const cache = join(configDirectory, ".circuit", "cache");
-    mkdirSync(cache, { recursive: true });
-    writeFileSync(join(cache, ".gitignore"), "# Written by Circuit Studio: checkouts of other commits, removed once read.\n*\n");
-
-    // A checkout left behind by a run that stopped is forgotten first.
-    await git(top, ["worktree", "prune"]);
-
-    const checkout = join(cache, commit.slice(0, 12));
-    await git(top, ["worktree", "add", "--detach", "--force", checkout, commit]);
-
-    try {
-        // Where the config sits inside the repository, as git says: comparing paths would trip on two spellings of one directory, such as Windows' short names.
-        const prefix = (await git(configDirectory, ["rev-parse", "--show-prefix"])).trim();
-        return await gather(join(checkout, prefix, basename(configPath)));
-    } finally {
-        await git(top, ["worktree", "remove", "--force", checkout]).catch(() => {});
+    /**
+     * Read the network as it was at a commit: check that commit out beside the project, in `.circuit/cache/`, which git ignores, gather it there with `gather`, then remove the checkout. The config is the file of that name in the same directory, `configDirectory`.
+     *
+     * The checkout sits inside the project, so its imports of Circuit resolve to the version installed now.
+     */
+    static async networkAt(
+        configDirectory: string,
+        configPath: string,
+        commit: string,
+        gather: (configPath: string) => Promise<string>
+    ): Promise<string> {
+        const top = await Git.top(configDirectory);
+        if (!top) throw new Error("the config is not in a git repository");
+
+        const cache = join(configDirectory, ".circuit", "cache");
+        mkdirSync(cache, { recursive: true });
+        writeFileSync(join(cache, ".gitignore"), "# Written by Circuit Studio: checkouts of other commits, removed once read.\n*\n");
+
+        // A checkout left behind by a run that stopped is forgotten first.
+        await Git.run(top, ["worktree", "prune"]);
+
+        const checkout = join(cache, commit.slice(0, 12));
+        // The checkout sits deep inside the project, so a long path in the repository passes the 260 characters Windows allows unless git is told otherwise.
+        await Git.run(top, ["-c", "core.longpaths=true", "worktree", "add", "--detach", "--force", checkout, commit]);
+
+        try {
+            // Where the config sits inside the repository, as git says: comparing paths would trip on two spellings of one directory, such as Windows' short names.
+            const prefix = (await Git.run(configDirectory, ["rev-parse", "--show-prefix"])).trim();
+            return await gather(join(checkout, prefix, basename(configPath)));
+        } finally {
+            await Git.run(top, ["-c", "core.longpaths=true", "worktree", "remove", "--force", checkout]).catch(() => {});
+        }
     }
 }