@takodotid/circuit 0.43.1 → 1.0.0-rc.2

package/src/config/merge.ts

@@ -0,0 +1,335 @@
+// `merge`, by MODEL.md's Merge rules for a language with import, and the types that check a merge in the editor. Each map remembers the file that wrote each of its keys, so an error names both.
+
+/** Where each key of a map was written, `file:line`. Not enumerable, so the JSON never shows it. */
+const WRITTEN = Symbol("written in");
+
+/** For a key written through a function in `lib/`, the line in `lib/` that called Circuit, `file:line`. Not enumerable either. */
+const INNER = Symbol("written through");
+
+type Obj = Record<string, unknown>;
+const isMap = (v: unknown): v is Obj => !!v && typeof v === "object" && !Array.isArray(v);
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
+
+/** Circuit's own folder, the one above this file's: its files are left out when looking for the user's file on the stack. */
+const CIRCUIT = decodeURIComponent(new URL("..", import.meta.url).pathname)
+    .replace(/^\/([A-Za-z]:)/, "$1")
+    .toLowerCase();
+
+/** Whether a file on the stack is one of Circuit's own. */
+const isCircuit = (file: string) => file.replaceAll("\\", "/").toLowerCase().startsWith(CIRCUIT);
+
+/** The user's frames on the stack of `error`, innermost first, each `file:line`. */
+export function userFrames(error: Error = new Error()): string[] {
+    return (error.stack ?? "")
+        .split("\n")
+        .map((line) => /\(?((?:[A-Za-z]:)?[^():]+\.ts):(\d+)/.exec(line))
+        .filter((m): m is RegExpExecArray => !!m && !isCircuit(m[1]!))
+        .map((m) => `${m[1]!.trim()}:${m[2]}`);
+}
+
+/**
+ * The user's file and line that called into Circuit: the outermost frame outside Circuit. A part a function in `lib/` builds is
+ * named after the file that called that function, such as the tenant's file, which is the one to change.
+ */
+export const caller = (): string => userFrames().at(-1) ?? "?";
+
+/** The innermost frame outside Circuit, such as the line in `lib/` that called `part`. */
+export const innerCaller = (): string => userFrames()[0] ?? "?";
+
+/** Marks every map in a value as written in `file`, and through `inner` when that is another line, where nothing marked it before. */
+export function mark<T>(value: T, file: string, inner = file): T {
+    if (Array.isArray(value)) value.forEach((v) => mark(v, file, inner));
+    else if (isMap(value)) {
+        if (!Object.hasOwn(value, WRITTEN)) {
+            Object.defineProperty(value, WRITTEN, { value: Object.fromEntries(Object.keys(value).map((k) => [k, file])) });
+            if (inner !== file)
+                Object.defineProperty(value, INNER, { value: Object.fromEntries(Object.keys(value).map((k) => [k, inner])) });
+        }
+        for (const v of Object.values(value)) mark(v, file, inner);
+    }
+    return value;
+}
+
+/** Where each key of a map was written, for an error that names the file. */
+export const writtenIn = (map: object, key: string): string => (map as { [WRITTEN]?: Record<string, string> })[WRITTEN]?.[key] ?? "?";
+
+/** The line in `lib/` a key was written through, or nothing. */
+const innerIn = (map: object, key: string): string | undefined => (map as { [INNER]?: Record<string, string> })[INNER]?.[key];
+
+/** Reads a file of the project as its lines. Circuit gives it when it reads a project (src/project/project.ts): the project's editor has no Node types, so this file reads none itself. */
+export const source = { read: (_file: string): string => "" };
+
+/** Each file's lines, read once. */
+const lines = new Map<string, string[]>();
+const escape = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * From `written`, `file:line`, the first line at or after it that writes each of `path` in turn, as `file:line`, or undefined when the last
+ * of `path` is not found. A key not found before the last is skipped.
+ */
+function find(written: string, path: string[]): string | undefined {
+    const colon = written.lastIndexOf(":");
+    if (colon < 0) return undefined;
+    const file = written.slice(0, colon);
+    let line = Number(written.slice(colon + 1)) - 1;
+    if (!lines.has(file))
+        try {
+            lines.set(file, source.read(file).split("\n"));
+        } catch {
+            lines.set(file, []);
+        }
+    const text = lines.get(file)!;
+    let found = -1;
+    path.forEach((name, p) => {
+        const writes = new RegExp(`(^|[\\s{,])(["']?)${escape(name)}\\2\\s*:`);
+        const i = text.findIndex((t, n) => n >= line && !t.trim().startsWith("//") && writes.test(t));
+        if (i >= 0) line = found = i;
+        else if (p === path.length - 1) found = -1;
+    });
+    return found >= 0 ? `${file}:${found + 1}` : undefined;
+}
+
+/**
+ * Where `key` of `map` is written, as `file:line: `, or nothing when no file is known. `writtenIn` knows the line that made the map (a
+ * network's `device()`, a `literal`, a `part`); from there, the file is read for the first line that writes each of `path` in turn,
+ * `path` ending in the key: `["vlans", "exchange-a"]`. A key written through `lib/` is looked for there first. When the key is not found,
+ * the line that made the map stays.
+ */
+export function writtenAt(map: unknown, key: string, path: string[] = [key]): string {
+    const outer = writtenIn(map as object, key);
+    const inner = innerIn(map as object, key);
+    const at = (inner && find(inner, path)) ?? find(outer, path) ?? (outer === "?" ? undefined : outer);
+    return at ? `${at}: ` : "";
+}
+
+/** From `written`, `file:line`, the line that writes the last of `path`, as `file:line: `; `written` itself when it is not found. */
+export const lineOf = (written: string, path: string[]): string => `${find(written, path) ?? written}: `;
+
+/**
+ * An ordered list, by its path: a chain's rules, NAT, an ACL, a route policy, policy routing. Under a source, the hostname comes
+ * first (`edge-01.firewall.nat.source`). It is written whole in one place, never joined.
+ */
+const ORDERED =
+    /(^|\.)(firewall\.filter\.[^.]+\.rules|firewall\.nat\.(source|destination)|switching\.acls\.[^.]+|routing\.policies\.[^.]+|routing\.policy_routing)$/;
+export const isOrdered = (path: string) => ORDERED.test(path);
+
+/** A value that is one value, compared whole and never merged key by key: a secret, a link, a threshold, a port range. */
+const isOneValue = (key: string, v: Obj) =>
+    key === "link" ||
+    "secret" in v ||
+    "secret_file" in v ||
+    "pps" in v ||
+    "percent" in v ||
+    ("min" in v && "max" in v && Object.keys(v).length === 2);
+
+/** Marks a rule list `part` made. Not enumerable, so nothing else sees it. */
+const RULE_LIST = Symbol("rule list");
+export const ruleList = <T extends object>(list: T): T => Object.defineProperty(list, RULE_LIST, { value: true });
+const isRuleList = (v: unknown) => Array.isArray(v) && Object.hasOwn(v, RULE_LIST);
+
+/**
+ * Merges `b` into a copy of `a`. Two rule lists `part` made, at one path that is no ordered list, join in order with every rule kept:
+ * each tenant's router input rules, one tenant after another, for the router to place.
+ */
+function mergeTwo(a: Obj, b: Obj, path: string): Obj {
+    const out: Obj = { ...a };
+    const written: Record<string, string> = {};
+    const inner: Record<string, string> = {};
+    const note = (from: Obj, key: string) => {
+        written[key] = writtenIn(from, key);
+        const through = innerIn(from, key);
+        if (through) inner[key] = through;
+        else delete inner[key];
+    };
+    for (const key of Object.keys(a)) note(a, key);
+
+    for (const [key, value] of Object.entries(b)) {
+        const here = path ? `${path}.${key}` : key;
+        if (!(key in out)) {
+            out[key] = value;
+            note(b, key);
+            continue;
+        }
+        const old = out[key];
+        const both = `in ${written[key]} and in ${writtenIn(b, key)}`;
+        if (Array.isArray(old) && Array.isArray(value) && isOrdered(here))
+            throw new Error(
+                `${here} is an ordered list, written ${both}. Write it whole in one place, and place the other's rules in it with merge.`
+            );
+        if (isRuleList(old) && isRuleList(value)) out[key] = ruleList([...(old as unknown[]), ...(value as unknown[])]);
+        else if (Array.isArray(old) && Array.isArray(value)) out[key] = [...old, ...value.filter((v) => !old.some((o) => same(o, v)))];
+        else if (isMap(old) && isMap(value) && !isOneValue(key, old) && !isOneValue(key, value)) out[key] = mergeTwo(old, value, here);
+        else if (!same(old, value))
+            throw new Error(
+                `${here} is written twice with two values: ${JSON.stringify(old)} in ${written[key]}, and ${JSON.stringify(value)} in ${writtenIn(b, key)}. One name holds one value: rename one, or make both the same.`
+            );
+    }
+
+    Object.defineProperty(out, WRITTEN, { value: written });
+    if (Object.keys(inner).length) Object.defineProperty(out, INNER, { value: inner });
+    return out;
+}
+
+/** Merges parts in order. The file of a part not marked yet is `file`. */
+export function mergeAll(parts: readonly unknown[], file: string, path = ""): Obj {
+    let out: Obj = {};
+    for (const part of parts) if (part !== undefined) out = mergeTwo(out, mark(part as Obj, file), path);
+    return out;
+}
+
+// ---------- `merge([...])`: one list or one map, by where it lands ----------
+
+/** What a `merge` call was given, flat, and the file that called it. Not enumerable, so nothing else sees it. */
+const MADE = Symbol("merge items");
+type Made = { [MADE]: { values: readonly unknown[]; file: string } };
+const madeBy = (v: unknown) => (v && typeof v === "object" && Object.hasOwn(v, MADE) ? (v as Made)[MADE] : undefined);
+
+/** The items, flat: a list in the items gives its own items in its place, in order. */
+const flat = (items: readonly unknown[]): unknown[] => items.flatMap((v) => (Array.isArray(v) ? flat(v) : [v]));
+
+/**
+ * What `merge` returns before it lands: a list when an item is a list or no map, else the maps merged. The same rule the editor uses
+ * for a `merge` that lands in no field. Where it lands decides (`resolve`).
+ */
+export function made(items: readonly unknown[], file: string): object {
+    const values = flat(items);
+    // One map given twice, such as a tenant: its data would be kept once and its rules twice, and nothing would say so.
+    if (values.some((v, i) => isMap(v) && values.indexOf(v) !== i))
+        throw new Error(`${file}: merge is given the same value twice. Give each once.`);
+    const isList = items.some(Array.isArray) || values.some((v) => !isMap(v));
+    let out: object = [...values];
+    if (!isList)
+        try {
+            out = mergeAll(values, file);
+        } catch (error) {
+            // Maps that clash may be single rules, which a list field takes as they are: they stay a list until they land (`resolve`).
+            // A field of them read before, such as `tenants.parts` of two tenants with one VLAN name, says what clashed, naming both
+            // values and where each is written, not that the field is missing. Never `then`, which a promise reads.
+            const clash = `${file}: merge: ${error instanceof Error ? error.message : String(error)}`;
+            for (const key of new Set(values.flatMap((v) => Object.keys(v as object))))
+                if (key !== "then")
+                    Object.defineProperty(out, key, {
+                        get: () => {
+                            throw new Error(clash);
+                        },
+                    });
+        }
+    return Object.defineProperty(out, MADE, { value: { values, file } });
+}
+
+/**
+ * Lists of the model whose items are maps, besides the ordered ones: there, a merge of single maps is a list of them, never one map.
+ * Taken from Circuit's schema (every array of objects under a device).
+ */
+const MAP_LISTS =
+    /(^|\.)(routing\.(static_routes|rpki)|monitoring\.(syslog|flow_export\.collectors)|system\.vdoms\.[^.]+\.static_routes|interfaces\.[^.]+\.[^.]+\.(addresses|peers|vrrp)|services\.dhcp_server\.[^.]+\.reservations)$/;
+
+/**
+ * Every `merge` in a value, made again by the field it lands in, `path`, which Circuit knows from the model:
+ *
+ * - in an ordered list (`isOrdered`), its items flat, in order, each kept as it is;
+ * - in a list of maps (`MAP_LISTS`), or when an item is no map (a VLAN name, a port), its items flat, the same item twice kept once;
+ * - anywhere else, its items merged as maps, by `mergeAll`.
+ *
+ * So two single rules, `merge([rule_a, rule_b])`, are two rules in a chain and never one map: the chain's path says so. A source in a
+ * device's `include` lands at the top, so it is a map, keyed by hostname. Changes maps and lists in place, so a rule keeps its identity.
+ */
+export function resolve(value: unknown, path: string): unknown {
+    const by = madeBy(value);
+    if (by) {
+        const { values, file } = by;
+        if (isOrdered(path)) value = [...values];
+        else if (MAP_LISTS.test(path) || values.some((v) => !isMap(v)))
+            value = values.filter((v, i, all) => all.findIndex((o) => same(o, v)) === i);
+        else if (Array.isArray(value))
+            try {
+                value = mergeAll(values, file, path);
+            } catch (error) {
+                throw new Error(`${file}: merge: ${error instanceof Error ? error.message : String(error)}`);
+            }
+    }
+    if (Array.isArray(value)) value.forEach((v, i) => (value[i] = resolve(v, `${path}[]`)));
+    else if (isMap(value))
+        for (const [k, v] of Object.entries(value)) if (v && typeof v === "object") value[k] = resolve(v, path ? `${path}.${k}` : k);
+    return value;
+}
+
+// ---------- the types: what the editor checks ----------
+
+/**
+ * Two parts merged as `merge` merges them: maps key by key, lists joined, anything else the later one. A key one side writes out keeps
+ * its own type, even when the other side has an index signature.
+ */
+export type Merge2<A, B> = [A] extends [readonly (infer X)[]]
+    ? [B] extends [readonly (infer Y)[]]
+        ? readonly (X | Y)[]
+        : B
+    : [A] extends [object]
+      ? [B] extends [object]
+          ? {
+                [K in keyof A | keyof B]: K extends WrittenKeys<A>
+                    ? K extends WrittenKeys<B>
+                        ? Merge2<A[K], B[K]>
+                        : A[K]
+                    : K extends WrittenKeys<B>
+                      ? B[K]
+                      : (K extends keyof A ? A[K] : never) | (K extends keyof B ? B[K] : never);
+            }
+          : B
+      : B;
+
+/** Parts merged in order. */
+export type Merged<T extends readonly unknown[], Acc = {}> = T extends readonly [infer H, ...infer R] ? Merged<R, Merge2<Acc, H>> : Acc;
+
+/** The first `N` parts. */
+type Take<T extends readonly unknown[], N extends number, Acc extends unknown[] = []> = Acc["length"] extends N
+    ? Acc
+    : T extends readonly [infer H, ...infer R]
+      ? Take<R, N, [...Acc, H]>
+      : Acc;
+
+/** The parts before position `I` of `T`, merged, with `First` before them. */
+export type Before<T extends readonly unknown[], I, First = {}> = I extends `${infer N extends number}`
+    ? Merged<[First, ...Take<T, N>]>
+    : First;
+
+/** The keys written out, not those of an index signature. */
+type WrittenKeys<A> = keyof { [K in keyof A as number extends K ? never : string extends K ? never : K]: 0 };
+
+/** Keys to look into: a map's, without symbols. */
+type Keys<B> = keyof B & (string | number);
+
+/** The path of an ordered list, as `isOrdered` reads it. */
+type OrderedPath =
+    | `${string}firewall.filter.${string}.rules`
+    | `${string}firewall.nat.${"source" | "destination"}`
+    | `${string}switching.acls.${string}`
+    | `${string}routing.policies.${string}`
+    | `${string}routing.policy_routing`;
+
+/**
+ * Every place where part `B` clashes with what came before it, `A`, said in words: an ordered list both write, or another value at
+ * one path. Any other list never clashes: it joins.
+ */
+type ClashPaths<B, A, Path extends string = ""> = {
+    [K in Keys<B>]: K extends WrittenKeys<A>
+        ? [B[K]] extends [readonly unknown[]]
+            ? `${Path}${K}` extends OrderedPath
+                ? `${Path}${K} is an ordered list written in two places`
+                : never
+            : [B[K]] extends [object]
+              ? ClashPaths<B[K], A[K & keyof A], `${Path}${K}.`>
+              : [B[K]] extends [A[K & keyof A]]
+                ? never
+                : [A[K & keyof A]] extends [B[K]]
+                  ? never
+                  : `${Path}${K} is written twice`
+        : never;
+}[Keys<B>];
+
+/**
+ * What part `B` must also be, after `A`: nothing more when nothing clashes, and else a property named after each clash that it lacks,
+ * so the editor says `Property '"edge-01.firewall.nat.source is an ordered list written in two places"' is missing`. An
+ * ordered list is written whole in one place. Any other value written twice must be the same.
+ */
+export type Clash<B, A> = [ClashPaths<B, A>] extends [never] ? unknown : { [P in ClashPaths<B, A>]: true };

package/src/config/models.ts

@@ -0,0 +1,70 @@
+// Every platform Circuit runs on, every model it knows, each model's ports and how it prints them. The types read from here, so a model or port that does not exist fails to compile.
+
+import { models as fortios } from "../platforms/fortios/models";
+import { models as junos } from "../platforms/junos/models";
+import { models as raisecom } from "../platforms/raisecom-ros/models";
+import { models as routeros } from "../platforms/routeros/models";
+import { models as vrp } from "../platforms/vrp/models";
+
+/** What a model's hardware holds, where a real device held less than its datasheet lists. `circuit validate` checks a config against it. */
+export type ModelLimits = {
+    /** The most member ports one LAG may have. More is an error. */
+    readonly lag_members?: number;
+    /** About how many switch rules the switch chip held. More is a warning: a rule the chip cannot hold is invalid, and so is every rule after it, without a log line. */
+    readonly switch_rules?: number;
+    /** How many distinct port ranges the switch rules held. More is a warning, for the same reason. */
+    readonly switch_port_ranges?: number;
+};
+
+/** One hardware model: its ports per speed class, how the platform spells a port, and what its hardware holds. */
+export type ModelSpec = {
+    /** How many ports of each speed class, such as `{ "10g": 48 }`. A port is `<class>-<position>`, such as `10g-4`. */
+    readonly ports: Readonly<Record<string, number>>;
+    /** How the platform spells a port of each class. `{n}` is the position within the class; `{n+4}` and `{n-1}` shift it, because some platforms number every port in one run or count from 0. */
+    readonly spelling: Readonly<Record<string, string>>;
+    /** What the hardware held, where a real device held less than its datasheet. */
+    readonly limits?: ModelLimits;
+};
+
+/** Every model of every platform: each platform's own list, in its folder under `src/platforms/`. */
+export const MODELS = { routeros, vrp, "raisecom-ros": raisecom, junos, fortios } as const satisfies Record<
+    string,
+    Record<string, ModelSpec>
+>;
+
+type Models = typeof MODELS;
+
+/** The operating system of a device. It decides which adapter renders and applies the device. */
+export type Platform = keyof Models;
+
+/** A hardware model the platform runs on. It decides which port names exist. */
+export type Model<P extends Platform> = P extends Platform ? keyof Models[P] & string : never;
+
+type Upto<N extends number, A extends unknown[] = [], R = never> = A["length"] extends N
+    ? R
+    : Upto<N, [...A, 0], R | `${[...A, 0]["length"]}`>;
+type SpecOf<P extends Platform, M extends string> = P extends Platform ? (M extends keyof Models[P] ? Models[P][M] : never) : never;
+type PortsOf<P extends Platform, M extends string> = SpecOf<P, M> extends { ports: infer Ports } ? Ports : never;
+
+/** A port of the model, `<speed class>-<position>`: `10g-1` to `10g-48` on a model with 48 10G ports. */
+export type PortName<P extends Platform, M extends string> = {
+    [S in keyof PortsOf<P, M>]: `${S & string}-${Upto<PortsOf<P, M>[S] & number>}`;
+}[keyof PortsOf<P, M>];
+
+/** Every port a model has, in order. */
+export function portsOf(platform: string, model: string): string[] {
+    const spec = (MODELS as Record<string, Record<string, ModelSpec>>)[platform]?.[model];
+    if (!spec) return [];
+    return Object.entries(spec.ports).flatMap(([speed, count]) => Array.from({ length: count }, (_, i) => `${speed}-${i + 1}`));
+}
+
+/** A port as the platform prints it, from the model's `spelling`: `10g-2` on a FG-3700D is `port6`. The port as written when the model has no spelling for it. */
+export function spell(platform: string, model: string, port: string): string {
+    const spec = (MODELS as Record<string, Record<string, ModelSpec>>)[platform]?.[model];
+    const [speed = "", n = ""] = port.split("-");
+    const pattern = spec?.spelling[speed];
+    return pattern ? pattern.replace(/\{n([+-]\d+)?\}/g, (_, shift: string | undefined) => String(Number(n) + Number(shift ?? 0))) : port;
+}
+
+/** The platforms where a VLAN is only its number: no name, no description. A VLAN interface holds its own. Circuit drops a VLAN's `description` there, as their renderers do. */
+export const NUMBERED_VLANS: readonly Platform[] = ["raisecom-ros", "fortios"];

package/src/config/monitoring.ts

@@ -0,0 +1,64 @@
+// What the box reports to collectors: `monitoring.snmp`, `.syslog`, `.flow_export`, `.transceivers`.
+
+import type { IP, Secret, Severity } from "./common";
+import type { Service } from "./management";
+
+/** One SNMPv3 user. */
+export type SnmpUser = {
+    /** How messages are authenticated. */
+    auth: "sha1" | "sha256";
+    /** The authentication passphrase. */
+    auth_password: Secret;
+    /** How messages are encrypted. */
+    privacy: "aes128" | "des";
+    /** The encryption passphrase. */
+    privacy_password: Secret;
+};
+
+/** One syslog collector. */
+export type SyslogServer = {
+    /** Where the collector listens. */
+    address: IP;
+    /** UDP port. 514 when absent. */
+    port?: number;
+    /** The least severe message sent. */
+    level: Severity;
+};
+
+/** Export flow records or packet samples to collectors. */
+export type FlowExport<I extends string> = {
+    /** The record format. */
+    protocol: "sflow" | "netflow-v9" | "ipfix";
+    /** Where records are sent. */
+    collectors: readonly {
+        /** Where the collector listens. */
+        address: IP;
+        /** UDP port. When absent: 6343 for sFlow and 4739 for IPFIX (IANA), 2055 for NetFlow v9 (the usual one). */
+        port?: number;
+    }[];
+    /** Sample one packet in this many. Every packet when absent, on a platform that can export every packet. */
+    sampling?: number;
+    /** Some of the device's ports and interfaces: where traffic is observed. Every interface when absent. */
+    interfaces?: readonly I[];
+};
+
+/** What the device reports to collectors. `I` is the device's ports and interfaces. */
+export type Monitoring<I extends string> = {
+    /** Polling by SNMP. */
+    snmp?: Service & {
+        /** Read-only community for version 2c. Version 2c is off when absent. */
+        community?: Secret;
+        /** Version 3 users, keyed by name. */
+        users?: Record<string, SnmpUser>;
+        /** Who to contact about the device. */
+        contact?: string;
+        /** Where the device is. */
+        location?: string;
+    };
+    /** Log messages sent to syslog collectors, each from its own `level` up. */
+    syslog?: readonly SyslogServer[];
+    /** Flow records or packet samples sent to collectors. */
+    flow_export?: FlowExport<I>;
+    /** Read optic temperature, power and voltage. */
+    transceivers?: boolean;
+};

package/src/config/network.ts

@@ -0,0 +1,180 @@
+// The whole network, what `circuit()` in `circuit.ts` at a project's root takes: `asn`, `prefixes`, `communities`, `sites`, `checks`, `integrations`. Its devices register with it.
+
+import type { Prefix, Secret } from "./common";
+import type { CommunityRequest, CommunityScheme, SchemeCheck } from "./communities";
+import type { AnyDevice } from "./device";
+import type { RouteRule } from "./routing";
+
+/**
+ * The network's own prefixes, in groups of your choosing, such as a location (`id01`), each a map of named prefixes:
+ * `{ region_a: { v4_1: "192.0.2.0/24", v6_1: "2001:db8::/48" } }`.
+ */
+export type Prefixes = Readonly<Record<string, Readonly<Record<string, Prefix>>>>;
+
+/**
+ * One BGP community the network defines, in the community description format of the NLNOG Ring looking glass, which bgp.tools also reads.
+ */
+export type Community = {
+    /** The community. `nnn` stands for any number, `x` for one digit and `a-b` for a range, such as `65535:0:nnn`. */
+    community: string;
+    /** What it means. `$0`, `$1` and so on stand for what each wildcard matched, such as `do not announce to AS$0`. */
+    description: string;
+};
+
+/** A site: a data centre or an office. */
+export type Site = {
+    /** What and where the site is. */
+    description?: string;
+    /**
+     * The site's number, the last part of the community `learned_at_site` tags a route with, such as `64500:2:0`. Only Circuit reads
+     * it: the resolved network leaves it out.
+     */
+    number?: number;
+};
+
+/** Circuit's built-in checks, by name. A check is on when it is here. `D` is the network's device names: `circuit validate` checks each is a device of the network. */
+export type Checks<D extends string> = {
+    /**
+     * Where traffic from outside, before anything filters it, may go. The untrusted VLANs are those written `untrusted: true` in
+     * `switching.vlans`; every other VLAN is trusted, so a VLAN added later is protected without being listed. `untrusted: true` is
+     * allowed only while this check is on.
+     */
+    untrusted_vlans?: {
+        /** The devices that filter: the only ones that may give an untrusted VLAN an address, and the only ones a port carrying both kinds may face. */
+        filtering_devices: readonly D[];
+        /** Links between two switches that may carry both kinds, each named by its two devices: a site's switch extended to another building, with an exchange's VLAN and its own management on one cable. Neither end gives an untrusted VLAN an address. */
+        mixed_links?: readonly (readonly [D, D])[];
+    };
+    /** Every BGP export ends in a reject that matches everything, so nothing leaves by accident. An export to a neighbor whose `role` is `customer` is left out. */
+    exports_end_in_reject?: true;
+    /** Every BGP import ends in a rule that decides for every route, an accept or a reject without a match. */
+    imports_end_in_accept_or_reject?: true;
+    /** A native VLAN is a dead end: native on one trunk (a port or a LAG) of a device at most, and never an access VLAN or a tagged VLAN anywhere on that device. */
+    native_vlans_are_dead_ends?: true;
+    /** A GRE or VXLAN tunnel's local address is outside what the neighbors over it are offered, or their replies route back into the tunnel. */
+    tunnels_outside_offered?: true;
+    /**
+     * One VLAN name has one ID on every device of the network. Circuit runs it when it reads the project, and `circuit validate` stops on a VLAN
+     * with two IDs, naming both devices and where each is written. So the resolved network always passes it, and leaves it out.
+     */
+    same_vlan_ids?: true;
+};
+
+/**
+ * What one of your own checks found: a sentence, and the device and path it is about, when it knows them. Circuit prints it with the
+ * file and line that write that path, as for its own errors: `sites/site-a/switch-01.ts:21: tenants_dont_clash: switch-01: interfaces.ethernet.10g-2: ...`.
+ */
+export type Finding = {
+    /** What is wrong, in a sentence. */
+    message: string;
+    /** The device it is about, by name. */
+    device?: string;
+    /** Where in that device, dot by dot, as Circuit names a field: `interfaces.ethernet.10g-2`, `routing.policies.transit-a-export[2]`. */
+    path?: string;
+};
+
+/**
+ * A device as your own checks read it: as it will run. Each BGP neighbor holds what it takes from its group. Each policy is route rules
+ * only: a `call` is the called policy's rules, and a `{ communities }` rule the rules it means there. `management.allow` written as an
+ * address set's name is that set's addresses, and a rule's interface set is its interfaces. A copy: a check changes nothing.
+ */
+export type ResolvedDevice = Omit<AnyDevice, "routing" | "management"> & {
+    readonly routing?: Omit<NonNullable<AnyDevice["routing"]>, "policies"> & {
+        readonly policies?: Readonly<Record<string, readonly RouteRule<string>[]>>;
+    };
+    readonly management?: Omit<NonNullable<AnyDevice["management"]>, "allow"> & { readonly allow?: readonly Prefix[] };
+};
+
+/** The network as your own checks read it: its AS, its prefixes, and each device as it will run, its parts merged in. */
+export type ResolvedNetwork = { readonly asn?: number; readonly prefixes: Prefixes; readonly devices: readonly ResolvedDevice[] };
+
+/**
+ * A check of your own, beside Circuit's: it reads the network resolved, as its devices will run it, and returns what is wrong. Nothing
+ * found is an empty list. `circuit validate` runs it; the resolved network never shows it.
+ */
+export type Check = (network: ResolvedNetwork) => readonly Finding[];
+
+/** Where a network's secrets are: a file of `NAME="value"` lines, each value encrypted, changed with `circuit secrets`. */
+export type NetworkSecrets = {
+    /** The file, relative to the project, such as `.circuit/lab-secrets` for a lab network with its own password. Commit it. */
+    file: string;
+};
+
+/** Systems Circuit keeps in step with the config. */
+export type Integrations = {
+    /** Keeps the network's PeeringDB record in step with the config: `circuit peeringdb`. Needs `asn`. */
+    peeringdb?: {
+        /** An API key with write access to the network's record. */
+        api_key: Secret;
+    };
+    /** Keeps LibreNMS monitoring every device, under its name, with its SNMP credentials and location, and in a group for its site: `circuit librenms`. */
+    librenms?: {
+        /** Where LibreNMS is, such as `https://librenms.example.com`. */
+        url: `http://${string}` | `https://${string}`;
+        /** An API token that can add and change devices and device groups. */
+        api_token: Secret;
+    };
+    /** Keeps NetBox in step with the config: `circuit netbox`. Each device's `site` and `role` place it there. */
+    netbox?: {
+        /** Where NetBox is, such as `https://netbox.example.com`. */
+        url: `http://${string}` | `https://${string}`;
+        /** An API token that can write. */
+        api_token: Secret;
+    };
+};
+
+/**
+ * What a device takes from its network, for the editor: whether `untrusted_vlans` is on, whether the network writes `communities`, and
+ * the scheme's groups and requests.
+ */
+export type NetworkFacts = { untrusted: boolean; communities: boolean; groups: string; requests: string };
+
+/** Any network's facts: what a part, or a device seen from the network, takes. */
+export type AnyFacts = { untrusted: true; communities: true; groups: string; requests: CommunityRequest };
+
+/** Whether a site has a number, which `learned_at_site` needs. */
+export type Numbered<Sites> = true extends (
+    Sites[keyof Sites] extends infer X ? (X extends { readonly number: number } ? true : false) : never
+)
+    ? true
+    : false;
+
+/**
+ * What `circuit()` takes: the whole network but its devices, which register with it from their own files. `Sites` is its sites as
+ * written. `Own` is the `checks` as written: a key that is not one of Circuit's is a check of your own. `C` is the `communities` as
+ * written. `P` is the `prefixes` as written.
+ */
+export type NetworkSettings<
+    Sites extends Readonly<Record<string, Site>>,
+    Asn extends number,
+    Own = {},
+    C = undefined,
+    P extends Prefixes = {},
+> = {
+    /** The AS the network operates. A device's BGP runs it, unless the device writes `routing.bgp.asn`. */
+    asn?: Asn;
+    /**
+     * The network's own prefixes, in groups of your choosing, each a map of named prefixes: `{ region_a: { v4_1: "192.0.2.0/24" } }`.
+     * Devices use them by name, `as64500.prefixes.id01.v4_1`, and your own checks read them. The resolved network keeps them, for the
+     * commands that would use them: PeeringDB's prefix counts, and RPKI and IRR checks.
+     */
+    prefixes?: P;
+    /**
+     * The network's BGP large communities, `asn:code:value` (RFC 8092), used as RFC 8195 describes. Written once here: a neighbor group
+     * says which `groups` it is in, and a policy places `{ communities: "import" }` or `{ communities: "export" }`. Circuit writes the
+     * catalogue from it, for a looking glass or bgp.tools.
+     */
+    communities?: C & CommunityScheme & SchemeCheck<C, Numbered<Sites>>;
+    /** Each site, by name: a data centre or an office. The NetBox site and LibreNMS group of that name. A device's `site` is one of these, and each has a device. */
+    sites: Sites;
+    /**
+     * Circuit's built-in checks, turned on by name, with their settings, and your own: any other name takes a function that reads the
+     * network and returns what it found (`Check`). `circuit validate` runs them all. `untrusted: true` on a VLAN is allowed only while
+     * `untrusted_vlans` is here.
+     */
+    checks?: Own & Checks<string> & { [K in Exclude<keyof Own, keyof Checks<string>>]: Check };
+    /** Systems Circuit keeps in step with the config. */
+    integrations?: Integrations;
+    /** Where the network's secrets are. `.circuit/secrets` when absent. */
+    secrets?: NetworkSecrets;
+};