@takodotid/circuit 0.34.2 → 0.35.0

package/src/core/address-space.ts

@@ -0,0 +1,320 @@
+// Every address the config uses, by prefix, and what is still free: what `circuit addresses` prints. It reads the config only, so an address a device gave out by itself, such as a DHCP lease, is not known.
+
+import type { Device } from "../schema";
+import { Address } from "./address";
+import { Topology } from "./topology";
+
+/** One address or range in a segment, and what holds it. */
+export type Use = {
+    /** An address, or `first-last` for a range. */
+    address: string;
+    what: string;
+};
+
+/** A prefix our devices have addresses in. */
+export type Segment = {
+    prefix: string;
+    uses: Use[];
+    /** How many addresses no one uses, as a number written out, since an IPv6 count does not fit a JavaScript number. */
+    free: string;
+    /** The lowest free address, when there is one. */
+    next?: string;
+};
+
+/** A prefix in use without being a segment: a loopback's address, or a block routed elsewhere. */
+export type Block = {
+    prefix: string;
+    what: string;
+};
+
+/** Space the network owns: a prefix it originates in BGP, or one asked for. Everything in use inside it, and what is free. */
+export type Space = {
+    prefix: string;
+    /** Why it is listed, such as `originated by edge-01`. */
+    owner: string;
+    segments: Segment[];
+    blocks: Block[];
+    /** The fewest prefixes that cover what nothing uses. */
+    free: string[];
+};
+
+export type AddressReport = {
+    spaces: Space[];
+    /** What is in use outside every space. Left out when a prefix is asked for. */
+    elsewhere: { segments: Segment[]; blocks: Block[] };
+};
+
+/** A use as a range of numbers, for counting. */
+type Taken = { first: bigint; last: bigint };
+
+export class AddressSpace {
+    private static isHostRoute(cidr: string): boolean {
+        return Address.split(cidr).len === Address.bits(Address.split(cidr).family);
+    }
+
+    private static numberOf(address: string): bigint {
+        return Address.toNumber(address)!;
+    }
+
+    /** Addresses a segment can give out: IPv4 leaves out the network and broadcast addresses below /31, and IPv6 the subnet-router anycast address. */
+    private static usable(prefix: string): Taken {
+        const { first, last, family } = Address.range(prefix);
+        const { len } = Address.split(prefix);
+
+        if (family === "ipv4" && len <= 30) return { first: first + 1n, last: last - 1n };
+        if (family === "ipv6" && len < 127) return { first: first + 1n, last };
+
+        return { first, last };
+    }
+
+    /** Ranges merged, so overlapping ones count once. */
+    private static merged(ranges: Taken[]): Taken[] {
+        const sorted = [...ranges].sort((a, b) => (a.first < b.first ? -1 : a.first > b.first ? 1 : 0));
+        const result: Taken[] = [];
+
+        for (const range of sorted) {
+            const previous = result.at(-1);
+            if (previous && range.first <= previous.last + 1n) previous.last = range.last > previous.last ? range.last : previous.last;
+            else result.push({ ...range });
+        }
+
+        return result;
+    }
+
+    /** What is inside `within` and not in any of the ranges. */
+    private static gaps(within: Taken, taken: Taken[]): Taken[] {
+        const result: Taken[] = [];
+        let cursor = within.first;
+
+        for (const range of AddressSpace.merged(taken)) {
+            if (range.last < within.first || range.first > within.last) continue;
+            if (range.first > cursor) result.push({ first: cursor, last: range.first - 1n });
+            if (range.last + 1n > cursor) cursor = range.last + 1n;
+        }
+
+        if (cursor <= within.last) result.push({ first: cursor, last: within.last });
+        return result;
+    }
+
+    /** `12` or, for a count too long to read, `about 2^64`, to the nearest power of two. */
+    private static count(value: bigint): string {
+        if (value <= 1n << 20n) return String(value);
+
+        const power = value.toString(2).length - 1;
+        const nearer = value - (1n << BigInt(power)) >= 1n << BigInt(power - 1) ? power + 1 : power;
+        return `about 2^${nearer}`;
+    }
+
+    private static byAddress(a: Use, b: Use): number {
+        const first = (use: Use) => AddressSpace.numberOf(use.address.split("-")[0]!);
+        return first(a) < first(b) ? -1 : first(a) > first(b) ? 1 : 0;
+    }
+
+    /** IPv4 before IPv6, then by first address. */
+    private static comparePrefixes(a: string, b: string): number {
+        const [ra, rb] = [Address.range(a), Address.range(b)];
+        if (ra.family !== rb.family) return ra.family === "ipv4" ? -1 : 1;
+        return ra.first < rb.first ? -1 : ra.first > rb.first ? 1 : 0;
+    }
+
+    private static byPrefix(a: { prefix: string }, b: { prefix: string }): number {
+        return AddressSpace.comparePrefixes(a.prefix, b.prefix);
+    }
+
+    /** Every address in use, by segment, under the space the network owns. With `within`, only what falls inside that prefix, as the one space. */
+    static report(devices: readonly Device[], within?: string): AddressReport {
+        const segments = new Map<string, { uses: Use[]; taken: Taken[] }>();
+        const blocks: Block[] = [];
+
+        const segmentOf = (address: string) => [...segments.keys()].find((prefix) => Address.contains(prefix, address));
+
+        // Segments come from the addresses on interfaces; a host route, such as a loopback's, is a block of its own.
+        for (const holder of Topology.holders(devices)) {
+            const vrf = holder.device.ports?.[holder.name]?.vrf ?? holder.device.interfaces?.[holder.name]?.vrf;
+            const what = `${holder.device.name} ${holder.name}${vrf ? `, VRF ${vrf}` : ""}`;
+
+            if (AddressSpace.isHostRoute(holder.address) || holder.peer) {
+                blocks.push({ prefix: `${Address.host(holder.address)}/${Address.bits(Address.family(holder.address))}`, what });
+                continue;
+            }
+
+            const prefix = Address.prefixOf(holder.address);
+            const segment = segments.get(prefix) ?? { uses: [], taken: [] };
+            const value = AddressSpace.numberOf(Address.host(holder.address));
+
+            segment.uses.push({ address: Address.host(holder.address), what });
+            segment.taken.push({ first: value, last: value });
+            segments.set(prefix, segment);
+
+            for (const group of holder.vrrp) {
+                if (!Address.isValid(group.address) || !Address.contains(prefix, group.address)) continue;
+                if (segment.uses.some((use) => use.address === group.address)) continue;
+
+                const holders = devices.filter((device) =>
+                    Object.values({ ...device.ports, ...device.interfaces }).some((settings) =>
+                        settings?.vrrp?.some((other) => other.id === group.id && other.address === group.address)
+                    )
+                );
+
+                segment.uses.push({
+                    address: group.address,
+                    what: `VRRP ${group.id} on ${holders.map((device) => device.name).join(", ")}`,
+                });
+                segment.taken.push({ first: AddressSpace.numberOf(group.address), last: AddressSpace.numberOf(group.address) });
+            }
+        }
+
+        // A use inside a segment is an address taken; outside every segment, a block of its own. An address one of our interfaces holds is listed once, as that interface.
+        const take = (address: string, what: string, first = address, last = address) => {
+            const prefix = segmentOf(first);
+            if (!prefix) return false;
+
+            const segment = segments.get(prefix)!;
+            if (segment.uses.some((use) => use.address === address)) return true;
+
+            segment.uses.push({ address, what });
+            segment.taken.push({ first: AddressSpace.numberOf(first), last: AddressSpace.numberOf(last) });
+            return true;
+        };
+
+        for (const device of devices) {
+            for (const [name, server] of Object.entries(device.dhcp ?? {})) {
+                const [start, end] = server.pool;
+                if (Address.isValid(start) && Address.isValid(end))
+                    take(`${start}-${end}`, `DHCP pool ${name} on ${device.name}`, start, end);
+
+                for (const reservation of server.reservations ?? []) {
+                    if (Address.isValid(reservation.address))
+                        take(reservation.address, `reserved for ${reservation.description ?? reservation.mac} by ${device.name}`);
+                }
+            }
+
+            for (const route of device.routing?.static ?? []) {
+                if (route.via && Address.isValid(route.via)) take(route.via, `next hop for ${route.prefix} on ${device.name}`);
+            }
+
+            for (const [name, neighbor] of Object.entries(device.routing?.bgp?.neighbors ?? {})) {
+                if (Address.isValid(neighbor.address)) take(neighbor.address, `BGP neighbor ${name} of ${device.name}`);
+            }
+
+            for (const [name, iface] of Object.entries(device.interfaces ?? {})) {
+                if (iface.type !== "wireguard") continue;
+
+                for (const peer of iface.peers ?? []) {
+                    for (const allowed of peer.allowed_addresses) {
+                        if (!Address.isCidr(allowed)) continue;
+
+                        const what = `WireGuard peer ${peer.name} on ${device.name} ${name}`;
+                        if (AddressSpace.isHostRoute(allowed) && take(Address.host(allowed), what)) continue;
+                        if (!segmentOf(Address.host(allowed))) blocks.push({ prefix: Address.prefixOf(allowed), what });
+                    }
+                }
+            }
+        }
+
+        // Space the network owns: what it originates in BGP, or the prefix asked for.
+        const owners = new Map<string, string[]>();
+        for (const device of devices) {
+            for (const prefix of device.routing?.bgp?.networks ?? []) {
+                if (!Address.isCidr(prefix)) continue;
+                owners.set(Address.prefixOf(prefix), [...(owners.get(Address.prefixOf(prefix)) ?? []), device.name]);
+            }
+        }
+
+        // A static route to a prefix no segment is in hands that block to whoever is at the next hop. A route covering segments or owned space, such as an aggregate, is not a use.
+        for (const device of devices) {
+            for (const route of device.routing?.static ?? []) {
+                if (!Address.isCidr(route.prefix) || Address.split(route.prefix).len === 0) continue;
+
+                const overlapsSegment = [...segments.keys()].some(
+                    (prefix) => Address.contains(route.prefix, prefix) || Address.contains(prefix, route.prefix)
+                );
+                const coversOwned = [...owners.keys()].some((owned) => Address.contains(route.prefix, owned));
+                if (overlapsSegment || coversOwned) continue;
+
+                const how = route.blackhole ? "discarded" : route.via ? `routed via ${route.via}` : `routed out ${route.interface}`;
+                blocks.push({ prefix: Address.prefixOf(route.prefix), what: `${how} by ${device.name}` });
+            }
+        }
+
+        const asked = within ? Address.prefixOf(within) : undefined;
+        const spacePrefixes = asked ? [asked] : [...owners.keys()];
+
+        // A segment or block belongs to the smallest space it is inside.
+        const spaceOf = (prefix: string) =>
+            spacePrefixes.filter((space) => Address.contains(space, prefix)).sort((a, b) => Address.split(b).len - Address.split(a).len)[0];
+
+        const toSegment = (prefix: string): Segment => {
+            const { uses, taken } = segments.get(prefix)!;
+            const free = AddressSpace.gaps(AddressSpace.usable(prefix), taken);
+            const total = free.reduce((sum, range) => sum + range.last - range.first + 1n, 0n);
+            const family = Address.family(prefix);
+
+            return {
+                prefix,
+                uses: uses.sort(AddressSpace.byAddress),
+                free: AddressSpace.count(total),
+                ...(free[0] ? { next: Address.fromNumber(free[0].first, family) } : {}),
+            };
+        };
+
+        const uniqueBlocks = blocks.filter(
+            (block, index) => blocks.findIndex((other) => other.prefix === block.prefix && other.what === block.what) === index
+        );
+
+        const spaces: Space[] = spacePrefixes.sort(AddressSpace.comparePrefixes).map((space) => {
+            const inside = (prefix: string) => spaceOf(prefix) === space;
+            const spaceSegments = [...segments.keys()].filter(inside).sort(AddressSpace.comparePrefixes);
+            const spaceBlocks = uniqueBlocks.filter((block) => inside(block.prefix)).sort(AddressSpace.byPrefix);
+
+            // Smaller spaces inside this one are in use too.
+            const nested = spacePrefixes.filter((other) => other !== space && Address.contains(space, other));
+            const taken = [...spaceSegments, ...spaceBlocks.map((block) => block.prefix), ...nested].map((prefix) => Address.range(prefix));
+            const family = Address.family(space);
+
+            return {
+                prefix: space,
+                owner: asked && !owners.has(space) ? "asked for" : `originated by ${(owners.get(space) ?? []).join(", ")}`,
+                segments: spaceSegments.map(toSegment),
+                blocks: spaceBlocks,
+                free: AddressSpace.gaps(Address.range(space), taken).flatMap((range) =>
+                    Address.prefixesBetween(range.first, range.last, family)
+                ),
+            };
+        });
+
+        const outside = (prefix: string) => !spaceOf(prefix);
+
+        return {
+            spaces,
+            elsewhere: asked
+                ? { segments: [], blocks: [] }
+                : {
+                      segments: [...segments.keys()].filter(outside).sort(AddressSpace.comparePrefixes).map(toSegment),
+                      blocks: uniqueBlocks.filter((block) => outside(block.prefix)).sort(AddressSpace.byPrefix),
+                  },
+        };
+    }
+
+    /** Free prefixes of one length inside the free space, up to `limit`, and how many there are in all. */
+    static freeOfLength(free: readonly string[], length: number, limit: number): { prefixes: string[]; total: bigint } {
+        const prefixes: string[] = [];
+        let total = 0n;
+
+        for (const prefix of free) {
+            const { len, family } = Address.split(prefix);
+            if (len > length || length > Address.bits(family)) continue;
+
+            const { first } = Address.range(prefix);
+            const step = 1n << BigInt(Address.bits(family) - length);
+            const fits = 1n << BigInt(length - len);
+            total += fits;
+
+            for (let index = 0n; index < fits && prefixes.length < limit; index++) {
+                prefixes.push(`${Address.fromNumber(first + index * step, family)}/${length}`);
+            }
+        }
+
+        return { prefixes, total };
+    }
+}

package/src/core/address.ts

@@ -0,0 +1,202 @@
+// Address arithmetic for both families. Addresses are parsed to bigint so v4 and v6 share one code path.
+
+import type { Family, IP, IPv4, IPv6, Prefix } from "../schema";
+
+/** Address helpers, for checks of your own. */
+export class Address {
+    /** IPv4 space another network cannot reach: this host, private, shared, loopback, link-local and documentation, after RFC 6890. */
+    private static readonly NOT_GLOBAL_V4 = [
+        "0.0.0.0/8",
+        "10.0.0.0/8",
+        "100.64.0.0/10",
+        "127.0.0.0/8",
+        "169.254.0.0/16",
+        "172.16.0.0/12",
+        "192.0.2.0/24",
+        "192.168.0.0/16",
+        "198.18.0.0/15",
+        "198.51.100.0/24",
+        "203.0.113.0/24",
+    ];
+
+    static family(address: string): Family {
+        return address.includes(":") ? "ipv6" : "ipv4";
+    }
+
+    /** How many bits an address of the family has: 32 or 128. */
+    static bits(family: Family): number {
+        return family === "ipv4" ? 32 : 128;
+    }
+
+    /** An address as a number, or null when it is not one. */
+    static toNumber(address: string): bigint | null {
+        if (!address.includes(":")) {
+            const octets = address.split(".");
+            const valid = octets.length === 4 && octets.every((octet) => /^\d{1,3}$/.test(octet) && Number(octet) <= 255);
+            if (!valid) return null;
+
+            return octets.reduce((value, octet) => (value << 8n) | BigInt(octet), 0n);
+        }
+
+        const [before, after, extra] = address.split("::");
+        if (extra !== undefined) return null;
+
+        const groupsOf = (text: string | undefined) => (text ? text.split(":") : []);
+        const leading = groupsOf(before);
+        const trailing = groupsOf(after);
+
+        // `::` stands for as many zero groups as make eight.
+        const zeros = after === undefined ? 0 : 8 - leading.length - trailing.length;
+        const groups = [...leading, ...Array(zeros).fill("0"), ...trailing];
+
+        const valid = groups.length === 8 && groups.every((group) => /^[0-9a-fA-F]{1,4}$/.test(group));
+        if (!valid) return null;
+
+        return groups.reduce((value, group) => (value << 16n) | BigInt(parseInt(group, 16)), 0n);
+    }
+
+    /** `10.0.0.1/24` to its parts. Throws when it is not an address with a length. */
+    static split(cidr: string): { addr: string; len: number; family: Family } {
+        const [address, lengthText] = cidr.split("/");
+        const family = Address.family(address!);
+        const length = Number(lengthText);
+
+        const valid =
+            Address.toNumber(address!) !== null &&
+            lengthText !== undefined &&
+            Number.isInteger(length) &&
+            length >= 0 &&
+            length <= Address.bits(family);
+        if (!valid) throw new Error(`'${cidr}' is not an address with a length`);
+
+        return { addr: address!, len: length, family };
+    }
+
+    static isValid(text: string): boolean {
+        return Address.toNumber(text) !== null;
+    }
+
+    static isCidr(text: string): boolean {
+        try {
+            Address.split(text);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    private static mask(length: number, family: Family): bigint {
+        const all = (1n << BigInt(Address.bits(family))) - 1n;
+        const hostBits = (1n << BigInt(Address.bits(family) - length)) - 1n;
+        return all ^ hostBits;
+    }
+
+    /** A number back to the address it stands for. */
+    static fromNumber(value: bigint, family: Family): IP {
+        if (family === "ipv4") {
+            return [24n, 16n, 8n, 0n].map((shift) => String((value >> shift) & 255n)).join(".") as IPv4;
+        }
+
+        const groups = Array.from({ length: 8 }, (_, index) => ((value >> BigInt(112 - index * 16)) & 0xffffn).toString(16));
+
+        // Compress the longest run of zero groups, as RFC 5952 asks.
+        let longestStart = -1;
+        let longestLength = 0;
+
+        for (let start = 0; start < 8;) {
+            let end = start;
+            while (end < 8 && groups[end] === "0") end++;
+
+            const runLength = end - start;
+            if (runLength > longestLength && runLength > 1) {
+                longestStart = start;
+                longestLength = runLength;
+            }
+
+            start = end === start ? start + 1 : end;
+        }
+
+        if (longestStart < 0) return groups.join(":") as IPv6;
+
+        const head = groups.slice(0, longestStart).join(":");
+        const tail = groups.slice(longestStart + longestLength).join(":");
+        return `${head}::${tail}`;
+    }
+
+    /** An address, with or without its length, in one spelling: IPv6 as RFC 5952 writes it, so `2001:DB8:0:0::1` and `2001:db8::1` compare equal. Text that is not an address comes back as it is. */
+    static canonical(text: string): string {
+        const [address, length] = text.split("/");
+        const value = Address.toNumber(address!);
+        if (value === null) return text;
+
+        const spelled = Address.fromNumber(value, Address.family(address!));
+        return length === undefined ? spelled : `${spelled}/${length}`;
+    }
+
+    /** `10.0.0.1/24` to `10.0.0.0/24`. */
+    static prefixOf(cidr: string): Prefix {
+        const { addr, len, family } = Address.split(cidr);
+        return `${Address.fromNumber(Address.toNumber(addr)! & Address.mask(len, family), family)}/${len}`;
+    }
+
+    /** Is the address or prefix `inner` inside `outer`? */
+    static contains(outer: string, inner: string): boolean {
+        const outerParts = Address.split(outer);
+        const [innerAddress, innerLengthText] = inner.split("/");
+        if (Address.family(innerAddress!) !== outerParts.family) return false;
+
+        const innerLength = innerLengthText === undefined ? Address.bits(outerParts.family) : Number(innerLengthText);
+        if (innerLength < outerParts.len) return false;
+
+        const outerMask = Address.mask(outerParts.len, outerParts.family);
+        return (Address.toNumber(innerAddress!)! & outerMask) === (Address.toNumber(outerParts.addr)! & outerMask);
+    }
+
+    /** The first and last address of a prefix, as numbers. */
+    static range(cidr: string): { first: bigint; last: bigint; family: Family } {
+        const { addr, len, family } = Address.split(cidr);
+        const hostBits = Address.mask(len, family) ^ ((1n << BigInt(Address.bits(family))) - 1n);
+        const first = Address.toNumber(addr)! & Address.mask(len, family);
+
+        return { first, last: first | hostBits, family };
+    }
+
+    /** The fewest prefixes that cover every address from `first` to `last` and nothing else. */
+    static prefixesBetween(first: bigint, last: bigint, family: Family): Prefix[] {
+        const bits = Address.bits(family);
+        const prefixes: Prefix[] = [];
+
+        for (let start = first; start <= last;) {
+            // The largest block that starts here on its own boundary and does not pass `last`.
+            let size = 0;
+            while (size < bits && start % (1n << BigInt(size + 1)) === 0n && start + (1n << BigInt(size + 1)) - 1n <= last) size++;
+
+            prefixes.push(`${Address.fromNumber(start, family)}/${bits - size}`);
+            start += 1n << BigInt(size);
+        }
+
+        return prefixes;
+    }
+
+    /** `/25` to `255.255.255.128`. */
+    static netmask(length: number): IPv4 {
+        return Address.fromNumber(Address.mask(length, "ipv4"), "ipv4") as IPv4;
+    }
+
+    /** `/24` to `0.0.0.255`, the inverted mask some ACLs take. */
+    static wildcard(length: number): IPv4 {
+        return Address.fromNumber(Address.mask(length, "ipv4") ^ 0xffffffffn, "ipv4") as IPv4;
+    }
+
+    /** The address with its length dropped. */
+    static host(cidr: string): IP {
+        return cidr.split("/")[0]! as IP;
+    }
+
+    /** Whether another network can reach the address. IPv6 is global only inside 2000::/3, less documentation space. */
+    static isGlobal(address: string): boolean {
+        if (Address.family(address) === "ipv6") return Address.contains("2000::/3", address) && !Address.contains("2001:db8::/32", address);
+
+        return !Address.NOT_GLOBAL_V4.some((prefix) => Address.contains(prefix, address));
+    }
+}

package/src/core/cabling.ts

@@ -0,0 +1,154 @@
+// The cabling as LLDP sees it, compared with what `link` says. `snapshot` saves each device's LLDP neighbors beside its config; `validate` warns where they disagree.
+
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { Catalog } from "../platforms/catalog";
+import type { Device } from "../schema";
+import type { Finding } from "./define";
+
+/** A device one of our ports sees at the far end of its cable, over LLDP. */
+export type Neighbor = {
+    /** Our port, by Circuit's name, such as `10g-1`. */
+    port: string;
+    /** The system name the far device sends, its hostname. */
+    system: string;
+    /** The far device's port, as that device spells it, such as `XGigabitEthernet0/0/1`. */
+    remote_port: string;
+};
+
+export class Cabling {
+    /** The end of a state file that holds a device's LLDP neighbors, beside its config. */
+    static readonly SUFFIX = ".lldp.json";
+
+    /** The file a device's neighbors are saved in. */
+    static path(stateDirectory: string, device: string): string {
+        return join(stateDirectory, device + Cabling.SUFFIX);
+    }
+
+    /** Save what a device sees, sorted, so a file changes only when a neighbor does. */
+    static save(stateDirectory: string, device: string, neighbors: readonly Neighbor[]): void {
+        const sorted = [...neighbors].sort((a, b) => Cabling.order(a).localeCompare(Cabling.order(b)));
+        const tidy = sorted.map(({ port, system, remote_port }) => ({ port, system, remote_port }));
+
+        writeFileSync(Cabling.path(stateDirectory, device), JSON.stringify(tidy, null, 4) + "\n");
+    }
+
+    /** Forget what a device saw, when its neighbors could not be read this time. */
+    static forget(stateDirectory: string, device: string): void {
+        rmSync(Cabling.path(stateDirectory, device), { force: true });
+    }
+
+    /** What a device saw at its last snapshot, or undefined when its neighbors were never read. */
+    static load(stateDirectory: string, device: string): Neighbor[] | undefined {
+        const path = Cabling.path(stateDirectory, device);
+        if (!existsSync(path)) return undefined;
+
+        return JSON.parse(readFileSync(path, "utf8")) as Neighbor[];
+    }
+
+    private static order(neighbor: Neighbor): string {
+        return `${neighbor.port} ${neighbor.system} ${neighbor.remote_port}`;
+    }
+
+    /** The device runs LLDP somewhere: on every port, on the interfaces it lists, or on a port that turns it on. */
+    static runsAnywhere(device: Device): boolean {
+        return Boolean(device.lldp) || Object.values(device.ports ?? {}).some((port) => port?.lldp === true);
+    }
+
+    /** The port runs LLDP, by the port's own `lldp`, or else the device's. */
+    static runsOn(device: Device, port: string): boolean {
+        const own = device.ports?.[port as keyof typeof device.ports]?.lldp;
+        if (own !== undefined) return own;
+
+        const lldp = device.lldp;
+        return lldp === true || (typeof lldp === "object" && (lldp.interfaces as readonly string[]).includes(port));
+    }
+
+    /**
+     * Warnings where LLDP and `link` disagree, from each device's own view: a cable in another port than `link` names, a cable `link` names that LLDP does not see, and another of our devices on a port without `link`.
+     *
+     * Only ports where both ends run LLDP, by the config, are compared, and only on devices whose neighbors were read. LLDP can be off at the far end, so each is a warning.
+     */
+    static compare(devices: readonly Device[], neighbors: ReadonlyMap<string, readonly Neighbor[]>): Finding[] {
+        const findings: Finding[] = [];
+
+        for (const device of devices) {
+            const seen = neighbors.get(device.name);
+            if (!seen) continue;
+
+            const warn = (message: string) => findings.push({ level: "warning", device: device.name, message });
+            const linked = Object.entries(device.ports ?? {}).filter(([, port]) => port?.link);
+            const ports = new Set([...linked.map(([name]) => name), ...seen.map((neighbor) => neighbor.port)]);
+
+            for (const port of ports) {
+                if (!Cabling.runsOn(device, port)) continue;
+
+                const here = seen.filter((neighbor) => neighbor.port === port);
+                const link = device.ports?.[port as keyof typeof device.ports]?.link;
+
+                if (!link) {
+                    for (const neighbor of here) {
+                        const far = Cabling.deviceOf(devices, neighbor.system);
+                        if (!far) continue;
+
+                        const farPort = Cabling.portOf(far, neighbor.remote_port);
+                        if (Cabling.runsOn(far, farPort)) warn(`port ${port}: LLDP sees ${far.name} ${farPort}, but the port has no link`);
+                    }
+                    continue;
+                }
+
+                const far = devices.find((candidate) => candidate.name === link.device);
+                if (!far || !Cabling.runsOn(far, link.port)) continue;
+
+                const named = `${link.device} ${link.port}`;
+
+                if (!here.length) {
+                    warn(`port ${port}: LLDP sees nothing, but link names ${named}: the cable is missing or down`);
+                } else if (
+                    !here.some(
+                        (neighbor) => Cabling.isDevice(neighbor.system, far.name) && Cabling.isPort(far, link.port, neighbor.remote_port)
+                    )
+                ) {
+                    const what = here.map((neighbor) => `${neighbor.system} ${neighbor.remote_port}`).join(" and ");
+                    warn(`port ${port}: LLDP sees ${what}, but link names ${named}`);
+                }
+            }
+        }
+
+        return findings;
+    }
+
+    /** A system name is the device's name, alone or with a domain after it. */
+    private static isDevice(system: string, name: string): boolean {
+        return system === name || system.startsWith(`${name}.`);
+    }
+
+    private static deviceOf(devices: readonly Device[], system: string): Device | undefined {
+        return devices.find((device) => Cabling.isDevice(system, device.name));
+    }
+
+    /** A port LLDP reports, as the far device spells it, is that device's port by Circuit's name. */
+    private static isPort(device: Device, port: string, reported: string): boolean {
+        const tidy = (text: string) => text.replace(/\s+/g, "").toLowerCase();
+        if (tidy(reported) === tidy(port)) return true;
+
+        try {
+            return tidy(Catalog.spell(device.platform, device.model, port)) === tidy(reported);
+        } catch {
+            return false;
+        }
+    }
+
+    /** Circuit's name for a port LLDP reports, or the report itself when no port of the device is spelled that way. */
+    private static portOf(device: Device, reported: string): string {
+        let ports: string[] = [];
+
+        try {
+            ports = Catalog.ports(device.platform, device.model);
+        } catch {
+            return reported;
+        }
+
+        return ports.find((port) => Cabling.isPort(device, port, reported)) ?? reported;
+    }
+}